Hermes' on_session_end plugin hook fires at the end of every run_conversation call (turn_finalizer.py:490), not at true session end. This caused per-session state to be deleted every turn, making the sentinel trigger always fire — injecting on every user message. Remove the `_on_session_end` callback and its registration. State cleanup is handled by the existing lazy TTL (24h) + LRU cap (1024 sessions) in `_evict_if_needed()`.
3.8 KiB
hermes-currenttime-hint
Appends an ISO-8601 current-time hint to user messages via the
pre_llm_call plugin hook. Two independent triggers — whichever fires first
wins: every Nth user message (default 5), or 30 minutes since the last hint.
How it works
pre_llm_callhook fires once per turn. Plugin keeps per-session state (session_id→_SessionState) holding:count— user messages seen since last injectionlast_inserted_at— monotonic time of last injectioninitialized—Trueafter first injectionlast_seen— monotonic time of most recentpre_llm_call(TTL + LRU)
- Decision function
_should_injectis pure (testable in isolation):initialized == False→ inject (sentinel for first message)count >= USER_MESSAGE_INTERVAL→ injectnow_monotonic - last_inserted_at >= TIME_INTERVAL_SECONDS→ inject
- State cleanup is handled by lazy TTL (24h) + LRU cap (1024 sessions)
via
_evict_if_needed()on eachpre_llm_callinvocation.
The injected string is a single-line XML tag appended to the user message
tail by Hermes' pre-llm-call injection machinery
(agent/conversation_loop.py:807). The injection is ephemeral — never
persisted to the session DB.
Verification
just verify # full pipeline: lint → format-check → bandit → vulture → ty → pytest
just test # pytest only (fastest smoke test)
just lint # ruff check
just format # ruff format
just format-check # ruff format --check
just typecheck # ty check
just bandit # bandit security scan
just vulture # dead code detection
Quick smoke test (minimal Python environment)
cd ~/.hermes/plugins/hermes-currenttime-hint
PYTHONPATH=. python3 -m pytest tests/ -v
Runs with any Python 3.12+ that has pytest and PyYAML installed.
For the full just verify pipeline, run uv sync --group dev once.
Full standalone verification (no just needed):
cd ~/.hermes/plugins/hermes-currenttime-hint
uv sync --group dev
uv run ruff check __init__.py tests/
uv run ty check __init__.py tests/
uv run pytest tests/ -v
The standalone static checks cover every test source. All three (lint, type check, tests) must pass before committing.
File layout
~/.hermes/plugins/hermes-currenttime-hint/
├── plugin.yaml # Plugin manifest
├── __init__.py # Plugin entry — register() + hook callbacks
├── pyproject.toml # uv-managed Python project + ruff/ty config
├── justfile # Task runner (verify, test, lint)
├── AGENTS.md # This file
├── README.md # User-facing documentation
├── .gitignore
├── .vulture_whitelist.py
└── tests/
├── __init__.py
├── test_stamper.py # _should_inject, _build_hint, hook integration
└── test_registration.py # register() wiring + manifest metadata
Python toolchain
- Python 3.12+
- uv for package management (not pip)
- ruff for linting and formatting
tyfor static type checking- bandit for security scanning
- vulture for dead code detection
- pytest for testing
How tests load the plugin
Because the directory name contains hyphens, Python can't import it as a
package. Tests use importlib.util.spec_from_file_location to load
__init__.py directly and bind the resulting module into sys.modules so
@dataclass can resolve its module reference. This mirrors the pattern used
by kuri-tool-guard.
Adding tunables
If you want to make USER_MESSAGE_INTERVAL or TIME_INTERVAL_SECONDS
configurable without code changes, add a YAML config block under a top-level
config: key in plugin.yaml and read it in register(ctx). Today both are
module constants — change requires an edit + gateway restart.