@agent-relay/wrapper 0.1.0

package/src/tmux-resolver.ts

@@ -0,0 +1,207 @@
+/**
+ * Tmux Binary Resolver
+ *
+ * Locates tmux binary with fallback to bundled version.
+ * Priority:
+ * 1. System tmux (in PATH)
+ * 2. Bundled tmux within the agent-relay package (bin/tmux)
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Get the package root directory (where agent-relay is installed)
+ * This works whether we're in dist/utils/ or src/utils/
+ */
+function getPackageRoot(): string {
+  // Navigate up from dist/utils or src/utils to package root
+  return path.resolve(__dirname, '..', '..');
+}
+
+/** Path where bundled tmux binary is installed (within the package) */
+export function getBundledTmuxDir(): string {
+  return path.join(getPackageRoot(), 'bin');
+}
+
+export function getBundledTmuxPath(): string {
+  return path.join(getBundledTmuxDir(), 'tmux');
+}
+
+// Legacy exports for backwards compatibility
+export const BUNDLED_TMUX_DIR = getBundledTmuxDir();
+export const BUNDLED_TMUX_PATH = getBundledTmuxPath();
+
+/** Minimum supported tmux version */
+export const MIN_TMUX_VERSION = '3.0';
+
+export interface TmuxInfo {
+  /** Full path to tmux binary */
+  path: string;
+  /** Version string (e.g., "3.6a") */
+  version: string;
+  /** Whether this is the bundled version */
+  isBundled: boolean;
+}
+
+/**
+ * Check if tmux exists at a given path and get its version
+ */
+function getTmuxVersion(tmuxPath: string): string | null {
+  try {
+    const output = execSync(`"${tmuxPath}" -V`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    // Output format: "tmux 3.6a" or similar
+    const match = output.trim().match(/tmux\s+(\d+\.\d+\w?)/i);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find tmux in system PATH
+ */
+function findSystemTmux(): string | null {
+  try {
+    const output = execSync('which tmux', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve tmux binary path with fallback to bundled version.
+ * Returns null if tmux is not available.
+ */
+export function resolveTmux(): TmuxInfo | null {
+  // 1. Check system tmux first
+  const systemPath = findSystemTmux();
+  if (systemPath) {
+    const version = getTmuxVersion(systemPath);
+    if (version) {
+      return {
+        path: systemPath,
+        version,
+        isBundled: false,
+      };
+    }
+  }
+
+  // 2. Check bundled tmux (within the package)
+  const bundledPath = getBundledTmuxPath();
+  if (fs.existsSync(bundledPath)) {
+    const version = getTmuxVersion(bundledPath);
+    if (version) {
+      return {
+        path: bundledPath,
+        version,
+        isBundled: true,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get the tmux command to use. Throws if tmux is not available.
+ */
+export function getTmuxPath(): string {
+  const info = resolveTmux();
+  if (!info) {
+    throw new TmuxNotFoundError();
+  }
+  return info.path;
+}
+
+/**
+ * Check if tmux is available (either system or bundled)
+ */
+export function isTmuxAvailable(): boolean {
+  return resolveTmux() !== null;
+}
+
+/**
+ * Get platform identifier for downloading binaries
+ */
+export function getPlatformIdentifier(): string | null {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  if (platform === 'darwin') {
+    return arch === 'arm64' ? 'macos-arm64' : 'macos-x86_64';
+  } else if (platform === 'linux') {
+    return arch === 'arm64' ? 'linux-arm64' : 'linux-x86_64';
+  }
+
+  // Unsupported platform
+  return null;
+}
+
+/**
+ * Error thrown when tmux is not available
+ */
+export class TmuxNotFoundError extends Error {
+  constructor() {
+    const platformInstructions = (() => {
+      switch (os.platform()) {
+        case 'darwin':
+          return '  macOS: brew install tmux';
+        case 'linux':
+          return '  Ubuntu/Debian: sudo apt install tmux\n  Fedora: sudo dnf install tmux\n  Arch: sudo pacman -S tmux';
+        case 'win32':
+          return '  Windows: tmux requires WSL (Windows Subsystem for Linux)\n  Install WSL, then: sudo apt install tmux';
+        default:
+          return '  See: https://github.com/tmux/tmux/wiki/Installing';
+      }
+    })();
+
+    super(
+      `tmux is required but not found.\n\nInstall tmux:\n${platformInstructions}\n\nThen reinstall agent-relay: npm install agent-relay`
+    );
+    this.name = 'TmuxNotFoundError';
+  }
+}
+
+/**
+ * Parse version string to compare versions
+ */
+function parseVersion(version: string): { major: number; minor: number } {
+  const match = version.match(/(\d+)\.(\d+)/);
+  if (!match) {
+    return { major: 0, minor: 0 };
+  }
+  return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
+}
+
+/**
+ * Check if installed tmux version meets minimum requirements
+ */
+export function checkTmuxVersion(): { ok: boolean; version: string | null; minimum: string } {
+  const info = resolveTmux();
+  if (!info) {
+    return { ok: false, version: null, minimum: MIN_TMUX_VERSION };
+  }
+
+  const installed = parseVersion(info.version);
+  const required = parseVersion(MIN_TMUX_VERSION);
+
+  const ok =
+    installed.major > required.major ||
+    (installed.major === required.major && installed.minor >= required.minor);
+
+  return { ok, version: info.version, minimum: MIN_TMUX_VERSION };
+}

package/src/tmux-wrapper.test.ts

@@ -0,0 +1,316 @@
+/**
+ * Unit tests for TmuxWrapper constants and utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getDefaultPrefix } from './tmux-wrapper.js';
+import {
+  type InjectionResult,
+  INJECTION_CONSTANTS,
+  createInjectionMetrics,
+} from './shared.js';
+
+describe('TmuxWrapper constants', () => {
+  // Unified prefix across all CLI types
+  describe('getDefaultPrefix', () => {
+    it('returns ->relay: for gemini CLI type', () => {
+      expect(getDefaultPrefix('gemini')).toBe('->relay:');
+    });
+
+    it('returns ->relay: for claude CLI type', () => {
+      expect(getDefaultPrefix('claude')).toBe('->relay:');
+    });
+
+    it('returns ->relay: for codex CLI type', () => {
+      expect(getDefaultPrefix('codex')).toBe('->relay:');
+    });
+
+    it('returns ->relay: for other CLI type', () => {
+      expect(getDefaultPrefix('other')).toBe('->relay:');
+    });
+  });
+});
+
+describe('String truncation safety', () => {
+  // Test the truncation pattern used throughout tmux-wrapper
+  // Pattern: str.substring(0, Math.min(LIMIT, str.length))
+
+  const safeSubstring = (str: string, maxLen: number): string => {
+    return str.substring(0, Math.min(maxLen, str.length));
+  };
+
+  describe('safeSubstring helper pattern', () => {
+    it('truncates long strings', () => {
+      const longString = 'a'.repeat(100);
+      expect(safeSubstring(longString, 40)).toBe('a'.repeat(40));
+      expect(safeSubstring(longString, 40)).toHaveLength(40);
+    });
+
+    it('preserves short strings', () => {
+      const shortString = 'hello';
+      expect(safeSubstring(shortString, 40)).toBe('hello');
+      expect(safeSubstring(shortString, 40)).toHaveLength(5);
+    });
+
+    it('handles exact length strings', () => {
+      const exactString = 'a'.repeat(40);
+      expect(safeSubstring(exactString, 40)).toBe(exactString);
+      expect(safeSubstring(exactString, 40)).toHaveLength(40);
+    });
+
+    it('handles empty strings', () => {
+      expect(safeSubstring('', 40)).toBe('');
+      expect(safeSubstring('', 40)).toHaveLength(0);
+    });
+
+    it('handles strings shorter than limit', () => {
+      expect(safeSubstring('ab', 40)).toBe('ab');
+    });
+
+    it('handles limit of 0', () => {
+      expect(safeSubstring('hello', 0)).toBe('');
+    });
+
+    it('handles unicode characters', () => {
+      const unicodeStr = ''.repeat(100);
+      expect(safeSubstring(unicodeStr, 10)).toBe(''.repeat(10));
+    });
+  });
+
+  describe('DEBUG_LOG_TRUNCATE_LENGTH constant (40)', () => {
+    const DEBUG_LOG_TRUNCATE_LENGTH = 40;
+
+    it('truncates debug log content appropriately', () => {
+      const longMessage = 'This is a very long debug message that exceeds the limit';
+      const truncated = safeSubstring(longMessage, DEBUG_LOG_TRUNCATE_LENGTH);
+      expect(truncated).toBe('This is a very long debug message that e');
+      expect(truncated).toHaveLength(40);
+    });
+  });
+
+  describe('RELAY_LOG_TRUNCATE_LENGTH constant (50)', () => {
+    const RELAY_LOG_TRUNCATE_LENGTH = 50;
+
+    it('truncates relay command log content appropriately', () => {
+      const longMessage = 'This is a very long relay message that definitely exceeds the fifty character limit';
+      const truncated = safeSubstring(longMessage, RELAY_LOG_TRUNCATE_LENGTH);
+      expect(truncated).toBe('This is a very long relay message that definitely ');
+      expect(truncated).toHaveLength(50);
+    });
+  });
+});
+
+describe('Cursor stability constants', () => {
+  // These test the logic that uses STABLE_CURSOR_THRESHOLD and MAX_PROMPT_CURSOR_POSITION
+
+  const STABLE_CURSOR_THRESHOLD = 3;
+  const MAX_PROMPT_CURSOR_POSITION = 4;
+
+  describe('STABLE_CURSOR_THRESHOLD', () => {
+    it('requires 3 or more stable polls to consider input clear', () => {
+      // Simulate cursor stability counting
+      let stableCursorCount = 0;
+      const cursorX = 2;
+
+      // First poll - not stable yet
+      stableCursorCount++;
+      expect(stableCursorCount >= STABLE_CURSOR_THRESHOLD).toBe(false);
+
+      // Second poll - still not stable
+      stableCursorCount++;
+      expect(stableCursorCount >= STABLE_CURSOR_THRESHOLD).toBe(false);
+
+      // Third poll - now stable
+      stableCursorCount++;
+      expect(stableCursorCount >= STABLE_CURSOR_THRESHOLD).toBe(true);
+      expect(cursorX <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+    });
+
+    it('resets count when cursor moves', () => {
+      let stableCursorCount = 2;
+      let lastCursorX = 2;
+      const newCursorX = 5; // Cursor moved
+
+      if (newCursorX !== lastCursorX) {
+        stableCursorCount = 0;
+        lastCursorX = newCursorX;
+      }
+
+      expect(stableCursorCount).toBe(0);
+    });
+  });
+
+  describe('MAX_PROMPT_CURSOR_POSITION', () => {
+    it('considers positions 0-4 as typical prompt positions', () => {
+      expect(0 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(1 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(2 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(3 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+      expect(4 <= MAX_PROMPT_CURSOR_POSITION).toBe(true);
+    });
+
+    it('considers positions > 4 as likely having user input', () => {
+      expect(5 <= MAX_PROMPT_CURSOR_POSITION).toBe(false);
+      expect(10 <= MAX_PROMPT_CURSOR_POSITION).toBe(false);
+    });
+
+    it('works with combined stability check', () => {
+      const stableCursorCount = 3;
+      const cursorAtPrompt = 2;
+      const cursorWithInput = 10;
+
+      // At prompt position - should be considered clear
+      const isClearAtPrompt =
+        stableCursorCount >= STABLE_CURSOR_THRESHOLD &&
+        cursorAtPrompt <= MAX_PROMPT_CURSOR_POSITION;
+      expect(isClearAtPrompt).toBe(true);
+
+      // With input - should not be considered clear
+      const isClearWithInput =
+        stableCursorCount >= STABLE_CURSOR_THRESHOLD &&
+        cursorWithInput <= MAX_PROMPT_CURSOR_POSITION;
+      expect(isClearWithInput).toBe(false);
+    });
+  });
+});
+
+describe('Injection retry logic', () => {
+  // Test the retry logic pattern used by injectWithRetry
+
+  describe('INJECTION_CONSTANTS', () => {
+    it('has correct MAX_RETRIES', () => {
+      expect(INJECTION_CONSTANTS.MAX_RETRIES).toBe(3);
+    });
+
+    it('has correct VERIFICATION_TIMEOUT_MS', () => {
+      expect(INJECTION_CONSTANTS.VERIFICATION_TIMEOUT_MS).toBe(2000);
+    });
+
+    it('has correct RETRY_BACKOFF_MS', () => {
+      expect(INJECTION_CONSTANTS.RETRY_BACKOFF_MS).toBe(200);
+    });
+  });
+
+  describe('InjectionMetrics tracking', () => {
+    it('initializes with zero counts', () => {
+      const metrics = createInjectionMetrics();
+      expect(metrics.total).toBe(0);
+      expect(metrics.successFirstTry).toBe(0);
+      expect(metrics.successWithRetry).toBe(0);
+      expect(metrics.failed).toBe(0);
+    });
+
+    it('tracks successful first-try injection', () => {
+      const metrics = createInjectionMetrics();
+
+      // Simulate successful first-try injection
+      metrics.total++;
+      const verified = true;
+      const attempt = 0;
+      if (verified && attempt === 0) {
+        metrics.successFirstTry++;
+      }
+
+      expect(metrics.total).toBe(1);
+      expect(metrics.successFirstTry).toBe(1);
+      expect(metrics.successWithRetry).toBe(0);
+      expect(metrics.failed).toBe(0);
+    });
+
+    it('tracks successful retry injection', () => {
+      const metrics = createInjectionMetrics();
+
+      // Simulate successful injection on retry
+      metrics.total++;
+      const verified = true;
+      const attempt = 2; // Third attempt
+      if (verified && attempt > 0) {
+        metrics.successWithRetry++;
+      }
+
+      expect(metrics.total).toBe(1);
+      expect(metrics.successFirstTry).toBe(0);
+      expect(metrics.successWithRetry).toBe(1);
+      expect(metrics.failed).toBe(0);
+    });
+
+    it('tracks failed injection', () => {
+      const metrics = createInjectionMetrics();
+
+      // Simulate failed injection after all retries
+      metrics.total++;
+      metrics.failed++;
+
+      expect(metrics.total).toBe(1);
+      expect(metrics.successFirstTry).toBe(0);
+      expect(metrics.successWithRetry).toBe(0);
+      expect(metrics.failed).toBe(1);
+    });
+  });
+
+  describe('InjectionResult structure', () => {
+    it('returns success result on first try', () => {
+      const result: InjectionResult = { success: true, attempts: 1 };
+      expect(result.success).toBe(true);
+      expect(result.attempts).toBe(1);
+    });
+
+    it('returns success result after retries', () => {
+      const result: InjectionResult = { success: true, attempts: 3 };
+      expect(result.success).toBe(true);
+      expect(result.attempts).toBe(3);
+    });
+
+    it('returns failure result after max retries', () => {
+      const result: InjectionResult = {
+        success: false,
+        attempts: INJECTION_CONSTANTS.MAX_RETRIES,
+      };
+      expect(result.success).toBe(false);
+      expect(result.attempts).toBe(3);
+    });
+
+    it('can include fallback flag', () => {
+      const result: InjectionResult = {
+        success: false,
+        attempts: 3,
+        fallbackUsed: true,
+      };
+      expect(result.fallbackUsed).toBe(true);
+    });
+  });
+
+  describe('Backoff calculation', () => {
+    it('increases backoff with each attempt', () => {
+      const backoffMs = INJECTION_CONSTANTS.RETRY_BACKOFF_MS;
+
+      // Backoff for attempt 0 (first retry)
+      const backoff0 = backoffMs * 1;
+      expect(backoff0).toBe(200);
+
+      // Backoff for attempt 1 (second retry)
+      const backoff1 = backoffMs * 2;
+      expect(backoff1).toBe(400);
+
+      // Backoff for attempt 2 (third retry - but no backoff needed after last attempt)
+      const backoff2 = backoffMs * 3;
+      expect(backoff2).toBe(600);
+    });
+  });
+
+  describe('Verification pattern matching', () => {
+    it('generates correct expected pattern', () => {
+      const shortId = 'abc12345';
+      const from = 'TestAgent';
+      const expectedPattern = `Relay message from ${from} [${shortId}]`;
+      expect(expectedPattern).toBe('Relay message from TestAgent [abc12345]');
+    });
+
+    it('handles different agent names', () => {
+      const shortId = 'def67890';
+      const from = 'Backend';
+      const expectedPattern = `Relay message from ${from} [${shortId}]`;
+      expect(expectedPattern).toBe('Relay message from Backend [def67890]');
+    });
+  });
+});