PR #15872: fix: prevent stale timestamp perception by injecting current time per-turn

• Repository: NousResearch/hermes-agent
• Author: quinnmacro
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/15872

Description (problem / solution / changelog)

Problem

The system prompt includes a timestamp frozen at session creation time (for prompt cache stability). However, the label "Conversation started: <time>" is ambiguous — agents interpret it as the current time, leading to incorrect time-sensitive behavior.

Observed: In a session started at 5:07 AM, the agent said "good night 🌙" at 9:00 AM because the only timestamp it saw was "Conversation started: Sunday, April 26, 2026 05:07 AM".

Solution

Split the timestamp into two layers, both using user-message injection to preserve prompt cache:

Why user-message injection (not system prompt)?

PR #10448 addresses the same bug but injects Current time: into the system prompt via _build_turn_scoped_system_prompt(). This changes the system prompt content every turn, which breaks prompt cache prefix.

This PR injects into the user message — the same mechanism that plugins use (pre_llm_call context). The Hermes codebase itself documents this principle:

"Context is ALWAYS injected into the user message, never the system prompt. This preserves the prompt cache prefix — the system prompt stays identical across turns so cached tokens are reused."

User-message injection also composes naturally with the existing plugin system — time context merges with plugin context in _plugin_user_context.

Changes

1. run_agent.py — _build_system_prompt(): Rename "Conversation started" → "Session started" and add timezone name
2. run_agent.py — run_conversation(): Inject current time + timezone into _plugin_user_context on every turn
3. run_agent.py — _handle_max_iterations(): Inject current time into the summary request user message (recovery path)
4. hermes_time.py: Add get_timezone_name() public API
5. Comment update: Layer 6 comment now documents the split explicitly
6. Tests: 4 new/updated tests covering cache safety, user-message injection, and max-iterations path

Test results

tests/run_agent/test_run_agent.py::TestBuildSystemPrompt::test_includes_datetime PASSED
tests/run_agent/test_run_agent.py::TestBuildSystemPrompt::test_excludes_current_time_from_cached_prompt PASSED
tests/run_agent/test_run_agent.py::TestHandleMaxIterations::test_summary_injects_current_time_into_user_message PASSED
tests/run_agent/test_run_agent.py::TestRunConversation::test_turn_level_time_injected_into_user_message PASSED

Relation to #10448

Same bug, different injection location. See my comment on #10448 for the full comparison. Key difference: this PR preserves prompt cache by using user-message injection; #10448 breaks cache by modifying the system prompt per turn.

Token impact

~50 tokens per turn (two lines: current time + timezone). This is minimal compared to typical tool schemas and memory blocks, and the information is essential for correct agent behavior.

Changed files

• hermes_time.py (modified, +40/-0)
• run_agent.py (modified, +48/-4)
• tests/run_agent/test_run_agent.py (modified, +73/-2)
• tests/run_agent/test_run_agent_codex_responses.py (modified, +31/-0)

PR #17531: docs: document tool-time advisory-not-enforcement principle

• Repository: NousResearch/hermes-agent
• Author: alexzhu0
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/17531

Description (problem / solution / changelog)

Closes #17475.

Summary

Adds TOOL-PRINCIPLES.md at repo root capturing the architectural invariant established in #17459: runtime time/timezone/contact-window facts are surfaced to the agent as advisory context, not silently enforced in the control plane.

Why this doc needs to exist

Two closed-unmerged PRs tried to add quiet-hours enforcement and were rejected for the same reason:

• #4711 feat: Add profile-scoped gateway autonomy runtime — held contacts in control plane
• #7402 feat: drain Ockham outbox notifications via Hermes scheduler — held approvals during quiet hours

Without a durable written principle, it's easy for a future contributor to re-invent the same shape and get rejected again. The doc also names the preferred shape (#10421 / #15872: inject Current time + timezone into the ephemeral user-message context) so reviewers and contributors have a positive template to point at.

Shape

Each principle follows a consistent template so future invariants can be appended without re-designing the structure:

1. Title — one-line statement of the invariant
2. Decision — date + originating issue/PR references
3. Why — failure mode the inverse produces
4. What this means in practice — rejected vs encouraged PR shapes
5. Related history — closed PRs demonstrating the wrong shape + open PRs doing it right

This first entry documents tool-time. Future candidates (credential-scope boundaries, cross-platform identity, etc.) can slot in identically.

Not in scope

• No behavior change.
• Does not close #10421, #15872, #17474 (those implement the principle; this just writes it down).
• Does not take a position on whether opt-in quiet-hours enforcement should exist as a gateway plugin — the doc explicitly leaves that door open if visibility/overridability constraints are met.

File

• TOOL-PRINCIPLES.md (new, 88 lines)

Changed files

• TOOL-PRINCIPLES.md (added, +88/-0)