@karmaniverous/jeeves-runner 0.1.2 → 0.2.1

package/dist/mjs/index.js

@@ -1,12 +1,14 @@
 import { z } from 'zod';
-import { mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { pino } from 'pino';
 import Fastify from 'fastify';
 import { dirname, extname } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { request as request$1 } from 'node:http';
 import { request } from 'node:https';
 import { spawn } from 'node:child_process';
 import { Cron } from 'croner';
+import { JSONPath } from 'jsonpath-plus';
 
 /**
  * Runner configuration schema and types.
@@ -15,30 +17,54 @@ import { Cron } from 'croner';
  */
 /** Notification configuration sub-schema. */
 const notificationsSchema = z.object({
+    /** Path to Slack bot token file. */
     slackTokenPath: z.string().optional(),
+    /** Default Slack channel ID for failure notifications. */
     defaultOnFailure: z.string().nullable().default(null),
+    /** Default Slack channel ID for success notifications. */
     defaultOnSuccess: z.string().nullable().default(null),
 });
 /** Log configuration sub-schema. */
 const logSchema = z.object({
+    /** Log level threshold (trace, debug, info, warn, error, fatal). */
     level: z
         .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
         .default('info'),
+    /** Optional log file path. */
     file: z.string().optional(),
 });
+/** Gateway configuration sub-schema. */
+const gatewaySchema = z.object({
+    /** OpenClaw Gateway URL. */
+    url: z.string().default('http://127.0.0.1:18789'),
+    /** Path to file containing Gateway auth token. */
+    tokenPath: z.string().optional(),
+});
 /** Full runner configuration schema. Validates and provides defaults. */
 const runnerConfigSchema = z.object({
-    port: z.number().default(3100),
+    /** HTTP server port for the runner API. */
+    port: z.number().default(1937),
+    /** Path to SQLite database file. */
     dbPath: z.string().default('./data/runner.sqlite'),
+    /** Maximum number of concurrent job executions. */
     maxConcurrency: z.number().default(4),
+    /** Number of days to retain completed run records. */
     runRetentionDays: z.number().default(30),
+    /** Interval in milliseconds for cursor cleanup task. */
     cursorCleanupIntervalMs: z.number().default(3600000),
+    /** Grace period in milliseconds for shutdown completion. */
     shutdownGraceMs: z.number().default(30000),
+    /** Interval in milliseconds for job reconciliation checks. */
+    reconcileIntervalMs: z.number().default(60000),
+    /** Notification configuration for job completion events. */
     notifications: notificationsSchema.default({
         defaultOnFailure: null,
         defaultOnSuccess: null,
     }),
+    /** Logging configuration. */
     log: logSchema.default({ level: 'info' }),
+    /** Gateway configuration for session-type jobs. */
+    gateway: gatewaySchema.default({ url: 'http://127.0.0.1:18789' }),
 });
 
 /**
@@ -46,25 +72,63 @@ const runnerConfigSchema = z.object({
  *
  * @module
  */
+/** Job definition schema for scheduled tasks. */
 const jobSchema = z.object({
+    /** Unique job identifier. */
     id: z.string(),
+    /** Human-readable job name. */
     name: z.string(),
+    /** Cron expression defining the job schedule. */
     schedule: z.string(),
+    /** Script path or command to execute. */
     script: z.string(),
+    /** Job execution type (script or session). */
     type: z.enum(['script', 'session']).default('script'),
+    /** Optional job description. */
     description: z.string().optional(),
+    /** Whether the job is enabled for scheduling. */
     enabled: z.boolean().default(true),
+    /** Optional execution timeout in milliseconds. */
     timeoutMs: z.number().optional(),
+    /** Policy for handling overlapping job executions (skip, queue, or allow). */
     overlapPolicy: z.enum(['skip', 'queue', 'allow']).default('skip'),
+    /** Slack channel ID for failure notifications. */
     onFailure: z.string().nullable().default(null),
+    /** Slack channel ID for success notifications. */
     onSuccess: z.string().nullable().default(null),
 });
 
+/**
+ * Queue definition schema and types.
+ *
+ * @module
+ */
+/** Queue definition schema for managing queue behavior and retention. */
+const queueSchema = z.object({
+    /** Unique queue identifier. */
+    id: z.string(),
+    /** Human-readable queue name. */
+    name: z.string(),
+    /** Optional queue description. */
+    description: z.string().nullable().optional(),
+    /** JSONPath expression for deduplication key extraction. */
+    dedupExpr: z.string().nullable().optional(),
+    /** Deduplication scope: 'pending' checks pending/processing items, 'all' checks all non-failed items. */
+    dedupScope: z.enum(['pending', 'all']).default('pending'),
+    /** Maximum retry attempts before dead-lettering. */
+    maxAttempts: z.number().default(1),
+    /** Retention period in days for completed/failed items. */
+    retentionDays: z.number().default(7),
+    /** Queue creation timestamp. */
+    createdAt: z.string(),
+});
+
 /**
  * Run record schema and types.
  *
  * @module
  */
+/** Run status enumeration schema (pending, running, ok, error, timeout, skipped). */
 const runStatusSchema = z.enum([
     'pending',
     'running',
@@ -73,20 +137,35 @@ const runStatusSchema = z.enum([
     'timeout',
     'skipped',
 ]);
+/** Run trigger type enumeration schema (schedule, manual, retry). */
 const runTriggerSchema = z.enum(['schedule', 'manual', 'retry']);
+/** Run record schema representing a job execution instance. */
 const runSchema = z.object({
+    /** Unique run identifier. */
     id: z.number(),
+    /** Reference to the parent job ID. */
     jobId: z.string(),
+    /** Current execution status. */
     status: runStatusSchema,
+    /** ISO timestamp when execution started. */
     startedAt: z.string().optional(),
+    /** ISO timestamp when execution finished. */
     finishedAt: z.string().optional(),
+    /** Execution duration in milliseconds. */
     durationMs: z.number().optional(),
+    /** Process exit code. */
     exitCode: z.number().optional(),
+    /** Token count for session-type jobs. */
     tokens: z.number().optional(),
+    /** Additional result metadata (JSON string). */
     resultMeta: z.string().optional(),
+    /** Error message if execution failed. */
     error: z.string().optional(),
+    /** Last N characters of stdout. */
     stdoutTail: z.string().optional(),
+    /** Last N characters of stderr. */
     stderrTail: z.string().optional(),
+    /** What triggered this run (schedule, manual, or retry). */
     trigger: runTriggerSchema.default('schedule'),
 });
 
@@ -100,7 +179,11 @@ function registerRoutes(app, deps) {
     const { db, scheduler } = deps;
     /** GET /health — Health check. */
     app.get('/health', () => {
-        return { ok: true, uptime: process.uptime() };
+        return {
+            ok: true,
+            uptime: process.uptime(),
+            failedRegistrations: scheduler.getFailedRegistrations().length,
+        };
     });
     /** GET /jobs — List all jobs with last run status. */
     app.get('/jobs', () => {
@@ -151,6 +234,7 @@ function registerRoutes(app, deps) {
             reply.code(404);
             return { error: 'Job not found' };
         }
+        scheduler.reconcileNow();
         return { ok: true };
     });
     /** POST /jobs/:id/disable — Disable a job. */
@@ -162,6 +246,7 @@ function registerRoutes(app, deps) {
             reply.code(404);
             return { error: 'Job not found' };
         }
+        scheduler.reconcileNow();
         return { ok: true };
     });
     /** GET /stats — Aggregate job statistics. */
@@ -170,6 +255,7 @@ function registerRoutes(app, deps) {
             .prepare('SELECT COUNT(*) as count FROM jobs')
             .get();
         const runningCount = scheduler.getRunningJobs().length;
+        const failedCount = scheduler.getFailedRegistrations().length;
         const okLastHour = db
             .prepare(`SELECT COUNT(*) as count FROM runs 
          WHERE status = 'ok' AND started_at > datetime('now', '-1 hour')`)
@@ -181,6 +267,7 @@ function registerRoutes(app, deps) {
         return {
             totalJobs: totalJobs.count,
             running: runningCount,
+            failedRegistrations: failedCount,
             okLastHour: okLastHour.count,
             errorsLastHour: errorsLastHour.count,
         };
@@ -193,19 +280,21 @@ function registerRoutes(app, deps) {
 /**
  * Create and configure the Fastify server. Routes are registered but server is not started.
  */
-function createServer(config, deps) {
+function createServer(deps) {
     const app = Fastify({
-        logger: {
-            level: config.log.level,
-            ...(config.log.file
-                ? {
-                    transport: {
-                        target: 'pino/file',
-                        options: { destination: config.log.file },
-                    },
-                }
-                : {}),
-        },
+        logger: deps.loggerConfig
+            ? {
+                level: deps.loggerConfig.level,
+                ...(deps.loggerConfig.file
+                    ? {
+                        transport: {
+                            target: 'pino/file',
+                            options: { destination: deps.loggerConfig.file },
+                        },
+                    }
+                    : {}),
+            }
+            : false,
     });
     registerRoutes(app, deps);
     return app;
@@ -241,20 +330,36 @@ function closeConnection(db) {
  */
 /** Delete runs older than the configured retention period. */
 function pruneOldRuns(db, days, logger) {
+    const cutoffDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
     const result = db
-        .prepare(`DELETE FROM runs WHERE started_at < datetime('now', '-${String(days)} days')`)
-        .run();
+        .prepare(`DELETE FROM runs WHERE started_at < ?`)
+        .run(cutoffDate);
     if (result.changes > 0) {
         logger.info({ deleted: result.changes }, 'Pruned old runs');
     }
 }
-/** Delete expired cursor entries. */
+/** Delete expired state entries. */
 function cleanExpiredCursors(db, logger) {
     const result = db
-        .prepare(`DELETE FROM cursors WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
+        .prepare(`DELETE FROM state WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
         .run();
     if (result.changes > 0) {
-        logger.info({ deleted: result.changes }, 'Cleaned expired cursors');
+        logger.info({ deleted: result.changes }, 'Cleaned expired state entries');
+    }
+}
+/** Prune old queue items based on per-queue retention settings. */
+function pruneOldQueueItems(db, logger) {
+    const result = db
+        .prepare(`DELETE FROM queue_items 
+       WHERE status IN ('done', 'failed') 
+       AND finished_at < datetime('now', '-' || 
+         COALESCE(
+           (SELECT retention_days FROM queues WHERE queues.id = queue_items.queue_id),
+           7
+         ) || ' days')`)
+        .run();
+    if (result.changes > 0) {
+        logger.info({ deleted: result.changes }, 'Pruned old queue items');
     }
 }
 /**
@@ -265,6 +370,7 @@ function createMaintenance(db, config, logger) {
     function runAll() {
         pruneOldRuns(db, config.runRetentionDays, logger);
         cleanExpiredCursors(db, logger);
+        pruneOldQueueItems(db, logger);
     }
     return {
         start() {
@@ -352,9 +458,76 @@ CREATE TABLE IF NOT EXISTS queues (
 
 CREATE INDEX IF NOT EXISTS idx_queues_poll ON queues(queue, status, priority DESC, created_at);
 `;
+/** Migration 002: Rename queues → queue_items, create queues definition table, add dedup support. */
+const MIGRATION_002 = `
+-- Drop old index first (references 'queue' column)
+DROP INDEX IF EXISTS idx_queues_poll;
+
+-- Rename existing queues table to queue_items
+ALTER TABLE queues RENAME TO queue_items;
+
+-- Create new queues definition table
+CREATE TABLE queues (
+  id              TEXT PRIMARY KEY,
+  name            TEXT NOT NULL,
+  description     TEXT,
+  dedup_expr      TEXT,
+  dedup_scope     TEXT DEFAULT 'pending',
+  max_attempts    INTEGER DEFAULT 1,
+  retention_days  INTEGER DEFAULT 7,
+  created_at      TEXT DEFAULT (datetime('now'))
+);
+
+-- Add new columns to queue_items
+ALTER TABLE queue_items ADD COLUMN queue_id TEXT;
+ALTER TABLE queue_items ADD COLUMN dedup_key TEXT;
+
+-- Migrate existing queue column to queue_id
+UPDATE queue_items SET queue_id = queue;
+
+-- Drop old queue column
+ALTER TABLE queue_items DROP COLUMN queue;
+
+-- Create dedup lookup index
+CREATE INDEX idx_queue_items_dedup ON queue_items(queue_id, dedup_key, status);
+
+-- Create new poll index
+CREATE INDEX idx_queue_items_poll ON queue_items(queue_id, status, priority DESC, created_at);
+
+-- Seed queue definitions
+INSERT INTO queues (id, name, description, dedup_expr, dedup_scope, max_attempts, retention_days) VALUES
+  ('email-updates', 'Email Update Queue', NULL, NULL, NULL, 1, 7),
+  ('email-pending', 'Email Pending', NULL, '$.threadId', 'pending', 1, 7),
+  ('x-posts', 'X Post Queue', NULL, '$.id', 'pending', 1, 7),
+  ('gh-collabs', 'GH Collab Queue', NULL, '$.full_name', 'pending', 1, 7);
+`;
+/** Migration 003: Rename cursors → state, add state_items table for collection state. */
+const MIGRATION_003 = `
+-- Rename cursors → state
+ALTER TABLE cursors RENAME TO state;
+
+-- Rename index
+DROP INDEX IF EXISTS idx_cursors_expires;
+CREATE INDEX idx_state_expires ON state(expires_at) WHERE expires_at IS NOT NULL;
+
+-- Create state_items table
+CREATE TABLE state_items (
+    namespace   TEXT NOT NULL,
+    key         TEXT NOT NULL,
+    item_key    TEXT NOT NULL,
+    value       TEXT,
+    created_at  TEXT DEFAULT (datetime('now')),
+    updated_at  TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (namespace, key, item_key),
+    FOREIGN KEY (namespace, key) REFERENCES state(namespace, key)
+);
+CREATE INDEX idx_state_items_ns_key ON state_items(namespace, key);
+`;
 /** Registry of all migrations keyed by version number. */
 const MIGRATIONS = {
     1: MIGRATION_001,
+    2: MIGRATION_002,
+    3: MIGRATION_003,
 };
 /**
  * Run all pending migrations. Creates schema_version table if needed, applies migrations in order.
@@ -384,38 +557,128 @@ function runMigrations(db) {
 }
 
 /**
- * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ * Shared HTTP utility for making POST requests.
  */
-/** Post a message to Slack via chat.postMessage API. */
-function postToSlack(token, channel, text) {
+/** Make an HTTP/HTTPS POST request. Returns the parsed JSON response body. */
+function httpPost(url, headers, body, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
-        const payload = JSON.stringify({ channel, text });
-        const req = request('https://slack.com/api/chat.postMessage', {
+        const parsedUrl = new URL(url);
+        const isHttps = parsedUrl.protocol === 'https:';
+        const requestFn = isHttps ? request : request$1;
+        const req = requestFn({
+            hostname: parsedUrl.hostname,
+            port: parsedUrl.port,
+            path: parsedUrl.pathname + parsedUrl.search,
             method: 'POST',
             headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${token}`,
-                'Content-Length': Buffer.byteLength(payload),
+                ...headers,
+                'Content-Length': Buffer.byteLength(body),
             },
+            timeout: timeoutMs,
         }, (res) => {
-            let body = '';
+            let responseBody = '';
             res.on('data', (chunk) => {
-                body += chunk.toString();
+                responseBody += chunk.toString();
             });
             res.on('end', () => {
-                if (res.statusCode === 200) {
-                    resolve();
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${String(res.statusCode)}: ${responseBody}`));
+                    return;
                 }
-                else {
-                    reject(new Error(`Slack API returned ${String(res.statusCode)}: ${body}`));
+                try {
+                    resolve(JSON.parse(responseBody));
+                }
+                catch {
+                    reject(new Error(`Failed to parse JSON response: ${responseBody}`));
                 }
             });
         });
         req.on('error', reject);
-        req.write(payload);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Request timed out'));
+        });
+        req.write(body);
         req.end();
     });
 }
+
+/**
+ * OpenClaw Gateway HTTP client for spawning and monitoring sessions.
+ */
+/** Make an HTTP POST request to the Gateway /tools/invoke endpoint. */
+function invokeGateway(url, token, tool, args, timeoutMs = 30000) {
+    const payload = JSON.stringify({ tool, args });
+    return httpPost(`${url}/tools/invoke`, {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+    }, payload, timeoutMs);
+}
+/** Create a Gateway client. */
+function createGatewayClient(options) {
+    const { url, token, timeoutMs = 30000 } = options;
+    return {
+        async spawnSession(task, opts) {
+            const response = (await invokeGateway(url, token, 'sessions_spawn', {
+                task,
+                label: opts?.label,
+                thinking: opts?.thinking,
+                runTimeoutSeconds: opts?.runTimeoutSeconds,
+            }, timeoutMs));
+            if (!response.ok) {
+                throw new Error('Failed to spawn session');
+            }
+            return {
+                sessionKey: response.result.details.childSessionKey,
+                runId: response.result.details.runId,
+            };
+        },
+        async getSessionHistory(sessionKey, limit = 3) {
+            const response = (await invokeGateway(url, token, 'sessions_history', { sessionKey, limit, includeTools: false }, timeoutMs));
+            if (!response.ok) {
+                throw new Error('Failed to get session history');
+            }
+            return response.result;
+        },
+        async getSessionInfo(sessionKey) {
+            // Note: sessions_list doesn't support filtering by key, so we fetch recent sessions
+            // and search client-side. Consider using sessions_history with limit 1 as alternative,
+            // or request a sessions_get tool from Gateway for more efficient single-session lookup.
+            const response = (await invokeGateway(url, token, 'sessions_list', { activeMinutes: 120, limit: 500 }, // Increased from 100 to reduce false negatives
+            timeoutMs));
+            if (!response.ok) {
+                throw new Error('Failed to list sessions');
+            }
+            const session = response.result.find((s) => s.sessionKey === sessionKey);
+            if (!session)
+                return null;
+            return {
+                totalTokens: session.totalTokens,
+                model: session.model,
+                transcriptPath: session.transcriptPath,
+            };
+        },
+        async isSessionComplete(sessionKey) {
+            const history = await this.getSessionHistory(sessionKey, 3);
+            if (history.length === 0)
+                return false;
+            const lastMessage = history[history.length - 1];
+            return (lastMessage.role === 'assistant' && lastMessage.stopReason !== undefined);
+        },
+    };
+}
+
+/**
+ * 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. */
+async function postToSlack(token, channel, text) {
+    const payload = JSON.stringify({ channel, text });
+    await httpPost('https://slack.com/api/chat.postMessage', {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+    }, payload);
+}
 /**
  * Create a notifier that sends Slack messages for job events. If no token, logs warning and returns silently.
  */
@@ -507,12 +770,14 @@ 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 } = options;
+    const { script, dbPath, jobId, runId, timeoutMs, commandResolver } = options;
     const startTime = Date.now();
     return new Promise((resolve) => {
         const stdoutBuffer = new RingBuffer(100);
         const stderrBuffer = new RingBuffer(100);
-        const { command, args } = resolveCommand(script);
+        const { command, args } = commandResolver
+            ? commandResolver(script)
+            : resolveCommand(script);
         const child = spawn(command, args, {
             env: {
                 ...process.env,
@@ -607,66 +872,289 @@ function executeJob(options) {
     });
 }
 
+/**
+ * Cron registration and reconciliation utilities.
+ */
+function createCronRegistry(deps) {
+    const { db, logger, onScheduledRun } = deps;
+    const crons = new Map();
+    const cronSchedules = new Map();
+    const failedRegistrations = new Set();
+    function registerCron(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);
+            failedRegistrations.delete(job.id);
+            logger.info({ jobId: job.id, schedule: job.schedule }, 'Scheduled job');
+            return true;
+        }
+        catch (err) {
+            logger.error({ jobId: job.id, err }, 'Failed to schedule job');
+            failedRegistrations.add(job.id);
+            return false;
+        }
+    }
+    function reconcile() {
+        const enabledJobs = db
+            .prepare('SELECT * FROM jobs WHERE enabled = 1')
+            .all();
+        const enabledById = new Map(enabledJobs.map((j) => [j.id, j]));
+        // Remove disabled/deleted jobs
+        for (const [jobId, cron] of crons.entries()) {
+            if (!enabledById.has(jobId)) {
+                cron.stop();
+                crons.delete(jobId);
+                cronSchedules.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))
+                    failedIds.push(job.id);
+                continue;
+            }
+            if (existingSchedule !== job.schedule) {
+                existingCron.stop();
+                crons.delete(job.id);
+                cronSchedules.delete(job.id);
+                if (!registerCron(job))
+                    failedIds.push(job.id);
+            }
+        }
+        return { totalEnabled: enabledJobs.length, failedIds };
+    }
+    function stopAll() {
+        for (const cron of crons.values()) {
+            cron.stop();
+        }
+        crons.clear();
+        cronSchedules.clear();
+    }
+    return {
+        reconcile,
+        stopAll,
+        getFailedRegistrations() {
+            return Array.from(failedRegistrations);
+        },
+    };
+}
+
+/**
+ * Notification dispatch helper for job completion events.
+ */
+/** Dispatch notification based on execution result and job configuration. */
+async function dispatchNotification(result, jobName, onSuccess, onFailure, notifier, logger) {
+    if (result.status === 'ok' && onSuccess) {
+        await notifier
+            .notifySuccess(jobName, result.durationMs, onSuccess)
+            .catch((err) => {
+            logger.error({ jobName, err }, 'Success notification failed');
+        });
+    }
+    else if (result.status !== 'ok' && onFailure) {
+        await notifier
+            .notifyFailure(jobName, result.durationMs, result.error, onFailure)
+            .catch((err) => {
+            logger.error({ jobName, err }, 'Failure notification failed');
+        });
+    }
+}
+
+/**
+ * Run record repository for managing job execution records.
+ */
+/** Create a run repository for the given database connection. */
+function createRunRepository(db) {
+    return {
+        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;
+        },
+        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);
+        },
+    };
+}
+
+/**
+ * Session executor for job type='session'. Spawns OpenClaw Gateway sessions and polls for completion.
+ */
+/** File extensions that indicate a script rather than a prompt. */
+const SCRIPT_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ps1', '.cmd', '.bat'];
+/** Resolve task prompt from script field: read file if .md/.txt, return raw text otherwise. */
+function resolveTaskPrompt(script) {
+    const ext = extname(script).toLowerCase();
+    // If script extension, caller should fall back to script executor
+    if (SCRIPT_EXTENSIONS.includes(ext)) {
+        return null;
+    }
+    // If .md or .txt, read file contents
+    if (ext === '.md' || ext === '.txt') {
+        if (!existsSync(script)) {
+            throw new Error(`Prompt file not found: ${script}`);
+        }
+        return readFileSync(script, 'utf-8');
+    }
+    // Otherwise, treat script as raw prompt text
+    return script;
+}
+/** Poll for session completion with exponential backoff (capped). */
+async function pollCompletion(gatewayClient, sessionKey, timeoutMs, initialIntervalMs = 5000) {
+    const startTime = Date.now();
+    let interval = initialIntervalMs;
+    const maxInterval = 15000;
+    while (Date.now() - startTime < timeoutMs) {
+        const isComplete = await gatewayClient.isSessionComplete(sessionKey);
+        if (isComplete)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, interval));
+        interval = Math.min(interval * 1.2, maxInterval); // Exponential backoff capped
+    }
+    throw new Error(`Session timed out after ${String(timeoutMs)}ms`);
+}
+/**
+ * Execute a session job: spawn a Gateway session, poll for completion, fetch token usage.
+ */
+async function executeSession(options) {
+    const { script, jobId, timeoutMs = 300000, gatewayClient, pollIntervalMs, } = options;
+    const startTime = Date.now();
+    try {
+        // Resolve task prompt
+        const taskPrompt = resolveTaskPrompt(script);
+        if (taskPrompt === null) {
+            throw new Error('Session job script has script extension; expected prompt text or .md/.txt file');
+        }
+        // Spawn session
+        const { sessionKey } = await gatewayClient.spawnSession(taskPrompt, {
+            label: jobId,
+            thinking: 'low',
+            runTimeoutSeconds: Math.floor(timeoutMs / 1000),
+        });
+        // Poll for completion
+        await pollCompletion(gatewayClient, sessionKey, timeoutMs, pollIntervalMs);
+        // Fetch session info for token count
+        const sessionInfo = await gatewayClient.getSessionInfo(sessionKey);
+        const tokens = sessionInfo?.totalTokens ?? null;
+        const durationMs = Date.now() - startTime;
+        return {
+            status: 'ok',
+            exitCode: null,
+            durationMs,
+            tokens,
+            resultMeta: sessionKey,
+            stdoutTail: `Session completed: ${sessionKey}`,
+            stderrTail: '',
+            error: null,
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        const errorMessage = err instanceof Error ? err.message : 'Unknown session error';
+        // Check if timeout
+        if (errorMessage.includes('timed out')) {
+            return {
+                status: 'timeout',
+                exitCode: null,
+                durationMs,
+                tokens: null,
+                resultMeta: null,
+                stdoutTail: '',
+                stderrTail: errorMessage,
+                error: errorMessage,
+            };
+        }
+        return {
+            status: 'error',
+            exitCode: null,
+            durationMs,
+            tokens: null,
+            resultMeta: null,
+            stdoutTail: '',
+            stderrTail: errorMessage,
+            error: errorMessage,
+        };
+    }
+}
+
 /**
  * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
  */
+// JobRow is imported from cron-registry
 /**
  * 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 { db, executor, notifier, config, logger, gatewayClient } = deps;
     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);
-    }
+    const cronRegistry = createCronRegistry({
+        db,
+        logger,
+        onScheduledRun: (job) => {
+            void onScheduledRun(job);
+        },
+    });
+    const runRepository = createRunRepository(db);
+    let reconcileInterval = null;
     /** 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;
+        const { id, name, script, type, 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');
+        const runId = runRepository.createRun(id, trigger);
+        logger.info({ jobId: id, runId, trigger, type }, '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');
+            let result;
+            // Route based on job type
+            if (type === 'session') {
+                if (!gatewayClient) {
+                    throw new Error('Session job requires Gateway client (gateway.tokenPath not configured)');
+                }
+                result = await executeSession({
+                    script,
+                    jobId: id,
+                    timeoutMs: timeout_ms ?? undefined,
+                    gatewayClient,
                 });
             }
-            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');
+            else {
+                // Default to script executor
+                result = await executor({
+                    script,
+                    dbPath: config.dbPath,
+                    jobId: id,
+                    runId,
+                    timeoutMs: timeout_ms ?? undefined,
                 });
             }
+            runRepository.finishRun(runId, result);
+            logger.info({ jobId: id, runId, status: result.status }, 'Job finished');
+            // Send notifications
+            await dispatchNotification(result, name, on_success, on_failure, notifier, logger);
             return result;
         }
         finally {
@@ -682,63 +1170,53 @@ function createScheduler(deps) {
                 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');
         });
     }
+    // Cron registration and reconciliation are handled by cronRegistry.
     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 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;
-                        }
-                        void onScheduledRun(currentJob);
-                    });
-                    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');
+            const { totalEnabled, failedIds } = cronRegistry.reconcile();
+            logger.info({ count: totalEnabled }, 'Loading jobs');
+            if (failedIds.length > 0) {
+                const ok = totalEnabled - failedIds.length;
+                logger.warn({ failed: failedIds.length, total: totalEnabled }, `${String(failedIds.length)} of ${String(totalEnabled)} jobs failed to register`);
+                const message = `⚠️ jeeves-runner started: ${String(ok)}/${String(totalEnabled)} jobs scheduled, ${String(failedIds.length)} failed: ${failedIds.join(', ')}`;
+                const channel = config.notifications.defaultOnFailure;
+                if (channel) {
+                    void notifier.notifyFailure('jeeves-runner', 0, message, channel);
                 }
             }
+            if (reconcileInterval === null && config.reconcileIntervalMs > 0) {
+                reconcileInterval = setInterval(() => {
+                    try {
+                        cronRegistry.reconcile();
+                    }
+                    catch (err) {
+                        logger.error({ err }, 'Reconciliation failed');
+                    }
+                }, config.reconcileIntervalMs);
+            }
         },
-        stop() {
+        async stop() {
             logger.info('Stopping scheduler');
-            // Stop all crons
-            for (const cron of crons.values()) {
-                cron.stop();
+            if (reconcileInterval) {
+                clearInterval(reconcileInterval);
+                reconcileInterval = null;
             }
-            crons.clear();
-            // Wait for running jobs (simple poll with timeout)
+            // Stop all crons
+            cronRegistry.stopAll();
+            // Wait for running jobs (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);
+            while (runningJobs.size > 0 && Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+            if (runningJobs.size > 0) {
+                logger.warn({ count: runningJobs.size }, 'Forced shutdown with running jobs');
+            }
         },
         async triggerJob(jobId) {
             const job = db.prepare('SELECT * FROM jobs WHERE id = ?').get(jobId);
@@ -746,9 +1224,15 @@ function createScheduler(deps) {
                 throw new Error(`Job not found: ${jobId}`);
             return runJob(job, 'manual');
         },
+        reconcileNow() {
+            cronRegistry.reconcile();
+        },
         getRunningJobs() {
             return Array.from(runningJobs);
         },
+        getFailedRegistrations() {
+            return cronRegistry.getFailedRegistrations();
+        },
     };
 }
 
@@ -758,22 +1242,23 @@ function createScheduler(deps) {
 /**
  * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
  */
-function createRunner(config) {
+function createRunner(config, deps) {
     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 },
-                },
-            }
-            : {}),
-    });
+    const logger = deps?.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');
@@ -786,6 +1271,19 @@ function createRunner(config) {
                 ? readFileSync(config.notifications.slackTokenPath, 'utf-8').trim()
                 : null;
             const notifier = createNotifier({ slackToken });
+            // Gateway client (optional, for session-type jobs)
+            const gatewayToken = config.gateway.tokenPath
+                ? readFileSync(config.gateway.tokenPath, 'utf-8').trim()
+                : (process.env.OPENCLAW_GATEWAY_TOKEN ?? null);
+            const gatewayClient = gatewayToken && config.gateway.url
+                ? createGatewayClient({
+                    url: config.gateway.url,
+                    token: gatewayToken,
+                })
+                : undefined;
+            if (gatewayClient) {
+                logger.info('Gateway client initialized');
+            }
             // Maintenance (run retention pruning + cursor cleanup)
             maintenance = createMaintenance(db, {
                 runRetentionDays: config.runRetentionDays,
@@ -800,11 +1298,16 @@ function createRunner(config) {
                 notifier,
                 config,
                 logger,
+                gatewayClient,
             });
             scheduler.start();
             logger.info('Scheduler started');
             // API server
-            server = createServer(config, { db, scheduler });
+            server = createServer({
+                db,
+                scheduler,
+                loggerConfig: { level: config.log.level, file: config.log.file },
+            });
             await server.listen({ port: config.port, host: '127.0.0.1' });
             logger.info({ port: config.port }, 'API server listening');
             // Graceful shutdown
@@ -827,7 +1330,7 @@ function createRunner(config) {
                 logger.info('Maintenance stopped');
             }
             if (scheduler) {
-                scheduler.stop();
+                await scheduler.stop();
                 logger.info('Scheduler stopped');
             }
             if (server) {
@@ -843,7 +1346,109 @@ function createRunner(config) {
 }
 
 /**
- * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ * Queue operations module for runner client. Provides enqueue, dequeue, done, and fail operations.
+ */
+/** Create queue operations for the given database connection. */
+function createQueueOps(db) {
+    return {
+        enqueue(queue, payload, options) {
+            const priority = options?.priority ?? 0;
+            const payloadJson = JSON.stringify(payload);
+            // Look up queue definition
+            const queueDef = db
+                .prepare('SELECT dedup_expr, dedup_scope, max_attempts FROM queues WHERE id = ?')
+                .get(queue);
+            let dedupKey = null;
+            const maxAttempts = options?.maxAttempts ?? queueDef?.max_attempts ?? 1;
+            // Handle deduplication if queue definition exists and has dedup_expr
+            if (queueDef?.dedup_expr) {
+                try {
+                    const result = JSONPath({
+                        path: queueDef.dedup_expr,
+                        json: payload,
+                    });
+                    if (Array.isArray(result) && result.length > 0) {
+                        dedupKey = String(result[0]);
+                    }
+                }
+                catch {
+                    // If JSONPath evaluation fails, proceed without dedup
+                    dedupKey = null;
+                }
+                // Check for duplicates
+                if (dedupKey) {
+                    const dedupScope = queueDef.dedup_scope || 'pending';
+                    const statusFilter = dedupScope === 'pending'
+                        ? "status IN ('pending', 'processing')"
+                        : "status IN ('pending', 'processing', 'done')";
+                    const existing = db
+                        .prepare(`SELECT id FROM queue_items 
+               WHERE queue_id = ? AND dedup_key = ? AND ${statusFilter}
+               LIMIT 1`)
+                        .get(queue, dedupKey);
+                    if (existing) {
+                        return -1; // Duplicate found, skip enqueue
+                    }
+                }
+            }
+            // Insert the item
+            const result = db
+                .prepare('INSERT INTO queue_items (queue_id, payload, priority, max_attempts, dedup_key) VALUES (?, ?, ?, ?, ?)')
+                .run(queue, payloadJson, priority, maxAttempts, dedupKey);
+            return result.lastInsertRowid;
+        },
+        dequeue(queue, count = 1) {
+            // Wrap SELECT + UPDATE in a transaction for atomicity
+            db.exec('BEGIN');
+            try {
+                // First, SELECT the items to claim (with correct ordering)
+                const rows = db
+                    .prepare(`SELECT id, payload FROM queue_items 
+             WHERE queue_id = ? 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 queue_items 
+           SET status = 'processing', claimed_at = datetime('now'), attempts = attempts + 1
+           WHERE id = ?`);
+                for (const row of rows) {
+                    updateStmt.run(row.id);
+                }
+                db.exec('COMMIT');
+                return rows.map((row) => ({
+                    id: row.id,
+                    payload: JSON.parse(row.payload),
+                }));
+            }
+            catch (err) {
+                db.exec('ROLLBACK');
+                throw err;
+            }
+        },
+        done(queueItemId) {
+            db.prepare(`UPDATE queue_items SET status = 'done', finished_at = datetime('now') WHERE id = ?`).run(queueItemId);
+        },
+        fail(queueItemId, error) {
+            // Get current item state
+            const item = db
+                .prepare('SELECT attempts, max_attempts FROM queue_items WHERE id = ?')
+                .get(queueItemId);
+            if (!item)
+                return;
+            // If under max attempts, retry (reset to pending); else dead-letter (mark failed)
+            if (item.attempts < item.max_attempts) {
+                db.prepare(`UPDATE queue_items SET status = 'pending', error = ? WHERE id = ?`).run(error ?? null, queueItemId);
+            }
+            else {
+                db.prepare(`UPDATE queue_items SET status = 'failed', finished_at = datetime('now'), error = ? WHERE id = ?`).run(error ?? null, queueItemId);
+            }
+        },
+    };
+}
+
+/**
+ * State operations module for runner client. Provides scalar state (key-value) and collection state (grouped items).
  */
 /** Parse TTL string (e.g., '30d', '24h', '60m') into ISO datetime offset from now. */
 function parseTtl(ttl) {
@@ -855,34 +1460,28 @@ function parseTtl(ttl) {
     if (!amount || !unit)
         throw new Error(`Invalid TTL format: ${ttl}`);
     const num = parseInt(amount, 10);
-    let modifier;
+    let ms;
     switch (unit) {
         case 'd':
-            modifier = `+${String(num)} days`;
+            ms = num * 24 * 60 * 60 * 1000;
             break;
         case 'h':
-            modifier = `+${String(num)} hours`;
+            ms = num * 60 * 60 * 1000;
             break;
         case 'm':
-            modifier = `+${String(num)} minutes`;
+            ms = num * 60 * 1000;
             break;
         default:
             throw new Error(`Unknown TTL unit: ${unit}`);
     }
-    return `datetime('now', '${modifier}')`;
+    return new Date(Date.now() + ms).toISOString();
 }
-/**
- * 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);
+/** Create state operations for the given database connection. */
+function createStateOps(db) {
     return {
         getCursor(namespace, key) {
             const row = db
-                .prepare(`SELECT value FROM cursors 
+                .prepare(`SELECT value FROM state 
            WHERE namespace = ? AND key = ? 
            AND (expires_at IS NULL OR expires_at > datetime('now'))`)
                 .get(namespace, key);
@@ -890,55 +1489,100 @@ function createClient(dbPath) {
         },
         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);
+            if (expiresAt) {
+                db.prepare(`INSERT INTO state (namespace, key, value, expires_at) VALUES (?, ?, ?, ?)
+           ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at, updated_at = datetime('now')`).run(namespace, key, value, expiresAt);
+            }
+            else {
+                db.prepare(`INSERT INTO state (namespace, key, value) VALUES (?, ?, ?)
+           ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')`).run(namespace, key, value);
+            }
         },
         deleteCursor(namespace, key) {
-            db.prepare('DELETE FROM cursors WHERE namespace = ? AND key = ?').run(namespace, key);
+            db.prepare('DELETE FROM state 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;
+        getState(namespace, key) {
+            return this.getCursor(namespace, key);
         },
-        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),
-            }));
+        setState(namespace, key, value, options) {
+            this.setCursor(namespace, key, value, options);
         },
-        done(queueItemId) {
-            db.prepare(`UPDATE queues SET status = 'done', finished_at = datetime('now') WHERE id = ?`).run(queueItemId);
+        deleteState(namespace, key) {
+            this.deleteCursor(namespace, key);
         },
-        fail(queueItemId, error) {
-            db.prepare(`UPDATE queues SET status = 'failed', finished_at = datetime('now'), error = ? WHERE id = ?`).run(error ?? null, queueItemId);
+    };
+}
+/** Create collection state operations for the given database connection. */
+function createCollectionOps(db) {
+    return {
+        hasItem(namespace, key, itemKey) {
+            const row = db
+                .prepare('SELECT 1 FROM state_items WHERE namespace = ? AND key = ? AND item_key = ?')
+                .get(namespace, key, itemKey);
+            return row !== undefined;
+        },
+        getItem(namespace, key, itemKey) {
+            const row = db
+                .prepare('SELECT value FROM state_items WHERE namespace = ? AND key = ? AND item_key = ?')
+                .get(namespace, key, itemKey);
+            return row?.value ?? null;
+        },
+        setItem(namespace, key, itemKey, value) {
+            // Auto-create parent state row if it doesn't exist
+            db.prepare(`INSERT OR IGNORE INTO state (namespace, key, value) VALUES (?, ?, NULL)`).run(namespace, key);
+            db.prepare(`INSERT INTO state_items (namespace, key, item_key, value) VALUES (?, ?, ?, ?)
+         ON CONFLICT(namespace, key, item_key) DO UPDATE SET value = excluded.value, updated_at = datetime('now')`).run(namespace, key, itemKey, value ?? null);
+        },
+        deleteItem(namespace, key, itemKey) {
+            db.prepare('DELETE FROM state_items WHERE namespace = ? AND key = ? AND item_key = ?').run(namespace, key, itemKey);
+        },
+        countItems(namespace, key) {
+            const row = db
+                .prepare('SELECT COUNT(*) as count FROM state_items WHERE namespace = ? AND key = ?')
+                .get(namespace, key);
+            return row?.count ?? 0;
+        },
+        pruneItems(namespace, key, keepCount) {
+            const result = db
+                .prepare(`DELETE FROM state_items WHERE namespace = ? AND key = ? AND rowid NOT IN (SELECT rowid FROM state_items WHERE namespace = ? AND key = ? ORDER BY updated_at DESC LIMIT ?)`)
+                .run(namespace, key, namespace, key, keepCount);
+            return result.changes;
         },
+        listItemKeys(namespace, key, options) {
+            const order = options?.order === 'asc' ? 'ASC' : 'DESC';
+            const limitClause = options?.limit
+                ? ` LIMIT ${String(options.limit)}`
+                : '';
+            const rows = db
+                .prepare(`SELECT item_key FROM state_items WHERE namespace = ? AND key = ? ORDER BY updated_at ${order}${limitClause}`)
+                .all(namespace, key);
+            return rows.map((r) => r.item_key);
+        },
+    };
+}
+
+/**
+ * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ */
+/**
+ * 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);
+    const stateOps = createStateOps(db);
+    const collectionOps = createCollectionOps(db);
+    const queueOps = createQueueOps(db);
+    return {
+        ...stateOps,
+        ...collectionOps,
+        ...queueOps,
         close() {
             closeConnection(db);
         },
     };
 }
 
-export { closeConnection, createClient, createConnection, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, jobSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };
+export { closeConnection, createClient, createConnection, createGatewayClient, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, executeSession, jobSchema, queueSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };