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()`.
104 lines
No EOL
3.8 KiB
Markdown
104 lines
No EOL
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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):**
|
|
|
|
```bash
|
|
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. |