@teamvibe/poller 0.1.45 → 0.1.46

package/dist/claude-spawner.js

@@ -82,6 +82,10 @@ async function countNewThreadMessages(botToken, channel, threadTs, sinceTs) {
     }
 }
 function buildPrompt(msg, resumeHint) {
+    // Heartbeat messages get a minimal prompt — CLAUDE.md/MAINTENANCE.md handle the rest
+    if (msg.source === 'heartbeat') {
+        return 'heartbeat';
+    }
     let prompt = '## Incoming Slack Message\n\n';
     prompt += `**From:** ${msg.sender.name}`;
     if (msg.sender.id && msg.sender.id !== msg.sender.name) {
@@ -173,7 +177,8 @@ function formatStreamEvent(event) {
 async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = true, lastMessageTs, onMessageSent, typingIndicator) {
     const slackContext = msg.response_context.slack;
     const isCronMessage = msg.source === 'cron';
-    if (!slackContext && !isCronMessage) {
+    const isHeartbeat = msg.source === 'heartbeat';
+    if (!slackContext && !isCronMessage && !isHeartbeat) {
         throw new Error('No Slack context in message');
     }
     // Build resume hint

package/dist/config.d.ts

@@ -22,6 +22,9 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: z.ZodDefault<z.ZodString>;
     BRAIN_AUTO_UPDATE: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     BRAIN_UPDATE_COOLDOWN_MS: z.ZodDefault<z.ZodNumber>;
+    MAINTENANCE_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
+    MAINTENANCE_CHECK_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
+    MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
 }, "strip", z.ZodTypeAny, {
     AWS_REGION: string;
     TEAMVIBE_API_URL: string;
@@ -41,6 +44,9 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    MAINTENANCE_INTERVAL_MS: number;
+    MAINTENANCE_CHECK_INTERVAL_MS: number;
+    MAINTENANCE_ENABLED: boolean;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;
@@ -66,6 +72,9 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH?: string | undefined;
     BRAIN_AUTO_UPDATE?: string | undefined;
     BRAIN_UPDATE_COOLDOWN_MS?: number | undefined;
+    MAINTENANCE_INTERVAL_MS?: number | undefined;
+    MAINTENANCE_CHECK_INTERVAL_MS?: number | undefined;
+    MAINTENANCE_ENABLED?: string | undefined;
 }>;
 export type Config = z.infer<typeof configSchema>;
 export declare function loadConfig(): Config;
@@ -88,6 +97,9 @@ export declare const config: {
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    MAINTENANCE_INTERVAL_MS: number;
+    MAINTENANCE_CHECK_INTERVAL_MS: number;
+    MAINTENANCE_ENABLED: boolean;
     SQS_QUEUE_URL?: string | undefined;
     SESSIONS_TABLE?: string | undefined;
     TEAMVIBE_POLLER_TOKEN?: string | undefined;

package/dist/config.js

@@ -37,6 +37,10 @@ const configSchema = z.object({
         .default('true')
         .transform((v) => v.toLowerCase() === 'true'),
     BRAIN_UPDATE_COOLDOWN_MS: z.coerce.number().default(300000), // 5 minutes
+    // Maintenance heartbeat
+    MAINTENANCE_INTERVAL_MS: z.coerce.number().default(21600000), // 6 hours between maintenance per brain
+    MAINTENANCE_CHECK_INTERVAL_MS: z.coerce.number().default(300000), // 5 min check loop
+    MAINTENANCE_ENABLED: z.string().default('true').transform((v) => v.toLowerCase() === 'true'),
 });
 export function loadConfig() {
     const result = configSchema.safeParse(process.env);

package/dist/heartbeat-manager.d.ts

@@ -0,0 +1,19 @@
+import type { TeamVibeQueueMessage } from './types.js';
+/**
+ * Register a brain from a real message so we know about it for heartbeats.
+ * Called from processMessage() after brain path is resolved.
+ */
+export declare function registerBrain(msg: TeamVibeQueueMessage): void;
+/**
+ * Start the periodic heartbeat check loop.
+ * Checks every MAINTENANCE_CHECK_INTERVAL_MS whether any brain needs maintenance.
+ */
+export declare function startHeartbeatLoop(processMessageFn: (msg: {
+    queueMessage: TeamVibeQueueMessage;
+    receiptHandle: string;
+    messageId: string;
+}) => Promise<void>): void;
+/**
+ * Stop the heartbeat loop (for shutdown).
+ */
+export declare function stopHeartbeatLoop(): void;

package/dist/heartbeat-manager.js

@@ -0,0 +1,101 @@
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { isAtCapacity } from './claude-spawner.js';
+const trackedBrains = new Map();
+let heartbeatInterval = null;
+/**
+ * Register a brain from a real message so we know about it for heartbeats.
+ * Called from processMessage() after brain path is resolved.
+ */
+export function registerBrain(msg) {
+    const brain = msg.teamvibe.brain;
+    if (!brain?.brainId)
+        return;
+    // Don't register from heartbeat messages (avoid self-referential loop)
+    if (msg.source === 'heartbeat')
+        return;
+    const existing = trackedBrains.get(brain.brainId);
+    // Update brain info but preserve lastHeartbeat if it exists
+    trackedBrains.set(brain.brainId, {
+        brainId: brain.brainId,
+        gitRepoUrl: brain.gitRepoUrl,
+        branch: brain.branch,
+        workspaceId: msg.teamvibe.workspaceId,
+        botId: msg.teamvibe.botId,
+        botToken: msg.teamvibe.botToken,
+        channelId: msg.teamvibe.channelId,
+        lastHeartbeat: existing?.lastHeartbeat ?? 0,
+    });
+    logger.debug(`[Heartbeat] Registered brain: ${brain.brainId}`);
+}
+/**
+ * Start the periodic heartbeat check loop.
+ * Checks every MAINTENANCE_CHECK_INTERVAL_MS whether any brain needs maintenance.
+ */
+export function startHeartbeatLoop(processMessageFn) {
+    if (!config.MAINTENANCE_ENABLED) {
+        logger.info('[Heartbeat] Maintenance disabled via config');
+        return;
+    }
+    logger.info(`[Heartbeat] Starting heartbeat loop (check every ${config.MAINTENANCE_CHECK_INTERVAL_MS}ms, interval ${config.MAINTENANCE_INTERVAL_MS}ms)`);
+    heartbeatInterval = setInterval(async () => {
+        const now = Date.now();
+        for (const [brainId, info] of trackedBrains.entries()) {
+            const elapsed = now - info.lastHeartbeat;
+            if (elapsed < config.MAINTENANCE_INTERVAL_MS) {
+                continue;
+            }
+            if (isAtCapacity()) {
+                logger.debug(`[Heartbeat] At capacity, skipping heartbeat for ${brainId}`);
+                continue;
+            }
+            logger.info(`[Heartbeat] Triggering maintenance for brain ${brainId} (last: ${info.lastHeartbeat === 0 ? 'never' : `${Math.round(elapsed / 60000)}m ago`})`);
+            // Update lastHeartbeat immediately to prevent double-triggering
+            info.lastHeartbeat = now;
+            const syntheticMessage = {
+                id: `heartbeat_${brainId}_${now}`,
+                source: 'heartbeat',
+                thread_id: `heartbeat_${brainId}_${now}`,
+                sender: {
+                    id: 'system',
+                    name: 'System',
+                },
+                text: 'heartbeat',
+                attachments: [],
+                response_context: {},
+                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,
+                    },
+                },
+            };
+            try {
+                await processMessageFn({
+                    queueMessage: syntheticMessage,
+                    receiptHandle: '', // No SQS receipt for synthetic messages
+                    messageId: syntheticMessage.id,
+                });
+            }
+            catch (error) {
+                logger.error(`[Heartbeat] Failed maintenance for ${brainId}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    }, config.MAINTENANCE_CHECK_INTERVAL_MS);
+}
+/**
+ * Stop the heartbeat loop (for shutdown).
+ */
+export function stopHeartbeatLoop() {
+    if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+        logger.info('[Heartbeat] Stopped heartbeat loop');
+    }
+}

package/dist/poller.js

@@ -6,6 +6,7 @@ import { sendSlackError, addReaction, getUserInfo, startTypingIndicator } from '
 import { acquireSessionLock, releaseSessionLock, updateSessionId } from './session-store.js';
 import { getBrainPath, ensureDirectories, ensureBaseBrain, pushBrainChanges } from './brain-manager.js';
 import { initAuth, stopRefresh } from './auth-provider.js';
+import { registerBrain, startHeartbeatLoop, stopHeartbeatLoop } from './heartbeat-manager.js';
 // Track active message processing
 const processingMessages = new Set();
 // Per-thread completion signals
@@ -65,7 +66,7 @@ async function processMessage(received) {
     const threadId = queueMessage.thread_id;
     const sessionLog = logger.createSession(logSessionId);
     // Fetch user info if we only have ID
-    if (queueMessage.source !== 'cron' &&
+    if (queueMessage.source !== 'cron' && queueMessage.source !== 'heartbeat' &&
         queueMessage.sender.name === 'Unknown User' &&
         queueMessage.sender.id !== 'unknown') {
         const userInfo = await getUserInfo(queueMessage.teamvibe.botToken, queueMessage.sender.id);
@@ -96,9 +97,13 @@ async function processMessage(received) {
                 sessionLog.error(`Failed to send Slack error: ${slackError}`);
             }
         }
-        await deleteMessage(receiptHandle);
+        if (receiptHandle) {
+            await deleteMessage(receiptHandle);
+        }
         return;
     }
+    // Register brain for heartbeat tracking
+    registerBrain(queueMessage);
     // Try to acquire session lock
     let lockResult = await acquireSessionLock(threadId, kbPath);
     if (!lockResult.success) {
@@ -160,7 +165,9 @@ async function processMessage(received) {
                 await releaseSessionLock(threadId, lockToken, 'idle');
             }
         }
-        await deleteMessage(receiptHandle);
+        if (receiptHandle) {
+            await deleteMessage(receiptHandle);
+        }
         sessionLog.info('Message processed and deleted');
     }
     catch (error) {
@@ -238,6 +245,7 @@ async function shutdown(signal) {
     shuttingDown = true;
     logger.info(`${signal} received, shutting down gracefully...`);
     stopRefresh();
+    stopHeartbeatLoop();
     // Unblock all messages waiting on thread completion so they can exit
     for (const [threadId, signals] of threadCompletionSignals.entries()) {
         logger.info(`Unblocking ${signals.length} waiting message(s) on thread ${threadId}`);
@@ -277,5 +285,6 @@ export async function startPoller() {
     }
     await ensureDirectories();
     await ensureBaseBrain();
+    startHeartbeatLoop(processMessage);
     await pollLoop();
 }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export interface TeamVibeQueueMessage {
     id: string;
-    source: 'slack' | 'cron';
+    source: 'slack' | 'cron' | 'heartbeat';
     thread_id: string;
     sender: {
         id: string;

package/package.json

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