@teamvibe/poller 0.3.0 → 0.4.0

package/dist/cron-telemetry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Module-scoped state for poller-level cron-job telemetry.
+ *
+ * Per teamvibeai/teamvibe.ai#119, the metrics collector reports six measures:
+ *   last{Heartbeat,Maintenance,AutoUpdate}Job{,Success}Ms
+ * each computed as `Date.now() - storedTs` at collection time, with the
+ * measure omitted entirely when the cron has never fired (storedTs null).
+ *
+ * Pulled out of heartbeat-manager.ts / poller.ts into a dedicated module to
+ * avoid a circular import — the metrics collector reads from these getters,
+ * and heartbeat-manager.ts already imports from the collector.
+ */
+export declare function markHeartbeatJobFired(at?: number): void;
+export declare function markHeartbeatJobSuccess(at?: number): void;
+export declare function markMaintenanceJobFired(at?: number): void;
+export declare function markMaintenanceJobSuccess(at?: number): void;
+export declare function markAutoUpdateJobFired(at?: number): void;
+export declare function markAutoUpdateJobSuccess(at?: number): void;
+export interface CronJobTimestamps {
+    lastHeartbeatJobFiredAt: number | null;
+    lastHeartbeatJobSuccessAt: number | null;
+    lastMaintenanceJobFiredAt: number | null;
+    lastMaintenanceJobSuccessAt: number | null;
+    lastAutoUpdateJobFiredAt: number | null;
+    lastAutoUpdateJobSuccessAt: number | null;
+}
+export declare function getCronJobTimestamps(): CronJobTimestamps;
+/**
+ * Test-only helper to clear telemetry between tests.
+ * @internal
+ */
+export declare function __resetCronTelemetryForTest(): void;

package/dist/cron-telemetry.js

@@ -0,0 +1,58 @@
+/**
+ * Module-scoped state for poller-level cron-job telemetry.
+ *
+ * Per teamvibeai/teamvibe.ai#119, the metrics collector reports six measures:
+ *   last{Heartbeat,Maintenance,AutoUpdate}Job{,Success}Ms
+ * each computed as `Date.now() - storedTs` at collection time, with the
+ * measure omitted entirely when the cron has never fired (storedTs null).
+ *
+ * Pulled out of heartbeat-manager.ts / poller.ts into a dedicated module to
+ * avoid a circular import — the metrics collector reads from these getters,
+ * and heartbeat-manager.ts already imports from the collector.
+ */
+let lastHeartbeatJobFiredAt = null;
+let lastHeartbeatJobSuccessAt = null;
+let lastMaintenanceJobFiredAt = null;
+let lastMaintenanceJobSuccessAt = null;
+let lastAutoUpdateJobFiredAt = null;
+let lastAutoUpdateJobSuccessAt = null;
+export function markHeartbeatJobFired(at = Date.now()) {
+    lastHeartbeatJobFiredAt = at;
+}
+export function markHeartbeatJobSuccess(at = Date.now()) {
+    lastHeartbeatJobSuccessAt = at;
+}
+export function markMaintenanceJobFired(at = Date.now()) {
+    lastMaintenanceJobFiredAt = at;
+}
+export function markMaintenanceJobSuccess(at = Date.now()) {
+    lastMaintenanceJobSuccessAt = at;
+}
+export function markAutoUpdateJobFired(at = Date.now()) {
+    lastAutoUpdateJobFiredAt = at;
+}
+export function markAutoUpdateJobSuccess(at = Date.now()) {
+    lastAutoUpdateJobSuccessAt = at;
+}
+export function getCronJobTimestamps() {
+    return {
+        lastHeartbeatJobFiredAt,
+        lastHeartbeatJobSuccessAt,
+        lastMaintenanceJobFiredAt,
+        lastMaintenanceJobSuccessAt,
+        lastAutoUpdateJobFiredAt,
+        lastAutoUpdateJobSuccessAt,
+    };
+}
+/**
+ * Test-only helper to clear telemetry between tests.
+ * @internal
+ */
+export function __resetCronTelemetryForTest() {
+    lastHeartbeatJobFiredAt = null;
+    lastHeartbeatJobSuccessAt = null;
+    lastMaintenanceJobFiredAt = null;
+    lastMaintenanceJobSuccessAt = null;
+    lastAutoUpdateJobFiredAt = null;
+    lastAutoUpdateJobSuccessAt = null;
+}

package/dist/heartbeat-manager.d.ts

@@ -15,6 +15,24 @@ export declare function startHeartbeatLoop(processMessageFn: (msg: {
     receiptHandle: string;
     messageId: string;
 }) => Promise<void>): void;
+/**
+ * Run the heartbeat cron handler with telemetry instrumentation (#119).
+ * Records last-fire timestamp on entry and last-success timestamp on completion.
+ * Exported for use by the cron registration above and tests that fire it manually.
+ */
+export declare function runHeartbeatJob(processMessageFn: (msg: {
+    queueMessage: TeamVibeQueueMessage;
+    receiptHandle: string;
+    messageId: string;
+}) => Promise<void>): Promise<void>;
+/**
+ * Run the maintenance cron handler with telemetry instrumentation (#119).
+ */
+export declare function runMaintenanceJob(processMessageFn: (msg: {
+    queueMessage: TeamVibeQueueMessage;
+    receiptHandle: string;
+    messageId: string;
+}) => Promise<void>): Promise<void>;
 /**
  * Stop the heartbeat and maintenance crons (for shutdown).
  */

package/dist/heartbeat-manager.js

@@ -6,6 +6,7 @@ import { emitError } from './event-queue.js';
 import { registerBrainForMetrics } from './metrics/scheduler.js';
 import { collectMetrics } from './metrics/collector.js';
 import { sendMetrics } from './metrics/sender.js';
+import { markHeartbeatJobFired, markHeartbeatJobSuccess, markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
 import { join } from 'path';
 const trackedBrains = new Map();
 let heartbeatJob = null;
@@ -115,14 +116,44 @@ export function startHeartbeatLoop(processMessageFn) {
     // Heartbeat cron — frequent, lightweight
     logger.info(`[Heartbeat] Starting heartbeat cron: "${config.HEARTBEAT_CRON}"`);
     heartbeatJob = new Cron(config.HEARTBEAT_CRON, { timezone: 'UTC', protect: true }, async () => {
-        await triggerAllBrains('heartbeat', processMessageFn);
+        await runHeartbeatJob(processMessageFn);
     });
     // Maintenance cron — daily, heavy (consolidation, memory cleanup)
     logger.info(`[Maintenance] Starting maintenance cron: "${config.MAINTENANCE_CRON}"`);
     maintenanceJob = new Cron(config.MAINTENANCE_CRON, { timezone: 'UTC', protect: true }, async () => {
-        await triggerAllBrains('maintenance', processMessageFn);
+        await runMaintenanceJob(processMessageFn);
     });
 }
+/**
+ * Run the heartbeat cron handler with telemetry instrumentation (#119).
+ * Records last-fire timestamp on entry and last-success timestamp on completion.
+ * Exported for use by the cron registration above and tests that fire it manually.
+ */
+export async function runHeartbeatJob(processMessageFn) {
+    markHeartbeatJobFired();
+    try {
+        await triggerAllBrains('heartbeat', processMessageFn);
+        markHeartbeatJobSuccess();
+    }
+    catch (e) {
+        logger.error(`[Heartbeat] heartbeatJob handler threw: ${e instanceof Error ? e.message : e}`);
+        throw e; // preserve existing behavior; croner protect handles overlap
+    }
+}
+/**
+ * Run the maintenance cron handler with telemetry instrumentation (#119).
+ */
+export async function runMaintenanceJob(processMessageFn) {
+    markMaintenanceJobFired();
+    try {
+        await triggerAllBrains('maintenance', processMessageFn);
+        markMaintenanceJobSuccess();
+    }
+    catch (e) {
+        logger.error(`[Maintenance] maintenanceJob handler threw: ${e instanceof Error ? e.message : e}`);
+        throw e;
+    }
+}
 /**
  * Stop the heartbeat and maintenance crons (for shutdown).
  */

package/dist/metrics/collector.d.ts

@@ -19,6 +19,12 @@ export interface MetricsPayload {
     oldestInboxMessageAgeSeconds?: number;
     uncommittedChangeCount?: number;
     daysSinceMaintenance?: number;
+    lastHeartbeatJobMs?: number;
+    lastHeartbeatJobSuccessMs?: number;
+    lastMaintenanceJobMs?: number;
+    lastMaintenanceJobSuccessMs?: number;
+    lastAutoUpdateJobMs?: number;
+    lastAutoUpdateJobSuccessMs?: number;
     timestamp?: string;
 }
 /**

package/dist/metrics/collector.js

@@ -3,6 +3,7 @@ import { statfs } from 'fs';
 import { promisify } from 'util';
 import { execFile } from 'child_process';
 import { join } from 'path';
+import { getCronJobTimestamps } from '../cron-telemetry.js';
 const statfsAsync = promisify(statfs);
 const execFileAsync = promisify(execFile);
 const MS_PER_DAY = 86_400_000;
@@ -210,5 +211,28 @@ export async function collectMetrics(brainPath, brainId) {
     catch {
         // Non-git brain, missing git binary, timeout — omit.
     }
+    // Poller-level cron-job telemetry (#119). Same six values for every brain on
+    // the poller — see issue body for storage cost rationale. Each measure is
+    // `now - storedTs`; if the cron has never fired (storedTs null), omit it.
+    const now = Date.now();
+    const cron = getCronJobTimestamps();
+    if (cron.lastHeartbeatJobFiredAt !== null) {
+        payload.lastHeartbeatJobMs = now - cron.lastHeartbeatJobFiredAt;
+    }
+    if (cron.lastHeartbeatJobSuccessAt !== null) {
+        payload.lastHeartbeatJobSuccessMs = now - cron.lastHeartbeatJobSuccessAt;
+    }
+    if (cron.lastMaintenanceJobFiredAt !== null) {
+        payload.lastMaintenanceJobMs = now - cron.lastMaintenanceJobFiredAt;
+    }
+    if (cron.lastMaintenanceJobSuccessAt !== null) {
+        payload.lastMaintenanceJobSuccessMs = now - cron.lastMaintenanceJobSuccessAt;
+    }
+    if (cron.lastAutoUpdateJobFiredAt !== null) {
+        payload.lastAutoUpdateJobMs = now - cron.lastAutoUpdateJobFiredAt;
+    }
+    if (cron.lastAutoUpdateJobSuccessAt !== null) {
+        payload.lastAutoUpdateJobSuccessMs = now - cron.lastAutoUpdateJobSuccessAt;
+    }
     return payload;
 }

package/dist/poller.d.ts

@@ -1 +1,11 @@
+/**
+ * Run the auto-update cron handler with telemetry instrumentation (#119).
+ * Exported for tests that fire the handler manually.
+ *
+ * `checkForUpdateFn` is injected (default = real checkForUpdate) so tests
+ * can lock in the "swallow but still mark fired" contract that
+ * distinguishes scenario (A) cron-doesn't-fire from (B/C) cron-fires-but-fails
+ * in morning-check telemetry. Same DI shape as runHeartbeatJob/runMaintenanceJob.
+ */
+export declare function runAutoUpdateJob(checkForUpdateFn?: () => Promise<boolean>): Promise<void>;
 export declare function startPoller(): Promise<void>;

package/dist/poller.js

@@ -14,6 +14,7 @@ import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocesse
 import { Cron } from 'croner';
 import { isControlMessage, handleControlMessage } from './control-handler.js';
 import { checkForUpdate } from './auto-update.js';
+import { markAutoUpdateJobFired, markAutoUpdateJobSuccess } from './cron-telemetry.js';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { platform } from 'os';
@@ -22,6 +23,30 @@ const execAsync = promisify(exec);
 const processingMessages = new Set();
 // Poller auto-update cron (separate from brain heartbeats)
 let autoUpdateJob = null;
+/**
+ * Run the auto-update cron handler with telemetry instrumentation (#119).
+ * Exported for tests that fire the handler manually.
+ *
+ * `checkForUpdateFn` is injected (default = real checkForUpdate) so tests
+ * can lock in the "swallow but still mark fired" contract that
+ * distinguishes scenario (A) cron-doesn't-fire from (B/C) cron-fires-but-fails
+ * in morning-check telemetry. Same DI shape as runHeartbeatJob/runMaintenanceJob.
+ */
+export async function runAutoUpdateJob(checkForUpdateFn = checkForUpdate) {
+    markAutoUpdateJobFired();
+    try {
+        const shouldRestart = await checkForUpdateFn();
+        markAutoUpdateJobSuccess();
+        if (shouldRestart) {
+            logger.info('[AutoUpdate] Update applied, restarting...');
+            await flushEventQueue();
+            process.exit(0);
+        }
+    }
+    catch (error) {
+        logger.error(`[AutoUpdate] Check error: ${error instanceof Error ? error.message : error}`);
+    }
+}
 function startAutoUpdateCron() {
     const schedule = config.AUTO_UPDATE_SCHEDULE;
     const match = schedule.match(/^(\d{2}):(\d{2})$/);
@@ -35,17 +60,7 @@ function startAutoUpdateCron() {
     const cronExpr = `${match[2]} ${match[1]} * * *`;
     logger.info(`[AutoUpdate] Scheduled daily at ${schedule} UTC (cron: ${cronExpr}), policy: ${config.AUTO_UPDATE_POLICY}`);
     autoUpdateJob = new Cron(cronExpr, { timezone: 'UTC' }, async () => {
-        try {
-            const shouldRestart = await checkForUpdate();
-            if (shouldRestart) {
-                logger.info('[AutoUpdate] Update applied, restarting...');
-                await flushEventQueue();
-                process.exit(0);
-            }
-        }
-        catch (error) {
-            logger.error(`[AutoUpdate] Check error: ${error instanceof Error ? error.message : error}`);
-        }
+        await runAutoUpdateJob();
     });
 }
 function stopAutoUpdateCron() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {