PR #28750: fix(gateway): emit session:end from idle-expiry watcher + auto-reset paths

• Repository: NousResearch/hermes-agent
• Author: mbs-vhs
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/28750

Description (problem / solution / changelog)

What does this PR do?

Fix the gateway session:end hook so it fires from every session-close path, not just /new//reset. Without this, external hook subscribers (under ~/.hermes/hooks/) silently miss every idle-expiry- and auto-reset-driven close — leaving stale mirror state forever.

The gateway emits the lifecycle event session:end from exactly one call site, the /new//reset handler. Two other paths close sessions but don't emit:

1. Idle-expiry watcher (gateway/run.py:_session_expiry_watcher) — fires the plugin-level on_session_finalize (per #14981), evicts the cached agent, marks entry.expiry_finalized = True. But never self.hooks.emit("session:end", ...).

2. Auto-reset branch (gateway/session.py:get_or_create_session) — when a stale entry is rolled over for a new session_id, the local SQLite session ends but no gateway event fires for the old session_id.

This PR makes session:end symmetric with session:start — every close path now emits, every subscriber sees the close.

Related Issue

Fixes #28746

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• gateway/run.py:_session_expiry_watcher — emit session:end with reason="idle_expiry" right after entry.expiry_finalized = True. Wrapped in try/except logger.debug(..., exc_info=True) so a misbehaving subscriber can't break the watcher loop. (platform is pulled from the session_key just like the existing on_session_finalize invocation; user_id from entry.origin with the same or "" guard pattern used elsewhere in this file.)

• gateway/run.py:_handle_message_with_agent — in the _is_new_session branch, before emitting session:start, check getattr(session_entry, "auto_reset_prior_session_id", None). If set, emit session:end with reason="auto_reset", then clear the field so a follow-up turn cannot re-emit for the same close.

• gateway/session.py — add a transient field auto_reset_prior_session_id: Optional[str] = None to SessionEntry. get_or_create_session populates it (with the prior session_id) whenever the auto-reset branch fires. Not added to to_dict() — this is a transient signal consumed by the next emit pass, never persisted to sessions.json.

• gateway/hooks.py — docstring update to reflect the new firing contract: session:end now lists the three close paths and notes the reason key on the new emit paths.

• tests/gateway/test_session_boundary_hooks.py — three new tests:

  • test_idle_expiry_emits_session_end — runs _session_expiry_watcher against a mocked-out store with one expired entry; asserts the emit fires with the expired session_id, session_key, and reason="idle_expiry". Regression guard for the watcher path.
  • test_auto_reset_emits_session_end_for_prior_session — exercises the emit fragment in _handle_message_with_agent against a SessionEntry that was just produced by auto-reset (with auto_reset_prior_session_id="sess-old-prior"); asserts session:end fires before session:start, with the right session_id + reason="auto_reset", and that the transient field is cleared after consume.
  • test_session_entry_has_auto_reset_prior_session_id_field — dataclass-level sanity check (default None, writable, not in to_dict()).

The existing 6 tests in this file (test_reset_*, test_finalize_before_reset, test_shutdown_*, test_hook_error_*, test_idle_expiry_fires_finalize_hook) all still pass — no existing call site changes behavior.

How to Test

Automated

pytest tests/gateway/test_session_boundary_hooks.py -v --override-ini="addopts="

All 9 tests pass (6 pre-existing + 3 new).

Manual reproduction

1. Install a gateway hook in ~/.hermes/hooks/test-session-end/:

   # HOOK.yaml
   name: test-session-end
   events: [session:start, session:end]

   # handler.py
   import datetime, json, pathlib
   LOG = pathlib.Path.home() / "session_end_test.log"
   async def handle(event_type, context):
       LOG.parent.mkdir(parents=True, exist_ok=True)
       with LOG.open("a") as f:
           f.write(json.dumps({"event": event_type, "ts": datetime.datetime.now().isoformat(), "ctx": context}) + "\n")

2. Start the gateway. Open a Telegram DM session. Send one message. Confirm session:start lands in ~/session_end_test.log.

3. Stop messaging. Wait for the configured idle-reset window to pass plus one 5-min watcher tick.

4. Before this fix: the log shows only session:start (no session:end). ~/.hermes/sessions/sessions.json shows expiry_finalized: true for the session.

5. After this fix: the log shows session:end with reason: "idle_expiry", session_id, session_key, platform, user_id. sessions.json still shows expiry_finalized: true.

6. Repeat for the auto-reset path: start a fresh session, idle past the reset window, then send a NEW message (not /new). The handler logs session:end for the OLD session_id (with reason: "auto_reset"), then session:start for the NEW one.

Note on Hermes version

Tested against the fork's main branch (currently aligned with hermes-agent 0.14.0 per pyproject.toml). The patched code paths exist identically in 0.13.0 and earlier — the line numbers in the original issue reference the v0.13.0 layout. The semantic anchors (function names, code shapes) are unchanged.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(gateway): ...)
• I searched for existing PRs to make sure this isn't a duplicate (#24982 adds chat_id to the existing emit sites — different bug, cleanly compatible with this change)
• My PR contains only changes related to this fix (no unrelated commits)
• I've run pytest tests/gateway/test_session_boundary_hooks.py -v and all tests pass (9/9)
• I've added tests for my changes (3 new tests in test_session_boundary_hooks.py)
• I've tested on my platform: macOS 25.4 (Darwin 25.4.0)

Documentation & Housekeeping

• I've updated relevant documentation — gateway/hooks.py Events docstring reflects the new firing contract for session:end
• I've updated cli-config.yaml.example if I added/changed config keys — N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — N/A (no platform-specific code paths touched)
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

Changed files

• gateway/hooks.py (modified, +6/-1)
• gateway/run.py (modified, +54/-0)
• gateway/session.py (modified, +16/-0)
• tests/gateway/test_session_boundary_hooks.py (modified, +192/-0)

PR #29048: feat: Typed Hook Payloads (Phase 2) + Path Parity Tests (Phase 3)

• Repository: NousResearch/hermes-agent
• Author: zccyman
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/29048

Description (problem / solution / changelog)

Summary

Implements Phase 2 (Typed Hook Payloads) and Phase 3 (Path Parity Tests) of FR #28984.

Phase 1 was submitted separately as PR #28995.

Phase 2 — Typed Hook Payloads

New file: hermes_cli/hook_payloads.py (276 lines)

Defines frozen dataclass payloads for all 14 hook types:

payload_to_kwargs() converts dataclass → plain dict, preserving cb(**kwargs) compatibility for all existing plugin callbacks.

5 call sites migrated (adds type safety, zero breaking changes):

New tests: tests/hermes_cli/test_hook_payloads.py — 21 tests covering all payloads, frozen immutability, round-trip, registry completeness.

Phase 3 — Path Parity Tests

New file: hermes_cli/path_parity.py (155 lines)

assert_field_parity(
    "fallback_model",
    {
        "gateway_run_agent": lambda: extract_gateway_fields(),
        "tui_make_agent": lambda: extract_tui_fields(),
    },
)

When any path does not consume the field, raises PathParityError with a diff showing which paths are missing it.

3 known divergences documented as failing tests:

• #28753: TUI doesn't pass fallback_model to AIAgent
• #28746: idle-expiry path doesn't emit session:end event
• #28637: /model switch loses per-model token usage

New tests: tests/hermes_cli/test_path_parity.py — 13 tests covering the helper functions and documented divergence patterns.

What This Prevents

Test Results

tests/hermes_cli/test_hook_payloads.py  21 passed
tests/hermes_cli/test_path_parity.py   13 passed
tests/hermes_cli/test_plugins.py       105 passed
tests/test_model_tools.py               passed
tests/test_transform_tool_result_hook.py passed
tests/agent/test_plugin_llm.py          passed
tests/agent/test_shell_hooks.py         passed
─────────────────────────────────────────────
Total                                     139 passed

Refs: FR #28984 | PR #28995 (Phase 1)

Changed files

• .dev-workflow/code-graph.db (added, +0/-0)
• agent/conversation_loop.py (modified, +6/-4)
• hermes_cli/hook_payloads.py (added, +276/-0)
• hermes_cli/path_parity.py (added, +155/-0)
• hermes_cli/plugins.py (modified, +7/-2)
• hook_system_analysis.md (added, +348/-0)
• model_tools.py (modified, +6/-4)
• plans/path_parity_analysis.md (added, +135/-0)
• tests/hermes_cli/test_hook_payloads.py (added, +245/-0)
• tests/hermes_cli/test_path_parity.py (added, +198/-0)