Summary

Injects timestamps into messages flowing through the gateway so agents always know the current date/time — without modifying the system prompt (which is cached for stability).

Two injection points cover all non-channel paths:

Why?

Commit 66eec295b removed date/time from the system prompt for cache stability. Channel plugins (Discord, Telegram) already inject timestamps into messages, but TUI, webchat, spawned subagents, and sessions_send had no date/time context. Models either hallucinated dates or had to burn a tool call (exec date) to check.

Approach

Extracted a pure function injectTimestamp(message, opts) that:

• Prepends [Wed 2026-01-28 22:30 EST] to messages (3-letter DOW + compact date/time + timezone)
• Reuses the existing formatZonedTimestamp from channel envelope formatting for consistency
• Respects configured timezone
• Skips messages that already have channel envelope timestamps ([Discord user 2026-...])
• Skips messages with cron-injected timestamps (Current time: ...)
• Handles edge cases: empty messages, midnight, date boundaries

Called from two gateway handlers:

1. agent handler (server-methods/agent.ts) — covers spawned subagents, sessions_send, heartbeat wake events
2. chat.send handler (server-methods/chat.ts) — covers webchat and TUI, injecting into BodyForAgent only (UI display stays clean)

Format: [Wed 2026-01-28 22:30 EST]

Compact, ~7 tokens. Includes:

• 3-letter DOW — small models (8B) can't reliably derive day-of-week from a date alone; costs ~1 extra token
• ISO-ish date — unambiguous, models parse it natively
• Time + timezone — for scheduling and relative time questions

No Current Date: label — frontier models don't need it, and the bracket format is self-evident.

QA Results

Before (no timestamps in TUI/web/spawn):

• "Is it the weekend?" → "Yes! It's Saturday, July 19, 2025" ❌ (hallucinated)
• "How many days until Feb 1?" → "199 days" ❌ (hallucinated July 2025)

After (timestamps injected):

• TUI: [Wed 2026-01-28 21:35 EST] OK restarted gateway... ✅
• Webchat: [Wed 2026-01-28 21:36 EST] message ✅
• Spawned subagent ("Is it the weekend?"): "No, it's Wednesday." ✅ — zero tool calls, answered from timestamp in message

Tests

• 12 unit tests for injectTimestamp: timezone handling, DOW prefix, midnight boundaries, channel envelope detection, cron detection, empty messages, custom now
• 1 integration test for agent handler: frozen time, verifies agentCommand receives timestamped message
• All tests use vi.useFakeTimers() + vi.setSystemTime() for deterministic time

Known Gap: Heartbeat Polls

Heartbeat polls go through getReplyFromConfig directly (same as channel dispatch), not through agent or chat.send. They set ctx.Body = prompt with no timestamp. This is a separate code path and riskier to modify. Recommend addressing separately.

Heartbeats run in the main session which has the session_status hint (PR #3677), so they can still look up the time — they just don't get it for free in the message.

Complements

• PR fix(system-prompt): hint session_status for date/time instead of embedding it #3677 — session_status hint in system prompt (teaches models where to look)
• This PR — timestamp injection (gives models the date directly, no lookup needed)

Together they cover the full spectrum: injection for paths that support it, hint for paths that don't.

Closes #3658
Refs: #1897, #1928, #2108

Small Model Testing

Tested format variations on local models to validate the compact approach:

Key finding: Frontier models handle the compact format fine. Sub-8B models struggle regardless of format — not a prompt engineering problem, it's a capability gap.

🤖 AI-Assisted

Developed and tested collaboratively between a human and AI agent (Claude in Moltbot). Includes live QA across TUI, webchat, and spawned subagents. We understand what the code does.