openclaw-scheduler 0.2.0

package/dispatch-queue.js

@@ -0,0 +1,112 @@
+import { randomUUID } from 'crypto';
+import { getDb } from './db.js';
+import { sqliteNow } from './dispatcher-utils.js';
+
+const VALID_DISPATCH_KINDS = new Set(['manual', 'chain', 'retry']);
+const VALID_DISPATCH_STATUSES = new Set([
+  'pending',
+  'claimed',
+  'awaiting_approval',
+  'done',
+  'cancelled',
+]);
+
+function assertKind(kind) {
+  if (!VALID_DISPATCH_KINDS.has(kind)) {
+    throw new Error(`Invalid dispatch kind "${kind}". Valid: ${[...VALID_DISPATCH_KINDS].join(', ')}`);
+  }
+}
+
+function assertStatus(status) {
+  if (!VALID_DISPATCH_STATUSES.has(status)) {
+    throw new Error(`Invalid dispatch status "${status}". Valid: ${[...VALID_DISPATCH_STATUSES].join(', ')}`);
+  }
+}
+
+export function enqueueDispatch(jobId, opts = {}) {
+  const db = getDb();
+  const id = opts.id || randomUUID();
+  const kind = opts.kind || 'manual';
+  const status = opts.status || 'pending';
+  assertKind(kind);
+  assertStatus(status);
+
+  db.prepare(`
+    INSERT INTO job_dispatch_queue (
+      id, job_id, dispatch_kind, status, scheduled_for,
+      source_run_id, retry_of_run_id, created_at, claimed_at, processed_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'), ?, ?)
+  `).run(
+    id,
+    jobId,
+    kind,
+    status,
+    opts.scheduled_for || sqliteNow(-1000),
+    opts.source_run_id || null,
+    opts.retry_of_run_id || null,
+    opts.claimed_at || null,
+    opts.processed_at || null
+  );
+
+  return getDispatch(id);
+}
+
+export function getDispatch(id) {
+  return getDb().prepare('SELECT * FROM job_dispatch_queue WHERE id = ?').get(id) || null;
+}
+
+export function getDueDispatches(limit = 100) {
+  return getDb().prepare(`
+    SELECT q.*, j.name as job_name
+    FROM job_dispatch_queue q
+    JOIN jobs j ON q.job_id = j.id
+    WHERE q.status = 'pending'
+      AND q.scheduled_for <= datetime('now')
+      AND (j.enabled = 1 OR q.dispatch_kind = 'manual')
+    ORDER BY q.scheduled_for ASC, q.created_at ASC
+    LIMIT ?
+  `).all(limit);
+}
+
+export function claimDispatch(id) {
+  const result = getDb().prepare(`
+    UPDATE job_dispatch_queue
+    SET status = 'claimed',
+        claimed_at = datetime('now')
+    WHERE id = ? AND status = 'pending'
+  `).run(id);
+  return result.changes > 0 ? getDispatch(id) : null;
+}
+
+export function releaseDispatch(id, scheduledFor = null) {
+  const result = getDb().prepare(`
+    UPDATE job_dispatch_queue
+    SET status = 'pending',
+        scheduled_for = COALESCE(?, scheduled_for),
+        claimed_at = NULL
+    WHERE id = ? AND status IN ('claimed', 'awaiting_approval')
+  `).run(scheduledFor, id);
+  return result.changes > 0 ? getDispatch(id) : null;
+}
+
+export function setDispatchStatus(id, status) {
+  assertStatus(status);
+  const processedAt = ['done', 'cancelled'].includes(status) ? sqliteNow() : null;
+  getDb().prepare(`
+    UPDATE job_dispatch_queue
+    SET status = ?,
+        processed_at = COALESCE(?, processed_at)
+    WHERE id = ?
+  `).run(status, processedAt, id);
+  return getDispatch(id);
+}
+
+export function listDispatchesForJob(jobId, limit = 20) {
+  return getDb().prepare(`
+    SELECT *
+    FROM job_dispatch_queue
+    WHERE job_id = ?
+    ORDER BY created_at DESC
+    LIMIT ?
+  `).all(jobId, limit);
+}

package/dispatcher-approvals.js

@@ -0,0 +1,96 @@
+export async function checkApprovals({
+  log,
+  getDb,
+  getTimedOutApprovals,
+  getJob,
+  resolveApproval,
+  dispatchJob,
+  getDispatch,
+  setDispatchStatus,
+}) {
+  try {
+    const timedOut = getTimedOutApprovals();
+    for (const approval of timedOut) {
+      const job = getJob(approval.job_id);
+      if (!job) continue;
+
+      if (approval.approval_auto === 'approve' || job.approval_auto === 'approve') {
+        resolveApproval(approval.id, 'approved', 'timeout');
+        getDb().prepare(`
+          UPDATE approvals
+          SET status = 'dispatched',
+              notes = COALESCE(notes, 'Auto-approved and dispatched by scheduler')
+          WHERE id = ? AND status = 'approved'
+        `).run(approval.id);
+        log('info', `Approval auto-approved (timeout): ${approval.job_name || job.name}`, { approvalId: approval.id });
+        if (approval.run_id) {
+          getDb().prepare(`
+            UPDATE runs
+            SET status = 'approved',
+                finished_at = datetime('now'),
+                duration_ms = CAST((julianday('now') - julianday(started_at)) * 86400000 AS INTEGER),
+                summary = COALESCE(summary, 'Approval granted (timeout auto-approve)')
+            WHERE id = ? AND status IN ('awaiting_approval', 'pending')
+          `).run(approval.run_id);
+        }
+        await dispatchJob(job, {
+          approvalBypass: true,
+          dispatchRecord: approval.dispatch_queue_id ? getDispatch(approval.dispatch_queue_id) : null,
+        });
+      } else {
+        resolveApproval(approval.id, 'timed_out', 'timeout');
+        if (approval.dispatch_queue_id) setDispatchStatus(approval.dispatch_queue_id, 'cancelled');
+        if (approval.run_id) {
+          getDb().prepare(`
+            UPDATE runs
+            SET status = 'cancelled', finished_at = datetime('now')
+            WHERE id = ? AND status = 'awaiting_approval'
+          `).run(approval.run_id);
+        }
+        log('info', `Approval timed out (rejected): ${approval.job_name || job.name}`, { approvalId: approval.id });
+      }
+    }
+  } catch (err) {
+    log('error', `Approval timeout check error: ${err.message}`);
+  }
+
+  try {
+    const db = getDb();
+    const approved = db.prepare(`
+      SELECT a.*, j.name as job_name
+      FROM approvals a
+      JOIN jobs j ON a.job_id = j.id
+      LEFT JOIN runs r ON a.run_id = r.id
+      WHERE a.status = 'approved'
+        AND (a.run_id IS NULL OR r.status IN ('awaiting_approval', 'pending'))
+    `).all();
+
+    for (const approval of approved) {
+      const job = getJob(approval.job_id);
+      if (!job) continue;
+      if (approval.run_id) {
+        db.prepare(`
+          UPDATE runs
+          SET status = 'approved',
+              finished_at = datetime('now'),
+              duration_ms = CAST((julianday('now') - julianday(started_at)) * 86400000 AS INTEGER),
+              summary = COALESCE(summary, 'Approved by operator')
+          WHERE id = ? AND status IN ('awaiting_approval', 'pending')
+        `).run(approval.run_id);
+      }
+      log('info', `Dispatching approved job: ${approval.job_name}`, { approvalId: approval.id });
+      await dispatchJob(job, {
+        approvalBypass: true,
+        dispatchRecord: approval.dispatch_queue_id ? getDispatch(approval.dispatch_queue_id) : null,
+      });
+      db.prepare(`
+        UPDATE approvals
+        SET status = 'dispatched',
+            notes = COALESCE(notes, 'Approved and dispatched by scheduler')
+        WHERE id = ? AND status = 'approved'
+      `).run(approval.id);
+    }
+  } catch (err) {
+    log('error', `Approval dispatch error: ${err.message}`);
+  }
+}

package/dispatcher-delivery.js

@@ -0,0 +1,43 @@
+import { sendMessage } from './messages.js';
+
+export function createDeliveryHelpers({ log, resolveDeliveryAlias }) {
+  function resolveAlias(target) {
+    if (!target) return null;
+    return resolveDeliveryAlias(target);
+  }
+
+  async function handleDelivery(job, content) {
+    if (!['announce', 'announce-always'].includes(job.delivery_mode)) return;
+    if (!job.delivery_channel && !job.delivery_to) return;
+
+    let channel = job.delivery_channel;
+    let target = job.delivery_to;
+
+    if (target) {
+      const resolved = resolveAlias(target);
+      if (resolved) {
+        channel = resolved.channel;
+        target = resolved.target;
+        log('info', `Resolved alias '${job.delivery_to}' -> ${channel}/${target}`);
+      }
+    }
+
+    try {
+      const subject = (job.name || '').slice(0, 100);
+      sendMessage({
+        from_agent: 'scheduler',
+        to_agent:   'main',
+        kind:       'result',
+        subject,
+        body:       content,
+        channel,
+        delivery_to: target,
+      });
+      log('info', `Enqueued: ${job.name}`, { channel, to: target });
+    } catch (err) {
+      log('error', `Delivery enqueue failed: ${job.name}: ${err.message}`);
+    }
+  }
+
+  return { handleDelivery };
+}

package/dispatcher-maintenance.js

@@ -0,0 +1,242 @@
+export async function checkRunHealth({
+  log,
+  getDb,
+  getRunningRuns,
+  getStaleRuns,
+  getTimedOutRuns,
+  finishRun,
+  getJob,
+  updateJobAfterRun,
+  handleDelivery,
+  dequeueJob,
+  shouldRetry,
+  scheduleRetry,
+  staleThresholdSeconds,
+}) {
+  const runningRuns = getRunningRuns();
+  if (runningRuns.length === 0) return;
+
+  log('debug', `Checking ${runningRuns.length} running run(s)`);
+
+  const staleRuns = getStaleRuns(staleThresholdSeconds);
+  for (const run of staleRuns) {
+    log('warn', `Stale run: ${run.job_name}`, { runId: run.id });
+    finishRun(run.id, 'timeout', {
+      error_message: `No activity for ${staleThresholdSeconds}s`,
+    });
+    const job = getJob(run.job_id);
+    if (!job) continue;
+    if (shouldRetry(job, run.id)) {
+      const retry = scheduleRetry(job, run.id, { lastStatus: 'timeout' });
+      if (retry && !retry.skipped) {
+        getDb().prepare('UPDATE runs SET retry_count = ? WHERE id = ?').run(retry.retryCount, run.id);
+        if (['announce', 'announce-always'].includes(job.delivery_mode)) {
+          await handleDelivery(
+            job,
+            `[timeout] Job timed out (stale, will retry): ${job.name}\n\nNo activity for ${staleThresholdSeconds}s\nRetry ${retry.retryCount}/${job.max_retries} in ${retry.delaySec}s`
+          );
+        }
+        if (dequeueJob(job.id)) {
+          log('info', `Dequeued pending dispatch for ${job.name} (after stale timeout retry scheduling)`);
+        }
+        log('info', `Scheduled retry ${retry.retryCount} for timed-out stale run: ${job.name}`, { runId: run.id, delaySec: retry.delaySec });
+        continue;
+      }
+    }
+    updateJobAfterRun(job, 'timeout');
+    if (['announce', 'announce-always'].includes(job.delivery_mode)) {
+      await handleDelivery(job, `[timeout] Job timed out (stale): ${job.name}\n\nNo activity for ${staleThresholdSeconds}s`);
+    }
+    if (dequeueJob(job.id)) {
+      log('info', `Dequeued pending dispatch for ${job.name} (after stale timeout)`);
+    }
+  }
+
+  const staleRunIds = new Set(staleRuns.map(r => r.id));
+  const timedOut = getTimedOutRuns();
+  for (const run of timedOut) {
+    if (staleRunIds.has(run.id)) continue; // already handled above
+    log('warn', `Timed out: ${run.job_name}`, { runId: run.id, timeoutMs: run.run_timeout_ms });
+    finishRun(run.id, 'timeout', {
+      error_message: `Exceeded ${run.run_timeout_ms}ms timeout`,
+    });
+    const job = getJob(run.job_id);
+    if (!job) continue;
+    if (shouldRetry(job, run.id)) {
+      const retry = scheduleRetry(job, run.id, { lastStatus: 'timeout' });
+      if (retry && !retry.skipped) {
+        getDb().prepare('UPDATE runs SET retry_count = ? WHERE id = ?').run(retry.retryCount, run.id);
+        if (['announce', 'announce-always'].includes(job.delivery_mode)) {
+          await handleDelivery(
+            job,
+            `[timeout] Job timed out (will retry): ${job.name}\n\nExceeded ${run.run_timeout_ms}ms timeout\nRetry ${retry.retryCount}/${job.max_retries} in ${retry.delaySec}s`
+          );
+        }
+        if (dequeueJob(job.id)) {
+          log('info', `Dequeued pending dispatch for ${job.name} (after timeout retry scheduling)`);
+        }
+        log('info', `Scheduled retry ${retry.retryCount} for timed-out run: ${job.name}`, { runId: run.id, delaySec: retry.delaySec });
+        continue;
+      }
+    }
+    updateJobAfterRun(job, 'timeout');
+    if (['announce', 'announce-always'].includes(job.delivery_mode)) {
+      await handleDelivery(job, `[timeout] Job timed out: ${job.name}\n\nExceeded ${run.run_timeout_ms}ms timeout`);
+    }
+    if (dequeueJob(job.id)) {
+      log('info', `Dequeued pending dispatch for ${job.name} (after absolute timeout)`);
+    }
+  }
+}
+
+export async function checkTaskTrackers({
+  log,
+  getDb,
+  getAllSubAgentSessions,
+  touchAgentHeartbeat,
+  checkDeadAgents,
+  listActiveTaskGroups,
+  checkGroupCompletion,
+  getTaskGroupStatus,
+  resolveDeliveryAlias,
+  deliverMessage,
+}) {
+  try {
+    try {
+      const db = getDb();
+      const activeSessions = await getAllSubAgentSessions(10);
+      if (activeSessions.length > 0) {
+        for (const session of activeSessions) {
+          const sessionKey = session.key || session.sessionKey;
+          if (!sessionKey) continue;
+
+          const agent = db.prepare(`
+            SELECT a.tracker_id, a.agent_label
+            FROM task_tracker_agents a
+            JOIN task_tracker t ON a.tracker_id = t.id
+            WHERE a.session_key = ? AND a.status IN ('pending', 'running') AND t.status = 'active'
+          `).get(sessionKey);
+
+          if (agent) {
+            touchAgentHeartbeat(agent.tracker_id, agent.agent_label);
+            log('debug', `Auto-heartbeat: ${agent.agent_label} (session active)`);
+          }
+        }
+      }
+    } catch (corrErr) {
+      log('debug', `Session auto-correlation skipped: ${corrErr.message}`);
+    }
+
+    const deadAgents = checkDeadAgents();
+    if (deadAgents.length > 0) {
+      log('warn', `Marked ${deadAgents.length} dead agent(s)`, {
+        agents: deadAgents.map(d => `${d.tracker_id.slice(0, 8)}/${d.agent_label}`),
+      });
+    }
+
+    const activeGroups = listActiveTaskGroups();
+    for (const group of activeGroups) {
+      const result = checkGroupCompletion(group.id);
+      if (!result) continue;
+      const status = getTaskGroupStatus(group.id);
+      const statusTag = result.status === 'completed' ? '[ok]' : '[FAILED]';
+      const msg = `${statusTag} Task group "${group.name}" ${result.status}\n\n${result.summary || ''}`;
+      log('info', `Task group ${result.status}: ${group.name}`, {
+        trackerId: group.id,
+        status: status?.status || result.status,
+      });
+
+      if (group.delivery_channel && group.delivery_to) {
+        try {
+          let channel = group.delivery_channel;
+          let target = group.delivery_to;
+          const resolved = resolveDeliveryAlias(target);
+          if (resolved) {
+            channel = resolved.channel;
+            target = resolved.target;
+          }
+          await deliverMessage(channel, target, msg);
+          log('info', `Task tracker summary delivered`, { channel, target, trackerId: group.id });
+        } catch (err) {
+          log('error', `Task tracker delivery failed: ${err.message}`, { trackerId: group.id });
+        }
+      }
+    }
+  } catch (err) {
+    log('error', `Task tracker check error: ${err.message}`);
+  }
+}
+
+export function expireStaleMessages({ expireMessages }) {
+  expireMessages();
+}
+
+/**
+ * Validate that a value does not contain shell metacharacters that could
+ * enable injection when interpolated into a shell command string.
+ */
+function assertSafeShellArg(val, name) {
+  if (typeof val !== 'string') return;
+  if (/[`$\\;|&<>(){}[\]!#~\n\r]/.test(val)) {
+    throw new Error(`${name} contains unsafe shell characters: ${val}`);
+  }
+}
+
+/**
+ * Shell-safe single-quote escaping. Returns a fully-quoted token wrapped
+ * in single quotes. Embedded single quotes use the standard bash idiom
+ * 'foo'\''bar' which ends the current single-quoted string, inserts an
+ * escaped single quote, and reopens single quoting.
+ */
+function sq(val) {
+  return "'" + String(val).replace(/'/g, "'\\''") + "'";
+}
+
+export function ensureAgentInboxJobs({ log, getDb, createJob }) {
+  try {
+    const db = getDb();
+
+    // Find agents with delivery config
+    const agents = db.prepare(`
+      SELECT id, delivery_channel, delivery_to, brand_name
+      FROM agents
+      WHERE delivery_channel IS NOT NULL AND delivery_to IS NOT NULL
+    `).all();
+
+    if (agents.length === 0) return;
+
+    for (const agent of agents) {
+      const jobName = `inbox-consumer:${agent.id}`;
+
+      // Check if job already exists
+      const existing = db.prepare('SELECT id FROM jobs WHERE name = ?').get(jobName);
+      if (existing) continue;
+
+      // Validate args are free of shell metacharacters before interpolation
+      assertSafeShellArg(agent.id, 'agent.id');
+      assertSafeShellArg(agent.delivery_to, 'delivery_to');
+      assertSafeShellArg(agent.delivery_channel, 'delivery_channel');
+
+      // Use the bin command registered in package.json so the job does not
+      // embed an absolute filesystem path that would break after upgrades.
+      const consumerCmd = `openclaw-inbox-consumer --agent ${sq(agent.id)} --to ${sq(agent.delivery_to)} --channel ${sq(agent.delivery_channel)}`;
+
+      createJob({
+        name:             jobName,
+        schedule_cron:    '*/5 * * * *',
+        session_target:   'shell',
+        payload_kind:     'shellCommand',
+        payload_message:  consumerCmd,
+        delivery_mode:    'none',
+        overlap_policy:   'skip',
+        enabled:          1,
+        run_timeout_ms:   120_000,  // 2 min: inbox consumer shell script should be fast
+        origin:           'system',
+      });
+
+      log('info', `Created inbox consumer job: ${jobName} -> ${agent.delivery_channel}:${agent.delivery_to}`);
+    }
+  } catch (err) {
+    log('error', `ensureAgentInboxJobs error: ${err.message}`);
+  }
+}

package/dispatcher-shell.js

@@ -0,0 +1,29 @@
+import { exec as execCb } from 'child_process';
+
+// Platform-aware shell defaults:
+// - macOS: /bin/zsh
+// - Linux/WSL: /bin/bash
+// - Windows: cmd.exe
+// Override with SCHEDULER_SHELL env var.
+export const DEFAULT_SHELL = process.env.SCHEDULER_SHELL
+  || (process.platform === 'darwin'
+    ? '/bin/zsh'
+    : process.platform === 'win32'
+      ? 'cmd.exe'
+      : '/bin/bash');
+
+export function runShellCommand(cmd, timeoutMs = 300000, env = null) {
+  if (!cmd || typeof cmd !== 'string') throw new Error('Shell command must be a non-empty string');
+  const safeTimeout = (Number.isFinite(timeoutMs) && timeoutMs > 0) ? timeoutMs : 300_000;
+  return new Promise((resolve) => {
+    execCb(cmd, { timeout: safeTimeout, maxBuffer: 64 * 1024 * 1024, shell: DEFAULT_SHELL, env: env ? { ...process.env, ...env } : undefined }, (err, stdout, stderr) => {
+      resolve({
+        stdout: stdout || '',
+        stderr: stderr || '',
+        exitCode: Number.isInteger(err?.code) ? err.code : (err ? 1 : 0),
+        signal: err?.signal || null,
+        error: err || null,
+      });
+    });
+  });
+}