agentic-qe 2.8.0 → 2.8.2

package/dist/nervous-system/integration/CircadianAgent.d.ts

@@ -0,0 +1,389 @@
+/**
+ * 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
+ */
+import { EventEmitter } from 'events';
+import type { CircadianController, CircadianPhase, CircadianMetrics, CircadianState } from '../adapters/CircadianController.js';
+import type { BaseAgent } from '../../agents/BaseAgent.js';
+/**
+ * Criticality level determines agent behavior during phase transitions
+ */
+export type CriticalityLevel = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Configuration for agent phase management
+ */
+export interface AgentPhaseConfig {
+    /** Unique agent identifier */
+    agentId: string;
+    /** Type of the agent (e.g., 'test-generator', 'coverage-analyzer') */
+    agentType: string;
+    /** Criticality level determines wake priority and rest eligibility */
+    criticalityLevel: CriticalityLevel;
+    /** Minimum hours agent must be active per cycle */
+    minActiveHours: number;
+    /** Whether agent can enter rest phase (critical agents never rest) */
+    canRest: boolean;
+    /** Custom duty factor override (0-1, optional) */
+    customDutyFactor?: number;
+    /** Tags for grouping agents (e.g., 'core', 'optional') */
+    tags?: string[];
+}
+/**
+ * State of a managed agent
+ */
+export interface ManagedAgentState {
+    /** Current circadian phase for this agent */
+    phase: CircadianPhase;
+    /** Whether agent is currently active */
+    isActive: boolean;
+    /** Time spent in current state (ms) */
+    timeInState: number;
+    /** Total active time in current cycle (ms) */
+    activeTimeInCycle: number;
+    /** Number of tasks processed in current cycle */
+    tasksProcessed: number;
+    /** Last activity timestamp */
+    lastActivity: number;
+    /** Whether agent is currently sleeping */
+    isSleeping: boolean;
+}
+/**
+ * Energy savings report
+ */
+export interface EnergySavingsReport {
+    /** Total compute cycles saved */
+    savedCycles: number;
+    /** Percentage of compute saved (0-100) */
+    savingsPercentage: number;
+    /** Total time in rest phase (ms) */
+    totalRestTime: number;
+    /** Total time in active phase (ms) */
+    totalActiveTime: number;
+    /** Average duty factor achieved */
+    averageDutyFactor: number;
+    /** Estimated cost reduction factor (e.g., 5x) */
+    costReductionFactor: number;
+}
+/**
+ * Phase transition event data
+ */
+export interface PhaseTransitionEvent {
+    /** Agent that transitioned */
+    agentId: string;
+    /** Previous phase */
+    fromPhase: CircadianPhase;
+    /** New phase */
+    toPhase: CircadianPhase;
+    /** Timestamp of transition */
+    timestamp: number;
+    /** Reason for transition */
+    reason: string;
+}
+/**
+ * Agent wake/sleep event data
+ */
+export interface AgentSleepEvent {
+    /** Agent that changed sleep state */
+    agentId: string;
+    /** Whether agent is now sleeping */
+    isSleeping: boolean;
+    /** Current phase when sleep state changed */
+    phase: CircadianPhase;
+    /** Timestamp of change */
+    timestamp: number;
+    /** Expected duration of sleep (ms, 0 if waking) */
+    expectedDuration: number;
+}
+/**
+ * Manager configuration
+ */
+export interface CircadianAgentManagerConfig {
+    /** The CircadianController instance to use */
+    controller: CircadianController;
+    /** Default criticality for agents without explicit config */
+    defaultCriticality?: CriticalityLevel;
+    /** Whether to auto-register agents on add */
+    autoRegister?: boolean;
+    /** Time resolution for phase checks (ms) */
+    checkIntervalMs?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Events emitted by CircadianAgentManager
+ */
+export interface CircadianAgentEvents {
+    /** Emitted when agent transitions between phases */
+    'phase-transition': PhaseTransitionEvent;
+    /** Emitted when agent enters/exits sleep */
+    'agent-sleep': AgentSleepEvent;
+    /** Emitted when all agents enter rest phase */
+    'fleet-rest': {
+        timestamp: number;
+        agentCount: number;
+    };
+    /** Emitted when fleet wakes from rest */
+    'fleet-wake': {
+        timestamp: number;
+        agentCount: number;
+    };
+    /** Emitted on phase change for the entire fleet */
+    'fleet-phase-change': {
+        fromPhase: CircadianPhase;
+        toPhase: CircadianPhase;
+        timestamp: number;
+    };
+    /** Emitted when energy savings milestone reached */
+    'savings-milestone': {
+        savingsPercentage: number;
+        savedCycles: number;
+        timestamp: number;
+    };
+}
+/**
+ * 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`);
+ * ```
+ */
+export declare class CircadianAgentManager extends EventEmitter {
+    private readonly controller;
+    private readonly agents;
+    private readonly defaultCriticality;
+    private readonly checkIntervalMs;
+    private readonly debug;
+    private checkInterval;
+    private lastPhase;
+    private totalComputeCycles;
+    private savedComputeCycles;
+    private lastSavingsMilestone;
+    private startTime;
+    private isRunning;
+    /**
+     * Create a new CircadianAgentManager
+     *
+     * @param config - Manager configuration
+     */
+    constructor(config: CircadianAgentManagerConfig);
+    /**
+     * 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
+     */
+    registerAgent(agent: BaseAgent, config: AgentPhaseConfig): Promise<void>;
+    /**
+     * Unregister an agent from circadian management
+     *
+     * @param agentId - ID of agent to unregister
+     */
+    unregisterAgent(agentId: string): Promise<void>;
+    /**
+     * 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: string): boolean;
+    /**
+     * Check if agent needs more active time to meet minimum requirement
+     */
+    private needsMoreActiveTime;
+    /**
+     * Enter rest phase - put eligible agents to sleep
+     *
+     * Agents are put to sleep in order of criticality (low first).
+     * Critical agents never sleep.
+     */
+    enterRestPhase(): Promise<void>;
+    /**
+     * Enter active phase - wake all agents
+     */
+    enterActivePhase(): Promise<void>;
+    /**
+     * Force a specific phase transition for the fleet
+     *
+     * @param phase - Phase to transition to
+     */
+    forcePhaseTransition(phase: CircadianPhase): Promise<void>;
+    /**
+     * Put an agent to sleep
+     */
+    private sleepAgent;
+    /**
+     * Wake an agent from sleep
+     */
+    private wakeAgent;
+    /**
+     * Get current state of all managed agents
+     *
+     * @returns Map of agent IDs to their current states
+     */
+    getAgentStates(): Map<string, {
+        phase: CircadianPhase;
+        isActive: boolean;
+    }>;
+    /**
+     * Get detailed state for a specific agent
+     */
+    getAgentState(agentId: string): ManagedAgentState | null;
+    /**
+     * Get agents by their current state
+     */
+    private getAgentsByState;
+    /**
+     * Get agents sorted by criticality
+     */
+    private getSortedAgentsByCriticality;
+    /**
+     * Calculate compute savings achieved by circadian cycling
+     *
+     * @returns Energy savings report with cycles saved and percentages
+     */
+    getEnergySavings(): EnergySavingsReport;
+    /**
+     * Update compute savings tracking
+     */
+    private updateComputeSavings;
+    /**
+     * Start the circadian manager
+     *
+     * Begins periodic phase checks and applies current phase to all agents.
+     */
+    start(): void;
+    /**
+     * Stop the circadian manager
+     *
+     * Stops phase checks and wakes all sleeping agents.
+     */
+    stop(): Promise<void>;
+    /**
+     * 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: number): void;
+    /**
+     * Check for and handle phase transitions
+     */
+    private checkPhaseTransition;
+    /**
+     * Handle a phase change
+     */
+    private handlePhaseChange;
+    /**
+     * Apply current phase to a specific agent
+     */
+    private applyPhaseToAgent;
+    /**
+     * Handle dawn phase - prepare agents for active period
+     */
+    private handleDawnPhase;
+    /**
+     * Handle dusk phase - start ramping down
+     */
+    private handleDuskPhase;
+    /**
+     * Get circadian controller metrics
+     */
+    getControllerMetrics(): CircadianMetrics;
+    /**
+     * Get circadian controller state
+     */
+    getControllerState(): CircadianState;
+    /**
+     * Get manager statistics
+     */
+    getStats(): {
+        totalAgents: number;
+        activeAgents: number;
+        sleepingAgents: number;
+        currentPhase: CircadianPhase;
+        uptime: number;
+        savings: EnergySavingsReport;
+    };
+    /**
+     * Log message if debug is enabled
+     */
+    private log;
+    /**
+     * Record a task completion for an agent
+     *
+     * Call this when an agent completes a task to track activity.
+     */
+    recordTaskCompletion(agentId: string): void;
+    /**
+     * Get the number of registered agents
+     */
+    get agentCount(): number;
+    /**
+     * Check if manager is currently running
+     */
+    get running(): boolean;
+}
+export default CircadianAgentManager;
+//# sourceMappingURL=CircadianAgent.d.ts.map

package/dist/nervous-system/integration/CircadianAgent.d.ts.map

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