aegis-bridge 0.1.0

package/dist/terminal-parser.js

@@ -0,0 +1,346 @@
+/**
+ * terminal-parser.ts — Detects Claude Code UI state from tmux pane content.
+ *
+ * Port of CCBot's terminal_parser.py.
+ * Detects: permission prompts, plan mode, ask questions, status line.
+ */
+const UI_PATTERNS = [
+    {
+        name: 'plan_mode',
+        top: [
+            /^\s*Would you like to proceed\?/,
+            /^\s*Claude has written up a plan/,
+        ],
+        bottom: [
+            /^\s*ctrl-g to edit in /,
+            /^\s*Esc to (cancel|exit)/,
+        ],
+        minGap: 2,
+    },
+    {
+        name: 'ask_question',
+        top: [/^\s*[☐✔☒]/],
+        bottom: [/^\s*Enter to select/],
+        minGap: 1,
+    },
+    {
+        name: 'permission_prompt',
+        top: [
+            /^\s*Do you want to proceed\?/,
+            /^\s*Do you want to make this edit/,
+            /^\s*Do you want to create \S/,
+            /^\s*Do you want to delete \S/,
+            /^\s*Do you want to allow Claude to make these changes/, // batch edit
+            /^\s*Do you want to allow Claude to use/, // MCP tool
+            /^\s*Do you want to trust this (project|workspace)/, // workspace trust (old)
+            /^\s*Quick safety check/, // workspace trust (CC ≥2.1.92)
+            /^\s*Is this a project you created/, // workspace trust alt text
+            /^\s*Do you want to allow (reading|writing)/, // file scope
+            /^\s*Do you want to run this command/, // alt bash approval
+            /^\s*Do you want to allow writing to/, // file write scope
+            /^\s*Continue\?/, // continuation
+        ],
+        bottom: [/^\s*Esc to cancel/],
+        minGap: 2,
+    },
+    {
+        name: 'permission_prompt',
+        top: [/^\s*❯\s*1\.\s*Yes/],
+        bottom: [],
+        minGap: 2,
+    },
+    {
+        name: 'bash_approval',
+        top: [
+            /^\s*Bash command\s*$/,
+            /^\s*This command requires approval/,
+        ],
+        bottom: [/^\s*Esc to cancel/],
+        minGap: 2,
+    },
+    {
+        name: 'settings',
+        top: [
+            /^\s*Settings:.*tab to cycle/,
+            /^\s*Select model/,
+        ],
+        bottom: [
+            /^\s*Esc to cancel/,
+            /^\s*Esc to exit/,
+            /^\s*Enter to confirm/,
+            /^\s*Type to filter/,
+        ],
+        minGap: 2,
+    },
+    {
+        name: 'error',
+        top: [
+            /^Error:/,
+            /Rate limit/,
+            /Authentication failed/,
+            /overloaded/i,
+            /API error/,
+            /^429\b/,
+        ],
+        bottom: [/^\s*❯\s*$/],
+        minGap: 1,
+    },
+];
+// Spinner characters Claude Code uses (including braille spinners with TERM=xterm-256color)
+// Issue #102: CC also uses * (asterisk) and ● (bullet) for status lines like "* Perambulating…"
+const STATUS_SPINNERS = new Set([
+    '·', '✻', '✽', '✶', '✳', '✢', '*', '●',
+    '⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏',
+    '⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷',
+]);
+/** Detect the UI state from captured pane text. */
+export function detectUIState(paneText) {
+    if (!paneText)
+        return 'unknown';
+    const lines = paneText.trim().split('\n');
+    // Check for interactive UI patterns first (highest priority)
+    for (const pattern of UI_PATTERNS) {
+        if (tryMatchPattern(lines, pattern)) {
+            return pattern.name;
+        }
+    }
+    // Check for working status — scan entire pane for active spinners
+    const statusText = parseStatusLine(paneText);
+    const hasActiveSpinner = hasSpinnerAnywhere(lines);
+    // Check for the prompt (❯) near the bottom
+    const hasPrompt = hasIdlePrompt(lines);
+    const hasChrome = hasChromeSeparator(lines);
+    if (statusText) {
+        // "Worked for Xs" = finished, not working; "Aborted" = CC was interrupted
+        if (/^Worked for/i.test(statusText) || /^Compacted/i.test(statusText) || /aborted/i.test(statusText)) {
+            return hasPrompt ? 'idle' : 'unknown';
+        }
+        // Active spinner text = working regardless of prompt
+        return 'working';
+    }
+    // Even without parseStatusLine match, if we see active spinners → working
+    if (hasActiveSpinner) {
+        return 'working';
+    }
+    // L30: Check for compacting state — CC shows "Compacting..." when compacting context
+    // Checked after working so active spinners take priority over compacting text
+    const compactingState = detectCompacting(lines);
+    if (compactingState)
+        return 'compacting';
+    // L31: Check for context window warning — CC shows "Context window X% full"
+    const contextWarning = detectContextWarning(lines);
+    if (contextWarning)
+        return 'context_warning';
+    if (hasPrompt) {
+        // L32: Differentiate idle (chrome separator present) vs waiting_for_input (no chrome)
+        return hasChrome ? 'idle' : 'waiting_for_input';
+    }
+    // Check for chrome separator (─────) near bottom = CC is loaded
+    if (hasChrome) {
+        return 'idle';
+    }
+    // L32: Check for waiting-for-input patterns without the idle separator
+    if (detectWaitingForInput(lines))
+        return 'waiting_for_input';
+    return 'unknown';
+}
+/** Number of lines from the bottom of the pane to scan for active spinners. */
+const SPINNER_SEARCH_LINES = 30;
+/** Check if any line in the pane has an active spinner character followed by working text. */
+function hasSpinnerAnywhere(lines) {
+    // Only check lines in the content area (not the very bottom few which are prompt/footer)
+    const searchEnd = Math.max(0, lines.length - 3);
+    for (let i = Math.max(0, lines.length - SPINNER_SEARCH_LINES); i < searchEnd; i++) {
+        const stripped = lines[i].trim();
+        if (!stripped)
+            continue;
+        // Check for spinner characters at start of line, followed by text containing "…" or "..."
+        const firstChar = stripped[0];
+        if (STATUS_SPINNERS.has(firstChar) && stripped.length > 1) {
+            // For `*` (also a markdown bullet), require `* ` + ellipsis/dots to avoid false positives
+            if (firstChar === '*') {
+                if (stripped[1] !== ' ' || !(stripped.includes('…') || stripped.includes('...')))
+                    continue;
+            }
+            else if (!(stripped.includes('…') || stripped.includes('...') || /[^\s\u00a0]/.test(stripped.slice(1)))) {
+                continue;
+            }
+            // Exclude "Worked for" which is a completion indicator, and "Aborted" which means CC stopped
+            if (/^.Worked for/i.test(stripped) || /^.Compacted/i.test(stripped) || /aborted/i.test(stripped))
+                continue;
+            return true;
+        }
+    }
+    return false;
+}
+/** Check if the prompt ❯ is visible between chrome separators. */
+function hasIdlePrompt(lines) {
+    // Look for ❯ on its own line near the bottom, between two ─── separators
+    for (let i = Math.max(0, lines.length - 8); i < lines.length; i++) {
+        const stripped = lines[i].trim();
+        if (stripped === '❯' || stripped === '❯\u00a0' || stripped.startsWith('❯ ') || stripped.startsWith('❯\u00a0')) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Check if a chrome separator (─────) is present near the bottom of the pane. */
+function hasChromeSeparator(lines) {
+    for (let i = Math.max(0, lines.length - 10); i < lines.length; i++) {
+        const stripped = lines[i].trim();
+        if (stripped.length >= 20 && /^─+$/.test(stripped)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** L30: Detect compacting state — CC shows "Compacting..." when compacting context. */
+function detectCompacting(lines) {
+    // Check last 15 lines for compacting indicators
+    const searchStart = Math.max(0, lines.length - 15);
+    for (let i = searchStart; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (/compacting/i.test(line) && !/compacted/i.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** L31: Detect context window warning — CC shows "Context window X% full". */
+function detectContextWarning(lines) {
+    // Check last 15 lines for context window warnings
+    const searchStart = Math.max(0, lines.length - 15);
+    for (let i = searchStart; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (/context\s+window/i.test(line) && /(\d+)%/.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** L32: Detect waiting-for-input state — CC prompt without chrome separator. */
+function detectWaitingForInput(lines) {
+    // Look for prompt-like text near the bottom without the chrome separator
+    const searchStart = Math.max(0, lines.length - 8);
+    for (let i = searchStart; i < lines.length; i++) {
+        const stripped = lines[i].trim();
+        // ❯ with text (but not bare ❯ which is idle)
+        if ((stripped.startsWith('❯ ') || stripped.startsWith('❯\u00a0')) && stripped.length > 2) {
+            return true;
+        }
+        // CC asking questions like "What would you like to do?" near bottom
+        if (/^(What would you like|What do you want|How would you like|How should I)/i.test(stripped)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Extract the interactive UI content if present. */
+export function extractInteractiveContent(paneText) {
+    if (!paneText)
+        return null;
+    const lines = paneText.trim().split('\n');
+    for (const pattern of UI_PATTERNS) {
+        const result = extractPattern(lines, pattern);
+        if (result)
+            return { content: result, name: pattern.name };
+    }
+    return null;
+}
+/** Parse the status line text (what CC is doing). */
+export function parseStatusLine(paneText) {
+    if (!paneText)
+        return null;
+    const lines = paneText.split('\n');
+    // Find chrome separator
+    let chromeIdx = null;
+    const searchStart = Math.max(0, lines.length - 10);
+    for (let i = searchStart; i < lines.length; i++) {
+        const stripped = lines[i].trim();
+        if (stripped.length >= 20 && /^─+$/.test(stripped)) {
+            chromeIdx = i;
+            break;
+        }
+    }
+    if (chromeIdx === null)
+        return null;
+    // Check lines above separator for spinner
+    for (let i = chromeIdx - 1; i > Math.max(chromeIdx - 10, -1); i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        if (STATUS_SPINNERS.has(line[0])) {
+            // For `*`, require `* ` + ellipsis/dots to avoid matching markdown bullets
+            if (line[0] === '*' && (line[1] !== ' ' || !(line.includes('…') || line.includes('...')))) {
+                // Not a real spinner line — skip
+                continue;
+            }
+            return line.slice(1).trim();
+        }
+        // Skip non-spinner lines (tool output between spinner and separator) and keep scanning
+    }
+    return null;
+}
+function tryMatchPattern(lines, pattern) {
+    // Only search the last 30 lines to avoid matching scrollback text
+    const searchStart = Math.max(0, lines.length - 30);
+    // Try each top match — don't give up after the first one fails to find a bottom
+    for (let t = searchStart; t < lines.length; t++) {
+        if (!pattern.top.some(re => re.test(lines[t])))
+            continue;
+        if (pattern.bottom.length === 0) {
+            const lastNonEmpty = findLastNonEmpty(lines, t + 1);
+            if (lastNonEmpty !== null && lastNonEmpty - t >= pattern.minGap) {
+                return true;
+            }
+            continue;
+        }
+        // Search for a matching bottom after this top
+        for (let b = t + 1; b < lines.length; b++) {
+            if (pattern.bottom.some(re => re.test(lines[b]))) {
+                if (b - t >= pattern.minGap) {
+                    return true;
+                }
+            }
+        }
+        // No matching bottom for this top — try next top match
+    }
+    return false;
+}
+function extractPattern(lines, pattern) {
+    let topIdx = null;
+    let bottomIdx = null;
+    // Only search the last 30 lines to avoid matching scrollback text
+    const searchStart = Math.max(0, lines.length - 30);
+    for (let i = searchStart; i < lines.length; i++) {
+        if (topIdx === null) {
+            if (pattern.top.some(re => re.test(lines[i]))) {
+                topIdx = i;
+            }
+        }
+        else if (pattern.bottom.length > 0 && pattern.bottom.some(re => re.test(lines[i]))) {
+            bottomIdx = i;
+            break;
+        }
+    }
+    if (topIdx === null)
+        return null;
+    if (pattern.bottom.length === 0) {
+        bottomIdx = findLastNonEmpty(lines, topIdx + 1);
+    }
+    if (bottomIdx === null || bottomIdx - topIdx < pattern.minGap)
+        return null;
+    return lines.slice(topIdx, bottomIdx + 1).join('\n').trimEnd();
+}
+function findLastNonEmpty(lines, from = 0) {
+    let last = null;
+    for (let i = from; i < lines.length; i++) {
+        if (lines[i].trim())
+            last = i;
+    }
+    return last;
+}

package/dist/tmux-capture-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * tmux-capture-cache.ts — TTL-based cache for capture-pane results.
+ *
+ * Avoids redundant tmux capture-pane CLI calls when the same window
+ * is polled multiple times within a short window (e.g. monitor poll +
+ * status check hitting the same pane).
+ */
+export declare class TmuxCaptureCache {
+    private cache;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    /** Return cached capture-pane text if within TTL, otherwise call `captureFn` and cache. */
+    get(windowId: string, captureFn: () => Promise<string>): Promise<string>;
+    /** Invalidate a single window's cached result. */
+    invalidate(windowId: string): void;
+    /** Clear all cached entries. */
+    clear(): void;
+}

package/dist/tmux-capture-cache.js

@@ -0,0 +1,34 @@
+/**
+ * tmux-capture-cache.ts — TTL-based cache for capture-pane results.
+ *
+ * Avoids redundant tmux capture-pane CLI calls when the same window
+ * is polled multiple times within a short window (e.g. monitor poll +
+ * status check hitting the same pane).
+ */
+const DEFAULT_TTL_MS = 500;
+export class TmuxCaptureCache {
+    cache = new Map();
+    ttlMs;
+    constructor(ttlMs = DEFAULT_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    /** Return cached capture-pane text if within TTL, otherwise call `captureFn` and cache. */
+    async get(windowId, captureFn) {
+        const now = Date.now();
+        const entry = this.cache.get(windowId);
+        if (entry && now - entry.at < this.ttlMs) {
+            return entry.text;
+        }
+        const text = await captureFn();
+        this.cache.set(windowId, { text, at: now });
+        return text;
+    }
+    /** Invalidate a single window's cached result. */
+    invalidate(windowId) {
+        this.cache.delete(windowId);
+    }
+    /** Clear all cached entries. */
+    clear() {
+        this.cache.clear();
+    }
+}

package/dist/tmux.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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.
+ */
+/** Build the platform-specific launch wrapper that clears inherited tmux vars. */
+export declare function buildClaudeLaunchCommand(baseCommand: string, platform?: NodeJS.Platform): string;
+/** 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;
+    paneDead?: boolean;
+}
+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;
+    /** Determine whether an error indicates tmux rejected a duplicate window name. */
+    private isDuplicateWindowNameError;
+    /** Compute an available window name by suffixing -2, -3, ... when needed. */
+    private resolveAvailableWindowName;
+    /** 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;
+    /** #909: Windows variant — set tmux env and dot-source a temp .ps1 in the active pane. */
+    private setEnvSecureWin32;
+    /** #837: Direct variant of setEnvSecure that uses sendKeysDirectInternal instead of
+     *  sendKeys, safe to call from inside a serialize() callback without deadlocking.
+     *  Identical logic otherwise. */
+    private setEnvSecureDirect;
+    /** #909: Direct Windows variant that avoids serialize() re-entry. */
+    private setEnvSecureDirectWin32;
+    /** 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;
+        paneDead: 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 through the serialize queue.
+     *  #824: Always serialize to prevent race conditions with concurrent reads
+     *  from monitor polls and ! command mode. The previous _creatingCount guard
+     *  only queued during window creation, leaving a race window at other times.
+     */
+    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>;
+    /** Issue #397: Check if the tmux server is reachable and healthy.
+     *  Returns { healthy, error } — does not throw. */
+    isServerHealthy(): Promise<{
+        healthy: boolean;
+        error: string | null;
+    }>;
+    /** Issue #397: Check if a tmux error indicates the server crashed (vs window-not-found).
+     *  Server crash errors contain specific patterns from tmux CLI. */
+    isTmuxServerError(error: unknown): boolean;
+    /** 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;
+}