@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/agent-manager.js

@@ -0,0 +1,749 @@
+/**
+ * Agent manager service for discovering, parsing, and managing agents.
+ *
+ * Agents are defined as Markdown files with YAML frontmatter in:
+ * - .compass/agents/ (project-level, highest priority)
+ * - ~/.compass/agents/ (user-level)
+ *
+ * Agents can also be passed via CLI --agents flag or are built-in defaults.
+ *
+ * Priority order (highest to lowest):
+ * 1. Project agents
+ * 2. CLI agents
+ * 3. User agents
+ * 4. Built-in agents
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { glob } from 'glob';
+import { v4 as uuidv4 } from 'uuid';
+import { getGlobalCompassDir, getProjectCompassDir } from '../utils/path.js';
+import { AGENTS_DIR, MAX_AGENT_DEPTH } from '../constants/defaults.js';
+import { BUILTIN_AGENTS } from '../constants/builtin-agents.js';
+import { logger } from '../utils/logger.js';
+import { AGENT_SOURCE_PRIORITY, isValidAgentFrontmatter, parseToolsList, } from '../types/agent.js';
+import { normalizeToolsList } from '../utils/tool-mapper.js';
+// =============================================================================
+// Module State
+// =============================================================================
+/** Cache for discovered agents */
+let cachedAgents = null;
+let cacheTimestamp = 0;
+const CACHE_TTL_MS = 5000; // 5 seconds
+/** CLI agents registered via --agents flag */
+let cliAgents = [];
+/** Current project root for agent discovery */
+let currentProjectRoot = process.cwd();
+// =============================================================================
+// Path Utilities
+// =============================================================================
+/**
+ * Gets the project agents directory path.
+ * Uses the currentProjectRoot set via setProjectRoot() or --cwd flag.
+ */
+export function getProjectAgentsDir() {
+    return path.join(getProjectCompassDir(currentProjectRoot), AGENTS_DIR);
+}
+/**
+ * Gets the user agents directory path.
+ */
+export function getUserAgentsDir() {
+    return path.join(getGlobalCompassDir(), AGENTS_DIR);
+}
+/**
+ * Sets the project root for agent discovery.
+ */
+export function setProjectRoot(projectRoot) {
+    if (currentProjectRoot !== projectRoot) {
+        currentProjectRoot = projectRoot;
+        invalidateAgentCache();
+    }
+}
+/**
+ * Gets the current project root.
+ * Returns the value set via setProjectRoot() or --cwd flag, defaulting to process.cwd().
+ */
+export function getProjectRoot() {
+    return currentProjectRoot;
+}
+// =============================================================================
+// Permission Mode Mapping
+// =============================================================================
+/**
+ * Maps Anthropic permission modes to Compass permission modes.
+ *
+ * Anthropic modes: default, acceptEdits, dontAsk, bypassPermissions, plan
+ * Compass modes: default, acceptEditsAsk, bypassPermissions, plan, ignore
+ *
+ * @param mode - Permission mode (Anthropic or Compass format)
+ * @returns Compass-compatible permission mode
+ */
+function normalizePermissionMode(mode) {
+    // Direct matches (Compass modes)
+    const compassModes = [
+        'default',
+        'acceptEditsAsk',
+        'bypassPermissions',
+        'plan',
+        'ignore',
+    ];
+    if (compassModes.includes(mode)) {
+        return mode;
+    }
+    // Map Anthropic modes to Compass modes
+    const anthropicToCompass = {
+        'acceptEdits': 'acceptEditsAsk', // Anthropic's acceptEdits -> Compass's acceptEditsAsk
+        'dontAsk': 'bypassPermissions', // Anthropic's dontAsk -> Compass's bypassPermissions
+    };
+    return anthropicToCompass[mode] || 'default';
+}
+// =============================================================================
+// Frontmatter Parsing
+// =============================================================================
+/**
+ * Parses YAML frontmatter from markdown content.
+ * Uses a simple regex-based approach for portability.
+ *
+ * @param content - The markdown file content
+ * @returns Object containing parsed frontmatter and system prompt (body)
+ */
+export function parseAgentFrontmatter(content) {
+    const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        return { frontmatter: {}, systemPrompt: content };
+    }
+    const [, yamlContent, body] = match;
+    const frontmatter = {};
+    // Parse simple YAML key-value pairs
+    const lines = yamlContent.split(/\r?\n/);
+    for (const line of lines) {
+        // Skip empty lines and comments
+        if (!line.trim() || line.trim().startsWith('#')) {
+            continue;
+        }
+        // Check for key-value pair
+        const kvMatch = line.match(/^([a-zA-Z-]+):\s*(.*)$/);
+        if (kvMatch) {
+            const [, key, value] = kvMatch;
+            let parsedValue = value.trim();
+            // Remove quotes if present
+            parsedValue = parsedValue.replace(/^["']|["']$/g, '');
+            // Map key to frontmatter property
+            switch (key.toLowerCase()) {
+                case 'name':
+                    frontmatter.name = parsedValue;
+                    break;
+                case 'description':
+                    frontmatter.description = parsedValue;
+                    break;
+                case 'tools':
+                    frontmatter.tools = parsedValue;
+                    break;
+                case 'disallowedtools':
+                case 'disallowed-tools':
+                case 'disallowedTools':
+                    frontmatter.disallowedTools = parsedValue;
+                    break;
+                case 'model':
+                    frontmatter.model = parsedValue;
+                    break;
+                case 'permissionmode':
+                case 'permissionMode':
+                case 'permission-mode':
+                    frontmatter.permissionMode = normalizePermissionMode(parsedValue);
+                    break;
+                case 'skills':
+                    frontmatter.skills = parsedValue;
+                    break;
+                case 'standalone':
+                    frontmatter.standalone = parsedValue.toLowerCase() === 'true';
+                    break;
+                case 'mcpservers':
+                case 'mcp-servers':
+                case 'mcpServers':
+                    frontmatter.mcpServers = parsedValue;
+                    break;
+            }
+        }
+    }
+    return { frontmatter, systemPrompt: body.trim() };
+}
+/**
+ * Serializes agent frontmatter to YAML string.
+ */
+export function serializeAgentFrontmatter(frontmatter) {
+    const lines = ['---'];
+    lines.push(`name: ${frontmatter.name}`);
+    lines.push(`description: ${frontmatter.description}`);
+    if (frontmatter.tools) {
+        lines.push(`tools: ${frontmatter.tools}`);
+    }
+    if (frontmatter.disallowedTools) {
+        lines.push(`disallowedTools: ${frontmatter.disallowedTools}`);
+    }
+    if (frontmatter.model) {
+        lines.push(`model: ${frontmatter.model}`);
+    }
+    if (frontmatter.permissionMode && frontmatter.permissionMode !== 'default') {
+        lines.push(`permissionMode: ${frontmatter.permissionMode}`);
+    }
+    if (frontmatter.skills) {
+        lines.push(`skills: ${frontmatter.skills}`);
+    }
+    if (frontmatter.standalone) {
+        lines.push(`standalone: true`);
+    }
+    if (frontmatter.mcpServers) {
+        lines.push(`mcpServers: ${frontmatter.mcpServers}`);
+    }
+    lines.push('---');
+    return lines.join('\n');
+}
+/**
+ * Serializes a complete agent to markdown format.
+ */
+export function serializeAgent(agent) {
+    const frontmatter = serializeAgentFrontmatter(agent.rawFrontmatter);
+    return `${frontmatter}\n\n${agent.systemPrompt}`;
+}
+// =============================================================================
+// Agent File Parsing
+// =============================================================================
+/**
+ * Parses an agent file and creates an AgentDefinition.
+ *
+ * @param filePath - Absolute path to the .md file
+ * @param source - Where this agent was found
+ * @returns Parsed agent definition
+ */
+export async function parseAgentFile(filePath, source) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const { frontmatter, systemPrompt } = parseAgentFrontmatter(content);
+        // Validate required fields
+        if (!frontmatter.name || !frontmatter.description) {
+            logger.warn(`Agent file missing required fields (name, description): ${filePath}`);
+            return null;
+        }
+        if (!isValidAgentFrontmatter(frontmatter)) {
+            const issues = [];
+            // Check required fields
+            if (typeof frontmatter.name !== 'string' || frontmatter.name.length === 0) {
+                issues.push('missing or empty "name" field');
+            }
+            if (typeof frontmatter.description !== 'string' || frontmatter.description.length === 0) {
+                issues.push('missing or empty "description" field');
+            }
+            // Check optional field types
+            if (frontmatter.tools !== undefined && typeof frontmatter.tools !== 'string') {
+                issues.push(`"tools" must be a string, got ${typeof frontmatter.tools}`);
+            }
+            if (frontmatter.model !== undefined && typeof frontmatter.model !== 'string') {
+                issues.push(`"model" must be a string, got ${typeof frontmatter.model}`);
+            }
+            if (frontmatter.permissionMode !== undefined) {
+                const validModes = [
+                    // Compass modes
+                    'default', 'acceptEditsAsk', 'bypassPermissions', 'plan', 'ignore',
+                    // Anthropic modes (for compatibility)
+                    'acceptEdits', 'dontAsk'
+                ];
+                if (!validModes.includes(frontmatter.permissionMode)) {
+                    issues.push(`"permissionMode" must be one of: ${validModes.join(', ')} (got "${frontmatter.permissionMode}")`);
+                }
+            }
+            if (frontmatter.skills !== undefined && typeof frontmatter.skills !== 'string') {
+                issues.push(`"skills" must be a string, got ${typeof frontmatter.skills}`);
+            }
+            if (frontmatter.standalone !== undefined && typeof frontmatter.standalone !== 'boolean') {
+                issues.push(`"standalone" must be a boolean, got ${typeof frontmatter.standalone}`);
+            }
+            if (frontmatter.mcpServers !== undefined && typeof frontmatter.mcpServers !== 'string') {
+                issues.push(`"mcpServers" must be a string, got ${typeof frontmatter.mcpServers}`);
+            }
+            logger.warn(`Invalid agent frontmatter in: ${filePath}\nIssues: ${issues.join(', ')}`);
+            return null;
+        }
+        const validFrontmatter = frontmatter;
+        // Parse and normalize tool lists (supports both Nova and Roo-Cline/Claude.dev formats)
+        const parsedAllowedTools = parseToolsList(validFrontmatter.tools);
+        const parsedDisallowedTools = parseToolsList(validFrontmatter.disallowedTools);
+        return {
+            id: `${source}-${validFrontmatter.name}`,
+            name: validFrontmatter.name,
+            description: validFrontmatter.description,
+            systemPrompt,
+            source,
+            filePath,
+            allowedTools: normalizeToolsList(parsedAllowedTools, true),
+            disallowedTools: normalizeToolsList(parsedDisallowedTools, true),
+            model: validFrontmatter.model,
+            permissionMode: validFrontmatter.permissionMode || 'default',
+            skills: parseToolsList(validFrontmatter.skills),
+            standalone: validFrontmatter.standalone,
+            mcpServers: parseToolsList(validFrontmatter.mcpServers),
+            isActive: true, // Will be updated during priority resolution
+            rawFrontmatter: validFrontmatter,
+        };
+    }
+    catch (error) {
+        logger.warn(`Failed to parse agent file: ${filePath}`, error);
+        return null;
+    }
+}
+// =============================================================================
+// Agent Discovery
+// =============================================================================
+/**
+ * Discovers agents from a specific directory.
+ *
+ * @param directory - Directory to search
+ * @param source - Source type for discovered agents
+ * @returns Array of discovered agents
+ */
+async function discoverAgentsInDirectory(directory, source) {
+    const agents = [];
+    if (!(await fs.pathExists(directory))) {
+        return agents;
+    }
+    try {
+        const files = await glob('**/*.md', {
+            cwd: directory,
+            nodir: true,
+            absolute: true,
+        });
+        for (const filePath of files) {
+            const agent = await parseAgentFile(filePath, source);
+            if (agent) {
+                agents.push(agent);
+                logger.debug(`Discovered ${source} agent: ${agent.name}`, {
+                    path: filePath,
+                    model: agent.model,
+                    tools: agent.allowedTools?.length ?? 'all',
+                });
+            }
+        }
+    }
+    catch (error) {
+        logger.warn(`Failed to discover agents in ${directory}`, error);
+    }
+    return agents;
+}
+/**
+ * Resolves agent priorities and marks inactive agents.
+ *
+ * @param agents - All discovered agents
+ * @returns Discovery result with priority resolution
+ */
+function resolveAgentPriorities(agents) {
+    const bySource = {
+        project: [],
+        cli: [],
+        user: [],
+        builtin: [],
+    };
+    // Group by source
+    for (const agent of agents) {
+        bySource[agent.source].push(agent);
+    }
+    // Build active agents map (higher priority wins)
+    const activeByName = new Map();
+    const overrides = new Map();
+    // Process in priority order (lowest first, so higher overwrites)
+    for (const source of AGENT_SOURCE_PRIORITY) {
+        for (const agent of bySource[source]) {
+            const existing = activeByName.get(agent.name.toLowerCase());
+            if (existing) {
+                overrides.set(existing.id, agent.id);
+            }
+            activeByName.set(agent.name.toLowerCase(), agent);
+        }
+    }
+    // Mark active status on all agents
+    const active = [];
+    for (const agent of agents) {
+        const isActive = activeByName.get(agent.name.toLowerCase())?.id === agent.id;
+        agent.isActive = isActive;
+        if (isActive) {
+            active.push(agent);
+        }
+    }
+    return {
+        all: agents,
+        active,
+        bySource,
+        overrides,
+    };
+}
+/**
+ * Discovers all agents from all sources.
+ *
+ * @param forceRefresh - Force refresh the cache
+ * @returns Discovery result with all agents
+ */
+export async function discoverAgents(forceRefresh = false) {
+    // Check cache
+    if (!forceRefresh && cachedAgents && Date.now() - cacheTimestamp < CACHE_TTL_MS) {
+        return cachedAgents;
+    }
+    const allAgents = [];
+    // 1. Built-in agents (lowest priority)
+    allAgents.push(...BUILTIN_AGENTS.map((agent) => ({ ...agent })));
+    // 2. User agents
+    const userAgents = await discoverAgentsInDirectory(getUserAgentsDir(), 'user');
+    allAgents.push(...userAgents);
+    // 3. CLI agents
+    allAgents.push(...cliAgents);
+    // 4. Project agents (highest priority)
+    const projectAgents = await discoverAgentsInDirectory(getProjectAgentsDir(), 'project');
+    allAgents.push(...projectAgents);
+    // Resolve priorities
+    const result = resolveAgentPriorities(allAgents);
+    // Update cache
+    cachedAgents = result;
+    cacheTimestamp = Date.now();
+    logger.info(`Discovered ${result.active.length} active agents (${result.all.length} total)`);
+    return result;
+}
+/**
+ * Invalidates the agent cache.
+ */
+export function invalidateAgentCache() {
+    cachedAgents = null;
+    cacheTimestamp = 0;
+}
+// =============================================================================
+// CLI Agents
+// =============================================================================
+/**
+ * Registers agents from CLI --agents flag.
+ *
+ * @param agentsMap - Map of agent names to configurations
+ */
+export function registerCLIAgents(agentsMap) {
+    cliAgents = [];
+    for (const [name, config] of Object.entries(agentsMap)) {
+        if (!config.description || !config.prompt) {
+            logger.warn(`CLI agent "${name}" missing required fields (description, prompt)`);
+            continue;
+        }
+        // Normalize tool lists (supports both Nova and Roo-Cline/Claude.dev formats)
+        const normalizedAllowedTools = normalizeToolsList(config.tools, true);
+        const normalizedDisallowedTools = normalizeToolsList(config.disallowedTools, true);
+        const agent = {
+            id: `cli-${name}`,
+            name,
+            description: config.description,
+            systemPrompt: config.prompt,
+            source: 'cli',
+            allowedTools: normalizedAllowedTools,
+            disallowedTools: normalizedDisallowedTools,
+            model: config.model,
+            permissionMode: config.permissionMode || 'default',
+            skills: config.skills,
+            standalone: config.standalone,
+            mcpServers: config.mcpServers,
+            isActive: true,
+            rawFrontmatter: {
+                name,
+                description: config.description,
+                tools: normalizedAllowedTools ? normalizedAllowedTools.join(', ') : undefined,
+                disallowedTools: normalizedDisallowedTools ? normalizedDisallowedTools.join(', ') : undefined,
+                model: config.model,
+                permissionMode: config.permissionMode,
+                skills: config.skills ? config.skills.join(', ') : undefined,
+                standalone: config.standalone,
+                mcpServers: config.mcpServers ? config.mcpServers.join(', ') : undefined,
+            },
+        };
+        cliAgents.push(agent);
+        logger.debug(`Registered CLI agent: ${name}`);
+    }
+    invalidateAgentCache();
+}
+/**
+ * Clears all CLI agents.
+ */
+export function clearCLIAgents() {
+    cliAgents = [];
+    invalidateAgentCache();
+}
+// =============================================================================
+// Agent Lookup
+// =============================================================================
+/**
+ * Gets all active agents.
+ */
+export async function getActiveAgents() {
+    const result = await discoverAgents();
+    return result.active;
+}
+/**
+ * Gets an agent by name (only active agents).
+ */
+export async function getAgentByName(name) {
+    const result = await discoverAgents();
+    return result.active.find((agent) => agent.name.toLowerCase() === name.toLowerCase());
+}
+/**
+ * Gets an agent by ID (includes inactive agents).
+ */
+export async function getAgentById(id) {
+    const result = await discoverAgents();
+    return result.all.find((agent) => agent.id === id);
+}
+/**
+ * Checks if an agent exists (active only).
+ */
+export async function hasAgent(name) {
+    const agent = await getAgentByName(name);
+    return agent !== undefined;
+}
+/**
+ * Determines the safety tier label for an agent based on its allowed tools.
+ */
+function getAgentSafetyTier(agent) {
+    if (!agent.allowedTools) {
+        return 'all tools';
+    }
+    const tools = new Set(agent.allowedTools.map(t => t.toLowerCase()));
+    const hasEdit = tools.has('edit') || tools.has('write');
+    const hasBash = tools.has('bash');
+    if (!hasEdit && !hasBash)
+        return 'read-only';
+    if (!hasEdit && hasBash)
+        return 'read + inspect';
+    if (hasEdit && hasBash)
+        return 'read + write + execute';
+    return 'read + write';
+}
+/**
+ * Formats active agents as a list for inclusion in system prompts.
+ * Returns a formatted string describing available sub-agents for task delegation.
+ * Includes safety tier and budget information to help the LLM make informed decisions.
+ */
+export async function formatAgentsForPrompt() {
+    const { DEFAULT_AGENT_BUDGETS } = await import('./agent-budget-allocator.js');
+    const agents = await getActiveAgents();
+    if (agents.length === 0) {
+        return 'No specialized sub-agents are currently available.';
+    }
+    const agentDescriptions = agents.map(agent => {
+        const budget = DEFAULT_AGENT_BUDGETS[agent.name] || DEFAULT_AGENT_BUDGETS['default'];
+        const tier = getAgentSafetyTier(agent);
+        const model = agent.model || 'sonnet';
+        return `- **${agent.name}** [${tier}, ${model}, ${budget.maxTurns} turns]: ${agent.description}`;
+    }).join('\n');
+    return `The following specialized sub-agents are available via \`spawn_task\`:
+${agentDescriptions}
+
+Agents marked **read-only** cannot run shell commands — provide any needed diffs, logs, or CLI output in the \`context\` parameter.`;
+}
+// =============================================================================
+// Agent CRUD Operations
+// =============================================================================
+/**
+ * Creates a new agent file.
+ *
+ * @param agent - Agent definition to create
+ * @param location - Where to save ('project' or 'user')
+ * @returns The created agent's file path
+ */
+export async function createAgent(agent, location = 'project') {
+    const baseDir = location === 'project' ? getProjectAgentsDir() : getUserAgentsDir();
+    const fileName = `${agent.name}.md`;
+    const filePath = path.join(baseDir, fileName);
+    // Ensure directory exists
+    await fs.ensureDir(baseDir);
+    // Check if file already exists
+    if (await fs.pathExists(filePath)) {
+        throw new Error(`Agent file already exists: ${filePath}`);
+    }
+    // Build frontmatter
+    const frontmatter = {
+        name: agent.name,
+        description: agent.description,
+        tools: agent.allowedTools ? agent.allowedTools.join(', ') : undefined,
+        disallowedTools: agent.disallowedTools ? agent.disallowedTools.join(', ') : undefined,
+        model: agent.model,
+        permissionMode: agent.permissionMode !== 'default' ? agent.permissionMode : undefined,
+        skills: agent.skills ? agent.skills.join(', ') : undefined,
+    };
+    // Serialize and write
+    const content = `${serializeAgentFrontmatter(frontmatter)}\n\n${agent.systemPrompt}`;
+    await fs.writeFile(filePath, content, 'utf-8');
+    logger.info(`Created agent: ${agent.name} at ${filePath}`);
+    invalidateAgentCache();
+    return filePath;
+}
+/**
+ * Updates an existing agent.
+ *
+ * @param agentId - ID of the agent to update
+ * @param updates - Fields to update
+ */
+export async function updateAgent(agentId, updates) {
+    const agent = await getAgentById(agentId);
+    if (!agent) {
+        throw new Error(`Agent not found: ${agentId}`);
+    }
+    if (!agent.filePath) {
+        throw new Error(`Cannot update ${agent.source} agent "${agent.name}" - no file path`);
+    }
+    if (agent.source === 'builtin' || agent.source === 'cli') {
+        throw new Error(`Cannot update ${agent.source} agent "${agent.name}"`);
+    }
+    // Apply updates (normalize tool names if provided)
+    const normalizedAllowedTools = updates.tools ? normalizeToolsList(updates.tools, true) : undefined;
+    const normalizedDisallowedTools = updates.disallowedTools ? normalizeToolsList(updates.disallowedTools, true) : undefined;
+    const updatedAgent = {
+        ...agent,
+        description: updates.description ?? agent.description,
+        systemPrompt: updates.systemPrompt ?? agent.systemPrompt,
+        allowedTools: normalizedAllowedTools ?? agent.allowedTools,
+        disallowedTools: normalizedDisallowedTools ?? agent.disallowedTools,
+        model: updates.model ?? agent.model,
+        permissionMode: updates.permissionMode ?? agent.permissionMode,
+        skills: updates.skills ?? agent.skills,
+        rawFrontmatter: {
+            ...agent.rawFrontmatter,
+            description: updates.description ?? agent.rawFrontmatter.description,
+            tools: normalizedAllowedTools ? normalizedAllowedTools.join(', ') : agent.rawFrontmatter.tools,
+            disallowedTools: normalizedDisallowedTools ? normalizedDisallowedTools.join(', ') : agent.rawFrontmatter.disallowedTools,
+            model: updates.model ?? agent.rawFrontmatter.model,
+            permissionMode: updates.permissionMode ?? agent.rawFrontmatter.permissionMode,
+            skills: updates.skills ? updates.skills.join(', ') : agent.rawFrontmatter.skills,
+        },
+    };
+    // Write updated content
+    const content = serializeAgent(updatedAgent);
+    await fs.writeFile(agent.filePath, content, 'utf-8');
+    logger.info(`Updated agent: ${agent.name}`);
+    invalidateAgentCache();
+}
+/**
+ * Deletes an agent file.
+ *
+ * @param agentId - ID of the agent to delete
+ */
+export async function deleteAgent(agentId) {
+    const agent = await getAgentById(agentId);
+    if (!agent) {
+        throw new Error(`Agent not found: ${agentId}`);
+    }
+    if (!agent.filePath) {
+        throw new Error(`Cannot delete ${agent.source} agent "${agent.name}" - no file path`);
+    }
+    if (agent.source === 'builtin') {
+        throw new Error(`Cannot delete built-in agent "${agent.name}"`);
+    }
+    if (agent.source === 'cli') {
+        throw new Error(`Cannot delete CLI agent "${agent.name}" - it was passed via --agents flag`);
+    }
+    await fs.remove(agent.filePath);
+    logger.info(`Deleted agent: ${agent.name} from ${agent.filePath}`);
+    invalidateAgentCache();
+}
+// =============================================================================
+// Execution Context
+// =============================================================================
+/**
+ * Creates an execution context for an agent.
+ *
+ * @param agent - The agent to execute
+ * @param parentContext - Optional parent context for sub-agents
+ * @returns Execution context
+ */
+export function createExecutionContext(agent, parentContext) {
+    const depth = parentContext ? parentContext.depth + 1 : 0;
+    const parentChain = parentContext
+        ? [...parentContext.parentChain, parentContext.agent.name]
+        : [];
+    return {
+        agent,
+        executionId: uuidv4(),
+        parentAgentId: parentContext?.executionId,
+        parentChain,
+        depth,
+        maxDepth: MAX_AGENT_DEPTH,
+    };
+}
+/**
+ * Validates an execution context for cycle detection.
+ *
+ * @param context - Context to validate
+ * @returns Error message if invalid, undefined if valid
+ */
+export function validateExecutionContext(context) {
+    // Check depth limit
+    if (context.depth > context.maxDepth) {
+        return `Maximum agent nesting depth (${context.maxDepth}) exceeded`;
+    }
+    // Check for cycles (same agent appearing twice in chain)
+    if (context.parentChain.includes(context.agent.name)) {
+        return `Circular agent reference detected: ${context.agent.name} already in chain [${context.parentChain.join(' -> ')}]`;
+    }
+    return undefined;
+}
+// =============================================================================
+// Initialization
+// =============================================================================
+/**
+ * Initializes the agent manager.
+ *
+ * @param projectRoot - Project root directory
+ * @param cliAgentsJson - Optional CLI agents JSON string
+ */
+export async function initializeAgentManager(projectRoot, cliAgentsJson) {
+    setProjectRoot(projectRoot);
+    // Parse CLI agents if provided
+    if (cliAgentsJson) {
+        try {
+            const parsed = JSON.parse(cliAgentsJson);
+            registerCLIAgents(parsed);
+        }
+        catch (error) {
+            logger.error('Failed to parse --agents JSON', error);
+            throw new Error(`Invalid --agents JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    // Pre-warm the cache
+    await discoverAgents(true);
+}
+// =============================================================================
+// Export Default
+// =============================================================================
+export default {
+    // Path utilities
+    getProjectAgentsDir,
+    getUserAgentsDir,
+    setProjectRoot,
+    getProjectRoot,
+    // Discovery
+    discoverAgents,
+    invalidateAgentCache,
+    // CLI agents
+    registerCLIAgents,
+    clearCLIAgents,
+    // Lookup
+    getActiveAgents,
+    getAgentByName,
+    getAgentById,
+    hasAgent,
+    // CRUD
+    createAgent,
+    updateAgent,
+    deleteAgent,
+    // Execution
+    createExecutionContext,
+    validateExecutionContext,
+    // Initialization
+    initializeAgentManager,
+    // Parsing utilities
+    parseAgentFrontmatter,
+    parseAgentFile,
+    serializeAgent,
+    serializeAgentFrontmatter,
+};
+//# sourceMappingURL=agent-manager.js.map