@karmaniverous/jeeves-runner 0.5.0 → 0.6.0

package/dist/cli/jeeves-runner/index.js

@@ -1,19 +1,24 @@
 #!/usr/bin/env node
-import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, extname, resolve } from 'node:path';
+import { mkdirSync, mkdtempSync, writeFileSync, unlinkSync, existsSync, readFileSync } from 'node:fs';
+import { dirname, join, extname, resolve } from 'node:path';
 import { Command } from 'commander';
-import { Cron, CronPattern } from 'croner';
 import { DatabaseSync } from 'node:sqlite';
 import { pino } from 'pino';
 import Fastify from 'fastify';
 import { createConfigQueryHandler } from '@karmaniverous/jeeves';
+import { z } from 'zod';
+import { RRStack } from '@karmaniverous/rrstack';
+import { Cron } from 'croner';
+import { JSONPath } from 'jsonpath-plus';
 import { request as request$1 } from 'node:http';
 import { request } from 'node:https';
 import { spawn } from 'node:child_process';
-import { z } from 'zod';
+import { tmpdir } from 'node:os';
 
 /**
  * SQLite connection manager. Creates DB file with parent directories, enables WAL mode for concurrency.
+ *
+ * @module
  */
 /**
  * Create and configure a SQLite database connection.
@@ -42,6 +47,8 @@ function closeConnection(db) {
 
 /**
  * Schema migration runner. Tracks applied migrations via schema_version table, applies pending migrations idempotently.
+ *
+ * @module
  */
 /** Initial schema migration SQL (embedded to avoid runtime file resolution issues). */
 const MIGRATION_001 = `
@@ -175,11 +182,16 @@ CREATE TABLE state_items (
 );
 CREATE INDEX idx_state_items_ns_key ON state_items(namespace, key);
 `;
+/** Migration 004: Add source_type column to jobs. */
+const MIGRATION_004 = `
+ALTER TABLE jobs ADD COLUMN source_type TEXT DEFAULT 'path';
+`;
 /** Registry of all migrations keyed by version number. */
 const MIGRATIONS = {
     1: MIGRATION_001,
     2: MIGRATION_002,
     3: MIGRATION_003,
+    4: MIGRATION_004,
 };
 /**
  * Run all pending migrations. Creates schema_version table if needed, applies migrations in order.
@@ -208,6 +220,385 @@ function runMigrations(db) {
     }
 }
 
+/**
+ * Schedule parsing, validation, and next-fire-time computation for cron and RRStack formats.
+ *
+ * @module
+ */
+/**
+ * Attempt to parse a schedule string as RRStack JSON (non-null, non-array
+ * object). Returns the parsed options on success, or null if the string
+ * is not a JSON object.
+ */
+function tryParseRRStack(schedule) {
+    try {
+        const parsed = JSON.parse(schedule);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the next fire time for a schedule string.
+ * Supports cron expressions (via croner) and RRStack JSON (via nextEvent).
+ *
+ * @param schedule - Cron expression or RRStack JSON string.
+ * @returns Next fire time as a Date, or null if none can be determined.
+ */
+function getNextFireTime(schedule) {
+    const rrOpts = tryParseRRStack(schedule);
+    if (rrOpts) {
+        const stack = new RRStack(rrOpts);
+        const next = stack.nextEvent();
+        if (!next)
+            return null;
+        const unit = stack.timeUnit;
+        return new Date(unit === 's' ? next.at * 1000 : next.at);
+    }
+    const cron = new Cron(schedule);
+    return cron.nextRun() ?? null;
+}
+/**
+ * Validate a schedule string as either a cron expression or RRStack JSON.
+ *
+ * @param schedule - Cron expression or RRStack JSON string.
+ * @returns Validation result with format on success, or error message on failure.
+ */
+function validateSchedule(schedule) {
+    const rrOpts = tryParseRRStack(schedule);
+    if (rrOpts) {
+        try {
+            new RRStack(rrOpts);
+            return { valid: true, format: 'rrstack' };
+        }
+        catch (err) {
+            return {
+                valid: false,
+                error: `Invalid RRStack schedule: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    try {
+        new Cron(schedule);
+        return { valid: true, format: 'cron' };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Invalid cron expression: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+
+/**
+ * Job CRUD routes: create, update, delete, enable/disable, and script update endpoints.
+ *
+ * @module
+ */
+/** Zod schema for job creation/update request body. */
+const createJobSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    schedule: z.string().min(1),
+    script: z.string().min(1),
+    source_type: z.enum(['path', 'inline']).default('path'),
+    type: z.enum(['script', 'session']).default('script'),
+    timeout_seconds: z.number().positive().optional(),
+    overlap_policy: z.enum(['skip', 'allow']).default('skip'),
+    enabled: z.boolean().default(true),
+    description: z.string().optional(),
+    on_failure: z.string().nullable().optional(),
+    on_success: z.string().nullable().optional(),
+});
+/** Zod schema for job update (all fields optional except what's set). */
+const updateJobSchema = createJobSchema.omit({ id: true }).partial();
+/** Zod schema for script update request body. */
+const updateScriptSchema = z.object({
+    script: z.string().min(1),
+    source_type: z.enum(['path', 'inline']).optional(),
+});
+/** Standard error message for missing job resources. */
+const JOB_NOT_FOUND = 'Job not found';
+/**
+ * Register job CRUD routes on the Fastify instance.
+ */
+function registerJobRoutes(app, deps) {
+    const { db, scheduler } = deps;
+    /** POST /jobs — Create a new job. */
+    app.post('/jobs', (request, reply) => {
+        const parsed = createJobSchema.safeParse(request.body);
+        if (!parsed.success) {
+            reply.code(400);
+            return { error: parsed.error.message };
+        }
+        const data = parsed.data;
+        const validation = validateSchedule(data.schedule);
+        if (!validation.valid) {
+            reply.code(400);
+            return { error: validation.error };
+        }
+        const timeoutMs = data.timeout_seconds ? data.timeout_seconds * 1000 : null;
+        db.prepare(`INSERT INTO jobs (id, name, schedule, script, source_type, type, timeout_ms,
+       overlap_policy, enabled, description, on_failure, on_success)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(data.id, data.name, data.schedule, data.script, data.source_type, data.type, timeoutMs, data.overlap_policy, data.enabled ? 1 : 0, data.description ?? null, data.on_failure ?? null, data.on_success ?? null);
+        scheduler.reconcileNow();
+        reply.code(201);
+        return { ok: true, id: data.id };
+    });
+    /** PATCH /jobs/:id — Partial update of an existing job. */
+    app.patch('/jobs/:id', (request, reply) => {
+        const parsed = updateJobSchema.safeParse(request.body);
+        if (!parsed.success) {
+            reply.code(400);
+            return { error: parsed.error.message };
+        }
+        const existing = db
+            .prepare('SELECT id FROM jobs WHERE id = ?')
+            .get(request.params.id);
+        if (!existing) {
+            reply.code(404);
+            return { error: JOB_NOT_FOUND };
+        }
+        const data = parsed.data;
+        if (data.schedule) {
+            const validation = validateSchedule(data.schedule);
+            if (!validation.valid) {
+                reply.code(400);
+                return { error: validation.error };
+            }
+        }
+        /** Map input field → DB column + value transform. */
+        const fieldMap = [
+            { input: 'name', column: 'name' },
+            { input: 'schedule', column: 'schedule' },
+            { input: 'script', column: 'script' },
+            { input: 'source_type', column: 'source_type' },
+            { input: 'type', column: 'type' },
+            {
+                input: 'timeout_seconds',
+                column: 'timeout_ms',
+                transform: (v) => v * 1000,
+            },
+            { input: 'overlap_policy', column: 'overlap_policy' },
+            {
+                input: 'enabled',
+                column: 'enabled',
+                transform: (v) => (v ? 1 : 0),
+            },
+            { input: 'description', column: 'description' },
+            { input: 'on_failure', column: 'on_failure' },
+            { input: 'on_success', column: 'on_success' },
+        ];
+        const sets = [];
+        const values = [];
+        for (const { input, column, transform } of fieldMap) {
+            if (data[input] !== undefined) {
+                sets.push(`${column} = ?`);
+                values.push(transform ? transform(data[input]) : data[input]);
+            }
+        }
+        if (sets.length > 0) {
+            sets.push("updated_at = datetime('now')");
+            values.push(request.params.id);
+            db.prepare(`UPDATE jobs SET ${sets.join(', ')} WHERE id = ?`).run(...values);
+        }
+        scheduler.reconcileNow();
+        return { ok: true };
+    });
+    /** DELETE /jobs/:id — Delete a job and its runs. */
+    app.delete('/jobs/:id', (request, reply) => {
+        db.prepare('DELETE FROM runs WHERE job_id = ?').run(request.params.id);
+        const result = db
+            .prepare('DELETE FROM jobs WHERE id = ?')
+            .run(request.params.id);
+        if (result.changes === 0) {
+            reply.code(404);
+            return { error: JOB_NOT_FOUND };
+        }
+        scheduler.reconcileNow();
+        return { ok: true };
+    });
+    /** Register a PATCH toggle endpoint (enable or disable). */
+    function registerToggle(path, enabledValue) {
+        app.patch(path, (request, reply) => {
+            const result = db
+                .prepare('UPDATE jobs SET enabled = ? WHERE id = ?')
+                .run(enabledValue, request.params.id);
+            if (result.changes === 0) {
+                reply.code(404);
+                return { error: JOB_NOT_FOUND };
+            }
+            scheduler.reconcileNow();
+            return { ok: true };
+        });
+    }
+    registerToggle('/jobs/:id/enable', 1);
+    registerToggle('/jobs/:id/disable', 0);
+    /** PUT /jobs/:id/script — Update job script and source_type. */
+    app.put('/jobs/:id/script', (request, reply) => {
+        const parsed = updateScriptSchema.safeParse(request.body);
+        if (!parsed.success) {
+            reply.code(400);
+            return { error: parsed.error.message };
+        }
+        const data = parsed.data;
+        const result = data.source_type
+            ? db
+                .prepare('UPDATE jobs SET script = ?, source_type = ? WHERE id = ?')
+                .run(data.script, data.source_type, request.params.id)
+            : db
+                .prepare('UPDATE jobs SET script = ? WHERE id = ?')
+                .run(data.script, request.params.id);
+        if (result.changes === 0) {
+            reply.code(404);
+            return { error: JOB_NOT_FOUND };
+        }
+        scheduler.reconcileNow();
+        return { ok: true };
+    });
+}
+
+/**
+ * Queue inspection routes: list queues, queue status, and peek at pending items.
+ *
+ * @module
+ */
+/**
+ * Register queue inspection routes on the Fastify instance.
+ */
+function registerQueueRoutes(app, deps) {
+    const { db } = deps;
+    /** GET /queues — List all distinct queues that have items. */
+    app.get('/queues', () => {
+        const rows = db
+            .prepare('SELECT DISTINCT queue_id FROM queue_items')
+            .all();
+        return { queues: rows.map((r) => r.queue_id) };
+    });
+    /** GET /queues/:name/status — Queue depth, claimed count, failed count, oldest age. */
+    app.get('/queues/:name/status', (request) => {
+        const row = db
+            .prepare(`SELECT
+           SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) AS depth,
+           SUM(CASE WHEN status = 'processing' THEN 1 ELSE 0 END) AS claimed,
+           SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+           MIN(CASE WHEN status = 'pending' THEN created_at END) AS oldest
+         FROM queue_items
+         WHERE queue_id = ?`)
+            .get(request.params.name);
+        return {
+            depth: row.depth ?? 0,
+            claimedCount: row.claimed ?? 0,
+            failedCount: row.failed ?? 0,
+            oldestAge: row.oldest
+                ? Date.now() - new Date(row.oldest).getTime()
+                : null,
+        };
+    });
+    /** GET /queues/:name/peek — Non-claiming read of pending items. */
+    app.get('/queues/:name/peek', (request) => {
+        const name = request.params.name;
+        const limit = parseInt(request.query.limit ?? '10', 10);
+        const items = db
+            .prepare(`SELECT id, payload, priority, created_at FROM queue_items
+           WHERE queue_id = ? AND status = 'pending'
+           ORDER BY priority DESC, created_at
+           LIMIT ?`)
+            .all(name, limit);
+        return {
+            items: items.map((item) => ({
+                id: item.id,
+                payload: JSON.parse(item.payload),
+                priority: item.priority,
+                createdAt: item.created_at,
+            })),
+        };
+    });
+}
+
+/**
+ * State inspection routes: list namespaces, read scalar state, and read collection items.
+ *
+ * @module
+ */
+/**
+ * Register state inspection routes on the Fastify instance.
+ */
+function registerStateRoutes(app, deps) {
+    const { db } = deps;
+    /** GET /state — List all distinct namespaces. */
+    app.get('/state', () => {
+        const rows = db
+            .prepare('SELECT DISTINCT namespace FROM state')
+            .all();
+        return { namespaces: rows.map((r) => r.namespace) };
+    });
+    /** GET /state/:namespace — Materialise all scalar state as key-value map. */
+    app.get('/state/:namespace', (request) => {
+        const { namespace } = request.params;
+        const rows = db
+            .prepare(`SELECT key, value FROM state
+           WHERE namespace = ?
+           AND (expires_at IS NULL OR expires_at > datetime('now'))`)
+            .all(namespace);
+        const state = {};
+        for (const row of rows) {
+            state[row.key] = row.value;
+        }
+        if (request.query.path) {
+            const result = JSONPath({
+                path: request.query.path,
+                json: state,
+            });
+            return { result, count: Array.isArray(result) ? result.length : 1 };
+        }
+        return state;
+    });
+    /** GET /state/:namespace/:key — Read collection items for a state key. */
+    app.get('/state/:namespace/:key', (request) => {
+        const { namespace, key } = request.params;
+        const limit = parseInt(request.query.limit ?? '100', 10);
+        const order = request.query.order === 'asc' ? 'ASC' : 'DESC';
+        // First check scalar state value
+        const scalar = db
+            .prepare(`SELECT value FROM state
+         WHERE namespace = ? AND key = ?
+         AND (expires_at IS NULL OR expires_at > datetime('now'))`)
+            .get(namespace, key);
+        // Get collection items
+        const items = db
+            .prepare(`SELECT item_key, value, updated_at FROM state_items
+         WHERE namespace = ? AND key = ?
+         ORDER BY updated_at ${order}
+         LIMIT ?`)
+            .all(namespace, key, limit);
+        const mappedItems = items.map((item) => ({
+            itemKey: item.item_key,
+            value: item.value,
+            updatedAt: item.updated_at,
+        }));
+        const body = {
+            value: scalar?.value ?? null,
+            items: mappedItems,
+            count: mappedItems.length,
+        };
+        if (request.query.path) {
+            const result = JSONPath({
+                path: request.query.path,
+                json: body,
+            });
+            return { result, count: Array.isArray(result) ? result.length : 1 };
+        }
+        return body;
+    });
+}
+
 /**
  * Fastify API routes for job management and monitoring. Provides endpoints for job CRUD, run history, manual triggers, system stats, and config queries.
  *
@@ -237,7 +628,7 @@ function registerRoutes(app, deps) {
         return { jobs: rows };
     });
     /** GET /jobs/:id — Single job detail. */
-    app.get('/jobs/:id', async (request, reply) => {
+    app.get('/jobs/:id', (request, reply) => {
         const job = db
             .prepare('SELECT * FROM jobs WHERE id = ?')
             .get(request.params.id);
@@ -266,30 +657,6 @@ function registerRoutes(app, deps) {
             return { error: err instanceof Error ? err.message : 'Unknown error' };
         }
     });
-    /** POST /jobs/:id/enable — Enable a job. */
-    app.post('/jobs/:id/enable', (request, reply) => {
-        const result = db
-            .prepare('UPDATE jobs SET enabled = 1 WHERE id = ?')
-            .run(request.params.id);
-        if (result.changes === 0) {
-            reply.code(404);
-            return { error: 'Job not found' };
-        }
-        scheduler.reconcileNow();
-        return { ok: true };
-    });
-    /** POST /jobs/:id/disable — Disable a job. */
-    app.post('/jobs/:id/disable', (request, reply) => {
-        const result = db
-            .prepare('UPDATE jobs SET enabled = 0 WHERE id = ?')
-            .run(request.params.id);
-        if (result.changes === 0) {
-            reply.code(404);
-            return { error: 'Job not found' };
-        }
-        scheduler.reconcileNow();
-        return { ok: true };
-    });
     /** GET /stats — Aggregate job statistics. */
     app.get('/stats', () => {
         const totalJobs = db
@@ -321,10 +688,17 @@ function registerRoutes(app, deps) {
         });
         return reply.status(result.status).send(result.body);
     });
+    // Register job CRUD routes (POST, PATCH, DELETE, PATCH enable/disable, PUT script)
+    registerJobRoutes(app, { db, scheduler });
+    // Register queue and state inspection routes
+    registerQueueRoutes(app, { db });
+    registerStateRoutes(app, { db });
 }
 
 /**
  * Fastify HTTP server for runner API. Creates server instance with logging, registers routes, listens on configured port (localhost only).
+ *
+ * @module
  */
 /**
  * Create and configure the Fastify server. Routes are registered but server is not started.
@@ -355,6 +729,8 @@ function createServer(deps) {
 
 /**
  * Database maintenance tasks: run retention pruning and expired state cleanup.
+ *
+ * @module
  */
 /** Delete runs older than the configured retention period. */
 function pruneOldRuns(db, days, logger) {
@@ -421,6 +797,8 @@ function createMaintenance(db, config, logger) {
 
 /**
  * Shared HTTP utility for making POST requests.
+ *
+ * @module
  */
 /** Make an HTTP/HTTPS POST request. Returns the parsed JSON response body. */
 function httpPost(url, headers, body, timeoutMs = 30000) {
@@ -468,6 +846,8 @@ function httpPost(url, headers, body, timeoutMs = 30000) {
 
 /**
  * OpenClaw Gateway HTTP client for spawning and monitoring sessions.
+ *
+ * @module
  */
 /** Make an HTTP POST request to the Gateway /tools/invoke endpoint. */
 function invokeGateway(url, token, tool, args, timeoutMs = 30000) {
@@ -534,6 +914,8 @@ function createGatewayClient(options) {
 
 /**
  * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ *
+ * @module
  */
 /** Post a message to Slack via chat.postMessage API. */
 async function postToSlack(token, channel, text) {
@@ -551,21 +933,21 @@ function createNotifier(config) {
     return {
         async notifySuccess(jobName, durationMs, channel) {
             if (!slackToken) {
-                console.warn(`No Slack token configured � skipping success notification for ${jobName}`);
+                console.warn(`No Slack token configured \u2014 skipping success notification for ${jobName}`);
                 return;
             }
             const durationSec = (durationMs / 1000).toFixed(1);
-            const text = `?? *${jobName}* completed (${durationSec}s)`;
+            const text = `\u2705 *${jobName}* completed (${durationSec}s)`;
             await postToSlack(slackToken, channel, text);
         },
         async notifyFailure(jobName, durationMs, error, channel) {
             if (!slackToken) {
-                console.warn(`No Slack token configured � skipping failure notification for ${jobName}`);
+                console.warn(`No Slack token configured \u2014 skipping failure notification for ${jobName}`);
                 return;
             }
             const durationSec = (durationMs / 1000).toFixed(1);
             const errorMsg = error ? `: ${error}` : '';
-            const text = `?? *${jobName}* failed (${durationSec}s)${errorMsg}`;
+            const text = `\u274c *${jobName}* failed (${durationSec}s)${errorMsg}`;
             await postToSlack(slackToken, channel, text);
         },
         async dispatchResult(result, jobName, onSuccess, onFailure, logger) {
@@ -585,6 +967,8 @@ function createNotifier(config) {
 
 /**
  * Job executor. Spawns job scripts as child processes, captures output, parses result metadata, enforces timeouts.
+ *
+ * @module
  */
 /** Ring buffer for capturing last N lines of output. */
 class RingBuffer {
@@ -646,14 +1030,23 @@ function resolveCommand(script) {
  * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
  */
 function executeJob(options) {
-    const { script, dbPath, jobId, runId, timeoutMs, commandResolver } = options;
+    const { script, dbPath, jobId, runId, timeoutMs, commandResolver, sourceType = 'path', } = options;
     const startTime = Date.now();
+    // For inline scripts, write to a temp file and clean up after.
+    let tempFile = null;
+    let effectiveScript = script;
+    if (sourceType === 'inline') {
+        const tempDir = mkdtempSync(join(tmpdir(), 'jr-inline-'));
+        tempFile = join(tempDir, 'inline.js');
+        writeFileSync(tempFile, script);
+        effectiveScript = tempFile;
+    }
     return new Promise((resolve) => {
         const stdoutBuffer = new RingBuffer(100);
         const stderrBuffer = new RingBuffer(100);
         const { command, args } = commandResolver
-            ? commandResolver(script)
-            : resolveCommand(script);
+            ? commandResolver(effectiveScript)
+            : resolveCommand(effectiveScript);
         const child = spawn(command, args, {
             env: {
                 ...process.env,
@@ -689,6 +1082,7 @@ function executeJob(options) {
         child.on('close', (exitCode) => {
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
+            cleanupTempFile(tempFile);
             const durationMs = Date.now() - startTime;
             const stdoutTail = stdoutBuffer.getAll();
             const stderrTail = stderrBuffer.getAll();
@@ -733,6 +1127,7 @@ function executeJob(options) {
         child.on('error', (err) => {
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
+            cleanupTempFile(tempFile);
             const durationMs = Date.now() - startTime;
             resolve({
                 status: 'error',
@@ -747,31 +1142,73 @@ function executeJob(options) {
         });
     });
 }
+/** Remove a temp file created for inline script execution. */
+function cleanupTempFile(tempFile) {
+    if (!tempFile)
+        return;
+    try {
+        unlinkSync(tempFile);
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
 
 /**
- * Cron registration and reconciliation utilities.
+ * Schedule registration and reconciliation. Supports cron (croner) and RRStack schedule formats via unified setTimeout-based scheduling.
+ *
+ * @module
  */
+/** Maximum setTimeout delay (Node.js limit: ~24.8 days). */
+const MAX_TIMEOUT_MS = 2_147_483_647;
 function createCronRegistry(deps) {
     const { db, logger, onScheduledRun } = deps;
-    const crons = new Map();
-    const cronSchedules = new Map();
+    const handles = new Map();
+    const scheduleStrings = new Map();
     const failedRegistrations = new Set();
-    function registerCron(job) {
+    /**
+     * Schedule the next fire for a job. Computes next fire time, sets a
+     * setTimeout, and re-arms after each fire.
+     */
+    function scheduleNext(jobId, schedule) {
+        const nextDate = getNextFireTime(schedule);
+        if (!nextDate) {
+            logger.warn({ jobId }, 'No upcoming fire time, job will not fire');
+            return;
+        }
+        const delayMs = Math.max(0, nextDate.getTime() - Date.now());
+        // Node.js setTimeout max is ~24.8 days. If delay exceeds that,
+        // set an intermediate wakeup and re-check.
+        const effectiveDelay = Math.min(delayMs, MAX_TIMEOUT_MS);
+        const isIntermediate = delayMs > MAX_TIMEOUT_MS;
+        const timeout = setTimeout(() => {
+            if (isIntermediate) {
+                // Woke up early just to re-check; schedule again.
+                scheduleNext(jobId, schedule);
+                return;
+            }
+            // Re-read job from DB to get current configuration
+            const currentJob = db
+                .prepare('SELECT * FROM jobs WHERE id = ? AND enabled = 1')
+                .get(jobId);
+            if (!currentJob) {
+                logger.warn({ jobId }, 'Job no longer exists or disabled, skipping');
+                return;
+            }
+            onScheduledRun(currentJob);
+            // Re-arm for the next occurrence
+            scheduleNext(jobId, schedule);
+        }, effectiveDelay);
+        handles.set(jobId, {
+            cancel: () => {
+                clearTimeout(timeout);
+            },
+        });
+    }
+    function registerSchedule(job) {
         try {
-            const jobId = job.id;
-            const cron = new Cron(job.schedule, () => {
-                // Re-read job from DB to get current configuration
-                const currentJob = db
-                    .prepare('SELECT * FROM jobs WHERE id = ? AND enabled = 1')
-                    .get(jobId);
-                if (!currentJob) {
-                    logger.warn({ jobId }, 'Job no longer exists or disabled, skipping');
-                    return;
-                }
-                onScheduledRun(currentJob);
-            });
-            crons.set(job.id, cron);
-            cronSchedules.set(job.id, job.schedule);
+            scheduleNext(job.id, job.schedule);
+            scheduleStrings.set(job.id, job.schedule);
             failedRegistrations.delete(job.id);
             logger.info({ jobId: job.id, schedule: job.schedule }, 'Scheduled job');
             return true;
@@ -788,39 +1225,39 @@ function createCronRegistry(deps) {
             .all();
         const enabledById = new Map(enabledJobs.map((j) => [j.id, j]));
         // Remove disabled/deleted jobs
-        for (const [jobId, cron] of crons.entries()) {
+        for (const [jobId, handle] of handles.entries()) {
             if (!enabledById.has(jobId)) {
-                cron.stop();
-                crons.delete(jobId);
-                cronSchedules.delete(jobId);
+                handle.cancel();
+                handles.delete(jobId);
+                scheduleStrings.delete(jobId);
             }
         }
         const failedIds = [];
         // Add or update enabled jobs
         for (const job of enabledJobs) {
-            const existingCron = crons.get(job.id);
-            const existingSchedule = cronSchedules.get(job.id);
-            if (!existingCron) {
-                if (!registerCron(job))
+            const existingHandle = handles.get(job.id);
+            const existingSchedule = scheduleStrings.get(job.id);
+            if (!existingHandle) {
+                if (!registerSchedule(job))
                     failedIds.push(job.id);
                 continue;
             }
             if (existingSchedule !== job.schedule) {
-                existingCron.stop();
-                crons.delete(job.id);
-                cronSchedules.delete(job.id);
-                if (!registerCron(job))
+                existingHandle.cancel();
+                handles.delete(job.id);
+                scheduleStrings.delete(job.id);
+                if (!registerSchedule(job))
                     failedIds.push(job.id);
             }
         }
         return { totalEnabled: enabledJobs.length, failedIds };
     }
     function stopAll() {
-        for (const cron of crons.values()) {
-            cron.stop();
+        for (const handle of handles.values()) {
+            handle.cancel();
         }
-        crons.clear();
-        cronSchedules.clear();
+        handles.clear();
+        scheduleStrings.clear();
     }
     return {
         reconcile,
@@ -833,6 +1270,8 @@ function createCronRegistry(deps) {
 
 /**
  * Run record repository for managing job execution records.
+ *
+ * @module
  */
 /** Create a run repository for the given database connection. */
 function createRunRepository(db) {
@@ -854,6 +1293,8 @@ function createRunRepository(db) {
 
 /**
  * Session executor for job type='session'. Spawns OpenClaw Gateway sessions and polls for completion.
+ *
+ * @module
  */
 /** File extensions that indicate a script rather than a prompt. */
 const SCRIPT_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ps1', '.cmd', '.bat'];
@@ -953,7 +1394,9 @@ async function executeSession(options) {
 }
 
 /**
- * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
+ * Job scheduler. Loads enabled jobs, registers schedules (cron or rrstack), manages execution, respects overlap policies and concurrency limits.
+ *
+ * @module
  */
 // JobRow is imported from cron-registry
 /**
@@ -973,7 +1416,7 @@ function createScheduler(deps) {
     let reconcileInterval = null;
     /** Execute a job: create run record, run script, update record, send notifications. */
     async function runJob(job, trigger) {
-        const { id, name, script, type, timeout_ms, on_success, on_failure } = job;
+        const { id, name, script, type, timeout_ms, on_success, on_failure, source_type, } = job;
         // Check concurrency limit
         if (runningJobs.size >= config.maxConcurrency) {
             logger.warn({ jobId: id }, 'Max concurrency reached, skipping job');
@@ -1004,6 +1447,7 @@ function createScheduler(deps) {
                     jobId: id,
                     runId,
                     timeoutMs: timeout_ms ?? undefined,
+                    sourceType: source_type ?? 'path',
                 });
             }
             runRepository.finishRun(runId, result);
@@ -1093,6 +1537,8 @@ function createScheduler(deps) {
 
 /**
  * Main runner orchestrator. Wires up database, scheduler, API server, and handles graceful shutdown on SIGTERM/SIGINT.
+ *
+ * @module
  */
 /**
  * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
@@ -1163,7 +1609,7 @@ function createRunner(config, deps) {
                 getConfig: () => config,
                 loggerConfig: { level: config.log.level, file: config.log.file },
             });
-            await server.listen({ port: config.port, host: '127.0.0.1' });
+            await server.listen({ port: config.port, host: config.host });
             logger.info({ port: config.port }, 'API server listening');
             // Graceful shutdown
             const shutdown = async (signal) => {
@@ -1234,6 +1680,8 @@ const gatewaySchema = z.object({
 const runnerConfigSchema = z.object({
     /** HTTP server port for the runner API. */
     port: z.number().default(1937),
+    /** Bind address for the HTTP server. */
+    host: z.string().default('127.0.0.1'),
     /** Path to SQLite database file. */
     dbPath: z.string().default('./data/runner.sqlite'),
     /** Maximum number of concurrent job executions. */
@@ -1265,6 +1713,7 @@ const runnerConfigSchema = z.object({
 /** Minimal starter config template. */
 const INIT_CONFIG_TEMPLATE = {
     port: 1937,
+    host: '127.0.0.1',
     dbPath: './data/runner.sqlite',
     maxConcurrency: 4,
     runRetentionDays: 30,
@@ -1539,12 +1988,10 @@ program
     .option('-c, --config <path>', 'Path to config file')
     .action((options) => {
     const config = loadConfig(options.config);
-    // Validate schedule expression before inserting
-    try {
-        new CronPattern(options.schedule);
-    }
-    catch (err) {
-        console.error(`Invalid schedule expression: ${err instanceof Error ? err.message : String(err)}`);
+    // Validate schedule expression (cron or rrstack) before inserting
+    const scheduleValidation = validateSchedule(options.schedule);
+    if (!scheduleValidation.valid) {
+        console.error(`Invalid schedule: ${scheduleValidation.error}`);
         process.exit(1);
     }
     // Validate overlap_policy