aicodeman 0.2.8

package/dist/session.d.ts

@@ -0,0 +1,686 @@
+/**
+ * @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
+ *
+ * The session can optionally run inside a tmux session for persistence across disconnects.
+ * It tracks tokens, costs, background tasks, and supports
+ * auto-clear/auto-compact functionality when token limits are approached.
+ *
+ * @module session
+ */
+import { EventEmitter } from 'node:events';
+import { SessionState, SessionStatus, SessionConfig, RalphTrackerState, RalphTodoItem, ActiveBashTool, NiceConfig, type ClaudeMode, type SessionMode, type OpenCodeConfig } from './types.js';
+import type { TerminalMultiplexer, MuxSession } from './mux-interface.js';
+import { TaskTracker, type BackgroundTask } from './task-tracker.js';
+import { RalphTracker } from './ralph-tracker.js';
+import { BashToolParser } from './bash-tool-parser.js';
+export type { BackgroundTask } from './task-tracker.js';
+export type { RalphTrackerState, RalphTodoItem, ActiveBashTool } from './types.js';
+/**
+ * Represents a JSON message from Claude CLI's stream-json output format.
+ * Messages are newline-delimited JSON objects parsed from PTY output.
+ */
+export interface ClaudeMessage {
+    /** Message type indicating the role or purpose */
+    type: 'system' | 'assistant' | 'user' | 'result';
+    /** Optional subtype for further classification */
+    subtype?: string;
+    /** Claude's internal session identifier */
+    session_id?: string;
+    /** Message content with optional token usage */
+    message?: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+        };
+    };
+    /** Final result text (on result messages) */
+    result?: string;
+    /** Whether this message represents an error */
+    is_error?: boolean;
+    /** Total cost in USD (on result messages) */
+    total_cost_usd?: number;
+    /** Total duration in milliseconds (on result messages) */
+    duration_ms?: number;
+}
+/**
+ * Event signatures emitted by the Session class.
+ * Subscribe using `session.on('eventName', handler)`.
+ */
+export interface SessionEvents {
+    /** Processed text output (ANSI stripped) */
+    output: (data: string) => void;
+    /** Parsed JSON message from Claude CLI */
+    message: (msg: ClaudeMessage) => void;
+    /** Error output from the session */
+    error: (data: string) => void;
+    /** Session process exited */
+    exit: (code: number | null) => void;
+    /** One-shot prompt completed with result and cost */
+    completion: (result: string, cost: number) => void;
+    /** Raw terminal data (includes ANSI codes) */
+    terminal: (data: string) => void;
+    /** Signal to clear terminal display (after mux attach) */
+    clearTerminal: () => void;
+    /** New background task started */
+    taskCreated: (task: BackgroundTask) => void;
+    /** Background task status changed */
+    taskUpdated: (task: BackgroundTask) => void;
+    /** Background task finished successfully */
+    taskCompleted: (task: BackgroundTask) => void;
+    /** Background task failed with error */
+    taskFailed: (task: BackgroundTask, error: string) => void;
+    /** Auto-clear triggered due to token threshold */
+    autoClear: (data: {
+        tokens: number;
+        threshold: number;
+    }) => void;
+    /** Auto-compact triggered due to token threshold */
+    autoCompact: (data: {
+        tokens: number;
+        threshold: number;
+        prompt?: string;
+    }) => void;
+    /** Ralph loop state changed */
+    ralphLoopUpdate: (state: RalphTrackerState) => void;
+    /** Ralph todo list updated */
+    ralphTodoUpdate: (todos: RalphTodoItem[]) => void;
+    /** Ralph completion phrase detected */
+    ralphCompletionDetected: (phrase: string) => void;
+    /** 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;
+    /** 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;
+    /** CLI info (version, model, account) updated */
+    cliInfoUpdated: (info: {
+        version: string | null;
+        model: string | null;
+        accountType: string | null;
+        latestVersion: string | null;
+    }) => void;
+}
+export type { SessionMode } from './types.js';
+/**
+ * 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',
+ *   mux: muxManager,
+ *   useMux: true
+ * });
+ * 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
+ */
+export declare class Session extends EventEmitter {
+    readonly id: string;
+    readonly workingDir: string;
+    readonly createdAt: number;
+    readonly mode: SessionMode;
+    /** Maximum number of task descriptions to keep (LRUMap handles size limit automatically) */
+    private static readonly MAX_TASK_DESCRIPTIONS;
+    private static readonly TASK_DESCRIPTION_MAX_AGE_MS;
+    private _name;
+    private ptyProcess;
+    private _pid;
+    private _status;
+    private _currentTaskId;
+    private _terminalBuffer;
+    private _textOutput;
+    private _errorBuffer;
+    private _lastActivityAt;
+    private _claudeSessionId;
+    private _totalCost;
+    private _messages;
+    private _lineBuffer;
+    private _lineBufferFlushTimer;
+    private resolvePromise;
+    private rejectPromise;
+    private _promptResolved;
+    private _isWorking;
+    private _lastPromptTime;
+    private activityTimeout;
+    private _awaitingIdleConfirmation;
+    private _taskTracker;
+    private _totalInputTokens;
+    private _totalOutputTokens;
+    private _autoClearThreshold;
+    private _autoClearEnabled;
+    private _isClearing;
+    private _autoCompactThreshold;
+    private _autoCompactEnabled;
+    private _autoCompactPrompt;
+    private _isCompacting;
+    private _imageWatcherEnabled;
+    private _flickerFilterEnabled;
+    private _cliVersion;
+    private _cliModel;
+    private _cliAccountType;
+    private _cliLatestVersion;
+    private _cliInfoParsed;
+    private _autoCompactTimer;
+    private _autoClearTimer;
+    private _promptCheckInterval;
+    private _promptCheckTimeout;
+    private _shellIdleTimer;
+    private _mux;
+    private _muxSession;
+    private _useMux;
+    private _isStopped;
+    private _ralphTracker;
+    private _parentAgentId;
+    private _childAgentIds;
+    private _niceConfig;
+    private _model;
+    private _claudeMode;
+    private _allowedTools;
+    private _openCodeConfig;
+    private _color;
+    private _taskTrackerHandlers;
+    private _ralphHandlers;
+    private _bashToolParser;
+    private _bashToolHandlers;
+    private _recentTaskDescriptions;
+    private _lastExpensiveProcessTime;
+    private _pendingCleanData;
+    private _expensiveProcessTimer;
+    private static readonly EXPENSIVE_PROCESS_INTERVAL_MS;
+    constructor(config: Partial<SessionConfig> & {
+        workingDir: string;
+        mode?: SessionMode;
+        name?: string;
+        /** Terminal multiplexer instance (tmux) */
+        mux?: TerminalMultiplexer;
+        /** Whether to use multiplexer wrapping */
+        useMux?: boolean;
+        /** Existing mux session for restored sessions */
+        muxSession?: MuxSession;
+        niceConfig?: NiceConfig;
+        /** Claude model override (e.g., 'opus', 'sonnet', 'haiku') */
+        model?: string;
+        /** Claude CLI startup permission mode */
+        claudeMode?: ClaudeMode;
+        /** Comma-separated allowed tools (for 'allowedTools' mode) */
+        allowedTools?: string;
+        /** OpenCode configuration (only for mode === 'opencode') */
+        openCodeConfig?: OpenCodeConfig;
+    });
+    get status(): SessionStatus;
+    get currentTaskId(): string | null;
+    get pid(): number | null;
+    get terminalBuffer(): string;
+    get terminalBufferLength(): number;
+    get textOutput(): string;
+    get errorBuffer(): string;
+    get lastActivityAt(): number;
+    get claudeSessionId(): string | null;
+    get totalCost(): number;
+    get messages(): ClaudeMessage[];
+    get isWorking(): boolean;
+    get lastPromptTime(): number;
+    get taskTracker(): TaskTracker;
+    get runningTaskCount(): number;
+    get taskTree(): BackgroundTask[];
+    get taskStats(): {
+        total: number;
+        running: number;
+        completed: number;
+        failed: number;
+    };
+    get ralphTracker(): RalphTracker;
+    get ralphLoopState(): RalphTrackerState;
+    get ralphTodos(): RalphTodoItem[];
+    get ralphTodoStats(): {
+        total: number;
+        pending: number;
+        inProgress: number;
+        completed: number;
+    };
+    get bashToolParser(): BashToolParser;
+    get activeTools(): ActiveBashTool[];
+    get parentAgentId(): string | null;
+    set parentAgentId(value: string | null);
+    get childAgentIds(): string[];
+    addChildAgentId(agentId: string): void;
+    removeChildAgentId(agentId: string): void;
+    get niceConfig(): NiceConfig;
+    /** Claude CLI startup permission mode */
+    get claudeMode(): ClaudeMode;
+    /** Allowed tools list (for 'allowedTools' mode) */
+    get allowedTools(): string | undefined;
+    /**
+     * Build Claude CLI permission flags based on the configured mode.
+     * Returns an array of args to pass to the CLI.
+     */
+    private _buildPermissionArgs;
+    /**
+     * Set CPU priority configuration.
+     * Note: This only affects new sessions; existing running processes won't be changed.
+     */
+    setNice(config: Partial<NiceConfig>): void;
+    get color(): import('./types.js').SessionColor;
+    setColor(color: import('./types.js').SessionColor): void;
+    get totalTokens(): number;
+    get inputTokens(): number;
+    get outputTokens(): number;
+    /**
+     * Restore token and cost values from saved state.
+     * Called when recovering sessions after server restart.
+     */
+    restoreTokens(inputTokens: number, outputTokens: number, totalCost: number): void;
+    get autoClearThreshold(): number;
+    get autoClearEnabled(): boolean;
+    get name(): string;
+    set name(value: string);
+    /** Minimum valid threshold for auto-clear/compact (1000 tokens) */
+    private static readonly MIN_AUTO_THRESHOLD;
+    /** Maximum valid threshold for auto-clear/compact (500k tokens) */
+    private static readonly MAX_AUTO_THRESHOLD;
+    /** Default auto-clear threshold when invalid value provided */
+    private static readonly DEFAULT_AUTO_CLEAR_THRESHOLD;
+    /** Default auto-compact threshold when invalid value provided */
+    private static readonly DEFAULT_AUTO_COMPACT_THRESHOLD;
+    setAutoClear(enabled: boolean, threshold?: number): void;
+    get autoCompactThreshold(): number;
+    get autoCompactEnabled(): boolean;
+    get autoCompactPrompt(): string;
+    setAutoCompact(enabled: boolean, threshold?: number, prompt?: string): void;
+    get imageWatcherEnabled(): boolean;
+    set imageWatcherEnabled(enabled: boolean);
+    get flickerFilterEnabled(): boolean;
+    set flickerFilterEnabled(enabled: boolean);
+    isIdle(): boolean;
+    isBusy(): boolean;
+    isRunning(): boolean;
+    toState(): SessionState;
+    toDetailedState(): {
+        textOutput: string;
+        terminalBuffer: string;
+        name: string;
+        mode: SessionMode;
+        claudeSessionId: string | null;
+        totalCost: number;
+        messageCount: number;
+        isWorking: boolean;
+        lastPromptTime: number;
+        bufferStats: {
+            terminalBufferSize: number;
+            textOutputSize: number;
+            messageCount: number;
+            maxTerminalBuffer: number;
+            maxTextOutput: number;
+            maxMessages: number;
+        };
+        taskStats: {
+            total: number;
+            running: number;
+            completed: number;
+            failed: number;
+        };
+        taskTree: Omit<BackgroundTask, "output">[];
+        tokens: {
+            input: number;
+            output: number;
+            total: number;
+        };
+        autoClear: {
+            enabled: boolean;
+            threshold: number;
+        };
+        nice: {
+            enabled: boolean;
+            niceValue: number;
+        };
+        ralphLoop: RalphTrackerState;
+        ralphTodos: RalphTodoItem[];
+        ralphTodoStats: {
+            total: number;
+            pending: number;
+            inProgress: number;
+            completed: number;
+        };
+        id: string;
+        pid: number | null;
+        status: SessionStatus;
+        workingDir: string;
+        currentTaskId: string | null;
+        createdAt: number;
+        lastActivityAt: number;
+        autoClearEnabled?: boolean;
+        autoClearThreshold?: number;
+        autoCompactEnabled?: boolean;
+        autoCompactThreshold?: number;
+        autoCompactPrompt?: string;
+        imageWatcherEnabled?: boolean;
+        inputTokens?: number;
+        outputTokens?: number;
+        respawnEnabled?: boolean;
+        respawnConfig?: import("./types.js").RespawnConfig & {
+            durationMinutes?: number;
+        };
+        ralphEnabled?: boolean;
+        ralphAutoEnableDisabled?: boolean;
+        ralphCompletionPhrase?: string;
+        parentAgentId?: string;
+        childAgentIds?: string[];
+        niceEnabled?: boolean;
+        niceValue?: number;
+        color?: import("./types.js").SessionColor;
+        flickerFilterEnabled?: boolean;
+        cliVersion?: string;
+        cliModel?: string;
+        cliAccountType?: string;
+        cliLatestVersion?: string;
+        openCodeConfig?: OpenCodeConfig;
+    };
+    /**
+     * 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(): {
+        name: string;
+        mode: SessionMode;
+        claudeSessionId: string | null;
+        totalCost: number;
+        messageCount: number;
+        isWorking: boolean;
+        lastPromptTime: number;
+        bufferStats: {
+            terminalBufferSize: number;
+            textOutputSize: number;
+            messageCount: number;
+            maxTerminalBuffer: number;
+            maxTextOutput: number;
+            maxMessages: number;
+        };
+        taskStats: {
+            total: number;
+            running: number;
+            completed: number;
+            failed: number;
+        };
+        taskTree: Omit<BackgroundTask, "output">[];
+        tokens: {
+            input: number;
+            output: number;
+            total: number;
+        };
+        autoClear: {
+            enabled: boolean;
+            threshold: number;
+        };
+        nice: {
+            enabled: boolean;
+            niceValue: number;
+        };
+        ralphLoop: RalphTrackerState;
+        ralphTodos: RalphTodoItem[];
+        ralphTodoStats: {
+            total: number;
+            pending: number;
+            inProgress: number;
+            completed: number;
+        };
+        id: string;
+        pid: number | null;
+        status: SessionStatus;
+        workingDir: string;
+        currentTaskId: string | null;
+        createdAt: number;
+        lastActivityAt: number;
+        autoClearEnabled?: boolean;
+        autoClearThreshold?: number;
+        autoCompactEnabled?: boolean;
+        autoCompactThreshold?: number;
+        autoCompactPrompt?: string;
+        imageWatcherEnabled?: boolean;
+        inputTokens?: number;
+        outputTokens?: number;
+        respawnEnabled?: boolean;
+        respawnConfig?: import("./types.js").RespawnConfig & {
+            durationMinutes?: number;
+        };
+        ralphEnabled?: boolean;
+        ralphAutoEnableDisabled?: boolean;
+        ralphCompletionPhrase?: string;
+        parentAgentId?: string;
+        childAgentIds?: string[];
+        niceEnabled?: boolean;
+        niceValue?: number;
+        color?: import("./types.js").SessionColor;
+        flickerFilterEnabled?: boolean;
+        cliVersion?: string;
+        cliModel?: string;
+        cliAccountType?: string;
+        cliLatestVersion?: string;
+        openCodeConfig?: OpenCodeConfig;
+    };
+    /**
+     * Starts an interactive Claude CLI session with full terminal support.
+     *
+     * This spawns Claude CLI in interactive mode with the configured permission
+     * mode (default: `--dangerously-skip-permissions`). If mux wrapping is enabled,
+     * the session runs inside a tmux session for persistence across disconnects.
+     *
+     * @throws {Error} If a process is already running in this session
+     *
+     * @example
+     * ```typescript
+     * const session = new Session({ workingDir: '/project', useMux: true });
+     * await session.startInteractive();
+     * session.on('terminal', (data) => process.stdout.write(data));
+     * session.write('help me with this code\r');
+     * ```
+     */
+    startInteractive(): Promise<void>;
+    /**
+     * Process expensive parsers (ANSI strip, Ralph, bash tool, token, CLI info, task descriptions).
+     * Called on a throttled schedule (every EXPENSIVE_PROCESS_INTERVAL_MS) instead of on every
+     * PTY data chunk. Receives accumulated raw data to process in one batch.
+     */
+    private _processExpensiveParsers;
+    /**
+     * 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');
+     * ```
+     */
+    startShell(): Promise<void>;
+    /**
+     * 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
+     * @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)
+     * @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' });
+     * const { result, cost } = await session.runPrompt('Explain this code', { model: 'opus' });
+     * console.log(`Response: ${result}`);
+     * console.log(`Cost: $${cost.toFixed(4)}`);
+     * ```
+     */
+    runPrompt(prompt: string, options?: {
+        model?: string;
+        onProgress?: (info: {
+            tokens?: number;
+            status?: string;
+        }) => void;
+    }): Promise<{
+        result: string;
+        cost: number;
+    }>;
+    private processOutput;
+    /**
+     * 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
+     */
+    private parseTaskDescriptionsFromTerminalData;
+    /**
+     * Parse task descriptions from a pre-cleaned line (no ANSI codes).
+     * Used by both processOutput() and parseTaskDescriptionsFromTerminalData().
+     */
+    private parseTaskDescriptionsDirect;
+    /**
+     * Remove task descriptions older than TASK_DESCRIPTION_MAX_AGE_MS.
+     * Size limit is handled automatically by LRUMap eviction on set().
+     */
+    private cleanupOldTaskDescriptions;
+    /**
+     * Get recent task descriptions parsed from terminal output.
+     * Returns descriptions sorted by timestamp (most recent first).
+     */
+    getRecentTaskDescriptions(): Array<{
+        timestamp: number;
+        description: string;
+    }>;
+    /**
+     * 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): string | undefined;
+    private parseTokensFromStatusLine;
+    private parseClaudeCodeInfo;
+    private checkAutoCompact;
+    private checkAutoClear;
+    /**
+     * 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
+     * ```
+     */
+    write(data: string): void;
+    /**
+     * Sends input via the terminal multiplexer's direct input mechanism.
+     *
+     * More reliable than direct PTY write for programmatic input, especially
+     * with Claude CLI which uses Ink (React for terminals).
+     * Uses tmux `send-keys -l` to inject text + Enter.
+     *
+     * @param data - Input data with optional `\r` for Enter
+     * @returns true if input was sent, false if no mux session or PTY
+     *
+     * @example
+     * ```typescript
+     * session.writeViaMux('/clear\r');  // Send /clear command
+     * session.writeViaMux('/init\r');   // Send /init command
+     * ```
+     */
+    writeViaMux(data: string): Promise<boolean>;
+    /** Current PTY dimensions — used to skip no-op resizes that trigger Ink redraws */
+    private _ptyCols;
+    private _ptyRows;
+    /**
+     * Resizes the PTY terminal dimensions.
+     * Skips the resize if dimensions haven't changed to avoid triggering
+     * unnecessary Ink full-screen redraws (visible flicker on tab switch).
+     *
+     * @param cols - Number of columns (width in characters)
+     * @param rows - Number of rows (height in lines)
+     */
+    resize(cols: number, rows: number): void;
+    start(): Promise<void>;
+    sendInput(input: string): Promise<void>;
+    /**
+     * Remove event listeners from TaskTracker and RalphTracker.
+     * Prevents memory leaks by ensuring handlers don't persist after session stop.
+     */
+    private cleanupTrackerListeners;
+    /**
+     * Stops the session and cleans up resources.
+     *
+     * This kills the PTY process and optionally the associated tmux session.
+     * All buffers are cleared and the session is marked as stopped.
+     *
+     * @param killMux - Whether to also kill the mux session (default: true)
+     *
+     * @example
+     * ```typescript
+     * // Stop and kill everything
+     * await session.stop();
+     *
+     * // Stop but keep mux session running for later reattachment
+     * await session.stop(false);
+     * ```
+     */
+    stop(killMux?: boolean): Promise<void>;
+    assignTask(taskId: string): void;
+    clearTask(): void;
+    getOutput(): string;
+    getError(): string;
+    getTerminalBuffer(): string;
+    clearBuffers(): void;
+}
+//# sourceMappingURL=session.d.ts.map