aegis-bridge 2.2.2

package/dist/session.d.ts

@@ -0,0 +1,297 @@
+/**
+ * session.ts — Session state manager.
+ *
+ * Manages the lifecycle of CC sessions running in tmux windows.
+ * Tracks: session ID, window ID, byte offset for JSONL reading, status.
+ */
+import { TmuxManager } from './tmux.js';
+import { type ParsedEntry } from './transcript.js';
+import { type UIState } from './terminal-parser.js';
+import type { Config } from './config.js';
+export interface SessionInfo {
+    id: string;
+    windowId: string;
+    windowName: string;
+    workDir: string;
+    claudeSessionId?: string;
+    jsonlPath?: string;
+    byteOffset: number;
+    monitorOffset: number;
+    status: UIState;
+    createdAt: number;
+    lastActivity: number;
+    stallThresholdMs: number;
+    permissionStallMs: number;
+    permissionMode: string;
+    settingsPatched?: boolean;
+    hookSettingsFile?: string;
+    lastHookAt?: number;
+    activeSubagents?: Set<string>;
+    permissionPromptAt?: number;
+    permissionRespondedAt?: number;
+    lastHookReceivedAt?: number;
+    lastHookEventAt?: number;
+    model?: string;
+    lastDeadAt?: number;
+    ccPid?: number;
+}
+export interface SessionState {
+    sessions: Record<string, SessionInfo>;
+}
+/**
+ * Detect whether CC is showing numbered permission options (e.g. "1. Yes, 2. No")
+ * vs a simple y/N prompt. Returns the approval method to use.
+ *
+ * CC's permission UI uses indented numbered lines with "Esc to cancel" nearby.
+ * We look for the pattern "  <N>. <option>" where N is 1-3, which distinguishes
+ * permission options from regular numbered lists in output.
+ */
+export declare function detectApprovalMethod(paneText: string): 'numbered' | 'yes';
+/** Resolves a pending PermissionRequest hook with a decision. */
+export type PermissionDecision = 'allow' | 'deny';
+export declare class SessionManager {
+    private tmux;
+    private config;
+    private state;
+    private stateFile;
+    private sessionMapFile;
+    private pollTimers;
+    private saveQueue;
+    private saveDebounceTimer;
+    private static readonly SAVE_DEBOUNCE_MS;
+    private pendingPermissions;
+    private pendingQuestions;
+    private parsedEntriesCache;
+    constructor(tmux: TmuxManager, config: Config);
+    /** Validate that parsed data looks like a valid SessionState. */
+    private isValidState;
+    /** Clean up stale .tmp files left by crashed writes. */
+    private cleanTmpFiles;
+    /** Load state from disk. */
+    load(): Promise<void>;
+    /** Reconcile state with actual tmux windows. Remove dead sessions, restart discovery for live ones. */
+    private reconcile;
+    /** Save state to disk atomically (write to temp, then rename).
+     *  #218: Uses a write queue to serialize concurrent saves and prevent corruption. */
+    save(): Promise<void>;
+    /** #357: Debounced save — skips immediate save for offset-only changes.
+     *  Coalesces rapid successive reads into a single disk write. */
+    debouncedSave(): void;
+    private doSave;
+    /** Default stall threshold: 5 minutes (Issue #4: reduced from 60 min). */
+    static readonly DEFAULT_STALL_THRESHOLD_MS: number;
+    static readonly DEFAULT_PERMISSION_STALL_MS: number;
+    /** Create a new CC session. */
+    /** Default timeout for waiting CC to become ready (60s for cold starts). */
+    static readonly DEFAULT_PROMPT_TIMEOUT_MS = 60000;
+    /** Max retries if CC doesn't become ready in time. */
+    static readonly DEFAULT_PROMPT_MAX_RETRIES = 2;
+    /**
+     * Wait for CC to show its idle prompt in the tmux pane, then send the initial prompt.
+     * Uses exponential backoff on retry: first attempt waits timeoutMs, subsequent attempts
+     * wait 1.5x the previous timeout.
+     *
+     * Returns delivery result. Logs warnings on each retry for observability.
+     */
+    sendInitialPrompt(sessionId: string, prompt: string, timeoutMs?: number, maxRetries?: number): Promise<{
+        delivered: boolean;
+        attempts: number;
+    }>;
+    /** Wait for CC idle prompt, then send. Single attempt. */
+    private waitForReadyAndSend;
+    createSession(opts: {
+        workDir: string;
+        name?: string;
+        resumeSessionId?: string;
+        claudeCommand?: string;
+        env?: Record<string, string>;
+        stallThresholdMs?: number;
+        permissionStallMs?: number;
+        permissionMode?: string;
+        /** @deprecated Use permissionMode instead. Maps true→bypassPermissions, false→default. */
+        autoApprove?: boolean;
+    }): Promise<SessionInfo>;
+    /** Get a session by ID. */
+    getSession(id: string): SessionInfo | null;
+    /** Issue #169 Phase 3: Update session status from a hook event.
+     *  Returns the previous status for change detection.
+     *  Issue #87: Also records hook latency timestamps. */
+    updateStatusFromHook(id: string, hookEvent: string, hookTimestamp?: number): UIState | null;
+    /** Issue #88: Add an active subagent to a session. */
+    addSubagent(id: string, name: string): void;
+    /** Issue #88: Remove an active subagent from a session. */
+    removeSubagent(id: string, name: string): void;
+    /** Issue #89 L25: Update the model field on a session from hook payload. */
+    updateSessionModel(id: string, model: string): void;
+    /** Issue #87: Get latency metrics for a session. */
+    getLatencyMetrics(id: string): {
+        hook_latency_ms: number | null;
+        state_change_detection_ms: number | null;
+        permission_response_ms: number | null;
+    } | null;
+    /** Check if a session's tmux window still exists and has a live process.
+     *  Issue #69: A window can exist with a crashed/zombie CC process (zombie window).
+     *  After checking window exists, also verify the pane PID is alive.
+     *  Issue #390: Check stored ccPid first for immediate crash detection.
+     *  When CC crashes (SIGKILL, OOM), the shell prompt returns in the pane,
+     *  so the current pane PID is the shell (alive). Checking ccPid catches
+     *  the crash within seconds instead of waiting for the 5-min stall timer. */
+    isWindowAlive(id: string): Promise<boolean>;
+    /** List all sessions. */
+    listSessions(): SessionInfo[];
+    /** Get health info for a session.
+     *  Issue #2: Returns comprehensive health status for orchestrators.
+     */
+    getHealth(id: string): Promise<{
+        alive: boolean;
+        windowExists: boolean;
+        claudeRunning: boolean;
+        paneCommand: string | null;
+        status: UIState;
+        hasTranscript: boolean;
+        lastActivity: number;
+        lastActivityAgo: number;
+        sessionAge: number;
+        details: string;
+        actionHints?: Record<string, {
+            method: string;
+            url: string;
+            description: string;
+        }>;
+    }>;
+    /** Send a message to a session with delivery verification.
+     *  Issue #1: Uses capture-pane to verify the prompt was delivered.
+     *  Returns delivery status for API response.
+     */
+    sendMessage(id: string, text: string): Promise<{
+        delivered: boolean;
+        attempts: number;
+    }>;
+    /** Send message bypassing the tmux serialize queue.
+     *  Used by sendInitialPrompt for critical-path prompt delivery.
+     *
+     *  Issue #285: Changed from sendKeysDirect (unverified) to sendKeysVerified
+     *  with 3 retry attempts. tmux send-keys can silently fail even at session
+     *  creation time, causing ~20% prompt delivery failure rate.
+     *
+     *  We still bypass the serialize queue (using capturePaneDirect in verifyDelivery)
+     *  but now verify actual delivery to CC.
+     */
+    private sendMessageDirect;
+    /** Record that a permission prompt was detected for this session. */
+    recordPermissionPrompt(id: string): void;
+    /** Approve a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys. */
+    approve(id: string): Promise<void>;
+    /** Reject a permission prompt. Resolves pending hook permission first, falls back to tmux send-keys. */
+    reject(id: string): Promise<void>;
+    /**
+     * Issue #284: Store a pending permission request and return a promise that
+     * resolves when the client approves/rejects via the API.
+     *
+     * @param sessionId - Aegis session ID
+     * @param timeoutMs - Timeout before auto-rejecting (default 10_000ms, matching CC's hook timeout)
+     * @param toolName - Optional tool name from the hook payload
+     * @param prompt - Optional permission prompt text
+     * @returns Promise that resolves with the client's decision
+     */
+    waitForPermissionDecision(sessionId: string, timeoutMs?: number, toolName?: string, prompt?: string): Promise<PermissionDecision>;
+    /** Check if a session has a pending permission request. */
+    hasPendingPermission(sessionId: string): boolean;
+    /** Get info about a pending permission (for API responses). */
+    getPendingPermissionInfo(sessionId: string): {
+        toolName?: string;
+        prompt?: string;
+    } | null;
+    /**
+     * Resolve a pending permission. Returns true if there was a pending permission to resolve.
+     */
+    private resolvePendingPermission;
+    /** Clean up any pending permission for a session (e.g. on session delete). */
+    cleanupPendingPermission(sessionId: string): void;
+    /**
+     * Issue #336: Store a pending AskUserQuestion and return a promise that
+     * resolves when the external client provides an answer via POST /answer.
+     */
+    waitForAnswer(sessionId: string, toolUseId: string, question: string, timeoutMs?: number): Promise<string | null>;
+    /** Issue #336: Submit an answer to a pending question. Returns true if resolved. */
+    submitAnswer(sessionId: string, questionId: string, answer: string): boolean;
+    /** Issue #336: Check if a session has a pending question. */
+    hasPendingQuestion(sessionId: string): boolean;
+    /** Issue #336: Get info about a pending question. */
+    getPendingQuestionInfo(sessionId: string): {
+        toolUseId: string;
+        question: string;
+    } | null;
+    /** Issue #336: Clean up any pending question for a session. */
+    cleanupPendingQuestion(sessionId: string): void;
+    /** Send Escape key. */
+    escape(id: string): Promise<void>;
+    /** Send Ctrl+C. */
+    interrupt(id: string): Promise<void>;
+    /** Read new messages from a session. */
+    readMessages(id: string): Promise<{
+        messages: ParsedEntry[];
+        status: UIState;
+        statusText: string | null;
+        interactiveContent: string | null;
+    }>;
+    /** Read new messages for the monitor (separate offset from API reads). */
+    readMessagesForMonitor(id: string): Promise<{
+        messages: ParsedEntry[];
+        status: UIState;
+        statusText: string | null;
+        interactiveContent: string | null;
+    }>;
+    /** #357: Get all parsed entries for a session, using a cache to avoid full reparse.
+     *  Reads only the delta from the last cached offset. */
+    private getCachedEntries;
+    /** Issue #35: Get a condensed summary of a session's transcript. */
+    getSummary(id: string, maxMessages?: number): Promise<{
+        sessionId: string;
+        windowName: string;
+        status: UIState;
+        totalMessages: number;
+        messages: Array<{
+            role: string;
+            contentType: string;
+            text: string;
+        }>;
+        createdAt: number;
+        lastActivity: number;
+        permissionMode: string;
+    }>;
+    /** Paginated transcript read — does NOT advance the session's byteOffset. */
+    readTranscript(id: string, page?: number, limit?: number, roleFilter?: 'user' | 'assistant' | 'system'): Promise<{
+        messages: ParsedEntry[];
+        total: number;
+        page: number;
+        limit: number;
+        hasMore: boolean;
+    }>;
+    /** #405: Clean up all tracking maps for a session to prevent memory leaks. */
+    private cleanupSession;
+    /** Kill a session. */
+    killSession(id: string): Promise<void>;
+    /** Remove stale entries from session_map.json for a given window.
+     *  P0 fix: After aegis service restarts, old session_map entries with stale windowIds
+     *  can survive and cause new sessions to inherit context from old sessions.
+     *  We must clean by BOTH windowName AND windowId to prevent collisions.
+     *
+     *  After archiving old .jsonl files, old hook entries would cause discovery
+     *  to map the new session to a ghost claudeSessionId whose file no longer exists.
+     */
+    private cleanSessionMapForWindow;
+    /** P0 fix: Purge session_map entries that don't correspond to active aegis sessions.
+     *  After aegis restarts, old session_map entries with stale windowIds can survive
+     *  and cause new sessions to inherit context from old sessions.
+     */
+    private purgeStaleSessionMapEntries;
+    /** Try to discover the CC session ID and JSONL path. */
+    private startSessionIdDiscovery;
+    /** Issue #16: Filesystem-based discovery for --bare mode (no hooks).
+     *  Scans the Claude projects directory for new .jsonl files created after the session.
+     */
+    private startFilesystemDiscovery;
+    /** Sync CC session IDs from the hook-written session_map.json. */
+    private syncSessionMap;
+}