@poolzin/pool-bot 2026.3.9 → 2026.3.11

package/dist/tui/utils/safe-stop.js

@@ -0,0 +1,180 @@
+/**
+ * Safe TUI stop utilities
+ *
+ * Features:
+ * - Graceful TUI shutdown with error handling
+ * - EBADF error detection and handling
+ * - Ignorable error filtering
+ * - Signal handler management
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+const tuiLog = createSubsystemLogger("tui");
+/**
+ * Errors that can be safely ignored during TUI stop
+ * These typically occur when the terminal is already closed/detached
+ */
+const IGNORABLE_STOP_ERRORS = new Set([
+    "EBADF", // Bad file descriptor - terminal already closed
+    "EIO", // I/O error - terminal disconnected
+    "EPIPE", // Broken pipe
+    "ENOTTY", // Not a TTY
+    "ENODEV", // No such device
+]);
+/**
+ * Check if an error during TUI stop can be safely ignored
+ */
+export function isIgnorableTuiStopError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const err = error;
+    // Check error code
+    if (err.code && IGNORABLE_STOP_ERRORS.has(err.code)) {
+        return true;
+    }
+    // Check error message for known patterns
+    const message = err.message ?? "";
+    const ignorablePatterns = [
+        /bad file descriptor/i,
+        /not a tty/i,
+        /input\/output error/i,
+        /broken pipe/i,
+    ];
+    for (const pattern of ignorablePatterns) {
+        if (pattern.test(message)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Safely stop the TUI with proper error handling
+ *
+ * @param tui - The TUI instance to stop
+ * @param options - Stop options
+ */
+export function stopTuiSafely(tui, options = {}) {
+    const { logErrors = true, exitCode = 0, shouldExit = false } = options;
+    try {
+        tui.stop();
+        tuiLog.debug("TUI stopped gracefully");
+    }
+    catch (error) {
+        if (isIgnorableTuiStopError(error)) {
+            // These errors are expected when terminal is already closed
+            tuiLog.debug("TUI stop error (ignorable)", { error: String(error) });
+        }
+        else {
+            if (logErrors) {
+                tuiLog.error("Error stopping TUI:", { error: String(error) });
+            }
+            // Re-throw non-ignorable errors
+            throw error;
+        }
+    }
+    if (shouldExit) {
+        process.exit(exitCode);
+    }
+}
+/**
+ * Active signal handlers for cleanup
+ */
+const activeSignalHandlers = new Map();
+/**
+ * Register a signal handler with tracking for cleanup
+ *
+ * @param signal - Signal name (e.g., 'SIGINT', 'SIGTERM')
+ * @param handler - Handler function
+ * @param options - Registration options
+ * @returns Cleanup function to remove the handler
+ */
+export function registerSignalHandler(signal, handler, options = {}) {
+    const { once = false } = options;
+    // Wrap handler to track execution
+    const wrappedHandler = () => {
+        tuiLog.debug(`Signal ${signal} received`);
+        handler();
+    };
+    if (once) {
+        process.once(signal, wrappedHandler);
+    }
+    else {
+        process.on(signal, wrappedHandler);
+    }
+    // Store for potential cleanup
+    const key = `${signal}_${Date.now()}`;
+    activeSignalHandlers.set(key, handler);
+    // Return cleanup function
+    return () => {
+        process.removeListener(signal, wrappedHandler);
+        activeSignalHandlers.delete(key);
+    };
+}
+/**
+ * Remove all registered signal handlers
+ */
+export function cleanupAllSignalHandlers() {
+    activeSignalHandlers.clear();
+}
+/**
+ * Create SIGINT handler with proper cleanup
+ *
+ * @param cleanup - Cleanup function to run before exit
+ * @returns Signal handler function
+ */
+export function createSigintHandler(cleanup) {
+    return () => {
+        tuiLog.debug("SIGINT received, cleaning up...");
+        try {
+            cleanup?.();
+        }
+        catch (error) {
+            tuiLog.error("Error during SIGINT cleanup:", { error: String(error) });
+        }
+        // Force exit after cleanup
+        process.exit(0);
+    };
+}
+/**
+ * Create SIGTERM handler with proper cleanup
+ *
+ * @param cleanup - Cleanup function to run before exit
+ * @returns Signal handler function
+ */
+export function createSigtermHandler(cleanup) {
+    return () => {
+        tuiLog.debug("SIGTERM received, cleaning up...");
+        try {
+            cleanup?.();
+        }
+        catch (error) {
+            tuiLog.error("Error during SIGTERM cleanup:", { error: String(error) });
+        }
+        process.exit(0);
+    };
+}
+/**
+ * Request graceful exit with proper cleanup sequence
+ *
+ * @param tui - TUI instance
+ * @param client - Optional client to stop
+ * @param options - Exit options
+ */
+export function requestExit(tui, client, options = {}) {
+    const { exitCode = 0, reason = "user requested" } = options;
+    tuiLog.info(`Exit requested: ${reason}`);
+    // Stop client first if available
+    if (client) {
+        try {
+            client.stop();
+            tuiLog.debug("Client stopped");
+        }
+        catch (error) {
+            tuiLog.warn("Error stopping client:", { error: String(error) });
+        }
+    }
+    // Stop TUI safely
+    stopTuiSafely(tui, { logErrors: true, shouldExit: false });
+    // Exit process
+    process.exit(exitCode);
+}

package/dist/tui/utils/session-key-utils.js

@@ -0,0 +1,81 @@
+/**
+ * Session key normalization and comparison utilities
+ *
+ * Ensures consistent session key handling across the application
+ */
+import { parseAgentSessionKey, normalizeAgentId, normalizeMainKey, } from "../../routing/session-key.js";
+/**
+ * Parse and normalize a session key
+ *
+ * @param key - Raw session key
+ * @returns Normalized session key or null if invalid
+ */
+export function normalizeSessionKey(key) {
+    try {
+        const parsed = parseAgentSessionKey(key);
+        if (!parsed) {
+            // Try to normalize as plain key
+            return {
+                agentId: "",
+                mainKey: normalizeMainKey(key),
+            };
+        }
+        return {
+            agentId: normalizeAgentId(parsed.agentId),
+            mainKey: normalizeMainKey(parsed.rest),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare two session keys for equality
+ *
+ * Handles:
+ * - Case insensitivity
+ * - Different formats (agent:key vs key)
+ * - Normalization differences
+ *
+ * @param key1 - First session key
+ * @param key2 - Second session key
+ * @returns True if keys represent the same session
+ */
+export function isSameSessionKey(key1, key2) {
+    if (key1 === key2)
+        return true;
+    const normalized1 = normalizeSessionKey(key1);
+    const normalized2 = normalizeSessionKey(key2);
+    if (!normalized1 || !normalized2) {
+        // If normalization fails, do case-insensitive comparison
+        return key1.toLowerCase() === key2.toLowerCase();
+    }
+    return (normalized1.agentId.toLowerCase() === normalized2.agentId.toLowerCase() &&
+        normalized1.mainKey.toLowerCase() === normalized2.mainKey.toLowerCase());
+}
+/**
+ * Format session key for display
+ *
+ * @param key - Session key
+ * @param maxLength - Maximum length (default: 40)
+ * @returns Formatted key
+ */
+export function formatSessionKeyForDisplay(key, maxLength = 40) {
+    if (key.length <= maxLength)
+        return key;
+    // Show start and end with ellipsis
+    const start = key.slice(0, maxLength / 2 - 2);
+    const end = key.slice(-(maxLength / 2 - 2));
+    return `${start}...${end}`;
+}
+/**
+ * Extract session identifier for logging
+ * Removes sensitive or verbose parts
+ */
+export function getSessionIdentifier(key) {
+    const normalized = normalizeSessionKey(key);
+    if (!normalized)
+        return key.slice(0, 20);
+    // Return main key which is usually the user-facing identifier
+    return normalized.mainKey || normalized.agentId || key.slice(0, 20);
+}

package/dist/tui/utils/text-sanitization.js

@@ -0,0 +1,284 @@
+/**
+ * Text sanitization utilities for safe terminal rendering
+ *
+ * Features:
+ * - Control character stripping
+ * - ANSI sequence handling
+ * - Path and URL preservation
+ * - RTL text isolation
+ * - Binary data redaction
+ * - Safe truncation
+ */
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+const sanitizeLog = createSubsystemLogger("sanitize");
+/**
+ * Maximum safe length for a single token (word)
+ * Tokens longer than this will be chunked
+ */
+const MAX_TOKEN_LENGTH = 4096;
+/**
+ * Characters to strip (control characters except common whitespace)
+ */
+const CONTROL_CHARS_TO_STRIP = new Set([
+    0x00, // NUL - null
+    0x01, // SOH - start of heading
+    0x02, // STX - start of text
+    0x03, // ETX - end of text
+    0x04, // EOT - end of transmission
+    0x05, // ENQ - enquiry
+    0x06, // ACK - acknowledge
+    0x07, // BEL - bell
+    0x08, // BS - backspace
+    0x0b, // VT - vertical tab
+    0x0c, // FF - form feed
+    0x0e, // SO - shift out
+    0x0f, // SI - shift in
+    0x10, // DLE - data link escape
+    0x11, // DC1 - device control 1
+    0x12, // DC2 - device control 2
+    0x13, // DC3 - device control 3
+    0x14, // DC4 - device control 4
+    0x15, // NAK - negative acknowledge
+    0x16, // SYN - synchronous idle
+    0x17, // ETB - end of transmission block
+    0x18, // CAN - cancel
+    0x19, // EM - end of medium
+    0x1a, // SUB - substitute
+    0x1b, // ESC - escape (handled separately)
+    0x1c, // FS - file separator
+    0x1d, // GS - group separator
+    0x1e, // RS - record separator
+    0x1f, // US - unit separator
+    0x7f, // DEL - delete
+]);
+/**
+ * Check if a character is a control character that should be stripped
+ */
+function shouldStripControlChar(codePoint) {
+    return CONTROL_CHARS_TO_STRIP.has(codePoint);
+}
+/**
+ * Check if text contains binary/null bytes
+ */
+function containsBinaryData(text) {
+    for (let i = 0; i < Math.min(text.length, 1024); i++) {
+        const code = text.charCodeAt(i);
+        if (code === 0x00 || (code < 0x20 && !isCommonWhitespace(code))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if character is common whitespace (preserved)
+ */
+function isCommonWhitespace(codePoint) {
+    return (codePoint === 0x09 || // TAB
+        codePoint === 0x0a || // LF
+        codePoint === 0x0d || // CR
+        codePoint === 0x20); // SPACE
+}
+/**
+ * Check if character is RTL (right-to-left)
+ */
+function isRtlChar(codePoint) {
+    // Hebrew: U+0590 - U+05FF
+    if (codePoint >= 0x0590 && codePoint <= 0x05ff)
+        return true;
+    // Arabic: U+0600 - U+06FF
+    if (codePoint >= 0x0600 && codePoint <= 0x06ff)
+        return true;
+    // Arabic Supplement: U+0750 - U+077F
+    if (codePoint >= 0x0750 && codePoint <= 0x077f)
+        return true;
+    // RTL marks
+    if (codePoint === 0x200f || codePoint === 0x202e)
+        return true;
+    return false;
+}
+/**
+ * Check if text contains RTL characters
+ */
+function containsRtl(text) {
+    for (const char of text) {
+        if (isRtlChar(char.codePointAt(0) ?? 0)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * URL pattern for detection
+ */
+const URL_PATTERN = /https?:\/\/[^\s<>"{}|\\^`[\]]+/gi;
+/**
+ * Path pattern for detection (Unix and Windows)
+ */
+const PATH_PATTERN = /(?:~\/|\/|[a-zA-Z]:\\)[^\s<>"{}|\\^`[\]]*/g;
+/**
+ * Truncate a long token while preserving meaning
+ */
+function truncateToken(token, maxLength) {
+    if (token.length <= maxLength)
+        return token;
+    // For URLs, try to preserve the domain and endpoint
+    if (token.startsWith("http")) {
+        try {
+            const url = new URL(token);
+            const domain = url.hostname;
+            const path = url.pathname;
+            const search = url.search;
+            // Calculate available space for path
+            const prefix = `${url.protocol}//${domain}`;
+            const suffix = "…";
+            const available = maxLength - prefix.length - suffix.length;
+            if (available > 10) {
+                const truncatedPath = path.slice(0, Math.max(0, available - search.length)) + (search ? "?…" : "") + suffix;
+                return prefix + truncatedPath;
+            }
+        }
+        catch {
+            // Not a valid URL, fall through to default truncation
+        }
+    }
+    // Default truncation
+    return token.slice(0, maxLength - 1) + "…";
+}
+/**
+ * Sanitize text for safe terminal rendering
+ *
+ * @param text - Raw text to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized text safe for terminal rendering
+ */
+export function sanitizeRenderableText(text, options = {}) {
+    const { maxTokenLength = MAX_TOKEN_LENGTH, preserveUrls = true, isolateRtl = true, redactBinary = true, maxTotalLength, } = options;
+    if (!text || typeof text !== "string") {
+        return "";
+    }
+    let result = text;
+    // Check for binary data
+    if (redactBinary && containsBinaryData(result)) {
+        sanitizeLog.debug("Redacting binary data from text");
+        return "[binary data redacted]";
+    }
+    // Strip control characters
+    result = result
+        .split("")
+        .map((char) => {
+        const code = char.codePointAt(0) ?? 0;
+        if (shouldStripControlChar(code)) {
+            return "";
+        }
+        return char;
+    })
+        .join("");
+    // Handle very long tokens (preserve URLs/paths)
+    if (preserveUrls) {
+        // First identify URLs and paths to preserve
+        const preserved = [];
+        let preservedIndex = 0;
+        result = result.replace(URL_PATTERN, (url) => {
+            if (url.length > maxTokenLength) {
+                url = truncateToken(url, maxTokenLength);
+            }
+            const placeholder = `\x00PRESERVED_${preservedIndex++}\x00`;
+            preserved.push(url);
+            return placeholder;
+        });
+        result = result.replace(PATH_PATTERN, (path) => {
+            if (path.length > maxTokenLength) {
+                path = truncateToken(path, maxTokenLength);
+            }
+            const placeholder = `\x00PRESERVED_${preservedIndex++}\x00`;
+            preserved.push(path);
+            return placeholder;
+        });
+        // Truncate remaining long tokens
+        result = result
+            .split(/\s+/)
+            .map((token) => {
+            if (token.length > maxTokenLength) {
+                return truncateToken(token, maxTokenLength);
+            }
+            return token;
+        })
+            .join(" ");
+        // Restore preserved URLs/paths
+        for (let i = 0; i < preserved.length; i++) {
+            result = result.replace(`\x00PRESERVED_${i}\x00`, preserved[i]);
+        }
+    }
+    else {
+        // Simple token truncation
+        result = result
+            .split(/\s+/)
+            .map((token) => {
+            if (token.length > maxTokenLength) {
+                return truncateToken(token, maxTokenLength);
+            }
+            return token;
+        })
+            .join(" ");
+    }
+    // Isolate RTL text with Unicode marks
+    if (isolateRtl && containsRtl(result)) {
+        // Add LTR mark at start and end to ensure proper display
+        result = "\u200e" + result + "\u200e";
+    }
+    // Apply total length limit
+    if (maxTotalLength && result.length > maxTotalLength) {
+        result = result.slice(0, maxTotalLength - 3) + "...";
+    }
+    return result;
+}
+/**
+ * Sanitize error message for display
+ */
+export function sanitizeErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return sanitizeRenderableText(message, {
+        maxTokenLength: 1024,
+        maxTotalLength: 8192,
+    });
+}
+/**
+ * Strip ANSI escape sequences from text
+ */
+export function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
+/**
+ * Check if text is safe to render (no sanitization needed)
+ */
+export function isSafeToRender(text) {
+    if (!text || text.length === 0)
+        return true;
+    // Check length
+    if (text.length > MAX_TOKEN_LENGTH)
+        return false;
+    // Check for control characters
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (shouldStripControlChar(code)) {
+            return false;
+        }
+        if (code === 0x00)
+            return false; // Null bytes
+    }
+    return true;
+}
+/**
+ * Create a sanitized preview of text (for logging/debugging)
+ */
+export function createTextPreview(text, maxLength = 200) {
+    const sanitized = sanitizeRenderableText(text, {
+        maxTokenLength: maxLength,
+        maxTotalLength: maxLength,
+    });
+    if (text.length > maxLength) {
+        return sanitized + ` [+${text.length - maxLength} chars]`;
+    }
+    return sanitized;
+}

package/dist/utils/lru-cache.js

@@ -0,0 +1,116 @@
+/**
+ * LRU (Least Recently Used) Cache implementation
+ *
+ * Features:
+ * - Fixed maximum size
+ * - Automatic eviction of least recently used items
+ * - O(1) get and set operations
+ * - Type-safe with TypeScript generics
+ */
+export class LRUCache {
+    cache;
+    maxSize;
+    onEvict;
+    constructor(options) {
+        this.cache = new Map();
+        this.maxSize = options.maxSize;
+        this.onEvict = options.onEvict;
+    }
+    /**
+     * Get a value from the cache
+     * Updates recency of the accessed item
+     */
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            // Move to end (most recently used)
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    /**
+     * Set a value in the cache
+     * Evicts least recently used item if at capacity
+     */
+    set(key, value) {
+        if (this.cache.has(key)) {
+            // Update existing key
+            this.cache.delete(key);
+        }
+        else if (this.cache.size >= this.maxSize) {
+            // Evict least recently used (first item)
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                const evictedValue = this.cache.get(firstKey);
+                this.cache.delete(firstKey);
+                this.onEvict?.(firstKey, evictedValue);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+    /**
+     * Delete a key from the cache
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all items from the cache
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current size of the cache
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get all keys in the cache (in LRU order)
+     */
+    keys() {
+        return this.cache.keys();
+    }
+    /**
+     * Get all values in the cache (in LRU order)
+     */
+    values() {
+        return this.cache.values();
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            utilization: this.cache.size / this.maxSize,
+        };
+    }
+}
+/**
+ * Create a cached version of a function with LRU eviction
+ */
+export function memoizeWithLRU(fn, options) {
+    const cache = new LRUCache({ maxSize: options.maxSize });
+    const defaultKeyFn = (...args) => JSON.stringify(args);
+    const keyFn = options.keyFn ?? defaultKeyFn;
+    return (...args) => {
+        const key = keyFn(...args);
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = fn(...args);
+        cache.set(key, result);
+        return result;
+    };
+}