@yuaone/core 0.1.0

package/dist/interrupt-manager.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @module interrupt-manager
+ * @description 인터럽트 매니저 — 설계 문서 섹션 21.2 구현.
+ *
+ * CLI/Web/팀에서 에이전트에 전달되는 인터럽트를 처리한다.
+ *
+ * 인터럽트 유형:
+ * - soft: 현재 도구 실행 취소 + 피드백 주입 → 에이전트 루프 계속
+ * - hard: 모든 실행 즉시 중단 + 비상 체크포인트 + paused 상태
+ * - pause: 에이전트 루프 일시 정지 (상태 유지)
+ * - resume: 일시 정지된 에이전트 루프 재개
+ *
+ * EventEmitter를 확장하여 인터럽트 이벤트를 외부에 전파한다.
+ */
+import { EventEmitter } from "node:events";
+import type { InterruptSignal } from "./types.js";
+/** InterruptManager가 발행하는 이벤트 맵 */
+export interface InterruptManagerEvents {
+    /** soft interrupt 발생 */
+    "interrupt:soft": [signal: InterruptSignal];
+    /** hard interrupt 발생 — 전체 중단 */
+    "interrupt:hard": [signal: InterruptSignal];
+    /** 일시 정지 */
+    "interrupt:pause": [signal: InterruptSignal];
+    /** 재개 */
+    "interrupt:resume": [signal: InterruptSignal];
+    /** 피드백 주입 요청 (agent loop이 수신) */
+    "interrupt:feedback": [feedback: string];
+    /** 비상 체크포인트 요청 (reflection/persistence가 수신) */
+    "interrupt:emergency_checkpoint": [];
+    /** 세션 상태 변경 요청 */
+    "interrupt:status_change": [status: "paused" | "running"];
+}
+/**
+ * 인터럽트 매니저.
+ *
+ * 에이전트 실행 중 외부(CLI/Web/팀)에서 전달되는 인터럽트를 처리한다.
+ * AbortController를 관리하여 현재 실행 중인 도구를 취소할 수 있다.
+ *
+ * @example
+ * ```typescript
+ * const im = new InterruptManager();
+ *
+ * // 도구 실행 시 AbortController 등록
+ * const ac = new AbortController();
+ * im.registerToolAbort(ac);
+ * await shellExec(cmd, { signal: ac.signal });
+ *
+ * // soft interrupt: 현재 도구 취소 + 피드백 주입
+ * im.interrupt({ type: "soft", feedback: "다른 방향으로", source: "cli" });
+ *
+ * // hard interrupt: 전체 중단
+ * im.interrupt({ type: "hard", source: "web" });
+ * ```
+ */
+export declare class InterruptManager extends EventEmitter {
+    /** 현재 실행 중인 도구의 AbortController */
+    private currentToolAbort;
+    /** 에이전트 루프 일시 정지 여부 */
+    private paused;
+    /** 인터럽트 히스토리 (디버깅/감사용, 최근 50개) */
+    private readonly history;
+    private static readonly MAX_HISTORY;
+    /**
+     * 인터럽트를 처리한다.
+     *
+     * @param signal - 인터럽트 시그널 (type, feedback, source, userId)
+     */
+    interrupt(signal: InterruptSignal): void;
+    /**
+     * 현재 실행 중인 도구의 AbortController를 등록한다.
+     *
+     * 도구 실행 시작 시 호출하여, soft/hard interrupt 시
+     * 해당 도구를 취소할 수 있도록 한다.
+     *
+     * @param controller - 도구 실행에 사용되는 AbortController
+     */
+    registerToolAbort(controller: AbortController): void;
+    /**
+     * 현재 등록된 AbortController를 해제한다.
+     *
+     * 도구 실행 완료 후 호출하여, 다음 도구와 혼선을 방지한다.
+     */
+    clearToolAbort(): void;
+    /**
+     * 에이전트 루프가 일시 정지 상태인지 확인한다.
+     *
+     * 에이전트 루프는 매 iteration 시작 시 이 값을 확인하고,
+     * true이면 resume될 때까지 대기해야 한다.
+     */
+    isPaused(): boolean;
+    /**
+     * 인터럽트 히스토리를 반환한다 (디버깅/감사용).
+     *
+     * @returns 최근 인터럽트 기록 (최대 50개)
+     */
+    getHistory(): ReadonlyArray<{
+        signal: InterruptSignal;
+        timestamp: number;
+    }>;
+    /**
+     * 상태를 초기화한다.
+     *
+     * 새 세션 시작 시 호출하여 이전 상태를 정리한다.
+     */
+    reset(): void;
+    /**
+     * Soft interrupt 처리.
+     *
+     * 1. 현재 도구 실행 취소 (AbortController.abort())
+     * 2. 피드백이 있으면 에이전트 컨텍스트에 주입
+     * 3. 이벤트 발행 → 에이전트 루프는 계속 진행
+     */
+    private handleSoftInterrupt;
+    /**
+     * Hard interrupt 처리.
+     *
+     * 1. 모든 실행 즉시 중단 (도구 취소)
+     * 2. 비상 체크포인트 요청 발행
+     * 3. 세션 상태 → paused
+     * 4. 이벤트 발행
+     */
+    private handleHardInterrupt;
+    /**
+     * Pause 처리.
+     *
+     * 에이전트 루프를 일시 정지한다.
+     * 상태는 유지되며, 현재 진행 중인 도구 실행은 완료될 수 있다.
+     */
+    private handlePause;
+    /**
+     * Resume 처리.
+     *
+     * 일시 정지된 에이전트 루프를 재개한다.
+     */
+    private handleResume;
+    /**
+     * 인터럽트를 히스토리에 기록한다.
+     * 최대 MAX_HISTORY개까지 유지하며, 초과 시 오래된 것부터 제거.
+     */
+    private recordHistory;
+}
+//# sourceMappingURL=interrupt-manager.d.ts.map

package/dist/interrupt-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt-manager.d.ts","sourceRoot":"","sources":["../src/interrupt-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAA0C,MAAM,YAAY,CAAC;AAI1F,mCAAmC;AACnC,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,gBAAgB,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C,gCAAgC;IAChC,gBAAgB,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C,YAAY;IACZ,iBAAiB,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,SAAS;IACT,kBAAkB,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC9C,iCAAiC;IACjC,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACzC,+CAA+C;IAC/C,gCAAgC,EAAE,EAAE,CAAC;IACrC,kBAAkB;IAClB,yBAAyB,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;CAC3D;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,mCAAmC;IACnC,OAAO,CAAC,gBAAgB,CAAgC;IAExD,uBAAuB;IACvB,OAAO,CAAC,MAAM,CAAS;IAEvB,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6D;IACrF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAM;IAEzC;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAuBxC;;;;;;;OAOG;IACH,iBAAiB,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAIpD;;;;OAIG;IACH,cAAc,IAAI,IAAI;IAItB;;;;;OAKG;IACH,QAAQ,IAAI,OAAO;IAInB;;;;OAIG;IACH,UAAU,IAAI,aAAa,CAAC;QAAE,MAAM,EAAE,eAAe,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3E;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAQb;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB;;;OAGG;IACH,OAAO,CAAC,aAAa;CAMtB"}

package/dist/interrupt-manager.js

@@ -0,0 +1,196 @@
+/**
+ * @module interrupt-manager
+ * @description 인터럽트 매니저 — 설계 문서 섹션 21.2 구현.
+ *
+ * CLI/Web/팀에서 에이전트에 전달되는 인터럽트를 처리한다.
+ *
+ * 인터럽트 유형:
+ * - soft: 현재 도구 실행 취소 + 피드백 주입 → 에이전트 루프 계속
+ * - hard: 모든 실행 즉시 중단 + 비상 체크포인트 + paused 상태
+ * - pause: 에이전트 루프 일시 정지 (상태 유지)
+ * - resume: 일시 정지된 에이전트 루프 재개
+ *
+ * EventEmitter를 확장하여 인터럽트 이벤트를 외부에 전파한다.
+ */
+import { EventEmitter } from "node:events";
+// ─── InterruptManager ────────────────────────────────────────────
+/**
+ * 인터럽트 매니저.
+ *
+ * 에이전트 실행 중 외부(CLI/Web/팀)에서 전달되는 인터럽트를 처리한다.
+ * AbortController를 관리하여 현재 실행 중인 도구를 취소할 수 있다.
+ *
+ * @example
+ * ```typescript
+ * const im = new InterruptManager();
+ *
+ * // 도구 실행 시 AbortController 등록
+ * const ac = new AbortController();
+ * im.registerToolAbort(ac);
+ * await shellExec(cmd, { signal: ac.signal });
+ *
+ * // soft interrupt: 현재 도구 취소 + 피드백 주입
+ * im.interrupt({ type: "soft", feedback: "다른 방향으로", source: "cli" });
+ *
+ * // hard interrupt: 전체 중단
+ * im.interrupt({ type: "hard", source: "web" });
+ * ```
+ */
+export class InterruptManager extends EventEmitter {
+    /** 현재 실행 중인 도구의 AbortController */
+    currentToolAbort = null;
+    /** 에이전트 루프 일시 정지 여부 */
+    paused = false;
+    /** 인터럽트 히스토리 (디버깅/감사용, 최근 50개) */
+    history = [];
+    static MAX_HISTORY = 50;
+    /**
+     * 인터럽트를 처리한다.
+     *
+     * @param signal - 인터럽트 시그널 (type, feedback, source, userId)
+     */
+    interrupt(signal) {
+        // 히스토리 기록
+        this.recordHistory(signal);
+        switch (signal.type) {
+            case "soft":
+                this.handleSoftInterrupt(signal);
+                break;
+            case "hard":
+                this.handleHardInterrupt(signal);
+                break;
+            case "pause":
+                this.handlePause(signal);
+                break;
+            case "resume":
+                this.handleResume(signal);
+                break;
+        }
+    }
+    /**
+     * 현재 실행 중인 도구의 AbortController를 등록한다.
+     *
+     * 도구 실행 시작 시 호출하여, soft/hard interrupt 시
+     * 해당 도구를 취소할 수 있도록 한다.
+     *
+     * @param controller - 도구 실행에 사용되는 AbortController
+     */
+    registerToolAbort(controller) {
+        this.currentToolAbort = controller;
+    }
+    /**
+     * 현재 등록된 AbortController를 해제한다.
+     *
+     * 도구 실행 완료 후 호출하여, 다음 도구와 혼선을 방지한다.
+     */
+    clearToolAbort() {
+        this.currentToolAbort = null;
+    }
+    /**
+     * 에이전트 루프가 일시 정지 상태인지 확인한다.
+     *
+     * 에이전트 루프는 매 iteration 시작 시 이 값을 확인하고,
+     * true이면 resume될 때까지 대기해야 한다.
+     */
+    isPaused() {
+        return this.paused;
+    }
+    /**
+     * 인터럽트 히스토리를 반환한다 (디버깅/감사용).
+     *
+     * @returns 최근 인터럽트 기록 (최대 50개)
+     */
+    getHistory() {
+        return this.history;
+    }
+    /**
+     * 상태를 초기화한다.
+     *
+     * 새 세션 시작 시 호출하여 이전 상태를 정리한다.
+     */
+    reset() {
+        this.currentToolAbort = null;
+        this.paused = false;
+        this.history.length = 0;
+    }
+    // ─── Private Handlers ────────────────────────────────────────
+    /**
+     * Soft interrupt 처리.
+     *
+     * 1. 현재 도구 실행 취소 (AbortController.abort())
+     * 2. 피드백이 있으면 에이전트 컨텍스트에 주입
+     * 3. 이벤트 발행 → 에이전트 루프는 계속 진행
+     */
+    handleSoftInterrupt(signal) {
+        // 1. 현재 도구 실행 취소
+        if (this.currentToolAbort && !this.currentToolAbort.signal.aborted) {
+            this.currentToolAbort.abort();
+        }
+        this.currentToolAbort = null;
+        // 2. 피드백 주입 요청
+        if (signal.feedback) {
+            this.emit("interrupt:feedback", `[유저 Interrupt] ${signal.feedback}`);
+        }
+        // 3. 이벤트 발행
+        this.emit("interrupt:soft", signal);
+    }
+    /**
+     * Hard interrupt 처리.
+     *
+     * 1. 모든 실행 즉시 중단 (도구 취소)
+     * 2. 비상 체크포인트 요청 발행
+     * 3. 세션 상태 → paused
+     * 4. 이벤트 발행
+     */
+    handleHardInterrupt(signal) {
+        // 1. 현재 도구 실행 취소
+        if (this.currentToolAbort && !this.currentToolAbort.signal.aborted) {
+            this.currentToolAbort.abort();
+        }
+        this.currentToolAbort = null;
+        // 2. paused 상태로 전환
+        this.paused = true;
+        // 3. 비상 체크포인트 요청
+        this.emit("interrupt:emergency_checkpoint");
+        // 4. 세션 상태 변경 요청
+        this.emit("interrupt:status_change", "paused");
+        // 5. 이벤트 발행
+        this.emit("interrupt:hard", signal);
+    }
+    /**
+     * Pause 처리.
+     *
+     * 에이전트 루프를 일시 정지한다.
+     * 상태는 유지되며, 현재 진행 중인 도구 실행은 완료될 수 있다.
+     */
+    handlePause(signal) {
+        if (this.paused)
+            return; // 이미 정지 상태
+        this.paused = true;
+        this.emit("interrupt:status_change", "paused");
+        this.emit("interrupt:pause", signal);
+    }
+    /**
+     * Resume 처리.
+     *
+     * 일시 정지된 에이전트 루프를 재개한다.
+     */
+    handleResume(signal) {
+        if (!this.paused)
+            return; // 이미 실행 중
+        this.paused = false;
+        this.emit("interrupt:status_change", "running");
+        this.emit("interrupt:resume", signal);
+    }
+    /**
+     * 인터럽트를 히스토리에 기록한다.
+     * 최대 MAX_HISTORY개까지 유지하며, 초과 시 오래된 것부터 제거.
+     */
+    recordHistory(signal) {
+        this.history.push({ signal, timestamp: Date.now() });
+        if (this.history.length > InterruptManager.MAX_HISTORY) {
+            this.history.shift();
+        }
+    }
+}
+//# sourceMappingURL=interrupt-manager.js.map

package/dist/interrupt-manager.js.map

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