better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/cron-script-only.md

@@ -0,0 +1,247 @@
+---
+sidebar_position: 13
+title: "Script-Only Cron Jobs (No LLM)"
+description: "Classic watchdog cron jobs that skip the LLM entirely — a script runs on schedule and its stdout gets delivered to your messaging platform. Memory alerts, disk alerts, CI pings, periodic health checks."
+---
+
+# Script-Only Cron Jobs
+
+Sometimes you already know exactly what message you want to send. You don't need an agent to reason about it — you just need a script to run on a timer, and its output (if any) to land in Telegram / Discord / Slack / Signal.
+
+Hermes calls this **no-agent mode**. It's the cron system minus the LLM.
+
+<!-- ascii-guard-ignore -->
+```
+   ┌──────────────────┐          ┌──────────────────┐
+   │ scheduler tick   │  every   │ run script       │
+   │ (every N minutes)│ ──────▶ │ (bash or python) │
+   └──────────────────┘          └──────────────────┘
+                                          │
+                                          │ stdout
+                                          ▼
+                                 ┌──────────────────┐
+                                 │ delivery router  │
+                                 │ (telegram/disc…) │
+                                 └──────────────────┘
+```
+<!-- ascii-guard-ignore-end -->
+
+- **No LLM call.** Zero tokens, zero agent loop, zero model spend.
+- **Script is the job.** The script decides whether to alert. Emit output → message gets sent. Emit nothing → silent tick.
+- **Bash or Python.** `.sh` / `.bash` files run under `bash` from `PATH` when available, otherwise `/bin/bash`; any other extension runs under the current Python interpreter. Paths must resolve inside `~/.hermes/scripts/` (relative, absolute, or `~` forms are OK if they stay in that directory). Cron scripts do **not** inherit provider credentials from the Hermes process environment.
+- **Same scheduler.** Lives in `cronjob` alongside LLM jobs — pausing, resuming, listing, logs, and delivery targeting all work the same way.
+
+## When to Use It
+
+Use no-agent mode for:
+
+- **Memory / disk / GPU watchdogs.** Run every 5 minutes, alert only when a threshold is breached.
+- **CI hooks.** Deploy finished → post the commit SHA. Build failed → send the last 100 lines of the log.
+- **Periodic metrics.** "Daily Stripe revenue at 9am" as a simple API call + pretty-print.
+- **External event pollers.** Check an API, alert on state change.
+- **Heartbeats.** Ping a dashboard every N minutes to prove the host is alive.
+
+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'
+#!/usr/bin/env bash
+# Alert when RAM usage is over 85%. Silent otherwise.
+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 run; no message sent.
+EOF
+chmod +x ~/.hermes/scripts/memory-watchdog.sh
+
+# 2. Schedule it
+hermes cron create "every 5m" \
+  --no-agent \
+  --script memory-watchdog.sh \
+  --deliver telegram \
+  --name "memory-watchdog"
+
+# 3. Verify
+hermes cron list
+hermes cron run <job_id>    # fire it once to test
+```
+
+That's the whole thing. No prompt, no skill, no model.
+
+
+## How Script Output Maps to Delivery
+
+| Script behavior | Result |
+|-----------------|--------|
+| Exit 0, non-empty stdout | stdout is delivered verbatim |
+| Exit 0, empty stdout | Silent tick — no delivery |
+| Exit 0, stdout contains `{"wakeAgent": false}` on the last line | Silent tick (shared gate with LLM jobs) |
+| Non-zero exit code | Error alert is delivered (so a broken watchdog doesn't fail silently) |
+| Script timeout | Error alert is delivered |
+
+The "silent when empty" behavior is the key to the classic watchdog pattern: the script is free to run every minute, but the channel only sees a message when something actually needs attention.
+
+## Script Rules
+
+Scripts must live in `~/.hermes/scripts/`. This is enforced at both job-creation time and run time — absolute paths, `~/` expansion, and path-traversal patterns (`../`) are rejected. The same directory is shared with the pre-check script gate used by LLM jobs.
+
+Interpreter choice is by file extension:
+
+| Extension | Interpreter |
+|-----------|-------------|
+| `.sh`, `.bash` | `bash` from `PATH` (fallback `/bin/bash`) |
+| anything else | `sys.executable` (current Python) |
+
+We intentionally do NOT honour `#!/...` shebangs — keeping the interpreter set explicit and small reduces the surface the scheduler trusts.
+
+## Schedule Syntax
+
+Same as all other cron jobs:
+
+```bash
+hermes cron create "every 5m"        # interval
+hermes cron create "every 2h"
+hermes cron create "0 9 * * *"       # standard cron: 9am daily
+hermes cron create "30m"             # one-shot: run once in 30 minutes
+```
+
+See the [cron feature reference](/user-guide/features/cron) for the full syntax.
+
+## Delivery Targets
+
+`--deliver` accepts everything the gateway knows about. Some common shapes:
+
+```bash
+--deliver telegram                       # platform home channel
+--deliver telegram:-1001234567890        # specific chat
+--deliver telegram:-1001234567890:17585  # specific Telegram forum topic
+--deliver discord:#ops
+--deliver slack:#engineering
+--deliver signal:+15551234567
+--deliver local                          # just save to ~/.hermes/cron/output/
+```
+
+No running gateway is required at script-run time for bot-token platforms (Telegram, Discord, Slack, Signal, SMS, WhatsApp) — the tool calls each platform's REST endpoint directly using the credentials already in `~/.hermes/.env` / `~/.hermes/config.yaml`.
+
+## Editing and Lifecycle
+
+```bash
+hermes cron list                                    # see all jobs
+hermes cron pause <job_id>                          # stop firing, keep definition
+hermes cron resume <job_id>
+hermes cron edit <job_id> --schedule "every 10m"    # adjust cadence
+hermes cron edit <job_id> --agent                   # flip to LLM mode
+hermes cron edit <job_id> --no-agent --script …     # flip back
+hermes cron remove <job_id>                         # delete it
+```
+
+Everything that works on LLM jobs (pause, resume, manual trigger, delivery target changes) works on no-agent jobs too.
+
+## Worked Example: Disk Space Alert
+
+```bash
+cat > ~/.hermes/scripts/disk-alert.sh <<'EOF'
+#!/usr/bin/env bash
+# Alert when / or /home is over 90% full.
+THRESHOLD=90
+df -h / /home 2>/dev/null | awk -v t="$THRESHOLD" '
+  NR > 1 && $5+0 >= t {
+    printf "⚠ Disk %s full on %s\n", $5, $6
+  }
+'
+EOF
+chmod +x ~/.hermes/scripts/disk-alert.sh
+
+hermes cron create "*/15 * * * *" \
+  --no-agent \
+  --script disk-alert.sh \
+  --deliver telegram \
+  --name "disk-alert"
+```
+
+Silent when both filesystems are under 90%; fires exactly one line per over-threshold filesystem when one fills up.
+
+## Comparison with Other Patterns
+
+| Approach | What runs | When to use |
+|----------|-----------|-------------|
+| `cronjob --no-agent` (this page) | Your script on Hermes' schedule | Recurring watchdogs / alerts / metrics that don't need reasoning |
+| `cronjob` (default, LLM) | Agent with optional pre-check script | When the message content requires reasoning over data |
+| OS cron + `curl` to a [webhook subscription](/user-guide/messaging/webhooks) | Your script on the OS schedule | When Hermes might be unhealthy (the thing you're monitoring) |
+
+For critical system-health watchdogs that must fire *even when the gateway is down*, use OS-level cron with a plain `curl` to a Hermes webhook subscription (or any external alerting endpoint) — those run as independent OS processes and don't depend on Hermes being up. The in-gateway scheduler is the right choice when the thing being monitored is external.
+
+## Related
+
+- [Automate Anything with Cron](/guides/automate-with-cron) — LLM-driven cron patterns.
+- [Scheduled Tasks (Cron) reference](/user-guide/features/cron) — full schedule syntax, lifecycle, delivery routing.
+- [Webhook Subscriptions](/user-guide/messaging/webhooks) — fire-and-forget HTTP entry points for external schedulers.
+- [Gateway Internals](/developer-guide/gateway-internals) — delivery-router internals.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/cron-troubleshooting.md

@@ -0,0 +1,235 @@
+---
+sidebar_position: 12
+title: "Cron Troubleshooting"
+description: "Diagnose and fix common Hermes cron issues — jobs not firing, delivery failures, skill loading errors, and performance problems"
+---
+
+# Cron Troubleshooting
+
+When a cron job isn't behaving as expected, work through these checks in order. Most issues fall into one of four categories: timing, delivery, permissions, or skill loading.
+
+---
+
+## Jobs Not Firing
+
+### Check 1: Verify the job exists and is active
+
+```bash
+hermes cron list
+```
+
+Look for the job and confirm its state is `[active]` (not `[paused]` or `[completed]`). If it shows `[completed]`, the repeat count may be exhausted — edit the job to reset it.
+
+### Check 2: Confirm the schedule is correct
+
+A misformatted schedule silently defaults to one-shot or is rejected entirely. Test your expression:
+
+| Your expression | Should evaluate to |
+|----------------|-------------------|
+| `0 9 * * *` | 9:00 AM every day |
+| `0 9 * * 1` | 9:00 AM every Monday |
+| `every 2h` | Every 2 hours from now |
+| `30m` | 30 minutes from now |
+| `2025-06-01T09:00:00` | June 1, 2025 at 9:00 AM UTC |
+
+If the job fires once and then disappears from the list, it's a one-shot schedule (`30m`, `1d`, or an ISO timestamp) — expected behavior.
+
+### Check 3: Is the gateway running?
+
+Cron jobs are fired by the gateway's background ticker thread, which ticks every 60 seconds. A regular CLI chat session does **not** automatically fire cron jobs.
+
+If you're expecting jobs to fire automatically, you need a running gateway (`hermes gateway` for foreground, or `hermes gateway start` for the installed service). For one-off debugging, you can manually trigger a tick with `hermes cron tick`.
+
+**Desktop app:** the desktop's primary backend runs its own ticker, and it ticks **every local profile's** cron store — so jobs on a secondary profile keep firing even while that profile's backend is asleep (the desktop puts idle profile backends to sleep after ~10 minutes). You do not need to keep a profile open for its scheduled jobs to run.
+
+### Check 4: Check the system clock and timezone
+
+Jobs use the local timezone. If your machine's clock is wrong or in a different timezone than expected, jobs will fire at the wrong times. Verify:
+
+```bash
+date
+hermes cron list   # Compare next_run times with local time
+```
+
+---
+
+## Delivery Failures
+
+### Check 1: Verify the deliver target is correct
+
+Delivery targets are case-sensitive and require the correct platform to be configured. A misconfigured target silently drops the response.
+
+| Target | Requires |
+|--------|----------|
+| `telegram` | `TELEGRAM_BOT_TOKEN` in `~/.hermes/.env` |
+| `discord` | `DISCORD_BOT_TOKEN` in `~/.hermes/.env` |
+| `slack` | `SLACK_BOT_TOKEN` in `~/.hermes/.env` |
+| `whatsapp` | WhatsApp gateway configured |
+| `signal` | Signal gateway configured |
+| `matrix` | Matrix homeserver configured |
+| `email` | SMTP configured in `config.yaml` |
+| `sms` | SMS provider configured |
+| `local` | Write access to `~/.hermes/cron/output/` |
+| `origin` | Delivers to the chat where the job was created |
+
+Other supported platforms include `mattermost`, `homeassistant`, `dingtalk`, `feishu`, `wecom`, `weixin`, `bluebubbles`, `qqbot`, and `webhook`. You can also target a specific chat with `platform:chat_id` syntax (e.g., `telegram:-1001234567890`).
+
+If delivery fails, the job still runs — it just won't send anywhere. Check `hermes cron list` for updated `last_error` field (if available).
+
+### Check 2: Check `[SILENT]` usage
+
+If your cron job produces no output, delivery is suppressed. If the agent response includes the cron quiet marker `[SILENT]`, delivery is also suppressed. This is intentional for monitoring jobs — but make sure your prompt is not accidentally suppressing everything.
+
+Use prompts like "respond with only [SILENT] if nothing changed." Avoid asking the agent to include `[SILENT]` inside a longer explanation, because cron treats that marker as a suppression signal.
+
+### Check 3: Platform token permissions
+
+Each messaging platform bot needs specific permissions to receive messages. If delivery silently fails:
+
+- **Telegram**: Bot must be an admin in the target group/channel
+- **Discord**: Bot must have permission to send in the target channel
+- **Slack**: Bot must be added to the workspace and have `chat:write` scope
+
+### Check 4: Response wrapping
+
+By default, cron responses are wrapped with a header and footer (`cron.wrap_response: true` in `config.yaml`). Some platforms or integrations may not handle this well. To disable:
+
+```yaml
+cron:
+  wrap_response: false
+```
+
+### Check 5: Relay-fronted platforms (Hermes Cloud / Team Gateway)
+
+When a platform's credential lives in the relay connector (e.g. Slack or Discord fronted by a Team Gateway) rather than in your local `.env`, the **running gateway's live relay adapter is the only sender** — there is no standalone delivery path.
+
+- Scheduled fires work as long as the gateway is running: its ticker owns relay-fronted delivery.
+- A standalone `hermes cron run <id>` automatically **forwards the run to the gateway** over the api_server (`POST /api/jobs/{id}/run`). This requires the `api_server` platform to be enabled with an `API_SERVER_KEY` (16+ characters). A `--prompt` / `cronjob(action='run', prompt=...)` context is forwarded with it and applies to that single fire only.
+- If the gateway is not reachable, the run fails with a "relay-fronted … start the gateway" error instead of the misleading `platform 'slack' not configured/enabled`. Start the gateway and retry.
+
+---
+
+## Skill Loading Failures
+
+### Check 1: Verify skills are installed
+
+```bash
+hermes skills list
+```
+
+Skills must be installed before they can be attached to cron jobs. If a skill is missing, install it first with `hermes skills install <skill-name>` or via `/skills` in the CLI.
+
+### Check 2: Check skill name vs. skill folder name
+
+Skill names are case-sensitive and must match the installed skill's folder name. If your job specifies `ai-funding-report` but the skill folder is `ai-funding-daily-report`, confirm the exact name from `hermes skills list`.
+
+### Check 3: Skills that require interactive tools
+
+Cron jobs run with the `cronjob`, `messaging`, and `clarify` toolsets disabled. This prevents recursive cron creation, direct message sending (delivery is handled by the scheduler), and interactive prompts. If a skill relies on these toolsets, it won't work in a cron context.
+
+Check the skill's documentation to confirm it works in non-interactive (headless) mode.
+
+### Check 4: Multi-skill ordering
+
+When using multiple skills, they load in order. If Skill A depends on context from Skill B, make sure B loads first:
+
+```bash
+/cron add "0 9 * * *" "..." --skill context-skill --skill target-skill
+```
+
+In this example, `context-skill` loads before `target-skill`.
+
+---
+
+## Job Errors and Failures
+
+### Check 1: Review recent job output
+
+If a job ran and failed, you may see error context in:
+
+1. The chat where the job delivers (if delivery succeeded)
+2. `~/.hermes/logs/agent.log` for scheduler messages (or `errors.log` for warnings)
+3. The job's `last_run` metadata via `hermes cron list`
+
+### Check 2: Common error patterns
+
+**"No such file or directory" for scripts**
+The `script` path must be an absolute path (or relative to the Hermes config directory). Verify:
+```bash
+ls ~/.hermes/scripts/your-script.py   # Must exist
+hermes cron edit <job_id> --script ~/.hermes/scripts/your-script.py
+```
+
+**"Skill not found" at job execution**
+The skill must be installed on the machine running the scheduler. If you move between machines, skills don't automatically sync — reinstall them with `hermes skills install <skill-name>`.
+
+**Job runs but delivers nothing**
+Likely a delivery target issue (see Delivery Failures above), no output, or a response containing the cron quiet marker `[SILENT]`.
+
+**Job hangs or times out**
+The scheduler uses an inactivity-based timeout (default 600s, configurable via `HERMES_CRON_TIMEOUT` env var, `0` for unlimited). The agent can run as long as it's actively calling tools — the timer only fires after sustained inactivity. Long-running jobs should use scripts to handle data collection and deliver only the result.
+
+### Check 3: Lock contention
+
+The scheduler uses file-based locking to prevent overlapping ticks. If two gateway instances are running (or a CLI session conflicts with a gateway), jobs may be delayed or skipped.
+
+Kill duplicate gateway processes:
+```bash
+ps aux | grep hermes
+# Kill duplicate processes, keep only one
+```
+
+### Check 4: Permissions on jobs.json
+
+Jobs are stored in `~/.hermes/cron/jobs.json`. If this file is not readable/writable by your user, the scheduler will fail silently:
+
+```bash
+ls -la ~/.hermes/cron/jobs.json
+chmod 600 ~/.hermes/cron/jobs.json   # Your user should own it
+```
+
+---
+
+## Performance Issues
+
+### Slow job startup
+
+Each cron job creates a fresh AIAgent session, which may involve provider authentication and model loading. For time-sensitive schedules, add buffer time (e.g., `0 8 * * *` instead of `0 9 * * *`).
+
+### Too many overlapping jobs
+
+The scheduler executes jobs sequentially within each tick. If multiple jobs are due at the same time, they run one after another. Consider staggering schedules (e.g., `0 9 * * *` and `5 9 * * *` instead of both at `0 9 * * *`) to avoid delays.
+
+### Large script output
+
+Scripts that dump megabytes of output will slow down the agent and may hit token limits. Filter/summarize at the script level — emit only what the agent needs to reason about.
+
+---
+
+## Diagnostic Commands
+
+```bash
+hermes cron list                    # Show all jobs, states, next_run times
+hermes cron run <job_id>            # Schedule for next tick (for testing)
+hermes cron edit <job_id>           # Fix configuration issues
+hermes logs                         # View recent Hermes logs
+hermes skills list                  # Verify installed skills
+```
+
+---
+
+## Getting More Help
+
+If you've worked through this guide and the issue persists:
+
+1. Run the job with `hermes cron run <job_id>` (fires on next gateway tick) and watch for errors in the chat output
+2. Check `~/.hermes/logs/agent.log` for scheduler messages and `~/.hermes/logs/errors.log` for warnings
+3. Open an issue at [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) with:
+   - The job ID and schedule
+   - The delivery target
+   - What you expected vs. what happened
+   - Relevant error messages from the logs
+
+---
+
+*For the complete cron reference, see [Automate Anything with Cron](/guides/automate-with-cron) and [Scheduled Tasks (Cron)](/user-guide/features/cron).*