- 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
201 lines
6.9 KiB
Python
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)
|