- 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)
100 lines
No EOL
2.8 KiB
Markdown
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 |