agent-relay 1.1.0 → 1.2.3

package/dist/wrapper/shared.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 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>;
+    /** 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' | 'spawned' | 'other';
+/**
+ * Injection timing constants
+ */
+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) */
+    readonly STABILITY_POLL_MS: 200;
+    /** 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) */
+    readonly ENTER_DELAY_MS: 50;
+    /** Backoff multiplier for retries (ms per attempt) */
+    readonly RETRY_BACKOFF_MS: 300;
+    /** Delay between processing queued messages (ms) */
+    readonly QUEUE_PROCESS_DELAY_MS: 500;
+};
+/**
+ * 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}
+ */
+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/dist/wrapper/shared.js

@@ -0,0 +1,270 @@
+/**
+ * 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
+ */
+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) */
+    STABILITY_POLL_MS: 200,
+    /** 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) */
+    ENTER_DELAY_MS: 50,
+    /** Backoff multiplier for retries (ms per attempt) */
+    RETRY_BACKOFF_MS: 300,
+    /** Delay between processing queued messages (ms) */
+    QUEUE_PROCESS_DELAY_MS: 500,
+};
+/**
+ * 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}
+ */
+export function buildInjectionString(msg) {
+    const shortId = msg.messageId.substring(0, 8);
+    // Strip ANSI and normalize whitespace
+    const sanitizedBody = stripAnsi(msg.body).replace(/[\r\n]+/g, ' ').trim();
+    // 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 broadcasts
+    const channelHint = msg.originalTo === '*' ? ' [#general]' : '';
+    // 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 ${msg.from} [${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';
+    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';
+    },
+    /**
+     * 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*$/,
+            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/wrapper/tmux-wrapper.d.ts

@@ -11,6 +11,7 @@
  * The key insight: user sees the REAL tmux session, not a proxy.
  * We just do background parsing and injection.
  */
+import { type CliType } from './shared.js';
 export interface TmuxWrapperConfig {
     name: string;
     command: string;
@@ -47,7 +48,7 @@ export interface TmuxWrapperConfig {
     /** Polling interval when waiting for clear input (ms) */
     inputWaitPollMs?: number;
     /** CLI type for special handling (auto-detected from command if not set) */
-    cliType?: 'claude' | 'codex' | 'gemini' | 'droid' | 'other';
+    cliType?: 'claude' | 'codex' | 'gemini' | 'droid' | 'opencode' | 'other';
     /** Enable tmux mouse mode for scroll passthrough (default: true) */
     mouseMode?: boolean;
     /** Relay prefix pattern (default: '->relay:') */
@@ -62,12 +63,17 @@ export interface TmuxWrapperConfig {
     outputStabilityPollMs?: number;
     /** Stream output to daemon for dashboard log viewing (default: true) */
     streamLogs?: boolean;
+    /** Resume from a previous agent ID (for crash recovery) */
+    resumeAgentId?: string;
+    /** Dashboard port for API-based spawn/release (preferred over callbacks) */
+    dashboardPort?: number;
 }
 /**
  * Get the default relay prefix for a given CLI type.
  * All agents now use '->relay:' as the unified prefix.
+ * @deprecated Use getDefaultRelayPrefix() from shared.js instead
  */
-export declare function getDefaultPrefix(_cliType: 'claude' | 'codex' | 'gemini' | 'droid' | 'other'): string;
+export declare function getDefaultPrefix(_cliType: CliType): string;
 export declare class TmuxWrapper {
     private config;
     private sessionName;
@@ -95,20 +101,35 @@ export declare class TmuxWrapper {
     private lastSummaryHash;
     private lastSummaryRawContent;
     private sessionEndProcessed;
+    private sessionEndData?;
     private pendingRelayCommands;
     private queuedMessageHashes;
     private readonly MAX_PENDING_RELAY_COMMANDS;
     private processedSpawnCommands;
     private processedReleaseCommands;
+    private pendingFencedSpawn;
     private receivedMessageIdSet;
     private receivedMessageIdOrder;
     private readonly MAX_RECEIVED_MESSAGES;
     private tmuxPath;
+    private trajectory?;
+    private lastDetectedPhase?;
+    private seenToolCalls;
+    private seenErrors;
+    private continuity?;
+    private processedContinuityCommands;
+    private agentId?;
+    private injectionMetrics;
     constructor(config: TmuxWrapperConfig);
     /**
      * Log to stderr (safe - doesn't interfere with tmux display)
      */
     private logStderr;
+    /**
+     * Detect PDERO phase from output content and auto-transition if needed.
+     * Also detects tool calls and errors, recording them to the trajectory.
+     */
+    private detectAndTransitionPhase;
     /**
      * Build the full command with proper quoting
      * Args containing spaces need to be quoted
@@ -123,9 +144,26 @@ export declare class TmuxWrapper {
      */
     start(): Promise<void>;
     /**
-     * Inject usage instructions for the agent
+     * Initialize trajectory tracking
+     * Auto-starts a trajectory if task is provided in config
+     */
+    private initializeTrajectory;
+    /**
+     * Initialize agent ID for continuity/resume functionality
+     */
+    private initializeAgentId;
+    /**
+     * Get the current agent ID
+     */
+    getAgentId(): string | undefined;
+    /**
+     * Inject usage instructions for the agent including persistence protocol
      */
     private injectInstructions;
+    /**
+     * Inject continuity context from previous session
+     */
+    private injectContinuityContext;
     /**
      * Wait for tmux session to be ready
      */
@@ -148,10 +186,6 @@ export declare class TmuxWrapper {
      * Poll for ->relay commands in output (silent)
      */
     private pollForRelayCommands;
-    /**
-     * Strip ANSI escape codes
-     */
-    private stripAnsi;
     /**
      * Join continuation lines after ->relay commands.
      * Claude Code and other TUIs insert real newlines in output, causing
@@ -184,6 +218,21 @@ export declare class TmuxWrapper {
      * [[/SUMMARY]]
      */
     private parseSummaryAndSave;
+    /**
+     * Save a parsed summary to the continuity ledger.
+     * Maps summary fields to ledger fields for session recovery.
+     */
+    private saveSummaryToLedger;
+    /**
+     * Parse ->continuity: commands from output and handle them.
+     * Supported commands:
+     *   ->continuity:save <<<...>>>  - Save session state to ledger
+     *   ->continuity:load            - Request context injection
+     *   ->continuity:search "query"  - Search past handoffs
+     *   ->continuity:uncertain "..."  - Mark item as uncertain
+     *   ->continuity:handoff <<<...>>> - Create explicit handoff
+     */
+    private parseContinuityCommands;
     /**
      * Parse [[SESSION_END]] blocks from output and close session explicitly.
      * Agents output this to mark their work session as complete:
@@ -191,12 +240,25 @@ export declare class TmuxWrapper {
      * [[SESSION_END]]
      * {"summary": "Completed auth module", "completedTasks": ["login", "logout"]}
      * [[/SESSION_END]]
+     *
+     * Also stores the data for use in autoSave to populate handoff (fixes empty handoff issue).
      */
     private parseSessionEndAndClose;
+    /**
+     * Execute spawn via API (if dashboardPort set) or callback
+     */
+    private executeSpawn;
+    /**
+     * Execute release via API (if dashboardPort set) or callback
+     */
+    private executeRelease;
     /**
      * Parse ->relay:spawn and ->relay:release commands from output.
-     * Format:
-     *   ->relay:spawn WorkerName cli "task description"
+     * Supports two formats:
+     *   Single-line: ->relay:spawn WorkerName cli "task description"
+     *   Multi-line (fenced): ->relay:spawn WorkerName cli <<<
+     *                        task description here
+     *                        can span multiple lines>>>
      *   ->relay:release WorkerName
      */
     private parseSpawnReleaseCommands;
@@ -211,7 +273,8 @@ export declare class TmuxWrapper {
      */
     private checkForInjectionOpportunity;
     /**
-     * Inject message via tmux send-keys
+     * Inject message via tmux send-keys.
+     * Uses shared injection logic with tmux-specific callbacks.
      */
     private injectNextMessage;
     private hasSeenIncoming;
@@ -228,7 +291,6 @@ export declare class TmuxWrapper {
      * Some CLIs (like droid) don't handle bracketed paste sequences properly, so we skip -p for them.
      */
     private pasteLiteral;
-    private sleep;
     /**
      * Reset session-specific state for wrapper reuse.
      * Call this when starting a new session with the same wrapper instance.