pty-manager 1.9.7 → 1.10.0

package/README.md

@@ -2,6 +2,8 @@
 
 PTY session manager with lifecycle management, pluggable adapters, and blocking prompt detection.
 
+> Need crash-resilient sessions without native compilation? See [tmux-manager](../tmux-manager) — same adapter interface, backed by tmux instead of node-pty.
+
 ## Features
 
 - **Multi-session management** - Spawn and manage multiple PTY sessions concurrently

package/dist/index.d.mts

@@ -1,69 +1,37 @@
 import { EventEmitter } from 'events';
+import * as adapter_types from 'adapter-types';
+import { SpawnConfig, CLIAdapter, AutoResponseRule, ToolRunningInfo, AdapterRegistry, LoginDetection, BlockingPromptDetection, ParsedOutput } from 'adapter-types';
+export { AdapterFactoryConfig, AdapterRegistry, AutoResponseRule, BaseCLIAdapter, BlockingPromptDetection, BlockingPromptType, CLIAdapter, LoginDetection, MessageType, ParsedOutput, SpawnConfig, ToolRunningInfo, createAdapter } from 'adapter-types';
 
 /**
- * PTY Agent Manager Types
+ * Lazy runtime check for node-pty native addon.
  *
- * Standalone type definitions for PTY session and adapter management.
+ * 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;
+
 /**
  * Session lifecycle states
  */
 type SessionStatus = 'pending' | 'starting' | 'authenticating' | 'ready' | 'busy' | 'stopping' | 'stopped' | 'error';
-/**
- * Message types for session communication
- */
-type MessageType = 'task' | 'response' | 'question' | 'answer' | 'status' | 'error';
-/**
- * Configuration for spawning a PTY session
- */
-interface SpawnConfig {
-    /** Optional unique ID (auto-generated if not provided) */
-    id?: string;
-    /** Human-readable name */
-    name: string;
-    /** Adapter type to use */
-    type: string;
-    /** Working directory */
-    workdir?: string;
-    /** Environment variables */
-    env?: Record<string, string>;
-    /** Initial terminal columns (default: 120) */
-    cols?: number;
-    /** Initial terminal rows (default: 40) */
-    rows?: number;
-    /** Session timeout in ms */
-    timeout?: number;
-    /** Custom adapter configuration */
-    adapterConfig?: Record<string, unknown>;
-    /** Per-session stall timeout in ms. Overrides PTYManagerConfig.stallTimeoutMs. */
-    stallTimeoutMs?: number;
-    /** Override adapter's readySettleMs for this session.
-     *  Ms of output silence after detectReady match before emitting session_ready. */
-    readySettleMs?: number;
-    /** Enable verbose task-completion trace logs.
-     *  Disabled by default; set true to enable. */
-    traceTaskCompletion?: boolean;
-    /** 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>;
-    /** When true, adapter detectBlockingPrompt() results with suggestedResponse
-     *  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
  */
@@ -85,7 +53,7 @@ interface SessionMessage {
     id: string;
     sessionId: string;
     direction: 'inbound' | 'outbound';
-    type: MessageType;
+    type: adapter_types.MessageType;
     content: string;
     metadata?: Record<string, unknown>;
     timestamp: Date;
@@ -97,26 +65,6 @@ interface SessionFilter {
     status?: SessionStatus | SessionStatus[];
     type?: string | string[];
 }
-/**
- * Parsed output from a CLI
- */
-interface ParsedOutput {
-    type: MessageType;
-    content: string;
-    isComplete: boolean;
-    isQuestion: boolean;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Login/auth detection result
- */
-interface LoginDetection {
-    required: boolean;
-    type?: 'api_key' | 'oauth' | 'browser' | 'device_code' | 'cli_auth';
-    url?: string;
-    deviceCode?: string;
-    instructions?: string;
-}
 /**
  * Normalized authentication methods for runtime event consumers.
  */
@@ -131,57 +79,11 @@ interface AuthRequiredInfo {
     instructions?: string;
     promptSnippet?: string;
 }
-/**
- * Types of blocking prompts that can occur
- */
-type BlockingPromptType = 'login' | 'update' | 'config' | 'tos' | 'model_select' | 'project_select' | 'permission' | 'tool_wait' | 'unknown';
-/**
- * Blocking prompt detection result
- */
-interface BlockingPromptDetection {
-    /** Whether a blocking prompt was detected */
-    detected: boolean;
-    /** Type of blocking prompt */
-    type?: BlockingPromptType;
-    /** The prompt text shown to the user */
-    prompt?: string;
-    /** Available options/choices if detected */
-    options?: string[];
-    /** Suggested auto-response (if safe to auto-respond) */
-    suggestedResponse?: string;
-    /** Whether it's safe to auto-respond without user confirmation */
-    canAutoRespond?: boolean;
-    /** Instructions for the user if manual intervention needed */
-    instructions?: string;
-    /** URL to open if browser action needed */
-    url?: string;
-}
-/**
- * Auto-response rule for handling known blocking prompts
- */
-interface AutoResponseRule {
-    /** Pattern to match in output */
-    pattern: RegExp;
-    /** Type of prompt this handles */
-    type: BlockingPromptType;
-    /** Response to send automatically */
-    response: string;
-    /** How to deliver the response: 'text' writes raw text + CR, 'keys' sends key sequences (default: 'text') */
-    responseType?: 'text' | 'keys';
-    /** Key names to send when responseType is 'keys' (e.g. ['down', 'enter']) */
-    keys?: string[];
-    /** Human-readable description of what this does */
-    description: string;
-    /** Whether this is safe to auto-respond (default: true) */
-    safe?: boolean;
-    /** Fire this rule at most once per session (prevents thrashing on TUI re-renders) */
-    once?: boolean;
-}
 /**
  * Blocking prompt info for events
  */
 interface BlockingPromptInfo {
-    type: BlockingPromptType | string;
+    type: adapter_types.BlockingPromptType | string;
     prompt?: string;
     options?: string[];
     canAutoRespond: boolean;
@@ -199,17 +101,6 @@ 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)
  */
@@ -271,201 +162,6 @@ interface PTYManagerConfig {
      */
     onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
 }
-/**
- * Configuration for creating an adapter via factory
- */
-interface AdapterFactoryConfig {
-    /** Command to execute */
-    command: string;
-    /** Default arguments */
-    args?: string[] | ((config: SpawnConfig) => string[]);
-    /** Environment variables */
-    env?: Record<string, string> | ((config: SpawnConfig) => Record<string, string>);
-    /** Login detection configuration */
-    loginDetection?: {
-        patterns: RegExp[];
-        extractUrl?: (output: string) => string | null;
-        extractInstructions?: (output: string) => string | null;
-    };
-    /** Blocking prompt configuration */
-    blockingPrompts?: Array<{
-        pattern: RegExp;
-        type: BlockingPromptType;
-        autoResponse?: string;
-        safe?: boolean;
-        description?: string;
-    }>;
-    /** Ready state indicators */
-    readyIndicators?: RegExp[];
-    /** Exit indicators */
-    exitIndicators?: Array<{
-        pattern: RegExp;
-        codeExtractor?: (match: RegExpMatchArray) => number;
-    }>;
-    /** Output parser */
-    parseOutput?: (output: string) => ParsedOutput | null;
-    /** Input formatter */
-    formatInput?: (message: string) => string;
-    /** Prompt pattern for detecting input readiness */
-    promptPattern?: RegExp;
-}
-
-/**
- * CLI Adapter Interface
- *
- * Defines how to interact with different CLI tools via PTY.
- */
-
-/**
- * Interface that CLI adapters must implement
- */
-interface CLIAdapter {
-    /** Adapter type identifier */
-    readonly adapterType: string;
-    /** Display name for the CLI */
-    readonly displayName: string;
-    /**
-     * Auto-response rules for handling known blocking prompts.
-     * These are applied automatically during startup and execution.
-     */
-    readonly autoResponseRules?: AutoResponseRule[];
-    /**
-     * Whether this CLI uses TUI menus that require arrow-key navigation.
-     * When true, auto-response rules without an explicit responseType
-     * default to sending Enter via sendKeys instead of writeRaw.
-     */
-    readonly usesTuiMenus?: boolean;
-    /**
-     * Get the CLI command to execute
-     */
-    getCommand(): string;
-    /**
-     * Get command arguments
-     */
-    getArgs(config: SpawnConfig): string[];
-    /**
-     * Get environment variables needed
-     */
-    getEnv(config: SpawnConfig): Record<string, string>;
-    /**
-     * Detect if output indicates login is required
-     * @deprecated Use detectBlockingPrompt() instead for comprehensive detection
-     */
-    detectLogin(output: string): LoginDetection;
-    /**
-     * Detect any blocking prompt that requires user input or auto-response.
-     */
-    detectBlockingPrompt?(output: string): BlockingPromptDetection;
-    /**
-     * Detect if CLI is ready to receive input
-     */
-    detectReady(output: string): boolean;
-    /**
-     * Detect if CLI has exited or crashed
-     */
-    detectExit(output: string): {
-        exited: boolean;
-        code?: number;
-        error?: string;
-    };
-    /**
-     * Parse structured response from output buffer
-     * Returns null if output is incomplete
-     */
-    parseOutput(output: string): ParsedOutput | null;
-    /**
-     * Format a message/task for this CLI
-     */
-    formatInput(message: string): string;
-    /**
-     * Get prompt pattern to detect when CLI is waiting for input
-     */
-    getPromptPattern(): RegExp;
-    /**
-     * Optional: Detect if the CLI has completed a task and returned to its idle prompt.
-     * More specific than detectReady — matches high-confidence completion indicators
-     * (e.g. duration summaries, explicit "done" messages) alongside the idle prompt.
-     *
-     * Used as a fast-path in stall detection to avoid expensive LLM classifier calls.
-     * If not implemented, the stall classifier is used as the fallback.
-     */
-    detectTaskComplete?(output: string): boolean;
-    /**
-     * Optional: Validate that the CLI is installed and accessible
-     */
-    validateInstallation?(): Promise<{
-        installed: boolean;
-        version?: string;
-        error?: string;
-    }>;
-    /** Ms of output silence after detectReady match before emitting session_ready (default: 100) */
-    readonly readySettleMs?: number;
-    /**
-     * Optional: Detect if the CLI is actively loading/processing (thinking spinner,
-     * file reading, model streaming, etc.). When true, stall detection is suppressed
-     * because the agent is provably working — just not producing new visible text.
-     *
-     * Patterns should match active loading indicators like "esc to interrupt",
-     * "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
-     */
-    getHealthCheckCommand?(): string;
-}
-
-/**
- * Adapter Registry
- *
- * Registry for managing CLI adapters.
- */
-
-/**
- * Registry of available CLI adapters
- */
-declare class AdapterRegistry {
-    private adapters;
-    /**
-     * Register an adapter
-     */
-    register(adapter: CLIAdapter): void;
-    /**
-     * Get adapter for type
-     */
-    get(adapterType: string): CLIAdapter | undefined;
-    /**
-     * Check if adapter exists for type
-     */
-    has(adapterType: string): boolean;
-    /**
-     * Unregister an adapter
-     */
-    unregister(adapterType: string): boolean;
-    /**
-     * List all registered adapter types
-     */
-    list(): string[];
-    /**
-     * Get all adapters
-     */
-    all(): CLIAdapter[];
-    /**
-     * Clear all adapters
-     */
-    clear(): void;
-}
 
 /**
  * PTY Session
@@ -947,87 +643,6 @@ declare function extractTaskCompletionTraceRecords(entries: Array<string | Recor
  */
 declare function buildTaskCompletionTimeline(records: TaskCompletionTraceRecord[], options?: BuildTimelineOptions): TaskCompletionTimelineResult;
 
-/**
- * Base CLI Adapter
- *
- * Abstract base class with common functionality for CLI adapters.
- */
-
-/**
- * Abstract base class for CLI adapters with common functionality
- */
-declare abstract class BaseCLIAdapter implements CLIAdapter {
-    abstract readonly adapterType: string;
-    abstract readonly displayName: string;
-    /**
-     * Auto-response rules for handling known blocking prompts.
-     * Subclasses should override this to add CLI-specific rules.
-     */
-    readonly autoResponseRules: AutoResponseRule[];
-    /**
-     * Whether this CLI uses TUI menus requiring arrow-key navigation.
-     * Defaults to false; coding agent adapters override to true.
-     */
-    readonly usesTuiMenus: boolean;
-    abstract getCommand(): string;
-    abstract getArgs(config: SpawnConfig): string[];
-    abstract getEnv(config: SpawnConfig): Record<string, string>;
-    abstract detectLogin(output: string): LoginDetection;
-    abstract detectReady(output: string): boolean;
-    abstract parseOutput(output: string): ParsedOutput | null;
-    abstract getPromptPattern(): RegExp;
-    /**
-     * Default exit detection - look for common exit patterns
-     */
-    detectExit(output: string): {
-        exited: boolean;
-        code?: number;
-        error?: string;
-    };
-    /**
-     * Default blocking prompt detection - looks for common prompt patterns.
-     * Subclasses should override for CLI-specific detection.
-     */
-    detectBlockingPrompt(output: string): BlockingPromptDetection;
-    /**
-     * Default task completion detection — delegates to detectReady().
-     * Subclasses should override to match high-confidence completion patterns
-     * (e.g. duration summaries) that short-circuit the LLM stall classifier.
-     */
-    detectTaskComplete(output: string): boolean;
-    /**
-     * Default input formatting - just return as-is
-     */
-    formatInput(message: string): string;
-    /**
-     * Validate CLI installation by running --version or --help
-     */
-    validateInstallation(): Promise<{
-        installed: boolean;
-        version?: string;
-        error?: string;
-    }>;
-    /**
-     * Helper to check if output contains a question
-     */
-    protected containsQuestion(output: string): boolean;
-    /**
-     * Helper to strip ANSI escape codes from output
-     */
-    protected stripAnsi(str: string): string;
-}
-
-/**
- * Adapter Factory
- *
- * Factory function for creating CLI adapters from configuration.
- */
-
-/**
- * Creates a CLI adapter from configuration
- */
-declare function createAdapter(config: AdapterFactoryConfig): CLIAdapter;
-
 /**
  * Shell Adapter
  *
@@ -1251,4 +866,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 ToolRunningInfo, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };
+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 };