Expose the Alexa shopping list to Joanna through Home Assistant

[CCOSTAN]

Goal

Give Joanna read and scoped write access to the household's existing Alexa Shopping List without changing the voice habit of saying, "Alexa, add ... to my shopping list."

The first useful milestone is full item access, not only the incomplete-item count. Later work can use those items for product matching and draft-cart preparation, with a person reviewing the selected products before checkout.

Research decision - 2026-08-30

Stop waiting for Alexa Media Player to add list support. The preferred path is a controlled migration test from HACS Alexa Media Player to Home Assistant's core Alexa Devices integration. Do not keep both Amazon integrations running indefinitely.

What changed

• The live Home Assistant 2026.8.3 instance still has Alexa Media Player v5.15.7, no Alexa Devices config entry, and no todo entities.
• Alexa Media Player v5.15.7 still has no todo platform and still marks PUSH_TODO_CHANGE, PUSH_LIST_CHANGE, and PUSH_LIST_ITEM_CHANGE as unsupported. No shopping-list pull request was found, and the latest release remains v5.15.7.
• Alexa Media Player feature request #3518 was closed as not planned. Its active collaborator recommended the core Alexa Devices integration and said that is where current Alexa development is happening.
• The temporary HA Alexa To-do Lists integration was retired and archived on 2026-08-18 because its author contributed the feature to Home Assistant Core.
• Core Alexa Devices exposes shopping, to-do, and custom lists as standard Home Assistant todo entities. The platform supports reading item names plus adding, renaming, completing, reopening, and removing items.
• Core also supplies speak/announce notify entities, media-player metadata and controls, next alarm/reminder/timer sensors, routines, and per-device voice events. That makes replacement of most Alexa Media Player behavior plausible, but it must be proven against this repository before removal.
• Home Assistant 2026.8.3 has a stale-cache bug after Home Assistant writes to an Alexa list. Core PR #180598 now refreshes the affected list after create, update, and delete operations. The fix is merged, cherry-picked, and assigned to the 2026.9.0 milestone; test writes only after the installed release contains that fix.

Proposed architecture

Alexa voice -> Alexa Shopping List -> Alexa Devices todo entity -> bounded Joanna todo capability -> optional product matching -> draft cart -> human review

Joanna's existing bounded Home Assistant adapter can discover entities and read their state, so the open-item count would work immediately after the entity exists. Full list access still needs a narrow extension for:

• todo.get_items
• todo.add_item
• todo.update_item
• todo.remove_item

Limit those operations to the configured Alexa shopping-list entity. Keep the implementation shared and user-parameterized, with explicit policy for each household user.

Migration proof before removing Alexa Media Player

Alexa Media Player is still used by several automations and packages for notify.alexa_media_*, wake-alarm wrappers, and last-called-device behavior. A short, controlled overlap is acceptable for comparison; permanent dual Amazon sessions are not.

Validate these behaviors with core Alexa Devices:

• Announce and speak on every currently targeted Echo.
• Media state, title, artist, artwork, playback controls, and volume.
• Both bedroom next-alarm inputs through the replacement entities.
• Last-called behavior through the core per-device voice event.
• Alexa routines and any text-command behavior still in use.
• No authentication churn, rate limiting, or duplicate/unavailable entities during the test.

Alternatives reviewed

• Direct Joanna/Amazon client: pyalexatodo can read and modify Alexa lists, but it uses an unofficial reverse-engineered API and would add another Amazon session plus a second place to maintain list semantics. Core Alexa Devices already wraps the same class of Amazon access and provides Home Assistant-native entities.
• Amazon Data Portability: Amazon now documents an Alexa shopping-list export scope, but the product requires developer onboarding, identity/security assessment, allowlisting, customer authorization, and asynchronous export queries. Availability depends on customer location, and the interface is for importing data, not live list writes. It is not a practical operational list source here.
• AnyList or another Alexa skill: Amazon ended the old Lists Skill API on 2024-07-01. AnyList now requires phrases such as "Alexa, ask AnyList..." and no longer receives items added to Alexa's built-in Shopping List. That changes the household's established voice workflow.
• Alexa Shopping Actions: A custom Alexa skill can add a known Amazon ASIN to the customer's Amazon cart after confirmation, but it cannot read the built-in Alexa Shopping List; AMAZON.AddToList currently targets Wish Lists, not the Alexa Shopping List.
• Walmart cart: Walmart's published developer APIs are Marketplace seller APIs, not a consumer cart API. A future Walmart draft-cart flow will likely require an approved consumer connector or an isolated signed-in browser session. Product matching, substitutions, quantities, and checkout confirmation belong in that later phase.

Acceptance criteria

• Install a Home Assistant release containing the post-write refresh fix from core PR #180598.
• Add core Alexa Devices during a controlled test and expose the household Alexa Shopping List as one todo entity.
• Verify voice-added items appear promptly and todo.get_items matches the Alexa app.
• Verify add, rename, complete/reopen, and remove operations round-trip without stale reads or duplicates.
• Validate every required Alexa Media Player dependency listed above.
• Migrate off Alexa Media Player if parity is sufficient; otherwise document the exact remaining blocker before accepting any coexistence.
• Expose item reads to Joanna through one shared, allowlisted todo capability.
• Add scoped Joanna writes only after read behavior is stable and covered for both household users.
• Keep cart preparation separate from checkout; require human review of product matches and final purchase.
• Update relevant package documentation and focused tests when implemented.

[CCOSTAN]

Research update (2026-08-30): I changed this issue from an Alexa Media Player parity watch into a migration and Joanna-access plan.

The decisive findings are:

• Alexa Media Player list support is now explicitly not planned upstream.
• The standalone Alexa list integration has been retired because its feature moved into Home Assistant Core.
• Core Alexa Devices covers the list CRUD needed by Joanna and much of the media/notify/alarm surface currently supplied by Alexa Media Player.
• Home Assistant's own list writes had a cache-refresh defect in 2026.8.3; the fix is merged in home-assistant/core#180598, so the controlled test should wait until the installed release contains it.
• Joanna can already discover/read Home Assistant entities, but full shopping-list access requires a deliberately scoped todo adapter rather than exposing generic Home Assistant administration.
• Direct Amazon, Data Portability, AnyList, and retailer-cart paths all have larger workflow, support, or authorization drawbacks. Core Alexa Devices is the shortest supported path that preserves the household's existing Alexa voice behavior.

No Home Assistant or Joanna configuration was changed during this research. The next action is the controlled Alexa Devices parity test described in the revised acceptance criteria.

[CCOSTAN]

Implementation update (2026-08-30):

The Joanna-side preparation is now complete and intentionally inactive.

• Added a dedicated shopping_list tool. Reads map to home.read; add, complete, reopen, and remove map to home.write.
• Bound the tool to one configured todo.* entity. The caller cannot choose or enumerate another list.
• Kept production fail-closed with shoppingList.enabled: false and no entity ID until Alexa Devices creates the real list entity.
• Added duplicate protection for incomplete items, exact UID or unambiguous-summary matching for changes, explicit removal semantics, and post-write read-back verification.
• Kept one shared implementation for both household profiles with explicit policy coverage for each.
• Added focused tests, capability-catalog entries, configuration documentation, and multi-user feature contracts.

Validation completed:

• Focused runtime, policy, profile, catalog, and control-plane suite: 33/33 passed.
• Strict core multi-user audit: passed with 0 errors and 0 warnings.
• Strict full multi-user audit: passed with 0 errors and 0 warnings.
• Server and integration syntax checks passed.

This does not mark the live acceptance criteria complete. Home Assistant still has no Alexa shopping-list todo entity, and the installed 2026.8.3 release predates the write-refresh fix. Activation still requires:

1. Upgrade to a release containing home-assistant/core#180598.
2. Add Alexa Devices and confirm the exact shopping-list entity.
3. Set that entity in the staged shoppingList configuration and enable it.
4. Restart the Joanna appliance during a clear maintenance window.
5. Verify voice-added items plus read/add/complete/reopen/remove round trips against the Alexa app.

The capability is ready for that live binding; it cannot touch any list until those steps are complete.