Timers schedule future wakes. They do not run code automatically — when one fires, the system wakes the agent and the agent chooses what to do from context and work list.
set_timer.py
Create a one-shot scheduled wake (writes timers table + emits timer_set on the main stream).
--fire-at required — ISO 8601 instant, UTC or with offset (e.g. 2026-03-15T09:00:00Z)
--description optional label, max 500 chars
--recurrence reserved / future use
Validation:fire_at must be strictly in the future in UTC
cancel_timer.py
Cancel an active timer before it fires. Idempotent for already-cancelled; errors if already fired or missing.
--timer-id required — UUID from list_timers or timer_set
list_timers.py
Inspect scheduled timers to avoid duplicates or pick ids to cancel.
--statusactive (default), all, cancelled, or fired
--limit default 50, max 200
⚠ Recurring not native: No native recurring/cron timers. Simulate recurring behavior via chained one-offs (set next timer in the wake that handles the current one). Disclose if this tooling fails.
⚠ Timer history: Dispatch is reliable, but status/list views (especially fired history) may be sparse/lagging and are not complete historical truth in isolation.