Push notifications #16

[goncharik]

Push Notifications

Notify the iOS app when the self-hosted agent needs the user, even while backgrounded.

Architecture (3 components, this PR is the iOS app only)

• iOS app (this PR) — PushClient dependency client, app-delegate token/tap bridge, registration lifecycle, tap deep-link + nav-aware foreground suppression + approval badge, Settings toggle + "Send test notification", a plugin-readiness onboarding flow (below), and the push entitlement (aps-environment per-config) + remote-notification background mode.
• Push gateway — goncharik/hermes-mobile-push-gateway (private): stateless Cloudflare Worker holding the APNs .p8, mints the ES256 JWT, forwards to APNs.
• hermes-push plugin — goncharik/hermes-mobile-push-plugin (public): standalone pip plugin using hermes-agent's public plugin API (hermes-agent is not modified).

Privacy: only a generic title/body + session_id transit the gateway; content is fetched in-app over the private network. Plugin↔gateway HMAC is a shared secret.

Triggers (all four, via real plugin hooks — CLI + gateway)

• approval — pre_approval_request
• clarify — pre_tool_call filtered to the clarify tool (before the user is prompted; not duration-gated; suppresses that turn's trailing complete)
• turn-complete — post_llm_call (gated to ~>10s turns via a pre_llm_call start anchor + dedup)
• error — on_session_end (genuine failures only; not success/interrupt)

Onboarding flow

• On the sessions list appearing, the app checks plugin readiness via GET /api/dashboard/plugins/hub (ready / not-ready / unknown).
• Ready → request the system notification permission + register. Not ready (and not snoozed) → present a two-button info sheet. Unknown (404/error) → don't nag.
• Info sheet: "Ask agent to install" (opens a new chat with the install prompt pre-filled, not auto-sent) + "Later" + a small GitHub link. "Later" snoozes on a Fibonacci backoff (1→2→3→5→8→13→21→34→55→60-day cap).
• The Settings notifications toggle is gated by the same readiness check.

Tests

578 HermesKit tests + all snapshots green; app builds. (Gateway/plugin suites — 77 + 110 — live in their own repos.)

Before it works on a device (manual)

Apple: enable Push capability + create the APNs .p8. Gateway: set secrets + wrangler deploy, then point the plugin at the URL + shared HMAC secret. On-device E2E in both sandbox (Debug) and production (TestFlight).