@compilr-dev/sdk 0.1.27 → 0.2.0

package/dist/team/delegation-tracker.js

@@ -0,0 +1,215 @@
+/**
+ * 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';
+import { randomUUID } from 'crypto';
+// =============================================================================
+// Tracker Class
+// =============================================================================
+export class DelegationTracker extends EventEmitter {
+    delegations = new Map();
+    completionQueue = [];
+    /**
+     * Create a new delegation.
+     */
+    create(options) {
+        const delegation = {
+            id: `del_${randomUUID().slice(0, 8)}`,
+            coordinatorId: options.coordinatorId,
+            targetAgentId: options.targetAgentId,
+            task: options.task,
+            expectedOutput: options.expectedOutput,
+            todoIndex: options.todoIndex,
+            status: 'pending',
+            createdAt: new Date(),
+        };
+        this.delegations.set(delegation.id, delegation);
+        this.emit('delegation-created', delegation);
+        this.emit('count-changed', this.getStats());
+        return delegation;
+    }
+    /**
+     * Update a delegation's status.
+     */
+    updateStatus(id, status) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        delegation.status = status;
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Mark a delegation as completed with a result.
+     */
+    complete(id, result) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        delegation.status = 'completed';
+        delegation.result = result;
+        delegation.completedAt = new Date();
+        const event = {
+            delegationId: id,
+            agentId: delegation.targetAgentId,
+            status: 'completed',
+            result,
+            timestamp: new Date(),
+        };
+        this.completionQueue.push(event);
+        this.emit('delegation-completed', event);
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Mark a delegation as failed.
+     */
+    fail(id, error) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        const result = {
+            success: false,
+            summary: `Failed: ${error}`,
+            artifactIds: [],
+            error,
+        };
+        delegation.status = 'failed';
+        delegation.result = result;
+        delegation.completedAt = new Date();
+        const event = {
+            delegationId: id,
+            agentId: delegation.targetAgentId,
+            status: 'failed',
+            result,
+            timestamp: new Date(),
+        };
+        this.completionQueue.push(event);
+        this.emit('delegation-failed', event);
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Mark a delegation as cancelled.
+     */
+    cancel(id) {
+        const delegation = this.delegations.get(id);
+        if (!delegation)
+            return;
+        delegation.status = 'cancelled';
+        delegation.completedAt = new Date();
+        this.emit('count-changed', this.getStats());
+    }
+    /**
+     * Cancel all active delegations for a specific agent.
+     */
+    cancelAllForAgent(agentId) {
+        const active = this.getByAgent(agentId).filter((d) => d.status === 'pending' || d.status === 'running');
+        for (const delegation of active) {
+            this.cancel(delegation.id);
+        }
+        return active.length;
+    }
+    // ===========================================================================
+    // Query
+    // ===========================================================================
+    /**
+     * Get a delegation by ID.
+     */
+    getDelegation(id) {
+        return this.delegations.get(id);
+    }
+    /**
+     * Get all delegations targeting a specific agent.
+     */
+    getByAgent(agentId) {
+        return Array.from(this.delegations.values()).filter((d) => d.targetAgentId === agentId);
+    }
+    /**
+     * Get all active (pending or running) delegations.
+     */
+    getActive() {
+        return Array.from(this.delegations.values()).filter((d) => d.status === 'pending' || d.status === 'running');
+    }
+    /**
+     * Get all delegations.
+     */
+    getAll() {
+        return Array.from(this.delegations.values()).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    }
+    // ===========================================================================
+    // Completion Events
+    // ===========================================================================
+    /**
+     * Check if there are pending completion events.
+     */
+    hasCompletionEvents() {
+        return this.completionQueue.length > 0;
+    }
+    /**
+     * Drain all completion events (removes them from queue).
+     */
+    drainCompletionEvents() {
+        const events = [...this.completionQueue];
+        this.completionQueue.length = 0;
+        return events;
+    }
+    /**
+     * Peek at completion events without removing them.
+     */
+    peekCompletionEvents() {
+        return [...this.completionQueue];
+    }
+    // ===========================================================================
+    // Stats
+    // ===========================================================================
+    /**
+     * Get delegation statistics.
+     */
+    getStats() {
+        let pending = 0;
+        let running = 0;
+        let completed = 0;
+        let failed = 0;
+        let cancelled = 0;
+        for (const d of this.delegations.values()) {
+            switch (d.status) {
+                case 'pending':
+                    pending++;
+                    break;
+                case 'running':
+                    running++;
+                    break;
+                case 'completed':
+                    completed++;
+                    break;
+                case 'failed':
+                    failed++;
+                    break;
+                case 'cancelled':
+                    cancelled++;
+                    break;
+            }
+        }
+        return {
+            total: this.delegations.size,
+            pending,
+            running,
+            completed,
+            failed,
+            cancelled,
+        };
+    }
+    // ===========================================================================
+    // Cleanup
+    // ===========================================================================
+    /**
+     * Clear all delegations and completion events.
+     */
+    clear() {
+        this.delegations.clear();
+        this.completionQueue.length = 0;
+        this.emit('count-changed', this.getStats());
+    }
+}

package/dist/team/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Multi-agent team orchestration module
+ *
+ * Provides the complete team system for managing multiple persistent agents
+ * with shared context, artifacts, delegation tracking, and role-based access.
+ */
+export { AgentTeam } from './team.js';
+export type { AgentTeamConfig } from './team.js';
+export { TeamAgent } from './team-agent.js';
+export { SharedContextManager } from './shared-context.js';
+export type { SharedContext, SharedProjectInfo, SharedTeamInfo, TeamRosterEntry, TeamActivity, TeamActivityType, SharedDecision, TokenBudget, SerializedSharedContext, } from './shared-context.js';
+export { ArtifactStore } from './artifacts.js';
+export type { Artifact, ArtifactType, ArtifactSummary, CreateArtifactOptions, UpdateArtifactOptions, SerializedArtifact, } from './artifacts.js';
+export type { TeamAgentConfig, SerializedTeamAgent, TeamMetadata, SerializedTeam, TeamEvent, TeamEventType, TeamEventHandler, AgentRole, RoleMetadata, MascotExpression, ToolProfile, BackgroundSessionInfo, } from './types.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS } from './types.js';
+export { TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
+export type { ToolConfig, ToolTier, ToolGroup, ProfileInfo } from './tool-config.js';
+export { createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, } from './tool-config.js';
+export type { CustomAgentDefinition } from './custom-agents.js';
+export { CUSTOM_MASCOTS, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, } from './custom-agents.js';
+export type { ITeamPersistence, IArtifactStorage, ISessionRegistry } from './interfaces.js';
+export type { ParsedMention, ParsedInput } from './mention-parser.js';
+export { parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, } from './mention-parser.js';
+export type { ResolvedMention, ResolveOptions, ResolutionSource } from './context-resolver.js';
+export { ContextResolver, buildContextMap } from './context-resolver.js';
+export { findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, } from './agent-selection.js';
+export { suggestOwner, suggestOwners, matchesAgentExpertise } from './task-suggestion.js';
+export { wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, } from './task-assignment.js';
+export { DelegationTracker } from './delegation-tracker.js';
+export type { Delegation, DelegationStatus, DelegationResult, CompletionEvent, CreateDelegationOptions, DelegationStats, DelegationTrackerEvents, } from './delegation-tracker.js';
+export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity } from './activity.js';
+export type { SkillToolRequirement } from './skill-requirements.js';
+export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './skill-requirements.js';
+export { resolveAgentIdCollision } from './collision-utils.js';

package/dist/team/index.js

@@ -0,0 +1,30 @@
+/**
+ * Multi-agent team orchestration module
+ *
+ * Provides the complete team system for managing multiple persistent agents
+ * with shared context, artifacts, delegation tracking, and role-based access.
+ */
+// Core classes
+export { AgentTeam } from './team.js';
+export { TeamAgent } from './team-agent.js';
+export { SharedContextManager } from './shared-context.js';
+export { ArtifactStore } from './artifacts.js';
+export { ROLE_METADATA, ROLE_EXPERTISE, PREDEFINED_ROLE_IDS } from './types.js';
+// Tool configuration
+export { TOOL_GROUPS, TOOL_PROFILES, PROFILE_INFO, getToolsForProfile, detectProfileFromTools, isProfileReadOnly, generateToolAwarenessPrompt, generateCoordinatorGuidance, generateSpecialistGuidance, } from './tool-config.js';
+export { createDefaultToolConfig, validateToolConfig, getAllGroupIds, getGroupInfo, getGroupsByTier, getGroupsForProfile, } from './tool-config.js';
+export { CUSTOM_MASCOTS, assignMascot, generateCustomAgentSystemPrompt, getCustomAgentToolFilter, getCustomAgentProfileLabel, validateAgentId, isAgentIdTaken, createCustomAgentDefinition, } from './custom-agents.js';
+export { parseInputForMentions, getReferencedAgents, hasReferences, buildMessageWithContext, } from './mention-parser.js';
+export { ContextResolver, buildContextMap } from './context-resolver.js';
+// Agent selection
+export { findAgentForRole, findAgentById, getAvailableSpecialists, getSpecialistsSummary, hasSpecialists, } from './agent-selection.js';
+// Task management
+export { suggestOwner, suggestOwners, matchesAgentExpertise } from './task-suggestion.js';
+export { wouldCreateLoop, recordAssignment, getAssignmentHistory, clearAssignmentHistory, clearAllAssignmentHistory, canReassign, } from './task-assignment.js';
+// Delegation tracking
+export { DelegationTracker } from './delegation-tracker.js';
+// Activity recording
+export { setActiveSharedContext, getActiveSharedContext, recordTeamActivity } from './activity.js';
+export { SKILL_REQUIREMENTS, getDefinedSkillNames, getSkillRequirements, checkSkillCompatibility, getCompatibleSkills, getAllRequiredTools, getSkillsByCategory, } from './skill-requirements.js';
+// Collision utils
+export { resolveAgentIdCollision } from './collision-utils.js';

package/dist/team/interfaces.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Abstraction interfaces for team persistence and storage.
+ *
+ * Consumers (CLI, Desktop) implement these to provide
+ * platform-specific persistence (filesystem, SQLite, IDB, etc.)
+ */
+import type { SerializedTeam } from './types.js';
+import type { Artifact, SerializedArtifact } from './artifacts.js';
+/**
+ * Persistence for team state (serialization/restore)
+ */
+export interface ITeamPersistence {
+    saveTeam(team: SerializedTeam): Promise<void>;
+    loadTeam(teamId: string): Promise<SerializedTeam | null>;
+}
+/**
+ * Storage for team artifacts
+ */
+export interface IArtifactStorage {
+    read(id: string): Promise<Artifact | null>;
+    write(artifact: Artifact): Promise<void>;
+    list(): Promise<Artifact[]>;
+    delete(id: string): Promise<void>;
+}
+/**
+ * Serialized artifact data for persistence
+ */
+export type { SerializedArtifact };
+/**
+ * Session registry for cross-terminal collision detection.
+ * CLI provides this via SQLite; desktop/other consumers may omit it.
+ */
+export interface ISessionRegistry {
+    /** Get all agent IDs currently in use across all terminals */
+    getGlobalAgentIds(): string[];
+}

package/dist/team/interfaces.js

@@ -0,0 +1,7 @@
+/**
+ * Abstraction interfaces for team persistence and storage.
+ *
+ * Consumers (CLI, Desktop) implement these to provide
+ * platform-specific persistence (filesystem, SQLite, IDB, etc.)
+ */
+export {};

package/dist/team/mention-parser.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MentionParser - Parse $agent references in user input
+ *
+ * Two types of $agent usage:
+ * 1. Switch: "$arch message" at start of input → switch to arch, send message
+ * 2. Reference: "what did $arch propose" mid-sentence → inject arch's context
+ *
+ * Detection rule: $name at START of trimmed input = switch. Otherwise = reference.
+ */
+/**
+ * A parsed mention in the input
+ */
+export interface ParsedMention {
+    /** Agent ID without $ prefix */
+    agentId: string;
+    /** Position in original input */
+    startIndex: number;
+    endIndex: number;
+    /** The full match including $ prefix */
+    raw: string;
+    /** Optional query/context after the agent name */
+    context?: string;
+}
+/**
+ * Result of parsing user input for mentions
+ */
+export interface ParsedInput {
+    /** Original input text */
+    original: string;
+    /** Whether the input starts with a switch ($agent at beginning) */
+    hasSwitch: boolean;
+    /** The switch target agent (if hasSwitch is true) */
+    switchTarget?: string;
+    /** Message to send after switching (if hasSwitch is true) */
+    messageAfterSwitch?: string;
+    /** All reference mentions (mid-sentence $agent) */
+    references: ParsedMention[];
+    /** Input with mentions replaced by placeholders for context injection */
+    normalizedInput: string;
+}
+/**
+ * Parse user input for $agent mentions
+ *
+ * @param input - User input string
+ * @param validAgents - Set of valid agent IDs (for validation)
+ * @returns Parsed input with mentions identified
+ */
+export declare function parseInputForMentions(input: string, validAgents?: Set<string>): ParsedInput;
+/**
+ * Get unique agent IDs from references
+ */
+export declare function getReferencedAgents(parsed: ParsedInput): string[];
+/**
+ * Check if input contains any references (not just switch)
+ */
+export declare function hasReferences(parsed: ParsedInput): boolean;
+/**
+ * Build a message with context injected for mentions
+ *
+ * @param parsed - Parsed input
+ * @param contextMap - Map of agentId → resolved context string
+ * @returns Message with context prepended or injected
+ */
+export declare function buildMessageWithContext(parsed: ParsedInput, contextMap: Map<string, string>): string;

package/dist/team/mention-parser.js

@@ -0,0 +1,138 @@
+/**
+ * MentionParser - Parse $agent references in user input
+ *
+ * Two types of $agent usage:
+ * 1. Switch: "$arch message" at start of input → switch to arch, send message
+ * 2. Reference: "what did $arch propose" mid-sentence → inject arch's context
+ *
+ * Detection rule: $name at START of trimmed input = switch. Otherwise = reference.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+// Match $agentname pattern - alphanumeric and underscore/hyphen
+const MENTION_PATTERN = /\$([a-zA-Z][a-zA-Z0-9_-]*)/g;
+// Match $agent at start of input (for switch detection)
+const SWITCH_PATTERN = /^\$([a-zA-Z][a-zA-Z0-9_-]*)\s*/;
+// =============================================================================
+// Parser
+// =============================================================================
+/**
+ * Parse user input for $agent mentions
+ *
+ * @param input - User input string
+ * @param validAgents - Set of valid agent IDs (for validation)
+ * @returns Parsed input with mentions identified
+ */
+export function parseInputForMentions(input, validAgents) {
+    const trimmed = input.trim();
+    // Check for switch pattern at start
+    const switchMatch = trimmed.match(SWITCH_PATTERN);
+    let hasSwitch = false;
+    let switchTarget;
+    let messageAfterSwitch;
+    let searchStart = 0;
+    if (switchMatch) {
+        const agentId = switchMatch[1].toLowerCase();
+        // Only treat as switch if it's a valid agent
+        if (!validAgents || validAgents.has(agentId)) {
+            hasSwitch = true;
+            switchTarget = agentId;
+            messageAfterSwitch = trimmed.slice(switchMatch[0].length).trim();
+            searchStart = switchMatch[0].length; // Skip switch when looking for references
+        }
+    }
+    // Find all reference mentions (excluding the switch)
+    const references = [];
+    MENTION_PATTERN.lastIndex = searchStart;
+    let match;
+    while ((match = MENTION_PATTERN.exec(trimmed)) !== null) {
+        const agentId = match[1].toLowerCase();
+        // Skip if not a valid agent (if validation set provided)
+        if (validAgents && !validAgents.has(agentId)) {
+            continue;
+        }
+        // Skip if this is the switch mention
+        if (hasSwitch && match.index === 0) {
+            continue;
+        }
+        references.push({
+            agentId,
+            startIndex: match.index,
+            endIndex: match.index + match[0].length,
+            raw: match[0],
+        });
+    }
+    // Extract context hints for each reference
+    for (const ref of references) {
+        ref.context = extractContextHint(trimmed, ref.endIndex);
+    }
+    // Build normalized input (with mention placeholders)
+    const normalizedInput = hasSwitch ? (messageAfterSwitch ?? '') : trimmed;
+    return {
+        original: input,
+        hasSwitch,
+        switchTarget,
+        messageAfterSwitch,
+        references,
+        normalizedInput,
+    };
+}
+/**
+ * Extract a context hint following a mention
+ *
+ * Examples:
+ * - "what did $arch propose for the API" → "propose for the API"
+ * - "review $qa's feedback on the PR" → "'s feedback on the PR"
+ * - "based on $arch" → undefined
+ */
+function extractContextHint(text, afterIndex) {
+    const remaining = text.slice(afterIndex);
+    // Get up to end of sentence or 50 chars
+    const endMatch = remaining.match(/^[^.!?\n]{0,50}/);
+    if (!endMatch || endMatch[0].trim().length < 3) {
+        return undefined;
+    }
+    return endMatch[0].trim();
+}
+/**
+ * Get unique agent IDs from references
+ */
+export function getReferencedAgents(parsed) {
+    const agents = new Set();
+    for (const ref of parsed.references) {
+        agents.add(ref.agentId);
+    }
+    return Array.from(agents);
+}
+/**
+ * Check if input contains any references (not just switch)
+ */
+export function hasReferences(parsed) {
+    return parsed.references.length > 0;
+}
+/**
+ * Build a message with context injected for mentions
+ *
+ * @param parsed - Parsed input
+ * @param contextMap - Map of agentId → resolved context string
+ * @returns Message with context prepended or injected
+ */
+export function buildMessageWithContext(parsed, contextMap) {
+    if (parsed.references.length === 0) {
+        return parsed.normalizedInput;
+    }
+    // Collect context blocks
+    const contextBlocks = [];
+    for (const ref of parsed.references) {
+        const context = contextMap.get(ref.agentId);
+        if (context) {
+            contextBlocks.push(`[Context from $${ref.agentId}:\n${context}\n]`);
+        }
+    }
+    if (contextBlocks.length === 0) {
+        return parsed.normalizedInput;
+    }
+    // Prepend context blocks to the message
+    return `${contextBlocks.join('\n\n')}\n\n${parsed.normalizedInput}`;
+}