@compass-ai/nova 1.0.73 → 1.0.74

package/dist/services/agent-budget-allocator.js

@@ -0,0 +1,278 @@
+/**
+ * Agent Budget Allocator Service
+ *
+ * Manages budget allocation for agent processes, enforcing token and turn limits
+ * to prevent context bloat. Supports multiple allocation strategies.
+ */
+import { logger } from '../utils/logger.js';
+import { createDefaultBudget, getRemainingBudget, getBudgetUsagePercent, isBudgetExceeded, } from '../types/agent-process.js';
+// =============================================================================
+// Default Budgets by Agent Type
+// =============================================================================
+/**
+ * Default budget configurations for different agent types.
+ * These are tuned based on typical task complexity for each agent.
+ */
+export const DEFAULT_AGENT_BUDGETS = {
+    // Fast exploration - moderate context, quick iterations
+    'explore': {
+        maxTokens: 100000,
+        maxTurns: 15,
+        tokensUsed: 0,
+        turnsUsed: 0,
+    },
+    // Code review - generous context for reviewing files
+    'code-reviewer': {
+        maxTokens: 120000,
+        maxTurns: 20,
+        tokensUsed: 0,
+        turnsUsed: 0,
+    },
+    // Debugging - larger context for tracing issues
+    'debugger': {
+        maxTokens: 100000,
+        maxTurns: 25,
+        tokensUsed: 0,
+        turnsUsed: 0,
+    },
+    // Planning - needs generous context for codebase exploration and detailed plans
+    'planner': {
+        maxTokens: 100000,
+        maxTurns: 20,
+        tokensUsed: 0,
+        turnsUsed: 0,
+    },
+    // Default for unspecified agent types
+    'default': {
+        maxTokens: 120000,
+        maxTurns: 25,
+        tokensUsed: 0,
+        turnsUsed: 0,
+    },
+};
+/**
+ * Warning thresholds for budget consumption (percentage).
+ */
+export const BUDGET_WARNING_THRESHOLDS = {
+    /** First warning at 70% consumption */
+    WARNING: 70,
+    /** Critical warning at 90% consumption */
+    CRITICAL: 90,
+};
+// =============================================================================
+// Budget Allocator Class
+// =============================================================================
+/**
+ * Service for allocating and managing agent budgets.
+ */
+class AgentBudgetAllocatorService {
+    customBudgets = new Map();
+    /**
+     * Allocates a budget for an agent based on the specified strategy.
+     *
+     * @param agentName - Name of the agent type
+     * @param options - Budget allocation options
+     * @returns Allocated budget
+     */
+    allocateBudget(agentName, options) {
+        const strategy = options?.strategy ?? 'fixed';
+        switch (strategy) {
+            case 'fixed':
+                return this.allocateFixedBudget(agentName, options);
+            case 'percentage':
+                return this.allocatePercentageBudget(agentName, options);
+            case 'adaptive':
+                return this.allocateAdaptiveBudget(agentName, options);
+            default:
+                logger.warn(`Unknown budget strategy '${strategy}', using fixed`);
+                return this.allocateFixedBudget(agentName, options);
+        }
+    }
+    /**
+     * Allocates a fixed budget based on agent type defaults or explicit values.
+     */
+    allocateFixedBudget(agentName, options) {
+        // Check for custom budget registered for this agent
+        const customBudget = this.customBudgets.get(agentName);
+        if (customBudget) {
+            return { ...customBudget, tokensUsed: 0, turnsUsed: 0 };
+        }
+        // Get default budget for agent type
+        const defaultBudget = DEFAULT_AGENT_BUDGETS[agentName] ?? DEFAULT_AGENT_BUDGETS['default'];
+        // Apply overrides from options
+        return {
+            maxTokens: options?.maxTokens ?? defaultBudget.maxTokens,
+            maxTurns: options?.maxTurns ?? defaultBudget.maxTurns,
+            tokensUsed: 0,
+            turnsUsed: 0,
+        };
+    }
+    /**
+     * Allocates a budget as a percentage of the parent's remaining budget.
+     */
+    allocatePercentageBudget(agentName, options) {
+        if (!options?.parentBudget) {
+            logger.warn('Percentage strategy requires parentBudget, falling back to fixed');
+            return this.allocateFixedBudget(agentName, options);
+        }
+        const percentage = Math.min(100, Math.max(0, options.percentageOfParent ?? 50));
+        const remaining = getRemainingBudget(options.parentBudget);
+        // Calculate proportional budget
+        const allocatedTokens = Math.floor((remaining.tokens * percentage) / 100);
+        const allocatedTurns = Math.floor((remaining.turns * percentage) / 100);
+        // Ensure minimum viable budget
+        const minTokens = 10000;
+        const minTurns = 3;
+        return {
+            maxTokens: Math.max(minTokens, allocatedTokens),
+            maxTurns: Math.max(minTurns, allocatedTurns),
+            tokensUsed: 0,
+            turnsUsed: 0,
+        };
+    }
+    /**
+     * Allocates a budget based on task complexity (heuristic).
+     * Uses task length and agent type to estimate needed budget.
+     */
+    allocateAdaptiveBudget(agentName, options) {
+        // Start with default for agent type
+        const baseBudget = DEFAULT_AGENT_BUDGETS[agentName] ?? DEFAULT_AGENT_BUDGETS['default'];
+        // If we have parent budget, cap at remaining
+        if (options?.parentBudget) {
+            const remaining = getRemainingBudget(options.parentBudget);
+            return {
+                maxTokens: Math.min(baseBudget.maxTokens, remaining.tokens),
+                maxTurns: Math.min(baseBudget.maxTurns, remaining.turns),
+                tokensUsed: 0,
+                turnsUsed: 0,
+            };
+        }
+        // Otherwise use base budget
+        return { ...baseBudget, tokensUsed: 0, turnsUsed: 0 };
+    }
+    /**
+     * Validates that current usage is within budget limits.
+     *
+     * @param budget - Budget to validate
+     * @returns true if within limits, false if exceeded
+     */
+    validateBudget(budget) {
+        return !isBudgetExceeded(budget).exceeded;
+    }
+    /**
+     * Updates budget usage after an API call.
+     *
+     * @param budget - Budget to update
+     * @param tokensUsed - Tokens consumed in this call
+     * @param incrementTurn - Whether to increment turn count
+     * @returns Updated budget
+     */
+    updateUsage(budget, tokensUsed, incrementTurn = true) {
+        return {
+            ...budget,
+            tokensUsed: budget.tokensUsed + tokensUsed,
+            turnsUsed: incrementTurn ? budget.turnsUsed + 1 : budget.turnsUsed,
+        };
+    }
+    /**
+     * Checks if a budget warning should be issued.
+     *
+     * @param budget - Budget to check
+     * @returns Warning level or null if no warning
+     */
+    checkWarning(budget) {
+        const usage = getBudgetUsagePercent(budget);
+        const maxUsage = Math.max(usage.tokens, usage.turns);
+        if (maxUsage >= BUDGET_WARNING_THRESHOLDS.CRITICAL) {
+            return 'critical';
+        }
+        if (maxUsage >= BUDGET_WARNING_THRESHOLDS.WARNING) {
+            return 'warning';
+        }
+        return null;
+    }
+    /**
+     * Estimates if there's enough budget remaining for another turn.
+     * Uses average tokens per turn from current usage.
+     *
+     * @param budget - Budget to check
+     * @returns true if likely enough budget for another turn
+     */
+    hasRoomForNextTurn(budget) {
+        // Check turn limit
+        if (budget.turnsUsed >= budget.maxTurns) {
+            return false;
+        }
+        // Estimate average tokens per turn
+        const avgTokensPerTurn = budget.turnsUsed > 0
+            ? budget.tokensUsed / budget.turnsUsed
+            : 5000; // Default estimate for first turn
+        // Check if we have room for estimated next turn
+        const estimatedNextTurnTokens = budget.tokensUsed + avgTokensPerTurn;
+        return estimatedNextTurnTokens < budget.maxTokens;
+    }
+    /**
+     * Registers a custom budget configuration for an agent type.
+     *
+     * @param agentName - Agent type name
+     * @param budget - Budget configuration
+     */
+    registerCustomBudget(agentName, budget) {
+        this.customBudgets.set(agentName, {
+            ...budget,
+            tokensUsed: 0,
+            turnsUsed: 0,
+        });
+        logger.debug(`Registered custom budget for agent '${agentName}':`, budget);
+    }
+    /**
+     * Gets the default budget for an agent type.
+     *
+     * @param agentName - Agent type name
+     * @returns Default budget configuration
+     */
+    getDefaultBudget(agentName) {
+        const customBudget = this.customBudgets.get(agentName);
+        if (customBudget) {
+            return { ...customBudget, tokensUsed: 0, turnsUsed: 0 };
+        }
+        return { ...(DEFAULT_AGENT_BUDGETS[agentName] ?? DEFAULT_AGENT_BUDGETS['default']) };
+    }
+    /**
+     * Formats budget status for display/logging.
+     *
+     * @param budget - Budget to format
+     * @returns Human-readable budget status
+     */
+    formatBudgetStatus(budget) {
+        const usage = getBudgetUsagePercent(budget);
+        const remaining = getRemainingBudget(budget);
+        return [
+            `Tokens: ${budget.tokensUsed.toLocaleString()}/${budget.maxTokens.toLocaleString()} (${usage.tokens.toFixed(1)}%)`,
+            `Turns: ${budget.turnsUsed}/${budget.maxTurns} (${usage.turns.toFixed(1)}%)`,
+            `Remaining: ${remaining.tokens.toLocaleString()} tokens, ${remaining.turns} turns`,
+        ].join(' | ');
+    }
+}
+// =============================================================================
+// Singleton Instance
+// =============================================================================
+let allocatorInstance = null;
+/**
+ * Gets the singleton AgentBudgetAllocator instance.
+ */
+export function getAgentBudgetAllocator() {
+    if (!allocatorInstance) {
+        allocatorInstance = new AgentBudgetAllocatorService();
+    }
+    return allocatorInstance;
+}
+/**
+ * Resets the allocator instance (for testing).
+ */
+export function resetAgentBudgetAllocator() {
+    allocatorInstance = null;
+}
+// Re-export utility functions
+export { createDefaultBudget, getRemainingBudget, getBudgetUsagePercent, isBudgetExceeded, };
+//# sourceMappingURL=agent-budget-allocator.js.map

package/dist/services/agent-budget-allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-budget-allocator.js","sourceRoot":"","sources":["../../src/services/agent-budget-allocator.ts"],"names":[],"mappings":"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"}

package/dist/services/agent-manager.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 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 type { AgentDefinition, AgentSource, AgentFrontmatter, AgentDiscoveryResult, AgentExecutionContext, CLIAgentsMap, AgentPermissionMode } from '../types/agent.js';
+/**
+ * Gets the project agents directory path.
+ * Uses the currentProjectRoot set via setProjectRoot() or --cwd flag.
+ */
+export declare function getProjectAgentsDir(): string;
+/**
+ * Gets the user agents directory path.
+ */
+export declare function getUserAgentsDir(): string;
+/**
+ * Sets the project root for agent discovery.
+ */
+export declare function setProjectRoot(projectRoot: string): void;
+/**
+ * Gets the current project root.
+ * Returns the value set via setProjectRoot() or --cwd flag, defaulting to process.cwd().
+ */
+export declare function getProjectRoot(): string;
+/**
+ * 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 declare function parseAgentFrontmatter(content: string): {
+    frontmatter: Partial<AgentFrontmatter>;
+    systemPrompt: string;
+};
+/**
+ * Serializes agent frontmatter to YAML string.
+ */
+export declare function serializeAgentFrontmatter(frontmatter: AgentFrontmatter): string;
+/**
+ * Serializes a complete agent to markdown format.
+ */
+export declare function serializeAgent(agent: AgentDefinition): string;
+/**
+ * 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 declare function parseAgentFile(filePath: string, source: AgentSource): Promise<AgentDefinition | null>;
+/**
+ * Discovers all agents from all sources.
+ *
+ * @param forceRefresh - Force refresh the cache
+ * @returns Discovery result with all agents
+ */
+export declare function discoverAgents(forceRefresh?: boolean): Promise<AgentDiscoveryResult>;
+/**
+ * Invalidates the agent cache.
+ */
+export declare function invalidateAgentCache(): void;
+/**
+ * Registers agents from CLI --agents flag.
+ *
+ * @param agentsMap - Map of agent names to configurations
+ */
+export declare function registerCLIAgents(agentsMap: CLIAgentsMap): void;
+/**
+ * Clears all CLI agents.
+ */
+export declare function clearCLIAgents(): void;
+/**
+ * Gets all active agents.
+ */
+export declare function getActiveAgents(): Promise<AgentDefinition[]>;
+/**
+ * Gets an agent by name (only active agents).
+ */
+export declare function getAgentByName(name: string): Promise<AgentDefinition | undefined>;
+/**
+ * Gets an agent by ID (includes inactive agents).
+ */
+export declare function getAgentById(id: string): Promise<AgentDefinition | undefined>;
+/**
+ * Checks if an agent exists (active only).
+ */
+export declare function hasAgent(name: string): Promise<boolean>;
+/**
+ * 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 declare function formatAgentsForPrompt(): Promise<string>;
+/**
+ * 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 declare function createAgent(agent: Omit<AgentDefinition, 'id' | 'isActive' | 'source' | 'filePath'>, location?: 'project' | 'user'): Promise<string>;
+/**
+ * Updates an existing agent.
+ *
+ * @param agentId - ID of the agent to update
+ * @param updates - Fields to update
+ */
+export declare function updateAgent(agentId: string, updates: Partial<{
+    description: string;
+    systemPrompt: string;
+    tools: string[];
+    disallowedTools: string[];
+    model: string;
+    permissionMode: AgentPermissionMode;
+    skills: string[];
+}>): Promise<void>;
+/**
+ * Deletes an agent file.
+ *
+ * @param agentId - ID of the agent to delete
+ */
+export declare function deleteAgent(agentId: string): Promise<void>;
+/**
+ * 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 declare function createExecutionContext(agent: AgentDefinition, parentContext?: AgentExecutionContext): AgentExecutionContext;
+/**
+ * Validates an execution context for cycle detection.
+ *
+ * @param context - Context to validate
+ * @returns Error message if invalid, undefined if valid
+ */
+export declare function validateExecutionContext(context: AgentExecutionContext): string | undefined;
+/**
+ * Initializes the agent manager.
+ *
+ * @param projectRoot - Project root directory
+ * @param cliAgentsJson - Optional CLI agents JSON string
+ */
+export declare function initializeAgentManager(projectRoot: string, cliAgentsJson?: string): Promise<void>;
+declare const _default: {
+    getProjectAgentsDir: typeof getProjectAgentsDir;
+    getUserAgentsDir: typeof getUserAgentsDir;
+    setProjectRoot: typeof setProjectRoot;
+    getProjectRoot: typeof getProjectRoot;
+    discoverAgents: typeof discoverAgents;
+    invalidateAgentCache: typeof invalidateAgentCache;
+    registerCLIAgents: typeof registerCLIAgents;
+    clearCLIAgents: typeof clearCLIAgents;
+    getActiveAgents: typeof getActiveAgents;
+    getAgentByName: typeof getAgentByName;
+    getAgentById: typeof getAgentById;
+    hasAgent: typeof hasAgent;
+    createAgent: typeof createAgent;
+    updateAgent: typeof updateAgent;
+    deleteAgent: typeof deleteAgent;
+    createExecutionContext: typeof createExecutionContext;
+    validateExecutionContext: typeof validateExecutionContext;
+    initializeAgentManager: typeof initializeAgentManager;
+    parseAgentFrontmatter: typeof parseAgentFrontmatter;
+    parseAgentFile: typeof parseAgentFile;
+    serializeAgent: typeof serializeAgent;
+    serializeAgentFrontmatter: typeof serializeAgentFrontmatter;
+};
+export default _default;
+//# sourceMappingURL=agent-manager.d.ts.map

package/dist/services/agent-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manager.d.ts","sourceRoot":"","sources":["../../src/services/agent-manager.ts"],"names":[],"mappings":"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"}