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

package/packages/agent/src/services/connector-setup-service.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ConnectorSetupService — a runtime service that exposes shared
+ * connector setup utilities to plugins.
+ *
+ * Plugins access this during route handlers via:
+ *   `runtime.getService("connector-setup")`
+ *
+ * Provides config persistence, escalation channel registration,
+ * owner contact management, workspace dir, and WebSocket broadcasting
+ * so connector plugins don't need to import agent internals.
+ */
+import { type IAgentRuntime, Service } from "@elizaos/core";
+import { type OwnerContactUpdate } from "../api/owner-contact-helpers.ts";
+export type { OwnerContactUpdate };
+export interface ConnectorSetupServiceInstance extends Service {
+    /** Load the current Eliza config from disk. */
+    getConfig(): Record<string, unknown>;
+    /** Save the Eliza config to disk. */
+    persistConfig(config: Record<string, unknown>): void;
+    /** Load + return; caller mutates; then persistConfig(). Convenience wrapper. */
+    updateConfig(updater: (config: Record<string, unknown>) => void): void;
+    /** Register a channel name for escalation delivery (e.g. "telegram"). */
+    registerEscalationChannel(channelName: string): boolean;
+    /** Set/update an owner contact entry in the config. */
+    setOwnerContact(update: OwnerContactUpdate): boolean;
+    /** Resolve the default agent workspace directory. */
+    getWorkspaceDir(): string;
+    /** Broadcast a WebSocket message to all connected clients. */
+    broadcastWs(data: object): void;
+    /** Set the WebSocket broadcast function (called by the server during startup). */
+    setBroadcastWs(fn: ((data: object) => void) | null): void;
+}
+export declare class ConnectorSetupService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private broadcastWsFn;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    stop(): Promise<void>;
+    getConfig(): Record<string, unknown>;
+    persistConfig(config: Record<string, unknown>): void;
+    updateConfig(updater: (config: Record<string, unknown>) => void): void;
+    registerEscalationChannel(channelName: string): boolean;
+    setOwnerContact(update: OwnerContactUpdate): boolean;
+    getWorkspaceDir(): string;
+    broadcastWs(data: object): void;
+    setBroadcastWs(fn: ((data: object) => void) | null): void;
+}
+//# sourceMappingURL=connector-setup-service.d.ts.map

package/packages/agent/src/services/connector-setup-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-setup-service.d.ts","sourceRoot":"","sources":["../../../../../src/services/connector-setup-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,iCAAiC,CAAC;AAKzC,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAEnC,MAAM,WAAW,6BAA8B,SAAQ,OAAO;IAC5D,+CAA+C;IAC/C,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,qCAAqC;IACrC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrD,gFAAgF;IAChF,YAAY,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvE,yEAAyE;IACzE,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IACxD,uDAAuD;IACvD,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC;IACrD,qDAAqD;IACrD,eAAe,IAAI,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kFAAkF;IAClF,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CAC3D;AAED,qBAAa,qBAAsB,SAAQ,OAAO;IAChD,MAAM,CAAC,WAAW,SAAqB;IACvC,qBAAqB,SAAkD;IAEvE,OAAO,CAAC,aAAa,CAAyC;WAEjD,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIpC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpD,YAAY,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,IAAI;IAMtE,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIvD,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO;IAYpD,eAAe,IAAI,MAAM;IAIzB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;CAG1D"}

package/packages/agent/src/services/connector-setup-service.js

@@ -0,0 +1,60 @@
+/**
+ * ConnectorSetupService — a runtime service that exposes shared
+ * connector setup utilities to plugins.
+ *
+ * Plugins access this during route handlers via:
+ *   `runtime.getService("connector-setup")`
+ *
+ * Provides config persistence, escalation channel registration,
+ * owner contact management, workspace dir, and WebSocket broadcasting
+ * so connector plugins don't need to import agent internals.
+ */
+import { logger, Service } from "@elizaos/core";
+import { setOwnerContact, } from "../api/owner-contact-helpers.js";
+import { loadElizaConfig, saveElizaConfig } from "../config/config.js";
+import { resolveDefaultAgentWorkspaceDir } from "../shared/workspace-resolution.js";
+import { registerEscalationChannel } from "./escalation.js";
+export class ConnectorSetupService extends Service {
+    static serviceType = "connector-setup";
+    capabilityDescription = "Shared connector setup utilities for plugins";
+    broadcastWsFn = null;
+    static async start(runtime) {
+        const instance = new ConnectorSetupService(runtime);
+        logger.debug("[connector-setup] Service started");
+        return instance;
+    }
+    async stop() {
+        this.broadcastWsFn = null;
+    }
+    getConfig() {
+        return loadElizaConfig();
+    }
+    persistConfig(config) {
+        saveElizaConfig(config);
+    }
+    updateConfig(updater) {
+        const config = this.getConfig();
+        updater(config);
+        this.persistConfig(config);
+    }
+    registerEscalationChannel(channelName) {
+        return registerEscalationChannel(channelName);
+    }
+    setOwnerContact(update) {
+        const config = this.getConfig();
+        const modified = setOwnerContact(config, update);
+        if (modified) {
+            this.persistConfig(config);
+        }
+        return modified;
+    }
+    getWorkspaceDir() {
+        return resolveDefaultAgentWorkspaceDir();
+    }
+    broadcastWs(data) {
+        this.broadcastWsFn?.(data);
+    }
+    setBroadcastWs(fn) {
+        this.broadcastWsFn = fn;
+    }
+}

package/packages/agent/src/services/escalation.d.ts

@@ -0,0 +1,35 @@
+import type { IAgentRuntime } from "@elizaos/core";
+export interface EscalationState {
+    id: string;
+    reason: string;
+    text: string;
+    currentStep: number;
+    channelsSent: string[];
+    startedAt: number;
+    lastSentAt: number;
+    resolved: boolean;
+    resolvedAt?: number;
+}
+/**
+ * Register a channel in the escalation config's ordered channel list.
+ *
+ * Called after a connector pairing succeeds so that the escalation service
+ * can reach the owner on the newly connected platform without manual
+ * configuration. `client_chat` always stays first; new channels are
+ * appended in order of pairing.
+ *
+ * Persists the updated config to `eliza.json` via {@link saveElizaConfig}.
+ * Returns `true` if the channel was newly added, `false` if already present.
+ */
+export declare function registerEscalationChannel(channelName: string): boolean;
+export declare class EscalationService {
+    static startEscalation(runtime: IAgentRuntime, reason: string, text: string): Promise<EscalationState>;
+    static checkEscalation(runtime: IAgentRuntime, escalationId: string): Promise<void>;
+    static resolveEscalation(escalationId: string, runtime?: IAgentRuntime): Promise<void>;
+    static getActiveEscalationSync(): EscalationState | null;
+    static getActiveEscalation(runtime: IAgentRuntime): Promise<EscalationState | null>;
+    static rehydrateFromDb(runtime: IAgentRuntime): Promise<void>;
+    static _reset(): void;
+    static _resetDb(runtime: IAgentRuntime): Promise<void>;
+}
+//# sourceMappingURL=escalation.d.ts.map

package/packages/agent/src/services/escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.d.ts","sourceRoot":"","sources":["../../../../../src/services/escalation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,eAAe,CAAC;AAoBzD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAsDtE;AAyLD,qBAAa,iBAAiB;WACf,eAAe,CAC1B,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC;WAoEd,eAAe,CAC1B,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;WAgEH,iBAAiB,CAC5B,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC;IAoBhB,MAAM,CAAC,uBAAuB,IAAI,eAAe,GAAG,IAAI;WAO3C,mBAAmB,CAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;WAYrB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnE,MAAM,CAAC,MAAM,IAAI,IAAI;WAOR,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAO7D"}

package/packages/agent/src/services/escalation.js

@@ -0,0 +1,376 @@
+import { logger } from "@elizaos/core";
+import { loadElizaConfig, saveElizaConfig } from "../config/config.js";
+import { loadOwnerContactRoutingHints, loadOwnerContactsConfig, resolveOwnerContactWithFallback, } from "../config/owner-contacts.js";
+import { resolveOwnerEntityId } from "../runtime/owner-entity.js";
+import { hasRuntimeSendHandler, logMissingSendHandlerOnce, } from "./send-handler-availability.js";
+const DEFAULT_CHANNELS = ["client_chat"];
+const DEFAULT_WAIT_MINUTES = 5;
+const DEFAULT_MAX_RETRIES = 3;
+const ESCALATION_CACHE_KEY_PREFIX = "agent:escalation:active";
+const activeEscalations = new Map();
+const pendingTimers = new Map();
+// ---------------------------------------------------------------------------
+// Persistence helpers -- owned by agent state instead of app-lifeops storage.
+// ---------------------------------------------------------------------------
+function escalationCacheKey(runtime) {
+    return `${ESCALATION_CACHE_KEY_PREFIX}:${runtime.agentId}`;
+}
+async function persistState(runtime, state) {
+    try {
+        if (state.resolved) {
+            await runtime.deleteCache(escalationCacheKey(runtime));
+            return;
+        }
+        await runtime.setCache(escalationCacheKey(runtime), state);
+    }
+    catch (err) {
+        logger.debug("[escalation] Failed to persist escalation state to cache", err instanceof Error ? err.message : String(err));
+    }
+}
+async function loadActiveFromCache(runtime) {
+    try {
+        const state = await runtime.getCache(escalationCacheKey(runtime));
+        return state ?? null;
+    }
+    catch (err) {
+        logger.debug("[escalation] Failed to load escalation state from cache", err instanceof Error ? err.message : String(err));
+        return null;
+    }
+}
+function loadEscalationConfig() {
+    try {
+        const cfg = loadElizaConfig();
+        return cfg.agents?.defaults?.escalation ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Register a channel in the escalation config's ordered channel list.
+ *
+ * Called after a connector pairing succeeds so that the escalation service
+ * can reach the owner on the newly connected platform without manual
+ * configuration. `client_chat` always stays first; new channels are
+ * appended in order of pairing.
+ *
+ * Persists the updated config to `eliza.json` via {@link saveElizaConfig}.
+ * Returns `true` if the channel was newly added, `false` if already present.
+ */
+export function registerEscalationChannel(channelName) {
+    if (!channelName || typeof channelName !== "string") {
+        return false;
+    }
+    const trimmed = channelName.trim().toLowerCase();
+    if (trimmed.length === 0) {
+        return false;
+    }
+    try {
+        const cfg = loadElizaConfig();
+        if (!cfg.agents) {
+            cfg.agents = {};
+        }
+        const agents = cfg.agents;
+        if (!agents.defaults) {
+            agents.defaults = {};
+        }
+        const defaults = agents.defaults;
+        if (!defaults.escalation) {
+            defaults.escalation = {};
+        }
+        const escalation = defaults.escalation;
+        const existing = Array.isArray(escalation.channels)
+            ? escalation.channels
+            : [...DEFAULT_CHANNELS];
+        if (existing.includes(trimmed)) {
+            return false;
+        }
+        // Ensure client_chat stays first
+        if (!existing.includes("client_chat")) {
+            existing.unshift("client_chat");
+        }
+        existing.push(trimmed);
+        escalation.channels = existing;
+        saveElizaConfig(cfg);
+        logger.info(`[escalation] Registered channel "${trimmed}" -- escalation order: [${existing.join(", ")}]`);
+        return true;
+    }
+    catch (err) {
+        logger.warn(`[escalation] Failed to register channel "${trimmed}"`, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+function loadOwnerContacts() {
+    return loadOwnerContactsConfig({
+        boundary: "escalation",
+        operation: "owner_contacts_config",
+        message: "[escalation] Failed to load owner contacts config; escalation delivery has no configured owner channels.",
+    });
+}
+function resolveChannels(config) {
+    const channels = config.channels;
+    return Array.isArray(channels) && channels.length > 0
+        ? channels
+        : DEFAULT_CHANNELS;
+}
+function resolveWaitMs(config) {
+    const mins = typeof config.waitMinutes === "number" && config.waitMinutes > 0
+        ? config.waitMinutes
+        : DEFAULT_WAIT_MINUTES;
+    return mins * 60_000;
+}
+function resolveMaxRetries(config) {
+    return typeof config.maxRetries === "number" && config.maxRetries > 0
+        ? config.maxRetries
+        : DEFAULT_MAX_RETRIES;
+}
+async function sendToChannel(runtime, channel, text, ownerContacts, routingHints, ownerEntityId) {
+    const hint = routingHints[channel] ?? null;
+    const resolvedContact = resolveOwnerContactWithFallback({
+        ownerContacts,
+        source: channel,
+        ownerEntityId,
+    }) ??
+        (hint
+            ? resolveOwnerContactWithFallback({
+                ownerContacts,
+                source: hint.source,
+                ownerEntityId,
+            })
+            : null);
+    const contact = resolvedContact?.contact ??
+        (hint
+            ? {
+                entityId: hint.entityId ?? undefined,
+                channelId: hint.channelId ?? undefined,
+                roomId: hint.roomId ?? undefined,
+            }
+            : undefined);
+    if (!contact) {
+        logger.warn(`[escalation] No owner contact configured for channel "${channel}"`);
+        return false;
+    }
+    try {
+        const targetSource = resolvedContact?.source ?? channel;
+        if (targetSource === "client_chat" &&
+            !hasRuntimeSendHandler(runtime, targetSource)) {
+            logMissingSendHandlerOnce("escalation", targetSource);
+            return false;
+        }
+        await runtime.sendMessageToTarget({
+            source: targetSource,
+            entityId: contact.entityId,
+            channelId: contact.channelId,
+            roomId: contact.roomId,
+        }, {
+            text,
+            source: targetSource,
+            metadata: {
+                urgency: "urgent",
+                escalation: true,
+                routeSource: targetSource,
+                routeResolution: hint?.resolvedFrom ?? "config",
+                routeEndpoint: contact.channelId ?? contact.roomId ?? contact.entityId ?? null,
+                routeLastResponseAt: hint?.lastResponseAt ?? null,
+                routeLastResponseChannel: hint?.lastResponseChannel ?? null,
+            },
+        });
+        return true;
+    }
+    catch (err) {
+        logger.warn(`[escalation] Failed to send to channel "${channel}"`, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+async function ownerRespondedSince(runtime, ownerContacts, routingHints, ownerEntityId, sinceTimestamp) {
+    const entityIds = new Set();
+    if (ownerEntityId) {
+        entityIds.add(ownerEntityId);
+    }
+    for (const contact of Object.values(ownerContacts)) {
+        if (contact.entityId)
+            entityIds.add(contact.entityId);
+    }
+    for (const hint of Object.values(routingHints)) {
+        if (hint.entityId)
+            entityIds.add(hint.entityId);
+    }
+    for (const entityId of entityIds) {
+        try {
+            const rooms = await runtime.getRoomsForParticipant(entityId);
+            if (!rooms || rooms.length === 0)
+                continue;
+            const messages = await runtime.getMemoriesByRoomIds({
+                roomIds: rooms,
+                tableName: "messages",
+                limit: 20,
+            });
+            const ownerMessage = messages.find((m) => m.entityId === entityId &&
+                m.createdAt != null &&
+                m.createdAt > sinceTimestamp);
+            if (ownerMessage)
+                return true;
+        }
+        catch (err) {
+            logger.debug(`[escalation] Error checking owner response for entity ${entityId}`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    return false;
+}
+function scheduleCheck(runtime, escalationId, delayMs) {
+    const existing = pendingTimers.get(escalationId);
+    if (existing)
+        clearTimeout(existing);
+    const timer = setTimeout(async () => {
+        pendingTimers.delete(escalationId);
+        try {
+            await EscalationService.checkEscalation(runtime, escalationId);
+        }
+        catch (err) {
+            logger.error("[escalation] Scheduled check failed", err instanceof Error ? err.message : String(err));
+        }
+    }, delayMs);
+    pendingTimers.set(escalationId, timer);
+}
+let idCounter = 0;
+// biome-ignore lint/complexity/noStaticOnlyClass: module-style service API is intentional here
+export class EscalationService {
+    static async startEscalation(runtime, reason, text) {
+        const existing = EscalationService.getActiveEscalationSync();
+        if (existing) {
+            existing.reason = `${existing.reason}; ${reason}`;
+            existing.text = `${existing.text}\n---\n${text}`;
+            logger.info(`[escalation] Coalesced into active escalation ${existing.id}`);
+            await persistState(runtime, existing);
+            return existing;
+        }
+        const config = loadEscalationConfig();
+        const channels = resolveChannels(config);
+        const ownerContacts = loadOwnerContacts();
+        const routingHints = await loadOwnerContactRoutingHints(runtime, ownerContacts);
+        const ownerEntityId = await resolveOwnerEntityId(runtime);
+        const waitMs = resolveWaitMs(config);
+        idCounter += 1;
+        const escalationId = `esc-${Date.now()}-${idCounter}`;
+        const now = Date.now();
+        const state = {
+            id: escalationId,
+            reason,
+            text,
+            currentStep: 0,
+            channelsSent: [],
+            startedAt: now,
+            lastSentAt: now,
+            resolved: false,
+        };
+        activeEscalations.set(escalationId, state);
+        const firstChannel = channels[0];
+        if (firstChannel) {
+            const sent = await sendToChannel(runtime, firstChannel, text, ownerContacts, routingHints, ownerEntityId);
+            if (sent) {
+                state.channelsSent.push(firstChannel);
+            }
+        }
+        const maxRetries = resolveMaxRetries(config);
+        if (channels.length > 1 || maxRetries > 1) {
+            scheduleCheck(runtime, escalationId, waitMs);
+        }
+        logger.info(`[escalation] Started ${escalationId}: channel=${channels[0]}, reason="${reason}"`);
+        await persistState(runtime, state);
+        return state;
+    }
+    static async checkEscalation(runtime, escalationId) {
+        const state = activeEscalations.get(escalationId);
+        if (!state || state.resolved)
+            return;
+        const config = loadEscalationConfig();
+        const channels = resolveChannels(config);
+        const ownerContacts = loadOwnerContacts();
+        const routingHints = await loadOwnerContactRoutingHints(runtime, ownerContacts);
+        const ownerEntityId = await resolveOwnerEntityId(runtime);
+        const maxRetries = resolveMaxRetries(config);
+        const waitMs = resolveWaitMs(config);
+        const responded = await ownerRespondedSince(runtime, ownerContacts, routingHints, ownerEntityId, state.lastSentAt);
+        if (responded) {
+            await EscalationService.resolveEscalation(escalationId, runtime);
+            return;
+        }
+        state.currentStep += 1;
+        if (state.currentStep >= maxRetries) {
+            logger.warn(`[escalation] ${escalationId}: max retries (${maxRetries}) reached -- giving up`);
+            state.resolved = true;
+            state.resolvedAt = Date.now();
+            await persistState(runtime, state);
+            return;
+        }
+        const nextChannelIndex = state.currentStep % channels.length;
+        const nextChannel = channels[nextChannelIndex];
+        if (nextChannel) {
+            const sent = await sendToChannel(runtime, nextChannel, state.text, ownerContacts, routingHints, ownerEntityId);
+            if (sent) {
+                state.channelsSent.push(nextChannel);
+            }
+            state.lastSentAt = Date.now();
+        }
+        await persistState(runtime, state);
+        if (state.currentStep + 1 < maxRetries) {
+            scheduleCheck(runtime, escalationId, waitMs);
+        }
+    }
+    static async resolveEscalation(escalationId, runtime) {
+        const state = activeEscalations.get(escalationId);
+        if (!state || state.resolved)
+            return;
+        state.resolved = true;
+        state.resolvedAt = Date.now();
+        const timer = pendingTimers.get(escalationId);
+        if (timer) {
+            clearTimeout(timer);
+            pendingTimers.delete(escalationId);
+        }
+        logger.info(`[escalation] Resolved ${escalationId}`);
+        if (runtime) {
+            await persistState(runtime, state);
+        }
+    }
+    static getActiveEscalationSync() {
+        for (const state of activeEscalations.values()) {
+            if (!state.resolved)
+                return state;
+        }
+        return null;
+    }
+    static async getActiveEscalation(runtime) {
+        const cached = EscalationService.getActiveEscalationSync();
+        if (cached)
+            return cached;
+        const persisted = await loadActiveFromCache(runtime);
+        if (persisted) {
+            activeEscalations.set(persisted.id, persisted);
+            return persisted;
+        }
+        return null;
+    }
+    static async rehydrateFromDb(runtime) {
+        const persisted = await loadActiveFromCache(runtime);
+        if (persisted && !activeEscalations.has(persisted.id)) {
+            activeEscalations.set(persisted.id, persisted);
+            logger.info(`[escalation] Rehydrated unresolved escalation ${persisted.id} from cache`);
+        }
+    }
+    static _reset() {
+        for (const timer of pendingTimers.values())
+            clearTimeout(timer);
+        pendingTimers.clear();
+        activeEscalations.clear();
+        idCounter = 0;
+    }
+    static async _resetDb(runtime) {
+        try {
+            await runtime.deleteCache(escalationCacheKey(runtime));
+        }
+        catch {
+            // Best-effort -- test runtimes may not have a real cache adapter
+        }
+    }
+}

package/packages/agent/src/services/evm-signing-capability.d.ts

@@ -0,0 +1,33 @@
+import type { EvmSigningCapabilityKind } from "@elizaos/shared";
+/**
+ * EVM signing capability resolver.
+ *
+ * Enumerates the possible paths for signing EVM transactions and reports
+ * which (if any) is usable in the current process. A single authority for
+ * "does plugin-wallet have a working signer?" — consumed by auto-enable logic
+ * and wallet UI diagnostics so both agree on state.
+ *
+ * Paths (see `EvmSigningCapabilityKind` in shared/contracts/wallet.ts):
+ *   - "local"         — EVM_PRIVATE_KEY is set and non-placeholder
+ *   - "steward-self"  — self-hosted Steward (STEWARD_API_URL + STEWARD_AGENT_TOKEN,
+ *                       ELIZA_CLOUD_PROVISIONED != "1")
+ *   - "steward-cloud" — cloud-provisioned Steward sidecar (same creds,
+ *                       ELIZA_CLOUD_PROVISIONED == "1")
+ *   - "cloud-view-only" — cloud bind stored ELIZA_CLOUD_EVM_ADDRESS but no
+ *                         signing path is wired (backend contract not yet
+ *                         implemented locally). Address is visible, but no
+ *                         transactions can be signed from this process.
+ *   - "none"          — no address, no signer
+ *
+ * The UI surfaces `reason` verbatim, so it should be short and user-facing.
+ */
+export type { EvmSigningCapabilityKind };
+export interface EvmSigningCapability {
+    kind: EvmSigningCapabilityKind;
+    /** True when this capability can sign transactions in-process. */
+    canSign: boolean;
+    /** Short reason string for logs + UI. */
+    reason: string;
+}
+export declare function resolveEvmSigningCapability(env?: NodeJS.ProcessEnv): EvmSigningCapability;
+//# sourceMappingURL=evm-signing-capability.d.ts.map

package/packages/agent/src/services/evm-signing-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm-signing-capability.d.ts","sourceRoot":"","sources":["../../../../../src/services/evm-signing-capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,YAAY,EAAE,wBAAwB,EAAE,CAAC;AAEzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAqBD,wBAAgB,2BAA2B,CACzC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,oBAAoB,CAuCtB"}

package/packages/agent/src/services/evm-signing-capability.js

@@ -0,0 +1,52 @@
+const NONE = {
+    kind: "none",
+    canSign: false,
+    reason: "No EVM signing path configured",
+};
+/**
+ * Placeholder patterns that we treat the same as "unset". Mirrors the
+ * placeholder detection used in wallet.ts key validation so a stale
+ * "[REDACTED]" in env doesn't spoof capability detection.
+ */
+const PLACEHOLDER_RE = /^\[?\s*(REDACTED|PLACEHOLDER|T(?:O)D(?:O)|CHANGEME|EMPTY)\s*]?$/i;
+function isConcreteValue(value) {
+    const trimmed = value?.trim();
+    return Boolean(trimmed) && !PLACEHOLDER_RE.test(trimmed);
+}
+export function resolveEvmSigningCapability(env = process.env) {
+    if (isConcreteValue(env.EVM_PRIVATE_KEY)) {
+        return {
+            kind: "local",
+            canSign: true,
+            reason: "env: EVM_PRIVATE_KEY",
+        };
+    }
+    const stewardUrl = env.STEWARD_API_URL?.trim();
+    const stewardToken = env.STEWARD_AGENT_TOKEN?.trim();
+    if (stewardUrl && stewardToken) {
+        const isCloud = env.ELIZA_CLOUD_PROVISIONED === "1";
+        return isCloud
+            ? {
+                kind: "steward-cloud",
+                canSign: true,
+                reason: "cloud-provisioned Steward wallet",
+            }
+            : {
+                kind: "steward-self",
+                canSign: true,
+                reason: "self-hosted Steward wallet",
+            };
+    }
+    // Cloud bind persisted an address but no usable signing path is wired up
+    // in this runtime. The UI can still show the address (view-only), but
+    // plugin-wallet must NOT be auto-enabled — its actions would fail at runtime.
+    const cloudAddress = env.ELIZA_CLOUD_EVM_ADDRESS?.trim();
+    if (cloudAddress) {
+        return {
+            kind: "cloud-view-only",
+            canSign: false,
+            reason: "Cloud wallet provisioned (view-only — signing not yet wired)",
+        };
+    }
+    return NONE;
+}

package/packages/agent/src/services/external-bridge-state.d.ts

@@ -0,0 +1,10 @@
+/**
+ * External wallet bridge state — owned by the agent runtime so callers in this
+ * package don't have to reach upward into app plugin packages (plugins/app-*) for
+ * sync state queries. Outer-layer integrations (e.g. app-steward) write into
+ * this module via the public setters; agent-internal code reads via the
+ * getters.
+ */
+export declare function setStewardEvmBridgeActive(active: boolean): void;
+export declare function isStewardEvmBridgeActive(): boolean;
+//# sourceMappingURL=external-bridge-state.d.ts.map

package/packages/agent/src/services/external-bridge-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-bridge-state.d.ts","sourceRoot":"","sources":["../../../../../src/services/external-bridge-state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAE/D;AAED,wBAAgB,wBAAwB,IAAI,OAAO,CAElD"}

package/packages/agent/src/services/external-bridge-state.js

@@ -0,0 +1,14 @@
+/**
+ * External wallet bridge state — owned by the agent runtime so callers in this
+ * package don't have to reach upward into app plugin packages (plugins/app-*) for
+ * sync state queries. Outer-layer integrations (e.g. app-steward) write into
+ * this module via the public setters; agent-internal code reads via the
+ * getters.
+ */
+let stewardEvmBridgeActive = false;
+export function setStewardEvmBridgeActive(active) {
+    stewardEvmBridgeActive = active;
+}
+export function isStewardEvmBridgeActive() {
+    return stewardEvmBridgeActive;
+}