@compilr-dev/sdk 0.1.28 → 0.2.0

package/dist/team/team.js

@@ -0,0 +1,615 @@
+/**
+ * AgentTeam - Multi-agent orchestration
+ *
+ * Manages a team of persistent agents:
+ * - Agent switching ($name prefix)
+ * - Isolated contexts per agent
+ * - Team-level persistence
+ * - Event notifications
+ */
+import { TeamAgent } from './team-agent.js';
+import { ROLE_EXPERTISE } from './types.js';
+import { SharedContextManager } from './shared-context.js';
+import { ArtifactStore } from './artifacts.js';
+import { resolveAgentIdCollision } from './collision-utils.js';
+/**
+ * AgentTeam orchestrates multiple persistent agents
+ */
+export class AgentTeam {
+    /**
+     * Team name
+     */
+    name;
+    /**
+     * Map of agent ID to TeamAgent
+     */
+    agents = new Map();
+    /**
+     * Currently active agent ID
+     */
+    _activeAgentId = 'default';
+    /**
+     * Coordinator agent ID (optional)
+     */
+    _coordinatorId;
+    /**
+     * Factory for creating agents
+     */
+    agentFactory;
+    /**
+     * Event handler
+     */
+    onEvent;
+    /**
+     * Shared context manager for cross-agent knowledge sharing
+     */
+    _sharedContext;
+    /**
+     * Artifact store for team artifacts
+     */
+    _artifactStore;
+    /**
+     * Optional session registry for collision detection
+     */
+    _sessionRegistry;
+    /**
+     * Track handoff source: targetAgentId → sourceAgentId
+     * Used for one-hop prevention (agents that were handed a task
+     * cannot re-hand it off, except back to the coordinator)
+     */
+    _handedFrom = new Map();
+    /**
+     * Creation timestamp
+     */
+    createdAt = new Date();
+    /**
+     * Last updated timestamp
+     */
+    updatedAt = new Date();
+    constructor(config) {
+        this.name = config.name ?? 'Team';
+        this.agentFactory = config.agentFactory;
+        this.onEvent = config.onEvent;
+        this._sessionRegistry = config.sessionRegistry;
+        // Initialize shared context (use provided or create new)
+        this._sharedContext = config.sharedContext ?? new SharedContextManager();
+        // Initialize artifact store (use provided or create in-memory)
+        this._artifactStore = config.artifactStore ?? new ArtifactStore();
+        // Create default agent
+        const defaultAgent = TeamAgent.fromRole('default', 'default');
+        this.agents.set('default', defaultAgent);
+        // Add any initial agents
+        if (config.initialAgents) {
+            for (const agentConfig of config.initialAgents) {
+                if (agentConfig.id !== 'default') {
+                    this.agents.set(agentConfig.id, new TeamAgent(agentConfig));
+                }
+            }
+        }
+        // Update shared context with team roster (simple list)
+        this._sharedContext.setTeam(Array.from(this.agents.keys()), this._activeAgentId);
+        // Build full team roster for team awareness
+        this.updateTeamRoster();
+    }
+    /**
+     * Get the currently active agent ID
+     */
+    get activeAgentId() {
+        return this._activeAgentId;
+    }
+    /**
+     * Get the coordinator agent ID (if set)
+     */
+    get coordinatorId() {
+        return this._coordinatorId;
+    }
+    /**
+     * Get the shared context manager
+     */
+    get sharedContext() {
+        return this._sharedContext;
+    }
+    /**
+     * Get the artifact store
+     */
+    get artifactStore() {
+        return this._artifactStore;
+    }
+    /**
+     * Get the currently active TeamAgent
+     */
+    getActive() {
+        const agent = this.agents.get(this._activeAgentId);
+        if (!agent) {
+            // Fallback to default
+            const defaultAgent = this.agents.get('default');
+            if (!defaultAgent) {
+                throw new Error('Default agent not found - this should never happen');
+            }
+            return defaultAgent;
+        }
+        return agent;
+    }
+    /**
+     * Get the currently active Agent instance
+     * Returns null if not initialized
+     */
+    getActiveAgent() {
+        return this.getActive().agent;
+    }
+    /**
+     * Get a specific TeamAgent by ID
+     */
+    get(id) {
+        return this.agents.get(id);
+    }
+    /**
+     * Set the agent instance for the default TeamAgent
+     * Used when the agent is created before the team
+     */
+    setDefaultAgent(agent) {
+        const defaultTeamAgent = this.agents.get('default');
+        if (defaultTeamAgent) {
+            defaultTeamAgent.setAgent(agent);
+        }
+    }
+    /**
+     * Check if an agent exists in the team
+     */
+    has(id) {
+        return this.agents.has(id);
+    }
+    /**
+     * Get all agent IDs
+     */
+    getAgentIds() {
+        return Array.from(this.agents.keys());
+    }
+    /**
+     * Get all TeamAgents
+     */
+    getAll() {
+        return Array.from(this.agents.values());
+    }
+    /**
+     * Get team size (number of agents)
+     */
+    get size() {
+        return this.agents.size;
+    }
+    /**
+     * Add a new agent to the team
+     */
+    async addAgent(config) {
+        if (this.agents.has(config.id)) {
+            throw new Error(`Agent '${config.id}' already exists in team`);
+        }
+        const teamAgent = new TeamAgent(config);
+        this.agents.set(config.id, teamAgent);
+        // Initialize the agent with shared context
+        await teamAgent.initialize(this.agentFactory, this._sharedContext);
+        // Update shared context roster
+        this._sharedContext.addAgent(config.id);
+        // Update full team roster for team awareness
+        this.updateTeamRoster();
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:added', agentId: config.id });
+        return teamAgent;
+    }
+    /**
+     * Add an agent from a predefined role
+     * @param role - The predefined role
+     * @param id - Optional custom ID (defaults to role name)
+     * @param modelTier - Optional model tier override (defaults to role's default tier)
+     */
+    async addAgentFromRole(role, id, modelTier) {
+        let agentId = id ?? role;
+        // Cross-terminal collision check (if registry provided)
+        if (this._sessionRegistry) {
+            const globalIds = this._sessionRegistry.getGlobalAgentIds();
+            const localIds = Array.from(this.agents.keys());
+            const resolved = resolveAgentIdCollision(agentId, localIds, globalIds);
+            if (resolved.wasCollision) {
+                const originalId = agentId;
+                agentId = resolved.id;
+                this.emit({ type: 'agent:collision', originalId, agentId: resolved.id });
+            }
+        }
+        if (this.agents.has(agentId)) {
+            throw new Error(`Agent '${agentId}' already exists in team`);
+        }
+        const teamAgent = TeamAgent.fromRole(role, agentId, modelTier);
+        this.agents.set(agentId, teamAgent);
+        // Initialize the agent with shared context
+        await teamAgent.initialize(this.agentFactory, this._sharedContext);
+        // Update shared context roster
+        this._sharedContext.addAgent(agentId);
+        // Update full team roster for team awareness
+        this.updateTeamRoster();
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:added', agentId });
+        return teamAgent;
+    }
+    /**
+     * Add a custom agent from a CustomAgentDefinition
+     */
+    async addCustomAgent(def) {
+        let agentId = def.id;
+        // Cross-terminal collision check (if registry provided)
+        if (this._sessionRegistry) {
+            const globalIds = this._sessionRegistry.getGlobalAgentIds();
+            const localIds = Array.from(this.agents.keys());
+            const resolved = resolveAgentIdCollision(agentId, localIds, globalIds);
+            if (resolved.wasCollision) {
+                const originalId = agentId;
+                agentId = resolved.id;
+                def = { ...def, id: agentId };
+                this.emit({ type: 'agent:collision', originalId, agentId: resolved.id });
+            }
+        }
+        if (this.agents.has(agentId)) {
+            throw new Error(`Agent '${agentId}' already exists in team`);
+        }
+        const teamAgent = TeamAgent.fromCustomDefinition(def);
+        this.agents.set(agentId, teamAgent);
+        // Initialize the agent with shared context
+        await teamAgent.initialize(this.agentFactory, this._sharedContext);
+        // Update shared context roster
+        this._sharedContext.addAgent(def.id);
+        // Update full team roster for team awareness
+        this.updateTeamRoster();
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:added', agentId: def.id });
+        return teamAgent;
+    }
+    /**
+     * Remove an agent from the team
+     */
+    removeAgent(id) {
+        if (id === 'default') {
+            throw new Error('Cannot remove the default agent');
+        }
+        if (!this.agents.has(id)) {
+            return false;
+        }
+        // If removing active agent, switch to default
+        if (this._activeAgentId === id) {
+            this._activeAgentId = 'default';
+            this._sharedContext.setActiveAgent('default');
+        }
+        // If removing coordinator, clear coordinator
+        if (this._coordinatorId === id) {
+            this._coordinatorId = undefined;
+        }
+        this.agents.delete(id);
+        // Update shared context roster
+        this._sharedContext.removeAgent(id);
+        // Update full team roster for team awareness
+        this.updateTeamRoster();
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:removed', agentId: id });
+        return true;
+    }
+    /**
+     * Clear conversation history for all agents in the team
+     * Used by /reset command to start fresh
+     */
+    clearAllHistories() {
+        for (const agent of this.agents.values()) {
+            agent.clearHistory();
+        }
+        // Clear shared context activity feed
+        this._sharedContext.clearActivity();
+        this.updatedAt = new Date();
+        this.emit({ type: 'team:reset' });
+    }
+    /**
+     * Callback for checking in-progress tasks when switching agents
+     * Set by the consumer to provide task counts for warnings
+     */
+    _getInProgressTasksCallback;
+    /**
+     * Set the callback for getting in-progress tasks
+     * Used by consumer to integrate with todo list and work items
+     */
+    setInProgressTasksCallback(callback) {
+        this._getInProgressTasksCallback = callback;
+    }
+    /**
+     * Switch to a different agent
+     */
+    async switchTo(id) {
+        const agent = this.agents.get(id);
+        if (!agent) {
+            throw new Error(`Agent '${id}' not found in team`);
+        }
+        // Initialize if needed
+        if (!agent.isInitialized) {
+            await agent.initialize(this.agentFactory, this._sharedContext);
+        }
+        const previousId = this._activeAgentId;
+        // Check for in-progress tasks owned by the outgoing agent
+        if (previousId !== id && this._getInProgressTasksCallback) {
+            const inProgressTasks = this._getInProgressTasksCallback(previousId);
+            const hasTodos = inProgressTasks.todos.length > 0;
+            const hasWorkItems = inProgressTasks.workItems.length > 0;
+            if (hasTodos || hasWorkItems) {
+                this.emit({
+                    type: 'agent:switch_warning',
+                    agentId: id,
+                    previousAgentId: previousId,
+                    message: `Agent "${previousId}" has in-progress tasks: ${hasTodos ? `${String(inProgressTasks.todos.length)} todo(s)` : ''}${hasTodos && hasWorkItems ? ', ' : ''}${hasWorkItems ? `${String(inProgressTasks.workItems.length)} work item(s)` : ''}`,
+                });
+            }
+        }
+        this._activeAgentId = id;
+        this.updatedAt = new Date();
+        // Update shared context active agent
+        this._sharedContext.setActiveAgent(id);
+        // Update roster active agent for team awareness
+        this._sharedContext.setRosterActiveAgent(id);
+        this.emit({
+            type: 'agent:switched',
+            agentId: id,
+            previousAgentId: previousId,
+        });
+        return agent;
+    }
+    /**
+     * Set the coordinator agent
+     */
+    setCoordinator(id) {
+        if (id !== undefined && !this.agents.has(id)) {
+            throw new Error(`Agent '${id}' not found in team`);
+        }
+        this._coordinatorId = id;
+        this.updatedAt = new Date();
+    }
+    /**
+     * Check if an agent is the coordinator
+     * The default agent is considered coordinator if no explicit coordinator is set.
+     */
+    isCoordinator(id) {
+        if (this._coordinatorId !== undefined) {
+            return this._coordinatorId === id;
+        }
+        // If no coordinator explicitly set, default agent is the coordinator
+        return id === 'default';
+    }
+    /**
+     * Check if the active agent is the coordinator
+     * The default agent is considered coordinator if no explicit coordinator is set.
+     */
+    isActiveCoordinator() {
+        if (this._coordinatorId !== undefined) {
+            return this._coordinatorId === this._activeAgentId;
+        }
+        // If no coordinator explicitly set, default agent is the coordinator
+        return this._activeAgentId === 'default';
+    }
+    /**
+     * Change an agent's model tier
+     * This updates the tier and reinitializes the agent with the new model.
+     * Conversation history is preserved.
+     *
+     * @param id - The agent ID
+     * @param newTier - The new model tier
+     * @returns The updated TeamAgent
+     */
+    async changeAgentTier(id, newTier) {
+        const agent = this.agents.get(id);
+        if (!agent) {
+            throw new Error(`Agent '${id}' not found in team`);
+        }
+        // Set the new tier (this preserves state and clears the agent instance)
+        agent.setModelTier(newTier);
+        // Reinitialize with the new tier
+        await agent.initialize(this.agentFactory, this._sharedContext);
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:switched', agentId: id, previousAgentId: id });
+        return agent;
+    }
+    /**
+     * Initialize all agents (lazy initialization)
+     */
+    async initializeAll() {
+        for (const agent of this.agents.values()) {
+            if (!agent.isInitialized) {
+                await agent.initialize(this.agentFactory, this._sharedContext);
+            }
+        }
+    }
+    /**
+     * Initialize only the active agent
+     */
+    async initializeActive() {
+        const teamAgent = this.getActive();
+        if (!teamAgent.isInitialized) {
+            await teamAgent.initialize(this.agentFactory, this._sharedContext);
+        }
+        const agent = teamAgent.agent;
+        if (!agent) {
+            throw new Error('Agent not initialized after initialize() call');
+        }
+        return agent;
+    }
+    /**
+     * Parse a message for $agent prefix and switch if needed
+     * Returns the message without the prefix and whether a switch occurred
+     */
+    async parseAndSwitch(message) {
+        const match = message.match(/^\$(\w+)\s*(.*)/s);
+        if (!match) {
+            return { message, switched: false, agentId: this._activeAgentId };
+        }
+        const [, agentId, remainingMessage] = match;
+        // Check if agent exists
+        if (!this.agents.has(agentId)) {
+            // Return original message - let the agent handle invalid prefix
+            return { message, switched: false, agentId: this._activeAgentId };
+        }
+        // Switch to the agent
+        await this.switchTo(agentId);
+        return {
+            message: remainingMessage.trim() || message, // Keep original if no remaining message
+            switched: true,
+            agentId,
+        };
+    }
+    /**
+     * Get autocomplete suggestions for $agent prefix
+     */
+    getAgentSuggestions(prefix) {
+        const results = [];
+        const searchPrefix = prefix.toLowerCase();
+        for (const [id, agent] of this.agents) {
+            if (id.toLowerCase().startsWith(searchPrefix)) {
+                results.push({
+                    id,
+                    label: agent.getFullLabel(),
+                });
+            }
+        }
+        return results;
+    }
+    // ---------------------------------------------------------------------------
+    // Handoff Tracking (One-Hop Prevention)
+    // ---------------------------------------------------------------------------
+    /**
+     * Record that sourceAgent handed off to targetAgent.
+     * Used for one-hop prevention.
+     */
+    recordHandoff(targetAgentId, sourceAgentId) {
+        this._handedFrom.set(targetAgentId, sourceAgentId);
+    }
+    /**
+     * Check if an agent was handed a task (i.e., is a handoff target).
+     * If true, this agent cannot re-hand off (except back to coordinator).
+     */
+    wasHandedTo(agentId) {
+        return this._handedFrom.has(agentId);
+    }
+    /**
+     * Get the source agent that handed off to the given agent.
+     */
+    getHandoffSource(agentId) {
+        return this._handedFrom.get(agentId);
+    }
+    /**
+     * Clear handoff tracking for an agent (after it completes its task).
+     */
+    clearHandoffRecord(agentId) {
+        this._handedFrom.delete(agentId);
+    }
+    /**
+     * Serialize the team for persistence
+     */
+    serialize() {
+        const agents = [];
+        for (const agent of this.agents.values()) {
+            agents.push(agent.serialize());
+        }
+        return {
+            metadata: {
+                name: this.name,
+                activeAgentId: this._activeAgentId,
+                coordinatorId: this._coordinatorId,
+                agentIds: Array.from(this.agents.keys()),
+                createdAt: this.createdAt.toISOString(),
+                updatedAt: this.updatedAt.toISOString(),
+            },
+            agents,
+        };
+    }
+    /**
+     * Restore team state from serialized data
+     */
+    static restore(data, agentFactory, onEvent, options) {
+        const team = new AgentTeam({
+            name: data.metadata.name,
+            agentFactory,
+            onEvent,
+            sharedContext: options?.sharedContext,
+            artifactStore: options?.artifactStore,
+            sessionRegistry: options?.sessionRegistry,
+        });
+        // Clear default agent if not in serialized data
+        if (!data.metadata.agentIds.includes('default')) {
+            team.agents.delete('default');
+        }
+        // Restore agents
+        for (const agentData of data.agents) {
+            const teamAgent = TeamAgent.fromSerialized(agentData);
+            team.agents.set(agentData.id, teamAgent);
+        }
+        // Restore metadata
+        team._activeAgentId = data.metadata.activeAgentId;
+        team._coordinatorId = data.metadata.coordinatorId;
+        // Update shared context with restored team roster (simple list)
+        team._sharedContext.setTeam(Array.from(team.agents.keys()), team._activeAgentId);
+        // Build full team roster for team awareness
+        team.updateTeamRoster();
+        team.emit({ type: 'team:restored' });
+        return team;
+    }
+    /**
+     * Emit a team event
+     */
+    emit(event) {
+        this.onEvent?.(event);
+    }
+    // ---------------------------------------------------------------------------
+    // Team Awareness - Roster Management
+    // ---------------------------------------------------------------------------
+    /**
+     * Build and update the team roster in shared context
+     * Called when team composition or active agent changes
+     */
+    updateTeamRoster() {
+        const roster = this.buildTeamRoster();
+        this._sharedContext.updateTeamRoster(roster);
+        // Push updated roster to all initialized agents via anchors.
+        // Anchors are re-injected on every LLM call, so agents always see the latest roster.
+        if (this._sharedContext.hasTeamRoster()) {
+            const rosterContent = this._sharedContext.formatTeamRoster();
+            for (const [, teamAgent] of this.agents) {
+                const agent = teamAgent.agent;
+                if (agent && agent.hasAnchors()) {
+                    agent.addAnchor({
+                        id: 'team-roster',
+                        content: rosterContent,
+                        priority: 'info',
+                        scope: 'session',
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Build the team roster from current agents
+     */
+    buildTeamRoster() {
+        const roster = [];
+        for (const [id, agent] of this.agents) {
+            const role = agent.role;
+            // For custom agents, derive expertise from their specialty/description
+            // since ROLE_EXPERTISE['custom'] is empty
+            let expertise = ROLE_EXPERTISE[role];
+            if (role === 'custom' && expertise.length === 0 && agent.description) {
+                expertise = agent.description
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+            }
+            roster.push({
+                id,
+                displayName: agent.displayName,
+                mascot: agent.mascot,
+                role,
+                expertise,
+                isActive: id === this._activeAgentId,
+            });
+        }
+        return roster;
+    }
+}