Ha IOS Push Live Activities
Developmentha-ios-push-live-activitiesHa IOS Push Live Activities is an Agent Skill for development published in the home-assistant/iOS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Live Activities and push notifications across the local-push and remote-push delivery flows. Use when implementing or fixing notifications, Live Activities, payload parsing/promotion, alerting behavior, or the SharedPush parser (including the vendored relay copy).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/home-assistant/iOS/blob/HEAD/.agents/skills/ha-ios-push-live-activities/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ha-ios-push-live-activities, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Live Activities & Push Notifications
When implementing or fixing anything related to Live Activities (or push notifications generally), always check BOTH delivery flows — local push and remote push. They are handled by different code paths, so a field, behavior, or fix applied to one is easily missed in the other (e.g. a payload key parsed for APNs but dropped over local push, or alerting/sound handled differently per flow).
- Remote push (APNs / cloud): Home Assistant → the push relay (
Sources/PushServer) → APNs → the app /Sources/Extensions/NotificationService. The payload already carries ahomeassistantdictionary. - Local push (WebSocket /
NEAppPushProvider): delivered over the on-network channel and handled bySources/Extensions/PushProvider+Sources/Shared/Notifications/LocalPush(LocalPushManager,LocalPushEvent). The payload arrives as a flat{message, data}shape and is reshaped byLegacyNotificationParserImpl(Sources/SharedPush/Sources/NotificationParserLegacy.swift), which must explicitly promotedatafields intohomeassistant— any field not in that promotion list is silently dropped on this flow only.
Both flows converge on NotificationCommandManager → HandlerStartOrUpdateLiveActivity → LiveActivityRegistry (Sources/Shared/LiveActivity), with the UI rendered by Sources/Extensions/Widgets/LiveActivity.
Practical checklist when changing this area:
- If you add or read a notification/Live-Activity payload field, confirm it survives both the local-push parser promotion list and the remote-push payload.
- Verify alerting behavior (sound, haptics, banner suppression, the
silentflag) on both flows — local push presents notifications throughLocalPushManager, not the system directly. Sources/SharedPushis vendored as a separate copy underSources/PushServer/SharedPush(the relay). Keep the two parser copies in sync when a parsing change is relevant to both the app and the relay; some logic intentionally lives in only one copy (e.g. the Live Activitylive_updatepromotion is app-only, since the relay/cloud path already carries ahomeassistantdict). When you change one copy, decide explicitly whether the other needs the same change.- Add/extend tests for both flows (e.g.
Tests/Shared/LocalPushManager.test.swiftfor the local path,Sources/PushServer/Tests/SharedPushTestsfor the relay/parser).