@teamvibe/poller 0.6.0 → 0.7.0

package/dist/inbox-watcher.js

@@ -0,0 +1,262 @@
+import { existsSync, readdirSync, rmSync, watch as fsWatch } from 'fs';
+import { join } from 'path';
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { isAtCapacity } from './claude-spawner.js';
+import { getTrackedBrains } from './maintenance-cron.js';
+import { runInboxLoop, isInboxLoopActive } from './poller.js';
+const INBOX_SUBDIRS = ['new', 'processing', 'failed'];
+let brainWatchers = new Map();
+let fallbackInterval = null;
+let debounceTimer = null;
+function defaultDeps() {
+    return {
+        brainsPath: config.BRAINS_PATH,
+        getTrackedBrains,
+        isAtCapacity,
+        isInboxLoopActive,
+        runInboxLoop,
+        rmThreadDir: (path) => rmSync(path, { recursive: true }),
+    };
+}
+/**
+ * threadId is always `<botId>:<channel>:<threadTs>` for slack-originated
+ * threads (see modules-teamvibe/hooks/slack-events.ts). Synthetic threadIds
+ * used elsewhere (`maintenance_<brainId>_<ts>`, and
+ * `scheduled:<scheduleId>:<ts>` from
+ * modules-teamvibe/src/functions/scheduler.ts:86) never sit idle waiting on
+ * a background-task drop, so they're skipped rather than guessed at.
+ * `scheduled:*:*` has the same 3-colon-segment shape as a real Slack
+ * threadId, so it's rejected explicitly rather than by segment count alone
+ * — otherwise a leftover unprocessed file in a stale scheduled-session inbox
+ * dir would make this parse `scheduleId` as a Slack channel.
+ */
+export function parseSlackThreadId(threadId) {
+    const parts = threadId.split(':');
+    if (parts.length !== 3)
+        return null;
+    const [botId, channel, threadTs] = parts;
+    if (botId === 'scheduled')
+        return null;
+    if (!channel || !threadTs)
+        return null;
+    return { channel, threadTs };
+}
+function buildSyntheticMessage(info, threadId, parsed) {
+    return {
+        id: `inbox_watch_${threadId}`,
+        source: 'slack',
+        thread_id: threadId,
+        sender: { id: 'system', name: 'Background Task' },
+        text: '',
+        attachments: [],
+        response_context: {
+            slack: {
+                channel: parsed.channel,
+                thread_ts: parsed.threadTs,
+                message_ts: parsed.threadTs,
+            },
+        },
+        type: 'message',
+        teamvibe: {
+            workspaceId: info.workspaceId,
+            botId: info.botId,
+            botToken: info.botToken,
+            channelId: info.channelId,
+            brain: {
+                brainId: info.brainId,
+                gitRepoUrl: info.gitRepoUrl,
+                branch: info.branch,
+            },
+        },
+    };
+}
+export function listThreadDirs(inboxRoot) {
+    try {
+        return readdirSync(inboxRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+export function hasNewMessage(inboxRoot, threadId) {
+    const newDir = join(inboxRoot, threadId, 'new');
+    try {
+        return existsSync(newDir) && readdirSync(newDir).some((f) => f.endsWith('.txt'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan every tracked brain's .inbox/ for a thread that has a new message but
+ * no active runInboxLoop, and start one. This is the only config-only path
+ * that can wake a fully idle session (teamvibe.ai#242) — a file dropped into
+ * .inbox/ by e.g. a background task otherwise sits inert until the next SQS
+ * message for that thread, which may never come.
+ */
+export function checkInboxForNewSessions(deps = defaultDeps()) {
+    for (const [, info] of deps.getTrackedBrains()) {
+        if (deps.isAtCapacity()) {
+            logger.debug('[InboxWatcher] At capacity, pausing scan until next tick');
+            return;
+        }
+        const brainPath = join(deps.brainsPath, info.brainId);
+        const inboxRoot = join(brainPath, '.inbox');
+        if (!existsSync(inboxRoot))
+            continue;
+        for (const threadId of listThreadDirs(inboxRoot)) {
+            if (deps.isInboxLoopActive(threadId))
+                continue;
+            if (!hasNewMessage(inboxRoot, threadId))
+                continue;
+            const parsed = parseSlackThreadId(threadId);
+            if (!parsed) {
+                logger.debug(`[InboxWatcher] Skipping ${threadId}: not a slack-shaped threadId`);
+                continue;
+            }
+            logger.info(`[InboxWatcher] New message for idle thread ${threadId}, starting session`);
+            const sessionLog = logger.createSession(`iw_${Math.random().toString(36).slice(2, 10)}`);
+            const syntheticMessage = buildSyntheticMessage(info, threadId, parsed);
+            deps.runInboxLoop(threadId, brainPath, syntheticMessage, sessionLog).catch((error) => {
+                logger.error(`[InboxWatcher] runInboxLoop failed for ${threadId}: ${error instanceof Error ? error.message : error}`);
+            });
+        }
+    }
+}
+export function isThreadDirEmpty(inboxRoot, threadId) {
+    for (const sub of INBOX_SUBDIRS) {
+        const subDir = join(inboxRoot, threadId, sub);
+        if (!existsSync(subDir))
+            continue;
+        try {
+            if (readdirSync(subDir).length > 0)
+                return false;
+        }
+        catch {
+            return false; // unreadable — leave it alone rather than guess
+        }
+    }
+    return true;
+}
+/**
+ * Remove thread dirs whose new/processing/failed subdirs are all empty (or
+ * absent) and which have no active loop right now. Safe because
+ * writeMessage() always recreates the directory tree via a recursive
+ * mkdirSync before writing (inbox-manager.ts) — deleting an empty thread dir
+ * loses nothing, and a later message for the same thread just recreates it.
+ * Bounds the number of directories fs.watch has to track, which would
+ * otherwise only grow: thread dirs are never pruned anywhere else once
+ * created.
+ */
+export function pruneEmptyInboxDirs(deps = defaultDeps()) {
+    for (const [, info] of deps.getTrackedBrains()) {
+        const inboxRoot = join(deps.brainsPath, info.brainId, '.inbox');
+        if (!existsSync(inboxRoot))
+            continue;
+        for (const threadId of listThreadDirs(inboxRoot)) {
+            if (deps.isInboxLoopActive(threadId))
+                continue;
+            if (!isThreadDirEmpty(inboxRoot, threadId))
+                continue;
+            const threadDir = join(inboxRoot, threadId);
+            try {
+                deps.rmThreadDir(threadDir);
+                logger.debug(`[InboxWatcher] Pruned empty inbox dir: ${threadId}`);
+            }
+            catch (error) {
+                // Most likely a message landed between the emptiness check and the
+                // remove (rmSync without `force` throws on a dir that's non-empty
+                // by then) — leave it for the next sweep rather than force-delete.
+                logger.debug(`[InboxWatcher] Skipped pruning ${threadId}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    }
+}
+function scheduleCheck(deps) {
+    if (debounceTimer)
+        return;
+    debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        checkInboxForNewSessions(deps);
+    }, config.INBOX_WATCH_DEBOUNCE_MS);
+}
+/**
+ * Ensure every currently-tracked brain that already has a .inbox/ dir has a
+ * live fs.watch on it. Called on startup and on every fallback sweep, so a
+ * brain seen for the first time (or one whose .inbox/ didn't exist yet at
+ * watcher-startup — a brand-new brain's first-ever message always arrives
+ * via the normal SQS path, so this isn't on the critical path) gets covered
+ * within one fallback interval.
+ *
+ * Watching `<brain>/.inbox` specifically — not the whole brain checkout —
+ * keeps the watch count proportional to inbox activity: the brain repo
+ * itself (skills/, memory/, .git/) can have orders of magnitude more
+ * directories than its inbox ever will, and a single fs.watch holds one
+ * inotify watch descriptor per directory in the watched tree (verified:
+ * 801 watch descriptors for 200 nested thread dirs, all on one shared fd).
+ */
+function syncBrainWatchers(deps) {
+    const seen = new Set();
+    for (const [, info] of deps.getTrackedBrains()) {
+        seen.add(info.brainId);
+        if (brainWatchers.has(info.brainId))
+            continue;
+        const inboxRoot = join(deps.brainsPath, info.brainId, '.inbox');
+        if (!existsSync(inboxRoot))
+            continue;
+        try {
+            const watcher = fsWatch(inboxRoot, { recursive: true }, () => scheduleCheck(deps));
+            watcher.on('error', (error) => {
+                logger.warn(`[InboxWatcher] Watch error for brain ${info.brainId}, dropping watcher: ${error.message}`);
+                brainWatchers.delete(info.brainId);
+            });
+            brainWatchers.set(info.brainId, watcher);
+            logger.debug(`[InboxWatcher] Watching ${inboxRoot}`);
+        }
+        catch (error) {
+            logger.debug(`[InboxWatcher] Could not watch ${inboxRoot} (${error instanceof Error ? error.message : error}), relying on fallback poll`);
+        }
+    }
+    for (const brainId of brainWatchers.keys()) {
+        if (!seen.has(brainId)) {
+            brainWatchers.get(brainId)?.close();
+            brainWatchers.delete(brainId);
+        }
+    }
+}
+/**
+ * Starts the fs.watch-driven wake path plus a sparse fallback sweep
+ * (default 5min) that (a) catches anything a missed/coalesced fs event
+ * dropped, (b) picks up brains whose .inbox/ didn't exist at watcher
+ * startup, and (c) prunes empty thread dirs. fs.watch gives near-instant
+ * wake; the fallback exists because relying on it exclusively would be a
+ * silent single point of failure with no observable "did it fire" signal.
+ */
+export function startInboxWatcher(deps = defaultDeps()) {
+    if (fallbackInterval)
+        return;
+    syncBrainWatchers(deps);
+    const fallbackMs = config.INBOX_WATCH_FALLBACK_INTERVAL_MS;
+    logger.info(`[InboxWatcher] Started (fs.watch on ${brainWatchers.size} brain inbox dir(s), fallback sweep every ${fallbackMs}ms)`);
+    fallbackInterval = setInterval(() => {
+        syncBrainWatchers(deps);
+        checkInboxForNewSessions(deps);
+        pruneEmptyInboxDirs(deps);
+    }, fallbackMs);
+}
+export function stopInboxWatcher() {
+    if (fallbackInterval) {
+        clearInterval(fallbackInterval);
+        fallbackInterval = null;
+    }
+    if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = null;
+    }
+    for (const watcher of brainWatchers.values())
+        watcher.close();
+    brainWatchers.clear();
+}

package/dist/maintenance-activity.d.ts

@@ -0,0 +1,18 @@
+export interface ActivityCheckDeps {
+    statFn: (path: string) => Promise<{
+        mtimeMs: number;
+    }>;
+}
+/**
+ * Poller-side half of teamvibe.ai#131: skip the nightly maintenance trigger
+ * for a brain that has had zero real (non-maintenance-sourced) activity
+ * since its last maintenance run, so a quiet brain doesn't pay for a Claude
+ * spawn just to no-op inside the session's own time-debounce guard.
+ *
+ * `lastRealMessageAt` is set by registerBrain() (maintenance-cron.ts) on
+ * every non-maintenance message. It is undefined when the poller hasn't
+ * seen one since its own last restart (trackedBrains is in-memory, #127) —
+ * in that case we fail open (never skip) rather than risk starving a brain
+ * of maintenance because of a poller restart, not actual inactivity.
+ */
+export declare function shouldSkipMaintenance(brainsPath: string, brainId: string, lastRealMessageAt: number | undefined, deps?: ActivityCheckDeps): Promise<boolean>;

package/dist/maintenance-activity.js

@@ -0,0 +1,28 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+const defaultDeps = { statFn: stat };
+/**
+ * Poller-side half of teamvibe.ai#131: skip the nightly maintenance trigger
+ * for a brain that has had zero real (non-maintenance-sourced) activity
+ * since its last maintenance run, so a quiet brain doesn't pay for a Claude
+ * spawn just to no-op inside the session's own time-debounce guard.
+ *
+ * `lastRealMessageAt` is set by registerBrain() (maintenance-cron.ts) on
+ * every non-maintenance message. It is undefined when the poller hasn't
+ * seen one since its own last restart (trackedBrains is in-memory, #127) —
+ * in that case we fail open (never skip) rather than risk starving a brain
+ * of maintenance because of a poller restart, not actual inactivity.
+ */
+export async function shouldSkipMaintenance(brainsPath, brainId, lastRealMessageAt, deps = defaultDeps) {
+    if (lastRealMessageAt === undefined)
+        return false;
+    try {
+        const guardPath = join(brainsPath, brainId, 'memory/.last_consolidation');
+        const s = await deps.statFn(guardPath);
+        return lastRealMessageAt < s.mtimeMs;
+    }
+    catch {
+        // No guard file yet (brand-new brain, never consolidated) — never skip.
+        return false;
+    }
+}

package/dist/maintenance-cron.d.ts

@@ -1,4 +1,26 @@
 import type { TeamVibeQueueMessage } from './types.js';
+export interface TrackedBrainInfo {
+    brainId: string;
+    gitRepoUrl: string;
+    branch: string;
+    workspaceId: string;
+    botId: string;
+    botToken: string;
+    channelId: string;
+    lastRealMessageAt?: number;
+}
+/**
+ * Read-only view of brains seen so far (via registerBrain). Used by the inbox
+ * watcher (teamvibe.ai#242) to know which brain paths to scan and which
+ * workspace/bot credentials to use when starting a session for an idle thread.
+ */
+export declare function getTrackedBrains(): ReadonlyMap<string, TrackedBrainInfo>;
+/**
+ * Test-only helper to clear tracked brains between tests (module-scoped
+ * state persists across tests in the same file otherwise).
+ * @internal
+ */
+export declare function __resetTrackedBrainsForTest(): void;
 /**
  * Register a brain from a real message so the maintenance cron knows about it.
  * Called from processMessage() after brain path is resolved.

package/dist/maintenance-cron.js

@@ -6,9 +6,26 @@ 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 { markMaintenanceJobFired, markMaintenanceJobSuccess, } from './cron-telemetry.js';
+import { markMaintenanceJobFired, markMaintenanceJobSuccess, markMaintenanceJobSkipped, } from './cron-telemetry.js';
+import { shouldSkipMaintenance } from './maintenance-activity.js';
 import { join } from 'path';
 const trackedBrains = new Map();
+/**
+ * Read-only view of brains seen so far (via registerBrain). Used by the inbox
+ * watcher (teamvibe.ai#242) to know which brain paths to scan and which
+ * workspace/bot credentials to use when starting a session for an idle thread.
+ */
+export function getTrackedBrains() {
+    return trackedBrains;
+}
+/**
+ * Test-only helper to clear tracked brains between tests (module-scoped
+ * state persists across tests in the same file otherwise).
+ * @internal
+ */
+export function __resetTrackedBrainsForTest() {
+    trackedBrains.clear();
+}
 let maintenanceJob = null;
 /**
  * Register a brain from a real message so the maintenance cron knows about it.
@@ -30,6 +47,7 @@ export function registerBrain(msg) {
         botId: msg.teamvibe.botId,
         botToken: msg.teamvibe.botToken,
         channelId: msg.teamvibe.channelId,
+        lastRealMessageAt: Date.now(),
     });
     logger.debug(`[Maintenance] Registered brain: ${brain.brainId}`);
     // Metrics pipeline (teamvibe.ai#110): register for hourly collection. On the
@@ -60,6 +78,11 @@ async function triggerAllBrains(processMessageFn) {
             logger.debug(`[Maintenance] At capacity, skipping ${brainId}`);
             continue;
         }
+        if (await shouldSkipMaintenance(config.BRAINS_PATH, brainId, info.lastRealMessageAt)) {
+            markMaintenanceJobSkipped();
+            logger.debug(`[Maintenance] Skipping ${brainId} — no real activity since last maintenance (#131)`);
+            continue;
+        }
         logger.info(`[Maintenance] Triggering maintenance for brain ${brainId}`);
         const syntheticMessage = {
             id: `maintenance_${brainId}_${now}`,