@compilr-dev/cli 0.6.1 → 0.6.3

package/dist/multi-agent/shared-context.js

@@ -1,671 +0,0 @@
-/**
- * SharedContextManager - Shared context across team agents
- *
- * Provides a lightweight, token-budgeted context layer that's injected
- * into all agent system prompts. Enables cross-agent knowledge sharing.
- *
- * Token Budget: ~4000 tokens (2% of 200K context)
- */
-// =============================================================================
-// Constants
-// =============================================================================
-const DEFAULT_TOKEN_BUDGET = 4000;
-const MAX_DECISIONS = 10;
-const MAX_DECISION_LENGTH = 100;
-const MAX_MEMORY_SUMMARY_LENGTH = 2000;
-const MAX_ACTIVITY_ITEMS = 5;
-// Token counting via tiktoken
-import { estimateTokens } from '../utils/token-tracker.js';
-// =============================================================================
-// SharedContextManager
-// =============================================================================
-/**
- * Manages shared context across all team agents
- */
-export class SharedContextManager {
-    project;
-    team;
-    teamRoster = []; // Full roster for team awareness
-    recentActivity = []; // Activity feed for team awareness
-    decisions = [];
-    artifactIndex = [];
-    tokenBudget;
-    updatedAt = new Date();
-    constructor(options) {
-        this.project = {
-            id: options?.project?.id ?? null,
-            name: options?.project?.name ?? 'Unknown Project',
-            path: options?.project?.path ?? process.cwd(),
-            memorySummary: options?.project?.memorySummary ?? '',
-        };
-        this.team = {
-            agents: ['default'],
-            activeAgent: 'default',
-        };
-        this.tokenBudget = {
-            max: options?.maxTokens ?? DEFAULT_TOKEN_BUDGET,
-            current: 0,
-        };
-        this.updateTokenCount();
-    }
-    // ---------------------------------------------------------------------------
-    // Project Management
-    // ---------------------------------------------------------------------------
-    /**
-     * Update project information
-     */
-    setProject(project) {
-        if (project.id !== undefined)
-            this.project.id = project.id;
-        if (project.name !== undefined)
-            this.project.name = project.name;
-        if (project.path !== undefined)
-            this.project.path = project.path;
-        if (project.memorySummary !== undefined) {
-            // Truncate if too long
-            this.project.memorySummary = project.memorySummary.slice(0, MAX_MEMORY_SUMMARY_LENGTH);
-        }
-        this.touch();
-    }
-    /**
-     * Get project information
-     */
-    getProject() {
-        return { ...this.project };
-    }
-    // ---------------------------------------------------------------------------
-    // Team Management
-    // ---------------------------------------------------------------------------
-    /**
-     * Update team roster
-     */
-    setTeam(agents, activeAgent) {
-        this.team.agents = [...agents];
-        if (activeAgent && agents.includes(activeAgent)) {
-            this.team.activeAgent = activeAgent;
-        }
-        this.touch();
-    }
-    /**
-     * Set active agent
-     */
-    setActiveAgent(agentId) {
-        if (this.team.agents.includes(agentId)) {
-            this.team.activeAgent = agentId;
-            this.touch();
-        }
-    }
-    /**
-     * Add an agent to the team
-     */
-    addAgent(agentId) {
-        if (!this.team.agents.includes(agentId)) {
-            this.team.agents.push(agentId);
-            this.touch();
-        }
-    }
-    /**
-     * Remove an agent from the team
-     */
-    removeAgent(agentId) {
-        const index = this.team.agents.indexOf(agentId);
-        if (index !== -1) {
-            this.team.agents.splice(index, 1);
-            // If active agent was removed, switch to default
-            if (this.team.activeAgent === agentId) {
-                this.team.activeAgent = 'default';
-            }
-            this.touch();
-        }
-    }
-    /**
-     * Get team roster
-     */
-    getTeam() {
-        return { ...this.team, agents: [...this.team.agents] };
-    }
-    // ---------------------------------------------------------------------------
-    // Team Roster (for Team Awareness)
-    // ---------------------------------------------------------------------------
-    /**
-     * Update the full team roster with agent details
-     * Called when team composition changes
-     */
-    updateTeamRoster(entries) {
-        this.teamRoster = entries.map(entry => ({ ...entry }));
-        this.touch();
-    }
-    /**
-     * Set active agent in the roster
-     * Called on agent switch
-     */
-    setRosterActiveAgent(agentId) {
-        for (const entry of this.teamRoster) {
-            entry.isActive = entry.id === agentId;
-        }
-        // Also update the simple team info
-        if (this.team.agents.includes(agentId)) {
-            this.team.activeAgent = agentId;
-        }
-        this.touch();
-    }
-    /**
-     * Get the full team roster
-     */
-    getTeamRoster() {
-        return this.teamRoster.map(entry => ({ ...entry }));
-    }
-    /**
-     * Check if team roster is available (more than just default agent)
-     */
-    hasTeamRoster() {
-        return this.teamRoster.length > 1;
-    }
-    /**
-     * Update task counts for an agent
-     * Called by REPL when todo list or work items change
-     */
-    updateAgentTaskCounts(agentId, todoCount, workItemCount) {
-        const entry = this.teamRoster.find(e => e.id === agentId);
-        if (entry) {
-            entry.todoCount = todoCount;
-            entry.workItemCount = workItemCount;
-            this.touch();
-        }
-    }
-    /**
-     * Update task counts for all agents
-     * Called with a map of agentId -> { todoCount, workItemCount }
-     */
-    updateAllAgentTaskCounts(counts) {
-        for (const entry of this.teamRoster) {
-            if (entry.id in counts) {
-                const agentCounts = counts[entry.id];
-                entry.todoCount = agentCounts.todoCount;
-                entry.workItemCount = agentCounts.workItemCount;
-            }
-            else {
-                entry.todoCount = 0;
-                entry.workItemCount = 0;
-            }
-        }
-        this.touch();
-    }
-    // ---------------------------------------------------------------------------
-    // Activity Feed (for Team Awareness)
-    // ---------------------------------------------------------------------------
-    /**
-     * Record a team activity
-     * Called when significant actions occur (artifact created, task completed, etc.)
-     */
-    recordActivity(activity) {
-        const newActivity = {
-            ...activity,
-            timestamp: new Date(),
-        };
-        this.recentActivity.unshift(newActivity);
-        // Keep only MAX_ACTIVITY_ITEMS
-        if (this.recentActivity.length > MAX_ACTIVITY_ITEMS) {
-            this.recentActivity = this.recentActivity.slice(0, MAX_ACTIVITY_ITEMS);
-        }
-        this.touch();
-    }
-    /**
-     * Get recent activity
-     */
-    getRecentActivity() {
-        return this.recentActivity.map(a => ({ ...a }));
-    }
-    /**
-     * Check if there is recent activity to display
-     */
-    hasRecentActivity() {
-        return this.recentActivity.length > 0;
-    }
-    /**
-     * Clear activity feed
-     */
-    clearActivity() {
-        this.recentActivity = [];
-        this.touch();
-    }
-    // ---------------------------------------------------------------------------
-    // Decision Management
-    // ---------------------------------------------------------------------------
-    /**
-     * Add a decision to the shared context
-     */
-    addDecision(decision) {
-        const id = `dec-${String(Date.now())}-${Math.random().toString(36).slice(2, 8)}`;
-        // Truncate summary if too long
-        const summary = decision.summary.slice(0, MAX_DECISION_LENGTH);
-        const newDecision = {
-            id,
-            agent: decision.agent,
-            summary,
-            reasoning: decision.reasoning,
-            timestamp: new Date(),
-        };
-        this.decisions.unshift(newDecision);
-        // Keep only MAX_DECISIONS
-        if (this.decisions.length > MAX_DECISIONS) {
-            this.decisions = this.decisions.slice(0, MAX_DECISIONS);
-        }
-        this.touch();
-        return id;
-    }
-    /**
-     * Update/supersede a decision
-     */
-    supersededDecision(oldId, newDecision) {
-        // Mark old decision as superseded
-        const old = this.decisions.find(d => d.id === oldId);
-        const newId = this.addDecision(newDecision);
-        if (old) {
-            old.supersededBy = newId;
-        }
-        return newId;
-    }
-    /**
-     * Get all decisions (active only by default)
-     */
-    getDecisions(includeSuperseded = false) {
-        if (includeSuperseded) {
-            return [...this.decisions];
-        }
-        return this.decisions.filter(d => !d.supersededBy);
-    }
-    /**
-     * Clear all decisions
-     */
-    clearDecisions() {
-        this.decisions = [];
-        this.touch();
-    }
-    // ---------------------------------------------------------------------------
-    // Artifact Index Management
-    // ---------------------------------------------------------------------------
-    /**
-     * Update the artifact index (called by ArtifactStore)
-     */
-    setArtifactIndex(index) {
-        this.artifactIndex = [...index];
-        this.touch();
-    }
-    /**
-     * Add an artifact to the index
-     */
-    addArtifactToIndex(artifact) {
-        // Remove existing with same ID
-        this.artifactIndex = this.artifactIndex.filter(a => a.id !== artifact.id);
-        this.artifactIndex.unshift(artifact);
-        this.touch();
-    }
-    /**
-     * Remove an artifact from the index
-     */
-    removeArtifactFromIndex(artifactId) {
-        this.artifactIndex = this.artifactIndex.filter(a => a.id !== artifactId);
-        this.touch();
-    }
-    /**
-     * Get artifact index
-     */
-    getArtifactIndex() {
-        return [...this.artifactIndex];
-    }
-    // ---------------------------------------------------------------------------
-    // Token Budget Management
-    // ---------------------------------------------------------------------------
-    /**
-     * Update token count based on current content
-     */
-    updateTokenCount() {
-        let tokens = 0;
-        // Project info
-        tokens += estimateTokens(this.project.name);
-        tokens += estimateTokens(this.project.path);
-        tokens += estimateTokens(this.project.memorySummary);
-        // Team info
-        tokens += estimateTokens(this.team.agents.join(', '));
-        // Decisions
-        for (const decision of this.decisions) {
-            tokens += estimateTokens(decision.summary);
-            if (decision.reasoning) {
-                tokens += estimateTokens(decision.reasoning);
-            }
-        }
-        // Artifact index
-        for (const artifact of this.artifactIndex) {
-            tokens += estimateTokens(artifact.name);
-            tokens += estimateTokens(artifact.summary);
-        }
-        this.tokenBudget.current = tokens;
-    }
-    /**
-     * Check if adding content would exceed budget
-     */
-    wouldExceedBudget(additionalTokens) {
-        return (this.tokenBudget.current + additionalTokens) > this.tokenBudget.max;
-    }
-    /**
-     * Get token budget status
-     */
-    getTokenBudget() {
-        return { ...this.tokenBudget };
-    }
-    /**
-     * Get utilization percentage
-     */
-    getUtilization() {
-        return Math.round((this.tokenBudget.current / this.tokenBudget.max) * 100);
-    }
-    // ---------------------------------------------------------------------------
-    // Context Formatting
-    // ---------------------------------------------------------------------------
-    /**
-     * Format shared context for injection into system prompt.
-     * @param options.excludeRoster - If true, omit the team roster (it will be injected via anchor instead)
-     */
-    format(options) {
-        const lines = [];
-        lines.push('## SHARED TEAM CONTEXT');
-        lines.push('');
-        // Project info
-        lines.push(`**Project:** ${this.project.name}`);
-        lines.push(`**Path:** ${this.project.path}`);
-        if (this.project.memorySummary) {
-            lines.push(`**Summary:** ${this.project.memorySummary}`);
-        }
-        lines.push('');
-        // Team roster — skip if excluded (will be injected via anchor for live updates)
-        if (!options?.excludeRoster) {
-            if (this.hasTeamRoster()) {
-                lines.push(this.formatTeamRoster());
-                lines.push('');
-            }
-            else {
-                // Fallback to simple team info
-                lines.push(`**Team:** ${this.team.agents.map(a => `$${a}`).join(', ')}`);
-                lines.push(`**Active:** $${this.team.activeAgent}`);
-                lines.push('');
-                // Team collaboration instructions (only if multiple agents)
-                if (this.team.agents.length > 1) {
-                    lines.push('**Team Collaboration:**');
-                    lines.push('- You are part of a multi-agent team. Each agent has a specialized role.');
-                    lines.push('- If a question or task seems better suited for another team member, suggest asking them.');
-                    lines.push('- Example: "This is more of an architecture question - you might want to ask $arch about this."');
-                    lines.push('- Reference artifacts created by other agents when relevant using $mention syntax.');
-                    lines.push('');
-                }
-            }
-        }
-        // Recent team activity (if any)
-        if (this.hasRecentActivity()) {
-            lines.push(this.formatRecentActivity());
-            lines.push('');
-        }
-        // Decisions
-        const activeDecisions = this.getDecisions(false);
-        if (activeDecisions.length > 0) {
-            lines.push('**Recent Decisions:**');
-            for (const decision of activeDecisions.slice(0, 5)) {
-                lines.push(`- [$${decision.agent}] ${decision.summary}`);
-            }
-            lines.push('');
-        }
-        // Artifacts
-        if (this.artifactIndex.length > 0) {
-            lines.push('**Available Artifacts:**');
-            for (const artifact of this.artifactIndex.slice(0, 10)) {
-                lines.push(`- "${artifact.name}" by $${artifact.agent} (${artifact.type})`);
-            }
-            lines.push('');
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Format team roster as a table for team awareness
-     */
-    formatTeamRoster() {
-        const lines = [];
-        // Find the active agent for personalized guidance
-        const activeEntry = this.teamRoster.find(e => e.isActive);
-        // Check if any agent has task counts to show
-        const showTaskCounts = this.teamRoster.some(e => (e.todoCount ?? 0) > 0 || (e.workItemCount ?? 0) > 0);
-        lines.push('### Your Team');
-        lines.push('');
-        if (showTaskCounts) {
-            lines.push('| Agent | Role | Tasks | Expertise |');
-            lines.push('|-------|------|-------|-----------|');
-        }
-        else {
-            lines.push('| Agent | Role | Expertise |');
-            lines.push('|-------|------|-----------|');
-        }
-        for (const entry of this.teamRoster) {
-            const marker = entry.isActive ? '→ ' : '  ';
-            const youMarker = entry.isActive ? ' ← YOU' : '';
-            // Show first 3 expertise keywords to keep it concise
-            const expertise = entry.expertise.slice(0, 3).join(', ');
-            if (showTaskCounts) {
-                // Format task counts
-                const todoCount = entry.todoCount ?? 0;
-                const workItemCount = entry.workItemCount ?? 0;
-                const taskParts = [];
-                if (todoCount > 0)
-                    taskParts.push(`${String(todoCount)} todo${todoCount > 1 ? 's' : ''}`);
-                if (workItemCount > 0)
-                    taskParts.push(`${String(workItemCount)} item${workItemCount > 1 ? 's' : ''}`);
-                const taskStr = taskParts.length > 0 ? taskParts.join(', ') : '-';
-                lines.push(`| ${marker}$${entry.id} ${entry.mascot} | ${entry.displayName} | ${taskStr} | ${expertise}${youMarker} |`);
-            }
-            else {
-                lines.push(`| ${marker}$${entry.id} ${entry.mascot} | ${entry.displayName} | ${expertise}${youMarker} |`);
-            }
-        }
-        lines.push('');
-        // Handoff guidance - dynamic based on active agent and team
-        if (activeEntry) {
-            const yourExpertise = activeEntry.expertise.slice(0, 3).join(', ');
-            lines.push(`**Your expertise:** ${yourExpertise}`);
-            lines.push('');
-        }
-        lines.push('**Collaboration Guidelines:**');
-        lines.push('- If a task falls outside your expertise, suggest the appropriate specialist');
-        lines.push('- Example: "This would be better handled by $arch for architecture decisions"');
-        lines.push('- Do NOT attempt tasks far outside your expertise - it\'s better to suggest a handoff');
-        // Add specific handoff suggestions based on teammates
-        const handoffSuggestions = this.buildHandoffSuggestions(activeEntry?.id);
-        if (handoffSuggestions.length > 0) {
-            lines.push('');
-            lines.push('**When to involve teammates:**');
-            for (const suggestion of handoffSuggestions) {
-                lines.push(`- ${suggestion}`);
-            }
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Build handoff suggestions based on team composition
-     */
-    buildHandoffSuggestions(activeAgentId) {
-        const suggestions = [];
-        for (const entry of this.teamRoster) {
-            // Skip the active agent
-            if (entry.id === activeAgentId)
-                continue;
-            // Build suggestion based on role
-            const role = entry.role;
-            switch (role) {
-                case 'arch':
-                    suggestions.push(`Architecture/design questions → "Let me get $${entry.id}'s input on the design"`);
-                    break;
-                case 'pm':
-                    suggestions.push(`Planning/prioritization → "$${entry.id} can help with task breakdown"`);
-                    break;
-                case 'qa':
-                    suggestions.push(`Testing/quality concerns → "$${entry.id} should review the test strategy"`);
-                    break;
-                case 'dev':
-                    suggestions.push(`Implementation details → "$${entry.id} can handle the coding"`);
-                    break;
-                case 'ops':
-                    suggestions.push(`Deployment/infrastructure → "$${entry.id} can advise on CI/CD"`);
-                    break;
-                case 'docs':
-                    suggestions.push(`Documentation needs → "$${entry.id} can write the user docs"`);
-                    break;
-                case 'ba':
-                    suggestions.push(`Requirements clarity → "$${entry.id} can help clarify the business need"`);
-                    break;
-                default:
-                    // For default or custom agents, use their display name
-                    if (entry.expertise.length > 0) {
-                        suggestions.push(`${entry.expertise[0]} → "$${entry.id} specializes in this"`);
-                    }
-            }
-        }
-        // Limit to 5 suggestions to keep it concise
-        return suggestions.slice(0, 5);
-    }
-    /**
-     * Format recent activity feed for team awareness
-     */
-    formatRecentActivity() {
-        const lines = [];
-        lines.push('### Recent Team Activity');
-        lines.push('');
-        for (const activity of this.recentActivity) {
-            const ago = this.formatTimeAgo(activity.timestamp);
-            lines.push(`- [${ago}] $${activity.agentId} ${activity.summary}`);
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Format a timestamp as "Xm ago", "Xh ago", etc.
-     */
-    formatTimeAgo(timestamp) {
-        const now = Date.now();
-        const diff = now - timestamp.getTime();
-        const minutes = Math.floor(diff / 60000);
-        const hours = Math.floor(diff / 3600000);
-        if (minutes < 1) {
-            return 'just now';
-        }
-        else if (minutes < 60) {
-            return `${String(minutes)}m ago`;
-        }
-        else if (hours < 24) {
-            return `${String(hours)}h ago`;
-        }
-        else {
-            const days = Math.floor(hours / 24);
-            return `${String(days)}d ago`;
-        }
-    }
-    /**
-     * Format a compact version (for token-constrained situations)
-     */
-    formatCompact() {
-        const parts = [];
-        parts.push(`Project: ${this.project.name}`);
-        parts.push(`Team: ${this.team.agents.map(a => `$${a}`).join(', ')}`);
-        const activeDecisions = this.getDecisions(false);
-        if (activeDecisions.length > 0) {
-            parts.push(`Decisions: ${String(activeDecisions.length)}`);
-        }
-        if (this.artifactIndex.length > 0) {
-            parts.push(`Artifacts: ${this.artifactIndex.map(a => `"${a.name}"`).join(', ')}`);
-        }
-        return parts.join(' | ');
-    }
-    // ---------------------------------------------------------------------------
-    // Persistence
-    // ---------------------------------------------------------------------------
-    /**
-     * Mark as updated
-     */
-    touch() {
-        this.updatedAt = new Date();
-        this.updateTokenCount();
-    }
-    /**
-     * Serialize for persistence
-     */
-    serialize() {
-        return {
-            version: 1,
-            project: {
-                id: this.project.id,
-                name: this.project.name,
-                path: this.project.path,
-                memorySummary: this.project.memorySummary,
-            },
-            decisions: this.decisions.map(d => ({
-                id: d.id,
-                agent: d.agent,
-                summary: d.summary,
-                reasoning: d.reasoning,
-                timestamp: d.timestamp.toISOString(),
-                supersededBy: d.supersededBy,
-            })),
-            artifactIndex: this.artifactIndex.map(a => ({
-                id: a.id,
-                name: a.name,
-                agent: a.agent,
-                type: a.type,
-                summary: a.summary,
-                updatedAt: a.updatedAt.toISOString(),
-            })),
-            updatedAt: this.updatedAt.toISOString(),
-        };
-    }
-    /**
-     * Restore from serialized data
-     */
-    static fromSerialized(data) {
-        const manager = new SharedContextManager({
-            project: {
-                id: data.project.id,
-                name: data.project.name,
-                path: data.project.path,
-                memorySummary: data.project.memorySummary,
-            },
-        });
-        // Restore decisions
-        manager.decisions = data.decisions.map(d => ({
-            id: d.id,
-            agent: d.agent,
-            summary: d.summary,
-            reasoning: d.reasoning,
-            timestamp: new Date(d.timestamp),
-            supersededBy: d.supersededBy,
-        }));
-        // Restore artifact index
-        manager.artifactIndex = data.artifactIndex.map(a => ({
-            id: a.id,
-            name: a.name,
-            agent: a.agent,
-            type: a.type,
-            summary: a.summary,
-            updatedAt: new Date(a.updatedAt),
-        }));
-        manager.updatedAt = new Date(data.updatedAt);
-        manager.updateTokenCount();
-        return manager;
-    }
-    /**
-     * Get the full context object
-     */
-    getContext() {
-        return {
-            project: this.getProject(),
-            team: this.getTeam(),
-            decisions: this.getDecisions(),
-            artifactIndex: this.getArtifactIndex(),
-            tokenBudget: this.getTokenBudget(),
-            updatedAt: this.updatedAt,
-        };
-    }
-}