openclaw-scheduler 0.2.0

package/INSTALL.md

@@ -0,0 +1,364 @@
+# Installing OpenClaw Scheduler on macOS
+
+Step-by-step guide to deploy the scheduler on a macOS OpenClaw instance.
+
+If you just want the fastest path to a working local install, start with the npm-first flow and [Five-Minute Setup in the README](README.md#five-minute-setup). This document is the full host deployment guide.
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| macOS or Linux | Tested on macOS arm64 |
+| Node.js >= 20 | `node --version` |
+| OpenClaw gateway running | With auth token |
+| Git or SCP access | To clone/copy the repo |
+
+---
+
+## Step 1: Install Scheduler Files
+
+```bash
+cd ~/.openclaw
+git clone https://github.com/amittell/openclaw-scheduler.git scheduler
+cd scheduler
+```
+
+Or copy from an existing host:
+```bash
+scp -r user@source-host:~/.openclaw/scheduler ~/.openclaw/scheduler
+```
+
+Or npm-first install (no git clone):
+```bash
+mkdir -p ~/.openclaw/scheduler
+npm install --prefix ~/.openclaw/scheduler openclaw-scheduler@latest
+npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- help
+```
+
+Runtime state for npm installs defaults to `~/.openclaw/scheduler/`, not the package directory under `node_modules/`.
+
+---
+
+## Step 2: Install Dependencies
+
+If you used the npm-first install path in Step 1, dependencies are already installed; skip to Step 3.
+
+```bash
+cd ~/.openclaw/scheduler
+npm install
+```
+
+Installs `better-sqlite3` (native, compiles for your arch) and `croner`.
+
+If `better-sqlite3` fails: `xcode-select --install` (macOS).
+
+If Node changes later under this checkout, rebuild the native module before restarting the scheduler:
+
+```bash
+cd ~/.openclaw/scheduler
+npm rebuild better-sqlite3
+```
+
+Typical cases:
+- `brew upgrade node` on macOS
+- switching major Node versions with `nvm`, `fnm`, or `asdf`
+- distro package upgrades that replace the Node binary
+
+On Linux, install build deps first:
+```bash
+sudo apt install build-essential python3   # Ubuntu/Debian
+sudo dnf install gcc gcc-c++ make python3   # Fedora/RHEL
+```
+
+---
+
+## Step 2.5: Fix macOS shell PATH and completions
+
+If you use `zsh` on macOS, make sure Homebrew is available to non-interactive shells too.
+
+This matters for commands like:
+- `ssh host 'node cli.js status'`
+- remote admin scripts
+- one-off maintenance commands that do not run inside an interactive terminal
+
+`~/.zprofile` is not enough for that case. Put the minimal PATH bootstrap in `~/.zshenv`:
+
+```zsh
+# ~/.zshenv — sourced by all zsh instances, including non-interactive SSH commands
+if [ -x /opt/homebrew/bin/brew ]; then
+  eval "$(/opt/homebrew/bin/brew shellenv)"
+fi
+
+export PATH="$HOME/.local/bin:$HOME/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+```
+
+If you load OpenClaw completions in `~/.zshrc`, run `compinit` before sourcing them:
+
+```zsh
+autoload -Uz compinit
+compinit
+
+if [ -f "$HOME/.openclaw/completions/openclaw.zsh" ]; then
+  source "$HOME/.openclaw/completions/openclaw.zsh"
+fi
+```
+
+Avoid version-pinned Node PATH entries like `/opt/homebrew/opt/node@22/bin`. Use `/opt/homebrew/bin/node` instead so normal `brew upgrade node` keeps working.
+
+Verify:
+
+```bash
+ssh "$HOST" 'command -v node && node -v'
+```
+
+---
+
+## Step 3: Run Tests
+
+```bash
+SCHEDULER_DB=:memory: node test.js
+```
+
+**All tests must pass before proceeding.**
+
+---
+
+## Step 4: Enable Chat Completions on Gateway
+
+```bash
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+openclaw gateway restart
+```
+
+Verify:
+```bash
+curl -s -o /dev/null -w "%{http_code}" \
+  -X POST \
+  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openclaw:main","messages":[{"role":"user","content":"reply OK"}]}' \
+  http://127.0.0.1:18789/v1/chat/completions
+```
+
+Expected: `200`
+
+---
+
+## Step 5: Migrate Jobs from OC Cron
+
+```bash
+cd ~/.openclaw/scheduler
+node migrate.js
+```
+
+This imports jobs from `~/.openclaw/cron/jobs.json` → SQLite, converting schedule formats:
+- `cron` → direct expression
+- `every` → approximate cron (e.g., 30min → `*/30 * * * *`)
+- `at` → one-shot with `delete_after_run=true`
+
+Good default approach:
+- if the old job was just a script, keep it as a `shell` job
+- if the old job was really “run a prompt on a schedule,” rewrite it as an `isolated` job
+- if two jobs depended on manual ordering, convert them into a parent/child chain instead of two independent schedules
+
+For copy-paste examples, see [Starter Recipes in the README](README.md#starter-recipes) and [Common Migrations](README.md#common-migrations).
+
+Verify:
+```bash
+node cli.js jobs list
+node cli.js status
+```
+
+---
+
+## Step 6: Disable OC Built-in Cron
+
+```bash
+openclaw cron list
+# For each enabled job:
+openclaw cron edit <job-id> --disable
+openclaw config set cron.enabled false
+```
+
+Also set `OPENCLAW_SKIP_CRON=1` in your OpenClaw gateway service environment (launchctl/systemd/pm2), then restart the gateway.
+
+Verify: `openclaw cron list` shows no enabled jobs (or "No cron jobs").
+
+---
+
+## Step 7: Disable OC Heartbeat
+
+```bash
+openclaw config set agents.defaults.heartbeat.every "0m"
+# If you have per-agent heartbeat overrides, set/remove those too:
+# agents.list[].heartbeat.every = "0m"
+openclaw gateway restart
+```
+
+---
+
+## Step 8: Choose a macOS launchd mode
+
+OpenClaw Scheduler supports both common macOS service styles:
+
+- **LaunchAgent**: best for a personal Mac that auto-logs in and should run the scheduler inside your user session
+- **LaunchDaemon**: best for a headless Mac or for starting before login
+
+The simplest path is to let the setup wizard install the launchd plist for you:
+
+```bash
+cd ~/.openclaw/scheduler
+node setup.mjs --service-mode agent
+# or:
+node setup.mjs --service-mode daemon
+```
+
+If you installed from npm:
+
+```bash
+npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- setup --service-mode agent
+# or:
+npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- setup --service-mode daemon
+```
+
+What each mode does:
+
+- `agent` writes `~/Library/LaunchAgents/ai.openclaw.scheduler.plist` and bootstraps `gui/$UID/ai.openclaw.scheduler`
+- `daemon` writes `/Library/LaunchDaemons/ai.openclaw.scheduler.plist` and bootstraps `system/ai.openclaw.scheduler`
+
+Verify the mode you chose:
+
+```bash
+# LaunchAgent
+launchctl print gui/$UID/ai.openclaw.scheduler
+
+# LaunchDaemon
+sudo launchctl print system/ai.openclaw.scheduler
+
+# Either mode
+sleep 5 && tail -5 /tmp/openclaw-scheduler.log
+```
+
+---
+
+## Step 9: Smoke Tests
+
+> **Note:** These smoke test commands use direct file imports and are for the git-clone install path. For npm installs, use `openclaw-scheduler` CLI commands instead.
+
+### Isolated dispatch
+```bash
+cd ~/.openclaw/scheduler
+node --input-type=module -e "
+import { initDb, getDb } from './db.js';
+import { createJob } from './jobs.js';
+initDb();
+const job = createJob({
+  name: 'Smoke Test',
+  schedule_cron: '0 0 31 2 *',
+  payload_message: 'Reply with exactly: SCHEDULER_OK',
+  delivery_mode: 'none',
+  delete_after_run: true,
+  origin: 'system',
+  run_timeout_ms: 300000,
+});
+getDb().prepare(\"UPDATE jobs SET next_run_at = datetime('now', '-1 second') WHERE id = ?\").run(job.id);
+console.log('Created smoke test:', job.id);
+"
+sleep 20 && tail -10 /tmp/openclaw-scheduler.log
+```
+
+Look for: `Dispatching: Smoke Test` → `Completed: Smoke Test`
+
+### Telegram delivery
+```bash
+node --input-type=module -e "
+import { initDb, getDb } from './db.js';
+import { createJob } from './jobs.js';
+initDb();
+const job = createJob({
+  name: 'Telegram Test',
+  schedule_cron: '0 0 31 2 *',
+  payload_message: 'Confirm scheduler is working. Send a brief greeting.',
+  delivery_mode: 'announce',
+  delivery_channel: 'telegram',
+  delivery_to: 'YOUR_CHAT_ID',
+  delete_after_run: true,
+  origin: 'system',
+  run_timeout_ms: 300000,
+});
+getDb().prepare(\"UPDATE jobs SET next_run_at = datetime('now', '-1 second') WHERE id = ?\").run(job.id);
+console.log('Created Telegram test:', job.id);
+"
+```
+
+You should receive a Telegram message within 30 seconds.
+
+---
+
+## Step 10: Review Migrated Jobs
+
+```bash
+node cli.js jobs list
+```
+
+- Disable expired one-shot jobs: `node cli.js jobs disable <id>`
+- Delete unwanted jobs: `node cli.js jobs delete <id>`
+- Adjust timeouts: `node cli.js jobs update <id> '{"run_timeout_ms":600000}'`
+- Verify cron conversions are correct for `every`-based schedules
+
+---
+
+## Step 11: Verify First Real Job
+
+Wait for the next scheduled job and confirm:
+```bash
+tail -f /tmp/openclaw-scheduler.log
+# Or after it fires:
+node cli.js runs list <job-id>
+```
+
+---
+
+## Rollback
+
+If anything goes wrong:
+
+```bash
+# 1. Stop scheduler
+launchctl bootout gui/$UID/ai.openclaw.scheduler     # if using LaunchAgent
+sudo launchctl bootout system/ai.openclaw.scheduler  # if using LaunchDaemon
+
+# 2. Re-enable OC cron
+openclaw cron edit <job-id> --enable  # for each job
+openclaw config set cron.enabled true
+# remove OPENCLAW_SKIP_CRON=1 from gateway service env
+
+# 3. Re-enable heartbeat
+openclaw config set agents.defaults.heartbeat.every "5m"
+openclaw gateway restart
+```
+
+For a complete removal (deleting all data), see [UNINSTALL.md](UNINSTALL.md).
+
+---
+
+## Upgrading
+
+Already have the scheduler installed and need to update to a newer version? See [UPGRADING.md](UPGRADING.md).
+
+---
+
+## Validation Checklist
+
+- [ ] `SCHEDULER_DB=:memory: node test.js` -- all passing, 0 failed
+- [ ] `node cli.js status` → shows jobs, 0 stale
+- [ ] `launchctl print gui/$UID/ai.openclaw.scheduler` or `sudo launchctl print system/ai.openclaw.scheduler` → running
+- [ ] Log file has startup lines, no errors
+- [ ] OC cron → all disabled
+- [ ] OC heartbeat → `0m`
+- [ ] Chat completions → 200
+- [ ] Smoke test → dispatched + completed in log
+- [ ] Telegram test → message received
+- [ ] First real job → fires on schedule

package/JOB-QUICK-REF.md

@@ -0,0 +1,222 @@
+# Job Quick Reference
+
+Copy-paste patterns for common scheduler jobs.
+
+## Shell job with cron schedule
+
+```json
+{
+  "name": "Daily Backup",
+  "schedule_cron": "0 2 * * *",
+  "schedule_tz": "America/New_York",
+  "session_target": "shell",
+  "payload_kind": "shellCommand",
+  "payload_message": "/usr/local/bin/backup.sh",
+  "run_timeout_ms": 600000,
+  "delivery_mode": "announce",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID",
+  "origin": "system"
+}
+```
+
+## Agent task (isolated session)
+
+```json
+{
+  "name": "Morning Briefing",
+  "schedule_cron": "0 8 * * 1-5",
+  "schedule_tz": "America/New_York",
+  "session_target": "isolated",
+  "agent_id": "main",
+  "payload_kind": "systemEvent",
+  "payload_message": "Prepare the morning briefing with overnight alerts.",
+  "run_timeout_ms": 300000,
+  "delivery_mode": "announce-always",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID",
+  "origin": "YOUR_CHAT_ID"
+}
+```
+
+## Main session event (inject into persistent session)
+
+```json
+{
+  "name": "Pending Acks Check",
+  "schedule_cron": "*/30 * * * *",
+  "session_target": "main",
+  "agent_id": "main",
+  "payload_kind": "systemEvent",
+  "payload_message": "Check for unacknowledged messages and follow up.",
+  "run_timeout_ms": 120000,
+  "delivery_mode": "none",
+  "origin": "system"
+}
+```
+
+## One-shot job (run once at a specific time)
+
+```bash
+openclaw-scheduler jobs add '{
+  "name": "Deploy v2.1",
+  "session_target": "shell",
+  "payload_kind": "shellCommand",
+  "payload_message": "deploy.sh v2.1",
+  "run_timeout_ms": 600000,
+  "delivery_mode": "announce-always",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID",
+  "origin": "system"
+}' --at '2026-04-01T14:00:00-04:00'
+```
+
+Or with relative time:
+
+```bash
+openclaw-scheduler jobs add '{ ... }' --in '30m'
+openclaw-scheduler jobs add '{ ... }' --in '2h'
+```
+
+## Workflow chain (parent triggers child)
+
+```json
+[
+  {
+    "name": "Nightly Score Capture",
+    "schedule_cron": "30 0 * * *",
+    "session_target": "shell",
+    "payload_kind": "shellCommand",
+    "payload_message": "capture-scores.sh",
+    "run_timeout_ms": 300000,
+    "delivery_mode": "announce",
+    "delivery_channel": "telegram",
+    "delivery_to": "YOUR_CHAT_ID",
+    "origin": "system"
+  },
+  {
+    "name": "Auto-Settle Bets",
+    "parent_id": "<SCORE_CAPTURE_JOB_ID>",
+    "trigger_on": "success",
+    "session_target": "shell",
+    "payload_kind": "shellCommand",
+    "payload_message": "settle-bets.sh",
+    "run_timeout_ms": 300000,
+    "delivery_mode": "announce",
+    "delivery_channel": "telegram",
+    "delivery_to": "YOUR_CHAT_ID",
+    "origin": "system"
+  }
+]
+```
+
+Create parent first, then child with `parent_id` set to the parent's ID.
+
+## Job with retries
+
+```json
+{
+  "name": "API Sync",
+  "schedule_cron": "0 */4 * * *",
+  "session_target": "shell",
+  "payload_kind": "shellCommand",
+  "payload_message": "sync-api.sh",
+  "run_timeout_ms": 120000,
+  "max_retries": 3,
+  "delivery_mode": "announce",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID",
+  "origin": "system"
+}
+```
+
+## Job with approval gate
+
+```json
+{
+  "name": "Production Deploy",
+  "session_target": "shell",
+  "payload_kind": "shellCommand",
+  "payload_message": "deploy-prod.sh",
+  "run_timeout_ms": 600000,
+  "approval_required": true,
+  "approval_timeout_s": 3600,
+  "delivery_mode": "announce-always",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID",
+  "origin": "system"
+}
+```
+
+Approve or reject:
+
+```bash
+openclaw-scheduler jobs approve <id>
+openclaw-scheduler jobs reject <id> "not ready yet"
+```
+
+## Multi-agent job (target a specific agent)
+
+```json
+{
+  "name": "Ops Agent Task",
+  "schedule_cron": "0 9 * * *",
+  "session_target": "isolated",
+  "agent_id": "ops",
+  "payload_kind": "systemEvent",
+  "payload_message": "Check infrastructure health.",
+  "run_timeout_ms": 300000,
+  "delivery_mode": "announce-always",
+  "delivery_channel": "telegram",
+  "delivery_to": "YOUR_CHAT_ID",
+  "origin": "YOUR_CHAT_ID"
+}
+```
+
+## Trigger conditions
+
+```json
+{ "trigger_on": "success" }
+{ "trigger_on": "failure" }
+{ "trigger_on": "complete" }
+{ "trigger_on": "success", "trigger_condition": "contains:DEPLOYED" }
+{ "trigger_on": "success", "trigger_condition": "regex:status:\\s*healthy" }
+{ "trigger_on": "success", "trigger_delay_s": 60 }
+```
+
+## Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Job name |
+| `schedule_cron` | string | yes* | Cron expression (5-field). *Not needed for triggered children or at-jobs |
+| `schedule_tz` | string | no | Timezone (default: UTC) |
+| `session_target` | string | yes | `shell`, `isolated`, or `main` |
+| `agent_id` | string | no | Target agent (default: `main`) |
+| `payload_kind` | string | yes | `shellCommand`, `systemEvent`, or `agentTurn` |
+| `payload_message` | string | yes | Shell command or agent prompt |
+| `payload_model` | string | no | Model override for agent tasks |
+| `run_timeout_ms` | integer | yes | Max run duration in ms (no default) |
+| `delivery_mode` | string | no | `none`, `announce`, `announce-always` |
+| `delivery_channel` | string | no | Channel name (telegram, discord, etc.) |
+| `delivery_to` | string | no | Chat ID, channel ID, or @alias |
+| `origin` | string | yes (root jobs only; child jobs inherit) | Source chat ID or `system` |
+| `parent_id` | string | no | Parent job ID (for chains) |
+| `trigger_on` | string | no | `success`, `failure`, `complete` |
+| `trigger_condition` | string | no | `contains:X` or `regex:X` |
+| `trigger_delay_s` | integer | no | Delay before trigger fires |
+| `max_retries` | integer | no | Retry count on failure |
+| `overlap_policy` | string | no | `allow`, `skip`, `queue` |
+| `approval_required` | boolean | no | Require HITL approval |
+| `approval_timeout_s` | integer | no | Approval window in seconds |
+| `enabled` | integer | no | 1 (enabled) or 0 (disabled) |
+
+For the full field list, run `openclaw-scheduler schema jobs`.
+
+## Delivery channels
+
+All channels supported by the OpenClaw gateway work with the scheduler:
+Telegram, Discord, WhatsApp, Signal, iMessage, and Slack.
+
+Examples in this document use `telegram` as the delivery_channel.
+Replace with your channel of choice.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.