@compilr-dev/cli 0.5.0 → 0.5.1

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

@@ -0,0 +1,671 @@
+/**
+ * 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,
+        };
+    }
+}