agentic-qe 2.8.0 → 2.8.2

package/dist/nervous-system/integration/CircadianAgent.js

@@ -0,0 +1,696 @@
+"use strict";
+/**
+ * CircadianAgentManager - Bio-inspired duty cycling for QE agent lifecycle management
+ *
+ * Integrates CircadianController with BaseAgent lifecycle to achieve 5-50x compute
+ * cost reduction by intelligently cycling agents between active and rest phases.
+ *
+ * ## Agent Lifecycle Phases
+ * - **ACTIVE**: Full compute, agents process all tasks, run tests, make decisions
+ * - **DAWN**: Ramping up, agents pre-warm caches, prepare for active period
+ * - **DUSK**: Ramping down, agents process backlog, batch operations
+ * - **REST**: Memory consolidation, minimal compute, only critical events handled
+ *
+ * ## Compute Savings
+ * - Active phase: 100% compute usage
+ * - Dawn phase: 60% compute usage
+ * - Dusk phase: 40% compute usage
+ * - Rest phase: 10% compute usage (5-10x reduction)
+ *
+ * @module nervous-system/integration/CircadianAgent
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircadianAgentManager = void 0;
+const events_1 = require("events");
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * CircadianAgentManager integrates bio-inspired duty cycling with QE agent lifecycle
+ *
+ * Manages agent active/rest states based on circadian phases to achieve
+ * significant compute cost reduction while maintaining responsiveness for
+ * critical operations.
+ *
+ * @example
+ * ```typescript
+ * import { CircadianController } from '../adapters/CircadianController.js';
+ * import { CircadianAgentManager, AgentPhaseConfig } from './CircadianAgent.js';
+ *
+ * // Create controller with 1-hour cycles for demo
+ * const controller = new CircadianController({ cyclePeriodMs: 60 * 60 * 1000 });
+ *
+ * // Create manager
+ * const manager = new CircadianAgentManager({ controller });
+ *
+ * // Register agents
+ * const testAgent = await TestGeneratorAgent.create();
+ * await manager.registerAgent(testAgent, {
+ *   agentId: testAgent.getAgentId().id,
+ *   agentType: 'test-generator',
+ *   criticalityLevel: 'medium',
+ *   minActiveHours: 4,
+ *   canRest: true,
+ * });
+ *
+ * // Listen for phase transitions
+ * manager.on('phase-transition', (event) => {
+ *   console.log(`Agent ${event.agentId} transitioned to ${event.toPhase}`);
+ * });
+ *
+ * // Start the manager
+ * manager.start();
+ *
+ * // Check energy savings
+ * const savings = manager.getEnergySavings();
+ * console.log(`Saved ${savings.savingsPercentage}% compute`);
+ * ```
+ */
+class CircadianAgentManager extends events_1.EventEmitter {
+    /**
+     * Create a new CircadianAgentManager
+     *
+     * @param config - Manager configuration
+     */
+    constructor(config) {
+        super();
+        // Tracking state
+        this.checkInterval = null;
+        this.totalComputeCycles = 0;
+        this.savedComputeCycles = 0;
+        this.lastSavingsMilestone = 0;
+        this.startTime = 0;
+        this.isRunning = false;
+        this.controller = config.controller;
+        this.agents = new Map();
+        this.defaultCriticality = config.defaultCriticality ?? 'medium';
+        this.checkIntervalMs = config.checkIntervalMs ?? 1000;
+        this.debug = config.debug ?? false;
+        this.lastPhase = this.controller.getPhase();
+    }
+    // ============================================================================
+    // Agent Registration
+    // ============================================================================
+    /**
+     * Register an agent for circadian management
+     *
+     * Agents must be registered before they can be managed. Critical agents
+     * will never enter rest phase; low criticality agents rest first.
+     *
+     * @param agent - The BaseAgent instance to manage
+     * @param config - Phase configuration for this agent
+     */
+    async registerAgent(agent, config) {
+        const agentId = config.agentId;
+        if (this.agents.has(agentId)) {
+            throw new Error(`Agent ${agentId} is already registered`);
+        }
+        // Validate config
+        if (config.minActiveHours < 0 || config.minActiveHours > 24) {
+            throw new Error(`minActiveHours must be between 0 and 24, got ${config.minActiveHours}`);
+        }
+        if (config.criticalityLevel === 'critical' && config.canRest) {
+            this.log(`Warning: Critical agent ${agentId} should not have canRest=true, overriding to false`);
+            config.canRest = false;
+        }
+        // Initialize agent state
+        const initialState = {
+            phase: this.controller.getPhase(),
+            isActive: true,
+            timeInState: 0,
+            activeTimeInCycle: 0,
+            tasksProcessed: 0,
+            lastActivity: Date.now(),
+            isSleeping: false,
+        };
+        this.agents.set(agentId, { agent, config, state: initialState });
+        this.log(`Registered agent ${agentId} (${config.agentType}) with criticality ${config.criticalityLevel}`);
+        // If manager is already running, apply current phase
+        if (this.isRunning) {
+            await this.applyPhaseToAgent(agentId);
+        }
+    }
+    /**
+     * Unregister an agent from circadian management
+     *
+     * @param agentId - ID of agent to unregister
+     */
+    async unregisterAgent(agentId) {
+        const entry = this.agents.get(agentId);
+        if (!entry) {
+            return;
+        }
+        // Wake agent if sleeping before unregistering
+        if (entry.state.isSleeping) {
+            await this.wakeAgent(agentId, 'unregistering');
+        }
+        this.agents.delete(agentId);
+        this.log(`Unregistered agent ${agentId}`);
+    }
+    // ============================================================================
+    // Phase Management
+    // ============================================================================
+    /**
+     * Check if an agent should be active in the current phase
+     *
+     * Takes into account:
+     * - Current circadian phase
+     * - Agent criticality level
+     * - Minimum active hours requirement
+     * - Custom duty factor overrides
+     *
+     * @param agentId - ID of agent to check
+     * @returns true if agent should be active
+     */
+    shouldBeActive(agentId) {
+        const entry = this.agents.get(agentId);
+        if (!entry) {
+            return false;
+        }
+        const { config, state } = entry;
+        const currentPhase = this.controller.getPhase();
+        // Critical agents are always active
+        if (config.criticalityLevel === 'critical') {
+            return true;
+        }
+        // Check if agent can rest
+        if (!config.canRest) {
+            return true;
+        }
+        // Phase-based activity rules
+        switch (currentPhase) {
+            case 'Active':
+                // All agents active during Active phase
+                return true;
+            case 'Dawn':
+                // High agents active during Dawn (critical already handled above)
+                return config.criticalityLevel === 'high';
+            case 'Dusk':
+                // High agents stay active during Dusk (critical already handled above)
+                // Medium/low agents active if min active hours not met
+                if (config.criticalityLevel === 'high') {
+                    return true;
+                }
+                return this.needsMoreActiveTime(agentId);
+            case 'Rest':
+                // High agents check if they need more active time (critical handled above)
+                // Medium/low agents rest
+                if (config.criticalityLevel === 'high') {
+                    return this.needsMoreActiveTime(agentId);
+                }
+                return false;
+            default:
+                return true;
+        }
+    }
+    /**
+     * Check if agent needs more active time to meet minimum requirement
+     */
+    needsMoreActiveTime(agentId) {
+        const entry = this.agents.get(agentId);
+        if (!entry) {
+            return false;
+        }
+        const { config, state } = entry;
+        const cyclePeriodMs = this.controller.getConfig().cyclePeriodMs;
+        const minActiveMs = config.minActiveHours * 60 * 60 * 1000;
+        const minActiveFraction = minActiveMs / cyclePeriodMs;
+        // Calculate how much of cycle has passed
+        const cycleState = this.controller.getState();
+        const cycleFraction = cycleState.cycleTime / cyclePeriodMs;
+        // Calculate minimum active time needed by this point in cycle
+        const expectedActiveTimeMs = minActiveFraction * cycleState.cycleTime;
+        return state.activeTimeInCycle < expectedActiveTimeMs;
+    }
+    /**
+     * Enter rest phase - put eligible agents to sleep
+     *
+     * Agents are put to sleep in order of criticality (low first).
+     * Critical agents never sleep.
+     */
+    async enterRestPhase() {
+        this.log('Entering rest phase - putting eligible agents to sleep');
+        // Sort agents by criticality (low first)
+        const sortedAgents = this.getSortedAgentsByCriticality('ascending');
+        for (const agentId of sortedAgents) {
+            const entry = this.agents.get(agentId);
+            if (!entry)
+                continue;
+            if (!this.shouldBeActive(agentId) && !entry.state.isSleeping) {
+                await this.sleepAgent(agentId);
+            }
+        }
+        // Emit fleet rest event if all eligible agents are sleeping
+        const sleepingCount = this.getAgentsByState('sleeping').length;
+        this.emit('fleet-rest', {
+            timestamp: Date.now(),
+            agentCount: sleepingCount,
+        });
+    }
+    /**
+     * Enter active phase - wake all agents
+     */
+    async enterActivePhase() {
+        this.log('Entering active phase - waking all agents');
+        // Wake agents in reverse criticality order (high first)
+        const sortedAgents = this.getSortedAgentsByCriticality('descending');
+        for (const agentId of sortedAgents) {
+            const entry = this.agents.get(agentId);
+            if (!entry)
+                continue;
+            if (entry.state.isSleeping) {
+                await this.wakeAgent(agentId, 'entering active phase');
+            }
+        }
+        // Emit fleet wake event
+        const activeCount = this.getAgentsByState('active').length;
+        this.emit('fleet-wake', {
+            timestamp: Date.now(),
+            agentCount: activeCount,
+        });
+    }
+    /**
+     * Force a specific phase transition for the fleet
+     *
+     * @param phase - Phase to transition to
+     */
+    async forcePhaseTransition(phase) {
+        this.controller.modulate({
+            forcePhase: phase,
+            reason: 'manual override',
+        });
+        await this.handlePhaseChange(this.lastPhase, phase);
+        this.lastPhase = phase;
+    }
+    // ============================================================================
+    // Agent Sleep/Wake
+    // ============================================================================
+    /**
+     * Put an agent to sleep
+     */
+    async sleepAgent(agentId) {
+        const entry = this.agents.get(agentId);
+        if (!entry || entry.state.isSleeping) {
+            return;
+        }
+        const { agent, config, state } = entry;
+        // Calculate expected sleep duration based on phase
+        const cycleState = this.controller.getState();
+        const expectedDuration = cycleState.timeToNextPhase;
+        // Update state before transition
+        state.isSleeping = true;
+        state.isActive = false;
+        state.timeInState = 0;
+        // Emit sleep event
+        this.emit('agent-sleep', {
+            agentId,
+            isSleeping: true,
+            phase: state.phase,
+            timestamp: Date.now(),
+            expectedDuration,
+        });
+        this.log(`Agent ${agentId} entering sleep (expected: ${expectedDuration}ms)`);
+        // Track compute savings
+        this.updateComputeSavings(config.customDutyFactor ?? this.controller.getDutyFactor());
+    }
+    /**
+     * Wake an agent from sleep
+     */
+    async wakeAgent(agentId, reason) {
+        const entry = this.agents.get(agentId);
+        if (!entry || !entry.state.isSleeping) {
+            return;
+        }
+        const { agent, state } = entry;
+        // Update state
+        state.isSleeping = false;
+        state.isActive = true;
+        state.timeInState = 0;
+        state.lastActivity = Date.now();
+        // Emit wake event
+        this.emit('agent-sleep', {
+            agentId,
+            isSleeping: false,
+            phase: state.phase,
+            timestamp: Date.now(),
+            expectedDuration: 0,
+        });
+        this.log(`Agent ${agentId} waking (reason: ${reason})`);
+    }
+    // ============================================================================
+    // State Queries
+    // ============================================================================
+    /**
+     * Get current state of all managed agents
+     *
+     * @returns Map of agent IDs to their current states
+     */
+    getAgentStates() {
+        const states = new Map();
+        for (const [agentId, entry] of this.agents) {
+            states.set(agentId, {
+                phase: entry.state.phase,
+                isActive: entry.state.isActive,
+            });
+        }
+        return states;
+    }
+    /**
+     * Get detailed state for a specific agent
+     */
+    getAgentState(agentId) {
+        const entry = this.agents.get(agentId);
+        return entry ? { ...entry.state } : null;
+    }
+    /**
+     * Get agents by their current state
+     */
+    getAgentsByState(state) {
+        const result = [];
+        for (const [agentId, entry] of this.agents) {
+            if (state === 'sleeping' && entry.state.isSleeping) {
+                result.push(agentId);
+            }
+            else if (state === 'active' && entry.state.isActive) {
+                result.push(agentId);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get agents sorted by criticality
+     */
+    getSortedAgentsByCriticality(order) {
+        const criticalityOrder = {
+            low: 1,
+            medium: 2,
+            high: 3,
+            critical: 4,
+        };
+        const agents = Array.from(this.agents.entries());
+        agents.sort((a, b) => {
+            const aLevel = criticalityOrder[a[1].config.criticalityLevel];
+            const bLevel = criticalityOrder[b[1].config.criticalityLevel];
+            return order === 'ascending' ? aLevel - bLevel : bLevel - aLevel;
+        });
+        return agents.map(([agentId]) => agentId);
+    }
+    // ============================================================================
+    // Energy Savings
+    // ============================================================================
+    /**
+     * Calculate compute savings achieved by circadian cycling
+     *
+     * @returns Energy savings report with cycles saved and percentages
+     */
+    getEnergySavings() {
+        const metrics = this.controller.getMetrics();
+        const totalTime = metrics.phaseTime.Active + metrics.phaseTime.Dawn + metrics.phaseTime.Dusk + metrics.phaseTime.Rest;
+        if (totalTime === 0) {
+            return {
+                savedCycles: 0,
+                savingsPercentage: 0,
+                totalRestTime: 0,
+                totalActiveTime: 0,
+                averageDutyFactor: 1,
+                costReductionFactor: 1,
+            };
+        }
+        const averageDutyFactor = metrics.averageDutyFactor;
+        const savingsPercentage = (1 - averageDutyFactor) * 100;
+        const costReductionFactor = averageDutyFactor > 0 ? 1 / averageDutyFactor : 1;
+        return {
+            savedCycles: this.savedComputeCycles,
+            savingsPercentage: Math.round(savingsPercentage * 10) / 10,
+            totalRestTime: metrics.phaseTime.Rest,
+            totalActiveTime: metrics.phaseTime.Active,
+            averageDutyFactor: Math.round(averageDutyFactor * 1000) / 1000,
+            costReductionFactor: Math.round(costReductionFactor * 10) / 10,
+        };
+    }
+    /**
+     * Update compute savings tracking
+     */
+    updateComputeSavings(dutyFactor) {
+        this.totalComputeCycles++;
+        this.savedComputeCycles += 1 - dutyFactor;
+        // Check for savings milestones (every 10%)
+        const savings = this.getEnergySavings();
+        const milestone = Math.floor(savings.savingsPercentage / 10) * 10;
+        if (milestone > this.lastSavingsMilestone && milestone >= 10) {
+            this.lastSavingsMilestone = milestone;
+            this.emit('savings-milestone', {
+                savingsPercentage: savings.savingsPercentage,
+                savedCycles: savings.savedCycles,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    // ============================================================================
+    // Lifecycle Management
+    // ============================================================================
+    /**
+     * Start the circadian manager
+     *
+     * Begins periodic phase checks and applies current phase to all agents.
+     */
+    start() {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        this.startTime = Date.now();
+        this.lastPhase = this.controller.getPhase();
+        // Apply current phase to all agents
+        for (const agentId of this.agents.keys()) {
+            this.applyPhaseToAgent(agentId).catch((err) => {
+                this.log(`Error applying phase to agent ${agentId}: ${err.message}`);
+            });
+        }
+        // Start periodic phase check
+        this.checkInterval = setInterval(() => {
+            this.checkPhaseTransition();
+        }, this.checkIntervalMs);
+        this.log(`CircadianAgentManager started with ${this.agents.size} agents`);
+    }
+    /**
+     * Stop the circadian manager
+     *
+     * Stops phase checks and wakes all sleeping agents.
+     */
+    async stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        this.isRunning = false;
+        // Stop periodic check
+        if (this.checkInterval) {
+            clearInterval(this.checkInterval);
+            this.checkInterval = null;
+        }
+        // Wake all sleeping agents
+        for (const agentId of this.agents.keys()) {
+            const entry = this.agents.get(agentId);
+            if (entry?.state.isSleeping) {
+                await this.wakeAgent(agentId, 'manager stopping');
+            }
+        }
+        this.log('CircadianAgentManager stopped');
+    }
+    /**
+     * Advance the circadian controller time
+     *
+     * Call this to advance simulation time. In production, time advances
+     * automatically based on wall clock.
+     *
+     * @param dt - Time to advance in milliseconds
+     */
+    advance(dt) {
+        this.controller.advance(dt);
+        // Update agent state times
+        for (const [, entry] of this.agents) {
+            entry.state.timeInState += dt;
+            if (entry.state.isActive) {
+                entry.state.activeTimeInCycle += dt;
+            }
+        }
+        // Check for phase transition
+        this.checkPhaseTransition();
+    }
+    // ============================================================================
+    // Phase Transition Handling
+    // ============================================================================
+    /**
+     * Check for and handle phase transitions
+     */
+    checkPhaseTransition() {
+        const currentPhase = this.controller.getPhase();
+        if (currentPhase !== this.lastPhase) {
+            this.handlePhaseChange(this.lastPhase, currentPhase).catch((err) => {
+                this.log(`Error handling phase change: ${err.message}`);
+            });
+            this.lastPhase = currentPhase;
+        }
+    }
+    /**
+     * Handle a phase change
+     */
+    async handlePhaseChange(fromPhase, toPhase) {
+        this.log(`Phase transition: ${fromPhase} -> ${toPhase}`);
+        // Emit fleet phase change event
+        this.emit('fleet-phase-change', {
+            fromPhase,
+            toPhase,
+            timestamp: Date.now(),
+        });
+        // Apply phase to all agents
+        for (const agentId of this.agents.keys()) {
+            await this.applyPhaseToAgent(agentId, fromPhase, toPhase);
+        }
+        // Phase-specific handling
+        switch (toPhase) {
+            case 'Rest':
+                await this.enterRestPhase();
+                break;
+            case 'Active':
+                await this.enterActivePhase();
+                break;
+            case 'Dawn':
+                await this.handleDawnPhase();
+                break;
+            case 'Dusk':
+                await this.handleDuskPhase();
+                break;
+        }
+    }
+    /**
+     * Apply current phase to a specific agent
+     */
+    async applyPhaseToAgent(agentId, fromPhase, toPhase) {
+        const entry = this.agents.get(agentId);
+        if (!entry) {
+            return;
+        }
+        const currentPhase = toPhase ?? this.controller.getPhase();
+        const previousPhase = fromPhase ?? entry.state.phase;
+        // Update agent state
+        entry.state.phase = currentPhase;
+        // Emit phase transition event
+        if (previousPhase !== currentPhase) {
+            this.emit('phase-transition', {
+                agentId,
+                fromPhase: previousPhase,
+                toPhase: currentPhase,
+                timestamp: Date.now(),
+                reason: 'circadian cycle',
+            });
+        }
+        // Apply sleep/wake based on new phase
+        const shouldBeActive = this.shouldBeActive(agentId);
+        if (shouldBeActive && entry.state.isSleeping) {
+            await this.wakeAgent(agentId, `phase transition to ${currentPhase}`);
+        }
+        else if (!shouldBeActive && !entry.state.isSleeping) {
+            await this.sleepAgent(agentId);
+        }
+    }
+    /**
+     * Handle dawn phase - prepare agents for active period
+     */
+    async handleDawnPhase() {
+        // Wake high-criticality agents during dawn
+        const sortedAgents = this.getSortedAgentsByCriticality('descending');
+        for (const agentId of sortedAgents) {
+            const entry = this.agents.get(agentId);
+            if (!entry)
+                continue;
+            if (this.shouldBeActive(agentId) && entry.state.isSleeping) {
+                await this.wakeAgent(agentId, 'dawn phase preparation');
+            }
+        }
+    }
+    /**
+     * Handle dusk phase - start ramping down
+     */
+    async handleDuskPhase() {
+        // Low-criticality agents start sleeping during dusk
+        const sortedAgents = this.getSortedAgentsByCriticality('ascending');
+        for (const agentId of sortedAgents) {
+            const entry = this.agents.get(agentId);
+            if (!entry)
+                continue;
+            if (!this.shouldBeActive(agentId) && !entry.state.isSleeping) {
+                await this.sleepAgent(agentId);
+            }
+        }
+    }
+    // ============================================================================
+    // Metrics and Reporting
+    // ============================================================================
+    /**
+     * Get circadian controller metrics
+     */
+    getControllerMetrics() {
+        return this.controller.getMetrics();
+    }
+    /**
+     * Get circadian controller state
+     */
+    getControllerState() {
+        return this.controller.getState();
+    }
+    /**
+     * Get manager statistics
+     */
+    getStats() {
+        const activeAgents = this.getAgentsByState('active').length;
+        const sleepingAgents = this.getAgentsByState('sleeping').length;
+        return {
+            totalAgents: this.agents.size,
+            activeAgents,
+            sleepingAgents,
+            currentPhase: this.controller.getPhase(),
+            uptime: this.isRunning ? Date.now() - this.startTime : 0,
+            savings: this.getEnergySavings(),
+        };
+    }
+    // ============================================================================
+    // Utility
+    // ============================================================================
+    /**
+     * Log message if debug is enabled
+     */
+    log(message) {
+        if (this.debug) {
+            console.log(`[CircadianAgentManager] ${message}`);
+        }
+    }
+    /**
+     * Record a task completion for an agent
+     *
+     * Call this when an agent completes a task to track activity.
+     */
+    recordTaskCompletion(agentId) {
+        const entry = this.agents.get(agentId);
+        if (entry) {
+            entry.state.tasksProcessed++;
+            entry.state.lastActivity = Date.now();
+        }
+    }
+    /**
+     * Get the number of registered agents
+     */
+    get agentCount() {
+        return this.agents.size;
+    }
+    /**
+     * Check if manager is currently running
+     */
+    get running() {
+        return this.isRunning;
+    }
+}
+exports.CircadianAgentManager = CircadianAgentManager;
+exports.default = CircadianAgentManager;
+//# sourceMappingURL=CircadianAgent.js.map