agent-relay 1.3.0 → 1.3.2

package/dist/wrapper/idle-detector.js

@@ -0,0 +1,279 @@
+/**
+ * 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';
+const DEFAULT_CONFIG = {
+    minSilenceMs: 500,
+    bufferLimit: 10000,
+    confidenceThreshold: 0.7,
+};
+/**
+ * Universal idle detector for any CLI-based agent.
+ */
+export class UniversalIdleDetector {
+    lastOutputTime = 0;
+    outputBuffer = '';
+    pid = null;
+    config;
+    constructor(config = {}) {
+        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) {
+        this.pid = pid;
+    }
+    /**
+     * Get the current PID being monitored.
+     */
+    getPid() {
+        return this.pid;
+    }
+    /**
+     * Process output chunk from the agent.
+     * Call this for every output received from the agent process.
+     */
+    onOutput(chunk) {
+        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.
+     */
+    isProcessWaitingForInput() {
+        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.
+     */
+    getOutputSilenceMs() {
+        return Date.now() - this.lastOutputTime;
+    }
+    /**
+     * Check if the last output ends "naturally" (complete thought vs mid-sentence).
+     * Helps distinguish between pauses in output and waiting for input.
+     */
+    hasNaturalEnding() {
+        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 = {}) {
+        const minSilence = options.minSilenceMs ?? this.config.minSilenceMs;
+        const signals = [];
+        // 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',
+                        }],
+                };
+            }
+        }
+        // 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: [] };
+        }
+        // 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,
+        };
+    }
+    /**
+     * Wait for idle state with timeout.
+     * Returns the idle result when achieved or after timeout.
+     */
+    async waitForIdle(timeoutMs = 30000, pollMs = 200) {
+        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() {
+        this.outputBuffer = '';
+        this.lastOutputTime = Date.now();
+    }
+    /**
+     * Get time since last output in milliseconds.
+     */
+    getTimeSinceLastOutput() {
+        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, sessionName) {
+    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.
+ * Logs a warning on non-Linux platforms where process state inspection isn't available.
+ */
+export function createIdleDetector(config = {}, options = {}) {
+    const detector = new UniversalIdleDetector(config);
+    if (!options.quiet) {
+        if (process.platform === 'darwin') {
+            console.warn('[idle-detector] macOS: using output analysis only (less reliable)');
+        }
+        else if (process.platform === 'win32') {
+            console.warn('[idle-detector] Windows: using output analysis only (less reliable)');
+        }
+    }
+    return detector;
+}
+//# sourceMappingURL=idle-detector.js.map

package/dist/wrapper/parser.d.ts

@@ -104,6 +104,10 @@ export declare class OutputParser {
      *
      * IMPORTANT: We strip ANSI codes for pattern matching, but preserve
      * the original line for output to maintain terminal rendering.
+     *
+     * OPTIMIZATION: Early exit for lines that can't possibly be relay commands.
+     * Most lines don't contain relay patterns, so we avoid expensive regex/ANSI
+     * stripping for the common case.
      */
     private processLine;
     /**

package/dist/wrapper/parser.js

@@ -640,9 +640,23 @@ export class OutputParser {
      *
      * IMPORTANT: We strip ANSI codes for pattern matching, but preserve
      * the original line for output to maintain terminal rendering.
+     *
+     * OPTIMIZATION: Early exit for lines that can't possibly be relay commands.
+     * Most lines don't contain relay patterns, so we avoid expensive regex/ANSI
+     * stripping for the common case.
      */
     processLine(line) {
-        // Strip ANSI codes for pattern matching
+        // FAST PATH: Quick string check before any expensive operations
+        // Most lines don't contain relay commands, so early exit is a big win
+        // Check for prefix bases (without the colon to handle custom prefixes like '>>')
+        const relayBase = this.options.prefix.replace(/:$/, '');
+        const thinkingBase = this.options.thinkingPrefix.replace(/:$/, '');
+        const hasRelayPattern = line.includes(relayBase) || line.includes(thinkingBase);
+        const hasBlockPattern = line.includes('[[') || line.includes('```');
+        if (!hasRelayPattern && !hasBlockPattern) {
+            return { command: null, output: line };
+        }
+        // Strip ANSI codes for pattern matching (only when potentially needed)
         const stripped = stripAnsi(line);
         // Handle code fences
         if (CODE_FENCE.test(stripped)) {
@@ -672,11 +686,13 @@ export class OutputParser {
                 const [raw, target, threadProject, threadId, body] = relayMatch;
                 // Skip instructional/example text (common in system prompts)
                 if (isInstructionalText(body)) {
+                    console.error(`[parser] Filtered inline message to ${target} - instructional text. Body: ${body.substring(0, 100)}`);
                     return { command: null, output: line };
                 }
                 const { to, project } = parseTarget(target);
                 // Skip placeholder target names (common in documentation/examples)
                 if (isPlaceholderTarget(to)) {
+                    console.error(`[parser] Filtered inline message - placeholder target: ${to}`);
                     return { command: null, output: line };
                 }
                 return {
@@ -795,10 +811,12 @@ export class OutputParser {
     shouldFilterFencedInline(target, body) {
         // Check for placeholder target names
         if (isPlaceholderTarget(target)) {
+            console.error(`[parser] Filtered message - placeholder target: ${target}`);
             return true;
         }
         // Check for instructional body content
         if (isInstructionalText(body)) {
+            console.error(`[parser] Filtered message to ${target} - instructional text detected. Body preview: ${body.substring(0, 100)}`);
             return true;
         }
         return false;

package/dist/wrapper/pty-wrapper.d.ts

@@ -112,6 +112,11 @@ export declare class PtyWrapper extends BaseWrapper {
      * Start the agent process
      */
     start(): Promise<void>;
+    /**
+     * Wait for the agent to be ready for input.
+     * Uses idle detection instead of a fixed delay.
+     */
+    private waitForAgentReady;
     /**
      * Inject continuity context from previous session.
      * Called after agent ID initialization to restore state from ledger.
@@ -240,7 +245,8 @@ export declare class PtyWrapper extends BaseWrapper {
     protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
     /**
      * Wait for output to stabilize before injection.
-     * Returns true if output has been stable for the required duration.
+     * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.
+     * Returns true if agent is idle and ready for input.
      */
     private waitForOutputStable;
     /**

package/dist/wrapper/pty-wrapper.js

@@ -184,6 +184,11 @@ export class PtyWrapper extends BaseWrapper {
         }
         this.running = true;
         this.sessionStartTime = Date.now();
+        // Set PID for idle detector (enables process state inspection on Linux)
+        if (this.ptyProcess.pid) {
+            this.setIdleDetectorPid(this.ptyProcess.pid);
+            console.log(`[pty:${this.config.name}] Idle detector initialized with PID ${this.ptyProcess.pid}`);
+        }
         // Skip hooks and continuity in interactive mode - user handles all prompts directly
         if (!this.config.interactive) {
             // Dispatch session start hook (handles trajectory initialization)
@@ -208,9 +213,9 @@ export class PtyWrapper extends BaseWrapper {
             this.config.onExit?.(exitCode);
             this.client.destroy();
         });
-        // Inject initial instructions after a delay, then mark ready for messages
-        // Skip in interactive mode - user handles all prompts directly
-        setTimeout(() => {
+        // Wait for agent to be idle before injecting instructions
+        // This replaces the fixed 2-second delay with actual readiness detection
+        this.waitForAgentReady().then(() => {
             if (!this.config.interactive) {
                 this.injectInstructions();
             }
@@ -219,7 +224,27 @@ export class PtyWrapper extends BaseWrapper {
             if (!this.config.interactive) {
                 this.processMessageQueue();
             }
-        }, 2000);
+        }).catch(err => {
+            console.error(`[pty:${this.config.name}] Failed to wait for agent ready:`, err);
+            // Fall back to marking ready anyway to avoid blocking forever
+            this.readyForMessages = true;
+        });
+    }
+    /**
+     * Wait for the agent to be ready for input.
+     * Uses idle detection instead of a fixed delay.
+     */
+    async waitForAgentReady() {
+        // Minimum wait to ensure the CLI process has started
+        await sleep(500);
+        // Wait for agent to become idle (CLI fully initialized)
+        const result = await this.waitForIdleState(10000, 200);
+        if (result.isIdle) {
+            console.log(`[pty:${this.config.name}] Agent ready (confidence: ${(result.confidence * 100).toFixed(0)}%)`);
+        }
+        else {
+            console.warn(`[pty:${this.config.name}] Agent readiness timeout, proceeding anyway`);
+        }
     }
     // Note: initializeAgentId() and getAgentId() are inherited from BaseWrapper
     /**
@@ -322,6 +347,8 @@ export class PtyWrapper extends BaseWrapper {
     handleOutput(data) {
         // Track output timing for stability checks
         this.lastOutputTime = Date.now();
+        // Feed output to idle detector for robust idle detection
+        this.feedIdleDetectorOutput(data);
         // Append to raw buffer
         this.rawBuffer += data;
         // Write to log file if available
@@ -610,6 +637,7 @@ export class PtyWrapper extends BaseWrapper {
             }
             // Skip placeholder targets (documentation examples like "AgentName", "Lead", etc.)
             if (isPlaceholderTarget(target)) {
+                console.error(`[pty-wrapper] Filtered fenced message - placeholder target: ${target}`);
                 continue;
             }
             // Find the closing >>>
@@ -630,6 +658,7 @@ export class PtyWrapper extends BaseWrapper {
             }
             // Skip placeholder targets after parsing cross-project syntax
             if (isPlaceholderTarget(to)) {
+                console.error(`[pty-wrapper] Filtered fenced message - placeholder target after cross-project parse: ${to}`);
                 continue;
             }
             this.sendRelayCommand({
@@ -676,8 +705,10 @@ export class PtyWrapper extends BaseWrapper {
                 if (!body)
                     continue;
                 // Skip placeholder targets (documentation examples)
-                if (isPlaceholderTarget(target))
+                if (isPlaceholderTarget(target)) {
+                    console.error(`[pty-wrapper] Filtered single-line message - placeholder target: ${target}`);
                     continue;
+                }
                 // Parse target for cross-project syntax
                 const colonIdx = target.indexOf(':');
                 let to = target;
@@ -687,8 +718,10 @@ export class PtyWrapper extends BaseWrapper {
                     to = target.substring(colonIdx + 1);
                 }
                 // Skip placeholder targets after parsing cross-project syntax
-                if (isPlaceholderTarget(to))
+                if (isPlaceholderTarget(to)) {
+                    console.error(`[pty-wrapper] Filtered single-line message - placeholder target after cross-project parse: ${to}`);
                     continue;
+                }
                 this.sendRelayCommand({
                     to,
                     kind: 'message',
@@ -702,8 +735,10 @@ export class PtyWrapper extends BaseWrapper {
             if (!body)
                 continue;
             // Skip placeholder targets (documentation examples)
-            if (isPlaceholderTarget(target))
+            if (isPlaceholderTarget(target)) {
+                console.error(`[pty-wrapper] Filtered single-line message - placeholder target: ${target}`);
                 continue;
+            }
             // Parse target for cross-project syntax
             const colonIdx = target.indexOf(':');
             let to = target;
@@ -713,8 +748,10 @@ export class PtyWrapper extends BaseWrapper {
                 to = target.substring(colonIdx + 1);
             }
             // Skip placeholder targets after parsing cross-project syntax
-            if (isPlaceholderTarget(to))
+            if (isPlaceholderTarget(to)) {
+                console.error(`[pty-wrapper] Filtered single-line message - placeholder target after cross-project parse: ${to}`);
                 continue;
+            }
             this.sendRelayCommand({
                 to,
                 kind: 'message',
@@ -1032,27 +1069,14 @@ export class PtyWrapper extends BaseWrapper {
     }
     /**
      * Wait for output to stabilize before injection.
-     * Returns true if output has been stable for the required duration.
+     * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.
+     * Returns true if agent is idle and ready for input.
      */
     async waitForOutputStable() {
-        const startTime = Date.now();
-        let stablePolls = 0;
-        let lastBufferLength = this.rawBuffer.length;
-        while (Date.now() - startTime < INJECTION_CONSTANTS.STABILITY_TIMEOUT_MS) {
-            await sleep(INJECTION_CONSTANTS.STABILITY_POLL_MS);
-            const timeSinceOutput = Date.now() - this.lastOutputTime;
-            const bufferUnchanged = this.rawBuffer.length === lastBufferLength;
-            // Consider stable if no output for at least one poll interval
-            if (timeSinceOutput >= INJECTION_CONSTANTS.STABILITY_POLL_MS && bufferUnchanged) {
-                stablePolls++;
-                if (stablePolls >= INJECTION_CONSTANTS.REQUIRED_STABLE_POLLS) {
-                    return true;
-                }
-            }
-            else {
-                stablePolls = 0;
-                lastBufferLength = this.rawBuffer.length;
-            }
+        const result = await this.waitForIdleState(INJECTION_CONSTANTS.STABILITY_TIMEOUT_MS, INJECTION_CONSTANTS.STABILITY_POLL_MS);
+        if (result.isIdle) {
+            console.log(`[pty:${this.config.name}] Idle detected (confidence: ${(result.confidence * 100).toFixed(0)}%)`);
+            return true;
         }
         // Timeout - return true anyway to avoid blocking forever
         console.warn(`[pty:${this.config.name}] Stability timeout, proceeding with injection`);

package/dist/wrapper/tmux-wrapper.d.ts

@@ -127,6 +127,16 @@ export declare class TmuxWrapper extends BaseWrapper {
      * Initialize agent ID for continuity/resume functionality (uses logStderr for tmux)
      */
     protected initializeAgentId(): Promise<void>;
+    /**
+     * Initialize the idle detector with the tmux pane PID.
+     * This enables process state inspection on Linux for more reliable idle detection.
+     */
+    private initializeIdleDetectorPid;
+    /**
+     * Wait for the agent to be ready for input.
+     * Uses idle detection instead of a fixed delay.
+     */
+    private waitForAgentReady;
     /**
      * Inject usage instructions for the agent including persistence protocol
      */
@@ -246,7 +256,8 @@ export declare class TmuxWrapper extends BaseWrapper {
      */
     protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
     /**
-     * Check if we should inject a message
+     * Check if we should inject a message.
+     * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.
      */
     private checkForInjectionOpportunity;
     /**