@litmers/cursorflow-orchestrator 0.1.40 → 0.2.2

package/dist/core/lane-state-machine.d.ts

@@ -0,0 +1,423 @@
+/**
+ * Lane State Machine
+ *
+ * Lane의 생명주기를 세분화된 상태로 관리하는 상태 머신입니다.
+ *
+ * 핵심 원칙:
+ * 1. 명시적 상태 전이 (Explicit State Transitions)
+ * 2. 단일 상태 저장소 (Single Source of Truth)
+ * 3. 상태 전이 검증 (Transition Validation)
+ * 4. 복구/재시도 로직 중앙화 (Centralized Recovery)
+ *
+ * 상태 계층:
+ * - 주 상태 (Primary State): Lane의 기본 상태 (pending, running, completed 등)
+ * - 부 상태 (Sub State): 세부 작업 상태 (preparing_git, executing_task 등)
+ * - 복구 상태 (Recovery State): 복구 진행 상태 (idle, monitoring, recovering 등)
+ */
+/**
+ * Lane 주 상태 (Primary State)
+ *
+ * 상태 전이 규칙:
+ * - PENDING → INITIALIZING → RUNNING → COMPLETED | FAILED
+ * - RUNNING ↔ WAITING (의존성 대기)
+ * - RUNNING ↔ PAUSED (사용자 요청)
+ * - RUNNING → RECOVERING → RUNNING | FAILED
+ * - * → ABORTED (강제 중단)
+ */
+export declare enum LanePrimaryState {
+    /** 대기 중 - 아직 시작되지 않음 */
+    PENDING = "pending",
+    /** 초기화 중 - 워크트리/브랜치 준비 */
+    INITIALIZING = "initializing",
+    /** 실행 중 */
+    RUNNING = "running",
+    /** 의존성 대기 중 */
+    WAITING = "waiting",
+    /** 일시 중지 */
+    PAUSED = "paused",
+    /** 복구 중 */
+    RECOVERING = "recovering",
+    /** 완료 */
+    COMPLETED = "completed",
+    /** 실패 */
+    FAILED = "failed",
+    /** 강제 중단 */
+    ABORTED = "aborted"
+}
+/**
+ * Lane 부 상태 (Sub State) - RUNNING 상태의 세부 단계
+ */
+export declare enum LaneSubState {
+    /** 없음 (비실행 상태) */
+    NONE = "none",
+    /** Git 워크트리 준비 */
+    PREPARING_GIT = "preparing_git",
+    /** 의존성 브랜치 머지 */
+    MERGING_DEPENDENCIES = "merging_dependencies",
+    /** Task 브랜치 생성 */
+    CREATING_TASK_BRANCH = "creating_task_branch",
+    /** 변경사항 커밋 */
+    COMMITTING = "committing",
+    /** 푸시 */
+    PUSHING = "pushing",
+    /** 머지 */
+    MERGING = "merging",
+    /** Task 실행 준비 */
+    PREPARING_TASK = "preparing_task",
+    /** AI 에이전트와 통신 중 */
+    EXECUTING_AGENT = "executing_agent",
+    /** Task 실행 완료 처리 */
+    FINALIZING_TASK = "finalizing_task",
+    /** 의존성 완료 대기 */
+    WAITING_DEPENDENCY = "waiting_dependency",
+    /** 사용자 입력 대기 */
+    WAITING_USER_INPUT = "waiting_user_input",
+    /** Rate limit 대기 */
+    WAITING_RATE_LIMIT = "waiting_rate_limit"
+}
+/**
+ * 복구 상태 (Recovery State)
+ */
+export declare enum RecoveryState {
+    /** 복구 필요 없음 */
+    IDLE = "idle",
+    /** 모니터링 중 (Stall 감지) */
+    MONITORING = "monitoring",
+    /** Continue 신호 발송됨 */
+    CONTINUE_SENT = "continue_sent",
+    /** Stronger prompt 발송됨 */
+    STRONGER_PROMPT_SENT = "stronger_prompt_sent",
+    /** 재시작 요청됨 */
+    RESTART_REQUESTED = "restart_requested",
+    /** 진단 실행됨 */
+    DIAGNOSED = "diagnosed",
+    /** 복구 포기 */
+    EXHAUSTED = "exhausted"
+}
+/**
+ * 상태 전이를 발생시키는 트리거
+ */
+export declare enum StateTransitionTrigger {
+    /** Lane 시작 */
+    START = "start",
+    /** 초기화 완료 */
+    INITIALIZED = "initialized",
+    /** Task 완료 */
+    TASK_COMPLETED = "task_completed",
+    /** 모든 Task 완료 */
+    ALL_TASKS_COMPLETED = "all_tasks_completed",
+    /** 실패 발생 */
+    FAILURE = "failure",
+    /** 강제 중단 요청 */
+    ABORT = "abort",
+    /** 의존성 대기 시작 */
+    WAIT_DEPENDENCY = "wait_dependency",
+    /** 의존성 해결됨 */
+    DEPENDENCY_RESOLVED = "dependency_resolved",
+    /** 의존성 타임아웃 */
+    DEPENDENCY_TIMEOUT = "dependency_timeout",
+    /** 의존성 실패 */
+    DEPENDENCY_FAILED = "dependency_failed",
+    /** 일시 중지 요청 */
+    PAUSE = "pause",
+    /** 재개 요청 */
+    RESUME = "resume",
+    /** 복구 시작 */
+    RECOVERY_START = "recovery_start",
+    /** 복구 성공 */
+    RECOVERY_SUCCESS = "recovery_success",
+    /** 복구 실패 */
+    RECOVERY_FAILED = "recovery_failed",
+    /** Stall 감지 */
+    STALL_DETECTED = "stall_detected",
+    /** Continue 신호 발송 */
+    CONTINUE_SIGNAL_SENT = "continue_signal_sent",
+    /** Stronger prompt 발송 */
+    STRONGER_PROMPT_SENT = "stronger_prompt_sent",
+    /** 재시작 요청 */
+    RESTART_REQUESTED = "restart_requested",
+    /** 진단 완료 */
+    DIAGNOSIS_COMPLETE = "diagnosis_complete",
+    /** Git 작업 시작 */
+    GIT_START = "git_start",
+    /** Git 작업 완료 */
+    GIT_COMPLETE = "git_complete",
+    /** Task 실행 시작 */
+    TASK_START = "task_start",
+    /** Agent 통신 시작 */
+    AGENT_START = "agent_start",
+    /** Agent 응답 수신 */
+    AGENT_RESPONSE = "agent_response"
+}
+/**
+ * Lane 상태 컨텍스트 (전체 상태 정보)
+ */
+export interface LaneStateContext {
+    /** Lane 이름 */
+    laneName: string;
+    /** Run ID */
+    runId: string;
+    /** 주 상태 */
+    primaryState: LanePrimaryState;
+    /** 부 상태 */
+    subState: LaneSubState;
+    /** 복구 상태 */
+    recoveryState: RecoveryState;
+    /** 현재 Task 인덱스 */
+    currentTaskIndex: number;
+    /** 전체 Task 수 */
+    totalTasks: number;
+    /** 완료된 Task 목록 */
+    completedTasks: string[];
+    /** 현재 Task 이름 */
+    currentTaskName?: string;
+    /** 대기 중인 의존성 */
+    waitingFor?: string[];
+    /** 마지막 오류 */
+    lastError?: string;
+    /** 재시작 횟수 */
+    restartCount: number;
+    /** 시작 시간 */
+    startTime: number;
+    /** 종료 시간 */
+    endTime?: number;
+    /** 마지막 상태 변경 시간 */
+    lastTransitionTime: number;
+    /** 워크트리 디렉토리 */
+    worktreeDir?: string;
+    /** 파이프라인 브랜치 */
+    pipelineBranch?: string;
+    /** 현재 Task 브랜치 */
+    taskBranch?: string;
+    /** 프로세스 ID */
+    pid?: number;
+    /** 채팅 세션 ID */
+    chatId?: string;
+    /** 추가 메타데이터 */
+    metadata?: Record<string, any>;
+}
+/**
+ * 상태 전이 결과
+ */
+export interface StateTransitionResult {
+    /** 성공 여부 */
+    success: boolean;
+    /** 이전 상태 */
+    fromState: LanePrimaryState;
+    /** 새 상태 */
+    toState: LanePrimaryState;
+    /** 트리거 */
+    trigger: StateTransitionTrigger;
+    /** 오류 메시지 (실패 시) */
+    error?: string;
+}
+/**
+ * Lane 상태 머신
+ *
+ * 사용 예:
+ * ```typescript
+ * const sm = LaneStateMachine.getInstance();
+ *
+ * // Lane 등록
+ * sm.registerLane('lane-1', 'run-123', {
+ *   totalTasks: 5,
+ *   pipelineBranch: 'cursorflow/pipeline/lane-1'
+ * });
+ *
+ * // 상태 전이
+ * sm.transition('lane-1', StateTransitionTrigger.START);
+ * sm.transition('lane-1', StateTransitionTrigger.INITIALIZED);
+ *
+ * // 부 상태 업데이트
+ * sm.setSubState('lane-1', LaneSubState.EXECUTING_AGENT);
+ *
+ * // 상태 조회
+ * const ctx = sm.getContext('lane-1');
+ * console.log(ctx.primaryState, ctx.subState);
+ * ```
+ */
+export declare class LaneStateMachine {
+    private static instance;
+    /** Lane별 상태 컨텍스트 */
+    private contexts;
+    /** 상태 히스토리 (디버깅/감사용) */
+    private history;
+    /** 상태 변경 콜백 */
+    private onTransitionCallbacks;
+    /** 디버그 모드 */
+    private verbose;
+    private constructor();
+    /**
+     * 싱글톤 인스턴스 획득
+     */
+    static getInstance(): LaneStateMachine;
+    /**
+     * 인스턴스 리셋 (테스트용)
+     */
+    static resetInstance(): void;
+    /**
+     * Lane 등록
+     */
+    registerLane(laneName: string, runId: string, options?: {
+        totalTasks?: number;
+        pipelineBranch?: string;
+        worktreeDir?: string;
+        metadata?: Record<string, any>;
+    }): LaneStateContext;
+    /**
+     * Lane 해제
+     */
+    unregisterLane(laneName: string): void;
+    /**
+     * Lane 컨텍스트 조회
+     */
+    getContext(laneName: string): LaneStateContext | undefined;
+    /**
+     * 모든 Lane 컨텍스트 조회
+     */
+    getAllContexts(): Map<string, LaneStateContext>;
+    /**
+     * 상태 전이 실행
+     */
+    transition(laneName: string, trigger: StateTransitionTrigger, options?: {
+        error?: string;
+        force?: boolean;
+    }): StateTransitionResult;
+    /**
+     * 전이 규칙 찾기
+     */
+    private findTransitionRule;
+    /**
+     * 종료 상태인지 확인
+     */
+    private isTerminalState;
+    /**
+     * 부 상태 리셋 필요 여부
+     */
+    private shouldResetSubState;
+    /**
+     * 부 상태 설정
+     */
+    setSubState(laneName: string, subState: LaneSubState): boolean;
+    /**
+     * 부 상태 조회
+     */
+    getSubState(laneName: string): LaneSubState;
+    /**
+     * 복구 상태 설정
+     */
+    setRecoveryState(laneName: string, recoveryState: RecoveryState): boolean;
+    /**
+     * 복구 상태 조회
+     */
+    getRecoveryState(laneName: string): RecoveryState;
+    /**
+     * 재시작 횟수 증가
+     */
+    incrementRestartCount(laneName: string): number;
+    /**
+     * Task 진행 상황 업데이트
+     */
+    updateTaskProgress(laneName: string, taskIndex: number, taskName?: string, taskBranch?: string): boolean;
+    /**
+     * Task 완료 기록
+     */
+    recordTaskCompletion(laneName: string, taskName: string): boolean;
+    /**
+     * 대기 중인 의존성 설정
+     */
+    setWaitingFor(laneName: string, dependencies: string[]): boolean;
+    /**
+     * 오류 설정
+     */
+    setError(laneName: string, error: string): boolean;
+    /**
+     * 프로세스 ID 설정
+     */
+    setPid(laneName: string, pid: number): boolean;
+    /**
+     * 채팅 세션 ID 설정
+     */
+    setChatId(laneName: string, chatId: string): boolean;
+    /**
+     * 메타데이터 업데이트
+     */
+    updateMetadata(laneName: string, metadata: Record<string, any>): boolean;
+    /**
+     * 상태를 파일로 저장
+     */
+    persistState(laneName: string, stateDir: string): boolean;
+    /**
+     * 파일에서 상태 복구
+     */
+    restoreState(laneName: string, runId: string, stateDir: string): LaneStateContext | null;
+    /**
+     * 컨텍스트를 기존 LaneState 형식으로 변환
+     */
+    private contextToLaneState;
+    /**
+     * 기존 LaneState에서 컨텍스트로 변환
+     */
+    private laneStateToContext;
+    /**
+     * 상태 전이 콜백 등록
+     */
+    onTransition(callback: (laneName: string, result: StateTransitionResult) => void): () => void;
+    /**
+     * 전이 콜백 실행
+     */
+    private notifyTransition;
+    /**
+     * 전이 이벤트 발행
+     */
+    private emitTransition;
+    /**
+     * 전이 실패 이벤트 발행
+     */
+    private emitTransitionFailed;
+    /**
+     * 특정 상태의 Lane들 조회
+     */
+    getLanesInState(state: LanePrimaryState): string[];
+    /**
+     * 활성 상태 Lane들 조회 (종료되지 않은)
+     */
+    getActiveLanes(): string[];
+    /**
+     * 전이 히스토리 조회
+     */
+    getHistory(laneName: string): Array<{
+        timestamp: number;
+        fromState: LanePrimaryState;
+        toState: LanePrimaryState;
+        trigger: StateTransitionTrigger;
+    }>;
+    /**
+     * 전체 상태 요약 조회
+     */
+    getSummary(): Record<LanePrimaryState, number>;
+    /**
+     * 로깅
+     */
+    private log;
+    /**
+     * 디버그 모드 설정
+     */
+    setVerbose(verbose: boolean): void;
+    /**
+     * 디버그 덤프
+     */
+    dumpState(laneName: string): string;
+}
+/**
+ * 싱글톤 인스턴스 획득
+ */
+export declare function getStateMachine(): LaneStateMachine;
+/**
+ * 인스턴스 리셋 (테스트용)
+ */
+export declare function resetStateMachine(): void;
+/**
+ * LanePrimaryState를 기존 LaneStatus로 변환 (호환성)
+ */
+export declare function primaryStateToLaneStatus(state: LanePrimaryState): string;