| name | Heartbeat Cron |
| description | Use when the user wants scheduled jobs, daily digests, recurring reminders, or cron_register—not host crontab or shell pipelines. |
| version | 1.0.0 |
| category | bundled |
| primary-tools | ["cron_register","cron_list"] |
| tags | ["cron","schedule","heartbeat","automation","telegram","email","recurring","digest"] |
| triggers | ["schedule","cron","daily digest","recurring","every day","reminder job","cron_register","cron_list","periodic","automate daily"] |
Tool contract (read first)
| Need | Tool |
|---|
| Create or update a scheduled job | cron_register |
| List existing jobs | cron_list |
| Inspect job definitions on disk | read_file on .webagent/cronjobs.json |
| Step tools inside a job | Built-in names only — e.g. web_search, web_fetch, write_file, email, memory_save |
| Output destination | Job fields (cron_list → outputDestination) |
| Silent | delivery: silent |
| Web UI (agent terminal / chat) | delivery: terminal |
| Web UI + Telegram | delivery: terminal + notifyChannel: telegram:<chatId> |
| Email | delivery: email + deliveryEmailTo (wraps all step outputs into one digest email) |
| Send mail inside a step | Step tool email with {to, subject, text[, cc]} — distinct from job delivery |
Non-negotiable: No manual cron run — cron_list reports manualRunSupported: false. Register/refresh does not execute the job. Never use host crontab/at via run_shell. Job delivery routes where results go; step email sends during the run. Tab must stay open for jobs to run. Steps do not pass variables — use fixed write_file paths between steps. Cron runs tools only (no LLM between steps), so dynamic per-recipient cold outreach belongs in task-execution or an approval-first digest cron, not static spam templates.
Tool choice for step bodies: browser-runtime-map. Ad-hoc present/email: artifact-delivery.
When to Use
- User wants digest, reminders, periodic search, or multi-step automation inside Web Agent.
- "Run this every morning", recurring checks, or Telegram/email delivery for jobs.
- Explaining why a job did not run at an exact wall-clock time (tab must stay open).
- Choosing
delivery and avoiding invalid step shapes on Nodebox.
Relation to other skills
- Step tools:
browser-runtime-map. Ad-hoc delivery: artifact-delivery.
Facts (non-negotiable)
- Jobs run only while the app tab/session is open. Closing the browser stops the heartbeat until you return.
- Scheduling is heartbeat-gated, not systemd-style cron:
everyMinutes is minimum spacing between runs; ticks use HEARTBEAT_INTERVAL_MS (typically 30 minutes). Short everyMinutes still waits for the next tick after becoming due.
- State files:
.webagent/heartbeat-state.json, cron definition .webagent/cronjobs.json in the workspace.
tool at job root or each steps[] entry must be a built-in name with that tool's arguments.delivery is only on the job (see table above). notifyChannel applies only when delivery is terminal. Never put silent/terminal as a step tool. email is both job delivery and a valid step tool when arguments include to+subject (+ text for send).- After register/refresh, call
cron_list and tell the user nextEligibleAtMs and outputDestination — do not claim the job already ran unless heartbeat logged ▸ cron '<id>' ran.
- Multi-step chaining: write intermediate results to known paths (
work/...); later steps cannot read prior tool JSON automatically. For outreach: research → write_file targets → email operator for approval — not unsupervised bulk cold email.
Authoring
- Use
cron_register (or edit .webagent/cronjobs.json carefully) with id, everyMinutes (≥1), and delivery (confirm email vs terminal with the user).
- Prefer
web_search, write_file, memory tools — not run_shell in steps on Nodebox (no real POSIX shell). The canonical tool decision table is browser-runtime-map; this skill only adds cron/heartbeat/delivery rules.
- For Telegram side-channel:
delivery: terminal plus notifyChannel: telegram:<chatId> when Telegram is configured; silent/email do not use notifyChannel. Ad-hoc (non-cron) delivery formatting lives in artifact-delivery.
- Multi-step: ordered
steps with shape {"tool":"…","arguments":{…}} (legacy action aliases to tool).
Pitfalls
- Expecting overnight jobs without the tab open — they will not fire.
- Using host
crontab / at via shell — blocked; use cron_register.
- Packing shell pipelines into cron steps in browser-backed runtimes — will fail; use dedicated tools.
Anti-patterns
- Promising a manual cron run, "kick off the cron now", or conflating in-chat skill work with cron execution.
- Saying a job "ran" or "is hunting" right after
cron_register refresh without a heartbeat ▸ cron line.
run_shell steps on Nodebox for install or curl when web_fetch / web_search fits.- Omitting
delivery on new jobs — always set explicitly for clarity.
