TrueTime

Use this skill to avoid time mistakes caused by stale examples, wrong units, timezone drift, or DST confusion.

Non-Negotiable Rules

• Treat user-provided duration values as authoritative.
• Never copy numeric values from examples into real execution.
• Read current time from the runtime clock before calculating.
• Compute canonical target time in UTC first.
• Convert for display second (server timezone, user timezone, other timezone).
• Ask for clarification when timezone context is missing and outcome can change.

Required Workflow

• Extract timing intent exactly.
• Capture literal phrase, value, unit, timezone hint, and target date/time.
• Keep the original requested value unchanged (for example 1 minute stays 1 minute).
• Read current real time.
• Use the bundled script for deterministic calculations:
• Relative: node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai
• Relative (calendar units): node {baseDir}/scripts/true_time.mjs --plus 1month2weeks --user-tz America/New_York --calendar-tz America/New_York
• Absolute: node {baseDir}/scripts/true_time.mjs --target 2026-02-17T09:30:00 --target-tz Asia/Shanghai --user-tz America/Los_Angeles
• NTP time source: node {baseDir}/scripts/true_time.mjs --plus 1h --time-source ntp
• Parse the expression into one precise delta or one precise absolute timestamp.
• Compute UTC target first.
• Convert UTC target to server/user/other requested timezone for presentation.
• Verify the result before execution.
• Confirm target_utc - now_utc equals requested delta.
• Confirm timezone offset conversion is consistent.
• Execute schedules using UTC unless the target scheduler explicitly needs local timezone.
• Report both absolute and relative interpretation in the final response.

Relative Time Guardrails

• Accept explicit units only:
• milliseconds: ms, msec, msecs, millisecond, milliseconds
• seconds: s, sec, second, seconds
• minutes: m, min, minute, minutes
• hours: h, hr, hour, hours
• days: d, day, days
• weeks: w, week, weeks
• months: mo, mon, month, months
• years: y, yr, year, years
• decades: decade, decades
• centuries: century, centuries
• Reject ambiguous units instead of guessing.
• All units support decimal values, including calendar units.
• Examples: 1.5m, 0.25h, 2.5day, 250.5ms, 1.5month, 0.1year, 0.5decade, 0.01century.
• Decimal separator . is preferred; , is accepted as input and normalized.
• Fixed-unit decimals are computed to millisecond precision.
• Calendar-unit policy:
• month/year/decade/century are calendar-aware, not fixed seconds.
• Calendar arithmetic uses --calendar-tz (fallback: user timezone -> server timezone).
• Decimal calendar values are split into integer and fractional parts.
• Integer months use calendar shift; fractional months use the shifted month length to compute milliseconds.
• End-of-month handling clamps to the last valid day (for example Jan 31 + 1 month -> Feb 28/29).
• Keep verification examples explicit:
• 1.5m = 90s
• 250ms = 0.25s
• 1m = 60s
• 1h30m = 5400s
• 2d = 172800s
• 1.5year = 18 months
• 1decade = 10 years
• 0.5decade = 5 years
• 1century = 100 years
• 0.01century = 1 year

Absolute Time Guardrails

• Prefer IANA timezone names (Asia/Shanghai, America/Los_Angeles, UTC).
• Avoid ambiguous abbreviations (CST, IST) unless user confirms meaning.
• If user gives a naive datetime with no timezone, ask once or apply an explicit assumption.
• For DST transition windows, state that the chosen timezone rules were applied.

Timezone Catalog and Customization

• List all available runtime timezones:
• node {baseDir}/scripts/true_time.mjs --list-timezones
• Filter common choices quickly:
• node {baseDir}/scripts/true_time.mjs --list-timezones | rg -i '^(UTC|Asia/(Shanghai|Tokyo|Kolkata)|America/(Los_Angeles|New_York)|Europe/(London|Paris|Berlin))$'
• User custom timezone:
• Accept any valid IANA timezone from --list-timezones.
• Pass user timezone via --user-tz .
• If user timezone is unknown, ask before executing time-sensitive actions.

Common timezones to use in examples and user-facing confirmations:

• UTC (no DST)
• Asia/Shanghai (Beijing time, UTC+08:00, no DST)
• Asia/Tokyo (Tokyo time, UTC+09:00, no DST)
• Asia/Kolkata (India time, UTC+05:30, no DST)
• America/Los_Angeles (US West: PST UTC-08:00 / PDT UTC-07:00, DST applies)
• America/New_York (US East: EST UTC-05:00 / EDT UTC-04:00, DST applies)
• America/Chicago (US Central: CST UTC-06:00 / CDT UTC-05:00, DST applies)
• America/Denver (US Mountain: MST UTC-07:00 / MDT UTC-06:00, DST applies)
• America/Phoenix (Arizona: MST UTC-07:00, typically no DST)
• America/Anchorage (Alaska: AKST UTC-09:00 / AKDT UTC-08:00, DST applies)
• Pacific/Honolulu (Hawaii: HST UTC-10:00, no DST)
• Europe/London (UK: GMT UTC+00:00 / BST UTC+01:00, DST applies)
• Europe/Paris (CET UTC+01:00 / CEST UTC+02:00, DST applies)
• Europe/Berlin (CET UTC+01:00 / CEST UTC+02:00, DST applies)
• Europe/Amsterdam (CET UTC+01:00 / CEST UTC+02:00, DST applies)

DST and Standard-Time Rules

• Never assume fixed offsets for DST regions (America/, many Europe/).
• Always compute with the actual target date, not "current offset."
• For DST fall-back overlaps (ambiguous local time), require explicit offset:
• 2026-11-01T01:30:00 in America/Los_Angeles is ambiguous.
• Ask user to choose -07:00 (before fallback) or -08:00 (after fallback), or provide explicit offset in --target.
• For DST spring-forward gaps (invalid local time), require correction:
• 2026-03-08T02:30:00 in America/Los_Angeles does not exist.
• Ask user to use a valid local time (for example 01:30 or 03:30).
• Prefer explicit-offset absolute targets when DST risk is high:
• --target 2026-11-01T01:30:00-07:00
• --target 2026-11-01T01:30:00-08:00

Chinese Lunar Calendar

• This tool outputs Chinese lunar datetime fields by default:
• lunar_timezone (default Asia/Shanghai, configurable via --lunar-tz)
• now_lunar
• target_lunar
• Use these fields when the user asks for Chinese lunar context.
• For execution/scheduling, still use Gregorian UTC fields as canonical.
• If a user gives only lunar date text and no Gregorian equivalent, ask for confirmation or a Gregorian target before execution.

Time Source Policy (Server vs NTP)

• Default time source is server clock (--time-source server).
• If user explicitly requests "do not use server time", switch to public NTP:
• --time-source ntp
• Optional NTP controls:
• --ntp-server (repeatable or comma-separated)
• --ntp-timeout-ms
• NTP mode example:
• node {baseDir}/scripts/true_time.mjs --plus 30m --time-source ntp --ntp-server time.google.com
• If all NTP servers fail, stop and report failure instead of silently falling back to server time.

Mandatory Integration Points

Use TrueTime calculations before any of the following:

• Cron operations (cron add, cron update, cron wake, cron run) when time or schedule is involved.
• Calendar operations (create/update events, convert invite times, multi-timezone meeting planning).
• Reminder operations (in X minutes/hours, tomorrow at HH:mm, next weekday, repeating reminders).
• Planning tasks that include ETA, deadline conversion, or cross-timezone commitments.

Server Execution Policy

• Persist canonical time as UTC (target_utc_iso and optionally epoch seconds).
• Include human-facing fields for user timezone and server timezone.
• If the scheduler supports timezone-aware execution, pass timezone explicitly.
• If the scheduler only accepts UTC, keep execution in UTC and show converted local preview.
• Runtime note: this skill's helper script uses Node (node .../true_time.mjs).
• Sandbox note: default openclaw-sandbox:bookworm-slim may not include Node; use openclaw-sandbox-common:bookworm-slim or install Node in agents.defaults.sandbox.docker.setupCommand.

High-Frequency Examples

Relative calculations:

• Beijing time, 1 minute later:
• node {baseDir}/scripts/true_time.mjs --plus 1m --user-tz Asia/Shanghai
• Beijing time, 1.5 minutes later:
• node {baseDir}/scripts/true_time.mjs --plus 1.5m --user-tz Asia/Shanghai
• Tokyo time, 250.5 milliseconds later:
• node {baseDir}/scripts/true_time.mjs --plus 250.5ms --user-tz Asia/Tokyo
• Tokyo time, 90 minutes later:
• node {baseDir}/scripts/true_time.mjs --plus 1h30m --user-tz Asia/Tokyo
• US West time, 2 hours later:
• node {baseDir}/scripts/true_time.mjs --plus 2h --user-tz America/Los_Angeles
• US East time, 45 minutes later:
• node {baseDir}/scripts/true_time.mjs --plus 45m --user-tz America/New_York
• India time, 1 day later:
• node {baseDir}/scripts/true_time.mjs --plus 1d --user-tz Asia/Kolkata
• US Central, 1 month later:
• node {baseDir}/scripts/true_time.mjs --plus 1month --user-tz America/Chicago --calendar-tz America/Chicago
• US Central, 1.5 months later:
• node {baseDir}/scripts/true_time.mjs --plus 1.5month --user-tz America/Chicago --calendar-tz America/Chicago
• US Mountain, 1 year later:
• node {baseDir}/scripts/true_time.mjs --plus 1year --user-tz America/Denver --calendar-tz America/Denver
• US Mountain, 0.1 years later:
• node {baseDir}/scripts/true_time.mjs --plus 0.1year --user-tz America/Denver --calendar-tz America/Denver
• Hawaii, 1 decade later:
• node {baseDir}/scripts/true_time.mjs --plus 1decade --user-tz Pacific/Honolulu --calendar-tz Pacific/Honolulu
• Hawaii, 0.5 decades later:
• node {baseDir}/scripts/true_time.mjs --plus 0.5decade --user-tz Pacific/Honolulu --calendar-tz Pacific/Honolulu
• UTC, 1 century later:
• node {baseDir}/scripts/true_time.mjs --plus 1century --user-tz UTC --calendar-tz UTC
• UTC, 0.01 centuries later:
• node {baseDir}/scripts/true_time.mjs --plus 0.01century --user-tz UTC --calendar-tz UTC

Absolute and cross-timezone calculations:

• Beijing local absolute time:
• node {baseDir}/scripts/true_time.mjs --target 2026-02-18T09:00:00 --target-tz Asia/Shanghai --user-tz Asia/Shanghai
• London meeting shown to US East:
• node {baseDir}/scripts/true_time.mjs --target 2026-05-20T14:00:00 --target-tz Europe/London --user-tz America/New_York
• UTC target shown to Europe/Berlin:
• node {baseDir}/scripts/true_time.mjs --target 2026-04-15T16:00:00Z --user-tz Europe/Berlin
• DST ambiguity resolved by explicit offset:
• node {baseDir}/scripts/true_time.mjs --target 2026-11-01T01:30:00-07:00 --user-tz America/Los_Angeles
• node {baseDir}/scripts/true_time.mjs --target 2026-11-01T01:30:00-08:00 --user-tz America/Los_Angeles
• NTP-based reminder time:
• node {baseDir}/scripts/true_time.mjs --plus 15m --time-source ntp --user-tz Asia/Shanghai

Output Contract

When sending or scheduling time-sensitive actions, always include:

• now_utc
• target_utc
• target_user_tz (if known)
• target_server_tz
• delta_milliseconds
• delta_seconds
• time_source (server | ntp | override)
• ntp_server (when time_source=ntp)
• now_lunar
• target_lunar
• assumptions (if any)

Do not continue with execution when any required field is unknown and may change the target time materially.