pty-manager 1.8.0 → 1.9.1

package/dist/index.d.mts

@@ -52,6 +52,17 @@ interface SpawnConfig {
      *  are emitted as autoResponded=false instead of being auto-responded.
      *  Auto-response rules (ruleOverrides) are unaffected. */
     skipAdapterAutoResponse?: boolean;
+    /**
+     * Whether to inherit the parent process environment variables.
+     * When `true` (default), `process.env` is spread as the base of the spawned
+     * process environment. When `false`, only `adapter.getEnv()` output and
+     * `config.env` are used — the caller is responsible for providing any
+     * necessary system vars (PATH, HOME, etc.) via `config.env`.
+     *
+     * Set to `false` for security-sensitive contexts where the host process has
+     * secrets that spawned agents should not access.
+     */
+    inheritProcessEnv?: boolean;
 }
 /**
  * Handle to a running session
@@ -188,6 +199,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 +409,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 +486,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 +524,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 +704,12 @@ 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;
+    /**
+     * Build the environment object for spawning a PTY process.
+     * Merges base env (process.env unless opted out), adapter env, and config env,
+     * with TERM/COLORTERM always forced.
+     */
+    static buildSpawnEnv(config: SpawnConfig, adapterEnv: Record<string, string>): Record<string, string>;
     /**
      * Normalize a list of key names for SPECIAL_KEYS lookup.
      *
@@ -737,6 +778,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;
@@ -1199,4 +1241,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

@@ -52,6 +52,17 @@ interface SpawnConfig {
      *  are emitted as autoResponded=false instead of being auto-responded.
      *  Auto-response rules (ruleOverrides) are unaffected. */
     skipAdapterAutoResponse?: boolean;
+    /**
+     * Whether to inherit the parent process environment variables.
+     * When `true` (default), `process.env` is spread as the base of the spawned
+     * process environment. When `false`, only `adapter.getEnv()` output and
+     * `config.env` are used — the caller is responsible for providing any
+     * necessary system vars (PATH, HOME, etc.) via `config.env`.
+     *
+     * Set to `false` for security-sensitive contexts where the host process has
+     * secrets that spawned agents should not access.
+     */
+    inheritProcessEnv?: boolean;
 }
 /**
  * Handle to a running session
@@ -188,6 +199,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 +409,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 +486,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 +524,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 +704,12 @@ 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;
+    /**
+     * Build the environment object for spawning a PTY process.
+     * Merges base env (process.env unless opted out), adapter env, and config env,
+     * with TERM/COLORTERM always forced.
+     */
+    static buildSpawnEnv(config: SpawnConfig, adapterEnv: Record<string, string>): Record<string, string>;
     /**
      * Normalize a list of key names for SPECIAL_KEYS lookup.
      *
@@ -737,6 +778,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;
@@ -1199,4 +1241,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) {
@@ -882,14 +900,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     const command = this.adapter.getCommand();
     const args = this.adapter.getArgs(this.config);
     const adapterEnv = this.adapter.getEnv(this.config);
-    const env = {
-      ...process.env,
-      ...adapterEnv,
-      ...this.config.env,
-      // Force terminal settings
-      TERM: "xterm-256color",
-      COLORTERM: "truecolor"
-    };
+    const env = _PTYSession.buildSpawnEnv(this.config, adapterEnv);
     this.logger.info(
       { sessionId: this.id, command, args: args.join(" ") },
       "Starting PTY session"
@@ -967,6 +978,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) {
@@ -1260,6 +1282,21 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       }
     }
   }
+  /**
+   * Build the environment object for spawning a PTY process.
+   * Merges base env (process.env unless opted out), adapter env, and config env,
+   * with TERM/COLORTERM always forced.
+   */
+  static buildSpawnEnv(config, adapterEnv) {
+    const baseEnv = config.inheritProcessEnv !== false ? process.env : {};
+    return {
+      ...baseEnv,
+      ...adapterEnv,
+      ...config.env,
+      TERM: "xterm-256color",
+      COLORTERM: "truecolor"
+    };
+  }
   /**
    * Normalize a list of key names for SPECIAL_KEYS lookup.
    *
@@ -1498,6 +1535,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);
@@ -2576,6 +2616,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) {