crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/services/agent/agent-suspend.service.js

@@ -0,0 +1,304 @@
+/**
+ * Agent Suspend Service
+ *
+ * Central coordinator for the agent suspend/rehydrate lifecycle.
+ * Suspends idle agents to free resources (RAM/disk) and transparently
+ * rehydrates them when the orchestrator sends a message, using
+ * Claude Code's `--resume` flag to restore conversation context.
+ *
+ * @module agent-suspend-service
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { StorageService } from '../core/storage.service.js';
+import { CREWLY_CONSTANTS, AGENT_SUSPEND_CONSTANTS } from '../../constants.js';
+import { PtyActivityTrackerService } from './pty-activity-tracker.service.js';
+import { DiskCleanupService } from './disk-cleanup.service.js';
+import { RuntimeExitMonitorService } from './runtime-exit-monitor.service.js';
+import { getSessionBackendSync, getSessionStatePersistence } from '../session/index.js';
+import { getTerminalGateway } from '../../websocket/terminal.gateway.js';
+/**
+ * Manages suspension and rehydration of idle agents.
+ *
+ * Lifecycle:
+ * - `active → suspended`: Idle timeout triggers suspendAgent()
+ * - `suspended → starting → active`: Message triggers rehydrateAgent()
+ * - `suspended → inactive`: Manual stop by user
+ */
+export class AgentSuspendService {
+    static instance = null;
+    logger;
+    /** Map of sessionName → suspended agent metadata */
+    suspendedAgents = new Map();
+    /** Set of sessionNames currently being rehydrated (dedup guard) */
+    rehydratingSet = new Set();
+    /** Injected AgentRegistrationService (set via setDependencies) */
+    agentRegistrationService = null;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('AgentSuspend');
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The AgentSuspendService singleton
+     */
+    static getInstance() {
+        if (!AgentSuspendService.instance) {
+            AgentSuspendService.instance = new AgentSuspendService();
+        }
+        return AgentSuspendService.instance;
+    }
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance() {
+        AgentSuspendService.instance = null;
+    }
+    /**
+     * Inject the AgentRegistrationService dependency.
+     * Must be called during server startup before rehydration can work.
+     *
+     * @param registrationService - The AgentRegistrationService instance
+     */
+    setDependencies(registrationService) {
+        this.agentRegistrationService = registrationService;
+        this.logger.info('AgentSuspendService dependencies set');
+    }
+    /**
+     * Suspend an active agent, killing its process but preserving
+     * the Claude session ID so it can be rehydrated later.
+     *
+     * @param sessionName - PTY session name
+     * @param teamId - Team ID
+     * @param memberId - Member ID within the team
+     * @param role - Agent role
+     * @returns True if suspension was successful
+     */
+    async suspendAgent(sessionName, teamId, memberId, role) {
+        // Guard: exempt roles
+        if (AGENT_SUSPEND_CONSTANTS.EXEMPT_ROLES.includes(role)) {
+            this.logger.warn('Cannot suspend exempt role', { sessionName, role });
+            return false;
+        }
+        // Guard: already suspended
+        if (this.suspendedAgents.has(sessionName)) {
+            this.logger.warn('Agent is already suspended', { sessionName });
+            return false;
+        }
+        try {
+            // Get Claude session ID from persistence before killing
+            let claudeSessionId;
+            try {
+                const persistence = getSessionStatePersistence();
+                claudeSessionId = persistence.getSessionId(sessionName);
+            }
+            catch {
+                this.logger.warn('Could not retrieve Claude session ID for suspend', { sessionName });
+            }
+            // Save suspend info
+            const info = {
+                sessionName,
+                teamId,
+                memberId,
+                role,
+                claudeSessionId,
+                suspendedAt: new Date().toISOString(),
+            };
+            this.suspendedAgents.set(sessionName, info);
+            // Stop runtime exit monitoring (don't trigger exit callbacks)
+            RuntimeExitMonitorService.getInstance().stopMonitoring(sessionName);
+            // Kill the PTY session
+            const backend = getSessionBackendSync();
+            if (backend && backend.sessionExists(sessionName)) {
+                await backend.killSession(sessionName);
+            }
+            // Clear PTY activity tracker
+            PtyActivityTrackerService.getInstance().clearSession(sessionName);
+            // Run disk cleanup
+            DiskCleanupService.getInstance().runSuspendCleanup();
+            // Update status to suspended
+            await StorageService.getInstance().updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.SUSPENDED);
+            // Broadcast status change to frontend
+            const terminalGateway = getTerminalGateway();
+            if (terminalGateway) {
+                terminalGateway.broadcastTeamMemberStatus({
+                    teamId,
+                    memberId,
+                    sessionName,
+                    agentStatus: CREWLY_CONSTANTS.AGENT_STATUSES.SUSPENDED,
+                });
+            }
+            this.logger.info('Agent suspended successfully', {
+                sessionName,
+                role,
+                claudeSessionId: claudeSessionId ? '(saved)' : '(none)',
+            });
+            return true;
+        }
+        catch (error) {
+            // Rollback: remove from suspended map on failure
+            this.suspendedAgents.delete(sessionName);
+            this.logger.error('Failed to suspend agent', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Rehydrate a suspended agent by recreating its session.
+     * Uses the saved Claude session ID for `--resume` to restore context.
+     *
+     * @param sessionName - PTY session name of the suspended agent
+     * @returns True if rehydration was initiated (not necessarily complete)
+     */
+    async rehydrateAgent(sessionName) {
+        // Guard: deduplicate concurrent calls
+        if (this.rehydratingSet.has(sessionName)) {
+            this.logger.debug('Rehydration already in progress', { sessionName });
+            return true;
+        }
+        const info = this.suspendedAgents.get(sessionName);
+        if (!info) {
+            this.logger.warn('Cannot rehydrate: agent not in suspended map', { sessionName });
+            return false;
+        }
+        this.rehydratingSet.add(sessionName);
+        try {
+            // Update status to starting
+            await StorageService.getInstance().updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.STARTING);
+            // Broadcast starting status
+            const terminalGateway = getTerminalGateway();
+            if (terminalGateway) {
+                terminalGateway.broadcastTeamMemberStatus({
+                    teamId: info.teamId,
+                    memberId: info.memberId,
+                    sessionName,
+                    agentStatus: CREWLY_CONSTANTS.AGENT_STATUSES.STARTING,
+                });
+            }
+            // Ensure session persistence has the saved claudeSessionId
+            // so createAgentSession's resume logic picks it up
+            if (info.claudeSessionId) {
+                try {
+                    const persistence = getSessionStatePersistence();
+                    const metadata = persistence.getSessionMetadata(sessionName);
+                    if (metadata) {
+                        persistence.updateSessionId(sessionName, info.claudeSessionId);
+                    }
+                }
+                catch {
+                    this.logger.warn('Could not pre-set session ID for resume', { sessionName });
+                }
+            }
+            if (!this.agentRegistrationService) {
+                this.logger.error('Cannot rehydrate: AgentRegistrationService not set (call setDependencies first)');
+                return false;
+            }
+            // Recreate the agent session (this triggers the resume flow internally)
+            const result = await this.agentRegistrationService.createAgentSession({
+                sessionName,
+                role: info.role,
+                teamId: info.teamId,
+                memberId: info.memberId,
+            });
+            if (!result.success) {
+                this.logger.error('Rehydration createAgentSession failed', {
+                    sessionName,
+                    error: result.error,
+                });
+                // Revert to suspended status
+                await StorageService.getInstance().updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.SUSPENDED);
+                return false;
+            }
+            // Wait for agent to become active (poll with timeout)
+            const timeoutMs = AGENT_SUSPEND_CONSTANTS.REHYDRATION_TIMEOUT_MS;
+            const pollInterval = 2000;
+            const startTime = Date.now();
+            let active = false;
+            while (Date.now() - startTime < timeoutMs) {
+                const memberResult = await StorageService.getInstance().findMemberBySessionName(sessionName);
+                if (memberResult?.member.agentStatus === CREWLY_CONSTANTS.AGENT_STATUSES.ACTIVE) {
+                    active = true;
+                    break;
+                }
+                await new Promise(resolve => setTimeout(resolve, pollInterval));
+            }
+            if (active) {
+                // Success — remove from suspended map
+                this.suspendedAgents.delete(sessionName);
+                this.logger.info('Agent rehydrated successfully', { sessionName });
+                return true;
+            }
+            else {
+                this.logger.warn('Rehydration timed out waiting for active status', {
+                    sessionName,
+                    timeoutMs,
+                });
+                // Leave in suspended map — messages remain queued
+                return false;
+            }
+        }
+        catch (error) {
+            this.logger.error('Rehydration failed', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Revert to suspended status
+            try {
+                await StorageService.getInstance().updateAgentStatus(sessionName, CREWLY_CONSTANTS.AGENT_STATUSES.SUSPENDED);
+            }
+            catch {
+                // Best effort
+            }
+            return false;
+        }
+        finally {
+            this.rehydratingSet.delete(sessionName);
+        }
+    }
+    /**
+     * Check if a session is currently suspended.
+     *
+     * @param sessionName - PTY session name
+     * @returns True if the agent is suspended
+     */
+    isSuspended(sessionName) {
+        return this.suspendedAgents.has(sessionName);
+    }
+    /**
+     * Check if a session is currently being rehydrated.
+     *
+     * @param sessionName - PTY session name
+     * @returns True if rehydration is in progress
+     */
+    isRehydrating(sessionName) {
+        return this.rehydratingSet.has(sessionName);
+    }
+    /**
+     * Get suspend information for a session.
+     *
+     * @param sessionName - PTY session name
+     * @returns Suspend info or null if not suspended
+     */
+    getSuspendInfo(sessionName) {
+        return this.suspendedAgents.get(sessionName) ?? null;
+    }
+    /**
+     * Remove an agent from the suspended map without rehydrating.
+     * Used when a suspended agent is manually stopped by the user.
+     *
+     * @param sessionName - PTY session name
+     */
+    removeSuspended(sessionName) {
+        this.suspendedAgents.delete(sessionName);
+    }
+    /**
+     * Get the count of currently suspended agents.
+     *
+     * @returns Number of suspended agents
+     */
+    getSuspendedCount() {
+        return this.suspendedAgents.size;
+    }
+}
+//# sourceMappingURL=agent-suspend.service.js.map

package/dist/cli/backend/src/services/agent/agent-suspend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-suspend.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/agent/agent-suspend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAmB,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAqBzE;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAmB;IACvB,MAAM,CAAC,QAAQ,GAA+B,IAAI,CAAC;IACnD,MAAM,CAAkB;IAEhC,oDAAoD;IAC5C,eAAe,GAAoC,IAAI,GAAG,EAAE,CAAC;IAErE,mEAAmE;IAC3D,cAAc,GAAgB,IAAI,GAAG,EAAE,CAAC;IAEhD,kEAAkE;IAC1D,wBAAwB,GAAoC,IAAI,CAAC;IAEzE;QACC,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAAC,cAAc,CAAC,CAAC;IACjF,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,WAAW;QACjB,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC;YACnC,mBAAmB,CAAC,QAAQ,GAAG,IAAI,mBAAmB,EAAE,CAAC;QAC1D,CAAC;QACD,OAAO,mBAAmB,CAAC,QAAQ,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa;QACnB,mBAAmB,CAAC,QAAQ,GAAG,IAAI,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,mBAA6C;QAC5D,IAAI,CAAC,wBAAwB,GAAG,mBAAmB,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,YAAY,CACjB,WAAmB,EACnB,MAAc,EACd,QAAgB,EAChB,IAAY;QAEZ,sBAAsB;QACtB,IAAI,uBAAuB,CAAC,YAAY,CAAC,QAAQ,CAAC,IAA2D,CAAC,EAAE,CAAC;YAChH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;YACtE,OAAO,KAAK,CAAC;QACd,CAAC;QAED,2BAA2B;QAC3B,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YAChE,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACJ,wDAAwD;YACxD,IAAI,eAAmC,CAAC;YACxC,IAAI,CAAC;gBACJ,MAAM,WAAW,GAAG,0BAA0B,EAAE,CAAC;gBACjD,eAAe,GAAG,WAAW,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACR,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,kDAAkD,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YACvF,CAAC;YAED,oBAAoB;YACpB,MAAM,IAAI,GAAuB;gBAChC,WAAW;gBACX,MAAM;gBACN,QAAQ;gBACR,IAAI;gBACJ,eAAe;gBACf,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACrC,CAAC;YACF,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YAE5C,8DAA8D;YAC9D,yBAAyB,CAAC,WAAW,EAAE,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;YAEpE,uBAAuB;YACvB,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;YACxC,IAAI,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnD,MAAM,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;YACxC,CAAC;YAED,6BAA6B;YAC7B,yBAAyB,CAAC,WAAW,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAElE,mBAAmB;YACnB,kBAAkB,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC;YAErD,6BAA6B;YAC7B,MAAM,cAAc,CAAC,WAAW,EAAE,CAAC,iBAAiB,CACnD,WAAW,EACX,gBAAgB,CAAC,cAAc,CAAC,SAAgB,CAChD,CAAC;YAEF,sCAAsC;YACtC,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;YAC7C,IAAI,eAAe,EAAE,CAAC;gBACrB,eAAe,CAAC,yBAAyB,CAAC;oBACzC,MAAM;oBACN,QAAQ;oBACR,WAAW;oBACX,WAAW,EAAE,gBAAgB,CAAC,cAAc,CAAC,SAAS;iBACtD,CAAC,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE;gBAChD,WAAW;gBACX,IAAI;gBACJ,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;aACvD,CAAC,CAAC;YAEH,OAAO,IAAI,CAAC;QACb,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,iDAAiD;YACjD,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE;gBAC5C,WAAW;gBACX,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC7D,CAAC,CAAC;YACH,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAAC,WAAmB;QACvC,sCAAsC;QACtC,IAAI,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YACtE,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,8CAA8C,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YAClF,OAAO,KAAK,CAAC;QACd,CAAC;QAED,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAErC,IAAI,CAAC;YACJ,4BAA4B;YAC5B,MAAM,cAAc,CAAC,WAAW,EAAE,CAAC,iBAAiB,CACnD,WAAW,EACX,gBAAgB,CAAC,cAAc,CAAC,QAAe,CAC/C,CAAC;YAEF,4BAA4B;YAC5B,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;YAC7C,IAAI,eAAe,EAAE,CAAC;gBACrB,eAAe,CAAC,yBAAyB,CAAC;oBACzC,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,WAAW;oBACX,WAAW,EAAE,gBAAgB,CAAC,cAAc,CAAC,QAAQ;iBACrD,CAAC,CAAC;YACJ,CAAC;YAED,2DAA2D;YAC3D,mDAAmD;YACnD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACJ,MAAM,WAAW,GAAG,0BAA0B,EAAE,CAAC;oBACjD,MAAM,QAAQ,GAAG,WAAW,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC;oBAC7D,IAAI,QAAQ,EAAE,CAAC;wBACd,WAAW,CAAC,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;oBAChE,CAAC;gBACF,CAAC;gBAAC,MAAM,CAAC;oBACR,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yCAAyC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;gBAC9E,CAAC;YACF,CAAC;YAED,IAAI,CAAC,IAAI,CAAC,wBAAwB,EAAE,CAAC;gBACpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iFAAiF,CAAC,CAAC;gBACrG,OAAO,KAAK,CAAC;YACd,CAAC;YAED,wEAAwE;YACxE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,wBAAwB,CAAC,kBAAkB,CAAC;gBACrE,WAAW;gBACX,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACvB,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACrB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,EAAE;oBAC1D,WAAW;oBACX,KAAK,EAAE,MAAM,CAAC,KAAK;iBACnB,CAAC,CAAC;gBACH,6BAA6B;gBAC7B,MAAM,cAAc,CAAC,WAAW,EAAE,CAAC,iBAAiB,CACnD,WAAW,EACX,gBAAgB,CAAC,cAAc,CAAC,SAAgB,CAChD,CAAC;gBACF,OAAO,KAAK,CAAC;YACd,CAAC;YAED,sDAAsD;YACtD,MAAM,SAAS,GAAG,uBAAuB,CAAC,sBAAsB,CAAC;YACjE,MAAM,YAAY,GAAG,IAAI,CAAC;YAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC7B,IAAI,MAAM,GAAG,KAAK,CAAC;YAEnB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC;gBAC3C,MAAM,YAAY,GAAG,MAAM,cAAc,CAAC,WAAW,EAAE,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC;gBAC7F,IAAI,YAAY,EAAE,MAAM,CAAC,WAAW,KAAK,gBAAgB,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;oBACjF,MAAM,GAAG,IAAI,CAAC;oBACd,MAAM;gBACP,CAAC;gBACD,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;YACjE,CAAC;YAED,IAAI,MAAM,EAAE,CAAC;gBACZ,sCAAsC;gBACtC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;gBACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;gBACnE,OAAO,IAAI,CAAC;YACb,CAAC;iBAAM,CAAC;gBACP,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iDAAiD,EAAE;oBACnE,WAAW;oBACX,SAAS;iBACT,CAAC,CAAC;gBACH,kDAAkD;gBAClD,OAAO,KAAK,CAAC;YACd,CAAC;QACF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE;gBACvC,WAAW;gBACX,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC7D,CAAC,CAAC;YACH,6BAA6B;YAC7B,IAAI,CAAC;gBACJ,MAAM,cAAc,CAAC,WAAW,EAAE,CAAC,iBAAiB,CACnD,WAAW,EACX,gBAAgB,CAAC,cAAc,CAAC,SAAgB,CAChD,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACR,cAAc;YACf,CAAC;YACD,OAAO,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACV,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QACzC,CAAC;IACF,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,WAAmB;QAC9B,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,WAAmB;QAChC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,WAAmB;QACjC,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,WAAmB;QAClC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,iBAAiB;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;IAClC,CAAC"}

package/dist/cli/backend/src/services/agent/auditor-scheduler.service.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Auditor Scheduler Service
+ *
+ * Manages the lifecycle and triggering of the Crewly Auditor agent.
+ * The auditor runs as a Claude Code PTY session — initialized at server start
+ * and kept alive until the service stops.
+ *
+ * Three trigger layers:
+ *   L1 — Periodic: setInterval every AUDIT_INTERVAL_MS (15 min)
+ *   L2 — Event-driven: EventBus events (agent:inactive, task:failed) with debounce
+ *   L3 — API: POST /api/auditor/trigger manual trigger
+ *
+ * Additionally supports direct Slack conversation via handleUserMessage().
+ *
+ * @module services/agent/auditor-scheduler
+ */
+import type { EventBusService } from '../event-bus/event-bus.service.js';
+import type { AgentRegistrationService } from './agent-registration.service.js';
+/**
+ * Status of the AuditorSchedulerService.
+ */
+export type AuditorSchedulerStatus = 'stopped' | 'idle' | 'running_audit';
+/**
+ * Result from a trigger attempt.
+ */
+export interface AuditTriggerResult {
+    /** Whether the audit was started */
+    triggered: boolean;
+    /** Reason if not triggered */
+    reason?: string;
+    /** Trigger source */
+    source: 'periodic' | 'event' | 'api';
+    /** Timestamp */
+    timestamp: string;
+}
+/**
+ * Slack context for user message routing.
+ */
+export interface SlackContext {
+    channelId: string;
+    threadTs: string;
+}
+/**
+ * A scheduled audit item that may need catch-up on restart.
+ */
+export interface ScheduledAuditItem {
+    /** Unique identifier */
+    id: string;
+    /** When the audit was scheduled to fire */
+    scheduledTime: number;
+    /** Source of the schedule */
+    source: AuditTriggerResult['source'];
+    /** Whether the audit was actually fired */
+    fired: boolean;
+}
+/**
+ * Scheduler service that orchestrates Auditor agent lifecycle via Claude Code PTY session.
+ *
+ * Always-active mode: the auditor PTY session is created at start()
+ * and remains alive until stop(). Audit runs send messages to the existing session.
+ *
+ * Singleton — use AuditorSchedulerService.getInstance().
+ *
+ * @example
+ * ```typescript
+ * const scheduler = AuditorSchedulerService.getInstance();
+ * scheduler.setAgentRegistrationService(agentRegService);
+ * scheduler.setEventBusService(eventBus);
+ * scheduler.start();
+ * ```
+ */
+export declare class AuditorSchedulerService {
+    private static instance;
+    private logger;
+    private status;
+    private agentRegistrationService;
+    private eventBusService;
+    private periodicTimer;
+    private eventDebounceTimer;
+    private eventListenerBound;
+    private sessionRecoveryTimer;
+    private auditTimeoutTimer;
+    private lastAuditStart;
+    private auditCount;
+    private sessionReady;
+    private sessionInitializing;
+    private sessionRetryCount;
+    private sessionCooldownUntil;
+    private scheduledItems;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns AuditorSchedulerService instance
+     */
+    static getInstance(): AuditorSchedulerService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Set the AgentRegistrationService for PTY session management.
+     *
+     * @param service - The AgentRegistrationService instance
+     */
+    setAgentRegistrationService(service: AgentRegistrationService): void;
+    /**
+     * Set the EventBusService for L2 event-driven triggers.
+     *
+     * @param eventBus - The EventBusService instance
+     */
+    setEventBusService(eventBus: EventBusService): void;
+    /**
+     * Start all trigger layers and initialize the auditor PTY session.
+     * The auditor session is created immediately (always-active mode).
+     * L1: periodic interval. L2: EventBus listener.
+     */
+    start(): void;
+    /**
+     * Stop all trigger layers, clean up timers, and terminate the PTY session.
+     * Only called when the entire service is shutting down.
+     */
+    stop(): void;
+    /**
+     * Trigger an audit run.
+     *
+     * Checks if an audit is already running, ensures the auditor session exists,
+     * sends the audit command via PTY, and keeps the session alive after completion.
+     *
+     * @param source - What triggered this audit ('periodic', 'event', 'api')
+     * @returns Result indicating whether the audit was triggered
+     */
+    trigger(source: AuditTriggerResult['source']): Promise<AuditTriggerResult>;
+    /**
+     * Handle a user message routed from Slack.
+     *
+     * Passes the message to the auditor PTY session with Slack context
+     * so the auditor can reply directly via the reply_slack tool.
+     *
+     * @param message - User message text (auditor prefix already stripped)
+     * @param slackContext - Slack channel and thread identifiers
+     * @returns Result indicating whether the message was handled
+     */
+    handleUserMessage(message: string, slackContext: SlackContext): Promise<AuditTriggerResult>;
+    /**
+     * Get the current scheduler status and statistics.
+     *
+     * @returns Status object
+     */
+    getStatus(): {
+        status: AuditorSchedulerStatus;
+        auditCount: number;
+        lastAuditStart: string | null;
+        periodicEnabled: boolean;
+        eventListenerBound: boolean;
+        runtimeReady: boolean;
+    };
+    /**
+     * Add a scheduled audit item for future tracking.
+     * Items that are overdue at next startup will be caught up.
+     *
+     * @param scheduledTime - Unix timestamp when the audit should fire
+     * @param source - Trigger source
+     * @returns The created ScheduledAuditItem
+     */
+    addScheduledItem(scheduledTime: number, source: AuditTriggerResult['source']): ScheduledAuditItem;
+    /**
+     * Get all scheduled items (for testing/diagnostics).
+     *
+     * @returns Copy of the scheduled items array
+     */
+    getScheduledItems(): ScheduledAuditItem[];
+    /**
+     * Check for scheduled items where scheduledTime < now and status !== fired,
+     * then fire them immediately. Called on startup/restore to catch up on any
+     * audits that were missed during downtime.
+     *
+     * @returns Number of missed checks that were caught up
+     */
+    catchUpMissedChecks(): Promise<number>;
+    /**
+     * Ensure the auditor Claude Code PTY session exists.
+     * Creates a new session via AgentRegistrationService if not ready.
+     * Guards against concurrent initialization and enforces retry limits
+     * with exponential backoff to prevent restart loops.
+     */
+    private ensureAuditorSession;
+    /**
+     * Bind the EventBus listener for L2 event-driven triggers.
+     * Listens for agent:inactive and task:failed events with debounce.
+     * Uses event_published (fires on ALL published events) instead of
+     * event_delivered (only fires when a subscription match exists).
+     */
+    private bindEventBusListener;
+}
+//# sourceMappingURL=auditor-scheduler.service.d.ts.map

package/dist/cli/backend/src/services/agent/auditor-scheduler.service.d.ts.map

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