@happyvertical/smrt-jobs 0.30.0

package/dist/object-extension.d.ts

@@ -0,0 +1,68 @@
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { JobBuilder } from './job-builder.js';
+import { JobHandle } from './job-handle.js';
+/**
+ * Options for the simple .bg() method
+ */
+export interface BgOptions {
+    /** Queue name */
+    queue?: string;
+    /** Priority level */
+    priority?: 'critical' | 'high' | 'normal' | 'low' | number;
+    /** Delay before running (ms or string like '5m') */
+    delay?: string | number;
+    /** Maximum retries */
+    retries?: number;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Type for the extended SmrtObject with background job methods
+ */
+export interface BackgroundCapable {
+    /**
+     * Simple background job submission
+     *
+     * @param method - Method name to invoke
+     * @param args - Arguments to pass to the method
+     * @param options - Job options
+     * @returns JobHandle for tracking the job
+     *
+     * @example
+     * const handle = await doc.bg('generateSummary', { format: 'md' });
+     */
+    bg<T = unknown>(method: string, args?: Record<string, unknown>, options?: BgOptions): Promise<JobHandle<T>>;
+    /**
+     * Fluent job builder for advanced options
+     *
+     * @param method - Method name to invoke
+     * @param args - Arguments to pass to the method
+     * @returns JobBuilder for fluent configuration
+     *
+     * @example
+     * const handle = await doc.background('generateSummary', { format: 'md' })
+     *   .delay('5m')
+     *   .retries(5)
+     *   .priority('high')
+     *   .enqueue();
+     */
+    background<T = unknown>(method: string, args?: Record<string, unknown>): JobBuilder<T>;
+}
+type SmrtObjectConstructor = new (...args: any[]) => SmrtObject;
+type BackgroundCapableConstructor<T extends SmrtObjectConstructor> = T & {
+    new (...args: ConstructorParameters<T>): InstanceType<T> & BackgroundCapable;
+};
+/**
+ * Extend a SmrtObject class with background job methods
+ *
+ * @param BaseClass - The SmrtObject class to extend
+ * @returns Extended class with .bg() and .background() methods
+ *
+ * @example
+ * const BackgroundDocument = withBackgroundJobs(Document);
+ * const doc = new BackgroundDocument({ ... });
+ * const handle = await doc.bg('generateSummary', { format: 'md' });
+ */
+export declare function withBackgroundJobs<T extends SmrtObjectConstructor>(BaseClass: T): BackgroundCapableConstructor<T>;
+export default withBackgroundJobs;
+//# sourceMappingURL=object-extension.d.ts.map

package/dist/object-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-extension.d.ts","sourceRoot":"","sources":["../src/object-extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3E,OAAO,EACL,UAAU,EAIX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC3D,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;OAUG;IACH,EAAE,CAAC,CAAC,GAAG,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,SAAS,GAClB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,CAAC,GAAG,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,UAAU,CAAC,CAAC,CAAC,CAAC;CAClB;AAkCD,KAAK,qBAAqB,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC;AAChE,KAAK,4BAA4B,CAAC,CAAC,SAAS,qBAAqB,IAAI,CAAC,GAAG;IACvE,KAAK,GAAG,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC;CAC9E,CAAC;AAiIF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,qBAAqB,EAChE,SAAS,EAAE,CAAC,GACX,4BAA4B,CAAC,CAAC,CAAC,CAqBjC;AAED,eAAe,kBAAkB,CAAC"}

package/dist/playground.d.ts

@@ -0,0 +1,2 @@
+export { default } from './svelte/playground.js';
+//# sourceMappingURL=playground.d.ts.map

package/dist/playground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.d.ts","sourceRoot":"","sources":["../src/playground.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/playground.js

@@ -0,0 +1,179 @@
+import { JOBS_MODULE_META } from "./ui.js";
+const noop = () => {
+};
+const sampleJobs = [
+  {
+    id: "job-publish-1",
+    queue: "content",
+    objectType: "@happyvertical/smrt-content:Article",
+    objectId: "article-aurora-kitchen",
+    method: "publish",
+    args: { force: false },
+    status: "running",
+    priority: 80,
+    attempts: 1,
+    maxAttempts: 3,
+    timeout: 6e5,
+    timeoutBehavior: "fail",
+    runAt: "2026-03-21T16:15:00.000Z",
+    startedAt: "2026-03-21T16:15:15.000Z",
+    completedAt: null,
+    lastError: null,
+    resultPointer: null,
+    workerId: "worker-content-1",
+    createdAt: "2026-03-21T16:14:50.000Z",
+    updatedAt: "2026-03-21T16:15:20.000Z"
+  },
+  {
+    id: "job-review-2",
+    queue: "governance",
+    objectType: "@happyvertical/smrt-content:GovernancePolicy",
+    objectId: "policy-facts",
+    method: "recalculateReadiness",
+    args: { profileKey: "publication" },
+    status: "failed",
+    priority: 95,
+    attempts: 3,
+    maxAttempts: 3,
+    timeout: 3e5,
+    timeoutBehavior: "fail",
+    runAt: "2026-03-21T15:40:00.000Z",
+    startedAt: "2026-03-21T15:40:02.000Z",
+    completedAt: "2026-03-21T15:41:11.000Z",
+    lastError: "Relationship column missing during readiness sync.",
+    resultPointer: null,
+    workerId: "worker-governance-2",
+    createdAt: "2026-03-21T15:39:30.000Z",
+    updatedAt: "2026-03-21T15:41:11.000Z"
+  },
+  {
+    id: "job-export-3",
+    queue: "exports",
+    objectType: "@happyvertical/smrt-content:ArticleCollection",
+    objectId: null,
+    method: "buildStaticFeed",
+    args: { destination: "cdn" },
+    status: "completed",
+    priority: 40,
+    attempts: 1,
+    maxAttempts: 2,
+    timeout: 9e5,
+    timeoutBehavior: "warn",
+    runAt: "2026-03-21T14:30:00.000Z",
+    startedAt: "2026-03-21T14:30:00.000Z",
+    completedAt: "2026-03-21T14:31:25.000Z",
+    lastError: null,
+    resultPointer: "results/exports/build-static-feed-3.json",
+    workerId: "worker-export-1",
+    createdAt: "2026-03-21T14:29:52.000Z",
+    updatedAt: "2026-03-21T14:31:25.000Z"
+  }
+];
+const sampleStats = {
+  total: 3421,
+  pending: 24,
+  ready: 13,
+  running: 4,
+  completed: 3340,
+  failed: 31,
+  cancelled: 9,
+  avgDuration: 18450,
+  successRate: 0.976
+};
+const sampleQueues = [
+  {
+    name: "content",
+    pending: 8,
+    running: 2,
+    completed24h: 412,
+    failed24h: 4,
+    avgDuration: 22800
+  },
+  {
+    name: "governance",
+    pending: 5,
+    running: 1,
+    completed24h: 188,
+    failed24h: 7,
+    avgDuration: 31200
+  },
+  {
+    name: "exports",
+    pending: 11,
+    running: 1,
+    completed24h: 94,
+    failed24h: 1,
+    avgDuration: 52200
+  }
+];
+const loadJobDashboard = () => import("./svelte/components/JobDashboard.svelte");
+const loadJobDetail = () => import("./svelte/components/JobDetail.svelte");
+const loadJobStatusBadge = () => import("./svelte/components/JobStatusBadge.svelte");
+const playground = {
+  packageName: "@happyvertical/smrt-jobs",
+  displayName: JOBS_MODULE_META.displayName,
+  description: JOBS_MODULE_META.description,
+  moduleMeta: JOBS_MODULE_META,
+  entries: [
+    {
+      id: "job-dashboard",
+      title: "Job Dashboard",
+      description: "Operational overview for background job queues with recent and failed work.",
+      loadComponent: loadJobDashboard,
+      order: 1,
+      props: {
+        stats: sampleStats,
+        queues: sampleQueues,
+        recentJobs: sampleJobs,
+        failedJobs: sampleJobs.filter((job) => job.status === "failed"),
+        onJobClick: noop,
+        onRetry: noop,
+        onCancel: noop,
+        onViewAll: noop,
+        onViewFailed: noop
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    },
+    {
+      id: "job-detail",
+      title: "Job Detail",
+      description: "Detailed execution view for a single background job with retry and cancellation actions.",
+      loadComponent: loadJobDetail,
+      order: 2,
+      props: {
+        job: sampleJobs[1],
+        onRetry: noop,
+        onDelete: noop
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    },
+    {
+      id: "job-status-badge",
+      title: "Job Status Badge",
+      description: "Compact status treatment used throughout the jobs surface.",
+      loadComponent: loadJobStatusBadge,
+      order: 3,
+      props: {
+        status: "running",
+        size: "md"
+      },
+      modes: {
+        mock: {
+          label: "Mock"
+        }
+      }
+    }
+  ]
+};
+export {
+  playground as default
+};
+//# sourceMappingURL=playground.js.map

package/dist/playground.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playground.js","sources":["../src/svelte/playground.ts"],"sourcesContent":["import { JOBS_MODULE_META } from '../ui.js';\n\nconst noop = () => {};\n\nconst sampleJobs = [\n  {\n    id: 'job-publish-1',\n    queue: 'content',\n    objectType: '@happyvertical/smrt-content:Article',\n    objectId: 'article-aurora-kitchen',\n    method: 'publish',\n    args: { force: false },\n    status: 'running',\n    priority: 80,\n    attempts: 1,\n    maxAttempts: 3,\n    timeout: 600000,\n    timeoutBehavior: 'fail',\n    runAt: '2026-03-21T16:15:00.000Z',\n    startedAt: '2026-03-21T16:15:15.000Z',\n    completedAt: null,\n    lastError: null,\n    resultPointer: null,\n    workerId: 'worker-content-1',\n    createdAt: '2026-03-21T16:14:50.000Z',\n    updatedAt: '2026-03-21T16:15:20.000Z',\n  },\n  {\n    id: 'job-review-2',\n    queue: 'governance',\n    objectType: '@happyvertical/smrt-content:GovernancePolicy',\n    objectId: 'policy-facts',\n    method: 'recalculateReadiness',\n    args: { profileKey: 'publication' },\n    status: 'failed',\n    priority: 95,\n    attempts: 3,\n    maxAttempts: 3,\n    timeout: 300000,\n    timeoutBehavior: 'fail',\n    runAt: '2026-03-21T15:40:00.000Z',\n    startedAt: '2026-03-21T15:40:02.000Z',\n    completedAt: '2026-03-21T15:41:11.000Z',\n    lastError: 'Relationship column missing during readiness sync.',\n    resultPointer: null,\n    workerId: 'worker-governance-2',\n    createdAt: '2026-03-21T15:39:30.000Z',\n    updatedAt: '2026-03-21T15:41:11.000Z',\n  },\n  {\n    id: 'job-export-3',\n    queue: 'exports',\n    objectType: '@happyvertical/smrt-content:ArticleCollection',\n    objectId: null,\n    method: 'buildStaticFeed',\n    args: { destination: 'cdn' },\n    status: 'completed',\n    priority: 40,\n    attempts: 1,\n    maxAttempts: 2,\n    timeout: 900000,\n    timeoutBehavior: 'warn',\n    runAt: '2026-03-21T14:30:00.000Z',\n    startedAt: '2026-03-21T14:30:00.000Z',\n    completedAt: '2026-03-21T14:31:25.000Z',\n    lastError: null,\n    resultPointer: 'results/exports/build-static-feed-3.json',\n    workerId: 'worker-export-1',\n    createdAt: '2026-03-21T14:29:52.000Z',\n    updatedAt: '2026-03-21T14:31:25.000Z',\n  },\n];\n\nconst sampleStats = {\n  total: 3421,\n  pending: 24,\n  ready: 13,\n  running: 4,\n  completed: 3340,\n  failed: 31,\n  cancelled: 9,\n  avgDuration: 18450,\n  successRate: 0.976,\n};\n\nconst sampleQueues = [\n  {\n    name: 'content',\n    pending: 8,\n    running: 2,\n    completed24h: 412,\n    failed24h: 4,\n    avgDuration: 22800,\n  },\n  {\n    name: 'governance',\n    pending: 5,\n    running: 1,\n    completed24h: 188,\n    failed24h: 7,\n    avgDuration: 31200,\n  },\n  {\n    name: 'exports',\n    pending: 11,\n    running: 1,\n    completed24h: 94,\n    failed24h: 1,\n    avgDuration: 52200,\n  },\n];\n\nconst loadJobDashboard = () => import('./components/JobDashboard.svelte');\nconst loadJobDetail = () => import('./components/JobDetail.svelte');\nconst loadJobStatusBadge = () => import('./components/JobStatusBadge.svelte');\n\nexport default {\n  packageName: '@happyvertical/smrt-jobs',\n  displayName: JOBS_MODULE_META.displayName,\n  description: JOBS_MODULE_META.description,\n  moduleMeta: JOBS_MODULE_META,\n  entries: [\n    {\n      id: 'job-dashboard',\n      title: 'Job Dashboard',\n      description:\n        'Operational overview for background job queues with recent and failed work.',\n      loadComponent: loadJobDashboard,\n      order: 1,\n      props: {\n        stats: sampleStats,\n        queues: sampleQueues,\n        recentJobs: sampleJobs,\n        failedJobs: sampleJobs.filter((job) => job.status === 'failed'),\n        onJobClick: noop,\n        onRetry: noop,\n        onCancel: noop,\n        onViewAll: noop,\n        onViewFailed: noop,\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n    {\n      id: 'job-detail',\n      title: 'Job Detail',\n      description:\n        'Detailed execution view for a single background job with retry and cancellation actions.',\n      loadComponent: loadJobDetail,\n      order: 2,\n      props: {\n        job: sampleJobs[1],\n        onRetry: noop,\n        onDelete: noop,\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n    {\n      id: 'job-status-badge',\n      title: 'Job Status Badge',\n      description: 'Compact status treatment used throughout the jobs surface.',\n      loadComponent: loadJobStatusBadge,\n      order: 3,\n      props: {\n        status: 'running',\n        size: 'md',\n      },\n      modes: {\n        mock: {\n          label: 'Mock',\n        },\n      },\n    },\n  ],\n};\n"],"names":[],"mappings":"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"}

package/dist/runner.d.ts

@@ -0,0 +1,189 @@
+import { EventEmitter } from 'node:events';
+import { DatabaseInterface } from '@happyvertical/sql';
+import { SmrtJob } from './smrt-job.js';
+import { SmrtJobEvent } from './smrt-job-event.js';
+/**
+ * TaskRunner configuration
+ */
+export interface TaskRunnerConfig {
+    /** Worker ID (auto-generated if not provided) */
+    id?: string;
+    /** Number of concurrent jobs to process */
+    concurrency?: number;
+    /** Queues to process (default: ['default']) */
+    queues?: string[];
+    /** Polling interval in milliseconds */
+    pollInterval?: number;
+    /** Heartbeat interval in milliseconds */
+    heartbeatInterval?: number;
+    /** Maximum time to wait for jobs to complete on shutdown */
+    shutdownTimeout?: number;
+    /**
+     * @deprecated No longer used. Recovery keys on worker liveness, not per-job
+     * heartbeat staleness (#1474). Use {@link leaseTtlMs} / {@link leaseTickMs}.
+     */
+    staleJobThresholdMs?: number;
+    /** Worker liveness lease time-to-live in milliseconds */
+    leaseTtlMs?: number;
+    /** How often to renew the worker liveness lease, in milliseconds */
+    leaseTickMs?: number;
+}
+/**
+ * TaskRunner events
+ */
+export interface TaskRunnerEvents {
+    'job:started': (job: SmrtJob) => void;
+    'job:event': (job: SmrtJob, event: SmrtJobEvent) => void;
+    'job:progress': (job: SmrtJob, event: SmrtJobEvent) => void;
+    'job:completed': (job: SmrtJob, result: unknown) => void;
+    'job:failed': (job: SmrtJob, error: Error) => void;
+    'job:retrying': (job: SmrtJob, error: Error, delay: number) => void;
+    'runner:started': () => void;
+    'runner:stopped': () => void;
+    'runner:error': (error: Error) => void;
+}
+/**
+ * TaskRunner processes SMRT jobs by invoking methods on SmrtObjects
+ *
+ * Features:
+ * - Executes jobs via SmrtObject method invocation
+ * - Configurable concurrency and timeout behavior
+ * - Automatic retry with configurable strategies
+ * - Job context logging for visibility
+ * - Embedded mode (in-process) or standalone (CLI)
+ */
+export declare class TaskRunner extends EventEmitter {
+    readonly id: string;
+    /**
+     * Per-incarnation-unique worker key. Stored as the `worker_id` on claimed
+     * jobs and in `_smrt_workers`, so a restart of a runner sharing the same
+     * configured `id` does not look like it still owns the previous
+     * incarnation's orphaned jobs. The human-facing {@link id} stays stable for
+     * events/logs.
+     */
+    private readonly workerKey;
+    private readonly config;
+    private readonly effectiveLeaseTtlMs;
+    private collection;
+    private eventCollection;
+    private workerCollection;
+    private workersTableVerified;
+    private lastRecoverySweepAt;
+    private running;
+    private activeJobs;
+    private pollTimer;
+    private heartbeatTimer;
+    private leaseTimer;
+    private livenessWorker;
+    private shutdownPromise;
+    private db;
+    private logger;
+    constructor(config?: TaskRunnerConfig);
+    /**
+     * Initialize the runner with database connection
+     */
+    initialize(db: DatabaseInterface): Promise<void>;
+    /**
+     * Start processing jobs
+     */
+    start(): Promise<void>;
+    /**
+     * Stop processing jobs (graceful shutdown)
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if runner is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get count of active jobs
+     */
+    activeJobCount(): number;
+    /**
+     * Start the polling loop
+     */
+    private startPolling;
+    /**
+     * Poll for and process jobs
+     */
+    private poll;
+    /**
+     * Process a single job
+     */
+    private processJob;
+    /**
+     * Apply a terminal/retry state transition to a job only if this worker still
+     * owns it and it is still `running`. Returns whether the write applied.
+     *
+     * This closes the completion-vs-recovery race: if recovery already failed a
+     * job out from under a finishing handler (a genuine zombie), the handler's
+     * outcome is dropped rather than resurrecting the row.
+     */
+    private writeOwnedJob;
+    /**
+     * Execute a job by invoking the method on the SmrtObject
+     */
+    private executeJob;
+    /**
+     * Handle job execution error
+     */
+    private handleJobError;
+    private createExecutionContext;
+    private appendJobEvent;
+    /**
+     * Whether the `_smrt_workers` table exists. Cached once positive — the table
+     * never disappears mid-run, so this avoids a probe query on every poll.
+     */
+    private workersTableReady;
+    /**
+     * Recover jobs orphaned by dead/restarted workers.
+     *
+     * A `running` job is recovered only when its owning worker is *not alive*
+     * (issue #1474): not live in this process and holding no fresh lease in
+     * `_smrt_workers`. This is independent of the handler event loop, so a worker
+     * whose handler holds the loop synchronously keeps a fresh lease (renewed off
+     * the loop by the liveness thread) or stays in this process's live set, and is
+     * never false-recovered. The live set takes precedence over a stale lease, and
+     * a runner never recovers its own active jobs.
+     *
+     * Recovery is swept at most once per lease tick (not every poll), since
+     * detection is TTL-bound anyway — this bounds the per-poll database load.
+     */
+    private recoverStaleJobs;
+    /**
+     * Renew this worker's liveness lease.
+     *
+     * In Stage 1 this runs on the main event loop, so it provides cross-process
+     * detection no weaker than the old per-job heartbeat. Stage 2 moves the
+     * renewal to an off-loop worker thread so a synchronous handler can no longer
+     * starve it. Same-process correctness never depends on this timer — the
+     * in-memory live set covers it.
+     */
+    private startLeaseRenewal;
+    /**
+     * Spawn the off-loop liveness thread. It opens its own connection and renews
+     * this worker's lease on its own thread (unstarvable by handler CPU). Returns
+     * false if the thread can't be resolved or fails to start, so the caller can
+     * fall back to main-loop renewal.
+     */
+    private startLivenessThread;
+    private handleLivenessThreadLoss;
+    /** Stop the liveness thread (graceful, with a short bound), if running. */
+    private stopLivenessThread;
+    /**
+     * Per-job heartbeat loop — telemetry only ("last activity" for the UI). It no
+     * longer gates recovery (that is the worker lease), so a blocked loop missing
+     * a heartbeat is harmless.
+     */
+    private startHeartbeat;
+    /**
+     * Wait for active jobs to complete with timeout
+     */
+    private waitForActiveJobs;
+}
+/**
+ * Create a TaskRunner instance
+ */
+export declare function createTaskRunner(config?: TaskRunnerConfig): TaskRunner;
+export default TaskRunner;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/dist/runner.js

@@ -0,0 +1,15 @@
+import { T, l, T as T2 } from "./chunks/runner-DV8FBO0y.js";
+import "node:events";
+import "node:worker_threads";
+import "@happyvertical/jobs";
+import "@happyvertical/logger";
+import "@happyvertical/smrt-core";
+import "@happyvertical/smrt-tenancy";
+import "@happyvertical/utils";
+import "./chunks/worker-liveness-DOTjoIjr.js";
+export {
+  T as TaskRunner,
+  l as createTaskRunner,
+  T2 as default
+};
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}

package/dist/schedule-runner.d.ts

@@ -0,0 +1,151 @@
+import { EventEmitter } from 'node:events';
+import { DatabaseInterface } from '@happyvertical/sql';
+/**
+ * ScheduleRunner configuration
+ */
+export interface ScheduleRunnerConfig {
+    /** Runner ID (auto-generated if not provided) */
+    id?: string;
+    /** Polling interval in milliseconds (default: 60000 - 1 minute) */
+    pollInterval?: number;
+    /** Maximum schedules to process per poll */
+    batchSize?: number;
+    /**
+     * @deprecated No longer used. Slot reconciliation keys on worker liveness
+     * (the `_smrt_workers` lease), not per-job heartbeat staleness (#1474).
+     */
+    staleJobThresholdMs?: number;
+    /**
+     * @deprecated No longer used. See {@link staleJobThresholdMs}.
+     */
+    taskHeartbeatInterval?: number;
+}
+/**
+ * ScheduleRunner events
+ */
+export interface ScheduleRunnerEvents {
+    'schedule:triggered': (schedule: ScheduleInfo) => void;
+    'schedule:error': (schedule: ScheduleInfo, error: Error) => void;
+    'schedule:completed': (scheduleId: string) => void;
+    'schedule:failed': (scheduleId: string, error: string) => void;
+    'runner:started': () => void;
+    'runner:stopped': () => void;
+    'runner:error': (error: Error) => void;
+}
+/**
+ * Schedule info for events
+ */
+export interface ScheduleInfo {
+    id: string;
+    agentType: string;
+    agentId: string | null;
+    cron: string;
+}
+/**
+ * ScheduleRunner polls for due agent schedules and creates jobs for them
+ *
+ * This runner works in conjunction with TaskRunner:
+ * 1. ScheduleRunner checks for due schedules based on cron expressions
+ * 2. When a schedule is due, it creates a SmrtJob for the agent
+ * 3. TaskRunner picks up and executes the job
+ * 4. On job completion/failure, call handleJobCompletion() to update the schedule
+ *
+ * @example
+ * ```typescript
+ * const scheduleRunner = new ScheduleRunner({ pollInterval: 30000 });
+ * await scheduleRunner.initialize(db);
+ * await scheduleRunner.start();
+ *
+ * // Wire up TaskRunner events to update schedule state
+ * taskRunner.on('job:completed', (job) => {
+ *   const scheduleId = job.args?._scheduleId;
+ *   if (scheduleId) scheduleRunner.handleJobCompletion(scheduleId, true);
+ * });
+ * taskRunner.on('job:failed', (job, error) => {
+ *   const scheduleId = job.args?._scheduleId;
+ *   if (scheduleId) scheduleRunner.handleJobCompletion(scheduleId, false, error.message);
+ * });
+ *
+ * // Graceful shutdown
+ * process.on('SIGTERM', () => scheduleRunner.stop());
+ * ```
+ */
+export declare class ScheduleRunner extends EventEmitter {
+    readonly id: string;
+    private readonly config;
+    private jobCollection;
+    private workerCollection;
+    private running;
+    private pollTimer;
+    private db;
+    private logger;
+    constructor(config?: ScheduleRunnerConfig);
+    /**
+     * Initialize the runner with database connection
+     */
+    initialize(db: DatabaseInterface): Promise<void>;
+    /**
+     * Start processing schedules
+     */
+    start(): Promise<void>;
+    /**
+     * Stop processing schedules
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if runner is running
+     */
+    isRunning(): boolean;
+    /**
+     * Handle job completion for a scheduled job.
+     *
+     * Call this from TaskRunner's job:completed / job:failed events
+     * when the job has a `_scheduleId` in its args.
+     */
+    handleJobCompletion(scheduleId: string, success: boolean, errorMessage?: string): Promise<void>;
+    /**
+     * Start the polling loop
+     */
+    private startPolling;
+    /**
+     * Poll for due schedules and create jobs
+     */
+    private poll;
+    /**
+     * Reconcile stuck schedule slots against running jobs.
+     *
+     * This handles two failure modes:
+     * - a running job's owning worker is no longer alive (dead/restarted)
+     * - a schedule slot remains occupied even though no running job still exists
+     *
+     * Staleness keys on worker *liveness* (issue #1474), not per-job heartbeat
+     * freshness: a job whose `worker_id` is live in this process or holds a fresh
+     * lease in `_smrt_workers` is healthy even if its handler is holding the loop
+     * synchronously. ScheduleRunner has no in-process active-job set, so this is
+     * its entire correctness mechanism.
+     */
+    private recoverStaleScheduleState;
+    private getScheduleIdFromJobArgs;
+    /**
+     * Trigger a schedule by creating a job
+     */
+    private triggerSchedule;
+}
+/**
+ * Validate a standard 5-field cron expression: field count plus per-field
+ * value ranges. Throws a descriptive `Error` on the first invalid field.
+ *
+ * Exposed so callers (and the agents package, which owns schedule creation)
+ * can reject a bad cron at write time rather than letting an out-of-range
+ * field silently never match (S5 audit #1402).
+ *
+ * @param cron - The cron expression to validate.
+ * @returns The trimmed, whitespace-split fields when valid.
+ */
+export declare function validateCronExpression(cron: string): string[];
+/**
+ * Create a ScheduleRunner instance
+ */
+export declare function createScheduleRunner(config?: ScheduleRunnerConfig): ScheduleRunner;
+export default ScheduleRunner;
+//# sourceMappingURL=schedule-runner.d.ts.map

package/dist/schedule-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule-runner.d.ts","sourceRoot":"","sources":["../src/schedule-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAW5D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACvD,gBAAgB,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjE,oBAAoB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,iBAAiB,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/D,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,gBAAgB,CAAqC;IAC7D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,EAAE,CAAkC;IAC5C,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,GAAE,oBAAyB;IAU7C;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;OAKG;IACG,mBAAmB,CACvB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAgDhB;;OAEG;IACH,OAAO,CAAC,YAAY;IAqBpB;;OAEG;YACW,IAAI;IAyBlB;;;;;;;;;;;;OAYG;YACW,yBAAyB;IA4IvC,OAAO,CAAC,wBAAwB;IA0BhC;;OAEG;YACW,eAAe;CA0G9B;AAwGD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAa7D;AAwGD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,cAAc,CAEhB;AAED,eAAe,cAAc,CAAC"}