aegis-bridge 2.2.2

package/dist/tmux.d.ts

@@ -0,0 +1,161 @@
+/**
+ * tmux.ts — Low-level tmux interaction layer.
+ *
+ * Wraps tmux CLI commands to manage windows inside a named session.
+ * Port of CCBot's tmux_manager.py to TypeScript.
+ */
+/** Thrown when a tmux command exceeds its timeout. */
+export declare class TmuxTimeoutError extends Error {
+    constructor(args: string[], timeoutMs: number);
+}
+export interface TmuxWindow {
+    windowId: string;
+    windowName: string;
+    cwd: string;
+    paneCommand: string;
+}
+export declare class TmuxManager {
+    private sessionName;
+    /** tmux socket name (-L flag). Isolates sessions from other tmux instances. */
+    readonly socketName: string;
+    /** #357: Cache for window existence checks — avoids repeated tmux CLI calls. */
+    private windowExistsCache;
+    private static readonly WINDOW_CACHE_TTL_MS;
+    constructor(sessionName?: string, socketName?: string);
+    /** Promise-chain queue that serializes all tmux CLI calls to prevent race conditions. */
+    private queue;
+    /** #403: Counter of in-flight createWindow calls — direct methods must queue when > 0. */
+    private _creatingCount;
+    /** #357: Short-lived cache for window existence checks to reduce CLI calls. */
+    private windowCache;
+    /** Run `fn` sequentially after all previously-queued operations complete. */
+    private serialize;
+    /** Run a tmux command and return stdout (serialized through the queue).
+     *  Issue #66: All tmux commands have a timeout to prevent hangs.
+     *  A single hung tmux command would otherwise block the entire Aegis server.
+     */
+    private tmux;
+    private tmuxInternal;
+    /** Ensure our tmux session exists and is healthy.
+     *  Issue #7: After prolonged uptime, tmux session may exist but be degraded.
+     *  We verify by listing windows — if that fails, recreate the session.
+     */
+    ensureSession(): Promise<void>;
+    /** #403: Internal version that calls tmuxInternal directly (safe inside serialize). */
+    private ensureSessionInternal;
+    /** List all windows (excluding the placeholder _bridge_main). */
+    listWindows(): Promise<TmuxWindow[]>;
+    /** Create a new window, start claude, return window info.
+     *  Issue #7: Retries up to 3x on failure, with tmux session health check between retries.
+     */
+    createWindow(opts: {
+        workDir: string;
+        windowName: string;
+        claudeCommand?: string;
+        resumeSessionId?: string;
+        env?: Record<string, string>;
+        permissionMode?: string;
+        /** Path to a CC settings JSON file (via --settings flag). */
+        settingsFile?: string;
+        /** @deprecated Use permissionMode instead. Maps true→bypassPermissions, false→default. */
+        autoApprove?: boolean;
+    }): Promise<{
+        windowId: string;
+        windowName: string;
+        freshSessionId?: string;
+    }>;
+    /**
+     * Archive old Claude session files so interactive mode starts fresh.
+     *
+     * Claude CLI computes a project hash from the workDir path:
+     *   /home/user/projects/foo → -home-user-projects-foo
+     * and stores sessions at ~/.claude/projects/<hash>/*.jsonl.
+     *
+     * In interactive mode, Claude always auto-resumes the latest .jsonl file.
+     * There is no CLI flag to disable this. The only reliable way to force a
+     * fresh session is to move existing .jsonl files out of the way.
+     *
+     * Files are moved to an `_archived/` subfolder (not deleted), so they can
+     * be recovered if needed.
+     */
+    private archiveStaleSessionFiles;
+    /** Issue #23: Set env vars securely without exposing values in tmux pane.
+     *  Writes vars to a temp file, sources it, then deletes it.
+     *  Values never appear in terminal scrollback or capture-pane output.
+     */
+    private setEnvSecure;
+    /** P1 fix: Check if a window exists. Returns true if window is in the session.
+     *  #357: Uses a short-lived cache to avoid repeated tmux CLI calls. */
+    windowExists(windowId: string): Promise<boolean>;
+    /** Issue #69: Get the PID of the first pane in a window. Returns null on error. */
+    listPanePid(windowId: string): Promise<number | null>;
+    /** Issue #69: Check if a PID is alive using kill -0. */
+    isPidAlive(pid: number): boolean;
+    /** Get detailed window info for health checks.
+     *  Issue #2: Returns window existence, pane command, and whether Claude is running.
+     */
+    getWindowHealth(windowId: string): Promise<{
+        windowExists: boolean;
+        paneCommand: string | null;
+        claudeRunning: boolean;
+    }>;
+    /** Send text to a window's active pane. */
+    sendKeys(windowId: string, text: string, enter?: boolean): Promise<void>;
+    /** Check if a pane state indicates CC has received input (non-idle). */
+    private isActiveState;
+    /** Verify that a message was delivered to Claude Code.
+     *  Issue #1 v2: Compares pre-send and post-send pane state to detect delivery.
+     *
+     *  Strategy:
+     *  1. If CC transitioned from idle → active state → confirmed
+     *  2. If CC is in any active state (working, permission, etc.) → confirmed
+     *  3. If sent text (prefix) is visible in the pane → confirmed
+     *  4. If CC is still idle with no trace of input → NOT confirmed
+     *  5. Unknown state → benefit of the doubt (confirmed)
+     *
+     *  The `preSendState` parameter enables state-change detection to avoid
+     *  false negatives during transitional moments.
+     */
+    verifyDelivery(windowId: string, sentText: string, preSendState?: string): Promise<boolean>;
+    /** Send text and verify delivery with retry.
+     *  Issue #1 v2: Captures pre-send state and only re-sends if pane is still idle.
+     *  Prevents duplicate prompt delivery that plagued v1.
+     */
+    sendKeysVerified(windowId: string, text: string, maxAttempts?: number): Promise<{
+        delivered: boolean;
+        attempts: number;
+    }>;
+    /** Send a special key (Escape, C-c, etc.) */
+    sendSpecialKey(windowId: string, key: string): Promise<void>;
+    /** Capture the visible pane content.
+     *  Issue #89 L23: Strips DCS passthrough sequences (ESC P ... ESC \\)
+     *  that can leak through tmux's capture-pane into the output.
+     */
+    capturePane(windowId: string): Promise<string>;
+    /** Capture pane content WITHOUT going through the serialize queue.
+     *  Used for critical-path operations (e.g., sendInitialPrompt) that should
+     *  not be delayed by monitor polls. The queue is for preventing race conditions
+     *  in monitor/concurrent reads, but sendInitialPrompt is the ONLY writer at
+     *  session creation time.
+     *  #403: During window creation (_creatingCount > 0), queues behind serialize
+     *  to avoid racing with the creation sequence.
+     */
+    capturePaneDirect(windowId: string): Promise<string>;
+    private capturePaneDirectInternal;
+    /** Send keys WITHOUT going through the serialize queue.
+     *  Used for critical-path operations (e.g., sendInitialPrompt).
+     *  Simplified version: sends literal text + Enter (no ! command mode handling).
+     *  #403: During window creation (_creatingCount > 0), queues behind serialize
+     *  to avoid racing with the creation sequence.
+     */
+    sendKeysDirect(windowId: string, text: string, enter?: boolean): Promise<void>;
+    private sendKeysDirectInternal;
+    /** Resize a window's pane to the given dimensions. */
+    resizePane(windowId: string, cols: number, rows: number): Promise<void>;
+    /** Kill a window. */
+    killWindow(windowId: string): Promise<void>;
+    /** Kill the entire tmux session. Used for cleanup on shutdown. */
+    killSession(sessionName?: string): Promise<void>;
+    /** #357: Poll until condition returns true or timeout elapses. */
+    private pollUntil;
+}