openclaw-scheduler 0.2.0

package/INSTALL-LINUX.md

@@ -0,0 +1,419 @@
+# Installing OpenClaw Scheduler on Linux
+
+Step-by-step guide to deploy the scheduler on a Linux host running OpenClaw.
+
+> **macOS?** See [INSTALL.md](INSTALL.md).
+> **Windows?** See [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md).
+> **Need examples or migration help?** See [Starter Recipes in the README](README.md#starter-recipes) and [Common Migrations](README.md#common-migrations).
+
+---
+
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| Node.js >= 20 | Install via [nvm](https://github.com/nvm-sh/nvm) or [NodeSource](https://github.com/nodesource/distributions) |
+| build-essential | `sudo apt install build-essential python3` — required for `better-sqlite3` native compile |
+| OpenClaw gateway running | With auth token |
+| Git | `sudo apt install git` |
+| systemd (user units) | Ubuntu 18.04+, Debian 10+, Fedora, Arch — standard |
+
+---
+
+## 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 Build Dependencies and Node Modules
+
+If you used the npm-first install path in Step 1, dependencies are already installed; skip to Step 3.
+
+Install system build tools first — `better-sqlite3` compiles a native addon and needs them:
+
+```bash
+# Ubuntu/Debian
+sudo apt install build-essential python3
+
+# Fedora/RHEL
+sudo dnf install gcc gcc-c++ make python3
+
+# Arch
+sudo pacman -S base-devel python
+```
+
+Then install Node dependencies:
+
+```bash
+cd ~/.openclaw/scheduler
+npm install
+```
+
+If `better-sqlite3` still fails, check that `node-gyp` can find Python:
+```bash
+node -e "require('better-sqlite3')" && echo "OK"
+```
+
+If the host's Node runtime changes later, rebuild the native binding before restarting the scheduler:
+```bash
+cd ~/.openclaw/scheduler
+npm rebuild better-sqlite3
+```
+
+---
+
+## 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`
+
+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 (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: Install systemd User Service
+
+The scheduler runs as a **systemd user service** — it runs under your user account, starts on login (and optionally on boot via linger), and restarts automatically on crash.
+
+```bash
+# Create user service directory
+mkdir -p ~/.config/systemd/user/
+
+# Create the service file
+cat > ~/.config/systemd/user/openclaw-scheduler.service <<'EOF'
+[Unit]
+Description=OpenClaw Scheduler
+Documentation=https://github.com/amittell/openclaw-scheduler
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/.openclaw/scheduler
+ExecStart=/usr/bin/node --no-warnings %h/.openclaw/scheduler/dispatcher.js
+Environment=OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
+Environment=OPENCLAW_GATEWAY_TOKEN=YOUR_GATEWAY_TOKEN
+Environment=SCHEDULER_DB=%h/.openclaw/scheduler/scheduler.db
+Environment=SCHEDULER_TICK_MS=10000
+Environment=SCHEDULER_STALE_THRESHOLD_S=90
+# Uncomment to enable verbose logging:
+# Environment=SCHEDULER_DEBUG=1
+Restart=always
+RestartSec=5
+StandardOutput=append:/tmp/openclaw-scheduler.log
+StandardError=append:/tmp/openclaw-scheduler.log
+
+[Install]
+WantedBy=default.target
+EOF
+
+# Edit the service file if needed
+nano ~/.config/systemd/user/openclaw-scheduler.service
+```
+
+**Required edits in the service file:**
+
+1. Replace `YOUR_GATEWAY_TOKEN` with your actual OpenClaw gateway token
+2. Verify `ExecStart` uses the correct `node` path:
+   ```bash
+   which node   # check where node is — might be /usr/local/bin/node or ~/.nvm/versions/node/.../bin/node
+   ```
+   If node is not at `/usr/bin/node`, update the `ExecStart` line:
+   ```ini
+   ExecStart=/home/youruser/.nvm/versions/node/vX.Y.Z/bin/node --no-warnings /home/youruser/.openclaw/scheduler/dispatcher.js
+   ```
+   Replace `vX.Y.Z` with your installed Node.js version (run `node --version` to check).
+   Note: `%h` expands to your home directory in systemd user units.
+
+**Enable and start:**
+
+```bash
+# Reload systemd to pick up the new service
+systemctl --user daemon-reload
+
+# Enable autostart
+systemctl --user enable openclaw-scheduler
+
+# Start now
+systemctl --user start openclaw-scheduler
+
+# Verify
+systemctl --user status openclaw-scheduler
+journalctl --user -u openclaw-scheduler -f   # live logs (Ctrl-C to exit)
+```
+
+**Run without an active login session (important for servers):**
+
+By default, systemd user services stop when you log out. To keep the scheduler running 24/7 even without an active session:
+
+```bash
+loginctl enable-linger $USER
+```
+
+This is the Linux equivalent of macOS LaunchDaemon `RunAtLoad: true` + `KeepAlive: true`.
+
+---
+
+## 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
+
+Shell jobs on Linux use `/bin/bash` by default. Override with `SCHEDULER_SHELL` env var in the service file.
+
+```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`
+
+### Shell job smoke test
+
+```bash
+node --input-type=module -e "
+import { initDb, getDb } from './db.js';
+import { createJob } from './jobs.js';
+initDb();
+const job = createJob({
+  name: 'Shell Smoke Test',
+  schedule_cron: '0 0 31 2 *',
+  session_target: 'shell',
+  payload_message: 'echo scheduler_shell_ok',
+  delivery_mode: 'announce-always',
+  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 shell smoke test:', job.id);
+"
+sleep 15 && node cli.js runs list
+```
+
+### 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
+# Watch live
+journalctl --user -u openclaw-scheduler -f
+tail -f /tmp/openclaw-scheduler.log
+
+# After it fires:
+node cli.js runs list <job-id>
+```
+
+---
+
+## Service Management
+
+```bash
+# Start / Stop / Restart
+systemctl --user start openclaw-scheduler
+systemctl --user stop openclaw-scheduler
+systemctl --user restart openclaw-scheduler
+
+# Status
+systemctl --user status openclaw-scheduler
+
+# Logs
+journalctl --user -u openclaw-scheduler -f
+tail -f /tmp/openclaw-scheduler.log
+
+# Disable autostart (won't start on next login)
+systemctl --user disable openclaw-scheduler
+
+# Quick health
+node cli.js status
+```
+
+---
+
+## Rollback
+
+If anything goes wrong:
+
+```bash
+# 1. Stop and disable service
+systemctl --user stop openclaw-scheduler
+systemctl --user disable openclaw-scheduler
+rm ~/.config/systemd/user/openclaw-scheduler.service
+systemctl --user daemon-reload
+
+# 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).
+
+---
+
+## Validation Checklist
+
+- [ ] `SCHEDULER_DB=:memory: node test.js` -- all passing, 0 failed
+- [ ] `node cli.js status` → shows jobs, 0 stale
+- [ ] `systemctl --user status openclaw-scheduler` → active (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
+- [ ] `loginctl enable-linger $USER` → confirmed (for always-on servers)
+
+---
+
+## Upgrading
+
+Already have the scheduler installed and need to update to a newer version? See [UPGRADING.md](UPGRADING.md).

package/INSTALL-WINDOWS.md

@@ -0,0 +1,305 @@
+# Installing OpenClaw Scheduler on Windows
+
+> **TL;DR:** Use WSL2. It's faster to set up, fully supported, and eliminates every Windows-specific limitation listed in this guide.
+>
+> **Need examples or migration help?** See [Starter Recipes in the README](README.md#starter-recipes) and [Common Migrations](README.md#common-migrations).
+
+---
+
+## Option A: WSL2 (Strongly Recommended)
+
+If you're running OpenClaw in WSL2, follow the Linux guide: **[INSTALL-LINUX.md](INSTALL-LINUX.md)**
+
+WSL2 gives you a full Linux environment with:
+- **systemd support** — Ubuntu 22.04+ in WSL2 ships with systemd enabled by default
+- Full bash/zsh shell job compatibility
+- No path separator issues, no `.bat` script constraints
+- Identical behavior to a native Linux install
+
+To enable systemd in WSL2 (Ubuntu 22.04+), add to `/etc/wsl.conf`:
+```ini
+[boot]
+systemd=true
+```
+
+Then restart WSL: `wsl --shutdown` from PowerShell, reopen your terminal.
+
+---
+
+## Option B: PM2 (Native Windows)
+
+Use this path only if you can't use WSL2 — for example, if OpenClaw itself is running natively on Windows (not in WSL2).
+
+> ⚠️ **Shell job limitations apply.** See [Shell Jobs on Windows](#shell-jobs-on-windows) below.
+
+---
+
+### Prerequisites
+
+| Requirement | Install |
+|-------------|---------|
+| Node.js >= 20 | [nodejs.org](https://nodejs.org) -- use the LTS installer |
+| pm2 | `npm install -g pm2` |
+| OpenClaw gateway | Must be running with a valid auth token |
+| Git for Windows | [git-scm.com](https://git-scm.com) or use GitHub Desktop |
+
+**Build tools for `better-sqlite3`** (required -- it compiles a native addon):
+
+Option 1 -- Visual Studio Build Tools (recommended):
+1. Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) -- select the **"Desktop development with C++"** workload
+2. Install [Python 3.x](https://python.org) -- check "Add to PATH" during install
+
+Option 2 -- `windows-build-tools` (deprecated, may not work on newer Windows):
+```powershell
+npm install -g windows-build-tools
+```
+
+Verify:
+```powershell
+node -e "require('better-sqlite3')" && echo "OK"
+```
+
+---
+
+### Step 1: Install Scheduler Files
+
+```powershell
+cd $env:USERPROFILE\.openclaw
+git clone https://github.com/amittell/openclaw-scheduler.git scheduler
+cd scheduler
+```
+
+Or npm-first install (no git clone):
+```powershell
+mkdir $env:USERPROFILE\.openclaw\scheduler -Force
+npm install --prefix $env:USERPROFILE\.openclaw\scheduler openclaw-scheduler@latest
+npm exec --prefix $env:USERPROFILE\.openclaw\scheduler openclaw-scheduler -- help
+```
+
+Runtime state for npm installs defaults to `$env:USERPROFILE\.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.
+
+```powershell
+npm install
+```
+
+If `better-sqlite3` fails with a build error, make sure Visual Studio Build Tools and Python are installed (see Prerequisites above), then:
+```powershell
+npm install --build-from-source
+```
+
+If Node changes later on this machine, rebuild the native binding before restarting the scheduler:
+```powershell
+cd $env:USERPROFILE\.openclaw\scheduler
+npm rebuild better-sqlite3
+```
+
+---
+
+### Step 3: Run Tests
+
+```powershell
+$env:SCHEDULER_DB=":memory:"; node test.js
+```
+
+All tests must pass before continuing.
+
+---
+
+### Step 4: Enable Chat Completions on Gateway
+
+```powershell
+openclaw config set gateway.http.endpoints.chatCompletions.enabled true
+openclaw gateway restart
+```
+
+Verify (PowerShell):
+```powershell
+$headers = @{ Authorization = "Bearer YOUR_GATEWAY_TOKEN"; "Content-Type" = "application/json" }
+$body = '{"model":"openclaw:main","messages":[{"role":"user","content":"reply OK"}]}'
+(Invoke-WebRequest -Uri http://127.0.0.1:18789/v1/chat/completions -Method POST -Headers $headers -Body $body).StatusCode
+# Expected: 200
+```
+
+---
+
+### Step 5: Migrate Jobs from OC Cron
+
+```powershell
+node migrate.js
+```
+
+Verify:
+```powershell
+node cli.js jobs list
+node cli.js status
+```
+
+---
+
+### Step 6: Disable OC Built-in Cron and Heartbeat
+
+```powershell
+openclaw cron list
+# For each enabled job:
+openclaw cron edit <job-id> --disable
+openclaw config set cron.enabled false
+
+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
+```
+
+Also set `OPENCLAW_SKIP_CRON=1` in your OpenClaw gateway process environment (service wrapper/PM2 ecosystem), then restart the gateway.
+
+---
+
+### Step 7: Start with PM2
+
+```powershell
+$env:OPENCLAW_GATEWAY_URL = "http://127.0.0.1:18789"
+$env:OPENCLAW_GATEWAY_TOKEN = "YOUR_GATEWAY_TOKEN"
+$env:SCHEDULER_TICK_MS = "10000"
+$env:SCHEDULER_STALE_THRESHOLD_S = "90"
+pm2 start dispatcher.js --name openclaw-scheduler
+
+# Optional verbose logging:
+$env:SCHEDULER_DEBUG = "1"
+pm2 restart openclaw-scheduler --update-env
+
+# Save PM2 process list (persists across restarts)
+pm2 save
+
+# Generate and apply startup hook (run the printed command as Administrator)
+pm2 startup
+```
+
+Verify:
+```powershell
+pm2 status
+pm2 logs openclaw-scheduler --lines 20
+```
+
+---
+
+### Step 8: Smoke Test
+
+> **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.
+
+```powershell
+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);
+"
+Start-Sleep 20; pm2 logs openclaw-scheduler --lines 20
+```
+
+Look for: `Dispatching: Smoke Test` → `Completed: Smoke Test`
+
+---
+
+## PM2 Management
+
+```powershell
+# Status
+pm2 status
+
+# Logs (live)
+pm2 logs openclaw-scheduler
+
+# Restart
+pm2 restart openclaw-scheduler
+
+# Stop
+pm2 stop openclaw-scheduler
+
+# Remove from PM2
+pm2 delete openclaw-scheduler
+```
+
+---
+
+## Shell Jobs on Windows
+
+Shell jobs (`session_target: 'shell'`) use **`cmd.exe`** by default on Windows. Override with:
+
+```
+SCHEDULER_SHELL=powershell.exe
+```
+
+Set this in your PM2 launch command:
+```powershell
+pm2 start dispatcher.js --name openclaw-scheduler `
+  --env SCHEDULER_SHELL=powershell.exe `
+  ...
+```
+
+### Known Limitations (native Windows)
+
+| Limitation | Impact | Fix |
+|------------|--------|-----|
+| Shell is `cmd.exe` by default | Bash scripts won't work | Use `.bat`/`.cmd` or set `SCHEDULER_SHELL=powershell.exe` |
+| No `/bin/bash` or `/bin/zsh` | Can't use Unix shell syntax | Rewrite scripts as PowerShell |
+| Path separators | `\` vs `/` in commands | Use `\\` in `payload_message` strings |
+| Line endings | `.sh` scripts may fail | Save scripts with LF line endings |
+
+**WSL2 eliminates all of these.** If you hit these issues in practice, switching to WSL2 will be faster than working around them.
+
+---
+
+## Rollback
+
+```powershell
+# Stop and remove PM2 process
+pm2 stop openclaw-scheduler
+pm2 delete openclaw-scheduler
+
+# 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 process env
+
+# 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
+
+- [ ] `$env:SCHEDULER_DB=":memory:"; node test.js` -- all passing, 0 failed
+- [ ] `node cli.js status` → shows jobs, 0 stale
+- [ ] `pm2 status` → openclaw-scheduler is `online`
+- [ ] PM2 log has startup lines, no errors
+- [ ] OC cron → all disabled
+- [ ] OC heartbeat → `0m`
+- [ ] Chat completions → 200
+- [ ] Smoke test → dispatched + completed in log
+- [ ] First real job → fires on schedule