91 lines
2.2 KiB
Markdown
91 lines
2.2 KiB
Markdown
---
|
|
sidebar_position: 11
|
|
title: "Cron Internals"
|
|
description: "How Hermes stores, schedules, edits, pauses, skill-loads, and delivers cron jobs"
|
|
---
|
|
|
|
# Cron Internals
|
|
|
|
Hermes cron support is implemented primarily in:
|
|
|
|
- `cron/jobs.py`
|
|
- `cron/scheduler.py`
|
|
- `tools/cronjob_tools.py`
|
|
- `gateway/run.py`
|
|
- `hermes_cli/cron.py`
|
|
|
|
## Scheduling model
|
|
|
|
Hermes supports:
|
|
|
|
- one-shot delays
|
|
- intervals
|
|
- cron expressions
|
|
- explicit timestamps
|
|
|
|
The model-facing surface is a single `cronjob` tool with action-style operations:
|
|
|
|
- `create`
|
|
- `list`
|
|
- `update`
|
|
- `pause`
|
|
- `resume`
|
|
- `run`
|
|
- `remove`
|
|
|
|
## Job storage
|
|
|
|
Cron jobs are stored in Hermes-managed local state (`~/.hermes/cron/jobs.json`) with atomic write semantics.
|
|
|
|
Each job can carry:
|
|
|
|
- prompt
|
|
- schedule metadata
|
|
- repeat counters
|
|
- delivery target
|
|
- lifecycle state (`scheduled`, `paused`, `completed`, etc.)
|
|
- zero, one, or multiple attached skills
|
|
|
|
Backward compatibility is preserved for older jobs that only stored a legacy single `skill` field or none of the newer lifecycle fields.
|
|
|
|
## Runtime behavior
|
|
|
|
The scheduler:
|
|
|
|
- loads jobs
|
|
- computes due work
|
|
- executes jobs in fresh agent sessions
|
|
- optionally injects one or more skills before the prompt
|
|
- handles repeat counters
|
|
- updates next-run metadata and state
|
|
|
|
In gateway mode, cron ticking is integrated into the long-running gateway loop.
|
|
|
|
## Skill-backed jobs
|
|
|
|
A cron job may attach multiple skills. At runtime, Hermes loads those skills in order and then appends the job prompt as the task instruction.
|
|
|
|
This gives scheduled jobs reusable guidance without requiring the user to paste full skill bodies into the cron prompt.
|
|
|
|
## Recursion guard
|
|
|
|
Cron-run sessions disable the `cronjob` toolset. This prevents a scheduled job from recursively creating or mutating more cron jobs and accidentally exploding token usage or scheduler load.
|
|
|
|
## Delivery model
|
|
|
|
Cron jobs can deliver to:
|
|
|
|
- origin chat
|
|
- local files
|
|
- platform home channels
|
|
- explicit platform/chat IDs
|
|
|
|
## Locking
|
|
|
|
Hermes uses lock-based protections so overlapping scheduler ticks do not execute the same due-job batch twice.
|
|
|
|
## Related docs
|
|
|
|
- [Cron feature guide](../user-guide/features/cron.md)
|
|
- [Gateway Internals](./gateway-internals.md)
|