coding-agent-adapters 0.5.0 → 0.7.0

package/README.md

@@ -44,12 +44,12 @@ session.send('Help me refactor this function to use async/await');
 
 ## Available Adapters
 
-| Adapter | CLI | Type | Input Style | Auto-Response Rules |
-|---------|-----|------|-------------|---------------------|
-| `ClaudeAdapter` | Claude Code | `claude` | TUI menus | 5 rules |
-| `GeminiAdapter` | Gemini CLI | `gemini` | TUI menus | 3 rules |
-| `CodexAdapter` | OpenAI Codex | `codex` | TUI menus | 6 rules |
-| `AiderAdapter` | Aider | `aider` | Text `(Y)es/(N)o` | 17 rules |
+| Adapter | CLI | Type | Input Style | Auto-Response Rules | Ready Settle |
+|---------|-----|------|-------------|---------------------|-------------|
+| `ClaudeAdapter` | Claude Code | `claude` | TUI menus | 5 rules | 500ms |
+| `GeminiAdapter` | Gemini CLI | `gemini` | TUI menus | 3 rules | 300ms |
+| `CodexAdapter` | OpenAI Codex | `codex` | TUI menus | 6 rules | 300ms |
+| `AiderAdapter` | Aider | `aider` | Text `(Y)es/(N)o` | 17 rules | 200ms |
 
 ## Session Lifecycle Detection
 
@@ -83,6 +83,17 @@ Each adapter knows exactly what "ready for input" looks like:
 | Codex | `>` glyph, placeholder suggestions | `chat_composer.rs` |
 | Aider | `ask>`, `code>`, `architect>`, `help>`, `multi>`, startup banner | `io.py`, `base_coder.py` |
 
+### Ready Settle Delay
+
+Each adapter sets `readySettleMs` to control how long pty-manager waits after `detectReady()` matches before emitting `session_ready`. This prevents the orchestrator from sending input while the TUI is still rendering (status bar, shortcuts, update notices). The base default is 300ms; adapters override based on their rendering weight.
+
+| Adapter | `readySettleMs` | Rationale |
+|---------|----------------|-----------|
+| Claude Code | 500ms | Heaviest TUI — status bar, shortcuts, update notices, /ide suggestions |
+| Gemini CLI | 300ms | Moderate Ink TUI (inherits base default) |
+| Codex | 300ms | Moderate Rust TUI (inherits base default) |
+| Aider | 200ms | Minimal TUI, mostly text output |
+
 ### Blocking Prompt Detection
 
 Adapters detect prompts that block the session and require user action:
@@ -94,6 +105,28 @@ Adapters detect prompts that block the session and require user action:
 | Codex | Directory trust, tool approval, update available, model migration, CWD selection |
 | Aider | File operations, shell commands, git init, pip install, destructive operations |
 
+### Loading / Active-Work Detection
+
+Each adapter implements `detectLoading(output)` to detect when the CLI is actively processing — thinking spinners, file reading, model streaming. When loading is detected, pty-manager suppresses stall detection entirely, avoiding unnecessary LLM classifier calls during normal operation.
+
+| Adapter | Loading Indicators | Source Patterns |
+|---------|-------------------|----------------|
+| Claude | `esc to interrupt`, `Reading N files` | `claude_active_reading_files` |
+| Gemini | `esc to cancel`, `Waiting for user confirmation` | `gemini_active_loading_line` |
+| Codex | `esc to interrupt`, `Booting MCP server`, `Searching the web` | `codex_active_status_row`, `codex_active_booting_mcp` |
+| Aider | `Waiting for LLM/<model>`, `Generating commit message with` | `aider_active_waiting_model`, `aider_active_waiting_llm_default` |
+
+```typescript
+const claude = new ClaudeAdapter();
+claude.detectLoading('• Working (5s • esc to interrupt)');  // true
+claude.detectLoading('Reading 42 files…');                   // true
+claude.detectLoading('❯ ');                                  // false
+
+const aider = new AiderAdapter();
+aider.detectLoading('Waiting for claude-sonnet-4-20250514'); // true
+aider.detectLoading('code> ');                                // false
+```
+
 ### Task Completion Detection
 
 Each adapter implements `detectTaskComplete(output)` to recognize when the CLI has finished a task and returned to its idle prompt. This is more specific than `detectReady()` — it matches high-confidence completion indicators (duration summaries, explicit done messages) that short-circuit the LLM stall classifier in pty-manager.
@@ -382,6 +415,9 @@ export class CursorAdapter extends BaseCodingAdapter {
   // Set to false if the CLI uses text prompts instead of TUI menus
   override readonly usesTuiMenus = false;
 
+  // Tune ready settle delay for this CLI's rendering speed (base default: 300ms)
+  override readonly readySettleMs = 250;
+
   readonly autoResponseRules: AutoResponseRule[] = [
     { pattern: /accept terms/i, type: 'tos', response: 'y', responseType: 'text', description: 'Accept TOS', safe: true, once: true },
   ];
@@ -411,6 +447,11 @@ export class CursorAdapter extends BaseCodingAdapter {
     return /cursor>\s*$/m.test(output);
   }
 
+  detectLoading(output: string): boolean {
+    // Active loading indicator — suppresses stall detection
+    return /processing|thinking/i.test(output);
+  }
+
   detectTaskComplete(output: string): boolean {
     // High-confidence: task summary + idle prompt
     return /completed in \d+s/.test(output) && /cursor>\s*$/m.test(output);

package/dist/index.cjs

@@ -368,6 +368,12 @@ var BaseCodingAdapter = class extends ptyManager.BaseCLIAdapter {
    * Coding agent CLIs use TUI menus that require arrow-key navigation.
    */
   usesTuiMenus = true;
+  /**
+   * Ms of output silence after detectReady match before emitting session_ready.
+   * Allows TUI rendering (status bar, shortcuts, update notices) to complete
+   * before the orchestrator sends input.
+   */
+  readySettleMs = 300;
   /**
    * The primary memory file for this CLI (the one it reads for project instructions).
    * Returns the relativePath of the first 'memory' type file from getWorkspaceFiles().
@@ -535,6 +541,8 @@ Docs: ${this.installation.docsUrl}`
 var ClaudeAdapter = class extends BaseCodingAdapter {
   adapterType = "claude";
   displayName = "Claude Code";
+  /** Heaviest TUI — status bar, shortcuts, update notices, /ide suggestions */
+  readySettleMs = 500;
   installation = {
     command: "npm install -g @anthropic-ai/claude-code",
     alternatives: [
@@ -752,6 +760,24 @@ var ClaudeAdapter = class extends BaseCodingAdapter {
     }
     return super.detectBlockingPrompt(output);
   }
+  /**
+   * Detect if Claude Code is actively loading/processing.
+   *
+   * Patterns from: AGENT_LOADING_STATUS_PATTERNS.json
+   *   - claude_active_reading_files: "Reading N files…"
+   *   - General: "esc to interrupt" spinner status line
+   */
+  detectLoading(output) {
+    const stripped = this.stripAnsi(output);
+    const tail = stripped.slice(-500);
+    if (/esc\s+to\s+interrupt/i.test(tail)) {
+      return true;
+    }
+    if (/Reading\s+\d+\s+files/i.test(tail)) {
+      return true;
+    }
+    return false;
+  }
   /**
    * Detect task completion for Claude Code.
    *
@@ -1043,6 +1069,24 @@ var GeminiAdapter = class extends BaseCodingAdapter {
     }
     return super.detectBlockingPrompt(output);
   }
+  /**
+   * Detect if Gemini CLI is actively loading/processing.
+   *
+   * Patterns from: AGENT_LOADING_STATUS_PATTERNS.json
+   *   - gemini_active_loading_line: "(esc to cancel, Xs)"
+   *   - gemini_active_waiting_user_confirmation: "Waiting for user confirmation..."
+   */
+  detectLoading(output) {
+    const stripped = this.stripAnsi(output);
+    const tail = stripped.slice(-500);
+    if (/esc\s+to\s+cancel/i.test(tail)) {
+      return true;
+    }
+    if (/Waiting\s+for\s+user\s+confirmation/i.test(tail)) {
+      return true;
+    }
+    return false;
+  }
   /**
    * Detect task completion for Gemini CLI.
    *
@@ -1379,6 +1423,28 @@ var CodexAdapter = class extends BaseCodingAdapter {
     }
     return super.detectBlockingPrompt(output);
   }
+  /**
+   * Detect if Codex CLI is actively loading/processing.
+   *
+   * Patterns from: AGENT_LOADING_STATUS_PATTERNS.json
+   *   - codex_active_status_row: "• Working (0s • esc to interrupt)"
+   *   - codex_active_booting_mcp: "Booting MCP server: ..."
+   *   - codex_active_web_search: "Searching the web"
+   */
+  detectLoading(output) {
+    const stripped = this.stripAnsi(output);
+    const tail = stripped.slice(-500);
+    if (/esc\s+to\s+interrupt/i.test(tail)) {
+      return true;
+    }
+    if (/Booting\s+MCP\s+server/i.test(tail)) {
+      return true;
+    }
+    if (/Searching\s+the\s+web/i.test(tail)) {
+      return true;
+    }
+    return false;
+  }
   /**
    * Detect task completion for Codex CLI.
    *
@@ -1466,6 +1532,8 @@ var CodexAdapter = class extends BaseCodingAdapter {
 var AiderAdapter = class extends BaseCodingAdapter {
   adapterType = "aider";
   displayName = "Aider";
+  /** Minimal TUI, mostly text output — shorter settle delay */
+  readySettleMs = 200;
   /**
    * Aider uses plain text [y/n] prompts, NOT TUI arrow-key menus.
    */
@@ -1809,6 +1877,25 @@ var AiderAdapter = class extends BaseCodingAdapter {
     }
     return super.detectBlockingPrompt(output);
   }
+  /**
+   * Detect if Aider is actively loading/processing.
+   *
+   * Patterns from: AGENT_LOADING_STATUS_PATTERNS.json
+   *   - aider_active_waiting_model: "Waiting for <model>"
+   *   - aider_active_waiting_llm_default: "Waiting for LLM"
+   *   - aider_active_generating_commit_message: "Generating commit message with ..."
+   */
+  detectLoading(output) {
+    const stripped = this.stripAnsi(output);
+    const tail = stripped.slice(-500);
+    if (/Waiting\s+for\s+(?:LLM|[A-Za-z0-9_./:@-]+)/i.test(tail)) {
+      return true;
+    }
+    if (/Generating\s+commit\s+message\s+with\s+/i.test(tail)) {
+      return true;
+    }
+    return false;
+  }
   /**
    * Detect task completion for Aider.
    *