crewly 1.0.0

package/dist/backend/backend/src/services/agent/agent-registration.service.d.ts

@@ -0,0 +1,398 @@
+import { StorageService } from '../core/storage.service.js';
+import { CREWLY_CONSTANTS, RuntimeType } from '../../constants.js';
+export interface OrchestratorConfig {
+    sessionName: string;
+    projectPath: string;
+    windowName?: string;
+}
+/**
+ * Service responsible for the complex, multi-step process of agent initialization and registration.
+ * Isolates the complex state management of agent startup with progressive escalation.
+ *
+ * Key capabilities:
+ * - Agent session creation and management
+ * - Runtime initialization and registration
+ * - Reliable message delivery to Claude Code with retry logic
+ * - Health checking and status management
+ */
+export declare class AgentRegistrationService {
+    private logger;
+    private _sessionHelper;
+    private storageService;
+    private projectRoot;
+    private promptCache;
+    private registrationAbortControllers;
+    private stuckMessageDetectorTimer;
+    private tuiSessionRegistry;
+    private sentMessageTracker;
+    private static get CLAUDE_PROMPT_INDICATORS();
+    private static get CLAUDE_PROMPT_STREAM_PATTERN();
+    private static get CLAUDE_PROCESSING_INDICATORS();
+    constructor(_legacyTmuxService: unknown, // Legacy parameter for backwards compatibility
+    projectRoot: string | null, storageService: StorageService);
+    /**
+     * Cancel a pending registration prompt for a session.
+     * Called by RuntimeExitMonitorService when a runtime exit is detected.
+     *
+     * @param sessionName - The session whose registration to cancel
+     */
+    cancelPendingRegistration(sessionName: string): void;
+    /**
+     * Get or create the session helper with lazy initialization
+     */
+    private getSessionHelper;
+    /**
+     * Get session helper synchronously (may throw if not initialized)
+     */
+    private getSessionHelperSync;
+    /**
+     * Find the project root by looking for package.json
+     */
+    private findProjectRoot;
+    /**
+     * Resolve runtime flags from the agent's effective skills.
+     * Reads role config and skill configs to collect flags compatible with the runtime.
+     *
+     * @param role - The agent's role name
+     * @param runtimeType - The agent's runtime type (e.g. 'claude-code')
+     * @param skillOverrides - Additional skills assigned to the member
+     * @param excludedRoleSkills - Skills excluded from the role's default set
+     * @returns Array of CLI flags to inject (e.g. ['--chrome'])
+     */
+    private resolveRuntimeFlags;
+    /**
+     * Create a runtime service instance for the given runtime type.
+     * Centralizes RuntimeServiceFactory creation to reduce code duplication.
+     */
+    private createRuntimeService;
+    /**
+     * Get the check interval based on environment.
+     * Uses shorter intervals in test environment for faster tests.
+     */
+    private getCheckInterval;
+    /**
+     * Update agent status with safe error handling (non-blocking).
+     * Returns true if successful, false if failed.
+     */
+    private updateAgentStatusSafe;
+    /**
+     * Get prompt file path for a specific role
+     * Uses the unified config/roles/{role}/prompt.md structure
+     */
+    private getPromptFileForRole;
+    /**
+     * Initialize agent with optimized 2-step escalation process
+     * Reduced from 4-step to 2-step with shorter timeouts for better concurrency
+     */
+    initializeAgentWithRegistration(sessionName: string, role: string, projectPath?: string, timeout?: number, memberId?: string, runtimeType?: RuntimeType, runtimeFlags?: string[]): Promise<{
+        success: boolean;
+        message?: string;
+        error?: string;
+    }>;
+    /**
+     * Step 1: Try direct registration prompt
+     * Assumes Claude is already running and just needs a registration prompt
+     */
+    private tryDirectRegistration;
+    /**
+     * Step 2: Cleanup with Ctrl+C and reinitialize
+     * Tries to reset the runtime session and start fresh
+     */
+    private tryCleanupAndReinit;
+    /**
+     * Detect and store the Claude Code session ID by scanning the filesystem.
+     * Claude Code stores conversations as <UUID>.jsonl files in
+     * ~/.claude/projects/<path-slug>/ where path-slug is the absolute
+     * project path with / replaced by -.
+     *
+     * Runs in background after agent init to capture the session ID
+     * for resume-on-restart support.
+     *
+     * @param sessionName - PTY session name
+     * @param projectPath - Absolute path to the agent's project directory
+     */
+    private detectAndStoreSessionId;
+    /**
+     * Send registration prompt asynchronously (non-blocking).
+     * Uses an AbortController so the operation can be cancelled if the
+     * runtime exits before registration completes.
+     */
+    private sendRegistrationPromptAsync;
+    /**
+     * Step 3: Kill session and recreate completely
+     * Most aggressive approach - completely recreates the session from scratch
+     */
+    private tryFullRecreation;
+    /**
+     * Load registration prompt from config files (with caching to prevent file I/O contention)
+     */
+    private loadRegistrationPrompt;
+    /**
+     * Wait for agent registration to complete
+     */
+    private waitForRegistration;
+    /**
+     * Check if agent is properly registered
+     */
+    private checkAgentRegistration;
+    /**
+     * Fast registration with verification and retry mechanism
+     * Sends system prompt to runtime which triggers MCP registration via teams.json
+     * @param skipInitialCleanup If true, skips Ctrl+C on first attempt (when runtime was just initialized)
+     */
+    private attemptRegistrationWithVerification;
+    /**
+     * Fast registration polling with shorter intervals
+     */
+    private waitForRegistrationFast;
+    /**
+     * Create orchestrator session - extracted from the original tmux service
+     */
+    private createOrchestratorSession;
+    /**
+     * Unified session creation that handles both orchestrator and team members
+     * @param config Session configuration
+     * @returns Promise with success/error information
+     */
+    createAgentSession(config: {
+        sessionName: string;
+        role: string;
+        projectPath?: string;
+        windowName?: string;
+        memberId?: string;
+        runtimeType?: RuntimeType;
+        teamId?: string;
+    }): Promise<{
+        success: boolean;
+        sessionName?: string;
+        message?: string;
+        error?: string;
+    }>;
+    /**
+     * Unified session termination that handles both orchestrator and team members
+     * @param sessionName The session to terminate
+     * @param role The role for proper status updates
+     * @returns Promise with success/error information
+     */
+    terminateAgentSession(sessionName: string, role?: string): Promise<{
+        success: boolean;
+        message?: string;
+        error?: string;
+    }>;
+    /**
+     * Send a message to any agent session with reliable delivery.
+     * Uses robust delivery mechanism with retry logic to ensure messages
+     * are properly delivered to Claude Code's input.
+     *
+     * @param sessionName - The agent session name
+     * @param message - The message to send
+     * @returns Promise with success status and optional error message
+     *
+     * @example
+     * ```typescript
+     * const result = await agentRegistrationService.sendMessageToAgent(
+     *   'crewly-orc',
+     *   '[CHAT:123] Hello, orchestrator!'
+     * );
+     * if (result.success) {
+     *   console.log('Message delivered');
+     * } else {
+     *   console.error('Delivery failed:', result.error);
+     * }
+     * ```
+     */
+    sendMessageToAgent(sessionName: string, message: string, runtimeType?: RuntimeType): Promise<{
+        success: boolean;
+        message?: string;
+        error?: string;
+    }>;
+    /**
+     * Wait for an agent session to be at a ready prompt before sending messages.
+     *
+     * Subscribes to terminal output and polls capturePane to detect when the
+     * agent returns to an input prompt. This is critical for sequential message
+     * processing: after the orchestrator responds to a message it may continue
+     * working (managing agents, running commands) before returning to prompt.
+     *
+     * @param sessionName - The session name to wait on
+     * @param timeoutMs - Maximum time to wait (default 120s)
+     * @returns true if agent is ready, false if timed out
+     */
+    waitForAgentReady(sessionName: string, timeoutMs?: number, runtimeType?: RuntimeType): Promise<boolean>;
+    /**
+     * @deprecated Replaced by SessionCommandHelper.sendMessage() in sendMessageWithRetry.
+     * Complex event-driven state machine was fragile — Enter key often got lost.
+     * Kept as dead code for reference during transition.
+     */
+    private _deprecated_sendMessageEventDriven;
+    /**
+     * Send message with retry logic for reliable delivery to Claude Code.
+     * Uses SessionCommandHelper.sendMessage() (proven two-step write pattern)
+     * with stuck-message detection and retry on failure.
+     *
+     * @param sessionName - The session name
+     * @param message - The message to send
+     * @param maxAttempts - Maximum number of delivery attempts
+     * @returns true if message was delivered successfully
+     */
+    private sendMessageWithRetry;
+    /**
+     * Check if a sent message is stuck at the terminal prompt (Enter was not accepted).
+     *
+     * Captures the current terminal pane and looks for the message text still visible
+     * on the last few lines. If the text is found, Enter was not processed and the
+     * message is stuck.
+     *
+     * @param sessionName - The session to check
+     * @param message - The original message that was sent
+     * @returns true if the message text is still visible at the prompt (stuck)
+     */
+    private isMessageStuckAtPrompt;
+    /**
+     * Check if message text is stuck at the TUI prompt line (Enter was not pressed).
+     *
+     * Unlike `isMessageStuckAtPrompt` which checks the last 20 lines for the message
+     * text ANYWHERE, this method specifically checks whether the message text appears
+     * ON the prompt line itself (the line starting with `> ` or `│ > `).
+     *
+     * After Enter is successfully pressed, the text moves from the prompt line to the
+     * chat history area. So if the text is still on the prompt line, Enter was dropped.
+     *
+     * This avoids the false positive problem where `isMessageStuckAtPrompt` matches
+     * the message text in the TUI's chat history (which echoes submitted messages).
+     *
+     * @param sessionName - The session to check
+     * @param message - The original message that was sent
+     * @returns true if the message text is visible on the TUI prompt line (stuck)
+     */
+    private isTextStuckAtTuiPrompt;
+    /**
+     * Attempt to recover from text stuck at TUI prompt by pressing Enter.
+     * Checks if text is stuck, sends Enter, waits, then verifies.
+     *
+     * @param sessionName - The session to recover
+     * @param message - The original message
+     * @returns true if recovery succeeded (text is no longer at prompt)
+     */
+    private recoverStuckTuiMessage;
+    /**
+     * Start a background scanner that periodically checks all registered TUI
+     * sessions for text stuck at the prompt (Enter not pressed).
+     *
+     * This is a safety net that catches messages missed by the per-send
+     * verification in `sendMessageWithRetry`. It scans every 30 seconds.
+     *
+     * When stuck text is detected, the scanner presses Enter to recover.
+     * If text has been sitting at the prompt for multiple consecutive scans,
+     * it escalates to Tab + Enter (TUI focus recovery).
+     */
+    startStuckMessageDetector(): void;
+    /**
+     * Stop the background stuck-message detector.
+     */
+    stopStuckMessageDetector(): void;
+    /**
+     * Scan all sessions for stuck messages. Two complementary strategies:
+     *
+     * 1. TUI prompt-line scanning (existing): checks registered TUI sessions
+     *    for text sitting on the `> ` prompt line.
+     * 2. Tracked-message scanning (new, all runtimes): checks if any recently
+     *    sent message text is still visible at the bottom of the terminal
+     *    after 15+ seconds — runtime-agnostic Enter-drop detection.
+     */
+    private scanForStuckMessages;
+    /**
+     * Unregister a TUI session from the stuck-message detector.
+     * Call this when a session is destroyed or agent is stopped.
+     *
+     * @param sessionName - The session to unregister
+     */
+    unregisterTuiSession(sessionName: string): void;
+    /**
+     * Register a message that was sent to a session for background
+     * stuck-detection. The scanner will periodically check if the
+     * message text is still visible at the bottom of the terminal.
+     *
+     * @param sessionName - The session the message was sent to
+     * @param message - The full message text
+     */
+    trackSentMessage(sessionName: string, message: string): void;
+    /**
+     * Check if Claude Code appears to be at an input prompt.
+     * Looks for common prompt indicators in terminal output.
+     *
+     * @param terminalOutput - The terminal output to check
+     * @returns true if Claude Code appears to be at a prompt
+     */
+    private isClaudeAtPrompt;
+    /**
+     * Detect if Gemini CLI is currently in shell mode.
+     *
+     * In shell mode, Gemini CLI changes its prompt from `>` to `!`. Any input
+     * sent in this mode is executed as a shell command instead of being passed
+     * to the model. This method examines the last few lines of terminal output
+     * for shell mode prompt indicators.
+     *
+     * @param terminalOutput - Captured terminal pane content
+     * @returns true if the terminal shows a shell mode prompt
+     */
+    private isGeminiInShellMode;
+    /**
+     * Escape from Gemini CLI shell mode by sending Escape key.
+     *
+     * Sends Escape and waits for the prompt to change from `!` back to `>`.
+     * Retries up to MAX_ESCAPE_ATTEMPTS times.
+     *
+     * @param sessionName - The session running Gemini CLI
+     * @param sessionHelper - SessionCommandHelper instance
+     * @returns true if successfully escaped shell mode, false if still in shell mode
+     */
+    private escapeGeminiShellMode;
+    /**
+     * Generic key sending to any agent session
+     * @param sessionName The agent session name
+     * @param key The key to send (e.g., 'Enter', 'Ctrl+C')
+     * @returns Promise with success/error information
+     */
+    sendKeyToAgent(sessionName: string, key: string): Promise<{
+        success: boolean;
+        message?: string;
+        error?: string;
+    }>;
+    /**
+     * Generic health check for any agent session
+     * @param sessionName The agent session name
+     * @param role The agent role for additional context
+     * @param timeout Timeout for health check in milliseconds
+     * @returns Promise with health status information
+     */
+    checkAgentHealth(sessionName: string, role?: string, timeout?: number): Promise<{
+        success: boolean;
+        data?: {
+            agent: {
+                sessionName: string;
+                role?: string;
+                running: boolean;
+                status: (typeof CREWLY_CONSTANTS.AGENT_STATUSES)[keyof typeof CREWLY_CONSTANTS.AGENT_STATUSES];
+            };
+            timestamp: string;
+        };
+        error?: string;
+    }>;
+    /**
+     * Write the prompt to a file and send a short instruction to the agent to read it.
+     *
+     * Instead of pasting large multi-line prompts directly into the terminal (which
+     * causes bracketed paste issues, shell interpretation errors, and truncation),
+     * we write the prompt to ~/.crewly/prompts/{sessionName}-init.md and send a
+     * single-line instruction telling the agent to read that file.
+     *
+     * @param sessionName The session name
+     * @param prompt The full system prompt to deliver
+     * @param runtimeType The agent runtime type
+     * @param abortSignal Optional signal to cancel the operation (e.g. on runtime exit)
+     * @returns true if the instruction was delivered successfully
+     */
+    private sendPromptRobustly;
+}
+//# sourceMappingURL=agent-registration.service.d.ts.map

package/dist/backend/backend/src/services/agent/agent-registration.service.d.ts.map

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