Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
PWA Web Push for Workbench Inbox · Design Doc
Branch:
feature/pwa-web-push-planStatus: Implementation in progress Owner: cyhhao
1. Goal
Add a first-class PWA Web Push notification path for the Workbench Inbox.
The product goal is not to replace the existing in-app realtime feed. It is to reach the user when the Vibe Remote Web UI is installed as a mobile PWA and the page is not actively open. The active Web UI should continue to use the existing SSE realtime channel.
This plan intentionally excludes email, IM, and native app push channels.
2. Platform Feasibility
PWA Web Push can reach the iOS notification shade when the following conditions are true:
- iOS/iPadOS is 16.4 or newer.
- The user has added the Web App to the Home Screen.
- The user opens the app from the Home Screen.
- The user grants notification permission from a direct user gesture.
- A registered service worker receives push events and calls
showNotification().
The same implementation also covers Chromium/Android and modern desktop browsers through the standard Push API.
Important iOS constraints:
- Ordinary Safari tabs are not enough for iOS notification delivery. The app must be a Home Screen Web App.
- Permission prompts must be initiated by a user action.
- Safari does not provide a useful invisible-push path for our use case. The service worker should show a notification for every delivered push event.
- Notifications are tied to each installed web app's origin. A subscription should therefore be treated as a per-device/per-install endpoint, not a global user preference.
3. Current Code Facts
PWA shell
The UI already ships a PWA manifest and iOS standalone metadata:
ui/public/manifest.webmanifestui/index.html
The HTML currently says "No service worker on purpose" so frontend assets stay network-fresh. That means the app is installable but cannot yet receive Web Push.
In-app realtime
Workbench realtime is already implemented and should stay as the active-page transport:
- Frontend opens one
EventSource('/api/events'). WorkbenchInboxContextowns the shared inbox cache.inbox.session.updatedupserts/re-sorts a session card.inbox.unread.changedrefreshes unread state after mark-read.- The UI server exposes
/api/eventsas an SSE stream with keep-alive pings. vibe.sse_broker.SSEBrokerfans events out to browser subscribers.- Controller-side agent replies publish through
core.inbox_events.bus,GET /internal/events, andvibe.inbox_bridgeinto the UI server broker.
SSE is an in-memory fan-out, not a persistent event log. It is correct for open-page realtime and should not be used as the mobile background notification mechanism.
4. Boundary Decision
Keep two separate capabilities:
| Capability | Runtime state | Transport | Responsibility |
|---|---|---|---|
| Active Web UI realtime | Page open | SSE /api/events |
Update chat, inbox list, unread counts |
| User reachability | Page closed/backgrounded | Web Push | Show OS notification and badge |
The Web Push path should trigger from durable message/inbox write paths, not from browser SSE subscription state. A missing or disconnected browser should not affect whether a notification is sent.
5. Data Model
Add a SQLite table for PWA push subscriptions.
Proposed table: web_push_subscriptions
| Column | Purpose |
|---|---|
id |
Stable local UUID / token |
user_key |
Local authenticated user key, or "local" when no remote user is known |
endpoint |
Push endpoint URL; unique |
p256dh |
Browser public encryption key |
auth |
Browser auth secret |
user_agent |
Optional client user agent snapshot |
device_label |
Optional label shown in settings/debug UI |
enabled |
Soft-disable without deleting history |
last_success_at |
Last successful send |
last_failure_at |
Last failed send |
failure_count |
Consecutive failures |
created_at |
Created timestamp |
updated_at |
Updated timestamp |
Why SQLite instead of V2 config:
- Subscriptions are runtime/device state, not user-authored configuration.
- A user may have multiple installed PWAs/devices.
- Endpoints rotate or expire and need operational metadata.
- The existing durable state model already owns messages, sessions, media, show pages, and background runs.
Migration work:
- Add
storage.models.web_push_subscriptions. - Add an Alembic migration after the current head.
- Extend
storage.migrationsdrift repair andHEAD_TABLES/required columns if needed. - Add a small
storage/web_push_service.pywith CRUD and failure handling.
6. VAPID Keys and Configuration
Use standard Web Push with VAPID.
Implementation choice:
- Add Python dependency
pywebpushunless a smaller maintained library is preferred during implementation review. - Generate a local VAPID keypair automatically on first use and store it under the Vibe Remote state directory, not in source.
- Expose the public VAPID key through an authenticated API endpoint.
Suggested storage:
- Private key:
~/.vibe_remote/state/web_push_vapid.json - Public key: returned by
GET /api/web-push/vapid-public-key
Rationale:
- Self-hosted installs should work without external setup.
- VAPID private key is secret runtime state and must not live in repo config.
- Keeping a stable key preserves existing subscriptions across restarts.
7. Backend API
Add authenticated UI APIs:
GET /api/web-push/status
Returns feature availability and current browser-independent server status:
configuredpublic_keysubscription_count
GET /api/web-push/vapid-public-key
Returns the base64url public VAPID key for PushManager.subscribe().
POST /api/web-push/subscriptions
Accepts the browser PushSubscription JSON and upserts by endpoint.
Input:
{
"endpoint": "https://...",
"keys": {
"p256dh": "...",
"auth": "..."
},
"user_agent": "..."
}
Validation:
endpointmust be a non-empty HTTPS URL.keys.p256dhandkeys.authmust be non-empty strings.- Reject malformed payloads with 400.
DELETE /api/web-push/subscriptions
Accepts an endpoint and disables/removes that subscription.
POST /api/web-push/test
Sends a test notification to the current subscription/device. This is necessary because iOS support must be validated on a real device after Home Screen install and permission grant.
8. Frontend and Service Worker
Service worker
Add ui/public/push-sw.js or equivalent static asset.
Responsibilities:
- Listen for
push. - Parse payload defensively.
- Call
self.registration.showNotification(title, options). - Update badge when supported (
navigator.setAppBadgeis page-side; service worker support differs, so keep badge best-effort). - Listen for
notificationclick. - Focus an existing client if available; otherwise open the target URL.
Payload shape:
{
"title": "Agent replied",
"body": "Short preview text",
"url": "/sessions/<session_id>",
"tag": "session:<session_id>",
"badge_count": 3
}
App registration
Add a small frontend module, for example ui/src/lib/webPush.ts.
Responsibilities:
- Detect support:
serviceWorkerinnavigatorPushManagerinwindowNotificationinwindow
- Detect standalone display where possible:
matchMedia('(display-mode: standalone)')- iOS
navigator.standalone
- Register service worker only when the user opts in.
- Request permission only inside the click handler.
- Subscribe with
userVisibleOnly: trueand the server public VAPID key. - Upsert the subscription to the backend.
UX placement:
- Put the first implementation in an existing Workbench/settings surface, not as an aggressive global prompt.
- Show the enable button only when the browser claims support.
- On iOS Safari that is not standalone, show a concise blocked state: add to Home Screen first, then open from the Home Screen.
All user-visible copy must go through ui/src/i18n/en.json and
ui/src/i18n/zh.json.
9. Notification Trigger
Trigger Web Push after durable inbox-relevant messages are persisted.
Initial trigger rule:
- Platform:
avibe - Session-backed message
- Message author:
agent - Message type:
resultor terminalnotify - Message is unread after persistence
Preferred implementation boundary:
- Add
core/web_push_notifications.pyas the notification dispatcher. - Call it from the same durable write paths that already compute/publish
inbox.session.updated. - Keep it non-blocking for agent turns: failures should be logged and recorded on subscriptions but must not break message persistence or SSE realtime.
The first implementation can be synchronous in a threadpool or fire-and-forget task, but it should have one clear service boundary so later batching/rate-limit logic can land without changing message persistence again.
Deduping:
- Use the persisted
message.idas the logical notification id. - If needed, add a small
web_push_deliveriestable later. Do not add it in the first pass unless duplicate sends appear in tests or runtime.
10. In-App Realtime Check
The current SSE path is good enough to remain the active UI realtime foundation.
Recommended small hardening:
- On
EventSourceconnected, refresh the inbox snapshot. This reconciles any events missed during reconnect. - On
visibilitychangefrom hidden to visible, refresh the inbox snapshot. - Keep realtime events as fast incremental updates, but treat REST snapshots as authoritative.
This hardening belongs in WorkbenchInboxContext; it does not require a new
transport.
11. Test Plan
Backend unit tests:
- Subscription upsert validates required fields and endpoint uniqueness.
- Disabled/expired subscription is skipped.
- 410/404 Web Push response disables a subscription.
- Inbox notification trigger sends only for avibe unread agent
result/terminalnotifymessages. - Message persistence still succeeds when Web Push send fails.
Frontend tests/build:
npm run build.- Type-check service worker registration helper.
- Verify i18n keys exist in English and Chinese.
Manual device validation:
- Serve the branch through the regression or an isolated dev environment over HTTPS.
- Open on iOS 16.4+ Safari.
- Add Vibe Remote to Home Screen.
- Open the Home Screen app.
- Tap "Enable notifications".
- Confirm the iOS permission prompt.
- Send
/api/web-push/test. - Lock the phone or leave the app.
- Confirm the notification appears in the iOS notification shade.
- Tap the notification and confirm it opens the intended Workbench session.
Non-goals for the first validation:
- Email fallback.
- IM fallback.
- Cross-device notification preference UI.
- Full delivery analytics.
12. Implementation Phases
Phase 1: Plan and skeleton
- Land this plan.
- Add storage service and migration for subscriptions.
- Add VAPID key generation/loading.
Phase 2: API and service worker
- Add authenticated Web Push APIs.
- Add
push-sw.js. - Add frontend helper and opt-in UI.
- Add test notification endpoint.
Phase 3: Inbox trigger
- Hook durable agent result/notify persistence into Web Push dispatcher.
- Keep failures isolated from message persistence.
- Add focused tests.
Phase 4: Realtime hardening
- Refresh inbox on SSE connected/reconnected.
- Refresh inbox on page visibility restore.
Phase 5: Device validation
- Build UI.
- Run focused Python tests.
- Validate on a real iOS 16.4+ Home Screen PWA.
13. Current Implementation Status
Implemented in this branch:
- SQLite
web_push_subscriptionsmodel, Alembic migration, and storage helpers. - Local VAPID key generation under the Vibe Remote state directory.
- Authenticated Web Push status, subscribe, unsubscribe, public-key, and test-send APIs.
- Static push service worker with
pushandnotificationclickhandling. - Inbox toolbar opt-in control with iOS standalone/PWA support detection.
- Durable Workbench inbox trigger from agent
result/notify/errormessages. - Owner scoping: subscriptions are bound to the current remote user when known, with local-install fallback for non-remote local UI.
- Targeted backend tests, migration coverage, and frontend production build.
Still pending before release:
- Real iOS Home Screen PWA validation on an actual device.
- Product decision on notification noise suppression when the same session is actively open.
- Optional settings surface for listing/removing multiple registered devices.
14. Open Questions
- Should the first opt-in UI live in Settings or directly in the Inbox header? Settings is less intrusive; Inbox is more discoverable.
- What should
user_keybe when remote access is disabled? The first pass can use"local"and evolve once multi-user local Web UI is real. - Should terminal
notifymessages push in v1? They are inbox-visible and can represent failures that need attention, but regular progress notifications should not wake the user.