pty-manager 1.2.21 → 1.3.0

package/README.md

@@ -10,6 +10,7 @@ PTY session manager with lifecycle management, pluggable adapters, and blocking
 - **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
 - **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
@@ -130,6 +131,11 @@ class MyCLIAdapter extends BaseCLIAdapter {
     return /ready>/.test(output);
   }
 
+  // Optional: high-confidence task completion detection
+  detectTaskComplete(output) {
+    return /done in \d+s/.test(output) && /ready>/.test(output);
+  }
+
   parseOutput(output) {
     return {
       type: 'response',
@@ -189,6 +195,8 @@ class PTYManager extends EventEmitter {
 | `blocking_prompt` | `SessionHandle, promptInfo, autoResponded` | Prompt detected |
 | `message` | `SessionMessage` | Parsed message received |
 | `question` | `SessionHandle, question` | Question detected |
+| `stall_detected` | `SessionHandle, recentOutput, stallDurationMs` | Output stalled, needs classification |
+| `task_complete` | `SessionHandle` | Agent finished task, returned to idle |
 
 ### SpawnConfig
 
@@ -435,9 +443,11 @@ Adapters can declare `usesTuiMenus: true` to indicate they use arrow-key menus i
 await session.selectMenuOption(2);  // Sends Down, Down, Enter with 50ms delays
 ```
 
-## Stall Detection
+## Stall Detection & Task Completion
 
-Content-based stall detection monitors sessions for output that stops changing. When a stall is detected, the session emits a `stall_detected` event with the buffered output for external classification.
+Content-based stall detection monitors sessions for output that stops changing. 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.
+
+If the adapter doesn't recognize the output, the session falls back to emitting `stall_detected` for external classification.
 
 ```typescript
 // Enable stall detection with a pluggable classifier
@@ -460,6 +470,30 @@ const session = await manager.spawn({
 });
 ```
 
+### Adapter-Level Task Completion (Fast Path)
+
+Adapters can implement `detectTaskComplete(output)` to recognize high-confidence completion patterns specific to their CLI. This avoids the latency and cost of an LLM classifier call.
+
+```typescript
+class MyCLIAdapter extends BaseCLIAdapter {
+  // ...
+
+  detectTaskComplete(output: string): boolean {
+    // Match CLI-specific patterns that indicate work is done
+    return /completed in \d+s/.test(output) && /my-cli>/.test(output);
+  }
+}
+```
+
+The default `BaseCLIAdapter` implementation delegates to `detectReady()`. Coding agent adapters override this with CLI-specific patterns:
+
+| Adapter | Completion Indicators |
+|---------|----------------------|
+| Claude Code | Turn duration (`Cooked for 3m 12s`) + `❯` prompt |
+| Gemini CLI | `◇ Ready` window title, `Type your message` composer |
+| Codex | `Worked for 1m 05s` separator + `›` prompt |
+| Aider | `Aider is waiting for your input`, mode prompts with edit markers |
+
 ## Blocking Prompt Types
 
 The library recognizes these blocking prompt types:

package/dist/index.d.mts

@@ -334,6 +334,15 @@ interface CLIAdapter {
      * Get prompt pattern to detect when CLI is waiting for input
      */
     getPromptPattern(): RegExp;
+    /**
+     * Optional: Detect if the CLI has completed a task and returned to its idle prompt.
+     * More specific than detectReady — matches high-confidence completion indicators
+     * (e.g. duration summaries, explicit "done" messages) alongside the idle prompt.
+     *
+     * Used as a fast-path in stall detection to avoid expensive LLM classifier calls.
+     * If not implemented, the stall classifier is used as the fallback.
+     */
+    detectTaskComplete?(output: string): boolean;
     /**
      * Optional: Validate that the CLI is installed and accessible
      */
@@ -405,6 +414,8 @@ interface PTYSessionEvents {
     exit: (code: number) => void;
     error: (error: Error) => void;
     stall_detected: (recentOutput: string, stallDurationMs: number) => void;
+    status_changed: (status: SessionStatus) => void;
+    task_complete: () => void;
 }
 /**
  * Special key mappings to escape sequences
@@ -433,6 +444,8 @@ declare class PTYSession extends EventEmitter {
     private _lastStallHash;
     private _stallStartedAt;
     private _lastContentHash;
+    private _taskCompleteTimer;
+    private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     readonly id: string;
     readonly config: SpawnConfig;
     constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger, stallDetectionEnabled?: boolean, defaultStallTimeoutMs?: number);
@@ -501,6 +514,17 @@ declare class PTYSession extends EventEmitter {
      * Called by the manager after onStallClassify resolves.
      */
     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).
+     */
+    private scheduleTaskComplete;
+    /**
+     * Cancel a pending task_complete timer (new output arrived that
+     * doesn't match the idle prompt, so the agent is still working).
+     */
+    private cancelTaskComplete;
     /**
      * Start the PTY session
      */
@@ -612,6 +636,8 @@ interface PTYManagerEvents {
     message: (message: SessionMessage) => void;
     question: (session: SessionHandle, question: string) => void;
     stall_detected: (session: SessionHandle, recentOutput: string, stallDurationMs: number) => void;
+    session_status_changed: (session: SessionHandle) => void;
+    task_complete: (session: SessionHandle) => void;
 }
 declare class PTYManager extends EventEmitter {
     private sessions;
@@ -757,6 +783,12 @@ declare abstract class BaseCLIAdapter implements CLIAdapter {
      * Subclasses should override for CLI-specific detection.
      */
     detectBlockingPrompt(output: string): BlockingPromptDetection;
+    /**
+     * Default task completion detection — delegates to detectReady().
+     * Subclasses should override to match high-confidence completion patterns
+     * (e.g. duration summaries) that short-circuit the LLM stall classifier.
+     */
+    detectTaskComplete(output: string): boolean;
     /**
      * Default input formatting - just return as-is
      */

package/dist/index.d.ts

@@ -334,6 +334,15 @@ interface CLIAdapter {
      * Get prompt pattern to detect when CLI is waiting for input
      */
     getPromptPattern(): RegExp;
+    /**
+     * Optional: Detect if the CLI has completed a task and returned to its idle prompt.
+     * More specific than detectReady — matches high-confidence completion indicators
+     * (e.g. duration summaries, explicit "done" messages) alongside the idle prompt.
+     *
+     * Used as a fast-path in stall detection to avoid expensive LLM classifier calls.
+     * If not implemented, the stall classifier is used as the fallback.
+     */
+    detectTaskComplete?(output: string): boolean;
     /**
      * Optional: Validate that the CLI is installed and accessible
      */
@@ -405,6 +414,8 @@ interface PTYSessionEvents {
     exit: (code: number) => void;
     error: (error: Error) => void;
     stall_detected: (recentOutput: string, stallDurationMs: number) => void;
+    status_changed: (status: SessionStatus) => void;
+    task_complete: () => void;
 }
 /**
  * Special key mappings to escape sequences
@@ -433,6 +444,8 @@ declare class PTYSession extends EventEmitter {
     private _lastStallHash;
     private _stallStartedAt;
     private _lastContentHash;
+    private _taskCompleteTimer;
+    private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     readonly id: string;
     readonly config: SpawnConfig;
     constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger, stallDetectionEnabled?: boolean, defaultStallTimeoutMs?: number);
@@ -501,6 +514,17 @@ declare class PTYSession extends EventEmitter {
      * Called by the manager after onStallClassify resolves.
      */
     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).
+     */
+    private scheduleTaskComplete;
+    /**
+     * Cancel a pending task_complete timer (new output arrived that
+     * doesn't match the idle prompt, so the agent is still working).
+     */
+    private cancelTaskComplete;
     /**
      * Start the PTY session
      */
@@ -612,6 +636,8 @@ interface PTYManagerEvents {
     message: (message: SessionMessage) => void;
     question: (session: SessionHandle, question: string) => void;
     stall_detected: (session: SessionHandle, recentOutput: string, stallDurationMs: number) => void;
+    session_status_changed: (session: SessionHandle) => void;
+    task_complete: (session: SessionHandle) => void;
 }
 declare class PTYManager extends EventEmitter {
     private sessions;
@@ -757,6 +783,12 @@ declare abstract class BaseCLIAdapter implements CLIAdapter {
      * Subclasses should override for CLI-specific detection.
      */
     detectBlockingPrompt(output: string): BlockingPromptDetection;
+    /**
+     * Default task completion detection — delegates to detectReady().
+     * Subclasses should override to match high-confidence completion patterns
+     * (e.g. duration summaries) that short-circuit the LLM stall classifier.
+     */
+    detectTaskComplete(output: string): boolean;
     /**
      * Default input formatting - just return as-is
      */

package/dist/index.js

@@ -306,7 +306,7 @@ var SPECIAL_KEYS = {
 };
 var BRACKETED_PASTE_START = "\x1B[200~";
 var BRACKETED_PASTE_END = "\x1B[201~";
-var PTYSession = class extends import_events.EventEmitter {
+var PTYSession = class _PTYSession extends import_events.EventEmitter {
   constructor(adapter, config, logger, stallDetectionEnabled, defaultStallTimeoutMs) {
     super();
     this.adapter = adapter;
@@ -344,6 +344,9 @@ var PTYSession = class extends import_events.EventEmitter {
   _lastStallHash = null;
   _stallStartedAt = null;
   _lastContentHash = null;
+  // Task completion detection (idle detection when busy)
+  _taskCompleteTimer = null;
+  static TASK_COMPLETE_DEBOUNCE_MS = 1500;
   id;
   config;
   get status() {
@@ -483,6 +486,19 @@ var PTYSession = class extends import_events.EventEmitter {
       return;
     }
     this._lastStallHash = hash;
+    if (this._status === "busy" && this.adapter.detectTaskComplete?.(this.outputBuffer)) {
+      this._status = "ready";
+      this._lastBlockingPromptHash = null;
+      this.outputBuffer = "";
+      this.clearStallTimer();
+      this.emit("status_changed", "ready");
+      this.emit("task_complete");
+      this.logger.info(
+        { sessionId: this.id },
+        "Task complete (adapter fast-path) \u2014 agent returned to idle prompt"
+      );
+      return;
+    }
     const recentRaw = this.outputBuffer.slice(-2e3);
     const recentOutput = this.stripAnsiForStall(recentRaw);
     const stallDurationMs = this._stallStartedAt ? Date.now() - this._stallStartedAt : this._stallTimeoutMs;
@@ -519,10 +535,12 @@ var PTYSession = class extends import_events.EventEmitter {
    * word boundaries — e.g. "Do\x1b[5Cyou" becomes "Do you", not "Doyou".
    */
   stripAnsiForStall(str) {
-    let result = str.replace(/\x1b\[\d*[CDABG]/g, " ");
+    let result = str.replace(/\x1b\[\d*[CDABGdEF]/g, " ");
     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(/[│╭╰╮╯─═╌║╔╗╚╝╠╣╦╩╬┌┐└┘├┤┬┴┼●○❯❮▶◀⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⣾⣽⣻⢿⡿⣟⣯⣷✻✶✳✢⏺←→↑↓]/g, " ");
+    result = result.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
+    result = result.replace(/[│╭╰╮╯─═╌║╔╗╚╝╠╣╦╩╬┌┐└┘├┤┬┴┼●○❯❮▶◀⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⣾⣽⣻⢿⡿⣟⣯⣷✻✶✳✢⏺←→↑↓⬆⬇◆◇▪▫■□▲△▼▽◈⟨⟩⌘⏎⏏⌫⌦⇧⇪⌥]/g, " ");
     result = result.replace(/ {2,}/g, " ");
     return result;
   }
@@ -580,6 +598,39 @@ var PTYSession = class extends import_events.EventEmitter {
     }
   }
   // ─────────────────────────────────────────────────────────────────────────────
+  // Task Completion Detection
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * 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).
+   */
+  scheduleTaskComplete() {
+    if (this._taskCompleteTimer) return;
+    this._taskCompleteTimer = setTimeout(() => {
+      this._taskCompleteTimer = null;
+      if (this._status !== "busy") return;
+      if (!this.adapter.detectReady(this.outputBuffer)) return;
+      this._status = "ready";
+      this._lastBlockingPromptHash = null;
+      this.outputBuffer = "";
+      this.clearStallTimer();
+      this.emit("status_changed", "ready");
+      this.emit("task_complete");
+      this.logger.info({ sessionId: this.id }, "Task complete \u2014 agent returned to idle prompt");
+    }, _PTYSession.TASK_COMPLETE_DEBOUNCE_MS);
+  }
+  /**
+   * Cancel a pending task_complete timer (new output arrived that
+   * doesn't match the idle prompt, so the agent is still working).
+   */
+  cancelTaskComplete() {
+    if (this._taskCompleteTimer) {
+      clearTimeout(this._taskCompleteTimer);
+      this._taskCompleteTimer = null;
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
   // Lifecycle
   // ─────────────────────────────────────────────────────────────────────────────
   /**
@@ -641,10 +692,6 @@ var PTYSession = class extends import_events.EventEmitter {
         this.resetStallTimer();
       }
       this.emit("output", data);
-      const blockingPrompt = this.detectAndHandleBlockingPrompt();
-      if (blockingPrompt) {
-        return;
-      }
       if ((this._status === "starting" || this._status === "authenticating") && this.adapter.detectReady(this.outputBuffer)) {
         this._status = "ready";
         this._lastBlockingPromptHash = null;
@@ -654,6 +701,15 @@ var PTYSession = class extends import_events.EventEmitter {
         this.logger.info({ sessionId: this.id }, "Session ready");
         return;
       }
+      if (this._status === "busy" && this.adapter.detectReady(this.outputBuffer)) {
+        this.scheduleTaskComplete();
+      } else {
+        this.cancelTaskComplete();
+      }
+      const blockingPrompt = this.detectAndHandleBlockingPrompt();
+      if (blockingPrompt) {
+        return;
+      }
       if (this._status !== "ready" && this._status !== "busy") {
         const loginDetection = this.adapter.detectLogin(this.outputBuffer);
         if (loginDetection.required && this._status !== "authenticating") {
@@ -876,6 +932,7 @@ var PTYSession = class extends import_events.EventEmitter {
    */
   send(message) {
     this._status = "busy";
+    this.emit("status_changed", "busy");
     this.resetStallTimer();
     const msg = {
       id: `${this.id}-msg-${++this.messageCounter}`,
@@ -986,6 +1043,7 @@ var PTYSession = class extends import_events.EventEmitter {
     if (this.ptyProcess) {
       this._status = "stopping";
       this.clearStallTimer();
+      this.cancelTaskComplete();
       this.ptyProcess.kill(signal);
       this.logger.info({ sessionId: this.id, signal }, "Killing PTY session");
     }
@@ -1139,6 +1197,12 @@ var PTYManager = class extends import_events2.EventEmitter {
     session.on("error", (error) => {
       this.emit("session_error", session.toHandle(), error.message);
     });
+    session.on("status_changed", () => {
+      this.emit("session_status_changed", session.toHandle());
+    });
+    session.on("task_complete", () => {
+      this.emit("task_complete", session.toHandle());
+    });
     session.on("stall_detected", (recentOutput, stallDurationMs) => {
       const handle = session.toHandle();
       this.emit("stall_detected", handle, recentOutput, stallDurationMs);
@@ -1543,6 +1607,14 @@ var BaseCLIAdapter = class {
     }
     return { detected: false };
   }
+  /**
+   * Default task completion detection — delegates to detectReady().
+   * Subclasses should override to match high-confidence completion patterns
+   * (e.g. duration summaries) that short-circuit the LLM stall classifier.
+   */
+  detectTaskComplete(output) {
+    return this.detectReady(output);
+  }
   /**
    * Default input formatting - just return as-is
    */
@@ -1992,6 +2064,24 @@ var BunCompatiblePTYManager = class extends import_events3.EventEmitter {
         }
         break;
       }
+      case "status_changed": {
+        const session = this.sessions.get(id);
+        if (session) {
+          session.status = event.status;
+          session.lastActivityAt = /* @__PURE__ */ new Date();
+          this.emit("session_status_changed", session);
+        }
+        break;
+      }
+      case "task_complete": {
+        const session = this.sessions.get(id);
+        if (session) {
+          session.status = "ready";
+          session.lastActivityAt = /* @__PURE__ */ new Date();
+          this.emit("task_complete", session);
+        }
+        break;
+      }
       case "stall_detected": {
         const session = this.sessions.get(id);
         if (session) {