mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-09-30 12:39:42 +02:00
480584de63
* add project setup * add tools to eslint * remove contributing.md * update claude md * chore: simplify CI to single Node.js version (22) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * use node 20 * adjust formatting * fix linting * format * fix layout * fix: align CI node version to .nvmrc (22), remove redundant gotcha Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: arkon <arkon.85@hotmail.com>
3622 lines
123 KiB
TypeScript
3622 lines
123 KiB
TypeScript
/**
|
||
* @fileoverview Respawn Controller for autonomous Claude Code session cycling
|
||
*
|
||
* The RespawnController manages automatic respawning of Claude Code sessions.
|
||
* When Claude finishes working (detected by completion message + output silence),
|
||
* it automatically cycles through update → clear → init steps to keep the session productive.
|
||
*
|
||
* ## State Machine
|
||
*
|
||
* ```
|
||
* WATCHING → CONFIRMING_IDLE → SENDING_UPDATE → WAITING_UPDATE → SENDING_CLEAR → WAITING_CLEAR
|
||
* ↑ │ │
|
||
* │ │ (new output) ▼
|
||
* │ └─────────────► SENDING_INIT → WAITING_INIT → MONITORING_INIT ────────┘
|
||
* │ │
|
||
* │ ▼ (if no work triggered)
|
||
* └──────────────────────── SENDING_KICKSTART → WAITING_KICKSTART ──┘
|
||
* ```
|
||
*
|
||
* ## Idle Detection (Updated for Claude Code 2024+)
|
||
*
|
||
* Primary detection: Completion message pattern "for Xm Xs" (e.g., "✻ Worked for 2m 46s")
|
||
* Confirmation: No new output for configurable duration (default 5s)
|
||
* Fallback: No output at all for extended period (default 30s)
|
||
*
|
||
* ## Configuration
|
||
*
|
||
* - `sendClear`: Whether to send /clear after update (default: true)
|
||
* - `sendInit`: Whether to send /init after clear (default: true)
|
||
* - `kickstartPrompt`: Optional prompt if /init doesn't trigger work
|
||
* - `completionConfirmMs`: Time to wait after completion message (default: 10000)
|
||
* - `noOutputTimeoutMs`: Fallback timeout with no output at all (default: 30000)
|
||
*
|
||
* @module respawn-controller
|
||
*/
|
||
|
||
import { EventEmitter } from 'node:events';
|
||
import { randomUUID } from 'node:crypto';
|
||
import { Session } from './session.js';
|
||
import { AiIdleChecker, type AiCheckResult, type AiCheckState } from './ai-idle-checker.js';
|
||
import { AiPlanChecker, type AiPlanCheckResult } from './ai-plan-checker.js';
|
||
import type { TeamWatcher } from './team-watcher.js';
|
||
import { BufferAccumulator } from './utils/buffer-accumulator.js';
|
||
import { ANSI_ESCAPE_PATTERN_SIMPLE, TOKEN_PATTERN, assertNever } from './utils/index.js';
|
||
import { MAX_RESPAWN_BUFFER_SIZE, TRIM_RESPAWN_BUFFER_TO as RESPAWN_BUFFER_TRIM_SIZE } from './config/buffer-limits.js';
|
||
import type {
|
||
RespawnCycleMetrics,
|
||
RespawnAggregateMetrics,
|
||
RalphLoopHealthScore,
|
||
TimingHistory,
|
||
CycleOutcome,
|
||
HealthStatus,
|
||
} from './types.js';
|
||
|
||
// ========== Constants ==========
|
||
|
||
/**
|
||
* Pattern to detect completion messages from Claude Code.
|
||
* Requires "Worked for" prefix to avoid false positives from bare time durations
|
||
* in regular text (e.g., "wait for 5s", "run for 2m").
|
||
*
|
||
* Matches: "✻ Worked for 2m 46s", "Worked for 46s", "Worked for 1h 2m 3s"
|
||
* Does NOT match: "wait for 5s", "run for 2m", "for 3s the system..."
|
||
*/
|
||
const COMPLETION_TIME_PATTERN = /\bWorked\s+for\s+\d+[hms](\s*\d+[hms])*/i;
|
||
|
||
/** Pre-filter: numbered option pattern for plan mode detection */
|
||
const PLAN_MODE_OPTION_PATTERN = /\d+\.\s+(Yes|No|Type|Cancel|Skip|Proceed|Approve|Reject)/i;
|
||
|
||
/** Pre-filter: selection indicator arrow for plan mode detection */
|
||
const PLAN_MODE_SELECTOR_PATTERN = /[❯>]\s*\d+\./;
|
||
|
||
// Note: The old '↵ send' indicator is no longer reliable in Claude Code 2024+
|
||
// Detection now uses completion message patterns ("for Xm Xs") instead.
|
||
|
||
// ========== Detection Layer Types ==========
|
||
|
||
/**
|
||
* Detection layers for multi-signal idle detection.
|
||
* Each layer provides a confidence signal that Claude has finished working.
|
||
*/
|
||
/** Active timer info for UI display */
|
||
export interface ActiveTimerInfo {
|
||
name: string;
|
||
remainingMs: number;
|
||
totalMs: number;
|
||
}
|
||
|
||
export interface DetectionStatus {
|
||
/** Layer 0: Stop hook received (highest priority - definitive signal) */
|
||
stopHookReceived: boolean;
|
||
/** Timestamp when Stop hook was received */
|
||
stopHookTime: number | null;
|
||
/** Layer 0: idle_prompt notification received (definitive signal) */
|
||
idlePromptReceived: boolean;
|
||
/** Timestamp when idle_prompt was received */
|
||
idlePromptTime: number | null;
|
||
|
||
/** Layer 1: Completion message detected ("for Xm Xs") */
|
||
completionMessageDetected: boolean;
|
||
/** Timestamp when completion message was last seen */
|
||
completionMessageTime: number | null;
|
||
|
||
/** Layer 2: Output silence - no new output for threshold duration */
|
||
outputSilent: boolean;
|
||
/** Milliseconds since last output */
|
||
msSinceLastOutput: number;
|
||
|
||
/** Layer 3: Token count stability - tokens haven't changed */
|
||
tokensStable: boolean;
|
||
/** Last observed token count */
|
||
lastTokenCount: number;
|
||
/** Milliseconds since token count changed */
|
||
msSinceTokenChange: number;
|
||
|
||
/** Layer 4: Working patterns absent - no spinners/activity words */
|
||
workingPatternsAbsent: boolean;
|
||
/** Milliseconds since last working pattern */
|
||
msSinceLastWorking: number;
|
||
|
||
/** Layer 5: AI idle check status */
|
||
aiCheck: AiCheckState | null;
|
||
|
||
/** Overall confidence level (0-100) */
|
||
confidenceLevel: number;
|
||
|
||
/** Human-readable status for UI */
|
||
statusText: string;
|
||
|
||
/** What the controller is currently waiting for */
|
||
waitingFor: string;
|
||
|
||
/** Active countdown timers */
|
||
activeTimers: ActiveTimerInfo[];
|
||
|
||
/** Recent action log entries (last 10) */
|
||
recentActions: ActionLogEntry[];
|
||
|
||
/** Current phase description */
|
||
currentPhase: string;
|
||
|
||
/** Next expected action */
|
||
nextAction: string;
|
||
|
||
/** Stuck-state detection metrics */
|
||
stuckState: {
|
||
/** How long the controller has been in the current state (ms) */
|
||
currentStateDurationMs: number;
|
||
/** Warning threshold (ms) */
|
||
warningThresholdMs: number;
|
||
/** Recovery threshold (ms) */
|
||
recoveryThresholdMs: number;
|
||
/** Number of recovery attempts made */
|
||
recoveryAttempts: number;
|
||
/** Maximum allowed recoveries */
|
||
maxRecoveries: number;
|
||
/** Whether a warning has been emitted for current state */
|
||
isWarned: boolean;
|
||
};
|
||
}
|
||
|
||
// ========== Type Definitions ==========
|
||
|
||
/**
|
||
* Respawn sequence states.
|
||
*
|
||
* The controller cycles through these states:
|
||
* ```
|
||
* WATCHING → SENDING_UPDATE → WAITING_UPDATE →
|
||
* SENDING_CLEAR → WAITING_CLEAR →
|
||
* SENDING_INIT → WAITING_INIT →
|
||
* MONITORING_INIT → (maybe SENDING_KICKSTART → WAITING_KICKSTART) →
|
||
* WATCHING (repeat)
|
||
* ```
|
||
*
|
||
* Steps can be skipped via config (`sendClear: false`, `sendInit: false`).
|
||
*/
|
||
export type RespawnState =
|
||
/** Watching for idle, ready to start respawn sequence */
|
||
| 'watching'
|
||
/** Completion message detected, waiting for output silence to confirm */
|
||
| 'confirming_idle'
|
||
/** AI checker is analyzing terminal output for IDLE/WORKING verdict */
|
||
| 'ai_checking'
|
||
/** About to send the update docs prompt */
|
||
| 'sending_update'
|
||
/** Waiting for update to complete */
|
||
| 'waiting_update'
|
||
/** About to send /clear command */
|
||
| 'sending_clear'
|
||
/** Waiting for clear to complete */
|
||
| 'waiting_clear'
|
||
/** About to send /init command */
|
||
| 'sending_init'
|
||
/** Waiting for init to complete */
|
||
| 'waiting_init'
|
||
/** Monitoring if /init triggered work */
|
||
| 'monitoring_init'
|
||
/** About to send kickstart prompt */
|
||
| 'sending_kickstart'
|
||
/** Waiting for kickstart to complete */
|
||
| 'waiting_kickstart'
|
||
/** Controller stopped (not running) */
|
||
| 'stopped';
|
||
|
||
/**
|
||
* Configuration options for the RespawnController.
|
||
*/
|
||
export interface RespawnConfig {
|
||
/**
|
||
* How long to wait after seeing prompt before considering truly idle.
|
||
* Prevents premature cycling when user is about to type.
|
||
* @default 10000 (10 seconds)
|
||
*/
|
||
idleTimeoutMs: number;
|
||
|
||
/**
|
||
* The prompt to send when updating docs.
|
||
* Sent at the start of each respawn cycle.
|
||
* @default 'write a brief progress summary to CLAUDE.md noting what you accomplished, then continue working.'
|
||
*/
|
||
updatePrompt: string;
|
||
|
||
/**
|
||
* Delay between sending steps (ms).
|
||
* Gives Claude time to process each command.
|
||
* @default 1000 (1 second)
|
||
*/
|
||
interStepDelayMs: number;
|
||
|
||
/**
|
||
* Whether the respawn loop is enabled.
|
||
* When false, start() will be a no-op.
|
||
* @default true
|
||
*/
|
||
enabled: boolean;
|
||
|
||
/**
|
||
* Whether to send /clear after update prompt completes.
|
||
* Resets Claude's context for fresh start.
|
||
* @default true
|
||
*/
|
||
sendClear: boolean;
|
||
|
||
/**
|
||
* Whether to send /init after /clear completes.
|
||
* Re-initializes Claude with CLAUDE.md context.
|
||
* @default true
|
||
*/
|
||
sendInit: boolean;
|
||
|
||
/**
|
||
* Optional prompt to send if /init doesn't trigger work.
|
||
* Used as a fallback when /init completes but Claude doesn't start working.
|
||
* @default undefined
|
||
*/
|
||
kickstartPrompt?: string;
|
||
|
||
/**
|
||
* Time to wait after completion message before confirming idle (ms).
|
||
* After seeing "for Xm Xs" pattern, waits this long with no new output.
|
||
* @default 10000 (10 seconds)
|
||
*/
|
||
completionConfirmMs: number;
|
||
|
||
/**
|
||
* Fallback timeout when no output received at all (ms).
|
||
* If no terminal output for this duration, assumes idle even without completion message.
|
||
* @default 30000 (30 seconds)
|
||
*/
|
||
noOutputTimeoutMs: number;
|
||
|
||
/**
|
||
* Whether to auto-accept plan mode prompts by pressing Enter.
|
||
* When Claude enters plan mode and presents a plan for approval, output stops
|
||
* without a completion message. This feature detects that state and sends Enter
|
||
* to accept the plan. Does NOT auto-accept AskUserQuestion prompts (those are
|
||
* blocked via the elicitation_dialog hook signal).
|
||
* @default true
|
||
*/
|
||
autoAcceptPrompts: boolean;
|
||
|
||
/**
|
||
* Delay before auto-accepting plan mode prompts (ms).
|
||
* After no output for this duration AND no completion message detected
|
||
* AND no elicitation dialog signaled, sends Enter to accept the plan.
|
||
* Must be shorter than noOutputTimeoutMs.
|
||
* @default 8000 (8 seconds)
|
||
*/
|
||
autoAcceptDelayMs: number;
|
||
|
||
/**
|
||
* Whether AI idle check is enabled.
|
||
* When enabled, spawns a fresh Claude CLI to analyze terminal output
|
||
* and provide a definitive IDLE/WORKING verdict before starting respawn.
|
||
* @default true
|
||
*/
|
||
aiIdleCheckEnabled: boolean;
|
||
|
||
/**
|
||
* Model to use for AI idle check.
|
||
* @default 'claude-opus-4-5-20251101'
|
||
*/
|
||
aiIdleCheckModel: string;
|
||
|
||
/**
|
||
* Maximum characters of terminal buffer to send to AI checker.
|
||
* @default 16000
|
||
*/
|
||
aiIdleCheckMaxContext: number;
|
||
|
||
/**
|
||
* Timeout for the AI check in ms.
|
||
* @default 90000 (90 seconds)
|
||
*/
|
||
aiIdleCheckTimeoutMs: number;
|
||
|
||
/**
|
||
* Cooldown after WORKING verdict in ms.
|
||
* @default 180000 (3 minutes)
|
||
*/
|
||
aiIdleCheckCooldownMs: number;
|
||
|
||
/**
|
||
* Whether AI plan mode check is enabled for auto-accept.
|
||
* When enabled, spawns a fresh Claude CLI to confirm the terminal is
|
||
* showing a plan mode approval prompt before auto-accepting.
|
||
* @default true
|
||
*/
|
||
aiPlanCheckEnabled: boolean;
|
||
|
||
/**
|
||
* Model to use for AI plan mode check.
|
||
* @default 'claude-opus-4-5-20251101' (thinking enabled by default)
|
||
*/
|
||
aiPlanCheckModel: string;
|
||
|
||
/**
|
||
* Maximum characters of terminal buffer to send to plan checker.
|
||
* @default 8000
|
||
*/
|
||
aiPlanCheckMaxContext: number;
|
||
|
||
/**
|
||
* Timeout for the AI plan check in ms.
|
||
* @default 60000 (60 seconds, allows time for thinking)
|
||
*/
|
||
aiPlanCheckTimeoutMs: number;
|
||
|
||
/**
|
||
* Cooldown after NOT_PLAN_MODE verdict in ms.
|
||
* @default 30000 (30 seconds)
|
||
*/
|
||
aiPlanCheckCooldownMs: number;
|
||
|
||
/**
|
||
* Enable stuck-state detection.
|
||
* Detects when the controller stays in the same state for too long.
|
||
* @default true
|
||
*/
|
||
stuckStateDetectionEnabled: boolean;
|
||
|
||
/**
|
||
* Threshold for stuck-state warning in ms.
|
||
* If state doesn't change for this duration, emits a warning.
|
||
* @default 300000 (5 minutes)
|
||
*/
|
||
stuckStateWarningMs: number;
|
||
|
||
/**
|
||
* Threshold for stuck-state recovery in ms.
|
||
* If state doesn't change for this duration, triggers recovery action.
|
||
* @default 600000 (10 minutes)
|
||
*/
|
||
stuckStateRecoveryMs: number;
|
||
|
||
/**
|
||
* Maximum consecutive stuck-state recoveries before giving up.
|
||
* @default 3
|
||
*/
|
||
maxStuckRecoveries: number;
|
||
|
||
// ========== P2-001: Adaptive Timing ==========
|
||
|
||
/**
|
||
* Enable adaptive timing based on historical patterns.
|
||
* Adjusts completion confirm timeout dynamically.
|
||
* @default true
|
||
*/
|
||
adaptiveTimingEnabled?: boolean;
|
||
|
||
/**
|
||
* Minimum adaptive completion confirm timeout (ms).
|
||
* @default 5000
|
||
*/
|
||
adaptiveMinConfirmMs?: number;
|
||
|
||
/**
|
||
* Maximum adaptive completion confirm timeout (ms).
|
||
* @default 30000
|
||
*/
|
||
adaptiveMaxConfirmMs?: number;
|
||
|
||
// ========== P2-002: Skip-Clear Optimization ==========
|
||
|
||
/**
|
||
* Skip /clear when context usage is low.
|
||
* @default true
|
||
*/
|
||
skipClearWhenLowContext?: boolean;
|
||
|
||
/**
|
||
* Context threshold percentage below which to skip /clear.
|
||
* @default 30
|
||
*/
|
||
skipClearThresholdPercent?: number;
|
||
|
||
// ========== P2-004: Cycle Metrics ==========
|
||
|
||
/**
|
||
* Enable tracking of respawn cycle metrics.
|
||
* @default true
|
||
*/
|
||
trackCycleMetrics?: boolean;
|
||
|
||
// ========== P2-001: Confidence Scoring ==========
|
||
|
||
/**
|
||
* Minimum confidence level required to trigger idle detection.
|
||
* Below this threshold, the controller waits for more signals.
|
||
* @default 65
|
||
*/
|
||
minIdleConfidence?: number;
|
||
|
||
/**
|
||
* Confidence weight for completion message detection.
|
||
* @default 40
|
||
*/
|
||
confidenceWeightCompletion?: number;
|
||
|
||
/**
|
||
* Confidence weight for output silence.
|
||
* @default 25
|
||
*/
|
||
confidenceWeightSilence?: number;
|
||
|
||
/**
|
||
* Confidence weight for token stability.
|
||
* @default 20
|
||
*/
|
||
confidenceWeightTokens?: number;
|
||
|
||
/**
|
||
* Confidence weight for working pattern absence.
|
||
* @default 15
|
||
*/
|
||
confidenceWeightNoWorking?: number;
|
||
}
|
||
|
||
/**
|
||
* Events emitted by RespawnController.
|
||
*
|
||
* @event stateChanged - Fired when state machine transitions
|
||
* @event respawnCycleStarted - Fired when a new cycle begins
|
||
* @event respawnCycleCompleted - Fired when a cycle finishes
|
||
* @event stepSent - Fired when a command is sent to the session
|
||
* @event stepCompleted - Fired when a step finishes (ready indicator detected)
|
||
* @event detectionUpdate - Fired when detection status changes (for UI)
|
||
* @event error - Fired on errors
|
||
* @event log - Fired for debug logging
|
||
*/
|
||
/** Timer info for countdown display */
|
||
export interface TimerInfo {
|
||
name: string;
|
||
durationMs: number;
|
||
endsAt: number;
|
||
reason?: string;
|
||
}
|
||
|
||
/** Action log entry for detailed UI feedback */
|
||
export interface ActionLogEntry {
|
||
type: string;
|
||
detail: string;
|
||
timestamp: number;
|
||
}
|
||
|
||
export interface RespawnEvents {
|
||
/** State machine transition */
|
||
stateChanged: (state: RespawnState, prevState: RespawnState) => void;
|
||
/** New respawn cycle started */
|
||
respawnCycleStarted: (cycleNumber: number) => void;
|
||
/** Respawn cycle finished */
|
||
respawnCycleCompleted: (cycleNumber: number) => void;
|
||
/** Command sent to session */
|
||
stepSent: (step: string, input: string) => void;
|
||
/** Step completed (ready indicator detected) */
|
||
stepCompleted: (step: string) => void;
|
||
/** Detection status update for UI display */
|
||
detectionUpdate: (status: DetectionStatus) => void;
|
||
/** Auto-accept sent for plan mode approval */
|
||
autoAcceptSent: () => void;
|
||
/** AI idle check started */
|
||
aiCheckStarted: () => void;
|
||
/** AI idle check completed with verdict */
|
||
aiCheckCompleted: (result: AiCheckResult) => void;
|
||
/** AI idle check failed */
|
||
aiCheckFailed: (error: string) => void;
|
||
/** AI idle check cooldown state changed */
|
||
aiCheckCooldown: (active: boolean, endsAt: number | null) => void;
|
||
/** AI plan check started */
|
||
planCheckStarted: () => void;
|
||
/** AI plan check completed with verdict */
|
||
planCheckCompleted: (result: AiPlanCheckResult) => void;
|
||
/** AI plan check failed */
|
||
planCheckFailed: (error: string) => void;
|
||
/** Timer started for countdown display */
|
||
timerStarted: (timer: TimerInfo) => void;
|
||
/** Timer cancelled */
|
||
timerCancelled: (timerName: string, reason?: string) => void;
|
||
/** Timer completed */
|
||
timerCompleted: (timerName: string) => void;
|
||
/** Verbose action log for detailed UI feedback */
|
||
actionLog: (action: ActionLogEntry) => void;
|
||
/** Error occurred */
|
||
error: (error: Error) => void;
|
||
/** Debug log message */
|
||
log: (message: string) => void;
|
||
/** Stuck state warning emitted */
|
||
stuckStateWarning: (state: RespawnState, durationMs: number) => void;
|
||
/** Stuck state recovery triggered */
|
||
stuckStateRecovery: (state: RespawnState, durationMs: number, attempt: number) => void;
|
||
/** Respawn blocked by external signal */
|
||
respawnBlocked: (data: { reason: string; details: string }) => void;
|
||
}
|
||
|
||
/** Default configuration values */
|
||
const DEFAULT_CONFIG: RespawnConfig = {
|
||
idleTimeoutMs: 10000, // 10 seconds of no activity after prompt (legacy, still used as fallback)
|
||
updatePrompt: 'write a brief progress summary to CLAUDE.md noting what you accomplished, then continue working.',
|
||
interStepDelayMs: 1000, // 1 second between steps
|
||
enabled: true,
|
||
sendClear: true, // send /clear after update prompt
|
||
sendInit: true, // send /init after /clear
|
||
completionConfirmMs: 10000, // 10 seconds of silence after completion message
|
||
noOutputTimeoutMs: 30000, // 30 seconds fallback if no output at all
|
||
autoAcceptPrompts: true, // auto-accept plan mode prompts (not questions)
|
||
autoAcceptDelayMs: 8000, // 8 seconds before auto-accepting
|
||
aiIdleCheckEnabled: true, // use AI to confirm idle state
|
||
aiIdleCheckModel: 'claude-opus-4-5-20251101',
|
||
aiIdleCheckMaxContext: 16000, // ~4k tokens
|
||
aiIdleCheckTimeoutMs: 90000, // 90 seconds (thinking can be slow)
|
||
aiIdleCheckCooldownMs: 180000, // 3 minutes after WORKING verdict
|
||
aiPlanCheckEnabled: true, // use AI to confirm plan mode before auto-accept
|
||
aiPlanCheckModel: 'claude-opus-4-5-20251101',
|
||
aiPlanCheckMaxContext: 8000, // ~2k tokens (plan mode UI is compact)
|
||
aiPlanCheckTimeoutMs: 60000, // 60 seconds (thinking can be slow)
|
||
aiPlanCheckCooldownMs: 30000, // 30 seconds after NOT_PLAN_MODE
|
||
stuckStateDetectionEnabled: true, // detect stuck states
|
||
stuckStateWarningMs: 300000, // 5 minutes warning threshold
|
||
stuckStateRecoveryMs: 600000, // 10 minutes recovery threshold
|
||
maxStuckRecoveries: 3, // max recovery attempts
|
||
// P2-001: Adaptive timing
|
||
adaptiveTimingEnabled: true, // Use adaptive timing based on historical patterns
|
||
adaptiveMinConfirmMs: 5000, // Minimum 5 seconds
|
||
adaptiveMaxConfirmMs: 30000, // Maximum 30 seconds
|
||
// P2-002: Skip-clear optimization
|
||
skipClearWhenLowContext: true, // Skip /clear when token count is low
|
||
skipClearThresholdPercent: 30, // Skip if below 30% of max context
|
||
// P2-004: Cycle metrics
|
||
trackCycleMetrics: true, // Track and persist cycle metrics
|
||
// P2-001: Confidence scoring
|
||
minIdleConfidence: 65, // Minimum confidence to trigger idle (0-100)
|
||
confidenceWeightCompletion: 40, // Weight for completion message
|
||
confidenceWeightSilence: 25, // Weight for output silence
|
||
confidenceWeightTokens: 20, // Weight for token stability
|
||
confidenceWeightNoWorking: 15, // Weight for working pattern absence
|
||
};
|
||
|
||
/**
|
||
* RespawnController - Automatic session cycling for continuous Claude work.
|
||
*
|
||
* Monitors a Claude Code session for idle state and automatically cycles
|
||
* through update → clear → init steps to keep the session productive.
|
||
*
|
||
* ## How It Works
|
||
*
|
||
* 1. **Idle Detection**: Watches for completion message ("for Xm Xs" pattern)
|
||
* 2. **Confirmation**: Waits for output silence (no new tokens for 5s)
|
||
* 3. **Update**: Sends configured prompt (e.g., "update all docs")
|
||
* 4. **Clear**: Sends `/clear` to reset context (optional)
|
||
* 5. **Init**: Sends `/init` to re-initialize with CLAUDE.md (optional)
|
||
* 6. **Kickstart**: If /init doesn't trigger work, sends fallback prompt (optional)
|
||
* 7. **Repeat**: Returns to watching state for next cycle
|
||
*
|
||
* ## Idle Detection (Updated for Claude Code 2024+)
|
||
*
|
||
* Primary: Completion message with time duration (e.g., "✻ Worked for 2m 46s")
|
||
* The pattern "for Xm Xs" indicates Claude finished work and reports duration.
|
||
*
|
||
* Confirmation: After seeing completion message, waits for output silence.
|
||
* If no new output for `completionConfirmMs` (default 10s), confirms idle.
|
||
*
|
||
* Fallback: If no output at all for `noOutputTimeoutMs` (default 30s), assumes idle.
|
||
*
|
||
* Working indicators: Thinking, Writing, spinner characters, etc. reset detection.
|
||
*
|
||
* ## Events
|
||
*
|
||
* - `stateChanged`: State machine transition
|
||
* - `respawnCycleStarted`: New cycle began
|
||
* - `respawnCycleCompleted`: Cycle finished
|
||
* - `stepSent`: Command sent to session
|
||
* - `stepCompleted`: Step finished
|
||
* - `log`: Debug messages
|
||
*
|
||
* @extends EventEmitter
|
||
* @example
|
||
* ```typescript
|
||
* const respawn = new RespawnController(session, {
|
||
* updatePrompt: 'continue working on the task',
|
||
* completionConfirmMs: 10000, // Wait 10s after completion message
|
||
* });
|
||
*
|
||
* respawn.on('respawnCycleCompleted', (cycle) => {
|
||
* console.log(`Completed cycle ${cycle}`);
|
||
* });
|
||
*
|
||
* respawn.start();
|
||
* ```
|
||
*/
|
||
export class RespawnController extends EventEmitter {
|
||
/** The session being controlled */
|
||
private session: Session;
|
||
|
||
/** Optional team watcher for team-aware idle detection */
|
||
private teamWatcher: TeamWatcher | null = null;
|
||
|
||
/** Current configuration */
|
||
private config: RespawnConfig;
|
||
|
||
/** Current state machine state */
|
||
private _state: RespawnState = 'stopped';
|
||
|
||
/** Timer for idle detection timeout */
|
||
private idleTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for step delays */
|
||
private stepTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for completion confirmation (Layer 2) */
|
||
private completionConfirmTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for no-output fallback (Layer 5) */
|
||
private noOutputTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for periodic detection status updates */
|
||
private detectionUpdateTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for auto-accepting plan mode prompts */
|
||
private autoAcceptTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for pre-filter silence detection (triggers AI check) */
|
||
private preFilterTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Whether any terminal output has been received since start/last-auto-accept */
|
||
private hasReceivedOutput: boolean = false;
|
||
|
||
/** Whether an elicitation dialog (AskUserQuestion) was detected via hook signal */
|
||
private elicitationDetected: boolean = false;
|
||
|
||
// ========== Hook-Based Detection State (Layer 0 - Highest Priority) ==========
|
||
|
||
/** Whether a Stop hook was received (definitive idle signal from Claude Code) */
|
||
private stopHookReceived: boolean = false;
|
||
|
||
/** Timestamp when Stop hook was received */
|
||
private stopHookTime: number | null = null;
|
||
|
||
/** Whether an idle_prompt notification was received (60s+ idle signal) */
|
||
private idlePromptReceived: boolean = false;
|
||
|
||
/** Timestamp when idle_prompt was received */
|
||
private idlePromptTime: number | null = null;
|
||
|
||
/** Timer for short confirmation after hook signal (handles race conditions) */
|
||
private hookConfirmTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Confirmation delay after hook signal before confirming idle (ms) */
|
||
private static readonly HOOK_CONFIRM_DELAY_MS = 3000;
|
||
|
||
/** Number of completed respawn cycles */
|
||
private cycleCount: number = 0;
|
||
|
||
/** Timestamp of last terminal activity */
|
||
private lastActivityTime: number = 0;
|
||
|
||
/** Buffer for recent terminal output (uses BufferAccumulator to reduce GC pressure) */
|
||
private terminalBuffer = new BufferAccumulator(MAX_RESPAWN_BUFFER_SIZE, RESPAWN_BUFFER_TRIM_SIZE);
|
||
|
||
/** Whether a prompt indicator was detected */
|
||
private promptDetected: boolean = false;
|
||
|
||
/** Whether a working indicator was detected */
|
||
private workingDetected: boolean = false;
|
||
|
||
/** Reference to terminal event handler (for cleanup) */
|
||
private terminalHandler: ((data: string) => void) | null = null;
|
||
|
||
/** AI idle checker instance */
|
||
private aiChecker: AiIdleChecker;
|
||
|
||
/** AI plan mode checker instance */
|
||
private planChecker: AiPlanChecker;
|
||
|
||
/** Timestamp when plan check was started (to detect stale results) */
|
||
private planCheckStartTime: number = 0;
|
||
|
||
/** Unique ID for current AI check request (to detect stale results) */
|
||
private _currentAiCheckId: string | null = null;
|
||
|
||
/** Timer for /clear step fallback (sends /init if no prompt detected) */
|
||
private clearFallbackTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Timer for step completion confirmation (waits for silence after completion) */
|
||
private stepConfirmTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Fallback timeout for /clear step (ms) - sends /init without waiting for prompt */
|
||
private static readonly CLEAR_FALLBACK_TIMEOUT_MS = 10000;
|
||
|
||
// ========== Timer Tracking for UI Countdown Display ==========
|
||
|
||
/** Active timers being tracked for UI display */
|
||
private activeTimers: Map<string, { name: string; startedAt: number; durationMs: number; endsAt: number }> =
|
||
new Map();
|
||
|
||
/** Recent action log entries (for UI display, max 20) */
|
||
private recentActions: ActionLogEntry[] = [];
|
||
|
||
// ========== Stuck-State Detection State ==========
|
||
|
||
/** Timestamp when the current state was entered */
|
||
private stateEnteredAt: number = 0;
|
||
|
||
/** Timer for stuck-state detection */
|
||
private stuckStateTimer: NodeJS.Timeout | null = null;
|
||
|
||
/** Whether a stuck-state warning has been emitted for current state */
|
||
private stuckStateWarned: boolean = false;
|
||
|
||
/** Number of stuck-state recovery attempts */
|
||
private stuckRecoveryCount: number = 0;
|
||
|
||
// ========== P2-001: Adaptive Timing State ==========
|
||
|
||
/** Historical timing data for adaptive adjustments */
|
||
private timingHistory: TimingHistory = {
|
||
recentIdleDetectionMs: [],
|
||
recentCycleDurationMs: [],
|
||
adaptiveCompletionConfirmMs: 10000, // Start with default
|
||
sampleCount: 0,
|
||
maxSamples: 20, // Keep last 20 samples for rolling average
|
||
lastUpdatedAt: Date.now(),
|
||
};
|
||
|
||
// ========== P2-004: Cycle Metrics State ==========
|
||
|
||
/** Current cycle being tracked */
|
||
private currentCycleMetrics: Partial<RespawnCycleMetrics> | null = null;
|
||
|
||
/** Timestamp when idle detection started for current cycle */
|
||
private idleDetectionStartTime: number = 0;
|
||
|
||
/** Recent cycle metrics (rolling window for aggregate calculation) */
|
||
private recentCycleMetrics: RespawnCycleMetrics[] = [];
|
||
|
||
/** Maximum number of cycle metrics to keep in memory */
|
||
private static readonly MAX_CYCLE_METRICS_IN_MEMORY = 100;
|
||
|
||
/** Aggregate metrics across all tracked cycles */
|
||
private aggregateMetrics: RespawnAggregateMetrics = {
|
||
totalCycles: 0,
|
||
successfulCycles: 0,
|
||
stuckRecoveryCycles: 0,
|
||
blockedCycles: 0,
|
||
errorCycles: 0,
|
||
avgCycleDurationMs: 0,
|
||
avgIdleDetectionMs: 0,
|
||
p90CycleDurationMs: 0,
|
||
successRate: 100,
|
||
lastUpdatedAt: Date.now(),
|
||
};
|
||
|
||
// ========== Multi-Layer Detection State ==========
|
||
|
||
/** Layer 1: Timestamp when completion message was detected */
|
||
private completionMessageTime: number | null = null;
|
||
|
||
/** Layer 2: Timestamp of last terminal output received */
|
||
private lastOutputTime: number = 0;
|
||
|
||
/** Layer 3: Last observed token count */
|
||
private lastTokenCount: number = 0;
|
||
|
||
/** Layer 3: Timestamp when token count last changed */
|
||
private lastTokenChangeTime: number = 0;
|
||
|
||
/** Layer 4: Timestamp when last working pattern was seen */
|
||
private lastWorkingPatternTime: number = 0;
|
||
|
||
/**
|
||
* Patterns indicating Claude is ready for input (legacy fallback).
|
||
* Used as secondary signals, not primary detection.
|
||
*/
|
||
private readonly PROMPT_PATTERNS = [
|
||
'❯', // Standard prompt
|
||
'\u276f', // Unicode variant
|
||
'⏵', // Claude Code prompt variant
|
||
];
|
||
|
||
/**
|
||
* Patterns indicating Claude is actively working.
|
||
* When detected, resets all idle detection timers.
|
||
* Note: ✻ and ✽ removed - they appear in completion messages too.
|
||
*/
|
||
private readonly WORKING_PATTERNS = [
|
||
'Thinking',
|
||
'Writing',
|
||
'Reading',
|
||
'Running',
|
||
'Searching',
|
||
'Editing',
|
||
'Creating',
|
||
'Deleting',
|
||
'Analyzing',
|
||
'Executing',
|
||
'Synthesizing',
|
||
'Brewing', // Claude's processing indicators
|
||
'Compiling',
|
||
'Building',
|
||
'Installing',
|
||
'Fetching',
|
||
'Downloading',
|
||
'Processing',
|
||
'Generating',
|
||
'Loading',
|
||
'Starting',
|
||
'Updating',
|
||
'Checking',
|
||
'Validating',
|
||
'Testing',
|
||
'Formatting',
|
||
'Linting',
|
||
'⠋',
|
||
'⠙',
|
||
'⠹',
|
||
'⠸',
|
||
'⠼',
|
||
'⠴',
|
||
'⠦',
|
||
'⠧',
|
||
'⠇',
|
||
'⠏', // Spinner chars
|
||
'◐',
|
||
'◓',
|
||
'◑',
|
||
'◒', // Alternative spinners
|
||
'⣾',
|
||
'⣽',
|
||
'⣻',
|
||
'⢿',
|
||
'⡿',
|
||
'⣟',
|
||
'⣯',
|
||
'⣷', // Braille spinners
|
||
];
|
||
|
||
/**
|
||
* Rolling window buffer for working pattern detection.
|
||
* Prevents split-chunk issues where "Thinking" arrives as "Thin" + "king".
|
||
* Size: 300 chars should be enough to catch any split pattern.
|
||
*/
|
||
private workingPatternWindow: string = '';
|
||
private static readonly WORKING_PATTERN_WINDOW_SIZE = 300;
|
||
|
||
/**
|
||
* Minimum time without working patterns before considering idle (ms).
|
||
* Increased from 3s to 8s to avoid false positives during tool execution gaps.
|
||
*/
|
||
private static readonly MIN_WORKING_PATTERN_ABSENCE_MS = 8000;
|
||
|
||
/**
|
||
* Creates a new RespawnController.
|
||
*
|
||
* @param session - The Session instance to control
|
||
* @param config - Partial configuration (merged with defaults)
|
||
*/
|
||
constructor(session: Session, config: Partial<RespawnConfig> = {}) {
|
||
super();
|
||
this.session = session;
|
||
// Filter out undefined values from config to prevent overwriting defaults
|
||
const filteredConfig = Object.fromEntries(
|
||
Object.entries(config).filter(([, v]) => v !== undefined)
|
||
) as Partial<RespawnConfig>;
|
||
this.config = { ...DEFAULT_CONFIG, ...filteredConfig };
|
||
|
||
// Validate configuration values
|
||
this.validateConfig();
|
||
|
||
this.aiChecker = new AiIdleChecker(session.id, {
|
||
enabled: this.config.aiIdleCheckEnabled,
|
||
model: this.config.aiIdleCheckModel,
|
||
maxContextChars: this.config.aiIdleCheckMaxContext,
|
||
checkTimeoutMs: this.config.aiIdleCheckTimeoutMs,
|
||
cooldownMs: this.config.aiIdleCheckCooldownMs,
|
||
});
|
||
this.planChecker = new AiPlanChecker(session.id, {
|
||
enabled: this.config.aiPlanCheckEnabled,
|
||
model: this.config.aiPlanCheckModel,
|
||
maxContextChars: this.config.aiPlanCheckMaxContext,
|
||
checkTimeoutMs: this.config.aiPlanCheckTimeoutMs,
|
||
cooldownMs: this.config.aiPlanCheckCooldownMs,
|
||
});
|
||
this.setupAiCheckerListeners();
|
||
this.setupPlanCheckerListeners();
|
||
}
|
||
|
||
/**
|
||
* Validate configuration values and reset invalid ones to defaults.
|
||
* Ensures timeouts are positive and logically consistent.
|
||
*/
|
||
private validateConfig(): void {
|
||
const c = this.config;
|
||
|
||
// Ensure timeouts are positive
|
||
if (c.idleTimeoutMs <= 0) c.idleTimeoutMs = DEFAULT_CONFIG.idleTimeoutMs;
|
||
if (c.completionConfirmMs <= 0) c.completionConfirmMs = DEFAULT_CONFIG.completionConfirmMs;
|
||
if (c.noOutputTimeoutMs <= 0) c.noOutputTimeoutMs = DEFAULT_CONFIG.noOutputTimeoutMs;
|
||
if (c.autoAcceptDelayMs < 0) c.autoAcceptDelayMs = DEFAULT_CONFIG.autoAcceptDelayMs;
|
||
if (c.interStepDelayMs <= 0) c.interStepDelayMs = DEFAULT_CONFIG.interStepDelayMs;
|
||
|
||
// Ensure completion confirm doesn't exceed no-output timeout
|
||
if (c.completionConfirmMs > c.noOutputTimeoutMs) {
|
||
c.completionConfirmMs = c.noOutputTimeoutMs;
|
||
}
|
||
|
||
// Ensure AI check timeouts are positive
|
||
if (c.aiIdleCheckTimeoutMs <= 0) c.aiIdleCheckTimeoutMs = DEFAULT_CONFIG.aiIdleCheckTimeoutMs;
|
||
if (c.aiIdleCheckCooldownMs < 0) c.aiIdleCheckCooldownMs = DEFAULT_CONFIG.aiIdleCheckCooldownMs;
|
||
if (c.aiIdleCheckMaxContext <= 0) c.aiIdleCheckMaxContext = DEFAULT_CONFIG.aiIdleCheckMaxContext;
|
||
|
||
// Ensure plan check timeouts are positive
|
||
if (c.aiPlanCheckTimeoutMs <= 0) c.aiPlanCheckTimeoutMs = DEFAULT_CONFIG.aiPlanCheckTimeoutMs;
|
||
if (c.aiPlanCheckCooldownMs < 0) c.aiPlanCheckCooldownMs = DEFAULT_CONFIG.aiPlanCheckCooldownMs;
|
||
if (c.aiPlanCheckMaxContext <= 0) c.aiPlanCheckMaxContext = DEFAULT_CONFIG.aiPlanCheckMaxContext;
|
||
}
|
||
|
||
/** Wire up AI checker events to controller events (removes existing listeners first to prevent duplicates) */
|
||
private setupAiCheckerListeners(): void {
|
||
// Remove any existing listeners to prevent duplicates when restarting
|
||
this.aiChecker.removeAllListeners();
|
||
|
||
this.aiChecker.on('log', (message: string) => {
|
||
this.log(message);
|
||
});
|
||
|
||
this.aiChecker.on('cooldownStarted', (endsAt: number) => {
|
||
this.emit('aiCheckCooldown', true, endsAt);
|
||
});
|
||
|
||
this.aiChecker.on('cooldownEnded', () => {
|
||
this.emit('aiCheckCooldown', false, null);
|
||
// Restart pre-filter timer when cooldown expires so a new check can be triggered
|
||
if (this._state === 'watching') {
|
||
this.startPreFilterTimer();
|
||
}
|
||
});
|
||
|
||
this.aiChecker.on('disabled', (reason: string) => {
|
||
this.log(`AI checker disabled: ${reason}. Falling back to noOutputTimeoutMs.`);
|
||
});
|
||
}
|
||
|
||
/** Wire up plan checker events to controller events (removes existing listeners first to prevent duplicates) */
|
||
private setupPlanCheckerListeners(): void {
|
||
// Remove any existing listeners to prevent duplicates when restarting
|
||
this.planChecker.removeAllListeners();
|
||
|
||
this.planChecker.on('log', (message: string) => {
|
||
this.log(message);
|
||
});
|
||
|
||
this.planChecker.on('disabled', (reason: string) => {
|
||
this.log(`Plan checker disabled: ${reason}. Falling back to pre-filter only.`);
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Get the current state machine state.
|
||
* @returns Current RespawnState
|
||
*/
|
||
get state(): RespawnState {
|
||
return this._state;
|
||
}
|
||
|
||
/**
|
||
* Get the current respawn cycle count.
|
||
* Increments each time a new cycle starts.
|
||
* @returns Number of cycles started
|
||
*/
|
||
get currentCycle(): number {
|
||
return this.cycleCount;
|
||
}
|
||
|
||
/**
|
||
* Check if the controller is currently running.
|
||
* @returns True if state is not 'stopped'
|
||
*/
|
||
get isRunning(): boolean {
|
||
return this._state !== 'stopped';
|
||
}
|
||
|
||
/**
|
||
* Get current detection status for UI display.
|
||
* Shows all detection layers and their current state.
|
||
* @returns DetectionStatus object
|
||
*/
|
||
getDetectionStatus(): DetectionStatus {
|
||
const now = Date.now();
|
||
const msSinceLastOutput = now - this.lastOutputTime;
|
||
const msSinceTokenChange = now - this.lastTokenChangeTime;
|
||
const msSinceLastWorking = now - this.lastWorkingPatternTime;
|
||
|
||
const completionMessageDetected = this.completionMessageTime !== null;
|
||
const outputSilent = msSinceLastOutput >= this.config.completionConfirmMs;
|
||
const tokensStable = msSinceTokenChange >= this.config.completionConfirmMs;
|
||
const workingPatternsAbsent = msSinceLastWorking >= RespawnController.MIN_WORKING_PATTERN_ABSENCE_MS;
|
||
|
||
// Calculate confidence level (0-100) using configurable weights
|
||
// P2-001: Configurable confidence scoring
|
||
// Hook signals are definitive (100% confidence)
|
||
let confidence = 0;
|
||
if (this.stopHookReceived || this.idlePromptReceived) {
|
||
confidence = 100;
|
||
} else {
|
||
// Use configured weights (with fallback to defaults)
|
||
const weightCompletion = this.config.confidenceWeightCompletion ?? 40;
|
||
const weightSilence = this.config.confidenceWeightSilence ?? 25;
|
||
const weightTokens = this.config.confidenceWeightTokens ?? 20;
|
||
const weightNoWorking = this.config.confidenceWeightNoWorking ?? 15;
|
||
|
||
if (completionMessageDetected) confidence += weightCompletion;
|
||
if (outputSilent) confidence += weightSilence;
|
||
if (tokensStable) confidence += weightTokens;
|
||
if (workingPatternsAbsent) confidence += weightNoWorking;
|
||
|
||
// Confidence decay: if no output for extended time, add bonus confidence
|
||
// This helps detect stuck states where Claude is truly idle but no completion message
|
||
const extendedSilenceBonus = Math.min(20, Math.floor(msSinceLastOutput / 30000) * 5);
|
||
if (msSinceLastOutput > 30000) {
|
||
confidence += extendedSilenceBonus;
|
||
}
|
||
}
|
||
// Cap at 100
|
||
confidence = Math.min(100, confidence);
|
||
|
||
// Determine status text and what we're waiting for
|
||
let statusText: string;
|
||
let waitingFor: string;
|
||
|
||
if (this._state === 'stopped') {
|
||
statusText = 'Controller stopped';
|
||
waitingFor = 'Start to begin monitoring';
|
||
} else if (this.stopHookReceived || this.idlePromptReceived) {
|
||
const hookType = this.idlePromptReceived ? 'idle_prompt' : 'Stop';
|
||
statusText = `${hookType} hook received - confirming idle`;
|
||
waitingFor = 'Short confirmation (race condition check)';
|
||
} else if (this._state === 'ai_checking') {
|
||
statusText = 'AI Check: Analyzing terminal output...';
|
||
waitingFor = 'AI verdict (IDLE or WORKING)';
|
||
} else if (this._state === 'confirming_idle') {
|
||
statusText = `Confirming idle (${confidence}% confidence)`;
|
||
waitingFor = `${Math.max(0, Math.ceil((this.config.completionConfirmMs - msSinceLastOutput) / 1000))}s more silence`;
|
||
} else if (this._state === 'watching') {
|
||
const aiState = this.aiChecker.getState();
|
||
if (aiState.status === 'cooldown') {
|
||
const remaining = Math.ceil(this.aiChecker.getCooldownRemainingMs() / 1000);
|
||
statusText = `AI Check: WORKING (cooldown ${remaining}s)`;
|
||
waitingFor = 'Cooldown to expire';
|
||
} else if (completionMessageDetected) {
|
||
statusText = 'Completion detected, confirming...';
|
||
waitingFor = 'Output silence to confirm';
|
||
} else if (workingPatternsAbsent && msSinceLastOutput > 5000) {
|
||
statusText = 'No activity detected';
|
||
waitingFor = 'Pre-filter conditions for AI check';
|
||
} else {
|
||
statusText = 'Watching for idle signals';
|
||
waitingFor = 'Silence + no working patterns + tokens stable';
|
||
}
|
||
} else if (this._state.startsWith('waiting_') || this._state.startsWith('sending_')) {
|
||
statusText = `Respawn step: ${this._state}`;
|
||
waitingFor = 'Step completion';
|
||
} else {
|
||
statusText = `State: ${this._state}`;
|
||
waitingFor = 'Next event';
|
||
}
|
||
|
||
// Determine current phase and next action
|
||
let currentPhase: string;
|
||
let nextAction: string;
|
||
|
||
switch (this._state) {
|
||
case 'stopped':
|
||
currentPhase = 'Stopped';
|
||
nextAction = 'Start to begin';
|
||
break;
|
||
case 'watching':
|
||
currentPhase = 'Monitoring for idle';
|
||
nextAction = 'Waiting for silence + no working patterns';
|
||
break;
|
||
case 'confirming_idle':
|
||
currentPhase = 'Confirming idle state';
|
||
nextAction = 'Waiting for output silence';
|
||
break;
|
||
case 'ai_checking':
|
||
currentPhase = 'AI analyzing terminal';
|
||
nextAction = 'Waiting for IDLE/WORKING verdict';
|
||
break;
|
||
case 'sending_update':
|
||
currentPhase = 'Sending update prompt';
|
||
nextAction = 'Will send prompt after delay';
|
||
break;
|
||
case 'waiting_update':
|
||
currentPhase = 'Waiting for update to complete';
|
||
nextAction = 'Will send /clear when done';
|
||
break;
|
||
case 'sending_clear':
|
||
currentPhase = 'Sending /clear';
|
||
nextAction = 'Will clear context';
|
||
break;
|
||
case 'waiting_clear':
|
||
currentPhase = 'Waiting for /clear to complete';
|
||
nextAction = 'Will send /init when done';
|
||
break;
|
||
case 'sending_init':
|
||
currentPhase = 'Sending /init';
|
||
nextAction = 'Will re-initialize';
|
||
break;
|
||
case 'waiting_init':
|
||
currentPhase = 'Waiting for /init to complete';
|
||
nextAction = 'Monitoring for work';
|
||
break;
|
||
case 'monitoring_init':
|
||
currentPhase = 'Monitoring if /init triggered work';
|
||
nextAction = 'Kickstart if no work started';
|
||
break;
|
||
case 'sending_kickstart':
|
||
currentPhase = 'Sending kickstart prompt';
|
||
nextAction = 'Will send prompt after delay';
|
||
break;
|
||
case 'waiting_kickstart':
|
||
currentPhase = 'Waiting for kickstart to complete';
|
||
nextAction = 'Completing cycle';
|
||
break;
|
||
default:
|
||
currentPhase = this._state;
|
||
nextAction = 'Processing...';
|
||
}
|
||
|
||
return {
|
||
stopHookReceived: this.stopHookReceived,
|
||
stopHookTime: this.stopHookTime,
|
||
idlePromptReceived: this.idlePromptReceived,
|
||
idlePromptTime: this.idlePromptTime,
|
||
completionMessageDetected,
|
||
completionMessageTime: this.completionMessageTime,
|
||
outputSilent,
|
||
msSinceLastOutput,
|
||
tokensStable,
|
||
lastTokenCount: this.lastTokenCount,
|
||
msSinceTokenChange,
|
||
workingPatternsAbsent,
|
||
msSinceLastWorking,
|
||
aiCheck: this.config.aiIdleCheckEnabled ? this.aiChecker.getState() : null,
|
||
confidenceLevel: confidence,
|
||
statusText,
|
||
waitingFor,
|
||
activeTimers: this.getActiveTimers(),
|
||
recentActions: this.recentActions.slice(0, 10),
|
||
currentPhase,
|
||
nextAction,
|
||
stuckState: this.getStuckStateMetrics(),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Start periodic detection status updates for UI.
|
||
* Emits 'detectionUpdate' event every 2s while running.
|
||
*/
|
||
private startDetectionUpdates(): void {
|
||
this.stopDetectionUpdates();
|
||
if (this._state === 'stopped') return;
|
||
this.detectionUpdateTimer = setInterval(() => {
|
||
try {
|
||
if (this._state !== 'stopped') {
|
||
this.emit('detectionUpdate', this.getDetectionStatus());
|
||
}
|
||
} catch (err) {
|
||
console.error(`[RespawnController] Error in detectionUpdateTimer:`, err);
|
||
}
|
||
}, 2000);
|
||
}
|
||
|
||
/**
|
||
* Stop periodic detection status updates.
|
||
*/
|
||
private stopDetectionUpdates(): void {
|
||
if (this.detectionUpdateTimer) {
|
||
clearInterval(this.detectionUpdateTimer);
|
||
this.detectionUpdateTimer = null;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Transition to a new state.
|
||
* Emits 'stateChanged' event with old and new states.
|
||
* No-op if already in the target state.
|
||
*
|
||
* @param newState - State to transition to
|
||
* @fires stateChanged
|
||
*/
|
||
private setState(newState: RespawnState): void {
|
||
if (newState === this._state) return;
|
||
|
||
const prevState = this._state;
|
||
this._state = newState;
|
||
this.stateEnteredAt = Date.now();
|
||
this.stuckStateWarned = false; // Reset warning for new state
|
||
this.log(`State: ${prevState} → ${newState}`);
|
||
this.logAction('state', `${prevState} → ${newState}`);
|
||
this.emit('stateChanged', newState, prevState);
|
||
|
||
// Reset stuck recovery count on successful state transition to normal states
|
||
if (newState === 'watching' && prevState !== 'stopped') {
|
||
this.stuckRecoveryCount = 0;
|
||
}
|
||
|
||
// Start/restart stuck-state detection timer
|
||
this.startStuckStateTimer();
|
||
}
|
||
|
||
/**
|
||
* Emit a timestamped log message.
|
||
* @param message - Log message content
|
||
* @fires log
|
||
*/
|
||
private log(message: string): void {
|
||
const timestamp = new Date().toISOString();
|
||
this.emit('log', `[${timestamp}] [Respawn] ${message}`);
|
||
}
|
||
|
||
/** Set team watcher for team-aware idle detection */
|
||
setTeamWatcher(watcher: TeamWatcher): void {
|
||
this.teamWatcher = watcher;
|
||
}
|
||
|
||
/**
|
||
* Start watching the session for idle state.
|
||
*
|
||
* Begins monitoring terminal output for idle indicators.
|
||
* When idle is detected, starts the respawn cycle.
|
||
*
|
||
* No-op if:
|
||
* - `config.enabled` is false
|
||
* - Already running (state !== 'stopped')
|
||
*
|
||
* @fires stateChanged - Transitions to 'watching'
|
||
*/
|
||
start(): void {
|
||
if (!this.config.enabled) {
|
||
this.log('Respawn is disabled');
|
||
return;
|
||
}
|
||
|
||
if (this._state !== 'stopped') {
|
||
this.log('Already running');
|
||
return;
|
||
}
|
||
|
||
this.log('Starting respawn controller (multi-layer detection)');
|
||
|
||
// Re-setup AI checker listeners in case they were removed by a previous stop()
|
||
// This allows the controller to be restarted after being stopped
|
||
this.setupAiCheckerListeners();
|
||
this.setupPlanCheckerListeners();
|
||
|
||
// Initialize all timestamps and reset hook state
|
||
const now = Date.now();
|
||
this.lastActivityTime = now;
|
||
this.lastOutputTime = now;
|
||
this.lastTokenChangeTime = now;
|
||
this.lastWorkingPatternTime = now;
|
||
this.completionMessageTime = null;
|
||
this.hasReceivedOutput = false;
|
||
this.resetHookState();
|
||
|
||
// Seed the terminal buffer from the session's existing output.
|
||
// This gives the AI checker context even if no new output arrives.
|
||
const existingBuffer = this.session.terminalBuffer;
|
||
if (existingBuffer) {
|
||
this.terminalBuffer.clear();
|
||
this.terminalBuffer.append(existingBuffer);
|
||
}
|
||
|
||
this.aiChecker.reset();
|
||
this.planChecker.reset();
|
||
this.setState('watching');
|
||
this.setupTerminalListener();
|
||
this.startDetectionUpdates();
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
if (this.config.autoAcceptPrompts) {
|
||
this.startAutoAcceptTimer();
|
||
}
|
||
|
||
// P2-001: Initialize idle detection start time
|
||
this.idleDetectionStartTime = Date.now();
|
||
}
|
||
|
||
/**
|
||
* Stop the respawn controller.
|
||
*
|
||
* Clears all timers, removes terminal listener, and sets state to 'stopped'.
|
||
* Safe to call multiple times.
|
||
*
|
||
* @fires stateChanged - Transitions to 'stopped'
|
||
*/
|
||
stop(): void {
|
||
this.log('Stopping respawn controller');
|
||
this.aiChecker.cancel();
|
||
this.planChecker.cancel();
|
||
// Remove event listeners from checkers to prevent memory leaks
|
||
this.aiChecker.removeAllListeners();
|
||
this.planChecker.removeAllListeners();
|
||
this.clearTimers();
|
||
this.stopDetectionUpdates();
|
||
this.recentActions.length = 0;
|
||
this.setState('stopped');
|
||
if (this.terminalHandler) {
|
||
this.session.off('terminal', this.terminalHandler);
|
||
this.terminalHandler = null;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Pause respawn without stopping.
|
||
*
|
||
* Clears timers but keeps listening to terminal.
|
||
* State is preserved; won't trigger idle detection while paused.
|
||
* Use resume() to continue.
|
||
*/
|
||
pause(): void {
|
||
this.log('Pausing respawn');
|
||
this.clearTimers();
|
||
// Stay in current state but clear timers
|
||
}
|
||
|
||
/**
|
||
* Resume respawn after pause.
|
||
*
|
||
* If in 'watching' state, immediately checks for idle condition.
|
||
* Otherwise, continues from current state.
|
||
* Re-setups terminal listener if it was removed (e.g., after stop()).
|
||
*/
|
||
resume(): void {
|
||
this.log('Resuming respawn');
|
||
// After a full stop(), use start() for clean restart to avoid double-registering listeners
|
||
if (this._state === 'stopped') {
|
||
this.start();
|
||
return;
|
||
}
|
||
// Re-setup terminal listener if it was removed
|
||
if (!this.terminalHandler) {
|
||
this.setupTerminalListener();
|
||
}
|
||
if (this._state === 'watching') {
|
||
this.checkIdleAndMaybeStart();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Set up terminal output listener on the session.
|
||
* Removes any previous listener first to avoid duplicates.
|
||
*/
|
||
private setupTerminalListener(): void {
|
||
// Remove our previous listener if any (don't remove other listeners!)
|
||
if (this.terminalHandler) {
|
||
this.session.off('terminal', this.terminalHandler);
|
||
}
|
||
|
||
this.terminalHandler = (data: string) => {
|
||
this.handleTerminalData(data);
|
||
};
|
||
this.session.on('terminal', this.terminalHandler);
|
||
}
|
||
|
||
/**
|
||
* Process terminal data for idle/working detection using multi-layer approach.
|
||
*
|
||
* Detection Layers:
|
||
* 1. Completion message ("for Xm Xs") - PRIMARY signal
|
||
* 2. Output silence - confirms completion
|
||
* 3. Token stability - additional confirmation
|
||
* 4. Working pattern absence - supports idle detection
|
||
* 5. No-output fallback - catches edge cases
|
||
*
|
||
* @param data - Raw terminal output data
|
||
*/
|
||
private handleTerminalData(data: string): void {
|
||
// Guard against null/undefined/empty data
|
||
if (!data || typeof data !== 'string') {
|
||
return;
|
||
}
|
||
|
||
const now = Date.now();
|
||
|
||
// BufferAccumulator handles auto-trimming when max size exceeded
|
||
this.terminalBuffer.append(data);
|
||
|
||
// Track output time (Layer 2)
|
||
this.lastOutputTime = now;
|
||
this.lastActivityTime = now;
|
||
this.hasReceivedOutput = true;
|
||
this.resetNoOutputTimer();
|
||
this.resetPreFilterTimer();
|
||
this.resetAutoAcceptTimer();
|
||
|
||
// Cancel plan check if running (new output makes result stale)
|
||
if (this.planChecker.status === 'checking') {
|
||
this.log('New output during plan check, cancelling (stale)');
|
||
this.planChecker.cancel();
|
||
}
|
||
|
||
// Track token count (Layer 3)
|
||
const tokenCount = this.extractTokenCount(data);
|
||
if (tokenCount !== null && tokenCount !== this.lastTokenCount) {
|
||
this.lastTokenCount = tokenCount;
|
||
this.lastTokenChangeTime = now;
|
||
}
|
||
|
||
// Detect completion message FIRST (Layer 1) - PRIMARY DETECTION
|
||
// Check this before working patterns because completion message indicates
|
||
// the work is done, even if working patterns are still in the rolling window
|
||
if (this.isCompletionMessage(data)) {
|
||
// Clear the rolling window - completion marks a transition point
|
||
this.clearWorkingPatternWindow();
|
||
this.workingDetected = false;
|
||
this.completionMessageTime = now;
|
||
this.cancelAutoAcceptTimer(); // Normal idle flow handles this
|
||
this.log(`Completion message detected: "${data.trim().substring(0, 50)}..."`);
|
||
|
||
// In watching state, start completion confirmation timer
|
||
if (this._state === 'watching') {
|
||
this.startCompletionConfirmTimer();
|
||
return;
|
||
}
|
||
|
||
// In waiting states, also use confirmation timer (same detection logic)
|
||
// This ensures we wait for Claude to finish before proceeding
|
||
// Note: 'watching' is already handled above and returns early
|
||
switch (this._state) {
|
||
case 'waiting_update':
|
||
this.startStepConfirmTimer('update');
|
||
break;
|
||
case 'waiting_clear':
|
||
this.checkClearComplete(); // /clear is quick, no need to wait
|
||
break;
|
||
case 'waiting_init':
|
||
this.startStepConfirmTimer('init');
|
||
break;
|
||
case 'waiting_kickstart':
|
||
this.startStepConfirmTimer('kickstart');
|
||
break;
|
||
// Non-waiting states: completion message is ignored
|
||
case 'confirming_idle':
|
||
case 'ai_checking':
|
||
case 'sending_update':
|
||
case 'sending_clear':
|
||
case 'sending_init':
|
||
case 'monitoring_init':
|
||
case 'sending_kickstart':
|
||
case 'stopped':
|
||
// Completion message during these states is ignored
|
||
break;
|
||
default:
|
||
assertNever(this._state, `Unhandled RespawnState in completion detection: ${this._state}`);
|
||
}
|
||
return;
|
||
}
|
||
|
||
// Detect working patterns (Layer 4)
|
||
const isWorking = this.hasWorkingPattern(data);
|
||
if (isWorking) {
|
||
this.workingDetected = true;
|
||
this.promptDetected = false;
|
||
this.elicitationDetected = false; // Clear on new work cycle
|
||
this.resetHookState(); // Clear hook signals on new work
|
||
this.lastWorkingPatternTime = now;
|
||
this.clearIdleTimer();
|
||
|
||
// Cancel hook confirmation timer if running
|
||
this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimer, 'working patterns detected');
|
||
this.hookConfirmTimer = null;
|
||
|
||
// Cancel any pending completion confirmation
|
||
this.cancelCompletionConfirm();
|
||
|
||
// Cancel any pending step confirmation (Claude is still working)
|
||
this.cancelStepConfirm();
|
||
|
||
// If AI check is running, cancel it (Claude is working)
|
||
if (this._state === 'ai_checking') {
|
||
this.log('Working patterns detected during AI check, cancelling');
|
||
this.aiChecker.cancel();
|
||
this.setState('watching');
|
||
}
|
||
|
||
// Cancel plan check if running (Claude started working)
|
||
if (this.planChecker.status === 'checking') {
|
||
this.log('Working patterns detected during plan check, cancelling');
|
||
this.planChecker.cancel();
|
||
}
|
||
|
||
// If we're monitoring init and work started, go to watching (no kickstart needed)
|
||
if (this._state === 'monitoring_init') {
|
||
this.log('/init triggered work, skipping kickstart');
|
||
this.emit('stepCompleted', 'init');
|
||
this.completeCycle();
|
||
}
|
||
return;
|
||
}
|
||
|
||
// In confirming_idle or ai_checking state, substantial output cancels the flow.
|
||
// This prevents false triggers when Claude pauses briefly mid-work.
|
||
if (this._state === 'confirming_idle' || this._state === 'ai_checking') {
|
||
// Strip ANSI escape codes to check if there's real content
|
||
ANSI_ESCAPE_PATTERN_SIMPLE.lastIndex = 0;
|
||
const stripped = data.replace(ANSI_ESCAPE_PATTERN_SIMPLE, '').trim();
|
||
if (stripped.length > 2) {
|
||
if (this._state === 'ai_checking') {
|
||
this.log(`Substantial output during AI check ("${stripped.substring(0, 40)}..."), cancelling`);
|
||
this.aiChecker.cancel();
|
||
this.setState('watching');
|
||
} else {
|
||
// Real content (not just escape codes or single chars) - cancel confirmation
|
||
this.log(
|
||
`Substantial output during confirmation ("${stripped.substring(0, 40)}..."), cancelling idle detection`
|
||
);
|
||
this.cancelCompletionConfirm();
|
||
}
|
||
return;
|
||
}
|
||
}
|
||
|
||
// Legacy fallback: detect prompt characters (still useful for waiting_* states)
|
||
const hasPrompt = this.PROMPT_PATTERNS.some((pattern) => data.includes(pattern));
|
||
if (hasPrompt) {
|
||
this.promptDetected = true;
|
||
this.workingDetected = false;
|
||
|
||
// Handle legacy detection in waiting states - also use confirmation timers
|
||
switch (this._state) {
|
||
case 'waiting_update':
|
||
this.startStepConfirmTimer('update');
|
||
break;
|
||
case 'waiting_clear':
|
||
this.checkClearComplete(); // /clear is quick, no need to wait
|
||
break;
|
||
case 'waiting_init':
|
||
this.startStepConfirmTimer('init');
|
||
break;
|
||
case 'monitoring_init':
|
||
this.checkMonitoringInitIdle();
|
||
break;
|
||
case 'waiting_kickstart':
|
||
this.startStepConfirmTimer('kickstart');
|
||
break;
|
||
// Non-waiting states: prompt detection is informational only
|
||
case 'watching':
|
||
case 'confirming_idle':
|
||
case 'ai_checking':
|
||
case 'sending_update':
|
||
case 'sending_clear':
|
||
case 'sending_init':
|
||
case 'sending_kickstart':
|
||
case 'stopped':
|
||
// Prompt detection during these states doesn't trigger action
|
||
break;
|
||
default:
|
||
assertNever(this._state, `Unhandled RespawnState in prompt detection: ${this._state}`);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Handle update step completion.
|
||
* Called when ready indicator detected in waiting_update state.
|
||
* Proceeds to clear, init, or completes cycle based on config.
|
||
* @fires stepCompleted - With step 'update'
|
||
*/
|
||
private checkUpdateComplete(): void {
|
||
this.clearIdleTimer();
|
||
this.log('Update completed (ready indicator)');
|
||
this.emit('stepCompleted', 'update');
|
||
|
||
// P2-004: Record step completion
|
||
this.recordCycleStep('update');
|
||
|
||
if (this.config.sendClear) {
|
||
// P2-002: Check if we should skip /clear
|
||
if (this.shouldSkipClear()) {
|
||
if (this.currentCycleMetrics) {
|
||
this.currentCycleMetrics.clearSkipped = true;
|
||
}
|
||
// Skip /clear, go directly to /init or complete
|
||
if (this.config.sendInit) {
|
||
this.sendInit();
|
||
} else {
|
||
this.completeCycle();
|
||
}
|
||
} else {
|
||
this.sendClear();
|
||
}
|
||
} else if (this.config.sendInit) {
|
||
this.sendInit();
|
||
} else {
|
||
this.completeCycle();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Handle /clear step completion.
|
||
* Proceeds to init or completes cycle based on config.
|
||
* @fires stepCompleted - With step 'clear'
|
||
*/
|
||
private checkClearComplete(): void {
|
||
this.clearIdleTimer();
|
||
// Clear the fallback timer since we got prompt detection
|
||
this.cancelTrackedTimer('clear-fallback', this.clearFallbackTimer, 'prompt detected');
|
||
this.clearFallbackTimer = null;
|
||
this.logAction('step', '/clear completed');
|
||
this.emit('stepCompleted', 'clear');
|
||
|
||
// P2-004: Record step completion
|
||
this.recordCycleStep('clear');
|
||
|
||
if (this.config.sendInit) {
|
||
this.sendInit();
|
||
} else {
|
||
this.completeCycle();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Handle /init step completion.
|
||
* If kickstart is configured, monitors for work.
|
||
* Otherwise completes cycle.
|
||
* @fires stepCompleted - With step 'init' (if no kickstart)
|
||
*/
|
||
private checkInitComplete(): void {
|
||
this.clearIdleTimer();
|
||
this.log('/init completed (ready indicator)');
|
||
|
||
// P2-004: Record step completion
|
||
this.recordCycleStep('init');
|
||
|
||
// If kickstart prompt is configured, monitor to see if /init triggered work
|
||
if (this.config.kickstartPrompt) {
|
||
this.startMonitoringInit();
|
||
} else {
|
||
this.emit('stepCompleted', 'init');
|
||
this.completeCycle();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Start monitoring to see if /init triggered work.
|
||
* Enters 'monitoring_init' state and waits 3s grace period.
|
||
* If no work detected, sends kickstart prompt.
|
||
*/
|
||
private startMonitoringInit(): void {
|
||
this.setState('monitoring_init');
|
||
this.terminalBuffer.clear();
|
||
this.clearWorkingPatternWindow();
|
||
this.workingDetected = false;
|
||
this.logAction('step', 'Monitoring if /init triggered work...');
|
||
|
||
// Give Claude a moment to start working before checking for idle
|
||
this.stepTimer = this.startTrackedTimer(
|
||
'init-monitor',
|
||
3000,
|
||
() => {
|
||
this.stepTimer = null;
|
||
// If still in monitoring state and no work detected, consider it idle
|
||
if (this._state === 'monitoring_init' && !this.workingDetected) {
|
||
this.checkMonitoringInitIdle();
|
||
}
|
||
},
|
||
'grace period for /init'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Handle monitoring timeout when /init didn't trigger work.
|
||
* Sends kickstart prompt as fallback.
|
||
* @fires stepCompleted - With step 'init'
|
||
*/
|
||
private checkMonitoringInitIdle(): void {
|
||
this.clearIdleTimer();
|
||
if (this.stepTimer) {
|
||
clearTimeout(this.stepTimer);
|
||
this.stepTimer = null;
|
||
}
|
||
this.log('/init did not trigger work, sending kickstart prompt');
|
||
this.emit('stepCompleted', 'init');
|
||
this.sendKickstart();
|
||
}
|
||
|
||
/**
|
||
* Send the kickstart prompt to get Claude working.
|
||
* @fires stepSent - With step 'kickstart'
|
||
*/
|
||
private sendKickstart(): void {
|
||
this.setState('sending_kickstart');
|
||
this.terminalBuffer.clear();
|
||
this.clearWorkingPatternWindow();
|
||
|
||
this.stepTimer = this.startTrackedTimer(
|
||
'step-delay',
|
||
this.config.interStepDelayMs,
|
||
async () => {
|
||
this.stepTimer = null;
|
||
if (this._state === 'stopped') return;
|
||
const prompt = this.config.kickstartPrompt!;
|
||
this.logAction('command', `Sending kickstart: "${prompt.substring(0, 40)}..."`);
|
||
await this.session.writeViaMux(prompt + '\r'); // \r triggers key.return in Ink/Claude CLI
|
||
this.emit('stepSent', 'kickstart', prompt);
|
||
this.setState('waiting_kickstart');
|
||
this.promptDetected = false;
|
||
this.workingDetected = false;
|
||
},
|
||
'delay before kickstart'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Handle kickstart step completion.
|
||
* @fires stepCompleted - With step 'kickstart'
|
||
*/
|
||
private checkKickstartComplete(): void {
|
||
this.clearIdleTimer();
|
||
this.log('Kickstart completed (ready indicator)');
|
||
this.emit('stepCompleted', 'kickstart');
|
||
|
||
// P2-004: Record step completion
|
||
this.recordCycleStep('kickstart');
|
||
|
||
this.completeCycle();
|
||
}
|
||
|
||
// Note: Legacy startIdleTimer removed - now using completion-based detection
|
||
// with startCompletionConfirmTimer() and startNoOutputTimer() instead.
|
||
|
||
/** Clear the idle detection timer if running (legacy cleanup) */
|
||
private clearIdleTimer(): void {
|
||
if (this.idleTimer) {
|
||
clearTimeout(this.idleTimer);
|
||
this.idleTimer = null;
|
||
}
|
||
}
|
||
|
||
/** Clear all timers (idle, step, completion confirm, no-output, pre-filter, step confirm, auto-accept, hook confirm, and clear fallback) */
|
||
private clearTimers(): void {
|
||
// Clear tracked timers map first to avoid stale entries during individual cleanup
|
||
this.activeTimers.clear();
|
||
this.clearIdleTimer();
|
||
if (this.stepTimer) {
|
||
clearTimeout(this.stepTimer);
|
||
this.stepTimer = null;
|
||
}
|
||
if (this.clearFallbackTimer) {
|
||
clearTimeout(this.clearFallbackTimer);
|
||
this.clearFallbackTimer = null;
|
||
}
|
||
if (this.completionConfirmTimer) {
|
||
clearTimeout(this.completionConfirmTimer);
|
||
this.completionConfirmTimer = null;
|
||
}
|
||
if (this.stepConfirmTimer) {
|
||
clearTimeout(this.stepConfirmTimer);
|
||
this.stepConfirmTimer = null;
|
||
}
|
||
if (this.autoAcceptTimer) {
|
||
clearTimeout(this.autoAcceptTimer);
|
||
this.autoAcceptTimer = null;
|
||
}
|
||
if (this.preFilterTimer) {
|
||
clearTimeout(this.preFilterTimer);
|
||
this.preFilterTimer = null;
|
||
}
|
||
if (this.noOutputTimer) {
|
||
clearTimeout(this.noOutputTimer);
|
||
this.noOutputTimer = null;
|
||
}
|
||
if (this.hookConfirmTimer) {
|
||
clearTimeout(this.hookConfirmTimer);
|
||
this.hookConfirmTimer = null;
|
||
}
|
||
if (this.stuckStateTimer) {
|
||
clearInterval(this.stuckStateTimer);
|
||
this.stuckStateTimer = null;
|
||
}
|
||
if (this.detectionUpdateTimer) {
|
||
clearInterval(this.detectionUpdateTimer);
|
||
this.detectionUpdateTimer = null;
|
||
}
|
||
}
|
||
|
||
// ========== Stuck-State Detection Methods ==========
|
||
|
||
/**
|
||
* Start or restart the stuck-state detection timer.
|
||
* Emits warning after stuckStateWarningMs, triggers recovery after stuckStateRecoveryMs.
|
||
*/
|
||
private startStuckStateTimer(): void {
|
||
if (!this.config.stuckStateDetectionEnabled) return;
|
||
if (this._state === 'stopped') return;
|
||
|
||
// Clear existing timer
|
||
if (this.stuckStateTimer) {
|
||
clearInterval(this.stuckStateTimer);
|
||
this.stuckStateTimer = null;
|
||
}
|
||
|
||
// Check interval for stuck state
|
||
const checkIntervalMs = Math.min(this.config.stuckStateWarningMs, 60000); // Check every minute max
|
||
|
||
this.stuckStateTimer = setInterval(() => {
|
||
try {
|
||
this.checkStuckState();
|
||
} catch (err) {
|
||
console.error(`[RespawnController] Error in stuckStateTimer:`, err);
|
||
}
|
||
}, checkIntervalMs);
|
||
}
|
||
|
||
/**
|
||
* Check if the controller is stuck in the current state.
|
||
* Emits warnings and triggers recovery actions as appropriate.
|
||
*/
|
||
private checkStuckState(): void {
|
||
if (this._state === 'stopped') return;
|
||
|
||
const durationMs = Date.now() - this.stateEnteredAt;
|
||
|
||
// Check for recovery threshold (more severe)
|
||
if (durationMs >= this.config.stuckStateRecoveryMs) {
|
||
if (this.stuckRecoveryCount < this.config.maxStuckRecoveries) {
|
||
this.stuckRecoveryCount++;
|
||
this.logAction('stuck', `Recovery attempt ${this.stuckRecoveryCount}/${this.config.maxStuckRecoveries}`);
|
||
this.log(
|
||
`Stuck-state recovery triggered (state: ${this._state}, duration: ${Math.round(durationMs / 1000)}s, attempt: ${this.stuckRecoveryCount})`
|
||
);
|
||
this.emit('stuckStateRecovery', this._state, durationMs, this.stuckRecoveryCount);
|
||
this.handleStuckStateRecovery();
|
||
} else {
|
||
this.logAction(
|
||
'stuck',
|
||
`Max recoveries (${this.config.maxStuckRecoveries}) reached - manual intervention needed`
|
||
);
|
||
this.log(`Stuck-state: max recoveries reached, manual intervention needed`);
|
||
}
|
||
return;
|
||
}
|
||
|
||
// Check for warning threshold
|
||
if (durationMs >= this.config.stuckStateWarningMs && !this.stuckStateWarned) {
|
||
this.stuckStateWarned = true;
|
||
this.logAction('stuck', `Warning: in state '${this._state}' for ${Math.round(durationMs / 1000)}s`);
|
||
this.log(`Stuck-state warning: state '${this._state}' for ${Math.round(durationMs / 1000)}s without progress`);
|
||
this.emit('stuckStateWarning', this._state, durationMs);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Handle stuck-state recovery by resetting to a known good state.
|
||
* Uses escalating recovery strategies based on current state.
|
||
*/
|
||
private handleStuckStateRecovery(): void {
|
||
const currentState = this._state;
|
||
|
||
// P2-004: Complete current cycle metrics with stuck_recovery outcome
|
||
if (this.currentCycleMetrics) {
|
||
this.completeCycleMetrics('stuck_recovery', `Stuck in state: ${currentState}`);
|
||
}
|
||
|
||
// Cancel any running AI checks
|
||
if (this.aiChecker.status === 'checking') {
|
||
this.aiChecker.cancel();
|
||
}
|
||
if (this.planChecker.status === 'checking') {
|
||
this.planChecker.cancel();
|
||
}
|
||
|
||
// Clear all timers and reset detection state
|
||
this.clearTimers();
|
||
this.completionMessageTime = null;
|
||
this.promptDetected = false;
|
||
this.workingDetected = false;
|
||
this.resetHookState();
|
||
|
||
// Escalating recovery strategies
|
||
switch (currentState) {
|
||
case 'watching':
|
||
case 'confirming_idle':
|
||
case 'ai_checking':
|
||
// For detection states, try forcing idle confirmation
|
||
this.log('Recovery: forcing idle confirmation');
|
||
this.onIdleConfirmed(`stuck-state recovery (was ${currentState})`);
|
||
break;
|
||
|
||
case 'waiting_update':
|
||
case 'waiting_clear':
|
||
case 'waiting_init':
|
||
case 'waiting_kickstart':
|
||
case 'monitoring_init':
|
||
// For waiting states, skip to next step or complete cycle
|
||
this.log('Recovery: skipping stuck step');
|
||
this.completeCycle();
|
||
break;
|
||
|
||
case 'sending_update':
|
||
case 'sending_clear':
|
||
case 'sending_init':
|
||
case 'sending_kickstart':
|
||
// For sending states, retry the send
|
||
this.log('Recovery: returning to watching state');
|
||
this.setState('watching');
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
if (this.config.autoAcceptPrompts) {
|
||
this.startAutoAcceptTimer();
|
||
}
|
||
break;
|
||
|
||
default:
|
||
// Fallback: reset to watching
|
||
this.log('Recovery: fallback to watching state');
|
||
this.setState('watching');
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
if (this.config.autoAcceptPrompts) {
|
||
this.startAutoAcceptTimer();
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Get stuck-state metrics for UI display.
|
||
*/
|
||
getStuckStateMetrics(): {
|
||
currentStateDurationMs: number;
|
||
warningThresholdMs: number;
|
||
recoveryThresholdMs: number;
|
||
recoveryAttempts: number;
|
||
maxRecoveries: number;
|
||
isWarned: boolean;
|
||
} {
|
||
return {
|
||
currentStateDurationMs: this._state !== 'stopped' ? Date.now() - this.stateEnteredAt : 0,
|
||
warningThresholdMs: this.config.stuckStateWarningMs,
|
||
recoveryThresholdMs: this.config.stuckStateRecoveryMs,
|
||
recoveryAttempts: this.stuckRecoveryCount,
|
||
maxRecoveries: this.config.maxStuckRecoveries,
|
||
isWarned: this.stuckStateWarned,
|
||
};
|
||
}
|
||
|
||
// ========== Timer Tracking Methods ==========
|
||
|
||
/**
|
||
* Start a tracked timer with UI countdown support.
|
||
* Emits timerStarted event and tracks the timer for UI display.
|
||
*/
|
||
private startTrackedTimer(name: string, durationMs: number, callback: () => void, reason?: string): NodeJS.Timeout {
|
||
const now = Date.now();
|
||
const endsAt = now + durationMs;
|
||
|
||
this.activeTimers.set(name, { name, startedAt: now, durationMs, endsAt });
|
||
this.emit('timerStarted', { name, durationMs, endsAt, reason });
|
||
this.logAction('timer', `Started ${name}: ${Math.round(durationMs / 1000)}s${reason ? ` (${reason})` : ''}`);
|
||
|
||
return setTimeout(() => {
|
||
this.activeTimers.delete(name);
|
||
this.emit('timerCompleted', name);
|
||
callback();
|
||
}, durationMs);
|
||
}
|
||
|
||
/**
|
||
* Cancel a tracked timer and emit cancellation event.
|
||
*/
|
||
private cancelTrackedTimer(name: string, timerRef: NodeJS.Timeout | null, reason?: string): void {
|
||
if (timerRef) {
|
||
clearTimeout(timerRef);
|
||
if (this.activeTimers.has(name)) {
|
||
this.activeTimers.delete(name);
|
||
this.emit('timerCancelled', name, reason);
|
||
this.logAction('timer-cancel', `${name}${reason ? `: ${reason}` : ''}`);
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Get all active timers with remaining time for UI display.
|
||
*/
|
||
getActiveTimers(): ActiveTimerInfo[] {
|
||
const now = Date.now();
|
||
return Array.from(this.activeTimers.values()).map((t) => ({
|
||
name: t.name,
|
||
remainingMs: Math.max(0, t.endsAt - now),
|
||
totalMs: t.durationMs,
|
||
}));
|
||
}
|
||
|
||
/**
|
||
* Log an action for detailed UI feedback.
|
||
* Keeps the last 20 entries.
|
||
*/
|
||
private logAction(type: string, detail: string): void {
|
||
const action: ActionLogEntry = { type, detail, timestamp: Date.now() };
|
||
this.recentActions.unshift(action);
|
||
if (this.recentActions.length > 20) {
|
||
this.recentActions.pop();
|
||
}
|
||
this.emit('actionLog', action);
|
||
}
|
||
|
||
/**
|
||
* Get recent action log entries.
|
||
*/
|
||
getRecentActions(): ActionLogEntry[] {
|
||
return [...this.recentActions];
|
||
}
|
||
|
||
// ========== Multi-Layer Detection Methods ==========
|
||
|
||
/**
|
||
* Check if data contains a completion message pattern.
|
||
* Matches "for Xh Xm Xs" time duration patterns.
|
||
*/
|
||
private isCompletionMessage(data: string): boolean {
|
||
return COMPLETION_TIME_PATTERN.test(data);
|
||
}
|
||
|
||
/**
|
||
* Check if data contains working patterns.
|
||
* Uses rolling window to catch patterns split across chunks (e.g., "Thin" + "king").
|
||
*/
|
||
private hasWorkingPattern(data: string): boolean {
|
||
// Always update the rolling window first to maintain continuity
|
||
this.workingPatternWindow += data;
|
||
if (this.workingPatternWindow.length > RespawnController.WORKING_PATTERN_WINDOW_SIZE) {
|
||
this.workingPatternWindow = this.workingPatternWindow.slice(-RespawnController.WORKING_PATTERN_WINDOW_SIZE);
|
||
}
|
||
|
||
// Check the rolling window (includes current data, catches both complete and split patterns)
|
||
return this.WORKING_PATTERNS.some((pattern) => this.workingPatternWindow.includes(pattern));
|
||
}
|
||
|
||
/**
|
||
* Clear the working pattern rolling window.
|
||
* Called when starting a new detection cycle.
|
||
*/
|
||
private clearWorkingPatternWindow(): void {
|
||
this.workingPatternWindow = '';
|
||
}
|
||
|
||
/**
|
||
* Extract token count from data if present.
|
||
* Returns null if no token pattern found.
|
||
*/
|
||
private extractTokenCount(data: string): number | null {
|
||
const match = data.match(TOKEN_PATTERN);
|
||
if (!match) return null;
|
||
|
||
let count = parseFloat(match[1]);
|
||
const suffix = match[2]?.toLowerCase();
|
||
if (suffix === 'k') count *= 1000;
|
||
else if (suffix === 'm') count *= 1000000;
|
||
|
||
return Math.round(count);
|
||
}
|
||
|
||
/**
|
||
* Start the no-output fallback timer.
|
||
* If no output for noOutputTimeoutMs, triggers idle detection as safety net
|
||
* (used when AI check is disabled or has too many errors).
|
||
*/
|
||
private startNoOutputTimer(): void {
|
||
this.cancelTrackedTimer('no-output-fallback', this.noOutputTimer, 'restarting');
|
||
this.noOutputTimer = null;
|
||
|
||
this.noOutputTimer = this.startTrackedTimer(
|
||
'no-output-fallback',
|
||
this.config.noOutputTimeoutMs,
|
||
() => {
|
||
this.noOutputTimer = null;
|
||
if (this._state === 'watching' || this._state === 'confirming_idle') {
|
||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||
this.logAction('detection', `No-output fallback: ${Math.round(msSinceOutput / 1000)}s silence`);
|
||
// If AI check is disabled or errored out, go directly to idle
|
||
if (!this.config.aiIdleCheckEnabled || this.aiChecker.status === 'disabled') {
|
||
this.onIdleConfirmed('no-output fallback (AI check disabled)');
|
||
} else {
|
||
this.tryStartAiCheck('no-output fallback');
|
||
}
|
||
}
|
||
},
|
||
'fallback if no output at all'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Reset the no-output fallback timer.
|
||
* Called whenever output is received.
|
||
*/
|
||
private resetNoOutputTimer(): void {
|
||
this.startNoOutputTimer();
|
||
}
|
||
|
||
// ========== Pre-Filter & AI Check Methods ==========
|
||
|
||
/**
|
||
* Start the pre-filter timer.
|
||
* Fires after completionConfirmMs of silence. When it fires, checks if
|
||
* all pre-filter conditions are met and starts the AI check if so.
|
||
* This provides an additional path to AI check even without a completion message.
|
||
*/
|
||
private startPreFilterTimer(): void {
|
||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'restarting');
|
||
this.preFilterTimer = null;
|
||
|
||
// Only set up pre-filter when AI check is enabled
|
||
if (!this.config.aiIdleCheckEnabled) return;
|
||
|
||
this.preFilterTimer = this.startTrackedTimer(
|
||
'pre-filter',
|
||
this.config.completionConfirmMs,
|
||
() => {
|
||
this.preFilterTimer = null;
|
||
if (this._state === 'watching') {
|
||
const now = Date.now();
|
||
const msSinceOutput = now - this.lastOutputTime;
|
||
const msSinceWorking = now - this.lastWorkingPatternTime;
|
||
const msSinceTokenChange = now - this.lastTokenChangeTime;
|
||
|
||
// Check pre-filter conditions
|
||
const silenceMet = msSinceOutput >= this.config.completionConfirmMs;
|
||
const noWorkingMet = msSinceWorking >= RespawnController.MIN_WORKING_PATTERN_ABSENCE_MS;
|
||
const tokensStableMet = msSinceTokenChange >= this.config.completionConfirmMs;
|
||
|
||
if (silenceMet && noWorkingMet && tokensStableMet) {
|
||
this.logAction('detection', `Pre-filter passed: silence=${Math.round(msSinceOutput / 1000)}s`);
|
||
this.tryStartAiCheck('pre-filter');
|
||
}
|
||
}
|
||
},
|
||
'checking idle conditions'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Reset the pre-filter timer.
|
||
* Called whenever output is received.
|
||
*/
|
||
private resetPreFilterTimer(): void {
|
||
this.startPreFilterTimer();
|
||
}
|
||
|
||
/**
|
||
* Attempt to start an AI idle check.
|
||
* Checks if AI check is enabled, not on cooldown, and not already checking.
|
||
* Falls back to direct idle confirmation if AI check is unavailable.
|
||
*
|
||
* @param reason - What triggered this attempt (for logging)
|
||
*/
|
||
private tryStartAiCheck(reason: string): void {
|
||
// P0-006: Check Session.isWorking first to skip expensive AI call if session reports working
|
||
if (this.session.isWorking) {
|
||
this.log(`Skipping AI check - Session reports isWorking=true (reason: ${reason})`);
|
||
this.logAction('detection', 'Skipped AI check: Session is working');
|
||
return;
|
||
}
|
||
|
||
// If AI check is disabled or errored out, fall back to direct idle confirmation
|
||
if (!this.config.aiIdleCheckEnabled || this.aiChecker.status === 'disabled') {
|
||
this.log(`AI check unavailable (${this.aiChecker.status}), confirming idle directly via: ${reason}`);
|
||
this.onIdleConfirmed(reason);
|
||
return;
|
||
}
|
||
|
||
// If on cooldown, don't start check - wait for cooldown to expire
|
||
if (this.aiChecker.isOnCooldown()) {
|
||
this.log(
|
||
`AI check on cooldown (${Math.ceil(this.aiChecker.getCooldownRemainingMs() / 1000)}s remaining), waiting...`
|
||
);
|
||
return;
|
||
}
|
||
|
||
// If already checking, don't start another
|
||
if (this.aiChecker.status === 'checking') {
|
||
this.log('AI check already in progress');
|
||
return;
|
||
}
|
||
|
||
// Start the AI check
|
||
this.startAiCheck(reason);
|
||
}
|
||
|
||
/**
|
||
* Start the AI idle check.
|
||
* Transitions to 'ai_checking' state and runs the check asynchronously.
|
||
*
|
||
* @param reason - What triggered this check (for logging)
|
||
*/
|
||
private startAiCheck(reason: string): void {
|
||
this.setState('ai_checking');
|
||
this.logAction('ai-check', `Spawning AI idle checker (${reason})`);
|
||
this.emit('aiCheckStarted');
|
||
|
||
// Generate unique ID for this check to detect stale results
|
||
const checkId = randomUUID();
|
||
this._currentAiCheckId = checkId;
|
||
|
||
// Get the terminal buffer for analysis
|
||
const buffer = this.terminalBuffer.value;
|
||
|
||
this.aiChecker
|
||
.check(buffer)
|
||
.then((result) => {
|
||
// If state changed while checking (e.g., cancelled), ignore result
|
||
if (this._state !== 'ai_checking') {
|
||
this.log(`AI check result ignored (state is now ${this._state})`);
|
||
return;
|
||
}
|
||
|
||
// Validate this is the result for the current check (not a stale one)
|
||
if (this._currentAiCheckId !== checkId) {
|
||
this.log(`AI check result ignored (stale check ID: ${checkId.substring(0, 8)})`);
|
||
return;
|
||
}
|
||
|
||
if (result.verdict === 'IDLE') {
|
||
// Cancel any pending confirmation timers - AI has spoken
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'AI verdict: IDLE');
|
||
this.completionConfirmTimer = null;
|
||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'AI verdict: IDLE');
|
||
this.preFilterTimer = null;
|
||
|
||
this.logAction('ai-check', `Verdict: IDLE - ${result.reasoning}`);
|
||
this.emit('aiCheckCompleted', result);
|
||
this.onIdleConfirmed(`ai-check: idle (${result.reasoning})`);
|
||
} else if (result.verdict === 'WORKING') {
|
||
// Cancel timers and go to cooldown
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'AI verdict: WORKING');
|
||
this.completionConfirmTimer = null;
|
||
|
||
this.logAction('ai-check', `Verdict: WORKING - ${result.reasoning}`);
|
||
this.emit('aiCheckCompleted', result);
|
||
this.setState('watching');
|
||
this.log(`AI check says WORKING, returning to watching with ${this.config.aiIdleCheckCooldownMs}ms cooldown`);
|
||
// Restart timers so the controller retries after cooldown expires
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
} else {
|
||
// ERROR verdict
|
||
this.logAction('ai-check', `Error: ${result.reasoning}`);
|
||
this.emit('aiCheckFailed', result.reasoning);
|
||
this.setState('watching');
|
||
// Restart timers to allow retry
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
}
|
||
})
|
||
.catch((err) => {
|
||
// Validate this is the error for the current check
|
||
if (this._currentAiCheckId !== checkId) {
|
||
return; // Stale check, ignore error
|
||
}
|
||
if (this._state === 'stopped') return; // Guard against stopped state
|
||
if (this._state === 'ai_checking') {
|
||
const errorMsg = err instanceof Error ? err.message : String(err);
|
||
this.logAction('ai-check', `Failed: ${errorMsg.substring(0, 50)}`);
|
||
this.emit('aiCheckFailed', errorMsg);
|
||
this.setState('watching');
|
||
this.log(`AI check error: ${errorMsg}`);
|
||
// Restart timers to allow retry
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
}
|
||
});
|
||
}
|
||
|
||
// ========== Auto-Accept Prompt Methods ==========
|
||
|
||
/**
|
||
* Reset the auto-accept timer.
|
||
* Called whenever output is received. After autoAcceptDelayMs of silence
|
||
* (without a completion message), sends Enter to accept prompts.
|
||
*/
|
||
private resetAutoAcceptTimer(): void {
|
||
if (!this.config.autoAcceptPrompts) return;
|
||
this.startAutoAcceptTimer();
|
||
}
|
||
|
||
/**
|
||
* Start the auto-accept timer.
|
||
* Fires after autoAcceptDelayMs of no output when no completion message
|
||
* and no elicitation dialog was detected. Only handles plan mode approvals.
|
||
*/
|
||
private startAutoAcceptTimer(): void {
|
||
this.cancelTrackedTimer('auto-accept', this.autoAcceptTimer, 'restarting');
|
||
this.autoAcceptTimer = null;
|
||
|
||
this.autoAcceptTimer = this.startTrackedTimer(
|
||
'auto-accept',
|
||
this.config.autoAcceptDelayMs,
|
||
() => {
|
||
this.autoAcceptTimer = null;
|
||
this.tryAutoAccept();
|
||
},
|
||
'plan mode detection'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Cancel the auto-accept timer.
|
||
* Called when a completion message is detected (normal idle flow handles it).
|
||
*/
|
||
private cancelAutoAcceptTimer(): void {
|
||
this.cancelTrackedTimer('auto-accept', this.autoAcceptTimer, 'cancelled');
|
||
this.autoAcceptTimer = null;
|
||
}
|
||
|
||
/**
|
||
* Attempt to auto-accept a plan mode prompt by sending Enter.
|
||
* Two-stage gate:
|
||
* 1. Strict regex pre-filter — check if terminal buffer contains plan mode UI elements
|
||
* 2. AI confirmation — spawn Opus to classify buffer as PLAN_MODE or NOT_PLAN_MODE
|
||
*
|
||
* Only sends Enter if both stages confirm (or pre-filter only if AI disabled).
|
||
*
|
||
* @fires autoAcceptSent
|
||
* @fires planCheckStarted
|
||
*/
|
||
private tryAutoAccept(): void {
|
||
// Only auto-accept in watching state (not during a respawn cycle)
|
||
if (this._state !== 'watching') return;
|
||
|
||
// Don't auto-accept if a completion message was detected (normal idle handles it)
|
||
if (this.completionMessageTime !== null) return;
|
||
|
||
// Don't auto-accept if disabled
|
||
if (!this.config.autoAcceptPrompts) return;
|
||
|
||
// Don't auto-accept if we haven't received any output yet (prevents spurious Enter on fresh start)
|
||
if (!this.hasReceivedOutput) return;
|
||
|
||
// Don't auto-accept if an elicitation dialog (AskUserQuestion) was detected
|
||
if (this.elicitationDetected) {
|
||
this.log('Skipping auto-accept: elicitation dialog detected (AskUserQuestion)');
|
||
return;
|
||
}
|
||
|
||
// Stage 1: Pre-filter — check if buffer looks like plan mode
|
||
const buffer = this.terminalBuffer.value;
|
||
if (!this.isPlanModePreFilterMatch(buffer)) {
|
||
this.log('Skipping auto-accept: pre-filter did not match plan mode patterns');
|
||
return;
|
||
}
|
||
|
||
// Stage 2: AI confirmation (if enabled and available)
|
||
if (this.config.aiPlanCheckEnabled && this.planChecker.status !== 'disabled') {
|
||
if (this.planChecker.isOnCooldown()) {
|
||
this.log(
|
||
`Skipping auto-accept: plan checker on cooldown (${Math.ceil(this.planChecker.getCooldownRemainingMs() / 1000)}s remaining)`
|
||
);
|
||
return;
|
||
}
|
||
if (this.planChecker.status === 'checking') {
|
||
this.log('Skipping auto-accept: plan check already in progress');
|
||
return;
|
||
}
|
||
// Start async AI plan check
|
||
this.startPlanCheck(buffer);
|
||
return;
|
||
}
|
||
|
||
// AI plan check disabled — pre-filter passed, send Enter directly
|
||
this.sendAutoAcceptEnter();
|
||
}
|
||
|
||
/**
|
||
* Check if the terminal buffer matches plan mode pre-filter patterns.
|
||
* Only checks the last 2000 chars (plan mode UI appears at the bottom).
|
||
*
|
||
* Must find:
|
||
* - Numbered option pattern (e.g., "1. Yes", "2. No")
|
||
* - Selection indicator (❯ or > followed by number)
|
||
* Must NOT find:
|
||
* - Recent working patterns (spinners, "Thinking", etc.) in the tail
|
||
*/
|
||
private isPlanModePreFilterMatch(buffer: string): boolean {
|
||
// Only check the last 2000 chars (plan mode UI is at the bottom)
|
||
const tail = buffer.slice(-2000);
|
||
|
||
// Strip ANSI codes for pattern matching
|
||
ANSI_ESCAPE_PATTERN_SIMPLE.lastIndex = 0;
|
||
const stripped = tail.replace(ANSI_ESCAPE_PATTERN_SIMPLE, '');
|
||
|
||
// Must find numbered option pattern
|
||
if (!PLAN_MODE_OPTION_PATTERN.test(stripped)) return false;
|
||
|
||
// Must find selection indicator
|
||
const selectorMatch = stripped.match(PLAN_MODE_SELECTOR_PATTERN);
|
||
if (!selectorMatch) return false;
|
||
|
||
// Must NOT have working patterns AFTER the selector position.
|
||
// Working patterns before the selector are from earlier work and don't matter.
|
||
const selectorIndex = stripped.lastIndexOf(selectorMatch[0]);
|
||
const afterSelector = stripped.slice(selectorIndex + selectorMatch[0].length);
|
||
const hasWorking = this.WORKING_PATTERNS.some((pattern) => afterSelector.includes(pattern));
|
||
if (hasWorking) return false;
|
||
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* Start an AI plan check to confirm plan mode before auto-accepting.
|
||
* Async — result handled by then/catch.
|
||
*
|
||
* @param buffer - Terminal buffer to analyze
|
||
* @fires planCheckStarted
|
||
* @fires planCheckCompleted
|
||
* @fires planCheckFailed
|
||
*/
|
||
private startPlanCheck(buffer: string): void {
|
||
this.planCheckStartTime = Date.now();
|
||
this.logAction('plan-check', 'Spawning AI plan checker');
|
||
this.emit('planCheckStarted');
|
||
|
||
this.planChecker
|
||
.check(buffer)
|
||
.then((result) => {
|
||
// Discard stale result if new output arrived during check
|
||
if (this.lastOutputTime > this.planCheckStartTime) {
|
||
this.logAction('plan-check', 'Result discarded (output arrived during check)');
|
||
return;
|
||
}
|
||
|
||
if (result.verdict === 'PLAN_MODE') {
|
||
// Don't send Enter if state changed (e.g., AI idle check started or respawn cycle began)
|
||
if (this._state !== 'watching') {
|
||
this.logAction('plan-check', `Verdict: PLAN_MODE but state is ${this._state}, not sending Enter`);
|
||
return;
|
||
}
|
||
this.emit('planCheckCompleted', result);
|
||
this.logAction('plan-check', 'Verdict: PLAN_MODE - sending Enter immediately');
|
||
this.sendAutoAcceptEnter();
|
||
// No cooldown needed - we're taking action
|
||
} else if (result.verdict === 'NOT_PLAN_MODE') {
|
||
this.emit('planCheckCompleted', result);
|
||
this.logAction('plan-check', `Verdict: NOT_PLAN_MODE - ${result.reasoning}`);
|
||
} else {
|
||
// ERROR verdict
|
||
this.emit('planCheckFailed', result.reasoning);
|
||
this.logAction('plan-check', `Error: ${result.reasoning}`);
|
||
}
|
||
})
|
||
.catch((err) => {
|
||
const errorMsg = err instanceof Error ? err.message : String(err);
|
||
this.emit('planCheckFailed', errorMsg);
|
||
this.logAction('plan-check', `Failed: ${errorMsg.substring(0, 50)}`);
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Send the actual Enter keystroke for auto-accept.
|
||
* Factored out so both pre-filter-only and AI-confirmed paths can call it.
|
||
* @fires autoAcceptSent
|
||
*/
|
||
private sendAutoAcceptEnter(): void {
|
||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||
this.log(`Auto-accepting plan mode prompt (${msSinceOutput}ms silence, pre-filter + AI confirmed)`);
|
||
|
||
// Cancel any pending AI idle checks - we're about to make Claude work
|
||
if (this.aiChecker.status === 'checking') {
|
||
this.log('Cancelling AI idle check before auto-accept');
|
||
this.aiChecker.cancel();
|
||
}
|
||
|
||
// Cancel completion confirmation - auto-accept takes precedence
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'auto-accept');
|
||
this.completionConfirmTimer = null;
|
||
this.completionMessageTime = null;
|
||
|
||
// Ensure we're in watching state (not confirming_idle or ai_checking)
|
||
if (this._state !== 'watching') {
|
||
this.setState('watching');
|
||
}
|
||
|
||
this.logAction('command', 'Auto-accept: ↵ Enter (plan approved)');
|
||
this.emit('stepSent', 'auto-accept', '↵');
|
||
void this.session.writeViaMux('\r');
|
||
this.emit('autoAcceptSent');
|
||
// Reset so we don't keep spamming Enter if Claude doesn't respond
|
||
this.hasReceivedOutput = false;
|
||
}
|
||
|
||
/**
|
||
* Signal that an elicitation dialog (AskUserQuestion) was detected via hook.
|
||
* This prevents auto-accept from firing, since the user needs to make a selection.
|
||
* The flag is cleared when working patterns are detected (new turn starts).
|
||
*/
|
||
signalElicitation(): void {
|
||
this.elicitationDetected = true;
|
||
this.cancelAutoAcceptTimer();
|
||
this.log('Elicitation dialog signaled - auto-accept blocked until next work cycle');
|
||
}
|
||
|
||
/**
|
||
* Signal that a Stop hook was received from Claude Code.
|
||
* This is a DEFINITIVE signal that Claude has finished responding.
|
||
* Skips AI idle check and uses a short confirmation period to handle race conditions.
|
||
*
|
||
* @fires log
|
||
*/
|
||
signalStopHook(): void {
|
||
// Only process in states where we're watching for idle
|
||
if (this._state !== 'watching' && this._state !== 'confirming_idle' && this._state !== 'ai_checking') {
|
||
this.log(`Stop hook received but ignoring (state is ${this._state})`);
|
||
return;
|
||
}
|
||
|
||
const now = Date.now();
|
||
this.stopHookReceived = true;
|
||
this.stopHookTime = now;
|
||
this.logAction('hook', 'Stop hook received - definitive idle signal');
|
||
this.log('Stop hook received from Claude Code - definitive idle signal');
|
||
|
||
// Cancel any running AI check - we have a definitive signal
|
||
if (this._state === 'ai_checking') {
|
||
this.log('Cancelling AI check - Stop hook is definitive');
|
||
this.aiChecker.cancel();
|
||
}
|
||
|
||
// Cancel completion confirm timer - hook takes precedence
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'Stop hook received');
|
||
this.completionConfirmTimer = null;
|
||
|
||
// Cancel pre-filter timer - hook takes precedence
|
||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'Stop hook received');
|
||
this.preFilterTimer = null;
|
||
|
||
// Start short confirmation timer to handle race conditions
|
||
// (e.g., Stop hook arrives but Claude immediately starts new work)
|
||
this.startHookConfirmTimer('stop');
|
||
}
|
||
|
||
/**
|
||
* Signal that an idle_prompt notification was received from Claude Code.
|
||
* This fires after 60+ seconds of Claude waiting for user input.
|
||
* This is a DEFINITIVE signal that Claude is idle.
|
||
*
|
||
* @fires log
|
||
*/
|
||
signalIdlePrompt(): void {
|
||
// Only process in states where we're watching for idle
|
||
if (this._state !== 'watching' && this._state !== 'confirming_idle' && this._state !== 'ai_checking') {
|
||
this.log(`idle_prompt received but ignoring (state is ${this._state})`);
|
||
return;
|
||
}
|
||
|
||
const now = Date.now();
|
||
this.idlePromptReceived = true;
|
||
this.idlePromptTime = now;
|
||
this.logAction('hook', 'idle_prompt received - 60s+ idle confirmed');
|
||
this.log('idle_prompt notification received - Claude has been idle for 60+ seconds');
|
||
|
||
// Cancel any running AI check - we have a definitive signal
|
||
if (this._state === 'ai_checking') {
|
||
this.log('Cancelling AI check - idle_prompt is definitive');
|
||
this.aiChecker.cancel();
|
||
}
|
||
|
||
// Cancel all other detection timers - this is definitive
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'idle_prompt received');
|
||
this.completionConfirmTimer = null;
|
||
this.cancelTrackedTimer('pre-filter', this.preFilterTimer, 'idle_prompt received');
|
||
this.preFilterTimer = null;
|
||
this.cancelTrackedTimer('no-output-fallback', this.noOutputTimer, 'idle_prompt received');
|
||
this.noOutputTimer = null;
|
||
|
||
// idle_prompt is an even stronger signal than Stop hook (60s+ idle)
|
||
// Skip confirmation and go directly to idle
|
||
this.onIdleConfirmed('idle_prompt hook (60s+ idle)');
|
||
}
|
||
|
||
/**
|
||
* Start a short confirmation timer after receiving a hook signal.
|
||
* This handles race conditions where a hook arrives but Claude immediately starts new work.
|
||
*
|
||
* @param hookType - Which hook triggered this ('stop' or 'idle_prompt')
|
||
*/
|
||
private startHookConfirmTimer(hookType: 'stop' | 'idle_prompt'): void {
|
||
this.cancelTrackedTimer('hook-confirm', this.hookConfirmTimer, 'restarting');
|
||
this.hookConfirmTimer = null;
|
||
|
||
this.hookConfirmTimer = this.startTrackedTimer(
|
||
'hook-confirm',
|
||
RespawnController.HOOK_CONFIRM_DELAY_MS,
|
||
() => {
|
||
this.hookConfirmTimer = null;
|
||
|
||
// Verify we haven't received new output since the hook arrived
|
||
const hookTime = hookType === 'stop' ? this.stopHookTime : this.idlePromptTime;
|
||
if (hookTime && this.lastOutputTime > hookTime) {
|
||
// Output arrived after hook - Claude started new work
|
||
this.log(`Output received after ${hookType} hook, cancelling idle confirmation`);
|
||
this.logAction('hook', `${hookType} cancelled - new output detected`);
|
||
// Set state before resetting flags so event handlers see consistent state
|
||
this.setState('watching');
|
||
this.resetHookState();
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
if (this.config.autoAcceptPrompts) {
|
||
this.startAutoAcceptTimer();
|
||
}
|
||
return;
|
||
}
|
||
|
||
// No new output - confirm idle via hook signal
|
||
this.logAction('hook', `${hookType} confirmed after ${RespawnController.HOOK_CONFIRM_DELAY_MS}ms`);
|
||
this.onIdleConfirmed(`${hookType} hook (confirmed)`);
|
||
},
|
||
`confirming ${hookType} hook`
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Reset hook-based detection state.
|
||
* Called when hooks are cancelled due to new activity.
|
||
*/
|
||
private resetHookState(): void {
|
||
this.stopHookReceived = false;
|
||
this.stopHookTime = null;
|
||
this.idlePromptReceived = false;
|
||
this.idlePromptTime = null;
|
||
}
|
||
|
||
/**
|
||
* Signal that the transcript indicates completion.
|
||
* This is a supporting signal from transcript file monitoring.
|
||
* Unlike hooks, this doesn't immediately trigger idle - it boosts confidence.
|
||
*/
|
||
signalTranscriptComplete(): void {
|
||
// Transcript completion is a supporting signal, not definitive
|
||
// It can help reduce the confirmation time needed
|
||
if (this._state === 'watching') {
|
||
this.logAction('transcript', 'Transcript shows completion - boosting confidence');
|
||
this.log('Transcript completion detected - may accelerate idle detection');
|
||
// If we have a completion message and transcript confirms, try AI check
|
||
if (this.completionMessageTime !== null) {
|
||
this.tryStartAiCheck('transcript + completion message');
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Signal that the transcript indicates plan mode.
|
||
* This helps prevent auto-accept from triggering on AskUserQuestion.
|
||
*/
|
||
signalTranscriptPlanMode(): void {
|
||
// Plan mode from transcript = potential AskUserQuestion
|
||
// This is similar to elicitation detection
|
||
if (this._state === 'watching') {
|
||
this.logAction('transcript', 'Plan mode / AskUserQuestion detected');
|
||
this.cancelAutoAcceptTimer();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Start completion confirmation timer.
|
||
* After completion message, waits for output silence then triggers AI check.
|
||
*/
|
||
private startCompletionConfirmTimer(): void {
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'restarting');
|
||
this.completionConfirmTimer = null;
|
||
|
||
this.setState('confirming_idle');
|
||
this.logAction('detection', 'Completion message found in output');
|
||
|
||
this.completionConfirmTimer = this.startTrackedTimer(
|
||
'completion-confirm',
|
||
this.config.completionConfirmMs,
|
||
() => {
|
||
this.completionConfirmTimer = null;
|
||
if (this._state === 'stopped') return;
|
||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||
if (msSinceOutput >= this.config.completionConfirmMs) {
|
||
this.logAction('detection', `Silence confirmed: ${Math.round(msSinceOutput / 1000)}s`);
|
||
this.tryStartAiCheck('completion + silence');
|
||
} else {
|
||
// Output received during wait, stay in confirming state and re-check
|
||
this.logAction('detection', 'Output during confirmation, resetting');
|
||
if (this._state !== 'confirming_idle') return;
|
||
this.startCompletionConfirmTimer();
|
||
}
|
||
},
|
||
'waiting for silence after completion'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Cancel completion confirmation if new activity detected.
|
||
*/
|
||
private cancelCompletionConfirm(): void {
|
||
this.cancelTrackedTimer('completion-confirm', this.completionConfirmTimer, 'activity detected');
|
||
this.completionConfirmTimer = null;
|
||
if (this._state === 'confirming_idle') {
|
||
this.setState('watching');
|
||
this.completionMessageTime = null;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Start step confirmation timer for waiting states.
|
||
* Waits for output silence before proceeding to next step.
|
||
* This ensures Claude has finished processing before we send the next command.
|
||
*/
|
||
private startStepConfirmTimer(step: 'update' | 'init' | 'kickstart'): void {
|
||
this.cancelTrackedTimer('step-confirm', this.stepConfirmTimer, 'restarting');
|
||
this.stepConfirmTimer = null;
|
||
|
||
this.stepConfirmTimer = this.startTrackedTimer(
|
||
'step-confirm',
|
||
this.config.completionConfirmMs,
|
||
() => {
|
||
this.stepConfirmTimer = null;
|
||
if (this._state === 'stopped') return;
|
||
const msSinceOutput = Date.now() - this.lastOutputTime;
|
||
|
||
if (msSinceOutput >= this.config.completionConfirmMs) {
|
||
this.logAction('step', `${step} confirmed after ${Math.round(msSinceOutput / 1000)}s silence`);
|
||
|
||
// Proceed with the step completion
|
||
switch (step) {
|
||
case 'update':
|
||
this.checkUpdateComplete();
|
||
break;
|
||
case 'init':
|
||
this.checkInitComplete();
|
||
break;
|
||
case 'kickstart':
|
||
this.checkKickstartComplete();
|
||
break;
|
||
}
|
||
} else {
|
||
// Output received during wait, restart timer
|
||
this.logAction('step', `Output during ${step} confirmation, resetting`);
|
||
this.startStepConfirmTimer(step);
|
||
}
|
||
},
|
||
`confirming ${step} completion`
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Cancel step confirmation if working patterns detected.
|
||
*/
|
||
private cancelStepConfirm(): void {
|
||
this.cancelTrackedTimer('step-confirm', this.stepConfirmTimer, 'working detected');
|
||
this.stepConfirmTimer = null;
|
||
}
|
||
|
||
/**
|
||
* Called when idle is confirmed through any detection layer.
|
||
* @param reason - What triggered the confirmation
|
||
*/
|
||
private onIdleConfirmed(reason: string): void {
|
||
// Safety check: if Session thinks it's still working, don't trigger idle
|
||
// This catches cases where our detection missed working patterns
|
||
if (this.session.isWorking) {
|
||
this.log(`Idle confirmation rejected - Session reports isWorking=true (reason was: ${reason})`);
|
||
this.logAction('detection', 'Rejected: Session still working');
|
||
this.setState('watching');
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
return;
|
||
}
|
||
|
||
this.log(`Idle confirmed via: ${reason}`);
|
||
const status = this.getDetectionStatus();
|
||
this.log(
|
||
`Detection status: confidence=${status.confidenceLevel}%, ` +
|
||
`completion=${status.completionMessageDetected}, ` +
|
||
`silent=${status.outputSilent}, ` +
|
||
`tokensStable=${status.tokensStable}, ` +
|
||
`noWorking=${status.workingPatternsAbsent}`
|
||
);
|
||
|
||
// ========== Agent Teams Integration ==========
|
||
// Check if session has active teammates — don't respawn while team is working
|
||
if (this.teamWatcher?.hasActiveTeammates(this.session.id)) {
|
||
const count = this.teamWatcher.getActiveTeammateCount(this.session.id);
|
||
this.log(`Respawn blocked - ${count} active teammate(s) working`);
|
||
this.logAction('team', `Active teammates: ${count}`);
|
||
this.emit('respawnBlocked', {
|
||
reason: 'active_teammates',
|
||
details: `${count} teammate(s) still working`,
|
||
});
|
||
this.setState('watching');
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
return;
|
||
}
|
||
|
||
// ========== RALPH_STATUS Integration ==========
|
||
// Check circuit breaker status - if OPEN, pause respawn
|
||
const ralphTracker = this.session.ralphTracker;
|
||
if (ralphTracker) {
|
||
const circuitBreaker = ralphTracker.circuitBreakerStatus;
|
||
if (circuitBreaker.state === 'OPEN') {
|
||
this.log(`Respawn blocked - Circuit breaker OPEN: ${circuitBreaker.reason}`);
|
||
this.logAction('ralph', `Circuit breaker OPEN: ${circuitBreaker.reason}`);
|
||
this.emit('respawnBlocked', {
|
||
reason: 'circuit_breaker_open',
|
||
details: circuitBreaker.reason,
|
||
});
|
||
this.setState('watching');
|
||
// Don't restart timers - wait for manual reset or circuit breaker resolution
|
||
return;
|
||
}
|
||
}
|
||
|
||
// Check RALPH_STATUS EXIT_SIGNAL - if true, loop is complete
|
||
const statusBlock = ralphTracker?.lastStatusBlock;
|
||
if (statusBlock?.exitSignal) {
|
||
this.log(`Respawn paused - RALPH_STATUS EXIT_SIGNAL=true`);
|
||
this.logAction('ralph', `Exit signal detected: ${statusBlock.recommendation || 'Task complete'}`);
|
||
this.emit('respawnBlocked', {
|
||
reason: 'exit_signal',
|
||
details: statusBlock.recommendation || 'Task complete',
|
||
});
|
||
this.setState('watching');
|
||
// Don't restart timers - loop is complete
|
||
return;
|
||
}
|
||
|
||
// Check if STATUS=BLOCKED - trigger circuit breaker
|
||
if (statusBlock?.status === 'BLOCKED') {
|
||
this.log(`Respawn blocked - RALPH_STATUS reports BLOCKED`);
|
||
this.logAction('ralph', `Claude reported BLOCKED: ${statusBlock.recommendation || 'Needs human intervention'}`);
|
||
this.emit('respawnBlocked', {
|
||
reason: 'status_blocked',
|
||
details: statusBlock.recommendation || 'Needs human intervention',
|
||
});
|
||
this.setState('watching');
|
||
return;
|
||
}
|
||
|
||
// Reset detection state
|
||
this.completionMessageTime = null;
|
||
this.cancelCompletionConfirm();
|
||
|
||
// Trigger the respawn cycle
|
||
this.onIdleDetected();
|
||
}
|
||
|
||
/**
|
||
* Handle confirmed idle detection.
|
||
* Starts a new respawn cycle.
|
||
* @fires respawnCycleStarted
|
||
*/
|
||
private onIdleDetected(): void {
|
||
// Accept watching, confirming_idle, and ai_checking states
|
||
if (this._state !== 'watching' && this._state !== 'confirming_idle' && this._state !== 'ai_checking') {
|
||
return;
|
||
}
|
||
|
||
// Clear all detection timers before starting cycle to prevent stale callbacks
|
||
this.clearTimers();
|
||
|
||
// P1-006: Session health check before respawn cycle
|
||
// Skip if session is in error state or not running
|
||
if (this.session.status === 'error') {
|
||
this.log('Skipping respawn cycle - session is in error state');
|
||
this.logAction('health', 'Respawn skipped: Session error state');
|
||
this.emit('respawnBlocked', {
|
||
reason: 'session_error',
|
||
details: 'Session is in error state',
|
||
});
|
||
this.setState('watching');
|
||
return;
|
||
}
|
||
|
||
if (this.session.status === 'stopped') {
|
||
this.log('Skipping respawn cycle - session is stopped');
|
||
this.logAction('health', 'Respawn skipped: Session stopped');
|
||
this.emit('respawnBlocked', { reason: 'session_stopped', details: 'Session is stopped' });
|
||
this.setState('watching');
|
||
return;
|
||
}
|
||
|
||
// Check if session PTY is still alive (via PID)
|
||
if (!this.session.pid) {
|
||
this.log('Skipping respawn cycle - session PTY not running (no PID)');
|
||
this.logAction('health', 'Respawn skipped: No PTY process');
|
||
this.emit('respawnBlocked', { reason: 'no_pty', details: 'Session PTY process not running' });
|
||
this.setState('watching');
|
||
return;
|
||
}
|
||
|
||
// Start the respawn cycle
|
||
this.cycleCount++;
|
||
this.log(`Starting respawn cycle #${this.cycleCount}`);
|
||
this.emit('respawnCycleStarted', this.cycleCount);
|
||
|
||
// P2-004: Start tracking cycle metrics
|
||
this.startCycleMetrics('idle_confirmed');
|
||
|
||
this.sendUpdateDocs();
|
||
}
|
||
|
||
/**
|
||
* Send the update docs prompt (first step of cycle).
|
||
* Uses RALPH_STATUS RECOMMENDATION if available, otherwise falls back to configured prompt.
|
||
* @fires stepSent - With step 'update'
|
||
*/
|
||
private sendUpdateDocs(): void {
|
||
this.setState('sending_update');
|
||
this.terminalBuffer.clear(); // Clear buffer for fresh detection
|
||
this.clearWorkingPatternWindow(); // Clear rolling window
|
||
|
||
this.stepTimer = this.startTrackedTimer(
|
||
'step-delay',
|
||
this.config.interStepDelayMs,
|
||
async () => {
|
||
this.stepTimer = null;
|
||
if (this._state === 'stopped') return;
|
||
|
||
// Use RALPH_STATUS RECOMMENDATION if available, otherwise fall back to config
|
||
const statusBlock = this.session.ralphTracker?.lastStatusBlock;
|
||
let updatePrompt = this.config.updatePrompt;
|
||
|
||
if (statusBlock?.recommendation) {
|
||
// Append RECOMMENDATION to the update prompt (single-line — writeViaMux breaks on newlines)
|
||
const rec = statusBlock.recommendation.replace(/\n/g, ' ').substring(0, 200);
|
||
updatePrompt = `${this.config.updatePrompt} (Claude's last recommendation: ${rec})`;
|
||
this.logAction('ralph', `Using RECOMMENDATION: ${rec.substring(0, 50)}...`);
|
||
}
|
||
|
||
const input = updatePrompt + '\r'; // \r triggers Enter in Ink/Claude CLI
|
||
this.logAction('command', `Sending: "${updatePrompt.substring(0, 50)}..."`);
|
||
await this.session.writeViaMux(input);
|
||
this.emit('stepSent', 'update', updatePrompt);
|
||
this.setState('waiting_update');
|
||
this.promptDetected = false;
|
||
this.workingDetected = false;
|
||
},
|
||
'delay before update prompt'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Send /clear command.
|
||
* Starts a 10-second fallback timer - if no prompt is detected after /clear,
|
||
* proceeds to /init anyway (workaround for when Claude doesn't show prompt after /clear).
|
||
* @fires stepSent - With step 'clear'
|
||
*/
|
||
private sendClear(): void {
|
||
this.setState('sending_clear');
|
||
this.terminalBuffer.clear();
|
||
this.clearWorkingPatternWindow();
|
||
|
||
this.stepTimer = this.startTrackedTimer(
|
||
'step-delay',
|
||
this.config.interStepDelayMs,
|
||
async () => {
|
||
this.stepTimer = null;
|
||
if (this._state === 'stopped') return;
|
||
this.logAction('command', 'Sending: /clear');
|
||
await this.session.writeViaMux('/clear\r'); // \r triggers Enter in Ink/Claude CLI
|
||
this.emit('stepSent', 'clear', '/clear');
|
||
this.setState('waiting_clear');
|
||
this.promptDetected = false;
|
||
|
||
// Start fallback timer - if no prompt detected after 10s, proceed to /init anyway
|
||
this.clearFallbackTimer = this.startTrackedTimer(
|
||
'clear-fallback',
|
||
RespawnController.CLEAR_FALLBACK_TIMEOUT_MS,
|
||
() => {
|
||
this.clearFallbackTimer = null;
|
||
if (this._state === 'waiting_clear') {
|
||
this.logAction('step', '/clear fallback: proceeding to /init');
|
||
this.emit('stepCompleted', 'clear');
|
||
if (this.config.sendInit) {
|
||
this.sendInit();
|
||
} else {
|
||
this.completeCycle();
|
||
}
|
||
}
|
||
},
|
||
'fallback if no prompt after /clear'
|
||
);
|
||
},
|
||
'delay before /clear'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Send /init command.
|
||
* @fires stepSent - With step 'init'
|
||
*/
|
||
private sendInit(): void {
|
||
this.setState('sending_init');
|
||
this.terminalBuffer.clear();
|
||
this.clearWorkingPatternWindow();
|
||
|
||
this.stepTimer = this.startTrackedTimer(
|
||
'step-delay',
|
||
this.config.interStepDelayMs,
|
||
async () => {
|
||
this.stepTimer = null;
|
||
if (this._state === 'stopped') return;
|
||
this.logAction('command', 'Sending: /init');
|
||
await this.session.writeViaMux('/init\r'); // \r triggers Enter in Ink/Claude CLI
|
||
this.emit('stepSent', 'init', '/init');
|
||
this.setState('waiting_init');
|
||
this.promptDetected = false;
|
||
this.workingDetected = false;
|
||
},
|
||
'delay before /init'
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Complete the current respawn cycle.
|
||
* Returns to watching state for next cycle.
|
||
* @fires respawnCycleCompleted
|
||
*/
|
||
private completeCycle(): void {
|
||
this.log(`Respawn cycle #${this.cycleCount} completed`);
|
||
this.emit('respawnCycleCompleted', this.cycleCount);
|
||
|
||
// P2-004: Complete cycle metrics with success outcome
|
||
this.completeCycleMetrics('success');
|
||
|
||
// Go back to watching state for next cycle
|
||
this.setState('watching');
|
||
this.terminalBuffer.clear();
|
||
this.clearWorkingPatternWindow(); // Clear rolling window for fresh detection
|
||
this.promptDetected = false;
|
||
this.workingDetected = false;
|
||
this.resetHookState(); // Clear hook signals for next cycle
|
||
|
||
// P2-001: Reset idle detection start time for next cycle
|
||
this.idleDetectionStartTime = Date.now();
|
||
|
||
// Restart detection timers for next cycle
|
||
this.startNoOutputTimer();
|
||
this.startPreFilterTimer();
|
||
if (this.config.autoAcceptPrompts) {
|
||
this.startAutoAcceptTimer();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Check if already idle and start cycle if so.
|
||
* Used when resuming from pause.
|
||
*/
|
||
private checkIdleAndMaybeStart(): void {
|
||
if (this._state === 'stopped') return;
|
||
// Check if already idle
|
||
const timeSinceActivity = Date.now() - this.lastActivityTime;
|
||
if (timeSinceActivity > this.config.idleTimeoutMs && this.promptDetected) {
|
||
this.onIdleDetected();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Update configuration at runtime.
|
||
*
|
||
* Merges provided config with existing config.
|
||
* Takes effect immediately for new operations.
|
||
*
|
||
* @param config - Partial configuration to merge
|
||
* @fires log - With updated config details
|
||
*/
|
||
updateConfig(config: Partial<RespawnConfig>): void {
|
||
// Filter out undefined values to prevent overwriting existing config with undefined
|
||
const filteredConfig = Object.fromEntries(
|
||
Object.entries(config).filter(([, v]) => v !== undefined)
|
||
) as Partial<RespawnConfig>;
|
||
this.config = { ...this.config, ...filteredConfig };
|
||
|
||
// Sync AI checker config if relevant fields changed
|
||
if (
|
||
config.aiIdleCheckEnabled !== undefined ||
|
||
config.aiIdleCheckModel !== undefined ||
|
||
config.aiIdleCheckMaxContext !== undefined ||
|
||
config.aiIdleCheckTimeoutMs !== undefined ||
|
||
config.aiIdleCheckCooldownMs !== undefined
|
||
) {
|
||
this.aiChecker.updateConfig({
|
||
enabled: this.config.aiIdleCheckEnabled,
|
||
model: this.config.aiIdleCheckModel,
|
||
maxContextChars: this.config.aiIdleCheckMaxContext,
|
||
checkTimeoutMs: this.config.aiIdleCheckTimeoutMs,
|
||
cooldownMs: this.config.aiIdleCheckCooldownMs,
|
||
});
|
||
}
|
||
|
||
// Sync plan checker config if relevant fields changed
|
||
if (
|
||
config.aiPlanCheckEnabled !== undefined ||
|
||
config.aiPlanCheckModel !== undefined ||
|
||
config.aiPlanCheckMaxContext !== undefined ||
|
||
config.aiPlanCheckTimeoutMs !== undefined ||
|
||
config.aiPlanCheckCooldownMs !== undefined
|
||
) {
|
||
this.planChecker.updateConfig({
|
||
enabled: this.config.aiPlanCheckEnabled,
|
||
model: this.config.aiPlanCheckModel,
|
||
maxContextChars: this.config.aiPlanCheckMaxContext,
|
||
checkTimeoutMs: this.config.aiPlanCheckTimeoutMs,
|
||
cooldownMs: this.config.aiPlanCheckCooldownMs,
|
||
});
|
||
}
|
||
|
||
this.log(`Config updated: ${JSON.stringify(config)}`);
|
||
}
|
||
|
||
/**
|
||
* Get current configuration.
|
||
* @returns Copy of current config (safe to modify)
|
||
*/
|
||
getConfig(): RespawnConfig {
|
||
return { ...this.config };
|
||
}
|
||
|
||
/**
|
||
* Get comprehensive status information.
|
||
*
|
||
* Useful for debugging and monitoring.
|
||
*
|
||
* @returns Status object with:
|
||
* - state: Current state machine state
|
||
* - cycleCount: Number of cycles started
|
||
* - lastActivityTime: Timestamp of last activity
|
||
* - timeSinceActivity: Milliseconds since last activity
|
||
* - promptDetected: Whether prompt indicator seen
|
||
* - workingDetected: Whether working indicator seen
|
||
* - detection: Multi-layer detection status
|
||
* - config: Current configuration
|
||
*/
|
||
getStatus() {
|
||
return {
|
||
state: this._state,
|
||
cycleCount: this.cycleCount,
|
||
lastActivityTime: this.lastActivityTime,
|
||
timeSinceActivity: Date.now() - this.lastActivityTime,
|
||
promptDetected: this.promptDetected,
|
||
workingDetected: this.workingDetected,
|
||
detection: this.getDetectionStatus(),
|
||
config: this.config,
|
||
};
|
||
}
|
||
|
||
// ========== P2-001: Adaptive Timing Methods ==========
|
||
|
||
/**
|
||
* Get the current completion confirm timeout, potentially adjusted by adaptive timing.
|
||
* Uses historical idle detection durations to calculate an optimal timeout.
|
||
*
|
||
* @returns Completion confirm timeout in milliseconds
|
||
*/
|
||
getAdaptiveCompletionConfirmMs(): number {
|
||
if (!this.config.adaptiveTimingEnabled) {
|
||
return this.config.completionConfirmMs ?? 10000;
|
||
}
|
||
|
||
// Need at least 5 samples before adjusting
|
||
if (this.timingHistory.sampleCount < 5) {
|
||
return this.config.completionConfirmMs ?? 10000;
|
||
}
|
||
|
||
return this.timingHistory.adaptiveCompletionConfirmMs;
|
||
}
|
||
|
||
/**
|
||
* Record timing data from a completed cycle for adaptive adjustments.
|
||
*
|
||
* @param idleDetectionMs - Time spent detecting idle
|
||
* @param cycleDurationMs - Total cycle duration
|
||
*/
|
||
private recordTimingData(idleDetectionMs: number, cycleDurationMs: number): void {
|
||
if (!this.config.adaptiveTimingEnabled) return;
|
||
|
||
const history = this.timingHistory;
|
||
|
||
// Add to rolling windows
|
||
history.recentIdleDetectionMs.push(idleDetectionMs);
|
||
history.recentCycleDurationMs.push(cycleDurationMs);
|
||
|
||
// Trim to max samples
|
||
if (history.recentIdleDetectionMs.length > history.maxSamples) {
|
||
history.recentIdleDetectionMs.shift();
|
||
}
|
||
if (history.recentCycleDurationMs.length > history.maxSamples) {
|
||
history.recentCycleDurationMs.shift();
|
||
}
|
||
|
||
history.sampleCount = history.recentIdleDetectionMs.length;
|
||
history.lastUpdatedAt = Date.now();
|
||
|
||
// Recalculate adaptive timing
|
||
this.updateAdaptiveTiming();
|
||
}
|
||
|
||
/**
|
||
* Recalculate the adaptive completion confirm timeout based on historical data.
|
||
* Uses the 75th percentile of recent idle detection times as the new timeout,
|
||
* with a 20% buffer for safety.
|
||
*/
|
||
private updateAdaptiveTiming(): void {
|
||
const history = this.timingHistory;
|
||
const minMs = this.config.adaptiveMinConfirmMs ?? 5000;
|
||
const maxMs = this.config.adaptiveMaxConfirmMs ?? 30000;
|
||
|
||
if (history.recentIdleDetectionMs.length < 5) return;
|
||
|
||
// Sort for percentile calculation
|
||
const sorted = [...history.recentIdleDetectionMs].sort((a, b) => a - b);
|
||
|
||
// Use 75th percentile with 20% buffer
|
||
const p75Index = Math.floor(sorted.length * 0.75);
|
||
const p75Value = sorted[p75Index];
|
||
const withBuffer = Math.round(p75Value * 1.2);
|
||
|
||
// Clamp to configured bounds
|
||
const clamped = Math.max(minMs, Math.min(maxMs, withBuffer));
|
||
|
||
history.adaptiveCompletionConfirmMs = clamped;
|
||
this.log(`Adaptive timing updated: ${clamped}ms (p75=${p75Value}ms, samples=${sorted.length})`);
|
||
}
|
||
|
||
/**
|
||
* Get the current timing history for monitoring.
|
||
* @returns Copy of timing history
|
||
*/
|
||
getTimingHistory(): TimingHistory {
|
||
return { ...this.timingHistory };
|
||
}
|
||
|
||
// ========== P2-002: Skip-Clear Optimization Methods ==========
|
||
|
||
/**
|
||
* Determine whether to skip the /clear step based on current context usage.
|
||
* Skips if token count is below the configured threshold percentage.
|
||
*
|
||
* @returns True if /clear should be skipped
|
||
*/
|
||
private shouldSkipClear(): boolean {
|
||
if (!this.config.skipClearWhenLowContext) return false;
|
||
|
||
const thresholdPercent = this.config.skipClearThresholdPercent ?? 30;
|
||
const maxContext = 200000; // Approximate max context for Claude
|
||
|
||
// Use the session's token count if available
|
||
const currentTokens = this.lastTokenCount;
|
||
if (currentTokens === 0) return false; // Can't determine, don't skip
|
||
|
||
const usagePercent = (currentTokens / maxContext) * 100;
|
||
|
||
if (usagePercent < thresholdPercent) {
|
||
this.log(`Skip-clear optimization: ${usagePercent.toFixed(1)}% < ${thresholdPercent}% threshold`);
|
||
this.logAction('optimization', `Skipping /clear (${usagePercent.toFixed(1)}% context used)`);
|
||
return true;
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
// ========== P2-004: Cycle Metrics Methods ==========
|
||
|
||
/**
|
||
* Start tracking metrics for a new cycle.
|
||
* Called when a respawn cycle begins.
|
||
*/
|
||
private startCycleMetrics(idleReason: string): void {
|
||
if (!this.config.trackCycleMetrics) return;
|
||
|
||
const now = Date.now();
|
||
this.currentCycleMetrics = {
|
||
cycleId: `${this.session.id}:${this.cycleCount}`,
|
||
sessionId: this.session.id,
|
||
cycleNumber: this.cycleCount,
|
||
startedAt: now,
|
||
idleReason,
|
||
idleDetectionMs: now - this.idleDetectionStartTime,
|
||
stepsCompleted: [],
|
||
clearSkipped: false,
|
||
tokenCountAtStart: this.lastTokenCount,
|
||
completionConfirmMsUsed: this.getAdaptiveCompletionConfirmMs(),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Record a completed step in the current cycle.
|
||
* @param step - Name of the step (e.g., 'update', 'clear', 'init')
|
||
*/
|
||
private recordCycleStep(step: string): void {
|
||
if (!this.config.trackCycleMetrics || !this.currentCycleMetrics) return;
|
||
this.currentCycleMetrics.stepsCompleted?.push(step);
|
||
}
|
||
|
||
/**
|
||
* Complete the current cycle metrics with outcome.
|
||
* Adds to recent metrics and updates aggregates.
|
||
*
|
||
* @param outcome - Outcome of the cycle
|
||
* @param errorMessage - Optional error message if outcome is 'error'
|
||
*/
|
||
private completeCycleMetrics(outcome: CycleOutcome, errorMessage?: string): void {
|
||
if (!this.config.trackCycleMetrics || !this.currentCycleMetrics) return;
|
||
|
||
const now = Date.now();
|
||
const metrics: RespawnCycleMetrics = {
|
||
...(this.currentCycleMetrics as RespawnCycleMetrics),
|
||
completedAt: now,
|
||
durationMs: now - (this.currentCycleMetrics.startedAt ?? now),
|
||
outcome,
|
||
errorMessage,
|
||
tokenCountAtEnd: this.lastTokenCount,
|
||
};
|
||
|
||
// Add to recent metrics
|
||
this.recentCycleMetrics.push(metrics);
|
||
if (this.recentCycleMetrics.length > RespawnController.MAX_CYCLE_METRICS_IN_MEMORY) {
|
||
this.recentCycleMetrics.shift();
|
||
}
|
||
|
||
// Record timing data for adaptive timing
|
||
this.recordTimingData(metrics.idleDetectionMs, metrics.durationMs);
|
||
|
||
// Update aggregate metrics
|
||
this.updateAggregateMetrics(metrics);
|
||
|
||
// Clear current cycle
|
||
this.currentCycleMetrics = null;
|
||
|
||
this.log(
|
||
`Cycle #${metrics.cycleNumber} metrics: ${outcome}, duration=${metrics.durationMs}ms, idle_detection=${metrics.idleDetectionMs}ms`
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Update aggregate metrics with a new cycle's data.
|
||
* @param metrics - The completed cycle metrics
|
||
*/
|
||
private updateAggregateMetrics(metrics: RespawnCycleMetrics): void {
|
||
const agg = this.aggregateMetrics;
|
||
|
||
agg.totalCycles++;
|
||
|
||
switch (metrics.outcome) {
|
||
case 'success':
|
||
agg.successfulCycles++;
|
||
break;
|
||
case 'stuck_recovery':
|
||
agg.stuckRecoveryCycles++;
|
||
break;
|
||
case 'blocked':
|
||
agg.blockedCycles++;
|
||
break;
|
||
case 'error':
|
||
agg.errorCycles++;
|
||
break;
|
||
case 'cancelled':
|
||
// Cancelled cycles don't count towards any specific category
|
||
// but are still counted in totalCycles
|
||
break;
|
||
default:
|
||
assertNever(metrics.outcome, `Unhandled CycleOutcome: ${metrics.outcome}`);
|
||
}
|
||
|
||
// Recalculate averages using all recent metrics
|
||
const durations = this.recentCycleMetrics.map((m) => m.durationMs);
|
||
const idleTimes = this.recentCycleMetrics.map((m) => m.idleDetectionMs);
|
||
|
||
if (durations.length > 0) {
|
||
agg.avgCycleDurationMs = Math.round(durations.reduce((a, b) => a + b, 0) / durations.length);
|
||
agg.avgIdleDetectionMs = Math.round(idleTimes.reduce((a, b) => a + b, 0) / idleTimes.length);
|
||
|
||
// Calculate P90
|
||
const sortedDurations = [...durations].sort((a, b) => a - b);
|
||
const p90Index = Math.floor(sortedDurations.length * 0.9);
|
||
agg.p90CycleDurationMs = sortedDurations[p90Index];
|
||
}
|
||
|
||
// Calculate success rate
|
||
agg.successRate = agg.totalCycles > 0 ? Math.round((agg.successfulCycles / agg.totalCycles) * 100) : 100;
|
||
|
||
agg.lastUpdatedAt = Date.now();
|
||
}
|
||
|
||
/**
|
||
* Get aggregate metrics for monitoring.
|
||
* @returns Copy of aggregate metrics
|
||
*/
|
||
getAggregateMetrics(): RespawnAggregateMetrics {
|
||
return { ...this.aggregateMetrics };
|
||
}
|
||
|
||
/**
|
||
* Get recent cycle metrics for analysis.
|
||
* @param limit - Maximum number of metrics to return (default: 20)
|
||
* @returns Recent cycle metrics, newest first
|
||
*/
|
||
getRecentCycleMetrics(limit: number = 20): RespawnCycleMetrics[] {
|
||
return this.recentCycleMetrics.slice(-limit).reverse();
|
||
}
|
||
|
||
// ========== P2-005: Health Score Methods ==========
|
||
|
||
/**
|
||
* Calculate a comprehensive health score for the Ralph Loop system.
|
||
* Aggregates multiple health signals into a single score (0-100).
|
||
*
|
||
* @returns Health score with component breakdown
|
||
*/
|
||
calculateHealthScore(): RalphLoopHealthScore {
|
||
const now = Date.now();
|
||
const components = {
|
||
cycleSuccess: this.calculateCycleSuccessScore(),
|
||
circuitBreaker: this.calculateCircuitBreakerScore(),
|
||
iterationProgress: this.calculateIterationProgressScore(),
|
||
aiChecker: this.calculateAiCheckerScore(),
|
||
stuckRecovery: this.calculateStuckRecoveryScore(),
|
||
};
|
||
|
||
// Weighted average (cycle success is most important)
|
||
const weights = {
|
||
cycleSuccess: 0.35,
|
||
circuitBreaker: 0.2,
|
||
iterationProgress: 0.2,
|
||
aiChecker: 0.15,
|
||
stuckRecovery: 0.1,
|
||
};
|
||
|
||
const score = Math.round(
|
||
components.cycleSuccess * weights.cycleSuccess +
|
||
components.circuitBreaker * weights.circuitBreaker +
|
||
components.iterationProgress * weights.iterationProgress +
|
||
components.aiChecker * weights.aiChecker +
|
||
components.stuckRecovery * weights.stuckRecovery
|
||
);
|
||
|
||
// Determine status
|
||
let status: HealthStatus;
|
||
if (score >= 90) status = 'excellent';
|
||
else if (score >= 70) status = 'good';
|
||
else if (score >= 50) status = 'degraded';
|
||
else status = 'critical';
|
||
|
||
// Generate recommendations
|
||
const recommendations = this.generateHealthRecommendations(components);
|
||
|
||
// Generate summary
|
||
const summary = this.generateHealthSummary(score, status, components);
|
||
|
||
return {
|
||
score,
|
||
status,
|
||
components,
|
||
summary,
|
||
recommendations,
|
||
calculatedAt: now,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Calculate score based on recent cycle success rate.
|
||
*/
|
||
private calculateCycleSuccessScore(): number {
|
||
if (this.aggregateMetrics.totalCycles === 0) return 100; // No data = assume healthy
|
||
return this.aggregateMetrics.successRate;
|
||
}
|
||
|
||
/**
|
||
* Calculate score based on circuit breaker state.
|
||
*/
|
||
private calculateCircuitBreakerScore(): number {
|
||
const tracker = this.session.ralphTracker;
|
||
if (!tracker) return 100;
|
||
|
||
const cb = tracker.circuitBreakerStatus;
|
||
switch (cb.state) {
|
||
case 'CLOSED':
|
||
return 100;
|
||
case 'HALF_OPEN':
|
||
return 50;
|
||
case 'OPEN':
|
||
return 0;
|
||
default:
|
||
return 100;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Calculate score based on iteration progress.
|
||
*/
|
||
private calculateIterationProgressScore(): number {
|
||
const tracker = this.session.ralphTracker;
|
||
if (!tracker) return 100;
|
||
|
||
const stallMetrics = tracker.getIterationStallMetrics();
|
||
const { stallDurationMs, warningThresholdMs, criticalThresholdMs } = stallMetrics;
|
||
|
||
if (stallDurationMs >= criticalThresholdMs) return 0;
|
||
if (stallDurationMs >= warningThresholdMs) return 30;
|
||
if (stallDurationMs >= warningThresholdMs / 2) return 70;
|
||
return 100;
|
||
}
|
||
|
||
/**
|
||
* Calculate score based on AI checker health.
|
||
*/
|
||
private calculateAiCheckerScore(): number {
|
||
const state = this.aiChecker.getState();
|
||
if (state.status === 'disabled') return 30;
|
||
if (state.status === 'cooldown') return 70;
|
||
if (state.consecutiveErrors > 0) return 50;
|
||
return 100;
|
||
}
|
||
|
||
/**
|
||
* Calculate score based on stuck-state recovery count.
|
||
*/
|
||
private calculateStuckRecoveryScore(): number {
|
||
const maxRecoveries = this.config.maxStuckRecoveries ?? 3;
|
||
if (this.stuckRecoveryCount === 0) return 100;
|
||
if (this.stuckRecoveryCount >= maxRecoveries) return 0;
|
||
return Math.round(100 - (this.stuckRecoveryCount / maxRecoveries) * 100);
|
||
}
|
||
|
||
/**
|
||
* Generate health recommendations based on component scores.
|
||
*/
|
||
private generateHealthRecommendations(components: RalphLoopHealthScore['components']): string[] {
|
||
const recommendations: string[] = [];
|
||
|
||
if (components.cycleSuccess < 70) {
|
||
recommendations.push('Cycle success rate is low. Check for recurring errors or stuck states.');
|
||
}
|
||
if (components.circuitBreaker < 50) {
|
||
recommendations.push('Circuit breaker is open or half-open. Review recent errors and consider manual reset.');
|
||
}
|
||
if (components.iterationProgress < 50) {
|
||
recommendations.push('Iteration progress has stalled. Check if Claude is stuck on a task.');
|
||
}
|
||
if (components.aiChecker < 50) {
|
||
recommendations.push('AI idle checker has errors. May need to check Claude CLI availability.');
|
||
}
|
||
if (components.stuckRecovery < 50) {
|
||
recommendations.push('Multiple stuck-state recoveries occurred. Consider increasing timeouts.');
|
||
}
|
||
|
||
if (recommendations.length === 0) {
|
||
recommendations.push('System is healthy. No action needed.');
|
||
}
|
||
|
||
return recommendations;
|
||
}
|
||
|
||
/**
|
||
* Generate a human-readable health summary.
|
||
*/
|
||
private generateHealthSummary(
|
||
score: number,
|
||
status: HealthStatus,
|
||
components: RalphLoopHealthScore['components']
|
||
): string {
|
||
const lowest = Object.entries(components).reduce((min, [key, val]) => (val < min.val ? { key, val } : min), {
|
||
key: '',
|
||
val: 100,
|
||
});
|
||
|
||
if (status === 'excellent') {
|
||
return `Ralph Loop is operating excellently (${score}/100). All systems healthy.`;
|
||
}
|
||
if (status === 'good') {
|
||
return `Ralph Loop is operating well (${score}/100). Minor issues in ${lowest.key}.`;
|
||
}
|
||
if (status === 'degraded') {
|
||
return `Ralph Loop is degraded (${score}/100). Primary issue: ${lowest.key} (${lowest.val}/100).`;
|
||
}
|
||
return `Ralph Loop is in critical state (${score}/100). Immediate attention needed: ${lowest.key}.`;
|
||
}
|
||
}
|