@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/multi-agent/notification-manager.js

@@ -0,0 +1,224 @@
+/**
+ * NotificationManager - Cross-session notifications
+ *
+ * Polls the shared session_notifications table so that events in one terminal
+ * (e.g. a background agent finishing, a pending approval request) are surfaced
+ * to other terminals working on the same project.
+ *
+ * Singleton pattern — same as SessionRegistry and FileLockManager.
+ */
+import { EventEmitter } from 'events';
+import { randomUUID } from 'crypto';
+import { getDb } from '../db/index.js';
+import { getActiveTerminalSessionId } from './session-registry.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const POLL_INTERVAL_MS = 5_000; // 5 seconds
+// =============================================================================
+// Module-level singleton
+// =============================================================================
+let _notificationManager = null;
+/**
+ * Get the current NotificationManager instance (null if not initialized)
+ */
+export function getNotificationManager() {
+    return _notificationManager;
+}
+/**
+ * Initialize and return the NotificationManager singleton.
+ */
+export function initNotificationManager() {
+    if (!_notificationManager) {
+        _notificationManager = new NotificationManager(getDb());
+    }
+    return _notificationManager;
+}
+// =============================================================================
+// NotificationManager
+// =============================================================================
+export class NotificationManager extends EventEmitter {
+    db;
+    pollInterval = null;
+    lastKnownCount = 0;
+    constructor(db) {
+        super();
+        this.db = db;
+    }
+    /**
+     * Start polling for new notifications (5s interval, .unref()).
+     */
+    startPolling() {
+        if (this.pollInterval)
+            return;
+        // Initial count
+        this.lastKnownCount = this.getUnreadCount();
+        this.pollInterval = setInterval(() => {
+            this.checkForNewNotifications();
+        }, POLL_INTERVAL_MS);
+        this.pollInterval.unref();
+    }
+    /**
+     * Stop polling.
+     */
+    stopPolling() {
+        if (this.pollInterval) {
+            clearInterval(this.pollInterval);
+            this.pollInterval = null;
+        }
+    }
+    /**
+     * Insert a new notification into the shared DB.
+     * Returns the notification ID, or null on failure.
+     */
+    insert(options) {
+        try {
+            const id = randomUUID();
+            const payloadJson = options.payload ? JSON.stringify(options.payload) : null;
+            this.db.prepare(`
+        INSERT INTO session_notifications (id, project_id, from_session_id, to_session_id, type, title, message, payload_json)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(id, options.projectId, options.fromSessionId, options.toSessionId ?? null, options.type, options.title, options.message ?? null, payloadJson);
+            return id;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get the count of unread notifications for this session.
+     * Lightweight COUNT(*) — used by the status bar poll.
+     */
+    getUnreadCount() {
+        const selfId = getActiveTerminalSessionId();
+        if (!selfId)
+            return 0;
+        try {
+            const row = this.db.prepare(`
+        SELECT COUNT(*) as count
+        FROM session_notifications n
+        WHERE n.from_session_id != ?
+          AND n.read_at IS NULL
+          AND n.project_id = (SELECT project_id FROM terminal_sessions WHERE id = ?)
+          AND (n.to_session_id IS NULL OR n.to_session_id = ?)
+      `).get(selfId, selfId, selfId);
+            return row.count;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Get all unread notifications for this session (with sender label).
+     * Used by the overlay for full display.
+     */
+    getUnread() {
+        const selfId = getActiveTerminalSessionId();
+        if (!selfId)
+            return [];
+        try {
+            return this.db.prepare(`
+        SELECT n.*, ts.label as from_label
+        FROM session_notifications n
+        LEFT JOIN terminal_sessions ts ON ts.id = n.from_session_id
+        WHERE n.from_session_id != ?
+          AND n.read_at IS NULL
+          AND n.project_id = (SELECT project_id FROM terminal_sessions WHERE id = ?)
+          AND (n.to_session_id IS NULL OR n.to_session_id = ?)
+        ORDER BY n.created_at DESC
+      `).all(selfId, selfId, selfId);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Mark a single notification as read.
+     */
+    markRead(notificationId) {
+        try {
+            this.db.prepare(`UPDATE session_notifications SET read_at = CURRENT_TIMESTAMP WHERE id = ?`).run(notificationId);
+            this.emitCountChange();
+        }
+        catch {
+            // Best effort
+        }
+    }
+    /**
+     * Mark all unread notifications for this session as read.
+     */
+    markAllRead() {
+        const selfId = getActiveTerminalSessionId();
+        if (!selfId)
+            return;
+        try {
+            this.db.prepare(`
+        UPDATE session_notifications SET read_at = CURRENT_TIMESTAMP
+        WHERE from_session_id != ?
+          AND read_at IS NULL
+          AND project_id = (SELECT project_id FROM terminal_sessions WHERE id = ?)
+          AND (to_session_id IS NULL OR to_session_id = ?)
+      `).run(selfId, selfId, selfId);
+            this.emitCountChange();
+        }
+        catch {
+            // Best effort
+        }
+    }
+    /**
+     * Clean up old notifications:
+     * - Delete read notifications older than 1 hour
+     * - Delete orphaned notifications (sender session gone, CASCADE missed)
+     */
+    cleanup() {
+        try {
+            // Delete read notifications older than 1 hour
+            this.db.prepare(`
+        DELETE FROM session_notifications
+        WHERE read_at IS NOT NULL
+          AND read_at < datetime('now', '-1 hour')
+      `).run();
+            // Delete unread notifications older than 24 hours (stale)
+            this.db.prepare(`
+        DELETE FROM session_notifications
+        WHERE created_at < datetime('now', '-24 hours')
+      `).run();
+        }
+        catch {
+            // Best effort
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    /**
+     * Poll for new notifications and emit 'count-changed' on delta.
+     */
+    checkForNewNotifications() {
+        try {
+            const currentCount = this.getUnreadCount();
+            if (currentCount !== this.lastKnownCount) {
+                this.lastKnownCount = currentCount;
+                this.emit('count-changed', currentCount);
+            }
+        }
+        catch {
+            // Best effort
+        }
+    }
+    /**
+     * Re-check count and emit if changed (after mark operations).
+     */
+    emitCountChange() {
+        try {
+            const currentCount = this.getUnreadCount();
+            if (currentCount !== this.lastKnownCount) {
+                this.lastKnownCount = currentCount;
+                this.emit('count-changed', currentCount);
+            }
+        }
+        catch {
+            // Best effort
+        }
+    }
+}

package/dist/multi-agent/pending-requests.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Pending Requests Manager (Phase 3b - Background Agents)
+ *
+ * Manages a queue of requests from background agents that need user input.
+ * Background agents can enqueue permission requests or questions, and the
+ * user can respond when convenient without blocking foreground work.
+ */
+import { EventEmitter } from 'events';
+export type PendingRequestType = 'permission' | 'question';
+export interface PendingRequest {
+    /** Unique request ID */
+    id: string;
+    /** Agent that made the request */
+    agentId: string;
+    /** Agent's mascot for display */
+    mascot: string;
+    /** Type of request */
+    type: PendingRequestType;
+    /** The prompt/question to show user */
+    prompt: string;
+    /** Available options (for questions) */
+    options?: string[];
+    /** When the request was created */
+    createdAt: Date;
+    /** Additional context (e.g., file path for permission, tool name) */
+    context?: Record<string, unknown>;
+    /** Resolve function - called when user responds */
+    resolve: (response: PendingRequestResponse) => void;
+    /** Reject function - called if request is cancelled */
+    reject: (error: Error) => void;
+}
+export interface PendingRequestResponse {
+    /** Whether the request was approved (for permissions) or answered (for questions) */
+    approved: boolean;
+    /** The selected option (for questions with options) */
+    selectedOption?: string;
+    /** Free-form response text */
+    responseText?: string;
+    /** Full overlay result (for question-type requests that use standard overlays) */
+    overlayResult?: unknown;
+}
+export interface EnqueueOptions {
+    agentId: string;
+    mascot: string;
+    type: PendingRequestType;
+    prompt: string;
+    options?: string[];
+    context?: Record<string, unknown>;
+}
+export interface PendingRequestsEvents {
+    /** Emitted when a new request is added */
+    'request-added': (request: PendingRequest) => void;
+    /** Emitted when a request is resolved */
+    'request-resolved': (requestId: string, response: PendingRequestResponse) => void;
+    /** Emitted when a request is rejected/cancelled */
+    'request-rejected': (requestId: string, error: Error) => void;
+    /** Emitted when the pending count changes */
+    'count-changed': (count: number) => void;
+}
+export declare class PendingRequestsManager extends EventEmitter {
+    private readonly requests;
+    /**
+     * Enqueue a request from a background agent.
+     * Returns a promise that resolves when the user responds.
+     *
+     * @param options - Request options
+     * @returns Promise that resolves with the user's response
+     */
+    enqueue(options: EnqueueOptions): Promise<PendingRequestResponse>;
+    /**
+     * Get the number of pending requests.
+     */
+    getCount(): number;
+    /**
+     * Get all pending requests (for overlay display).
+     */
+    getAll(): PendingRequest[];
+    /**
+     * Get a specific request by ID.
+     */
+    get(id: string): PendingRequest | undefined;
+    /**
+     * Get requests for a specific agent.
+     */
+    getByAgent(agentId: string): PendingRequest[];
+    /**
+     * Respond to a pending request (approve/answer).
+     * This resolves the promise returned by enqueue().
+     *
+     * @param id - Request ID
+     * @param response - User's response
+     */
+    respond(id: string, response: PendingRequestResponse): boolean;
+    /**
+     * Reject/cancel a pending request.
+     * This rejects the promise returned by enqueue().
+     *
+     * @param id - Request ID
+     * @param reason - Rejection reason
+     */
+    reject(id: string, reason?: string): boolean;
+    /**
+     * Reject all requests for a specific agent.
+     * Called when an agent is killed/cancelled.
+     *
+     * @param agentId - Agent ID
+     * @param reason - Rejection reason
+     */
+    rejectAllForAgent(agentId: string, reason?: string): number;
+    /**
+     * Clear all pending requests.
+     */
+    clear(): void;
+}
+/**
+ * Get the singleton PendingRequestsManager instance.
+ */
+export declare function getPendingRequestsManager(): PendingRequestsManager;
+/**
+ * Reset the singleton (for testing).
+ */
+export declare function resetPendingRequestsManager(): void;

package/dist/multi-agent/pending-requests.js

@@ -0,0 +1,155 @@
+/**
+ * Pending Requests Manager (Phase 3b - Background Agents)
+ *
+ * Manages a queue of requests from background agents that need user input.
+ * Background agents can enqueue permission requests or questions, and the
+ * user can respond when convenient without blocking foreground work.
+ */
+import { EventEmitter } from 'events';
+import { randomUUID } from 'crypto';
+// =============================================================================
+// Manager Class
+// =============================================================================
+export class PendingRequestsManager extends EventEmitter {
+    requests = new Map();
+    /**
+     * Enqueue a request from a background agent.
+     * Returns a promise that resolves when the user responds.
+     *
+     * @param options - Request options
+     * @returns Promise that resolves with the user's response
+     */
+    enqueue(options) {
+        return new Promise((resolve, reject) => {
+            const request = {
+                id: randomUUID(),
+                agentId: options.agentId,
+                mascot: options.mascot,
+                type: options.type,
+                prompt: options.prompt,
+                options: options.options,
+                context: options.context,
+                createdAt: new Date(),
+                resolve,
+                reject,
+            };
+            this.requests.set(request.id, request);
+            this.emit('request-added', request);
+            this.emit('count-changed', this.requests.size);
+        });
+    }
+    /**
+     * Get the number of pending requests.
+     */
+    getCount() {
+        return this.requests.size;
+    }
+    /**
+     * Get all pending requests (for overlay display).
+     */
+    getAll() {
+        return Array.from(this.requests.values()).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    }
+    /**
+     * Get a specific request by ID.
+     */
+    get(id) {
+        return this.requests.get(id);
+    }
+    /**
+     * Get requests for a specific agent.
+     */
+    getByAgent(agentId) {
+        return this.getAll().filter(r => r.agentId === agentId);
+    }
+    /**
+     * Respond to a pending request (approve/answer).
+     * This resolves the promise returned by enqueue().
+     *
+     * @param id - Request ID
+     * @param response - User's response
+     */
+    respond(id, response) {
+        const request = this.requests.get(id);
+        if (!request) {
+            return false;
+        }
+        // Remove from queue
+        this.requests.delete(id);
+        // Resolve the promise
+        request.resolve(response);
+        // Emit events
+        this.emit('request-resolved', id, response);
+        this.emit('count-changed', this.requests.size);
+        return true;
+    }
+    /**
+     * Reject/cancel a pending request.
+     * This rejects the promise returned by enqueue().
+     *
+     * @param id - Request ID
+     * @param reason - Rejection reason
+     */
+    reject(id, reason = 'Request cancelled') {
+        const request = this.requests.get(id);
+        if (!request) {
+            return false;
+        }
+        // Remove from queue
+        this.requests.delete(id);
+        // Reject the promise
+        const error = new Error(reason);
+        request.reject(error);
+        // Emit events
+        this.emit('request-rejected', id, error);
+        this.emit('count-changed', this.requests.size);
+        return true;
+    }
+    /**
+     * Reject all requests for a specific agent.
+     * Called when an agent is killed/cancelled.
+     *
+     * @param agentId - Agent ID
+     * @param reason - Rejection reason
+     */
+    rejectAllForAgent(agentId, reason = 'Agent cancelled') {
+        const agentRequests = this.getByAgent(agentId);
+        for (const request of agentRequests) {
+            this.reject(request.id, reason);
+        }
+        return agentRequests.length;
+    }
+    /**
+     * Clear all pending requests.
+     */
+    clear() {
+        for (const request of this.requests.values()) {
+            request.reject(new Error('All requests cleared'));
+        }
+        this.requests.clear();
+        this.emit('count-changed', 0);
+    }
+}
+// =============================================================================
+// Singleton Instance
+// =============================================================================
+let instance = null;
+/**
+ * Get the singleton PendingRequestsManager instance.
+ */
+export function getPendingRequestsManager() {
+    if (!instance) {
+        instance = new PendingRequestsManager();
+    }
+    return instance;
+}
+/**
+ * Reset the singleton (for testing).
+ */
+export function resetPendingRequestsManager() {
+    if (instance) {
+        instance.clear();
+        instance.removeAllListeners();
+    }
+    instance = null;
+}

package/dist/multi-agent/session-registry.d.ts

@@ -0,0 +1,139 @@
+/**
+ * SessionRegistry - Multi-terminal session awareness
+ *
+ * Manages this terminal's session lifecycle in a shared SQLite table.
+ * Each CLI instance registers on startup, heartbeats periodically,
+ * and unregisters on shutdown. Other instances can query active sessions.
+ *
+ * Uses the shared projects.db with WAL mode for concurrent access.
+ */
+import type Database from 'better-sqlite3';
+import { type TerminalSessionRecord } from '../db/index.js';
+export interface AgentDescriptor {
+    id: string;
+    displayName: string;
+    mascot: string;
+}
+/**
+ * Get the current SessionRegistry instance (null if not initialized)
+ */
+export declare function getSessionRegistry(): SessionRegistry | null;
+/**
+ * Initialize and return the SessionRegistry singleton.
+ * @param sessionsBasePath - Optional base path for session files (e.g., ~/.compilr-dev/sessions).
+ *   Used for session file cleanup when terminals unregister.
+ */
+export declare function initSessionRegistry(sessionsBasePath?: string): SessionRegistry;
+/**
+ * Get the active terminal session ID for this process
+ */
+export declare function getActiveTerminalSessionId(): string | null;
+/**
+ * Set the active terminal session ID for this process
+ */
+export declare function setActiveTerminalSessionId(id: string | null): void;
+export declare class SessionRegistry {
+    private sessionId;
+    private currentProjectId;
+    private heartbeatInterval;
+    private countCheckInterval;
+    private readonly db;
+    private readonly sessionsBasePath;
+    private lastKnownCount;
+    private onCountChangeCallback;
+    constructor(db: Database.Database, sessionsBasePath?: string);
+    /**
+     * Set a callback invoked when the active session count changes.
+     * Used by the footer to trigger a re-render when terminals join/leave.
+     */
+    onCountChange(callback: (count: number) => void): void;
+    /**
+     * Register this terminal in the session registry.
+     * Cleans up stale sessions, then inserts a new row.
+     * Returns the session ID.
+     */
+    register(projectId: number | null, label?: string): string;
+    /**
+     * Unregister this terminal from the session registry.
+     * Stops heartbeat and deletes the row.
+     */
+    unregister(): void;
+    /**
+     * Update the agent roster for this terminal session
+     */
+    updateAgents(agents: AgentDescriptor[]): void;
+    /**
+     * Set the currently active agent for this terminal session
+     */
+    setActiveAgent(agentId: string): void;
+    /**
+     * Get the project-scoped active session count.
+     * Returns the count scoped to this terminal's current project,
+     * or global count if no project is set.
+     * Used by footer rendering to show the correct terminal count.
+     */
+    getProjectScopedSessionCount(): number;
+    /**
+     * Update the project ID for this terminal session.
+     * Called when the user switches projects.
+     * Triggers an immediate count re-check for the new project scope.
+     */
+    updateProjectId(projectId: number | null): void;
+    /**
+     * Get all active sessions, optionally filtered by project.
+     * Pass undefined to get all sessions regardless of project.
+     */
+    getActiveSessions(projectId?: number | null): TerminalSessionRecord[];
+    /**
+     * Get the count of active sessions, optionally filtered by project.
+     * Pass undefined to count all sessions.
+     */
+    getActiveSessionCount(projectId?: number | null): number;
+    /**
+     * Clean up stale and dead sessions.
+     * A session is stale if its last heartbeat is older than the threshold.
+     * A session is dead if its PID no longer exists.
+     * Returns the count of sessions cleaned.
+     */
+    cleanupStale(): number;
+    /**
+     * Get all agent IDs in use by other terminals (excluding self).
+     * Optionally filtered to the same project.
+     * Used for cross-terminal collision detection.
+     */
+    getGlobalAgentIds(projectId?: number | null): string[];
+    /**
+     * Clean up orphaned session files for all stale sessions.
+     * Scans project directories under sessionsBasePath for terminal-scoped files
+     * whose session prefix is not in the active set.
+     * Returns the count of files cleaned.
+     */
+    cleanupSessionFiles(): number;
+    /**
+     * Clean up transient session files for a specific session prefix in all project directories.
+     * Preserves current-{prefix}.json files so they remain available for /resume.
+     */
+    private cleanupSessionFilesForPrefix;
+    /**
+     * Clean up orphaned transient session files in a single project directory.
+     * Preserves current-*.json files so they remain available for /resume.
+     * Returns count of files removed.
+     */
+    private cleanupOrphanFilesInDir;
+    /**
+     * Send a heartbeat (update last_heartbeat timestamp).
+     * Also opportunistically clean up stale sessions.
+     */
+    private heartbeat;
+    /**
+     * Check if the active session count changed and notify listener.
+     * Runs on a 5s interval — lightweight SELECT COUNT query.
+     * Scoped to current project for project-aware terminal count.
+     */
+    private checkCountChange;
+    /**
+     * Generate a label like "Terminal 1", "Terminal 2" using the next available number.
+     * Avoids duplicates by checking which numbers are already in use.
+     */
+    private generateLabel;
+}