openclaw-scheduler 0.2.0

package/migrate.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Migrate existing OpenClaw cron jobs.json -> SQLite scheduler
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { initDb } from './db.js';
+import { createJob, listJobs } from './jobs.js';
+
+import { homedir } from 'os';
+
+const JOBS_JSON = process.env.OPENCLAW_JOBS_JSON
+  || join(process.env.HOME || homedir(), '.openclaw/cron/jobs.json');
+
+function cronFromSchedule(schedule) {
+  // OpenClaw supports: cron (expr), every (everyMs), at (one-shot ISO)
+  if (schedule.kind === 'cron') {
+    return { cron: schedule.expr, tz: schedule.tz || 'UTC' };
+  }
+  if (schedule.kind === 'every') {
+    // Convert interval to approximate cron. everyMs -> minutes
+    if (schedule.everyMs < 60000) {
+      console.warn(`  WARN: ${schedule.everyMs}ms interval rounded up to 1 minute (cron minimum)`);
+    }
+    const mins = Math.max(1, Math.round(schedule.everyMs / 60000));
+    if (mins < 60) return { cron: `*/${mins} * * * *`, tz: schedule.tz || 'UTC' };
+    const hours = Math.max(1, Math.round(mins / 60));
+    const remaining = mins % 60;
+    const clampedHours = Math.min(hours, 23);
+    if (hours > 23) {
+      console.warn(`  WARN: ${schedule.everyMs}ms interval exceeds 23 hours; clamping to */23 hours`);
+    }
+    if (remaining !== 0) {
+      console.warn(`  WARN: ${schedule.everyMs}ms interval (${mins}min) cannot be represented exactly in standard cron; approximating to every ${clampedHours} hour(s)`);
+    }
+    return { cron: `0 */${clampedHours} * * *`, tz: schedule.tz || 'UTC' };
+  }
+  if (schedule.kind === 'at') {
+    // One-shot: compute the specific minute/hour/day cron that fires once
+    const d = new Date(schedule.at);
+    return {
+      cron: `${d.getUTCMinutes()} ${d.getUTCHours()} ${d.getUTCDate()} ${d.getUTCMonth() + 1} *`,
+      tz: 'UTC',
+    };
+  }
+  throw new Error(`Unknown schedule kind: ${schedule.kind}`);
+}
+
+function main() {
+  if (!existsSync(JOBS_JSON)) {
+    console.error(`No jobs.json found at: ${JOBS_JSON}`);
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(JOBS_JSON, 'utf8'));
+  } catch (err) {
+    console.error(`Failed to parse ${JOBS_JSON}: ${err.message}`);
+    process.exit(1);
+  }
+  const jobs = data.jobs || [];
+
+  console.log(`Found ${jobs.length} job(s) in ${JOBS_JSON}`);
+
+  initDb();
+
+  const existing = listJobs();
+  const existingIds = new Set(existing.map(j => j.id));
+
+  let imported = 0;
+  let skipped = 0;
+
+  for (const job of jobs) {
+    if (existingIds.has(job.id)) {
+      console.log(`  SKIP: ${job.name} (already exists)`);
+      skipped++;
+      continue;
+    }
+
+    try {
+      const { cron, tz } = cronFromSchedule(job.schedule);
+
+      let deliveryMode = job.delivery?.mode || 'announce';
+      const deliveryTo = job.delivery?.to || null;
+      let deliveryOptOutReason = null;
+
+      if ((deliveryMode === 'announce' || deliveryMode === 'announce-always') && !deliveryTo) {
+        console.warn(`  WARN: ${job.name}: delivery_mode='${deliveryMode}' but no delivery_to configured; downgrading to 'none'`);
+        deliveryMode = 'none';
+        deliveryOptOutReason = 'migrated: no delivery target configured';
+      }
+
+      createJob({
+        id: job.id,
+        name: job.name,
+        enabled: job.enabled !== false,
+        schedule_cron: cron,
+        schedule_tz: tz,
+        session_target: job.sessionTarget || 'isolated',
+        agent_id: job.agentId || 'main',
+        payload_kind: job.payload?.kind || 'agentTurn',
+        payload_message: job.payload?.message || job.payload?.text || '',
+        payload_model: job.payload?.model || null,
+        payload_thinking: job.payload?.thinking || null,
+        payload_timeout_seconds: job.payload?.timeoutSeconds || 120,
+        overlap_policy: 'skip',
+        run_timeout_ms: 300000,
+        delivery_mode: deliveryMode,
+        delivery_channel: job.delivery?.channel || null,
+        delivery_to: deliveryTo,
+        delivery_opt_out_reason: deliveryOptOutReason,
+        delete_after_run: job.schedule?.kind === 'at',
+        origin: job.origin || 'system',
+      });
+
+      console.log(`  OK: ${job.name} -> cron="${cron}" tz=${tz}`);
+      imported++;
+    } catch (err) {
+      console.error(`  ERR: ${job.name}: ${err.message}`);
+    }
+  }
+
+  console.log(`\nDone: ${imported} imported, ${skipped} skipped`);
+}
+
+main();

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "openclaw-scheduler",
+  "version": "0.2.0",
+  "description": "SQLite-backed job scheduler and workflow engine for OpenClaw agents",
+  "type": "module",
+  "main": "./index.js",
+  "bin": {
+    "openclaw-scheduler": "bin/openclaw-scheduler.js",
+    "openclaw-inbox-consumer": "scripts/inbox-consumer.mjs"
+  },
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node dispatcher.js",
+    "migrate": "node migrate.js",
+    "test": "SCHEDULER_DB=:memory: node test.js",
+    "lint": "eslint . --max-warnings=0",
+    "coverage": "SCHEDULER_DB=:memory: node scripts/coverage.mjs",
+    "typecheck": "tsc --project tsconfig.json",
+    "verify:smoke": "node scripts/verify-local.mjs --smoke",
+    "verify:local": "node scripts/verify-local.mjs",
+    "prepublishOnly": "npm run verify:local"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.5",
+    "flatted": "^3.4.2"
+  },
+  "files": [
+    "bin",
+    "dispatch/529-recovery.mjs",
+    "dispatch/config.example.json",
+    "dispatch/deliver-watcher.sh",
+    "dispatch/hooks.mjs",
+    "dispatch/index.mjs",
+    "dispatch/README.md",
+    "dispatch/watcher.mjs",
+    "scripts/dispatch-cli-utils.mjs",
+    "scripts/inbox-consumer.mjs",
+    "scripts/stuck-run-detector.mjs",
+    "scripts/stuck-detector.sh",
+    "scripts/telegram-webhook-check.mjs",
+    "agents.js",
+    "approval.js",
+    "backup.js",
+    "cli.js",
+    "db.js",
+    "dispatch-queue.js",
+    "dispatcher-approvals.js",
+    "dispatcher-delivery.js",
+    "dispatcher-maintenance.js",
+    "dispatcher-shell.js",
+    "dispatcher-strategies.js",
+    "dispatcher-utils.js",
+    "dispatcher.js",
+    "gateway.js",
+    "idempotency.js",
+    "index.d.ts",
+    "index.js",
+    "jobs.js",
+    "messages.js",
+    "migrate.js",
+    "migrate-consolidate.js",
+    "paths.js",
+    "prompt-context.js",
+    "retrieval.js",
+    "runs.js",
+    "scheduler-schema.js",
+    "schema.sql",
+    "setup.mjs",
+    "shell-result.js",
+    "task-tracker.js",
+    "team-adapter.js",
+    "v02-runtime.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "INSTALL*.md",
+    "UNINSTALL.md",
+    "UPGRADING.md",
+    "BEST-PRACTICES.md",
+    "QUICK-START.md",
+    "AGENTS.md",
+    "CONTEXT.md",
+    "JOB-QUICK-REF.md",
+    "IMPLEMENTATION_SPEC.md",
+    "docs"
+  ],
+  "keywords": [
+    "openclaw",
+    "scheduler",
+    "cron",
+    "workflow",
+    "sqlite",
+    "agent",
+    "automation"
+  ],
+  "author": "Alex Mittell",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amittell/openclaw-scheduler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amittell/openclaw-scheduler/issues"
+  },
+  "homepage": "https://github.com/amittell/openclaw-scheduler#readme",
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    "croner": "^10.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "c8": "^11.0.0",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "typescript": "^5.9.2"
+  }
+}

package/paths.js

@@ -0,0 +1,79 @@
+import { accessSync, constants, existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function firstNonEmpty(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : '';
+}
+
+function ensureWritableDir(dirPath) {
+  try {
+    mkdirSync(dirPath, { recursive: true });
+    accessSync(dirPath, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isNodeModulesInstall(moduleDir) {
+  return /[\\/]node_modules[\\/](?:@[^\\/]+[\\/])?openclaw-scheduler(?:[\\/]|$)/.test(moduleDir);
+}
+
+export function resolveSchedulerHome(env = process.env) {
+  const explicitHome = firstNonEmpty(env.SCHEDULER_HOME);
+  if (explicitHome) return explicitHome;
+  const home = firstNonEmpty(env.HOME) || homedir();
+  return join(home, '.openclaw', 'scheduler');
+}
+
+export function resolveSchedulerDbPath(params = {}) {
+  const env = params.env || process.env;
+  const explicitPath = firstNonEmpty(params.explicitPath);
+  if (explicitPath) return explicitPath;
+
+  const envDbPath = firstNonEmpty(env.SCHEDULER_DB);
+  if (envDbPath) return envDbPath;
+
+  const moduleDir = firstNonEmpty(params.moduleDir) || __dirname;
+  const moduleDbPath = join(moduleDir, 'scheduler.db');
+  const moduleDirWritable = !isNodeModulesInstall(moduleDir) && ensureWritableDir(moduleDir);
+  if (!isNodeModulesInstall(moduleDir) && (existsSync(moduleDbPath) || moduleDirWritable)) {
+    return moduleDbPath;
+  }
+
+  return join(resolveSchedulerHome(env), 'scheduler.db');
+}
+
+export function ensureSchedulerDbParent(dbPath) {
+  const parent = dirname(dbPath);
+  mkdirSync(parent, { recursive: true });
+  return parent;
+}
+
+export function resolveBackupStagingDir(env = process.env) {
+  const explicit = firstNonEmpty(env.SCHEDULER_BACKUP_STAGING_DIR);
+  if (explicit) return explicit;
+  return join(resolveSchedulerHome(env), '.backup-staging');
+}
+
+export function resolveArtifactsDir(params = {}) {
+  const env = params.env || process.env;
+  const explicit = firstNonEmpty(params.explicitPath) || firstNonEmpty(env.SCHEDULER_ARTIFACTS_DIR);
+  if (explicit) return explicit;
+  const dbPath = firstNonEmpty(params.dbPath);
+  if (dbPath && dbPath !== ':memory:') {
+    return join(dirname(dbPath), 'artifacts');
+  }
+  return join(resolveSchedulerHome(env), 'artifacts');
+}
+
+export function ensureArtifactsDir(dirPath) {
+  mkdirSync(dirPath, { recursive: true });
+  return dirPath;
+}

package/prompt-context.js

@@ -0,0 +1,94 @@
+import { getRun } from './runs.js';
+import { getJob } from './jobs.js';
+import { extractShellResultFromRun } from './shell-result.js';
+
+function truncate(text, limit) {
+  if (!text || text.length <= limit) return text;
+  return `${text.slice(0, Math.max(0, limit - 16))}\n...[truncated]`;
+}
+
+export function buildTriggeredRunContext(run, deps = {}) {
+  if (!run?.triggered_by_run) {
+    return { text: '', meta: {} };
+  }
+
+  const getRunById = deps.getRunById || getRun;
+  const getJobById = deps.getJobById || getJob;
+  const parentRun = getRunById(run.triggered_by_run);
+
+  if (!parentRun) {
+    return {
+      text: '',
+      meta: {
+        triggered_by_run: run.triggered_by_run,
+        parent_run_missing: true
+      }
+    };
+  }
+
+  const parentJob = getJobById(parentRun.job_id);
+  const lines = [
+    '',
+    '--- Trigger Context ---',
+    `Triggered by: ${parentJob?.name || parentRun.job_id}`,
+    `Parent run status: ${parentRun.status}`
+  ];
+
+  const shellResult = extractShellResultFromRun(parentRun);
+  if (shellResult) {
+    lines.push('Parent shell result:');
+    if (shellResult.timedOut) {
+      lines.push('Timed out: true');
+    }
+    if (typeof shellResult.exitCode === 'number') {
+      lines.push(`Exit code: ${shellResult.exitCode}`);
+    }
+    if (shellResult.signal) {
+      lines.push(`Signal: ${shellResult.signal}`);
+    }
+    if (shellResult.errorMessage) {
+      lines.push(`Error: ${shellResult.errorMessage}`);
+    }
+    if (shellResult.stdout?.trim()) {
+      lines.push('stdout:');
+      lines.push(truncate(shellResult.stdout, 3000));
+    }
+    if (shellResult.stdoutPath) {
+      lines.push(`stdout file: ${shellResult.stdoutPath} (${shellResult.stdoutBytes || 0} bytes)`);
+    }
+    if (shellResult.stderr?.trim()) {
+      lines.push('stderr:');
+      lines.push(truncate(shellResult.stderr, 3000));
+    }
+    if (shellResult.stderrPath) {
+      lines.push(`stderr file: ${shellResult.stderrPath} (${shellResult.stderrBytes || 0} bytes)`);
+    }
+  } else if (parentRun.summary?.trim()) {
+    lines.push('Parent run output:');
+    lines.push(parentRun.summary.slice(0, 5000));
+  } else if (parentRun.error_message?.trim()) {
+    lines.push('Parent run error:');
+    lines.push(parentRun.error_message.slice(0, 2000));
+  }
+
+  lines.push('---');
+
+  return {
+    text: lines.join('\n'),
+    meta: {
+      triggered_by_run: parentRun.id,
+      parent_job_id: parentRun.job_id,
+      parent_job_name: parentJob?.name || null,
+      parent_run_status: parentRun.status,
+      ...(shellResult
+        ? {
+            parent_shell_exit_code: shellResult.exitCode,
+            parent_shell_signal: shellResult.signal,
+            parent_shell_timed_out: shellResult.timedOut,
+            parent_shell_stdout_path: shellResult.stdoutPath || null,
+            parent_shell_stderr_path: shellResult.stderrPath || null,
+          }
+        : {})
+    }
+  };
+}

package/retrieval.js

@@ -0,0 +1,176 @@
+// Hybrid retrieval for injecting prior-run context into job prompts
+import { getDb } from './db.js';
+
+// ---- TF-IDF helpers ----
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'shall',
+  'should', 'may', 'might', 'must', 'can', 'could', 'to', 'of', 'in',
+  'for', 'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through',
+  'during', 'before', 'after', 'above', 'below', 'between', 'and',
+  'but', 'or', 'nor', 'not', 'so', 'yet', 'both', 'either', 'neither',
+  'each', 'every', 'all', 'any', 'few', 'more', 'most', 'other', 'some',
+  'such', 'no', 'only', 'own', 'same', 'than', 'too', 'very', 'just',
+  'it', 'its', 'this', 'that', 'these', 'those', 'i', 'me', 'my',
+  'we', 'our', 'you', 'your', 'he', 'him', 'his', 'she', 'her',
+  'they', 'them', 'their', 'what', 'which', 'who', 'whom',
+]);
+
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .split(/\s+/)
+    .map(t => t.replace(/[^a-z0-9]/g, ''))
+    .filter(t => t.length > 1 && !STOPWORDS.has(t));
+}
+
+function computeTF(tokens) {
+  const freq = {};
+  for (const t of tokens) {
+    freq[t] = (freq[t] || 0) + 1;
+  }
+  const len = tokens.length || 1;
+  const tf = {};
+  for (const [term, count] of Object.entries(freq)) {
+    tf[term] = count / len;
+  }
+  return tf;
+}
+
+function computeIDF(docs) {
+  // docs: array of TF maps
+  const N = docs.length || 1;
+  const df = {}; // document frequency per term
+  for (const tf of docs) {
+    for (const term of Object.keys(tf)) {
+      df[term] = (df[term] || 0) + 1;
+    }
+  }
+  const idf = {};
+  for (const [term, count] of Object.entries(df)) {
+    idf[term] = Math.log(N / count) + 1; // smoothed IDF
+  }
+  return idf;
+}
+
+function tfidfScore(queryTokens, docTF, idf) {
+  let score = 0;
+  for (const qt of queryTokens) {
+    if (docTF[qt]) {
+      score += docTF[qt] * (idf[qt] || 1);
+    }
+  }
+  return score;
+}
+
+/**
+ * Extract readable text from a context_summary field.
+ * The field may be a JSON string (object with string values) or plain text.
+ */
+function extractSummaryText(raw) {
+  if (!raw) return '';
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object') {
+      return Object.values(parsed)
+        .filter(v => typeof v === 'string')
+        .join(' ');
+    }
+    return String(parsed);
+  } catch {
+    return raw;
+  }
+}
+
+// ---- Exports ----
+
+/**
+ * Get the last N run summaries (non-null context_summary) for a job.
+ */
+export function getRecentRunSummaries(jobId, limit = 5) {
+  return getDb().prepare(`
+    SELECT id, job_id, started_at, finished_at, status, context_summary, summary
+    FROM runs
+    WHERE job_id = ? AND context_summary IS NOT NULL
+    ORDER BY started_at DESC
+    LIMIT ?
+  `).all(jobId, limit);
+}
+
+/**
+ * Search run summaries using hybrid substring + TF-IDF scoring.
+ * Returns top N matches from the last 50 runs with summaries.
+ */
+export function searchRunSummaries(jobId, query, limit = 5) {
+  // Fetch candidate pool
+  const candidates = getDb().prepare(`
+    SELECT id, job_id, started_at, finished_at, status, context_summary, summary
+    FROM runs
+    WHERE job_id = ? AND context_summary IS NOT NULL
+    ORDER BY started_at DESC
+    LIMIT 50
+  `).all(jobId);
+
+  if (!candidates.length || !query) return candidates.slice(0, limit);
+
+  const queryTokens = tokenize(query);
+  const queryLower = query.toLowerCase();
+
+  // Build TF for each doc
+  const docTFs = candidates.map(c => {
+    const text = [extractSummaryText(c.context_summary), c.summary || ''].join(' ');
+    return computeTF(tokenize(text));
+  });
+
+  const idf = computeIDF(docTFs);
+
+  // Score each candidate
+  const scored = candidates.map((c, i) => {
+    const text = [extractSummaryText(c.context_summary), c.summary || ''].join(' ').toLowerCase();
+    // Substring bonus
+    const substringBonus = text.includes(queryLower) ? 1.0 : 0;
+    // TF-IDF score
+    const tfidf = tfidfScore(queryTokens, docTFs[i], idf);
+    return { ...c, _score: tfidf + substringBonus };
+  });
+
+  scored.sort((a, b) => b._score - a._score);
+  return scored.slice(0, limit).filter(s => s._score > 0);
+}
+
+/**
+ * Build retrieval context string to inject into a job prompt.
+ * Returns empty string if retrieval is disabled or no results found.
+ */
+export function buildRetrievalContext(job) {
+  if (!job.context_retrieval || job.context_retrieval === 'none') return '';
+
+  const limit = job.context_retrieval_limit || 5;
+  let runs;
+
+  if (job.context_retrieval === 'recent') {
+    runs = getRecentRunSummaries(job.id, limit);
+  } else if (job.context_retrieval === 'hybrid') {
+    // Use the job's payload_message as the search query
+    runs = searchRunSummaries(job.id, job.payload_message, limit);
+    // Fallback to recent if search returns nothing
+    if (!runs.length) {
+      runs = getRecentRunSummaries(job.id, limit);
+    }
+  } else {
+    return '';
+  }
+
+  if (!runs.length) return '';
+
+  const lines = ['--- Prior Run Context ---'];
+  for (const run of runs) {
+    const date = run.started_at || 'unknown';
+    const summaryText = extractSummaryText(run.context_summary) || run.summary || '';
+    lines.push(`[${date}] ${summaryText}`);
+  }
+  lines.push('--- End Prior Run Context ---');
+
+  return lines.join('\n');
+}