Skip to content

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

Closed
teknium1 wants to merge 2 commits into
mainfrom
salvage/199-ha-deliver
Closed

teknium1 wants to merge 2 commits into
mainfrom
salvage/199-ha-deliver

Conversation

@teknium1

Copy link
Copy Markdown
Contributor

Salvage of #199 by @Bendak (itself the community re-submission of #5, the port of NousResearch/hermes-homeassistant#2), rebased onto current main. Both of Bendak's commits cherry-picked, authorship kept.

Adds, for watched entities/domains:

  • deliver (per entity/domain + top-level default): route a state-change alert to another platform's home channel (tag ha_events:<platform>[;session]).
  • deliver_mode: session: inject the event into that chat's existing session (never mints one; unmatched → broadcast), with a silence contract and a per-chat rolling injection budget.

Rebase notes: only conflicts were next to main's newer ws_heartbeat_seconds (adapter __init__ + README table); both kept, the duplicate _last_event_time init dropped. #199 vs #5: identical adapter/README; #199 adds the HASS_TOKEN test fix from #194.

Tests: test_homeassistant_adapter_ported.py over main's adapter: 51 failed / 31 passed; here: homeassistant suite 296 passed, 2 skipped.

Review flag: the routing reaches gateway internals not in plugin_api.json (gateway_runner._authorization_adapter, gateway.wake.admit_internal_event, gateway.run._profile_runtime_scope, gateway.session.build_session_key). Each call is wrapped to degrade to the HA notification if core changes, but it is a private-API dependency.

Supersedes #199 and #5.

Bendak and others added 2 commits November 19, 2026 03:54
…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.
@Bendak

Bendak commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Thanks for the salvage — both commits carried over cleanly, authorship intact.

CI note for reviewers: 63/64 checks pass on e79b107c. The single failure, bubblewrap · ubuntu-latest, is pre-existing on main: run 44478782362 (main @ e726eb7d, 19/11 07:19) fails the same job at Run the plugin suite. Nothing in this diff touches that plugin.

On the private-API flag: that's the right call to surface. On a live install the wrapped calls degrade to the HA notification, so a core rename (admit_internal_event, build_session_key, _profile_runtime_scope) shows up as "deliver silently stopped routing" rather than an exception. If you want, a startup one-shot warning when a wrapped symbol is missing would make that visible instead of silent — happy to open that as a separate small PR.

I can also run this branch against a real config (watch entities + deliver to a messaging platform, deliver_mode: session on an existing chat) and report back, and switch a production install from the standalone fork to this version once it's pinned — that would exercise the rebase (heartbeat, script allowlist, timezone twins) under live traffic.

#199 and #5 can be closed from my side whenever you merge; say the word.

Prepared with AI assistance (Hermes agent), reviewed by the account owner.

@teknium1 teknium1 added the needs-decision Awaiting an owner policy or product decision label Nov 19, 2026
@Bendak

Bendak commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

To keep the pending decision concrete, here is the only part of this PR that is a policy question rather than a code question — the flag already named in the description.

The routing path calls six symbols that are not plugin-facing surface:

symbol where
gateway_runner._authorization_adapter() adapter.py:652, :752
gateway.wake.admit_internal_event() :914-925
gateway.run._profile_runtime_scope() :1060-1062
gateway.session.build_session_key() :796-837
session_store.lookup_by_session_key() :843
gateway.response_filters.LIVE_GATEWAY_SILENT_MARKERS :86-87

So the decision I can see is: does a first-party plugin get to depend on gateway internals, and if so which shape?

  • A — sanction them: add the six to the documented plugin surface (a core PR) and treat "missing symbol ⇒ degrade to the HA notification" as the compatibility contract. Cheapest; keeps today's behaviour; the debt is named.
  • B — narrow it to one hook: expose a single supported call (e.g. runner.deliver_to_home(platform, text) plus inject_event(platform, event)), and the plugin stops reaching inside. More core work, but it is the only version that survives an internal refactor silently.
  • C — don't sanction: merge broadcast-only and drop deliver_mode: session. That removes the part of the feature that makes it worth having.

My recommendation is A now, B as the follow-up: A is a documentation/compat decision that does not block this merge, and it is reversible; B needs its own core PR and should not gate a feature that already runs in production.

Two clarifications that may or may not be what the label is tracking:

  1. Scope of the fix PR: #440 targets this branch and touches only homeassistant/adapter.py and its ported test file — no other plugin, no core, and nothing related to bubblewrap. It fixes four defects found by review in this diff (thread routing, refused sends, compat-wrapper coverage, and the sanitizer degradation), with 303 passed / 2 skipped and a mutation check per guard.
  2. Merge mechanics are yours: merge feat(homeassistant): cross-platform deliver + session-mode delivery for watched entities (salvage #199/#5) #433 then fix(homeassistant): route to the configured home thread and honour send refusals #440, or fold fix(homeassistant): route to the configured home thread and honour send refusals #440 into the salvage branch first — both work from my side. feat(homeassistant): cross-platform deliver + session-mode delivery for watched entities #199 and [homeassistant] feat(homeassistant): cross-platform deliver + session-mode delivery for watched entities #5 can be closed whenever you merge.

If the label is tracking something else about this feature (product scope, delivery semantics, session injection as a capability), say which and I will answer it directly instead of guessing.

Prepared with AI assistance (Hermes agent), reviewed by the account owner.

@Bendak

Bendak commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Heads-up on the conflict: #447 merges main into this branch, resolving the two conflicts (homeassistant/README.md — keep notification_id + deliver + deliver_mode; homeassistant/adapter.py — keep both _notification_id and the deliver init block) and carrying the reviewed fixes from #440.

Merge #447 here and this PR becomes mergeable with the fixes already inside. Suite on that tree: 323 passed, 2 skipped, zero failures; AST parity with main checked (nothing dropped); no bubblewrap changes.

If you would rather rebase yourself, that is fine too — the resolution above is the whole of it, and #440 can be re-pointed afterwards.

Prepared with AI assistance (Hermes agent), reviewed by the account owner.

teknium1 added a commit that referenced this pull request Nov 20, 2026
…er uses is missing

Cross-platform deliver and deliver_mode: session call six gateway internals
that are not in the published plugin API (_authorization_adapter,
admit_internal_event, _profile_runtime_scope, build_session_key,
SessionStore.lookup_by_session_key, LIVE_GATEWAY_SILENT_MARKERS). Each call
already falls back to the HA notification, so a core rename read as deliver
quietly stopping. connect() now checks them once per process, only when a
deliver target other than homeassistant is configured, and logs one warning
naming every missing symbol and the fallback.

Suggested by @Bendak on #433.
@teknium1

Copy link
Copy Markdown
Contributor Author

Landed on main via #451 (tip ca9e4de), with the missing-symbol startup warning Bendak suggested (option B). To get it now: hermes plugins install NousResearch/hermes-official-plugins#<plugin> --force; hermes plugins update follows once the catalog pin moves (in progress).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-decision Awaiting an owner policy or product decision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants