@yuaone/core 0.1.0

package/dist/state-machine.d.ts

@@ -0,0 +1,289 @@
+/**
+ * @module state-machine
+ * @description LangGraph-style Agent State Machine — 에이전트 실행을 위한 유한 상태 기계.
+ *
+ * 에이전트 실행 흐름을 명시적 phase 전이로 관리한다.
+ * analyze → design → plan → implement/parallel → verify → fix/replan → done
+ *
+ * 각 phase는 독립적인 핸들러로 구현되며, 전이 조건은 핸들러 반환값으로 결정.
+ * EventEmitter를 통해 외부에서 phase 진입/퇴장, 전이, 완료 등을 구독할 수 있다.
+ */
+import { EventEmitter } from "node:events";
+import type { ExecutionPlan } from "./types.js";
+/** 에이전트 실행 단계 */
+export type AgentPhase = "idle" | "analyze" | "design" | "plan" | "implement" | "parallel" | "delegate" | "verify" | "fix" | "replan" | "done";
+/** 접근법 옵션 — design phase에서 LLM이 제안하는 구현 방안 */
+export interface ApproachOption {
+    /** 옵션 ID */
+    id: number;
+    /** 옵션 이름 */
+    name: string;
+    /** 설명 */
+    description: string;
+    /** 장점 */
+    pros: string[];
+    /** 단점 */
+    cons: string[];
+    /** 예상 복잡도 */
+    estimatedComplexity: "low" | "medium" | "high";
+    /** 추천 여부 */
+    recommended: boolean;
+}
+/** 단계 실행 결과 */
+export interface StepResult {
+    /** 실행된 단계 인덱스 */
+    stepIndex: number;
+    /** 실행된 phase */
+    phase: AgentPhase;
+    /** 성공 여부 */
+    success: boolean;
+    /** 실행 결과 출력 */
+    output: string;
+    /** 변경된 파일 목록 */
+    changedFiles: string[];
+    /** 사용된 토큰 수 */
+    tokensUsed: number;
+    /** 실행 시간 (ms) */
+    durationMs: number;
+}
+/** 단계 실행 에러 */
+export interface StepError {
+    /** 에러가 발생한 단계 인덱스 */
+    stepIndex: number;
+    /** 에러가 발생한 phase */
+    phase: AgentPhase;
+    /** 에러 메시지 */
+    error: string;
+    /** 복구 가능 여부 */
+    recoverable: boolean;
+    /** 자동 수정 제안 */
+    suggestedFix?: string;
+}
+/** 검증 결과 — verify phase에서 반환 */
+export interface VerifyResult {
+    /** 검증 판정 */
+    verdict: "pass" | "concern" | "fail";
+    /** 개별 검증 항목 */
+    checks: {
+        buildSuccess: boolean;
+        typesSafe: boolean;
+        testsPass: boolean;
+        noRegressions: boolean;
+        followsPatterns: boolean;
+        securityClean: boolean;
+    };
+    /** 발견된 문제 */
+    issues: string[];
+    /** 개선 제안 */
+    suggestions: string[];
+    /** 신뢰도 (0–1) */
+    confidence: number;
+}
+/** 에이전트 상태 — 전체 실행 컨텍스트를 담는 단일 객체 */
+export interface AgentState {
+    /** 현재 phase */
+    phase: AgentPhase;
+    /** 에이전트 목표 */
+    goal: string;
+    /** 실행 계획 */
+    plan: ExecutionPlan | null;
+    /** 현재 실행 중인 step 인덱스 */
+    currentStepIndex: number;
+    /** 제안된 접근법 목록 */
+    approaches: ApproachOption[];
+    /** 선택된 접근법 인덱스 */
+    selectedApproach: number;
+    /** 단계별 실행 결과 */
+    stepResults: StepResult[];
+    /** 발생한 에러 */
+    errors: StepError[];
+    /** 검증 결과 이력 */
+    reflections: VerifyResult[];
+    /** 현재 수정 시도 횟수 */
+    fixAttempts: number;
+    /** 최대 수정 시도 횟수 */
+    maxFixAttempts: number;
+    /** 작업 메모리 (phase 간 데이터 전달) */
+    workingMemory: Map<string, unknown>;
+    /** 누적 토큰 사용량 */
+    tokenUsage: {
+        input: number;
+        output: number;
+    };
+    /** 총 도구 호출 횟수 */
+    toolCalls: number;
+    /** 총 반복 횟수 */
+    iterationCount: number;
+    /** 실행 시작 시각 (epoch ms) */
+    startTime: number;
+    /** 중단 시그널 */
+    abortSignal?: AbortSignal;
+    /** 사용자 피드백 (delegate phase 등에서 수집) */
+    userFeedback: string[];
+}
+/** Phase 전이 결과 — 핸들러가 반환 */
+export interface PhaseTransition {
+    /** 다음 phase */
+    nextPhase: AgentPhase;
+    /** 상태 업데이트 (부분 적용) */
+    updates: Partial<AgentState>;
+    /** 전이 사유 */
+    reason: string;
+}
+/** Phase 핸들러 함수 타입 */
+export type PhaseHandler = (state: AgentState, context: StateMachineContext) => Promise<PhaseTransition>;
+/** 상태 기계 컨텍스트 — 외부 시스템 콜백 주입 */
+export interface StateMachineContext {
+    /** 코드베이스/요청 분석 */
+    analyzeFn: (goal: string, state: AgentState) => Promise<{
+        complexity: string;
+        context: string;
+    }>;
+    /** 접근법 설계 */
+    designFn: (goal: string, context: string) => Promise<ApproachOption[]>;
+    /** 실행 계획 수립 */
+    planFn: (goal: string, approach: ApproachOption) => Promise<ExecutionPlan>;
+    /** 단일 step 실행 */
+    executeFn: (plan: ExecutionPlan, stepIndex: number, state: AgentState) => Promise<StepResult>;
+    /** 결과 검증 */
+    verifyFn: (state: AgentState) => Promise<VerifyResult>;
+    /** 에러 수정 */
+    fixFn: (errors: StepError[], state: AgentState) => Promise<StepResult>;
+    /** 실패 후 재계획 */
+    replanFn: (state: AgentState) => Promise<ExecutionPlan>;
+    /** 사용자 위임 (질문/승인) */
+    delegateFn: (question: string) => Promise<string>;
+}
+/** 상태 기계 설정 */
+export interface StateMachineConfig {
+    /** 최대 수정 시도 횟수 (기본 3) */
+    maxFixAttempts: number;
+    /** 최대 재계획 횟수 (기본 2) */
+    maxReplanAttempts: number;
+    /** 단순 태스크 시 design phase 스킵 (기본 true) */
+    skipDesignForSimple: boolean;
+    /** 병렬 실행 활성화 (기본 true) */
+    enableParallel: boolean;
+    /** 각 step 후 검증 수행 (기본 false — 전체 완료 후에만) */
+    verifyAfterEachStep: boolean;
+}
+/** 상태 기계 이벤트 정의 */
+export interface StateMachineEvents {
+    "phase:enter": (phase: AgentPhase, state: AgentState) => void;
+    "phase:exit": (phase: AgentPhase, state: AgentState) => void;
+    transition: (from: AgentPhase, to: AgentPhase, reason: string) => void;
+    "step:complete": (result: StepResult) => void;
+    "step:error": (error: StepError) => void;
+    "verify:result": (result: VerifyResult) => void;
+    done: (state: AgentState) => void;
+    abort: (reason: string) => void;
+}
+/**
+ * LangGraph-style Agent State Machine.
+ *
+ * 에이전트 실행을 유한 상태 기계(FSM)로 모델링한다.
+ * 각 phase에 대응하는 핸들러가 상태를 변환하고 다음 phase를 결정한다.
+ * run()을 호출하면 idle → analyze → ... → done까지 자동 진행.
+ *
+ * @example
+ * ```typescript
+ * const sm = new AgentStateMachine(context, { maxFixAttempts: 5 });
+ * sm.on("transition", (from, to, reason) => console.log(`${from} → ${to}: ${reason}`));
+ * const finalState = await sm.run("모든 console.log를 제거해줘");
+ * ```
+ */
+export declare class AgentStateMachine extends EventEmitter {
+    private state;
+    private readonly context;
+    private readonly config;
+    private readonly handlers;
+    private replanCount;
+    constructor(context: StateMachineContext, config?: Partial<StateMachineConfig>);
+    /**
+     * 상태 기계를 실행한다.
+     * idle → analyze부터 시작하여 done에 도달할 때까지 phase를 자동 전이한다.
+     *
+     * @param goal - 에이전트 목표
+     * @param abortSignal - 외부 중단 시그널 (선택)
+     * @returns 최종 에이전트 상태
+     */
+    run(goal: string, abortSignal?: AbortSignal): Promise<AgentState>;
+    /**
+     * 현재 상태를 읽기 전용으로 반환한다.
+     */
+    getState(): Readonly<AgentState>;
+    /**
+     * 실행 중인 에이전트에 사용자 피드백을 주입한다.
+     * delegate phase에서 수집되거나, 외부에서 즉시 주입 가능.
+     *
+     * @param feedback - 사용자 피드백 문자열
+     */
+    injectFeedback(feedback: string): void;
+    /**
+     * 특정 phase로 강제 전이한다 (escape hatch).
+     * 디버깅이나 외부 제어에 사용.
+     *
+     * @param phase - 전이할 phase
+     * @param reason - 전이 사유
+     */
+    forceTransition(phase: AgentPhase, reason: string): void;
+    /**
+     * analyze phase — 코드베이스와 요청을 분석한다.
+     * 복잡도가 trivial이고 skipDesignForSimple이면 plan으로 직행.
+     */
+    private handleAnalyze;
+    /**
+     * design phase — 구현 접근법을 제안한다.
+     * 추천 접근법이 있으면 자동 선택 후 plan으로, 없으면 delegate로.
+     */
+    private handleDesign;
+    /**
+     * plan phase — 실행 계획을 수립한다.
+     * 독립적 태스크가 있고 enableParallel이면 parallel로, 아니면 implement로.
+     */
+    private handlePlan;
+    /**
+     * implement phase — step을 순차 실행한다.
+     * 각 step 후: 복구 불가 에러 → fix, 모든 step 완료 → verify.
+     */
+    private handleImplement;
+    /**
+     * parallel phase — 독립 태스크를 병렬 실행한다.
+     * DAG 실행 후 verify로 이동.
+     */
+    private handleParallel;
+    /**
+     * delegate phase — 사용자에게 질문/승인을 요청한다.
+     * 피드백에 따라 analyze 또는 plan으로 전이.
+     */
+    private handleDelegate;
+    /**
+     * verify phase — 실행 결과를 검증한다.
+     * pass → done, concern + fixAttempts < max → fix, fail → replan.
+     */
+    private handleVerify;
+    /**
+     * fix phase — 에러를 자동 수정한다.
+     * fixAttempts를 증가시키고 verify로 복귀.
+     */
+    private handleFix;
+    /**
+     * replan phase — 실패 후 재계획을 수립한다.
+     * maxReplanAttempts 초과 시 done으로 (경고 포함).
+     */
+    private handleReplan;
+    /**
+     * phase 전이를 수행한다.
+     * phase:exit → 상태 업데이트 → transition 이벤트 → phase:enter.
+     */
+    private transition;
+    /**
+     * 초기 상태를 생성한다.
+     */
+    private createInitialState;
+    /**
+     * 터미널 phase인지 확인한다.
+     */
+    private isTerminal;
+}
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/state-machine.d.ts.map

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