pty-manager 1.10.1 → 1.11.0

package/dist/index.d.mts

@@ -1,32 +1,7 @@
-import { EventEmitter } from 'events';
 import * as adapter_types from 'adapter-types';
-import { SpawnConfig, CLIAdapter, AutoResponseRule, ToolRunningInfo, AdapterRegistry, LoginDetection, BlockingPromptDetection, ParsedOutput } from 'adapter-types';
+import { CLIAdapter, AutoResponseRule, SpawnConfig, LoginDetection, BlockingPromptDetection, ParsedOutput, ToolRunningInfo, AdapterRegistry } from 'adapter-types';
 export { AdapterFactoryConfig, AdapterRegistry, AutoResponseRule, BaseCLIAdapter, BlockingPromptDetection, BlockingPromptType, CLIAdapter, LoginDetection, MessageType, ParsedOutput, SpawnConfig, ToolRunningInfo, createAdapter } from 'adapter-types';
-
-/**
- * Lazy runtime check for node-pty native addon.
- *
- * Called once before the first PTY spawn. Ensures the native binary is
- * loadable and spawn-helper permissions are correct.
- *
- * 1. Finds the binary — checks for prebuilt pty.node under
- *    prebuilds/<platform>-<arch>/ (node-pty >=1.0), then falls back to
- *    checking for a node-gyp compiled build/Release/pty.node
- * 2. Fixes spawn-helper permissions — bun install can strip execute
- *    bits from the spawn-helper Mach-O binary, causing posix_spawnp
- *    failed at runtime. The script chmod 755s all spawn-helpers under
- *    prebuilds/
- * 3. Rebuilds if missing — if no binary is found at all, runs
- *    node-gyp rebuild as a last resort (with a 2-minute timeout)
- */
-/**
- * Ensure node-pty is usable. Called once before first spawn.
- * Idempotent — subsequent calls are no-ops.
- *
- * @param log - logger function (defaults to console.log)
- * @throws Error if no native binary can be found or built
- */
-declare function ensurePty(log?: (msg: string) => void): void;
+import { EventEmitter } from 'node:events';
 
 /**
  * Session lifecycle states
@@ -163,6 +138,269 @@ interface PTYManagerConfig {
     onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
 }
 
+/**
+ * Shell Adapter
+ *
+ * Built-in adapter for bash/zsh shell sessions.
+ */
+
+/**
+ * Options for the shell adapter
+ */
+interface ShellAdapterOptions {
+    /** Shell to use (default: $SHELL or /bin/bash) */
+    shell?: string;
+    /** Custom prompt string (default: 'pty> ') */
+    prompt?: string;
+}
+/**
+ * Built-in adapter for shell sessions (bash/zsh)
+ */
+declare class ShellAdapter implements CLIAdapter {
+    readonly adapterType = "shell";
+    readonly displayName = "Shell";
+    readonly autoResponseRules: AutoResponseRule[];
+    private shell;
+    private promptStr;
+    constructor(options?: ShellAdapterOptions);
+    getCommand(): string;
+    getArgs(_config: SpawnConfig): string[];
+    getEnv(_config: SpawnConfig): Record<string, string>;
+    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;
+        error?: string;
+    };
+    parseOutput(output: string): ParsedOutput | null;
+    formatInput(message: string): string;
+    getPromptPattern(): RegExp;
+    validateInstallation(): Promise<{
+        installed: boolean;
+        version?: string;
+        error?: string;
+    }>;
+    private stripAnsi;
+}
+
+/**
+ * Bun-Compatible PTY Manager
+ *
+ * A wrapper that spawns a Node.js worker process to handle PTY operations,
+ * allowing pty-manager to work from Bun or other non-Node runtimes.
+ */
+
+interface WorkerSessionHandle {
+    id: string;
+    name: string;
+    type: string;
+    status: SessionStatus;
+    pid: number | undefined;
+    cols: number;
+    rows: number;
+    startedAt?: Date;
+    lastActivityAt?: Date;
+    error?: string;
+    exitCode?: number;
+}
+interface BunPTYManagerOptions {
+    /** Path to node executable (default: 'node') */
+    nodePath?: string;
+    /** Path to worker script (default: auto-detected) */
+    workerPath?: string;
+    /** Environment variables for worker process */
+    env?: Record<string, string>;
+    /**
+     * Adapter modules to load in the worker process.
+     * Each module should export a `createAllAdapters()` function that returns an array of adapters.
+     * Example: ['coding-agent-adapters']
+     */
+    adapterModules?: string[];
+    /** Enable stall detection (default: false) */
+    stallDetectionEnabled?: boolean;
+    /** Default stall timeout in ms (default: 8000) */
+    stallTimeoutMs?: number;
+    /**
+     * External classification callback invoked when a stall is detected.
+     * The worker emits stall_detected; this callback runs on the parent side.
+     */
+    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
+}
+/**
+ * PTY Manager that works with Bun and other non-Node runtimes
+ * by spawning a Node.js worker process.
+ */
+declare class BunCompatiblePTYManager extends EventEmitter {
+    private worker;
+    private sessions;
+    private pending;
+    private ready;
+    private readyPromise;
+    private readyResolve;
+    private nodePath;
+    private workerPath;
+    private env;
+    private adapterModules;
+    private _stallDetectionEnabled;
+    private _stallTimeoutMs;
+    private _onStallClassify?;
+    constructor(options?: BunPTYManagerOptions);
+    private findWorkerPath;
+    private startWorker;
+    private handleWorkerMessage;
+    private sendCommand;
+    private createPending;
+    private resolvePending;
+    /**
+     * Wait for the worker to be ready
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Check if worker is ready
+     */
+    isReady(): boolean;
+    /**
+     * Spawn a new PTY session
+     */
+    spawn(config: SpawnConfig & {
+        id: string;
+    }): Promise<WorkerSessionHandle>;
+    /**
+     * Send data to a session
+     */
+    send(id: string, data: string): Promise<void>;
+    /**
+     * Send special keys to a session
+     */
+    sendKeys(id: string, keys: string | string[]): Promise<void>;
+    /**
+     * Notify a session of an external hook event (resets stall timer, updates status).
+     */
+    notifyHookEvent(id: string, hookEvent: string): Promise<void>;
+    /**
+     * Write raw data to a session (bypasses adapter formatting)
+     */
+    writeRaw(id: string, data: string): Promise<void>;
+    /**
+     * Paste text to a session
+     */
+    paste(id: string, text: string, bracketed?: boolean): Promise<void>;
+    /**
+     * Resize a session
+     */
+    resize(id: string, cols: number, rows: number): Promise<void>;
+    /**
+     * Kill a session
+     */
+    kill(id: string, signal?: string): Promise<void>;
+    /**
+     * Get a session by ID
+     */
+    get(id: string): WorkerSessionHandle | undefined;
+    /**
+     * List all sessions
+     */
+    list(): Promise<WorkerSessionHandle[]>;
+    /**
+     * Check if a session exists
+     */
+    has(id: string): boolean;
+    /**
+     * Whether the adapter currently classifies the session as actively
+     * processing work.
+     *
+     * This round-trips to the worker since the adapter lives in the
+     * worker process. Orchestrators (like milady's swarm idle watchdog)
+     * should consult this before assuming a session is idle based on
+     * output byte diffs — TUIs that redraw their status row in place
+     * (Codex's "Working… esc to interrupt") can fool a raw text diff
+     * even while the model is actively reasoning.
+     *
+     * Returns `false` for unknown sessions, adapters that don't
+     * implement `detectLoading`, or on IPC errors.
+     */
+    isSessionLoading(id: string): Promise<boolean>;
+    /**
+     * Subscribe to output from a specific session
+     */
+    onSessionData(id: string, callback: (data: string) => void): () => void;
+    private serializeRule;
+    /**
+     * Add an auto-response rule to a session.
+     * Session rules are checked before adapter rules.
+     */
+    addAutoResponseRule(sessionId: string, rule: AutoResponseRule): Promise<void>;
+    /**
+     * Remove an auto-response rule from a session by pattern.
+     * Returns true if a rule was removed.
+     */
+    removeAutoResponseRule(sessionId: string, pattern: RegExp): Promise<boolean>;
+    /**
+     * Set all auto-response rules for a session, replacing existing ones.
+     */
+    setAutoResponseRules(sessionId: string, rules: AutoResponseRule[]): Promise<void>;
+    /**
+     * Get all auto-response rules for a session.
+     */
+    getAutoResponseRules(sessionId: string): Promise<AutoResponseRule[]>;
+    /**
+     * Select a TUI menu option by index (0-based) in a session.
+     */
+    selectMenuOption(id: string, optionIndex: number): Promise<void>;
+    /**
+     * Clear all auto-response rules for a session.
+     */
+    clearAutoResponseRules(sessionId: string): Promise<void>;
+    /**
+     * Shutdown the worker and all sessions
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Restart the worker process
+     */
+    restart(): Promise<void>;
+}
+/**
+ * Detect if running in Bun
+ */
+declare function isBun(): boolean;
+/**
+ * Create the appropriate PTY manager based on runtime
+ */
+declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
+
+/**
+ * Lazy runtime check for node-pty native addon.
+ *
+ * Called once before the first PTY spawn. Ensures the native binary is
+ * loadable and spawn-helper permissions are correct.
+ *
+ * 1. Finds the binary — checks for prebuilt pty.node under
+ *    prebuilds/<platform>-<arch>/ (node-pty >=1.0), then falls back to
+ *    checking for a node-gyp compiled build/Release/pty.node
+ * 2. Fixes spawn-helper permissions — bun install can strip execute
+ *    bits from the spawn-helper Mach-O binary, causing posix_spawnp
+ *    failed at runtime. The script chmod 755s all spawn-helpers under
+ *    prebuilds/
+ * 3. Rebuilds if missing — if no binary is found at all, runs
+ *    node-gyp rebuild as a last resort (with a 2-minute timeout)
+ */
+/**
+ * Ensure node-pty is usable. Called once before first spawn.
+ * Idempotent — subsequent calls are no-ops.
+ *
+ * @param log - logger function (defaults to console.log)
+ * @throws Error if no native binary can be found or built
+ */
+declare function ensurePty(log?: (msg: string) => void): void;
+
 /**
  * PTY Session
  *
@@ -203,6 +441,8 @@ declare class PTYSession extends EventEmitter {
     private sessionRules;
     private _firedOnceRules;
     private _lastBlockingPromptHash;
+    private _lastBlockingPromptEmitAt;
+    private static readonly BLOCKING_PROMPT_DEBOUNCE_MS;
     private _ruleOverrides;
     private _disabledRulePatterns;
     private _stallTimer;
@@ -311,6 +551,18 @@ declare class PTYSession extends EventEmitter {
      * signal before transitioning, so stale triggers are safe.
      */
     private scheduleTaskComplete;
+    /**
+     * Whether the adapter's `detectLoading()` currently classifies the
+     * session as actively processing work.
+     *
+     * This wraps `adapter.detectLoading(outputBuffer)` for consumers outside
+     * the PTY layer (e.g. milady's swarm idle watchdog) that need a
+     * reliable "is the agent busy right now?" signal without reimplementing
+     * heuristics over raw terminal output.
+     *
+     * Returns `false` if the adapter does not implement `detectLoading`.
+     */
+    isLoading(): boolean;
     /**
      * Adapter-level task completion check with compatibility fallback.
      * Prefer detectTaskComplete() because detectReady() may be broad for TUIs.
@@ -555,6 +807,18 @@ declare class PTYManager extends EventEmitter {
      * Get the underlying PTYSession (for advanced use)
      */
     getSession(sessionId: string): PTYSession | undefined;
+    /**
+     * Whether the adapter currently classifies the session as actively
+     * processing work (e.g. Codex's "esc to interrupt" status row).
+     *
+     * Orchestrators (like milady's swarm idle watchdog) should consult
+     * this before assuming a session is idle based on output byte diffs,
+     * which are fooled by TUIs that redraw the same status row in place.
+     *
+     * Returns `false` for unknown sessions or adapters that don't
+     * implement `detectLoading`.
+     */
+    isSessionLoading(sessionId: string): boolean;
     /**
      * Configure stall detection at runtime.
      * Affects newly spawned sessions only — existing sessions keep their config.
@@ -643,227 +907,4 @@ declare function extractTaskCompletionTraceRecords(entries: Array<string | Recor
  */
 declare function buildTaskCompletionTimeline(records: TaskCompletionTraceRecord[], options?: BuildTimelineOptions): TaskCompletionTimelineResult;
 
-/**
- * Shell Adapter
- *
- * Built-in adapter for bash/zsh shell sessions.
- */
-
-/**
- * Options for the shell adapter
- */
-interface ShellAdapterOptions {
-    /** Shell to use (default: $SHELL or /bin/bash) */
-    shell?: string;
-    /** Custom prompt string (default: 'pty> ') */
-    prompt?: string;
-}
-/**
- * Built-in adapter for shell sessions (bash/zsh)
- */
-declare class ShellAdapter implements CLIAdapter {
-    readonly adapterType = "shell";
-    readonly displayName = "Shell";
-    readonly autoResponseRules: AutoResponseRule[];
-    private shell;
-    private promptStr;
-    constructor(options?: ShellAdapterOptions);
-    getCommand(): string;
-    getArgs(_config: SpawnConfig): string[];
-    getEnv(_config: SpawnConfig): Record<string, string>;
-    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;
-        error?: string;
-    };
-    parseOutput(output: string): ParsedOutput | null;
-    formatInput(message: string): string;
-    getPromptPattern(): RegExp;
-    validateInstallation(): Promise<{
-        installed: boolean;
-        version?: string;
-        error?: string;
-    }>;
-    private stripAnsi;
-}
-
-/**
- * Bun-Compatible PTY Manager
- *
- * A wrapper that spawns a Node.js worker process to handle PTY operations,
- * allowing pty-manager to work from Bun or other non-Node runtimes.
- */
-
-interface WorkerSessionHandle {
-    id: string;
-    name: string;
-    type: string;
-    status: SessionStatus;
-    pid: number | undefined;
-    cols: number;
-    rows: number;
-    startedAt?: Date;
-    lastActivityAt?: Date;
-    error?: string;
-    exitCode?: number;
-}
-interface BunPTYManagerOptions {
-    /** Path to node executable (default: 'node') */
-    nodePath?: string;
-    /** Path to worker script (default: auto-detected) */
-    workerPath?: string;
-    /** Environment variables for worker process */
-    env?: Record<string, string>;
-    /**
-     * Adapter modules to load in the worker process.
-     * Each module should export a `createAllAdapters()` function that returns an array of adapters.
-     * Example: ['coding-agent-adapters']
-     */
-    adapterModules?: string[];
-    /** Enable stall detection (default: false) */
-    stallDetectionEnabled?: boolean;
-    /** Default stall timeout in ms (default: 8000) */
-    stallTimeoutMs?: number;
-    /**
-     * External classification callback invoked when a stall is detected.
-     * The worker emits stall_detected; this callback runs on the parent side.
-     */
-    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
-}
-/**
- * PTY Manager that works with Bun and other non-Node runtimes
- * by spawning a Node.js worker process.
- */
-declare class BunCompatiblePTYManager extends EventEmitter {
-    private worker;
-    private sessions;
-    private pending;
-    private ready;
-    private readyPromise;
-    private readyResolve;
-    private nodePath;
-    private workerPath;
-    private env;
-    private adapterModules;
-    private _stallDetectionEnabled;
-    private _stallTimeoutMs;
-    private _onStallClassify?;
-    constructor(options?: BunPTYManagerOptions);
-    private findWorkerPath;
-    private startWorker;
-    private handleWorkerMessage;
-    private sendCommand;
-    private createPending;
-    private resolvePending;
-    /**
-     * Wait for the worker to be ready
-     */
-    waitForReady(): Promise<void>;
-    /**
-     * Check if worker is ready
-     */
-    isReady(): boolean;
-    /**
-     * Spawn a new PTY session
-     */
-    spawn(config: SpawnConfig & {
-        id: string;
-    }): Promise<WorkerSessionHandle>;
-    /**
-     * Send data to a session
-     */
-    send(id: string, data: string): Promise<void>;
-    /**
-     * Send special keys to a session
-     */
-    sendKeys(id: string, keys: string | string[]): Promise<void>;
-    /**
-     * Notify a session of an external hook event (resets stall timer, updates status).
-     */
-    notifyHookEvent(id: string, hookEvent: string): Promise<void>;
-    /**
-     * Write raw data to a session (bypasses adapter formatting)
-     */
-    writeRaw(id: string, data: string): Promise<void>;
-    /**
-     * Paste text to a session
-     */
-    paste(id: string, text: string, bracketed?: boolean): Promise<void>;
-    /**
-     * Resize a session
-     */
-    resize(id: string, cols: number, rows: number): Promise<void>;
-    /**
-     * Kill a session
-     */
-    kill(id: string, signal?: string): Promise<void>;
-    /**
-     * Get a session by ID
-     */
-    get(id: string): WorkerSessionHandle | undefined;
-    /**
-     * List all sessions
-     */
-    list(): Promise<WorkerSessionHandle[]>;
-    /**
-     * Check if a session exists
-     */
-    has(id: string): boolean;
-    /**
-     * Subscribe to output from a specific session
-     */
-    onSessionData(id: string, callback: (data: string) => void): () => void;
-    private serializeRule;
-    /**
-     * Add an auto-response rule to a session.
-     * Session rules are checked before adapter rules.
-     */
-    addAutoResponseRule(sessionId: string, rule: AutoResponseRule): Promise<void>;
-    /**
-     * Remove an auto-response rule from a session by pattern.
-     * Returns true if a rule was removed.
-     */
-    removeAutoResponseRule(sessionId: string, pattern: RegExp): Promise<boolean>;
-    /**
-     * Set all auto-response rules for a session, replacing existing ones.
-     */
-    setAutoResponseRules(sessionId: string, rules: AutoResponseRule[]): Promise<void>;
-    /**
-     * Get all auto-response rules for a session.
-     */
-    getAutoResponseRules(sessionId: string): Promise<AutoResponseRule[]>;
-    /**
-     * Select a TUI menu option by index (0-based) in a session.
-     */
-    selectMenuOption(id: string, optionIndex: number): Promise<void>;
-    /**
-     * Clear all auto-response rules for a session.
-     */
-    clearAutoResponseRules(sessionId: string): Promise<void>;
-    /**
-     * Shutdown the worker and all sessions
-     */
-    shutdown(): Promise<void>;
-    /**
-     * Restart the worker process
-     */
-    restart(): Promise<void>;
-}
-/**
- * Detect if running in Bun
- */
-declare function isBun(): boolean;
-/**
- * Create the appropriate PTY manager based on runtime
- */
-declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
-
 export { type AuthRequiredInfo, type AuthRequiredMethod, type BlockingPromptInfo, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type LogOptions, type Logger, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type WorkerSessionHandle, buildTaskCompletionTimeline, createPTYManager, ensurePty, extractTaskCompletionTraceRecords, isBun };