better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,247 +0,0 @@
----
-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

@@ -1,235 +0,0 @@
----
-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).*