pty-manager 1.3.3 → 1.5.0

package/README.md

@@ -188,7 +188,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 |
@@ -443,6 +443,20 @@ 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;
+  // ...
+}
+```
+
 ## 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.

package/dist/index.d.mts

@@ -98,7 +98,7 @@ interface LoginDetection {
 /**
  * Types of blocking prompts that can occur
  */
-type BlockingPromptType = 'login' | 'update' | 'config' | 'tos' | 'model_select' | 'project_select' | 'permission' | 'unknown';
+type BlockingPromptType = 'login' | 'update' | 'config' | 'tos' | 'model_select' | 'project_select' | 'permission' | 'tool_wait' | 'unknown';
 /**
  * Blocking prompt detection result
  */
@@ -351,6 +351,8 @@ interface CLIAdapter {
         version?: string;
         error?: string;
     }>;
+    /** Ms of output silence after detectReady match before emitting session_ready (default: 100) */
+    readonly readySettleMs?: number;
     /**
      * Optional: Get health check command
      */
@@ -446,6 +448,8 @@ declare class PTYSession extends EventEmitter {
     private _lastContentHash;
     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 +531,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

@@ -98,7 +98,7 @@ interface LoginDetection {
 /**
  * Types of blocking prompts that can occur
  */
-type BlockingPromptType = 'login' | 'update' | 'config' | 'tos' | 'model_select' | 'project_select' | 'permission' | 'unknown';
+type BlockingPromptType = 'login' | 'update' | 'config' | 'tos' | 'model_select' | 'project_select' | 'permission' | 'tool_wait' | 'unknown';
 /**
  * Blocking prompt detection result
  */
@@ -351,6 +351,8 @@ interface CLIAdapter {
         version?: string;
         error?: string;
     }>;
+    /** Ms of output silence after detectReady match before emitting session_ready (default: 100) */
+    readonly readySettleMs?: number;
     /**
      * Optional: Get health check command
      */
@@ -446,6 +448,8 @@ declare class PTYSession extends EventEmitter {
     private _lastContentHash;
     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 +531,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

@@ -347,6 +347,9 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
   // 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;
@@ -638,6 +641,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.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 +768,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 +1113,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");
     }