@phuetz/code-buddy 0.1.12 → 0.1.14

package/dist/daemon/health-monitor.js.map

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

package/dist/daemon/heartbeat.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Heartbeat Engine
+ *
+ * OpenClaw-inspired periodic wake system that reads a HEARTBEAT.md checklist
+ * and surfaces important items via agent review. Integrates with the existing
+ * CronAgentBridge pattern to create agent instances for checklist evaluation.
+ *
+ * Features:
+ * - Configurable interval (default 30 minutes)
+ * - Active hours filtering (only fires during configured hours)
+ * - Smart suppression (HEARTBEAT_OK skips with counter)
+ * - Event-driven (heartbeat:wake, heartbeat:result, heartbeat:suppressed)
+ */
+import { EventEmitter } from 'events';
+export interface HeartbeatConfig {
+    /** Interval between heartbeat checks (ms). Default: 30 minutes */
+    intervalMs: number;
+    /** Start of active hours (0-23). Default: 8 */
+    activeHoursStart: number;
+    /** End of active hours (0-23). Default: 22 */
+    activeHoursEnd: number;
+    /** IANA timezone string. Default: system timezone */
+    timezone: string;
+    /** Path to HEARTBEAT.md checklist. Default: .codebuddy/HEARTBEAT.md */
+    heartbeatFilePath: string;
+    /** Keyword in agent response that suppresses action. Default: HEARTBEAT_OK */
+    suppressionKeyword: string;
+    /** Max consecutive suppressions before forcing a full review. Default: 5 */
+    maxConsecutiveSuppressions: number;
+    /** Whether the heartbeat engine is enabled. Default: true */
+    enabled: boolean;
+    /** Optional override for agent review (used in tests). */
+    agentReviewFn?: (checklistContent: string) => Promise<string>;
+}
+export interface HeartbeatStatus {
+    running: boolean;
+    enabled: boolean;
+    lastRunTime: Date | null;
+    nextRunTime: Date | null;
+    consecutiveSuppressions: number;
+    totalTicks: number;
+    totalSuppressions: number;
+    lastResult: string | null;
+}
+export interface HeartbeatTickResult {
+    timestamp: Date;
+    skipped: boolean;
+    skipReason?: 'outside_active_hours' | 'disabled' | 'file_not_found';
+    suppressed: boolean;
+    agentResponse?: string;
+    checklistContent?: string;
+    duration: number;
+}
+export declare class HeartbeatEngine extends EventEmitter {
+    private config;
+    private timer;
+    private running;
+    private lastRunTime;
+    private nextRunTime;
+    private consecutiveSuppressions;
+    private totalTicks;
+    private totalSuppressions;
+    private lastResult;
+    constructor(config?: Partial<HeartbeatConfig>);
+    /**
+     * Start the heartbeat engine
+     */
+    start(): void;
+    /**
+     * Stop the heartbeat engine
+     */
+    stop(): void;
+    /**
+     * Schedule the next tick
+     */
+    private scheduleNext;
+    /**
+     * Execute a single heartbeat tick
+     *
+     * Reads HEARTBEAT.md, creates an agent to review the checklist,
+     * and emits appropriate events based on the result.
+     */
+    tick(): Promise<HeartbeatTickResult>;
+    /**
+     * Check if the current time is within configured active hours
+     */
+    isWithinActiveHours(now?: Date): boolean;
+    /**
+     * Execute agent review of the heartbeat checklist
+     *
+     * Uses the same lazy-load agent pattern as CronAgentBridge.
+     */
+    private executeAgentReview;
+    /**
+     * Get current heartbeat engine status
+     */
+    getStatus(): HeartbeatStatus;
+    /**
+     * Get the current configuration (copy)
+     */
+    getConfig(): HeartbeatConfig;
+    /**
+     * Update configuration (requires restart to take effect for interval changes)
+     */
+    updateConfig(updates: Partial<HeartbeatConfig>): void;
+    /**
+     * Check if the engine is currently running
+     */
+    isRunning(): boolean;
+}
+export declare function getHeartbeatEngine(config?: Partial<HeartbeatConfig>): HeartbeatEngine;
+export declare function resetHeartbeatEngine(): void;

package/dist/daemon/heartbeat.js

@@ -0,0 +1,339 @@
+/**
+ * Heartbeat Engine
+ *
+ * OpenClaw-inspired periodic wake system that reads a HEARTBEAT.md checklist
+ * and surfaces important items via agent review. Integrates with the existing
+ * CronAgentBridge pattern to create agent instances for checklist evaluation.
+ *
+ * Features:
+ * - Configurable interval (default 30 minutes)
+ * - Active hours filtering (only fires during configured hours)
+ * - Smart suppression (HEARTBEAT_OK skips with counter)
+ * - Event-driven (heartbeat:wake, heartbeat:result, heartbeat:suppressed)
+ */
+import { EventEmitter } from 'events';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { logger } from '../utils/logger.js';
+const DEFAULT_HEARTBEAT_CONFIG = {
+    intervalMs: 30 * 60 * 1000, // 30 minutes
+    activeHoursStart: 8,
+    activeHoursEnd: 22,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    heartbeatFilePath: path.join(process.cwd(), '.codebuddy', 'HEARTBEAT.md'),
+    suppressionKeyword: 'HEARTBEAT_OK',
+    maxConsecutiveSuppressions: 5,
+    enabled: true,
+};
+// ============================================================================
+// Heartbeat Engine
+// ============================================================================
+export class HeartbeatEngine extends EventEmitter {
+    config;
+    timer = null;
+    running = false;
+    lastRunTime = null;
+    nextRunTime = null;
+    consecutiveSuppressions = 0;
+    totalTicks = 0;
+    totalSuppressions = 0;
+    lastResult = null;
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_HEARTBEAT_CONFIG, ...config };
+    }
+    /**
+     * Start the heartbeat engine
+     */
+    start() {
+        if (this.running) {
+            logger.warn('Heartbeat engine already running');
+            return;
+        }
+        if (!this.config.enabled) {
+            logger.info('Heartbeat engine is disabled');
+            return;
+        }
+        this.running = true;
+        this.scheduleNext();
+        logger.info('Heartbeat engine started', {
+            intervalMs: this.config.intervalMs,
+            activeHours: `${this.config.activeHoursStart}-${this.config.activeHoursEnd}`,
+            timezone: this.config.timezone,
+        });
+        this.emit('started');
+    }
+    /**
+     * Stop the heartbeat engine
+     */
+    stop() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.running = false;
+        this.nextRunTime = null;
+        logger.info('Heartbeat engine stopped');
+        this.emit('stopped');
+    }
+    /**
+     * Schedule the next tick
+     */
+    scheduleNext() {
+        if (!this.running)
+            return;
+        // Clear any existing timer to prevent orphaned timers
+        if (this.timer) {
+            clearTimeout(this.timer);
+        }
+        this.nextRunTime = new Date(Date.now() + this.config.intervalMs);
+        this.timer = setTimeout(async () => {
+            try {
+                await this.tick();
+            }
+            catch (error) {
+                logger.error('Heartbeat tick error', { error: String(error) });
+                this.emit('heartbeat:error', { error });
+            }
+            // Schedule next tick after completion
+            this.scheduleNext();
+        }, this.config.intervalMs);
+    }
+    /**
+     * Execute a single heartbeat tick
+     *
+     * Reads HEARTBEAT.md, creates an agent to review the checklist,
+     * and emits appropriate events based on the result.
+     */
+    async tick() {
+        const startTime = Date.now();
+        this.totalTicks++;
+        // Check if enabled
+        if (!this.config.enabled) {
+            const result = {
+                timestamp: new Date(),
+                skipped: true,
+                skipReason: 'disabled',
+                suppressed: false,
+                duration: Date.now() - startTime,
+            };
+            logger.debug('Heartbeat tick skipped: disabled');
+            return result;
+        }
+        // Check active hours
+        if (!this.isWithinActiveHours()) {
+            const result = {
+                timestamp: new Date(),
+                skipped: true,
+                skipReason: 'outside_active_hours',
+                suppressed: false,
+                duration: Date.now() - startTime,
+            };
+            logger.debug('Heartbeat tick skipped: outside active hours');
+            this.emit('heartbeat:skipped', result);
+            return result;
+        }
+        // Read the heartbeat checklist
+        let checklistContent;
+        try {
+            checklistContent = await fs.readFile(this.config.heartbeatFilePath, 'utf-8');
+        }
+        catch {
+            const result = {
+                timestamp: new Date(),
+                skipped: true,
+                skipReason: 'file_not_found',
+                suppressed: false,
+                duration: Date.now() - startTime,
+            };
+            logger.warn('Heartbeat file not found', { path: this.config.heartbeatFilePath });
+            this.emit('heartbeat:skipped', result);
+            return result;
+        }
+        this.lastRunTime = new Date();
+        this.emit('heartbeat:wake', { timestamp: this.lastRunTime, checklistContent });
+        // Create agent instance to review checklist (same pattern as CronAgentBridge)
+        let agentResponse;
+        try {
+            agentResponse = await this.executeAgentReview(checklistContent);
+        }
+        catch (error) {
+            logger.error('Heartbeat agent review failed', { error: String(error) });
+            const result = {
+                timestamp: new Date(),
+                skipped: false,
+                suppressed: false,
+                checklistContent,
+                agentResponse: `Error: ${String(error)}`,
+                duration: Date.now() - startTime,
+            };
+            this.emit('heartbeat:error', { error });
+            return result;
+        }
+        this.lastResult = agentResponse;
+        // Check for suppression keyword
+        const isSuppressed = agentResponse.includes(this.config.suppressionKeyword);
+        if (isSuppressed) {
+            this.consecutiveSuppressions++;
+            this.totalSuppressions++;
+            // If max consecutive suppressions reached, force a full review next time
+            if (this.consecutiveSuppressions >= this.config.maxConsecutiveSuppressions) {
+                logger.info('Max consecutive suppressions reached, resetting counter', {
+                    count: this.consecutiveSuppressions,
+                });
+                this.consecutiveSuppressions = 0;
+                this.emit('heartbeat:suppression-limit', {
+                    totalSuppressions: this.totalSuppressions,
+                });
+            }
+            const result = {
+                timestamp: new Date(),
+                skipped: false,
+                suppressed: true,
+                agentResponse,
+                checklistContent,
+                duration: Date.now() - startTime,
+            };
+            logger.debug('Heartbeat suppressed by agent', {
+                consecutiveSuppressions: this.consecutiveSuppressions,
+            });
+            this.emit('heartbeat:suppressed', {
+                consecutiveSuppressions: this.consecutiveSuppressions,
+                agentResponse,
+            });
+            return result;
+        }
+        // Agent found something noteworthy - reset suppression counter
+        this.consecutiveSuppressions = 0;
+        const result = {
+            timestamp: new Date(),
+            skipped: false,
+            suppressed: false,
+            agentResponse,
+            checklistContent,
+            duration: Date.now() - startTime,
+        };
+        this.emit('heartbeat:result', {
+            agentResponse,
+            checklistContent,
+            duration: result.duration,
+        });
+        return result;
+    }
+    /**
+     * Check if the current time is within configured active hours
+     */
+    isWithinActiveHours(now) {
+        const date = now || new Date();
+        // Get the hour in the configured timezone
+        let hour;
+        try {
+            const formatter = new Intl.DateTimeFormat('en-US', {
+                hour: 'numeric',
+                hourCycle: 'h23',
+                timeZone: this.config.timezone,
+            });
+            hour = parseInt(formatter.format(date), 10);
+        }
+        catch {
+            // Fallback to local time if timezone is invalid
+            hour = date.getHours();
+        }
+        const { activeHoursStart, activeHoursEnd } = this.config;
+        // Handle wrap-around (e.g., activeHoursStart=22, activeHoursEnd=6)
+        if (activeHoursStart <= activeHoursEnd) {
+            return hour >= activeHoursStart && hour < activeHoursEnd;
+        }
+        else {
+            return hour >= activeHoursStart || hour < activeHoursEnd;
+        }
+    }
+    /**
+     * Execute agent review of the heartbeat checklist
+     *
+     * Uses the same lazy-load agent pattern as CronAgentBridge.
+     */
+    async executeAgentReview(checklistContent) {
+        // Allow override for testing
+        if (this.config.agentReviewFn) {
+            return this.config.agentReviewFn(checklistContent);
+        }
+        const apiKey = process.env.GROK_API_KEY || '';
+        const baseURL = process.env.GROK_BASE_URL;
+        const model = process.env.GROK_MODEL;
+        const forceReview = this.consecutiveSuppressions >= this.config.maxConsecutiveSuppressions - 1;
+        const suppressionContext = forceReview
+            ? `\n\nIMPORTANT: There have been ${this.consecutiveSuppressions} consecutive suppressions. Please do a thorough review even if everything looks fine.`
+            : '';
+        const prompt = [
+            'You are a heartbeat monitor reviewing a project checklist.',
+            'Review the following HEARTBEAT.md checklist and determine if any items need attention.',
+            '',
+            `If everything looks fine, respond with exactly: ${this.config.suppressionKeyword}`,
+            'If any items need attention, describe what needs to be done.',
+            suppressionContext,
+            '',
+            '---',
+            checklistContent,
+        ].join('\n');
+        // Lazy load agent to avoid circular deps
+        const { CodeBuddyAgent } = await import('../agent/codebuddy-agent.js');
+        const agent = new CodeBuddyAgent(apiKey, baseURL, model, 10, // limited tool rounds for heartbeat review
+        false // no RAG for heartbeat
+        );
+        const entries = await agent.processUserMessage(prompt);
+        const assistantEntries = entries.filter(e => e.type === 'assistant');
+        return assistantEntries.map(e => e.content).join('\n') || 'No response';
+    }
+    /**
+     * Get current heartbeat engine status
+     */
+    getStatus() {
+        return {
+            running: this.running,
+            enabled: this.config.enabled,
+            lastRunTime: this.lastRunTime,
+            nextRunTime: this.nextRunTime,
+            consecutiveSuppressions: this.consecutiveSuppressions,
+            totalTicks: this.totalTicks,
+            totalSuppressions: this.totalSuppressions,
+            lastResult: this.lastResult,
+        };
+    }
+    /**
+     * Get the current configuration (copy)
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration (requires restart to take effect for interval changes)
+     */
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        logger.info('Heartbeat config updated', { updates: Object.keys(updates) });
+    }
+    /**
+     * Check if the engine is currently running
+     */
+    isRunning() {
+        return this.running;
+    }
+}
+// ============================================================================
+// Singleton
+// ============================================================================
+let heartbeatInstance = null;
+export function getHeartbeatEngine(config) {
+    if (!heartbeatInstance) {
+        heartbeatInstance = new HeartbeatEngine(config);
+    }
+    return heartbeatInstance;
+}
+export function resetHeartbeatEngine() {
+    if (heartbeatInstance) {
+        heartbeatInstance.stop();
+    }
+    heartbeatInstance = null;
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/daemon/heartbeat.js.map

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

package/dist/desktop-automation/smart-snapshot.d.ts

@@ -129,6 +129,17 @@ export declare class SmartSnapshotManager extends EventEmitter {
      * Take a snapshot of the current screen/window
      */
     takeSnapshot(options?: SnapshotOptions): Promise<Snapshot>;
+    /**
+     * Get the next available ref number.
+     * Allows external modules (e.g. browser-automation) to share the global ref space
+     * so desktop and browser refs never collide.
+     */
+    getNextRef(): number;
+    /**
+     * Inject browser-sourced elements into the current snapshot.
+     * This allows unified ref lookup across desktop and browser elements.
+     */
+    injectBrowserElements(elements: UIElement[], source?: string): void;
     /**
      * Get element by reference number
      */

package/dist/desktop-automation/smart-snapshot.js

@@ -114,6 +114,34 @@ export class SmartSnapshotManager extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get the next available ref number.
+     * Allows external modules (e.g. browser-automation) to share the global ref space
+     * so desktop and browser refs never collide.
+     */
+    getNextRef() {
+        return this.nextRef++;
+    }
+    /**
+     * Inject browser-sourced elements into the current snapshot.
+     * This allows unified ref lookup across desktop and browser elements.
+     */
+    injectBrowserElements(elements, source = 'browser-accessibility') {
+        if (!this.currentSnapshot?.valid) {
+            logger.warn('Cannot inject browser elements: no valid snapshot');
+            return;
+        }
+        for (const elem of elements) {
+            // Tag element with browser source
+            elem.attributes = { ...elem.attributes, source };
+            this.currentSnapshot.elements.push(elem);
+            this.currentSnapshot.elementMap.set(elem.ref, elem);
+        }
+        logger.debug('Injected browser elements into desktop snapshot', {
+            count: elements.length,
+            source,
+        });
+    }
     /**
      * Get element by reference number
      */
@@ -351,6 +379,11 @@ export class SmartSnapshotManager extends EventEmitter {
                 unlinkSync(outputPath);
             }
             catch (_e) { /* ignore */ }
+            try {
+                const { rmdirSync } = await import('fs');
+                rmdirSync(tmpDir);
+            }
+            catch (_e) { /* ignore */ }
             return {
                 image: buf.toString('base64'),
                 format: 'png',
@@ -360,6 +393,11 @@ export class SmartSnapshotManager extends EventEmitter {
             };
         }
         catch (_err) {
+            try {
+                const { rmSync } = await import('fs');
+                rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch (_e) { /* ignore */ }
             return null;
         }
     }