@lelouchhe/webagent 0.3.0 → 0.4.0

package/lib/push-service.js

@@ -1,21 +1,78 @@
 import webpush from "web-push";
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
+import { log } from "./log.js";
+const slog = log.scope("push");
+const elog = log.scope("egress");
 const VAPID_FILE = "vapid.json";
 /** Remove a subscription after this many consecutive send failures. */
 const MAX_CONSECUTIVE_FAILURES = 5;
+/** Derive the push tag for an ACP event. Kept module-level so it can be
+ *  reused by the close-on-handle path without instantiating the service. */
+export function pushTagForEvent(sessionId, event) {
+    switch (event.type) {
+        case "prompt_done":
+            return `sess-${sessionId}-done`;
+        case "permission_request":
+            return `sess-${sessionId}-perm-${event.eventId ?? "0"}`;
+        case "bash_done":
+            return `sess-${sessionId}-bash-${event.eventId ?? "0"}`;
+        default:
+            return `sess-${sessionId}-${event.type}`;
+    }
+}
+/**
+ * True iff the push endpoint is an Apple (APNs / Web Push on Apple) host.
+ *
+ * We deliberately filter silent `kind:"close"` pushes to these endpoints in
+ * `sendToAll` — iOS Safari PWA enforces an undocumented silent-push budget
+ * that, once exhausted, causes WebKit to drop ALL subsequent pushes for the
+ * subscription (including user-visible `kind:"notify"`). APNs returns 201
+ * throughout, so the server has zero visibility.
+ *
+ * macOS Safari shares the same host but is not subject to that budget; the
+ * conflation here is accepted collateral damage until we add a `platform`
+ * column to `push_subscriptions`.
+ */
+export function isAppleEndpoint(endpoint) {
+    let host;
+    try {
+        host = new URL(endpoint).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return host === "web.push.apple.com" || host.endsWith(".push.apple.com");
+}
+function emptyClientState() {
+    return { visible: false, sessionId: null, endpoint: null, visibleSince: 0 };
+}
 export class PushService {
     store;
     vapidKeys;
-    clientVisibility = new Map(); // clientId → visible
-    clientEndpoints = new Map(); // clientId → push endpoint
-    clientSessions = new Map(); // clientId → currently viewed sessionId
+    /**
+     * Consolidated per-client state. Previously 3 separate Maps
+     * (clientVisibility/clientEndpoints/clientSessions) which drifted under
+     * partial updates. v2 merges them; `visibleSince` stamps when the client
+     * transitioned to visible so the server can TTL-expire "ghost" visibility
+     * records left by iOS PWA process suspension (where the client never gets
+     * to POST visible:false).
+     */
+    clients = new Map();
     /** endpoint → consecutive failure count (absent or 0 = healthy) */
     failureCounts = new Map();
-    constructor(store, dataDir, vapidSubject) {
+    globalVisibilitySuppression;
+    visibilityTtlMs;
+    now;
+    constructor(store, dataDir, vapidSubject, options = {}) {
         this.store = store;
         this.vapidKeys = this.loadOrGenerateKeys(dataDir);
         webpush.setVapidDetails(vapidSubject, this.vapidKeys.publicKey, this.vapidKeys.privateKey);
+        this.globalVisibilitySuppression =
+            options.globalVisibilitySuppression ?? true;
+        this.visibilityTtlMs = options.visibilityTtlMs ?? 60_000;
+        this.now = options.now ?? (() => Date.now());
     }
     // ---------------------------------------------------------------------------
     // VAPID keys
@@ -25,12 +82,14 @@ export class PushService {
         if (existsSync(filePath)) {
             chmodSync(filePath, 0o600);
             const keys = JSON.parse(readFileSync(filePath, "utf8"));
-            console.log("[push] loaded VAPID keys");
+            slog.info("loaded VAPID keys");
             return keys;
         }
         const keys = webpush.generateVAPIDKeys();
-        writeFileSync(filePath, JSON.stringify(keys, null, 2) + "\n", { mode: 0o600 });
-        console.log("[push] generated new VAPID keys");
+        writeFileSync(filePath, JSON.stringify(keys, null, 2) + "\n", {
+            mode: 0o600,
+        });
+        slog.info("generated new VAPID keys");
         return keys;
     }
     getPublicKey() {
@@ -39,81 +98,153 @@ export class PushService {
     // ---------------------------------------------------------------------------
     // Notification formatting
     // ---------------------------------------------------------------------------
-    formatNotification(sessionId, sessionTitle, eventType, eventData) {
-        const title = sessionTitle || "WebAgent";
+    formatNotification(sessionId, sessionTitle, eventType, eventData, tag) {
+        const title = sessionTitle ?? "WebAgent";
         let body;
         switch (eventType) {
             case "permission_request":
-                body = `⚿ ${eventData.description ?? "Permission requested"}`;
+                body = `⚿ ${typeof eventData.description === "string" ? eventData.description : "Permission requested"}`;
                 break;
             case "prompt_done":
                 body = "✓ Task complete";
                 break;
             case "bash_done": {
-                const cmd = eventData.command ?? "command";
-                const code = eventData.exitCode ?? "?";
+                const cmd = typeof eventData.command === "string" ? eventData.command : "command";
+                const code = typeof eventData.exitCode === "number" ||
+                    typeof eventData.exitCode === "string"
+                    ? String(eventData.exitCode)
+                    : "?";
                 body = `$ ${cmd} — exit ${code}`;
                 break;
             }
             default:
                 body = eventType;
         }
-        return { title, body, data: { sessionId } };
+        return { kind: "notify", title, body, tag, data: { sessionId } };
     }
     // ---------------------------------------------------------------------------
     // Client visibility tracking
     // ---------------------------------------------------------------------------
+    /**
+     * Atomic consolidated setter. All visibility/session/endpoint updates
+     * should route through here. Callers distinguish "preserve" from "clear"
+     * by omitting the key vs passing `null`. Returns an edge flag so the
+     * caller can fire edge-triggered side effects (e.g. sendClose) without
+     * double-firing on every heartbeat refresh.
+     */
+    updateClient(clientId, patch) {
+        const prev = this.clients.get(clientId) ?? emptyClientState();
+        const wasVisibleForSession = prev.visible && prev.sessionId != null ? prev.sessionId : null;
+        const next = { ...prev };
+        if (patch.visible !== undefined) {
+            next.visible = patch.visible;
+            next.visibleSince = patch.visible ? this.now() : 0;
+        }
+        if (patch.sessionId !== undefined)
+            next.sessionId = patch.sessionId;
+        if (patch.endpoint !== undefined)
+            next.endpoint = patch.endpoint;
+        const becameVisibleForSession = next.visible &&
+            next.sessionId != null &&
+            next.sessionId !== wasVisibleForSession
+            ? next.sessionId
+            : null;
+        // Any transition into "visible + session X" restarts the TTL clock,
+        // including a session-switch that arrives without an explicit
+        // visible:true in the patch (e.g. a session_created POST that only
+        // carries sessionId). Otherwise the TTL would keep counting from the
+        // previous session's first-visible moment and could prematurely
+        // declare the newly-focused session "stale".
+        if (becameVisibleForSession) {
+            next.visibleSince = this.now();
+        }
+        this.clients.set(clientId, next);
+        return { becameVisibleForSession };
+    }
+    /**
+     * Read-only snapshot for tests and diagnostics. Do NOT mutate the
+     * returned object.
+     */
+    getClientState(clientId) {
+        return this.clients.get(clientId) ?? null;
+    }
+    /** @deprecated Shim: prefer `updateClient({ visible })`. */
     setClientVisibility(clientId, visible) {
-        this.clientVisibility.set(clientId, visible);
+        this.updateClient(clientId, { visible });
     }
+    /** @deprecated Shim: prefer `updateClient({ sessionId })`. */
     setClientSession(clientId, sessionId) {
-        this.clientSessions.set(clientId, sessionId);
+        this.updateClient(clientId, { sessionId });
     }
+    /** @deprecated Shim: prefer `updateClient({ endpoint })`. */
     registerClient(clientId, endpoint) {
-        this.clientEndpoints.set(clientId, endpoint);
+        this.updateClient(clientId, { endpoint });
     }
     removeClient(clientId) {
-        this.clientVisibility.delete(clientId);
-        this.clientEndpoints.delete(clientId);
-        this.clientSessions.delete(clientId);
+        this.clients.delete(clientId);
     }
     hasVisibleClient() {
-        for (const visible of this.clientVisibility.values()) {
-            if (visible)
+        const now = this.now();
+        for (const s of this.clients.values()) {
+            if (s.visible && now - s.visibleSince <= this.visibilityTtlMs)
                 return true;
         }
         return false;
     }
-    /** Check if a specific endpoint has at least one visible client. */
+    /** Check if a specific endpoint has at least one visible (non-stale) client. */
     isEndpointVisible(endpoint) {
-        for (const [clientId, ep] of this.clientEndpoints) {
-            if (ep === endpoint && this.clientVisibility.get(clientId))
-                return true;
+        const now = this.now();
+        for (const s of this.clients.values()) {
+            if (s.endpoint !== endpoint)
+                continue;
+            if (!s.visible)
+                continue;
+            if (now - s.visibleSince > this.visibilityTtlMs)
+                continue;
+            return true;
         }
         return false;
     }
     /**
-     * Check if any client (across all endpoints) is visible and viewing the given session.
-     * A client with no session set does not suppress any session's push.
-     * Used for global suppression: if any client sees this session, all endpoints are skipped.
+     * Check if any client (across all endpoints) is visible and viewing the
+     * given session. A client with no session set does not suppress any
+     * session's push. Stale records (older than `visibilityTtlMs` since the
+     * last heartbeat refresh) are ignored — this is the server-side safety
+     * net for iOS PWA suspension, where the client's `visible:false` POST may
+     * never leave the device.
+     *
+     * Returns false unconditionally when global suppression is disabled via
+     * the `globalVisibilitySuppression` option (kill switch).
      */
     isSessionVisibleToAnyClient(sessionId) {
-        for (const [clientId, visible] of this.clientVisibility) {
-            if (visible && this.clientSessions.get(clientId) === sessionId)
-                return true;
+        if (!this.globalVisibilitySuppression)
+            return false;
+        const now = this.now();
+        for (const s of this.clients.values()) {
+            if (!s.visible)
+                continue;
+            if (s.sessionId !== sessionId)
+                continue;
+            if (now - s.visibleSince > this.visibilityTtlMs)
+                continue;
+            return true;
         }
         return false;
     }
     // ---------------------------------------------------------------------------
     // High-level: decide whether to push, and if so, send
     // ---------------------------------------------------------------------------
-    static NOTIFIABLE = new Set(["permission_request", "prompt_done", "bash_done"]);
+    static NOTIFIABLE = new Set([
+        "permission_request",
+        "prompt_done",
+        "bash_done",
+    ]);
     /**
      * Check if this event should trigger a push notification.
      * Returns true if a notification should be sent (caller should then call sendToAll).
      * Global session visibility suppression happens inside sendToAll.
      */
-    maybeNotify(sessionId, sessionTitle, eventType, eventData) {
+    maybeNotify(sessionId, sessionTitle, eventType, _eventData) {
         if (!PushService.NOTIFIABLE.has(eventType))
             return false;
         return true;
@@ -122,45 +253,207 @@ export class PushService {
     // Send push to all subscriptions
     // ---------------------------------------------------------------------------
     async sendToAll(notification) {
-        const subs = this.store.getAllSubscriptions();
-        if (subs.length === 0)
+        const allSubs = this.store.getAllSubscriptions();
+        if (allSubs.length === 0)
             return;
+        // Global visibility: if any client is viewing this session, suppress notify pushes.
+        // Close pushes are never suppressed — they're silent and are the mechanism
+        // by which cross-device recall actually closes banners on the "losing" devices.
+        if (notification.kind === "notify") {
+            const targetSession = notification.data.sessionId;
+            if (targetSession && this.isSessionVisibleToAnyClient(targetSession))
+                return;
+        }
+        // Skip Apple endpoints for silent close pushes to preserve iOS PWA's
+        // silent-push budget. See isAppleEndpoint() for rationale.
+        let subs = allSubs;
+        let filteredApple = 0;
+        if (notification.kind === "close") {
+            subs = allSubs.filter((s) => {
+                if (isAppleEndpoint(s.endpoint)) {
+                    filteredApple++;
+                    return false;
+                }
+                return true;
+            });
+            if (subs.length === 0) {
+                elog.info("sendClose", {
+                    tag: notification.tag,
+                    endpoints: 0,
+                    ok: 0,
+                    fail: 0,
+                    fail_410: 0,
+                    filtered_apple: filteredApple,
+                });
+                return;
+            }
+        }
         const payload = JSON.stringify(notification);
-        // Global visibility: if any client is viewing this session, suppress all push
-        if (this.isSessionVisibleToAnyClient(notification.data.sessionId))
-            return;
-        const results = await Promise.allSettled(subs.map((sub) => this.sendOne({ endpoint: sub.endpoint, keys: { auth: sub.auth, p256dh: sub.p256dh } }, payload)));
+        // Derive an RFC 8030 Topic so push services can collapse undelivered
+        // pushes on the wire. FCM (Chrome/Firefox desktop + Android) honors
+        // this and collapses correctly. APNs (iOS Safari PWA) does NOT — we
+        // verified in dogfood that two same-Topic pushes still surface as
+        // two stacked banners on iOS 17, even combined with the SW-side
+        // close-before-show workaround (see public/sw.js). Keep the header
+        // anyway: it's spec-compliant, cheap, and benefits every non-Apple
+        // client. iOS banner stacking is a platform limitation we accept.
+        const topic = tagToTopic(notification.tag);
+        const results = await Promise.allSettled(subs.map((sub) => this.sendOne({
+            endpoint: sub.endpoint,
+            keys: { auth: sub.auth, p256dh: sub.p256dh },
+        }, payload, { topic })));
+        let ok = 0;
+        let fail = 0;
+        let fail410 = 0;
         for (let i = 0; i < results.length; i++) {
             const result = results[i];
             const endpoint = subs[i].endpoint;
             if (result.status === "fulfilled") {
                 this.failureCounts.delete(endpoint);
+                ok++;
             }
             else {
+                fail++;
                 const err = result.reason;
                 if (err.statusCode === 410) {
-                    // Subscription expired — clean up immediately
+                    fail410++;
                     this.store.removeSubscription(endpoint);
                     this.failureCounts.delete(endpoint);
-                    console.log(`[push] removed expired subscription (410): ${endpoint.slice(0, 60)}…`);
+                    slog.info("removed expired subscription (410)", {
+                        endpoint: endpoint.slice(0, 60) + "…",
+                    });
                 }
                 else {
                     const count = (this.failureCounts.get(endpoint) ?? 0) + 1;
                     if (count >= MAX_CONSECUTIVE_FAILURES) {
                         this.store.removeSubscription(endpoint);
                         this.failureCounts.delete(endpoint);
-                        console.log(`[push] removed subscription after ${count} consecutive failures: ${endpoint.slice(0, 60)}…`);
+                        slog.info("removed subscription after consecutive failures", {
+                            count,
+                            endpoint: endpoint.slice(0, 60) + "…",
+                        });
                     }
                     else {
                         this.failureCounts.set(endpoint, count);
-                        console.error(`[push] send failed (${count}/${MAX_CONSECUTIVE_FAILURES}) for ${endpoint.slice(0, 60)}…:`, result.reason);
+                        slog.error("send failed", {
+                            count,
+                            max: MAX_CONSECUTIVE_FAILURES,
+                            endpoint: endpoint.slice(0, 60) + "…",
+                            error: result.reason,
+                        });
                     }
                 }
             }
         }
+        if (notification.kind === "close") {
+            // Observability signal #6 — aggregated per-call close outcome.
+            elog.info("sendClose", {
+                tag: notification.tag,
+                endpoints: subs.length,
+                ok,
+                fail,
+                fail_410: fail410,
+                filtered_apple: filteredApple,
+            });
+        }
+    }
+    /** Send a silent close push for the given tag. Never visibility-suppressed. */
+    async sendClose(tag) {
+        await this.sendToAll({ kind: "close", tag });
+    }
+    /**
+     * Send a push for an external message. Respects the message's `deliver`
+     * intent: `silent` sends nothing, `inapp` and `push` both send through
+     * web-push (the `inapp` vs `push` distinction is enforced by the SW /
+     * frontend rendering, not by the server).
+     *
+     * Tag = `msg-<id>` for unbound messages; bound messages get the
+     * `sess-<sid>-msg-<eid>` tag by taking a different code path in the
+     * consume handler.
+     */
+    async sendForMessage(msg) {
+        const deliver = msg.deliver ?? "push";
+        if (deliver === "silent")
+            return false;
+        const subs = this.store.getAllSubscriptions();
+        const title = msg.from_label ?? msg.from_ref ?? "Message";
+        const body = msg.body.length > 140 ? msg.body.slice(0, 137) + "…" : msg.body;
+        const tag = msg.dedup_key ? `dedup-${msg.to}-${msg.dedup_key}` : msg.id;
+        // If this message targets a specific session, surface the sid in the
+        // push data so SW notificationclick can route the user there. Without
+        // this, clicks fall back to "/" and land on whatever session was last
+        // open — a confusing UX when multiple sessions get background pushes.
+        const sessionId = msg.to.startsWith("session:")
+            ? msg.to.slice("session:".length)
+            : undefined;
+        // Observability signal #7 — sendForMessage entry.
+        elog.info("sendForMessage", {
+            msg_id: msg.id,
+            tag,
+            deliver,
+            endpoints: subs.length,
+            suppressed_by_visibility: false,
+        });
+        await this.sendToAll({
+            kind: "notify",
+            title,
+            body,
+            tag,
+            data: sessionId
+                ? { messageId: msg.id, sessionId }
+                : { messageId: msg.id },
+        });
+        return true;
+    }
+    /**
+     * Send a push for an ACP session event (permission_request / prompt_done /
+     * bash_done). Handles tag derivation, visibility suppression, and session-
+     * title lookup. Returns `true` if a push attempt was made.
+     */
+    async sendForEvent(sessionId, event) {
+        if (!PushService.NOTIFIABLE.has(event.type))
+            return false;
+        const session = this.store.getSession(sessionId);
+        const sessionTitle = session?.title ?? null;
+        const tag = pushTagForEvent(sessionId, event);
+        const eventData = {};
+        if (event.type === "permission_request" && event.title !== undefined) {
+            eventData.description = event.title;
+        }
+        if (event.type === "bash_done") {
+            if (event.command !== undefined)
+                eventData.command = event.command;
+            if (event.exitCode !== undefined)
+                eventData.exitCode = event.exitCode;
+        }
+        const suppressed = this.isSessionVisibleToAnyClient(sessionId);
+        const subs = this.store.getAllSubscriptions();
+        elog.info("sendForEvent", {
+            sess_id: sessionId.slice(0, 8),
+            type: event.type,
+            tag,
+            endpoints: subs.length,
+            suppressed_by_visibility: suppressed,
+        });
+        const notification = this.formatNotification(sessionId, sessionTitle, event.type, eventData, tag);
+        await this.sendToAll(notification);
+        return true;
     }
     /** Send a single push notification. Extracted for testability. */
-    sendOne(sub, payload) {
-        return webpush.sendNotification(sub, payload);
+    sendOne(sub, payload, options) {
+        return webpush.sendNotification(sub, payload, options);
     }
 }
+/**
+ * Derive an RFC 8030 `Topic` header value from a notification tag. The
+ * spec limits topic to ≤32 chars of URL-safe Base64, so we hash and
+ * truncate. FCM maps this to its on-wire collapse key and works
+ * correctly. APNs is documented to map Topic → `apns-collapse-id`,
+ * but in practice iOS Safari PWA (≤17 at least) still surfaces
+ * stacked banners for same-Topic pushes — confirmed in dogfood.
+ * We keep the header for the platforms where it does work and for
+ * spec compliance; don't expect it to fix iOS.
+ */
+function tagToTopic(tag) {
+    return createHash("sha256").update(tag).digest("base64url").slice(0, 22);
+}