openclaw-scheduler 0.2.0

package/dispatch/config.example.json

@@ -0,0 +1,24 @@
+{
+  "_comment": "Copy this to config.json and customize. All fields are optional.",
+
+  "name": "dispatch",
+  "_name": "Branding name used in notifications and log output. e.g. 'my-bot' or 'dispatch'",
+
+  "startupGraceMs": 90000,
+  "_startupGraceMs": "How long after spawn before stuck-detector and auto-resolve kick in (ms). Default: 90000 (90s)",
+
+  "deliver_watcher_ttl_hours": 48,
+  "_deliver_watcher_ttl_hours": "TTL (in hours) for scheduler-registered deliver-watcher jobs. These jobs are transient -- they auto-prune once delivery is confirmed. Default: 48. Lower values (e.g. 4) aggressively prune; higher values (e.g. 72) retain audit history longer.",
+
+  "watchdogIntervalCron": "*/5 * * * *",
+  "_watchdogIntervalCron": "Cron schedule for the built-in watchdog check job. Default: every 5 minutes.",
+
+  "watchdogTimeoutMin": 10,
+  "_watchdogTimeoutMin": "Timeout in minutes for the watchdog check job. Default: 10.",
+
+  "deliverTo": null,
+  "_deliverTo": "Fallback delivery target for untracked-label done calls (e.g. 'telegram:123456789'). Default: null (no fallback delivery).",
+
+  "deliveryChannel": null,
+  "_deliveryChannel": "Fallback delivery channel for untracked-label done calls (e.g. 'telegram'). Default: null."
+}

package/dispatch/deliver-watcher.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# deliver-watcher.sh — Poll dispatch session for a result; exit 0 when done (triggers scheduler delivery)
+# Called by scheduler as a one-shot shell job. Exits non-zero while no result available,
+# causing the scheduler to retry on the next cron tick. On completion, outputs the result
+# and exits 0 — scheduler delivers the output and self-deletes the job.
+#
+# Usage: deliver-watcher.sh <label>
+
+set -euo pipefail
+LABEL="${1:?Usage: deliver-watcher.sh <label>}"
+OPENCLAW_HOME="${OPENCLAW_HOME:-$HOME/.openclaw}"
+NODE_BIN="${NODE_BIN:-$(command -v node)}"
+
+# Resolution order:
+#  1) openclaw-scheduler bin (preferred, if in PATH)
+#  2) DISPATCH_CLI env override
+#  3) dispatch/index.mjs directly
+
+CLI_PATH=""
+USE_BIN=false
+
+if command -v openclaw-scheduler >/dev/null 2>&1; then
+  USE_BIN=true
+elif [ -n "${DISPATCH_CLI:-}" ] && [ -f "$DISPATCH_CLI" ]; then
+  CLI_PATH="$DISPATCH_CLI"
+elif [ -f "$OPENCLAW_HOME/scheduler/dispatch/index.mjs" ]; then
+  CLI_PATH="$OPENCLAW_HOME/scheduler/dispatch/index.mjs"
+else
+  echo "[deliver-watcher] dispatch CLI not found" >&2
+  exit 1
+fi
+
+run_dispatch() {
+  if [ "$USE_BIN" = true ]; then
+    openclaw-scheduler "$@"
+  else
+    "$NODE_BIN" "$CLI_PATH" "$@"
+  fi
+}
+
+# Check if the agent produced a reply (direct check, no idle threshold)
+RESULT_JSON=$(run_dispatch result --label "$LABEL" 2>/dev/null || echo '{}')
+REPLY=$(echo "$RESULT_JSON" | "$NODE_BIN" -e "
+let d='';process.stdin.on('data',c=>d+=c).on('end',()=>{
+  try{const r=JSON.parse(d);console.log((r.lastReply||r.summary||'').trim().slice(0,3000));}catch(e){process.stderr.write('parse error: '+e.message+'\\n');}
+});
+" || echo "")
+
+if [ -n "$REPLY" ]; then
+  # Mark as done in labels.json (best-effort)
+  run_dispatch status --label "$LABEL" >/dev/null 2>&1 || true
+  echo "✅ $LABEL: $REPLY"
+  exit 0
+fi
+
+# No reply yet — retry later
+exit 1

package/dispatch/hooks.mjs

@@ -0,0 +1,171 @@
+/**
+ * dispatch-hooks.mjs -- Lifecycle event emitter
+ *
+ * Fires structured dispatch events to:
+ *   1. Loki (always -- structured log stream for Grafana observability)
+ *   2. DISPATCH_WEBHOOK_URL (optional -- external systems, dashboards, etc.)
+ *   3. Gateway post office (optional -- when opts.deliverTo is set)
+ *
+ * All calls are best-effort and non-blocking. A hook failure never
+ * prevents dispatch from completing.
+ *
+ * Event types:
+ *   dispatch.started   -- job created + queued in scheduler
+ *   dispatch.finished  -- run completed (ok or error)
+ *   dispatch.stuck     -- stuck run detected by detector
+ *   dispatch.cancelled -- run manually cancelled
+ */
+
+import { hostname } from 'os';
+import { sendMessage } from '../messages.js';
+
+const LOKI_URL     = process.env.LOKI_PUSH_URL     || '';
+const WEBHOOK_URL  = process.env.DISPATCH_WEBHOOK_URL || '';
+const HOST         = process.env.DISPATCH_HOST
+  || hostname()
+  || 'unknown-host';
+const TIMEOUT_MS   = 3000;
+
+// -- Loki push -----------------------------------------------
+
+async function lokiPush(event, payload) {
+  if (!LOKI_URL) return; // not configured -- skip silently
+  const ts     = String(Date.now() * 1_000_000); // nanoseconds
+  const logLine = JSON.stringify({ event, host: HOST, ...payload });
+
+  const body = JSON.stringify({
+    streams: [{
+      stream: { service_name: 'dispatch', host: HOST, event },
+      values: [[ts, logLine]],
+    }],
+  });
+
+  const res = await fetch(LOKI_URL, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+    signal:  AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+}
+
+// -- Webhook push --------------------------------------------
+
+async function webhookPush(event, payload) {
+  if (!WEBHOOK_URL) return;
+  const res = await fetch(WEBHOOK_URL, {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body:    JSON.stringify({ event, ts: Date.now(), host: HOST, ...payload }),
+    signal:  AbortSignal.timeout(TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+}
+
+// -- Post-office notification ---------------------------------
+
+/**
+ * Enqueue a completion notification into the messages queue (post office).
+ * The Inbox Consumer drains pending messages and delivers to Telegram.
+ * Used for unregistered-label done signals where no watcher is waiting.
+ *
+ * @param {string} label           - Dispatch label
+ * @param {string} summary         - One-line summary of what was done
+ * @param {string} deliverTo       - Target chat/user ID (stored for reference)
+ * @param {string} [deliveryChannel='telegram'] - Channel to deliver via (stored for reference)
+ */
+async function gatewayNotify(label, summary, deliverTo, deliveryChannel = 'telegram') {
+  try {
+    const body = `✅ [${label}] done -- ${summary}`;
+    await sendMessage({
+      from_agent:  'dispatch',
+      to_agent:    'main',
+      kind:        'result',
+      subject:     label,
+      body,
+      channel:     deliveryChannel,
+      delivery_to: deliverTo,
+    });
+  } catch (e) {
+    process.stderr.write(`[dispatch-hooks] post-office enqueue failed for ${label}: ${e.message}\n`);
+  }
+}
+
+// -- Public API -----------------------------------------------
+
+/**
+ * Emit a dispatch lifecycle event. Best-effort -- never throws.
+ */
+export async function emitEvent(event, payload = {}) {
+  const tasks = [
+    lokiPush(event, payload).catch(e =>
+      process.stderr.write(`[dispatch-hooks] loki failed (${event}): ${e.message}\n`)
+    ),
+    WEBHOOK_URL
+      ? webhookPush(event, payload).catch(e =>
+          process.stderr.write(`[dispatch-hooks] webhook failed (${event}): ${e.message}\n`)
+        )
+      : Promise.resolve(),
+  ];
+  await Promise.allSettled(tasks);
+}
+
+/** Convenience: dispatch.started */
+export function onStarted(opts) {
+  return emitEvent('dispatch.started', {
+    label:      opts.label,
+    job_id:     opts.job_id,
+    run_id:     opts.run_id,
+    agent:      opts.agent,
+    mode:       opts.mode,
+    session_key: opts.session_key || null,
+  });
+}
+
+/**
+ * Convenience: dispatch.finished
+ *
+ * Fires to Loki + webhook (always) and optionally to the gateway post office.
+ *
+ * Extended opts:
+ *   deliverTo       {string}  -- If set, send a completion notification via gateway
+ *   deliveryChannel {string}  -- Channel for delivery (default: 'telegram')
+ *   summary         {string}  -- One-line summary to include in the notification
+ */
+export async function onFinished(opts) {
+  const tasks = [
+    emitEvent('dispatch.finished', {
+      label:       opts.label,
+      job_id:      opts.job_id,
+      run_id:      opts.run_id,
+      agent:       opts.agent,
+      status:      opts.status,        // ok | error | timeout | cancelled
+      duration_ms: opts.duration_ms || null,
+      error:       opts.error || null,
+      session_key: opts.session_key || null,
+    }),
+  ];
+
+  // Optional gateway post-office delivery (used for unregistered-label done signals)
+  if (opts.deliverTo) {
+    const summary = opts.summary || opts.status || 'completed';
+    tasks.push(
+      gatewayNotify(opts.label, summary, opts.deliverTo, opts.deliveryChannel || 'telegram')
+    );
+  }
+
+  return Promise.allSettled(tasks);
+}
+
+/** Convenience: dispatch.stuck */
+export function onStuck(stuckRuns) {
+  return emitEvent('dispatch.stuck', {
+    stuck_count: stuckRuns.length,
+    runs: stuckRuns.map(r => ({
+      run_id:     r.id,
+      job_name:   r.job_name,
+      started_at: r.started_at,
+      age_s:      r.age_s,
+    })),
+  });
+}