@nexus-cortex/executors 4.26.0

package/dist/utils/SessionPersistence.js

@@ -0,0 +1,244 @@
+/**
+ * SessionPersistence - Manages tmux session metadata storage
+ * Stores session information in .cortex/tmux-sessions/metadata/
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class SessionPersistence {
+    metadataDir;
+    constructor(projectPath) {
+        const basePath = projectPath || process.cwd();
+        this.metadataDir = path.join(basePath, '.cortex', 'tmux-sessions', 'metadata');
+        this.ensureMetadataDir();
+    }
+    /**
+     * Ensure the metadata directory exists
+     */
+    ensureMetadataDir() {
+        if (!fs.existsSync(this.metadataDir)) {
+            fs.mkdirSync(this.metadataDir, { recursive: true });
+        }
+    }
+    /**
+     * Get the file path for a session's metadata
+     */
+    getMetadataPath(sessionId) {
+        return path.join(this.metadataDir, `${sessionId}.json`);
+    }
+    /**
+     * Save session metadata to disk
+     * @param metadata Session metadata to save
+     */
+    async saveSession(metadata) {
+        try {
+            const filePath = this.getMetadataPath(metadata.sessionId);
+            const data = JSON.stringify({
+                ...metadata,
+                created: metadata.created.toISOString(),
+                lastUsed: metadata.lastUsed.toISOString()
+            }, null, 2);
+            fs.writeFileSync(filePath, data, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to save session metadata: ${error.message}`);
+        }
+    }
+    /**
+     * Load session metadata from disk
+     * @param sessionId Session identifier
+     * @returns Session metadata or null if not found
+     */
+    async loadSession(sessionId) {
+        try {
+            const filePath = this.getMetadataPath(sessionId);
+            if (!fs.existsSync(filePath)) {
+                return null;
+            }
+            const data = fs.readFileSync(filePath, 'utf-8');
+            const parsed = JSON.parse(data);
+            return {
+                ...parsed,
+                created: new Date(parsed.created),
+                lastUsed: new Date(parsed.lastUsed)
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to load session metadata: ${error.message}`);
+        }
+    }
+    /**
+     * Update lastUsed timestamp for a session
+     * @param sessionId Session identifier
+     */
+    async touchSession(sessionId) {
+        const metadata = await this.loadSession(sessionId);
+        if (metadata) {
+            metadata.lastUsed = new Date();
+            await this.saveSession(metadata);
+        }
+    }
+    /**
+     * Delete session metadata from disk
+     * @param sessionId Session identifier
+     */
+    async deleteSession(sessionId) {
+        try {
+            const filePath = this.getMetadataPath(sessionId);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to delete session metadata: ${error.message}`);
+        }
+    }
+    /**
+     * List all stored session metadata
+     * @returns Array of session metadata
+     */
+    async listSessions() {
+        try {
+            if (!fs.existsSync(this.metadataDir)) {
+                return [];
+            }
+            const files = fs.readdirSync(this.metadataDir);
+            const sessions = [];
+            for (const file of files) {
+                if (file.endsWith('.json')) {
+                    const sessionId = file.replace('.json', '');
+                    const metadata = await this.loadSession(sessionId);
+                    if (metadata) {
+                        sessions.push(metadata);
+                    }
+                }
+            }
+            return sessions;
+        }
+        catch (error) {
+            throw new Error(`Failed to list sessions: ${error.message}`);
+        }
+    }
+    /**
+     * Clean up metadata for sessions that no longer exist in tmux
+     * @param activeSessions Array of active session IDs from tmux
+     */
+    async cleanupOrphaned(activeSessions) {
+        try {
+            const stored = await this.listSessions();
+            let cleaned = 0;
+            for (const metadata of stored) {
+                if (!activeSessions.includes(metadata.sessionId)) {
+                    await this.deleteSession(metadata.sessionId);
+                    cleaned++;
+                }
+            }
+            return cleaned;
+        }
+        catch (error) {
+            throw new Error(`Failed to cleanup orphaned sessions: ${error.message}`);
+        }
+    }
+    /**
+     * Clean up sessions that haven't been used in a specified time period
+     * @param maxAgeMs Maximum age in milliseconds
+     */
+    async cleanupStale(maxAgeMs) {
+        try {
+            const stored = await this.listSessions();
+            const now = Date.now();
+            let cleaned = 0;
+            for (const metadata of stored) {
+                const age = now - metadata.lastUsed.getTime();
+                if (age > maxAgeMs) {
+                    await this.deleteSession(metadata.sessionId);
+                    cleaned++;
+                }
+            }
+            return cleaned;
+        }
+        catch (error) {
+            throw new Error(`Failed to cleanup stale sessions: ${error.message}`);
+        }
+    }
+    /**
+     * Get metadata directory path
+     */
+    getMetadataDirectory() {
+        return this.metadataDir;
+    }
+    /**
+     * Recover sessions on startup
+     * Checks which persisted sessions still exist in tmux
+     * and cleans up metadata for sessions that no longer exist
+     *
+     * @param activeSessions Array of currently active tmux session IDs
+     * @returns Object with recovered and cleaned session counts
+     */
+    async recoverSessions(activeSessions) {
+        const storedSessions = await this.listSessions();
+        let recovered = 0;
+        let cleaned = 0;
+        for (const metadata of storedSessions) {
+            if (activeSessions.includes(metadata.sessionId)) {
+                // Session still exists - recovered
+                recovered++;
+                // Update lastUsed to indicate recovery
+                metadata.lastUsed = new Date();
+                await this.saveSession(metadata);
+            }
+            else {
+                // Session no longer exists - clean up metadata
+                await this.deleteSession(metadata.sessionId);
+                cleaned++;
+            }
+        }
+        return {
+            recovered,
+            cleaned,
+            total: storedSessions.length
+        };
+    }
+    /**
+     * Auto-cleanup stale and orphaned sessions
+     * Should be called periodically (e.g., every hour)
+     *
+     * @param activeSessions Current active tmux sessions
+     * @param maxAgeHours Maximum age in hours before session is considered stale
+     * @returns Cleanup statistics
+     */
+    async autoCleanup(activeSessions, maxAgeHours = 24) {
+        const maxAgeMs = maxAgeHours * 60 * 60 * 1000;
+        const orphanedCount = await this.cleanupOrphaned(activeSessions);
+        const staleCount = await this.cleanupStale(maxAgeMs);
+        return {
+            orphaned: orphanedCount,
+            stale: staleCount,
+            total: orphanedCount + staleCount
+        };
+    }
+    /**
+     * Get session statistics
+     */
+    async getStats() {
+        const sessions = await this.listSessions();
+        if (sessions.length === 0) {
+            return {
+                totalSessions: 0,
+                oldestSession: null,
+                newestSession: null,
+                averageAge: 0
+            };
+        }
+        const now = Date.now();
+        const ages = sessions.map(s => now - s.created.getTime());
+        const averageAge = ages.reduce((sum, age) => sum + age, 0) / ages.length;
+        const sortedByCreated = sessions.sort((a, b) => a.created.getTime() - b.created.getTime());
+        return {
+            totalSessions: sessions.length,
+            oldestSession: sortedByCreated[0]?.created || new Date(),
+            newestSession: sortedByCreated[sortedByCreated.length - 1]?.created || new Date(),
+            averageAge: averageAge / (60 * 60 * 1000) // Convert to hours
+        };
+    }
+}
+//# sourceMappingURL=SessionPersistence.js.map

package/dist/utils/SessionPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionPersistence.js","sourceRoot":"","sources":["../../src/utils/SessionPersistence.ts"],"names":[],"mappings":"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"}

package/dist/utils/TextUtils.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Text Utility Functions
+ *
+ * Safe text manipulation utilities, especially for handling special characters
+ * in string replacements.
+ */
+/**
+ * Performs a safe literal string replacement that correctly handles $ sequences.
+ *
+ * JavaScript's String.replace() treats $ specially in replacement strings:
+ * - $& = the matched substring
+ * - $` = portion before match
+ * - $' = portion after match
+ * - $1, $2, etc. = capture groups
+ * - $$ = literal $
+ *
+ * This function ensures $ characters in the replacement string are treated literally.
+ *
+ * @param content The string to search in
+ * @param oldString The exact string to find (literal, not regex)
+ * @param newString The exact string to replace with (literal, $ are escaped)
+ * @returns The content with replacements made
+ *
+ * @example
+ * // Without safe replacement:
+ * "foo".replace("foo", "$100")  // Returns "0" ($ is special)
+ *
+ * // With safe replacement:
+ * safeLiteralReplace("foo", "foo", "$100")  // Returns "$100" ($ is literal)
+ */
+export declare function safeLiteralReplace(content: string, oldString: string, newString: string): string;
+/**
+ * Counts occurrences of a literal string in content.
+ *
+ * @param content The string to search in
+ * @param searchString The exact string to count
+ * @returns The number of non-overlapping occurrences
+ */
+export declare function countOccurrences(content: string, searchString: string): number;
+/**
+ * Escapes special regex characters in a string to make it safe for use in a RegExp.
+ *
+ * @param str The string to escape
+ * @returns The escaped string safe for use in new RegExp()
+ */
+export declare function escapeRegex(str: string): string;
+/**
+ * Normalizes line endings to LF (\n).
+ *
+ * @param content The content with potentially mixed line endings
+ * @returns The content with normalized LF line endings
+ */
+export declare function normalizeLineEndings(content: string): string;
+/**
+ * Truncates text to a maximum length, adding ellipsis if needed.
+ *
+ * @param text The text to truncate
+ * @param maxLength Maximum length (default: 100)
+ * @param ellipsis The ellipsis to add (default: '...')
+ * @returns The truncated text
+ */
+export declare function truncate(text: string, maxLength?: number, ellipsis?: string): string;
+/**
+ * Gets the first line of text.
+ *
+ * @param text The multi-line text
+ * @returns The first line
+ */
+export declare function getFirstLine(text: string): string;
+/**
+ * Strips ANSI escape codes from text.
+ *
+ * @param text The text with ANSI codes
+ * @returns The text without ANSI codes
+ */
+export declare function stripAnsi(text: string): string;
+//# sourceMappingURL=TextUtils.d.ts.map

package/dist/utils/TextUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextUtils.d.ts","sourceRoot":"","sources":["../../src/utils/TextUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,CAWR;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAc9E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAY,EACvB,QAAQ,GAAE,MAAc,GACvB,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9C"}

package/dist/utils/TextUtils.js

@@ -0,0 +1,112 @@
+/**
+ * Text Utility Functions
+ *
+ * Safe text manipulation utilities, especially for handling special characters
+ * in string replacements.
+ */
+/**
+ * Performs a safe literal string replacement that correctly handles $ sequences.
+ *
+ * JavaScript's String.replace() treats $ specially in replacement strings:
+ * - $& = the matched substring
+ * - $` = portion before match
+ * - $' = portion after match
+ * - $1, $2, etc. = capture groups
+ * - $$ = literal $
+ *
+ * This function ensures $ characters in the replacement string are treated literally.
+ *
+ * @param content The string to search in
+ * @param oldString The exact string to find (literal, not regex)
+ * @param newString The exact string to replace with (literal, $ are escaped)
+ * @returns The content with replacements made
+ *
+ * @example
+ * // Without safe replacement:
+ * "foo".replace("foo", "$100")  // Returns "0" ($ is special)
+ *
+ * // With safe replacement:
+ * safeLiteralReplace("foo", "foo", "$100")  // Returns "$100" ($ is literal)
+ */
+export function safeLiteralReplace(content, oldString, newString) {
+    // replaceAll() is safe for literal strings (doesn't use regex)
+    // But we still need to escape $ in the replacement string
+    // because replaceAll treats $ specially in replacement patterns
+    // Escape all $ characters by doubling them
+    // This ensures $100 becomes $$100 which replaceAll interprets as literal $100
+    const safeNewString = newString.replace(/\$/g, '$$$$');
+    // Use replaceAll for literal string replacement
+    return content.replaceAll(oldString, safeNewString);
+}
+/**
+ * Counts occurrences of a literal string in content.
+ *
+ * @param content The string to search in
+ * @param searchString The exact string to count
+ * @returns The number of non-overlapping occurrences
+ */
+export function countOccurrences(content, searchString) {
+    if (searchString === '') {
+        return 0; // Empty string has no meaningful occurrences
+    }
+    let count = 0;
+    let position = 0;
+    while ((position = content.indexOf(searchString, position)) !== -1) {
+        count++;
+        position += searchString.length; // Move past this occurrence
+    }
+    return count;
+}
+/**
+ * Escapes special regex characters in a string to make it safe for use in a RegExp.
+ *
+ * @param str The string to escape
+ * @returns The escaped string safe for use in new RegExp()
+ */
+export function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Normalizes line endings to LF (\n).
+ *
+ * @param content The content with potentially mixed line endings
+ * @returns The content with normalized LF line endings
+ */
+export function normalizeLineEndings(content) {
+    return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+/**
+ * Truncates text to a maximum length, adding ellipsis if needed.
+ *
+ * @param text The text to truncate
+ * @param maxLength Maximum length (default: 100)
+ * @param ellipsis The ellipsis to add (default: '...')
+ * @returns The truncated text
+ */
+export function truncate(text, maxLength = 100, ellipsis = '...') {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.substring(0, maxLength - ellipsis.length) + ellipsis;
+}
+/**
+ * Gets the first line of text.
+ *
+ * @param text The multi-line text
+ * @returns The first line
+ */
+export function getFirstLine(text) {
+    const lines = text.split('\n');
+    return lines[0] || '';
+}
+/**
+ * Strips ANSI escape codes from text.
+ *
+ * @param text The text with ANSI codes
+ * @returns The text without ANSI codes
+ */
+export function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '');
+}
+//# sourceMappingURL=TextUtils.js.map

package/dist/utils/TextUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextUtils.js","sourceRoot":"","sources":["../../src/utils/TextUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,SAAiB,EACjB,SAAiB;IAEjB,+DAA+D;IAC/D,0DAA0D;IAC1D,gEAAgE;IAEhE,2CAA2C;IAC3C,8EAA8E;IAC9E,MAAM,aAAa,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAEvD,gDAAgD;IAChD,OAAO,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,YAAoB;IACpE,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC,CAAC,6CAA6C;IACzD,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnE,KAAK,EAAE,CAAC;QACR,QAAQ,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC,4BAA4B;IAC/D,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACtB,IAAY,EACZ,YAAoB,GAAG,EACvB,WAAmB,KAAK;IAExB,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC;AACnE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,4CAA4C;IAC5C,OAAO,IAAI,CAAC,OAAO,CACjB,6EAA6E,EAC7E,EAAE,CACH,CAAC;AACJ,CAAC"}

package/dist/utils/TmuxCapture.d.ts

@@ -0,0 +1,94 @@
+/**
+ * TmuxCapture - Visual screenshot capture for tmux sessions
+ *
+ * Leverages existing WindowManager and TerminalSandbox infrastructure
+ * to capture visual screenshots of tmux sessions.
+ *
+ * Features:
+ * - Visual PNG screenshots of tmux sessions
+ * - Uses Playwright via TerminalSandbox
+ * - Minimal overhead (reuses existing browser instance)
+ * - Automatic cleanup
+ */
+export interface CaptureOptions {
+    /**
+     * Screenshot format
+     */
+    format?: 'png' | 'jpeg';
+    /**
+     * JPEG quality (0-100, only for JPEG format)
+     */
+    quality?: number;
+    /**
+     * Terminal dimensions (defaults to 80x24)
+     */
+    dimensions?: {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Wait time in ms before capturing (allow rendering)
+     */
+    waitTime?: number;
+}
+export interface CaptureResult {
+    /**
+     * Screenshot buffer (PNG or JPEG)
+     */
+    screenshot: Buffer;
+    /**
+     * Screenshot as base64 string
+     */
+    base64: string;
+    /**
+     * Format of the screenshot
+     */
+    format: 'png' | 'jpeg';
+    /**
+     * Timestamp of capture
+     */
+    timestamp: number;
+    /**
+     * Session ID that was captured
+     */
+    sessionId: string;
+}
+/**
+ * TmuxCapture - Visual screenshot capture for tmux sessions
+ *
+ * Strategy:
+ * 1. Use WindowManager to create a terminal window
+ * 2. Attach to the tmux session in that terminal
+ * 3. Take a screenshot using Playwright
+ * 4. Clean up the window
+ */
+export declare class TmuxCapture {
+    private static windowManager;
+    private static initPromise;
+    /**
+     * Initialize WindowManager (singleton pattern)
+     */
+    private static ensureWindowManager;
+    /**
+     * Capture visual screenshot of a tmux session
+     *
+     * @param sessionId Tmux session ID
+     * @param options Capture options
+     * @returns Screenshot and metadata
+     */
+    static captureSession(sessionId: string, options?: CaptureOptions): Promise<CaptureResult>;
+    /**
+     * Capture screenshot and save to file
+     *
+     * @param sessionId Tmux session ID
+     * @param filepath Path to save screenshot
+     * @param options Capture options
+     */
+    static captureToFile(sessionId: string, filepath: string, options?: CaptureOptions): Promise<void>;
+    /**
+     * Cleanup and shutdown WindowManager
+     * Call this when done with all captures
+     */
+    static cleanup(): Promise<void>;
+}
+//# sourceMappingURL=TmuxCapture.d.ts.map

package/dist/utils/TmuxCapture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TmuxCapture.d.ts","sourceRoot":"","sources":["../../src/utils/TmuxCapture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAExB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,aAAa,CAA8B;IAC1D,OAAO,CAAC,MAAM,CAAC,WAAW,CAA8B;IAExD;;OAEG;mBACkB,mBAAmB;IAgBxC;;;;;;OAMG;WACiB,cAAc,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC;IAoEzB;;;;;;OAMG;WACiB,aAAa,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAMhB;;;OAGG;WACiB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7C"}

package/dist/utils/TmuxCapture.js

@@ -0,0 +1,131 @@
+/**
+ * TmuxCapture - Visual screenshot capture for tmux sessions
+ *
+ * Leverages existing WindowManager and TerminalSandbox infrastructure
+ * to capture visual screenshots of tmux sessions.
+ *
+ * Features:
+ * - Visual PNG screenshots of tmux sessions
+ * - Uses Playwright via TerminalSandbox
+ * - Minimal overhead (reuses existing browser instance)
+ * - Automatic cleanup
+ */
+import { WindowManager } from '../implementations/addon/WindowManager.js';
+import { TmuxManager } from './TmuxManager.js';
+/**
+ * TmuxCapture - Visual screenshot capture for tmux sessions
+ *
+ * Strategy:
+ * 1. Use WindowManager to create a terminal window
+ * 2. Attach to the tmux session in that terminal
+ * 3. Take a screenshot using Playwright
+ * 4. Clean up the window
+ */
+export class TmuxCapture {
+    static windowManager = null;
+    static initPromise = null;
+    /**
+     * Initialize WindowManager (singleton pattern)
+     */
+    static async ensureWindowManager() {
+        if (TmuxCapture.windowManager) {
+            return TmuxCapture.windowManager;
+        }
+        if (!TmuxCapture.initPromise) {
+            TmuxCapture.initPromise = (async () => {
+                TmuxCapture.windowManager = new WindowManager();
+                await TmuxCapture.windowManager.initialize();
+            })();
+        }
+        await TmuxCapture.initPromise;
+        return TmuxCapture.windowManager;
+    }
+    /**
+     * Capture visual screenshot of a tmux session
+     *
+     * @param sessionId Tmux session ID
+     * @param options Capture options
+     * @returns Screenshot and metadata
+     */
+    static async captureSession(sessionId, options = {}) {
+        const tmux = TmuxManager.getInstance();
+        // Verify tmux is available
+        if (!(await tmux.isAvailable())) {
+            throw new Error('tmux is not installed');
+        }
+        // Verify session exists
+        if (!(await tmux.sessionExists(sessionId))) {
+            throw new Error(`Tmux session '${sessionId}' does not exist`);
+        }
+        // Get or create WindowManager
+        const windowManager = await TmuxCapture.ensureWindowManager();
+        // Create temporary window ID
+        const windowId = `tmux-capture-${sessionId}-${Date.now()}`;
+        try {
+            // Create terminal window that attaches to tmux session
+            const windowConfig = {
+                type: 'terminal',
+                id: windowId,
+                shell: `tmux attach-session -t ${sessionId}`,
+                position: {
+                    x: 0,
+                    y: 0,
+                    width: (options.dimensions?.cols || 80) * 10, // Approximate pixels
+                    height: (options.dimensions?.rows || 24) * 20
+                }
+            };
+            await windowManager.createWindow(windowConfig);
+            // Wait for rendering
+            const waitTime = options.waitTime || 1000;
+            await new Promise(resolve => setTimeout(resolve, waitTime));
+            // Capture screenshot
+            const screenshot = await windowManager.captureWindow(windowId);
+            // Clean up window
+            await windowManager.closeWindow(windowId);
+            // Prepare result
+            const format = options.format || 'png';
+            const base64 = screenshot.toString('base64');
+            return {
+                screenshot,
+                base64,
+                format,
+                timestamp: Date.now(),
+                sessionId
+            };
+        }
+        catch (error) {
+            // Attempt cleanup on error
+            try {
+                await windowManager.closeWindow(windowId);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            throw new Error(`Failed to capture tmux session: ${error.message}`);
+        }
+    }
+    /**
+     * Capture screenshot and save to file
+     *
+     * @param sessionId Tmux session ID
+     * @param filepath Path to save screenshot
+     * @param options Capture options
+     */
+    static async captureToFile(sessionId, filepath, options = {}) {
+        const fs = await import('fs/promises');
+        const result = await TmuxCapture.captureSession(sessionId, options);
+        await fs.writeFile(filepath, result.screenshot);
+    }
+    /**
+     * Cleanup and shutdown WindowManager
+     * Call this when done with all captures
+     */
+    static async cleanup() {
+        if (TmuxCapture.windowManager) {
+            await TmuxCapture.windowManager.close();
+            TmuxCapture.windowManager = null;
+            TmuxCapture.initPromise = null;
+        }
+    }
+}
+//# sourceMappingURL=TmuxCapture.js.map