#3196: Feature request: Web Push / iOS PWA notifications for completed agent runs and cron deliveries

Feature Description

Add optional Web Push notifications to Hermes WebUI, including support for iOS/iPadOS Home Screen PWA notifications.

Hermes WebUI already has basic PWA support via manifest.json and sw.js, but it currently does not appear to implement browser push notifications:

• no Notification / Notification API flow
• no PushManager / PushSubscription registration
• no push / notificationclick service worker handlers
• no backend API for storing browser push subscriptions
• no VAPID / Web Push sending path

This request is for an opt-in notification channel so WebUI can notify users at the OS level when useful events happen.

Motivation

Hermes WebUI is increasingly usable as a mobile / tablet command center, especially when installed as a PWA.

However, if a user starts a long-running agent task or relies on scheduled jobs, they currently need to keep the WebUI open or use another platform such as Telegram/Discord to get notifications.

Useful notification events could include:

• agent run completed while the WebUI was backgrounded
• long-running background process finished (notify_on_complete)
• cron job delivered to WebUI origin / local UI
• user approval required for a pending tool call
• session received a new assistant reply
• agent run failed or needs attention

On iOS/iPadOS, Web Push is supported for installed Home Screen web apps on iOS 16.4+, so this would make Hermes WebUI much more useful as a standalone mobile app.

Proposed Solution

Frontend

Add an opt-in notifications section in Settings:

• Show whether browser notifications are supported.
• Explain platform requirements:
  • HTTPS required
  • iOS/iPadOS requires installing the PWA to the Home Screen
  • iOS 16.4+ required for Web Push
• Request notification permission from a user gesture.
• Register a push subscription via:

const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: vapidPublicKey,
});

• POST the subscription to a backend endpoint.

Backend

Add push subscription management endpoints, for example:

• GET /api/push/status
• GET /api/push/vapid-public-key
• POST /api/push/subscriptions
• DELETE /api/push/subscriptions/:id
• optional POST /api/push/test

Store subscriptions in WebUI state, preferably profile-aware if relevant.

Use VAPID Web Push for delivery. Configuration could be environment/config driven:

• HERMES_WEBUI_PUSH_ENABLED=true
• HERMES_WEBUI_VAPID_PUBLIC_KEY=...
• HERMES_WEBUI_VAPID_PRIVATE_KEY=...
• HERMES_WEBUI_VAPID_SUBJECT=mailto:...

Service Worker

Add push notification handlers to static/sw.js:

self.addEventListener('push', (event) => {
  const data = event.data ? event.data.json() : {};
  event.waitUntil(
    self.registration.showNotification(data.title || 'Hermes', {
      body: data.body || '',
      icon: './static/favicon-192.png',
      badge: './static/favicon-192.png',
      data: data.data || {},
    })
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const targetUrl = event.notification.data?.url || './';
  event.waitUntil(
    clients.matchAll({ type: 'window', includeUncontrolled: true }).then((clientList) => {
      for (const client of clientList) {
        if ('focus' in client) {
          client.navigate(targetUrl);
          return client.focus();
        }
      }
      return clients.openWindow(targetUrl);
    })
  );
});

Suggested Notification Events

Initial MVP could be small:

1. A manual “Send test notification” button.
2. Notify when a WebUI-originated agent run completes while the page is not visible.
3. Notify when a cron job delivery targets WebUI origin/local UI.

Later events could include:

• pending approval required
• failed run
• background process completion
• new reply in another session
• scheduled job failure

Alternatives Considered

Current workaround: use Hermes gateway delivery to Telegram/Discord and rely on those native apps for iOS notifications.

That works, but it means WebUI cannot operate as a self-contained notification surface.

Constraints / Notes

• Browser push requires HTTPS.
• iOS support requires the app to be installed to the Home Screen.
• iOS/iPadOS Web Push requires iOS 16.4+.
• Notifications should be opt-in and easy to disable.
• API/session responses should not be cached by the service worker.
• Subscriptions may need to be scoped to local WebUI auth/profile state.
• This should probably be disabled by default unless VAPID keys are configured.

Expected Outcome

Hermes WebUI can notify the user at the OS level when agent work finishes or needs attention, without requiring Telegram/Discord as the notification transport.