pty-manager 1.2.13 → 1.2.15

package/dist/index.d.mts

@@ -35,6 +35,8 @@ interface SpawnConfig {
     timeout?: number;
     /** Custom adapter configuration */
     adapterConfig?: Record<string, unknown>;
+    /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
+    stallTimeoutMs?: number;
 }
 /**
  * Handle to a running session
@@ -123,6 +125,10 @@ interface AutoResponseRule {
     type: BlockingPromptType;
     /** Response to send automatically */
     response: string;
+    /** How to deliver the response: 'text' writes raw text + CR, 'keys' sends key sequences (default: 'text') */
+    responseType?: 'text' | 'keys';
+    /** Key names to send when responseType is 'keys' (e.g. ['down', 'enter']) */
+    keys?: string[];
     /** Human-readable description of what this does */
     description: string;
     /** Whether this is safe to auto-respond (default: true) */
@@ -139,6 +145,17 @@ interface BlockingPromptInfo {
     instructions?: string;
     url?: string;
 }
+/**
+ * Classification result from external stall analysis
+ */
+interface StallClassification {
+    /** What the external classifier determined */
+    state: 'waiting_for_input' | 'still_working' | 'task_complete' | 'error';
+    /** Description of the detected prompt (for waiting_for_input) */
+    prompt?: string;
+    /** Suggested response to send (for waiting_for_input with auto-respond) */
+    suggestedResponse?: string;
+}
 /**
  * Logger interface (bring your own logger)
  */
@@ -187,6 +204,18 @@ interface PTYManagerConfig {
     logger?: Logger;
     /** Maximum output log lines per session (default: 1000) */
     maxLogLines?: number;
+    /** Enable stall detection (default: false) */
+    stallDetectionEnabled?: boolean;
+    /** Default stall timeout in ms (default: 8000). Can be overridden per-session via SpawnConfig. */
+    stallTimeoutMs?: number;
+    /**
+     * External classification callback invoked when a stall is detected.
+     * Return null or { state: 'still_working' } to reset the timer.
+     * Return { state: 'waiting_for_input', suggestedResponse } to auto-respond.
+     * Return { state: 'task_complete' } to transition session to ready.
+     * Return { state: 'error' } to emit session_error.
+     */
+    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
 }
 /**
  * Configuration for creating an adapter via factory
@@ -246,6 +275,12 @@ interface CLIAdapter {
      * These are applied automatically during startup and execution.
      */
     readonly autoResponseRules?: AutoResponseRule[];
+    /**
+     * Whether this CLI uses TUI menus that require arrow-key navigation.
+     * When true, auto-response rules without an explicit responseType
+     * default to sending Enter via sendKeys instead of writeRaw.
+     */
+    readonly usesTuiMenus?: boolean;
     /**
      * Get the CLI command to execute
      */
@@ -362,6 +397,7 @@ interface PTYSessionEvents {
     question: (question: string) => void;
     exit: (code: number) => void;
     error: (error: Error) => void;
+    stall_detected: (recentOutput: string, stallDurationMs: number) => void;
 }
 /**
  * Special key mappings to escape sequences
@@ -381,9 +417,14 @@ declare class PTYSession extends EventEmitter {
     private logger;
     private sessionRules;
     private _lastBlockingPromptHash;
+    private _stallTimer;
+    private _stallTimeoutMs;
+    private _stallDetectionEnabled;
+    private _lastStallHash;
+    private _stallStartedAt;
     readonly id: string;
     readonly config: SpawnConfig;
-    constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger);
+    constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger, stallDetectionEnabled?: boolean, defaultStallTimeoutMs?: number);
     get status(): SessionStatus;
     get pid(): number | undefined;
     get startedAt(): Date | undefined;
@@ -410,6 +451,37 @@ declare class PTYSession extends EventEmitter {
      * Clear all session auto-response rules.
      */
     clearAutoResponseRules(): void;
+    /**
+     * Start or reset the stall detection timer.
+     * Only active when status is "busy" and stall detection is enabled.
+     */
+    private resetStallTimer;
+    /**
+     * Clear the stall detection timer.
+     */
+    private clearStallTimer;
+    /**
+     * Called when the stall timer fires (no output for stallTimeoutMs).
+     */
+    private onStallTimerFired;
+    /**
+     * Promise-based delay helper.
+     */
+    private delay;
+    /**
+     * Simple string hash for deduplication.
+     */
+    private simpleHash;
+    /**
+     * Strip ANSI codes for stall detection output.
+     * Replaces cursor-forward sequences with spaces first.
+     */
+    private stripAnsiForStall;
+    /**
+     * Handle external stall classification result.
+     * Called by the manager after onStallClassify resolves.
+     */
+    handleStallClassification(classification: StallClassification | null): void;
     /**
      * Start the PTY session
      */
@@ -465,6 +537,16 @@ declare class PTYSession extends EventEmitter {
      * @param keys - Key name(s) to send, e.g. "ctrl+c" or ["up", "up", "enter"]
      */
     sendKeys(keys: string | string[]): void;
+    /**
+     * Select a TUI menu option by index (0-based).
+     * Sends Down arrow `optionIndex` times, then Enter, with 50ms delays.
+     */
+    selectMenuOption(optionIndex: number): Promise<void>;
+    /**
+     * Send a sequence of keys with staggered timing.
+     * Each key is sent 50ms apart using setTimeout to keep the caller synchronous.
+     */
+    private sendKeySequence;
     /**
      * Paste text using bracketed paste mode
      *
@@ -510,6 +592,7 @@ interface PTYManagerEvents {
     blocking_prompt: (session: SessionHandle, promptInfo: BlockingPromptInfo, autoResponded: boolean) => void;
     message: (message: SessionMessage) => void;
     question: (session: SessionHandle, question: string) => void;
+    stall_detected: (session: SessionHandle, recentOutput: string, stallDurationMs: number) => void;
 }
 declare class PTYManager extends EventEmitter {
     private sessions;
@@ -517,6 +600,9 @@ declare class PTYManager extends EventEmitter {
     private maxLogLines;
     private logger;
     readonly adapters: AdapterRegistry;
+    private _stallDetectionEnabled;
+    private _stallTimeoutMs;
+    private _onStallClassify?;
     constructor(config?: PTYManagerConfig);
     /**
      * Register a CLI adapter
@@ -581,6 +667,11 @@ declare class PTYManager extends EventEmitter {
      * Get the underlying PTYSession (for advanced use)
      */
     getSession(sessionId: string): PTYSession | undefined;
+    /**
+     * Configure stall detection at runtime.
+     * Affects newly spawned sessions only — existing sessions keep their config.
+     */
+    configureStallDetection(enabled: boolean, timeoutMs?: number, classify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>): void;
     /**
      * Add an auto-response rule to a session.
      * Session rules are checked before adapter rules.
@@ -622,6 +713,11 @@ declare abstract class BaseCLIAdapter implements CLIAdapter {
      * Subclasses should override this to add CLI-specific rules.
      */
     readonly autoResponseRules: AutoResponseRule[];
+    /**
+     * Whether this CLI uses TUI menus requiring arrow-key navigation.
+     * Defaults to false; coding agent adapters override to true.
+     */
+    readonly usesTuiMenus: boolean;
     abstract getCommand(): string;
     abstract getArgs(config: SpawnConfig): string[];
     abstract getEnv(config: SpawnConfig): Record<string, string>;
@@ -755,6 +851,15 @@ interface BunPTYManagerOptions {
      * Example: ['coding-agent-adapters']
      */
     adapterModules?: string[];
+    /** Enable stall detection (default: false) */
+    stallDetectionEnabled?: boolean;
+    /** Default stall timeout in ms (default: 8000) */
+    stallTimeoutMs?: number;
+    /**
+     * External classification callback invoked when a stall is detected.
+     * The worker emits stall_detected; this callback runs on the parent side.
+     */
+    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
 }
 /**
  * PTY Manager that works with Bun and other non-Node runtimes
@@ -771,6 +876,9 @@ declare class BunCompatiblePTYManager extends EventEmitter {
     private workerPath;
     private env;
     private adapterModules;
+    private _stallDetectionEnabled;
+    private _stallTimeoutMs;
+    private _onStallClassify?;
     constructor(options?: BunPTYManagerOptions);
     private findWorkerPath;
     private startWorker;
@@ -847,6 +955,10 @@ declare class BunCompatiblePTYManager extends EventEmitter {
      * Get all auto-response rules for a session.
      */
     getAutoResponseRules(sessionId: string): Promise<AutoResponseRule[]>;
+    /**
+     * Select a TUI menu option by index (0-based) in a session.
+     */
+    selectMenuOption(id: string, optionIndex: number): Promise<void>;
     /**
      * Clear all auto-response rules for a session.
      */
@@ -869,4 +981,4 @@ declare function isBun(): boolean;
  */
 declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };

package/dist/index.d.ts

@@ -35,6 +35,8 @@ interface SpawnConfig {
     timeout?: number;
     /** Custom adapter configuration */
     adapterConfig?: Record<string, unknown>;
+    /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
+    stallTimeoutMs?: number;
 }
 /**
  * Handle to a running session
@@ -123,6 +125,10 @@ interface AutoResponseRule {
     type: BlockingPromptType;
     /** Response to send automatically */
     response: string;
+    /** How to deliver the response: 'text' writes raw text + CR, 'keys' sends key sequences (default: 'text') */
+    responseType?: 'text' | 'keys';
+    /** Key names to send when responseType is 'keys' (e.g. ['down', 'enter']) */
+    keys?: string[];
     /** Human-readable description of what this does */
     description: string;
     /** Whether this is safe to auto-respond (default: true) */
@@ -139,6 +145,17 @@ interface BlockingPromptInfo {
     instructions?: string;
     url?: string;
 }
+/**
+ * Classification result from external stall analysis
+ */
+interface StallClassification {
+    /** What the external classifier determined */
+    state: 'waiting_for_input' | 'still_working' | 'task_complete' | 'error';
+    /** Description of the detected prompt (for waiting_for_input) */
+    prompt?: string;
+    /** Suggested response to send (for waiting_for_input with auto-respond) */
+    suggestedResponse?: string;
+}
 /**
  * Logger interface (bring your own logger)
  */
@@ -187,6 +204,18 @@ interface PTYManagerConfig {
     logger?: Logger;
     /** Maximum output log lines per session (default: 1000) */
     maxLogLines?: number;
+    /** Enable stall detection (default: false) */
+    stallDetectionEnabled?: boolean;
+    /** Default stall timeout in ms (default: 8000). Can be overridden per-session via SpawnConfig. */
+    stallTimeoutMs?: number;
+    /**
+     * External classification callback invoked when a stall is detected.
+     * Return null or { state: 'still_working' } to reset the timer.
+     * Return { state: 'waiting_for_input', suggestedResponse } to auto-respond.
+     * Return { state: 'task_complete' } to transition session to ready.
+     * Return { state: 'error' } to emit session_error.
+     */
+    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
 }
 /**
  * Configuration for creating an adapter via factory
@@ -246,6 +275,12 @@ interface CLIAdapter {
      * These are applied automatically during startup and execution.
      */
     readonly autoResponseRules?: AutoResponseRule[];
+    /**
+     * Whether this CLI uses TUI menus that require arrow-key navigation.
+     * When true, auto-response rules without an explicit responseType
+     * default to sending Enter via sendKeys instead of writeRaw.
+     */
+    readonly usesTuiMenus?: boolean;
     /**
      * Get the CLI command to execute
      */
@@ -362,6 +397,7 @@ interface PTYSessionEvents {
     question: (question: string) => void;
     exit: (code: number) => void;
     error: (error: Error) => void;
+    stall_detected: (recentOutput: string, stallDurationMs: number) => void;
 }
 /**
  * Special key mappings to escape sequences
@@ -381,9 +417,14 @@ declare class PTYSession extends EventEmitter {
     private logger;
     private sessionRules;
     private _lastBlockingPromptHash;
+    private _stallTimer;
+    private _stallTimeoutMs;
+    private _stallDetectionEnabled;
+    private _lastStallHash;
+    private _stallStartedAt;
     readonly id: string;
     readonly config: SpawnConfig;
-    constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger);
+    constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger, stallDetectionEnabled?: boolean, defaultStallTimeoutMs?: number);
     get status(): SessionStatus;
     get pid(): number | undefined;
     get startedAt(): Date | undefined;
@@ -410,6 +451,37 @@ declare class PTYSession extends EventEmitter {
      * Clear all session auto-response rules.
      */
     clearAutoResponseRules(): void;
+    /**
+     * Start or reset the stall detection timer.
+     * Only active when status is "busy" and stall detection is enabled.
+     */
+    private resetStallTimer;
+    /**
+     * Clear the stall detection timer.
+     */
+    private clearStallTimer;
+    /**
+     * Called when the stall timer fires (no output for stallTimeoutMs).
+     */
+    private onStallTimerFired;
+    /**
+     * Promise-based delay helper.
+     */
+    private delay;
+    /**
+     * Simple string hash for deduplication.
+     */
+    private simpleHash;
+    /**
+     * Strip ANSI codes for stall detection output.
+     * Replaces cursor-forward sequences with spaces first.
+     */
+    private stripAnsiForStall;
+    /**
+     * Handle external stall classification result.
+     * Called by the manager after onStallClassify resolves.
+     */
+    handleStallClassification(classification: StallClassification | null): void;
     /**
      * Start the PTY session
      */
@@ -465,6 +537,16 @@ declare class PTYSession extends EventEmitter {
      * @param keys - Key name(s) to send, e.g. "ctrl+c" or ["up", "up", "enter"]
      */
     sendKeys(keys: string | string[]): void;
+    /**
+     * Select a TUI menu option by index (0-based).
+     * Sends Down arrow `optionIndex` times, then Enter, with 50ms delays.
+     */
+    selectMenuOption(optionIndex: number): Promise<void>;
+    /**
+     * Send a sequence of keys with staggered timing.
+     * Each key is sent 50ms apart using setTimeout to keep the caller synchronous.
+     */
+    private sendKeySequence;
     /**
      * Paste text using bracketed paste mode
      *
@@ -510,6 +592,7 @@ interface PTYManagerEvents {
     blocking_prompt: (session: SessionHandle, promptInfo: BlockingPromptInfo, autoResponded: boolean) => void;
     message: (message: SessionMessage) => void;
     question: (session: SessionHandle, question: string) => void;
+    stall_detected: (session: SessionHandle, recentOutput: string, stallDurationMs: number) => void;
 }
 declare class PTYManager extends EventEmitter {
     private sessions;
@@ -517,6 +600,9 @@ declare class PTYManager extends EventEmitter {
     private maxLogLines;
     private logger;
     readonly adapters: AdapterRegistry;
+    private _stallDetectionEnabled;
+    private _stallTimeoutMs;
+    private _onStallClassify?;
     constructor(config?: PTYManagerConfig);
     /**
      * Register a CLI adapter
@@ -581,6 +667,11 @@ declare class PTYManager extends EventEmitter {
      * Get the underlying PTYSession (for advanced use)
      */
     getSession(sessionId: string): PTYSession | undefined;
+    /**
+     * Configure stall detection at runtime.
+     * Affects newly spawned sessions only — existing sessions keep their config.
+     */
+    configureStallDetection(enabled: boolean, timeoutMs?: number, classify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>): void;
     /**
      * Add an auto-response rule to a session.
      * Session rules are checked before adapter rules.
@@ -622,6 +713,11 @@ declare abstract class BaseCLIAdapter implements CLIAdapter {
      * Subclasses should override this to add CLI-specific rules.
      */
     readonly autoResponseRules: AutoResponseRule[];
+    /**
+     * Whether this CLI uses TUI menus requiring arrow-key navigation.
+     * Defaults to false; coding agent adapters override to true.
+     */
+    readonly usesTuiMenus: boolean;
     abstract getCommand(): string;
     abstract getArgs(config: SpawnConfig): string[];
     abstract getEnv(config: SpawnConfig): Record<string, string>;
@@ -755,6 +851,15 @@ interface BunPTYManagerOptions {
      * Example: ['coding-agent-adapters']
      */
     adapterModules?: string[];
+    /** Enable stall detection (default: false) */
+    stallDetectionEnabled?: boolean;
+    /** Default stall timeout in ms (default: 8000) */
+    stallTimeoutMs?: number;
+    /**
+     * External classification callback invoked when a stall is detected.
+     * The worker emits stall_detected; this callback runs on the parent side.
+     */
+    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
 }
 /**
  * PTY Manager that works with Bun and other non-Node runtimes
@@ -771,6 +876,9 @@ declare class BunCompatiblePTYManager extends EventEmitter {
     private workerPath;
     private env;
     private adapterModules;
+    private _stallDetectionEnabled;
+    private _stallTimeoutMs;
+    private _onStallClassify?;
     constructor(options?: BunPTYManagerOptions);
     private findWorkerPath;
     private startWorker;
@@ -847,6 +955,10 @@ declare class BunCompatiblePTYManager extends EventEmitter {
      * Get all auto-response rules for a session.
      */
     getAutoResponseRules(sessionId: string): Promise<AutoResponseRule[]>;
+    /**
+     * Select a TUI menu option by index (0-based) in a session.
+     */
+    selectMenuOption(id: string, optionIndex: number): Promise<void>;
     /**
      * Clear all auto-response rules for a session.
      */
@@ -869,4 +981,4 @@ declare function isBun(): boolean;
  */
 declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };