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

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.