octos-org/octos/cron

Cron Scheduling

Use the cron tool to schedule reminders and recurring tasks.

IMPORTANT: User Consent Required

NEVER add, remove, enable, or disable cron jobs unless the user explicitly asks you to. Do NOT proactively create scheduled tasks, reminders, or recurring jobs. Only use the cron tool when the user's message clearly requests scheduling (e.g., "remind me every day at 9am", "set up a recurring check", "schedule a task"). Listing jobs is always allowed.

Actions

Add a recurring job

{"action": "add", "name": "standup", "message": "Time for daily standup!", "every_seconds": 86400}

Add a cron-expression job

{"action": "add", "name": "morning", "message": "Good morning check-in", "cron_expr": "0 0 9 * * * *", "timezone": "America/Los_Angeles"}

Add a one-time job

{"action": "add", "name": "reminder", "message": "Meeting in 5 minutes", "at_ms": 1707552000000}

List jobs

{"action": "list"}

Remove a job

By exact ID:

{"action": "remove", "job_id": "abc12345"}

By name (partial match, preferred when user says "cancel X"):

{"action": "remove", "name": "ua877"}

This removes ALL jobs whose name or message contains "ua877" (case-insensitive). Always prefer name-based removal — don't ask the user for a job ID.

Enable/disable a job

{"action": "enable", "job_id": "abc12345"}
{"action": "disable", "job_id": "abc12345"}

Delivery

To deliver responses to a specific channel:

{"action": "add", "name": "alert", "message": "Check metrics", "every_seconds": 3600, "channel": "telegram", "chat_id": "123456"}

Timezone

IMPORTANT: Cron expressions are evaluated in UTC by default. You MUST use the timezone parameter when the user specifies a local time. Use IANA timezone names.

Before creating any cron job with a specific time, you MUST confirm the user's timezone. Ask: "What is your timezone? (e.g. America/Los_Angeles for Pacific Time, Asia/Shanghai for China Standard Time)". Do NOT guess or assume — always ask if you don't know.

Once confirmed, always include timezone in the cron tool call:

{"action": "add", "name": "daily-report", "message": "Send report", "cron_expr": "0 0 9 * * * *", "timezone": "Asia/Shanghai"}

Common timezones: America/Los_Angeles (Pacific), America/New_York (Eastern), Asia/Shanghai (China), Asia/Tokyo (Japan), Europe/London (UK), Europe/Berlin (Central Europe).

Cron Expression Format

Standard 7-field cron: sec min hour day-of-month month day-of-week year