hermes-currenttime-hint/README.md
Shihfu Juan 9a8b240a45
docs: rewrite README with TZ format table, installation guide, and profile setup
- Add detailed TZ format examples table (IANA and POSIX)
- Add Installation section with git clone
- Add Verify and Using in other profiles sections
- Align format with other plugins (kuri-tool-guard, kuri-skill-gate)
2026-07-10 20:49:22 +08:00

100 lines
No EOL
2.8 KiB
Markdown

# hermes-currenttime-hint
Appends an ISO-8601 current-time tag to the user message tail on every Nth
turn (default 5), or after 30 minutes since the last injection — whichever
fires first. Injected via `pre_llm_call`, ephemeral — never persisted.
```xml
<current-time>2026-07-10T18:30:45+08:00</current-time>
```
## How it works
Two independent triggers, whichever fires first wins:
1. **User-message count** — after every 5 user messages, the next one gets a
tag. Count resets to 0 after injection.
2. **Wall-clock interval** — 30 minutes after the last injection, the next
user message gets a tag regardless of count.
The **first** message in every session always fires (sentinel).
State is pure in-memory (`dict[session_id, _SessionState]`). Gateway restart
loses state — acceptable per the spec (miss is harmless). Stale sessions are
evicted after 24 hours; the map caps at 1,024 sessions (LRU).
## Timezone
The tag uses the host's system local time by default (`Asia/Taipei` on this
host). Override with the `TZ` environment variable — `time.tzset()` is called
on every injection (Linux only; POSIX).
### TZ format examples
| Variable | Result |
|---|---|
| (unset) | System local time |
| `TZ=Asia/Taipei` | Taiwan (UTC+8) |
| `TZ=America/New_York` | US Eastern (UTC-5/-4) |
| `TZ=UTC` | UTC |
| `TZ=Europe/Berlin` | Central European (UTC+1/+2) |
| `TZ=CST-8` | POSIX: CST = 8 hours **behind** UTC → UTC+8 |
| `TZ=EST+5EDT` | POSIX: US Eastern with DST |
On glibc systems (Linux) the IANA timezone name with a leading colon also
works (`TZ=:Asia/Taipei`). This plugin calls `time.tzset()` before every
injection, so changing `TZ` at runtime takes effect on the next hit.
## Installation
```bash
git clone https://git.xlion.tw/xlionjuan/hermes-currenttime-hint.git \
~/.hermes/plugins/hermes-currenttime-hint
```
## Enable
```bash
hermes plugins enable hermes-currenttime-hint
```
Takes effect after a gateway restart (`/restart` or restart the Hermes
gateway service).
## Disable
```bash
hermes plugins disable hermes-currenttime-hint
```
## Verify
```bash
cd ~/.hermes/plugins/hermes-currenttime-hint
just verify
```
`just verify` runs ruff lint and format checks, Bandit, Vulture, ty, and
pytest (21 tests). Run `uv sync --group dev` once before the first run.
## Using in other profiles
```bash
mkdir -p ~/.hermes/profiles/<profile>/plugins
ln -s ../../../plugins/hermes-currenttime-hint \
~/.hermes/profiles/<profile>/plugins/hermes-currenttime-hint
hermes plugins --profile <profile> enable hermes-currenttime-hint
```
## Tunables (code-level only)
Edit module constants in `__init__.py` and restart the gateway:
- `USER_MESSAGE_INTERVAL` — default `5`
- `TIME_INTERVAL_SECONDS` — default `1800` (30 min)
- `_SESSION_TTL_SECONDS` — default `86400` (24 h)
- `_MAX_TRACKED_SESSIONS` — default `1024`
## Author
Shihfu Juan / Kuri