/**
 * Orchestrator Heartbeat Monitor Service
 *
 * Monitors the orchestrator's heartbeat and takes progressive action
 * when the orchestrator becomes unresponsive:
 *
 * 1. Implicit heartbeat: Every API call with X-Agent-Session header
 *    automatically updates the orchestrator's heartbeat timestamp
 *    (handled by agentHeartbeatMiddleware — not this service).
 *
 * 2. Active heartbeat request: After HEARTBEAT_REQUEST_THRESHOLD_MS
 *    without any API activity, this service sends a heartbeat request
 *    message directly into the orchestrator's PTY session.
 *
 * 3. Auto-restart + resume: After an additional RESTART_THRESHOLD_MS
 *    with no response, this service triggers OrchestratorRestartService
 *    to kill and recreate the orchestrator PTY session.
 *
 * @module orchestrator-heartbeat-monitor.service
 */
import type { ISessionBackend } from '../session/session-backend.interface.js';
/**
 * Per-agent API activity record for on-demand heartbeat optimization.
 */
export interface AgentActivityRecord {
    /** Last time this agent made an API call (unix ms) */
    lastApiCallTime: number;
    /** Agent's role (orchestrator gets unconditional heartbeat) */
    role: string;
    /** Whether heartbeat is currently suspended for this agent */
    suspended: boolean;
}
/**
 * Internal state for the heartbeat monitor.
 */
export interface HeartbeatMonitorState {
    /** Whether the monitor is currently running */
    isRunning: boolean;
    /** Timestamp when the heartbeat request was sent (null if none pending) */
    heartbeatRequestSentAt: number | null;
    /** Number of heartbeat requests sent since last successful heartbeat */
    heartbeatRequestCount: number;
    /** Number of auto-restarts triggered by this monitor */
    autoRestartCount: number;
    /** Timestamp when the service started monitoring */
    startedAt: number | null;
    /** Timestamp when the orchestrator was first seen in_progress (null if idle) */
    inProgressSince: number | null;
    /** Per-agent activity tracking */
    agentActivity: Map<string, AgentActivityRecord>;
}
/**
 * Monitors the orchestrator's heartbeat and takes progressive action
 * when it becomes unresponsive.
 *
 * The monitor uses PtyActivityTrackerService as the single source of truth
 * for orchestrator activity. The agentHeartbeatMiddleware calls
 * PtyActivityTrackerService.recordActivity() on every API call with
 * X-Agent-Session header, so any skill call counts as a heartbeat.
 *
 * @example
 * ```typescript
 * const monitor = OrchestratorHeartbeatMonitorService.getInstance();
 * monitor.setDependencies(sessionBackend);
 * monitor.start();
 * // ... later
 * monitor.stop();
 * ```
 */
export declare class OrchestratorHeartbeatMonitorService {
    private static instance;
    private logger;
    /** Interval timer handle */
    private checkTimer;
    /** When the heartbeat request was sent to the orchestrator PTY */
    private heartbeatRequestSentAt;
    /** Counter for heartbeat requests sent */
    private heartbeatRequestCount;
    /** Counter for auto-restarts triggered */
    private autoRestartCount;
    /** When monitoring started */
    private startedAt;
    /** When the orchestrator was first seen with recent activity but no idle period.
     *  Used to detect stuck in_progress state where spinner animation prevents
     *  idle detection from ever exceeding the heartbeat threshold. */
    private inProgressSince;
    /** Session backend for writing to orchestrator PTY */
    private sessionBackend;
    /** Optional callback used to suppress idle heartbeats when no work is pending. */
    private hasPendingWork;
    /** Per-agent API activity tracking for on-demand heartbeat optimization */
    private agentActivity;
    /** Threshold for considering an agent "recently active" (skip heartbeat) — 2 minutes */
    private static readonly RECENT_ACTIVITY_THRESHOLD_MS;
    /** Threshold for suspending heartbeat for idle agents — 10 minutes */
    private static readonly IDLE_SUSPEND_THRESHOLD_MS;
    private constructor();
    /**
     * Get the singleton instance.
     *
     * @returns The OrchestratorHeartbeatMonitorService singleton
     */
    static getInstance(): OrchestratorHeartbeatMonitorService;
    /**
     * Reset the singleton (for testing).
     */
    static resetInstance(): void;
    /**
     * Inject the session backend dependency.
     *
     * @param sessionBackend - Session backend for accessing the orchestrator PTY
     */
    setDependencies(sessionBackend: ISessionBackend, hasPendingWork?: () => boolean): void;
    /**
     * Start the heartbeat monitoring loop.
     * Applies a startup grace period before the first check.
     */
    start(): void;
    /**
     * Stop the heartbeat monitoring loop.
     */
    stop(): void;
    /**
     * Check if the monitor is currently running.
     *
     * @returns True if the check loop is active
     */
    isRunning(): boolean;
    /**
     * Get the current state of the heartbeat monitor.
     *
     * @returns Current monitor state for diagnostics
     */
    getState(): HeartbeatMonitorState;
    /**
     * Record an API call for an agent. Updates lastApiCallTime and
     * un-suspends the agent if it was previously suspended.
     *
     * Called by the heartbeat middleware on every API request with
     * an X-Agent-Session header.
     *
     * @param sessionName - The agent's session name
     * @param role - The agent's role
     */
    recordAgentApiCall(sessionName: string, role: string): void;
    /**
     * Check whether heartbeat should be skipped for a given agent.
     *
     * Rules:
     * - Orchestrator role: NEVER skip (unconditional heartbeat)
     * - Agent with recent API activity: skip (already known alive)
     * - Agent suspended due to prolonged idle: skip
     *
     * @param sessionName - The agent's session name
     * @returns True if heartbeat should be skipped
     */
    shouldSkipHeartbeat(sessionName: string): boolean;
    /**
     * Suspend heartbeat for agents that have been idle beyond the
     * idle suspension threshold. Called periodically to clean up
     * agents that are no longer active.
     *
     * @returns Number of agents newly suspended
     */
    suspendIdleAgents(): number;
    /**
     * Get the activity record for a specific agent.
     *
     * @param sessionName - The agent's session name
     * @returns The agent's activity record, or undefined
     */
    getAgentActivity(sessionName: string): AgentActivityRecord | undefined;
    /**
     * Perform a single heartbeat check cycle.
     *
     * Decision tree:
     * 1. If within startup grace period → skip
     * 2. If orchestrator session doesn't exist → skip (not started yet)
     * 3. If recent API activity → clear any pending heartbeat request
     * 4. If heartbeat request pending and RESTART_THRESHOLD_MS exceeded → auto-restart
     * 5. If no activity for HEARTBEAT_REQUEST_THRESHOLD_MS → send heartbeat request
     */
    performCheck(): Promise<void>;
    /**
     * Send a heartbeat request message to the orchestrator PTY.
     * This writes the heartbeat request directly into the orchestrator's terminal.
     */
    private sendHeartbeatRequest;
    /**
     * Trigger an auto-restart of the orchestrator via OrchestratorRestartService.
     * Also notifies the Auditor agent so it can log the incident and handle
     * any user messages that arrive during the restart window.
     */
    private triggerAutoRestart;
    /**
     * Notify the Auditor agent that the orchestrator is down / being restarted.
     * The Auditor can log the incident and handle any user messages that arrive
     * during the restart window.
     */
    private notifyAuditorOfOrchestratorDown;
}
//# sourceMappingURL=orchestrator-heartbeat-monitor.service.d.ts.map