@compilr-dev/sdk 0.1.27 → 0.2.0

package/dist/team/context-resolver.js

@@ -0,0 +1,322 @@
+/**
+ * ContextResolver - Resolve $agent mentions to actual content
+ *
+ * Resolution strategy:
+ * 1. Check for explicit artifact reference in context hint
+ * 2. Search artifacts by name/content matching context hint
+ * 3. Fall back to recent conversation history
+ *
+ * Token budgets:
+ * - Single mention: 2000 tokens max
+ * - Multiple mentions: 3000 tokens total, split among mentions
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+const DEFAULT_MAX_TOKENS_PER_MENTION = 2000;
+const DEFAULT_MAX_TOTAL_TOKENS = 3000;
+const DEFAULT_MAX_HISTORY_MESSAGES = 10;
+/**
+ * Simple token estimation: ~4 chars per token
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// =============================================================================
+// ContextResolver
+// =============================================================================
+/**
+ * Resolve mentions to actual content
+ */
+export class ContextResolver {
+    team;
+    artifactStore;
+    constructor(team, artifactStore) {
+        this.team = team;
+        this.artifactStore = artifactStore;
+    }
+    /**
+     * Resolve multiple mentions
+     */
+    resolveAll(mentions, options = {}) {
+        const maxTotal = options.maxTotalTokens ?? DEFAULT_MAX_TOTAL_TOKENS;
+        const perMention = options.maxTokensPerMention ?? DEFAULT_MAX_TOKENS_PER_MENTION;
+        // Calculate budget per mention
+        const budgetPerMention = Math.min(perMention, Math.floor(maxTotal / mentions.length));
+        const results = new Map();
+        let totalTokens = 0;
+        for (const mention of mentions) {
+            // Skip if we're out of budget
+            if (totalTokens >= maxTotal) {
+                results.set(mention.agentId, {
+                    mention,
+                    resolved: false,
+                    source: 'not_found',
+                    sourceName: 'budget exceeded',
+                    content: '',
+                    tokenCount: 0,
+                });
+                continue;
+            }
+            const remainingBudget = Math.min(budgetPerMention, maxTotal - totalTokens);
+            const resolved = this.resolveMention(mention, {
+                ...options,
+                maxTokensPerMention: remainingBudget,
+            });
+            results.set(mention.agentId, resolved);
+            totalTokens += resolved.tokenCount;
+        }
+        return results;
+    }
+    /**
+     * Resolve a single mention
+     */
+    resolveMention(mention, options = {}) {
+        const maxTokens = options.maxTokensPerMention ?? DEFAULT_MAX_TOKENS_PER_MENTION;
+        // 1. Try to find matching artifact
+        const artifactResult = this.resolveFromArtifacts(mention, maxTokens, options);
+        if (artifactResult) {
+            return artifactResult;
+        }
+        // 2. Try to extract from conversation history
+        const historyResult = this.resolveFromHistory(mention, maxTokens, options);
+        if (historyResult) {
+            return historyResult;
+        }
+        // 3. Not found
+        return {
+            mention,
+            resolved: false,
+            source: 'not_found',
+            sourceName: 'no relevant content found',
+            content: '',
+            tokenCount: 0,
+        };
+    }
+    /**
+     * Resolve from artifacts
+     */
+    resolveFromArtifacts(mention, maxTokens, options) {
+        const { agentId, context } = mention;
+        // Get artifacts by this agent
+        const agentArtifacts = this.artifactStore.listByAgent(agentId);
+        if (agentArtifacts.length === 0) {
+            return null;
+        }
+        // Sort artifacts by most recent first
+        const sortedArtifacts = agentArtifacts.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+        // Find matching artifact based on context hint
+        let matchedArtifact;
+        if (context) {
+            // Search by name or content
+            const searchResults = this.artifactStore.search(context);
+            const searchMatch = searchResults.find((a) => a.agent === agentId);
+            // Use search match if found, otherwise fall back to most recent
+            matchedArtifact = searchMatch ?? sortedArtifacts[0];
+        }
+        else {
+            // No context hint - use most recent artifact
+            matchedArtifact = sortedArtifacts[0];
+        }
+        // Format artifact content
+        let content;
+        let tokenCount;
+        if (options.includeFullArtifact) {
+            content = this.formatArtifactFull(matchedArtifact);
+            tokenCount = estimateTokens(content);
+            // If over budget, fall back to summary
+            if (tokenCount > maxTokens) {
+                content = this.formatArtifactSummary(matchedArtifact);
+                tokenCount = estimateTokens(content);
+            }
+        }
+        else {
+            // Start with summary, include full if within budget
+            const summary = this.formatArtifactSummary(matchedArtifact);
+            const full = this.formatArtifactFull(matchedArtifact);
+            if (estimateTokens(full) <= maxTokens) {
+                content = full;
+            }
+            else {
+                content = summary;
+            }
+            tokenCount = estimateTokens(content);
+        }
+        return {
+            mention,
+            resolved: true,
+            source: 'artifact',
+            sourceName: matchedArtifact.name,
+            content,
+            tokenCount,
+        };
+    }
+    /**
+     * Resolve from conversation history
+     */
+    resolveFromHistory(mention, maxTokens, options) {
+        const { agentId, context } = mention;
+        const maxMessages = options.maxHistoryMessages ?? DEFAULT_MAX_HISTORY_MESSAGES;
+        // Get the team agent
+        const teamAgent = this.team.get(agentId);
+        if (!teamAgent) {
+            return null;
+        }
+        // Get the underlying agent
+        const agent = teamAgent.agent;
+        if (!agent) {
+            return null;
+        }
+        // Get recent messages from the agent's history
+        const state = agent.serialize();
+        const messages = state.messages;
+        if (messages.length === 0) {
+            return null;
+        }
+        // Get assistant messages (agent's responses)
+        const assistantMessages = messages
+            .filter((m) => m.role === 'assistant')
+            .slice(-maxMessages);
+        if (assistantMessages.length === 0) {
+            return null;
+        }
+        // Extract relevant content
+        let relevantContent;
+        if (context) {
+            // Search for context in messages
+            relevantContent = this.extractRelevantContent(assistantMessages, context, maxTokens);
+        }
+        else {
+            // Use most recent message
+            const lastMessage = assistantMessages[assistantMessages.length - 1];
+            relevantContent = this.formatMessage(lastMessage);
+        }
+        if (!relevantContent) {
+            return null;
+        }
+        // Truncate if needed
+        const tokenCount = estimateTokens(relevantContent);
+        if (tokenCount > maxTokens) {
+            relevantContent = this.truncateToTokens(relevantContent, maxTokens);
+        }
+        return {
+            mention,
+            resolved: true,
+            source: 'history',
+            sourceName: 'recent conversation',
+            content: relevantContent,
+            tokenCount: estimateTokens(relevantContent),
+        };
+    }
+    /**
+     * Extract relevant content from messages based on context hint
+     */
+    extractRelevantContent(messages, context, maxTokens) {
+        const keywords = context
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 2);
+        // Score messages by relevance
+        const scored = messages.map((msg) => {
+            const content = this.formatMessage(msg);
+            const contentLower = content.toLowerCase();
+            let score = 0;
+            for (const keyword of keywords) {
+                if (contentLower.includes(keyword)) {
+                    score += 1;
+                }
+            }
+            return { content, score };
+        });
+        // Sort by score (highest first)
+        scored.sort((a, b) => b.score - a.score);
+        // Take best matches within token budget
+        const results = [];
+        let totalTokens = 0;
+        for (const { content, score } of scored) {
+            if (score === 0)
+                continue;
+            const tokens = estimateTokens(content);
+            if (totalTokens + tokens > maxTokens) {
+                // Try to include truncated version
+                const remaining = maxTokens - totalTokens;
+                if (remaining > 100) {
+                    results.push(this.truncateToTokens(content, remaining));
+                }
+                break;
+            }
+            results.push(content);
+            totalTokens += tokens;
+        }
+        return results.join('\n\n---\n\n');
+    }
+    /**
+     * Format a message for injection
+     */
+    formatMessage(message) {
+        if (typeof message.content === 'string') {
+            return message.content;
+        }
+        // Handle array content (Claude format)
+        if (Array.isArray(message.content)) {
+            const blocks = message.content;
+            return blocks
+                .filter((block) => block.type === 'text' && typeof block.text === 'string')
+                .map((block) => block.text)
+                .join('\n');
+        }
+        return String(message.content);
+    }
+    /**
+     * Format artifact with full content
+     */
+    formatArtifactFull(artifact) {
+        return [
+            `**${artifact.name}** (${artifact.type})`,
+            `By: $${artifact.agent} | Updated: ${artifact.updatedAt.toLocaleDateString()}`,
+            '',
+            artifact.content,
+        ].join('\n');
+    }
+    /**
+     * Format artifact with summary only
+     */
+    formatArtifactSummary(artifact) {
+        return [
+            `**${artifact.name}** (${artifact.type})`,
+            `By: $${artifact.agent} | Updated: ${artifact.updatedAt.toLocaleDateString()}`,
+            '',
+            `Summary: ${artifact.summary}`,
+            '',
+            `[Full content available via artifact store]`,
+        ].join('\n');
+    }
+    /**
+     * Truncate content to approximate token count
+     */
+    truncateToTokens(content, maxTokens) {
+        const maxChars = maxTokens * 4;
+        if (content.length <= maxChars) {
+            return content;
+        }
+        // Truncate at word boundary
+        const truncated = content.slice(0, maxChars);
+        const lastSpace = truncated.lastIndexOf(' ');
+        if (lastSpace > maxChars * 0.8) {
+            return truncated.slice(0, lastSpace) + '...';
+        }
+        return truncated + '...';
+    }
+}
+/**
+ * Build a context map from resolved mentions
+ */
+export function buildContextMap(resolved) {
+    const contextMap = new Map();
+    for (const [agentId, resolution] of resolved) {
+        if (resolution.resolved && resolution.content) {
+            contextMap.set(agentId, resolution.content);
+        }
+    }
+    return contextMap;
+}

package/dist/team/custom-agents.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Custom Agent Definitions
+ *
+ * Enables users to create custom specialized agents beyond predefined templates.
+ * Custom agents have user-defined names, specialties, and personalities.
+ *
+ * This SDK version contains only types and pure functions.
+ * Consumers handle their own persistence (load/save).
+ */
+import { type ToolConfig, type ToolProfile } from './tool-config.js';
+import type { ModelTier } from '../models/index.js';
+export interface CustomAgentDefinition {
+    id: string;
+    displayName: string;
+    specialty: string;
+    personality?: string;
+    mascot: string;
+    createdAt: string;
+    toolConfig?: ToolConfig;
+    enabledSkills?: string[];
+    modelTier?: ModelTier;
+}
+export type { ToolConfig, ToolProfile };
+/**
+ * Mascots available for custom agents.
+ * These are distinct from predefined role mascots.
+ */
+export declare const CUSTOM_MASCOTS: string[];
+/**
+ * Assign a mascot from the available pool.
+ * Avoids mascots already in use by other custom agents.
+ */
+export declare function assignMascot(existingAgents: CustomAgentDefinition[]): string;
+/**
+ * Generate system prompt for a custom agent.
+ * Uses a template-based approach (no LLM call).
+ * Includes tool awareness if the agent has tool restrictions.
+ */
+export declare function generateCustomAgentSystemPrompt(agent: CustomAgentDefinition): string;
+/**
+ * Get the tool filter (list of allowed tools) for a custom agent.
+ * Returns undefined for full access (no filtering).
+ */
+export declare function getCustomAgentToolFilter(agent: CustomAgentDefinition): string[] | undefined;
+/**
+ * Get the profile display name for a custom agent.
+ */
+export declare function getCustomAgentProfileLabel(agent: CustomAgentDefinition): string;
+/**
+ * Validate agent ID format.
+ * Must be lowercase letters, numbers, and underscores.
+ * Must start with a letter.
+ */
+export declare function validateAgentId(id: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Check if agent ID is already in use.
+ */
+export declare function isAgentIdTaken(id: string, existingCustomAgents: CustomAgentDefinition[], teamAgentIds: string[], predefinedRoleIds: string[]): {
+    taken: boolean;
+    reason?: string;
+};
+/**
+ * Create a new CustomAgentDefinition with auto-assigned mascot.
+ */
+export declare function createCustomAgentDefinition(id: string, displayName: string, specialty: string, personality: string | undefined, existingAgents: CustomAgentDefinition[], toolConfig?: ToolConfig, enabledSkills?: string[], modelTier?: ModelTier): CustomAgentDefinition;

package/dist/team/custom-agents.js

@@ -0,0 +1,150 @@
+/**
+ * Custom Agent Definitions
+ *
+ * Enables users to create custom specialized agents beyond predefined templates.
+ * Custom agents have user-defined names, specialties, and personalities.
+ *
+ * This SDK version contains only types and pure functions.
+ * Consumers handle their own persistence (load/save).
+ */
+import { createDefaultToolConfig, getToolsForProfile, generateToolAwarenessPrompt, PROFILE_INFO, } from './tool-config.js';
+// =============================================================================
+// Mascot Pool for Custom Agents
+// =============================================================================
+/**
+ * Mascots available for custom agents.
+ * These are distinct from predefined role mascots.
+ */
+export const CUSTOM_MASCOTS = [
+    '[⊡_⊡]',
+    '[⊞_⊞]',
+    '[⊟_⊟]',
+    '[⊠_⊠]',
+    '[⋈_⋈]',
+    '[⋐_⋐]',
+    '[⋑_⋑]',
+    '[⋒_⋒]',
+    '[◌_◌]',
+    '[◍_◍]',
+    '[●_●]',
+    '[◐_◐]',
+    '[◑_◑]',
+    '[◒_◒]',
+    '[◓_◓]',
+    '[◔_◔]',
+];
+/**
+ * Assign a mascot from the available pool.
+ * Avoids mascots already in use by other custom agents.
+ */
+export function assignMascot(existingAgents) {
+    const usedMascots = new Set(existingAgents.map((a) => a.mascot));
+    const available = CUSTOM_MASCOTS.filter((m) => !usedMascots.has(m));
+    if (available.length > 0) {
+        return available[0];
+    }
+    // Fall back to random selection if all are used
+    return CUSTOM_MASCOTS[Math.floor(Math.random() * CUSTOM_MASCOTS.length)];
+}
+// =============================================================================
+// System Prompt Generation
+// =============================================================================
+/**
+ * Generate system prompt for a custom agent.
+ * Uses a template-based approach (no LLM call).
+ * Includes tool awareness if the agent has tool restrictions.
+ */
+export function generateCustomAgentSystemPrompt(agent) {
+    const lines = [`You are a ${agent.displayName} specialized in ${agent.specialty}.`];
+    if (agent.personality) {
+        lines.push('');
+        lines.push(`Your approach: ${agent.personality}`);
+    }
+    lines.push('');
+    lines.push('Focus on your area of expertise. When questions fall outside your specialty, suggest which team member might be better suited to help.');
+    // Add tool awareness if agent has tool restrictions
+    const toolConfig = agent.toolConfig ?? createDefaultToolConfig();
+    if (toolConfig.profile !== 'full') {
+        lines.push('');
+        lines.push('---');
+        lines.push('');
+        lines.push(generateToolAwarenessPrompt(toolConfig));
+    }
+    return lines.join('\n');
+}
+/**
+ * Get the tool filter (list of allowed tools) for a custom agent.
+ * Returns undefined for full access (no filtering).
+ */
+export function getCustomAgentToolFilter(agent) {
+    const toolConfig = agent.toolConfig ?? createDefaultToolConfig();
+    return getToolsForProfile(toolConfig.profile, toolConfig.customGroups);
+}
+/**
+ * Get the profile display name for a custom agent.
+ */
+export function getCustomAgentProfileLabel(agent) {
+    const toolConfig = agent.toolConfig ?? createDefaultToolConfig();
+    const info = PROFILE_INFO[toolConfig.profile];
+    return info.label;
+}
+// =============================================================================
+// Validation
+// =============================================================================
+/**
+ * Validate agent ID format.
+ * Must be lowercase letters, numbers, and underscores.
+ * Must start with a letter.
+ */
+export function validateAgentId(id) {
+    if (!id || id.trim() === '') {
+        return { valid: false, error: 'Agent ID is required' };
+    }
+    if (id.length > 20) {
+        return { valid: false, error: 'Agent ID must be 20 characters or less' };
+    }
+    if (!/^[a-z][a-z0-9_]*$/.test(id)) {
+        return {
+            valid: false,
+            error: 'Must be lowercase letters, numbers, underscore (start with letter)',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Check if agent ID is already in use.
+ */
+export function isAgentIdTaken(id, existingCustomAgents, teamAgentIds, predefinedRoleIds) {
+    // Check predefined roles
+    if (predefinedRoleIds.includes(id)) {
+        return { taken: true, reason: `"${id}" is a predefined role` };
+    }
+    // Check team agents
+    if (teamAgentIds.includes(id)) {
+        return { taken: true, reason: `"${id}" is already in your team` };
+    }
+    // Check custom agents
+    if (existingCustomAgents.some((a) => a.id === id)) {
+        return { taken: true, reason: `"${id}" already exists as a custom agent` };
+    }
+    return { taken: false };
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a new CustomAgentDefinition with auto-assigned mascot.
+ */
+export function createCustomAgentDefinition(id, displayName, specialty, personality, existingAgents, toolConfig, enabledSkills, modelTier) {
+    return {
+        id,
+        displayName,
+        specialty,
+        personality: personality || undefined,
+        mascot: assignMascot(existingAgents),
+        createdAt: new Date().toISOString(),
+        toolConfig: toolConfig ?? createDefaultToolConfig(),
+        enabledSkills: enabledSkills ?? [], // Empty = all skills
+        modelTier: modelTier ?? 'balanced', // Default tier
+    };
+}

package/dist/team/delegation-tracker.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Delegation Tracker (Coordinator Mode)
+ *
+ * Tracks active delegations from the coordinator to background specialists.
+ * Maintains a completion event queue so the coordinator can be notified
+ * when specialists finish their work.
+ */
+import { EventEmitter } from 'events';
+export type DelegationStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+export interface Delegation {
+    /** Unique delegation ID (del_<uuid>) */
+    id: string;
+    /** Agent that initiated the delegation (always 'default' for now) */
+    coordinatorId: string;
+    /** Target specialist agent ID (e.g., 'arch', 'dev', 'qa') */
+    targetAgentId: string;
+    /** Task description sent to the specialist */
+    task: string;
+    /** What the specialist is expected to produce */
+    expectedOutput?: string;
+    /** Associated todo index (if any) */
+    todoIndex?: number;
+    /** Current status */
+    status: DelegationStatus;
+    /** Result (set on completion or failure) */
+    result?: DelegationResult;
+    /** When the delegation was created */
+    createdAt: Date;
+    /** When the delegation completed */
+    completedAt?: Date;
+}
+export interface DelegationResult {
+    /** Whether the task completed successfully */
+    success: boolean;
+    /** Brief outcome summary */
+    summary: string;
+    /** Artifact IDs created by the specialist */
+    artifactIds: string[];
+    /** Error message (if failed) */
+    error?: string;
+}
+export interface CompletionEvent {
+    /** The delegation ID */
+    delegationId: string;
+    /** The specialist that completed the work */
+    agentId: string;
+    /** Completion status */
+    status: 'completed' | 'failed';
+    /** Result details */
+    result: DelegationResult;
+    /** When the event was generated */
+    timestamp: Date;
+}
+export interface CreateDelegationOptions {
+    /** Agent that initiated the delegation */
+    coordinatorId: string;
+    /** Target specialist agent ID */
+    targetAgentId: string;
+    /** Task description */
+    task: string;
+    /** Expected output description */
+    expectedOutput?: string;
+    /** Associated todo index */
+    todoIndex?: number;
+}
+export interface DelegationStats {
+    total: number;
+    pending: number;
+    running: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+}
+export interface DelegationTrackerEvents {
+    /** Emitted when a new delegation is created */
+    'delegation-created': (delegation: Delegation) => void;
+    /** Emitted when a delegation completes successfully */
+    'delegation-completed': (event: CompletionEvent) => void;
+    /** Emitted when a delegation fails */
+    'delegation-failed': (event: CompletionEvent) => void;
+    /** Emitted when delegation counts change */
+    'count-changed': (stats: DelegationStats) => void;
+}
+export declare class DelegationTracker extends EventEmitter {
+    private readonly delegations;
+    private readonly completionQueue;
+    /**
+     * Create a new delegation.
+     */
+    create(options: CreateDelegationOptions): Delegation;
+    /**
+     * Update a delegation's status.
+     */
+    updateStatus(id: string, status: DelegationStatus): void;
+    /**
+     * Mark a delegation as completed with a result.
+     */
+    complete(id: string, result: DelegationResult): void;
+    /**
+     * Mark a delegation as failed.
+     */
+    fail(id: string, error: string): void;
+    /**
+     * Mark a delegation as cancelled.
+     */
+    cancel(id: string): void;
+    /**
+     * Cancel all active delegations for a specific agent.
+     */
+    cancelAllForAgent(agentId: string): number;
+    /**
+     * Get a delegation by ID.
+     */
+    getDelegation(id: string): Delegation | undefined;
+    /**
+     * Get all delegations targeting a specific agent.
+     */
+    getByAgent(agentId: string): Delegation[];
+    /**
+     * Get all active (pending or running) delegations.
+     */
+    getActive(): Delegation[];
+    /**
+     * Get all delegations.
+     */
+    getAll(): Delegation[];
+    /**
+     * Check if there are pending completion events.
+     */
+    hasCompletionEvents(): boolean;
+    /**
+     * Drain all completion events (removes them from queue).
+     */
+    drainCompletionEvents(): CompletionEvent[];
+    /**
+     * Peek at completion events without removing them.
+     */
+    peekCompletionEvents(): CompletionEvent[];
+    /**
+     * Get delegation statistics.
+     */
+    getStats(): DelegationStats;
+    /**
+     * Clear all delegations and completion events.
+     */
+    clear(): void;
+}