@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/multi-agent/delegation-tracker.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Delegation Tracker (Phase 3d-beta - Coordinator Mode)
+ *
+ * Tracks active delegations from the coordinator to background specialists.
+ * Maintains a completion event queue so the coordinator can be notified
+ * when specialists finish their work.
+ *
+ * Pattern follows PendingRequestsManager (singleton, event-based).
+ */
+import { EventEmitter } from 'events';
+export type DelegationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+export interface Delegation {
+    /** Unique delegation ID (del_<uuid>) */
+    id: string;
+    /** Agent that initiated the delegation (always 'default' for now) */
+    coordinatorId: string;
+    /** Target specialist agent ID (e.g., 'arch', 'dev', 'qa') */
+    targetAgentId: string;
+    /** Task description sent to the specialist */
+    task: string;
+    /** What the specialist is expected to produce */
+    expectedOutput?: string;
+    /** Associated todo index (if any) */
+    todoIndex?: number;
+    /** Current status */
+    status: DelegationStatus;
+    /** Result (set on completion or failure) */
+    result?: DelegationResult;
+    /** When the delegation was created */
+    createdAt: Date;
+    /** When the delegation completed */
+    completedAt?: Date;
+}
+export interface DelegationResult {
+    /** Whether the task completed successfully */
+    success: boolean;
+    /** Brief outcome summary */
+    summary: string;
+    /** Artifact IDs created by the specialist */
+    artifactIds: string[];
+    /** Error message (if failed) */
+    error?: string;
+}
+export interface CompletionEvent {
+    /** The delegation ID */
+    delegationId: string;
+    /** The specialist that completed the work */
+    agentId: string;
+    /** Completion status */
+    status: 'completed' | 'failed';
+    /** Result details */
+    result: DelegationResult;
+    /** When the event was generated */
+    timestamp: Date;
+}
+export interface CreateDelegationOptions {
+    /** Agent that initiated the delegation */
+    coordinatorId: string;
+    /** Target specialist agent ID */
+    targetAgentId: string;
+    /** Task description */
+    task: string;
+    /** Expected output description */
+    expectedOutput?: string;
+    /** Associated todo index */
+    todoIndex?: number;
+}
+export interface DelegationStats {
+    total: number;
+    pending: number;
+    running: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+}
+export interface DelegationTrackerEvents {
+    /** Emitted when a new delegation is created */
+    'delegation-created': (delegation: Delegation) => void;
+    /** Emitted when a delegation completes successfully */
+    'delegation-completed': (event: CompletionEvent) => void;
+    /** Emitted when a delegation fails */
+    'delegation-failed': (event: CompletionEvent) => void;
+    /** Emitted when delegation counts change */
+    'count-changed': (stats: DelegationStats) => void;
+}
+export declare class DelegationTracker extends EventEmitter {
+    private readonly delegations;
+    private readonly completionQueue;
+    /**
+     * Create a new delegation.
+     */
+    create(options: CreateDelegationOptions): Delegation;
+    /**
+     * Update a delegation's status.
+     */
+    updateStatus(id: string, status: DelegationStatus): void;
+    /**
+     * Mark a delegation as completed with a result.
+     */
+    complete(id: string, result: DelegationResult): void;
+    /**
+     * Mark a delegation as failed.
+     */
+    fail(id: string, error: string): void;
+    /**
+     * Mark a delegation as cancelled.
+     */
+    cancel(id: string): void;
+    /**
+     * Cancel all active delegations for a specific agent.
+     */
+    cancelAllForAgent(agentId: string): number;
+    /**
+     * Get a delegation by ID.
+     */
+    get(id: string): Delegation | undefined;
+    /**
+     * Get all delegations targeting a specific agent.
+     */
+    getByAgent(agentId: string): Delegation[];
+    /**
+     * Get all active (pending or running) delegations.
+     */
+    getActive(): Delegation[];
+    /**
+     * Get all delegations.
+     */
+    getAll(): Delegation[];
+    /**
+     * Check if there are pending completion events.
+     */
+    hasCompletionEvents(): boolean;
+    /**
+     * Drain all completion events (removes them from queue).
+     */
+    drainCompletionEvents(): CompletionEvent[];
+    /**
+     * Peek at completion events without removing them.
+     */
+    peekCompletionEvents(): CompletionEvent[];
+    /**
+     * Get delegation statistics.
+     */
+    getStats(): DelegationStats;
+    /**
+     * Clear all delegations and completion events.
+     */
+    clear(): void;
+}
+/**
+ * Get the singleton DelegationTracker instance.
+ */
+export declare function getDelegationTracker(): DelegationTracker;
+/**
+ * Reset the singleton (for testing).
+ */
+export declare function resetDelegationTracker(): void;

package/dist/multi-agent/delegation-tracker.js

@@ -0,0 +1,243 @@
+/**
+ * Delegation Tracker (Phase 3d-beta - Coordinator Mode)
+ *
+ * Tracks active delegations from the coordinator to background specialists.
+ * Maintains a completion event queue so the coordinator can be notified
+ * when specialists finish their work.
+ *
+ * Pattern follows PendingRequestsManager (singleton, event-based).
+ */
+import { EventEmitter } from 'events';
+import { randomUUID } from 'crypto';
+// =============================================================================
+// Tracker Class
+// =============================================================================
+export class DelegationTracker extends EventEmitter {
+    delegations = new Map();
+    completionQueue = [];
+    /**
+     * Create a new delegation.
+     */
+    create(options) {
+        const delegation = {
+            id: `del_${randomUUID().slice(0, 8)}`,
+            coordinatorId: options.coordinatorId,
+            targetAgentId: options.targetAgentId,
+            task: options.task,
+            expectedOutput: options.expectedOutput,
+            todoIndex: options.todoIndex,
+            status: 'pending',
+            createdAt: new Date(),
+        };
+        this.delegations.set(delegation.id, delegation);
+        this.emit('delegation-created', delegation);
+        this.emit('count-changed', this.getStats());
+        return delegation;
+    }
+    /**
+     * Update a delegation's status.
+     */
+    updateStatus(id, status) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        delegation.status = status;
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Mark a delegation as completed with a result.
+     */
+    complete(id, result) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        delegation.status = 'completed';
+        delegation.result = result;
+        delegation.completedAt = new Date();
+        const event = {
+            delegationId: id,
+            agentId: delegation.targetAgentId,
+            status: 'completed',
+            result,
+            timestamp: new Date(),
+        };
+        this.completionQueue.push(event);
+        this.emit('delegation-completed', event);
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Mark a delegation as failed.
+     */
+    fail(id, error) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        const result = {
+            success: false,
+            summary: `Failed: ${error}`,
+            artifactIds: [],
+            error,
+        };
+        delegation.status = 'failed';
+        delegation.result = result;
+        delegation.completedAt = new Date();
+        const event = {
+            delegationId: id,
+            agentId: delegation.targetAgentId,
+            status: 'failed',
+            result,
+            timestamp: new Date(),
+        };
+        this.completionQueue.push(event);
+        this.emit('delegation-failed', event);
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Mark a delegation as cancelled.
+     */
+    cancel(id) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        delegation.status = 'cancelled';
+        delegation.completedAt = new Date();
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Cancel all active delegations for a specific agent.
+     */
+    cancelAllForAgent(agentId) {
+        const active = this.getByAgent(agentId).filter(d => d.status === 'pending' || d.status === 'running');
+        for (const delegation of active) {
+            this.cancel(delegation.id);
+        }
+        return active.length;
+    }
+    // ===========================================================================
+    // Query
+    // ===========================================================================
+    /**
+     * Get a delegation by ID.
+     */
+    get(id) {
+        return this.delegations.get(id);
+    }
+    /**
+     * Get all delegations targeting a specific agent.
+     */
+    getByAgent(agentId) {
+        return Array.from(this.delegations.values())
+            .filter(d => d.targetAgentId === agentId);
+    }
+    /**
+     * Get all active (pending or running) delegations.
+     */
+    getActive() {
+        return Array.from(this.delegations.values())
+            .filter(d => d.status === 'pending' || d.status === 'running');
+    }
+    /**
+     * Get all delegations.
+     */
+    getAll() {
+        return Array.from(this.delegations.values())
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    }
+    // ===========================================================================
+    // Completion Events
+    // ===========================================================================
+    /**
+     * Check if there are pending completion events.
+     */
+    hasCompletionEvents() {
+        return this.completionQueue.length > 0;
+    }
+    /**
+     * Drain all completion events (removes them from queue).
+     */
+    drainCompletionEvents() {
+        const events = [...this.completionQueue];
+        this.completionQueue.length = 0;
+        return events;
+    }
+    /**
+     * Peek at completion events without removing them.
+     */
+    peekCompletionEvents() {
+        return [...this.completionQueue];
+    }
+    // ===========================================================================
+    // Stats
+    // ===========================================================================
+    /**
+     * Get delegation statistics.
+     */
+    getStats() {
+        let pending = 0;
+        let running = 0;
+        let completed = 0;
+        let failed = 0;
+        let cancelled = 0;
+        for (const d of this.delegations.values()) {
+            switch (d.status) {
+                case 'pending':
+                    pending++;
+                    break;
+                case 'running':
+                    running++;
+                    break;
+                case 'completed':
+                    completed++;
+                    break;
+                case 'failed':
+                    failed++;
+                    break;
+                case 'cancelled':
+                    cancelled++;
+                    break;
+            }
+        }
+        return {
+            total: this.delegations.size,
+            pending,
+            running,
+            completed,
+            failed,
+            cancelled,
+        };
+    }
+    // ===========================================================================
+    // Cleanup
+    // ===========================================================================
+    /**
+     * Clear all delegations and completion events.
+     */
+    clear() {
+        this.delegations.clear();
+        this.completionQueue.length = 0;
+        this.emit('count-changed', this.getStats());
+    }
+}
+// =============================================================================
+// Singleton Instance
+// =============================================================================
+let instance = null;
+/**
+ * Get the singleton DelegationTracker instance.
+ */
+export function getDelegationTracker() {
+    if (!instance) {
+        instance = new DelegationTracker();
+    }
+    return instance;
+}
+/**
+ * Reset the singleton (for testing).
+ */
+export function resetDelegationTracker() {
+    if (instance) {
+        instance.clear();
+        instance.removeAllListeners();
+    }
+    instance = null;
+}

package/dist/multi-agent/file-lock-hook.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File Lock Hooks - Advisory lock checks for multi-terminal file editing
+ *
+ * beforeTool hook: Checks for file lock conflicts before write_file/edit operations.
+ * afterTool hook: Acquires locks after successful write_file/edit operations.
+ *
+ * These hooks read getActiveProject() and getActiveTerminalSessionId() at call time
+ * (not capture time), so they work correctly even when project/session changes.
+ */
+import { type BeforeToolHook, type AfterToolHook } from '@compilr-dev/sdk';
+/** Getter for the active project — injected by caller to avoid tools/ → multi-agent/ cycle. */
+type ProjectGetter = () => {
+    id: number;
+    name: string;
+    displayName: string;
+    path: string;
+} | null;
+/**
+ * Create a beforeTool hook that checks for file lock conflicts.
+ * Blocks write_file and edit operations if the file is locked by another terminal.
+ * Returns an advisory error that the LLM can relay to the user.
+ */
+export declare function createFileLockCheckHook(getActiveProject: ProjectGetter): BeforeToolHook;
+/**
+ * Create an afterTool hook that acquires locks after successful writes.
+ * Locks are acquired for write_file and edit operations that succeed.
+ */
+export declare function createFileLockAcquireHook(getActiveProject: ProjectGetter): AfterToolHook;
+export {};

package/dist/multi-agent/file-lock-hook.js

@@ -0,0 +1,97 @@
+/**
+ * File Lock Hooks - Advisory lock checks for multi-terminal file editing
+ *
+ * beforeTool hook: Checks for file lock conflicts before write_file/edit operations.
+ * afterTool hook: Acquires locks after successful write_file/edit operations.
+ *
+ * These hooks read getActiveProject() and getActiveTerminalSessionId() at call time
+ * (not capture time), so they work correctly even when project/session changes.
+ */
+import { TOOL_NAMES } from '@compilr-dev/sdk';
+import { getFileLockManager } from './file-locks.js';
+import { getActiveTerminalSessionId, getSessionRegistry } from './session-registry.js';
+/**
+ * Create a beforeTool hook that checks for file lock conflicts.
+ * Blocks write_file and edit operations if the file is locked by another terminal.
+ * Returns an advisory error that the LLM can relay to the user.
+ */
+export function createFileLockCheckHook(getActiveProject) {
+    return (context) => {
+        const sessionId = getActiveTerminalSessionId();
+        const project = getActiveProject();
+        if (!sessionId || !project)
+            return undefined;
+        const { toolName, input } = context;
+        // Only check write operations
+        let filePath;
+        if (toolName === TOOL_NAMES.WRITE_FILE) {
+            filePath = input.path;
+        }
+        else if (toolName === TOOL_NAMES.EDIT) {
+            filePath = input.filePath;
+        }
+        if (!filePath)
+            return undefined;
+        const manager = getFileLockManager();
+        if (!manager)
+            return undefined;
+        const conflict = manager.checkLock(filePath, project.id, sessionId);
+        if (!conflict)
+            return undefined;
+        // Block the write — return error describing the conflict
+        return {
+            skip: true,
+            result: {
+                success: false,
+                error: `File locked by another terminal.\n` +
+                    `${conflict.path} is being edited by $${conflict.agentId} in ${conflict.sessionLabel} (locked ${conflict.lockedAgo}).\n` +
+                    `Wait for the other terminal to finish, or use the file anyway if you're sure there's no conflict.`,
+            },
+        };
+    };
+}
+/**
+ * Create an afterTool hook that acquires locks after successful writes.
+ * Locks are acquired for write_file and edit operations that succeed.
+ */
+export function createFileLockAcquireHook(getActiveProject) {
+    return (context) => {
+        const sessionId = getActiveTerminalSessionId();
+        const project = getActiveProject();
+        if (!sessionId || !project)
+            return undefined;
+        const { toolName, input, result } = context;
+        if (!result.success)
+            return undefined;
+        let filePath;
+        if (toolName === TOOL_NAMES.WRITE_FILE) {
+            filePath = input.path;
+        }
+        else if (toolName === TOOL_NAMES.EDIT) {
+            filePath = input.filePath;
+        }
+        if (!filePath)
+            return undefined;
+        const manager = getFileLockManager();
+        if (!manager)
+            return undefined;
+        // Get active agent ID from session registry
+        const registry = getSessionRegistry();
+        let agentId = 'default';
+        if (registry) {
+            try {
+                const sessions = registry.getActiveSessions();
+                const selfSession = sessions.find(s => s.id === sessionId);
+                if (selfSession) {
+                    agentId = selfSession.active_agent;
+                }
+            }
+            catch {
+                // Best effort — use default
+            }
+        }
+        // Acquire lock (INSERT OR REPLACE — idempotent for same session)
+        manager.acquireLock(filePath, project.id, sessionId, agentId);
+        return undefined;
+    };
+}

package/dist/multi-agent/file-locks.d.ts

@@ -0,0 +1,58 @@
+/**
+ * FileLockManager - Multi-terminal file lock awareness
+ *
+ * Manages advisory file locks to prevent two terminals from editing
+ * the same file simultaneously. Locks are stored in the shared projects.db
+ * and auto-cleaned when sessions are removed (via ON DELETE CASCADE).
+ *
+ * Locks are advisory — the before-tool hook blocks writes with an error
+ * message that the LLM can relay to the user.
+ */
+import type Database from 'better-sqlite3';
+export interface FileLockConflict {
+    path: string;
+    sessionId: string;
+    sessionLabel: string;
+    agentId: string;
+    lockedAt: string;
+    lockedAgo: string;
+}
+/**
+ * Get the current FileLockManager instance (null if not initialized)
+ */
+export declare function getFileLockManager(): FileLockManager | null;
+/**
+ * Initialize and return the FileLockManager singleton.
+ */
+export declare function initFileLockManager(): FileLockManager;
+export declare class FileLockManager {
+    private readonly db;
+    constructor(db: Database.Database);
+    /**
+     * Acquire a lock on a file. Returns true if lock acquired, false if held by another session.
+     * Uses INSERT OR REPLACE — if same session re-locks, just updates timestamp.
+     * If another active (non-expired) session holds the lock, returns false.
+     * Expired locks (older than LOCK_TTL_SECONDS) are overwritten.
+     */
+    acquireLock(filePath: string, projectId: number, sessionId: string, agentId: string): boolean;
+    /**
+     * Release a specific file lock.
+     */
+    releaseLock(filePath: string, projectId: number): void;
+    /**
+     * Release all locks held by a session.
+     * Called on unregister or project switch.
+     */
+    releaseSessionLocks(sessionId: string): void;
+    /**
+     * Check if a file is locked by another active session.
+     * Returns lock info if locked by someone else (and not expired), null otherwise.
+     * Expired locks (older than LOCK_TTL_SECONDS) are treated as free.
+     */
+    checkLock(filePath: string, projectId: number, selfSessionId: string): FileLockConflict | null;
+    /**
+     * Clean up locks from stale/dead sessions (heartbeat expired).
+     * Called opportunistically during stale session cleanup.
+     */
+    cleanupStaleLocks(staleThresholdMs: number): number;
+}