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

package/packages/agent/src/api/health-routes.js

@@ -0,0 +1,450 @@
+import { isCloudProvisionedContainer, resolveCloudApiKey, } from "@elizaos/plugin-elizacloud";
+import { getLocalInferenceActiveSnapshot } from "@elizaos/plugin-local-inference";
+// ---------------------------------------------------------------------------
+// Runtime debug utilities (only used by GET /api/runtime)
+// ---------------------------------------------------------------------------
+const RUNTIME_DEBUG_DEFAULT_MAX_DEPTH = 10;
+const RUNTIME_DEBUG_MAX_DEPTH_CAP = 24;
+const RUNTIME_DEBUG_DEFAULT_MAX_ARRAY_LENGTH = 1000;
+const RUNTIME_DEBUG_DEFAULT_MAX_OBJECT_ENTRIES = 1000;
+const RUNTIME_DEBUG_DEFAULT_MAX_STRING_LENGTH = 8000;
+function parseDebugPositiveInt(raw, fallback, min, max) {
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    const intValue = Math.floor(parsed);
+    if (intValue < min)
+        return min;
+    if (intValue > max)
+        return max;
+    return intValue;
+}
+function classNameFor(value) {
+    const ctor = value.constructor;
+    const maybeName = typeof ctor?.name === "string" ? ctor.name.trim() : "";
+    return maybeName || "Object";
+}
+function stringDataProperty(value, key) {
+    if (!value || typeof value !== "object")
+        return null;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !("value" in descriptor))
+        return null;
+    const maybeString = descriptor.value;
+    if (typeof maybeString !== "string")
+        return null;
+    const trimmed = maybeString.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function describeRuntimeOrder(values, fallbackLabel) {
+    return values.map((value, index) => {
+        const className = value && typeof value === "object" ? classNameFor(value) : typeof value;
+        const name = stringDataProperty(value, "name") ??
+            stringDataProperty(value, "id") ??
+            stringDataProperty(value, "key") ??
+            stringDataProperty(value, "serviceType") ??
+            `${fallbackLabel} ${index + 1}`;
+        const id = stringDataProperty(value, "id") ?? stringDataProperty(value, "name");
+        return { index, name, className, id };
+    });
+}
+function describeRuntimeServiceOrder(servicesMap) {
+    return Array.from(servicesMap.entries()).map(([serviceType, instances], i) => {
+        const values = Array.isArray(instances) ? instances : [];
+        return {
+            index: i,
+            serviceType,
+            count: values.length,
+            instances: describeRuntimeOrder(values, serviceType),
+        };
+    });
+}
+function serializeForRuntimeDebug(value, options) {
+    const seen = new WeakMap();
+    const visit = (current, path, depth) => {
+        if (current === null)
+            return null;
+        const kind = typeof current;
+        if (kind === "string") {
+            if (current.length <= options.maxStringLength)
+                return current;
+            return {
+                __type: "string",
+                length: current.length,
+                preview: `${current.slice(0, options.maxStringLength)}...`,
+                truncated: true,
+            };
+        }
+        if (kind === "number") {
+            const n = current;
+            if (Number.isFinite(n))
+                return n;
+            return { __type: "number", value: String(n) };
+        }
+        if (kind === "boolean")
+            return current;
+        if (kind === "bigint")
+            return { __type: "bigint", value: String(current) };
+        if (kind === "undefined")
+            return { __type: "undefined" };
+        if (kind === "symbol")
+            return { __type: "symbol", value: String(current) };
+        if (kind === "function") {
+            const fn = current;
+            return {
+                __type: "function",
+                name: fn.name || "(anonymous)",
+                length: fn.length,
+            };
+        }
+        const obj = current;
+        if (obj instanceof Date) {
+            return { __type: "date", value: obj.toISOString() };
+        }
+        if (obj instanceof RegExp) {
+            return { __type: "regexp", value: String(obj) };
+        }
+        if (obj instanceof Error) {
+            const err = obj;
+            const out = {
+                __type: "error",
+                name: err.name,
+                message: err.message,
+            };
+            if (err.stack) {
+                out.stack =
+                    err.stack.length > options.maxStringLength
+                        ? `${err.stack.slice(0, options.maxStringLength)}...`
+                        : err.stack;
+            }
+            if (err.cause !== undefined) {
+                out.cause = visit(err.cause, `${path}.cause`, depth + 1);
+            }
+            return out;
+        }
+        if (Buffer.isBuffer(obj)) {
+            const previewLength = Math.min(obj.length, 64);
+            return {
+                __type: "buffer",
+                length: obj.length,
+                previewHex: obj.subarray(0, previewLength).toString("hex"),
+                truncated: obj.length > previewLength,
+            };
+        }
+        if (ArrayBuffer.isView(obj)) {
+            const view = obj;
+            const previewLength = Math.min(view.byteLength, 64);
+            const bytes = new Uint8Array(view.buffer, view.byteOffset, previewLength);
+            return {
+                __type: classNameFor(obj),
+                byteLength: view.byteLength,
+                previewHex: Buffer.from(bytes).toString("hex"),
+                truncated: view.byteLength > previewLength,
+            };
+        }
+        if (obj instanceof ArrayBuffer) {
+            const previewLength = Math.min(obj.byteLength, 64);
+            const bytes = new Uint8Array(obj, 0, previewLength);
+            return {
+                __type: "array-buffer",
+                byteLength: obj.byteLength,
+                previewHex: Buffer.from(bytes).toString("hex"),
+                truncated: obj.byteLength > previewLength,
+            };
+        }
+        const seenPath = seen.get(obj);
+        if (seenPath)
+            return { __type: "circular", ref: seenPath };
+        if (depth >= options.maxDepth) {
+            return {
+                __type: "max-depth",
+                className: classNameFor(obj),
+                path,
+            };
+        }
+        seen.set(obj, path);
+        if (Array.isArray(obj)) {
+            const arr = obj;
+            const limit = Math.min(arr.length, options.maxArrayLength);
+            const items = new Array(limit);
+            for (let i = 0; i < limit; i++) {
+                items[i] = visit(arr[i], `${path}[${i}]`, depth + 1);
+            }
+            const out = {
+                __type: "array",
+                length: arr.length,
+                items,
+            };
+            if (arr.length > limit)
+                out.truncatedItems = arr.length - limit;
+            return out;
+        }
+        if (obj instanceof Map) {
+            const entries = [];
+            let i = 0;
+            for (const [entryKey, entryValue] of obj.entries()) {
+                if (i >= options.maxObjectEntries)
+                    break;
+                entries.push({
+                    key: visit(entryKey, `${path}.<key:${i}>`, depth + 1),
+                    value: visit(entryValue, `${path}.<value:${i}>`, depth + 1),
+                });
+                i += 1;
+            }
+            const out = {
+                __type: "map",
+                size: obj.size,
+                entries,
+            };
+            if (obj.size > entries.length) {
+                out.truncatedEntries = obj.size - entries.length;
+            }
+            return out;
+        }
+        if (obj instanceof Set) {
+            const values = [];
+            let i = 0;
+            for (const entry of obj.values()) {
+                if (i >= options.maxArrayLength)
+                    break;
+                values.push(visit(entry, `${path}.<set:${i}>`, depth + 1));
+                i += 1;
+            }
+            const out = {
+                __type: "set",
+                size: obj.size,
+                values,
+            };
+            if (obj.size > values.length)
+                out.truncatedEntries = obj.size - values.length;
+            return out;
+        }
+        if (obj instanceof WeakMap) {
+            return { __type: "weak-map" };
+        }
+        if (obj instanceof WeakSet) {
+            return { __type: "weak-set" };
+        }
+        if (obj instanceof Promise) {
+            return { __type: "promise" };
+        }
+        const ownNames = Object.getOwnPropertyNames(obj);
+        const ownSymbols = Object.getOwnPropertySymbols(obj);
+        const allKeys = [...ownNames, ...ownSymbols];
+        const limit = Math.min(allKeys.length, options.maxObjectEntries);
+        const properties = {};
+        for (let i = 0; i < limit; i++) {
+            const propertyKey = allKeys[i];
+            const keyLabel = typeof propertyKey === "string"
+                ? propertyKey
+                : `[${String(propertyKey)}]`;
+            const descriptor = Object.getOwnPropertyDescriptor(obj, propertyKey);
+            if (!descriptor)
+                continue;
+            if ("value" in descriptor) {
+                properties[keyLabel] = visit(descriptor.value, `${path}.${keyLabel}`, depth + 1);
+            }
+            else {
+                properties[keyLabel] = {
+                    __type: "accessor",
+                    hasGetter: typeof descriptor.get === "function",
+                    hasSetter: typeof descriptor.set === "function",
+                    enumerable: descriptor.enumerable,
+                };
+            }
+        }
+        if (allKeys.length > limit) {
+            properties.__truncatedKeys = allKeys.length - limit;
+        }
+        const prototype = Object.getPrototypeOf(obj);
+        const isPlainObject = prototype === Object.prototype || prototype === null;
+        if (isPlainObject)
+            return properties;
+        return {
+            __type: "object",
+            className: classNameFor(obj),
+            properties,
+        };
+    };
+    return visit(value, "$", 0);
+}
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle health / status / runtime introspection routes.
+ * Returns `true` if the request was handled.
+ */
+export async function handleHealthRoutes(ctx) {
+    const { res, method, pathname, url, state, json, error } = ctx;
+    // ── GET /api/status ─────────────────────────────────────────────────────
+    if (method === "GET" && pathname === "/api/status") {
+        const uptime = state.startedAt ? Date.now() - state.startedAt : undefined;
+        const localInferenceActive = await getLocalInferenceActiveSnapshot().catch(() => null);
+        const activeLocalModel = localInferenceActive?.status === "ready" &&
+            localInferenceActive.modelId?.trim()
+            ? localInferenceActive.modelId.trim()
+            : undefined;
+        const model = state.model ?? activeLocalModel;
+        const cloudProvisioned = isCloudProvisionedContainer();
+        const hasCloudApiKey = Boolean(resolveCloudApiKey(state.config, state.runtime));
+        const cloudStatus = {
+            connectionStatus: cloudProvisioned || hasCloudApiKey ? "connected" : "disconnected",
+            activeAgentId: cloudProvisioned ? state.agentName : null,
+            cloudProvisioned,
+            hasApiKey: hasCloudApiKey,
+        };
+        json(res, {
+            state: state.agentState,
+            agentName: state.agentName,
+            model,
+            startedAt: state.startedAt,
+            uptime,
+            startup: state.startup,
+            cloud: cloudStatus,
+            pendingRestart: state.pendingRestartReasons.length > 0,
+            pendingRestartReasons: state.pendingRestartReasons,
+        });
+        return true;
+    }
+    // ── GET /api/health ──────────────────────────────────────────────────────
+    // Structured health check endpoint returning subsystem status.
+    if (method === "GET" && pathname === "/api/health") {
+        const runtime = state.runtime;
+        const uptime = state.startedAt
+            ? Math.floor((Date.now() - state.startedAt) / 1000)
+            : 0;
+        const loadedPluginCount = runtime?.plugins?.length
+            ? runtime.plugins.length
+            : state.plugins.filter((p) => p.enabled || p.isActive).length;
+        const failedPluginCount = state.plugins.filter((p) => p.loadError).length;
+        let coordinatorStatus = "not_wired";
+        try {
+            if (runtime?.getService("SWARM_COORDINATOR")) {
+                coordinatorStatus = "ok";
+            }
+        }
+        catch {
+            // not available
+        }
+        const connectors = state.connectorHealthMonitor
+            ? state.connectorHealthMonitor.getConnectorStatuses()
+            : {};
+        if (Object.keys(connectors).length === 0 && state.config.connectors) {
+            for (const [name, cfg] of Object.entries(state.config.connectors)) {
+                if (cfg &&
+                    typeof cfg === "object" &&
+                    cfg.enabled !== false) {
+                    connectors[name] = "configured";
+                }
+            }
+        }
+        const ready = state.agentState !== "starting" && state.agentState !== "restarting";
+        json(res, {
+            ready,
+            runtime: runtime ? "ok" : "not_initialized",
+            database: runtime ? "ok" : "unknown",
+            plugins: {
+                loaded: loadedPluginCount,
+                failed: failedPluginCount,
+            },
+            coordinator: coordinatorStatus,
+            connectors,
+            uptime,
+            agentState: state.agentState,
+            startup: state.startup,
+        });
+        return true;
+    }
+    // ── GET /api/runtime ───────────────────────────────────────────────────
+    // Deep runtime introspection endpoint for advanced debugging UI.
+    if (method === "GET" && pathname === "/api/runtime") {
+        const maxDepth = parseDebugPositiveInt(url.searchParams.get("depth"), RUNTIME_DEBUG_DEFAULT_MAX_DEPTH, 1, RUNTIME_DEBUG_MAX_DEPTH_CAP);
+        const maxArrayLength = parseDebugPositiveInt(url.searchParams.get("maxArrayLength"), RUNTIME_DEBUG_DEFAULT_MAX_ARRAY_LENGTH, 1, 5000);
+        const maxObjectEntries = parseDebugPositiveInt(url.searchParams.get("maxObjectEntries"), RUNTIME_DEBUG_DEFAULT_MAX_OBJECT_ENTRIES, 1, 5000);
+        const maxStringLength = parseDebugPositiveInt(url.searchParams.get("maxStringLength"), RUNTIME_DEBUG_DEFAULT_MAX_STRING_LENGTH, 64, 100_000);
+        const serializeOptions = {
+            maxDepth,
+            maxArrayLength,
+            maxObjectEntries,
+            maxStringLength,
+        };
+        const runtime = state.runtime;
+        const generatedAt = Date.now();
+        if (!runtime) {
+            json(res, {
+                runtimeAvailable: false,
+                generatedAt,
+                settings: serializeOptions,
+                meta: {
+                    agentState: state.agentState,
+                    agentName: state.agentName,
+                    model: state.model ?? null,
+                    pluginCount: 0,
+                    actionCount: 0,
+                    providerCount: 0,
+                    serviceTypeCount: 0,
+                    serviceCount: 0,
+                },
+                order: {
+                    plugins: [],
+                    actions: [],
+                    providers: [],
+                    services: [],
+                },
+                sections: {
+                    runtime: null,
+                    plugins: [],
+                    actions: [],
+                    providers: [],
+                    services: {},
+                },
+            });
+            return true;
+        }
+        try {
+            const servicesMap = runtime.services;
+            const serviceCount = Array.from(servicesMap.values()).reduce((sum, entries) => sum + (Array.isArray(entries) ? entries.length : 0), 0);
+            const orderServices = describeRuntimeServiceOrder(servicesMap);
+            const orderPlugins = describeRuntimeOrder(runtime.plugins, "plugin");
+            const orderActions = describeRuntimeOrder(runtime.actions, "action");
+            const orderProviders = describeRuntimeOrder(runtime.providers, "provider");
+            json(res, {
+                runtimeAvailable: true,
+                generatedAt,
+                settings: serializeOptions,
+                meta: {
+                    agentId: runtime.agentId,
+                    agentState: state.agentState,
+                    agentName: runtime.character.name ?? state.agentName,
+                    model: state.model ?? null,
+                    pluginCount: runtime.plugins.length,
+                    actionCount: runtime.actions.length,
+                    providerCount: runtime.providers.length,
+                    serviceTypeCount: servicesMap.size,
+                    serviceCount,
+                },
+                order: {
+                    plugins: orderPlugins,
+                    actions: orderActions,
+                    providers: orderProviders,
+                    services: orderServices,
+                },
+                sections: {
+                    runtime: serializeForRuntimeDebug(runtime, serializeOptions),
+                    plugins: serializeForRuntimeDebug(runtime.plugins, serializeOptions),
+                    actions: serializeForRuntimeDebug(runtime.actions, serializeOptions),
+                    providers: serializeForRuntimeDebug(runtime.providers, serializeOptions),
+                    services: serializeForRuntimeDebug(servicesMap, serializeOptions),
+                },
+            });
+        }
+        catch (err) {
+            error(res, `Failed to build runtime debug snapshot: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    return false;
+}

package/packages/agent/src/api/inbox-routes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Inbox routes.
+ *
+ * Exposes a read-only, time-ordered view of messages from every channel
+ * the agent participates in — dashboard web chat plus every connector
+ * plugin (iMessage, Telegram, Discord, WhatsApp, WeChat, etc.) — merged
+ * into a single feed so the UI can render an inbox without the
+ * client having to know which rooms each source uses.
+ *
+ * Why a separate endpoint instead of reusing /api/conversations/:id/messages:
+ *
+ *   Each connector plugin creates its own rooms keyed by the external
+ *   chat id (chat.db chat_identifier for iMessage, chat_id for Telegram,
+ *   etc.). The dashboard conversation room is pinned to
+ *   `${agentName}-web-chat-room`. A single-room read path can't see
+ *   cross-channel traffic, and we don't want to fan out writes to the
+ *   web-chat room on every connector dispatch (it would pollute the
+ *   dashboard world with entities that don't belong to it and break
+ *   the "one conversation = one room" invariant that bootstrap relies
+ *   on). The read-side aggregator keeps each connector's world/room
+ *   graph intact while still giving the UI a combined feed.
+ *
+ * Routes:
+ *
+ *   GET /api/inbox/messages?limit=N&sources=imessage,telegram
+ *     Returns the N most recent messages across all agent rooms where
+ *     `content.source` is set to a connector tag. `sources` (optional,
+ *     comma-separated) filters to a specific subset. Ordered newest
+ *     first. Default limit is 100, hard cap 500.
+ *
+ *   GET /api/inbox/sources
+ *     Returns the distinct set of source tags the agent currently has
+ *     memories for, so the UI can render a dynamic source filter chip
+ *     list without hardcoding connector names.
+ */
+import type http from "node:http";
+import type { AgentRuntime, RouteHelpers } from "@elizaos/core";
+export interface InboxRouteState {
+    runtime: AgentRuntime | null;
+}
+/**
+ * Route handler entry point. Returns `true` when a route matched and
+ * the response has been written; `false` so the caller can continue
+ * trying other handlers. Mirrors the handleIMessageRoute pattern.
+ */
+export declare function handleInboxRoute(req: http.IncomingMessage, res: http.ServerResponse, pathname: string, method: string, state: InboxRouteState, helpers: RouteHelpers): Promise<boolean>;
+//# sourceMappingURL=inbox-routes.d.ts.map

package/packages/agent/src/api/inbox-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-routes.d.ts","sourceRoot":"","sources":["../../../../../src/api/inbox-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EACV,YAAY,EAGZ,YAAY,EAGb,MAAM,eAAe,CAAC;AA2EvB,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;CAC9B;AA20DD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,CA+KlB"}