crewly 1.0.0

package/dist/backend/backend/src/services/session/session-command-helper.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Session Command Helper
+ *
+ * Provides high-level terminal command operations using the ISessionBackend abstraction.
+ * This helper bridges the gap between low-level PTY operations and the higher-level
+ * commands that services like AgentRegistrationService need.
+ *
+ * Key mappings from TmuxCommandService:
+ * - sendMessage → write(message + '\r')
+ * - sendKey → write(keyCode)
+ * - sendCtrlC → write('\x03')
+ * - sendEnter → write('\r')
+ * - clearCurrentCommandLine → write('\x03\x15') (Ctrl+C then Ctrl+U)
+ * - capturePane → captureOutput()
+ *
+ * @module session-command-helper
+ */
+import type { ISession, ISessionBackend } from './session-backend.interface.js';
+/**
+ * Key code mappings for special keys
+ */
+export declare const KEY_CODES: Record<string, string>;
+/**
+ * Session Command Helper class
+ *
+ * Provides a unified interface for terminal commands that works with both
+ * PTY and tmux backends through the ISessionBackend abstraction.
+ */
+export declare class SessionCommandHelper {
+    private logger;
+    private backend;
+    constructor(backend: ISessionBackend);
+    /**
+     * Get a session by name, throwing an error if it doesn't exist.
+     *
+     * @param sessionName - The name of the session to retrieve
+     * @returns The session instance
+     * @throws Error if the session does not exist
+     */
+    private getSessionOrThrow;
+    /**
+     * Check if a session exists
+     */
+    sessionExists(sessionName: string): boolean;
+    /**
+     * Get a session by name
+     */
+    getSession(sessionName: string): ISession | undefined;
+    /**
+     * Send a message to a session with Enter key.
+     * For multi-line messages, sends the text first then Enter separately
+     * to avoid bracketed paste mode issues where Enter is treated as part of the paste.
+     *
+     * @param sessionName - The session to send to
+     * @param message - The message to send
+     * @throws Error if session does not exist
+     */
+    sendMessage(sessionName: string, message: string): Promise<void>;
+    /**
+     * Send a key to a session
+     *
+     * @param sessionName - The session to send to
+     * @param key - The key name (e.g., 'Enter', 'C-c', 'Escape')
+     * @throws Error if session does not exist or key is unknown
+     */
+    sendKey(sessionName: string, key: string): Promise<void>;
+    /**
+     * Send Ctrl+C to a session
+     */
+    sendCtrlC(sessionName: string): Promise<void>;
+    /**
+     * Send Enter key to a session
+     */
+    sendEnter(sessionName: string): Promise<void>;
+    /**
+     * Send Escape key to a session
+     */
+    sendEscape(sessionName: string): Promise<void>;
+    /**
+     * Clear the current command line in a session
+     * Sends Ctrl+C followed by Ctrl+U to cancel any input and clear the line
+     */
+    clearCurrentCommandLine(sessionName: string): Promise<void>;
+    /**
+     * Capture terminal output from a session.
+     *
+     * Strips trailing empty lines that result from empty terminal rows below
+     * the actual content. Large terminals (e.g., maximized browser windows)
+     * can have 50+ empty rows below the prompt, which would cause prompt
+     * detection to fail if the capture window is too small.
+     *
+     * @param sessionName - The session to capture from
+     * @param lines - Number of lines to capture (default: 200)
+     * @returns The captured terminal content with trailing empty lines removed
+     */
+    capturePane(sessionName: string, lines?: number): string;
+    /**
+     * Get raw output history with ANSI escape codes preserved.
+     *
+     * @param sessionName - The session to get history from
+     * @returns Raw output history with ANSI codes
+     */
+    getRawHistory(sessionName: string): string;
+    /**
+     * List all active sessions
+     */
+    listSessions(): string[];
+    /**
+     * Kill a session
+     */
+    killSession(sessionName: string): Promise<void>;
+    /**
+     * Create a new session
+     *
+     * @param sessionName - Unique name for the session
+     * @param cwd - Working directory for the session
+     * @param options - Additional session options
+     * @returns The created session
+     */
+    createSession(sessionName: string, cwd: string, options?: {
+        command?: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cols?: number;
+        rows?: number;
+    }): Promise<ISession>;
+    /**
+     * Set an environment variable in a session by executing export command
+     * Note: This only affects new commands run in the session
+     */
+    setEnvironmentVariable(sessionName: string, key: string, value: string): Promise<void>;
+    /**
+     * Resize a session's terminal
+     */
+    resizeSession(sessionName: string, cols: number, rows: number): void;
+    /**
+     * Get the underlying backend
+     */
+    getBackend(): ISessionBackend;
+    /**
+     * Subscribe to session output events.
+     *
+     * This method provides direct access to the terminal output stream,
+     * enabling event-driven processing instead of polling.
+     *
+     * @param sessionName - The session to subscribe to
+     * @param callback - Function called on each data event
+     * @returns Unsubscribe function to stop receiving events
+     * @throws Error if session does not exist
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = helper.subscribeToOutput('my-session', (data) => {
+     *   console.log('Received:', data);
+     * });
+     * // Later: unsubscribe();
+     * ```
+     */
+    subscribeToOutput(sessionName: string, callback: (data: string) => void): () => void;
+    /**
+     * Subscribe to session exit events.
+     *
+     * @param sessionName - The session to subscribe to
+     * @param callback - Function called when session exits with exit code
+     * @returns Unsubscribe function to stop receiving events
+     * @throws Error if session does not exist
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = helper.subscribeToExit('my-session', (code) => {
+     *   console.log('Session exited with code:', code);
+     * });
+     * ```
+     */
+    subscribeToExit(sessionName: string, callback: (code: number) => void): () => void;
+    /**
+     * Wait for a pattern to appear in session output.
+     *
+     * Subscribes to the output stream and resolves when the pattern is found.
+     * Useful for waiting for specific prompts or indicators.
+     *
+     * @param sessionName - The session to monitor
+     * @param pattern - RegExp or string to match against output
+     * @param timeoutMs - Maximum time to wait (default: 30 seconds)
+     * @returns Promise resolving to the accumulated buffer when pattern matches
+     * @throws Error if timeout or session does not exist
+     *
+     * @example
+     * ```typescript
+     * // Wait for Claude prompt
+     * const output = await helper.waitForPattern('agent-1', />\s*$/, 10000);
+     * console.log('Claude is ready:', output);
+     * ```
+     */
+    waitForPattern(sessionName: string, pattern: RegExp | string, timeoutMs?: number): Promise<string>;
+    /**
+     * Wait for any of multiple patterns to appear in session output.
+     *
+     * Useful when multiple outcomes are possible (e.g., success or error).
+     *
+     * @param sessionName - The session to monitor
+     * @param patterns - Array of patterns with identifiers
+     * @param timeoutMs - Maximum time to wait
+     * @returns Promise resolving to which pattern matched and the buffer
+     *
+     * @example
+     * ```typescript
+     * const result = await helper.waitForAnyPattern('agent-1', [
+     *   { id: 'prompt', pattern: />\s*$/ },
+     *   { id: 'error', pattern: /error:/i },
+     * ], 10000);
+     *
+     * if (result.matchedId === 'error') {
+     *   console.log('Error occurred:', result.buffer);
+     * }
+     * ```
+     */
+    waitForAnyPattern(sessionName: string, patterns: Array<{
+        id: string;
+        pattern: RegExp | string;
+    }>, timeoutMs?: number): Promise<{
+        matchedId: string;
+        buffer: string;
+    }>;
+    /**
+     * Send message and wait for delivery confirmation via events.
+     *
+     * This is the core event-driven message delivery method. It:
+     * 1. Sends the message to the terminal
+     * 2. Subscribes to output to detect confirmation patterns
+     * 3. Resolves when confirmation is detected or timeout occurs
+     *
+     * @param sessionName - The session to send to
+     * @param message - The message to send
+     * @param confirmationPattern - Pattern indicating successful delivery
+     * @param timeoutMs - Maximum time to wait for confirmation
+     * @returns Promise resolving to true if confirmed, false if timeout
+     *
+     * @example
+     * ```typescript
+     * // Send message and wait for processing indicator
+     * const confirmed = await helper.sendMessageWithConfirmation(
+     *   'agent-1',
+     *   'Hello Claude',
+     *   /⠋|⠙|⠹|Thinking/,
+     *   5000
+     * );
+     * ```
+     */
+    sendMessageWithConfirmation(sessionName: string, message: string, confirmationPattern: RegExp | string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Smart message sending with event-driven paste detection.
+     *
+     * This method intelligently handles bracketed paste mode by:
+     * 1. Sending the message text
+     * 2. Waiting for "[Pasted text" indicator (paste received)
+     * 3. Sending Enter key only after paste is confirmed
+     * 4. Optionally waiting for processing indicators
+     *
+     * This is much more reliable than fixed delays because it detects
+     * the actual terminal state rather than guessing timing.
+     *
+     * @param sessionName - The session to send to
+     * @param message - The message to send
+     * @param options - Configuration options
+     * @returns Promise with delivery result
+     *
+     * @example
+     * ```typescript
+     * const result = await helper.sendMessageSmart('agent-1', 'Hello', {
+     *   waitForProcessing: true,
+     *   pasteTimeout: 3000,
+     * });
+     * if (result.pasteDetected && result.processingStarted) {
+     *   console.log('Message delivered and being processed');
+     * }
+     * ```
+     */
+    sendMessageSmart(sessionName: string, message: string, options?: {
+        /** Timeout for detecting paste confirmation (ms) */
+        pasteTimeout?: number;
+        /** Timeout for detecting processing start (ms) */
+        processingTimeout?: number;
+        /** Whether to wait for processing indicators after sending */
+        waitForProcessing?: boolean;
+        /** Custom pattern for paste detection (default: /\[Pasted text/) */
+        pastePattern?: RegExp;
+        /** Custom pattern for processing detection (default: spinner/thinking) */
+        processingPattern?: RegExp;
+        /** Fallback delay if paste not detected (ms) - sends Enter anyway */
+        fallbackDelay?: number;
+    }): Promise<{
+        pasteDetected: boolean;
+        enterSent: boolean;
+        processingStarted: boolean;
+        usedFallback: boolean;
+    }>;
+    /**
+     * Send message with retry logic using smart detection.
+     *
+     * Attempts to deliver a message with intelligent retry behavior:
+     * - Uses event-driven paste detection
+     * - Retries with Enter key if message appears stuck
+     * - Detects common failure modes (prompt still visible, no response)
+     *
+     * @param sessionName - The session to send to
+     * @param message - The message to send
+     * @param maxRetries - Maximum number of retry attempts
+     * @returns Promise resolving to true if message was successfully processed
+     */
+    sendMessageWithSmartRetry(sessionName: string, message: string, maxRetries?: number): Promise<boolean>;
+    /**
+     * Write raw data to session without Enter key.
+     *
+     * Useful for sending partial input or special key sequences.
+     *
+     * @param sessionName - The session to write to
+     * @param data - Data to write
+     * @throws Error if session does not exist
+     */
+    writeRaw(sessionName: string, data: string): void;
+}
+/**
+ * Create a SessionCommandHelper instance
+ */
+export declare function createSessionCommandHelper(backend: ISessionBackend): SessionCommandHelper;
+//# sourceMappingURL=session-command-helper.d.ts.map

package/dist/backend/backend/src/services/session/session-command-helper.d.ts.map

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