2026-01-21 04:25:53 +01:00
/**
* @fileoverview Core PTY session wrapper for Claude CLI interactions.
*
* This module provides the Session class which manages a PTY (pseudo-terminal)
* process running the Claude CLI. It supports three operation modes:
*
* 1. **One-shot mode** (`runPrompt`): Execute a single prompt and get JSON response
* 2. **Interactive mode** (`startInteractive`): Start an interactive Claude session
* 3. **Shell mode**: Run a plain bash shell for debugging/testing
*
2026-02-18 12:51:35 +01:00
* The session can optionally run inside a tmux session for persistence across disconnects.
* It tracks tokens, costs, background tasks, and supports
2026-01-21 04:25:53 +01:00
* auto-clear/auto-compact functionality when token limits are approached.
*
* @module session
*/
2026-01-18 04:50:46 +01:00
import { EventEmitter } from 'node:events' ;
import { v4 as uuidv4 } from 'uuid' ;
2026-01-18 21:36:03 +01:00
import * as pty from 'node-pty' ;
2026-02-12 10:29:57 +01:00
import { SessionState , SessionStatus , SessionConfig , RalphTrackerState , RalphTodoItem , ActiveBashTool , NiceConfig , DEFAULT_NICE_CONFIG } from './types.js' ;
import type { TerminalMultiplexer , MuxSession } from './mux-interface.js' ;
2026-01-19 00:38:11 +01:00
import { TaskTracker , type BackgroundTask } from './task-tracker.js' ;
2026-01-21 22:36:45 +01:00
import { RalphTracker } from './ralph-tracker.js' ;
2026-01-26 00:55:29 +01:00
import { BashToolParser } from './bash-tool-parser.js' ;
2026-01-28 04:38:43 +01:00
import { BufferAccumulator } from './utils/buffer-accumulator.js' ;
2026-01-31 23:47:49 +01:00
import { LRUMap } from './utils/lru-map.js' ;
2026-01-29 10:55:49 +01:00
import {
ANSI_ESCAPE_PATTERN_FULL ,
TOKEN_PATTERN ,
MAX_SESSION_TOKENS ,
} from './utils/index.js' ;
2026-01-28 04:38:43 +01:00
import {
MAX_TERMINAL_BUFFER_SIZE ,
TRIM_TERMINAL_TO as TERMINAL_BUFFER_TRIM_SIZE ,
MAX_TEXT_OUTPUT_SIZE ,
TRIM_TEXT_TO as TEXT_OUTPUT_TRIM_SIZE ,
MAX_MESSAGES ,
MAX_LINE_BUFFER_SIZE ,
} from './config/buffer-limits.js' ;
2026-01-19 00:38:11 +01:00
export type { BackgroundTask } from './task-tracker.js' ;
2026-01-26 00:55:29 +01:00
export type { RalphTrackerState , RalphTodoItem , ActiveBashTool } from './types.js' ;
2026-01-21 05:34:45 +01:00
export { withTimeout };
2026-01-18 04:50:46 +01:00
2026-01-21 04:25:53 +01:00
/** Line buffer flush interval (100ms) - forces processing of partial lines */
2026-01-19 06:51:25 +01:00
const LINE_BUFFER_FLUSH_INTERVAL = 100 ;
2026-01-18 21:36:03 +01:00
2026-01-26 14:27:21 +01:00
// ============================================================================
// Timing Constants
// ============================================================================
2026-02-18 12:51:35 +01:00
/** Delay after mux session creation before sending commands (300ms) */
const MUX_STARTUP_DELAY_MS = 300 ;
2026-01-26 14:27:21 +01:00
/** Delay before declaring session idle after last output (2 seconds) */
const IDLE_DETECTION_DELAY_MS = 2000 ;
/** Delay for auto-compact/clear retry attempts (2 seconds) */
const AUTO_RETRY_DELAY_MS = 2000 ;
/** Delay for auto-compact/clear initial check (1 second) */
const AUTO_INITIAL_DELAY_MS = 1000 ;
/** Graceful shutdown delay when stopping session (100ms) */
const GRACEFUL_SHUTDOWN_DELAY_MS = 100 ;
2026-01-21 05:34:45 +01:00
2026-01-19 02:04:30 +01:00
// Filter out terminal focus escape sequences (focus in/out reports)
// ^[[I (focus in), ^[[O (focus out), and the enable/disable sequences
const FOCUS_ESCAPE_FILTER = /\x1b\[\?1004[hl]|\x1b\[[IO]/g ;
2026-01-26 10:42:04 +01:00
// Pattern to match Task tool invocations in terminal output
// Matches: "Explore(Description)", "Task(Description)", "Bash(Description)", etc.
// The prefix characters vary (●, ·, ✶, etc.) so we don't require them
// We look for the tool name followed by (description)
const TASK_TOOL_PATTERN = /\b(Explore|Task|Bash|Plan|general-purpose)\(([^)]+)\)/g ;
2026-01-19 11:48:02 +01:00
2026-01-30 11:30:51 +01:00
// Pre-compiled patterns for hot paths (avoid regex compilation per call)
/** Pattern to strip leading ANSI escapes and whitespace from terminal buffer */
const LEADING_ANSI_WHITESPACE_PATTERN = /^(\x1b\[\??[\d;]*[A-Za-z]|[\s\r\n])+/ ;
/** Pattern to match Ctrl+L (form feed) characters */
const CTRL_L_PATTERN = /\x0c/g ;
/** Pattern to split by newlines (CR or LF) */
const NEWLINE_SPLIT_PATTERN = /\r?\n/ ;
2026-02-12 18:26:16 +01:00
// Claude CLI PATH resolution — shared utility
import { getAugmentedPath } from './utils/claude-cli-resolver.js' ;
2026-01-24 17:43:31 +01:00
2026-01-21 05:34:45 +01:00
/**
* Wraps a promise with a timeout to prevent indefinite hangs.
* If the promise doesn't resolve within the timeout, rejects with TimeoutError.
*
* @param promise - The promise to wrap
* @param timeoutMs - Timeout in milliseconds
* @param operation - Description of the operation for error messages
* @returns Promise that resolves/rejects with the original result or timeout error
*/
function withTimeout < T >(
promise : Promise < T >,
timeoutMs : number ,
operation : string
) : Promise < T > {
let timeoutId : NodeJS.Timeout ;
const timeoutPromise = new Promise < never >(( _ , reject ) => {
timeoutId = setTimeout (() => {
reject ( new Error ( ` ${ operation } timed out after ${ timeoutMs } ms` ));
}, timeoutMs );
});
return Promise . race ([ promise , timeoutPromise ]). finally (() => {
clearTimeout ( timeoutId );
});
}
2026-01-21 04:25:53 +01:00
/**
* Represents a JSON message from Claude CLI's stream-json output format.
* Messages are newline-delimited JSON objects parsed from PTY output.
*/
2026-01-18 05:14:34 +01:00
export interface ClaudeMessage {
2026-01-21 04:25:53 +01:00
/** Message type indicating the role or purpose */
2026-01-18 05:14:34 +01:00
type : 'system' | 'assistant' | 'user' | 'result' ;
2026-01-21 04:25:53 +01:00
/** Optional subtype for further classification */
2026-01-18 05:14:34 +01:00
subtype? : string ;
2026-01-21 04:25:53 +01:00
/** Claude's internal session identifier */
2026-01-18 05:14:34 +01:00
session_id? : string ;
2026-01-21 04:25:53 +01:00
/** Message content with optional token usage */
2026-01-18 05:14:34 +01:00
message ?: {
content : Array < { type : string ; text? : string } > ;
usage ?: {
input_tokens : number ;
output_tokens : number ;
};
};
2026-01-21 04:25:53 +01:00
/** Final result text (on result messages) */
2026-01-18 05:14:34 +01:00
result? : string ;
2026-01-21 04:25:53 +01:00
/** Whether this message represents an error */
2026-01-18 05:14:34 +01:00
is_error? : boolean ;
2026-01-21 04:25:53 +01:00
/** Total cost in USD (on result messages) */
2026-01-18 05:14:34 +01:00
total_cost_usd? : number ;
2026-01-21 04:25:53 +01:00
/** Total duration in milliseconds (on result messages) */
2026-01-18 05:14:34 +01:00
duration_ms? : number ;
}
2026-01-21 04:25:53 +01:00
/**
* Event signatures emitted by the Session class.
* Subscribe using `session.on('eventName', handler)`.
*/
2026-01-18 04:50:46 +01:00
export interface SessionEvents {
2026-01-21 04:25:53 +01:00
/** Processed text output (ANSI stripped) */
2026-01-18 04:50:46 +01:00
output : ( data : string ) => void ;
2026-01-21 04:25:53 +01:00
/** Parsed JSON message from Claude CLI */
2026-01-18 05:14:34 +01:00
message : ( msg : ClaudeMessage ) => void ;
2026-01-21 04:25:53 +01:00
/** Error output from the session */
2026-01-18 04:50:46 +01:00
error : ( data : string ) => void ;
2026-01-21 04:25:53 +01:00
/** Session process exited */
2026-01-18 04:50:46 +01:00
exit : ( code : number | null ) => void ;
2026-01-21 04:25:53 +01:00
/** One-shot prompt completed with result and cost */
2026-01-18 05:14:34 +01:00
completion : ( result : string , cost : number ) => void ;
2026-01-21 04:25:53 +01:00
/** Raw terminal data (includes ANSI codes) */
terminal : ( data : string ) => void ;
2026-02-18 12:51:35 +01:00
/** Signal to clear terminal display (after mux attach) */
2026-01-21 04:25:53 +01:00
clearTerminal : () => void ;
/** New background task started */
2026-01-19 00:38:11 +01:00
taskCreated : ( task : BackgroundTask ) => void ;
2026-01-21 04:25:53 +01:00
/** Background task status changed */
2026-01-19 00:38:11 +01:00
taskUpdated : ( task : BackgroundTask ) => void ;
2026-01-21 04:25:53 +01:00
/** Background task finished successfully */
2026-01-19 00:38:11 +01:00
taskCompleted : ( task : BackgroundTask ) => void ;
2026-01-21 04:25:53 +01:00
/** Background task failed with error */
2026-01-19 00:38:11 +01:00
taskFailed : ( task : BackgroundTask , error : string ) => void ;
2026-01-21 04:25:53 +01:00
/** Auto-clear triggered due to token threshold */
2026-01-19 00:38:11 +01:00
autoClear : ( data : { tokens : number ; threshold : number }) => void ;
2026-01-21 04:25:53 +01:00
/** Auto-compact triggered due to token threshold */
2026-01-19 13:08:53 +01:00
autoCompact : ( data : { tokens : number ; threshold : number ; prompt? : string }) => void ;
2026-01-21 22:36:45 +01:00
/** Ralph loop state changed */
ralphLoopUpdate : ( state : RalphTrackerState ) => void ;
/** Ralph todo list updated */
ralphTodoUpdate : ( todos : RalphTodoItem []) => void ;
/** Ralph completion phrase detected */
ralphCompletionDetected : ( phrase : string ) => void ;
2026-01-27 00:29:38 +01:00
/** RALPH_STATUS block detected */
ralphStatusBlockDetected : ( block : import ( './types.js' ). RalphStatusBlock ) => void ;
/** Circuit breaker state changed */
ralphCircuitBreakerUpdate : ( status : import ( './types.js' ). CircuitBreakerStatus ) => void ;
/** Dual-condition exit gate met */
ralphExitGateMet : ( data : { completionIndicators : number ; exitSignal : boolean }) => void ;
2026-01-26 00:55:29 +01:00
/** Bash tool with file paths started */
bashToolStart : ( tool : ActiveBashTool ) => void ;
/** Bash tool completed */
bashToolEnd : ( tool : ActiveBashTool ) => void ;
/** Active Bash tools list updated */
bashToolsUpdate : ( tools : ActiveBashTool []) => void ;
2026-02-19 08:49:36 +01:00
/** CLI info (version, model, account) updated */
cliInfoUpdated : ( info : { version : string | null ; model : string | null ; accountType : string | null ; latestVersion : string | null }) => void ;
2026-01-18 04:50:46 +01:00
}
2026-01-21 04:25:53 +01:00
/**
* Session operation mode.
* - `'claude'`: Runs Claude CLI for AI interactions (default)
* - `'shell'`: Runs a plain bash shell for debugging/testing
*/
2026-01-19 01:26:38 +01:00
export type SessionMode = 'claude' | 'shell' ;
2026-01-21 04:25:53 +01:00
/**
* Core session class that wraps a PTY process running Claude CLI or a shell.
*
* @example
* ```typescript
* // Create and start an interactive Claude session
* const session = new Session({
* workingDir: '/path/to/project',
2026-02-18 12:51:35 +01:00
* mux: muxManager,
* useMux: true
2026-01-21 04:25:53 +01:00
* });
* await session.startInteractive();
*
* // Listen for events
* session.on('terminal', (data) => console.log(data));
* session.on('message', (msg) => console.log('Claude:', msg));
*
* // Send input
* session.write('Hello Claude!\r');
*
* // Stop when done
* await session.stop();
* ```
*
* @fires Session#terminal - Raw terminal output
* @fires Session#message - Parsed Claude JSON message
* @fires Session#completion - One-shot prompt completed
* @fires Session#exit - Process exited
* @fires Session#autoClear - Token threshold reached, clearing context
* @fires Session#autoCompact - Token threshold reached, compacting context
*/
2026-01-18 04:50:46 +01:00
export class Session extends EventEmitter {
readonly id : string ;
readonly workingDir : string ;
readonly createdAt : number ;
2026-01-19 01:26:38 +01:00
readonly mode : SessionMode ;
2026-01-18 04:50:46 +01:00
2026-01-31 23:47:49 +01:00
/** Maximum number of task descriptions to keep (LRUMap handles size limit automatically) */
private static readonly MAX_TASK_DESCRIPTIONS = 100 ;
private static readonly TASK_DESCRIPTION_MAX_AGE_MS = 30000 ; // Keep descriptions for 30 seconds
2026-01-19 01:26:38 +01:00
private _name : string ;
2026-01-18 21:36:03 +01:00
private ptyProcess : pty.IPty | null = null ;
private _pid : number | null = null ;
2026-01-18 04:50:46 +01:00
private _status : SessionStatus = 'idle' ;
private _currentTaskId : string | null = null ;
2026-01-21 04:55:48 +01:00
// Use BufferAccumulator for hot-path buffers to reduce GC pressure
private _terminalBuffer = new BufferAccumulator ( MAX_TERMINAL_BUFFER_SIZE , TERMINAL_BUFFER_TRIM_SIZE );
private _textOutput = new BufferAccumulator ( MAX_TEXT_OUTPUT_SIZE , TEXT_OUTPUT_TRIM_SIZE );
2026-01-18 04:50:46 +01:00
private _errorBuffer : string = '' ;
private _lastActivityAt : number ;
2026-01-18 05:14:34 +01:00
private _claudeSessionId : string | null = null ;
private _totalCost : number = 0 ;
private _messages : ClaudeMessage [] = [];
private _lineBuffer : string = '' ;
2026-01-19 06:51:25 +01:00
private _lineBufferFlushTimer : NodeJS.Timeout | null = null ;
2026-01-18 21:36:03 +01:00
private resolvePromise : (( value : { result : string ; cost : number }) => void ) | null = null ;
private rejectPromise : (( reason : Error ) => void ) | null = null ;
2026-01-21 05:47:17 +01:00
private _promptResolved : boolean = false ; // Guard against race conditions in runPrompt
2026-01-18 21:36:03 +01:00
private _isWorking : boolean = false ;
private _lastPromptTime : number = 0 ;
private activityTimeout : NodeJS.Timeout | null = null ;
2026-01-28 05:34:25 +01:00
private _awaitingIdleConfirmation : boolean = false ; // Prevents timeout reset during idle detection
2026-01-19 00:38:11 +01:00
private _taskTracker : TaskTracker ;
// Token tracking for auto-clear
private _totalInputTokens : number = 0 ;
private _totalOutputTokens : number = 0 ;
2026-01-19 13:08:53 +01:00
private _autoClearThreshold : number = 140000 ; // Default 140k tokens
2026-01-19 00:38:11 +01:00
private _autoClearEnabled : boolean = false ;
private _isClearing : boolean = false ; // Prevent recursive clearing
2026-01-18 04:50:46 +01:00
2026-01-19 13:08:53 +01:00
// Auto-compact settings
private _autoCompactThreshold : number = 110000 ; // Default 110k tokens (lower than clear)
private _autoCompactEnabled : boolean = false ;
private _autoCompactPrompt : string = '' ; // Optional prompt for compact
private _isCompacting : boolean = false ; // Prevent recursive compacting
2026-01-28 07:18:45 +01:00
// Image watcher setting (per-session toggle)
2026-02-17 16:47:54 +01:00
private _imageWatcherEnabled : boolean = false ;
2026-01-28 07:18:45 +01:00
2026-01-30 17:50:02 +01:00
// Flicker filter setting (per-session toggle, applied on frontend)
private _flickerFilterEnabled : boolean = false ;
2026-01-31 04:44:46 +01:00
// Claude Code CLI info (parsed from terminal startup)
private _cliVersion : string = '' ;
private _cliModel : string = '' ;
private _cliAccountType : string = '' ;
private _cliLatestVersion : string = '' ;
private _cliInfoParsed : boolean = false ; // Only parse once per session
2026-01-21 09:54:42 +01:00
// Timer tracking for cleanup (prevents memory leaks)
private _autoCompactTimer : NodeJS.Timeout | null = null ;
private _autoClearTimer : NodeJS.Timeout | null = null ;
private _promptCheckInterval : NodeJS.Timeout | null = null ;
private _promptCheckTimeout : NodeJS.Timeout | null = null ;
private _shellIdleTimer : NodeJS.Timeout | null = null ;
2026-02-18 12:51:35 +01:00
// Multiplexer session support (tmux)
2026-02-12 10:29:57 +01:00
private _mux : TerminalMultiplexer | null = null ;
private _muxSession : MuxSession | null = null ;
private _useMux : boolean = false ;
2026-01-22 00:08:32 +01:00
// Flag to prevent new timers after session is stopped
private _isStopped : boolean = false ;
2026-01-19 03:40:57 +01:00
2026-01-21 22:36:45 +01:00
// Ralph tracking (Ralph Wiggum loops and todo lists inside Claude Code)
private _ralphTracker : RalphTracker ;
2026-01-19 13:21:01 +01:00
2026-01-23 10:20:37 +01:00
// Agent tree tracking
private _parentAgentId : string | null = null ;
private _childAgentIds : string [] = [];
2026-01-27 11:43:20 +01:00
// Nice prioritying configuration
private _niceConfig : NiceConfig = { ... DEFAULT_NICE_CONFIG };
2026-01-27 01:58:02 +01:00
2026-02-18 23:14:39 +01:00
// Claude model override (e.g., 'opus', 'sonnet', 'haiku')
private _model : string | undefined ;
2026-01-30 13:25:18 +01:00
// Session color for visual differentiation
private _color : import ( './types.js' ). SessionColor = 'default' ;
2026-01-21 05:50:09 +01:00
// Store handler references for cleanup (prevents memory leaks)
private _taskTrackerHandlers : {
taskCreated : ( task : BackgroundTask ) => void ;
taskUpdated : ( task : BackgroundTask ) => void ;
taskCompleted : ( task : BackgroundTask ) => void ;
taskFailed : ( task : BackgroundTask , error : string ) => void ;
} | null = null ;
2026-01-21 22:36:45 +01:00
private _ralphHandlers : {
loopUpdate : ( state : RalphTrackerState ) => void ;
todoUpdate : ( todos : RalphTodoItem []) => void ;
2026-01-21 05:50:09 +01:00
completionDetected : ( phrase : string ) => void ;
2026-01-27 00:29:38 +01:00
statusBlockDetected : ( block : import ( './types.js' ). RalphStatusBlock ) => void ;
circuitBreakerUpdate : ( status : import ( './types.js' ). CircuitBreakerStatus ) => void ;
exitGateMet : ( data : { completionIndicators : number ; exitSignal : boolean }) => void ;
2026-01-21 05:50:09 +01:00
} | null = null ;
2026-01-26 00:55:29 +01:00
// Bash tool tracking (file paths for live log viewing)
private _bashToolParser : BashToolParser ;
private _bashToolHandlers : {
toolStart : ( tool : ActiveBashTool ) => void ;
toolEnd : ( tool : ActiveBashTool ) => void ;
toolsUpdate : ( tools : ActiveBashTool []) => void ;
} | null = null ;
2026-01-26 10:42:04 +01:00
// Task descriptions parsed from terminal output (e.g., "Explore(Description)")
// Used to correlate with SubagentWatcher discoveries for better window titles
2026-01-31 23:47:49 +01:00
// Uses LRUMap for automatic eviction at MAX_TASK_DESCRIPTIONS limit
private _recentTaskDescriptions : LRUMap < number , string > = new LRUMap ({ maxSize : Session.MAX_TASK_DESCRIPTIONS });
2026-01-26 10:42:04 +01:00
2026-01-19 03:40:57 +01:00
constructor ( config : Partial < SessionConfig > & {
workingDir : string ;
mode? : SessionMode ;
name? : string ;
2026-02-18 12:51:35 +01:00
/** Terminal multiplexer instance (tmux) */
2026-02-12 10:29:57 +01:00
mux? : TerminalMultiplexer ;
/** Whether to use multiplexer wrapping */
useMux? : boolean ;
/** Existing mux session for restored sessions */
muxSession? : MuxSession ;
2026-01-27 11:43:20 +01:00
niceConfig? : NiceConfig ; // Nice prioritying configuration
2026-02-18 23:14:39 +01:00
/** Claude model override (e.g., 'opus', 'sonnet', 'haiku') */
model? : string ;
2026-01-19 03:40:57 +01:00
}) {
2026-01-18 04:50:46 +01:00
super ();
2026-02-15 05:33:34 +01:00
this . setMaxListeners ( 25 );
2026-02-12 14:41:27 +01:00
// Default error handler prevents unhandled 'error' events from crashing the process.
// Server attaches its own handler after construction — this is a safety net for the gap.
this . on ( 'error' , ( err ) => {
console . error ( `[Session] Unhandled error event:` , err );
});
2026-01-18 04:50:46 +01:00
this . id = config . id || uuidv4 ();
this . workingDir = config . workingDir ;
this . createdAt = config . createdAt || Date . now ();
2026-01-19 01:26:38 +01:00
this . mode = config . mode || 'claude' ;
this . _name = config . name || '' ;
2026-01-18 04:50:46 +01:00
this . _lastActivityAt = this . createdAt ;
2026-02-13 05:07:51 +01:00
// Set claudeSessionId immediately — Claudeman always passes --session-id ${this.id}
// to Claude CLI, so the Claude session ID always matches the Claudeman session ID.
// This ensures subagent matching works even for recovered sessions (where
// startInteractive() hasn't been called yet).
this . _claudeSessionId = this . id ;
2026-02-18 12:51:35 +01:00
this . _mux = config . mux || null ;
this . _useMux = config . useMux ?? ( this . _mux !== null && this . _mux . isAvailable ());
this . _muxSession = config . muxSession || null ;
2026-01-19 00:38:11 +01:00
2026-01-27 11:43:20 +01:00
// Apply Nice priority configuration if provided
if ( config . niceConfig ) {
this . _niceConfig = { ... config . niceConfig };
2026-01-27 01:58:02 +01:00
}
2026-02-18 23:14:39 +01:00
// Apply model override if provided
if ( config . model ) {
this . _model = config . model ;
}
2026-01-21 05:50:09 +01:00
// Initialize task tracker and forward events (store handlers for cleanup)
2026-01-19 00:38:11 +01:00
this . _taskTracker = new TaskTracker ();
2026-01-21 05:50:09 +01:00
this . _taskTrackerHandlers = {
taskCreated : ( task ) => this . emit ( 'taskCreated' , task ),
taskUpdated : ( task ) => this . emit ( 'taskUpdated' , task ),
taskCompleted : ( task ) => this . emit ( 'taskCompleted' , task ),
taskFailed : ( task , error ) => this . emit ( 'taskFailed' , task , error ),
};
this . _taskTracker . on ( 'taskCreated' , this . _taskTrackerHandlers . taskCreated );
this . _taskTracker . on ( 'taskUpdated' , this . _taskTrackerHandlers . taskUpdated );
this . _taskTracker . on ( 'taskCompleted' , this . _taskTrackerHandlers . taskCompleted );
this . _taskTracker . on ( 'taskFailed' , this . _taskTrackerHandlers . taskFailed );
2026-01-19 13:21:01 +01:00
2026-01-21 22:36:45 +01:00
// Initialize Ralph tracker and forward events (store handlers for cleanup)
this . _ralphTracker = new RalphTracker ();
this . _ralphHandlers = {
loopUpdate : ( state ) => this . emit ( 'ralphLoopUpdate' , state ),
todoUpdate : ( todos ) => this . emit ( 'ralphTodoUpdate' , todos ),
completionDetected : ( phrase ) => this . emit ( 'ralphCompletionDetected' , phrase ),
2026-01-27 00:29:38 +01:00
statusBlockDetected : ( block ) => this . emit ( 'ralphStatusBlockDetected' , block ),
circuitBreakerUpdate : ( status ) => this . emit ( 'ralphCircuitBreakerUpdate' , status ),
exitGateMet : ( data ) => this . emit ( 'ralphExitGateMet' , data ),
2026-01-21 05:50:09 +01:00
};
2026-01-21 22:36:45 +01:00
this . _ralphTracker . on ( 'loopUpdate' , this . _ralphHandlers . loopUpdate );
this . _ralphTracker . on ( 'todoUpdate' , this . _ralphHandlers . todoUpdate );
this . _ralphTracker . on ( 'completionDetected' , this . _ralphHandlers . completionDetected );
2026-01-27 00:29:38 +01:00
this . _ralphTracker . on ( 'statusBlockDetected' , this . _ralphHandlers . statusBlockDetected );
this . _ralphTracker . on ( 'circuitBreakerUpdate' , this . _ralphHandlers . circuitBreakerUpdate );
this . _ralphTracker . on ( 'exitGateMet' , this . _ralphHandlers . exitGateMet );
2026-01-23 10:20:37 +01:00
2026-01-26 00:55:29 +01:00
// Initialize Bash tool parser and forward events (store handlers for cleanup)
2026-01-26 04:35:50 +01:00
this . _bashToolParser = new BashToolParser ({ sessionId : this.id , workingDir : this.workingDir });
2026-01-26 00:55:29 +01:00
this . _bashToolHandlers = {
toolStart : ( tool ) => this . emit ( 'bashToolStart' , tool ),
toolEnd : ( tool ) => this . emit ( 'bashToolEnd' , tool ),
toolsUpdate : ( tools ) => this . emit ( 'bashToolsUpdate' , tools ),
};
this . _bashToolParser . on ( 'toolStart' , this . _bashToolHandlers . toolStart );
this . _bashToolParser . on ( 'toolEnd' , this . _bashToolHandlers . toolEnd );
this . _bashToolParser . on ( 'toolsUpdate' , this . _bashToolHandlers . toolsUpdate );
2026-01-18 04:50:46 +01:00
}
get status () : SessionStatus {
return this . _status ;
}
get currentTaskId () : string | null {
return this . _currentTaskId ;
}
get pid () : number | null {
2026-01-18 21:36:03 +01:00
return this . _pid ;
}
get terminalBuffer () : string {
2026-01-21 04:55:48 +01:00
return this . _terminalBuffer . value ;
2026-01-18 04:50:46 +01:00
}
2026-01-18 05:14:34 +01:00
get textOutput () : string {
2026-01-21 04:55:48 +01:00
return this . _textOutput . value ;
2026-01-18 05:14:34 +01:00
}
2026-01-18 04:50:46 +01:00
get errorBuffer () : string {
return this . _errorBuffer ;
}
get lastActivityAt () : number {
return this . _lastActivityAt ;
}
2026-01-18 05:14:34 +01:00
get claudeSessionId () : string | null {
return this . _claudeSessionId ;
}
get totalCost () : number {
return this . _totalCost ;
}
get messages () : ClaudeMessage [] {
return this . _messages ;
}
2026-01-18 21:36:03 +01:00
get isWorking () : boolean {
return this . _isWorking ;
}
get lastPromptTime () : number {
return this . _lastPromptTime ;
}
2026-01-19 00:38:11 +01:00
get taskTracker () : TaskTracker {
return this . _taskTracker ;
}
get runningTaskCount () : number {
return this . _taskTracker . getRunningCount ();
}
get taskTree () : BackgroundTask [] {
return this . _taskTracker . getTaskTree ();
}
get taskStats () : { total : number ; running : number ; completed : number ; failed : number } {
return this . _taskTracker . getStats ();
}
2026-01-21 22:36:45 +01:00
// Ralph tracking getters
get ralphTracker () : RalphTracker {
return this . _ralphTracker ;
2026-01-19 13:21:01 +01:00
}
2026-01-21 22:36:45 +01:00
get ralphLoopState () : RalphTrackerState {
return this . _ralphTracker . loopState ;
2026-01-19 13:21:01 +01:00
}
2026-01-21 22:36:45 +01:00
get ralphTodos () : RalphTodoItem [] {
return this . _ralphTracker . todos ;
2026-01-19 13:21:01 +01:00
}
2026-01-21 22:36:45 +01:00
get ralphTodoStats () : { total : number ; pending : number ; inProgress : number ; completed : number } {
return this . _ralphTracker . getTodoStats ();
2026-01-19 13:21:01 +01:00
}
2026-01-26 00:55:29 +01:00
// Bash tool tracking getters
get bashToolParser () : BashToolParser {
return this . _bashToolParser ;
}
get activeTools () : ActiveBashTool [] {
return this . _bashToolParser . activeTools ;
}
2026-01-23 10:20:37 +01:00
get parentAgentId () : string | null {
return this . _parentAgentId ;
}
set parentAgentId ( value : string | null ) {
this . _parentAgentId = value ;
}
get childAgentIds () : string [] {
return [... this . _childAgentIds ];
}
addChildAgentId ( agentId : string ) : void {
if ( ! this . _childAgentIds . includes ( agentId )) {
this . _childAgentIds . push ( agentId );
}
}
removeChildAgentId ( agentId : string ) : void {
const idx = this . _childAgentIds . indexOf ( agentId );
if ( idx >= 0 ) this . _childAgentIds . splice ( idx , 1 );
}
2026-01-27 11:43:20 +01:00
// Nice priority config getters and setters
get niceConfig () : NiceConfig {
return { ... this . _niceConfig };
2026-01-27 01:58:02 +01:00
}
/**
2026-01-27 11:43:20 +01:00
* Set CPU priority configuration.
* Note: This only affects new sessions; existing running processes won't be changed.
2026-01-27 01:58:02 +01:00
*/
2026-01-27 11:43:20 +01:00
setNice ( config : Partial < NiceConfig >) : void {
2026-01-27 01:58:02 +01:00
if ( config . enabled !== undefined ) {
2026-01-27 11:43:20 +01:00
this . _niceConfig . enabled = config . enabled ;
2026-01-27 01:58:02 +01:00
}
if ( config . niceValue !== undefined ) {
// Clamp to valid range
2026-01-27 11:43:20 +01:00
this . _niceConfig . niceValue = Math . max ( - 20 , Math . min ( 19 , config . niceValue ));
2026-01-27 01:58:02 +01:00
}
}
2026-01-30 13:25:18 +01:00
// Session color for visual differentiation
get color () : import ( './types.js' ). SessionColor {
return this . _color ;
}
setColor ( color : import ( './types.js' ). SessionColor ) : void {
const validColors = [ 'default' , 'red' , 'orange' , 'yellow' , 'green' , 'blue' , 'purple' , 'pink' ];
if ( validColors . includes ( color )) {
this . _color = color ;
}
}
2026-01-19 00:38:11 +01:00
// Token tracking getters and setters
get totalTokens () : number {
return this . _totalInputTokens + this . _totalOutputTokens ;
}
get inputTokens () : number {
return this . _totalInputTokens ;
}
get outputTokens () : number {
return this . _totalOutputTokens ;
}
2026-01-25 07:26:49 +01:00
/**
* Restore token and cost values from saved state.
* Called when recovering sessions after server restart.
*/
restoreTokens ( inputTokens : number , outputTokens : number , totalCost : number ) : void {
2026-01-31 23:47:49 +01:00
// Sanity check: reject absurdly large individual values
2026-01-26 12:22:05 +01:00
if ( inputTokens > MAX_SESSION_TOKENS || outputTokens > MAX_SESSION_TOKENS ) {
console . warn ( `[Session ${ this . id } ] Rejected absurd restored tokens: input= ${ inputTokens } , output= ${ outputTokens } ` );
return ;
}
2026-01-31 23:47:49 +01:00
// Check token sum doesn't overflow MAX_SESSION_TOKENS
if ( inputTokens + outputTokens > MAX_SESSION_TOKENS ) {
console . warn ( `[Session ${ this . id } ] Rejected token sum overflow: input= ${ inputTokens } + output= ${ outputTokens } = ${ inputTokens + outputTokens } > ${ MAX_SESSION_TOKENS } ` );
return ;
}
2026-01-26 12:22:05 +01:00
// Reject negative values
if ( inputTokens < 0 || outputTokens < 0 || totalCost < 0 ) {
console . warn ( `[Session ${ this . id } ] Rejected negative restored tokens: input= ${ inputTokens } , output= ${ outputTokens } , cost= ${ totalCost } ` );
return ;
}
2026-01-25 07:26:49 +01:00
this . _totalInputTokens = inputTokens ;
this . _totalOutputTokens = outputTokens ;
this . _totalCost = totalCost ;
}
2026-01-19 00:38:11 +01:00
get autoClearThreshold () : number {
return this . _autoClearThreshold ;
}
get autoClearEnabled () : boolean {
return this . _autoClearEnabled ;
}
2026-01-19 01:26:38 +01:00
get name () : string {
return this . _name ;
}
set name ( value : string ) {
this . _name = value ;
}
2026-01-31 23:47:49 +01:00
/** Minimum valid threshold for auto-clear/compact (1000 tokens) */
private static readonly MIN_AUTO_THRESHOLD = 1000 ;
/** Maximum valid threshold for auto-clear/compact (500k tokens) */
private static readonly MAX_AUTO_THRESHOLD = 500 _000 ;
/** Default auto-clear threshold when invalid value provided */
private static readonly DEFAULT_AUTO_CLEAR_THRESHOLD = 140 _000 ;
/** Default auto-compact threshold when invalid value provided */
private static readonly DEFAULT_AUTO_COMPACT_THRESHOLD = 110 _000 ;
2026-01-19 00:38:11 +01:00
setAutoClear ( enabled : boolean , threshold? : number ) : void {
this . _autoClearEnabled = enabled ;
if ( threshold !== undefined ) {
2026-01-31 23:47:49 +01:00
// Validate threshold bounds
if ( threshold < Session . MIN_AUTO_THRESHOLD || threshold > Session . MAX_AUTO_THRESHOLD ) {
console . warn ( `[Session ${ this . id } ] Invalid autoClear threshold ${ threshold } , must be between ${ Session . MIN_AUTO_THRESHOLD } and ${ Session . MAX_AUTO_THRESHOLD } . Using default ${ Session . DEFAULT_AUTO_CLEAR_THRESHOLD } .` );
this . _autoClearThreshold = Session . DEFAULT_AUTO_CLEAR_THRESHOLD ;
} else {
this . _autoClearThreshold = threshold ;
}
2026-01-19 00:38:11 +01:00
}
}
2026-01-19 13:08:53 +01:00
get autoCompactThreshold () : number {
return this . _autoCompactThreshold ;
}
get autoCompactEnabled () : boolean {
return this . _autoCompactEnabled ;
}
get autoCompactPrompt () : string {
return this . _autoCompactPrompt ;
}
setAutoCompact ( enabled : boolean , threshold? : number , prompt? : string ) : void {
this . _autoCompactEnabled = enabled ;
if ( threshold !== undefined ) {
2026-01-31 23:47:49 +01:00
// Validate threshold bounds
if ( threshold < Session . MIN_AUTO_THRESHOLD || threshold > Session . MAX_AUTO_THRESHOLD ) {
console . warn ( `[Session ${ this . id } ] Invalid autoCompact threshold ${ threshold } , must be between ${ Session . MIN_AUTO_THRESHOLD } and ${ Session . MAX_AUTO_THRESHOLD } . Using default ${ Session . DEFAULT_AUTO_COMPACT_THRESHOLD } .` );
this . _autoCompactThreshold = Session . DEFAULT_AUTO_COMPACT_THRESHOLD ;
} else {
this . _autoCompactThreshold = threshold ;
}
2026-01-19 13:08:53 +01:00
}
if ( prompt !== undefined ) {
this . _autoCompactPrompt = prompt ;
}
}
2026-01-28 07:18:45 +01:00
get imageWatcherEnabled () : boolean {
return this . _imageWatcherEnabled ;
}
set imageWatcherEnabled ( enabled : boolean ) {
this . _imageWatcherEnabled = enabled ;
}
2026-01-30 17:50:02 +01:00
get flickerFilterEnabled () : boolean {
return this . _flickerFilterEnabled ;
}
set flickerFilterEnabled ( enabled : boolean ) {
this . _flickerFilterEnabled = enabled ;
}
2026-01-18 04:50:46 +01:00
isIdle () : boolean {
return this . _status === 'idle' ;
}
isBusy () : boolean {
return this . _status === 'busy' ;
}
isRunning () : boolean {
return this . _status === 'idle' || this . _status === 'busy' ;
}
toState () : SessionState {
return {
id : this.id ,
pid : this.pid ,
status : this._status ,
workingDir : this.workingDir ,
currentTaskId : this._currentTaskId ,
createdAt : this.createdAt ,
lastActivityAt : this._lastActivityAt ,
2026-01-22 20:36:06 +01:00
name : this._name ,
mode : this.mode ,
autoClearEnabled : this._autoClearEnabled ,
autoClearThreshold : this._autoClearThreshold ,
autoCompactEnabled : this._autoCompactEnabled ,
autoCompactThreshold : this._autoCompactThreshold ,
autoCompactPrompt : this._autoCompactPrompt ,
2026-01-28 07:18:45 +01:00
imageWatcherEnabled : this._imageWatcherEnabled ,
2026-01-22 20:36:06 +01:00
totalCost : this._totalCost ,
inputTokens : this._totalInputTokens ,
outputTokens : this._totalOutputTokens ,
ralphEnabled : this._ralphTracker.enabled ,
2026-01-30 17:20:53 +01:00
ralphAutoEnableDisabled : this._ralphTracker.autoEnableDisabled || undefined ,
2026-01-22 20:36:06 +01:00
ralphCompletionPhrase : this._ralphTracker.loopState.completionPhrase || undefined ,
2026-01-23 10:20:37 +01:00
parentAgentId : this._parentAgentId || undefined ,
childAgentIds : this._childAgentIds.length > 0 ? this . _childAgentIds : undefined ,
2026-01-27 11:43:20 +01:00
niceEnabled : this._niceConfig.enabled ,
niceValue : this._niceConfig.niceValue ,
2026-01-30 13:25:18 +01:00
color : this._color ,
2026-01-30 17:50:02 +01:00
flickerFilterEnabled : this._flickerFilterEnabled ,
2026-01-31 04:44:46 +01:00
cliVersion : this._cliVersion || undefined ,
cliModel : this._cliModel || undefined ,
cliAccountType : this._cliAccountType || undefined ,
cliLatestVersion : this._cliLatestVersion || undefined ,
2026-01-18 04:50:46 +01:00
};
}
2026-01-18 05:14:34 +01:00
toDetailedState() {
2026-02-13 21:07:49 +01:00
return {
... this . toLightDetailedState (),
textOutput : this._textOutput.value ,
terminalBuffer : this._terminalBuffer.value ,
};
}
/**
* Lightweight detailed state that excludes heavy buffers (textOutput, terminalBuffer).
* Use for SSE session:updated broadcasts where buffers aren't needed.
* Full buffers are fetched on-demand via /api/sessions/:id/terminal.
*/
toLightDetailedState() {
2026-01-18 05:14:34 +01:00
return {
... this . toState (),
2026-01-19 01:26:38 +01:00
name : this._name ,
mode : this.mode ,
2026-01-18 05:14:34 +01:00
claudeSessionId : this._claudeSessionId ,
totalCost : this._totalCost ,
messageCount : this._messages.length ,
2026-01-18 21:36:03 +01:00
isWorking : this._isWorking ,
lastPromptTime : this._lastPromptTime ,
// Buffer statistics for monitoring long-running sessions
bufferStats : {
terminalBufferSize : this._terminalBuffer.length ,
textOutputSize : this._textOutput.length ,
messageCount : this._messages.length ,
maxTerminalBuffer : MAX_TERMINAL_BUFFER_SIZE ,
maxTextOutput : MAX_TEXT_OUTPUT_SIZE ,
maxMessages : MAX_MESSAGES ,
},
2026-01-19 00:38:11 +01:00
// Background task tracking
taskStats : this._taskTracker.getStats (),
taskTree : this._taskTracker.getTaskTree (),
// Token tracking
tokens : {
input : this._totalInputTokens ,
output : this._totalOutputTokens ,
total : this._totalInputTokens + this . _totalOutputTokens ,
},
autoClear : {
enabled : this._autoClearEnabled ,
threshold : this._autoClearThreshold ,
},
2026-01-27 11:43:20 +01:00
// CPU priority configuration
nice : {
enabled : this._niceConfig.enabled ,
niceValue : this._niceConfig.niceValue ,
2026-01-27 01:58:02 +01:00
},
2026-01-21 22:36:45 +01:00
// Ralph tracking state
ralphLoop : this._ralphTracker.loopState ,
ralphTodos : this._ralphTracker.todos ,
ralphTodoStats : this._ralphTracker.getTodoStats (),
2026-01-18 05:14:34 +01:00
};
}
2026-01-21 04:25:53 +01:00
/**
* Starts an interactive Claude CLI session with full terminal support.
*
* This spawns Claude CLI with `--dangerously-skip-permissions` flag in
2026-02-18 12:51:35 +01:00
* interactive mode. If mux wrapping is enabled, the session runs inside
* a tmux session for persistence across disconnects.
2026-01-21 04:25:53 +01:00
*
* @throws {Error} If a process is already running in this session
*
* @example
* ```typescript
2026-02-18 12:51:35 +01:00
* const session = new Session({ workingDir: '/project', useMux: true });
2026-01-21 04:25:53 +01:00
* await session.startInteractive();
* session.on('terminal', (data) => process.stdout.write(data));
* session.write('help me with this code\r');
* ```
*/
2026-01-18 21:36:03 +01:00
async startInteractive () : Promise < void > {
if ( this . ptyProcess ) {
throw new Error ( 'Session already has a running process' );
}
this . _status = 'busy' ;
2026-01-21 04:55:48 +01:00
this . _terminalBuffer . clear ();
this . _textOutput . clear ();
2026-01-18 21:36:03 +01:00
this . _errorBuffer = '' ;
this . _messages = [];
this . _lineBuffer = '' ;
this . _lastActivityAt = Date . now ();
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Starting interactive Claude session' + ( this . _useMux ? ` (with ${ this . _mux ! . backend } )` : '' ));
2026-01-18 21:36:03 +01:00
2026-02-12 10:29:57 +01:00
// If mux wrapping is enabled, create or attach to a mux session
if ( this . _useMux && this . _mux ) {
2026-01-19 03:40:57 +01:00
try {
2026-02-19 22:37:45 +01:00
// Verify stale mux session — tmux may have been destroyed (e.g., killed externally)
2026-02-19 21:38:01 +01:00
if ( this . _muxSession && ! this . _mux . muxSessionExists ( this . _muxSession . muxName )) {
console . log ( '[Session] Stale mux session detected (tmux gone):' , this . _muxSession . muxName );
this . _muxSession = null ;
}
2026-02-19 22:37:45 +01:00
// Check if session exists but pane is dead (remain-on-exit keeps it alive)
// Respawn the pane instead of creating a whole new session — preserves tmux scrollback
let needsNewSession = false ;
if ( this . _muxSession && this . _mux . isPaneDead ( this . _muxSession . muxName )) {
console . log ( '[Session] Dead pane detected, respawning:' , this . _muxSession . muxName );
const newPid = await this . _mux . respawnPane ( this . id , this . workingDir , 'claude' , this . _niceConfig , this . _model );
if ( ! newPid ) {
console . error ( '[Session] Failed to respawn pane, will create new session' );
needsNewSession = true ;
} else {
// Wait a moment for the respawned process to fully start
await new Promise ( resolve => setTimeout ( resolve , MUX_STARTUP_DELAY_MS ));
}
}
2026-02-12 10:29:57 +01:00
// Check if we already have a mux session (restored session)
2026-02-19 22:37:45 +01:00
const isRestoredSession = this . _muxSession !== null && ! needsNewSession ;
2026-01-19 19:56:28 +01:00
if ( isRestoredSession ) {
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Attaching to existing mux session:' , this . _muxSession ! . muxName );
2026-01-19 19:56:28 +01:00
} else {
2026-02-12 10:29:57 +01:00
// Create a new mux session
2026-02-18 23:14:39 +01:00
this . _muxSession = await this . _mux . createSession ( this . id , this . workingDir , 'claude' , this . _name , this . _niceConfig , this . _model );
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Created mux session:' , this . _muxSession . muxName );
2026-01-19 03:40:57 +01:00
2026-02-12 10:29:57 +01:00
// Wait a moment for mux to fully start
2026-02-18 12:51:35 +01:00
await new Promise ( resolve => setTimeout ( resolve , MUX_STARTUP_DELAY_MS ));
2026-01-19 19:56:28 +01:00
}
2026-01-19 03:40:57 +01:00
2026-02-12 10:29:57 +01:00
// Attach to the mux session via PTY
2026-01-27 20:24:00 +01:00
try {
2026-02-12 10:29:57 +01:00
this . ptyProcess = pty . spawn (
this . _mux . getAttachCommand (),
this . _mux . getAttachArgs ( this . _muxSession ! . muxName ),
{
2026-01-27 20:24:00 +01:00
name : 'xterm-256color' ,
cols : 120 ,
rows : 40 ,
cwd : this.workingDir ,
2026-02-18 07:28:15 +01:00
env : { ... process . env , TERM : 'xterm-256color' , COLORTERM : undefined , CLAUDECODE : undefined },
2026-01-27 20:24:00 +01:00
});
2026-01-29 14:56:11 +01:00
// Set claudeSessionId immediately since we passed --session-id to Claude
2026-02-12 10:29:57 +01:00
// The mux manager passes --session-id ${sessionId} to Claude
2026-01-29 14:56:11 +01:00
this . _claudeSessionId = this . id ;
2026-01-27 20:24:00 +01:00
} catch ( spawnErr ) {
2026-02-18 12:51:35 +01:00
console . error ( '[Session] Failed to spawn PTY for mux attachment:' , spawnErr );
this . emit ( 'error' , `Failed to attach to mux session: ${ spawnErr } ` );
2026-01-27 20:24:00 +01:00
throw spawnErr ;
}
2026-01-19 07:33:33 +01:00
2026-02-18 12:51:35 +01:00
// For NEW mux sessions: wait for prompt to appear then clean buffer
// For RESTORED mux sessions: don't do anything - client will fetch buffer on tab switch
2026-01-19 19:56:28 +01:00
if ( ! isRestoredSession ) {
2026-01-21 09:54:42 +01:00
this . _promptCheckInterval = setInterval (() => {
2026-01-20 20:56:25 +01:00
// Wait for the prompt character (❯ ) which means Claude is fully initialized
2026-01-21 04:55:48 +01:00
const bufferValue = this . _terminalBuffer . value ;
if ( bufferValue . includes ( '❯ ' ) || bufferValue . includes ( '\u276f' )) {
2026-01-21 09:54:42 +01:00
if ( this . _promptCheckInterval ) {
clearInterval ( this . _promptCheckInterval );
this . _promptCheckInterval = null ;
}
if ( this . _promptCheckTimeout ) {
clearTimeout ( this . _promptCheckTimeout );
this . _promptCheckTimeout = null ;
}
2026-02-18 12:51:35 +01:00
// Clean the buffer - remove mux init junk before actual content
2026-01-20 20:56:25 +01:00
// Strip: cursor movement (\x1b[nA/B/C/D), positioning (\x1b[n;nH),
// clear screen (\x1b[2J), scroll region (\x1b[n;nr), and whitespace
2026-01-21 04:55:48 +01:00
this . _terminalBuffer . set (
2026-01-30 11:30:51 +01:00
bufferValue . replace ( LEADING_ANSI_WHITESPACE_PATTERN , '' )
2026-01-21 04:55:48 +01:00
);
2026-01-20 20:56:25 +01:00
// Signal client to refresh
this . emit ( 'clearTerminal' );
}
}, 50 );
// Timeout after 5 seconds if prompt not found
2026-01-21 09:54:42 +01:00
this . _promptCheckTimeout = setTimeout (() => {
if ( this . _promptCheckInterval ) {
clearInterval ( this . _promptCheckInterval );
this . _promptCheckInterval = null ;
}
this . _promptCheckTimeout = null ;
}, 5000 );
2026-01-19 19:56:28 +01:00
}
2026-01-19 03:40:57 +01:00
} catch ( err ) {
2026-02-12 10:29:57 +01:00
console . error ( '[Session] Failed to create mux session, falling back to direct PTY:' , err );
this . _useMux = false ;
this . _muxSession = null ;
2026-01-19 03:40:57 +01:00
}
}
2026-02-12 10:29:57 +01:00
// Fallback to direct PTY if mux is not used
2026-01-19 03:40:57 +01:00
if ( ! this . ptyProcess ) {
2026-01-27 20:24:00 +01:00
try {
2026-01-29 14:56:11 +01:00
// Pass --session-id to use the SAME ID as the Claudeman session
// This ensures subagents can be directly matched to the correct tab
2026-02-18 23:14:39 +01:00
const args = [ '--dangerously-skip-permissions' , '--session-id' , this . id ];
if ( this . _model ) args . push ( '--model' , this . _model );
this . ptyProcess = pty . spawn ( 'claude' , args , {
2026-01-27 20:24:00 +01:00
name : 'xterm-256color' ,
cols : 120 ,
rows : 40 ,
cwd : this.workingDir ,
env : {
... process . env ,
PATH : getAugmentedPath (),
TERM : 'xterm-256color' ,
2026-02-18 07:28:15 +01:00
COLORTERM : undefined ,
CLAUDECODE : undefined ,
2026-01-27 20:24:00 +01:00
// Inform Claude it's running within Claudeman (helps prevent self-termination)
2026-02-18 12:51:35 +01:00
CLAUDEMAN_MUX : '1' ,
2026-01-27 20:24:00 +01:00
CLAUDEMAN_SESSION_ID : this.id ,
CLAUDEMAN_API_URL : process.env.CLAUDEMAN_API_URL || 'http://localhost:3000' ,
},
});
} catch ( spawnErr ) {
console . error ( '[Session] Failed to spawn Claude PTY:' , spawnErr );
this . _status = 'stopped' ;
this . emit ( 'error' , `Failed to start Claude: ${ spawnErr } ` );
throw new Error ( `Failed to spawn Claude process: ${ spawnErr } ` );
}
2026-01-19 03:40:57 +01:00
}
2026-01-18 21:36:03 +01:00
2026-01-29 14:56:11 +01:00
// Set the claudeSessionId immediately since we passed --session-id
// This ensures subagent matching works without waiting for JSON messages
this . _claudeSessionId = this . id ;
2026-01-18 21:36:03 +01:00
this . _pid = this . ptyProcess . pid ;
console . log ( '[Session] Interactive PTY spawned with PID:' , this . _pid );
2026-01-19 02:04:30 +01:00
this . ptyProcess . onData (( rawData : string ) => {
2026-01-20 20:56:25 +01:00
// Filter out focus escape sequences and Ctrl+L (form feed)
const data = rawData
. replace ( FOCUS_ESCAPE_FILTER , '' )
2026-01-30 11:30:51 +01:00
. replace ( CTRL_L_PATTERN , '' ); // Remove Ctrl+L
2026-01-20 20:56:25 +01:00
if ( ! data ) return ; // Skip if only filtered sequences
2026-01-20 19:02:31 +01:00
2026-02-13 05:07:51 +01:00
// Lazy ANSI strip: only compute cleanData when a consumer actually needs it.
// During active streaming, many consumers early-exit (ralph disabled, cli info parsed,
// no 'token' in data, etc.), so we skip the expensive O(n) regex on most chunks.
let _cleanData : string | null = null ;
const getCleanData = () : string => {
if ( _cleanData === null ) {
_cleanData = data . replace ( ANSI_ESCAPE_PATTERN_FULL , '' );
}
return _cleanData ;
};
2026-02-04 07:24:32 +01:00
2026-01-21 04:55:48 +01:00
// BufferAccumulator handles auto-trimming when max size exceeded
this . _terminalBuffer . append ( data );
2026-01-18 21:36:03 +01:00
this . _lastActivityAt = Date . now ();
this . emit ( 'terminal' , data );
this . emit ( 'output' , data );
2026-02-13 05:07:51 +01:00
// Forward to Ralph tracker to detect Ralph loops and todos
// Ralph tracker early-exits when disabled + autoEnableDisabled, skipping ANSI strip
if ( this . _ralphTracker . enabled || ! this . _ralphTracker . autoEnableDisabled ) {
this . _ralphTracker . processCleanData ( getCleanData ());
}
2026-01-19 13:21:01 +01:00
2026-02-13 05:07:51 +01:00
// Forward to Bash tool parser to detect file-viewing commands
// Parser early-exits when disabled, skipping ANSI strip
if ( this . _bashToolParser . enabled ) {
this . _bashToolParser . processCleanData ( getCleanData ());
}
2026-01-26 00:55:29 +01:00
2026-01-19 04:42:13 +01:00
// Parse token count from status line (e.g., "123.4k tokens" or "5234 tokens")
2026-02-13 05:07:51 +01:00
// Pre-check on raw data: 'token' won't appear in ANSI sequences
if ( data . includes ( 'token' )) {
this . parseTokensFromStatusLine ( getCleanData ());
}
2026-01-19 04:42:13 +01:00
2026-01-31 04:44:46 +01:00
// Parse Claude Code CLI info (version, model, account type) from startup
2026-02-13 05:07:51 +01:00
// Gated by _cliInfoParsed — only runs during first few chunks
if ( ! this . _cliInfoParsed ) {
this . parseClaudeCodeInfo ( getCleanData ());
}
2026-01-31 04:44:46 +01:00
2026-01-26 10:42:04 +01:00
// Parse task descriptions from terminal output (e.g., "Explore(Check files)")
2026-02-13 05:07:51 +01:00
// Pre-check on raw data: parentheses are safe to check without ANSI strip
if ( data . includes ( '(' ) && data . includes ( ')' )) {
this . parseTaskDescriptionsFromTerminalData ( getCleanData ());
}
2026-01-26 10:42:04 +01:00
2026-01-18 21:36:03 +01:00
// Detect if Claude is working or at prompt
// The prompt line contains "❯ " when waiting for input
if ( data . includes ( '❯ ' ) || data . includes ( '\u276f' )) {
2026-01-28 05:34:25 +01:00
// Only start a new timeout if we're not already awaiting idle confirmation
// This prevents status bar redraws (which include ❯ ) from resetting the timer
if ( ! this . _awaitingIdleConfirmation ) {
if ( this . activityTimeout ) clearTimeout ( this . activityTimeout );
this . _awaitingIdleConfirmation = true ;
this . activityTimeout = setTimeout (() => {
this . _awaitingIdleConfirmation = false ;
// Emit idle if either:
// 1. Claude was working and is now at prompt (normal case)
// 2. Session just started and is ready (status is 'busy' but _isWorking is false)
const wasWorking = this . _isWorking ;
const isInitialReady = this . _status === 'busy' && ! this . _isWorking ;
if ( wasWorking || isInitialReady ) {
this . _isWorking = false ;
this . _status = 'idle' ;
this . _lastPromptTime = Date . now ();
this . emit ( 'idle' );
}
}, IDLE_DETECTION_DELAY_MS );
}
2026-01-18 21:36:03 +01:00
}
// Detect when Claude starts working (thinking, writing, etc)
2026-02-13 05:07:51 +01:00
// Fast path: check spinner characters on raw data (Unicode, never in ANSI sequences)
const hasSpinner = data . includes ( '⠋' ) || data . includes ( '⠙' ) ||
data . includes ( '⠹' ) || data . includes ( '⠸' ) ||
data . includes ( '⠼' ) || data . includes ( '⠴' ) ||
data . includes ( '⠦' ) || data . includes ( '⠧' );
// Slow path: check text keywords on clean data (avoids false positives from window titles)
const hasWorkKeyword = hasSpinner ||
getCleanData (). includes ( 'Thinking' ) || getCleanData (). includes ( 'Writing' ) ||
getCleanData (). includes ( 'Reading' ) || getCleanData (). includes ( 'Running' );
if ( hasWorkKeyword ) {
2026-01-18 21:36:03 +01:00
if ( ! this . _isWorking ) {
this . _isWorking = true ;
2026-01-27 11:02:02 +01:00
this . _status = 'busy' ;
2026-01-18 21:36:03 +01:00
this . emit ( 'working' );
}
2026-01-28 05:34:25 +01:00
// Reset timeout and idle confirmation flag since Claude is active
this . _awaitingIdleConfirmation = false ;
2026-01-18 21:36:03 +01:00
if ( this . activityTimeout ) clearTimeout ( this . activityTimeout );
}
});
this . ptyProcess . onExit (({ exitCode }) => {
console . log ( '[Session] Interactive PTY exited with code:' , exitCode );
this . ptyProcess = null ;
this . _pid = null ;
this . _status = 'idle' ;
2026-01-28 05:34:25 +01:00
this . _awaitingIdleConfirmation = false ;
2026-01-21 09:54:42 +01:00
// Clear all timers to prevent memory leaks
if ( this . activityTimeout ) {
clearTimeout ( this . activityTimeout );
this . activityTimeout = null ;
}
if ( this . _promptCheckInterval ) {
clearInterval ( this . _promptCheckInterval );
this . _promptCheckInterval = null ;
}
if ( this . _promptCheckTimeout ) {
clearTimeout ( this . _promptCheckTimeout );
this . _promptCheckTimeout = null ;
}
2026-02-12 10:29:57 +01:00
// If using mux, mark the session as detached but don't kill it
if ( this . _muxSession && this . _mux ) {
this . _mux . setAttached ( this . id , false );
2026-01-19 03:40:57 +01:00
}
2026-01-18 21:36:03 +01:00
this . emit ( 'exit' , exitCode );
});
}
2026-01-21 04:25:53 +01:00
/**
* Starts a plain shell session (bash/zsh) without Claude CLI.
*
* Useful for debugging, testing, or when you just need a terminal.
* Uses the user's default shell from $SHELL or falls back to /bin/bash.
*
* @throws {Error} If a process is already running in this session
*
* @example
* ```typescript
* const session = new Session({ workingDir: '/project', mode: 'shell' });
* await session.startShell();
* session.write('ls -la\r');
* ```
*/
2026-01-19 01:26:38 +01:00
async startShell () : Promise < void > {
if ( this . ptyProcess ) {
throw new Error ( 'Session already has a running process' );
}
this . _status = 'busy' ;
2026-01-21 04:55:48 +01:00
this . _terminalBuffer . clear ();
this . _textOutput . clear ();
2026-01-19 01:26:38 +01:00
this . _errorBuffer = '' ;
this . _messages = [];
this . _lineBuffer = '' ;
this . _lastActivityAt = Date . now ();
// Use user's default shell or bash
const shell = process . env . SHELL || '/bin/bash' ;
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Starting shell session with:' , shell + ( this . _useMux ? ` (with ${ this . _mux ! . backend } )` : '' ));
2026-01-19 01:26:38 +01:00
2026-02-12 10:29:57 +01:00
// If mux wrapping is enabled, create or attach to a mux session
if ( this . _useMux && this . _mux ) {
2026-01-19 03:40:57 +01:00
try {
2026-02-19 22:37:45 +01:00
// Verify stale mux session — tmux may have been destroyed externally
2026-02-19 21:38:01 +01:00
if ( this . _muxSession && ! this . _mux . muxSessionExists ( this . _muxSession . muxName )) {
console . log ( '[Session] Stale mux session detected (tmux gone):' , this . _muxSession . muxName );
this . _muxSession = null ;
}
2026-02-19 22:37:45 +01:00
// Check if session exists but pane is dead (remain-on-exit keeps it alive)
let needsNewSession = false ;
if ( this . _muxSession && this . _mux . isPaneDead ( this . _muxSession . muxName )) {
console . log ( '[Session] Dead pane detected, respawning:' , this . _muxSession . muxName );
const newPid = await this . _mux . respawnPane ( this . id , this . workingDir , 'shell' , this . _niceConfig );
if ( ! newPid ) {
console . error ( '[Session] Failed to respawn pane, will create new session' );
needsNewSession = true ;
} else {
await new Promise ( resolve => setTimeout ( resolve , MUX_STARTUP_DELAY_MS ));
}
}
2026-02-12 10:29:57 +01:00
// Check if we already have a mux session (restored session)
2026-02-19 22:37:45 +01:00
const isRestoredSession = this . _muxSession !== null && ! needsNewSession ;
2026-01-19 19:56:28 +01:00
if ( isRestoredSession ) {
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Attaching to existing mux session:' , this . _muxSession ! . muxName );
2026-01-19 19:56:28 +01:00
} else {
2026-02-12 10:29:57 +01:00
// Create a new mux session
this . _muxSession = await this . _mux . createSession ( this . id , this . workingDir , 'shell' , this . _name , this . _niceConfig );
console . log ( '[Session] Created mux session:' , this . _muxSession . muxName );
2026-01-19 03:40:57 +01:00
2026-02-12 10:29:57 +01:00
// Wait a moment for mux to fully start
2026-02-18 12:51:35 +01:00
await new Promise ( resolve => setTimeout ( resolve , MUX_STARTUP_DELAY_MS ));
2026-01-19 19:56:28 +01:00
}
2026-01-19 03:40:57 +01:00
2026-02-12 10:29:57 +01:00
// Attach to the mux session via PTY
2026-01-27 20:24:00 +01:00
try {
2026-02-12 10:29:57 +01:00
this . ptyProcess = pty . spawn (
this . _mux . getAttachCommand (),
this . _mux . getAttachArgs ( this . _muxSession ! . muxName ),
{
2026-01-27 20:24:00 +01:00
name : 'xterm-256color' ,
cols : 120 ,
rows : 40 ,
cwd : this.workingDir ,
2026-02-18 07:28:15 +01:00
env : { ... process . env , TERM : 'xterm-256color' , COLORTERM : undefined , CLAUDECODE : undefined },
2026-01-27 20:24:00 +01:00
});
} catch ( spawnErr ) {
2026-02-12 10:29:57 +01:00
console . error ( '[Session] Failed to spawn PTY for shell mux attachment:' , spawnErr );
this . emit ( 'error' , `Failed to attach to mux session: ${ spawnErr } ` );
2026-01-27 20:24:00 +01:00
throw spawnErr ;
}
2026-01-19 07:33:33 +01:00
2026-02-12 10:29:57 +01:00
// For NEW sessions: clear by sending 'clear' command to the shell
// For RESTORED sessions: don't clear - we want to see the existing output
2026-01-19 19:56:28 +01:00
if ( ! isRestoredSession ) {
setTimeout (() => {
if ( this . ptyProcess ) {
2026-01-21 04:55:48 +01:00
this . _terminalBuffer . clear ();
2026-01-19 19:56:28 +01:00
this . ptyProcess . write ( 'clear\n' );
}
}, 100 );
}
2026-01-19 03:40:57 +01:00
} catch ( err ) {
2026-02-12 10:29:57 +01:00
console . error ( '[Session] Failed to create mux session, falling back to direct PTY:' , err );
this . _useMux = false ;
this . _muxSession = null ;
2026-01-19 03:40:57 +01:00
}
}
2026-02-12 10:29:57 +01:00
// Fallback to direct PTY if mux is not used
2026-01-19 03:40:57 +01:00
if ( ! this . ptyProcess ) {
2026-01-27 20:24:00 +01:00
try {
this . ptyProcess = pty . spawn ( shell , [], {
name : 'xterm-256color' ,
cols : 120 ,
rows : 40 ,
cwd : this.workingDir ,
env : {
... process . env ,
TERM : 'xterm-256color' ,
2026-02-18 12:51:35 +01:00
CLAUDEMAN_MUX : '1' ,
2026-01-27 20:24:00 +01:00
CLAUDEMAN_SESSION_ID : this.id ,
CLAUDEMAN_API_URL : process.env.CLAUDEMAN_API_URL || 'http://localhost:3000' ,
},
});
} catch ( spawnErr ) {
console . error ( '[Session] Failed to spawn shell PTY:' , spawnErr );
this . _status = 'stopped' ;
this . emit ( 'error' , `Failed to start shell: ${ spawnErr } ` );
throw new Error ( `Failed to spawn shell process: ${ spawnErr } ` );
}
2026-01-19 03:40:57 +01:00
}
2026-01-19 01:26:38 +01:00
this . _pid = this . ptyProcess . pid ;
console . log ( '[Session] Shell PTY spawned with PID:' , this . _pid );
2026-01-19 02:04:30 +01:00
this . ptyProcess . onData (( rawData : string ) => {
// Filter out focus escape sequences
const data = rawData . replace ( FOCUS_ESCAPE_FILTER , '' );
if ( ! data ) return ; // Skip if only focus sequences
2026-01-21 04:55:48 +01:00
// BufferAccumulator handles auto-trimming when max size exceeded
this . _terminalBuffer . append ( data );
2026-01-19 01:26:38 +01:00
this . _lastActivityAt = Date . now ();
this . emit ( 'terminal' , data );
this . emit ( 'output' , data );
});
this . ptyProcess . onExit (({ exitCode }) => {
console . log ( '[Session] Shell PTY exited with code:' , exitCode );
this . ptyProcess = null ;
this . _pid = null ;
this . _status = 'idle' ;
2026-01-21 09:54:42 +01:00
// Clear timers to prevent memory leaks
if ( this . _shellIdleTimer ) {
clearTimeout ( this . _shellIdleTimer );
this . _shellIdleTimer = null ;
}
if ( this . activityTimeout ) {
clearTimeout ( this . activityTimeout );
this . activityTimeout = null ;
}
2026-02-12 10:29:57 +01:00
// If using mux, mark the session as detached but don't kill it
if ( this . _muxSession && this . _mux ) {
this . _mux . setAttached ( this . id , false );
2026-01-19 03:40:57 +01:00
}
2026-01-19 01:26:38 +01:00
this . emit ( 'exit' , exitCode );
});
// Mark as idle after a short delay (shell is ready)
2026-01-21 09:54:42 +01:00
this . _shellIdleTimer = setTimeout (() => {
this . _shellIdleTimer = null ;
2026-01-19 01:26:38 +01:00
this . _status = 'idle' ;
this . _isWorking = false ;
this . emit ( 'idle' );
}, 500 );
}
2026-01-21 04:25:53 +01:00
/**
* Runs a one-shot prompt and returns the result.
*
* This spawns Claude CLI with `--output-format stream-json` to get
* structured JSON output. The promise resolves when Claude completes
* the response.
*
* @param prompt - The prompt text to send to Claude
2026-01-27 02:38:37 +01:00
* @param options - Optional configuration
* @param options.model - Model to use ('opus', 'sonnet', or full model name). Defaults to default model.
* @param options.onProgress - Callback for progress updates (token count, status)
2026-01-21 04:25:53 +01:00
* @returns Promise resolving to the result text and total cost in USD
* @throws {Error} If a process is already running in this session
*
* @example
* ```typescript
* const session = new Session({ workingDir: '/project' });
2026-01-27 02:38:37 +01:00
* const { result, cost } = await session.runPrompt('Explain this code', { model: 'opus' });
2026-01-21 04:25:53 +01:00
* console.log(`Response: ${result}`);
* console.log(`Cost: $${cost.toFixed(4)}`);
* ```
*/
2026-01-27 02:38:37 +01:00
async runPrompt (
prompt : string ,
options ?: { model? : string ; onProgress ?: ( info : { tokens? : number ; status? : string }) => void }
) : Promise < { result : string ; cost : number } > {
2026-01-18 04:50:46 +01:00
return new Promise (( resolve , reject ) => {
2026-01-18 21:36:03 +01:00
if ( this . ptyProcess ) {
2026-01-18 05:14:34 +01:00
reject ( new Error ( 'Session already has a running process' ));
2026-01-18 04:50:46 +01:00
return ;
}
2026-01-18 05:14:34 +01:00
this . _status = 'busy' ;
2026-01-21 04:55:48 +01:00
this . _terminalBuffer . clear ();
this . _textOutput . clear ();
2026-01-18 05:14:34 +01:00
this . _errorBuffer = '' ;
this . _messages = [];
this . _lineBuffer = '' ;
this . _lastActivityAt = Date . now ();
2026-01-21 05:47:17 +01:00
this . _promptResolved = false ; // Reset race condition guard
2026-01-18 05:14:34 +01:00
2026-01-18 21:36:03 +01:00
this . resolvePromise = resolve ;
this . rejectPromise = reject ;
2026-01-18 04:50:46 +01:00
try {
2026-01-18 21:36:03 +01:00
// Spawn claude in a real PTY
2026-01-27 02:38:37 +01:00
const model = options ? . model ;
console . log ( '[Session] Spawning PTY for claude with prompt:' , prompt . substring ( 0 , 50 ), model ? `(model: ${ model } )` : '' );
2026-01-18 21:36:03 +01:00
2026-01-27 02:38:37 +01:00
const args = [
2026-01-18 05:14:34 +01:00
'-p' ,
2026-02-18 07:28:15 +01:00
'--verbose' ,
2026-01-18 21:36:03 +01:00
'--dangerously-skip-permissions' ,
2026-01-19 04:42:13 +01:00
'--output-format' , 'stream-json' ,
2026-01-27 02:38:37 +01:00
];
if ( model ) {
args . push ( '--model' , model );
}
args . push ( prompt );
2026-01-27 20:24:00 +01:00
try {
this . ptyProcess = pty . spawn ( 'claude' , args , {
name : 'xterm-256color' ,
cols : 120 ,
rows : 40 ,
cwd : this.workingDir ,
env : {
... process . env ,
PATH : getAugmentedPath (),
TERM : 'xterm-256color' ,
2026-02-18 07:28:15 +01:00
COLORTERM : undefined ,
CLAUDECODE : undefined ,
2026-01-27 20:24:00 +01:00
// Inform Claude it's running within Claudeman
2026-02-18 12:51:35 +01:00
CLAUDEMAN_MUX : '1' ,
2026-01-27 20:24:00 +01:00
CLAUDEMAN_SESSION_ID : this.id ,
CLAUDEMAN_API_URL : process.env.CLAUDEMAN_API_URL || 'http://localhost:3000' ,
},
});
} catch ( spawnErr ) {
console . error ( '[Session] Failed to spawn Claude PTY for runPrompt:' , spawnErr );
this . emit ( 'error' , `Failed to spawn Claude: ${ spawnErr instanceof Error ? spawnErr.message : String ( spawnErr ) } ` );
throw spawnErr ;
}
2026-01-18 04:50:46 +01:00
2026-01-18 21:36:03 +01:00
this . _pid = this . ptyProcess . pid ;
console . log ( '[Session] PTY spawned with PID:' , this . _pid );
// Handle terminal data
2026-01-19 02:04:30 +01:00
this . ptyProcess . onData (( rawData : string ) => {
// Filter out focus escape sequences
const data = rawData . replace ( FOCUS_ESCAPE_FILTER , '' );
if ( ! data ) return ; // Skip if only focus sequences
2026-01-21 04:55:48 +01:00
// BufferAccumulator handles auto-trimming when max size exceeded
this . _terminalBuffer . append ( data );
2026-01-18 04:50:46 +01:00
this . _lastActivityAt = Date . now ();
2026-01-18 21:36:03 +01:00
this . emit ( 'terminal' , data );
this . emit ( 'output' , data );
// Also try to parse JSON lines for structured data
this . processOutput ( data );
2026-01-18 04:50:46 +01:00
});
2026-01-18 21:36:03 +01:00
// Handle exit
this . ptyProcess . onExit (({ exitCode }) => {
console . log ( '[Session] PTY exited with code:' , exitCode );
this . ptyProcess = null ;
this . _pid = null ;
2026-01-18 04:50:46 +01:00
2026-01-21 05:47:17 +01:00
// Guard against race conditions: only process once per runPrompt call
if ( this . _promptResolved ) {
this . emit ( 'exit' , exitCode );
return ;
}
this . _promptResolved = true ;
// Capture callbacks atomically before processing
const resolve = this . resolvePromise ;
const reject = this . rejectPromise ;
this . resolvePromise = null ;
this . rejectPromise = null ;
2026-01-18 21:36:03 +01:00
// Find result from parsed messages or use text output
2026-01-18 05:14:34 +01:00
const resultMsg = this . _messages . find ( m => m . type === 'result' );
if ( resultMsg && ! resultMsg . is_error ) {
this . _status = 'idle' ;
const cost = resultMsg . total_cost_usd || 0 ;
this . _totalCost += cost ;
this . emit ( 'completion' , resultMsg . result || '' , cost );
2026-01-21 05:47:17 +01:00
if ( resolve ) {
resolve ({ result : resultMsg.result || '' , cost });
2026-01-18 21:36:03 +01:00
}
} else if ( exitCode !== 0 || ( resultMsg && resultMsg . is_error )) {
2026-01-18 05:14:34 +01:00
this . _status = 'error' ;
2026-01-21 05:47:17 +01:00
if ( reject ) {
reject ( new Error ( this . _errorBuffer || this . _textOutput . value || 'Process exited with error' ));
2026-01-18 21:36:03 +01:00
}
2026-01-18 05:14:34 +01:00
} else {
this . _status = 'idle' ;
2026-01-21 05:47:17 +01:00
if ( resolve ) {
resolve ({ result : this._textOutput.value || this . _terminalBuffer . value , cost : this._totalCost });
2026-01-18 21:36:03 +01:00
}
2026-01-18 05:14:34 +01:00
}
2026-01-18 21:36:03 +01:00
this . emit ( 'exit' , exitCode );
2026-01-18 04:50:46 +01:00
});
2026-01-18 21:36:03 +01:00
2026-01-18 04:50:46 +01:00
} catch ( err ) {
this . _status = 'error' ;
reject ( err );
2026-01-30 13:25:18 +01:00
// Null callbacks to prevent memory leak (onExit won't run if spawn failed)
this . resolvePromise = null ;
this . rejectPromise = null ;
2026-01-18 04:50:46 +01:00
}
});
}
2026-01-18 21:36:03 +01:00
private processOutput ( data : string ) : void {
2026-01-26 13:58:34 +01:00
// Early return if session is stopped to prevent any processing or timer creation
if ( this . _isStopped ) return ;
2026-01-18 21:36:03 +01:00
// Try to extract JSON from output (Claude may output JSON in stream mode)
this . _lineBuffer += data ;
2026-01-19 06:51:25 +01:00
// Prevent unbounded line buffer growth for very long lines
if ( this . _lineBuffer . length > MAX_LINE_BUFFER_SIZE ) {
// Force flush the oversized buffer as text output
2026-01-21 04:55:48 +01:00
this . _textOutput . append ( this . _lineBuffer + '\n' );
2026-01-19 06:51:25 +01:00
this . _lineBuffer = '' ;
}
// Start flush timer if not running (handles partial lines after 100ms)
2026-01-22 00:08:32 +01:00
if ( ! this . _lineBufferFlushTimer && this . _lineBuffer . length > 0 && ! this . _isStopped ) {
2026-01-19 06:51:25 +01:00
this . _lineBufferFlushTimer = setTimeout (() => {
this . _lineBufferFlushTimer = null ;
2026-01-22 00:08:32 +01:00
if ( this . _lineBuffer . length > 0 && ! this . _isStopped ) {
2026-01-19 06:51:25 +01:00
// Flush partial line as text output
2026-01-21 04:55:48 +01:00
this . _textOutput . append ( this . _lineBuffer );
2026-01-19 06:51:25 +01:00
this . _lineBuffer = '' ;
}
}, LINE_BUFFER_FLUSH_INTERVAL );
}
2026-01-18 05:14:34 +01:00
const lines = this . _lineBuffer . split ( '\n' );
this . _lineBuffer = lines . pop () || '' ;
2026-01-19 06:51:25 +01:00
// Clear flush timer if buffer is now empty
if ( this . _lineBuffer . length === 0 && this . _lineBufferFlushTimer ) {
clearTimeout ( this . _lineBufferFlushTimer );
this . _lineBufferFlushTimer = null ;
}
2026-01-18 05:14:34 +01:00
for ( const line of lines ) {
2026-01-18 21:36:03 +01:00
const trimmed = line . trim ();
2026-01-19 11:48:02 +01:00
// Remove ANSI escape codes for JSON parsing (use pre-compiled pattern)
2026-01-29 10:55:49 +01:00
const cleanLine = trimmed . replace ( ANSI_ESCAPE_PATTERN_FULL , '' );
2026-01-18 21:36:03 +01:00
if ( cleanLine . startsWith ( '{' ) && cleanLine . endsWith ( '}' )) {
2026-01-18 05:14:34 +01:00
try {
2026-01-18 21:36:03 +01:00
const msg = JSON . parse ( cleanLine ) as ClaudeMessage ;
2026-01-18 05:14:34 +01:00
this . _messages . push ( msg );
this . emit ( 'message' , msg );
2026-01-18 21:36:03 +01:00
// Trim messages array for long-running sessions
if ( this . _messages . length > MAX_MESSAGES ) {
this . _messages = this . _messages . slice ( - Math . floor ( MAX_MESSAGES * 0.8 ));
}
2026-01-29 14:56:11 +01:00
// Extract Claude session ID from messages (can be in any message type)
// Support both sessionId (camelCase) and session_id (snake_case)
const msgSessionId = ( msg as unknown as Record < string , unknown >). sessionId as string | undefined
?? msg . session_id ;
if ( msgSessionId && ! this . _claudeSessionId ) {
this . _claudeSessionId = msgSessionId ;
2026-01-18 05:14:34 +01:00
}
2026-01-19 00:38:11 +01:00
// Process message for task tracking
this . _taskTracker . processMessage ( msg );
2026-01-18 05:14:34 +01:00
if ( msg . type === 'assistant' && msg . message ? . content ) {
for ( const block of msg . message . content ) {
if ( block . type === 'text' && block . text ) {
2026-01-21 04:55:48 +01:00
this . _textOutput . append ( block . text );
2026-01-18 05:14:34 +01:00
}
}
2026-01-26 12:22:05 +01:00
// Track tokens from usage (with validation)
2026-01-19 00:38:11 +01:00
if ( msg . message . usage ) {
2026-01-26 12:22:05 +01:00
const inputDelta = msg . message . usage . input_tokens || 0 ;
const outputDelta = msg . message . usage . output_tokens || 0 ;
// Sanity check: max 100k tokens per message (generous limit)
const MAX_TOKENS_PER_MESSAGE = 100 _000 ;
if ( inputDelta > 0 && inputDelta <= MAX_TOKENS_PER_MESSAGE ) {
this . _totalInputTokens += inputDelta ;
}
if ( outputDelta > 0 && outputDelta <= MAX_TOKENS_PER_MESSAGE ) {
this . _totalOutputTokens += outputDelta ;
}
2026-01-19 00:38:11 +01:00
2026-01-19 13:08:53 +01:00
// Check if we should auto-compact or auto-clear
this . checkAutoCompact ();
2026-01-19 00:38:11 +01:00
this . checkAutoClear ();
}
2026-01-18 05:14:34 +01:00
}
2026-01-18 21:36:03 +01:00
if ( msg . type === 'result' && msg . total_cost_usd ) {
this . _totalCost = msg . total_cost_usd ;
2026-01-18 05:14:34 +01:00
}
2026-01-30 19:05:46 +01:00
} catch ( parseErr ) {
// Not JSON, just regular output - this is expected for non-JSON lines
console . debug ( '[Session] Line not JSON (expected for text output):' , parseErr instanceof Error ? parseErr.message : parseErr );
2026-01-21 04:55:48 +01:00
this . _textOutput . append ( line + '\n' );
2026-01-18 05:14:34 +01:00
}
2026-01-18 21:36:03 +01:00
} else if ( trimmed ) {
2026-01-21 04:55:48 +01:00
this . _textOutput . append ( line + '\n' );
2026-01-18 05:14:34 +01:00
}
2026-01-26 10:42:04 +01:00
// Parse task descriptions from terminal output (e.g., "Explore(Description)")
// This captures the short description from Claude Code's Task tool output
2026-02-12 18:26:16 +01:00
// Use direct method since cleanLine is already ANSI-stripped (line 1460)
this . parseTaskDescriptionsDirect ( cleanLine );
2026-01-18 05:14:34 +01:00
}
2026-01-21 04:55:48 +01:00
// Note: BufferAccumulator auto-trims when max size exceeded
2026-01-18 21:36:03 +01:00
}
2026-01-26 10:42:04 +01:00
/**
2026-02-04 07:24:32 +01:00
* Parse task descriptions from terminal data (may contain multiple lines).
* Called from interactive mode's onData handler with ANSI-stripped data.
* @param cleanData - Terminal data with ANSI codes already stripped
2026-01-26 10:42:04 +01:00
*/
2026-02-04 07:24:32 +01:00
private parseTaskDescriptionsFromTerminalData ( cleanData : string ) : void {
2026-01-26 10:42:04 +01:00
// Quick pre-check: skip if no parentheses present
2026-02-04 07:24:32 +01:00
if ( ! cleanData . includes ( '(' ) || ! cleanData . includes ( ')' )) return ;
2026-01-26 10:42:04 +01:00
2026-02-04 07:24:32 +01:00
// Split by newlines and process each line (data already ANSI-stripped)
const lines = cleanData . split ( NEWLINE_SPLIT_PATTERN );
2026-01-26 10:42:04 +01:00
for ( const line of lines ) {
2026-02-04 07:24:32 +01:00
this . parseTaskDescriptionsDirect ( line );
2026-01-26 10:42:04 +01:00
}
}
2026-02-04 07:24:32 +01:00
/**
* Parse task descriptions from a pre-cleaned line (no ANSI codes).
2026-02-12 18:26:16 +01:00
* Used by both processOutput() and parseTaskDescriptionsFromTerminalData().
2026-02-04 07:24:32 +01:00
*/
private parseTaskDescriptionsDirect ( cleanLine : string ) : void {
// Quick pre-check: skip expensive regex if no common tool patterns present
if ( ! cleanLine . includes ( '(' ) || ! cleanLine . includes ( ')' )) return ;
2026-01-26 10:42:04 +01:00
// Reset regex lastIndex for global pattern
TASK_TOOL_PATTERN . lastIndex = 0 ;
let match ;
while (( match = TASK_TOOL_PATTERN . exec ( cleanLine )) !== null ) {
const description = match [ 2 ]. trim ();
if ( description && description . length > 0 ) {
const now = Date . now ();
this . _recentTaskDescriptions . set ( now , description );
// Cleanup old entries
this . cleanupOldTaskDescriptions ();
}
}
}
/**
* Remove task descriptions older than TASK_DESCRIPTION_MAX_AGE_MS.
2026-01-31 23:47:49 +01:00
* Size limit is handled automatically by LRUMap eviction on set().
2026-01-26 10:42:04 +01:00
*/
private cleanupOldTaskDescriptions () : void {
const cutoff = Date . now () - Session . TASK_DESCRIPTION_MAX_AGE_MS ;
2026-01-31 23:47:49 +01:00
// Keys are timestamps - iterate and delete expired entries
// LRUMap maintains insertion order, so we can break early once we find a non-expired entry
for ( const timestamp of this . _recentTaskDescriptions . keysInOrder ()) {
2026-01-26 10:42:04 +01:00
if ( timestamp < cutoff ) {
2026-01-31 23:47:49 +01:00
this . _recentTaskDescriptions . delete ( timestamp );
} else {
// Keys are ordered by insertion time (which is the timestamp)
// Once we find a non-expired one, all subsequent are also non-expired
break ;
2026-01-26 13:58:34 +01:00
}
}
2026-01-26 10:42:04 +01:00
}
/**
* Get recent task descriptions parsed from terminal output.
* Returns descriptions sorted by timestamp (most recent first).
*/
getRecentTaskDescriptions () : Array < { timestamp : number ; description : string } > {
this . cleanupOldTaskDescriptions ();
const results : Array < { timestamp : number ; description : string } > = [];
for ( const [ timestamp , description ] of this . _recentTaskDescriptions ) {
results . push ({ timestamp , description });
}
return results . sort (( a , b ) => b . timestamp - a . timestamp );
}
/**
* Find a task description that was parsed close to a given timestamp.
* Used to correlate with SubagentWatcher discoveries.
*
* @param subagentStartTime - The timestamp when the subagent was discovered
* @param maxAgeMs - Maximum age difference to consider (default 10 seconds)
* @returns The matching description or undefined
*/
findTaskDescriptionNear ( subagentStartTime : number , maxAgeMs : number = 10000 ) : string | undefined {
this . cleanupOldTaskDescriptions ();
// Find the most recent description that was parsed before or around the subagent start time
let bestMatch : { timestamp : number ; description : string } | undefined ;
let bestDiff = Infinity ;
for ( const [ timestamp , description ] of this . _recentTaskDescriptions ) {
const diff = Math . abs ( subagentStartTime - timestamp );
if ( diff < maxAgeMs && diff < bestDiff ) {
bestMatch = { timestamp , description };
bestDiff = diff ;
}
}
return bestMatch ? . description ;
}
2026-01-19 04:42:13 +01:00
// Parse token count from Claude's status line in interactive mode
// Matches patterns like "123.4k tokens", "5234 tokens", "1.2M tokens"
2026-01-26 12:22:05 +01:00
//
// SAFETY LIMITS:
// - Max tokens per session: 500k (Claude's context is ~200k)
// - Max delta per update: 100k (prevents sudden jumps from parsing errors)
// - Rejects "M" suffix values > 0.5 (500k) to prevent false matches
2026-02-04 07:24:32 +01:00
private parseTokensFromStatusLine ( cleanData : string ) : void {
2026-01-21 10:05:39 +01:00
// Quick pre-check: skip expensive regex if "token" not present (performance optimization)
2026-02-04 07:24:32 +01:00
if ( ! cleanData . includes ( 'token' )) return ;
2026-01-19 04:42:13 +01:00
// Match patterns: "123.4k tokens", "5234 tokens", "1.2M tokens"
// The status line typically shows total tokens like "1.2k tokens" near the prompt
2026-02-04 07:24:32 +01:00
// Note: ANSI codes are already stripped by caller for performance
2026-01-19 11:48:02 +01:00
const tokenMatch = cleanData . match ( TOKEN_PATTERN );
2026-01-19 04:42:13 +01:00
if ( tokenMatch ) {
let tokenCount = parseFloat ( tokenMatch [ 1 ]);
const suffix = tokenMatch [ 2 ] ? . toLowerCase ();
// Convert k/M suffix to actual number
if ( suffix === 'k' ) {
tokenCount *= 1000 ;
} else if ( suffix === 'm' ) {
2026-01-26 12:22:05 +01:00
// Safety: Reject M values that would result in > 500k tokens
// Claude's context window is ~200k, so anything claiming millions is likely a false match
if ( tokenCount > 0.5 ) {
console . warn ( `[Session ${ this . id } ] Rejected suspicious M token value: ${ tokenMatch [ 0 ] } (would be ${ tokenCount * 1000000 } tokens)` );
return ;
}
2026-01-19 04:42:13 +01:00
tokenCount *= 1000000 ;
}
2026-01-29 10:55:49 +01:00
// Safety: Absolute maximum tokens per session
2026-01-26 12:22:05 +01:00
if ( tokenCount > MAX_SESSION_TOKENS ) {
console . warn ( `[Session ${ this . id } ] Rejected token count exceeding max: ${ tokenCount } > ${ MAX_SESSION_TOKENS } ` );
return ;
}
2026-01-19 04:42:13 +01:00
// Only update if the new count is higher (tokens only increase within a session)
// We use total tokens as an estimate - Claude shows combined input+output
const currentTotal = this . _totalInputTokens + this . _totalOutputTokens ;
if ( tokenCount > currentTotal ) {
2026-01-26 12:22:05 +01:00
const delta = tokenCount - currentTotal ;
// Safety: Reject suspiciously large jumps (max 100k per update)
const MAX_DELTA_PER_UPDATE = 100 _000 ;
if ( delta > MAX_DELTA_PER_UPDATE ) {
console . warn ( `[Session ${ this . id } ] Rejected suspicious token jump: ${ currentTotal } -> ${ tokenCount } (delta: ${ delta } )` );
return ;
}
2026-01-19 04:42:13 +01:00
// Estimate: split roughly 60% input, 40% output (common ratio)
// This is an approximation since interactive mode doesn't give us the breakdown
this . _totalInputTokens += Math . round ( delta * 0.6 );
this . _totalOutputTokens += Math . round ( delta * 0.4 );
2026-01-19 13:08:53 +01:00
// Check if we should auto-compact or auto-clear
this . checkAutoCompact ();
2026-01-19 04:42:13 +01:00
this . checkAutoClear ();
}
}
}
2026-01-31 04:44:46 +01:00
// Parse Claude Code CLI info from terminal startup output
// Extracts version, model, and account type for display in Claudeman UI
2026-02-04 07:24:32 +01:00
// Note: Expects cleanData with ANSI codes already stripped by caller
private parseClaudeCodeInfo ( cleanData : string ) : void {
2026-01-31 04:44:46 +01:00
// Only parse once per session (during startup)
if ( this . _cliInfoParsed ) return ;
// Quick pre-checks
2026-02-04 07:24:32 +01:00
if ( ! cleanData . includes ( 'Claude' ) && ! cleanData . includes ( 'current:' ) && ! cleanData . includes ( 'Opus' ) && ! cleanData . includes ( 'Sonnet' )) {
2026-01-31 04:44:46 +01:00
return ;
}
let changed = false ;
// Match "Claude Code v2.1.27" or "Claude Code vX.Y.Z"
if ( ! this . _cliVersion ) {
const versionMatch = cleanData . match ( /Claude Code v(\d+\.\d+\.\d+)/ );
if ( versionMatch ) {
this . _cliVersion = versionMatch [ 1 ];
changed = true ;
}
}
// Match model and account: "Opus 4.5 · Claude Max" or "Sonnet 4 · API"
// The · character separates model from account type
if ( ! this . _cliModel || ! this . _cliAccountType ) {
// Try various model patterns
const modelPatterns = [
/(Opus \d+(?:\.\d+)?)\s*[·•]\s*(.+?)(?:\s*$|\s+[~/])/ ,
/(Sonnet \d+(?:\.\d+)?)\s*[·•]\s*(.+?)(?:\s*$|\s+[~/])/ ,
/(Haiku \d+(?:\.\d+)?)\s*[·•]\s*(.+?)(?:\s*$|\s+[~/])/ ,
];
for ( const pattern of modelPatterns ) {
const match = cleanData . match ( pattern );
if ( match ) {
if ( ! this . _cliModel ) {
this . _cliModel = match [ 1 ]. trim ();
changed = true ;
}
if ( ! this . _cliAccountType ) {
this . _cliAccountType = match [ 2 ]. trim ();
changed = true ;
}
break ;
}
}
}
// Match version check: "current: 2.1.27" and "latest: 2.1.27"
if ( ! this . _cliLatestVersion ) {
const latestMatch = cleanData . match ( /latest:\s*(\d+\.\d+\.\d+)/ );
if ( latestMatch ) {
this . _cliLatestVersion = latestMatch [ 1 ];
changed = true ;
}
}
// Mark as parsed once we have the essential info
if ( this . _cliVersion && this . _cliModel ) {
this . _cliInfoParsed = true ;
}
// Emit update if anything changed
if ( changed ) {
this . emit ( 'cliInfoUpdated' , {
version : this._cliVersion ,
model : this._cliModel ,
accountType : this._cliAccountType ,
latestVersion : this._cliLatestVersion ,
});
}
}
2026-01-19 13:08:53 +01:00
// Check if we should auto-compact based on token threshold
private checkAutoCompact () : void {
2026-01-30 19:05:46 +01:00
if ( this . _isStopped ) return ; // Early exit check
if ( ! this . _autoCompactEnabled || this . _isCompacting || this . _isClearing ) return ;
2026-01-19 13:08:53 +01:00
const totalTokens = this . _totalInputTokens + this . _totalOutputTokens ;
if ( totalTokens >= this . _autoCompactThreshold ) {
this . _isCompacting = true ;
console . log ( `[Session] Auto-compact triggered: ${ totalTokens } tokens >= ${ this . _autoCompactThreshold } threshold` );
// Wait for Claude to be idle before compacting
2026-02-13 05:07:51 +01:00
const checkAndCompact = async () => {
2026-01-30 19:05:46 +01:00
// Check if session is still valid (not stopped) - must be first check
if ( this . _isStopped ) return ;
if ( ! this . _isCompacting ) return ;
2026-01-21 09:54:42 +01:00
2026-01-19 13:08:53 +01:00
if ( ! this . _isWorking ) {
2026-01-30 19:05:46 +01:00
// Re-check stopped state after async operation might have completed
if ( this . _isStopped ) return ;
2026-01-19 13:08:53 +01:00
// Send /compact command with optional prompt
const compactCmd = this . _autoCompactPrompt
2026-01-19 16:39:45 +01:00
? `/compact ${ this . _autoCompactPrompt } \ r`
: '/compact\r' ;
2026-02-18 12:51:35 +01:00
await this . writeViaMux ( compactCmd );
2026-01-19 13:08:53 +01:00
this . emit ( 'autoCompact' , {
tokens : totalTokens ,
threshold : this._autoCompactThreshold ,
prompt : this._autoCompactPrompt || undefined
});
// Wait a moment then re-enable (longer than clear since compact takes time)
2026-01-22 00:08:32 +01:00
if ( ! this . _isStopped ) {
this . _autoCompactTimer = setTimeout (() => {
2026-01-30 19:05:46 +01:00
if ( this . _isStopped ) return ; // Check at callback start
2026-01-22 00:08:32 +01:00
this . _autoCompactTimer = null ;
this . _isCompacting = false ;
}, 10000 );
}
2026-01-19 13:08:53 +01:00
} else {
2026-01-26 14:27:21 +01:00
// Check again after delay
2026-01-22 00:08:32 +01:00
if ( ! this . _isStopped ) {
2026-01-26 14:27:21 +01:00
this . _autoCompactTimer = setTimeout ( checkAndCompact , AUTO_RETRY_DELAY_MS );
2026-01-22 00:08:32 +01:00
}
2026-01-19 13:08:53 +01:00
}
};
// Start checking after a short delay
2026-01-22 00:08:32 +01:00
if ( ! this . _isStopped ) {
2026-01-26 14:27:21 +01:00
this . _autoCompactTimer = setTimeout ( checkAndCompact , AUTO_INITIAL_DELAY_MS );
2026-01-22 00:08:32 +01:00
}
2026-01-19 13:08:53 +01:00
}
}
2026-01-19 00:38:11 +01:00
// Check if we should auto-clear based on token threshold
private checkAutoClear () : void {
2026-01-30 19:05:46 +01:00
if ( this . _isStopped ) return ; // Early exit check
if ( ! this . _autoClearEnabled || this . _isClearing || this . _isCompacting ) return ;
2026-01-19 00:38:11 +01:00
const totalTokens = this . _totalInputTokens + this . _totalOutputTokens ;
if ( totalTokens >= this . _autoClearThreshold ) {
this . _isClearing = true ;
console . log ( `[Session] Auto-clear triggered: ${ totalTokens } tokens >= ${ this . _autoClearThreshold } threshold` );
// Wait for Claude to be idle before clearing
2026-02-13 05:07:51 +01:00
const checkAndClear = async () => {
2026-01-30 19:05:46 +01:00
// Check if session is still valid (not stopped) - must be first check
if ( this . _isStopped ) return ;
if ( ! this . _isClearing ) return ;
2026-01-21 09:54:42 +01:00
2026-01-19 00:38:11 +01:00
if ( ! this . _isWorking ) {
2026-01-30 19:05:46 +01:00
// Re-check stopped state after async operation might have completed
if ( this . _isStopped ) return ;
2026-01-19 00:38:11 +01:00
// Send /clear command
2026-02-18 12:51:35 +01:00
await this . writeViaMux ( '/clear\r' );
2026-01-19 00:38:11 +01:00
// Reset token counts
this . _totalInputTokens = 0 ;
this . _totalOutputTokens = 0 ;
this . emit ( 'autoClear' , { tokens : totalTokens , threshold : this._autoClearThreshold });
// Wait a moment then re-enable
2026-01-22 00:08:32 +01:00
if ( ! this . _isStopped ) {
this . _autoClearTimer = setTimeout (() => {
2026-01-30 19:05:46 +01:00
if ( this . _isStopped ) return ; // Check at callback start
2026-01-22 00:08:32 +01:00
this . _autoClearTimer = null ;
this . _isClearing = false ;
}, 5000 );
}
2026-01-19 00:38:11 +01:00
} else {
2026-01-26 14:27:21 +01:00
// Check again after delay
2026-01-22 00:08:32 +01:00
if ( ! this . _isStopped ) {
2026-01-26 14:27:21 +01:00
this . _autoClearTimer = setTimeout ( checkAndClear , AUTO_RETRY_DELAY_MS );
2026-01-22 00:08:32 +01:00
}
2026-01-19 00:38:11 +01:00
}
};
// Start checking after a short delay
2026-01-22 00:08:32 +01:00
if ( ! this . _isStopped ) {
2026-01-26 14:27:21 +01:00
this . _autoClearTimer = setTimeout ( checkAndClear , AUTO_INITIAL_DELAY_MS );
2026-01-22 00:08:32 +01:00
}
2026-01-19 00:38:11 +01:00
}
}
2026-01-21 04:25:53 +01:00
/**
* Sends input directly to the PTY process.
*
* For interactive sessions, this is how you send user input to Claude.
* Remember to include `\r` (carriage return) to simulate pressing Enter.
*
* @param data - The input data to send (text, escape sequences, etc.)
*
* @example
* ```typescript
* session.write('hello world'); // Text only, no Enter
* session.write('\r'); // Enter key
* session.write('ls -la\r'); // Command with Enter
* ```
*/
2026-01-18 21:36:03 +01:00
write ( data : string ) : void {
if ( this . ptyProcess ) {
this . ptyProcess . write ( data );
}
}
2026-01-21 04:25:53 +01:00
/**
2026-02-12 10:29:57 +01:00
* Sends input via the terminal multiplexer's direct input mechanism.
2026-01-21 04:25:53 +01:00
*
* More reliable than direct PTY write for programmatic input, especially
2026-02-12 10:29:57 +01:00
* with Claude CLI which uses Ink (React for terminals).
2026-02-18 12:51:35 +01:00
* Uses tmux `send-keys -l` to inject text + Enter.
2026-01-21 04:25:53 +01:00
*
* @param data - Input data with optional `\r` for Enter
2026-02-12 10:29:57 +01:00
* @returns true if input was sent, false if no mux session or PTY
2026-01-21 04:25:53 +01:00
*
* @example
* ```typescript
2026-02-18 12:51:35 +01:00
* session.writeViaMux('/clear\r'); // Send /clear command
* session.writeViaMux('/init\r'); // Send /init command
2026-01-21 04:25:53 +01:00
* ```
*/
2026-02-18 12:51:35 +01:00
async writeViaMux ( data : string ) : Promise < boolean > {
2026-02-12 10:29:57 +01:00
if ( this . _mux && this . _muxSession ) {
return this . _mux . sendInput ( this . id , data );
2026-01-19 15:35:41 +01:00
}
// Fallback to PTY write
if ( this . ptyProcess ) {
this . ptyProcess . write ( data );
return true ;
}
return false ;
}
2026-01-21 04:25:53 +01:00
/**
* Resizes the PTY terminal dimensions.
*
* Call this when the frontend terminal is resized to keep PTY in sync.
*
* @param cols - Number of columns (width in characters)
* @param rows - Number of rows (height in lines)
*/
2026-01-18 21:36:03 +01:00
resize ( cols : number , rows : number ) : void {
if ( this . ptyProcess ) {
this . ptyProcess . resize ( cols , rows );
}
2026-01-18 05:14:34 +01:00
}
// Legacy method for compatibility with session-manager
async start () : Promise < void > {
this . _status = 'idle' ;
}
// Legacy method for sending input - wraps runPrompt
async sendInput ( input : string ) : Promise < void > {
this . _status = 'busy' ;
this . _lastActivityAt = Date . now ();
this . runPrompt ( input ). catch ( err => {
2026-02-04 07:24:32 +01:00
const errorMsg = err instanceof Error ? err.message : String ( err );
this . emit ( 'error' , errorMsg );
2026-01-18 05:14:34 +01:00
});
}
2026-01-21 05:50:09 +01:00
/**
2026-01-21 22:36:45 +01:00
* Remove event listeners from TaskTracker and RalphTracker.
2026-01-21 05:50:09 +01:00
* Prevents memory leaks by ensuring handlers don't persist after session stop.
*/
private cleanupTrackerListeners () : void {
// Remove TaskTracker handlers
if ( this . _taskTrackerHandlers ) {
this . _taskTracker . off ( 'taskCreated' , this . _taskTrackerHandlers . taskCreated );
this . _taskTracker . off ( 'taskUpdated' , this . _taskTrackerHandlers . taskUpdated );
this . _taskTracker . off ( 'taskCompleted' , this . _taskTrackerHandlers . taskCompleted );
this . _taskTracker . off ( 'taskFailed' , this . _taskTrackerHandlers . taskFailed );
this . _taskTrackerHandlers = null ;
}
2026-01-21 22:36:45 +01:00
// Remove RalphTracker handlers
if ( this . _ralphHandlers ) {
this . _ralphTracker . off ( 'loopUpdate' , this . _ralphHandlers . loopUpdate );
this . _ralphTracker . off ( 'todoUpdate' , this . _ralphHandlers . todoUpdate );
this . _ralphTracker . off ( 'completionDetected' , this . _ralphHandlers . completionDetected );
2026-01-27 00:29:38 +01:00
this . _ralphTracker . off ( 'statusBlockDetected' , this . _ralphHandlers . statusBlockDetected );
this . _ralphTracker . off ( 'circuitBreakerUpdate' , this . _ralphHandlers . circuitBreakerUpdate );
this . _ralphTracker . off ( 'exitGateMet' , this . _ralphHandlers . exitGateMet );
2026-01-21 22:36:45 +01:00
this . _ralphHandlers = null ;
2026-01-21 05:50:09 +01:00
}
2026-01-23 10:20:37 +01:00
2026-01-26 00:55:29 +01:00
// Remove BashToolParser handlers
if ( this . _bashToolHandlers ) {
this . _bashToolParser . off ( 'toolStart' , this . _bashToolHandlers . toolStart );
this . _bashToolParser . off ( 'toolEnd' , this . _bashToolHandlers . toolEnd );
this . _bashToolParser . off ( 'toolsUpdate' , this . _bashToolHandlers . toolsUpdate );
this . _bashToolHandlers = null ;
}
2026-01-30 11:30:51 +01:00
// Destroy all trackers to release memory and stop timers
this . _bashToolParser . destroy ();
this . _taskTracker . destroy ();
this . _ralphTracker . destroy ();
2026-01-21 05:50:09 +01:00
}
2026-01-21 04:25:53 +01:00
/**
* Stops the session and cleans up resources.
*
2026-02-18 12:51:35 +01:00
* This kills the PTY process and optionally the associated tmux session.
* All buffers are cleared and the session is marked as stopped.
2026-01-21 04:25:53 +01:00
*
2026-02-18 12:51:35 +01:00
* @param killMux - Whether to also kill the mux session (default: true)
2026-01-21 04:25:53 +01:00
*
* @example
* ```typescript
* // Stop and kill everything
* await session.stop();
*
2026-02-18 12:51:35 +01:00
* // Stop but keep mux session running for later reattachment
2026-01-21 04:25:53 +01:00
* await session.stop(false);
* ```
*/
2026-02-18 12:51:35 +01:00
async stop ( killMux : boolean = true ) : Promise < void > {
2026-01-22 00:08:32 +01:00
// Set stopped flag first to prevent new timers from being created
this . _isStopped = true ;
2026-01-18 21:36:03 +01:00
// Clear activity timeout to prevent memory leak
if ( this . activityTimeout ) {
clearTimeout ( this . activityTimeout );
this . activityTimeout = null ;
}
2026-01-19 06:51:25 +01:00
// Clear line buffer flush timer
if ( this . _lineBufferFlushTimer ) {
clearTimeout ( this . _lineBufferFlushTimer );
this . _lineBufferFlushTimer = null ;
}
2026-01-21 09:54:42 +01:00
// Clear auto-compact/auto-clear timers to prevent memory leaks
if ( this . _autoCompactTimer ) {
clearTimeout ( this . _autoCompactTimer );
this . _autoCompactTimer = null ;
}
this . _isCompacting = false ;
if ( this . _autoClearTimer ) {
clearTimeout ( this . _autoClearTimer );
this . _autoClearTimer = null ;
}
this . _isClearing = false ;
// Clear prompt check timers
if ( this . _promptCheckInterval ) {
clearInterval ( this . _promptCheckInterval );
this . _promptCheckInterval = null ;
}
if ( this . _promptCheckTimeout ) {
clearTimeout ( this . _promptCheckTimeout );
this . _promptCheckTimeout = null ;
}
// Clear shell idle timer
if ( this . _shellIdleTimer ) {
clearTimeout ( this . _shellIdleTimer );
this . _shellIdleTimer = null ;
}
2026-01-21 05:34:45 +01:00
// Immediately cleanup Promise callbacks to prevent orphaned references
2026-02-18 12:51:35 +01:00
// during the rest of stop() processing (e.g., if mux kill times out)
2026-02-12 20:14:01 +01:00
if ( this . rejectPromise && ! this . _promptResolved ) {
this . _promptResolved = true ;
2026-01-21 05:34:45 +01:00
this . rejectPromise ( new Error ( 'Session stopped' ));
}
this . resolvePromise = null ;
this . rejectPromise = null ;
2026-01-21 05:50:09 +01:00
// Remove event listeners from trackers to prevent memory leaks
this . cleanupTrackerListeners ();
2026-01-18 21:36:03 +01:00
if ( this . ptyProcess ) {
2026-02-19 22:15:36 +01:00
if ( killMux ) {
// Full kill: SIGTERM → wait → SIGKILL the PTY and its children
const pid = this . ptyProcess . pid ;
2026-01-18 21:36:03 +01:00
2026-02-19 22:15:36 +01:00
// First try graceful SIGTERM
try {
this . ptyProcess . kill ();
} catch ( err ) {
console . warn ( '[Session] Failed to send SIGTERM to PTY process (may already be dead):' , err );
2026-01-18 04:50:46 +01:00
}
2026-01-18 21:36:03 +01:00
2026-02-19 22:15:36 +01:00
// Give it a moment to terminate gracefully
await new Promise ( resolve => setTimeout ( resolve , GRACEFUL_SHUTDOWN_DELAY_MS ));
// Force kill with SIGKILL if still alive
try {
if ( pid ) {
process . kill ( pid , 'SIGKILL' );
}
} catch ( err ) {
console . warn ( '[Session] Failed to send SIGKILL to process (already terminated):' , err );
2026-01-18 21:36:03 +01:00
}
2026-02-19 22:15:36 +01:00
// Also try to kill any child processes in the process group
try {
if ( pid ) {
process . kill ( - pid , 'SIGKILL' );
}
} catch ( err ) {
console . warn ( '[Session] Failed to send SIGKILL to process group (may not exist):' , err );
}
} else {
// Server shutdown: just detach — the process lives on inside tmux
console . log ( '[Session] Detaching from PTY (server shutdown) — mux session preserved' );
2026-01-18 21:36:03 +01:00
}
this . ptyProcess = null ;
}
this . _pid = null ;
2026-02-19 22:15:36 +01:00
this . _status = killMux ? 'stopped' : 'idle' ;
2026-01-18 21:36:03 +01:00
this . _currentTaskId = null ;
2026-02-12 18:26:16 +01:00
// Clear task description cache and agent tree to prevent memory leak
2026-01-30 13:25:18 +01:00
this . _recentTaskDescriptions . clear ();
2026-02-12 18:26:16 +01:00
this . _childAgentIds = [];
2026-01-30 13:25:18 +01:00
2026-02-12 10:29:57 +01:00
// Kill the associated mux session if requested
2026-02-18 12:51:35 +01:00
if ( killMux && this . _mux ) {
2026-02-12 10:29:57 +01:00
// Try to kill mux session even if _muxSession is not set (e.g., restored sessions)
2026-01-19 04:22:41 +01:00
try {
2026-02-12 10:29:57 +01:00
const killed = await this . _mux . killSession ( this . id );
2026-01-19 11:48:02 +01:00
if ( killed ) {
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Killed mux session for:' , this . id );
2026-01-19 11:48:02 +01:00
}
2026-01-19 04:22:41 +01:00
} catch ( err ) {
2026-02-12 10:29:57 +01:00
console . error ( '[Session] Failed to kill mux session:' , err );
2026-01-19 04:22:41 +01:00
}
2026-02-12 10:29:57 +01:00
this . _muxSession = null ;
2026-02-18 12:51:35 +01:00
} else if ( this . _muxSession && ! killMux ) {
2026-02-12 10:29:57 +01:00
console . log ( '[Session] Keeping mux session alive:' , this . _muxSession . muxName );
this . _muxSession = null ; // Detach but don't kill
2026-01-19 04:22:41 +01:00
}
2026-01-18 04:50:46 +01:00
}
assignTask ( taskId : string ) : void {
this . _currentTaskId = taskId ;
this . _status = 'busy' ;
2026-01-21 05:10:57 +01:00
this . _terminalBuffer . clear ();
this . _textOutput . clear ();
2026-01-18 04:50:46 +01:00
this . _errorBuffer = '' ;
2026-01-18 05:14:34 +01:00
this . _messages = [];
2026-01-18 04:50:46 +01:00
this . _lastActivityAt = Date . now ();
}
clearTask () : void {
this . _currentTaskId = null ;
this . _status = 'idle' ;
this . _lastActivityAt = Date . now ();
}
getOutput () : string {
2026-01-21 04:55:48 +01:00
return this . _textOutput . value ;
2026-01-18 04:50:46 +01:00
}
getError () : string {
return this . _errorBuffer ;
}
2026-01-18 21:36:03 +01:00
getTerminalBuffer () : string {
2026-01-21 04:55:48 +01:00
return this . _terminalBuffer . value ;
2026-01-18 21:36:03 +01:00
}
2026-01-18 04:50:46 +01:00
clearBuffers () : void {
2026-01-21 04:55:48 +01:00
this . _terminalBuffer . clear ();
this . _textOutput . clear ();
2026-01-18 04:50:46 +01:00
this . _errorBuffer = '' ;
2026-01-18 05:14:34 +01:00
this . _messages = [];
2026-01-19 00:38:11 +01:00
this . _taskTracker . clear ();
2026-01-21 22:36:45 +01:00
this . _ralphTracker . clear ();
2026-01-30 13:25:18 +01:00
this . _recentTaskDescriptions . clear ();
2026-01-18 04:50:46 +01:00
}
}