From 9cda237bb16fe5cfd1185cf381a8db4ce396cf77 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Mon, 4 May 2026 12:39:19 -0700 Subject: [PATCH] docs(cron): lead with agent-driven setup for no-agent mode (#19871) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The shipped no-agent docs introduced the feature via CLI first and mentioned the chat path as a two-line afterthought. That buries the actual value prop: the cronjob tool exposes no_agent directly to the agent, so a user can describe a watchdog in plain language and Hermes wires up the script + schedule + delivery without anyone opening an editor. Changes: * cron-script-only.md: promote 'Create One from Chat' above 'Create One from the CLI', flesh it out with a worked transcript (the actual tool calls the agent makes), add subsections covering 'what the agent decides for you' (when to pick no_agent=True vs LLM mode) and 'managing watchdogs from chat' (pause/resume/edit/ remove all agent-accessible). * user-guide/features/cron.md: - Add 'no-agent mode' to the top-level feature list with a cross- link, plus a sentence up top making it clear everything is agent-accessible through the cronjob tool. - Add 'The agent sets these up for you' subsection to the no-agent section showing the exact tool call shape. * automate-with-cron.md: tighten the existing tip box to mention the agent-driven path, not just CLI scheduling. No behavior change — docs only. --- website/docs/guides/automate-with-cron.md | 2 +- website/docs/guides/cron-script-only.md | 76 +++++++++++++++++++---- website/docs/user-guide/features/cron.md | 21 +++++++ 3 files changed, 86 insertions(+), 13 deletions(-) diff --git a/website/docs/guides/automate-with-cron.md b/website/docs/guides/automate-with-cron.md index b47dae9378..46becd8857 100644 --- a/website/docs/guides/automate-with-cron.md +++ b/website/docs/guides/automate-with-cron.md @@ -15,7 +15,7 @@ Cron jobs run in fresh agent sessions with no memory of your current chat. Promp ::: :::tip Don't need the LLM? Use no-agent mode. -For recurring watchdogs where the script already produces the exact message you want to send (memory alerts, disk alerts, CI pings, heartbeats), skip the LLM entirely with [script-only cron jobs](/docs/guides/cron-script-only). Zero tokens, same scheduler. +For recurring watchdogs where the script already produces the exact message you want to send (memory alerts, disk alerts, CI pings, heartbeats), skip the LLM entirely with [script-only cron jobs](/docs/guides/cron-script-only). Zero tokens, same scheduler. You can ask Hermes to set one up for you in chat — the `cronjob` tool knows when to pick `no_agent=True` and writes the script for you. ::: --- diff --git a/website/docs/guides/cron-script-only.md b/website/docs/guides/cron-script-only.md index 67ab178d7a..06fa288006 100644 --- a/website/docs/guides/cron-script-only.md +++ b/website/docs/guides/cron-script-only.md @@ -41,8 +41,72 @@ Use no-agent mode for: Use a normal (LLM-driven) cron job when you need the agent to **decide** what to say — summarize a long document, pick interesting items from a feed, draft a human-friendly message. The no-agent path is for cases where the script's stdout already IS the message. +## Create One from Chat + +The real win of no-agent mode is that the agent itself can set up the watchdog for you — no editor, no shell, no remembering CLI flags. You describe what you want, Hermes writes the script, schedules it, and tells you when it'll fire. + +### Example transcript + +> **You:** ping me on telegram if RAM is over 85% every 5 minutes +> +> **Hermes:** *(writes `~/.hermes/scripts/memory-watchdog.sh`, then calls `cronjob(...)` with `no_agent=true`)* +> +> Set up. Runs every 5 min, alerts Telegram only when RAM is over 85%. Script: `memory-watchdog.sh`. Job ID: `abc123`. + +Under the hood, the agent makes two tool calls: + +```python +# 1. Write the check script +write_file( + path="~/.hermes/scripts/memory-watchdog.sh", + content='''#!/usr/bin/env bash +ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}') +if [ "$ram_pct" -ge 85 ]; then + echo "RAM ${ram_pct}% on $(hostname)" +fi +# Empty stdout = silent tick; no message sent. +''', +) + +# 2. Schedule it — no_agent=True skips the LLM on every tick +cronjob( + action="create", + schedule="every 5m", + script="memory-watchdog.sh", + no_agent=True, + deliver="telegram", + name="memory-watchdog", +) +``` + +From that point on every tick is free: the scheduler runs the script, pipes its stdout to Telegram if non-empty, and never touches a model. + +### What the agent decides for you + +When you phrase a request like "alert me when X" or "every N minutes check Y and tell me if Z", Hermes' `cronjob` tool description tells it to reach for `no_agent=True` whenever the message content is fully determined by the script. It falls back to the normal LLM-driven path when the request needs reasoning (*"summarize the new issues"*, *"pick the most interesting headlines"*, *"draft a friendly reminder"*). + +You don't have to specify `--no-agent` yourself. Just describe the behavior. + +### Managing watchdogs from chat + +The agent can pause, resume, edit, and remove jobs the same way it creates them: + +> **You:** stop the memory watchdog for tonight +> +> **Hermes:** *(calls `cronjob(action='pause', job_id='abc123')`)* +> +> Paused. Resume with "turn it back on" or via `hermes cron resume abc123`. + +> **You:** change it to every 15 minutes +> +> **Hermes:** *(calls `cronjob(action='update', job_id='abc123', schedule='every 15m')`)* + +The full lifecycle (create / list / update / pause / resume / run-now / remove) is available to the agent without you learning any CLI commands. + ## Create One from the CLI +Prefer the shell? The CLI path gives you the same result with three commands: + ```bash # 1. Write your script cat > ~/.hermes/scripts/memory-watchdog.sh <<'EOF' @@ -70,18 +134,6 @@ hermes cron run # fire it once to test That's the whole thing. No prompt, no skill, no model. -## Create One from Chat - -You can also ask the agent to set one up conversationally. The `cronjob` tool now accepts a `no_agent` parameter: - -> *"Ping me on Telegram if RAM is over 85%, every 5 minutes."* - -The agent will: - -1. Write the check script to `~/.hermes/scripts/` via `write_file`. -2. Call `cronjob(action='create', schedule='every 5m', script='memory-watchdog.sh', no_agent=true, deliver='telegram')`. - -This is the same scheduler the agent already uses for LLM-driven jobs; `no_agent=true` just picks the script-only code path. ## How Script Output Maps to Delivery diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md index cd6b4652ba..dd151dece7 100644 --- a/website/docs/user-guide/features/cron.md +++ b/website/docs/user-guide/features/cron.md @@ -17,6 +17,9 @@ Cron jobs can: - attach zero, one, or multiple skills to a job - deliver results back to the origin chat, local files, or configured platform targets - run in fresh agent sessions with the normal static tool list +- run in **no-agent mode** — a script on a schedule, its stdout delivered verbatim, zero LLM involvement (see the [no-agent mode](#no-agent-mode-script-only-jobs) section below) + +All of this is available to Hermes itself through the `cronjob` tool, so you can create, pause, edit, and remove jobs by asking in plain language — no CLI required. :::warning Cron-run sessions cannot recursively create more cron jobs. Hermes disables cron management tools inside cron executions to prevent runaway scheduling loops. @@ -308,6 +311,24 @@ Semantics: `.sh` / `.bash` files run under `/bin/bash`; anything else under the current Python interpreter (`sys.executable`). Scripts must live in `~/.hermes/scripts/` (same sandboxing rule as the pre-run script gate). +### The agent sets these up for you + +The `cronjob` tool's schema exposes `no_agent` to Hermes directly, so you can describe a watchdog in chat and let the agent wire it up: + +```text +Ping me on Telegram if RAM is over 85%, every 5 minutes. +``` + +Hermes will write the check script to `~/.hermes/scripts/` via `write_file`, then call: + +```python +cronjob(action="create", schedule="every 5m", + script="memory-watchdog.sh", no_agent=True, + deliver="telegram", name="memory-watchdog") +``` + +It picks `no_agent=True` automatically when the message content is fully determined by the script (watchdogs, threshold alerts, heartbeats). The same tool also lets the agent pause, resume, edit, and remove jobs — so the whole lifecycle is chat-driven without anyone touching the CLI. + See the [Script-Only Cron Jobs guide](/docs/guides/cron-script-only) for worked examples. ## Provider recovery