feat(intents): the registered-intent engine, the buttons and the send_intent action (t17, part 1)

Second half of the intents feature (docs/INTENTS_PLAN.md §3-§5), engine first: the
options screen that WRITES a registration follows in this same ticket.

WHAT SHIPPED.

* THE MODEL (const.py + media_player.py). A registered intent is ordinary options
  data — a list of dicts {id,name,package,activity,action,categories,data,fields}
  — so it survives a reload and is otherwise inert. `normalise_intent` accepts a
  row only if it names something to launch (a component with the slash Android
  requires, OR an action), `registered_intents` reads the options defensively
  (junk rows dropped, duplicate ids keep the first, the registration cap applied)
  and never touches a shell.
* THE COMMAND. `intent_am_start_command` assembles
  `am start -n <component> -a <action> -c <category>… -d <data> --es/--ei/--ez key value`.
  `{placeholder}` substitution is plain regex replacement over the DATA template
  only — no eval, no format(), no shell interpolation — and every value is
  shlex.quote'd, so a variable whose value is `"; rm -rf /"` reaches the device as
  literal data inside one quoted word. Address validation for adb_command is
  untouched; `adb_command` stays the one raw-shell door.
* HONEST FAILURES, each with a plain message AND a translation key so the button
  and the action both read well: an unknown intent name lists the registered ones,
  a missing REQUIRED field names the field, a variable the intent did not declare
  is REFUSED (nothing silently travels to the device and nothing is silently
  dropped), a value that cannot become its declared type names the field and the
  value, a data template with an unfilled placeholder names the placeholder, ADB
  off/down says the protocol cannot carry intents, a transport that never answered
  says so, and a device that refused the intent surfaces the DEVICE'S OWN message
  ("unable to resolve Intent", "does not exist", "Permission Denial") and raises.
* THE ACTION. `nvidia_shield.send_intent` takes `intent` (a select selector whose
  options are the loaded intents, `custom_value` on) plus `variables`, resolves
  exactly ONE Shield through t14's resolver (one participant, or no_target /
  unsupported_target / ambiguous_target naming the service), and returns the
  device's output under `intent_response`. Registered with
  `SupportsResponse.OPTIONAL` FIRST, because `async_set_service_schema` reads
  `hass.services.supports_response()` to publish the response flag — the t14
  mechanism, re-verified against the installed HA for t17. The description is
  republished on every entry setup, so an options change (which reloads) refreshes
  the dropdown.
* THE BUTTONS. One button per registered intent (name from the registration, id
  from the intent's stable id so a rename does not orphan the entity), pressing it
  sends the intent with the fields' declared defaults and raises on every failure
  instead of doing nothing. Its extra attributes expose what it will send.

TWO MEASURED REPAIRS IN THE SAME HOOK (media_player.py). Both were latent because
the test harness pre-sets `_manager`:
* the service registries were filled BEFORE the entry's manager was assigned, so a
  real entry registered `None` and `adb_command` would crash with AttributeError
  instead of answering. The manager is now consumed first, and both registries are
  filled after it;
* `async_will_remove_from_hass` never dropped the entity's participation (the
  comment said it did), so a removed or unloaded entry left a stale manager and the
  action answered `adb_unavailable` for an entity that no longer exists instead of
  reporting an unsupported target. Both registries are dropped now, keyed by the
  key computed at add time.

Verify: 794 passed / 4 skipped and 795 passed / 3 skipped (androidtvremote2) —
unchanged counts, so nothing regressed; ruff clean.

custom_components/nvidia_shield/__init__.py

@@ -29,11 +29,13 @@ from .const import (
     CONF_HOST,
     CONF_PROTOCOL_ENABLED,
     CONF_PROTOCOL_HOST,
+    CONF_REGISTERED_INTENTS,
     DEFAULT_ADB_PORT,
     DEFAULT_NAME,
     DOMAIN,
     ENTRY_VERSION,
     SERVICE_ADB_COMMAND,
+    SERVICE_SEND_INTENT,
 )
 from .helpers import (
     entry_host,
@@ -90,7 +92,13 @@ async def async_setup(hass: HomeAssistant, config) -> bool:
     from homeassistant.core import SupportsResponse
     from homeassistant.helpers.service import async_set_service_schema
 
-    from .media_player import _ADB_COMMAND_SCHEMA, _async_adb_command_service
+    from .media_player import (
+        _ADB_COMMAND_SCHEMA,
+        _INTENT_SCHEMA,
+        _async_adb_command_service,
+        _async_send_intent_service,
+        send_intent_service_description,
+    )
 
     # t14: the action must be SELECTABLE for the user's Shield. Measured on HA
     # 2026.10.1: `async_register` has no `target` parameter, so the UI's target
@@ -111,6 +119,24 @@ async def async_setup(hass: HomeAssistant, config) -> bool:
     async_set_service_schema(
         hass, DOMAIN, SERVICE_ADB_COMMAND, ADB_COMMAND_SERVICE_DESCRIPTION
     )
+
+    # t17: send_intent — the same measured mechanism as t14 (a runtime
+    # description carries the target picker, and the response flag is read from
+    # the registration, so OPTIONAL is registered FIRST). The description is
+    # republished by every async_setup_entry because the intent DROPDOWN is
+    # per-entry data while the service is domain-wide; at domain setup no entry
+    # has loaded yet, so the list is empty and every name is still typeable
+    # (`custom_value`), with the call-time lookup as the authority.
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_SEND_INTENT,
+        _async_send_intent_service,
+        schema=_INTENT_SCHEMA,
+        supports_response=SupportsResponse.OPTIONAL,
+    )
+    async_set_service_schema(
+        hass, DOMAIN, SERVICE_SEND_INTENT, send_intent_service_description(())
+    )
     return True
 
 
@@ -133,6 +159,11 @@ def _yaml_seed_blocks(domain_config) -> list[dict]:
         }
         if block.get("unique_id"):
             seed["unique_id"] = str(block["unique_id"])
+        # t17: the intents block travels VERBATIM to the import flow, which owns
+        # the validation (and drops unusable rows with a log line) — the seed
+        # normaliser here only decides which keys reach the flow at all.
+        if isinstance(block.get(CONF_REGISTERED_INTENTS), list):
+            seed[CONF_REGISTERED_INTENTS] = block[CONF_REGISTERED_INTENTS]
         blocks.append(seed)
     return blocks
 
@@ -209,9 +240,43 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
 
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
 
+    # t17: refresh the send_intent dropdown from what is ACTUALLY loaded. This
+    # runs on every reload, and an options change reloads the entry, so adding
+    # or removing an intent updates the picker. The union across entries is
+    # deliberate: the service is domain-wide and any of them may be the target.
+    _publish_send_intent_description(hass)
+
     return True
 
 
+def _publish_send_intent_description(hass: HomeAssistant) -> None:
+    """Republish send_intent's description with the loaded intent names (t17).
+
+    Reads each loaded entry's OPTIONS through the runtime's own view of them
+    (``registered_intents``), so a hand-edited or malformed row cannot reach the
+    picker — the dropdown offers exactly what the action would accept.
+    """
+    try:
+        from homeassistant.helpers.service import async_set_service_schema
+
+        from .media_player import registered_intents, send_intent_service_description
+    except ImportError:  # pragma: no cover - a harness without HA's service module
+        # The dropdown is a RENDERING nicety: the action itself is registered by
+        # async_setup and works without it. Only a stub harness (which loads this
+        # module without the real homeassistant package) can get here.
+        return
+
+    names: list[str] = []
+    for loaded in (hass.data.get(DOMAIN) or {}).values():
+        options = getattr(loaded, "options", None)
+        if options is None:
+            options = getattr(getattr(loaded, "entry", None), "options", None)
+        names.extend(intent["name"] for intent in registered_intents(options or {}))
+    async_set_service_schema(
+        hass, DOMAIN, SERVICE_SEND_INTENT, send_intent_service_description(names)
+    )
+
+
 async def _build_protocol_settings(hass: HomeAssistant, entry: ConfigEntry):
     """Manager protocol_settings when the transport is enabled & resolvable.