| name | manage-timers |
| description | Start, stop, and run countdown timers and Pomodoro focus sessions, and react to the user's timer controls. Use for "set a 5-minute timer", "cancel the timer", "start a pomodoro", egg timers, focus sessions, and pause/resume/reset taps. Triggers: timer, countdown, set a timer, cancel timer, pomodoro, focus session, remind me in N minutes (short). |
| license | MIT |
| compatibility | Requires JarvisVR agent-backend (server tracks timer state in session.store). |
| metadata | {"agent":"productivity-agent","category":"productivity","version":"1.0","author":"jarvisvr"} |
| allowed-tools | start_timer stop_timer start_pomodoro |
Manage Timers
Own the lifecycle of timer and pomodoro holograms: create them, cancel them,
and handle the control events they emit.
Start a countdown
- Parse the duration to seconds (e.g. "5 minutes" → 300; "an hour and a half" →
5400).
- Call
start_timer{duration_seconds, label?}. The server tracks ends_at_ms
and returns a timer_ref plus a timer directive.
timer props (registry.json; durations in ms):
{ "widget_type": "timer",
"transform": { "anchor": "head", "position": [-0.45,0.1,0.9], "billboard": true },
"props": { "label": "Tea", "duration_ms": 300000, "remaining_ms": 300000,
"state": "running", "mode": "countdown" },
"interactions": ["tap","grab","resize"] }
agent.speech: { "text": "Timer started for 5 minutes.", "final": true }
Pomodoro
Call start_pomodoro{task?} → a pomodoro widget cycling focus →
short_break → … with completed_sessions tracking:
{ "widget_type": "pomodoro",
"props": { "phase": "focus", "remaining_ms": 1500000, "focus_ms": 1500000,
"break_ms": 300000, "state": "running", "task": "Write report" } }
Handle controls (client.interaction, protocol §5.11)
The widget emits events; react with holo.update (or stop_timer):
Event (name) | element | Your action |
|---|
pause | pause_button | recompute remaining_ms, holo.update state:"paused" |
resume | resume_button | set new ends_at, holo.update state:"running" |
reset | reset_button | remaining_ms = duration_ms, state:"idle" |
dismiss | close_button | stop_timer → holo.destroy |
Completion
When remaining_ms hits 0, set state:"completed" and fire a
notification_toast (via the system/notify path):
{ "widget_type": "notification_toast",
"props": { "title": "Timer finished", "body": "Your 5-minute tea timer is done.",
"severity": "success", "source": "Timer", "actions": [ { "id": "snooze", "label": "Snooze" } ] } }
Edge cases
- No duration given →
clarify-intent ("how long?"). Don't default silently.
- "Cancel the timer" with multiple → cancel the most recent (
last_timer_ref)
or ask which; stop_timer{timer_ref} targets a specific one.
- Very long timers / alarms at a clock time → that's a
set-reminders job,
not a countdown.
- Stopwatch →
mode:"stopwatch" counts up; omit a meaningful duration_ms.
