Add Android push notifications through FCM

[Rowan-Paul]

Idea

Add push notifications for the Android app through Firebase Cloud Messaging (FCM).

Current behavior

Device Notifications and Live Activity Updates are iOS-only. Android users cannot receive a notification when an agent needs approval or input, completes work, or fails.

Issue #4892 fixed the misleading Android settings UI by labeling these controls as iOS-only, but it did not track Android notification support itself.

Proposed scope

• Register Android FCM device tokens with T3 Connect.
• Deliver approval, input, completion, and failure notifications through FCM.
• Open the correct environment and thread when a user taps a notification.
• Add Android notification channels and per-event preferences.
• Keep Live Activities iOS-only. Android could use an ongoing notification later if useful.

This would make remote Android use much more practical while keeping the first version focused on ordinary push notifications.

[fionn77]

Another data point from an Android user, plus a map of what currently blocks this in the code.

What Android users see today

On T3 Code 1.0.3 from Google Play, Device Notifications is greyed out with no explanation, and flipping Live Activity Updates raises "Couldn't finish enabling Live Activities — This device could not be registered with T3 Connect, so Live Activities won't appear yet. They'll start once registration succeeds", after which the switch returns to off. #4981 fixes the labelling, but it merged on 2026-08-15, after 1.0.3 was cut, so that build still shows the old dialog. The wording reads like a broken relay or tunnel setup, so people go debugging T3 Connect instead of learning that the feature is iOS-only.

Why nothing can reach an Android device today

• packages/contracts/src/relay.ts:19 — RelayAgentAwarenessPlatform = Schema.Literal("ios"), and RelayDeviceRegistrationRequest requires iosMajorVersion >= 18 (line 50). An Android device cannot even describe itself in the current contract.
• apps/mobile/src/features/agent-awareness/registrationPayload.ts hardcodes platform: "ios".
• apps/mobile/src/features/agent-awareness/remoteRegistration.ts:162 — canRegisterRemoteLiveActivities() is Platform.OS === "ios", and device registration, push-token subscription, and the foreground refresh all sit behind it.
• apps/mobile/src/features/agent-awareness/notificationPermissions.ts:37 returns { type: "unsupported" } off iOS, which is what disables the Device Notifications row.
• infra/relay/src/agentActivity/ is APNs-only (ApnsClient, ApnsDeliveries, ApnsDeliveryQueue, ApnsProviderTokens, apnsJwt). There is no FCM code in the repo.

So this is unimplemented rather than misconfigured, which matches the scope in the first post.

One suggestion on sequencing

Full FCM support is a large first PR: widening the platform literal ripples through Devices, MobileRegistrations, DeliveryAttempts and AgentActivityPublisher; iosMajorVersion has to stop being mandatory; the relay gains a second delivery transport; and relay config gains a service-account credential.

A smaller slice that needs none of that: post a local Android notification from the app when a turn reaches a terminal phase while the app is backgrounded but still alive. The expo-notifications plugin is already configured for Android in apps/mobile/app.config.ts (androidNotificationIcon, androidNotificationColor), so this needs no relay change, no contract change, and no credentials. It only covers the case where the process survives in the background, so it is not a substitute for FCM — but it covers the common "phone in pocket while a turn finishes" case, and it lets the notification channel, per-event preferences, and tap-to-thread deep link land and get tested before any transport work starts.

Happy to test either on a real device.

[abcumpanici]

Problem Statement

Android is a supported T3 Code mobile client, but its T3 Connect agent-awareness path cannot register an Android push target. Android users therefore receive no operating-system notification when an agent needs approval or input, completes work, or fails after the app has moved to the background or been terminated. This weakens the core remote workflow: a user can start work from their phone, desktop, or web client, put the phone away, and then miss the moment when their attention is needed.

The current product presents Device Notifications and Live Activity Updates as iOS-only on Android. That accurately avoids a broken toggle, but it does not provide Android notification support. The relay contract and persistence model are iOS-shaped, and delivery is routed only through APNs.

Notification eligibility should follow the signed-in T3 Connect user and linked environment, not the client that created or most recently interacted with the thread. If an Android device has notifications enabled for a linked environment, eligible agent-activity transitions from that environment may notify the device whether the turn began on mobile, web, or desktop.

Solution

Add ordinary Android push notifications to the existing T3 Connect agent-awareness pipeline. The Android app will request notification permission, create the required Android notification channel, acquire and rotate an Expo push token, and register the device with the relay. The relay will route eligible approval, input, completion, and failure transitions to Android through the Expo Push Service, which delivers to Firebase Cloud Messaging, while preserving the existing APNs and iOS Live Activity paths.

Notifications must work while the Android app is backgrounded or terminated, respect the existing device and environment notification state, avoid duplicate or stale alerts, and open the exact environment and thread when tapped. Android Live Activities or a persistent ongoing agent notification are not part of this feature.

User Stories

1. As an Android user, I want Device Notifications to be available in Settings, so that I can opt into agent alerts on my phone.
2. As an Android user, I want T3 Code to request the native notification permission at the moment I enable notifications, so that the permission request has clear context.
3. As an Android user who grants permission, I want the setting to show enabled only after my device has been registered successfully, so that the UI does not claim delivery is working when it is not.
4. As an Android user who denies permission, I want T3 Code to explain the result and offer a route to system settings when the permission cannot be requested again, so that I can recover without reinstalling the app.
5. As an Android user, I want notification registration to recover automatically after a temporary network or relay failure, so that one failed attempt does not permanently disable alerts.
6. As an Android user, I want notification registration to refresh when the app returns to the foreground, so that permission and token changes are reconciled.
7. As an Android user, I want token rotation to update my existing device registration, so that notifications continue after FCM or Expo replaces the token.
8. As an Android user, I want signing out to unregister or disable the account-bound push target, so that later activity is not delivered to the wrong account on the same installation.
9. As an Android user, I want unlinking an environment or disabling notifications for it to stop future alerts from that environment, so that my current choices are respected.
10. As an Android user, I want a notification when an agent completes a turn, so that I know when the result is ready to review.
11. As an Android user, I want a notification when an agent fails, so that I can investigate or retry promptly.
12. As an Android user, I want a notification when an agent is waiting for approval, so that work does not remain blocked unnoticed.
13. As an Android user, I want a notification when an agent is waiting for input, so that I can continue the conversation promptly.
14. As an Android user, I do not want an alert merely because an agent started or is still running, so that routine progress does not create noise.
15. As an Android user, I want eligible alerts from every environment linked to my T3 Connect account, so that remote work is covered consistently.
16. As an Android user, I want completion alerts even when the thread was started from web or desktop, so that notification behavior does not depend on remembering which client began the work.
17. As an Android user, I want completion alerts even when my last interaction with the thread was not on mobile, so that switching surfaces does not silently change delivery.
18. As an Android user with multiple registered Android devices, I want each enabled device to receive eligible alerts, so that I can use whichever device is with me.
19. As a user with both iOS and Android devices, I want each platform to receive its supported notification type without one registration displacing the other, so that multi-device use remains reliable.
20. As an Android user, I want a notification to identify the thread and project without exposing message contents, prompts, tool output, credentials, or filesystem data, so that lock-screen alerts remain useful and privacy-conscious.
21. As an Android user, I want tapping a notification to open the correct environment and thread, so that I can act immediately.
22. As an Android user who taps a notification from a terminated app, I want navigation to occur once after startup and authentication state is ready, so that the tap is not lost or applied twice.
23. As an Android user who taps an old or malformed notification, I want T3 Code to reject unsafe external links and fall back safely, so that notification data cannot navigate outside supported app routes.
24. As an Android user, I want repeated publication of the same agent state to produce at most one alert, so that reconnects and retries do not spam me.
25. As an Android user, I want a queued completion or failure alert to be discarded if the thread has already resumed, so that I do not receive stale terminal information.
26. As an Android user, I want old terminal states replayed after a server restart to remain silent, so that historical work does not trigger new alerts.
27. As an Android user, I want temporary Expo or FCM delivery failures retried within bounded limits, so that transient outages do not unnecessarily lose notifications.
28. As an Android user, I want permanently rejected push tokens to be invalidated automatically, so that the relay stops attempting delivery to an unusable installation.
29. As an operator, I want Android delivery attempts, provider tickets, and receipts recorded without storing or logging complete push tokens, so that delivery can be diagnosed safely.
30. As an operator, I want missing Android push credentials to fail clearly during build or deployment validation, so that a release cannot appear healthy while Android delivery is impossible.
31. As an iOS user, I want APNs notifications and Live Activities to behave exactly as before, so that adding Android does not regress the shipped experience.
32. As a T3 Code maintainer, I want the Android transport to reuse the existing agent-activity phases, preferences, redacted payloads, and deep-link model, so that platform parity does not create a second product model.
33. As a T3 Code maintainer, I want Android delivery to be independent of a continuously running mobile connection, so that notifications still arrive when the app process is stopped.
34. As a T3 Code maintainer, I want the feature to be deliverable in focused, reviewable slices, so that the change does not repeat the risk of a single XXL cross-cutting pull request.

Implementation Decisions

• Treat this as Android parity for ordinary agent-activity notifications, not Android Live Activities. The supported alert phases are waiting for approval, waiting for input, completed, and failed. Starting and running phases do not create alert notifications.
• Use the Expo Push Service as the relay-facing Android transport. Expo will deliver to FCM using the Android credentials associated with the existing Expo project. Do not introduce a direct relay-to-FCM client or Firebase Admin SDK in this scope.
• Keep T3 Connect as the remote delivery boundary. A local-only notification generated by a still-running app is not sufficient because the acceptance criterion includes a backgrounded or terminated app.
• Base eligibility on the T3 Connect user, enabled environment link, registered device, OS permission, and notification preferences. Do not add thread-origin or last-mobile-interaction tracking.
• Extend the mobile-device contract from an iOS-only platform to an explicit iOS-or-Android platform. Platform-specific metadata must be optional or discriminated: iOS version and APNs routing belong to iOS; Android API level and Expo push token belong to Android.
• Keep APNs tokens and Expo push tokens in separate, unambiguous fields. Token uniqueness and ownership changes must be handled transactionally so one physical token cannot remain attached to multiple registrations or users.
• Migrate existing iOS device rows without requiring re-registration. Android-only metadata must not weaken existing iOS validation, and iOS-only fields must no longer be globally required.
• Report Android devices through the existing device-list response with their platform and notification state. Live Activities must report unavailable or disabled for Android rather than pretending to be configurable.
• Reuse the existing stable per-installation device identifier. Registration signatures and deduplication must include the platform-specific token and relevant device metadata so unchanged launches remain no-ops.
• On Android, use Expo notification permission APIs and platform-appropriate permission semantics. Create the notification channel before requesting a token or permission where required by the Android version.
• Create a stable high-importance Android channel for approval, input, completion, and failure alerts. Channel identifiers must remain stable across upgrades so user-controlled Android channel settings are preserved.
• Acquire an Expo push token using the configured Expo project identity. Re-register on token rotation, relevant permission changes, account changes, and foreground reconciliation.
• Enable the Device Notifications setting on supported Android builds. Preserve truthful intermediate and failure states: native permission alone is not proof that relay registration succeeded.
• Keep Live Activity settings visibly iOS-only on Android. Do not re-enable the Android Live Activity control as part of notification support.
• Route delivery by registered device platform and available token. Preserve APNs delivery for iOS and use Expo delivery for Android without sending the same logical alert twice to one device.
• Extract or centralize transport-independent transition and preference policy so APNs and Expo use the same definitions for newly attention-requiring, newly terminal, fresh, stale, enabled, and disabled states.
• Queue Android deliveries rather than blocking the agent-activity publication request on an external push provider. Queue payloads must be authenticated or integrity-protected consistently with the existing relay delivery model.
• Use a deterministic notification identity per environment and thread where supported so a newer state can replace an older alert instead of stacking contradictory notifications.
• Apply the existing terminal freshness window and delivery-time state recheck to Android. A queued terminal notification must be skipped if newer relay state shows that the thread resumed or otherwise superseded it.
• Validate and bound titles, bodies, identifiers, timestamps, phases, and deep links before enqueueing or delivering. The payload contains only redacted thread/project metadata already represented by agent-awareness state.
• Record the Expo ticket result when a message is accepted or rejected, then reconcile Expo receipts asynchronously. Transient failures may retry within bounded limits; permanent device-token failures invalidate the token.
• Make delivery attempts provider-aware while keeping a shared operational view across APNs and Expo. Never expose full APNs or Expo tokens in APIs, traces, errors, or logs.
• Reuse the existing notification-response navigation path. Android notification taps must carry the canonical environment ID, thread ID, and internal deep link and must support both warm and cold app starts.
• Preserve all current iOS APNs, permission, registration, notification, and Live Activity semantics. Android work must not force iOS through Expo Push Service.
• Store Android push credentials and Google service configuration in the existing EAS/secret-management path. Do not commit credential files or provide insecure fallback credentials.
• Validate required Android push configuration in preview and production build workflows, with an actionable error when configuration is absent. Development builds may explicitly report push as unavailable when they lack valid credentials.
• Land the implementation as focused dependent pull requests where practical: first contract/persistence and platform-neutral dispatch; second Expo queue, delivery, receipts, and operational state; third Android permission, registration, settings, native configuration, navigation, and real-device evidence. Each slice must preserve a working iOS path.
• Update the contributor-facing T3 Connect architecture documentation and user-facing mobile notification documentation when behavior ships.

Testing Decisions

• Prefer the highest existing behavioral seam: the relay's public API with real contract decoding and persistence, a drained delivery queue, and a stubbed Expo HTTP gateway. The primary scenario registers an Android device, publishes a signed running-to-completed transition, and observes one correct Expo delivery plus its recorded provider outcome.
• Tests assert externally visible behavior and durable state rather than private helper calls. Queue-driven tests wait for typed receipts or worker drains; they do not use arbitrary sleeps or polling.
• At the same relay seam, cover waiting-for-approval, waiting-for-input, completed, and failed transitions; verify that starting and running do not emit alert notifications.
• Verify that eligibility is user/environment/device based and does not depend on the client that initiated or last interacted with the thread.
• Verify global and per-event notification preferences, environment-link disablement, device unregistration, and OS-permission-derived registration state prevent delivery as expected. Per-event preference UI is not required by this spec, but the existing contract behavior must remain correct.
• Verify duplicate state publication, server replay, expired terminal state, and completion followed by resumed work do not produce duplicate or stale alerts.
• Verify multiple Android devices, mixed iOS/Android devices, token rotation, token reassignment, account changes, and device removal preserve isolation and do not overwrite another device's registration.
• Stub Expo responses to cover accepted tickets, transient request failures, partial batch failures, permanent token rejection, receipt success, receipt failure, malformed responses, and idempotent reconciliation.
• Verify delivery-attempt records identify the provider and outcome while exposing no complete token or sensitive agent content.
• Verify contract and migration compatibility using existing iOS rows and old-client request shapes so deployed iOS builds continue registering during a rolling relay deployment.
• Keep focused tests around mobile registration for Android permission granted/denied/cannot-ask-again, channel creation, Expo project identity, token acquisition, token rotation, foreground reconciliation, sign-out cleanup, and truthful registration status.
• Reuse the existing notification-navigation tests for Android payloads, including exact thread routing, cold-start consumption, duplicate response suppression, malformed payloads, and rejection of external or unsupported links.
• Reuse the existing MobileRegistrations, Devices, AgentActivityPublisher, APNs delivery, managed-relay, remote-registration, and notification-navigation suites as prior art. Add provider-neutral assertions where behavior is shared and transport-specific assertions only at the transport boundary.
• Run focused relay, contracts, client-runtime, and mobile tests plus targeted typecheck and native mobile static analysis. Do not make a repository-wide check the acceptance seam.
• Produce one Android preview or development-client build with real configured push credentials and verify on a physical device: enable notifications, background the app, complete a thread, receive and tap the alert, then repeat with the app terminated. Capture the build identity, device/Android version, relay deployment, and observed result as PR evidence.
• Include an iOS regression pass proving APNs completion notification and Live Activity behavior still work after the shared contract and dispatch changes.

Out of Scope

• Android Live Activities, lock-screen live updates, widgets, or a persistent ongoing foreground-service notification.
• Keeping the Android WebSocket connection alive in the background; remote push delivery must not depend on that separate capability.
• Web or desktop completion notifications and sounds.
• A local-notification-only fallback that works only while the Android process survives.
• Direct relay integration with FCM or the Firebase Admin SDK; the relay-facing provider for this scope is Expo Push Service.
• Changing which agent-activity phases exist or changing the user-facing meaning of completed, failed, waiting for approval, or waiting for input.
• Restricting notifications to threads created or previously opened from mobile.
• Notification delivery for environments that are not linked to the signed-in T3 Connect user.
• A redesign of the full notification-preference UI, quiet hours, schedules, grouping preferences, custom sounds, or per-project rules.
• Remote notification actions such as approve, deny, reply, stop, or retry directly from the notification.
• Including prompts, responses, tool output, diffs, filenames, terminal output, or other sensitive work content in the notification.
• Unrelated Android identity/bootstrap or background-execution changes from earlier abandoned implementations unless a narrowly demonstrated dependency blocks reliable device registration.

Further Notes

• The current contract accepts only iOS agent-awareness devices and requires an iOS major version. Android permission and device registration paths return unsupported or exit early, while the relay's delivery implementation is APNs-specific. The notification-tap deep-link path and Expo Notifications package/configuration already exist and can be reused.
• Closed PR feat(android): implement T3 Connect end to end #3926 is useful prior art: it attempted Expo-based Android push end to end, including registration, relay schema, delivery tickets/receipts, invalid-token handling, settings, native configuration, and tests. It closed unmerged after changing 40 files with 4,218 additions, so it should be treated as a design reference rather than blindly revived.
• PR fix(mobile): explain iOS-only settings on Android #4981 intentionally made the unsupported Android controls truthful; this work supersedes only the Device Notifications limitation. Live Activities remain iOS-only.
• Issue [Bug]: T3 Connect mobile push/device registration fails — relay returns 404 on POST /v1/mobile/devices #7418 was closed after maintainers clarified that Android push is a separate feature proposal. This discussion is the canonical proposal for that feature.
• Open PR feat(mobile): keep Android connections alive in the background #5179 concerns keeping Android connections alive in the background and is not a substitute for terminated-app push delivery. Open PR feat(web): notification (and sound) when a thread finish #7348 concerns web notifications and is outside this mobile scope.
• Because the repository discourages large external feature PRs, maintainer agreement on the Expo transport and staged delivery should precede implementation. The prior XXL attempt demonstrates that one all-in-one PR is unlikely to be reviewable.