| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243 |
- """``hermes cron`` subcommand parser."""
- from __future__ import annotations
- import argparse
- from typing import Callable
- from hermes_cli.subcommands._shared import add_accept_hooks_flag
- def _flag(parser, *names, help, **kw):
- parser.add_argument(*names, action="store_true", help=help, **kw)
- def _catch_up_flag(value: str) -> bool:
- if value not in ("on", "off"):
- raise argparse.ArgumentTypeError("use 'on' (run missed runs once) or 'off' (skip them)")
- return value == "on"
- def _add_catch_up(parser) -> None:
- parser.add_argument(
- "--catch-up", dest="catch_up", type=_catch_up_flag, metavar="{on,off}",
- help="Runs missed while the machine was off: 'on' runs once on return, 'off' skips "
- "them (each is booked as a 'missed' row in `hermes cron runs`). Default: "
- "cron.catch_up_missed for recurring jobs; one-shots skip.")
- def build_cron_parser(subparsers, *, cmd_cron: Callable) -> None:
- """Attach the ``cron`` subcommand (and its sub-actions) to ``subparsers``."""
- cron_parser = subparsers.add_parser(
- "cron", help="Cron job management", description="Manage scheduled tasks")
- cron_subparsers = cron_parser.add_subparsers(dest="cron_command")
- cron_list = cron_subparsers.add_parser("list", help="List scheduled jobs")
- _flag(cron_list, "--all", help="Include disabled and completed jobs")
- cron_create = cron_subparsers.add_parser(
- "create", aliases=["add"], help="Create a scheduled job")
- cron_create.add_argument("schedule", help="Schedule like '30m', 'every 2h', or '0 9 * * *'")
- cron_create.add_argument(
- "prompt", nargs="?", help="Optional self-contained prompt or task instruction")
- cron_create.add_argument("--name", help="Optional human-friendly job name")
- cron_create.add_argument("--deliver",
- help="Delivery target: origin, local, telegram, discord, signal, "
- "platform:chat_id, or bot-chat[:profile] (inject output into a "
- "local profile's canonical Bot Chat as a message the bot responds to), "
- "or room:<room_id>[@profile] (post into a Group Chat; wakes only the Bots it @mentions)")
- cron_create.add_argument("--failure-deliver", dest="failure_deliver",
- help="Override target for FAILURE notices only (same grammar as "
- "--deliver). 'local' suppresses failure notices entirely; run "
- "state stays visible in `hermes cron list`. Omit = failures "
- "follow --deliver.")
- cron_create.add_argument("--repeat", type=int, help="Optional repeat count")
- _add_catch_up(cron_create)
- cron_create.add_argument("--skill", dest="skills", action="append",
- help="Attach a skill. Repeat to add multiple skills.")
- cron_create.add_argument("--script",
- help="Path to a script under ~/.hermes/scripts/. Default mode: "
- "script stdout is injected into the agent's prompt each run. "
- "With --no-agent: the script IS the job and its stdout is "
- "delivered verbatim. .sh/.bash files run via bash, everything "
- "else via Python.")
- _flag(cron_create, "--no-agent", dest="no_agent", default=False,
- help="Skip the LLM entirely — run --script on schedule and deliver "
- "its stdout directly. Empty stdout = silent. Classic watchdog "
- "pattern (memory alerts, disk alerts, CI pings).")
- cron_create.add_argument("--monitor-script", dest="monitor_script",
- help="Monitor mode: path to a cheap source script under "
- "~/.hermes/scripts/ that runs each tick BEFORE the agent. "
- "Unchanged output (exact-bytes hash) suppresses the agent run "
- "entirely; changed output injects a MONITOR CHANGE DETECTED "
- "diff into the prompt. Script output must be stable (no "
- "timestamps). Mutually exclusive with --monitor-url; "
- "incompatible with --no-agent.")
- cron_create.add_argument("--monitor-url", dest="monitor_url",
- help="Monitor mode: http(s) URL fetched with a bounded GET each tick "
- "instead of a script. Same hash-suppression semantics as "
- "--monitor-script.")
- cron_create.add_argument("--workdir",
- help="Absolute path for the job to run from. Injects AGENTS.md / CLAUDE.md / .cursorrules from that directory and uses it as the cwd for terminal/file/code_exec tools. Omit to preserve old behaviour (no project context files).",
- )
- cron_create.add_argument("--model",
- help="Pin this job to a specific inference model (user-owned; the "
- "agent's cronjob tool cannot set this). Omit to follow "
- "cron.model, then the main agent model (`hermes model`), at fire time.")
- cron_create.add_argument("--pin", dest="pinned", action="store_true", default=None,
- help="Lock the CURRENT main agent model (and its provider) onto this job so later "
- "`hermes model` changes never touch it. Ignored when --model is given.")
- cron_create.add_argument("--provider", dest="model_provider",
- help="Inference provider paired with --model (e.g. 'openrouter', 'nous').")
- cron_create.add_argument("--reasoning-effort", dest="reasoning_effort",
- help="Pin this job's reasoning (thinking) effort: none, minimal, low, "
- "medium, high, xhigh, max, or ultra. Overrides agent.reasoning_effort "
- "and agent.reasoning_overrides for this job; unsupported levels are "
- "clamped by the provider at request time. Omit to follow config.")
- cron_create.add_argument("--interpreter",
- help="Absolute or ~ path to a Python in your own venv (e.g. ~/venvs/report/bin/python) "
- "for a .py --script / --monitor-script, so it can import packages Hermes does not "
- "ship. .sh/.bash still run under bash. Omit to use Hermes' Python.")
- cron_create.add_argument("--timezone",
- help="IANA zone for this job's schedule (e.g. Asia/Hong_Kong), so the cron "
- "expression is read as THAT zone's wall clock whatever the profile's timezone "
- "is. Omit to inherit the profile timezone.")
- cron_create.add_argument("--grace-minutes", dest="grace_minutes",
- help="Catch-up window override in minutes (0-1440) for a cron schedule. "
- "Default: half the period, clamped to 2-120 minutes. 0 = never catch up "
- "(a missed occurrence is skipped, not run late).")
- cron_create.add_argument(
- "--continuity", dest="continuity", action="store_const", const=True, default=None,
- help="Each run wakes up with the job's own previous output injected "
- "into its prompt, so it can dedupe against what was already "
- "reported and continue where the last run left off (scouts, "
- "monitors, incremental digests). First run is unchanged.")
- _flag(cron_create, "--paused", default=False,
- help="Create disabled in one write; resume to schedule, or explicitly run now.")
- cron_create.add_argument("--paused-reason", help="Auditable reason; requires --paused.")
- cron_edit = cron_subparsers.add_parser("edit", help="Edit an existing scheduled job")
- cron_edit.add_argument("job_id", help="Job ID to edit")
- cron_edit.add_argument("--schedule", help="New schedule")
- cron_edit.add_argument("--prompt", help="New prompt/task instruction")
- cron_edit.add_argument("--name", help="New job name")
- cron_edit.add_argument("--deliver", help="New delivery target")
- cron_edit.add_argument("--failure-deliver", dest="failure_deliver",
- help="Override target for failure notices (same grammar as --deliver; "
- "'local' suppresses; '' clears the override)")
- cron_edit.add_argument("--repeat", type=int, help="New repeat count")
- _add_catch_up(cron_edit)
- cron_edit.add_argument("--skill", dest="skills", action="append",
- help="Replace the job's skills with this set. Repeat to attach multiple skills.")
- cron_edit.add_argument("--add-skill", dest="add_skills", action="append",
- help="Append a skill without replacing the existing list. Repeatable.")
- cron_edit.add_argument("--remove-skill", dest="remove_skills", action="append",
- help="Remove a specific attached skill. Repeatable.")
- _flag(cron_edit, "--clear-skills", help="Remove all attached skills from the job")
- cron_edit.add_argument("--script",
- help="Path to a script under ~/.hermes/scripts/. Pass empty string to clear. "
- "With --no-agent the script IS the job; otherwise its stdout is "
- "injected into the agent's prompt each run.")
- cron_edit.add_argument(
- "--no-agent", dest="no_agent", action="store_const", const=True, default=None,
- help="Enable no-agent mode on this job (requires --script or an "
- "existing script on the job).")
- cron_edit.add_argument("--agent", dest="no_agent", action="store_const", const=False,
- help="Disable no-agent mode on this job (reverts to LLM-driven execution).")
- cron_edit.add_argument(
- "--continuity", dest="continuity", action="store_const", const=True, default=None,
- help="Turn on run-to-run continuity: each run sees the job's own "
- "previous output (dedupe, continue where it left off).")
- cron_edit.add_argument("--no-continuity", dest="continuity", action="store_const", const=False,
- help=("Turn off run-to-run continuity (other context_from job refs are preserved)."))
- cron_edit.add_argument("--monitor-script", dest="monitor_script",
- help="Set/replace the monitor source script (see `hermes cron create "
- "--monitor-script`). Pass empty string to clear.")
- cron_edit.add_argument("--monitor-url", dest="monitor_url",
- help=("Set/replace the monitor source URL. Pass empty string to clear."))
- cron_edit.add_argument("--workdir",
- help="Absolute path for the job to run from (injects AGENTS.md etc. and sets terminal cwd). Pass empty string to clear.",
- )
- cron_edit.add_argument("--model",
- help="Pin this job to a specific inference model (user-owned; the "
- "agent's cronjob tool cannot set this). Pass empty string to "
- "clear the pin and follow cron.model, then the main agent model.")
- _pin = cron_edit.add_mutually_exclusive_group()
- _pin.add_argument("--pin", dest="pinned", action="store_true", default=None,
- help="Lock the CURRENT main agent model (and its provider) onto this job.")
- _pin.add_argument("--unpin", dest="pinned", action="store_false",
- help="Release the job's model pin so it follows the main agent model again.")
- cron_edit.add_argument("--provider", dest="model_provider",
- help="Inference provider paired with --model. Pass empty string to clear.")
- cron_edit.add_argument("--reasoning-effort", dest="reasoning_effort",
- help="Pin this job's reasoning (thinking) effort: none, minimal, low, "
- "medium, high, xhigh, max, or ultra. Pass empty string to clear "
- "the pin and follow config resolution.")
- cron_edit.add_argument("--interpreter",
- help="Absolute or ~ path to a Python for a .py script / monitor script. "
- "Pass empty string to clear (back to Hermes' Python).")
- cron_edit.add_argument("--timezone",
- help="IANA zone for this job's schedule. Pass empty string to clear the pin "
- "(back to the profile timezone); next_run_at is recomputed in the new zone.")
- cron_edit.add_argument("--grace-minutes", dest="grace_minutes",
- help="Catch-up window override in minutes (0-1440). 0 = never catch up. "
- "Pass empty string to restore the computed window.")
- # lifecycle actions
- cron_pause = cron_subparsers.add_parser("pause", help="Pause a scheduled job")
- cron_pause.add_argument("job_id", help="Job ID to pause")
- cron_resume = cron_subparsers.add_parser("resume", help="Resume a paused job")
- cron_resume.add_argument("job_id", help="Job ID to resume")
- cron_resume.add_argument("--at", dest="run_at", help="Re-arm at an ISO-8601 time")
- _flag(cron_resume, "--run-now", help="Re-arm to run now")
- cron_run = cron_subparsers.add_parser("run", help="Run a job on the next scheduler tick")
- cron_run.add_argument("job_id", help="Job ID to trigger")
- add_accept_hooks_flag(cron_run)
- cron_cancel = cron_subparsers.add_parser(
- "cancel", help="Stop a job's live run (its schedule is untouched)")
- cron_cancel.add_argument("job_id", help="Job ID whose in-flight run to stop")
- cron_cancel.add_argument(
- "--reason", help="Optional note recorded with the cancelled run")
- cron_remove = cron_subparsers.add_parser(
- "remove", aliases=["rm", "delete"], help="Remove a scheduled job")
- cron_remove.add_argument("job_id", help="Job ID to remove")
- # cron status
- cron_subparsers.add_parser("status", help="Check if cron scheduler is running")
- cron_runs = cron_subparsers.add_parser(
- "runs", aliases=["history"], help="Show durable execution attempts")
- cron_runs.add_argument("job_id", nargs="?", help="Optional job ID filter")
- cron_runs.add_argument("--limit", type=int, default=20, help="Rows to show (1-500)")
- # cron incidents — durable failure incidents (list/ack)
- cron_incidents = cron_subparsers.add_parser(
- "incidents", help="List or acknowledge durable cron failure incidents")
- cron_incidents.add_argument("--state", choices=["detected", "alerted", "resolved", "closed"],
- help="Filter incidents by lifecycle state")
- cron_incidents.add_argument(
- "incident_action", nargs="?", default="list", choices=["list", "ack"],
- help="Action (default: list)")
- cron_incidents.add_argument("incident_id", nargs="?", help="Incident ID to acknowledge (ack)")
- # notepad: per-job durable KV, injected into the job prompt each run.
- cron_notepad = cron_subparsers.add_parser(
- "notepad", help="Read/write a job's durable notepad (persistent KV across runs)")
- cron_notepad.add_argument("job_id", help="Job ID the notepad belongs to")
- cron_notepad.add_argument(
- "notepad_action", nargs="?", default="list", choices=["get", "set", "delete", "list"],
- help="Action (default: list)")
- cron_notepad.add_argument("key", nargs="?", help="Notepad key (get/set/delete)")
- cron_notepad.add_argument("value", nargs="?", help="Value to store (set)")
- cron_subparsers.add_parser("doctor", help="Check scheduled jobs for common health issues")
- cron_tick = cron_subparsers.add_parser("tick", help="Run due jobs once and exit")
- add_accept_hooks_flag(cron_tick)
- add_accept_hooks_flag(cron_parser)
- cron_parser.set_defaults(func=cmd_cron)
|