@teamvibe/poller 0.2.5 → 0.3.0

package/dist/heartbeat-manager.js

@@ -3,6 +3,10 @@ import { config } from './config.js';
 import { logger } from './logger.js';
 import { isAtCapacity } from './claude-spawner.js';
 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 { join } from 'path';
 const trackedBrains = new Map();
 let heartbeatJob = null;
 let maintenanceJob = null;
@@ -17,6 +21,7 @@ export function registerBrain(msg) {
     // Don't register from heartbeat/maintenance messages (avoid self-referential loop)
     if (msg.source === 'heartbeat' || msg.source === 'maintenance')
         return;
+    const isNew = !trackedBrains.has(brain.brainId);
     trackedBrains.set(brain.brainId, {
         brainId: brain.brainId,
         gitRepoUrl: brain.gitRepoUrl,
@@ -27,6 +32,23 @@ export function registerBrain(msg) {
         channelId: msg.teamvibe.channelId,
     });
     logger.debug(`[Heartbeat] Registered brain: ${brain.brainId}`);
+    // Metrics pipeline (teamvibe.ai#110): register for hourly collection. On the
+    // first sighting of this brain, fire one immediate collect+send so we don't
+    // wait up to an hour for the first sample.
+    registerBrainForMetrics(brain.brainId);
+    if (isNew) {
+        const brainId = brain.brainId;
+        void (async () => {
+            try {
+                const brainPath = join(config.BRAINS_PATH, brainId);
+                const payload = await collectMetrics(brainPath, brainId);
+                await sendMetrics(payload);
+            }
+            catch (err) {
+                logger.warn(`[Metrics] Initial send failed for ${brainId}: ${err instanceof Error ? err.message : err}`);
+            }
+        })();
+    }
 }
 /**
  * Send a synthetic message to all tracked brains.

package/dist/metrics/collector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * v1 metrics payload — see teamvibeai/teamvibe.ai#110 (revised post-review 2026-05-21).
+ *
+ * All measures are OPTIONAL: a missing field means "this measure could not be
+ * collected" (file absent, glob failed, command unavailable, etc.). Timestream
+ * handles sparse measures natively — never send a zero in place of a real omission.
+ */
+export interface MetricsPayload {
+    brainId: string;
+    todayMdBytes?: number;
+    todayMdLines?: number;
+    summaryMdBytes?: number;
+    summaryMdLines?: number;
+    brainDirBytes?: number;
+    vmDiskFreeBytes?: number;
+    vmDiskUsedBytes?: number;
+    inboxUnreadFiles?: number;
+    inboxTotalFiles?: number;
+    oldestInboxMessageAgeSeconds?: number;
+    uncommittedChangeCount?: number;
+    daysSinceMaintenance?: number;
+    timestamp?: string;
+}
+/**
+ * Collect all v1 metrics for a brain. Never throws — individual collector
+ * failures cause the corresponding measure to be omitted from the result.
+ */
+export declare function collectMetrics(brainPath: string, brainId: string): Promise<MetricsPayload>;

package/dist/metrics/collector.js

@@ -0,0 +1,214 @@
+import { stat, readdir, readFile } from 'fs/promises';
+import { statfs } from 'fs';
+import { promisify } from 'util';
+import { execFile } from 'child_process';
+import { join } from 'path';
+const statfsAsync = promisify(statfs);
+const execFileAsync = promisify(execFile);
+const MS_PER_DAY = 86_400_000;
+/**
+ * Recursively sum file sizes under a directory.
+ * Skips entries we cannot stat (permission errors, broken symlinks).
+ */
+async function dirSizeBytes(path) {
+    let total = 0;
+    let entries;
+    try {
+        entries = await readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const full = join(path, entry.name);
+        try {
+            if (entry.isDirectory()) {
+                total += await dirSizeBytes(full);
+            }
+            else if (entry.isFile()) {
+                const s = await stat(full);
+                total += s.size;
+            }
+            // Skip symlinks/sockets/etc.
+        }
+        catch {
+            // Single broken entry shouldn't tank the whole walk.
+        }
+    }
+    return total;
+}
+/**
+ * Count newline characters in a file. Returns line count using newline-count
+ * semantics (a trailing newline = N lines, no trailing newline = N-1 lines —
+ * matches what `wc -l` would have reported).
+ */
+async function countLines(path) {
+    const content = await readFile(path, 'utf-8');
+    let count = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 10 /* \n */)
+            count++;
+    }
+    return count;
+}
+/**
+ * Find files matching .inbox/<thread>/new/* under brainPath.
+ * Returns absolute paths. Throws if the .inbox directory itself is unreadable —
+ * caller wraps in try/catch and omits the measure on any failure.
+ */
+async function listInboxUnreadFiles(brainPath) {
+    const inboxRoot = join(brainPath, '.inbox');
+    const threads = (await readdir(inboxRoot, { withFileTypes: true }));
+    const files = [];
+    for (const t of threads) {
+        if (!t.isDirectory())
+            continue;
+        const newDir = join(inboxRoot, t.name, 'new');
+        let entries;
+        try {
+            entries = (await readdir(newDir, { withFileTypes: true }));
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isFile())
+                files.push(join(newDir, e.name));
+        }
+    }
+    return files;
+}
+/**
+ * Count regular files anywhere under brainPath/.inbox.
+ */
+async function countInboxTotalFiles(brainPath) {
+    const inboxRoot = join(brainPath, '.inbox');
+    let count = 0;
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = (await readdir(dir, { withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(full);
+            }
+            else if (e.isFile()) {
+                count++;
+            }
+        }
+    }
+    await walk(inboxRoot);
+    return count;
+}
+/**
+ * Collect all v1 metrics for a brain. Never throws — individual collector
+ * failures cause the corresponding measure to be omitted from the result.
+ */
+export async function collectMetrics(brainPath, brainId) {
+    const payload = {
+        brainId,
+        timestamp: new Date().toISOString(),
+    };
+    // memory/TODAY.md size + line count
+    try {
+        const todayPath = join(brainPath, 'memory/TODAY.md');
+        const s = await stat(todayPath);
+        payload.todayMdBytes = s.size;
+        payload.todayMdLines = await countLines(todayPath);
+    }
+    catch {
+        // File missing or unreadable — omit both measures.
+    }
+    // memory/SUMMARY.md size + line count
+    try {
+        const summaryPath = join(brainPath, 'memory/SUMMARY.md');
+        const s = await stat(summaryPath);
+        payload.summaryMdBytes = s.size;
+        payload.summaryMdLines = await countLines(summaryPath);
+    }
+    catch {
+        // omit
+    }
+    // brain dir total size
+    try {
+        payload.brainDirBytes = await dirSizeBytes(brainPath);
+    }
+    catch {
+        // omit
+    }
+    // VM disk usage (root filesystem)
+    try {
+        const fs = await statfsAsync('/');
+        // fs.bsize × fs.bfree = free bytes
+        // fs.bsize × (fs.blocks - fs.bfree) = used bytes
+        payload.vmDiskFreeBytes = fs.bsize * fs.bfree;
+        payload.vmDiskUsedBytes = fs.bsize * (fs.blocks - fs.bfree);
+    }
+    catch {
+        // omit
+    }
+    // days since maintenance — fractional, from .last_consolidation mtime
+    try {
+        const guardPath = join(brainPath, 'memory/.last_consolidation');
+        const s = await stat(guardPath);
+        payload.daysSinceMaintenance = (Date.now() - s.mtimeMs) / MS_PER_DAY;
+    }
+    catch {
+        // Guard file may legitimately not exist (new brain, never consolidated).
+        // Omit rather than send a misleading 0.
+    }
+    // Inbox: unread files (.inbox/<thread>/new/*)
+    try {
+        const unread = await listInboxUnreadFiles(brainPath);
+        payload.inboxUnreadFiles = unread.length;
+        // Oldest unread message age — same source, single walk would be cheaper
+        // but we already have the paths and the volume is small.
+        if (unread.length === 0) {
+            payload.oldestInboxMessageAgeSeconds = 0;
+        }
+        else {
+            let minMtime = Infinity;
+            for (const f of unread) {
+                try {
+                    const s = await stat(f);
+                    if (s.mtimeMs < minMtime)
+                        minMtime = s.mtimeMs;
+                }
+                catch {
+                    // skip
+                }
+            }
+            if (minMtime !== Infinity) {
+                payload.oldestInboxMessageAgeSeconds = Math.floor((Date.now() - minMtime) / 1000);
+            }
+        }
+    }
+    catch {
+        // Per Jarvis's review: different poller versions may lay out .inbox/ differently.
+        // Omit measures rather than fail the batch.
+    }
+    // Inbox: total files (anywhere under .inbox)
+    try {
+        payload.inboxTotalFiles = await countInboxTotalFiles(brainPath);
+    }
+    catch {
+        // omit
+    }
+    // Uncommitted change count — git status --porcelain
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', brainPath, 'status', '--porcelain'], {
+            timeout: 5000,
+        });
+        // Each non-empty line = one tracked change.
+        payload.uncommittedChangeCount = stdout.split('\n').filter((l) => l.length > 0).length;
+    }
+    catch {
+        // Non-git brain, missing git binary, timeout — omit.
+    }
+    return payload;
+}

package/dist/metrics/scheduler.d.ts

@@ -0,0 +1,52 @@
+interface RegisteredBrain {
+    brainId: string;
+}
+/**
+ * Register (or update) a brain for hourly metrics collection.
+ * Safe to call repeatedly with the same brainId.
+ */
+export declare function registerBrainForMetrics(brainId: string): void;
+/**
+ * Deterministic 32-bit FNV-1a hash of a string. Used to derive a stable
+ * per-brain jitter offset for hourly cron alignment (see #110 review):
+ * at fleet scale (100+ brains) we don't want every brain to fire at exactly
+ * UTC :00:00 — Lambda cold-start storm + Timestream write throttle risk.
+ *
+ * No crypto needed; we only need a stable, well-distributed integer.
+ */
+export declare function hashBrainId(s: string): number;
+/**
+ * Per-brain deterministic jitter offset in [0, JITTER_WINDOW_MS).
+ * Two brains with different ids should normally land on different offsets;
+ * the same brain id always lands on the same offset.
+ */
+export declare function jitterMsFor(brainId: string): number;
+/**
+ * Cron handler: fan out to every registered brain on its deterministic
+ * per-brain jitter offset (0–10 min after UTC :00). This avoids a thundering
+ * herd of metric writes at the exact hour boundary while keeping the
+ * per-brain offset stable (= no clock drift across hours).
+ *
+ * Exported for tests so they can fire the handler manually.
+ */
+export declare function collectAndSendAll(): void;
+/**
+ * Start the hourly metrics cron. Fires once per UTC hour boundary; each tick
+ * fans out per-brain on a deterministic jitter offset (0–10min).
+ *
+ * Idempotent: re-invocation while already running is a no-op.
+ */
+export declare function startMetricsCron(): void;
+/**
+ * Stop the metrics cron. Safe to call multiple times.
+ */
+export declare function stopMetricsCron(): void;
+/**
+ * Test-only: clear registered brain list.
+ */
+export declare function _resetForTests(): void;
+/**
+ * Test-only: read registered brains (returns a snapshot copy).
+ */
+export declare function _getRegisteredForTests(): RegisteredBrain[];
+export {};

package/dist/metrics/scheduler.js

@@ -0,0 +1,127 @@
+import { join } from 'path';
+import { Cron } from 'croner';
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+import { collectMetrics } from './collector.js';
+import { sendMetrics } from './sender.js';
+const JITTER_WINDOW_MS = 10 * 60 * 1000; // 10 minutes spread per #110 review
+const registered = new Map();
+const pendingJitterTimers = new Set();
+let metricsJob = null;
+/**
+ * Register (or update) a brain for hourly metrics collection.
+ * Safe to call repeatedly with the same brainId.
+ */
+export function registerBrainForMetrics(brainId) {
+    if (!brainId)
+        return;
+    registered.set(brainId, { brainId });
+}
+/**
+ * Collect + send metrics for a single brain. Never throws.
+ */
+async function collectAndSendOne(brain) {
+    try {
+        const brainPath = join(config.BRAINS_PATH, brain.brainId);
+        const payload = await collectMetrics(brainPath, brain.brainId);
+        await sendMetrics(payload);
+    }
+    catch (err) {
+        // Defensive: collector/sender already swallow their own errors, but if
+        // anything escapes (e.g. path resolution, unexpected runtime fault) we
+        // log and move on rather than crashing the cron tick.
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[Metrics] Unexpected failure for brain ${brain.brainId}: ${msg}`);
+    }
+}
+/**
+ * Deterministic 32-bit FNV-1a hash of a string. Used to derive a stable
+ * per-brain jitter offset for hourly cron alignment (see #110 review):
+ * at fleet scale (100+ brains) we don't want every brain to fire at exactly
+ * UTC :00:00 — Lambda cold-start storm + Timestream write throttle risk.
+ *
+ * No crypto needed; we only need a stable, well-distributed integer.
+ */
+export function hashBrainId(s) {
+    let h = 0x811c9dc5; // FNV offset basis
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        // FNV prime is 0x01000193; use Math.imul for 32-bit overflow semantics.
+        h = Math.imul(h, 0x01000193);
+    }
+    // Coerce to unsigned 32-bit.
+    return h >>> 0;
+}
+/**
+ * Per-brain deterministic jitter offset in [0, JITTER_WINDOW_MS).
+ * Two brains with different ids should normally land on different offsets;
+ * the same brain id always lands on the same offset.
+ */
+export function jitterMsFor(brainId) {
+    return hashBrainId(brainId) % JITTER_WINDOW_MS;
+}
+/**
+ * Cron handler: fan out to every registered brain on its deterministic
+ * per-brain jitter offset (0–10 min after UTC :00). This avoids a thundering
+ * herd of metric writes at the exact hour boundary while keeping the
+ * per-brain offset stable (= no clock drift across hours).
+ *
+ * Exported for tests so they can fire the handler manually.
+ */
+export function collectAndSendAll() {
+    if (registered.size === 0)
+        return;
+    const brains = Array.from(registered.values());
+    for (const brain of brains) {
+        const delay = jitterMsFor(brain.brainId);
+        const timer = setTimeout(() => {
+            pendingJitterTimers.delete(timer);
+            void collectAndSendOne(brain);
+        }, delay);
+        pendingJitterTimers.add(timer);
+    }
+}
+/**
+ * Start the hourly metrics cron. Fires once per UTC hour boundary; each tick
+ * fans out per-brain on a deterministic jitter offset (0–10min).
+ *
+ * Idempotent: re-invocation while already running is a no-op.
+ */
+export function startMetricsCron() {
+    if (metricsJob)
+        return;
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        // No-op in direct (non-token) mode.
+        return;
+    }
+    logger.info('[Metrics] Starting hourly cron: "0 * * * *" UTC (per-brain jitter 0–10min)');
+    metricsJob = new Cron('0 * * * *', { timezone: 'UTC', protect: true }, () => {
+        collectAndSendAll();
+    });
+}
+/**
+ * Stop the metrics cron. Safe to call multiple times.
+ */
+export function stopMetricsCron() {
+    if (metricsJob) {
+        metricsJob.stop();
+        metricsJob = null;
+    }
+    for (const timer of pendingJitterTimers) {
+        clearTimeout(timer);
+    }
+    pendingJitterTimers.clear();
+}
+/**
+ * Test-only: clear registered brain list.
+ */
+export function _resetForTests() {
+    registered.clear();
+    stopMetricsCron();
+}
+/**
+ * Test-only: read registered brains (returns a snapshot copy).
+ */
+export function _getRegisteredForTests() {
+    return Array.from(registered.values());
+}

package/dist/metrics/sender.d.ts

@@ -0,0 +1,10 @@
+import type { MetricsPayload } from './collector.js';
+/**
+ * Send a metrics payload to the platform. Fail-safe:
+ * - 5s timeout per attempt
+ * - 1 retry after 30s on non-2xx or network failure
+ * - Never throws
+ *
+ * Returns true on success, false if both attempts failed (caller can log/ignore).
+ */
+export declare function sendMetrics(payload: MetricsPayload): Promise<boolean>;

package/dist/metrics/sender.js

@@ -0,0 +1,58 @@
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+const SEND_TIMEOUT_MS = 5_000;
+const RETRY_DELAY_MS = 30_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function postOnce(payload) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${config.TEAMVIBE_API_URL}/metrics`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${config.TEAMVIBE_POLLER_TOKEN}`,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            logger.warn(`[Metrics] Send failed: ${response.status} for brain ${payload.brainId}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[Metrics] Send error for brain ${payload.brainId}: ${msg}`);
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Send a metrics payload to the platform. Fail-safe:
+ * - 5s timeout per attempt
+ * - 1 retry after 30s on non-2xx or network failure
+ * - Never throws
+ *
+ * Returns true on success, false if both attempts failed (caller can log/ignore).
+ */
+export async function sendMetrics(payload) {
+    if (!config.TEAMVIBE_API_URL || !config.TEAMVIBE_POLLER_TOKEN) {
+        // Direct (non-token) mode — metrics endpoint isn't reachable. No-op.
+        return false;
+    }
+    const ok = await postOnce(payload);
+    if (ok)
+        return true;
+    await sleep(RETRY_DELAY_MS);
+    const retried = await postOnce(payload);
+    if (!retried) {
+        logger.warn(`[Metrics] Dropping payload for brain ${payload.brainId} after 1 retry`);
+    }
+    return retried;
+}

package/dist/poller.js

@@ -9,6 +9,7 @@ import { postMaintenanceReports } from './maintenance-reporter.js';
 import { initAuth, stopRefresh } from './auth-provider.js';
 import { registerBrain, startHeartbeatLoop, stopHeartbeatLoop } from './heartbeat-manager.js';
 import { startEventQueue, stopEventQueue, flush as flushEventQueue, emitEvent } from './event-queue.js';
+import { startMetricsCron, stopMetricsCron } from './metrics/scheduler.js';
 import { writeMessage, pickNextMessage, markProcessed, markFailed, hasUnprocessed } from './inbox-manager.js';
 import { Cron } from 'croner';
 import { isControlMessage, handleControlMessage } from './control-handler.js';
@@ -464,6 +465,7 @@ async function shutdown(signal, exitCode = 0) {
     stopRefresh();
     stopHeartbeatLoop();
     stopAutoUpdateCron();
+    stopMetricsCron();
     stopEventQueue();
     // Kill all active Claude child processes
     await killAllActiveProcesses();
@@ -502,5 +504,6 @@ export async function startPoller() {
     await ensureBaseBrain();
     startHeartbeatLoop(processMessage);
     startAutoUpdateCron();
+    startMetricsCron();
     await pollLoop();
 }

package/package.json

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