agent-relay 1.6.0 → 2.0.4

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

@@ -0,0 +1,352 @@
+/**
+ * TmuxWrapper - Attach-based tmux wrapper
+ *
+ * Architecture:
+ * 1. Start agent in detached tmux session
+ * 2. Attach user to tmux (they see real terminal)
+ * 3. Background: poll capture-pane silently (no stdout writes)
+ * 4. Background: parse ->relay commands, send to daemon
+ * 5. Background: inject messages via send-keys
+ *
+ * The key insight: user sees the REAL tmux session, not a proxy.
+ * We just do background parsing and injection.
+ */
+import { BaseWrapper, type BaseWrapperConfig } from './base-wrapper.js';
+import { type ParsedCommand, type ParsedSummary } from './parser.js';
+import type { SendPayload, SendMeta } from '@agent-relay/protocol/types';
+import { type CliType } from './shared.js';
+export interface TmuxWrapperConfig extends BaseWrapperConfig {
+    cols?: number;
+    rows?: number;
+    /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
+    program?: string;
+    /** Optional model identifier (e.g., 'claude-3-opus') */
+    model?: string;
+    /** Use file-based inbox in addition to injection */
+    useInbox?: boolean;
+    /** Custom inbox directory */
+    inboxDir?: string;
+    /** Polling interval for capture-pane (ms) */
+    pollInterval?: number;
+    /** Enable debug logging to stderr */
+    debug?: boolean;
+    /** Throttle debug logs (ms) */
+    debugLogIntervalMs?: number;
+    /** Idle time after last output before injecting (ms) */
+    idleBeforeInjectMs?: number;
+    /** Retry interval while waiting for idle window (ms) */
+    injectRetryMs?: number;
+    /** How long with no output before marking session idle (ms) */
+    activityIdleThresholdMs?: number;
+    /** Max time to wait for clear input before injecting (ms) */
+    inputWaitTimeoutMs?: number;
+    /** Polling interval when waiting for clear input (ms) */
+    inputWaitPollMs?: number;
+    /** Enable tmux mouse mode for scroll passthrough (default: true) */
+    mouseMode?: boolean;
+    /** Max time to wait for stable pane output before injection (ms) */
+    outputStabilityTimeoutMs?: number;
+    /** Poll interval when checking pane stability before injection (ms) */
+    outputStabilityPollMs?: 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: CliType): string;
+export declare class TmuxWrapper extends BaseWrapper {
+    protected config: TmuxWrapperConfig;
+    private sessionName;
+    private parser;
+    private inbox?;
+    private storage?;
+    private storageReady;
+    private pollTimer?;
+    private attachProcess?;
+    private lastCapturedOutput;
+    private lastOutputTime;
+    private lastActivityTime;
+    private activityState;
+    private recentlySentMessages;
+    private processedOutputLength;
+    private lastLoggedLength;
+    private lastDebugLog;
+    private lastSummaryHash;
+    private pendingRelayCommands;
+    private queuedMessageHashes;
+    private readonly MAX_PENDING_RELAY_COMMANDS;
+    private receivedMessageIdSet;
+    private receivedMessageIdOrder;
+    private readonly MAX_RECEIVED_MESSAGES;
+    private tmuxPath;
+    private trajectory?;
+    private lastDetectedPhase?;
+    private seenToolCalls;
+    private seenErrors;
+    private authRevoked;
+    private lastAuthCheck;
+    private readonly AUTH_CHECK_INTERVAL;
+    private throttle;
+    constructor(config: TmuxWrapperConfig);
+    /**
+     * Inject content into the tmux session via paste
+     */
+    protected performInjection(content: string): Promise<void>;
+    /**
+     * Get cleaned output for parsing (strip ANSI codes)
+     */
+    protected getCleanOutput(): string;
+    /**
+     * 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
+     */
+    private buildCommand;
+    /**
+     * Check if tmux session exists
+     */
+    private sessionExists;
+    /**
+     * Start the wrapped agent process
+     */
+    start(): Promise<void>;
+    /**
+     * Initialize trajectory tracking
+     * Auto-starts a trajectory if task is provided in config
+     */
+    private initializeTrajectory;
+    /**
+     * 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
+     */
+    private injectInstructions;
+    /**
+     * Inject continuity context from previous session
+     */
+    private injectContinuityContext;
+    /**
+     * Wait for tmux session to be ready
+     */
+    private waitForSession;
+    /**
+     * Wait for shell prompt to appear (shell is ready for input)
+     */
+    private waitForShellReady;
+    /**
+     * Attach user to tmux session
+     * This spawns tmux attach and lets it take over stdin/stdout
+     */
+    private attachToSession;
+    /**
+     * Start silent polling for ->relay commands
+     * Does NOT write to stdout - just parses and sends to daemon
+     */
+    private startSilentPolling;
+    /**
+     * Poll for ->relay commands in output (silent)
+     */
+    private pollForRelayCommands;
+    /**
+     * Record recent activity and transition back to active if needed.
+     */
+    private markActivity;
+    /**
+     * Update activity state based on idle threshold and trigger injections when idle.
+     */
+    private updateActivityState;
+    /**
+     * Check if the CLI output indicates auth has been revoked.
+     * This can happen when the user authenticates elsewhere (limited sessions).
+     */
+    private checkAuthRevocation;
+    /**
+     * Reset auth revocation state (called after successful re-authentication)
+     */
+    resetAuthState(): void;
+    /**
+     * Check if auth has been revoked
+     */
+    isAuthRevoked(): boolean;
+    /**
+     * Send relay command to daemon (overrides BaseWrapper for offline queue support)
+     */
+    protected sendRelayCommand(cmd: ParsedCommand): void;
+    /**
+     * Flush any queued relay commands when the client reconnects.
+     */
+    private flushQueuedRelayCommands;
+    /**
+     * Parse [[SUMMARY]] blocks from output and save to storage.
+     * Agents can output summaries to maintain running context:
+     *
+     * [[SUMMARY]]
+     * {"currentTask": "Implementing auth", "context": "Completed login flow"}
+     * [[/SUMMARY]]
+     */
+    private parseSummaryAndSave;
+    /**
+     * Save a parsed summary to the continuity ledger (uses logStderr for tmux).
+     * Maps summary fields to ledger fields for session recovery.
+     */
+    protected saveSummaryToLedger(summary: ParsedSummary): Promise<void>;
+    /**
+     * 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
+     */
+    protected parseContinuityCommands(content: string): Promise<void>;
+    /**
+     * Parse [[SESSION_END]] blocks from output and close session explicitly.
+     * Agents output this to mark their work session as complete:
+     *
+     * [[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.
+     * After spawning, waits for the agent to come online and sends the task via relay.
+     */
+    protected executeSpawn(name: string, cli: string, task: string): Promise<void>;
+    /**
+     * Wait for a spawned agent to come online, then send the task via relay.
+     * Uses the wrapper's own relay client so the message comes "from" this agent,
+     * not from the dashboard's relay client.
+     */
+    private waitAndSendTask;
+    /**
+     * Execute release via API (if dashboardPort set) or callback
+     */
+    protected executeRelease(name: string): Promise<void>;
+    /**
+     * Parse ->relay:spawn and ->relay:release commands from output.
+     * 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
+     */
+    protected parseSpawnReleaseCommands(content: string): void;
+    /**
+     * Handle incoming message from relay
+     * @param originalTo - The original 'to' field from sender. '*' indicates this was a broadcast message.
+     *                     Agents should reply to originalTo to maintain channel routing (e.g., respond to #general, not DM).
+     */
+    protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
+    /**
+     * Handle incoming channel message from relay.
+     * Channel messages include a channel indicator so the agent knows to reply to the channel.
+     */
+    protected handleIncomingChannelMessage(from: string, channel: string, body: string, envelope: import('@agent-relay/protocol/types').Envelope<import('@agent-relay/protocol/channels').ChannelMessagePayload>): void;
+    /**
+     * Check if we should inject a message.
+     * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.
+     * Processes messages by priority (urgent first).
+     */
+    private checkForInjectionOpportunity;
+    /**
+     * Inject message via tmux send-keys.
+     * Uses shared injection logic with tmux-specific callbacks.
+     */
+    private injectNextMessage;
+    private hasSeenIncoming;
+    /**
+     * Send special keys to tmux
+     */
+    private sendKeys;
+    /**
+     * Send literal text to tmux
+     */
+    private sendKeysLiteral;
+    /**
+     * Paste text using tmux buffer with optional bracketed paste to avoid interleaving with ongoing output.
+     * Some CLIs (like droid) don't handle bracketed paste sequences properly, so we skip -p for them.
+     */
+    private pasteLiteral;
+    /**
+     * Reset session-specific state for wrapper reuse.
+     * Call this when starting a new session with the same wrapper instance.
+     */
+    resetSessionState(): void;
+    /**
+     * Get the prompt pattern for the current CLI type.
+     */
+    private getPromptPattern;
+    /**
+     * Capture the last non-empty line from the tmux pane.
+     */
+    private getLastLine;
+    /**
+     * Detect if the provided line contains visible user input (beyond the prompt).
+     */
+    private hasVisibleInput;
+    /**
+     * Check if the input line is clear (no user-typed text after the prompt).
+     * Returns true if the last visible line appears to be just a prompt.
+     */
+    private isInputClear;
+    /**
+     * Get cursor X position to detect input length.
+     * Returns the cursor column (0-indexed).
+     */
+    private getCursorX;
+    /**
+     * Wait for the input line to be clear before injecting.
+     * Polls until the input appears empty or timeout is reached.
+     *
+     * @param maxWaitMs Maximum time to wait (default 5000ms)
+     * @param pollIntervalMs How often to check (default 200ms)
+     * @returns true if input became clear, false if timed out
+     */
+    private waitForClearInput;
+    /**
+     * Capture a signature of the current pane content for stability checks.
+     * Uses hash+length to cheaply detect changes without storing full content.
+     */
+    private capturePaneSignature;
+    /**
+     * Wait for pane output to stabilize before injecting to avoid interleaving with ongoing output.
+     * Uses adaptive timeout based on idle detector confidence for faster injection when safe.
+     *
+     * @param maxWaitMs - Maximum time to wait (default from config)
+     * @param pollIntervalMs - Polling interval (default from config)
+     * @param requiredStablePolls - Consecutive stable polls needed (default 2)
+     * @param priority - Message priority (lower = more urgent, can use shorter timeout)
+     */
+    private waitForStablePane;
+    /**
+     * Stop and cleanup
+     */
+    stop(): void;
+}
+//# sourceMappingURL=tmux-wrapper.d.ts.map