cron v1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/03a667bef8eda8f7.

---
name: cron
description: >-
  Schedule, list, pause, resume, edit, or run the user's agentica cron jobs
  with the cronjob tool. Use when asked to remind, schedule a recurring or
  one-shot task, try a job now, or manage jobs that fire unattended.
metadata:
  version: "1.0"
---

# Scheduled jobs

Use the `cronjob` tool. Do not edit crontab or `~/.agentica/cron/jobs.json` by
hand. The tool schema lists the actions; do not invent them.

A job runs in a **fresh session** with none of this conversation. The prompt
must be self-contained: goal, constraints, where things are, what to do when
blocked. A prompt that needs a follow-up question will stall unattended.

## Waiting on something this session started? Not cron.

To learn when a training run, eval, build, or any `tmux`/`nohup` job finishes,
do not schedule a minute-level poll. Start a read-only watcher with
`execute(background=True)` that loops on the job's exit marker (see the
`execute` tool's tmux/nohup notes). It spends no tokens while it waits, and
its exit comes back to this session as a new message.

A cron monitor costs a full agent run per tick and cannot reach this session:
one production job polled a 37-hour training run every 6 minutes, 400+ times,
and kept polling for four days after the run had ended.

Cron is for work that must recur on a clock or outlive this session.

## If a job watches for an end state, it must stop itself

Write the exit condition into the prompt: "when `<marker>` exists (or the
process is gone), report the result and pause this job (its own id) with the
cronjob tool". Without it the job keeps firing after there is nothing left to
watch.

## Which tier a job runs under

A job always runs under the permission tier and working directory of the
session that created it, recorded at `create`. Switching this session's tier
later does not change the job. `permission_mode` on create/update can only
make it stricter. Use `ask` for a trial job ("check and tell me what you
would change"): it can read and report, but every write, mutating command and
network call is denied, because nobody is around to approve. Once its runs
look right, the user can raise it.

A job that cannot go on without a person (permission denied, missing
credential, out of scope) should pause its own job with the cronjob tool,
giving a one-line reason. The job's agent is told its own id. The user sees the reason at CLI startup and in
`/cron list`. Do not write a prompt that just retries.

## A job that checks for changes says so when there are none

For a job that looks for something new (a feed, a page, a queue, a report),
write into its prompt: "if nothing new since the last run, reply with exactly
`[NO_UPDATE]` and nothing else". Each run's result is kept in the job's
history; a fixed marker lets the user (and any surface that shows results)
skip empty runs instead of reading "nothing changed" in a dozen phrasings.

Example prompt: "Check https://example.com/releases for a version newer than
the one in ~/notes/last_release.txt. If there is one, write it to that file
and reply with the version and its headline changes. Otherwise reply with
exactly `[NO_UPDATE]`."

A job's agent has the CLI's file, shell, web, memory and `cronjob` tools, and
no session of its own. It has no `list_agents` / `send_message` /
`ask_user_question`: do not write a prompt that tells it to message a session
or ask the user.

Jobs only fire on their schedule while the scheduler daemon is on. How the user
turns it on depends on the surface:

- **Interactive CLI:** they type `/cron daemon on`. You cannot type slash commands; tell them which one. `/cron` is also their surface for list / add / pause / run.
- **Gateway and other surfaces:** `cron.enabled` in `config.yaml` is a
  deployment-level setting. You cannot toggle it from this conversation; tell
  the user to ask whoever manages this deployment to enable it.

`action='run'` executes a job once now so you can show the result before
waiting for the schedule.