@agent-relay/wrapper 0.1.0

package/src/idle-detector.ts

@@ -0,0 +1,370 @@
+/**
+ * UniversalIdleDetector - Detect when an agent is waiting for input
+ *
+ * Works across all CLI tools (Claude, Codex, Gemini, Aider, etc.) by combining:
+ * 1. Process state inspection via /proc/{pid}/stat (Linux, 95% confidence)
+ * 2. Output silence analysis (cross-platform, 60-80% confidence)
+ * 3. Natural ending detection (heuristic, 60% confidence)
+ *
+ * The hybrid approach ensures reliable idle detection regardless of CLI type.
+ */
+
+import fs from 'node:fs';
+
+export interface IdleSignal {
+  source: 'process_state' | 'output_silence' | 'natural_ending';
+  confidence: number; // 0-1
+  timestamp: number;
+  details?: string;
+}
+
+export interface IdleResult {
+  isIdle: boolean;
+  confidence: number;
+  signals: IdleSignal[];
+  /** True if agent appears to be in an editor mode (vim INSERT, etc.) */
+  inEditorMode?: boolean;
+}
+
+export interface IdleDetectorConfig {
+  /** Minimum silence duration to consider for idle (ms) */
+  minSilenceMs?: number;
+  /** Output buffer size limit */
+  bufferLimit?: number;
+  /** Confidence threshold for idle detection (0-1) */
+  confidenceThreshold?: number;
+}
+
+const DEFAULT_CONFIG: Required<IdleDetectorConfig> = {
+  minSilenceMs: 500,
+  bufferLimit: 10000,
+  confidenceThreshold: 0.7,
+};
+
+/**
+ * Universal idle detector for any CLI-based agent.
+ */
+export class UniversalIdleDetector {
+  private lastOutputTime = 0;
+  private outputBuffer = '';
+  private pid: number | null = null;
+  private config: Required<IdleDetectorConfig>;
+
+  constructor(config: IdleDetectorConfig = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    // Initialize lastOutputTime to now to avoid immediate false positives
+    this.lastOutputTime = Date.now();
+  }
+
+  /**
+   * Set the PID of the agent process to monitor.
+   * Required for Linux process state inspection.
+   */
+  setPid(pid: number): void {
+    this.pid = pid;
+  }
+
+  /**
+   * Get the current PID being monitored.
+   */
+  getPid(): number | null {
+    return this.pid;
+  }
+
+  /**
+   * Process output chunk from the agent.
+   * Call this for every output received from the agent process.
+   */
+  onOutput(chunk: string): void {
+    this.lastOutputTime = Date.now();
+    this.outputBuffer += chunk;
+
+    // Keep buffer bounded
+    if (this.outputBuffer.length > this.config.bufferLimit) {
+      this.outputBuffer = this.outputBuffer.slice(-Math.floor(this.config.bufferLimit / 2));
+    }
+  }
+
+  /**
+   * Check if the agent process is blocked on read (waiting for input).
+   * This is the most reliable signal - the OS knows when a process is waiting.
+   *
+   * Linux-only; returns null on other platforms.
+   */
+  private isProcessWaitingForInput(): { waiting: boolean; wchan?: string } | null {
+    if (process.platform !== 'linux' || !this.pid) {
+      return null; // Can't determine on non-Linux
+    }
+
+    try {
+      // Check process state from /proc/{pid}/stat
+      // State codes: R=running, S=sleeping, D=disk sleep, Z=zombie, T=stopped
+      const statPath = `/proc/${this.pid}/stat`;
+      const stat = fs.readFileSync(statPath, 'utf-8');
+      const fields = stat.split(' ');
+      const state = fields[2]; // Third field is state
+
+      // S (sleeping) often means waiting for I/O
+      if (state !== 'S') {
+        return { waiting: false }; // Running or other state = not waiting
+      }
+
+      // More precise: check what the process is blocked on
+      const wchanPath = `/proc/${this.pid}/wchan`;
+      const wchan = fs.readFileSync(wchanPath, 'utf-8').trim();
+
+      // Common wait channels for terminal input
+      const inputWaitChannels = [
+        'wait_woken',
+        'poll_schedule_timeout',
+        'do_select',
+        'n_tty_read',
+        'unix_stream_read_generic',
+        'pipe_read',
+        'ep_poll',  // epoll wait
+        'futex_wait_queue',  // sometimes seen
+      ];
+
+      const isWaiting = inputWaitChannels.some(ch => wchan.includes(ch));
+      return { waiting: isWaiting, wchan };
+    } catch {
+      return null; // Process may have exited or permission denied
+    }
+  }
+
+  /**
+   * Get milliseconds since last output.
+   */
+  private getOutputSilenceMs(): number {
+    return Date.now() - this.lastOutputTime;
+  }
+
+  /**
+   * Check if the agent is in an editor mode (vim INSERT, REPLACE, etc.).
+   * When in editor mode, message injection should be delayed.
+   */
+  isInEditorMode(): boolean {
+    // Check the last portion of output for editor mode indicators
+    const lastOutput = this.outputBuffer.slice(-500);
+
+    // Vim/Neovim mode indicators
+    const editorModePatterns = [
+      /-- INSERT --/i,
+      /-- REPLACE --/i,
+      /-- VISUAL --/i,
+      /-- VISUAL LINE --/i,
+      /-- VISUAL BLOCK --/i,
+      /-- SELECT --/i,
+      /-- TERMINAL --/i,
+      // Emacs indicators
+      /\*\*\* Emacs/,
+      /M-x/,
+      // nano indicators
+      /GNU nano/,
+      /\^G Get Help/,
+      // less/more pager
+      /:\s*$/,  // Pager prompt
+      /lines \d+-\d+/,  // Pager line indicator
+      // Git interactive rebase
+      /pick [a-f0-9]+/,
+      /# Rebase [a-f0-9]+/,
+    ];
+
+    return editorModePatterns.some(pattern => pattern.test(lastOutput));
+  }
+
+  /**
+   * Check if the last output ends "naturally" (complete thought vs mid-sentence).
+   * Helps distinguish between pauses in output and waiting for input.
+   */
+  private hasNaturalEnding(): boolean {
+    const lastChars = this.outputBuffer.slice(-100).trim();
+    if (lastChars.length === 0) return true;
+
+    // Positive signals: output ended cleanly
+    const naturalEndings = [
+      /[.!?]\s*$/,           // Sentence ended
+      /```\s*$/,             // Code block closed
+      /\n\n$/,               // Paragraph break
+      />\s*$/,               // Prompt character
+      /\$\s*$/,              // Shell prompt
+      />>>\s*$/,             // Python/Aider prompt
+      /❯\s*$/,               // Fancy prompts
+      /λ\s*$/,               // Lambda prompts
+      /→\s*$/,               // Arrow prompts
+    ];
+
+    // Negative signals: output mid-thought
+    const midThought = [
+      /[,;:]\s*$/,           // Comma, semicolon = more coming
+      /\w$/,                 // Ended mid-word (no trailing space)
+      /[-–—]\s*$/,           // Dash = continuation
+      /\(\s*$/,              // Open paren
+      /\[\s*$/,              // Open bracket
+      /\{\s*$/,              // Open brace
+      /\\\s*$/,              // Line continuation
+    ];
+
+    for (const pattern of midThought) {
+      if (pattern.test(lastChars)) {
+        return false;
+      }
+    }
+
+    for (const pattern of naturalEndings) {
+      if (pattern.test(lastChars)) {
+        return true;
+      }
+    }
+
+    // Default: assume natural if no negative signals and some silence
+    return true;
+  }
+
+  /**
+   * Determine if the agent is idle and ready for input.
+   * Combines multiple signals for reliability across all CLI types.
+   */
+  checkIdle(options: { minSilenceMs?: number } = {}): IdleResult {
+    const minSilence = options.minSilenceMs ?? this.config.minSilenceMs;
+    const signals: IdleSignal[] = [];
+
+    // Signal 1: Process state (most reliable on Linux)
+    const processState = this.isProcessWaitingForInput();
+    if (processState !== null) {
+      if (processState.waiting) {
+        signals.push({
+          source: 'process_state',
+          confidence: 0.95, // Very high - OS-level truth
+          timestamp: Date.now(),
+          details: processState.wchan,
+        });
+      } else {
+        // Process is actively running - definitely not idle
+        return {
+          isIdle: false,
+          confidence: 0.95,
+          signals: [{
+            source: 'process_state',
+            confidence: 0.95,
+            timestamp: Date.now(),
+            details: 'process running',
+          }],
+          inEditorMode: this.isInEditorMode(),
+        };
+      }
+    }
+    // processState === null means we can't determine (non-Linux)
+
+    // Signal 2: Output silence
+    const silenceMs = this.getOutputSilenceMs();
+    if (silenceMs > minSilence) {
+      // Confidence scales with silence duration (up to 0.8)
+      // 500ms = 0.13, 1000ms = 0.27, 2000ms = 0.53, 3000ms = 0.8
+      const silenceConfidence = Math.min(silenceMs / 3000, 0.8);
+      signals.push({
+        source: 'output_silence',
+        confidence: silenceConfidence,
+        timestamp: Date.now(),
+        details: `${silenceMs}ms`,
+      });
+    }
+
+    // Signal 3: Natural ending (only if some silence)
+    if (silenceMs > 200 && this.hasNaturalEnding()) {
+      signals.push({
+        source: 'natural_ending',
+        confidence: 0.6,
+        timestamp: Date.now(),
+      });
+    }
+
+    // No signals = not idle
+    if (signals.length === 0) {
+      return { isIdle: false, confidence: 0, signals: [], inEditorMode: this.isInEditorMode() };
+    }
+
+    // Combine signals
+    // Use max confidence, boosted if multiple signals agree
+    const maxConfidence = Math.max(...signals.map(s => s.confidence));
+    const boost = signals.length > 1 ? 0.1 : 0;
+    const combinedConfidence = Math.min(maxConfidence + boost, 1.0);
+
+    return {
+      isIdle: combinedConfidence >= this.config.confidenceThreshold,
+      confidence: combinedConfidence,
+      signals,
+      inEditorMode: this.isInEditorMode(),
+    };
+  }
+
+  /**
+   * Wait for idle state with timeout.
+   * Returns the idle result when achieved or after timeout.
+   */
+  async waitForIdle(timeoutMs = 30000, pollMs = 200): Promise<IdleResult> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeoutMs) {
+      const result = this.checkIdle();
+      if (result.isIdle) {
+        return result;
+      }
+      await new Promise(r => setTimeout(r, pollMs));
+    }
+
+    // Timeout - return current state
+    return this.checkIdle();
+  }
+
+  /**
+   * Reset state (call when agent starts new response).
+   */
+  reset(): void {
+    this.outputBuffer = '';
+    this.lastOutputTime = Date.now();
+  }
+
+  /**
+   * Get time since last output in milliseconds.
+   */
+  getTimeSinceLastOutput(): number {
+    return this.getOutputSilenceMs();
+  }
+}
+
+/**
+ * Get the PID of a process running in a tmux pane.
+ * Uses tmux list-panes with format specifier.
+ */
+export async function getTmuxPanePid(
+  tmuxPath: string,
+  sessionName: string
+): Promise<number | null> {
+  const { exec } = await import('node:child_process');
+  const { promisify } = await import('node:util');
+  const execAsync = promisify(exec);
+
+  try {
+    // Get the PID of the command running in the pane
+    const { stdout } = await execAsync(
+      `"${tmuxPath}" list-panes -t ${sessionName} -F "#{pane_pid}" 2>/dev/null`
+    );
+    const pid = parseInt(stdout.trim(), 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create an idle detector configured for the current platform.
+ * On non-Linux platforms, process state inspection is unavailable but
+ * output silence analysis still works.
+ */
+export function createIdleDetector(
+  config: IdleDetectorConfig = {},
+  options: { quiet?: boolean } = {}
+): UniversalIdleDetector {
+  return new UniversalIdleDetector(config);
+}

package/src/inbox.test.ts

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it, afterEach, beforeEach } from 'vitest';
+import { InboxManager, DEFAULT_INBOX_DIR } from './inbox.js';
+
+function makeTempDir(): string {
+  const base = path.join(process.cwd(), '.tmp-wrapper-inbox-tests');
+  fs.mkdirSync(base, { recursive: true });
+  const dir = fs.mkdtempSync(path.join(base, 'inbox-'));
+  return dir;
+}
+
+function cleanup(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+describe('InboxManager', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = makeTempDir();
+  });
+
+  afterEach(() => {
+    if (tempDir) {
+      cleanup(tempDir);
+    }
+  });
+
+  describe('DEFAULT_INBOX_DIR', () => {
+    it('has expected default value', () => {
+      expect(DEFAULT_INBOX_DIR).toBe('/tmp/agent-relay');
+    });
+  });
+
+  describe('constructor', () => {
+    it('uses default inbox directory when not provided', () => {
+      const manager = new InboxManager({ agentName: 'TestAgent' });
+      expect(manager.getInboxPath()).toBe(
+        path.join(DEFAULT_INBOX_DIR, 'TestAgent', 'inbox.md')
+      );
+    });
+
+    it('uses custom inbox directory when provided', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      expect(manager.getInboxPath()).toBe(
+        path.join(tempDir, 'TestAgent', 'inbox.md')
+      );
+    });
+  });
+
+  describe('init', () => {
+    it('creates agent directory if it does not exist', () => {
+      const manager = new InboxManager({
+        agentName: 'NewAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+
+      const agentDir = path.join(tempDir, 'NewAgent');
+      expect(fs.existsSync(agentDir)).toBe(true);
+    });
+
+    it('creates empty inbox file', () => {
+      const manager = new InboxManager({
+        agentName: 'NewAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+
+      const inboxPath = manager.getInboxPath();
+      expect(fs.existsSync(inboxPath)).toBe(true);
+      expect(fs.readFileSync(inboxPath, 'utf-8')).toBe('');
+    });
+
+    it('clears existing inbox on init', () => {
+      const agentDir = path.join(tempDir, 'ExistingAgent');
+      fs.mkdirSync(agentDir, { recursive: true });
+      const inboxPath = path.join(agentDir, 'inbox.md');
+      fs.writeFileSync(inboxPath, 'Old content');
+
+      const manager = new InboxManager({
+        agentName: 'ExistingAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+
+      expect(fs.readFileSync(inboxPath, 'utf-8')).toBe('');
+    });
+  });
+
+  describe('getInboxPath', () => {
+    it('returns correct path', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      expect(manager.getInboxPath()).toBe(
+        path.join(tempDir, 'TestAgent', 'inbox.md')
+      );
+    });
+  });
+
+  describe('addMessage', () => {
+    it('adds message to empty inbox with header', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+
+      manager.addMessage('SenderAgent', 'Hello World');
+
+      const content = fs.readFileSync(manager.getInboxPath(), 'utf-8');
+      expect(content).toContain('# 📬 INBOX');
+      expect(content).toContain('## Message from SenderAgent |');
+      expect(content).toContain('Hello World');
+    });
+
+    it('appends multiple messages', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+
+      manager.addMessage('Agent1', 'First message');
+      manager.addMessage('Agent2', 'Second message');
+
+      const content = fs.readFileSync(manager.getInboxPath(), 'utf-8');
+      expect(content).toContain('## Message from Agent1 |');
+      expect(content).toContain('First message');
+      expect(content).toContain('## Message from Agent2 |');
+      expect(content).toContain('Second message');
+    });
+
+    it('includes timestamp in ISO format', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+
+      manager.addMessage('Sender', 'Test');
+
+      const content = fs.readFileSync(manager.getInboxPath(), 'utf-8');
+      // Check timestamp is present (at least the date part)
+      expect(content).toMatch(/## Message from Sender \| \d{4}-\d{2}-\d{2}/);
+    });
+
+    it('handles adding to non-existent inbox file', () => {
+      const agentDir = path.join(tempDir, 'NoInit');
+      fs.mkdirSync(agentDir, { recursive: true });
+
+      const manager = new InboxManager({
+        agentName: 'NoInit',
+        inboxDir: tempDir,
+      });
+      // Don't call init()
+
+      manager.addMessage('Sender', 'Message without init');
+
+      const content = fs.readFileSync(manager.getInboxPath(), 'utf-8');
+      expect(content).toContain('# 📬 INBOX');
+      expect(content).toContain('Message without init');
+    });
+  });
+
+  describe('clear', () => {
+    it('clears inbox content', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+      manager.addMessage('Sender', 'Content to clear');
+
+      manager.clear();
+
+      expect(fs.readFileSync(manager.getInboxPath(), 'utf-8')).toBe('');
+    });
+  });
+
+  describe('hasMessages', () => {
+    it('returns false when inbox does not exist', () => {
+      const manager = new InboxManager({
+        agentName: 'NoExist',
+        inboxDir: tempDir,
+      });
+      expect(manager.hasMessages()).toBe(false);
+    });
+
+    it('returns false when inbox is empty', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+      expect(manager.hasMessages()).toBe(false);
+    });
+
+    it('returns false when inbox has only header', () => {
+      const agentDir = path.join(tempDir, 'TestAgent');
+      fs.mkdirSync(agentDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(agentDir, 'inbox.md'),
+        '# 📬 INBOX\n'
+      );
+
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      expect(manager.hasMessages()).toBe(false);
+    });
+
+    it('returns true when inbox has messages', () => {
+      const manager = new InboxManager({
+        agentName: 'TestAgent',
+        inboxDir: tempDir,
+      });
+      manager.init();
+      manager.addMessage('Sender', 'A message');
+
+      expect(manager.hasMessages()).toBe(true);
+    });
+  });
+});

package/src/inbox.ts

@@ -0,0 +1,89 @@
+/**
+ * File-based Inbox Manager
+ * Writes incoming messages to a file that the CLI agent reads itself.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_INBOX_DIR = '/tmp/agent-relay';
+
+export interface InboxConfig {
+  agentName: string;
+  inboxDir: string;
+}
+
+export class InboxManager {
+  private config: InboxConfig;
+  private inboxPath: string;
+
+  constructor(config: Partial<InboxConfig> & { agentName: string }) {
+    this.config = {
+      inboxDir: DEFAULT_INBOX_DIR,
+      ...config,
+    };
+    this.inboxPath = path.join(this.config.inboxDir, this.config.agentName, 'inbox.md');
+  }
+
+  /**
+   * Initialize inbox directory and file.
+   */
+  init(): void {
+    const dir = path.dirname(this.inboxPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    // Start with empty inbox
+    this.clear();
+  }
+
+  /**
+   * Get the inbox file path (for telling the agent where to read).
+   */
+  getInboxPath(): string {
+    return this.inboxPath;
+  }
+
+  /**
+   * Add a message to the inbox.
+   */
+  addMessage(from: string, body: string): void {
+    const timestamp = new Date().toISOString();
+    const entry = `\n## Message from ${from} | ${timestamp}\n${body}\n`;
+
+    // Read existing content
+    let content = '';
+    if (fs.existsSync(this.inboxPath)) {
+      content = fs.readFileSync(this.inboxPath, 'utf-8');
+    }
+
+    // If empty, add header
+    if (!content.trim()) {
+      content = `# 📬 INBOX - CHECK AND RESPOND TO ALL MESSAGES\n`;
+    }
+
+    // Append new message
+    content += entry;
+
+    // Atomic write (write to temp, then rename)
+    const tmpPath = `${this.inboxPath}.tmp`;
+    fs.writeFileSync(tmpPath, content, 'utf-8');
+    fs.renameSync(tmpPath, this.inboxPath);
+  }
+
+  /**
+   * Clear the inbox.
+   */
+  clear(): void {
+    fs.writeFileSync(this.inboxPath, '', 'utf-8');
+  }
+
+  /**
+   * Check if inbox has messages.
+   */
+  hasMessages(): boolean {
+    if (!fs.existsSync(this.inboxPath)) return false;
+    const content = fs.readFileSync(this.inboxPath, 'utf-8');
+    return content.includes('## Message from');
+  }
+}