pty-manager 1.2.19 → 1.2.21

package/README.md

@@ -7,7 +7,9 @@ PTY session manager with lifecycle management, pluggable adapters, and blocking
 - **Multi-session management** - Spawn and manage multiple PTY sessions concurrently
 - **Pluggable adapters** - Built-in shell adapter, easy to create custom adapters for Docker, SSH, or any CLI tool
 - **Blocking prompt detection** - Detect login prompts, confirmations, and interactive prompts
-- **Auto-response rules** - Automatically respond to known 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
 - **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
@@ -366,6 +368,9 @@ Commands (stdin → worker):
 - `{ "cmd": "spawn", "id": "...", "config": {...} }`
 - `{ "cmd": "send", "id": "...", "data": "..." }`
 - `{ "cmd": "sendKeys", "id": "...", "keys": ["ctrl+c"] }`
+- `{ "cmd": "selectMenuOption", "id": "...", "optionIndex": 2 }`
+- `{ "cmd": "addRules", "id": "...", "rules": [...] }`
+- `{ "cmd": "clearRules", "id": "..." }`
 - `{ "cmd": "kill", "id": "..." }`
 - `{ "cmd": "list" }`
 - `{ "cmd": "shutdown" }`
@@ -374,6 +379,8 @@ Events (worker → stdout):
 - `{ "event": "output", "id": "...", "data": "..." }`
 - `{ "event": "ready", "id": "..." }`
 - `{ "event": "exit", "id": "...", "code": 0 }`
+- `{ "event": "blocking_prompt", "id": "...", "promptInfo": {...}, "autoResponded": true }`
+- `{ "event": "login_required", "id": "...", "instructions": "..." }`
 
 ## Built-in Adapters
 
@@ -390,6 +397,69 @@ const adapter = new ShellAdapter({
 });
 ```
 
+## Auto-Response Rules
+
+Auto-response rules let adapters automatically handle known prompts. Rules support two response modes: **text** (for traditional `[y/n]` prompts) and **keys** (for TUI arrow-key menus).
+
+```typescript
+interface AutoResponseRule {
+  pattern: RegExp;              // Pattern to match in output
+  type: BlockingPromptType;     // Prompt category
+  response: string;             // Text to send (for responseType: 'text')
+  responseType?: 'text' | 'keys';  // How to deliver (default: 'text')
+  keys?: string[];              // Key names for responseType: 'keys'
+  description: string;          // Human-readable description
+  safe?: boolean;               // Whether safe to auto-respond (default: true)
+  once?: boolean;               // Fire at most once per session
+}
+```
+
+**Text response** — sends `response + '\r'` via raw write (for CLIs like Aider that use `[y/n]` prompts):
+
+```typescript
+{ pattern: /create new file\?/i, type: 'permission', response: 'y', responseType: 'text', description: 'Allow file creation', safe: true }
+```
+
+**Key sequence response** — sends key presses via `sendKeys()` (for TUI menus in Codex, Gemini, Claude):
+
+```typescript
+{ pattern: /update available/i, type: 'config', response: '', responseType: 'keys', keys: ['down', 'enter'], description: 'Skip update (select second option)', safe: true, once: true }
+```
+
+### TUI Menu Navigation
+
+Adapters can declare `usesTuiMenus: true` to indicate they use arrow-key menus instead of text prompts. When set, rules without an explicit `responseType` default to sending Enter via `sendKeys()` instead of raw text.
+
+```typescript
+// Navigate to the Nth option in a TUI menu (0-indexed)
+await session.selectMenuOption(2);  // Sends Down, Down, Enter with 50ms delays
+```
+
+## Stall Detection
+
+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.
+
+```typescript
+// Enable stall detection with a pluggable classifier
+const session = await manager.spawn({
+  name: 'agent',
+  type: 'claude',
+  stallDetection: {
+    enabled: true,
+    timeoutMs: 15000,
+    classify: async (output, stallDurationMs) => {
+      // Use an LLM or heuristics to classify the stalled output
+      return {
+        type: 'blocking_prompt',
+        confidence: 0.9,
+        suggestedResponse: 'keys:enter',  // or plain text like 'y'
+        reasoning: 'Trust folder dialog detected',
+      };
+    },
+  },
+});
+```
+
 ## Blocking Prompt Types
 
 The library recognizes these blocking prompt types:

package/dist/index.d.mts

@@ -37,6 +37,11 @@ interface SpawnConfig {
     adapterConfig?: Record<string, unknown>;
     /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
     stallTimeoutMs?: 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
+     *  - Object value merges fields into the matching adapter rule */
+    ruleOverrides?: Record<string, Partial<Omit<AutoResponseRule, 'pattern'>> | null>;
 }
 /**
  * Handle to a running session
@@ -420,6 +425,8 @@ declare class PTYSession extends EventEmitter {
     private sessionRules;
     private _firedOnceRules;
     private _lastBlockingPromptHash;
+    private _ruleOverrides;
+    private _disabledRulePatterns;
     private _stallTimer;
     private _stallTimeoutMs;
     private _stallDetectionEnabled;

package/dist/index.d.ts

@@ -37,6 +37,11 @@ interface SpawnConfig {
     adapterConfig?: Record<string, unknown>;
     /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
     stallTimeoutMs?: 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
+     *  - Object value merges fields into the matching adapter rule */
+    ruleOverrides?: Record<string, Partial<Omit<AutoResponseRule, 'pattern'>> | null>;
 }
 /**
  * Handle to a running session
@@ -420,6 +425,8 @@ declare class PTYSession extends EventEmitter {
     private sessionRules;
     private _firedOnceRules;
     private _lastBlockingPromptHash;
+    private _ruleOverrides;
+    private _disabledRulePatterns;
     private _stallTimer;
     private _stallTimeoutMs;
     private _stallDetectionEnabled;

package/dist/index.js

@@ -315,6 +315,15 @@ var PTYSession = class extends import_events.EventEmitter {
     this.logger = logger || consoleLogger;
     this._stallDetectionEnabled = stallDetectionEnabled ?? false;
     this._stallTimeoutMs = config.stallTimeoutMs ?? defaultStallTimeoutMs ?? 8e3;
+    if (config.ruleOverrides) {
+      for (const [key, value] of Object.entries(config.ruleOverrides)) {
+        if (value === null) {
+          this._disabledRulePatterns.add(key);
+        } else {
+          this._ruleOverrides.set(key, value);
+        }
+      }
+    }
   }
   ptyProcess = null;
   outputBuffer = "";
@@ -326,6 +335,8 @@ var PTYSession = class extends import_events.EventEmitter {
   sessionRules = [];
   _firedOnceRules = /* @__PURE__ */ new Set();
   _lastBlockingPromptHash = null;
+  _ruleOverrides = /* @__PURE__ */ new Map();
+  _disabledRulePatterns = /* @__PURE__ */ new Set();
   // Stall detection
   _stallTimer = null;
   _stallTimeoutMs;
@@ -548,6 +559,7 @@ var PTYSession = class extends import_events.EventEmitter {
             this.writeRaw(resp + "\r");
           }
           this.emit("blocking_prompt", promptInfo, true);
+          this.outputBuffer = "";
         } else {
           this.emit("blocking_prompt", promptInfo, false);
         }
@@ -717,6 +729,7 @@ var PTYSession = class extends import_events.EventEmitter {
             this.writeRaw(resp + "\r");
           }
           this._lastBlockingPromptHash = null;
+          this.outputBuffer = "";
           this.emit("blocking_prompt", promptInfo, true);
           return true;
         }
@@ -744,7 +757,10 @@ var PTYSession = class extends import_events.EventEmitter {
    * Session rules are checked first, then adapter rules.
    */
   tryAutoResponse() {
-    const adapterRules = this.adapter.autoResponseRules || [];
+    const adapterRules = (this.adapter.autoResponseRules || []).filter((r) => !this._disabledRulePatterns.has(r.pattern.source)).map((r) => {
+      const override = this._ruleOverrides.get(r.pattern.source);
+      return override ? { ...r, ...override } : r;
+    });
     const allRules = [...this.sessionRules, ...adapterRules];
     if (allRules.length === 0) {
       return false;