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

package/packages/agent/src/services/app-run-store.js

@@ -0,0 +1,547 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { writeJsonAtomicSync } from "../utils/atomic-json.js";
+const APP_RUN_STORE_VERSION = 2;
+const MAX_RECORDED_RUN_EVENTS = 20;
+function nowIso() {
+    return new Date().toISOString();
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function _defaultStoreFile() {
+    return {
+        version: APP_RUN_STORE_VERSION,
+        updatedAt: nowIso(),
+        runs: [],
+    };
+}
+function normalizeAvailability(value) {
+    if (value === "available" || value === "unavailable") {
+        return value;
+    }
+    return "unknown";
+}
+function normalizeHealthState(value) {
+    if (value === "healthy" || value === "degraded" || value === "offline") {
+        return value;
+    }
+    return "unknown";
+}
+function normalizeHealthFacet(value, fallbackMessage) {
+    if (isRecord(value)) {
+        return {
+            state: normalizeHealthState(value.state),
+            message: typeof value.message === "string" ? value.message : fallbackMessage,
+        };
+    }
+    return {
+        state: "unknown",
+        message: fallbackMessage,
+    };
+}
+function deriveHealthStateFromStatus(status) {
+    const normalized = status.trim().toLowerCase();
+    if (normalized === "running" ||
+        normalized === "connected" ||
+        normalized === "active") {
+        return "healthy";
+    }
+    if (normalized === "stopped" ||
+        normalized === "offline" ||
+        normalized === "error" ||
+        normalized === "failed") {
+        return "offline";
+    }
+    return "degraded";
+}
+function deriveRunHealth(status, summary) {
+    return {
+        state: deriveHealthStateFromStatus(status),
+        message: summary,
+    };
+}
+function normalizeHealth(value, status, summary) {
+    if (isRecord(value)) {
+        const normalizedState = normalizeHealthState(value.state);
+        return {
+            state: normalizedState === "unknown"
+                ? deriveHealthStateFromStatus(status)
+                : normalizedState,
+            message: typeof value.message === "string" ? value.message : summary,
+        };
+    }
+    return deriveRunHealth(status, summary);
+}
+function normalizeViewerConfig(value) {
+    if (!isRecord(value) || typeof value.url !== "string") {
+        return null;
+    }
+    return {
+        url: value.url,
+        ...(isRecord(value.embedParams) &&
+            Object.values(value.embedParams).every((entry) => typeof entry === "string")
+            ? { embedParams: value.embedParams }
+            : {}),
+        ...(typeof value.postMessageAuth === "boolean"
+            ? { postMessageAuth: value.postMessageAuth }
+            : {}),
+        ...(typeof value.sandbox === "string" ? { sandbox: value.sandbox } : {}),
+        ...(isRecord(value.authMessage) &&
+            typeof value.authMessage.type === "string"
+            ? {
+                authMessage: {
+                    type: value.authMessage.type,
+                    ...(typeof value.authMessage.authToken === "string"
+                        ? { authToken: value.authMessage.authToken }
+                        : {}),
+                    ...(typeof value.authMessage.characterId === "string"
+                        ? { characterId: value.authMessage.characterId }
+                        : {}),
+                    ...(typeof value.authMessage.sessionToken === "string"
+                        ? { sessionToken: value.authMessage.sessionToken }
+                        : {}),
+                    ...(typeof value.authMessage.agentId === "string"
+                        ? { agentId: value.authMessage.agentId }
+                        : {}),
+                    ...(typeof value.authMessage.followEntity === "string"
+                        ? { followEntity: value.authMessage.followEntity }
+                        : {}),
+                },
+            }
+            : {}),
+    };
+}
+function normalizeSessionState(value) {
+    if (!isRecord(value) ||
+        typeof value.sessionId !== "string" ||
+        typeof value.appName !== "string" ||
+        typeof value.mode !== "string" ||
+        typeof value.status !== "string") {
+        return null;
+    }
+    return {
+        sessionId: value.sessionId,
+        appName: value.appName,
+        mode: value.mode === "viewer" ||
+            value.mode === "spectate-and-steer" ||
+            value.mode === "external"
+            ? value.mode
+            : "external",
+        status: value.status,
+        ...(typeof value.displayName === "string"
+            ? { displayName: value.displayName }
+            : {}),
+        ...(typeof value.agentId === "string" ? { agentId: value.agentId } : {}),
+        ...(typeof value.characterId === "string"
+            ? { characterId: value.characterId }
+            : {}),
+        ...(typeof value.followEntity === "string"
+            ? { followEntity: value.followEntity }
+            : {}),
+        ...(typeof value.canSendCommands === "boolean"
+            ? { canSendCommands: value.canSendCommands }
+            : {}),
+        ...(Array.isArray(value.controls)
+            ? {
+                controls: value.controls.filter((control) => control === "pause" || control === "resume"),
+            }
+            : {}),
+        ...(typeof value.summary === "string" || value.summary === null
+            ? { summary: value.summary }
+            : {}),
+        ...(typeof value.goalLabel === "string" || value.goalLabel === null
+            ? { goalLabel: value.goalLabel }
+            : {}),
+        ...(Array.isArray(value.suggestedPrompts)
+            ? {
+                suggestedPrompts: value.suggestedPrompts.filter((prompt) => typeof prompt === "string"),
+            }
+            : {}),
+        ...(isRecord(value.telemetry) || value.telemetry === null
+            ? {
+                telemetry: value.telemetry === null
+                    ? null
+                    : normalizeSessionJsonValue(value.telemetry),
+            }
+            : {}),
+    };
+}
+function normalizeSessionJsonValue(value) {
+    if (value === null)
+        return null;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value
+            .map((entry) => normalizeSessionJsonValue(entry))
+            .filter((entry) => entry !== null);
+    }
+    if (isRecord(value)) {
+        const normalizedRecord = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const normalizedEntry = normalizeSessionJsonValue(entry);
+            if (normalizedEntry !== null) {
+                normalizedRecord[key] = normalizedEntry;
+            }
+        }
+        return normalizedRecord;
+    }
+    return null;
+}
+function normalizeRunEvent(value) {
+    if (!isRecord(value))
+        return null;
+    if (typeof value.eventId !== "string" ||
+        typeof value.kind !== "string" ||
+        typeof value.severity !== "string" ||
+        typeof value.message !== "string" ||
+        typeof value.createdAt !== "string") {
+        return null;
+    }
+    const normalizedDetails = normalizeSessionJsonValue(value.details);
+    return {
+        eventId: value.eventId,
+        kind: value.kind === "launch" ||
+            value.kind === "refresh" ||
+            value.kind === "attach" ||
+            value.kind === "detach" ||
+            value.kind === "stop" ||
+            value.kind === "status" ||
+            value.kind === "summary" ||
+            value.kind === "health"
+            ? value.kind
+            : "status",
+        severity: value.severity === "info" ||
+            value.severity === "warning" ||
+            value.severity === "error"
+            ? value.severity
+            : "info",
+        message: value.message,
+        createdAt: value.createdAt,
+        status: typeof value.status === "string" ? value.status : null,
+        details: normalizedDetails &&
+            !Array.isArray(normalizedDetails) &&
+            typeof normalizedDetails === "object"
+            ? normalizedDetails
+            : null,
+    };
+}
+function normalizeRunEvents(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((event) => normalizeRunEvent(event))
+        .filter((event) => event !== null)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+        .slice(0, MAX_RECORDED_RUN_EVENTS);
+}
+function normalizeAwaySummary(value) {
+    if (!isRecord(value))
+        return null;
+    if (typeof value.generatedAt !== "string" ||
+        typeof value.message !== "string" ||
+        typeof value.eventCount !== "number") {
+        return null;
+    }
+    return {
+        generatedAt: value.generatedAt,
+        message: value.message,
+        eventCount: value.eventCount,
+        since: typeof value.since === "string" ? value.since : null,
+        until: typeof value.until === "string" ? value.until : null,
+    };
+}
+function deriveChatAvailability(session) {
+    if (!session)
+        return "unknown";
+    return session.canSendCommands ? "available" : "unavailable";
+}
+function deriveControlAvailability(session) {
+    if (!session)
+        return "unknown";
+    return session.canSendCommands || (session.controls?.length ?? 0) > 0
+        ? "available"
+        : "unavailable";
+}
+function deriveRunHealthFacetState(availability) {
+    if (availability === "available")
+        return "healthy";
+    if (availability === "unavailable")
+        return "degraded";
+    return "unknown";
+}
+function deriveRunHealthDetails(run) {
+    const viewerState = !run.viewer
+        ? "unknown"
+        : run.viewerAttachment === "attached"
+            ? "healthy"
+            : run.viewerAttachment === "detached"
+                ? "degraded"
+                : "offline";
+    const authState = run.session
+        ? run.viewerAttachment === "attached" || run.viewer == null
+            ? "healthy"
+            : "degraded"
+        : "unknown";
+    return {
+        checkedAt: run.updatedAt,
+        auth: {
+            state: authState,
+            message: run.session?.summary ?? run.summary,
+        },
+        runtime: {
+            state: run.health.state,
+            message: run.health.message,
+        },
+        viewer: {
+            state: viewerState,
+            message: run.viewerAttachment === "attached"
+                ? "Viewer attached."
+                : run.viewerAttachment === "detached"
+                    ? "Viewer detached."
+                    : "Viewer unavailable.",
+        },
+        chat: {
+            state: deriveRunHealthFacetState(run.chatAvailability),
+            message: run.chatAvailability === "available"
+                ? "Operator chat is available."
+                : run.chatAvailability === "unavailable"
+                    ? "Operator chat is unavailable."
+                    : "Operator chat availability is unknown.",
+        },
+        control: {
+            state: deriveRunHealthFacetState(run.controlAvailability),
+            message: run.controlAvailability === "available"
+                ? "Control actions are available."
+                : run.controlAvailability === "unavailable"
+                    ? "Control actions are unavailable."
+                    : "Control availability is unknown.",
+        },
+        message: run.health.message,
+    };
+}
+function buildAwaySummary(run) {
+    const events = run.recentEvents;
+    const latestMessages = events.slice(0, 3).map((event) => event.message);
+    const message = latestMessages.length > 0
+        ? latestMessages.join(" ")
+        : (run.summary ?? `${run.displayName} is ${run.status}.`);
+    return {
+        generatedAt: run.updatedAt,
+        message,
+        eventCount: events.length,
+        since: events.at(-1)?.createdAt ?? run.startedAt,
+        until: events[0]?.createdAt ?? run.updatedAt,
+    };
+}
+function normalizeRun(input) {
+    if (!isRecord(input))
+        return null;
+    const run = input;
+    if (typeof run.runId !== "string" ||
+        typeof run.appName !== "string" ||
+        typeof run.displayName !== "string" ||
+        typeof run.pluginName !== "string" ||
+        typeof run.launchType !== "string" ||
+        typeof run.status !== "string" ||
+        typeof run.startedAt !== "string" ||
+        typeof run.updatedAt !== "string" ||
+        typeof run.viewerAttachment !== "string" ||
+        !run.health ||
+        typeof run.health !== "object") {
+        return null;
+    }
+    const runId = run.runId;
+    const appName = run.appName;
+    const displayName = run.displayName;
+    const pluginName = run.pluginName;
+    const launchType = run.launchType;
+    const startedAt = run.startedAt;
+    const updatedAt = run.updatedAt;
+    const viewerAttachmentValue = run.viewerAttachment;
+    const session = normalizeSessionState(run.session);
+    const viewer = normalizeViewerConfig(run.viewer);
+    const status = typeof run.status === "string"
+        ? run.status
+        : typeof session?.status === "string"
+            ? session.status
+            : "offline";
+    const summaryValue = run.summary;
+    let summary;
+    if (summaryValue === null) {
+        summary = null;
+    }
+    else if (typeof summaryValue === "string") {
+        summary = summaryValue;
+    }
+    else if (typeof session?.summary === "string" ||
+        session?.summary === null) {
+        summary = session.summary ?? null;
+    }
+    else {
+        summary = null;
+    }
+    const recentEvents = normalizeRunEvents(run.recentEvents);
+    const supportsBackground = typeof run.supportsBackground === "boolean" ? run.supportsBackground : true;
+    const supportsViewerDetach = typeof run.supportsViewerDetach === "boolean"
+        ? run.supportsViewerDetach
+        : supportsBackground;
+    const characterId = typeof run.characterId === "string"
+        ? run.characterId
+        : (session?.characterId ?? null);
+    const agentId = typeof run.agentId === "string" ? run.agentId : (session?.agentId ?? null);
+    const chatAvailability = typeof run.chatAvailability === "string"
+        ? normalizeAvailability(run.chatAvailability)
+        : deriveChatAvailability(session);
+    const controlAvailability = typeof run.controlAvailability === "string"
+        ? normalizeAvailability(run.controlAvailability)
+        : deriveControlAvailability(session);
+    const normalizedHealth = normalizeHealth(run.health, status, summary);
+    const baseRun = {
+        runId,
+        appName,
+        displayName,
+        pluginName,
+        launchType,
+        launchUrl: typeof run.launchUrl === "string" ? run.launchUrl : null,
+        viewer,
+        session,
+        characterId,
+        agentId,
+        status,
+        summary,
+        startedAt,
+        updatedAt,
+        lastHeartbeatAt: typeof run.lastHeartbeatAt === "string"
+            ? run.lastHeartbeatAt
+            : session
+                ? updatedAt
+                : null,
+        supportsBackground,
+        supportsViewerDetach,
+        chatAvailability,
+        controlAvailability,
+        viewerAttachment: viewerAttachmentValue === "attached" ||
+            viewerAttachmentValue === "detached" ||
+            viewerAttachmentValue === "unavailable"
+            ? viewerAttachmentValue
+            : viewer
+                ? "detached"
+                : "unavailable",
+        recentEvents,
+        awaySummary: null,
+        health: normalizedHealth,
+        healthDetails: {
+            checkedAt: updatedAt,
+            auth: {
+                state: "unknown",
+                message: summary,
+            },
+            runtime: {
+                state: normalizedHealth.state,
+                message: normalizedHealth.message,
+            },
+            viewer: {
+                state: "unknown",
+                message: null,
+            },
+            chat: {
+                state: "unknown",
+                message: null,
+            },
+            control: {
+                state: "unknown",
+                message: null,
+            },
+            message: normalizedHealth.message,
+        },
+    };
+    const derivedHealthDetails = deriveRunHealthDetails(baseRun);
+    return {
+        ...baseRun,
+        awaySummary: normalizeAwaySummary(run.awaySummary) ?? buildAwaySummary(baseRun),
+        healthDetails: isRecord(run.healthDetails)
+            ? {
+                checkedAt: typeof run.healthDetails.checkedAt === "string"
+                    ? run.healthDetails.checkedAt
+                    : derivedHealthDetails.checkedAt,
+                auth: normalizeHealthFacet(run.healthDetails.auth, derivedHealthDetails.auth.message),
+                runtime: normalizeHealthFacet(run.healthDetails.runtime, derivedHealthDetails.runtime.message),
+                viewer: normalizeHealthFacet(run.healthDetails.viewer, derivedHealthDetails.viewer.message),
+                chat: normalizeHealthFacet(run.healthDetails.chat, derivedHealthDetails.chat.message),
+                control: normalizeHealthFacet(run.healthDetails.control, derivedHealthDetails.control.message),
+                message: typeof run.healthDetails.message === "string"
+                    ? run.healthDetails.message
+                    : derivedHealthDetails.message,
+            }
+            : derivedHealthDetails,
+    };
+}
+export function resolveAppRunStoreFilePath(stateDir = resolveStateDir()) {
+    return path.join(stateDir, "apps", "runs.v2.json");
+}
+export function resolveLegacyAppRunStoreFilePath(stateDir = resolveStateDir()) {
+    return path.join(stateDir, "apps", "runs.v1.json");
+}
+function readAppRunStoreFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            version: typeof parsed.version === "number" ? parsed.version : 0,
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : nowIso(),
+            runs: Array.isArray(parsed.runs) ? parsed.runs : [],
+        };
+    }
+    catch {
+        const corruptPath = `${filePath}.corrupt-${Date.now()}.json`;
+        if (fs.existsSync(filePath)) {
+            fs.renameSync(filePath, corruptPath);
+        }
+        return null;
+    }
+}
+export function readAppRunStore(stateDir = resolveStateDir()) {
+    const currentPath = resolveAppRunStoreFilePath(stateDir);
+    const legacyPath = resolveLegacyAppRunStoreFilePath(stateDir);
+    const current = readAppRunStoreFile(currentPath);
+    if (current) {
+        const currentRuns = current.runs
+            .map((run) => normalizeRun(run))
+            .filter((run) => run !== null)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        if (current.version >= APP_RUN_STORE_VERSION) {
+            return currentRuns;
+        }
+        writeAppRunStore(currentRuns, stateDir);
+        return currentRuns;
+    }
+    const legacy = readAppRunStoreFile(legacyPath);
+    if (!legacy) {
+        return [];
+    }
+    const migratedRuns = legacy.runs
+        .map((run) => normalizeRun(run))
+        .filter((run) => run !== null)
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    writeAppRunStore(migratedRuns, stateDir);
+    return migratedRuns;
+}
+export function writeAppRunStore(runs, stateDir = resolveStateDir()) {
+    const filePath = resolveAppRunStoreFilePath(stateDir);
+    const normalizedRuns = [...runs].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    writeJsonAtomicSync(filePath, {
+        version: APP_RUN_STORE_VERSION,
+        updatedAt: nowIso(),
+        runs: normalizedRuns,
+    });
+    return normalizedRuns;
+}

package/packages/agent/src/services/app-session-gate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Gate hosted app plugins so actions/providers only apply while the app session
+ * is active (AppManager run and/or overlay heartbeat for local overlay apps).
+ */
+import type { Plugin } from "@elizaos/core";
+/** True when an AppManager run exists for this canonical app name and is not stopped. */
+export declare function hasActiveAppRunForCanonicalName(appCanonicalName: string): boolean;
+/**
+ * True when the app is usable for agent actions: either a live AppManager run
+ * or a recent dashboard heartbeat for an overlay app (e.g. companion).
+ */
+export declare function isHostedAppActiveForAgentActions(appCanonicalName: string): boolean;
+/** Wrap a plugin so every action validate and provider get requires an active app session. */
+export declare function gatePluginSessionForHostedApp(plugin: Plugin, appCanonicalName: string): Plugin;
+//# sourceMappingURL=app-session-gate.d.ts.map

package/packages/agent/src/services/app-session-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-session-gate.d.ts","sourceRoot":"","sources":["../../../../../src/services/app-session-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAU,MAAM,EAAY,MAAM,eAAe,CAAC;AAU9D,yFAAyF;AACzF,wBAAgB,+BAA+B,CAC7C,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAKT;AAED;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAKT;AA8CD,8FAA8F;AAC9F,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAMR"}

package/packages/agent/src/services/app-session-gate.js

@@ -0,0 +1,71 @@
+/**
+ * Gate hosted app plugins so actions/providers only apply while the app session
+ * is active (AppManager run and/or overlay heartbeat for local overlay apps).
+ */
+import { readAppRunStore } from "./app-run-store.js";
+import { isOverlayAppPresenceActive } from "./overlay-app-presence.js";
+const STOPPED_STATUSES = new Set(["stopped", "offline", "error", "failed"]);
+function isRunStatusActive(status) {
+    return !STOPPED_STATUSES.has(status.trim().toLowerCase());
+}
+/** True when an AppManager run exists for this canonical app name and is not stopped. */
+export function hasActiveAppRunForCanonicalName(appCanonicalName) {
+    const runs = readAppRunStore();
+    return runs.some((run) => run.appName === appCanonicalName && isRunStatusActive(run.status));
+}
+/**
+ * True when the app is usable for agent actions: either a live AppManager run
+ * or a recent dashboard heartbeat for an overlay app (e.g. companion).
+ */
+export function isHostedAppActiveForAgentActions(appCanonicalName) {
+    if (hasActiveAppRunForCanonicalName(appCanonicalName)) {
+        return true;
+    }
+    return isOverlayAppPresenceActive(appCanonicalName);
+}
+function gateActions(actions, appCanonicalName) {
+    if (!actions?.length)
+        return actions;
+    return actions.map((action) => {
+        const prevValidate = action.validate;
+        return {
+            ...action,
+            validate: async (runtime, message, state) => {
+                if (!isHostedAppActiveForAgentActions(appCanonicalName)) {
+                    return false;
+                }
+                if (prevValidate) {
+                    return prevValidate(runtime, message, state);
+                }
+                return true;
+            },
+        };
+    });
+}
+function gateProviders(providers, appCanonicalName) {
+    if (!providers?.length)
+        return providers;
+    return providers.map((provider) => {
+        const prevGet = provider.get;
+        return {
+            ...provider,
+            get: async (runtime, message, state) => {
+                if (!isHostedAppActiveForAgentActions(appCanonicalName)) {
+                    return {
+                        text: "",
+                        data: { available: false, appSessionInactive: true },
+                    };
+                }
+                return prevGet(runtime, message, state);
+            },
+        };
+    });
+}
+/** Wrap a plugin so every action validate and provider get requires an active app session. */
+export function gatePluginSessionForHostedApp(plugin, appCanonicalName) {
+    return {
+        ...plugin,
+        actions: gateActions(plugin.actions, appCanonicalName),
+        providers: gateProviders(plugin.providers, appCanonicalName),
+    };
+}