2026-01-24 18:48:37 +01:00
/**
* @fileoverview AI-Powered Idle Checker for Respawn Controller
*
2026-02-18 12:51:35 +01:00
* Spawns a fresh Claude CLI session in a tmux session to analyze terminal output
2026-01-24 18:48:37 +01:00
* and provide a definitive IDLE/WORKING verdict. This replaces the "Worked for Xm Xs"
* pattern as the primary idle detection signal.
*
* ## How It Works
*
* 1. Generate temp file path for output capture
2026-02-26 16:44:34 +01:00
* 2. Spawn tmux: `tmux new-session -d -s codeman-aicheck-<short> bash -c 'claude -p ...'`
2026-01-24 18:48:37 +01:00
* 3. Poll the temp file every 500ms for `__AICHECK_DONE__` marker
* 4. Parse the file content for IDLE/WORKING on the first word
2026-02-18 12:51:35 +01:00
* 5. Kill tmux session and delete temp file
2026-01-24 18:48:37 +01:00
*
* ## Error Handling
*
2026-02-18 12:51:35 +01:00
* - Tmux spawn fails: 1-min cooldown, increment error counter
* - Check times out (90s): Kill session, 1-min cooldown
2026-01-24 18:48:37 +01:00
* - Can't parse IDLE/WORKING: Treat as WORKING, 1-min cooldown
* - 3 consecutive errors: Disable AI check, fall back to noOutputTimeoutMs
* - Claude CLI not found: Disable permanently
*
* @module ai-idle-checker
*/
2026-01-25 08:25:51 +01:00
import {
AiCheckerBase ,
type AiCheckerConfigBase ,
type AiCheckerResultBase ,
type AiCheckerStateBase ,
} from './ai-checker-base.js' ;
2026-03-07 07:33:44 +01:00
import {
AI_CHECK_MODEL ,
AI_IDLE_CHECK_MAX_CONTEXT ,
AI_IDLE_CHECK_TIMEOUT_MS ,
AI_IDLE_CHECK_COOLDOWN_MS ,
AI_IDLE_CHECK_ERROR_COOLDOWN_MS ,
AI_CHECK_MAX_CONSECUTIVE_ERRORS ,
} from './config/ai-defaults.js' ;
2026-01-24 18:48:37 +01:00
// ========== Types ==========
2026-02-27 13:16:23 +01:00
export type AiIdleCheckConfig = AiCheckerConfigBase ;
2026-01-24 18:48:37 +01:00
export type AiCheckVerdict = 'IDLE' | 'WORKING' | 'ERROR' ;
2026-02-27 13:16:23 +01:00
export type AiCheckResult = AiCheckerResultBase < AiCheckVerdict >;
2026-01-24 18:48:37 +01:00
2026-02-27 13:16:23 +01:00
export type AiCheckState = AiCheckerStateBase < AiCheckVerdict >;
2026-01-24 18:48:37 +01:00
// ========== Constants ==========
const DEFAULT_AI_CHECK_CONFIG : AiIdleCheckConfig = {
enabled : true ,
2026-03-01 13:19:16 +01:00
model : AI_CHECK_MODEL ,
maxContextChars : AI_IDLE_CHECK_MAX_CONTEXT ,
2026-03-07 07:33:44 +01:00
checkTimeoutMs : AI_IDLE_CHECK_TIMEOUT_MS ,
cooldownMs : AI_IDLE_CHECK_COOLDOWN_MS ,
errorCooldownMs : AI_IDLE_CHECK_ERROR_COOLDOWN_MS ,
maxConsecutiveErrors : AI_CHECK_MAX_CONSECUTIVE_ERRORS ,
2026-01-24 18:48:37 +01:00
};
/** Pattern to match IDLE or WORKING as the first word of output */
const VERDICT_PATTERN = /^\s*(IDLE|WORKING)\b/i ;
2026-01-30 17:20:53 +01:00
/**
* The prompt sent to the AI idle checker.
*
* P1-005: Enhanced with more specific working pattern examples and clearer structure.
*/
const AI_CHECK_PROMPT = `You are analyzing terminal output from a Claude Code CLI session. Determine if Claude has FINISHED working (IDLE) or is STILL WORKING (WORKING).
2026-01-24 18:48:37 +01:00
2026-01-30 17:20:53 +01:00
CRITICAL RULE: When in doubt, ALWAYS answer WORKING. False positives (saying IDLE when Claude is working) cause session interruptions. It's safer to wait longer than to interrupt active work.
2026-01-26 00:55:29 +01:00
2026-01-30 17:20:53 +01:00
## IDLE Indicators (need AT LEAST 2 of these together)
2026-01-26 00:55:29 +01:00
2026-01-30 17:20:53 +01:00
1. **Completion Summary** - The most reliable signal:
- "✻ Worked for Xm Ys" (e.g., "✻ Worked for 2m 46s")
- "Worked for Xs" (e.g., "Worked for 5s")
- Cost summary: "$X.XX spent" or "X tokens used"
2026-01-24 18:48:37 +01:00
2026-01-30 17:20:53 +01:00
2. **Input Prompt Visible**:
- The ❯ prompt character at the very end
- Empty line after completion summary
- Waiting cursor position
3. **Task Completion Language**:
- "All done", "Finished", "Completed successfully"
- Explicit "waiting for input" or similar
## WORKING Indicators (ANY ONE of these = answer WORKING)
### Active Processing Indicators:
- **Spinners**: ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏ (Braille), ◐ ◓ ◑ ◒ (quarter), ⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷
- **Activity Words**: Thinking, Writing, Reading, Running, Searching, Editing, Creating, Deleting, Analyzing, Executing, Synthesizing, Compiling, Building, Processing, Loading, Generating, Testing, Checking, Validating, Brewing, Formatting, Linting, Installing, Fetching, Downloading
### Tool Execution in Progress:
- Bash commands with no result shown yet
- "Running: npm test", "Executing command..."
- File read/write operations incomplete
- Progress bars or percentage indicators
- Test suite running (dots appearing, "Test Suites: X passed")
### Output Structure Issues:
- Truncated lines without completion
- JSON/code blocks not closed
- Multi-line output clearly incomplete
- "..." indicating more to come
- Output ending mid-sentence or mid-word
### Claude Planning/Thinking:
- "Let me...", "I'll...", "Now I need to..."
- TodoWrite updates without completion
- Plan mode approval prompts (numbered options)
## Terminal Output to Analyze
2026-01-24 18:48:37 +01:00
---
{TERMINAL_BUFFER}
---
2026-01-30 17:20:53 +01:00
## Your Response
First line: EXACTLY "IDLE" or "WORKING" (nothing else)
Second line onwards: Brief explanation of your reasoning.
Remember: When uncertain, answer WORKING.` ;
2026-01-24 18:48:37 +01:00
// ========== AiIdleChecker Class ==========
/**
* Manages AI-powered idle detection by spawning a fresh Claude CLI session
* to analyze terminal output and provide a definitive IDLE/WORKING verdict.
*/
2026-02-27 13:16:23 +01:00
export class AiIdleChecker extends AiCheckerBase < AiCheckVerdict , AiIdleCheckConfig , AiCheckResult , AiCheckState > {
2026-02-26 16:44:34 +01:00
protected readonly muxNamePrefix = 'codeman-aicheck-' ;
2026-01-25 08:25:51 +01:00
protected readonly doneMarker = '__AICHECK_DONE__' ;
2026-02-26 16:44:34 +01:00
protected readonly tempFilePrefix = 'codeman-aicheck' ;
2026-01-25 08:25:51 +01:00
protected readonly logPrefix = '[AiIdleChecker]' ;
protected readonly checkDescription = 'AI idle check' ;
2026-01-24 18:48:37 +01:00
constructor ( sessionId : string , config : Partial < AiIdleCheckConfig > = {}) {
2026-01-25 08:25:51 +01:00
super ( sessionId , DEFAULT_AI_CHECK_CONFIG , config );
2026-01-24 18:48:37 +01:00
}
2026-01-25 08:25:51 +01:00
protected buildPrompt ( terminalBuffer : string ) : string {
2026-02-12 14:41:27 +01:00
return AI_CHECK_PROMPT . replace ( '{TERMINAL_BUFFER}' , terminalBuffer );
2026-01-24 18:48:37 +01:00
}
2026-01-25 08:25:51 +01:00
protected parseVerdict ( output : string ) : { verdict : AiCheckVerdict ; reasoning : string } | null {
2026-01-24 18:48:37 +01:00
const match = output . match ( VERDICT_PATTERN );
2026-01-25 08:25:51 +01:00
if ( ! match ) return null ;
2026-01-24 18:48:37 +01:00
const verdict = match [ 1 ]. toUpperCase () as 'IDLE' | 'WORKING' ;
const lines = output . split ( '\n' );
const reasoning = lines . slice ( 1 ). join ( '\n' ). trim () || `AI determined: ${ verdict } ` ;
2026-01-25 08:25:51 +01:00
return { verdict , reasoning };
}
protected getPositiveVerdict () : AiCheckVerdict {
return 'IDLE' ;
}
protected getNegativeVerdict () : AiCheckVerdict {
return 'WORKING' ;
}
protected getErrorVerdict () : AiCheckVerdict {
return 'ERROR' ;
}
protected createErrorResult ( reasoning : string , durationMs : number ) : AiCheckResult {
return { verdict : 'ERROR' , reasoning , durationMs };
}
protected createResult ( verdict : AiCheckVerdict , reasoning : string , durationMs : number ) : AiCheckResult {
2026-01-24 18:48:37 +01:00
return { verdict , reasoning , durationMs };
}
}