@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/multi-agent/file-locks.js

@@ -0,0 +1,194 @@
+/**
+ * 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 { getDb } from '../db/index.js';
+// =============================================================================
+// Module-level singleton
+// =============================================================================
+let _fileLockManager = null;
+/**
+ * Get the current FileLockManager instance (null if not initialized)
+ */
+export function getFileLockManager() {
+    return _fileLockManager;
+}
+/**
+ * Initialize and return the FileLockManager singleton.
+ */
+export function initFileLockManager() {
+    if (!_fileLockManager) {
+        _fileLockManager = new FileLockManager(getDb());
+    }
+    return _fileLockManager;
+}
+// =============================================================================
+// FileLockManager
+// =============================================================================
+/**
+ * Lock TTL in seconds. A lock older than this is considered expired and can be
+ * overwritten by another session. This allows multi-terminal workflows where
+ * terminals take turns editing different files — once a terminal moves on to
+ * another file, the lock on the previous file expires after this period.
+ *
+ * The lock is refreshed (locked_at updated) on every successful write to the
+ * same file, so sequential edits within a session keep the lock alive.
+ */
+const LOCK_TTL_SECONDS = 60;
+export class FileLockManager {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 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, projectId, sessionId, agentId) {
+        try {
+            // Check if another session holds the lock
+            const existing = this.db.prepare(`SELECT session_id, locked_at FROM file_locks WHERE path = ? AND project_id = ?`).get(filePath, projectId);
+            if (existing && existing.session_id !== sessionId) {
+                // Another session holds the lock — check if it's expired
+                if (!isLockExpired(existing.locked_at)) {
+                    return false;
+                }
+                // Lock expired — safe to overwrite
+            }
+            // Acquire or refresh the lock (INSERT OR REPLACE for idempotent re-lock)
+            this.db.prepare(`
+        INSERT OR REPLACE INTO file_locks (path, project_id, session_id, agent_id, locked_at)
+        VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+      `).run(filePath, projectId, sessionId, agentId);
+            return true;
+        }
+        catch {
+            // Best effort — if DB errors, allow the write
+            return true;
+        }
+    }
+    /**
+     * Release a specific file lock.
+     */
+    releaseLock(filePath, projectId) {
+        try {
+            this.db.prepare('DELETE FROM file_locks WHERE path = ? AND project_id = ?')
+                .run(filePath, projectId);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    /**
+     * Release all locks held by a session.
+     * Called on unregister or project switch.
+     */
+    releaseSessionLocks(sessionId) {
+        try {
+            this.db.prepare('DELETE FROM file_locks WHERE session_id = ?')
+                .run(sessionId);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    /**
+     * 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, projectId, selfSessionId) {
+        try {
+            const row = this.db.prepare(`
+        SELECT
+          fl.path,
+          fl.session_id,
+          fl.agent_id,
+          fl.locked_at,
+          ts.label,
+          ts.last_heartbeat
+        FROM file_locks fl
+        JOIN terminal_sessions ts ON fl.session_id = ts.id
+        WHERE fl.path = ? AND fl.project_id = ?
+          AND fl.session_id != ?
+          AND ts.status = 'active'
+      `).get(filePath, projectId, selfSessionId);
+            if (!row)
+                return null;
+            // Check if the lock has expired (file not recently written to)
+            if (isLockExpired(row.locked_at)) {
+                return null;
+            }
+            return {
+                path: row.path,
+                sessionId: row.session_id,
+                sessionLabel: row.label ?? `Terminal ${row.session_id.slice(0, 8)}`,
+                agentId: row.agent_id,
+                lockedAt: row.locked_at,
+                lockedAgo: formatRelativeTime(row.locked_at),
+            };
+        }
+        catch {
+            // Best effort — if DB errors, allow the write
+            return null;
+        }
+    }
+    /**
+     * Clean up locks from stale/dead sessions (heartbeat expired).
+     * Called opportunistically during stale session cleanup.
+     */
+    cleanupStaleLocks(staleThresholdMs) {
+        try {
+            // Delete locks whose owning session has expired heartbeat
+            const thresholdSec = Math.floor(staleThresholdMs / 1000);
+            const result = this.db.prepare(`
+        DELETE FROM file_locks
+        WHERE session_id IN (
+          SELECT id FROM terminal_sessions
+          WHERE (julianday('now') - julianday(last_heartbeat)) * 86400 > ?
+        )
+      `).run(thresholdSec);
+            return result.changes;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Check if a lock's locked_at timestamp is older than LOCK_TTL_SECONDS.
+ */
+function isLockExpired(lockedAt) {
+    const utcStr = lockedAt.endsWith('Z') ? lockedAt : lockedAt + 'Z';
+    const lockTime = new Date(utcStr).getTime();
+    const ageMs = Date.now() - lockTime;
+    return ageMs > LOCK_TTL_SECONDS * 1000;
+}
+/**
+ * Format a relative time string from a SQLite CURRENT_TIMESTAMP datetime.
+ */
+function formatRelativeTime(sqliteDatetime) {
+    const now = Date.now();
+    const utcStr = sqliteDatetime.endsWith('Z') ? sqliteDatetime : sqliteDatetime + 'Z';
+    const then = new Date(utcStr).getTime();
+    const diffMs = now - then;
+    const diffSec = Math.floor(diffMs / 1000);
+    if (diffSec < 60)
+        return `${String(diffSec)}s ago`;
+    const diffMin = Math.floor(diffSec / 60);
+    if (diffMin < 60)
+        return `${String(diffMin)}m ago`;
+    const diffHr = Math.floor(diffMin / 60);
+    return `${String(diffHr)}h ${String(diffMin % 60)}m ago`;
+}

package/dist/multi-agent/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Multi-Agent Module
+ *
+ * Provides multi-agent team functionality:
+ * - AgentTeam: Orchestrates multiple persistent agents
+ * - TeamAgent: Wrapper for individual team agents
+ * - Checkpointing: Persistence for team state
+ * - SharedContextManager: Shared context across agents
+ * - ArtifactStore: Storage for team artifacts
+ */
+export type { MascotExpression, AgentRole, RoleMetadata, TeamAgentConfig, SerializedTeamAgent, TeamMetadata, SerializedTeam, TeamEventType, TeamEvent, TeamEventHandler, } from './types.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS } from './types.js';
+export { TeamAgent } from './team-agent.js';
+export { AgentTeam, type AgentTeamConfig } from './team.js';
+export { TeamCheckpointer, getTeamCheckpointer, getSessionsPath } from './checkpointer.js';
+export { SharedContextManager, type SharedContext, type SharedProjectInfo, type SharedTeamInfo, type TeamRosterEntry, type TeamActivity, type TeamActivityType, type SharedDecision, type TokenBudget, type SerializedSharedContext, } from './shared-context.js';
+export { ArtifactStore, type Artifact, type ArtifactType, type ArtifactSummary, type CreateArtifactOptions, type UpdateArtifactOptions, } from './artifacts.js';
+export { parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, type ParsedMention, type ParsedInput, } from './mention-parser.js';
+export { ContextResolver, buildContextMap, type ResolvedMention, type ResolutionSource, type ResolveOptions, } from './context-resolver.js';
+export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity, } from './activity.js';
+export { findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, } from './agent-selection.js';
+export { suggestOwner, suggestOwners, matchesAgentExpertise, } from './task-suggestion.js';
+export { wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, } from './task-assignment.js';
+export { PendingRequestsManager, getPendingRequestsManager, resetPendingRequestsManager, type PendingRequest, type PendingRequestResponse, type PendingRequestType, type EnqueueOptions, type PendingRequestsEvents, } from './pending-requests.js';

package/dist/multi-agent/index.js

@@ -0,0 +1,30 @@
+/**
+ * Multi-Agent Module
+ *
+ * Provides multi-agent team functionality:
+ * - AgentTeam: Orchestrates multiple persistent agents
+ * - TeamAgent: Wrapper for individual team agents
+ * - Checkpointing: Persistence for team state
+ * - SharedContextManager: Shared context across agents
+ * - ArtifactStore: Storage for team artifacts
+ */
+export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS } from './types.js';
+// Classes
+export { TeamAgent } from './team-agent.js';
+export { AgentTeam } from './team.js';
+export { TeamCheckpointer, getTeamCheckpointer, getSessionsPath } from './checkpointer.js';
+// Phase 2: Shared Context
+export { SharedContextManager, } from './shared-context.js';
+export { ArtifactStore, } from './artifacts.js';
+// Phase 2c: Mention References
+export { parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, } from './mention-parser.js';
+export { ContextResolver, buildContextMap, } from './context-resolver.js';
+// Phase 2c: Activity Recording
+export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity, } from './activity.js';
+// Phase 3: Agent Selection (for delegation)
+export { findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, } from './agent-selection.js';
+// Task Ownership: Suggestion and Assignment
+export { suggestOwner, suggestOwners, matchesAgentExpertise, } from './task-suggestion.js';
+export { wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, } from './task-assignment.js';
+// Phase 3b: Background Agents - Pending Requests
+export { PendingRequestsManager, getPendingRequestsManager, resetPendingRequestsManager, } from './pending-requests.js';

package/dist/multi-agent/mention-parser.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MentionParser - Parse $agent references in user input
+ *
+ * Two types of $agent usage:
+ * 1. Switch: "$arch message" at start of input → switch to arch, send message
+ * 2. Reference: "what did $arch propose" mid-sentence → inject arch's context
+ *
+ * Detection rule: $name at START of trimmed input = switch. Otherwise = reference.
+ */
+/**
+ * A parsed mention in the input
+ */
+export interface ParsedMention {
+    /** Agent ID without $ prefix */
+    agentId: string;
+    /** Position in original input */
+    startIndex: number;
+    endIndex: number;
+    /** The full match including $ prefix */
+    raw: string;
+    /** Optional query/context after the agent name */
+    context?: string;
+}
+/**
+ * Result of parsing user input for mentions
+ */
+export interface ParsedInput {
+    /** Original input text */
+    original: string;
+    /** Whether the input starts with a switch ($agent at beginning) */
+    hasSwitch: boolean;
+    /** The switch target agent (if hasSwitch is true) */
+    switchTarget?: string;
+    /** Message to send after switching (if hasSwitch is true) */
+    messageAfterSwitch?: string;
+    /** All reference mentions (mid-sentence $agent) */
+    references: ParsedMention[];
+    /** Input with mentions replaced by placeholders for context injection */
+    normalizedInput: string;
+}
+/**
+ * Parse user input for $agent mentions
+ *
+ * @param input - User input string
+ * @param validAgents - Set of valid agent IDs (for validation)
+ * @returns Parsed input with mentions identified
+ */
+export declare function parseInputForMentions(input: string, validAgents?: Set<string>): ParsedInput;
+/**
+ * Get unique agent IDs from references
+ */
+export declare function getReferencedAgents(parsed: ParsedInput): string[];
+/**
+ * Check if input contains any references (not just switch)
+ */
+export declare function hasReferences(parsed: ParsedInput): boolean;
+/**
+ * Build a message with context injected for mentions
+ *
+ * @param parsed - Parsed input
+ * @param contextMap - Map of agentId → resolved context string
+ * @returns Message with context prepended or injected
+ */
+export declare function buildMessageWithContext(parsed: ParsedInput, contextMap: Map<string, string>): string;

package/dist/multi-agent/mention-parser.js

@@ -0,0 +1,146 @@
+/**
+ * MentionParser - Parse $agent references in user input
+ *
+ * Two types of $agent usage:
+ * 1. Switch: "$arch message" at start of input → switch to arch, send message
+ * 2. Reference: "what did $arch propose" mid-sentence → inject arch's context
+ *
+ * Detection rule: $name at START of trimmed input = switch. Otherwise = reference.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+// Match $agentname pattern - alphanumeric and underscore/hyphen
+const MENTION_PATTERN = /\$([a-zA-Z][a-zA-Z0-9_-]*)/g;
+// Match $agent at start of input (for switch detection)
+const SWITCH_PATTERN = /^\$([a-zA-Z][a-zA-Z0-9_-]*)\s*/;
+// =============================================================================
+// Parser
+// =============================================================================
+/**
+ * Parse user input for $agent mentions
+ *
+ * @param input - User input string
+ * @param validAgents - Set of valid agent IDs (for validation)
+ * @returns Parsed input with mentions identified
+ */
+export function parseInputForMentions(input, validAgents) {
+    const trimmed = input.trim();
+    // Check for switch pattern at start
+    const switchMatch = trimmed.match(SWITCH_PATTERN);
+    let hasSwitch = false;
+    let switchTarget;
+    let messageAfterSwitch;
+    let searchStart = 0;
+    if (switchMatch) {
+        const agentId = switchMatch[1].toLowerCase();
+        // Only treat as switch if it's a valid agent
+        if (!validAgents || validAgents.has(agentId)) {
+            hasSwitch = true;
+            switchTarget = agentId;
+            messageAfterSwitch = trimmed.slice(switchMatch[0].length).trim();
+            searchStart = switchMatch[0].length; // Skip switch when looking for references
+        }
+    }
+    // Find all reference mentions (excluding the switch)
+    const references = [];
+    MENTION_PATTERN.lastIndex = searchStart;
+    let match;
+    while ((match = MENTION_PATTERN.exec(trimmed)) !== null) {
+        const agentId = match[1].toLowerCase();
+        // Skip if not a valid agent (if validation set provided)
+        if (validAgents && !validAgents.has(agentId)) {
+            continue;
+        }
+        // Skip if this is the switch mention
+        if (hasSwitch && match.index === 0) {
+            continue;
+        }
+        references.push({
+            agentId,
+            startIndex: match.index,
+            endIndex: match.index + match[0].length,
+            raw: match[0],
+        });
+    }
+    // Extract context hints for each reference
+    for (const ref of references) {
+        ref.context = extractContextHint(trimmed, ref.endIndex);
+    }
+    // Build normalized input (with mention placeholders)
+    const normalizedInput = hasSwitch ? messageAfterSwitch ?? '' : trimmed;
+    // For normalized input, we keep mentions as-is but could replace with markers
+    // This is useful for the resolver to know where to inject context
+    return {
+        original: input,
+        hasSwitch,
+        switchTarget,
+        messageAfterSwitch,
+        references,
+        normalizedInput,
+    };
+}
+/**
+ * Extract a context hint following a mention
+ *
+ * Examples:
+ * - "what did $arch propose for the API" → "propose for the API"
+ * - "review $qa's feedback on the PR" → "'s feedback on the PR"
+ * - "based on $arch" → undefined
+ */
+function extractContextHint(text, afterIndex) {
+    const remaining = text.slice(afterIndex);
+    // Common patterns that provide context:
+    // - "'s <noun>" (possessive)
+    // - " <verb> <object>" (action)
+    // - " about <topic>"
+    // - " for <topic>"
+    // - " on <topic>"
+    // Get up to end of sentence or 50 chars
+    const endMatch = remaining.match(/^[^.!?\n]{0,50}/);
+    if (!endMatch || endMatch[0].trim().length < 3) {
+        return undefined;
+    }
+    return endMatch[0].trim();
+}
+/**
+ * Get unique agent IDs from references
+ */
+export function getReferencedAgents(parsed) {
+    const agents = new Set();
+    for (const ref of parsed.references) {
+        agents.add(ref.agentId);
+    }
+    return Array.from(agents);
+}
+/**
+ * Check if input contains any references (not just switch)
+ */
+export function hasReferences(parsed) {
+    return parsed.references.length > 0;
+}
+/**
+ * Build a message with context injected for mentions
+ *
+ * @param parsed - Parsed input
+ * @param contextMap - Map of agentId → resolved context string
+ * @returns Message with context prepended or injected
+ */
+export function buildMessageWithContext(parsed, contextMap) {
+    if (parsed.references.length === 0) {
+        return parsed.normalizedInput;
+    }
+    // Collect context blocks
+    const contextBlocks = [];
+    for (const ref of parsed.references) {
+        const context = contextMap.get(ref.agentId);
+        if (context) {
+            contextBlocks.push(`[Context from $${ref.agentId}:\n${context}\n]`);
+        }
+    }
+    if (contextBlocks.length === 0) {
+        return parsed.normalizedInput;
+    }
+    // Prepend context blocks to the message
+    return `${contextBlocks.join('\n\n')}\n\n${parsed.normalizedInput}`;
+}

package/dist/multi-agent/notification-manager.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 type Database from 'better-sqlite3';
+import { type SessionNotificationRecord } from '../db/index.js';
+export interface NotificationInsertOptions {
+    projectId: number;
+    fromSessionId: string;
+    toSessionId?: string | null;
+    type: 'pending_request' | 'agent_finished';
+    title: string;
+    message?: string | null;
+    payload?: Record<string, unknown>;
+}
+export interface SessionNotification extends SessionNotificationRecord {
+    /** Label of the sending session (joined from terminal_sessions) */
+    from_label: string | null;
+}
+/**
+ * Get the current NotificationManager instance (null if not initialized)
+ */
+export declare function getNotificationManager(): NotificationManager | null;
+/**
+ * Initialize and return the NotificationManager singleton.
+ */
+export declare function initNotificationManager(): NotificationManager;
+export declare class NotificationManager extends EventEmitter {
+    private readonly db;
+    private pollInterval;
+    private lastKnownCount;
+    constructor(db: Database.Database);
+    /**
+     * Start polling for new notifications (5s interval, .unref()).
+     */
+    startPolling(): void;
+    /**
+     * Stop polling.
+     */
+    stopPolling(): void;
+    /**
+     * Insert a new notification into the shared DB.
+     * Returns the notification ID, or null on failure.
+     */
+    insert(options: NotificationInsertOptions): string | null;
+    /**
+     * Get the count of unread notifications for this session.
+     * Lightweight COUNT(*) — used by the status bar poll.
+     */
+    getUnreadCount(): number;
+    /**
+     * Get all unread notifications for this session (with sender label).
+     * Used by the overlay for full display.
+     */
+    getUnread(): SessionNotification[];
+    /**
+     * Mark a single notification as read.
+     */
+    markRead(notificationId: string): void;
+    /**
+     * Mark all unread notifications for this session as read.
+     */
+    markAllRead(): void;
+    /**
+     * Clean up old notifications:
+     * - Delete read notifications older than 1 hour
+     * - Delete orphaned notifications (sender session gone, CASCADE missed)
+     */
+    cleanup(): void;
+    /**
+     * Poll for new notifications and emit 'count-changed' on delta.
+     */
+    private checkForNewNotifications;
+    /**
+     * Re-check count and emit if changed (after mark operations).
+     */
+    private emitCountChange;
+}