@agent-relay/wrapper 0.1.0

package/dist/shared.js

@@ -0,0 +1,341 @@
+/**
+ * Shared types and utilities for TmuxWrapper and PtyWrapper
+ *
+ * This module contains common code to prevent drift between the two
+ * wrapper implementations and reduce duplication.
+ */
+/**
+ * Injection timing constants
+ *
+ * Performance tuning (2024-01):
+ * - QUEUE_PROCESS_DELAY_MS: 500ms → 100ms (5x faster message throughput)
+ * - STABILITY_POLL_MS: 200ms → 100ms (faster idle detection)
+ * - ENTER_DELAY_MS: 100ms → 50ms (faster message completion)
+ * - RETRY_BACKOFF_MS: 300ms → 200ms (faster recovery)
+ *
+ * Use AdaptiveThrottle class for dynamic backpressure handling.
+ */
+export const INJECTION_CONSTANTS = {
+    /** Maximum retry attempts for injection */
+    MAX_RETRIES: 3,
+    /** Timeout for output stability check (ms) */
+    STABILITY_TIMEOUT_MS: 3000,
+    /** Polling interval for stability check (ms) - reduced from 200ms */
+    STABILITY_POLL_MS: 100,
+    /** Required consecutive stable polls before injection */
+    REQUIRED_STABLE_POLLS: 2,
+    /** Timeout for injection verification (ms) */
+    VERIFICATION_TIMEOUT_MS: 2000,
+    /** Delay between message and Enter key (ms) - reduced from 100ms */
+    ENTER_DELAY_MS: 50,
+    /** Backoff multiplier for retries (ms per attempt) - reduced from 300ms */
+    RETRY_BACKOFF_MS: 200,
+    /** Base delay between processing queued messages (ms) - reduced from 500ms */
+    QUEUE_PROCESS_DELAY_MS: 100,
+    /** Maximum delay when under backpressure (ms) */
+    QUEUE_PROCESS_DELAY_MAX_MS: 500,
+    /** Threshold for increasing delay (consecutive failures) */
+    BACKPRESSURE_THRESHOLD: 2,
+};
+/**
+ * Adaptive throttle for message queue processing.
+ * Increases delay when failures occur, decreases on success.
+ *
+ * This allows fast messaging under normal conditions (~100ms between messages)
+ * while automatically backing off when the system is under stress.
+ */
+export class AdaptiveThrottle {
+    consecutiveFailures = 0;
+    currentDelay = INJECTION_CONSTANTS.QUEUE_PROCESS_DELAY_MS;
+    /** Get current delay in milliseconds */
+    getDelay() {
+        return this.currentDelay;
+    }
+    /** Record a successful injection - decrease delay */
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        // Gradually decrease delay on success (exponential decay toward minimum)
+        this.currentDelay = Math.max(INJECTION_CONSTANTS.QUEUE_PROCESS_DELAY_MS, Math.floor(this.currentDelay * 0.7));
+    }
+    /** Record a failed injection - increase delay if threshold exceeded */
+    recordFailure() {
+        this.consecutiveFailures++;
+        if (this.consecutiveFailures >= INJECTION_CONSTANTS.BACKPRESSURE_THRESHOLD) {
+            // Increase delay when under backpressure (exponential backoff)
+            this.currentDelay = Math.min(INJECTION_CONSTANTS.QUEUE_PROCESS_DELAY_MAX_MS, Math.floor(this.currentDelay * 1.5));
+        }
+    }
+    /** Reset to default state */
+    reset() {
+        this.consecutiveFailures = 0;
+        this.currentDelay = INJECTION_CONSTANTS.QUEUE_PROCESS_DELAY_MS;
+    }
+}
+/**
+ * Strip ANSI escape codes from a string.
+ * Converts cursor movements to spaces to preserve visual layout.
+ */
+export function stripAnsi(str) {
+    // Convert cursor forward movements to spaces (CSI n C)
+    // eslint-disable-next-line no-control-regex
+    let result = str.replace(/\x1B\[(\d+)C/g, (_m, n) => ' '.repeat(parseInt(n, 10) || 1));
+    // Convert single cursor right (CSI C) to space
+    // eslint-disable-next-line no-control-regex
+    result = result.replace(/\x1B\[C/g, ' ');
+    // Remove carriage returns (causes text overwriting issues)
+    result = result.replace(/\r(?!\n)/g, '');
+    // Strip ANSI escape sequences (with \x1B prefix)
+    // eslint-disable-next-line no-control-regex
+    result = result.replace(/\x1B(?:\[[0-9;?]*[A-Za-z]|\].*?(?:\x07|\x1B\\)|[@-Z\\-_])/g, '');
+    // Strip orphaned CSI sequences that lost their escape byte
+    // Requires at least one digit or question mark to avoid stripping legitimate text like [Agent
+    result = result.replace(/^\s*(\[(?:\?|\d)\d*[A-Za-z])+\s*/g, '');
+    return result;
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Build the injection string for a relay message.
+ * Format: Relay message from {from} [{shortId}]{hints}: {body}
+ *
+ * If the body is already formatted (starts with "Relay message from"),
+ * returns it as-is to prevent double-wrapping.
+ */
+export function buildInjectionString(msg) {
+    // Check if body is already formatted (prevents double-wrapping)
+    // This can happen when:
+    // - Delivering queued/pending messages that were already formatted
+    // - Agent output includes quoted relay messages that get re-processed
+    // Strip ANSI first so escape codes don't interfere with detection
+    const sanitizedBody = stripAnsi(msg.body || '').replace(/[\r\n]+/g, ' ').trim();
+    if (sanitizedBody.startsWith('Relay message from ')) {
+        // Already formatted - return as-is
+        return sanitizedBody;
+    }
+    const shortId = msg.messageId.substring(0, 8);
+    // Use senderName from data if available (for dashboard messages sent via _DashboardUI)
+    // This allows showing the actual GitHub username instead of the system client name
+    const displayFrom = (msg.from === '_DashboardUI' && typeof msg.data?.senderName === 'string')
+        ? msg.data.senderName
+        : msg.from;
+    // Thread hint
+    const threadHint = msg.thread ? ` [thread:${msg.thread}]` : '';
+    // Importance indicator: [!!] for high (>75), [!] for medium (>50)
+    const importanceHint = msg.importance !== undefined && msg.importance > 75
+        ? ' [!!]'
+        : msg.importance !== undefined && msg.importance > 50
+            ? ' [!]'
+            : '';
+    // Channel indicator for channel messages and broadcasts
+    // originalTo will be '*' for broadcasts or the channel name (e.g., '#general') for channel messages
+    // Make it clear that replies should go to the channel, not the sender
+    const channelHint = msg.originalTo === '*'
+        ? ' [#general] (reply to #general, not sender)'
+        : msg.originalTo?.startsWith('#')
+            ? ` [${msg.originalTo}] (reply to ${msg.originalTo}, not sender)`
+            : '';
+    // Extract attachment file paths if present
+    let attachmentHint = '';
+    if (msg.data?.attachments && Array.isArray(msg.data.attachments)) {
+        const filePaths = msg.data.attachments
+            .map((att) => att.filePath)
+            .filter((p) => typeof p === 'string');
+        if (filePaths.length > 0) {
+            attachmentHint = ` [Attachments: ${filePaths.join(', ')}]`;
+        }
+    }
+    return `Relay message from ${displayFrom} [${shortId}]${threadHint}${importanceHint}${channelHint}${attachmentHint}: ${sanitizedBody}`;
+}
+/**
+ * Calculate injection success rate from metrics
+ */
+export function calculateSuccessRate(metrics) {
+    if (metrics.total === 0)
+        return 100;
+    const successful = metrics.successFirstTry + metrics.successWithRetry;
+    return Math.round((successful / metrics.total) * 10000) / 100;
+}
+/**
+ * Create a fresh injection metrics object
+ */
+export function createInjectionMetrics() {
+    return {
+        total: 0,
+        successFirstTry: 0,
+        successWithRetry: 0,
+        failed: 0,
+    };
+}
+/**
+ * Detect CLI type from command string
+ */
+export function detectCliType(command) {
+    const cmdLower = command.toLowerCase();
+    if (cmdLower.includes('gemini'))
+        return 'gemini';
+    if (cmdLower.includes('codex'))
+        return 'codex';
+    if (cmdLower.includes('claude'))
+        return 'claude';
+    if (cmdLower.includes('droid'))
+        return 'droid';
+    if (cmdLower.includes('opencode'))
+        return 'opencode';
+    if (cmdLower.includes('cursor'))
+        return 'cursor';
+    return 'other';
+}
+/**
+ * Get the default relay prefix (unified for all agent types)
+ */
+export function getDefaultRelayPrefix() {
+    return '->relay:';
+}
+/**
+ * CLI-specific quirks and handling
+ */
+export const CLI_QUIRKS = {
+    /**
+     * CLIs that support bracketed paste mode.
+     * Others may interpret the escape sequences literally.
+     */
+    supportsBracketedPaste: (cli) => {
+        return cli === 'claude' || cli === 'codex' || cli === 'gemini' || cli === 'opencode' || cli === 'cursor';
+    },
+    /**
+     * Gemini interprets certain keywords (While, For, If, etc.) as shell commands.
+     * Wrap message in backticks to prevent shell keyword interpretation.
+     */
+    wrapForGemini: (body) => {
+        return `\`${body.replace(/`/g, "'")}\``;
+    },
+    /**
+     * Get prompt pattern regex for a CLI type.
+     * Used to detect when input line is clear.
+     */
+    getPromptPattern: (cli) => {
+        const patterns = {
+            claude: /^[>›»]\s*$/,
+            gemini: /^[>›»]\s*$/,
+            codex: /^[>›»]\s*$/,
+            droid: /^[>›»]\s*$/,
+            opencode: /^[>›»]\s*$/,
+            cursor: /^[>›»]\s*$/,
+            spawned: /^[>›»]\s*$/,
+            other: /^[>$%#➜›»]\s*$/,
+        };
+        return patterns[cli] || patterns.other;
+    },
+    /**
+     * Check if a line looks like a shell prompt (for Gemini safety check).
+     * Gemini can drop into shell mode - we skip injection to avoid executing commands.
+     */
+    isShellPrompt: (line) => {
+        const clean = stripAnsi(line).trim();
+        return /^\$\s*$/.test(clean) || /^\s*\$\s*$/.test(clean);
+    },
+};
+/**
+ * Verify that an injected message appeared in the output.
+ * Uses a callback to get output content, allowing different backends
+ * (tmux capture-pane, PTY buffer) to be used.
+ *
+ * @param shortId - First 8 chars of message ID
+ * @param from - Sender name
+ * @param getOutput - Callback to retrieve current output
+ * @returns true if message pattern found in output
+ */
+export async function verifyInjection(shortId, from, getOutput) {
+    const expectedPattern = `Relay message from ${from} [${shortId}]`;
+    const startTime = Date.now();
+    while (Date.now() - startTime < INJECTION_CONSTANTS.VERIFICATION_TIMEOUT_MS) {
+        try {
+            const output = await getOutput();
+            if (output.includes(expectedPattern)) {
+                return true;
+            }
+        }
+        catch {
+            // Output retrieval failed, verification fails
+            return false;
+        }
+        await sleep(100);
+    }
+    return false;
+}
+/**
+ * Inject a message with retry logic and verification.
+ * Includes dedup check to prevent double-injection race condition.
+ *
+ * This consolidates the retry/verification logic that was duplicated
+ * in TmuxWrapper and PtyWrapper.
+ *
+ * @param injection - The formatted injection string
+ * @param shortId - First 8 chars of message ID for verification
+ * @param from - Sender name for verification pattern
+ * @param callbacks - Wrapper-specific callbacks for injection operations
+ * @returns Result indicating success/failure and attempt count
+ */
+export async function injectWithRetry(injection, shortId, from, callbacks) {
+    const metrics = callbacks.getMetrics();
+    metrics.total++;
+    // Skip verification mode: trust that write() succeeds without checking output
+    // Used for PTY-based injection where CLIs don't echo input back
+    if (callbacks.skipVerification) {
+        try {
+            await callbacks.performInjection(injection);
+            metrics.successFirstTry++;
+            return { success: true, attempts: 1 };
+        }
+        catch (err) {
+            callbacks.logError(`Injection error: ${err?.message || err}`);
+            metrics.failed++;
+            return { success: false, attempts: 1 };
+        }
+    }
+    for (let attempt = 0; attempt < INJECTION_CONSTANTS.MAX_RETRIES; attempt++) {
+        try {
+            // On retry attempts, first check if message already exists (race condition fix)
+            // Previous injection may have succeeded but verification timed out
+            if (attempt > 0) {
+                const alreadyExists = await verifyInjection(shortId, from, callbacks.getOutput);
+                if (alreadyExists) {
+                    metrics.successWithRetry++;
+                    callbacks.log(`Message already present (late verification), skipping re-injection`);
+                    return { success: true, attempts: attempt + 1 };
+                }
+            }
+            // Perform the injection
+            await callbacks.performInjection(injection);
+            // Verify it appeared in output
+            const verified = await verifyInjection(shortId, from, callbacks.getOutput);
+            if (verified) {
+                if (attempt === 0) {
+                    metrics.successFirstTry++;
+                }
+                else {
+                    metrics.successWithRetry++;
+                    callbacks.log(`Injection succeeded on attempt ${attempt + 1}`);
+                }
+                return { success: true, attempts: attempt + 1 };
+            }
+            // Not verified - log and retry
+            callbacks.log(`Injection not verified, attempt ${attempt + 1}/${INJECTION_CONSTANTS.MAX_RETRIES}`);
+            // Backoff before retry
+            if (attempt < INJECTION_CONSTANTS.MAX_RETRIES - 1) {
+                await sleep(INJECTION_CONSTANTS.RETRY_BACKOFF_MS * (attempt + 1));
+            }
+        }
+        catch (err) {
+            callbacks.logError(`Injection error on attempt ${attempt + 1}: ${err?.message || err}`);
+        }
+    }
+    // All retries failed
+    metrics.failed++;
+    return { success: false, attempts: INJECTION_CONSTANTS.MAX_RETRIES };
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

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

package/dist/stuck-detector.d.ts

@@ -0,0 +1,161 @@
+/**
+ * StuckDetector - Detect when an agent is stuck
+ *
+ * Implements agent-relay-501: Stuck detection heuristics
+ *
+ * Detects five stuck conditions:
+ * 1. Extended idle (no output for 10+ minutes)
+ * 2. Error loop (same error message repeated 3+ times)
+ * 3. Output loop (same output pattern repeated 3+ times)
+ * 4. Tool loop (same file operated on 10+ times in 5 minutes)
+ * 5. Output flood (abnormally high output rate suggesting infinite loop)
+ *
+ * NOTE: Message intent detection (agent says "I'll send" but doesn't) was removed
+ * because pattern-based NLP detection is unreliable. A protocol-level approach
+ * (detecting stale outbox files) should be implemented in relay-pty instead.
+ *
+ * Emits 'stuck' event when detected, with reason and details.
+ */
+import { EventEmitter } from 'node:events';
+export type StuckReason = 'extended_idle' | 'error_loop' | 'output_loop' | 'tool_loop' | 'output_flood';
+/**
+ * Tracked tool invocation for loop detection
+ */
+interface ToolInvocation {
+    tool: string;
+    target: string;
+    timestamp: number;
+}
+export interface StuckEvent {
+    reason: StuckReason;
+    details: string;
+    timestamp: number;
+    /** Time since last output in ms (for extended_idle) */
+    idleDurationMs?: number;
+    /** Repeated content (for loops) */
+    repeatedContent?: string;
+    /** Number of repetitions (for loops) */
+    repetitions?: number;
+    /** Target file/command (for tool_loop) */
+    targetFile?: string;
+    /** Tool name (for tool_loop) */
+    toolName?: string;
+    /** Output rate in lines per minute (for output_flood) */
+    linesPerMinute?: number;
+}
+export interface StuckDetectorConfig {
+    /** Duration of inactivity before considered stuck (ms, default: 10 minutes) */
+    extendedIdleMs?: number;
+    /** Number of repeated outputs before considered stuck (default: 3) */
+    loopThreshold?: number;
+    /** Check interval (ms, default: 30 seconds) */
+    checkIntervalMs?: number;
+    /** Minimum output length to consider for loop detection */
+    minLoopLength?: number;
+    /** Error patterns to detect (regexes) */
+    errorPatterns?: RegExp[];
+    /** Threshold for same file operations before considered stuck (default: 10) */
+    toolLoopThreshold?: number;
+    /** Time window for tool loop detection (ms, default: 5 minutes) */
+    toolLoopWindowMs?: number;
+    /** Output lines per minute threshold for flood detection (default: 5000) */
+    outputFloodLinesPerMinute?: number;
+    /** Minimum duration before flood detection activates (ms, default: 2 minutes) */
+    outputFloodMinDurationMs?: number;
+}
+export declare class StuckDetector extends EventEmitter {
+    private config;
+    private lastOutputTime;
+    private recentOutputs;
+    private checkInterval;
+    private isStuck;
+    private stuckReason;
+    private toolInvocations;
+    private outputLineCount;
+    private outputStartTime;
+    constructor(config?: StuckDetectorConfig);
+    /**
+     * Start monitoring for stuck conditions.
+     * Call this after the agent process starts.
+     */
+    start(): void;
+    /**
+     * Stop monitoring.
+     */
+    stop(): void;
+    /**
+     * Feed output to the detector.
+     * Call this for every output chunk from the agent.
+     */
+    onOutput(chunk: string): void;
+    /**
+     * Extract tool invocations from output and track them.
+     */
+    private extractToolInvocations;
+    /**
+     * Normalize output for comparison (strip ANSI, trim, lowercase).
+     */
+    private normalizeOutput;
+    /**
+     * Check for stuck conditions.
+     */
+    private checkStuck;
+    /**
+     * Detect repeated error messages.
+     */
+    private detectErrorLoop;
+    /**
+     * Detect repeated output patterns (not necessarily errors).
+     */
+    private detectOutputLoop;
+    /**
+     * Detect when the same file is being operated on repeatedly.
+     * This catches cases like an agent repeatedly reading/writing the same file
+     * in a loop, even if the output content differs each time.
+     */
+    private detectToolLoop;
+    /**
+     * Detect abnormally high output rates that suggest an infinite loop.
+     * Only triggers after minimum duration to avoid false positives during
+     * normal high-output operations (like builds or tests).
+     */
+    private detectOutputFlood;
+    /**
+     * Emit stuck event.
+     */
+    private emitStuck;
+    /**
+     * Check if currently detected as stuck.
+     */
+    getIsStuck(): boolean;
+    /**
+     * Get the reason for being stuck (if stuck).
+     */
+    getStuckReason(): StuckReason | null;
+    /**
+     * Get time since last output in milliseconds.
+     */
+    getIdleDuration(): number;
+    /**
+     * Reset state.
+     */
+    reset(): void;
+    /**
+     * Get current output statistics (useful for debugging).
+     */
+    getOutputStats(): {
+        lineCount: number;
+        durationMs: number;
+        linesPerMinute: number;
+    };
+    /**
+     * Get recent tool invocations (useful for debugging).
+     */
+    getToolInvocations(): ToolInvocation[];
+}
+/**
+ * Create a stuck detector with default configuration.
+ */
+export declare function createStuckDetector(config?: StuckDetectorConfig): StuckDetector;
+export {};
+//# sourceMappingURL=stuck-detector.d.ts.map

package/dist/stuck-detector.d.ts.map

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