@karmaniverous/jeeves-runner 0.1.0

package/dist/mjs/index.js

@@ -0,0 +1,917 @@
+import { z } from 'zod';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { pino } from 'pino';
+import Fastify from 'fastify';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { request } from 'node:https';
+import { spawn } from 'node:child_process';
+import { Cron } from 'croner';
+
+/**
+ * Runner configuration schema and types.
+ *
+ * @module
+ */
+/** Notification configuration sub-schema. */
+const notificationsSchema = z.object({
+    slackTokenPath: z.string().optional(),
+    defaultOnFailure: z.string().nullable().default(null),
+    defaultOnSuccess: z.string().nullable().default(null),
+});
+/** Log configuration sub-schema. */
+const logSchema = z.object({
+    level: z
+        .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
+        .default('info'),
+    file: z.string().optional(),
+});
+/** Full runner configuration schema. Validates and provides defaults. */
+const runnerConfigSchema = z.object({
+    port: z.number().default(3100),
+    dbPath: z.string().default('./data/runner.sqlite'),
+    maxConcurrency: z.number().default(4),
+    runRetentionDays: z.number().default(30),
+    cursorCleanupIntervalMs: z.number().default(3600000),
+    shutdownGraceMs: z.number().default(30000),
+    notifications: notificationsSchema.default({
+        defaultOnFailure: null,
+        defaultOnSuccess: null,
+    }),
+    log: logSchema.default({ level: 'info' }),
+});
+
+/**
+ * Job definition schema and types.
+ *
+ * @module
+ */
+const jobSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    schedule: z.string(),
+    script: z.string(),
+    type: z.enum(['script', 'session']).default('script'),
+    description: z.string().optional(),
+    enabled: z.boolean().default(true),
+    timeoutMs: z.number().optional(),
+    overlapPolicy: z.enum(['skip', 'queue', 'allow']).default('skip'),
+    onFailure: z.string().nullable().default(null),
+    onSuccess: z.string().nullable().default(null),
+});
+
+/**
+ * Run record schema and types.
+ *
+ * @module
+ */
+const runStatusSchema = z.enum([
+    'pending',
+    'running',
+    'ok',
+    'error',
+    'timeout',
+    'skipped',
+]);
+const runTriggerSchema = z.enum(['schedule', 'manual', 'retry']);
+const runSchema = z.object({
+    id: z.number(),
+    jobId: z.string(),
+    status: runStatusSchema,
+    startedAt: z.string().optional(),
+    finishedAt: z.string().optional(),
+    durationMs: z.number().optional(),
+    exitCode: z.number().optional(),
+    tokens: z.number().optional(),
+    resultMeta: z.string().optional(),
+    error: z.string().optional(),
+    stdoutTail: z.string().optional(),
+    stderrTail: z.string().optional(),
+    trigger: runTriggerSchema.default('schedule'),
+});
+
+/**
+ * Fastify API routes for job management and monitoring. Provides endpoints for job CRUD, run history, manual triggers, and system stats.
+ */
+/**
+ * Register all API routes on the Fastify instance.
+ */
+function registerRoutes(app, deps) {
+    const { db, scheduler } = deps;
+    /** GET /health — Health check. */
+    app.get('/health', () => {
+        return { ok: true, uptime: process.uptime() };
+    });
+    /** GET /jobs — List all jobs with last run status. */
+    app.get('/jobs', () => {
+        const rows = db
+            .prepare(`SELECT j.*, 
+          (SELECT status FROM runs WHERE job_id = j.id ORDER BY started_at DESC LIMIT 1) as last_status,
+          (SELECT started_at FROM runs WHERE job_id = j.id ORDER BY started_at DESC LIMIT 1) as last_run
+         FROM jobs j`)
+            .all();
+        return { jobs: rows };
+    });
+    /** GET /jobs/:id — Single job detail. */
+    app.get('/jobs/:id', async (request, reply) => {
+        const job = db
+            .prepare('SELECT * FROM jobs WHERE id = ?')
+            .get(request.params.id);
+        if (!job) {
+            reply.code(404);
+            return { error: 'Job not found' };
+        }
+        return { job };
+    });
+    /** GET /jobs/:id/runs — Run history for a job. */
+    app.get('/jobs/:id/runs', (request) => {
+        const limit = parseInt(request.query.limit ?? '50', 10);
+        const runs = db
+            .prepare('SELECT * FROM runs WHERE job_id = ? ORDER BY started_at DESC LIMIT ?')
+            .all(request.params.id, limit);
+        return { runs };
+    });
+    /** POST /jobs/:id/run — Trigger manual job run. */
+    app.post('/jobs/:id/run', async (request, reply) => {
+        try {
+            const result = await scheduler.triggerJob(request.params.id);
+            return { result };
+        }
+        catch (err) {
+            reply.code(404);
+            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' };
+        }
+        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' };
+        }
+        return { ok: true };
+    });
+    /** GET /stats — Aggregate job statistics. */
+    app.get('/stats', () => {
+        const totalJobs = db
+            .prepare('SELECT COUNT(*) as count FROM jobs')
+            .get();
+        const runningCount = scheduler.getRunningJobs().length;
+        const okLastHour = db
+            .prepare(`SELECT COUNT(*) as count FROM runs 
+         WHERE status = 'ok' AND started_at > datetime('now', '-1 hour')`)
+            .get();
+        const errorsLastHour = db
+            .prepare(`SELECT COUNT(*) as count FROM runs 
+         WHERE status IN ('error', 'timeout') AND started_at > datetime('now', '-1 hour')`)
+            .get();
+        return {
+            totalJobs: totalJobs.count,
+            running: runningCount,
+            okLastHour: okLastHour.count,
+            errorsLastHour: errorsLastHour.count,
+        };
+    });
+}
+
+/**
+ * Fastify HTTP server for runner API. Creates server instance with logging, registers routes, listens on configured port (localhost only).
+ */
+/**
+ * Create and configure the Fastify server. Routes are registered but server is not started.
+ */
+function createServer(config, deps) {
+    const app = Fastify({
+        logger: {
+            level: config.log.level,
+            ...(config.log.file
+                ? {
+                    transport: {
+                        target: 'pino/file',
+                        options: { destination: config.log.file },
+                    },
+                }
+                : {}),
+        },
+    });
+    registerRoutes(app, deps);
+    return app;
+}
+
+/**
+ * SQLite connection manager. Creates DB file with parent directories, enables WAL mode for concurrency.
+ */
+/**
+ * Create and configure a SQLite database connection.
+ * Ensures parent directories exist and enables WAL mode for better concurrency.
+ */
+function createConnection(dbPath) {
+    // Ensure parent directory exists
+    const dir = dirname(dbPath);
+    mkdirSync(dir, { recursive: true });
+    // Open database
+    const db = new DatabaseSync(dbPath);
+    // Enable WAL mode for better concurrency
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    return db;
+}
+/**
+ * Close a database connection cleanly.
+ */
+function closeConnection(db) {
+    db.close();
+}
+
+/**
+ * Database maintenance tasks: run retention pruning and expired cursor cleanup.
+ */
+/** Delete runs older than the configured retention period. */
+function pruneOldRuns(db, days, logger) {
+    const result = db
+        .prepare(`DELETE FROM runs WHERE started_at < datetime('now', '-${String(days)} days')`)
+        .run();
+    if (result.changes > 0) {
+        logger.info({ deleted: result.changes }, 'Pruned old runs');
+    }
+}
+/** Delete expired cursor entries. */
+function cleanExpiredCursors(db, logger) {
+    const result = db
+        .prepare(`DELETE FROM cursors WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
+        .run();
+    if (result.changes > 0) {
+        logger.info({ deleted: result.changes }, 'Cleaned expired cursors');
+    }
+}
+/**
+ * Create the maintenance controller. Runs cleanup tasks on startup and at configured intervals.
+ */
+function createMaintenance(db, config, logger) {
+    let interval = null;
+    function runAll() {
+        pruneOldRuns(db, config.runRetentionDays, logger);
+        cleanExpiredCursors(db, logger);
+    }
+    return {
+        start() {
+            // Run immediately on startup
+            runAll();
+            // Then run periodically
+            interval = setInterval(runAll, config.cursorCleanupIntervalMs);
+        },
+        stop() {
+            if (interval) {
+                clearInterval(interval);
+                interval = null;
+            }
+        },
+        runNow() {
+            runAll();
+        },
+    };
+}
+
+/**
+ * Schema migration runner. Tracks applied migrations via schema_version table, applies pending migrations idempotently.
+ */
+/** Initial schema migration SQL (embedded to avoid runtime file resolution issues). */
+const MIGRATION_001 = `
+CREATE TABLE IF NOT EXISTS jobs (
+    id              TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    schedule        TEXT NOT NULL,
+    script          TEXT NOT NULL,
+    type            TEXT DEFAULT 'script',
+    description     TEXT,
+    enabled         INTEGER DEFAULT 1,
+    timeout_ms      INTEGER,
+    overlap_policy  TEXT DEFAULT 'skip',
+    on_failure      TEXT,
+    on_success      TEXT,
+    created_at      TEXT DEFAULT (datetime('now')),
+    updated_at      TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS runs (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id          TEXT NOT NULL REFERENCES jobs(id),
+    status          TEXT NOT NULL,
+    started_at      TEXT,
+    finished_at     TEXT,
+    duration_ms     INTEGER,
+    exit_code       INTEGER,
+    tokens          INTEGER,
+    result_meta     TEXT,
+    error           TEXT,
+    stdout_tail     TEXT,
+    stderr_tail     TEXT,
+    trigger         TEXT DEFAULT 'schedule'
+);
+
+CREATE INDEX IF NOT EXISTS idx_runs_job_started ON runs(job_id, started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);
+
+CREATE TABLE IF NOT EXISTS cursors (
+    namespace       TEXT NOT NULL,
+    key             TEXT NOT NULL,
+    value           TEXT,
+    expires_at      TEXT,
+    updated_at      TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (namespace, key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cursors_expires ON cursors(expires_at) WHERE expires_at IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS queues (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    queue           TEXT NOT NULL,
+    payload         TEXT NOT NULL,
+    status          TEXT DEFAULT 'pending',
+    priority        INTEGER DEFAULT 0,
+    attempts        INTEGER DEFAULT 0,
+    max_attempts    INTEGER DEFAULT 1,
+    error           TEXT,
+    created_at      TEXT DEFAULT (datetime('now')),
+    claimed_at      TEXT,
+    finished_at     TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_queues_poll ON queues(queue, status, priority DESC, created_at);
+`;
+/** Registry of all migrations keyed by version number. */
+const MIGRATIONS = {
+    1: MIGRATION_001,
+};
+/**
+ * Run all pending migrations. Creates schema_version table if needed, applies migrations in order.
+ */
+function runMigrations(db) {
+    // Create schema_version table if it doesn't exist
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT DEFAULT (datetime('now'))
+    );
+  `);
+    // Get current version
+    const currentVersionRow = db
+        .prepare('SELECT MAX(version) as version FROM schema_version')
+        .get();
+    const currentVersion = currentVersionRow?.version ?? 0;
+    // Apply pending migrations
+    const pendingVersions = Object.keys(MIGRATIONS)
+        .map(Number)
+        .filter((v) => v > currentVersion)
+        .sort((a, b) => a - b);
+    for (const version of pendingVersions) {
+        db.exec(MIGRATIONS[version]);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(version);
+    }
+}
+
+/**
+ * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ */
+/** Post a message to Slack via chat.postMessage API. */
+function postToSlack(token, channel, text) {
+    return new Promise((resolve, reject) => {
+        const payload = JSON.stringify({ channel, text });
+        const req = request('https://slack.com/api/chat.postMessage', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+                'Content-Length': Buffer.byteLength(payload),
+            },
+        }, (res) => {
+            let body = '';
+            res.on('data', (chunk) => {
+                body += chunk.toString();
+            });
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Slack API returned ${String(res.statusCode)}: ${body}`));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.write(payload);
+        req.end();
+    });
+}
+/**
+ * Create a notifier that sends Slack messages for job events. If no token, logs warning and returns silently.
+ */
+function createNotifier(config) {
+    const { slackToken } = config;
+    return {
+        async notifySuccess(jobName, durationMs, channel) {
+            if (!slackToken) {
+                console.warn(`No Slack token configured — skipping success notification for ${jobName}`);
+                return;
+            }
+            const durationSec = (durationMs / 1000).toFixed(1);
+            const text = `✅ *${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}`);
+                return;
+            }
+            const durationSec = (durationMs / 1000).toFixed(1);
+            const errorMsg = error ? `: ${error}` : '';
+            const text = `⚠️ *${jobName}* failed (${durationSec}s)${errorMsg}`;
+            await postToSlack(slackToken, channel, text);
+        },
+    };
+}
+
+/**
+ * Job executor. Spawns job scripts as child processes, captures output, parses result metadata, enforces timeouts.
+ */
+/** Ring buffer for capturing last N lines of output. */
+class RingBuffer {
+    maxLines;
+    lines = [];
+    constructor(maxLines) {
+        this.maxLines = maxLines;
+    }
+    append(line) {
+        this.lines.push(line);
+        if (this.lines.length > this.maxLines) {
+            this.lines.shift();
+        }
+    }
+    getAll() {
+        return this.lines.join('\n');
+    }
+}
+/** Parse JR_RESULT:\{json\} lines from stdout to extract tokens and resultMeta. */
+function parseResultLines(stdout) {
+    const lines = stdout.split('\n');
+    let tokens = null;
+    let resultMeta = null;
+    for (const line of lines) {
+        const match = /^JR_RESULT:(.+)$/.exec(line.trim());
+        if (match) {
+            try {
+                const data = JSON.parse(match[1]);
+                if (data.tokens !== undefined)
+                    tokens = data.tokens;
+                if (data.meta !== undefined)
+                    resultMeta = data.meta;
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    return { tokens, resultMeta };
+}
+/**
+ * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
+ */
+function executeJob(options) {
+    const { script, dbPath, jobId, runId, timeoutMs } = options;
+    const startTime = Date.now();
+    return new Promise((resolve) => {
+        const stdoutBuffer = new RingBuffer(100);
+        const stderrBuffer = new RingBuffer(100);
+        const child = spawn('node', [script], {
+            env: {
+                ...process.env,
+                JR_DB_PATH: dbPath,
+                JR_JOB_ID: jobId,
+                JR_RUN_ID: String(runId),
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let timedOut = false;
+        let timeoutHandle = null;
+        if (timeoutMs) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+                setTimeout(() => child.kill('SIGKILL'), 5000); // Force kill after 5s
+            }, timeoutMs);
+        }
+        child.stdout.on('data', (chunk) => {
+            const lines = chunk.toString().split('\n');
+            for (const line of lines) {
+                if (line.trim())
+                    stdoutBuffer.append(line);
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            const lines = chunk.toString().split('\n');
+            for (const line of lines) {
+                if (line.trim())
+                    stderrBuffer.append(line);
+            }
+        });
+        child.on('close', (exitCode) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            const durationMs = Date.now() - startTime;
+            const stdoutTail = stdoutBuffer.getAll();
+            const stderrTail = stderrBuffer.getAll();
+            const { tokens, resultMeta } = parseResultLines(stdoutTail);
+            if (timedOut) {
+                resolve({
+                    status: 'timeout',
+                    exitCode: null,
+                    durationMs,
+                    tokens: null,
+                    resultMeta: null,
+                    stdoutTail,
+                    stderrTail,
+                    error: `Job timed out after ${String(timeoutMs)}ms`,
+                });
+            }
+            else if (exitCode === 0) {
+                resolve({
+                    status: 'ok',
+                    exitCode,
+                    durationMs,
+                    tokens,
+                    resultMeta,
+                    stdoutTail,
+                    stderrTail,
+                    error: null,
+                });
+            }
+            else {
+                resolve({
+                    status: 'error',
+                    exitCode,
+                    durationMs,
+                    tokens,
+                    resultMeta,
+                    stdoutTail,
+                    stderrTail,
+                    error: stderrTail || `Exit code ${String(exitCode)}`,
+                });
+            }
+        });
+        child.on('error', (err) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            const durationMs = Date.now() - startTime;
+            resolve({
+                status: 'error',
+                exitCode: null,
+                durationMs,
+                tokens: null,
+                resultMeta: null,
+                stdoutTail: stdoutBuffer.getAll(),
+                stderrTail: stderrBuffer.getAll(),
+                error: err.message,
+            });
+        });
+    });
+}
+
+/**
+ * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
+ */
+/**
+ * Create the job scheduler. Manages cron schedules, job execution, overlap policies, and notifications.
+ */
+function createScheduler(deps) {
+    const { db, executor, notifier, config, logger } = deps;
+    const crons = new Map();
+    const runningJobs = new Set();
+    /** Insert a run record and return its ID. */
+    function createRun(jobId, trigger) {
+        const result = db
+            .prepare(`INSERT INTO runs (job_id, status, started_at, trigger) 
+         VALUES (?, 'running', datetime('now'), ?)`)
+            .run(jobId, trigger);
+        return result.lastInsertRowid;
+    }
+    /** Update run record with completion data. */
+    function finishRun(runId, execResult) {
+        db.prepare(`UPDATE runs SET status = ?, finished_at = datetime('now'), duration_ms = ?, 
+       exit_code = ?, tokens = ?, result_meta = ?, error = ?, stdout_tail = ?, stderr_tail = ?
+       WHERE id = ?`).run(execResult.status, execResult.durationMs, execResult.exitCode, execResult.tokens, execResult.resultMeta, execResult.error, execResult.stdoutTail, execResult.stderrTail, runId);
+    }
+    /** Execute a job: create run record, run script, update record, send notifications. */
+    async function runJob(job, trigger) {
+        const { id, name, script, timeout_ms, on_success, on_failure } = job;
+        // Check concurrency limit
+        if (runningJobs.size >= config.maxConcurrency) {
+            logger.warn({ jobId: id }, 'Max concurrency reached, skipping job');
+            throw new Error('Max concurrency reached');
+        }
+        runningJobs.add(id);
+        const runId = createRun(id, trigger);
+        logger.info({ jobId: id, runId, trigger }, 'Starting job');
+        try {
+            const result = await executor({
+                script,
+                dbPath: config.dbPath,
+                jobId: id,
+                runId,
+                timeoutMs: timeout_ms ?? undefined,
+            });
+            finishRun(runId, result);
+            logger.info({ jobId: id, runId, status: result.status }, 'Job finished');
+            // Send notifications
+            if (result.status === 'ok' && on_success) {
+                await notifier
+                    .notifySuccess(name, result.durationMs, on_success)
+                    .catch((err) => {
+                    logger.error({ jobId: id, err }, 'Notification failed');
+                });
+            }
+            else if (result.status !== 'ok' && on_failure) {
+                await notifier
+                    .notifyFailure(name, result.durationMs, result.error, on_failure)
+                    .catch((err) => {
+                    logger.error({ jobId: id, err }, 'Notification failed');
+                });
+            }
+            return result;
+        }
+        finally {
+            runningJobs.delete(id);
+        }
+    }
+    /** Handle scheduled job fire. */
+    async function onScheduledRun(job) {
+        const { id, overlap_policy } = job;
+        // Check overlap policy
+        if (runningJobs.has(id)) {
+            if (overlap_policy === 'skip') {
+                logger.info({ jobId: id }, 'Job already running, skipping (overlap_policy=skip)');
+                return;
+            }
+            else if (overlap_policy === 'queue') {
+                logger.info({ jobId: id }, 'Job already running, queueing (overlap_policy=queue)');
+                // In a real implementation, we'd queue this. For now, just skip.
+                return;
+            }
+            // 'allow' policy: proceed
+        }
+        await runJob(job, 'schedule').catch((err) => {
+            logger.error({ jobId: id, err }, 'Job execution failed');
+        });
+    }
+    return {
+        start() {
+            // Load all enabled jobs
+            const jobs = db
+                .prepare('SELECT * FROM jobs WHERE enabled = 1')
+                .all();
+            logger.info({ count: jobs.length }, 'Loading jobs');
+            for (const job of jobs) {
+                try {
+                    const cron = new Cron(job.schedule, () => {
+                        void onScheduledRun(job);
+                    });
+                    crons.set(job.id, cron);
+                    logger.info({ jobId: job.id, schedule: job.schedule }, 'Scheduled job');
+                }
+                catch (err) {
+                    logger.error({ jobId: job.id, err }, 'Failed to schedule job');
+                }
+            }
+        },
+        stop() {
+            logger.info('Stopping scheduler');
+            // Stop all crons
+            for (const cron of crons.values()) {
+                cron.stop();
+            }
+            crons.clear();
+            // Wait for running jobs (simple poll with timeout)
+            const deadline = Date.now() + config.shutdownGraceMs;
+            const checkInterval = setInterval(() => {
+                if (runningJobs.size === 0 || Date.now() > deadline) {
+                    clearInterval(checkInterval);
+                    if (runningJobs.size > 0) {
+                        logger.warn({ count: runningJobs.size }, 'Forced shutdown with running jobs');
+                    }
+                }
+            }, 100);
+        },
+        async triggerJob(jobId) {
+            const job = db.prepare('SELECT * FROM jobs WHERE id = ?').get(jobId);
+            if (!job)
+                throw new Error(`Job not found: ${jobId}`);
+            return runJob(job, 'manual');
+        },
+        getRunningJobs() {
+            return Array.from(runningJobs);
+        },
+    };
+}
+
+/**
+ * Main runner orchestrator. Wires up database, scheduler, API server, and handles graceful shutdown on SIGTERM/SIGINT.
+ */
+/**
+ * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
+ */
+function createRunner(config) {
+    let db = null;
+    let scheduler = null;
+    let server = null;
+    let maintenance = null;
+    const logger = pino({
+        level: config.log.level,
+        ...(config.log.file
+            ? {
+                transport: {
+                    target: 'pino/file',
+                    options: { destination: config.log.file },
+                },
+            }
+            : {}),
+    });
+    return {
+        async start() {
+            logger.info('Starting runner');
+            // Database
+            db = createConnection(config.dbPath);
+            runMigrations(db);
+            logger.info({ dbPath: config.dbPath }, 'Database ready');
+            // Notifier
+            const slackToken = config.notifications.slackTokenPath
+                ? readFileSync(config.notifications.slackTokenPath, 'utf-8').trim()
+                : null;
+            const notifier = createNotifier({ slackToken });
+            // Maintenance (run retention pruning + cursor cleanup)
+            maintenance = createMaintenance(db, {
+                runRetentionDays: config.runRetentionDays,
+                cursorCleanupIntervalMs: config.cursorCleanupIntervalMs,
+            }, logger);
+            maintenance.start();
+            logger.info('Maintenance tasks started');
+            // Scheduler
+            scheduler = createScheduler({
+                db,
+                executor: executeJob,
+                notifier,
+                config,
+                logger,
+            });
+            scheduler.start();
+            logger.info('Scheduler started');
+            // API server
+            server = createServer(config, { db, scheduler });
+            await server.listen({ port: config.port, host: '127.0.0.1' });
+            logger.info({ port: config.port }, 'API server listening');
+            // Graceful shutdown
+            const shutdown = async (signal) => {
+                logger.info({ signal }, 'Received shutdown signal');
+                await this.stop();
+                process.exit(0);
+            };
+            process.on('SIGTERM', () => {
+                void shutdown('SIGTERM');
+            });
+            process.on('SIGINT', () => {
+                void shutdown('SIGINT');
+            });
+        },
+        async stop() {
+            logger.info('Stopping runner');
+            if (maintenance) {
+                maintenance.stop();
+                logger.info('Maintenance stopped');
+            }
+            if (scheduler) {
+                scheduler.stop();
+                logger.info('Scheduler stopped');
+            }
+            if (server) {
+                await server.close();
+                logger.info('API server stopped');
+            }
+            if (db) {
+                closeConnection(db);
+                logger.info('Database closed');
+            }
+        },
+    };
+}
+
+/**
+ * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ */
+/** Parse TTL string (e.g., '30d', '24h', '60m') into ISO datetime offset from now. */
+function parseTtl(ttl) {
+    const match = /^(\d+)([dhm])$/.exec(ttl);
+    if (!match)
+        throw new Error(`Invalid TTL format: ${ttl}`);
+    const amount = match[1];
+    const unit = match[2];
+    if (!amount || !unit)
+        throw new Error(`Invalid TTL format: ${ttl}`);
+    const num = parseInt(amount, 10);
+    let modifier;
+    switch (unit) {
+        case 'd':
+            modifier = `+${String(num)} days`;
+            break;
+        case 'h':
+            modifier = `+${String(num)} hours`;
+            break;
+        case 'm':
+            modifier = `+${String(num)} minutes`;
+            break;
+        default:
+            throw new Error(`Unknown TTL unit: ${unit}`);
+    }
+    return `datetime('now', '${modifier}')`;
+}
+/**
+ * Create a runner client for job scripts. Opens its own DB connection.
+ */
+function createClient(dbPath) {
+    const path = dbPath ?? process.env.JR_DB_PATH;
+    if (!path)
+        throw new Error('DB path required (provide dbPath or set JR_DB_PATH env var)');
+    const db = createConnection(path);
+    return {
+        getCursor(namespace, key) {
+            const row = db
+                .prepare(`SELECT value FROM cursors 
+           WHERE namespace = ? AND key = ? 
+           AND (expires_at IS NULL OR expires_at > datetime('now'))`)
+                .get(namespace, key);
+            return row?.value ?? null;
+        },
+        setCursor(namespace, key, value, options) {
+            const expiresAt = options?.ttl ? parseTtl(options.ttl) : null;
+            const sql = expiresAt
+                ? `INSERT INTO cursors (namespace, key, value, expires_at) VALUES (?, ?, ?, ${expiresAt})
+           ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at, updated_at = datetime('now')`
+                : `INSERT INTO cursors (namespace, key, value) VALUES (?, ?, ?)
+           ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')`;
+            db.prepare(sql).run(namespace, key, value);
+        },
+        deleteCursor(namespace, key) {
+            db.prepare('DELETE FROM cursors WHERE namespace = ? AND key = ?').run(namespace, key);
+        },
+        enqueue(queue, payload, options) {
+            const priority = options?.priority ?? 0;
+            const maxAttempts = options?.maxAttempts ?? 1;
+            const payloadJson = JSON.stringify(payload);
+            const result = db
+                .prepare('INSERT INTO queues (queue, payload, priority, max_attempts) VALUES (?, ?, ?, ?)')
+                .run(queue, payloadJson, priority, maxAttempts);
+            return result.lastInsertRowid;
+        },
+        dequeue(queue, count = 1) {
+            // First, SELECT the items to claim (with correct ordering)
+            const rows = db
+                .prepare(`SELECT id, payload FROM queues 
+           WHERE queue = ? AND status = 'pending' 
+           ORDER BY priority DESC, created_at 
+           LIMIT ?`)
+                .all(queue, count);
+            // Then UPDATE each one to claim it
+            const updateStmt = db.prepare(`UPDATE queues 
+         SET status = 'processing', claimed_at = datetime('now'), attempts = attempts + 1
+         WHERE id = ?`);
+            for (const row of rows) {
+                updateStmt.run(row.id);
+            }
+            return rows.map((row) => ({
+                id: row.id,
+                payload: JSON.parse(row.payload),
+            }));
+        },
+        done(queueItemId) {
+            db.prepare(`UPDATE queues SET status = 'done', finished_at = datetime('now') WHERE id = ?`).run(queueItemId);
+        },
+        fail(queueItemId, error) {
+            db.prepare(`UPDATE queues SET status = 'failed', finished_at = datetime('now'), error = ? WHERE id = ?`).run(error ?? null, queueItemId);
+        },
+        close() {
+            closeConnection(db);
+        },
+    };
+}
+
+export { closeConnection, createClient, createConnection, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, jobSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };