@compilr-dev/sdk 0.1.27 → 0.2.0

package/dist/team/team-agent.d.ts

@@ -0,0 +1,201 @@
+/**
+ * TeamAgent - Wrapper for persistent team agents
+ *
+ * Each team agent has:
+ * - Unique identity (id, name, mascot)
+ * - Isolated conversation history
+ * - Role-specific system prompt additions
+ * - Optional tool filtering
+ */
+import type { Agent, AgentConfig, ContextManager } from '@compilr-dev/agents';
+import type { TeamAgentConfig, SerializedTeamAgent, MascotExpression, AgentRole } from './types.js';
+import type { ModelTier } from '../models/index.js';
+import type { ProviderType } from '../config.js';
+import type { SharedContextManager } from './shared-context.js';
+import type { CustomAgentDefinition } from './custom-agents.js';
+/**
+ * TeamAgent wraps an Agent instance with team-specific metadata
+ */
+export declare class TeamAgent {
+    /**
+     * Unique identifier (e.g., 'pm', 'arch', 'qa')
+     */
+    readonly id: string;
+    /**
+     * Display name shown in UI
+     */
+    readonly displayName: string;
+    /**
+     * Mascot expression for visual differentiation
+     */
+    readonly mascot: MascotExpression;
+    /**
+     * Role type
+     */
+    readonly role: AgentRole;
+    /**
+     * Optional description
+     */
+    readonly description?: string;
+    /**
+     * System prompt addition specific to this agent
+     */
+    readonly systemPromptAddition?: string;
+    /**
+     * Use minimal system prompt - skip all modules
+     */
+    readonly useMinimalSystemPrompt?: boolean;
+    /**
+     * Skip all tool registration - agent has no tools
+     */
+    readonly noTools?: boolean;
+    /**
+     * Tool filter (tool names this agent can use)
+     */
+    readonly toolFilter?: string[];
+    /**
+     * Tool profile name (for display)
+     */
+    readonly toolProfile?: TeamAgentConfig['toolProfile'];
+    /**
+     * Enabled skills (empty = all skills)
+     */
+    readonly enabledSkills?: string[];
+    /**
+     * Auto-approve handoffs from this agent without user confirmation
+     */
+    readonly autoApproveHandoff?: boolean;
+    /**
+     * Model tier (fast/balanced/powerful)
+     * Determines which model to use based on provider
+     */
+    private _modelTier?;
+    /**
+     * The underlying agent instance
+     */
+    private _agent;
+    /**
+     * Agent configuration for lazy initialization
+     */
+    private readonly agentConfig;
+    /**
+     * Stored agent state (for persistence before agent is created)
+     */
+    private storedState?;
+    /**
+     * Token usage tracking
+     */
+    private _tokenUsage;
+    /**
+     * Last activity timestamp
+     */
+    private _lastActivity;
+    constructor(config: TeamAgentConfig);
+    /**
+     * Get the underlying agent instance
+     */
+    get agent(): Agent | null;
+    /**
+     * Check if agent is initialized
+     */
+    get isInitialized(): boolean;
+    /**
+     * Get token usage
+     */
+    get tokenUsage(): {
+        input: number;
+        output: number;
+    };
+    /**
+     * Get last activity timestamp
+     */
+    get lastActivity(): Date;
+    /**
+     * Get model tier
+     */
+    get modelTier(): ModelTier | undefined;
+    /**
+     * Change the model tier
+     * This preserves conversation history but strips thinking blocks
+     * (which contain provider-specific signatures that don't transfer).
+     *
+     * @param newTier - The new model tier to use
+     */
+    setModelTier(newTier: ModelTier): void;
+    /**
+     * Initialize the agent with the given factory
+     * This allows the team to control agent creation
+     *
+     * @param agentFactory Factory function to create the agent
+     * @param sharedContext Optional shared context to inject into system prompt
+     */
+    initialize(agentFactory: (config: Partial<AgentConfig>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean, toolFilter?: string[], modelTier?: ModelTier) => Promise<Agent>, sharedContext?: SharedContextManager): Promise<void>;
+    /**
+     * Set the agent instance directly
+     * Used for the default agent when an agent is created before the team
+     */
+    setAgent(agent: Agent): void;
+    /**
+     * Update token usage after a turn
+     */
+    updateTokenUsage(input: number, output: number): void;
+    /**
+     * Reset token usage (e.g., after compaction)
+     */
+    resetTokenUsage(): void;
+    /**
+     * Clear conversation history (for /reset command)
+     * Clears both the underlying agent and stored state
+     */
+    clearHistory(): void;
+    /**
+     * Get context manager from the agent (if available)
+     */
+    getContextManager(): ContextManager | undefined;
+    /**
+     * Get context utilization percentage
+     */
+    getContextUtilization(): number;
+    /**
+     * Get the max context window for this agent's model.
+     * Resolves: modelTier → modelId → contextWindow from MODEL_REGISTRY.
+     */
+    getMaxContextTokens(provider: ProviderType): number;
+    /**
+     * Get context stats (works even when agent is not initialized)
+     * Returns data from either the live agent or stored state.
+     * Includes maxTokens for per-agent context window display.
+     */
+    getContextStats(provider?: ProviderType): {
+        messageCount: number;
+        estimatedTokens: number;
+        maxTokens: number;
+    };
+    /**
+     * Serialize the team agent for persistence
+     */
+    serialize(): SerializedTeamAgent;
+    /**
+     * Create a TeamAgent from serialized state
+     */
+    static fromSerialized(data: SerializedTeamAgent): TeamAgent;
+    /**
+     * Create a TeamAgent 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)
+     */
+    static fromRole(role: AgentRole, id?: string, modelTier?: ModelTier): TeamAgent;
+    /**
+     * Create a TeamAgent from a custom agent definition
+     */
+    static fromCustomDefinition(def: CustomAgentDefinition): TeamAgent;
+    /**
+     * Get a formatted label for display (e.g., "[◈_◈] $arch")
+     */
+    getLabel(): string;
+    /**
+     * Get a full label with display name (e.g., "[◈_◈] $arch (Solution Architect)")
+     */
+    getFullLabel(): string;
+}

package/dist/team/team-agent.js

@@ -0,0 +1,492 @@
+/**
+ * TeamAgent - Wrapper for persistent team agents
+ *
+ * Each team agent has:
+ * - Unique identity (id, name, mascot)
+ * - Isolated conversation history
+ * - Role-specific system prompt additions
+ * - Optional tool filtering
+ */
+import { ROLE_METADATA } from './types.js';
+import { getModelForTier, getModelContextWindow } from '../models/index.js';
+import { generateCustomAgentSystemPrompt, getCustomAgentToolFilter } from './custom-agents.js';
+import { getToolsForProfile, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
+/**
+ * Estimate token count from text (approximate: ~4 chars per token)
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * TeamAgent wraps an Agent instance with team-specific metadata
+ */
+export class TeamAgent {
+    /**
+     * Unique identifier (e.g., 'pm', 'arch', 'qa')
+     */
+    id;
+    /**
+     * Display name shown in UI
+     */
+    displayName;
+    /**
+     * Mascot expression for visual differentiation
+     */
+    mascot;
+    /**
+     * Role type
+     */
+    role;
+    /**
+     * Optional description
+     */
+    description;
+    /**
+     * System prompt addition specific to this agent
+     */
+    systemPromptAddition;
+    /**
+     * Use minimal system prompt - skip all modules
+     */
+    useMinimalSystemPrompt;
+    /**
+     * Skip all tool registration - agent has no tools
+     */
+    noTools;
+    /**
+     * Tool filter (tool names this agent can use)
+     */
+    toolFilter;
+    /**
+     * Tool profile name (for display)
+     */
+    toolProfile;
+    /**
+     * Enabled skills (empty = all skills)
+     */
+    enabledSkills;
+    /**
+     * Auto-approve handoffs from this agent without user confirmation
+     */
+    autoApproveHandoff;
+    /**
+     * Model tier (fast/balanced/powerful)
+     * Determines which model to use based on provider
+     */
+    _modelTier;
+    /**
+     * The underlying agent instance
+     */
+    _agent = null;
+    /**
+     * Agent configuration for lazy initialization
+     */
+    agentConfig;
+    /**
+     * Stored agent state (for persistence before agent is created)
+     */
+    storedState;
+    /**
+     * Token usage tracking
+     */
+    _tokenUsage = {
+        input: 0,
+        output: 0,
+    };
+    /**
+     * Last activity timestamp
+     */
+    _lastActivity = new Date();
+    constructor(config) {
+        this.id = config.id;
+        this.displayName = config.displayName;
+        this.mascot = config.mascot;
+        this.role = config.role;
+        this.description = config.description;
+        this.systemPromptAddition = config.systemPromptAddition;
+        this.useMinimalSystemPrompt = config.useMinimalSystemPrompt;
+        this.noTools = config.noTools;
+        this.toolFilter = config.toolFilter;
+        this.toolProfile = config.toolProfile;
+        this.enabledSkills = config.enabledSkills;
+        this.autoApproveHandoff = config.autoApproveHandoff;
+        this._modelTier = config.modelTier;
+        this.agentConfig = config.agentConfig ?? {};
+    }
+    /**
+     * Get the underlying agent instance
+     */
+    get agent() {
+        return this._agent;
+    }
+    /**
+     * Check if agent is initialized
+     */
+    get isInitialized() {
+        return this._agent !== null;
+    }
+    /**
+     * Get token usage
+     */
+    get tokenUsage() {
+        return { ...this._tokenUsage };
+    }
+    /**
+     * Get last activity timestamp
+     */
+    get lastActivity() {
+        return this._lastActivity;
+    }
+    /**
+     * Get model tier
+     */
+    get modelTier() {
+        return this._modelTier;
+    }
+    /**
+     * Change the model tier
+     * This preserves conversation history but strips thinking blocks
+     * (which contain provider-specific signatures that don't transfer).
+     *
+     * @param newTier - The new model tier to use
+     */
+    setModelTier(newTier) {
+        if (newTier === this._modelTier) {
+            return; // No change needed
+        }
+        // Store current state if agent is initialized
+        if (this._agent) {
+            const state = this._agent.serialize();
+            // Strip thinking blocks from messages - they contain provider-specific
+            // signatures (e.g., Gemini's thought_signature) that don't transfer
+            // between sessions or model changes
+            state.messages = state.messages.map((msg) => {
+                // Content can be string or ContentBlock[]
+                if (typeof msg.content === 'string') {
+                    return msg;
+                }
+                return {
+                    ...msg,
+                    content: msg.content.filter((block) => block.type !== 'thinking'),
+                };
+            });
+            this.storedState = state;
+            this._agent = null; // Clear agent so it will be reinitialized
+        }
+        this._modelTier = newTier;
+    }
+    /**
+     * Initialize the agent with the given factory
+     * This allows the team to control agent creation
+     *
+     * @param agentFactory Factory function to create the agent
+     * @param sharedContext Optional shared context to inject into system prompt
+     */
+    async initialize(agentFactory, sharedContext) {
+        if (this._agent) {
+            return; // Already initialized
+        }
+        // Build system prompt addition with shared context
+        let finalSystemPromptAddition = this.systemPromptAddition ?? '';
+        // Inject shared context if provided (excluding roster — that goes via anchor for live updates)
+        if (sharedContext) {
+            const sharedContextBlock = sharedContext.format({ excludeRoster: true });
+            if (sharedContextBlock) {
+                // Prepend shared context to role-specific prompt
+                finalSystemPromptAddition = finalSystemPromptAddition
+                    ? `${sharedContextBlock}\n\n${finalSystemPromptAddition}`
+                    : sharedContextBlock;
+            }
+        }
+        this._agent = await agentFactory(this.agentConfig, finalSystemPromptAddition || undefined, this.useMinimalSystemPrompt, this.noTools, this.toolFilter, // Pass tool filter to factory
+        this._modelTier // Pass model tier to factory
+        );
+        // Set the team roster as an anchor (dynamically re-injected on every LLM call).
+        // This ensures roster updates (agent added/removed) are always visible.
+        if (sharedContext && sharedContext.hasTeamRoster() && this._agent.hasAnchors()) {
+            this._agent.addAnchor({
+                id: 'team-roster',
+                content: sharedContext.formatTeamRoster(),
+                priority: 'info',
+                scope: 'session',
+            });
+        }
+        // Restore state if we have stored state
+        if (this.storedState && this.storedState.messages.length > 0) {
+            // Strip thinking blocks - they contain provider-specific signatures
+            // (e.g., Gemini's thought_signature) that don't transfer between sessions
+            const messagesWithoutThinking = this.storedState.messages.map((msg) => {
+                if (typeof msg.content === 'string') {
+                    return msg;
+                }
+                return {
+                    ...msg,
+                    content: msg.content.filter((block) => block.type !== 'thinking'),
+                };
+            });
+            await this._agent.setHistory(messagesWithoutThinking, {
+                turnCount: this.storedState.turnCount,
+            });
+        }
+    }
+    /**
+     * Set the agent instance directly
+     * Used for the default agent when an agent is created before the team
+     */
+    setAgent(agent) {
+        this._agent = agent;
+    }
+    /**
+     * Update token usage after a turn
+     */
+    updateTokenUsage(input, output) {
+        this._tokenUsage.input += input;
+        this._tokenUsage.output += output;
+        this._lastActivity = new Date();
+    }
+    /**
+     * Reset token usage (e.g., after compaction)
+     */
+    resetTokenUsage() {
+        this._tokenUsage = { input: 0, output: 0 };
+    }
+    /**
+     * Clear conversation history (for /reset command)
+     * Clears both the underlying agent and stored state
+     */
+    clearHistory() {
+        // Clear underlying agent if initialized
+        if (this._agent) {
+            this._agent.clearHistory();
+        }
+        // Clear stored state messages
+        if (this.storedState) {
+            this.storedState.messages = [];
+            this.storedState.todos = [];
+            this.storedState.turnCount = 0;
+        }
+        // Reset token usage
+        this._tokenUsage = { input: 0, output: 0 };
+        this._lastActivity = new Date();
+    }
+    /**
+     * Get context manager from the agent (if available)
+     */
+    getContextManager() {
+        return this._agent?.getContextManager();
+    }
+    /**
+     * Get context utilization percentage
+     */
+    getContextUtilization() {
+        const cm = this.getContextManager();
+        if (!cm)
+            return 0;
+        const messageCount = this._agent?.serialize().messages.length ?? 0;
+        const stats = cm.getStats(messageCount);
+        return Math.round((stats.currentTokens / stats.maxTokens) * 100);
+    }
+    /**
+     * Get the max context window for this agent's model.
+     * Resolves: modelTier → modelId → contextWindow from MODEL_REGISTRY.
+     */
+    getMaxContextTokens(provider) {
+        // If agent is initialized, get from ContextManager
+        if (this._agent) {
+            const cm = this.getContextManager();
+            if (cm) {
+                const state = this._agent.serialize();
+                const stats = cm.getStats(state.messages.length);
+                return stats.maxTokens;
+            }
+        }
+        // Fall back to model-based lookup
+        if (this._modelTier) {
+            const modelId = getModelForTier(provider, this._modelTier);
+            return getModelContextWindow(modelId, provider);
+        }
+        return getModelContextWindow('', provider); // provider fallback
+    }
+    /**
+     * Get context stats (works even when agent is not initialized)
+     * Returns data from either the live agent or stored state.
+     * Includes maxTokens for per-agent context window display.
+     */
+    getContextStats(provider) {
+        // Try live agent first — use ContextManager stats (includes overhead)
+        if (this._agent) {
+            const cm = this.getContextManager();
+            if (cm) {
+                const state = this._agent.serialize();
+                const stats = cm.getStats(state.messages.length);
+                return {
+                    messageCount: state.messages.length,
+                    estimatedTokens: stats.currentTokens,
+                    maxTokens: stats.maxTokens,
+                };
+            }
+            // Agent exists but no context manager — estimate
+            const state = this._agent.serialize();
+            const messagesStr = JSON.stringify(state.messages);
+            return {
+                messageCount: state.messages.length,
+                estimatedTokens: estimateTokens(messagesStr),
+                maxTokens: provider ? this.getMaxContextTokens(provider) : 200000,
+            };
+        }
+        // Fall back to stored state
+        if (this.storedState && this.storedState.messages.length > 0) {
+            const messagesStr = JSON.stringify(this.storedState.messages);
+            return {
+                messageCount: this.storedState.messages.length,
+                estimatedTokens: estimateTokens(messagesStr),
+                maxTokens: provider ? this.getMaxContextTokens(provider) : 200000,
+            };
+        }
+        return {
+            messageCount: 0,
+            estimatedTokens: 0,
+            maxTokens: provider ? this.getMaxContextTokens(provider) : 200000,
+        };
+    }
+    /**
+     * Serialize the team agent for persistence
+     */
+    serialize() {
+        const now = new Date().toISOString();
+        const agentState = this._agent?.serialize() ??
+            this.storedState ?? {
+            sessionId: '',
+            messages: [],
+            systemPrompt: '',
+            todos: [],
+            currentIteration: 0,
+            turnCount: 0,
+            totalTokensUsed: 0,
+            createdAt: now,
+            updatedAt: now,
+            version: 1,
+        };
+        return {
+            id: this.id,
+            displayName: this.displayName,
+            mascot: this.mascot,
+            role: this.role,
+            description: this.description,
+            systemPromptAddition: this.systemPromptAddition,
+            useMinimalSystemPrompt: this.useMinimalSystemPrompt,
+            noTools: this.noTools,
+            toolFilter: this.toolFilter,
+            toolProfile: this.toolProfile,
+            enabledSkills: this.enabledSkills,
+            modelTier: this.modelTier,
+            autoApproveHandoff: this.autoApproveHandoff,
+            agentState,
+        };
+    }
+    /**
+     * Create a TeamAgent from serialized state
+     */
+    static fromSerialized(data) {
+        // Refresh tool filter from profile if available (ensures new tools are picked up)
+        // This handles the case where tools were added after the agent was created
+        const toolFilter = data.toolProfile ? getToolsForProfile(data.toolProfile) : data.toolFilter;
+        const agent = new TeamAgent({
+            id: data.id,
+            displayName: data.displayName,
+            mascot: data.mascot,
+            role: data.role,
+            description: data.description,
+            systemPromptAddition: data.systemPromptAddition,
+            useMinimalSystemPrompt: data.useMinimalSystemPrompt,
+            noTools: data.noTools,
+            toolFilter,
+            toolProfile: data.toolProfile,
+            enabledSkills: data.enabledSkills,
+            modelTier: data.modelTier,
+            autoApproveHandoff: data.autoApproveHandoff,
+        });
+        // Store the state for restoration when agent is initialized
+        agent.storedState = data.agentState;
+        return agent;
+    }
+    /**
+     * Create a TeamAgent 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)
+     */
+    static fromRole(role, id, modelTier) {
+        const metadata = ROLE_METADATA[role];
+        // Get tool filter from default profile (if specified)
+        const profile = metadata.defaultToolProfile;
+        const toolFilter = profile ? getToolsForProfile(profile) : undefined;
+        // Build system prompt with tool awareness (for non-full profiles)
+        let systemPromptAddition = metadata.defaultSystemPromptAddition ?? '';
+        if (profile && profile !== 'full') {
+            const toolAwareness = generateToolAwarenessPrompt({ profile });
+            systemPromptAddition = systemPromptAddition
+                ? `${systemPromptAddition}\n\n${toolAwareness}`
+                : toolAwareness;
+        }
+        // Add delegation guidance based on role
+        if (role === 'default') {
+            // Coordinator gets delegation tool guidance
+            const coordinatorGuidance = generateCoordinatorGuidance();
+            systemPromptAddition = systemPromptAddition
+                ? `${systemPromptAddition}\n\n${coordinatorGuidance}`
+                : coordinatorGuidance;
+        }
+        else {
+            // Specialists get collaboration guidance
+            const specialistGuidance = generateSpecialistGuidance(role);
+            systemPromptAddition = systemPromptAddition
+                ? `${systemPromptAddition}\n\n${specialistGuidance}`
+                : specialistGuidance;
+        }
+        return new TeamAgent({
+            id: id ?? role,
+            displayName: metadata.displayName,
+            mascot: metadata.mascot,
+            role,
+            description: metadata.description,
+            systemPromptAddition: systemPromptAddition || undefined,
+            useMinimalSystemPrompt: metadata.useMinimalSystemPrompt,
+            noTools: metadata.noTools,
+            toolFilter,
+            toolProfile: profile,
+            modelTier: modelTier ?? metadata.defaultModelTier,
+        });
+    }
+    /**
+     * Create a TeamAgent from a custom agent definition
+     */
+    static fromCustomDefinition(def) {
+        // Get tool filter from custom agent config
+        const toolFilter = getCustomAgentToolFilter(def);
+        return new TeamAgent({
+            id: def.id,
+            displayName: def.displayName,
+            mascot: def.mascot,
+            role: 'custom',
+            description: def.specialty,
+            systemPromptAddition: generateCustomAgentSystemPrompt(def),
+            toolFilter, // Pass tool filter from custom agent config
+            toolProfile: def.toolConfig?.profile, // Store profile for display
+            enabledSkills: def.enabledSkills, // Store skills for display
+            modelTier: def.modelTier, // Store model tier
+        });
+    }
+    /**
+     * Get a formatted label for display (e.g., "[◈_◈] $arch")
+     */
+    getLabel() {
+        return `${this.mascot} $${this.id}`;
+    }
+    /**
+     * Get a full label with display name (e.g., "[◈_◈] $arch (Solution Architect)")
+     */
+    getFullLabel() {
+        return `${this.mascot} $${this.id} (${this.displayName})`;
+    }
+}