pty-manager 1.2.12 → 1.2.14

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
@@ -139,6 +141,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 +200,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
@@ -362,6 +387,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 +407,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 +441,33 @@ 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;
+    /**
+     * 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
      */
@@ -510,6 +568,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 +576,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 +643,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.
@@ -755,6 +822,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 +847,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;
@@ -869,4 +948,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
@@ -139,6 +141,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 +200,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
@@ -362,6 +387,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 +407,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 +441,33 @@ 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;
+    /**
+     * 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
      */
@@ -510,6 +568,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 +576,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 +643,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.
@@ -755,6 +822,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 +847,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;
@@ -869,4 +948,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 };