12 · Scheduled Tasks (Cron)

cron/, 14 files, of which scheduler.py is 367 KB. This chapter covers letting the agent run on its own when nobody is around — and the whole new class of problems that brings.

12.1 What “cron” Is

cron is the Unix scheduled-task tool; the name comes from the Greek chronos (time). At its heart is an expression format:

0 9 * * 1-5      9:00 a.m., Monday through Friday
*/15 * * * *     every 15 minutes
0 0 1 * *        midnight on the 1st of every month

Field order: minute hour day-of-month month day-of-week

12.2 Scenarios for Scheduled Agents

12.3 The Single Most Important Class: CronPromptInjectionBlocked

class CronPromptInjectionBlocked(...)

“Prompt injection” is the central security threat to agent systems. Let's pin down what it is with a concrete example.

Why the scheduled setting is especially dangerous

12.4 Narrowing the Toolset for Scheduled Tasks

def _resolve_cron_disabled_toolsets(...)

Echoing chapter 4: when a scheduled task runs, certain toolsets are disabled.

This is the second layer of defense. Even if injection detection is bypassed, a hijacked agent can't perform the most dangerous operations — because those tools simply aren't on its tool list.

12.5 Failure Handling

def _failure_streak_nudge(...)          # nudge on consecutive failures
def _upsert_incident_for_failure(...)   # create/update an incident record for a failure

_failure_streak_nudge: the nudge on consecutive failures

The word “streak” is the key: it counts consecutive failures, and one success resets it. That way sporadic failures never accumulate into an alert, while a persistent fault hits the threshold quickly.

_upsert_incident_for_failure: deduplicating incident records

“upsert” = update + insert, meaning “update if it exists, insert if it doesn't.”

12.6 Preventing Duplicate Runs

def try_register_running_job(...)

The try_ in the function name is the key: “try to register” — if an identical job is already running, registration fails and this run is skipped.

One more detail: this registration record must be persistent and carry an expiry.

• Persistent — because the scheduler may be multi-process, and an in-memory flag is invisible to other processes
• With an expiry — if the task process crashes and the registration record isn't cleaned up, that task will never run again. There has to be a timeout that releases the lock automatically (the same problem as the kanban heartbeat in chapter 10)

12.7 Why scheduler.py Is 367 KB

“Run tasks on a schedule” sounds like a while True: sleep(); run() affair. What are 367 KB doing?

12.8 Where Scheduled Tasks Sit in the Overall Architecture