@esotech/contextuate 2.0.0 → 2.1.0

package/dist/monitor/daemon/notifier.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Notifier
+ *
+ * Sends notifications to the UI server via Unix socket and/or Redis.
+ * Uses fire-and-forget pattern for resilience.
+ */
+import { MonitorEvent, MonitorConfig, SessionMeta } from '../../types/monitor.js';
+export type BroadcastCallback = (data: any) => void;
+export declare class Notifier {
+    private config;
+    private broadcast;
+    constructor(config: MonitorConfig, broadcast: BroadcastCallback);
+    /**
+     * Notify UI server about a new event
+     */
+    notify(event: MonitorEvent): Promise<void>;
+    /**
+     * Notify UI server about a session update
+     */
+    notifySessionUpdate(session: SessionMeta): Promise<void>;
+    /**
+     * Send notification via Redis pub/sub
+     */
+    private notifyRedis;
+}

package/dist/monitor/daemon/notifier.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Notifier
+ *
+ * Sends notifications to the UI server via Unix socket and/or Redis.
+ * Uses fire-and-forget pattern for resilience.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Notifier = void 0;
+class Notifier {
+    constructor(config, broadcast) {
+        this.config = config;
+        this.broadcast = broadcast;
+    }
+    /**
+     * Notify UI server about a new event
+     */
+    async notify(event) {
+        // Broadcast to local UI clients via callback
+        this.broadcast({ type: 'event', event });
+        // If Redis mode, also publish for UI aggregation across machines
+        if (this.config.mode === 'redis' && this.config.redis) {
+            await this.notifyRedis({ type: 'event', event });
+        }
+    }
+    /**
+     * Notify UI server about a session update
+     */
+    async notifySessionUpdate(session) {
+        const notification = {
+            type: 'session_update',
+            session,
+            timestamp: Date.now(),
+        };
+        // Broadcast to local UI clients via callback
+        this.broadcast(notification);
+        // If Redis mode, also publish for UI aggregation
+        if (this.config.mode === 'redis' && this.config.redis) {
+            await this.notifyRedis(notification);
+        }
+    }
+    /**
+     * Send notification via Redis pub/sub
+     */
+    async notifyRedis(data) {
+        // Redis notification for multi-machine UI aggregation
+        try {
+            const Redis = (await Promise.resolve().then(() => __importStar(require('ioredis')))).default;
+            const client = new Redis({
+                host: this.config.redis?.host || 'localhost',
+                port: this.config.redis?.port || 6379,
+                password: this.config.redis?.password || undefined,
+                lazyConnect: true,
+                maxRetriesPerRequest: 0,
+            });
+            await client.connect();
+            await client.publish(this.config.redis?.channel || 'contextuate:ui', JSON.stringify(data));
+            await client.quit();
+        }
+        catch (err) {
+            // Fire-and-forget, don't fail
+        }
+    }
+}
+exports.Notifier = Notifier;

package/dist/monitor/daemon/processor.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Event Processor
+ *
+ * Core event processing logic extracted from broker.ts.
+ * Handles:
+ * - Session correlation (parent-child linking)
+ * - Subagent lifecycle tracking
+ * - Virtual session routing
+ * - Event persistence
+ */
+import { MonitorEvent } from '../../types/monitor.js';
+import { StateManager } from './state.js';
+import { Notifier } from './notifier.js';
+import type { CircuitBreaker } from './circuit-breaker.js';
+export declare class EventProcessor {
+    private state;
+    private notifier;
+    private sessions;
+    private circuitBreaker;
+    constructor(state: StateManager, notifier: Notifier);
+    /**
+     * Set the circuit breaker instance for health monitoring
+     */
+    setCircuitBreaker(circuitBreaker: CircuitBreaker): void;
+    /**
+     * Load existing sessions from disk
+     */
+    loadSessions(): Promise<void>;
+    private processedEventIds;
+    /**
+     * Process a single event
+     * @param event The event to process
+     * @param filepath The source file path (null if from socket)
+     */
+    processEvent(event: MonitorEvent, filepath: string | null): Promise<void>;
+    /**
+     * Find wrapper ID associated with a session (for circuit breaker)
+     * This is a placeholder - the daemon will provide better association
+     */
+    private findWrapperForSession;
+    /**
+     * Handle SubagentStart event - create child session immediately
+     */
+    private handleSubagentStart;
+    /**
+     * Generate a short unique ID for virtual sessions
+     */
+    private generateVirtualSessionId;
+    /**
+     * Start tracking a subagent context when Task tool is called
+     */
+    private startSubagentContext;
+    /**
+     * End the current subagent context
+     */
+    private endSubagentContext;
+    /**
+     * Extract agent type from Task tool input
+     */
+    private extractAgentType;
+    /**
+     * Track potential sub-agent spawns from Task tool calls
+     */
+    private trackSubagentSpawn;
+    /**
+     * Update session state based on event
+     */
+    private updateSession;
+    /**
+     * Try to correlate a new session with a pending sub-agent spawn
+     */
+    private correlateParent;
+    /**
+     * Check if two working directories match (handles git worktrees)
+     */
+    private directoriesMatch;
+    /**
+     * Persist session metadata to disk
+     */
+    private persistSession;
+    /**
+     * Persist event to session's events.jsonl file
+     */
+    private persistEvent;
+    /**
+     * Move processed file from raw/ to processed/
+     */
+    private moveToProcessed;
+}

package/dist/monitor/daemon/processor.js

@@ -0,0 +1,455 @@
+"use strict";
+/**
+ * Event Processor
+ *
+ * Core event processing logic extracted from broker.ts.
+ * Handles:
+ * - Session correlation (parent-child linking)
+ * - Subagent lifecycle tracking
+ * - Virtual session routing
+ * - Event persistence
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventProcessor = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const monitor_js_1 = require("../../types/monitor.js");
+const PATHS = (0, monitor_js_1.getDefaultMonitorPaths)();
+const SUBAGENT_CORRELATION_WINDOW_MS = 30000;
+class EventProcessor {
+    constructor(state, notifier) {
+        this.sessions = new Map();
+        this.circuitBreaker = null;
+        // Track processed event IDs to prevent duplicates (socket + file watcher)
+        this.processedEventIds = new Set();
+        this.state = state;
+        this.notifier = notifier;
+    }
+    /**
+     * Set the circuit breaker instance for health monitoring
+     */
+    setCircuitBreaker(circuitBreaker) {
+        this.circuitBreaker = circuitBreaker;
+    }
+    /**
+     * Load existing sessions from disk
+     */
+    async loadSessions() {
+        try {
+            const sessionDirs = await fs.promises.readdir(PATHS.sessionsDir);
+            for (const dir of sessionDirs) {
+                const metaPath = path.join(PATHS.sessionsDir, dir, 'meta.json');
+                try {
+                    const data = await fs.promises.readFile(metaPath, 'utf8');
+                    const session = JSON.parse(data);
+                    this.sessions.set(session.sessionId, session);
+                }
+                catch (err) {
+                    // Skip invalid session directories
+                }
+            }
+            console.log(`[Processor] Loaded ${this.sessions.size} sessions`);
+        }
+        catch (err) {
+            // No sessions directory yet
+        }
+    }
+    /**
+     * Process a single event
+     * @param event The event to process
+     * @param filepath The source file path (null if from socket)
+     */
+    async processEvent(event, filepath) {
+        // Deduplicate events (can arrive via socket AND file watcher)
+        if (this.processedEventIds.has(event.id)) {
+            // Already processed via socket, just move the file
+            if (filepath) {
+                await this.moveToProcessed(filepath);
+            }
+            return;
+        }
+        this.processedEventIds.add(event.id);
+        // Limit memory usage by keeping only recent event IDs
+        if (this.processedEventIds.size > 10000) {
+            const arr = Array.from(this.processedEventIds);
+            this.processedEventIds = new Set(arr.slice(-5000));
+        }
+        const originalSessionId = event.sessionId;
+        // Handle subagent lifecycle
+        if (event.hookType === 'PreToolUse' && event.data?.toolName === 'Task') {
+            await this.startSubagentContext(event);
+        }
+        else if (event.eventType === 'subagent_start') {
+            // Handle SubagentStart event for proper hierarchy
+            await this.handleSubagentStart(event);
+        }
+        else if (event.hookType === 'SubagentStop' || event.eventType === 'subagent_stop') {
+            await this.endSubagentContext(event);
+        }
+        else {
+            // Route to active subagent if exists
+            const activeStack = this.state.getActiveSubagentStack(originalSessionId);
+            if (activeStack.length > 0) {
+                const active = activeStack[activeStack.length - 1];
+                event = { ...event, sessionId: active.virtualSessionId, parentSessionId: originalSessionId };
+            }
+        }
+        // Track pending subagent spawns
+        this.trackSubagentSpawn(event);
+        // Update session
+        await this.updateSession(event);
+        // Persist event
+        await this.persistEvent(event);
+        // Update state checkpoint
+        this.state.lastProcessedTimestamp = event.timestamp;
+        // Move raw file to processed (only if from file watcher)
+        if (filepath) {
+            await this.moveToProcessed(filepath);
+        }
+        // Notify UI server
+        await this.notifier.notify(event);
+        // Feed event to circuit breaker for health monitoring
+        if (this.circuitBreaker) {
+            // Try to find associated wrapper for this session
+            const wrapperId = this.findWrapperForSession(event.sessionId);
+            this.circuitBreaker.processEvent(event, wrapperId);
+            // Clean up circuit breaker tracking when session ends
+            if (event.eventType === 'session_end' || event.eventType === 'agent_complete') {
+                this.circuitBreaker.removeSession(event.sessionId);
+            }
+        }
+    }
+    /**
+     * Find wrapper ID associated with a session (for circuit breaker)
+     * This is a placeholder - the daemon will provide better association
+     */
+    findWrapperForSession(sessionId) {
+        // This will be enhanced by the daemon's wrapper-session correlation
+        // For now, return null and let the circuit breaker handle it
+        return null;
+    }
+    /**
+     * Handle SubagentStart event - create child session immediately
+     */
+    async handleSubagentStart(event) {
+        const parentSessionId = event.parentSessionId || undefined;
+        // Ensure parent session exists first
+        if (parentSessionId && !this.sessions.has(parentSessionId)) {
+            const parentSession = {
+                sessionId: parentSessionId,
+                machineId: event.machineId,
+                workingDirectory: event.workingDirectory,
+                startTime: event.timestamp - 1, // Slightly before child
+                status: 'active',
+                childSessionIds: [],
+                tokenUsage: { totalInput: 0, totalOutput: 0 },
+                isUserInitiated: true, // Parent is user-initiated
+                isPinned: false,
+            };
+            this.sessions.set(parentSessionId, parentSession);
+            await this.persistSession(parentSession);
+            await this.notifier.notifySessionUpdate(parentSession);
+            console.log(`[Processor] Created parent session: ${parentSessionId}`);
+        }
+        // SubagentStart should have its own session_id from Claude
+        // Create the child session with parent relationship
+        const session = {
+            sessionId: event.sessionId,
+            parentSessionId,
+            machineId: event.machineId,
+            workingDirectory: event.workingDirectory,
+            startTime: event.timestamp,
+            status: 'active',
+            childSessionIds: [],
+            tokenUsage: { totalInput: 0, totalOutput: 0 },
+            agentType: event.data?.subagent?.type?.toLowerCase() || undefined,
+            isUserInitiated: false,
+            isPinned: false,
+        };
+        this.sessions.set(session.sessionId, session);
+        await this.persistSession(session);
+        // Add child to parent's childSessionIds
+        if (parentSessionId) {
+            const parent = this.sessions.get(parentSessionId);
+            if (parent && !parent.childSessionIds.includes(session.sessionId)) {
+                parent.childSessionIds.push(session.sessionId);
+                await this.persistSession(parent);
+                await this.notifier.notifySessionUpdate(parent);
+            }
+        }
+        await this.notifier.notifySessionUpdate(session);
+        console.log(`[Processor] SubagentStart: ${session.sessionId} (type: ${session.agentType}, parent: ${session.parentSessionId})`);
+    }
+    /**
+     * Generate a short unique ID for virtual sessions
+     */
+    generateVirtualSessionId() {
+        const chars = 'abcdef0123456789';
+        let id = '';
+        for (let i = 0; i < 8; i++) {
+            id += chars[Math.floor(Math.random() * chars.length)];
+        }
+        return id;
+    }
+    /**
+     * Start tracking a subagent context when Task tool is called
+     */
+    async startSubagentContext(event) {
+        const virtualId = this.generateVirtualSessionId();
+        const agentType = this.extractAgentType(event);
+        const subagent = {
+            virtualSessionId: virtualId,
+            parentSessionId: event.sessionId,
+            agentType: agentType?.toLowerCase(),
+            startTime: event.timestamp,
+        };
+        this.state.pushActiveSubagent(event.sessionId, subagent);
+        // Create the virtual session immediately with agentType
+        const session = {
+            sessionId: virtualId,
+            machineId: event.machineId,
+            workingDirectory: event.workingDirectory,
+            startTime: event.timestamp,
+            status: 'active',
+            parentSessionId: event.sessionId,
+            childSessionIds: [],
+            tokenUsage: { totalInput: 0, totalOutput: 0 },
+            isUserInitiated: false,
+            isPinned: false,
+            agentType: agentType?.toLowerCase(),
+        };
+        this.sessions.set(virtualId, session);
+        await this.persistSession(session);
+        // Add to parent's children
+        const parent = this.sessions.get(event.sessionId);
+        if (parent && !parent.childSessionIds.includes(virtualId)) {
+            parent.childSessionIds.push(virtualId);
+            await this.persistSession(parent);
+            await this.notifier.notifySessionUpdate(parent);
+        }
+        await this.notifier.notifySessionUpdate(session);
+        console.log(`[Processor] Started subagent: ${virtualId} (type: ${agentType || 'unknown'}, parent: ${event.sessionId})`);
+    }
+    /**
+     * End the current subagent context
+     */
+    async endSubagentContext(event) {
+        const subagent = this.state.popActiveSubagent(event.sessionId);
+        if (subagent) {
+            // Mark virtual session as completed
+            const session = this.sessions.get(subagent.virtualSessionId);
+            if (session) {
+                session.status = 'completed';
+                session.endTime = event.timestamp;
+                await this.persistSession(session);
+                await this.notifier.notifySessionUpdate(session);
+            }
+            console.log(`[Processor] Ended subagent: ${subagent.virtualSessionId} (type: ${subagent.agentType || 'unknown'})`);
+        }
+    }
+    /**
+     * Extract agent type from Task tool input
+     */
+    extractAgentType(event) {
+        const toolInput = event.data?.toolInput;
+        const type = toolInput?.subagent_type || toolInput?.agentType;
+        return type ? type.toLowerCase() : undefined;
+    }
+    /**
+     * Track potential sub-agent spawns from Task tool calls
+     */
+    trackSubagentSpawn(event) {
+        if (event.hookType === 'PreToolUse' && event.data?.toolName === 'Task') {
+            const spawn = {
+                parentSessionId: event.sessionId,
+                workingDirectory: event.workingDirectory,
+                timestamp: event.timestamp,
+                agentType: this.extractAgentType(event),
+            };
+            const spawns = this.state.pendingSubagentSpawns;
+            spawns.push(spawn);
+            // Clean up old spawns (older than correlation window)
+            const cutoff = Date.now() - SUBAGENT_CORRELATION_WINDOW_MS;
+            this.state.pendingSubagentSpawns = spawns.filter(s => s.timestamp > cutoff);
+        }
+    }
+    /**
+     * Update session state based on event
+     */
+    async updateSession(event) {
+        let session = this.sessions.get(event.sessionId);
+        if (!session) {
+            // New session
+            const parentSessionId = event.parentSessionId || this.correlateParent(event);
+            const isUserInitiated = !parentSessionId;
+            session = {
+                sessionId: event.sessionId,
+                machineId: event.machineId,
+                workingDirectory: event.workingDirectory,
+                startTime: event.timestamp,
+                status: 'active',
+                parentSessionId,
+                childSessionIds: [],
+                tokenUsage: { totalInput: 0, totalOutput: 0 },
+                isUserInitiated,
+                isPinned: false, // Manual pinning only
+            };
+            // Add to parent's children
+            if (parentSessionId) {
+                const parent = this.sessions.get(parentSessionId);
+                if (parent && !parent.childSessionIds.includes(event.sessionId)) {
+                    parent.childSessionIds.push(event.sessionId);
+                    await this.persistSession(parent);
+                }
+            }
+            this.sessions.set(event.sessionId, session);
+            console.log(`[Processor] New session: ${event.sessionId} (parent: ${parentSessionId || 'none'})`);
+        }
+        // Update session based on event
+        if (event.eventType === 'session_end' || event.eventType === 'agent_complete') {
+            session.status = 'completed';
+            session.endTime = event.timestamp;
+            // Use session token usage from transcript parsing
+            if (event.data.sessionTokenUsage) {
+                session.tokenUsage = {
+                    totalInput: event.data.sessionTokenUsage.input || 0,
+                    totalOutput: event.data.sessionTokenUsage.output || 0,
+                    totalCacheRead: event.data.sessionTokenUsage.cacheRead || 0,
+                    totalCacheCreation: (event.data.sessionTokenUsage.cacheCreation5m || 0) +
+                        (event.data.sessionTokenUsage.cacheCreation1h || 0),
+                };
+            }
+            // Store model and transcript path
+            if (event.data.model) {
+                session.model = event.data.model;
+            }
+            if (event.data.transcriptPath) {
+                session.transcriptPath = event.data.transcriptPath;
+            }
+        }
+        else if (event.eventType === 'error') {
+            session.status = 'error';
+        }
+        // Accumulate tokens
+        if (event.data?.tokenUsage) {
+            session.tokenUsage.totalInput += event.data.tokenUsage.input || 0;
+            session.tokenUsage.totalOutput += event.data.tokenUsage.output || 0;
+        }
+        await this.persistSession(session);
+        await this.notifier.notifySessionUpdate(session);
+    }
+    /**
+     * Try to correlate a new session with a pending sub-agent spawn
+     */
+    correlateParent(event) {
+        const spawns = this.state.pendingSubagentSpawns;
+        const cutoff = event.timestamp - SUBAGENT_CORRELATION_WINDOW_MS;
+        for (const spawn of spawns) {
+            if (spawn.timestamp < cutoff)
+                continue;
+            if (spawn.parentSessionId === event.sessionId)
+                continue;
+            if (!this.directoriesMatch(spawn.workingDirectory, event.workingDirectory))
+                continue;
+            return spawn.parentSessionId;
+        }
+        return undefined;
+    }
+    /**
+     * Check if two working directories match (handles git worktrees)
+     */
+    directoriesMatch(dir1, dir2) {
+        // Normalize paths
+        const norm1 = dir1.replace(/\\/g, '/').replace(/\/+$/, '');
+        const norm2 = dir2.replace(/\\/g, '/').replace(/\/+$/, '');
+        // Exact match
+        if (norm1 === norm2)
+            return true;
+        // One contains the other
+        if (norm1.startsWith(norm2 + '/') || norm2.startsWith(norm1 + '/'))
+            return true;
+        // Check for common parent (worktree scenario)
+        const parent1 = norm1.split('/').slice(0, -1).join('/');
+        const parent2 = norm2.split('/').slice(0, -1).join('/');
+        if (parent1 === parent2)
+            return true;
+        // Check for shared ancestor up to 3 levels
+        const parts1 = norm1.split('/');
+        const parts2 = norm2.split('/');
+        const minLength = Math.min(parts1.length, parts2.length);
+        // Find common prefix depth (at least 3 levels like /home/user/project)
+        for (let i = Math.min(minLength, parts1.length - 3); i >= 3; i--) {
+            const prefix1 = parts1.slice(0, i).join('/');
+            const prefix2 = parts2.slice(0, i).join('/');
+            if (prefix1 === prefix2)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Persist session metadata to disk
+     */
+    async persistSession(session) {
+        const sessionDir = path.join(PATHS.sessionsDir, session.sessionId);
+        await fs.promises.mkdir(sessionDir, { recursive: true });
+        const metaPath = path.join(sessionDir, 'meta.json');
+        await fs.promises.writeFile(metaPath, JSON.stringify(session, null, 2));
+    }
+    /**
+     * Persist event to session's events.jsonl file
+     */
+    async persistEvent(event) {
+        const sessionDir = path.join(PATHS.sessionsDir, event.sessionId);
+        await fs.promises.mkdir(sessionDir, { recursive: true });
+        const eventsPath = path.join(sessionDir, 'events.jsonl');
+        await fs.promises.appendFile(eventsPath, JSON.stringify(event) + '\n');
+    }
+    /**
+     * Move processed file from raw/ to processed/
+     */
+    async moveToProcessed(filepath) {
+        try {
+            await fs.promises.mkdir(PATHS.processedDir, { recursive: true });
+            const filename = path.basename(filepath);
+            const destPath = path.join(PATHS.processedDir, filename);
+            await fs.promises.rename(filepath, destPath);
+        }
+        catch (err) {
+            console.error('[Processor] Failed to move to processed:', err);
+        }
+    }
+}
+exports.EventProcessor = EventProcessor;