@agent-relay/wrapper 0.1.0

package/dist/tmux-wrapper.d.ts

@@ -0,0 +1,345 @@
+/**
+ * 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.
+     */
+    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.
+     */
+    private waitForStablePane;
+    /**
+     * Stop and cleanup
+     */
+    stop(): void;
+}
+//# sourceMappingURL=tmux-wrapper.d.ts.map

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

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