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

package/services/push/notification-push-service.js

@@ -0,0 +1,148 @@
+/**
+ * NotificationPushService
+ *
+ * The server-side bridge between the unified notification rail and remote push
+ * transports (APNs / FCM). It subscribes to the AgentEventService bus and, for
+ * every `stream:"notification"` event, fans the notification out to all
+ * registered device push tokens via the matching provider.
+ *
+ * DELIVERY POLICY (intentionally simple, documented):
+ *   - Every notification is pushed to every registered token of the matching
+ *     platform. The app dedupes by the notification `id` carried in the push
+ *     custom data against its in-app notification center, and the OS only
+ *     surfaces it when the app is backgrounded/killed.
+ *   - A "only push when the device isn't actively connected over WebSocket"
+ *     optimization is a future refinement; it is deliberately not implemented
+ *     here to keep the seam single-pathed.
+ *
+ * CREDENTIAL GATING: a provider is only used when `isConfigured()` is true.
+ * With NO provider configured the service still starts (so the registry/routes
+ * stay live) but logs once at debug and does nothing on each notification.
+ *
+ * VERIFIABILITY: subscription, no-op-when-unconfigured, token lookup, dispatch
+ * routing (ios→apns, android→fcm), and dead-token removal are unit-tested with
+ * an injected fake provider. Real network delivery is NOT tested — it needs
+ * live APNs/FCM credentials and a physical device.
+ */
+import { logger, NOTIFICATION_STREAM, Service, ServiceType, } from "@elizaos/core";
+import { ApnsProvider } from "./apns-provider.js";
+import { FcmProvider } from "./fcm-provider.js";
+import { PushTokenRegistry } from "./push-token-registry.js";
+import { PushUnregisteredError, } from "./push-types.js";
+/** Service type identifier for the push delivery service. */
+export const NOTIFICATION_PUSH_SERVICE_TYPE = "notification_push";
+function isSubscribableBus(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.subscribe === "function");
+}
+function isAgentNotification(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.id === "string" &&
+        typeof value.title === "string");
+}
+export class NotificationPushService extends Service {
+    static serviceType = NOTIFICATION_PUSH_SERVICE_TYPE;
+    capabilityDescription = "Delivers notifications to backgrounded/killed devices via APNs and FCM";
+    registry;
+    providers;
+    unsubscribe = null;
+    constructor(runtime, options) {
+        super(runtime);
+        this.registry = options?.registry ?? new PushTokenRegistry(runtime);
+        this.providers = options?.providers ?? {
+            ios: new ApnsProvider(),
+            android: new FcmProvider(),
+        };
+    }
+    static async start(runtime) {
+        const service = new NotificationPushService(runtime);
+        await service.attach();
+        return service;
+    }
+    /** Subscribe to the notification rail (idempotent). */
+    async attach() {
+        const anyConfigured = this.providers.ios.isConfigured() ||
+            this.providers.android.isConfigured();
+        if (!anyConfigured) {
+            logger.debug({ src: "service:notification_push" }, "[NotificationPushService] push delivery inactive (no APNs/FCM credentials)");
+        }
+        const bus = this.runtime.getService(ServiceType.AGENT_EVENT);
+        if (!isSubscribableBus(bus)) {
+            // No event bus (headless/test boot without AgentEventService): nothing to
+            // subscribe to. The registry + routes still function for diagnostics.
+            logger.debug({ src: "service:notification_push" }, "[NotificationPushService] no agent event bus; push delivery dormant");
+            return;
+        }
+        this.unsubscribe = bus.subscribe((event) => {
+            if (event.stream !== NOTIFICATION_STREAM)
+                return;
+            void this.onNotification(event);
+        });
+    }
+    /** The registry instance (used by the routes layer). */
+    getRegistry() {
+        return this.registry;
+    }
+    async onNotification(event) {
+        const notification = event.data?.notification;
+        if (!isAgentNotification(notification))
+            return;
+        // Skip work entirely when neither transport is configured.
+        if (!this.providers.ios.isConfigured() &&
+            !this.providers.android.isConfigured()) {
+            return;
+        }
+        const tokens = await this.registry.list();
+        if (tokens.length === 0)
+            return;
+        const message = toPushMessage(notification);
+        for (const record of tokens) {
+            const provider = this.providers[record.platform];
+            if (!provider.isConfigured())
+                continue;
+            await this.dispatch(provider, record.platform, record.token, message);
+        }
+    }
+    async dispatch(provider, platform, token, message) {
+        try {
+            await provider.send(token, message);
+        }
+        catch (error) {
+            if (error instanceof PushUnregisteredError) {
+                await this.registry.unregister(token);
+                logger.debug({ src: "service:notification_push", platform }, "[NotificationPushService] dropped unregistered push token");
+                return;
+            }
+            logger.error({ src: "service:notification_push", platform, error }, "[NotificationPushService] push delivery failed");
+        }
+    }
+    async stop() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+    }
+}
+/**
+ * Map an AgentNotification onto a PushMessage. The notification `id` and
+ * `deepLink` ride in custom data so the app can deep-link on tap and dedupe
+ * against the in-app center.
+ */
+function toPushMessage(notification) {
+    const data = {
+        notificationId: notification.id,
+        category: notification.category,
+    };
+    if (notification.deepLink)
+        data.deepLink = notification.deepLink;
+    if (notification.groupKey)
+        data.groupKey = notification.groupKey;
+    return {
+        title: notification.title,
+        body: notification.body,
+        data,
+    };
+}
+export default NotificationPushService;

package/services/push/push-token-registry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * PushTokenRegistry
+ *
+ * A small, persistent registry of device push tokens. Each registered device
+ * stores `{ token, platform, createdAt }`. The registry is keyed by token so a
+ * re-registration of the same token is an idempotent upsert (it refreshes
+ * `createdAt`).
+ *
+ * Persistence rides on the DB-backed runtime cache (`runtime.getCache` /
+ * `runtime.setCache`) under a single stable key, mirroring the persistence
+ * pattern in `@elizaos/core`'s `NotificationService`. A cold/headless runtime
+ * with no cache adapter starts empty and degrades to in-memory only.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+/** Mobile push transport a token belongs to. */
+export type PushPlatform = "ios" | "android";
+/** A single registered device push token. */
+export interface PushTokenRecord {
+    /** The raw device token (APNs hex token or FCM registration token). */
+    token: string;
+    /** Which transport delivers to this token. */
+    platform: PushPlatform;
+    /** Unix ms when first registered (refreshed on re-registration). */
+    createdAt: number;
+}
+export declare class PushTokenRegistry {
+    private readonly runtime;
+    private tokens;
+    private hydrated;
+    constructor(runtime: IAgentRuntime);
+    private get cacheKey();
+    /** Load persisted tokens from the DB-backed cache. Idempotent. */
+    hydrate(): Promise<void>;
+    private persist;
+    /**
+     * Register (upsert) a device token. Re-registering an existing token under a
+     * new platform moves it to that platform and refreshes `createdAt`.
+     */
+    register(platform: PushPlatform, token: string): Promise<void>;
+    /** Unregister a device token. Returns true if it existed. */
+    unregister(token: string): Promise<boolean>;
+    /** List every registered token record. */
+    list(): Promise<PushTokenRecord[]>;
+    /** List token records for one platform. */
+    listByPlatform(platform: PushPlatform): Promise<PushTokenRecord[]>;
+    /** Total number of registered tokens. */
+    count(): Promise<number>;
+}
+//# sourceMappingURL=push-token-registry.d.ts.map

package/services/push/push-token-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-token-registry.d.ts","sourceRoot":"","sources":["../../../src/services/push/push-token-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,SAAS,CAAC;AAE7C,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,YAAY,CAAC;IACvB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD,qBAAa,iBAAiB;IAIhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,MAAM,CAAsC;IACpD,OAAO,CAAC,QAAQ,CAAS;gBAEI,OAAO,EAAE,aAAa;IAEnD,OAAO,KAAK,QAAQ,GAEnB;IAED,kEAAkE;IAC5D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAehB,OAAO;IAIrB;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpE,6DAA6D;IACvD,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASjD,0CAA0C;IACpC,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAKxC,2CAA2C;IACrC,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAKxE,yCAAyC;IACnC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;CAI/B"}

package/services/push/push-token-registry.js

@@ -0,0 +1,91 @@
+/**
+ * PushTokenRegistry
+ *
+ * A small, persistent registry of device push tokens. Each registered device
+ * stores `{ token, platform, createdAt }`. The registry is keyed by token so a
+ * re-registration of the same token is an idempotent upsert (it refreshes
+ * `createdAt`).
+ *
+ * Persistence rides on the DB-backed runtime cache (`runtime.getCache` /
+ * `runtime.setCache`) under a single stable key, mirroring the persistence
+ * pattern in `@elizaos/core`'s `NotificationService`. A cold/headless runtime
+ * with no cache adapter starts empty and degrades to in-memory only.
+ */
+/** Stable cache key the registry persists under (scoped per agent). */
+const cacheKeyFor = (agentId) => `push-tokens:${agentId}`;
+export class PushTokenRegistry {
+    runtime;
+    tokens = new Map();
+    hydrated = false;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    get cacheKey() {
+        return cacheKeyFor(String(this.runtime.agentId));
+    }
+    /** Load persisted tokens from the DB-backed cache. Idempotent. */
+    async hydrate() {
+        if (this.hydrated)
+            return;
+        const stored = await this.runtime.getCache(this.cacheKey);
+        if (Array.isArray(stored)) {
+            this.tokens = new Map(stored
+                .filter(isPushTokenRecord)
+                .map((record) => [record.token, record]));
+        }
+        this.hydrated = true;
+    }
+    async persist() {
+        await this.runtime.setCache(this.cacheKey, [...this.tokens.values()]);
+    }
+    /**
+     * Register (upsert) a device token. Re-registering an existing token under a
+     * new platform moves it to that platform and refreshes `createdAt`.
+     */
+    async register(platform, token) {
+        const trimmed = token.trim();
+        if (!trimmed) {
+            throw new Error("[PushTokenRegistry] token is required");
+        }
+        await this.hydrate();
+        this.tokens.set(trimmed, {
+            token: trimmed,
+            platform,
+            createdAt: Date.now(),
+        });
+        await this.persist();
+    }
+    /** Unregister a device token. Returns true if it existed. */
+    async unregister(token) {
+        await this.hydrate();
+        const removed = this.tokens.delete(token.trim());
+        if (removed) {
+            await this.persist();
+        }
+        return removed;
+    }
+    /** List every registered token record. */
+    async list() {
+        await this.hydrate();
+        return [...this.tokens.values()];
+    }
+    /** List token records for one platform. */
+    async listByPlatform(platform) {
+        await this.hydrate();
+        return [...this.tokens.values()].filter((r) => r.platform === platform);
+    }
+    /** Total number of registered tokens. */
+    async count() {
+        await this.hydrate();
+        return this.tokens.size;
+    }
+}
+function isPushTokenRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.token === "string" &&
+        record.token.length > 0 &&
+        (record.platform === "ios" || record.platform === "android") &&
+        typeof record.createdAt === "number");
+}

package/services/push/push-types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared types for the remote-push delivery seam (APNs + FCM).
+ */
+import type { JsonValue } from "@elizaos/core";
+/** The user-facing content a single push carries. */
+export interface PushMessage {
+    /** Notification headline shown by the OS. */
+    title: string;
+    /** Optional longer body line. */
+    body?: string;
+    /**
+     * Structured custom data delivered alongside the alert so the app can
+     * deep-link and dedupe against the in-app notification center. Values are
+     * stringified by the FCM transport (FCM `data` is string→string only); APNs
+     * carries them as top-level JSON keys.
+     */
+    data?: Record<string, JsonValue>;
+}
+/**
+ * A push transport (APNs or FCM). `send` resolves on accept and throws on any
+ * HTTP/transport failure so the caller can react — in particular, an
+ * `PushUnregisteredError` signals the token is dead and should be dropped.
+ */
+export interface PushProvider {
+    /** Stable provider label for logs. */
+    readonly name: string;
+    /** True only when every required credential is present and well-formed. */
+    isConfigured(): boolean;
+    /** Deliver one message to one device token. Throws on failure. */
+    send(token: string, message: PushMessage): Promise<void>;
+}
+/**
+ * Thrown when a transport reports that a device token is no longer valid
+ * (APNs HTTP 410 / reason "Unregistered"; FCM 404 / UNREGISTERED). The caller
+ * removes the token from the registry on this error.
+ */
+export declare class PushUnregisteredError extends Error {
+    readonly token: string;
+    constructor(token: string, message: string);
+}
+//# sourceMappingURL=push-types.d.ts.map

package/services/push/push-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-types.d.ts","sourceRoot":"","sources":["../../../src/services/push/push-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC;IACxB,kEAAkE;IAClE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM,EAC7B,OAAO,EAAE,MAAM;CAKlB"}

package/services/push/push-types.js

@@ -0,0 +1,16 @@
+/**
+ * Shared types for the remote-push delivery seam (APNs + FCM).
+ */
+/**
+ * Thrown when a transport reports that a device token is no longer valid
+ * (APNs HTTP 410 / reason "Unregistered"; FCM 404 / UNREGISTERED). The caller
+ * removes the token from the registry on this error.
+ */
+export class PushUnregisteredError extends Error {
+    token;
+    constructor(token, message) {
+        super(message);
+        this.token = token;
+        this.name = "PushUnregisteredError";
+    }
+}

package/services/registry-client-app-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-client-app-meta.d.ts","sourceRoot":"","sources":["../../src/services/registry-client-app-meta.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,eAAe,EAGhB,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,yBAAyB,iDACU,CAAC;AAwCjD,wBAAgB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAwB3D;AA8CD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,eAAe,GAAG,SAAS,EACjC,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,eAAe,GAAG,SAAS,CAkB7B;AAED,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GAAG,SAAS,GACnC,eAAe,GAAG,SAAS,CAgD7B"}

package/services/registry-client-app-meta.js

@@ -0,0 +1,153 @@
+import { logger } from "@elizaos/core";
+import { packageNameToAppDisplayName } from "@elizaos/shared";
+export const LOCAL_APP_DEFAULT_SANDBOX = "allow-scripts allow-same-origin allow-popups";
+const ALLOWED_SANDBOX_TOKENS = new Set([
+    "allow-downloads",
+    "allow-forms",
+    "allow-modals",
+    "allow-orientation-lock",
+    "allow-pointer-lock",
+    "allow-popups",
+    "allow-popups-to-escape-sandbox",
+    "allow-presentation",
+    "allow-same-origin",
+    "allow-scripts",
+    "allow-storage-access-by-user-activation",
+    "allow-top-navigation-by-user-activation",
+]);
+const LOCAL_APP_OVERRIDES = {
+    "@elizaos/app-hyperfy": {
+        launchType: "connect",
+        launchUrl: "http://localhost:3003",
+        viewer: {
+            url: "http://localhost:3003",
+            sandbox: LOCAL_APP_DEFAULT_SANDBOX,
+        },
+    },
+};
+export function sanitizeSandbox(rawSandbox) {
+    if (!rawSandbox?.trim()) {
+        return LOCAL_APP_DEFAULT_SANDBOX;
+    }
+    const tokens = rawSandbox
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+    if (tokens.length === 0) {
+        return LOCAL_APP_DEFAULT_SANDBOX;
+    }
+    for (const token of tokens) {
+        if (!ALLOWED_SANDBOX_TOKENS.has(token)) {
+            logger.warn(`[registry-client] rejecting untrusted sandbox token: ${token}`);
+            return LOCAL_APP_DEFAULT_SANDBOX;
+        }
+    }
+    return Array.from(new Set(tokens)).join(" ");
+}
+function normalizeViewer(viewer) {
+    if (!viewer)
+        return undefined;
+    return {
+        ...viewer,
+        sandbox: sanitizeSandbox(viewer.sandbox),
+    };
+}
+function mergeViewer(base, patch) {
+    if (!base && !patch)
+        return undefined;
+    if (!base)
+        return normalizeViewer(patch);
+    if (!patch)
+        return normalizeViewer(base);
+    return normalizeViewer({
+        ...base,
+        ...patch,
+        embedParams: {
+            ...(base.embedParams ?? {}),
+            ...(patch.embedParams ?? {}),
+        },
+    });
+}
+function mergeSession(base, patch) {
+    if (!base && !patch)
+        return undefined;
+    if (!base)
+        return patch;
+    if (!patch)
+        return base;
+    return {
+        ...base,
+        ...patch,
+        features: patch.features && patch.features.length > 0
+            ? patch.features
+            : base.features,
+    };
+}
+export function mergeAppMeta(base, patch) {
+    if (!base && !patch)
+        return undefined;
+    if (!base)
+        return patch;
+    if (!patch)
+        return base;
+    return {
+        ...base,
+        ...patch,
+        capabilities: patch.capabilities.length > 0 ? patch.capabilities : base.capabilities,
+        runtimePlugin: patch.runtimePlugin ?? base.runtimePlugin,
+        bridgeExport: patch.bridgeExport ?? base.bridgeExport,
+        uiExtension: patch.uiExtension ?? base.uiExtension,
+        viewer: mergeViewer(base.viewer, patch.viewer),
+        session: mergeSession(base.session, patch.session),
+        developerOnly: patch.developerOnly ?? base.developerOnly,
+        visibleInAppStore: patch.visibleInAppStore ?? base.visibleInAppStore,
+        mainTab: patch.mainTab ?? base.mainTab,
+    };
+}
+export function resolveAppOverride(packageName, appMeta) {
+    const override = LOCAL_APP_OVERRIDES[packageName];
+    if (!override)
+        return appMeta;
+    const hasStandaloneMetadata = Object.values({
+        displayName: override.displayName,
+        category: override.category,
+        launchType: override.launchType,
+        launchUrl: override.launchUrl,
+        capabilities: override.capabilities,
+        runtimePlugin: override.runtimePlugin,
+        viewer: override.viewer,
+    }).some((value) => value !== undefined);
+    if (!appMeta && !hasStandaloneMetadata) {
+        return undefined;
+    }
+    const base = appMeta ?? {
+        displayName: override.displayName ?? packageNameToAppDisplayName(packageName),
+        category: override.category ?? "game",
+        launchType: override.launchType ?? "url",
+        launchUrl: override.launchUrl ?? null,
+        icon: null,
+        heroImage: null,
+        capabilities: override.capabilities ?? [],
+        minPlayers: null,
+        maxPlayers: null,
+        runtimePlugin: override.runtimePlugin,
+        uiExtension: override.uiExtension,
+        viewer: override.viewer,
+        session: override.session,
+    };
+    return {
+        ...base,
+        displayName: override.displayName ?? base.displayName,
+        category: override.category ?? base.category,
+        launchType: override.launchType ?? base.launchType,
+        launchUrl: override.launchUrl !== undefined ? override.launchUrl : base.launchUrl,
+        capabilities: override.capabilities !== undefined
+            ? override.capabilities
+            : base.capabilities,
+        runtimePlugin: override.runtimePlugin ?? base.runtimePlugin,
+        bridgeExport: base.bridgeExport,
+        uiExtension: override.uiExtension ?? base.uiExtension,
+        viewer: mergeViewer(base.viewer, override.viewer),
+        session: mergeSession(base.session, override.session),
+    };
+}

package/services/registry-client-endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-client-endpoints.d.ts","sourceRoot":"","sources":["../../src/services/registry-client-endpoints.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAKjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AA0DrE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CA4B5D;AAgLD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACxC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CAqBf"}