pty-manager 1.7.3 → 1.9.0

package/dist/index.d.mts

@@ -188,6 +188,17 @@ interface StallClassification {
     /** Suggested response to send (for waiting_for_input with auto-respond) */
     suggestedResponse?: string;
 }
+/**
+ * Information about an external tool/process running within a session.
+ * Emitted when the adapter detects a tool is actively executing (e.g. browser,
+ * bash command, Node process). Suppresses stall detection while active.
+ */
+interface ToolRunningInfo {
+    /** Name of the tool (e.g. "Chrome", "bash", "node", "python") */
+    toolName: string;
+    /** Optional description of what the tool is doing */
+    description?: string;
+}
 /**
  * Logger interface (bring your own logger)
  */
@@ -387,6 +398,17 @@ interface CLIAdapter {
      * "Reading N files", "Waiting for LLM", etc.
      */
     detectLoading?(output: string): boolean;
+    /**
+     * Optional: Detect if an external tool/process is currently running within
+     * the session (e.g. browser, bash command, Node server, Python script).
+     *
+     * When a tool is detected, stall detection is suppressed (the agent is
+     * working, just through an external process) and a `tool_running` event
+     * is emitted so the UI can display the active tool.
+     *
+     * Return null when no tool is detected.
+     */
+    detectToolRunning?(output: string): ToolRunningInfo | null;
     /**
      * Optional: Get health check command
      */
@@ -453,6 +475,7 @@ interface PTYSessionEvents {
     stall_detected: (recentOutput: string, stallDurationMs: number) => void;
     status_changed: (status: SessionStatus) => void;
     task_complete: () => void;
+    tool_running: (info: ToolRunningInfo) => void;
 }
 /**
  * Special key mappings to escape sequences
@@ -490,6 +513,7 @@ declare class PTYSession extends EventEmitter {
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     private _readySettleTimer;
     private _readySettlePending;
+    private _lastToolRunningName;
     private _processScheduled;
     private static readonly MAX_OUTPUT_BUFFER;
     readonly id: string;
@@ -669,6 +693,15 @@ declare class PTYSession extends EventEmitter {
      * @param keys - Key name(s) to send, e.g. "ctrl+c" or ["up", "up", "enter"]
      */
     sendKeys(keys: string | string[]): void;
+    /**
+     * Normalize a list of key names for SPECIAL_KEYS lookup.
+     *
+     * Handles two problems:
+     * 1. Modifier aliases: "control" → "ctrl", "command" → "meta", "option" → "alt"
+     * 2. Comma-separated compound keys from stall classifier: ["control", "c"] → ["ctrl+c"]
+     *    A bare modifier followed by a single char/key is joined with "+".
+     */
+    static normalizeKeyList(keys: string[]): string[];
     /**
      * Select a TUI menu option by index (0-based).
      * Sends Down arrow `optionIndex` times, then Enter, with 50ms delays.
@@ -728,6 +761,7 @@ interface PTYManagerEvents {
     stall_detected: (session: SessionHandle, recentOutput: string, stallDurationMs: number) => void;
     session_status_changed: (session: SessionHandle) => void;
     task_complete: (session: SessionHandle) => void;
+    tool_running: (session: SessionHandle, info: ToolRunningInfo) => void;
 }
 declare class PTYManager extends EventEmitter {
     private sessions;
@@ -1002,6 +1036,11 @@ declare class ShellAdapter implements CLIAdapter {
     detectLogin(_output: string): LoginDetection;
     detectBlockingPrompt(_output: string): BlockingPromptDetection;
     detectReady(output: string): boolean;
+    /**
+     * Detect shell continuation prompts that indicate the shell is NOT ready
+     * for a new command (e.g., unclosed quote, heredoc, backtick).
+     */
+    private isContinuationPrompt;
     detectExit(output: string): {
         exited: boolean;
         code?: number;
@@ -1185,4 +1224,4 @@ declare function isBun(): boolean;
  */
 declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AuthRequiredInfo, type AuthRequiredMethod, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };
+export { type AdapterFactoryConfig, AdapterRegistry, type AuthRequiredInfo, type AuthRequiredMethod, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type ToolRunningInfo, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };

package/dist/index.d.ts

@@ -188,6 +188,17 @@ interface StallClassification {
     /** Suggested response to send (for waiting_for_input with auto-respond) */
     suggestedResponse?: string;
 }
+/**
+ * Information about an external tool/process running within a session.
+ * Emitted when the adapter detects a tool is actively executing (e.g. browser,
+ * bash command, Node process). Suppresses stall detection while active.
+ */
+interface ToolRunningInfo {
+    /** Name of the tool (e.g. "Chrome", "bash", "node", "python") */
+    toolName: string;
+    /** Optional description of what the tool is doing */
+    description?: string;
+}
 /**
  * Logger interface (bring your own logger)
  */
@@ -387,6 +398,17 @@ interface CLIAdapter {
      * "Reading N files", "Waiting for LLM", etc.
      */
     detectLoading?(output: string): boolean;
+    /**
+     * Optional: Detect if an external tool/process is currently running within
+     * the session (e.g. browser, bash command, Node server, Python script).
+     *
+     * When a tool is detected, stall detection is suppressed (the agent is
+     * working, just through an external process) and a `tool_running` event
+     * is emitted so the UI can display the active tool.
+     *
+     * Return null when no tool is detected.
+     */
+    detectToolRunning?(output: string): ToolRunningInfo | null;
     /**
      * Optional: Get health check command
      */
@@ -453,6 +475,7 @@ interface PTYSessionEvents {
     stall_detected: (recentOutput: string, stallDurationMs: number) => void;
     status_changed: (status: SessionStatus) => void;
     task_complete: () => void;
+    tool_running: (info: ToolRunningInfo) => void;
 }
 /**
  * Special key mappings to escape sequences
@@ -490,6 +513,7 @@ declare class PTYSession extends EventEmitter {
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
     private _readySettleTimer;
     private _readySettlePending;
+    private _lastToolRunningName;
     private _processScheduled;
     private static readonly MAX_OUTPUT_BUFFER;
     readonly id: string;
@@ -669,6 +693,15 @@ declare class PTYSession extends EventEmitter {
      * @param keys - Key name(s) to send, e.g. "ctrl+c" or ["up", "up", "enter"]
      */
     sendKeys(keys: string | string[]): void;
+    /**
+     * Normalize a list of key names for SPECIAL_KEYS lookup.
+     *
+     * Handles two problems:
+     * 1. Modifier aliases: "control" → "ctrl", "command" → "meta", "option" → "alt"
+     * 2. Comma-separated compound keys from stall classifier: ["control", "c"] → ["ctrl+c"]
+     *    A bare modifier followed by a single char/key is joined with "+".
+     */
+    static normalizeKeyList(keys: string[]): string[];
     /**
      * Select a TUI menu option by index (0-based).
      * Sends Down arrow `optionIndex` times, then Enter, with 50ms delays.
@@ -728,6 +761,7 @@ interface PTYManagerEvents {
     stall_detected: (session: SessionHandle, recentOutput: string, stallDurationMs: number) => void;
     session_status_changed: (session: SessionHandle) => void;
     task_complete: (session: SessionHandle) => void;
+    tool_running: (session: SessionHandle, info: ToolRunningInfo) => void;
 }
 declare class PTYManager extends EventEmitter {
     private sessions;
@@ -1002,6 +1036,11 @@ declare class ShellAdapter implements CLIAdapter {
     detectLogin(_output: string): LoginDetection;
     detectBlockingPrompt(_output: string): BlockingPromptDetection;
     detectReady(output: string): boolean;
+    /**
+     * Detect shell continuation prompts that indicate the shell is NOT ready
+     * for a new command (e.g., unclosed quote, heredoc, backtick).
+     */
+    private isContinuationPrompt;
     detectExit(output: string): {
         exited: boolean;
         code?: number;
@@ -1185,4 +1224,4 @@ declare function isBun(): boolean;
  */
 declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AuthRequiredInfo, type AuthRequiredMethod, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };
+export { type AdapterFactoryConfig, AdapterRegistry, type AuthRequiredInfo, type AuthRequiredMethod, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type ToolRunningInfo, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };

package/dist/index.js

@@ -364,6 +364,8 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
   // Ready detection settle delay — defers session_ready until output goes quiet
   _readySettleTimer = null;
   _readySettlePending = false;
+  // Tool running deduplication — only emit when tool changes
+  _lastToolRunningName = null;
   // Deferred output processing — prevents node-pty's synchronous data
   // delivery from starving the event loop (timers, I/O callbacks, etc.)
   _processScheduled = false;
@@ -529,6 +531,22 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallBackoffMs);
       return;
     }
+    const toolInfo = this.adapter.detectToolRunning?.(this.outputBuffer);
+    if (toolInfo) {
+      if (toolInfo.toolName !== this._lastToolRunningName) {
+        this._lastToolRunningName = toolInfo.toolName;
+        this.emit("tool_running", toolInfo);
+      }
+      this.logger.debug(
+        { sessionId: this.id, tool: toolInfo.toolName },
+        "Tool running \u2014 suppressing stall emission"
+      );
+      this._stallTimer = setTimeout(() => this.onStallTimerFired(), this._stallBackoffMs);
+      return;
+    }
+    if (this._lastToolRunningName) {
+      this._lastToolRunningName = null;
+    }
     const tail = this.outputBuffer.slice(-500);
     const hash = this.simpleHash(tail);
     if (hash === this._lastStallHash) {
@@ -967,6 +985,17 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       this.scheduleReadySettle();
       return;
     }
+    if (this._status === "busy") {
+      const toolInfo = this.adapter.detectToolRunning?.(this.outputBuffer);
+      if (toolInfo) {
+        if (toolInfo.toolName !== this._lastToolRunningName) {
+          this._lastToolRunningName = toolInfo.toolName;
+          this.emit("tool_running", toolInfo);
+        }
+      } else if (this._lastToolRunningName) {
+        this._lastToolRunningName = null;
+      }
+    }
     if (this._status === "busy") {
       const signal = this.isTaskCompleteSignal(this.outputBuffer);
       if (this._taskCompletePending || signal) {
@@ -1242,24 +1271,71 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       throw new Error("Session not started");
     }
     const keyList = Array.isArray(keys) ? keys : [keys];
+    const normalized = _PTYSession.normalizeKeyList(keyList);
     this._stallEmissionCount = 0;
     this.resetStallTimer();
-    for (const key of keyList) {
-      const normalizedKey = key.toLowerCase().trim();
-      const sequence = SPECIAL_KEYS[normalizedKey];
+    for (const key of normalized) {
+      const sequence = SPECIAL_KEYS[key];
       if (sequence) {
         this._lastActivityAt = /* @__PURE__ */ new Date();
         this.ptyProcess.write(sequence);
-        this.logger.debug({ sessionId: this.id, key: normalizedKey }, "Sent special key");
+        this.logger.debug({ sessionId: this.id, key }, "Sent special key");
       } else {
         this.logger.warn(
-          { sessionId: this.id, key: normalizedKey },
+          { sessionId: this.id, key },
           "Unknown special key, sending as literal"
         );
         this.ptyProcess.write(key);
       }
     }
   }
+  /**
+   * Normalize a list of key names for SPECIAL_KEYS lookup.
+   *
+   * Handles two problems:
+   * 1. Modifier aliases: "control" → "ctrl", "command" → "meta", "option" → "alt"
+   * 2. Comma-separated compound keys from stall classifier: ["control", "c"] → ["ctrl+c"]
+   *    A bare modifier followed by a single char/key is joined with "+".
+   */
+  static normalizeKeyList(keys) {
+    const MODIFIER_MAP = {
+      control: "ctrl",
+      command: "meta",
+      cmd: "meta",
+      option: "alt",
+      opt: "alt"
+    };
+    const MODIFIER_NAMES = /* @__PURE__ */ new Set([
+      "ctrl",
+      "alt",
+      "shift",
+      "meta",
+      // Also match the aliases so we can detect them before remapping
+      ...Object.keys(MODIFIER_MAP)
+    ]);
+    const result = [];
+    let i = 0;
+    while (i < keys.length) {
+      let key = keys[i].toLowerCase().trim();
+      if (MODIFIER_MAP[key]) {
+        key = MODIFIER_MAP[key];
+      }
+      if (MODIFIER_NAMES.has(key) && i + 1 < keys.length) {
+        let nextKey = keys[i + 1].toLowerCase().trim();
+        if (MODIFIER_MAP[nextKey]) {
+          nextKey = MODIFIER_MAP[nextKey];
+        }
+        if (!MODIFIER_NAMES.has(nextKey)) {
+          result.push(`${key}+${nextKey}`);
+          i += 2;
+          continue;
+        }
+      }
+      result.push(key);
+      i++;
+    }
+    return result;
+  }
   /**
    * Select a TUI menu option by index (0-based).
    * Sends Down arrow `optionIndex` times, then Enter, with 50ms delays.
@@ -1451,6 +1527,9 @@ var PTYManager = class extends import_events2.EventEmitter {
     session.on("task_complete", () => {
       this.emit("task_complete", session.toHandle());
     });
+    session.on("tool_running", (info) => {
+      this.emit("tool_running", session.toHandle(), info);
+    });
     session.on("stall_detected", (recentOutput, stallDurationMs) => {
       const handle = session.toHandle();
       this.emit("stall_detected", handle, recentOutput, stallDurationMs);
@@ -2261,7 +2340,18 @@ var ShellAdapter = class {
     return { detected: false };
   }
   detectReady(output) {
-    return output.includes(this.promptStr) || output.includes("$") || output.length > 10;
+    if (this.isContinuationPrompt(output)) {
+      return false;
+    }
+    return this.getPromptPattern().test(this.stripAnsi(output));
+  }
+  /**
+   * Detect shell continuation prompts that indicate the shell is NOT ready
+   * for a new command (e.g., unclosed quote, heredoc, backtick).
+   */
+  isContinuationPrompt(output) {
+    const stripped = this.stripAnsi(output);
+    return /(?:quote|dquote|heredoc|bquote|cmdsubst|pipe|then|else|do|loop)>\s*$/.test(stripped) || /(?:quote|dquote|heredoc|bquote)>\s*$/m.test(stripped);
   }
   detectExit(output) {
     if (output.includes("exit")) {
@@ -2284,7 +2374,7 @@ var ShellAdapter = class {
   }
   getPromptPattern() {
     const escaped = this.promptStr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(`(?:${escaped}|\\$|#|>)\\s*$`, "m");
+    return new RegExp(`(?:${escaped}|\\$|#)\\s*$`, "m");
   }
   async validateInstallation() {
     return { installed: true };
@@ -2380,9 +2470,6 @@ var BunCompatiblePTYManager = class extends import_events3.EventEmitter {
     const id = event.id;
     switch (eventType) {
       case "worker_ready":
-        if (this.adapterModules.length > 0) {
-          this.sendCommand({ cmd: "registerAdapters", modules: this.adapterModules });
-        }
         if (this._stallDetectionEnabled) {
           this.sendCommand({
             cmd: "configureStallDetection",
@@ -2390,9 +2477,23 @@ var BunCompatiblePTYManager = class extends import_events3.EventEmitter {
             timeoutMs: this._stallTimeoutMs
           });
         }
-        this.ready = true;
-        this.readyResolve();
-        this.emit("ready");
+        if (this.adapterModules.length > 0) {
+          this.sendCommand({ cmd: "registerAdapters", modules: this.adapterModules });
+          this.createPending("registerAdapters").then(() => {
+            this.ready = true;
+            this.readyResolve();
+            this.emit("ready");
+          }).catch((err) => {
+            this.emit("worker_error", `Failed to register adapters: ${err}`);
+            this.ready = true;
+            this.readyResolve();
+            this.emit("ready");
+          });
+        } else {
+          this.ready = true;
+          this.readyResolve();
+          this.emit("ready");
+        }
         break;
       case "spawned": {
         const session = {
@@ -2507,6 +2608,13 @@ var BunCompatiblePTYManager = class extends import_events3.EventEmitter {
         }
         break;
       }
+      case "tool_running": {
+        const session = this.sessions.get(id);
+        if (session) {
+          this.emit("tool_running", session, event.info);
+        }
+        break;
+      }
       case "stall_detected": {
         const session = this.sessions.get(id);
         if (session) {