pty-manager 1.5.0 → 1.6.0

package/README.md

@@ -9,7 +9,7 @@ PTY session manager with lifecycle management, pluggable adapters, and blocking
 - **Blocking prompt detection** - Detect login prompts, confirmations, and interactive prompts
 - **Auto-response rules** - Automatically respond to known prompts with text or key sequences
 - **TUI menu navigation** - Navigate arrow-key menus via `selectMenuOption()` and key-sequence rules
-- **Stall detection** - Content-based stall detection with pluggable external classifiers
+- **Stall detection** - Content-based stall detection with pluggable external classifiers, loading suppression, and exponential backoff
 - **Task completion detection** - Adapter-level fast-path that short-circuits the LLM stall classifier when the CLI returns to its idle prompt
 - **Terminal attachment** - Attach to sessions for raw I/O streaming
 - **Special key support** - Send Ctrl, Alt, Shift, and function key combinations via `sendKeys()`
@@ -136,6 +136,11 @@ class MyCLIAdapter extends BaseCLIAdapter {
     return /done in \d+s/.test(output) && /ready>/.test(output);
   }
 
+  // Optional: detect active loading state (suppresses stall detection)
+  detectLoading(output) {
+    return /processing|loading/i.test(output);
+  }
+
   parseOutput(output) {
     return {
       type: 'response',
@@ -210,6 +215,7 @@ interface SpawnConfig {
   cols?: number;         // Terminal columns (default: 120)
   rows?: number;         // Terminal rows (default: 40)
   timeout?: number;      // Session timeout in ms
+  readySettleMs?: number; // Override adapter's ready settle delay
 }
 ```
 
@@ -457,6 +463,16 @@ class MyCLIAdapter extends BaseCLIAdapter {
 }
 ```
 
+The settle delay can also be overridden per-spawn via `SpawnConfig.readySettleMs`, which takes precedence over the adapter default. This lets orchestrators tune the delay for varying environments (CI, remote containers, local dev) without forking adapters:
+
+```typescript
+const handle = await manager.spawn({
+  name: 'agent',
+  type: 'claude',
+  readySettleMs: 1000, // Slow CI environment — wait longer
+});
+```
+
 ## Stall Detection & Task Completion
 
 Content-based stall detection monitors sessions for output that stops changing. The content hash strips the full buffer first, then slices the last 500 characters of the normalized text — this ensures identical visual content always produces the same hash regardless of how many raw escape sequences surround it. The normalization strips ANSI escape codes, TUI spinner characters, and countdown/duration text (e.g. `8m 17s` → constant) so that live timers and TUI redraws don't perpetually reset the stall timer. All detection work (ready, blocking prompt, login, exit, stall) runs in a deferred `setImmediate()` tick so that node-pty's synchronous data delivery cannot starve the event loop — timers and I/O callbacks always get a chance to run between data bursts. The output buffer is capped at 100 KB to prevent unbounded growth during long tasks.
@@ -510,6 +526,37 @@ The default `BaseCLIAdapter` implementation delegates to `detectReady()`. Coding
 | Codex | `Worked for 1m 05s` separator + `›` prompt |
 | Aider | `Aider is waiting for your input`, mode prompts with edit markers |
 
+### Loading Pattern Suppression
+
+Adapters can implement `detectLoading(output)` to detect when the CLI is actively working — thinking spinners, file reading progress, model streaming indicators. When `detectLoading()` returns `true`, stall detection is suppressed entirely because the agent is provably working, just not producing new visible text.
+
+```typescript
+class MyCLIAdapter extends BaseCLIAdapter {
+  detectLoading(output: string): boolean {
+    // Match loading indicators specific to this CLI
+    return /esc to interrupt/i.test(output) || /Reading \d+ files/i.test(output);
+  }
+}
+```
+
+This avoids unnecessary LLM classifier calls during normal operation and prevents false stall alerts when agents are thinking or reading files.
+
+### Stall Backoff
+
+When the external stall classifier returns `still_working` (or `null`), the next stall check interval doubles exponentially instead of repeating at the base rate. This prevents hammering the classifier every few seconds during long-running tasks.
+
+- Base interval: `stallTimeoutMs` (default: 8000ms)
+- After each `still_working`: interval doubles (8s → 16s → 30s cap)
+- Maximum interval: 30 seconds
+- Reset: backoff resets to the base interval whenever new real content arrives (content hash changes)
+
+```
+First stall check:  8s → classifier says "still_working"
+Second check:      16s → classifier says "still_working"
+Third check:       30s → (capped at 30s)
+New output arrives:     → backoff resets to 8s
+```
+
 ## Blocking Prompt Types
 
 The library recognizes these blocking prompt types:

package/dist/index.d.mts

@@ -37,6 +37,9 @@ interface SpawnConfig {
     adapterConfig?: Record<string, unknown>;
     /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
     stallTimeoutMs?: number;
+    /** Override adapter's readySettleMs for this session.
+     *  Ms of output silence after detectReady match before emitting session_ready. */
+    readySettleMs?: number;
     /** Override or disable specific adapter auto-response rules for this session.
      *  Keys are regex source strings (from rule.pattern.source).
      *  - null value disables that rule entirely
@@ -353,6 +356,15 @@ interface CLIAdapter {
     }>;
     /** Ms of output silence after detectReady match before emitting session_ready (default: 100) */
     readonly readySettleMs?: number;
+    /**
+     * Optional: Detect if the CLI is actively loading/processing (thinking spinner,
+     * file reading, model streaming, etc.). When true, stall detection is suppressed
+     * because the agent is provably working — just not producing new visible text.
+     *
+     * Patterns should match active loading indicators like "esc to interrupt",
+     * "Reading N files", "Waiting for LLM", etc.
+     */
+    detectLoading?(output: string): boolean;
     /**
      * Optional: Get health check command
      */
@@ -446,6 +458,8 @@ declare class PTYSession extends EventEmitter {
     private _lastStallHash;
     private _stallStartedAt;
     private _lastContentHash;
+    private _stallBackoffMs;
+    private static readonly MAX_STALL_BACKOFF_MS;
     private _taskCompleteTimer;
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     private _readySettleTimer;

package/dist/index.d.ts

@@ -37,6 +37,9 @@ interface SpawnConfig {
     adapterConfig?: Record<string, unknown>;
     /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
     stallTimeoutMs?: number;
+    /** Override adapter's readySettleMs for this session.
+     *  Ms of output silence after detectReady match before emitting session_ready. */
+    readySettleMs?: number;
     /** Override or disable specific adapter auto-response rules for this session.
      *  Keys are regex source strings (from rule.pattern.source).
      *  - null value disables that rule entirely
@@ -353,6 +356,15 @@ interface CLIAdapter {
     }>;
     /** Ms of output silence after detectReady match before emitting session_ready (default: 100) */
     readonly readySettleMs?: number;
+    /**
+     * Optional: Detect if the CLI is actively loading/processing (thinking spinner,
+     * file reading, model streaming, etc.). When true, stall detection is suppressed
+     * because the agent is provably working — just not producing new visible text.
+     *
+     * Patterns should match active loading indicators like "esc to interrupt",
+     * "Reading N files", "Waiting for LLM", etc.
+     */
+    detectLoading?(output: string): boolean;
     /**
      * Optional: Get health check command
      */
@@ -446,6 +458,8 @@ declare class PTYSession extends EventEmitter {
     private _lastStallHash;
     private _stallStartedAt;
     private _lastContentHash;
+    private _stallBackoffMs;
+    private static readonly MAX_STALL_BACKOFF_MS;
     private _taskCompleteTimer;
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     private _readySettleTimer;

package/dist/index.js

@@ -315,6 +315,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     this.logger = logger || consoleLogger;
     this._stallDetectionEnabled = stallDetectionEnabled ?? false;
     this._stallTimeoutMs = config.stallTimeoutMs ?? defaultStallTimeoutMs ?? 8e3;
+    this._stallBackoffMs = this._stallTimeoutMs;
     if (config.ruleOverrides) {
       for (const [key, value] of Object.entries(config.ruleOverrides)) {
         if (value === null) {
@@ -344,6 +345,9 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
   _lastStallHash = null;
   _stallStartedAt = null;
   _lastContentHash = null;
+  _stallBackoffMs = 0;
+  // Initialized in constructor from _stallTimeoutMs
+  static MAX_STALL_BACKOFF_MS = 3e4;
   // Task completion detection (idle detection when busy)
   _taskCompleteTimer = null;
   static TASK_COMPLETE_DEBOUNCE_MS = 1500;
@@ -466,6 +470,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     }
     this._stallStartedAt = Date.now();
     this._lastStallHash = null;
+    this._stallBackoffMs = this._stallTimeoutMs;
     this._stallTimer = setTimeout(() => {
       this.onStallTimerFired();
     }, this._stallTimeoutMs);
@@ -480,6 +485,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     }
     this._stallStartedAt = null;
     this._lastContentHash = null;
+    this._stallBackoffMs = this._stallTimeoutMs;
   }
   /**
    * Called when the stall timer fires (no output for stallTimeoutMs).
@@ -488,10 +494,18 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     if (this._status !== "busy" && this._status !== "authenticating") {
       return;
     }
+    if (this.adapter.detectLoading?.(this.outputBuffer)) {
+      this.logger.debug(
+        { sessionId: this.id },
+        "Loading pattern detected \u2014 suppressing stall emission"
+      );
+      this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallBackoffMs);
+      return;
+    }
     const tail = this.outputBuffer.slice(-500);
     const hash = this.simpleHash(tail);
     if (hash === this._lastStallHash) {
-      this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallTimeoutMs);
+      this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallBackoffMs);
       return;
     }
     this._lastStallHash = hash;
@@ -516,7 +530,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       "Stall detected"
     );
     this.emit("stall_detected", recentOutput, stallDurationMs);
-    this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallTimeoutMs);
+    this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallBackoffMs);
   }
   /**
    * Promise-based delay helper.
@@ -563,8 +577,21 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       return;
     }
     if (!classification || classification.state === "still_working") {
+      this._stallBackoffMs = Math.min(
+        this._stallBackoffMs * 2,
+        _PTYSession.MAX_STALL_BACKOFF_MS
+      );
+      this.logger.debug(
+        { sessionId: this.id, nextCheckMs: this._stallBackoffMs },
+        "Still working \u2014 backing off stall check interval"
+      );
       this._lastContentHash = null;
-      this.resetStallTimer();
+      this._lastStallHash = null;
+      if (this._stallTimer) {
+        clearTimeout(this._stallTimer);
+        this._stallTimer = null;
+      }
+      this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallBackoffMs);
       return;
     }
     switch (classification.state) {
@@ -654,7 +681,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     if (this._readySettleTimer) {
       clearTimeout(this._readySettleTimer);
     }
-    const settleMs = this.adapter.readySettleMs ?? 100;
+    const settleMs = this.config.readySettleMs ?? this.adapter.readySettleMs ?? 100;
     this._readySettleTimer = setTimeout(() => {
       this._readySettleTimer = null;
       this._readySettlePending = false;