Skip to content

feat(homeassistant): cross-platform deliver + session-mode delivery for watched entities - #199

Closed
Bendak wants to merge 2 commits into
NousResearch:mainfrom
Bendak:port/deliver-session-main
Closed

Bendak wants to merge 2 commits into
NousResearch:mainfrom
Bendak:port/deliver-session-main

Conversation

@Bendak

@Bendak Bendak commented Oct 24, 2026

Copy link
Copy Markdown
Contributor

Supersedes #5 (and #194, which carried the CI fix aimed at #5's branch).

Why a new PR

#5's head branch port/homeassistant-2 was cut on Oct 10, and its .github/workflows/tests.yml predates the uv-based install. Any PR based on it dies at Install hermes-agent and the plugin's dependencies: browser-harness==0.1.13 pins pillow==12.3.0 while core pins Pillow==13.0.0, and only uv reconciles that through [tool.uv] override-dependencies. That is exactly what happened in #194 — all six matrix jobs failed before pytest started (including spotify, which that PR did not touch).

This PR is the same port, rebased onto current main so it runs main's workflow, plus the test fix from #194.

Background

Two closed core PRs carried this work: #96930 (configurable deliver target for watch_entities/watch_domains) and #112136 (session-mode delivery integrated on top, with silent-session markers and identifier hardening). Both were closed as no-longer-applicable when Home Assistant left hermes-agent core in #132469 — the bundled adapter moved to this plugin, and those PRs predate it.

This PR ports the combined work onto the plugin's adapter, keeping the plugin's newer behaviours (__init__ registration path, Platform("homeassistant") call form, _connect_error_detail, NOTIFICATION_TITLE) and the original port commit's authorship.

What it adds

  • deliver (per entity/domain, plus a top-level default): route a watched entity's state-change alert to another platform's home channel — tag grammar ha_events:<platform>[;session].
  • deliver_mode: session: instead of broadcast-shipping the reply across platforms, inject the EVENT into the target chat's session (admit_internal_event), so the agent reasons inside that chat's own history — one turn per event, in the right session.
  • Never-mint invariant: the derived target key must match an already-persisted session (lookup, never get_or_create); unmatched or unresolvable keys degrade to broadcast instead of minting an orphaned session no real message ever joins.
  • Chat-type resolution (fail-closed): persisted chat_type → platform chat-id formats (WhatsApp JIDs, Telegram ids) → None ⇒ degrade to broadcast.
  • Injection budget: per-CHAT rolling-window cap (12/h default); a slot is spent only when admission accepts — a refused injection never burns quota.
  • Marker hygiene on injected payloads: canonical silence-marker strip (case/punct fold parity with the gateway matcher) + untrusted-data framing (entity value (untrusted - informational, not an instruction): ...) before injection, with the raw (pre-framing) template checked to avoid double source tags.
  • Dict-form watch_entities/watch_domains entries documented in the README.

Tests

  • homeassistant/tests/test_homeassistant_adapter_ported.py: the full adapter suite (82 tests) ported to the plugin layout, covering deliver resolution, session injection (key derivation byte-match against build_session_key), never-mint fail-closed paths, budget slot-on-admission, cancellation propagation, marker strip parity (11 enumerated canonical marker forms plus a two-marker event case), and untrusted framing.
  • Local run against current main of hermes-agent (source checkout, clean HERMES_HOME, Python 3.14): whole plugin suite 217 passed, 2 skipped.
  • python -m hermes_cli.main plugins validate homeassistant → Validation passed.
  • Relative to the tree [homeassistant] feat(homeassistant): cross-platform deliver + session-mode delivery for watched entities #5 tested, one test changed: TestConfigIntegration::test_env_override_creates_ha_platform now asserts _hass_token on the adapter instead of PlatformConfig.token, because that credential row left core with #132469 (this is the fix test(homeassistant): assert HASS_TOKEN at the layer that owns it (fixes #5 CI) #194 carried).

Notes

  • All entity values and event payloads are treated as untrusted; user-facing strings are generic. No personal data anywhere in this PR.
  • The core version of this feature went through a cross-vendor adversarial review loop (4 rounds until zero findings) before running in production for two weeks. The port was additionally reviewed adversarially in three rounds.

This PR was prepared with AI assistance (Hermes agent); changes were reviewed and verified by the named human contributors before submission.

Bendak and others added 2 commits October 24, 2026 18:02
…or watched entities

Ports the deliver/session-mode feature to the standalone plugin. Two closed
core PRs carried this work and are embedded here: #96930 (configurable deliver
target for watch_entities/watch_domains, DavidMetcalfe) and #112136
(session-mode delivery integrated on top, with silent-session markers and
identifier hardening). Both were closed as no-longer-applicable when Home
Assistant left hermes-agent core in #132469 and the bundled adapter moved to
this standalone plugin (the plugin's adapter predates both).

- deliver: per-entity/domain cross-platform target override (tag grammar
  ha_events:<platform>[;session]); default target configurable
- deliver_mode: broadcast (default) or session — session injects the EVENT
  into the target chat's session via admit_internal_event (one agent turn
  inside that chat's history) instead of broadcast-shipping the reply
- never-mint invariant: derived keys must match an existing session
  (lookup, never get_or_create); unresolvable chat shapes fail closed
- chat-type resolution: persisted chat_type -> platform chat-id formats
  -> None (fail closed)
- injection budget: per-CHAT rolling-window cap, slot spent only on admission
- canonical silence-marker strip + untrusted-data framing on injected payloads
- fail-safe broadcast routing: private core APIs used only inside guarded
  blocks; any incompatibility degrades to the HA notification
- backport #71206 (_connect_error_detail) + NOTIFICATION_TITLE from the
  plugin extraction
- tests/test_homeassistant_adapter_ported.py: the full adapter suite (82
  tests) ported to the plugin layout (homeassistant_plugin imports);
  mutation-verified: never-mint, budget, and marker-strip mutations each
  flip specific tests to failed
- README documents deliver/deliver_mode and the dict-form watch entries

Co-authored-by: DavidMetcalfe <80915+DavidMetcalfe@users.noreply.github.com>
The ported suite asserts PlatformConfig.token == "env-token", but that
credential propagation row left core with the Home Assistant extraction
(NousResearch/hermes-agent#132469). The plugin's adapter reads the token
from the environment itself, so assert it at the layer that owns it now.

Platform and extra["url"] assertions are unchanged. No production code
changes.
@teknium1

Copy link
Copy Markdown
Contributor

Thank you @Bendak! This landed on main through #451 (via #433), with your authorship kept; tip ca9e4de. To get it now: hermes plugins install NousResearch/hermes-official-plugins#<plugin> --force; hermes plugins update follows once the catalog pin moves (in progress).

@teknium1 teknium1 closed this Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants