Skip to main content

​
Date & Time

Fased keeps runtime time handling split by purpose:
  • Channel message envelopes use a configurable envelope timezone. The default is the host timezone.
  • Direct Gateway messages are timestamped with the resolved user timezone.
  • The system prompt includes the user timezone only, not a live clock.
  • Provider timestamps are preserved in tool payloads, with normalized UTC fields added where supported.
When the agent needs the current time, it should call session_status.

​
Message envelopes (local by default)

Inbound messages are wrapped with a timestamp (minute precision):
This envelope timestamp is host-local by default, regardless of the provider timezone. You can override this behavior:
  • envelopeTimezone: "utc" uses UTC.
  • envelopeTimezone: "local" uses the host timezone.
  • envelopeTimezone: "user" uses agents.defaults.userTimezone (falls back to host timezone).
  • Use an explicit IANA timezone (e.g., "America/Chicago") for a fixed zone.
  • envelopeTimestamp: "off" removes absolute timestamps from envelope headers.
  • envelopeElapsed: "off" removes elapsed time suffixes (the +2m style).

​
Examples

Local envelope (default):
User-timezone envelope:
Elapsed time enabled:

​
System prompt: Current Date & Time

If the user timezone is known, the system prompt includes a dedicated Current Date & Time section with the time zone only. It intentionally keeps the live clock, day, and date out of the system prompt so prompt caching stays stable:
The prompt also tells the agent to use session_status when it needs the current date, time, or day of week. The status card includes a timestamp line.

​
Direct Gateway messages

Messages sent through direct Gateway paths, including agent and chat.send, receive a compact timestamp prefix unless they already have one:
These prefixes use agents.defaults.userTimezone after validation. If no user timezone is configured, Fased resolves the host timezone at runtime and falls back to UTC only if the host cannot provide one.

​
System event lines (local by default)

Queued system events inserted into agent context are prefixed with a timestamp using the same timezone selection as message envelopes (default: host-local).

​
Configure user timezone + format

  • userTimezone sets the user-local timezone used for prompt context, direct Gateway timestamp injection, session_status, and cron-style current-time lines.
  • timeFormat controls 12h/24h display in session_status and cron-style current-time lines. auto follows OS prefs.

​
Time format detection (auto)

When timeFormat: "auto", Fased inspects the OS preference (macOS/Windows) and falls back to locale formatting. The detected value is cached per process to avoid repeated system calls.

​
Tool payloads + connectors (raw provider time + normalized fields)

Channel tools return provider-native timestamps and add normalized fields for consistency where the connector has a timestamp to normalize:
  • timestampMs: epoch milliseconds (UTC)
  • timestampUtc: ISO 8601 UTC string
Raw provider fields are preserved so nothing is lost.
  • Slack: epoch-like strings from the API
  • Discord: UTC ISO timestamps
  • Telegram/WhatsApp: provider-specific numeric/ISO timestamps
If you need local time, convert it downstream using the known timezone.