@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/multi-agent/checkpointer.js

@@ -0,0 +1,471 @@
+/**
+ * TeamCheckpointer - Persistence for multi-agent teams
+ *
+ * Stores team state alongside project sessions:
+ * ~/.compilr-dev/sessions/{project-id}/
+ * ├── current.json          # Single-agent session (existing)
+ * ├── team.json              # Team metadata
+ * ├── agent-default.json     # Per-agent state
+ * ├── agent-pm.json
+ * ├── agent-arch.json
+ * ├── shared-context.json    # Shared context (Phase 2)
+ * └── artifacts/             # Team artifacts (Phase 2)
+ *     ├── index.json
+ *     └── {id}.json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { AgentTeam } from './team.js';
+import { SharedContextManager } from './shared-context.js';
+import { ArtifactStore } from './artifacts.js';
+import { getActiveTerminalSessionId } from './session-registry.js';
+const ARTIFACTS_DIR = 'artifacts';
+/**
+ * Get terminal-scoped team filename, or shared 'team.json' if no session active.
+ */
+function getTeamFilename() {
+    const sessionId = getActiveTerminalSessionId();
+    if (sessionId)
+        return `team-${sessionId.slice(0, 8)}.json`;
+    return 'team.json';
+}
+/**
+ * Get terminal-scoped agent file prefix, or shared 'agent-' if no session active.
+ */
+function getAgentFilePrefix() {
+    const sessionId = getActiveTerminalSessionId();
+    if (sessionId)
+        return `agent-${sessionId.slice(0, 8)}-`;
+    return 'agent-';
+}
+/**
+ * Get terminal-scoped shared context filename, or shared 'shared-context.json' if no session active.
+ */
+function getSharedContextFilename() {
+    const sessionId = getActiveTerminalSessionId();
+    if (sessionId)
+        return `shared-context-${sessionId.slice(0, 8)}.json`;
+    return 'shared-context.json';
+}
+/**
+ * TeamCheckpointer handles persistence for multi-agent teams
+ */
+export class TeamCheckpointer {
+    sessionsPath;
+    constructor(sessionsPath) {
+        this.sessionsPath = sessionsPath;
+    }
+    /**
+     * Get the session directory for a project
+     */
+    getProjectDir(projectId) {
+        if (projectId === null) {
+            return path.join(this.sessionsPath, 'global');
+        }
+        return path.join(this.sessionsPath, `project-${String(projectId)}`);
+    }
+    /**
+     * Get the team metadata file path (terminal-scoped when multi-terminal active)
+     */
+    getTeamFilePath(projectId) {
+        return path.join(this.getProjectDir(projectId), getTeamFilename());
+    }
+    /**
+     * Get the agent state file path (terminal-scoped when multi-terminal active)
+     */
+    getAgentFilePath(projectId, agentId) {
+        return path.join(this.getProjectDir(projectId), `${getAgentFilePrefix()}${agentId}.json`);
+    }
+    /**
+     * Get the shared context file path (terminal-scoped when multi-terminal active)
+     */
+    getSharedContextPath(projectId) {
+        return path.join(this.getProjectDir(projectId), getSharedContextFilename());
+    }
+    /**
+     * Get the artifacts directory path
+     */
+    getArtifactsPath(projectId) {
+        return path.join(this.getProjectDir(projectId), ARTIFACTS_DIR);
+    }
+    /**
+     * Check if a team exists for THIS terminal's project.
+     * Only checks this terminal's scoped file — never cross-terminal.
+     */
+    hasTeam(projectId) {
+        return fs.existsSync(this.getTeamFilePath(projectId));
+    }
+    /**
+     * Save team state
+     */
+    saveTeam(projectId, team) {
+        const projectDir = this.getProjectDir(projectId);
+        // Ensure directory exists
+        if (!fs.existsSync(projectDir)) {
+            fs.mkdirSync(projectDir, { recursive: true });
+        }
+        const serialized = team.serialize();
+        // Save team metadata
+        const teamPath = this.getTeamFilePath(projectId);
+        fs.writeFileSync(teamPath, JSON.stringify(serialized.metadata, null, 2), 'utf-8');
+        // Save each agent's state separately
+        for (const agent of serialized.agents) {
+            const agentPath = this.getAgentFilePath(projectId, agent.id);
+            fs.writeFileSync(agentPath, JSON.stringify(agent, null, 2), 'utf-8');
+        }
+        // Clean up old agent files that are no longer in the team
+        this.cleanupOldAgentFiles(projectId, serialized.metadata.agentIds);
+    }
+    /**
+     * Load team state for THIS terminal.
+     * Only loads this terminal's scoped files. Never cross-terminal.
+     * For cross-terminal loading, use loadTeamByPrefix().
+     */
+    loadTeam(projectId, agentFactory, onEvent) {
+        const teamPath = this.getTeamFilePath(projectId);
+        if (!fs.existsSync(teamPath))
+            return null;
+        return this.loadTeamFromPath(projectId, teamPath, null, agentFactory, onEvent);
+    }
+    /**
+     * Load team state for a SPECIFIC terminal prefix (cross-terminal resume).
+     * Used when the user explicitly picks another terminal's session to resume.
+     */
+    loadTeamByPrefix(projectId, terminalPrefix, agentFactory, onEvent) {
+        const projectDir = this.getProjectDir(projectId);
+        const teamPath = path.join(projectDir, `team-${terminalPrefix}.json`);
+        if (!fs.existsSync(teamPath)) {
+            return null;
+        }
+        return this.loadTeamFromPath(projectId, teamPath, terminalPrefix, agentFactory, onEvent);
+    }
+    /**
+     * Get the agent count from a team file for a specific terminal prefix.
+     * Lightweight — reads only metadata, doesn't load agents.
+     * Returns 0 if no team file exists (default agent only).
+     */
+    getTeamAgentCountByPrefix(projectId, terminalPrefix) {
+        const projectDir = this.getProjectDir(projectId);
+        const teamPath = path.join(projectDir, `team-${terminalPrefix}.json`);
+        if (!fs.existsSync(teamPath))
+            return 0;
+        try {
+            const content = fs.readFileSync(teamPath, 'utf-8');
+            const metadata = JSON.parse(content);
+            return metadata.agentIds.length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * Internal: load team from a specific file path with optional terminal prefix for agent files.
+     */
+    loadTeamFromPath(projectId, teamPath, terminalPrefix, agentFactory, onEvent) {
+        try {
+            // Load team metadata
+            const metadataContent = fs.readFileSync(teamPath, 'utf-8');
+            const metadata = JSON.parse(metadataContent);
+            // Load each agent's state
+            const agents = [];
+            const projectDir = this.getProjectDir(projectId);
+            for (const agentId of metadata.agentIds) {
+                // Try paths in order: explicit prefix → this terminal
+                const explicitPath = terminalPrefix
+                    ? path.join(projectDir, `agent-${terminalPrefix}-${agentId}.json`)
+                    : null;
+                const ownPath = this.getAgentFilePath(projectId, agentId);
+                let loadedPath = null;
+                if (explicitPath && fs.existsSync(explicitPath)) {
+                    loadedPath = explicitPath;
+                }
+                else if (fs.existsSync(ownPath)) {
+                    loadedPath = ownPath;
+                }
+                if (loadedPath) {
+                    const agentContent = fs.readFileSync(loadedPath, 'utf-8');
+                    const agentData = JSON.parse(agentContent);
+                    agents.push(agentData);
+                }
+            }
+            const serialized = { metadata, agents };
+            // Load shared context if it exists
+            const sharedContext = this.loadSharedContext(projectId) ?? undefined;
+            // Load artifact store
+            const artifactStore = this.getArtifactStore(projectId);
+            // Restore the team with shared context and artifact store
+            return AgentTeam.restore(serialized, agentFactory, onEvent, {
+                sharedContext,
+                artifactStore,
+            });
+        }
+        catch {
+            // If loading fails, return null
+            return null;
+        }
+    }
+    /**
+     * Save a single agent's state (for incremental updates)
+     */
+    saveAgent(projectId, agentId, agent) {
+        const projectDir = this.getProjectDir(projectId);
+        // Ensure directory exists
+        if (!fs.existsSync(projectDir)) {
+            fs.mkdirSync(projectDir, { recursive: true });
+        }
+        const agentPath = this.getAgentFilePath(projectId, agentId);
+        fs.writeFileSync(agentPath, JSON.stringify(agent, null, 2), 'utf-8');
+    }
+    /**
+     * Delete team data for a project
+     */
+    deleteTeam(projectId) {
+        const teamPath = this.getTeamFilePath(projectId);
+        if (!fs.existsSync(teamPath)) {
+            return false;
+        }
+        try {
+            // Load metadata to get agent IDs
+            const metadataContent = fs.readFileSync(teamPath, 'utf-8');
+            const metadata = JSON.parse(metadataContent);
+            // Delete agent files
+            for (const agentId of metadata.agentIds) {
+                const agentPath = this.getAgentFilePath(projectId, agentId);
+                if (fs.existsSync(agentPath)) {
+                    fs.unlinkSync(agentPath);
+                }
+            }
+            // Delete team file
+            fs.unlinkSync(teamPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Claim team files from another terminal by renaming them to this terminal's prefix.
+     * Renames: team-{from}.json, agent-{from}-*.json, shared-context-{from}.json
+     */
+    claimTeamFiles(projectId, fromPrefix, toPrefix) {
+        const projectDir = this.getProjectDir(projectId);
+        if (!fs.existsSync(projectDir))
+            return false;
+        try {
+            const files = fs.readdirSync(projectDir);
+            for (const file of files) {
+                // team-{from}.json → team-{to}.json
+                if (file === `team-${fromPrefix}.json`) {
+                    fs.renameSync(path.join(projectDir, file), path.join(projectDir, `team-${toPrefix}.json`));
+                    continue;
+                }
+                // agent-{from}-{id}.json → agent-{to}-{id}.json
+                if (file.startsWith(`agent-${fromPrefix}-`) && file.endsWith('.json')) {
+                    const agentId = file.slice(`agent-${fromPrefix}-`.length, -'.json'.length);
+                    fs.renameSync(path.join(projectDir, file), path.join(projectDir, `agent-${toPrefix}-${agentId}.json`));
+                    continue;
+                }
+                // shared-context-{from}.json → shared-context-{to}.json
+                if (file === `shared-context-${fromPrefix}.json`) {
+                    fs.renameSync(path.join(projectDir, file), path.join(projectDir, `shared-context-${toPrefix}.json`));
+                    continue;
+                }
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Shared Context Persistence
+    // ---------------------------------------------------------------------------
+    /**
+     * Check if shared context exists for this project
+     */
+    hasSharedContext(projectId) {
+        const contextPath = this.getSharedContextPath(projectId);
+        return fs.existsSync(contextPath);
+    }
+    /**
+     * Save shared context
+     */
+    saveSharedContext(projectId, context) {
+        const projectDir = this.getProjectDir(projectId);
+        // Ensure directory exists
+        if (!fs.existsSync(projectDir)) {
+            fs.mkdirSync(projectDir, { recursive: true });
+        }
+        const serialized = context.serialize();
+        const contextPath = this.getSharedContextPath(projectId);
+        fs.writeFileSync(contextPath, JSON.stringify(serialized, null, 2), 'utf-8');
+    }
+    /**
+     * Load shared context
+     */
+    loadSharedContext(projectId) {
+        const contextPath = this.getSharedContextPath(projectId);
+        if (!fs.existsSync(contextPath)) {
+            return null;
+        }
+        try {
+            const content = fs.readFileSync(contextPath, 'utf-8');
+            const serialized = JSON.parse(content);
+            return SharedContextManager.fromSerialized(serialized);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Delete shared context
+     */
+    deleteSharedContext(projectId) {
+        const contextPath = this.getSharedContextPath(projectId);
+        if (!fs.existsSync(contextPath)) {
+            return false;
+        }
+        try {
+            fs.unlinkSync(contextPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Artifact Store Management
+    // ---------------------------------------------------------------------------
+    /**
+     * Get artifact store for a project
+     * The ArtifactStore handles its own persistence
+     */
+    getArtifactStore(projectId) {
+        const artifactsPath = this.getArtifactsPath(projectId);
+        const store = new ArtifactStore(artifactsPath);
+        store.load(); // Load existing artifacts
+        return store;
+    }
+    /**
+     * Check if artifacts exist for this project
+     */
+    hasArtifacts(projectId) {
+        const artifactsPath = this.getArtifactsPath(projectId);
+        return fs.existsSync(artifactsPath);
+    }
+    /**
+     * Delete all artifacts for a project
+     */
+    deleteArtifacts(projectId) {
+        const artifactsPath = this.getArtifactsPath(projectId);
+        if (!fs.existsSync(artifactsPath)) {
+            return false;
+        }
+        try {
+            // Delete all files in artifacts directory
+            const files = fs.readdirSync(artifactsPath);
+            for (const file of files) {
+                fs.unlinkSync(path.join(artifactsPath, file));
+            }
+            // Delete the directory
+            fs.rmdirSync(artifactsPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Cleanup Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Clean up agent files that are no longer in the team
+     */
+    cleanupOldAgentFiles(projectId, currentAgentIds) {
+        const projectDir = this.getProjectDir(projectId);
+        if (!fs.existsSync(projectDir)) {
+            return;
+        }
+        const prefix = getAgentFilePrefix();
+        try {
+            const files = fs.readdirSync(projectDir);
+            for (const file of files) {
+                if (file.startsWith(prefix) && file.endsWith('.json')) {
+                    const agentId = file.slice(prefix.length, -5); // Remove prefix and .json
+                    if (!currentAgentIds.includes(agentId)) {
+                        fs.unlinkSync(path.join(projectDir, file));
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    /**
+     * List all projects that have team data.
+     */
+    listProjectsWithTeams() {
+        const projectIds = [];
+        if (!fs.existsSync(this.sessionsPath)) {
+            return projectIds;
+        }
+        try {
+            const entries = fs.readdirSync(this.sessionsPath);
+            for (const entry of entries) {
+                if (entry.startsWith('project-')) {
+                    const idStr = entry.slice('project-'.length);
+                    const id = parseInt(idStr, 10);
+                    if (isNaN(id))
+                        continue;
+                    // Check for any team file (terminal-scoped or legacy)
+                    const dirPath = path.join(this.sessionsPath, entry);
+                    const files = fs.readdirSync(dirPath);
+                    const hasTeamFile = files.some(f => f.startsWith('team') && f.endsWith('.json'));
+                    if (hasTeamFile) {
+                        projectIds.push(id);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        return projectIds;
+    }
+    /**
+     * Get team metadata without loading the full team.
+     */
+    getTeamMetadata(projectId) {
+        const teamPath = this.getTeamFilePath(projectId);
+        if (!fs.existsSync(teamPath))
+            return null;
+        try {
+            const content = fs.readFileSync(teamPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Get the default sessions path
+ */
+export function getSessionsPath() {
+    const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? '.';
+    return path.join(homeDir, '.compilr-dev', 'sessions');
+}
+/**
+ * Singleton instance
+ */
+let checkpointerInstance = null;
+/**
+ * Get the shared TeamCheckpointer instance
+ */
+export function getTeamCheckpointer() {
+    if (!checkpointerInstance) {
+        checkpointerInstance = new TeamCheckpointer(getSessionsPath());
+    }
+    return checkpointerInstance;
+}

package/dist/multi-agent/collision-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Agent ID Collision Prevention
+ *
+ * When multiple terminals work on the same project, they may try to add
+ * agents with the same ID (e.g., both run `/add pm`). This module detects
+ * and resolves such collisions by querying the session registry for agent
+ * IDs already in use by other terminals.
+ */
+/**
+ * Check if an agent ID is in use by another terminal and resolve collisions.
+ * Returns the original ID if available, or a suffixed variant (e.g., "pm_2").
+ */
+export declare function resolveAgentIdCollision(requestedId: string, localTeamIds: string[], globalAgentIds: string[]): {
+    id: string;
+    wasCollision: boolean;
+};

package/dist/multi-agent/collision-utils.js

@@ -0,0 +1,28 @@
+/**
+ * Agent ID Collision Prevention
+ *
+ * When multiple terminals work on the same project, they may try to add
+ * agents with the same ID (e.g., both run `/add pm`). This module detects
+ * and resolves such collisions by querying the session registry for agent
+ * IDs already in use by other terminals.
+ */
+import * as crypto from 'node:crypto';
+/**
+ * Check if an agent ID is in use by another terminal and resolve collisions.
+ * Returns the original ID if available, or a suffixed variant (e.g., "pm_2").
+ */
+export function resolveAgentIdCollision(requestedId, localTeamIds, globalAgentIds) {
+    if (!globalAgentIds.includes(requestedId)) {
+        return { id: requestedId, wasCollision: false };
+    }
+    // Try suffixes: pm_2, pm_3, etc.
+    for (let i = 2; i <= 10; i++) {
+        const candidate = `${requestedId}_${String(i)}`;
+        if (!localTeamIds.includes(candidate) && !globalAgentIds.includes(candidate)) {
+            return { id: candidate, wasCollision: true };
+        }
+    }
+    // Fallback: UUID suffix
+    const fallback = `${requestedId}_${crypto.randomUUID().slice(0, 4)}`;
+    return { id: fallback, wasCollision: true };
+}

package/dist/multi-agent/context-resolver.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ContextResolver - Resolve $agent mentions to actual content
+ *
+ * Resolution strategy:
+ * 1. Check for explicit artifact reference in context hint
+ * 2. Search artifacts by name/content matching context hint
+ * 3. Fall back to recent conversation history
+ *
+ * Token budgets:
+ * - Single mention: 2000 tokens max
+ * - Multiple mentions: 3000 tokens total, split among mentions
+ */
+import type { AgentTeam } from './team.js';
+import type { ArtifactStore } from './artifacts.js';
+import type { ParsedMention } from './mention-parser.js';
+/**
+ * Resolution source type
+ */
+export type ResolutionSource = 'artifact' | 'history' | 'decision' | 'not_found';
+/**
+ * Resolved mention with content
+ */
+export interface ResolvedMention {
+    /** Original mention */
+    mention: ParsedMention;
+    /** Resolution status */
+    resolved: boolean;
+    /** Source of resolution */
+    source: ResolutionSource;
+    /** Source name (artifact name, "recent history", etc.) */
+    sourceName: string;
+    /** Resolved content to inject */
+    content: string;
+    /** Approximate token count */
+    tokenCount: number;
+}
+/**
+ * Options for resolution
+ */
+export interface ResolveOptions {
+    /** Max tokens per mention (default: 2000) */
+    maxTokensPerMention?: number;
+    /** Max total tokens for all mentions (default: 3000) */
+    maxTotalTokens?: number;
+    /** Include artifact content (not just summary) */
+    includeFullArtifact?: boolean;
+    /** Max history messages to search */
+    maxHistoryMessages?: number;
+}
+/**
+ * Resolve mentions to actual content
+ */
+export declare class ContextResolver {
+    private readonly team;
+    private readonly artifactStore;
+    constructor(team: AgentTeam, artifactStore: ArtifactStore);
+    /**
+     * Resolve multiple mentions
+     */
+    resolveAll(mentions: ParsedMention[], options?: ResolveOptions): Map<string, ResolvedMention>;
+    /**
+     * Resolve a single mention
+     */
+    resolveMention(mention: ParsedMention, options?: ResolveOptions): ResolvedMention;
+    /**
+     * Resolve from artifacts
+     */
+    private resolveFromArtifacts;
+    /**
+     * Resolve from conversation history
+     */
+    private resolveFromHistory;
+    /**
+     * Extract relevant content from messages based on context hint
+     */
+    private extractRelevantContent;
+    /**
+     * Format a message for injection
+     */
+    private formatMessage;
+    /**
+     * Format artifact with full content
+     */
+    private formatArtifactFull;
+    /**
+     * Format artifact with summary only
+     */
+    private formatArtifactSummary;
+    /**
+     * Truncate content to approximate token count
+     */
+    private truncateToTokens;
+}
+/**
+ * Build a context map from resolved mentions
+ */
+export declare function buildContextMap(resolved: Map<string, ResolvedMention>): Map<string, string>;