mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-08 08:29:42 +02:00
refactor: extract AI checker base class + fix persistence + dedupe restoration
- Add AiCheckerBase abstract class to eliminate ~700 lines of duplication between AiIdleChecker and AiPlanChecker - Fix missing persistence fields (completionConfirmMs, noOutputTimeoutMs) that caused custom timing values to be lost on server restart - Extract restoreRespawnController() helper to dedupe session restoration logic between state.json and screens.json paths Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
arkon
@@ -0,0 +1,554 @@
|
||||
/**
|
||||
* @fileoverview Base Class for AI Checker Components
|
||||
*
|
||||
* Provides shared functionality for AI-powered checkers that spawn fresh Claude CLI
|
||||
* sessions to analyze terminal output. This base class handles:
|
||||
* - Screen session spawning and cleanup
|
||||
* - Temp file management for output capture
|
||||
* - Polling for completion markers
|
||||
* - Cooldown management
|
||||
* - Error handling and consecutive error tracking
|
||||
* - Event emission for state changes
|
||||
*
|
||||
* Subclasses implement:
|
||||
* - `screenNamePrefix`: Prefix for screen session names (e.g., 'claudeman-aicheck-')
|
||||
* - `doneMarker`: Completion marker in output file (e.g., '__AICHECK_DONE__')
|
||||
* - `tempFilePrefix`: Prefix for temp files (e.g., 'claudeman-aicheck')
|
||||
* - `logPrefix`: Prefix for log messages (e.g., '[AiIdleChecker]')
|
||||
* - `buildPrompt()`: Build the prompt from terminal buffer
|
||||
* - `parseVerdict()`: Parse the verdict from AI output
|
||||
* - `getPositiveVerdict()`: Return the "positive" verdict that doesn't trigger cooldown
|
||||
* - `defaultConfig`: Default configuration values
|
||||
*
|
||||
* @module ai-checker-base
|
||||
*/
|
||||
|
||||
import { execSync, spawn as childSpawn } from 'node:child_process';
|
||||
import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import { EventEmitter } from 'node:events';
|
||||
import { getAugmentedPath } from './session.js';
|
||||
|
||||
// ========== Types ==========
|
||||
|
||||
/** Base configuration shared by all AI checkers */
|
||||
export interface AiCheckerConfigBase {
|
||||
/** Whether the checker is enabled */
|
||||
enabled: boolean;
|
||||
/** Model to use for the check */
|
||||
model: string;
|
||||
/** Maximum characters of terminal buffer to send */
|
||||
maxContextChars: number;
|
||||
/** Timeout for the check in ms */
|
||||
checkTimeoutMs: number;
|
||||
/** Cooldown after negative verdict in ms */
|
||||
cooldownMs: number;
|
||||
/** Cooldown after errors in ms */
|
||||
errorCooldownMs: number;
|
||||
/** Max consecutive errors before disabling */
|
||||
maxConsecutiveErrors: number;
|
||||
}
|
||||
|
||||
/** Status values shared by all AI checkers */
|
||||
export type AiCheckerStatus = 'ready' | 'checking' | 'cooldown' | 'disabled' | 'error';
|
||||
|
||||
/** Base result structure for all AI checkers */
|
||||
export interface AiCheckerResultBase<V extends string> {
|
||||
verdict: V;
|
||||
reasoning: string;
|
||||
durationMs: number;
|
||||
}
|
||||
|
||||
/** Base state structure for all AI checkers */
|
||||
export interface AiCheckerStateBase<V extends string> {
|
||||
status: AiCheckerStatus;
|
||||
lastVerdict: V | null;
|
||||
lastReasoning: string | null;
|
||||
lastCheckDurationMs: number | null;
|
||||
cooldownEndsAt: number | null;
|
||||
consecutiveErrors: number;
|
||||
totalChecks: number;
|
||||
disabledReason: string | null;
|
||||
}
|
||||
|
||||
/** Events emitted by AI checkers */
|
||||
export interface AiCheckerEvents<R> {
|
||||
checkStarted: () => void;
|
||||
checkCompleted: (result: R) => void;
|
||||
checkFailed: (error: string) => void;
|
||||
cooldownStarted: (endsAt: number) => void;
|
||||
cooldownEnded: () => void;
|
||||
disabled: (reason: string) => void;
|
||||
log: (message: string) => void;
|
||||
}
|
||||
|
||||
// ========== Constants ==========
|
||||
|
||||
/** ANSI escape code pattern for stripping terminal formatting */
|
||||
const ANSI_ESCAPE_PATTERN = /\x1b\[[0-9;]*[A-Za-z]/g;
|
||||
|
||||
/** Poll interval for checking temp file completion */
|
||||
const POLL_INTERVAL_MS = 500;
|
||||
|
||||
// ========== AiCheckerBase Class ==========
|
||||
|
||||
/**
|
||||
* Abstract base class for AI-powered checkers.
|
||||
* Handles spawning Claude CLI in a screen session to analyze terminal output.
|
||||
*
|
||||
* @template V - The verdict type (e.g., 'IDLE' | 'WORKING' | 'ERROR')
|
||||
* @template C - The configuration type
|
||||
* @template R - The result type
|
||||
* @template S - The state type
|
||||
*/
|
||||
export abstract class AiCheckerBase<
|
||||
V extends string,
|
||||
C extends AiCheckerConfigBase,
|
||||
R extends AiCheckerResultBase<V>,
|
||||
S extends AiCheckerStateBase<V>
|
||||
> extends EventEmitter {
|
||||
protected config: C;
|
||||
protected sessionId: string;
|
||||
|
||||
// State
|
||||
protected _status: AiCheckerStatus = 'ready';
|
||||
protected lastVerdict: V | null = null;
|
||||
protected lastReasoning: string | null = null;
|
||||
protected lastCheckDurationMs: number | null = null;
|
||||
protected cooldownEndsAt: number | null = null;
|
||||
protected cooldownTimer: NodeJS.Timeout | null = null;
|
||||
protected consecutiveErrors: number = 0;
|
||||
protected totalChecks: number = 0;
|
||||
protected disabledReason: string | null = null;
|
||||
|
||||
// Active check state
|
||||
protected checkScreenName: string | null = null;
|
||||
protected checkTempFile: string | null = null;
|
||||
protected checkPromptFile: string | null = null;
|
||||
protected checkPollTimer: NodeJS.Timeout | null = null;
|
||||
protected checkTimeoutTimer: NodeJS.Timeout | null = null;
|
||||
protected checkStartTime: number = 0;
|
||||
protected checkCancelled: boolean = false;
|
||||
protected checkResolve: ((result: R) => void) | null = null;
|
||||
|
||||
// ========== Abstract Properties ==========
|
||||
|
||||
/** Prefix for screen session names (e.g., 'claudeman-aicheck-') */
|
||||
protected abstract readonly screenNamePrefix: string;
|
||||
|
||||
/** Marker written to temp file when check is complete */
|
||||
protected abstract readonly doneMarker: string;
|
||||
|
||||
/** Prefix for temp files (e.g., 'claudeman-aicheck') */
|
||||
protected abstract readonly tempFilePrefix: string;
|
||||
|
||||
/** Prefix for log messages (e.g., '[AiIdleChecker]') */
|
||||
protected abstract readonly logPrefix: string;
|
||||
|
||||
/** Description for log messages (e.g., 'AI idle check', 'AI plan check') */
|
||||
protected abstract readonly checkDescription: string;
|
||||
|
||||
// ========== Abstract Methods ==========
|
||||
|
||||
/**
|
||||
* Build the prompt to send to Claude.
|
||||
* @param terminalBuffer - The trimmed and stripped terminal buffer
|
||||
* @returns The complete prompt string
|
||||
*/
|
||||
protected abstract buildPrompt(terminalBuffer: string): string;
|
||||
|
||||
/**
|
||||
* Parse the verdict from Claude's output.
|
||||
* @param output - The raw output from Claude (without done marker)
|
||||
* @returns The parsed verdict and reasoning, or null if unparseable
|
||||
*/
|
||||
protected abstract parseVerdict(output: string): { verdict: V; reasoning: string } | null;
|
||||
|
||||
/**
|
||||
* Get the "positive" verdict that indicates success and doesn't trigger cooldown.
|
||||
* For idle checker this is 'IDLE', for plan checker this is 'PLAN_MODE'.
|
||||
*/
|
||||
protected abstract getPositiveVerdict(): V;
|
||||
|
||||
/**
|
||||
* Get the "negative" verdict that triggers cooldown.
|
||||
* For idle checker this is 'WORKING', for plan checker this is 'NOT_PLAN_MODE'.
|
||||
*/
|
||||
protected abstract getNegativeVerdict(): V;
|
||||
|
||||
/**
|
||||
* Get the error verdict value.
|
||||
*/
|
||||
protected abstract getErrorVerdict(): V;
|
||||
|
||||
/**
|
||||
* Create an error result.
|
||||
*/
|
||||
protected abstract createErrorResult(reasoning: string, durationMs: number): R;
|
||||
|
||||
/**
|
||||
* Create a success result.
|
||||
*/
|
||||
protected abstract createResult(verdict: V, reasoning: string, durationMs: number): R;
|
||||
|
||||
constructor(sessionId: string, defaultConfig: C, config: Partial<C> = {}) {
|
||||
super();
|
||||
this.sessionId = sessionId;
|
||||
// Filter out undefined values to prevent overwriting defaults
|
||||
const filteredConfig = Object.fromEntries(
|
||||
Object.entries(config).filter(([, v]) => v !== undefined)
|
||||
) as Partial<C>;
|
||||
this.config = { ...defaultConfig, ...filteredConfig };
|
||||
}
|
||||
|
||||
/** Get the current status */
|
||||
get status(): AiCheckerStatus {
|
||||
return this._status;
|
||||
}
|
||||
|
||||
/** Get comprehensive state for UI display */
|
||||
getState(): S {
|
||||
return {
|
||||
status: this._status,
|
||||
lastVerdict: this.lastVerdict,
|
||||
lastReasoning: this.lastReasoning,
|
||||
lastCheckDurationMs: this.lastCheckDurationMs,
|
||||
cooldownEndsAt: this.cooldownEndsAt,
|
||||
consecutiveErrors: this.consecutiveErrors,
|
||||
totalChecks: this.totalChecks,
|
||||
disabledReason: this.disabledReason,
|
||||
} as S;
|
||||
}
|
||||
|
||||
/** Check if the checker is on cooldown */
|
||||
isOnCooldown(): boolean {
|
||||
if (this.cooldownEndsAt === null) return false;
|
||||
return Date.now() < this.cooldownEndsAt;
|
||||
}
|
||||
|
||||
/** Get remaining cooldown time in ms */
|
||||
getCooldownRemainingMs(): number {
|
||||
if (this.cooldownEndsAt === null) return 0;
|
||||
return Math.max(0, this.cooldownEndsAt - Date.now());
|
||||
}
|
||||
|
||||
/**
|
||||
* Run an AI check against the provided terminal buffer.
|
||||
* Spawns a fresh Claude CLI in a screen, captures output to temp file.
|
||||
*
|
||||
* @param terminalBuffer - Raw terminal output to analyze
|
||||
* @returns The verdict result
|
||||
*/
|
||||
async check(terminalBuffer: string): Promise<R> {
|
||||
if (this._status === 'disabled') {
|
||||
return this.createErrorResult(`Disabled: ${this.disabledReason}`, 0);
|
||||
}
|
||||
|
||||
if (this.isOnCooldown()) {
|
||||
return this.createErrorResult('On cooldown', 0);
|
||||
}
|
||||
|
||||
if (this._status === 'checking') {
|
||||
return this.createErrorResult('Already checking', 0);
|
||||
}
|
||||
|
||||
this._status = 'checking';
|
||||
this.checkCancelled = false;
|
||||
this.checkStartTime = Date.now();
|
||||
this.totalChecks++;
|
||||
this.emit('checkStarted');
|
||||
this.log(`Starting ${this.checkDescription}`);
|
||||
|
||||
try {
|
||||
const result = await this.runCheck(terminalBuffer);
|
||||
|
||||
if (this.checkCancelled) {
|
||||
return this.createErrorResult('Cancelled', Date.now() - this.checkStartTime);
|
||||
}
|
||||
|
||||
this.lastVerdict = result.verdict;
|
||||
this.lastReasoning = result.reasoning;
|
||||
this.lastCheckDurationMs = result.durationMs;
|
||||
|
||||
if (result.verdict === this.getPositiveVerdict()) {
|
||||
this.consecutiveErrors = 0;
|
||||
this._status = 'ready';
|
||||
this.log(`${this.checkDescription} verdict: ${result.verdict} (${result.durationMs}ms) - ${result.reasoning}`);
|
||||
} else if (result.verdict === this.getNegativeVerdict()) {
|
||||
this.consecutiveErrors = 0;
|
||||
this.startCooldown(this.config.cooldownMs);
|
||||
this.log(`${this.checkDescription} verdict: ${result.verdict} (${result.durationMs}ms) - ${result.reasoning}`);
|
||||
} else {
|
||||
this.handleError('Unexpected verdict');
|
||||
}
|
||||
|
||||
this.emit('checkCompleted', result);
|
||||
return result;
|
||||
} catch (err) {
|
||||
const errorMsg = err instanceof Error ? err.message : String(err);
|
||||
this.handleError(errorMsg);
|
||||
const result = this.createErrorResult(errorMsg, Date.now() - this.checkStartTime);
|
||||
this.emit('checkFailed', errorMsg);
|
||||
return result;
|
||||
} finally {
|
||||
this.cleanupCheck();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel an in-progress check.
|
||||
* Kills the screen session and cleans up.
|
||||
*/
|
||||
cancel(): void {
|
||||
if (this._status !== 'checking') return;
|
||||
|
||||
this.log(`Cancelling ${this.checkDescription}`);
|
||||
this.checkCancelled = true;
|
||||
|
||||
// Clear poll/timeout timers first to prevent race condition where
|
||||
// the poll timer fires between setting checkCancelled and cleanup
|
||||
this.cleanupCheck();
|
||||
|
||||
// Resolve the pending promise after cleanup
|
||||
if (this.checkResolve) {
|
||||
this.checkResolve(this.createErrorResult('Cancelled', Date.now() - this.checkStartTime));
|
||||
this.checkResolve = null;
|
||||
}
|
||||
|
||||
this._status = 'ready';
|
||||
}
|
||||
|
||||
/** Reset all state for a new cycle */
|
||||
reset(): void {
|
||||
this.cancel();
|
||||
this.clearCooldown();
|
||||
this.lastVerdict = null;
|
||||
this.lastReasoning = null;
|
||||
this.lastCheckDurationMs = null;
|
||||
this.consecutiveErrors = 0;
|
||||
this._status = this.disabledReason ? 'disabled' : 'ready';
|
||||
}
|
||||
|
||||
/** Update configuration at runtime */
|
||||
updateConfig(config: Partial<C>): void {
|
||||
// Filter out undefined values to prevent overwriting existing config
|
||||
const filteredConfig = Object.fromEntries(
|
||||
Object.entries(config).filter(([, v]) => v !== undefined)
|
||||
) as Partial<C>;
|
||||
this.config = { ...this.config, ...filteredConfig };
|
||||
if (config.enabled === false) {
|
||||
this.disable('Disabled by config');
|
||||
} else if (config.enabled === true && this._status === 'disabled') {
|
||||
this.disabledReason = null;
|
||||
this._status = 'ready';
|
||||
}
|
||||
}
|
||||
|
||||
/** Get current config */
|
||||
getConfig(): C {
|
||||
return { ...this.config };
|
||||
}
|
||||
|
||||
// ========== Private Methods ==========
|
||||
|
||||
private async runCheck(terminalBuffer: string): Promise<R> {
|
||||
// Prepare the terminal buffer (strip ANSI, trim to maxContextChars)
|
||||
const stripped = terminalBuffer.replace(ANSI_ESCAPE_PATTERN, '');
|
||||
const trimmed = stripped.length > this.config.maxContextChars
|
||||
? stripped.slice(-this.config.maxContextChars)
|
||||
: stripped;
|
||||
|
||||
// Build the prompt
|
||||
const prompt = this.buildPrompt(trimmed);
|
||||
|
||||
// Generate temp files and screen name
|
||||
const shortId = this.sessionId.slice(0, 8);
|
||||
const timestamp = Date.now();
|
||||
this.checkTempFile = join(tmpdir(), `${this.tempFilePrefix}-${shortId}-${timestamp}.txt`);
|
||||
this.checkPromptFile = join(tmpdir(), `${this.tempFilePrefix}-prompt-${shortId}-${timestamp}.txt`);
|
||||
this.checkScreenName = `${this.screenNamePrefix}${shortId}`;
|
||||
|
||||
// Ensure output temp file exists (empty) so we can poll it
|
||||
writeFileSync(this.checkTempFile, '');
|
||||
|
||||
// Write prompt to file to avoid E2BIG error (argument list too long)
|
||||
// The prompt can be 16KB+ which exceeds shell argument limits
|
||||
writeFileSync(this.checkPromptFile, prompt);
|
||||
|
||||
// Build the command - read prompt from file via stdin to avoid argument size limits
|
||||
const modelArg = `--model ${this.config.model}`;
|
||||
const augmentedPath = getAugmentedPath();
|
||||
const claudeCmd = `cat "${this.checkPromptFile}" | claude -p ${modelArg} --output-format text`;
|
||||
const fullCmd = `export PATH="${augmentedPath}"; ${claudeCmd} > "${this.checkTempFile}" 2>&1; echo "${this.doneMarker}" >> "${this.checkTempFile}"; rm -f "${this.checkPromptFile}"`;
|
||||
|
||||
// Spawn screen
|
||||
try {
|
||||
// Kill any leftover screen with this name first
|
||||
try {
|
||||
execSync(`screen -X -S ${this.checkScreenName} quit 2>/dev/null`, { timeout: 3000 });
|
||||
} catch {
|
||||
// No existing screen, that's fine
|
||||
}
|
||||
|
||||
const screenProcess = childSpawn('screen', [
|
||||
'-dmS', this.checkScreenName,
|
||||
'-c', '/dev/null',
|
||||
'bash', '-c', fullCmd
|
||||
], {
|
||||
detached: true,
|
||||
stdio: 'ignore',
|
||||
});
|
||||
screenProcess.unref();
|
||||
} catch (err) {
|
||||
throw new Error(`Failed to spawn ${this.checkDescription} screen: ${err instanceof Error ? err.message : String(err)}`);
|
||||
}
|
||||
|
||||
// Poll the temp file for completion
|
||||
return new Promise<R>((resolve, reject) => {
|
||||
const startTime = this.checkStartTime;
|
||||
this.checkResolve = resolve;
|
||||
|
||||
this.checkPollTimer = setInterval(() => {
|
||||
if (this.checkCancelled) {
|
||||
// Cancel was already handled by cancel() calling resolve
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
if (!this.checkTempFile || !existsSync(this.checkTempFile)) return;
|
||||
const content = readFileSync(this.checkTempFile, 'utf-8');
|
||||
if (content.includes(this.doneMarker)) {
|
||||
const durationMs = Date.now() - startTime;
|
||||
const result = this.parseOutput(content, durationMs);
|
||||
this.checkResolve = null;
|
||||
resolve(result);
|
||||
}
|
||||
} catch {
|
||||
// File might not be ready yet, keep polling
|
||||
}
|
||||
}, POLL_INTERVAL_MS);
|
||||
|
||||
// Set timeout
|
||||
this.checkTimeoutTimer = setTimeout(() => {
|
||||
if (this._status === 'checking' && !this.checkCancelled) {
|
||||
this.checkResolve = null;
|
||||
reject(new Error(`${this.checkDescription} timed out after ${this.config.checkTimeoutMs}ms`));
|
||||
}
|
||||
}, this.config.checkTimeoutMs);
|
||||
});
|
||||
}
|
||||
|
||||
private parseOutput(content: string, durationMs: number): R {
|
||||
// Remove the done marker and trim
|
||||
const output = content.replace(this.doneMarker, '').trim();
|
||||
|
||||
if (!output) {
|
||||
return this.createErrorResult(`Empty output from ${this.checkDescription}`, durationMs);
|
||||
}
|
||||
|
||||
// Delegate to subclass for verdict parsing
|
||||
const parsed = this.parseVerdict(output);
|
||||
if (!parsed) {
|
||||
return this.createErrorResult(`Could not parse verdict from: "${output.substring(0, 100)}"`, durationMs);
|
||||
}
|
||||
|
||||
return this.createResult(parsed.verdict, parsed.reasoning, durationMs);
|
||||
}
|
||||
|
||||
private cleanupCheck(): void {
|
||||
// Clear poll timer
|
||||
if (this.checkPollTimer) {
|
||||
clearInterval(this.checkPollTimer);
|
||||
this.checkPollTimer = null;
|
||||
}
|
||||
|
||||
// Clear timeout timer
|
||||
if (this.checkTimeoutTimer) {
|
||||
clearTimeout(this.checkTimeoutTimer);
|
||||
this.checkTimeoutTimer = null;
|
||||
}
|
||||
|
||||
// Kill the screen
|
||||
if (this.checkScreenName) {
|
||||
try {
|
||||
execSync(`screen -X -S ${this.checkScreenName} quit 2>/dev/null`, { timeout: 3000 });
|
||||
} catch {
|
||||
// Screen may already be dead
|
||||
}
|
||||
this.checkScreenName = null;
|
||||
}
|
||||
|
||||
// Delete temp files
|
||||
if (this.checkTempFile) {
|
||||
try {
|
||||
if (existsSync(this.checkTempFile)) {
|
||||
unlinkSync(this.checkTempFile);
|
||||
}
|
||||
} catch {
|
||||
// Best effort cleanup
|
||||
}
|
||||
this.checkTempFile = null;
|
||||
}
|
||||
|
||||
if (this.checkPromptFile) {
|
||||
try {
|
||||
if (existsSync(this.checkPromptFile)) {
|
||||
unlinkSync(this.checkPromptFile);
|
||||
}
|
||||
} catch {
|
||||
// Best effort cleanup
|
||||
}
|
||||
this.checkPromptFile = null;
|
||||
}
|
||||
}
|
||||
|
||||
private handleError(errorMsg: string): void {
|
||||
this.consecutiveErrors++;
|
||||
this.log(`${this.checkDescription} error (${this.consecutiveErrors}/${this.config.maxConsecutiveErrors}): ${errorMsg}`);
|
||||
|
||||
if (this.consecutiveErrors >= this.config.maxConsecutiveErrors) {
|
||||
this.disable(`${this.config.maxConsecutiveErrors} consecutive errors: ${errorMsg}`);
|
||||
} else {
|
||||
this.startCooldown(this.config.errorCooldownMs);
|
||||
}
|
||||
}
|
||||
|
||||
private startCooldown(durationMs: number): void {
|
||||
this.clearCooldown();
|
||||
this.cooldownEndsAt = Date.now() + durationMs;
|
||||
this._status = 'cooldown';
|
||||
this.emit('cooldownStarted', this.cooldownEndsAt);
|
||||
this.log(`Cooldown started: ${Math.round(durationMs / 1000)}s`);
|
||||
|
||||
this.cooldownTimer = setTimeout(() => {
|
||||
this.cooldownEndsAt = null;
|
||||
this._status = 'ready';
|
||||
this.emit('cooldownEnded');
|
||||
this.log('Cooldown ended');
|
||||
}, durationMs);
|
||||
}
|
||||
|
||||
private clearCooldown(): void {
|
||||
if (this.cooldownTimer) {
|
||||
clearTimeout(this.cooldownTimer);
|
||||
this.cooldownTimer = null;
|
||||
}
|
||||
this.cooldownEndsAt = null;
|
||||
if (this._status === 'cooldown') {
|
||||
this._status = 'ready';
|
||||
}
|
||||
}
|
||||
|
||||
private disable(reason: string): void {
|
||||
this.disabledReason = reason;
|
||||
this._status = 'disabled';
|
||||
this.clearCooldown();
|
||||
this.log(`${this.checkDescription} disabled: ${reason}`);
|
||||
this.emit('disabled', reason);
|
||||
}
|
||||
|
||||
private log(message: string): void {
|
||||
this.emit('log', `${this.logPrefix} ${message}`);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user