pty-manager 1.4.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',
@@ -188,7 +193,7 @@ class PTYManager extends EventEmitter {
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `session_started` | `SessionHandle` | Session spawn initiated |
-| `session_ready` | `SessionHandle` | Session ready for input |
+| `session_ready` | `SessionHandle` | Session ready for input (after settle delay) |
 | `session_stopped` | `SessionHandle, reason` | Session terminated |
 | `session_error` | `SessionHandle, error` | Error occurred |
 | `login_required` | `SessionHandle, instructions?, url?` | Auth required |
@@ -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
 }
 ```
 
@@ -443,6 +449,30 @@ Adapters can declare `usesTuiMenus: true` to indicate they use arrow-key menus i
 await session.selectMenuOption(2);  // Sends Down, Down, Enter with 50ms delays
 ```
 
+## Ready Detection Settle Delay
+
+When an adapter's `detectReady()` first matches during startup, `session_ready` is **not** emitted immediately. Instead, the session waits for output to go quiet for `readySettleMs` (default: 100ms) before firing the event. This prevents the orchestrator from sending input while a TUI agent is still rendering (status bar, keyboard shortcuts, update notices).
+
+Adapters can override `readySettleMs` to tune the delay for their CLI's rendering speed. If new output arrives during the settle window, the timer resets. If the ready indicator disappears (e.g. a blocking prompt appears), the settle is cancelled.
+
+```typescript
+class MyCLIAdapter extends BaseCLIAdapter {
+  // Heavy TUI rendering — wait longer before declaring ready
+  readonly readySettleMs = 500;
+  // ...
+}
+```
+
+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.
@@ -496,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
@@ -351,6 +354,17 @@ interface CLIAdapter {
         version?: string;
         error?: string;
     }>;
+    /** 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
      */
@@ -444,8 +458,12 @@ 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;
+    private _readySettlePending;
     private _processScheduled;
     private static readonly MAX_OUTPUT_BUFFER;
     readonly id: string;
@@ -527,6 +545,18 @@ declare class PTYSession extends EventEmitter {
      * doesn't match the idle prompt, so the agent is still working).
      */
     private cancelTaskComplete;
+    /**
+     * Schedule or reset the ready-settle timer.
+     * Defers emitting session_ready until output goes quiet for readySettleMs
+     * after detectReady first matches. This prevents sending input while
+     * TUI agents are still rendering (status bar, shortcuts, update notices).
+     */
+    private scheduleReadySettle;
+    /**
+     * Cancel a pending ready-settle timer (ready indicator disappeared
+     * or session status changed).
+     */
+    private cancelReadySettle;
     /**
      * Start the PTY session
      */

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
@@ -351,6 +354,17 @@ interface CLIAdapter {
         version?: string;
         error?: string;
     }>;
+    /** 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
      */
@@ -444,8 +458,12 @@ 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;
+    private _readySettlePending;
     private _processScheduled;
     private static readonly MAX_OUTPUT_BUFFER;
     readonly id: string;
@@ -527,6 +545,18 @@ declare class PTYSession extends EventEmitter {
      * doesn't match the idle prompt, so the agent is still working).
      */
     private cancelTaskComplete;
+    /**
+     * Schedule or reset the ready-settle timer.
+     * Defers emitting session_ready until output goes quiet for readySettleMs
+     * after detectReady first matches. This prevents sending input while
+     * TUI agents are still rendering (status bar, shortcuts, update notices).
+     */
+    private scheduleReadySettle;
+    /**
+     * Cancel a pending ready-settle timer (ready indicator disappeared
+     * or session status changed).
+     */
+    private cancelReadySettle;
     /**
      * Start the PTY session
      */

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,9 +345,15 @@ 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;
+  // Ready detection settle delay — defers session_ready until output goes quiet
+  _readySettleTimer = null;
+  _readySettlePending = false;
   // Deferred output processing — prevents node-pty's synchronous data
   // delivery from starving the event loop (timers, I/O callbacks, etc.)
   _processScheduled = false;
@@ -463,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);
@@ -477,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).
@@ -485,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;
@@ -513,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.
@@ -560,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) {
@@ -638,6 +668,45 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     }
   }
   // ─────────────────────────────────────────────────────────────────────────────
+  // Ready Detection Settle Delay
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Schedule or reset the ready-settle timer.
+   * Defers emitting session_ready until output goes quiet for readySettleMs
+   * after detectReady first matches. This prevents sending input while
+   * TUI agents are still rendering (status bar, shortcuts, update notices).
+   */
+  scheduleReadySettle() {
+    this._readySettlePending = true;
+    if (this._readySettleTimer) {
+      clearTimeout(this._readySettleTimer);
+    }
+    const settleMs = this.config.readySettleMs ?? this.adapter.readySettleMs ?? 100;
+    this._readySettleTimer = setTimeout(() => {
+      this._readySettleTimer = null;
+      this._readySettlePending = false;
+      if (this._status !== "starting" && this._status !== "authenticating") return;
+      if (!this.adapter.detectReady(this.outputBuffer)) return;
+      this._status = "ready";
+      this._lastBlockingPromptHash = null;
+      this.outputBuffer = "";
+      this.clearStallTimer();
+      this.emit("ready");
+      this.logger.info({ sessionId: this.id }, "Session ready (after settle)");
+    }, settleMs);
+  }
+  /**
+   * Cancel a pending ready-settle timer (ready indicator disappeared
+   * or session status changed).
+   */
+  cancelReadySettle() {
+    if (this._readySettleTimer) {
+      clearTimeout(this._readySettleTimer);
+      this._readySettleTimer = null;
+    }
+    this._readySettlePending = false;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
   // Lifecycle
   // ─────────────────────────────────────────────────────────────────────────────
   /**
@@ -726,13 +795,16 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     if (this._status === "busy" || this._status === "authenticating") {
       this.resetStallTimer();
     }
+    if (this._readySettlePending) {
+      if ((this._status === "starting" || this._status === "authenticating") && this.adapter.detectReady(this.outputBuffer)) {
+        this.scheduleReadySettle();
+      } else {
+        this.cancelReadySettle();
+      }
+      return;
+    }
     if ((this._status === "starting" || this._status === "authenticating") && this.adapter.detectReady(this.outputBuffer)) {
-      this._status = "ready";
-      this._lastBlockingPromptHash = null;
-      this.outputBuffer = "";
-      this.clearStallTimer();
-      this.emit("ready");
-      this.logger.info({ sessionId: this.id }, "Session ready");
+      this.scheduleReadySettle();
       return;
     }
     if (this._status === "busy" && this.adapter.detectReady(this.outputBuffer)) {
@@ -1068,6 +1140,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       this._status = "stopping";
       this.clearStallTimer();
       this.cancelTaskComplete();
+      this.cancelReadySettle();
       this.ptyProcess.kill(signal);
       this.logger.info({ sessionId: this.id, signal }, "Killing PTY session");
     }