@elizaos/agent 2.0.0-beta.2 → 2.0.11-beta.6

package/api/health-routes.js

@@ -0,0 +1,554 @@
+import { hasTextGenerationHandler } from "@elizaos/core";
+import { detectRuntimeModel } from "./agent-model.js";
+let cloudHealthApiPromise = null;
+let localInferenceHealthApiPromise = null;
+function getCloudHealthApi() {
+    cloudHealthApiPromise ??= import("@elizaos/plugin-elizacloud");
+    return cloudHealthApiPromise;
+}
+function getLocalInferenceHealthApi() {
+    // Import the route module directly, NOT the package's bare entry. The mobile
+    // agent bundle stubs `@elizaos/plugin-local-inference` (the heavy Plugin entry)
+    // to a null module, so a bare import returns `{ getLocalInferenceActiveSnapshot:
+    // undefined }` and /api/status 500s. The deep subpath (the `./*` wildcard
+    // export) isn't stubbed and carries the real implementation on every platform.
+    localInferenceHealthApiPromise ??= import(
+    /* @vite-ignore */ "@elizaos/plugin-local-inference/local-inference-routes");
+    return localInferenceHealthApiPromise;
+}
+// ---------------------------------------------------------------------------
+// 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;
+/**
+ * /api/runtime serializes the entire runtime object graph (six deep reflective
+ * walks). RuntimeView re-requests on depth/cap changes and may revalidate
+ * repeatedly, so the snapshot is memoized for a short window keyed by the
+ * serialize options and guarded by runtime identity — a restart swaps the
+ * runtime reference and forces a fresh build.
+ */
+const RUNTIME_DEBUG_SNAPSHOT_TTL_MS = 2_500;
+const runtimeDebugSnapshotCache = new Map();
+function getCachedRuntimeDebugSnapshot(runtime, options, build) {
+    const key = `${options.maxDepth}:${options.maxArrayLength}:${options.maxObjectEntries}:${options.maxStringLength}`;
+    const existing = runtimeDebugSnapshotCache.get(key);
+    const now = Date.now();
+    if (existing &&
+        existing.runtime === runtime &&
+        now - existing.builtAt < RUNTIME_DEBUG_SNAPSHOT_TTL_MS) {
+        return existing.payload;
+    }
+    const payload = build();
+    runtimeDebugSnapshotCache.set(key, { payload, builtAt: now, runtime });
+    return payload;
+}
+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
+// ---------------------------------------------------------------------------
+/**
+ * "First-turn capability online": the agent can actually produce a response.
+ *
+ * Distinct from `ready` (which is `true` even for stopped/error/paused states —
+ * it only negates `starting`/`restarting`). `canRespond` ANDs a live runtime, a
+ * `running` state, AND a registered TEXT_GENERATION handler — so it is `false`
+ * when no model provider is wired (local-inference is optional) and only flips
+ * `true` at the exact moment the agent can answer a first turn. This is the
+ * signal the UI uses to fade in first-turn capability: the shell paints early
+ * (agentState "starting"), and the composer goes live when this flips.
+ */
+export function computeCanRespond(runtime, agentState) {
+    if (!runtime || agentState !== "running") {
+        return false;
+    }
+    try {
+        return hasTextGenerationHandler(runtime);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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;
+        // The active-model snapshot is optional status info; never let an
+        // unavailable local-inference API turn /api/status into a 500. The deep
+        // subpath import itself can fail (mobile bundle stub, or a module-resolution
+        // environment where the subpath isn't aliased), so guard the import too, not
+        // just the snapshot call.
+        let activeLocalModel;
+        try {
+            const { getLocalInferenceActiveSnapshot } = await getLocalInferenceHealthApi();
+            const localInferenceActive = typeof getLocalInferenceActiveSnapshot === "function"
+                ? await getLocalInferenceActiveSnapshot().catch(() => null)
+                : null;
+            activeLocalModel =
+                localInferenceActive?.status === "ready" &&
+                    localInferenceActive.modelId?.trim()
+                    ? localInferenceActive.modelId.trim()
+                    : undefined;
+        }
+        catch {
+            activeLocalModel = undefined;
+        }
+        const model = state.model ??
+            activeLocalModel ??
+            detectRuntimeModel(state.runtime ?? null, state.config);
+        // Cloud health is optional status info under the same resilience contract:
+        // a missing/unloadable @elizaos/plugin-elizacloud must degrade to
+        // "disconnected", not 500 the status endpoint.
+        let cloudStatus = {
+            connectionStatus: "disconnected",
+            activeAgentId: null,
+            cloudProvisioned: false,
+            hasApiKey: false,
+        };
+        try {
+            const { isCloudProvisionedContainer, resolveCloudApiKey } = await getCloudHealthApi();
+            const cloudProvisioned = isCloudProvisionedContainer();
+            const hasCloudApiKey = Boolean(resolveCloudApiKey(state.config, state.runtime));
+            cloudStatus = {
+                connectionStatus: cloudProvisioned || hasCloudApiKey ? "connected" : "disconnected",
+                activeAgentId: cloudProvisioned ? state.agentName : null,
+                cloudProvisioned,
+                hasApiKey: hasCloudApiKey,
+            };
+        }
+        catch {
+            // keep the disconnected default — cloud health is optional status info
+        }
+        json(res, {
+            state: state.agentState,
+            agentName: state.agentName,
+            model,
+            canRespond: computeCanRespond(state.runtime, state.agentState),
+            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,
+            canRespond: computeCanRespond(runtime, state.agentState),
+            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,
+                    evaluatorCount: 0,
+                    serviceTypeCount: 0,
+                    serviceCount: 0,
+                },
+                order: {
+                    plugins: [],
+                    actions: [],
+                    providers: [],
+                    evaluators: [],
+                    services: [],
+                },
+                sections: {
+                    runtime: null,
+                    plugins: [],
+                    actions: [],
+                    providers: [],
+                    evaluators: [],
+                    services: {},
+                },
+            });
+            return true;
+        }
+        try {
+            const payload = getCachedRuntimeDebugSnapshot(runtime, serializeOptions, () => {
+                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");
+                const orderEvaluators = describeRuntimeOrder(runtime.evaluators, "evaluator");
+                return {
+                    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,
+                        evaluatorCount: runtime.evaluators.length,
+                        serviceTypeCount: servicesMap.size,
+                        serviceCount,
+                    },
+                    order: {
+                        plugins: orderPlugins,
+                        actions: orderActions,
+                        providers: orderProviders,
+                        evaluators: orderEvaluators,
+                        services: orderServices,
+                    },
+                    sections: {
+                        runtime: serializeForRuntimeDebug(runtime, serializeOptions),
+                        plugins: serializeForRuntimeDebug(runtime.plugins, serializeOptions),
+                        actions: serializeForRuntimeDebug(runtime.actions, serializeOptions),
+                        providers: serializeForRuntimeDebug(runtime.providers, serializeOptions),
+                        evaluators: serializeForRuntimeDebug(runtime.evaluators, serializeOptions),
+                        services: serializeForRuntimeDebug(servicesMap, serializeOptions),
+                    },
+                };
+            });
+            json(res, payload);
+        }
+        catch (err) {
+            error(res, `Failed to build runtime debug snapshot: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+        return true;
+    }
+    return false;
+}

package/api/hono-adapter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hono adapter for plugin routes.
+ *
+ * Registers every entry in `runtime.routes` onto a Hono app, marshals the
+ * incoming Hono `Context` into a `RouteHandlerContext`, calls the canonical
+ * `dispatchRoute` (with `inProcess: false`), and writes the result back to
+ * Hono.
+ *
+ * This lives in front of the existing hardcoded Node HTTP handlers — it
+ * covers any plugin route registered via `runtime.routes`. The hardcoded
+ * handlers will be migrated onto `runtime.routes` in later phases.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { Hono } from "hono";
+export interface HonoAdapterOptions {
+    /** Predicate that decides whether the incoming request has a valid token. */
+    isAuthorized: (req: Request) => boolean;
+}
+/**
+ * Mount every `runtime.routes` entry onto the given Hono app.
+ *
+ * Each registered handler runs the canonical {@link dispatchRoute}; that means
+ * the Hono surface and the in-process IPC surface execute the exact same code
+ * path against the same route table.
+ */
+export declare function mountRoutesOnHono(app: Hono, runtime: IAgentRuntime, options: HonoAdapterOptions): void;
+/** Convenience: build a new Hono app already wired to the runtime. */
+export declare function buildHonoAppForRuntime(runtime: IAgentRuntime, options: HonoAdapterOptions): Hono;
+//# sourceMappingURL=hono-adapter.d.ts.map

package/api/hono-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono-adapter.d.ts","sourceRoot":"","sources":["../../src/api/hono-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAA6B,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAK5B,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AA6ED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,IAAI,EACT,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,kBAAkB,GAC1B,IAAI,CA8FN;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,kBAAkB,GAC1B,IAAI,CAIN"}