cron — Scheduled Task System

🎯 Why This Module Exists

Without the cron module, users would have no way to schedule recurring agent tasks — every interaction with Hermes would require manual triggering. The core agent (run_agent.py) is designed for synchronous, on-demand execution: a user asks a question, the agent responds. But many valuable use cases are inherently periodic: daily news digests, hourly system health checks, weekly report generation, scheduled data collection. The cron module adds a time dimension to the agent, transforming it from a reactive tool into a proactive assistant. It handles schedule parsing (cron expressions, intervals, one-shots), job persistence across process restarts, delivery routing to 17+ platforms (Telegram, Discord, Slack, Matrix, etc.), and execution isolation so each job runs in a fresh session without state leakage. The module is intentionally separate from the agent core because scheduling, persistence, and delivery are daemon-level concerns that would bloat the lightweight CLI agent.

🚶 Step-by-Step Narrated Walkthrough

Follow a single cron job from creation through execution and delivery as it flows through the entire cron pipeline:

1. Job Creation — User runs hermes cron create --schedule "0 9 * * *" --prompt "Summarize top tech news" --deliver telegram:daily_channel. The create_job() function generates a UUID, parses the schedule, and persists the job to ~/.hermes/cron/jobs.json.
2. Schedule Parsing — parse_schedule("0 9 * * *") detects a 5-field cron expression, validates it with croniter, and returns {"kind": "cron", "expr": "0 9 * * *"}.
3. Gateway Tick — The gateway daemon calls tick() every 60 seconds. It acquires ~/.hermes/cron/.tick.lock to prevent concurrent execution across multiple gateway instances.
4. Due Check — compute_next_run() uses croniter to calculate the next fire time. At 09:00, the job is due. A dynamic grace period (half the schedule period, clamped to 120s–2h) handles missed ticks.
5. Pre-run Script — If the job has an optional pre-run script, it executes first. Its stdout is prepended to the prompt (e.g., injecting live stock prices). Script failures are non-fatal.
6. Agent Execution — A fresh AIAgent instance is created in an isolated session. The prompt and optional skills are passed in. No prior context or state leaks between runs.
7. Output Capture — The agent's response is captured and saved to ~/.hermes/cron/output/{job_id}/{timestamp}.md. Output is immutable — historical runs are never overwritten.
8. Delivery Resolution — _resolve_delivery_target() maps telegram:daily_channel to a concrete platform + chat_id. If "origin" is specified, it falls back through live adapter, standalone HTTP, and home channel env vars.
9. Message Delivery — The output is sent via the gateway's live adapter (if running, supports E2EE) or standalone HTTP. Delivery failures are logged but non-fatal; output is already saved locally.
10. State Update — mark_job_run() updates last_run_at and computes the next run time. The updated job is persisted back to jobs.json via atomic temp-file + rename.

Schedule Resolution and Grace Windows

The Problem: The scheduler ticks every 60 seconds, but jobs might be due between ticks. One-shot jobs have a narrow fire window. Recurring jobs that miss their window (gateway was down) need to catch up without executing stale tasks.

The Approach: Each schedule type has its own resolution logic. Interval jobs compare last_run + interval against now. Cron jobs use croniter.get_next() to find the next fire time. One-shot jobs get a fixed 120-second grace window after their run_at time. Recurring jobs get a dynamic grace period equal to half their schedule period, clamped between 120 seconds and 2 hours.

Why This Algorithm: A fixed grace period would either miss infrequent jobs (too short) or re-execute frequent jobs (too long). The dynamic approach scales: a 5-minute job gets a 2.5-minute grace, while a daily job gets a 2-hour catch-up window.

graph TD
    A["tick() called"] --> B{"Schedule kind?"}
    B -->|"interval"| C["last_run + minutes <= now?"]
    B -->|"cron"| D["croniter.get_next() <= now?"]
    B -->|"once"| E["run_at in grace window?"]
    C -->|"Yes"| F["Execute Job"]
    D -->|"Yes"| F
    E -->|"Yes and not already run"| F
    C -->|"No"| G["Skip"]
    D -->|"No"| G
    E -->|"No or already run"| G
    F --> H["mark_job_run()"]
    H --> I["compute_next_run()"]

Hot Paths

The most performance-sensitive code paths in this module:

• tick() — every 60 seconds: Loads jobs.json, iterates all jobs, checks schedules. O(n) where n is job count. For typical deployments (< 100 jobs), this is sub-millisecond.
• croniter evaluation: O(1) per job. croniter.get_next() is a mathematical computation, not a search.
• Delivery routing: Channel name resolution may involve a network call (e.g., Discord channel lookup). Cached after first resolution.

Resource Usage

• Memory: Minimal — jobs.json is loaded into memory only during tick(). Typical size is < 100 KB even with hundreds of jobs.
• Disk: Output files grow over time. Each execution creates a ~1-10 KB markdown file. No automatic cleanup; users manage via hermes cron clean.
• I/O: One file read (jobs.json) + one atomic write per tick with due jobs. Output writes are append-only (new files, never modify existing).