pty-manager 1.2.22 → 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
      */
@@ -774,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
      */
@@ -774,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

@@ -486,6 +486,19 @@ var PTYSession = class _PTYSession 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;
@@ -1594,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
    */