hermes-currenttime-hint/AGENTS.md
Shihfu Juan c0fad617de
fix: remove on_session_end hook — fires every turn, breaks injection counting
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()`.
2026-07-10 20:25:57 +08:00

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_call hook fires once per turn. Plugin keeps per-session state (session_id → _SessionState) holding:
    • count — user messages seen since last injection
    • last_inserted_at — monotonic time of last injection
    • initialized — True after first injection
    • last_seen — monotonic time of most recent pre_llm_call (TTL + LRU)
  • Decision function _should_inject is pure (testable in isolation):
    1. initialized == False → inject (sentinel for first message)
    2. count >= USER_MESSAGE_INTERVAL → inject
    3. now_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 each pre_llm_call invocation.

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
  • ty for 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.