pty-manager 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,641 @@
+import { EventEmitter } from 'events';
+
+/**
+ * PTY Agent Manager Types
+ *
+ * Standalone type definitions for PTY session and adapter management.
+ */
+/**
+ * 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>;
+}
+/**
+ * Handle to a running session
+ */
+interface SessionHandle {
+    id: string;
+    name: string;
+    type: string;
+    status: SessionStatus;
+    pid?: number;
+    startedAt?: Date;
+    lastActivityAt?: Date;
+    error?: string;
+    exitCode?: number;
+}
+/**
+ * Message to/from a session
+ */
+interface SessionMessage {
+    id: string;
+    sessionId: string;
+    direction: 'inbound' | 'outbound';
+    type: MessageType;
+    content: string;
+    metadata?: Record<string, unknown>;
+    timestamp: Date;
+}
+/**
+ * Filter for listing sessions
+ */
+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';
+    url?: string;
+    instructions?: string;
+}
+/**
+ * Types of blocking prompts that can occur
+ */
+type BlockingPromptType = 'login' | 'update' | 'config' | 'tos' | 'model_select' | 'project_select' | 'permission' | '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;
+    /** Human-readable description of what this does */
+    description: string;
+    /** Whether this is safe to auto-respond (default: true) */
+    safe?: boolean;
+}
+/**
+ * Blocking prompt info for events
+ */
+interface BlockingPromptInfo {
+    type: BlockingPromptType | string;
+    prompt?: string;
+    options?: string[];
+    canAutoRespond: boolean;
+    instructions?: string;
+    url?: string;
+}
+/**
+ * Logger interface (bring your own logger)
+ */
+interface Logger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    debug(context: Record<string, unknown>, message: string): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    info(context: Record<string, unknown>, message: string): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    warn(context: Record<string, unknown>, message: string): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    error(context: Record<string, unknown>, message: string): void;
+}
+/**
+ * Options for stopping a session
+ */
+interface StopOptions {
+    /** Force kill without graceful shutdown */
+    force?: boolean;
+    /** Timeout in ms before force kill (default: 5000) */
+    timeout?: number;
+}
+/**
+ * Options for reading logs
+ */
+interface LogOptions {
+    /** Number of lines from the end */
+    tail?: number;
+}
+/**
+ * Terminal attachment for raw I/O streaming
+ */
+interface TerminalAttachment {
+    /** Subscribe to raw terminal output (returns unsubscribe function) */
+    onData: (callback: (data: string) => void) => () => void;
+    /** Write raw data to terminal */
+    write: (data: string) => void;
+    /** Resize the terminal */
+    resize: (cols: number, rows: number) => void;
+}
+/**
+ * PTYManager configuration
+ */
+interface PTYManagerConfig {
+    /** Logger instance (optional - uses console if not provided) */
+    logger?: Logger;
+    /** Maximum output log lines per session (default: 1000) */
+    maxLogLines?: number;
+}
+/**
+ * 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[];
+    /**
+     * 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: Validate that the CLI is installed and accessible
+     */
+    validateInstallation?(): Promise<{
+        installed: boolean;
+        version?: string;
+        error?: string;
+    }>;
+    /**
+     * 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
+ *
+ * Manages a single pseudo-terminal session for a CLI tool.
+ */
+
+interface PTYSessionEvents {
+    output: (data: string) => void;
+    ready: () => void;
+    login_required: (instructions?: string, url?: string) => void;
+    blocking_prompt: (prompt: BlockingPromptInfo, autoResponded: boolean) => void;
+    message: (message: SessionMessage) => void;
+    question: (question: string) => void;
+    exit: (code: number) => void;
+    error: (error: Error) => void;
+}
+declare class PTYSession extends EventEmitter {
+    private adapter;
+    private ptyProcess;
+    private outputBuffer;
+    private _status;
+    private _startedAt;
+    private _lastActivityAt;
+    private messageCounter;
+    private logger;
+    readonly id: string;
+    readonly config: SpawnConfig;
+    constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger);
+    get status(): SessionStatus;
+    get pid(): number | undefined;
+    get startedAt(): Date | undefined;
+    get lastActivityAt(): Date | undefined;
+    /**
+     * Start the PTY session
+     */
+    start(): Promise<void>;
+    /**
+     * Set up event handlers for the PTY
+     */
+    private setupEventHandlers;
+    /**
+     * Detect blocking prompts and handle them with auto-responses or user notification
+     */
+    private detectAndHandleBlockingPrompt;
+    /**
+     * Try to match and apply auto-response rules
+     */
+    private tryAutoResponse;
+    /**
+     * Try to parse the output buffer into structured messages
+     */
+    private tryParseOutput;
+    /**
+     * Write data to the PTY (formatted by adapter)
+     */
+    write(data: string): void;
+    /**
+     * Write raw data directly to the PTY (no formatting)
+     */
+    writeRaw(data: string): void;
+    /**
+     * Send a task/message to the session
+     */
+    send(message: string): SessionMessage;
+    /**
+     * Resize the PTY terminal
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Kill the PTY process
+     */
+    kill(signal?: string): void;
+    /**
+     * Get current output buffer
+     */
+    getOutputBuffer(): string;
+    /**
+     * Clear output buffer
+     */
+    clearOutputBuffer(): void;
+    /**
+     * Convert to SessionHandle
+     */
+    toHandle(): SessionHandle;
+}
+
+/**
+ * PTY Manager
+ *
+ * Manages multiple PTY sessions for CLI tools.
+ */
+
+interface PTYManagerEvents {
+    session_started: (session: SessionHandle) => void;
+    session_ready: (session: SessionHandle) => void;
+    session_stopped: (session: SessionHandle, reason: string) => void;
+    session_error: (session: SessionHandle, error: string) => void;
+    login_required: (session: SessionHandle, instructions?: string, url?: string) => void;
+    blocking_prompt: (session: SessionHandle, promptInfo: BlockingPromptInfo, autoResponded: boolean) => void;
+    message: (message: SessionMessage) => void;
+    question: (session: SessionHandle, question: string) => void;
+}
+declare class PTYManager extends EventEmitter {
+    private sessions;
+    private outputLogs;
+    private maxLogLines;
+    private logger;
+    readonly adapters: AdapterRegistry;
+    constructor(config?: PTYManagerConfig);
+    /**
+     * Register a CLI adapter
+     */
+    registerAdapter(adapter: CLIAdapter): void;
+    /**
+     * Spawn a new PTY session
+     */
+    spawn(config: SpawnConfig): Promise<SessionHandle>;
+    /**
+     * Set up event handlers for a session
+     */
+    private setupSessionEvents;
+    /**
+     * Stop a session
+     */
+    stop(sessionId: string, options?: StopOptions): Promise<void>;
+    /**
+     * Stop all sessions
+     */
+    stopAll(options?: StopOptions): Promise<void>;
+    /**
+     * Get a session by ID
+     */
+    get(sessionId: string): SessionHandle | null;
+    /**
+     * List all sessions
+     */
+    list(filter?: SessionFilter): SessionHandle[];
+    /**
+     * Send a message to a session
+     */
+    send(sessionId: string, message: string): SessionMessage;
+    /**
+     * Get logs for a session
+     */
+    logs(sessionId: string, options?: LogOptions): AsyncIterable<string>;
+    /**
+     * Get metrics for a session
+     */
+    metrics(sessionId: string): {
+        uptime?: number;
+        messageCount?: number;
+    } | null;
+    /**
+     * Shutdown manager and stop all sessions
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get count of sessions by status
+     */
+    getStatusCounts(): Record<SessionStatus, number>;
+    /**
+     * Attach to a session's terminal for raw I/O streaming
+     */
+    attachTerminal(sessionId: string): TerminalAttachment | null;
+    /**
+     * Check if a session exists
+     */
+    has(sessionId: string): boolean;
+    /**
+     * Get the underlying PTYSession (for advanced use)
+     */
+    getSession(sessionId: string): PTYSession | undefined;
+}
+
+/**
+ * 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[];
+    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 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
+ *
+ * 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;
+    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;
+}
+
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StopOptions, type TerminalAttachment, createAdapter };