tmux-manager 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,669 @@
+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';
+
+/**
+ * Ensure tmux is installed and accessible.
+ *
+ * Checks that tmux is available on PATH and returns its version.
+ * Throws a descriptive error if tmux is not found.
+ */
+/**
+ * Verify that tmux is installed and usable.
+ * Caches the result after the first successful check.
+ *
+ * @param log - Optional log callback for status messages
+ * @returns The tmux version string (e.g., "3.4")
+ */
+declare function ensureTmux(log?: (msg: string) => void): string;
+/**
+ * Reset the cached check (useful for testing).
+ */
+declare function resetTmuxCheck(): void;
+
+/**
+ * Session lifecycle states
+ */
+type SessionStatus = 'pending' | 'starting' | 'authenticating' | 'ready' | 'busy' | 'stopping' | 'stopped' | 'error';
+/**
+ * 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;
+    /** Tmux session name (for reconnection) */
+    tmuxSessionName?: string;
+}
+/**
+ * Message to/from a session
+ */
+interface SessionMessage {
+    id: string;
+    sessionId: string;
+    direction: 'inbound' | 'outbound';
+    type: adapter_types.MessageType;
+    content: string;
+    metadata?: Record<string, unknown>;
+    timestamp: Date;
+}
+/**
+ * Filter for listing sessions
+ */
+interface SessionFilter {
+    status?: SessionStatus | SessionStatus[];
+    type?: string | string[];
+}
+/**
+ * Normalized authentication methods for runtime event consumers.
+ */
+type AuthRequiredMethod = 'api_key' | 'cli_auth' | 'oauth_browser' | 'device_code' | 'unknown';
+/**
+ * Structured authentication-required payload emitted by tmux session/manager.
+ */
+interface AuthRequiredInfo {
+    method: AuthRequiredMethod;
+    url?: string;
+    deviceCode?: string;
+    instructions?: string;
+    promptSnippet?: string;
+}
+/**
+ * Blocking prompt info for events
+ */
+interface BlockingPromptInfo {
+    type: adapter_types.BlockingPromptType | string;
+    prompt?: string;
+    options?: string[];
+    canAutoRespond: boolean;
+    instructions?: string;
+    url?: string;
+}
+/**
+ * Classification result from external stall analysis
+ */
+interface StallClassification {
+    /** What the external classifier determined */
+    state: 'waiting_for_input' | 'still_working' | 'task_complete' | 'error';
+    /** Description of the detected prompt (for waiting_for_input) */
+    prompt?: string;
+    /** Suggested response to send (for waiting_for_input with auto-respond) */
+    suggestedResponse?: 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;
+}
+/**
+ * TmuxManager configuration
+ */
+interface TmuxManagerConfig {
+    /** Logger instance (optional - uses console if not provided) */
+    logger?: Logger;
+    /** Maximum output log lines per session (default: 1000) */
+    maxLogLines?: number;
+    /** Enable stall detection (default: false) */
+    stallDetectionEnabled?: boolean;
+    /** Default stall timeout in ms (default: 8000). Can be overridden per-session via SpawnConfig. */
+    stallTimeoutMs?: number;
+    /**
+     * External classification callback invoked when a stall is detected.
+     */
+    onStallClassify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>;
+    /** Tmux scrollback history limit per session (default: 50000) */
+    historyLimit?: number;
+    /** Tmux session name prefix (default: 'parallax') */
+    sessionPrefix?: string;
+}
+
+/**
+ * Tmux Transport Layer
+ *
+ * Low-level interface to tmux sessions via the tmux CLI.
+ * Replaces node-pty as the PTY backend — no native addons required.
+ */
+interface TmuxSpawnOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    cols: number;
+    rows: number;
+    historyLimit: number;
+}
+interface TmuxCaptureOptions {
+    /** Include ANSI escape codes (default: false) */
+    ansi?: boolean;
+    /** Number of lines from scrollback to include (default: visible only) */
+    scrollback?: number;
+}
+/**
+ * Mapping from our SPECIAL_KEYS names to tmux send-keys key names.
+ */
+declare const TMUX_KEY_MAP: Record<string, string>;
+/**
+ * Low-level tmux session transport.
+ * Manages tmux sessions via CLI commands.
+ */
+declare class TmuxTransport {
+    private pollingTimers;
+    private lastCapture;
+    constructor();
+    /**
+     * Spawn a new tmux session running the given command.
+     */
+    spawn(sessionName: string, options: TmuxSpawnOptions): void;
+    /**
+     * Check if a tmux session exists and is alive.
+     */
+    isAlive(sessionName: string): boolean;
+    /**
+     * Kill a tmux session.
+     */
+    kill(sessionName: string): void;
+    /**
+     * Send a signal to the process in the tmux pane.
+     */
+    signal(sessionName: string, sig: string): void;
+    /**
+     * Send literal text to the tmux session (no key interpretation).
+     */
+    sendText(sessionName: string, text: string): void;
+    /**
+     * Send a named key to the tmux session.
+     * Uses TMUX_KEY_MAP for translation from our key names.
+     */
+    sendKey(sessionName: string, key: string): void;
+    /**
+     * Capture the current pane content.
+     */
+    capturePane(sessionName: string, options?: TmuxCaptureOptions): string;
+    /**
+     * Start polling output from a tmux session via capture-pane.
+     * Polls at the given interval and calls the callback with new/changed content.
+     *
+     * Uses capture-pane with ANSI codes (-e) and scrollback for full fidelity.
+     * Compares against last capture to detect changes and emit only new data.
+     */
+    startOutputStreaming(sessionName: string, callback: (data: string) => void, pollIntervalMs?: number): void;
+    /**
+     * Stop polling output from a tmux session.
+     */
+    stopOutputStreaming(sessionName: string): void;
+    /**
+     * Get the PID of the process running in the tmux pane.
+     */
+    getPanePid(sessionName: string): number | undefined;
+    /**
+     * Get the pane dimensions.
+     */
+    getPaneDimensions(sessionName: string): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Resize a tmux session window.
+     */
+    resize(sessionName: string, cols: number, rows: number): void;
+    /**
+     * Check if the pane's process has exited.
+     * Uses remain-on-exit to detect dead panes.
+     */
+    isPaneAlive(sessionName: string): boolean;
+    /**
+     * Get the exit status of a dead pane.
+     */
+    getPaneExitStatus(sessionName: string): number | undefined;
+    /**
+     * List all tmux sessions matching a prefix.
+     */
+    static listSessions(prefix?: string): Array<{
+        name: string;
+        created: string;
+        attached: boolean;
+    }>;
+    /**
+     * Clean up resources.
+     */
+    destroy(): void;
+    private tmuxExec;
+    private shellEscape;
+}
+
+/**
+ * Tmux Session
+ *
+ * Manages a single tmux session for a CLI tool.
+ * Mirrors PTYSession's API but uses TmuxTransport instead of node-pty.
+ */
+
+interface TmuxSessionEvents {
+    output: (data: string) => void;
+    ready: () => void;
+    login_required: (instructions?: string, url?: string) => void;
+    auth_required: (info: AuthRequiredInfo) => void;
+    blocking_prompt: (prompt: BlockingPromptInfo, autoResponded: boolean) => void;
+    message: (message: SessionMessage) => void;
+    question: (question: string) => void;
+    exit: (code: number) => void;
+    error: (error: Error) => void;
+    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 (for compatibility with adapters that reference SPECIAL_KEYS)
+ */
+declare const SPECIAL_KEYS: Record<string, string>;
+declare class TmuxSession extends EventEmitter {
+    private adapter;
+    private transport;
+    private tmuxSessionName;
+    private outputBuffer;
+    private _status;
+    private _startedAt;
+    private _lastActivityAt;
+    private messageCounter;
+    private logger;
+    private sessionRules;
+    private _firedOnceRules;
+    private _lastBlockingPromptHash;
+    private _ruleOverrides;
+    private _disabledRulePatterns;
+    private _stallTimer;
+    private _stallTimeoutMs;
+    private _stallDetectionEnabled;
+    private _lastStallHash;
+    private _stallStartedAt;
+    private _lastContentHash;
+    private _stallBackoffMs;
+    private static readonly MAX_STALL_BACKOFF_MS;
+    private _stallEmissionCount;
+    private static readonly MAX_STALL_EMISSIONS;
+    private _taskCompleteTimer;
+    private _taskCompletePending;
+    private static readonly TASK_COMPLETE_DEBOUNCE_MS;
+    private _readySettleTimer;
+    private _readySettlePending;
+    private _lastToolRunningName;
+    private static readonly MAX_OUTPUT_BUFFER;
+    private _exitPollTimer;
+    private sessionPrefix;
+    private historyLimit;
+    readonly id: string;
+    readonly config: SpawnConfig;
+    constructor(adapter: CLIAdapter, config: SpawnConfig, logger?: Logger, stallDetectionEnabled?: boolean, defaultStallTimeoutMs?: number, transport?: TmuxTransport, sessionPrefix?: string, historyLimit?: number);
+    get status(): SessionStatus;
+    get pid(): number | undefined;
+    get startedAt(): Date | undefined;
+    get lastActivityAt(): Date | undefined;
+    /**
+     * Get the tmux session name (for reconnection/debugging).
+     */
+    get tmuxName(): string;
+    addAutoResponseRule(rule: AutoResponseRule): void;
+    removeAutoResponseRule(pattern: RegExp): boolean;
+    setAutoResponseRules(rules: AutoResponseRule[]): void;
+    getAutoResponseRules(): AutoResponseRule[];
+    clearAutoResponseRules(): void;
+    private resetStallTimer;
+    private clearStallTimer;
+    private onStallTimerFired;
+    handleStallClassification(classification: StallClassification | null): void;
+    private scheduleTaskComplete;
+    private isTaskCompleteSignal;
+    private cancelTaskComplete;
+    private scheduleReadySettle;
+    private cancelReadySettle;
+    start(): Promise<void>;
+    /**
+     * Reconnect to an existing tmux session.
+     * Used for crash recovery.
+     */
+    reconnect(existingTmuxName: string): Promise<void>;
+    private handleExit;
+    private stopExitPolling;
+    private processOutputBuffer;
+    private detectAndHandleBlockingPrompt;
+    private tryAutoResponse;
+    private tryParseOutput;
+    /**
+     * Write data to the session (formatted by adapter, with Enter)
+     */
+    write(data: string): void;
+    /**
+     * Write raw data directly (no formatting, no Enter)
+     */
+    writeRaw(data: string): void;
+    /**
+     * Send a task/message to the session
+     */
+    send(message: string): SessionMessage;
+    /**
+     * Resize the terminal
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Send special keys to the session.
+     * Uses tmux send-keys with named keys.
+     */
+    sendKeys(keys: string | string[]): void;
+    /**
+     * Select a TUI menu option by index (0-based).
+     */
+    selectMenuOption(optionIndex: number): Promise<void>;
+    /**
+     * Send a sequence of keys with staggered timing.
+     */
+    private sendKeySequence;
+    /**
+     * Paste text using bracketed paste mode
+     */
+    paste(text: string, useBracketedPaste?: boolean): void;
+    /**
+     * Notify the session of an external hook event.
+     */
+    notifyHookEvent(event: string): void;
+    /**
+     * Kill the session.
+     */
+    kill(signal?: string): void;
+    /**
+     * Get current output buffer
+     */
+    getOutputBuffer(): string;
+    /**
+     * Clear output buffer
+     */
+    clearOutputBuffer(): void;
+    /**
+     * Convert to SessionHandle
+     */
+    toHandle(): SessionHandle;
+    static buildSpawnEnv(config: SpawnConfig, adapterEnv: Record<string, string>): Record<string, string>;
+    static normalizeKeyList(keys: string[]): string[];
+    private delay;
+    private simpleHash;
+    private mapLoginTypeToAuthMethod;
+    private emitAuthRequired;
+    /**
+     * Strip ANSI codes for stall detection hashing.
+     * Simplified compared to pty-manager since tmux capture-pane can give clean text.
+     */
+    private stripAnsiForStall;
+    /**
+     * Less-aggressive ANSI stripping for classifier context.
+     */
+    private stripAnsiForClassifier;
+}
+
+/**
+ * Tmux Manager
+ *
+ * Manages multiple tmux sessions for CLI tools.
+ * Mirrors PTYManager's API but uses tmux as the transport layer.
+ */
+
+interface TmuxManagerEvents {
+    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;
+    auth_required: (session: SessionHandle, info: AuthRequiredInfo) => void;
+    blocking_prompt: (session: SessionHandle, promptInfo: BlockingPromptInfo, autoResponded: boolean) => void;
+    message: (message: SessionMessage) => void;
+    question: (session: SessionHandle, question: string) => void;
+    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 TmuxManager extends EventEmitter {
+    private sessions;
+    private outputLogs;
+    private maxLogLines;
+    private logger;
+    private transport;
+    readonly adapters: AdapterRegistry;
+    private _stallDetectionEnabled;
+    private _stallTimeoutMs;
+    private _onStallClassify?;
+    private _historyLimit;
+    private _sessionPrefix;
+    constructor(config?: TmuxManagerConfig);
+    /**
+     * Register a CLI adapter
+     */
+    registerAdapter(adapter: CLIAdapter): void;
+    /**
+     * Spawn a new tmux 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 TmuxSession (for advanced use)
+     */
+    getSession(sessionId: string): TmuxSession | undefined;
+    /**
+     * List orphaned tmux sessions from previous runs.
+     * These are tmux sessions with the configured prefix that aren't tracked by this manager.
+     */
+    listOrphanedSessions(): Array<{
+        name: string;
+        created: string;
+        attached: boolean;
+    }>;
+    /**
+     * Clean up orphaned tmux sessions from previous runs.
+     */
+    cleanupOrphanedSessions(): number;
+    configureStallDetection(enabled: boolean, timeoutMs?: number, classify?: (sessionId: string, recentOutput: string, stallDurationMs: number) => Promise<StallClassification | null>): void;
+    addAutoResponseRule(sessionId: string, rule: AutoResponseRule): void;
+    removeAutoResponseRule(sessionId: string, pattern: RegExp): boolean;
+    setAutoResponseRules(sessionId: string, rules: AutoResponseRule[]): void;
+    getAutoResponseRules(sessionId: string): AutoResponseRule[];
+    clearAutoResponseRules(sessionId: string): void;
+}
+
+/**
+ * Task completion trace analysis helpers.
+ *
+ * Parses structured "Task completion trace" logs and builds a compact
+ * per-turn confidence timeline useful for debugging idle/completion detection.
+ */
+interface TaskCompletionTraceRecord {
+    sessionId?: string;
+    adapterType?: string;
+    event: string;
+    status?: string;
+    taskCompletePending?: boolean;
+    signal?: boolean;
+    wasPending?: boolean;
+    debounceMs?: number;
+    detectTaskComplete?: boolean;
+    detectReady?: boolean;
+    detectLoading?: boolean;
+    tailHash?: string;
+    tailSnippet?: string;
+    timestamp?: string | number | Date;
+}
+interface TaskCompletionTimelineStep {
+    event: string;
+    atIndex: number;
+    status: 'active' | 'active_loading' | 'likely_complete' | 'completed' | 'rejected';
+    confidence: number;
+    signal?: boolean;
+    detectTaskComplete?: boolean;
+    detectReady?: boolean;
+    detectLoading?: boolean;
+}
+interface TaskCompletionTurnTimeline {
+    turn: number;
+    startIndex: number;
+    endIndex: number;
+    completed: boolean;
+    maxConfidence: number;
+    finalConfidence: number;
+    events: TaskCompletionTimelineStep[];
+}
+interface TaskCompletionTimelineResult {
+    turns: TaskCompletionTurnTimeline[];
+    totalRecords: number;
+    ignoredRecords: number;
+}
+interface BuildTimelineOptions {
+    adapterType?: string;
+}
+/**
+ * Extract trace records from mixed log inputs.
+ */
+declare function extractTaskCompletionTraceRecords(entries: Array<string | Record<string, unknown>>): TaskCompletionTraceRecord[];
+/**
+ * Build a per-turn confidence timeline from task-completion traces.
+ */
+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;
+    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;
+}
+
+export { type AuthRequiredInfo, type AuthRequiredMethod, type BlockingPromptInfo, type BuildTimelineOptions, type LogOptions, type Logger, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type StallClassification, type StopOptions, TMUX_KEY_MAP, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type TmuxCaptureOptions, TmuxManager, type TmuxManagerConfig, type TmuxManagerEvents, TmuxSession, type TmuxSessionEvents, type TmuxSpawnOptions, TmuxTransport, buildTaskCompletionTimeline, ensureTmux, extractTaskCompletionTraceRecords, resetTmuxCheck };