agent-relay 1.6.0 → 2.0.4

package/packages/wrapper/dist/shared.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Shared types and utilities for TmuxWrapper and PtyWrapper
+ *
+ * This module contains common code to prevent drift between the two
+ * wrapper implementations and reduce duplication.
+ */
+import type { SyncMeta } from '@agent-relay/protocol/types';
+/**
+ * Message priority levels for queue ordering.
+ * Lower numbers = higher priority (processed first).
+ */
+export declare const MESSAGE_PRIORITY: {
+    /** System-critical messages (sync ACKs, errors) - skip idle wait */
+    readonly URGENT: 0;
+    /** Time-sensitive messages (user requests) - reduced idle wait */
+    readonly HIGH: 1;
+    /** Normal agent-to-agent messages */
+    readonly NORMAL: 2;
+    /** Batch/background messages - can wait longer */
+    readonly LOW: 3;
+};
+export type MessagePriority = typeof MESSAGE_PRIORITY[keyof typeof MESSAGE_PRIORITY];
+/**
+ * Get priority from importance value or default to NORMAL.
+ * Maps importance number to priority level.
+ */
+export declare function getPriorityFromImportance(importance?: number): MessagePriority;
+/**
+ * Sort messages by priority (lower number = higher priority).
+ * Stable sort - maintains order within same priority.
+ */
+export declare function sortByPriority(messages: QueuedMessage[]): QueuedMessage[];
+/**
+ * Message queued for injection into an agent's terminal
+ */
+export interface QueuedMessage {
+    from: string;
+    body: string;
+    messageId: string;
+    thread?: string;
+    importance?: number;
+    data?: Record<string, unknown>;
+    sync?: SyncMeta;
+    /** Original 'to' field - '*' indicates broadcast */
+    originalTo?: string;
+}
+/**
+ * Result of an injection attempt with retry
+ */
+export interface InjectionResult {
+    success: boolean;
+    attempts: number;
+    fallbackUsed?: boolean;
+}
+/**
+ * Metrics tracking injection reliability
+ */
+export interface InjectionMetrics {
+    total: number;
+    successFirstTry: number;
+    successWithRetry: number;
+    failed: number;
+}
+/**
+ * CLI types for special handling
+ */
+export type CliType = 'claude' | 'codex' | 'gemini' | 'droid' | 'opencode' | 'cursor' | 'spawned' | 'other';
+/**
+ * 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 declare const INJECTION_CONSTANTS: {
+    /** Maximum retry attempts for injection */
+    readonly MAX_RETRIES: 3;
+    /** Timeout for output stability check (ms) */
+    readonly STABILITY_TIMEOUT_MS: 3000;
+    /** Polling interval for stability check (ms) - reduced from 200ms */
+    readonly STABILITY_POLL_MS: 100;
+    /** Required consecutive stable polls before injection */
+    readonly REQUIRED_STABLE_POLLS: 2;
+    /** Timeout for injection verification (ms) */
+    readonly VERIFICATION_TIMEOUT_MS: 2000;
+    /** Delay between message and Enter key (ms) - reduced from 100ms */
+    readonly ENTER_DELAY_MS: 50;
+    /** Backoff multiplier for retries (ms per attempt) - reduced from 300ms */
+    readonly RETRY_BACKOFF_MS: 200;
+    /** Base delay between processing queued messages (ms) - reduced from 500ms */
+    readonly QUEUE_PROCESS_DELAY_MS: 100;
+    /** Maximum delay when under backpressure (ms) */
+    readonly QUEUE_PROCESS_DELAY_MAX_MS: 500;
+    /** Threshold for increasing delay (consecutive failures) */
+    readonly 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 declare class AdaptiveThrottle {
+    private consecutiveFailures;
+    private currentDelay;
+    /** Get current delay in milliseconds */
+    getDelay(): number;
+    /** Record a successful injection - decrease delay */
+    recordSuccess(): void;
+    /** Record a failed injection - increase delay if threshold exceeded */
+    recordFailure(): void;
+    /** Reset to default state */
+    reset(): void;
+}
+/**
+ * Strip ANSI escape codes from a string.
+ * Converts cursor movements to spaces to preserve visual layout.
+ */
+export declare function stripAnsi(str: string): string;
+/**
+ * Sleep for a given number of milliseconds
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * 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 declare function buildInjectionString(msg: QueuedMessage): string;
+/**
+ * Calculate injection success rate from metrics
+ */
+export declare function calculateSuccessRate(metrics: InjectionMetrics): number;
+/**
+ * Create a fresh injection metrics object
+ */
+export declare function createInjectionMetrics(): InjectionMetrics;
+/**
+ * Detect CLI type from command string
+ */
+export declare function detectCliType(command: string): CliType;
+/**
+ * Get the default relay prefix (unified for all agent types)
+ */
+export declare function getDefaultRelayPrefix(): string;
+/**
+ * CLI-specific quirks and handling
+ */
+export declare const CLI_QUIRKS: {
+    /**
+     * CLIs that support bracketed paste mode.
+     * Others may interpret the escape sequences literally.
+     */
+    readonly supportsBracketedPaste: (cli: CliType) => boolean;
+    /**
+     * Gemini interprets certain keywords (While, For, If, etc.) as shell commands.
+     * Wrap message in backticks to prevent shell keyword interpretation.
+     */
+    readonly wrapForGemini: (body: string) => string;
+    /**
+     * Get prompt pattern regex for a CLI type.
+     * Used to detect when input line is clear.
+     */
+    readonly getPromptPattern: (cli: CliType) => RegExp;
+    /**
+     * 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.
+     */
+    readonly isShellPrompt: (line: string) => boolean;
+};
+/**
+ * Callbacks for wrapper-specific injection operations.
+ * These allow the shared injection logic to work with both
+ * TmuxWrapper (tmux paste) and PtyWrapper (PTY write).
+ */
+export interface InjectionCallbacks {
+    /** Get current output content for verification */
+    getOutput: () => Promise<string>;
+    /** Perform the actual injection (write to terminal) */
+    performInjection: (injection: string) => Promise<void>;
+    /** Log a message (debug/info level) */
+    log: (message: string) => void;
+    /** Log an error message */
+    logError: (message: string) => void;
+    /** Get the injection metrics object to update */
+    getMetrics: () => InjectionMetrics;
+    /**
+     * Skip verification and trust that write succeeded.
+     * Set to true for PTY-based injection where CLIs don't echo input.
+     * When true, injection succeeds on first attempt without verification.
+     */
+    skipVerification?: boolean;
+}
+/**
+ * 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 declare function verifyInjection(shortId: string, from: string, getOutput: () => Promise<string>): Promise<boolean>;
+/**
+ * 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 declare function injectWithRetry(injection: string, shortId: string, from: string, callbacks: InjectionCallbacks): Promise<InjectionResult>;
+//# sourceMappingURL=shared.d.ts.map

package/packages/wrapper/dist/shared.js

@@ -0,0 +1,381 @@
+/**
+ * Shared types and utilities for TmuxWrapper and PtyWrapper
+ *
+ * This module contains common code to prevent drift between the two
+ * wrapper implementations and reduce duplication.
+ */
+/**
+ * Message priority levels for queue ordering.
+ * Lower numbers = higher priority (processed first).
+ */
+export const MESSAGE_PRIORITY = {
+    /** System-critical messages (sync ACKs, errors) - skip idle wait */
+    URGENT: 0,
+    /** Time-sensitive messages (user requests) - reduced idle wait */
+    HIGH: 1,
+    /** Normal agent-to-agent messages */
+    NORMAL: 2,
+    /** Batch/background messages - can wait longer */
+    LOW: 3,
+};
+/**
+ * Get priority from importance value or default to NORMAL.
+ * Maps importance number to priority level.
+ */
+export function getPriorityFromImportance(importance) {
+    if (importance === undefined)
+        return MESSAGE_PRIORITY.NORMAL;
+    if (importance >= 90)
+        return MESSAGE_PRIORITY.URGENT;
+    if (importance >= 70)
+        return MESSAGE_PRIORITY.HIGH;
+    if (importance >= 30)
+        return MESSAGE_PRIORITY.NORMAL;
+    return MESSAGE_PRIORITY.LOW;
+}
+/**
+ * Sort messages by priority (lower number = higher priority).
+ * Stable sort - maintains order within same priority.
+ */
+export function sortByPriority(messages) {
+    return [...messages].sort((a, b) => {
+        const priorityA = getPriorityFromImportance(a.importance);
+        const priorityB = getPriorityFromImportance(b.importance);
+        return priorityA - priorityB;
+    });
+}
+/**
+ * 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