pty-manager 1.2.13 → 1.2.15

package/dist/pty-worker.js

@@ -290,12 +290,14 @@ var SPECIAL_KEYS = {
 var BRACKETED_PASTE_START = "\x1B[200~";
 var BRACKETED_PASTE_END = "\x1B[201~";
 var PTYSession = class extends import_events.EventEmitter {
-  constructor(adapter, config, logger) {
+  constructor(adapter, config, logger, stallDetectionEnabled, defaultStallTimeoutMs) {
     super();
     this.adapter = adapter;
     this.id = config.id || generateId();
     this.config = { ...config, id: this.id };
     this.logger = logger || consoleLogger;
+    this._stallDetectionEnabled = stallDetectionEnabled ?? false;
+    this._stallTimeoutMs = config.stallTimeoutMs ?? defaultStallTimeoutMs ?? 8e3;
   }
   ptyProcess = null;
   outputBuffer = "";
@@ -306,6 +308,12 @@ var PTYSession = class extends import_events.EventEmitter {
   logger;
   sessionRules = [];
   _lastBlockingPromptHash = null;
+  // Stall detection
+  _stallTimer = null;
+  _stallTimeoutMs;
+  _stallDetectionEnabled;
+  _lastStallHash = null;
+  _stallStartedAt = null;
   id;
   config;
   get status() {
@@ -387,6 +395,135 @@ var PTYSession = class extends import_events.EventEmitter {
     this.logger.debug({ sessionId: this.id }, "Cleared auto-response rules");
   }
   // ─────────────────────────────────────────────────────────────────────────────
+  // Stall Detection
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Start or reset the stall detection timer.
+   * Only active when status is "busy" and stall detection is enabled.
+   */
+  resetStallTimer() {
+    this.clearStallTimer();
+    if (!this._stallDetectionEnabled || this._status !== "busy") {
+      return;
+    }
+    this._stallStartedAt = Date.now();
+    this._lastStallHash = null;
+    this._stallTimer = setTimeout(() => {
+      this.onStallTimerFired();
+    }, this._stallTimeoutMs);
+  }
+  /**
+   * Clear the stall detection timer.
+   */
+  clearStallTimer() {
+    if (this._stallTimer) {
+      clearTimeout(this._stallTimer);
+      this._stallTimer = null;
+    }
+    this._stallStartedAt = null;
+  }
+  /**
+   * Called when the stall timer fires (no output for stallTimeoutMs).
+   */
+  onStallTimerFired() {
+    if (this._status !== "busy") {
+      return;
+    }
+    const tail = this.outputBuffer.slice(-500);
+    const hash = this.simpleHash(tail);
+    if (hash === this._lastStallHash) {
+      this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallTimeoutMs);
+      return;
+    }
+    this._lastStallHash = hash;
+    const recentRaw = this.outputBuffer.slice(-2e3);
+    const recentOutput = this.stripAnsiForStall(recentRaw);
+    const stallDurationMs = this._stallStartedAt ? Date.now() - this._stallStartedAt : this._stallTimeoutMs;
+    this.logger.debug(
+      { sessionId: this.id, stallDurationMs, bufferTailLength: tail.length },
+      "Stall detected"
+    );
+    this.emit("stall_detected", recentOutput, stallDurationMs);
+    this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallTimeoutMs);
+  }
+  /**
+   * Promise-based delay helper.
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Simple string hash for deduplication.
+   */
+  simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return hash.toString(36);
+  }
+  /**
+   * Strip ANSI codes for stall detection output.
+   * Replaces cursor-forward sequences with spaces first.
+   */
+  stripAnsiForStall(str) {
+    const withSpaces = str.replace(/\x1b\[\d*C/g, " ");
+    return withSpaces.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
+  }
+  /**
+   * Handle external stall classification result.
+   * Called by the manager after onStallClassify resolves.
+   */
+  handleStallClassification(classification) {
+    if (this._status !== "busy") {
+      return;
+    }
+    if (!classification || classification.state === "still_working") {
+      this.resetStallTimer();
+      return;
+    }
+    switch (classification.state) {
+      case "waiting_for_input": {
+        const promptInfo = {
+          type: "stall_classified",
+          prompt: classification.prompt,
+          canAutoRespond: !!classification.suggestedResponse
+        };
+        if (classification.suggestedResponse) {
+          this.logger.info(
+            { sessionId: this.id, response: classification.suggestedResponse },
+            "Auto-responding to stall-classified prompt"
+          );
+          const resp = classification.suggestedResponse;
+          if (resp.startsWith("keys:")) {
+            const keys = resp.slice(5).split(",").map((k) => k.trim());
+            this.sendKeySequence(keys);
+          } else {
+            this.writeRaw(resp + "\r");
+          }
+          this.emit("blocking_prompt", promptInfo, true);
+        } else {
+          this.emit("blocking_prompt", promptInfo, false);
+        }
+        break;
+      }
+      case "task_complete":
+        this._status = "ready";
+        this._lastBlockingPromptHash = null;
+        this.outputBuffer = "";
+        this.clearStallTimer();
+        this.emit("ready");
+        this.logger.info({ sessionId: this.id }, "Stall classified as task_complete, transitioning to ready");
+        break;
+      case "error":
+        this.clearStallTimer();
+        this.emit("error", new Error(classification.prompt || "Stall classified as error"));
+        break;
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
   // Lifecycle
   // ─────────────────────────────────────────────────────────────────────────────
   /**
@@ -444,11 +581,15 @@ var PTYSession = class extends import_events.EventEmitter {
     this.ptyProcess.onData((data) => {
       this._lastActivityAt = /* @__PURE__ */ new Date();
       this.outputBuffer += data;
+      if (this._status === "busy") {
+        this.resetStallTimer();
+      }
       this.emit("output", data);
       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");
         return;
@@ -461,6 +602,7 @@ var PTYSession = class extends import_events.EventEmitter {
         const loginDetection = this.adapter.detectLogin(this.outputBuffer);
         if (loginDetection.required && this._status !== "authenticating") {
           this._status = "authenticating";
+          this.clearStallTimer();
           this.emit("login_required", loginDetection.instructions, loginDetection.url);
           this.logger.warn(
             { sessionId: this.id, loginType: loginDetection.type },
@@ -472,6 +614,7 @@ var PTYSession = class extends import_events.EventEmitter {
       const exitDetection = this.adapter.detectExit(this.outputBuffer);
       if (exitDetection.exited) {
         this._status = "stopped";
+        this.clearStallTimer();
         this.emit("exit", exitDetection.code || 0);
       }
       if (this._status !== "starting" && this._status !== "authenticating") {
@@ -480,6 +623,7 @@ var PTYSession = class extends import_events.EventEmitter {
     });
     this.ptyProcess.onExit(({ exitCode, signal }) => {
       this._status = "stopped";
+      this.clearStallTimer();
       this.logger.info(
         { sessionId: this.id, exitCode, signal },
         "PTY session exited"
@@ -521,7 +665,13 @@ var PTYSession = class extends import_events.EventEmitter {
             },
             "Auto-responding to blocking prompt"
           );
-          this.writeRaw(detection.suggestedResponse + "\r");
+          const resp = detection.suggestedResponse;
+          if (resp.startsWith("keys:")) {
+            const keys = resp.slice(5).split(",").map((k) => k.trim());
+            this.sendKeySequence(keys);
+          } else {
+            this.writeRaw(resp + "\r");
+          }
           this._lastBlockingPromptHash = null;
           this.emit("blocking_prompt", promptInfo, true);
           return true;
@@ -555,8 +705,11 @@ var PTYSession = class extends import_events.EventEmitter {
     if (allRules.length === 0) {
       return false;
     }
+    let stripped = this.stripAnsiForStall(this.outputBuffer);
+    stripped = stripped.replace(/[│╭╰╮╯─═╌║╔╗╚╝╠╣╦╩╬┌┐└┘├┤┬┴┼●○❯❮▶◀⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⏺←→↑↓]/g, " ");
+    stripped = stripped.replace(/ {2,}/g, " ");
     for (const rule of allRules) {
-      if (rule.pattern.test(this.outputBuffer)) {
+      if (rule.pattern.test(stripped)) {
         const safe = rule.safe !== false;
         const isSessionRule = this.sessionRules.includes(rule);
         if (safe) {
@@ -570,7 +723,15 @@ var PTYSession = class extends import_events.EventEmitter {
             },
             "Applying auto-response rule"
           );
-          this.writeRaw(rule.response + "\r");
+          const useKeys = rule.keys && rule.keys.length > 0;
+          const isTuiDefault = !rule.responseType && !rule.keys && this.adapter.usesTuiMenus;
+          if (useKeys) {
+            this.sendKeySequence(rule.keys);
+          } else if (isTuiDefault) {
+            this.sendKeys("enter");
+          } else {
+            this.writeRaw(rule.response + "\r");
+          }
           this.outputBuffer = this.outputBuffer.replace(rule.pattern, "");
           const promptInfo = {
             type: rule.type,
@@ -647,6 +808,7 @@ var PTYSession = class extends import_events.EventEmitter {
    */
   send(message) {
     this._status = "busy";
+    this.resetStallTimer();
     const msg = {
       id: `${this.id}-msg-${++this.messageCounter}`,
       sessionId: this.id,
@@ -699,6 +861,26 @@ var PTYSession = class extends import_events.EventEmitter {
       }
     }
   }
+  /**
+   * Select a TUI menu option by index (0-based).
+   * Sends Down arrow `optionIndex` times, then Enter, with 50ms delays.
+   */
+  async selectMenuOption(optionIndex) {
+    for (let i = 0; i < optionIndex; i++) {
+      this.sendKeys("down");
+      await this.delay(50);
+    }
+    this.sendKeys("enter");
+  }
+  /**
+   * Send a sequence of keys with staggered timing.
+   * Each key is sent 50ms apart using setTimeout to keep the caller synchronous.
+   */
+  sendKeySequence(keys) {
+    keys.forEach((key, i) => {
+      setTimeout(() => this.sendKeys(key), i * 50);
+    });
+  }
   /**
    * Paste text using bracketed paste mode
    *
@@ -735,6 +917,7 @@ var PTYSession = class extends import_events.EventEmitter {
   kill(signal) {
     if (this.ptyProcess) {
       this._status = "stopping";
+      this.clearStallTimer();
       this.ptyProcess.kill(signal);
       this.logger.info({ sessionId: this.id, signal }, "Killing PTY session");
     }
@@ -804,11 +987,18 @@ var PTYManager = class extends import_events2.EventEmitter {
   maxLogLines;
   logger;
   adapters;
+  // Stall detection config
+  _stallDetectionEnabled;
+  _stallTimeoutMs;
+  _onStallClassify;
   constructor(config = {}) {
     super();
     this.adapters = new AdapterRegistry();
     this.logger = config.logger || consoleLogger2;
     this.maxLogLines = config.maxLogLines || 1e3;
+    this._stallDetectionEnabled = config.stallDetectionEnabled ?? false;
+    this._stallTimeoutMs = config.stallTimeoutMs ?? 8e3;
+    this._onStallClassify = config.onStallClassify;
   }
   /**
    * Register a CLI adapter
@@ -831,7 +1021,13 @@ var PTYManager = class extends import_events2.EventEmitter {
       { type: config.type, name: config.name },
       "Spawning session"
     );
-    const session = new PTYSession(adapter, config, this.logger);
+    const session = new PTYSession(
+      adapter,
+      config,
+      this.logger,
+      this._stallDetectionEnabled,
+      this._stallTimeoutMs
+    );
     this.setupSessionEvents(session);
     this.sessions.set(session.id, session);
     this.outputLogs.set(session.id, []);
@@ -875,6 +1071,21 @@ var PTYManager = class extends import_events2.EventEmitter {
     session.on("error", (error) => {
       this.emit("session_error", session.toHandle(), error.message);
     });
+    session.on("stall_detected", (recentOutput, stallDurationMs) => {
+      const handle = session.toHandle();
+      this.emit("stall_detected", handle, recentOutput, stallDurationMs);
+      if (this._onStallClassify) {
+        this._onStallClassify(session.id, recentOutput, stallDurationMs).then((classification) => {
+          session.handleStallClassification(classification);
+        }).catch((err) => {
+          this.logger.error(
+            { sessionId: session.id, error: err },
+            "Stall classification callback failed"
+          );
+          session.handleStallClassification(null);
+        });
+      }
+    });
   }
   /**
    * Stop a session
@@ -1046,6 +1257,22 @@ var PTYManager = class extends import_events2.EventEmitter {
     return this.sessions.get(sessionId);
   }
   // ─────────────────────────────────────────────────────────────────────────────
+  // Stall Detection Configuration
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Configure stall detection at runtime.
+   * Affects newly spawned sessions only — existing sessions keep their config.
+   */
+  configureStallDetection(enabled, timeoutMs, classify) {
+    this._stallDetectionEnabled = enabled;
+    if (timeoutMs !== void 0) {
+      this._stallTimeoutMs = timeoutMs;
+    }
+    if (classify !== void 0) {
+      this._onStallClassify = classify;
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
   // Runtime Auto-Response Rules API
   // ─────────────────────────────────────────────────────────────────────────────
   /**
@@ -1234,6 +1461,14 @@ manager.on("question", (handle, question) => {
     question
   });
 });
+manager.on("stall_detected", (handle, recentOutput, stallDurationMs) => {
+  emit({
+    event: "stall_detected",
+    id: handle.id,
+    recentOutput,
+    stallDurationMs
+  });
+});
 async function handleSpawn(id, config) {
   try {
     if (manager.has(id)) {
@@ -1363,6 +1598,8 @@ function deserializeRule(serialized) {
     pattern: new RegExp(serialized.pattern, serialized.flags || ""),
     type: serialized.type,
     response: serialized.response,
+    responseType: serialized.responseType,
+    keys: serialized.keys,
     description: serialized.description,
     safe: serialized.safe
   };
@@ -1373,6 +1610,8 @@ function serializeRule(rule) {
     flags: rule.pattern.flags || void 0,
     type: rule.type,
     response: rule.response,
+    responseType: rule.responseType,
+    keys: rule.keys,
     description: rule.description,
     safe: rule.safe
   };
@@ -1421,6 +1660,35 @@ function handleClearRules(id) {
     ack("clearRules", id, false, err instanceof Error ? err.message : String(err));
   }
 }
+function handleConfigureStallDetection(enabled, timeoutMs) {
+  try {
+    manager.configureStallDetection(enabled, timeoutMs);
+    ack("configureStallDetection", void 0, true);
+  } catch (err) {
+    ack("configureStallDetection", void 0, false, err instanceof Error ? err.message : String(err));
+  }
+}
+function handleSelectMenuOption(id, optionIndex) {
+  const session = manager.getSession(id);
+  if (!session) {
+    ack("selectMenuOption", id, false, `Session ${id} not found`);
+    return;
+  }
+  session.selectMenuOption(optionIndex).then(() => ack("selectMenuOption", id, true)).catch((err) => ack("selectMenuOption", id, false, err instanceof Error ? err.message : String(err)));
+}
+function handleClassifyStallResult(id, classification) {
+  try {
+    const session = manager.getSession(id);
+    if (!session) {
+      ack("classifyStallResult", id, false, `Session ${id} not found`);
+      return;
+    }
+    session.handleStallClassification(classification);
+    ack("classifyStallResult", id, true);
+  } catch (err) {
+    ack("classifyStallResult", id, false, err instanceof Error ? err.message : String(err));
+  }
+}
 function processCommand(line) {
   let command;
   try {
@@ -1520,6 +1788,23 @@ function processCommand(line) {
       }
       handleClearRules(command.id);
       break;
+    case "selectMenuOption":
+      if (!command.id || command.optionIndex === void 0) {
+        ack("selectMenuOption", command.id, false, "Missing id or optionIndex");
+        return;
+      }
+      handleSelectMenuOption(command.id, command.optionIndex);
+      break;
+    case "configureStallDetection":
+      handleConfigureStallDetection(command.enabled ?? false, command.timeoutMs);
+      break;
+    case "classifyStallResult":
+      if (!command.id) {
+        ack("classifyStallResult", command.id, false, "Missing id");
+        return;
+      }
+      handleClassifyStallResult(command.id, command.classification ?? null);
+      break;
     default:
       emit({ event: "error", message: `Unknown command: ${command.cmd}` });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pty-manager",
-  "version": "1.2.13",
+  "version": "1.2.15",
   "description": "PTY session manager with lifecycle management, pluggable adapters, and blocking prompt detection",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,18 +24,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "test:coverage": "vitest --coverage",
-    "test:integration": "tsx test-integration.ts",
-    "type-check": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "pnpm run build"
-  },
   "keywords": [
     "pty",
     "terminal",
@@ -73,5 +61,16 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest --coverage",
+    "test:integration": "tsx test-integration.ts",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
   }
-}
+}