Background-tab notifications for pending user interactions and finished replies

[StephenZhang-hash]

Background-tab notifications for pending user interactions and finished replies

The problem

When the reader switches to another tab, the Web GUI has no way to pull them back. An ask_user_question prompt or an approval request just waits silently — no system notification, no title change, no badge — and a finished reply sits just as unread — so the session stalls until the reader happens to look back. Today the shell has no Notification API usage and no visibility tracking at all, so this stall is structural, not incidental.

The proposal

A small client plugin that watches the page visibility state and, while the tab is hidden, raises one system notification plus a once-per-second tab-title flash for:

1. each pending user interaction (a question or an approval request), and
2. each finished reply (a session's running → idle edge).

Returning to the tab settles everything at once.

Key behaviors:

• Order-independent. The pending alert fires whichever order "tab is hidden" and "a question arrived" happen in.
• One alert per interaction. A reader who returns and leaves again is not re-alerted for the same request; an answered request is pruned so a later same-key request alerts again.
• Completions alert at the edge only. A reply finishing while visible is dropped, not queued; several completions in one snapshot collapse into one alert.
• Graceful degradation. If the Notification API is missing or the permission is denied, the title flash still works alone. Permission is only ever asked from the settings-row toggle (a real user gesture), never spontaneously.
• Title-safe. The flasher tracks external title writes through a MutationObserver, so the layout's session-title projection always wins back the restored base title.

A General-settings switch (Settings → General → Background notifications) governs the behavior and persists through the Host user-settings document (notify.enabled, default on).

Reference implementation

I built this as a standalone client plugin package following the repo's conventions — one attention channel, all side effects behind a single injectable seam, and no cross-plugin mutable state beyond its settings namespace.

• Branch: StephenZhang-hash:feature/web-background-notifications
• Compare against upstream master: view diff

Contents: packages/client/notify (node + browser halves, locales, settings row), bilingual READMEs, an implemented Agent Note, bundle/tsconfig registrations, regenerated slot catalog, and 53 tests at 100% per-file coverage. pnpm run test:gui is green.

Happy to reshape this to fit the team's preferred seam if the visibility-watching responsibility belongs somewhere else in the shell.