agentic-qe 1.3.4 → 1.3.6

package/dist/agents/coordination/AgentCoordinator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * AgentCoordinator - Handles inter-agent coordination and communication
+ *
+ * Responsibilities:
+ * - Event emission and handling
+ * - Message broadcasting to other agents
+ * - Status reporting to coordination system
+ * - Event handler registration and lifecycle
+ *
+ * Part of BaseAgent refactoring (Phase 2)
+ * Reduces BaseAgent complexity by ~200 LOC
+ */
+import { EventEmitter } from 'events';
+import { AgentId, EventHandler, MemoryStore } from '../../types';
+export interface AgentCoordinatorConfig {
+    agentId: AgentId;
+    eventBus: EventEmitter;
+    memoryStore?: MemoryStore;
+}
+export declare class AgentCoordinator {
+    private readonly agentId;
+    private readonly eventBus;
+    private readonly memoryStore?;
+    private readonly eventHandlers;
+    constructor(config: AgentCoordinatorConfig);
+    /**
+     * Register an event handler for a specific event type
+     * @param handler Event handler configuration
+     */
+    registerEventHandler<T = any>(handler: EventHandler<T>): void;
+    /**
+     * Unregister an event handler
+     * @param eventType Event type to unregister
+     * @param handler Handler function to remove
+     */
+    unregisterEventHandler(eventType: string, handler: Function): void;
+    /**
+     * Emit an event to the event bus
+     * @param type Event type
+     * @param data Event payload
+     * @param priority Event priority
+     */
+    emitEvent(type: string, data: any, priority?: 'low' | 'medium' | 'high' | 'critical'): void;
+    /**
+     * Broadcast message to other agents
+     * @param type Message type
+     * @param payload Message payload
+     * @param priority Message priority
+     */
+    broadcastMessage(type: string, payload: any, priority?: 'low' | 'medium' | 'high' | 'critical'): Promise<void>;
+    /**
+     * Send direct message to specific agent
+     * @param toAgentId Target agent ID
+     * @param type Message type
+     * @param payload Message payload
+     * @param priority Message priority
+     */
+    sendMessage(toAgentId: AgentId, type: string, payload: any, priority?: 'low' | 'medium' | 'high' | 'critical'): Promise<void>;
+    /**
+     * Report agent status to coordination system
+     * @param status Status information to report
+     */
+    reportStatus(status: string, metrics?: any): Promise<void>;
+    /**
+     * Clean up all event handlers
+     * Should be called during agent termination
+     */
+    cleanup(): void;
+    /**
+     * Get registered event types
+     */
+    getRegisteredEventTypes(): string[];
+    /**
+     * Get handler count for specific event type
+     */
+    getHandlerCount(eventType: string): number;
+    /**
+     * Get total handler count
+     */
+    getTotalHandlerCount(): number;
+    /**
+     * Get event handlers map (for backward compatibility)
+     */
+    getEventHandlers(): Map<string, EventHandler[]>;
+    /**
+     * Clear all event handlers
+     */
+    clearAllHandlers(): void;
+    /**
+     * Generate unique event ID
+     */
+    private generateEventId;
+    /**
+     * Generate unique message ID
+     */
+    private generateMessageId;
+}
+//# sourceMappingURL=AgentCoordinator.d.ts.map

package/dist/agents/coordination/AgentCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentCoordinator.d.ts","sourceRoot":"","sources":["../../../src/agents/coordination/AgentCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,EACL,OAAO,EAEP,YAAY,EAIZ,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0C;gBAE5D,MAAM,EAAE,sBAAsB;IAM1C;;;OAGG;IACI,oBAAoB,CAAC,CAAC,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IASpE;;;;OAIG;IACI,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI;IAezE;;;;;OAKG;IACI,SAAS,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,GAAG,EACT,QAAQ,GAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAqB,GAC1D,IAAI;IAcP;;;;;OAKG;IACU,gBAAgB,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,GAAG,EACZ,QAAQ,GAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC;IAchB;;;;;;OAMG;IACU,WAAW,CACtB,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,GAAG,EACZ,QAAQ,GAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAqB,GAC1D,OAAO,CAAC,IAAI,CAAC;IAchB;;;OAGG;IACU,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BvE;;;OAGG;IACI,OAAO,IAAI,IAAI;IAStB;;OAEG;IACI,uBAAuB,IAAI,MAAM,EAAE;IAI1C;;OAEG;IACI,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIjD;;OAEG;IACI,oBAAoB,IAAI,MAAM;IAQrC;;OAEG;IACI,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAItD;;OAEG;IACI,gBAAgB,IAAI,IAAI;IAI/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAG1B"}

package/dist/agents/coordination/AgentCoordinator.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * AgentCoordinator - Handles inter-agent coordination and communication
+ *
+ * Responsibilities:
+ * - Event emission and handling
+ * - Message broadcasting to other agents
+ * - Status reporting to coordination system
+ * - Event handler registration and lifecycle
+ *
+ * Part of BaseAgent refactoring (Phase 2)
+ * Reduces BaseAgent complexity by ~200 LOC
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentCoordinator = void 0;
+const SecureRandom_js_1 = require("../../utils/SecureRandom.js");
+class AgentCoordinator {
+    constructor(config) {
+        this.eventHandlers = new Map();
+        this.agentId = config.agentId;
+        this.eventBus = config.eventBus;
+        this.memoryStore = config.memoryStore;
+    }
+    /**
+     * Register an event handler for a specific event type
+     * @param handler Event handler configuration
+     */
+    registerEventHandler(handler) {
+        const handlers = this.eventHandlers.get(handler.eventType) || [];
+        handlers.push(handler);
+        this.eventHandlers.set(handler.eventType, handlers);
+        // Register with event bus
+        this.eventBus.on(handler.eventType, handler.handler);
+    }
+    /**
+     * Unregister an event handler
+     * @param eventType Event type to unregister
+     * @param handler Handler function to remove
+     */
+    unregisterEventHandler(eventType, handler) {
+        const handlers = this.eventHandlers.get(eventType);
+        if (!handlers)
+            return;
+        const index = handlers.findIndex(h => h.handler === handler);
+        if (index !== -1) {
+            handlers.splice(index, 1);
+            this.eventBus.off(eventType, handler);
+        }
+        if (handlers.length === 0) {
+            this.eventHandlers.delete(eventType);
+        }
+    }
+    /**
+     * Emit an event to the event bus
+     * @param type Event type
+     * @param data Event payload
+     * @param priority Event priority
+     */
+    emitEvent(type, data, priority = 'medium') {
+        const event = {
+            id: this.generateEventId(),
+            type,
+            source: this.agentId,
+            data,
+            timestamp: new Date(),
+            priority,
+            scope: 'global'
+        };
+        this.eventBus.emit(type, event);
+    }
+    /**
+     * Broadcast message to other agents
+     * @param type Message type
+     * @param payload Message payload
+     * @param priority Message priority
+     */
+    async broadcastMessage(type, payload, priority = 'medium') {
+        const message = {
+            id: this.generateMessageId(),
+            from: this.agentId,
+            to: { id: 'broadcast', type: 'all', created: new Date() },
+            type: type,
+            payload,
+            timestamp: new Date(),
+            priority
+        };
+        this.eventBus.emit('agent.message', message);
+    }
+    /**
+     * Send direct message to specific agent
+     * @param toAgentId Target agent ID
+     * @param type Message type
+     * @param payload Message payload
+     * @param priority Message priority
+     */
+    async sendMessage(toAgentId, type, payload, priority = 'medium') {
+        const message = {
+            id: this.generateMessageId(),
+            from: this.agentId,
+            to: toAgentId,
+            type: type,
+            payload,
+            timestamp: new Date(),
+            priority
+        };
+        this.eventBus.emit(`agent.message.${toAgentId.id}`, message);
+    }
+    /**
+     * Report agent status to coordination system
+     * @param status Status information to report
+     */
+    async reportStatus(status, metrics) {
+        if (!this.memoryStore) {
+            console.warn(`[${this.agentId.id}] Cannot report status: memory store not available`);
+            return;
+        }
+        try {
+            const sharedKey = `shared:${this.agentId.type}:status`;
+            await this.memoryStore.store(sharedKey, {
+                agentId: this.agentId.id,
+                status,
+                metrics,
+                timestamp: new Date()
+            });
+            // Also emit event
+            this.emitEvent('agent.status.updated', {
+                agentId: this.agentId,
+                status,
+                metrics
+            });
+        }
+        catch (error) {
+            console.warn(`[${this.agentId.id}] Failed to report status:`, error);
+        }
+    }
+    /**
+     * Clean up all event handlers
+     * Should be called during agent termination
+     */
+    cleanup() {
+        for (const [eventType, handlers] of this.eventHandlers.entries()) {
+            for (const handler of handlers) {
+                this.eventBus.off(eventType, handler.handler);
+            }
+        }
+        this.eventHandlers.clear();
+    }
+    /**
+     * Get registered event types
+     */
+    getRegisteredEventTypes() {
+        return Array.from(this.eventHandlers.keys());
+    }
+    /**
+     * Get handler count for specific event type
+     */
+    getHandlerCount(eventType) {
+        return this.eventHandlers.get(eventType)?.length || 0;
+    }
+    /**
+     * Get total handler count
+     */
+    getTotalHandlerCount() {
+        let count = 0;
+        for (const handlers of this.eventHandlers.values()) {
+            count += handlers.length;
+        }
+        return count;
+    }
+    /**
+     * Get event handlers map (for backward compatibility)
+     */
+    getEventHandlers() {
+        return this.eventHandlers;
+    }
+    /**
+     * Clear all event handlers
+     */
+    clearAllHandlers() {
+        this.cleanup();
+    }
+    /**
+     * Generate unique event ID
+     */
+    generateEventId() {
+        return `event-${Date.now()}-${SecureRandom_js_1.SecureRandom.generateId(5)}`;
+    }
+    /**
+     * Generate unique message ID
+     */
+    generateMessageId() {
+        return `msg-${Date.now()}-${SecureRandom_js_1.SecureRandom.generateId(5)}`;
+    }
+}
+exports.AgentCoordinator = AgentCoordinator;
+//# sourceMappingURL=AgentCoordinator.js.map

package/dist/agents/coordination/AgentCoordinator.js.map

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

package/dist/agents/lifecycle/AgentLifecycleManager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * AgentLifecycleManager - Manages agent lifecycle state transitions
+ *
+ * Responsibilities:
+ * - Status management (INITIALIZING, ACTIVE, IDLE, TERMINATING, TERMINATED, ERROR)
+ * - Lifecycle state transitions with validation
+ * - Hook coordination during lifecycle events
+ * - State transition auditing
+ *
+ * Part of BaseAgent refactoring (Phase 1)
+ * Reduces BaseAgent complexity by ~150 LOC
+ */
+import { AgentStatus, AgentId } from '../../types';
+export interface LifecycleHooks {
+    onPreInitialization?: () => Promise<void>;
+    onPostInitialization?: () => Promise<void>;
+    onPreTermination?: () => Promise<void>;
+    onPostTermination?: () => Promise<void>;
+}
+export interface StateTransition {
+    from: AgentStatus;
+    to: AgentStatus;
+    timestamp: Date;
+    reason?: string;
+}
+export declare class AgentLifecycleManager {
+    private status;
+    private readonly agentId;
+    private readonly transitionHistory;
+    private readonly validTransitions;
+    constructor(agentId: AgentId);
+    /**
+     * Initialize the agent lifecycle
+     * @param hooks Optional lifecycle hooks to execute
+     */
+    initialize(hooks?: LifecycleHooks): Promise<void>;
+    /**
+     * Terminate the agent lifecycle
+     * @param hooks Optional lifecycle hooks to execute
+     */
+    terminate(hooks?: LifecycleHooks): Promise<void>;
+    /**
+     * Get current agent status
+     */
+    getStatus(): AgentStatus;
+    /**
+     * Check if agent is in a specific status
+     */
+    isInStatus(status: AgentStatus): boolean;
+    /**
+     * Check if agent is active and can accept tasks
+     */
+    canAcceptTasks(): boolean;
+    /**
+     * Mark agent as active (processing task)
+     */
+    markActive(): void;
+    /**
+     * Mark agent as idle (ready for next task)
+     */
+    markIdle(): void;
+    /**
+     * Mark agent as errored
+     */
+    markError(reason: string): void;
+    /**
+     * Get transition history
+     */
+    getTransitionHistory(): StateTransition[];
+    /**
+     * Get time in current status
+     */
+    getTimeInCurrentStatus(): number;
+    /**
+     * Validate if a state transition is allowed
+     * @throws Error if transition is invalid
+     */
+    validateTransition(from: AgentStatus, to: AgentStatus): void;
+    /**
+     * Internal method to perform state transition
+     */
+    private transitionTo;
+    /**
+     * Build valid state transition map
+     * Defines the finite state machine for agent lifecycle
+     */
+    private buildTransitionMap;
+    /**
+     * Get status statistics
+     */
+    getStatusStatistics(): {
+        currentStatus: AgentStatus;
+        totalTransitions: number;
+        timeInCurrentStatus: number;
+        statusBreakdown: Map<AgentStatus, number>;
+    };
+    /**
+     * Set agent status directly (for backward compatibility)
+     * @deprecated Use transitionTo() or specific methods like markActive() instead
+     */
+    setStatus(newStatus: AgentStatus): void;
+    /**
+     * Check if agent is terminating
+     */
+    isTerminating(): boolean;
+}
+//# sourceMappingURL=AgentLifecycleManager.d.ts.map

package/dist/agents/lifecycle/AgentLifecycleManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentLifecycleManager.d.ts","sourceRoot":"","sources":["../../../src/agents/lifecycle/AgentLifecycleManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAyC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;gBAE1D,OAAO,EAAE,OAAO;IAK5B;;;OAGG;IACU,UAAU,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB9D;;;OAGG;IACU,SAAS,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B7D;;OAEG;IACI,SAAS,IAAI,WAAW;IAI/B;;OAEG;IACI,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAI/C;;OAEG;IACI,cAAc,IAAI,OAAO;IAIhC;;OAEG;IACI,UAAU,IAAI,IAAI;IAKzB;;OAEG;IACI,QAAQ,IAAI,IAAI;IAKvB;;OAEG;IACI,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAItC;;OAEG;IACI,oBAAoB,IAAI,eAAe,EAAE;IAIhD;;OAEG;IACI,sBAAsB,IAAI,MAAM;IAMvC;;;OAGG;IACI,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI;IAcnE;;OAEG;IACH,OAAO,CAAC,YAAY;IAYpB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAuC1B;;OAEG;IACI,mBAAmB,IAAI;QAC5B,aAAa,EAAE,WAAW,CAAC;QAC3B,gBAAgB,EAAE,MAAM,CAAC;QACzB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,eAAe,EAAE,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;KAC3C;IAkBD;;;OAGG;IACI,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI;IAI9C;;OAEG;IACI,aAAa,IAAI,OAAO;CAGhC"}

package/dist/agents/lifecycle/AgentLifecycleManager.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * AgentLifecycleManager - Manages agent lifecycle state transitions
+ *
+ * Responsibilities:
+ * - Status management (INITIALIZING, ACTIVE, IDLE, TERMINATING, TERMINATED, ERROR)
+ * - Lifecycle state transitions with validation
+ * - Hook coordination during lifecycle events
+ * - State transition auditing
+ *
+ * Part of BaseAgent refactoring (Phase 1)
+ * Reduces BaseAgent complexity by ~150 LOC
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentLifecycleManager = void 0;
+const types_1 = require("../../types");
+class AgentLifecycleManager {
+    constructor(agentId) {
+        this.status = types_1.AgentStatus.INITIALIZING;
+        this.transitionHistory = [];
+        this.agentId = agentId;
+        this.validTransitions = this.buildTransitionMap();
+    }
+    /**
+     * Initialize the agent lifecycle
+     * @param hooks Optional lifecycle hooks to execute
+     */
+    async initialize(hooks) {
+        this.validateTransition(this.status, types_1.AgentStatus.INITIALIZING);
+        try {
+            // Execute pre-initialization hook
+            if (hooks?.onPreInitialization) {
+                await hooks.onPreInitialization();
+            }
+            // Transition to ACTIVE
+            this.transitionTo(types_1.AgentStatus.ACTIVE, 'Initialization complete');
+            // Execute post-initialization hook
+            if (hooks?.onPostInitialization) {
+                await hooks.onPostInitialization();
+            }
+        }
+        catch (error) {
+            this.transitionTo(types_1.AgentStatus.ERROR, `Initialization failed: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Terminate the agent lifecycle
+     * @param hooks Optional lifecycle hooks to execute
+     */
+    async terminate(hooks) {
+        this.validateTransition(this.status, types_1.AgentStatus.TERMINATING);
+        try {
+            // Transition to TERMINATING
+            this.transitionTo(types_1.AgentStatus.TERMINATING, 'Termination initiated');
+            // Execute pre-termination hook
+            if (hooks?.onPreTermination) {
+                await hooks.onPreTermination();
+            }
+            // Transition to TERMINATED
+            this.transitionTo(types_1.AgentStatus.TERMINATED, 'Termination complete');
+            // Execute post-termination hook
+            if (hooks?.onPostTermination) {
+                await hooks.onPostTermination();
+            }
+        }
+        catch (error) {
+            this.transitionTo(types_1.AgentStatus.ERROR, `Termination failed: ${error}`);
+            throw error;
+        }
+    }
+    /**
+     * Get current agent status
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Check if agent is in a specific status
+     */
+    isInStatus(status) {
+        return this.status === status;
+    }
+    /**
+     * Check if agent is active and can accept tasks
+     */
+    canAcceptTasks() {
+        return this.status === types_1.AgentStatus.ACTIVE || this.status === types_1.AgentStatus.IDLE;
+    }
+    /**
+     * Mark agent as active (processing task)
+     */
+    markActive() {
+        this.validateTransition(this.status, types_1.AgentStatus.ACTIVE);
+        this.transitionTo(types_1.AgentStatus.ACTIVE, 'Task execution started');
+    }
+    /**
+     * Mark agent as idle (ready for next task)
+     */
+    markIdle() {
+        this.validateTransition(this.status, types_1.AgentStatus.IDLE);
+        this.transitionTo(types_1.AgentStatus.IDLE, 'Task execution completed');
+    }
+    /**
+     * Mark agent as errored
+     */
+    markError(reason) {
+        this.transitionTo(types_1.AgentStatus.ERROR, reason);
+    }
+    /**
+     * Get transition history
+     */
+    getTransitionHistory() {
+        return [...this.transitionHistory];
+    }
+    /**
+     * Get time in current status
+     */
+    getTimeInCurrentStatus() {
+        const lastTransition = this.transitionHistory[this.transitionHistory.length - 1];
+        if (!lastTransition)
+            return 0;
+        return Date.now() - lastTransition.timestamp.getTime();
+    }
+    /**
+     * Validate if a state transition is allowed
+     * @throws Error if transition is invalid
+     */
+    validateTransition(from, to) {
+        // Allow same-state transitions
+        if (from === to)
+            return;
+        // Check if transition is valid
+        const validNextStates = this.validTransitions.get(from);
+        if (!validNextStates || !validNextStates.has(to)) {
+            throw new Error(`Invalid lifecycle transition for agent ${this.agentId.id}: ` +
+                `Cannot transition from ${from} to ${to}`);
+        }
+    }
+    /**
+     * Internal method to perform state transition
+     */
+    transitionTo(newStatus, reason) {
+        const transition = {
+            from: this.status,
+            to: newStatus,
+            timestamp: new Date(),
+            reason
+        };
+        this.status = newStatus;
+        this.transitionHistory.push(transition);
+    }
+    /**
+     * Build valid state transition map
+     * Defines the finite state machine for agent lifecycle
+     */
+    buildTransitionMap() {
+        return new Map([
+            // INITIALIZING can transition to ACTIVE or ERROR
+            [types_1.AgentStatus.INITIALIZING, new Set([
+                    types_1.AgentStatus.ACTIVE,
+                    types_1.AgentStatus.ERROR
+                ])],
+            // ACTIVE can transition to IDLE, TERMINATING, or ERROR
+            [types_1.AgentStatus.ACTIVE, new Set([
+                    types_1.AgentStatus.IDLE,
+                    types_1.AgentStatus.TERMINATING,
+                    types_1.AgentStatus.ERROR,
+                    types_1.AgentStatus.ACTIVE // Allow re-entry for task processing
+                ])],
+            // IDLE can transition to ACTIVE, TERMINATING, or ERROR
+            [types_1.AgentStatus.IDLE, new Set([
+                    types_1.AgentStatus.ACTIVE,
+                    types_1.AgentStatus.TERMINATING,
+                    types_1.AgentStatus.ERROR
+                ])],
+            // TERMINATING can transition to TERMINATED or ERROR
+            [types_1.AgentStatus.TERMINATING, new Set([
+                    types_1.AgentStatus.TERMINATED,
+                    types_1.AgentStatus.ERROR
+                ])],
+            // TERMINATED is a final state
+            [types_1.AgentStatus.TERMINATED, new Set()],
+            // ERROR can transition to TERMINATING (for cleanup)
+            [types_1.AgentStatus.ERROR, new Set([
+                    types_1.AgentStatus.TERMINATING
+                ])]
+        ]);
+    }
+    /**
+     * Get status statistics
+     */
+    getStatusStatistics() {
+        const statusBreakdown = new Map();
+        for (const transition of this.transitionHistory) {
+            statusBreakdown.set(transition.to, (statusBreakdown.get(transition.to) || 0) + 1);
+        }
+        return {
+            currentStatus: this.status,
+            totalTransitions: this.transitionHistory.length,
+            timeInCurrentStatus: this.getTimeInCurrentStatus(),
+            statusBreakdown
+        };
+    }
+    /**
+     * Set agent status directly (for backward compatibility)
+     * @deprecated Use transitionTo() or specific methods like markActive() instead
+     */
+    setStatus(newStatus) {
+        this.status = newStatus;
+    }
+    /**
+     * Check if agent is terminating
+     */
+    isTerminating() {
+        return this.status === types_1.AgentStatus.TERMINATING || this.status === types_1.AgentStatus.TERMINATED;
+    }
+}
+exports.AgentLifecycleManager = AgentLifecycleManager;
+//# sourceMappingURL=AgentLifecycleManager.js.map

package/dist/agents/lifecycle/AgentLifecycleManager.js.map

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