pty-manager 1.5.0 → 1.6.1

package/README.md

@@ -9,8 +9,8 @@ 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
-- **Task completion detection** - Adapter-level fast-path that short-circuits the LLM stall classifier when the CLI returns to its idle prompt
+- **Stall detection** - Content-based stall detection with pluggable external classifiers, loading suppression, and exponential backoff
+- **Task completion detection** - Settle-based fast-path that short-circuits the LLM stall classifier when the CLI returns to its idle prompt, resilient to decorative TUI rendering after the prompt
 - **Terminal attachment** - Attach to sessions for raw I/O streaming
 - **Special key support** - Send Ctrl, Alt, Shift, and function key combinations via `sendKeys()`
 - **Bracketed paste** - Proper paste handling with bracketed paste mode support
@@ -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,13 +463,27 @@ 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.
+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, carriage returns (`\r`), non-breaking spaces (`\xa0`), TUI spinner characters, and countdown/duration text (e.g. `8m 17s` → constant) so that live timers, TUI line-overwrites, and 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.
+
+### Task Completion Fast-Path (Settle Pattern)
 
-When a stall is detected, the session first tries the adapter's `detectTaskComplete()` fast-path. If the adapter recognizes the output as a completed task (e.g. duration summary + idle prompt), it transitions directly to `ready` and emits `task_complete` — skipping the expensive LLM stall classifier entirely.
+When a busy session's output matches the adapter's `detectReady()` pattern, a `task_complete` debounce timer starts. TUI agents like Claude Code continue rendering decorative output after the prompt — update notices, shortcut hints, status bar updates. Instead of cancelling the timer on each new data chunk (which would prevent the event from ever firing), the session uses a **settle pattern**: the debounce timer resets on each new chunk but is never cancelled. The timer callback re-verifies `detectReady()` before transitioning, so stale triggers are safe.
 
-If the adapter doesn't recognize the output, the session falls back to emitting `stall_detected` for external classification.
+This mirrors the `readySettlePending` pattern used for startup ready detection, and ensures the `task_complete` event fires reliably even when TUI chrome continues rendering after the agent has finished its task.
+
+If the fast-path timer doesn't fire (e.g. the prompt indicator disappears from the buffer), the session falls back to stall detection which emits `stall_detected` for external classification.
 
 ```typescript
 // Enable stall detection with a pluggable classifier
@@ -510,6 +530,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,7 +458,10 @@ declare class PTYSession extends EventEmitter {
     private _lastStallHash;
     private _stallStartedAt;
     private _lastContentHash;
+    private _stallBackoffMs;
+    private static readonly MAX_STALL_BACKOFF_MS;
     private _taskCompleteTimer;
+    private _taskCompletePending;
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     private _readySettleTimer;
     private _readySettlePending;
@@ -522,8 +537,12 @@ declare class PTYSession extends EventEmitter {
     handleStallClassification(classification: StallClassification | null): void;
     /**
      * Schedule a task_complete transition after a debounce period.
-     * If new non-whitespace output arrives before the timer fires,
-     * the timer is cancelled (by cancelTaskComplete in onData).
+     * Uses a settle pattern: each call resets the debounce timer instead of
+     * being a no-op when already scheduled. This allows TUI agents that
+     * continue rendering decorative output (status bar, update notices) after
+     * the prompt to eventually settle, rather than having the timer cancelled
+     * by every new data chunk. The callback re-verifies detectReady() before
+     * transitioning, so stale triggers are safe.
      */
     private scheduleTaskComplete;
     /**

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,7 +458,10 @@ declare class PTYSession extends EventEmitter {
     private _lastStallHash;
     private _stallStartedAt;
     private _lastContentHash;
+    private _stallBackoffMs;
+    private static readonly MAX_STALL_BACKOFF_MS;
     private _taskCompleteTimer;
+    private _taskCompletePending;
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     private _readySettleTimer;
     private _readySettlePending;
@@ -522,8 +537,12 @@ declare class PTYSession extends EventEmitter {
     handleStallClassification(classification: StallClassification | null): void;
     /**
      * Schedule a task_complete transition after a debounce period.
-     * If new non-whitespace output arrives before the timer fires,
-     * the timer is cancelled (by cancelTaskComplete in onData).
+     * Uses a settle pattern: each call resets the debounce timer instead of
+     * being a no-op when already scheduled. This allows TUI agents that
+     * continue rendering decorative output (status bar, update notices) after
+     * the prompt to eventually settle, rather than having the timer cancelled
+     * by every new data chunk. The callback re-verifies detectReady() before
+     * transitioning, so stale triggers are safe.
      */
     private scheduleTaskComplete;
     /**

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,8 +345,12 @@ 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;
+  _taskCompletePending = false;
   static TASK_COMPLETE_DEBOUNCE_MS = 1500;
   // Ready detection settle delay — defers session_ready until output goes quiet
   _readySettleTimer = null;
@@ -466,6 +471,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 +486,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 +495,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 +531,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.
@@ -548,7 +563,8 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     result = result.replace(/\x1b\[\d*(?:;\d+)?[Hf]/g, " ");
     result = result.replace(/\x1b\[\d*[JK]/g, " ");
     result = result.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
-    result = result.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
+    result = result.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+    result = result.replace(/\xa0/g, " ");
     result = result.replace(/[│╭╰╮╯─═╌║╔╗╚╝╠╣╦╩╬┌┐└┘├┤┬┴┼●○❯❮▶◀⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⣾⣽⣻⢿⡿⣟⣯⣷✻✶✳✢⏺←→↑↓⬆⬇◆◇▪▫■□▲△▼▽◈⟨⟩⌘⏎⏏⌫⌦⇧⇪⌥]/g, " ");
     result = result.replace(/\d+[hms](?:\s+\d+[hms])*/g, "0s");
     result = result.replace(/ {2,}/g, " ");
@@ -563,8 +579,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) {
@@ -612,13 +641,21 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
   // ─────────────────────────────────────────────────────────────────────────────
   /**
    * Schedule a task_complete transition after a debounce period.
-   * If new non-whitespace output arrives before the timer fires,
-   * the timer is cancelled (by cancelTaskComplete in onData).
+   * Uses a settle pattern: each call resets the debounce timer instead of
+   * being a no-op when already scheduled. This allows TUI agents that
+   * continue rendering decorative output (status bar, update notices) after
+   * the prompt to eventually settle, rather than having the timer cancelled
+   * by every new data chunk. The callback re-verifies detectReady() before
+   * transitioning, so stale triggers are safe.
    */
   scheduleTaskComplete() {
-    if (this._taskCompleteTimer) return;
+    if (this._taskCompleteTimer) {
+      clearTimeout(this._taskCompleteTimer);
+    }
+    this._taskCompletePending = true;
     this._taskCompleteTimer = setTimeout(() => {
       this._taskCompleteTimer = null;
+      this._taskCompletePending = false;
       if (this._status !== "busy") return;
       if (!this.adapter.detectReady(this.outputBuffer)) return;
       this._status = "ready";
@@ -639,6 +676,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       clearTimeout(this._taskCompleteTimer);
       this._taskCompleteTimer = null;
     }
+    this._taskCompletePending = false;
   }
   // ─────────────────────────────────────────────────────────────────────────────
   // Ready Detection Settle Delay
@@ -654,7 +692,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;
@@ -780,10 +818,10 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       this.scheduleReadySettle();
       return;
     }
-    if (this._status === "busy" && this.adapter.detectReady(this.outputBuffer)) {
-      this.scheduleTaskComplete();
-    } else {
-      this.cancelTaskComplete();
+    if (this._status === "busy") {
+      if (this._taskCompletePending || this.adapter.detectReady(this.outputBuffer)) {
+        this.scheduleTaskComplete();
+      }
     }
     const blockingPrompt = this.detectAndHandleBlockingPrompt();
     if (blockingPrompt) {