hermes-currenttime-hint/__init__.py
Shihfu Juan e419b9bb81
fix: move time.monotonic() inside lock, pass to _evict_if_needed()
- monotonic time sampling now inside the lock, so count/inserted_at/seen
  all share the same lock-protected value — no cross-thread time regression
- _evict_if_needed() takes now as a parameter instead of calling
  time.monotonic() itself, avoiding a redundant syscall
2026-07-10 20:39:42 +08:00

201 lines
6.9 KiB
Python

"""hermes-currenttime-hint — appends an ISO-8601 current-time hint to user messages.
Wires the ``pre_llm_call`` hook to track, per session, how many user messages have been
seen since the last injection and the wall-clock time of the last injection.
Injects a single-line ``<current-time>...</current-time>`` tag into the user
message tail when **either** the user-message interval (default 5) **or** the
wall-clock interval (default 30 minutes) has elapsed — whichever fires first.
The first injection for a session always fires on the very first user message
(count = 0 is treated as eligible).
The plugin is opt-in via ``hermes plugins enable hermes-currenttime-hint``.
No per-plugin configuration: enable/disable is the only switch.
"""
from __future__ import annotations
import logging
import os
import threading
import time
from dataclasses import dataclass
from datetime import datetime
from typing import Any
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# Tunables — keep these as module constants so tests can assert against them.
# ---------------------------------------------------------------------------
USER_MESSAGE_INTERVAL: int = 5
TIME_INTERVAL_SECONDS: float = 30 * 60 # 30 minutes
# Lazy expiry + capacity cap (mirrors kuri-tool-guard / kuri-skill-gate pattern).
_SESSION_TTL_SECONDS: float = 24 * 60 * 60
_MAX_TRACKED_SESSIONS: int = 1024
# Tag shape — single line, easy for LLMs to spot, easy to grep.
_TAG_PREFIX = "<current-time>"
_TAG_SUFFIX = "</current-time>"
# ---------------------------------------------------------------------------
# Session state
# ---------------------------------------------------------------------------
@dataclass
class _SessionState:
"""Per-session tracking: how many user messages since last injection.
Attributes:
count: User messages seen *since* the last injection. Reset to 0
immediately after each injection.
last_inserted_at: Monotonic time of the last injection. ``0.0`` means
"never injected yet" — use ``initialized`` instead of comparing
to 0.0 because ``time.monotonic()`` may return any value at boot.
initialized: ``False`` until the first injection, then ``True``
forever. The very first user message for a session always injects.
last_seen: Monotonic time of the most recent ``pre_llm_call`` for
this session. Drives lazy TTL + LRU eviction.
"""
count: int = 0
last_inserted_at: float = 0.0
initialized: bool = False
last_seen: float = 0.0
_state: dict[str, _SessionState] = {}
_lock = threading.Lock()
def _now() -> datetime:
"""Return the current local datetime.
Honours ``$TZ`` if set, by calling ``time.tzset()`` once before reading the
clock. ``time.tzset()`` is POSIX-only — Windows would raise, but this
plugin targets Linux (Bazzite), so the error is not caught here.
"""
tz = os.environ.get("TZ")
if tz:
# POSIX only; raises on Windows. See module docstring.
time.tzset()
return datetime.now().astimezone()
def _format_time(dt: datetime) -> str:
"""Format an aware datetime as ISO 8601 with offset, second precision."""
return dt.isoformat(timespec="seconds")
def _build_hint(dt: datetime) -> str:
"""Build the single-line tag injected into the user message tail."""
return f"{_TAG_PREFIX}{_format_time(dt)}{_TAG_SUFFIX}"
def _should_inject(state: _SessionState, now_monotonic: float) -> bool:
"""Pure decision function — easy to test in isolation.
Two triggers, either one fires injection:
1. **Never-injected sentinel**: if ``state.initialized`` is ``False``,
always inject (the very first user message for a session always
gets a timestamp).
2. **User-message interval**: ``state.count >= USER_MESSAGE_INTERVAL``.
``state.count`` is the number of user messages seen *since* the
last injection.
3. **Wall-clock interval**: ``now_monotonic - state.last_inserted_at
>= TIME_INTERVAL_SECONDS``.
Whichever fires first wins. If multiple fire, inject exactly once.
"""
if not state.initialized:
return True
if state.count >= USER_MESSAGE_INTERVAL:
return True
return (now_monotonic - state.last_inserted_at) >= TIME_INTERVAL_SECONDS
def _evict_if_needed(now: float) -> None:
"""Lazy TTL + LRU cap, mirroring kuri-tool-guard's pattern."""
# Expire stale entries first.
expired = [sid for sid, s in _state.items() if (now - s.last_seen) > _SESSION_TTL_SECONDS]
for sid in expired:
_state.pop(sid, None)
# Cap by evicting the least-recently-seen entry until under the cap.
while len(_state) >= _MAX_TRACKED_SESSIONS:
oldest = min(_state.items(), key=lambda kv: kv[1].last_seen)
_state.pop(oldest[0], None)
def reset_state() -> None:
"""Test hook — clear all session state."""
with _lock:
_state.clear()
# ---------------------------------------------------------------------------
# Hook callbacks
# ---------------------------------------------------------------------------
def _on_pre_llm_call(
session_id: str = "",
**_: Any,
) -> str | None:
"""Inject a current-time hint when either trigger fires.
Returns the tag string (which Hermes appends to the user message tail),
or ``None`` to leave the message unchanged.
"""
if not session_id:
return None
with _lock:
now_mono = time.monotonic()
_evict_if_needed(now_mono)
state = _state.get(session_id)
if state is None:
# First call for this session — always inject.
hint = _build_hint(_now())
_state[session_id] = _SessionState(
count=0,
last_inserted_at=now_mono,
initialized=True,
last_seen=now_mono,
)
logger.debug(
"hermes-currenttime-hint: first injection for session %s",
session_id,
)
return hint
# Increment count BEFORE evaluating so the trigger reflects "this message".
state.count += 1
state.last_seen = now_mono
if not _should_inject(state, now_mono):
return None
hint = _build_hint(_now())
state.count = 0
state.last_inserted_at = now_mono
state.initialized = True
logger.debug(
"hermes-currenttime-hint: injecting for session %s (count=%d trigger or time trigger)",
session_id,
USER_MESSAGE_INTERVAL,
)
return hint
# ---------------------------------------------------------------------------
# Plugin registration
# ---------------------------------------------------------------------------
def register(ctx: Any) -> None:
"""Wire hook callbacks into the Hermes plugin runtime."""
ctx.register_hook("pre_llm_call", _on_pre_llm_call)