@yuaone/core 0.1.0

package/dist/context-manager.js

@@ -0,0 +1,247 @@
+/**
+ * @module context-manager
+ * @description 컨텍스트 윈도우 관리.
+ * 메시지 히스토리 관리, 토큰 카운팅 (근사), 컨텍스트 압축.
+ */
+import { TOOL_RESULT_LIMITS, HISTORY_COMPACTION } from "./constants.js";
+import { ContextOverflowError } from "./errors.js";
+/**
+ * ContextManager — 컨텍스트 윈도우 크기를 관리.
+ *
+ * 역할:
+ * - 메시지 히스토리를 관리하고 토큰 수를 추적
+ * - 도구 결과가 너무 크면 자동 압축
+ * - 오래된 메시지를 요약으로 교체하여 컨텍스트 내에 유지
+ */
+export class ContextManager {
+    messages = [];
+    maxTokens;
+    outputReserve;
+    recentWindow;
+    summaryWindow;
+    constructor(config) {
+        this.maxTokens = config.maxContextTokens;
+        this.outputReserve = config.outputReserveTokens ?? 4096;
+        this.recentWindow =
+            config.compaction?.recentWindow ?? HISTORY_COMPACTION.recentWindow;
+        this.summaryWindow =
+            config.compaction?.summaryWindow ?? HISTORY_COMPACTION.summaryWindow;
+    }
+    /**
+     * 메시지를 히스토리에 추가.
+     * @param message 추가할 메시지
+     */
+    addMessage(message) {
+        this.messages.push(message);
+    }
+    /**
+     * 여러 메시지를 한 번에 추가.
+     * @param messages 추가할 메시지 목록
+     */
+    addMessages(messages) {
+        this.messages.push(...messages);
+    }
+    /**
+     * 현재 메시지 히스토리 반환.
+     * 컨텍스트 윈도우 내에 맞도록 자동 압축.
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * LLM에 보낼 메시지를 준비.
+     * 필요 시 압축하여 컨텍스트 윈도우 내에 맞춤.
+     */
+    prepareForLLM() {
+        const availableTokens = this.maxTokens - this.outputReserve;
+        let currentTokens = this.estimateTokens(this.messages);
+        if (currentTokens <= availableTokens) {
+            return [...this.messages];
+        }
+        // 압축 필요
+        const compacted = this.compactHistory(availableTokens);
+        currentTokens = this.estimateTokens(compacted);
+        if (currentTokens > availableTokens) {
+            throw new ContextOverflowError(currentTokens, availableTokens);
+        }
+        return compacted;
+    }
+    /**
+     * 메시지 목록의 대략적인 토큰 수를 추정.
+     * tiktoken 없이 근사치 사용 (영어 ~4자/토큰, 한국어 ~2자/토큰).
+     * @param messages 토큰 수를 추정할 메시지 목록
+     */
+    estimateTokens(messages) {
+        let total = 0;
+        for (const msg of messages) {
+            // 메시지 오버헤드 (~4 토큰)
+            total += 4;
+            if (msg.content) {
+                total += this.estimateStringTokens(msg.content);
+            }
+            if (msg.tool_calls) {
+                for (const tc of msg.tool_calls) {
+                    total += this.estimateStringTokens(tc.name) + 4;
+                    const argsStr = typeof tc.arguments === "string"
+                        ? tc.arguments
+                        : JSON.stringify(tc.arguments);
+                    total += this.estimateStringTokens(argsStr);
+                }
+            }
+        }
+        return total;
+    }
+    /**
+     * 도구 결과를 크기 제한에 맞게 압축.
+     * @param toolName 도구 이름
+     * @param result 도구 결과 문자열
+     * @returns 압축된 결과 (제한 내이면 원본 반환)
+     */
+    compressToolResult(toolName, result) {
+        const limit = TOOL_RESULT_LIMITS[toolName] ?? 10_000;
+        if (result.length <= limit)
+            return result;
+        const headSize = Math.floor(limit * 0.3);
+        const tailSize = Math.floor(limit * 0.3);
+        const truncated = result.length - headSize - tailSize;
+        return (result.slice(0, headSize) +
+            `\n\n... (${truncated} chars truncated) ...\n\n` +
+            result.slice(-tailSize));
+    }
+    /**
+     * 현재 총 토큰 수 추정치를 반환.
+     */
+    getCurrentTokenCount() {
+        return this.estimateTokens(this.messages);
+    }
+    /**
+     * 히스토리를 초기화.
+     */
+    clear() {
+        this.messages = [];
+    }
+    /**
+     * 히스토리 메시지 수를 반환.
+     */
+    get messageCount() {
+        return this.messages.length;
+    }
+    // ─── Private ───
+    /**
+     * 히스토리를 압축하여 토큰 예산 내에 맞춤.
+     *
+     * 전략:
+     * 1. system 메시지는 항상 유지
+     * 2. 최근 recentWindow개 메시지는 원본 유지
+     * 3. summaryWindow 범위: 도구 결과만 요약으로 교체
+     * 4. 그 이전: 전체를 1줄 요약으로 압축
+     */
+    compactHistory(targetTokens) {
+        const result = [];
+        // 1. system 메시지 추출
+        const systemMessages = this.messages.filter((m) => m.role === "system");
+        const nonSystemMessages = this.messages.filter((m) => m.role !== "system");
+        result.push(...systemMessages);
+        const total = nonSystemMessages.length;
+        const recentStart = Math.max(0, total - this.recentWindow);
+        const summaryStart = Math.max(0, recentStart - this.summaryWindow);
+        // 4. 아주 오래된 메시지 (summaryStart 이전) → 전체 요약
+        if (summaryStart > 0) {
+            const oldMessages = nonSystemMessages.slice(0, summaryStart);
+            const summary = this.summarizeMessages(oldMessages);
+            result.push({
+                role: "system",
+                content: `[Previous conversation summary]\n${summary}`,
+            });
+        }
+        // 3. 중간 메시지 (summaryStart ~ recentStart) → 도구 결과 압축
+        for (let i = summaryStart; i < recentStart; i++) {
+            const msg = nonSystemMessages[i];
+            if (msg.role === "tool" && msg.content) {
+                result.push({
+                    ...msg,
+                    content: this.truncateToolResult(msg.content),
+                });
+            }
+            else {
+                result.push(msg);
+            }
+        }
+        // 2. 최근 메시지 → 원본 유지
+        for (let i = recentStart; i < total; i++) {
+            result.push(nonSystemMessages[i]);
+        }
+        // 토큰 초과 시 중간 메시지도 추가 요약
+        let tokens = this.estimateTokens(result);
+        if (tokens > targetTokens && result.length > systemMessages.length + this.recentWindow) {
+            // 중간 메시지 제거하고 더 짧은 요약으로 교체
+            const keep = systemMessages.length + 1 + this.recentWindow; // system + summary + recent
+            while (result.length > keep && tokens > targetTokens) {
+                result.splice(systemMessages.length + 1, 1);
+                tokens = this.estimateTokens(result);
+            }
+        }
+        return result;
+    }
+    summarizeMessages(messages) {
+        const actions = [];
+        let userMsgCount = 0;
+        let toolCallCount = 0;
+        for (const msg of messages) {
+            if (msg.role === "user") {
+                userMsgCount++;
+                if (msg.content) {
+                    const preview = msg.content.slice(0, 100);
+                    actions.push(`User: ${preview}${msg.content.length > 100 ? "..." : ""}`);
+                }
+            }
+            else if (msg.role === "assistant" && msg.tool_calls) {
+                toolCallCount += msg.tool_calls.length;
+                for (const tc of msg.tool_calls) {
+                    actions.push(`Tool: ${tc.name}`);
+                }
+            }
+        }
+        return [
+            `${userMsgCount} user messages, ${toolCallCount} tool calls.`,
+            ...actions.slice(0, 10),
+            actions.length > 10
+                ? `... and ${actions.length - 10} more actions`
+                : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
+    truncateToolResult(content) {
+        const MAX = 500;
+        if (content.length <= MAX)
+            return content;
+        return content.slice(0, 200) + "\n...(truncated)...\n" + content.slice(-200);
+    }
+    /**
+     * 문자열의 대략적인 토큰 수를 추정 (근사치).
+     *
+     * **추정 방식:**
+     * - 영어/ASCII 텍스트: ~4 characters per token
+     * - CJK/한국어 텍스트 (U+3000–U+9FFF, U+AC00–U+D7AF): ~2 characters per token
+     * - 혼합 텍스트는 각 범위의 문자 수를 분리하여 합산
+     *
+     * **오차 범위:**
+     * - 영어: 실제 토큰 대비 ~±20% 오차 (서브워드 분할 특성상 변동)
+     * - CJK/한국어: ~±20% 이상 오차 가능 (모델별 토크나이저 차이가 큼)
+     * - 코드, 특수문자, 긴 단어 등에서 오차가 더 커질 수 있음
+     *
+     * **의도적 설계:**
+     * BYOK 환경에서는 사용자가 다양한 모델(Claude, GPT, Gemini 등)을
+     * 자유롭게 선택하므로 모델별 토크나이저에 접근할 수 없다.
+     * 따라서 정확한 토큰 카운팅 대신 범용 근사치를 사용하며,
+     * 컨텍스트 오버플로우는 outputReserve 마진으로 방어한다.
+     */
+    estimateStringTokens(str) {
+        // CJK 문자 비율 체크
+        const cjkCount = (str.match(/[\u3000-\u9fff\uac00-\ud7af]/g) ?? []).length;
+        const nonCjkCount = str.length - cjkCount;
+        return Math.ceil(nonCjkCount / 4 + cjkCount / 2);
+    }
+}
+//# sourceMappingURL=context-manager.js.map

package/dist/context-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-manager.js","sourceRoot":"","sources":["../src/context-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAenD;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IACjB,QAAQ,GAAc,EAAE,CAAC;IAChB,SAAS,CAAS;IAClB,aAAa,CAAS;IACtB,YAAY,CAAS;IACrB,aAAa,CAAS;IAEvC,YAAY,MAA4B;QACtC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,gBAAgB,CAAC;QACzC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,mBAAmB,IAAI,IAAI,CAAC;QACxD,IAAI,CAAC,YAAY;YACf,MAAM,CAAC,UAAU,EAAE,YAAY,IAAI,kBAAkB,CAAC,YAAY,CAAC;QACrE,IAAI,CAAC,aAAa;YAChB,MAAM,CAAC,UAAU,EAAE,aAAa,IAAI,kBAAkB,CAAC,aAAa,CAAC;IACzE,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,OAAgB;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,QAAmB;QAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC;QAC5D,IAAI,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEvD,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;YACrC,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAED,QAAQ;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,eAAe,CAAC,CAAC;QACvD,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAE/C,IAAI,aAAa,GAAG,eAAe,EAAE,CAAC;YACpC,MAAM,IAAI,oBAAoB,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;QACjE,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,QAAmB;QAChC,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,mBAAmB;YACnB,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,KAAK,IAAI,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClD,CAAC;YACD,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;gBACnB,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;oBAChC,KAAK,IAAI,IAAI,CAAC,oBAAoB,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBAChD,MAAM,OAAO,GACX,OAAO,EAAE,CAAC,SAAS,KAAK,QAAQ;wBAC9B,CAAC,CAAC,EAAE,CAAC,SAAS;wBACd,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;oBACnC,KAAK,IAAI,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,QAAgB,EAAE,MAAc;QACjD,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC;QACrD,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK;YAAE,OAAO,MAAM,CAAC;QAE1C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAEtD,OAAO,CACL,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;YACzB,YAAY,SAAS,2BAA2B;YAChD,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CACxB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,kBAAkB;IAElB;;;;;;;;OAQG;IACK,cAAc,CAAC,YAAoB;QACzC,MAAM,MAAM,GAAc,EAAE,CAAC;QAE7B,mBAAmB;QACnB,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CACzC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAC3B,CAAC;QACF,MAAM,iBAAiB,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAC5C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAC3B,CAAC;QAEF,MAAM,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC;QAE/B,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC;QACvC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAC3B,CAAC,EACD,WAAW,GAAG,IAAI,CAAC,aAAa,CACjC,CAAC;QAEF,0CAA0C;QAC1C,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,WAAW,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACpD,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,oCAAoC,OAAO,EAAE;aACvD,CAAC,CAAC;QACL,CAAC;QAED,oDAAoD;QACpD,KAAK,IAAI,CAAC,GAAG,YAAY,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,MAAM,GAAG,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBACvC,MAAM,CAAC,IAAI,CAAC;oBACV,GAAG,GAAG;oBACN,OAAO,EAAE,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC;iBAC9C,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QAED,oBAAoB;QACpB,KAAK,IAAI,CAAC,GAAG,WAAW,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC;QAED,wBAAwB;QACxB,IAAI,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,MAAM,GAAG,YAAY,IAAI,MAAM,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACvF,2BAA2B;YAC3B,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,4BAA4B;YACxF,OAAO,MAAM,CAAC,MAAM,GAAG,IAAI,IAAI,MAAM,GAAG,YAAY,EAAE,CAAC;gBACrD,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC5C,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,iBAAiB,CAAC,QAAmB;QAC3C,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,IAAI,aAAa,GAAG,CAAC,CAAC;QAEtB,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACxB,YAAY,EAAE,CAAC;gBACf,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;oBAChB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;oBAC1C,OAAO,CAAC,IAAI,CAAC,SAAS,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;iBAAM,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;gBACtD,aAAa,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC;gBACvC,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;oBAChC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,GAAG,YAAY,mBAAmB,aAAa,cAAc;YAC7D,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACvB,OAAO,CAAC,MAAM,GAAG,EAAE;gBACjB,CAAC,CAAC,WAAW,OAAO,CAAC,MAAM,GAAG,EAAE,eAAe;gBAC/C,CAAC,CAAC,EAAE;SACP;aACE,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAEO,kBAAkB,CAAC,OAAe;QACxC,MAAM,GAAG,GAAG,GAAG,CAAC;QAChB,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG;YAAE,OAAO,OAAO,CAAC;QAC1C,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,uBAAuB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/E,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACK,oBAAoB,CAAC,GAAW;QACtC,eAAe;QACf,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,+BAA+B,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QAC3E,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,GAAG,QAAQ,CAAC;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/continuous-reflection.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @module continuous-reflection
+ * @description Continuous Reflection — 설계 문서 섹션 20.2 구현.
+ *
+ * 1분 간격으로 3가지 자율 점검을 수행한다:
+ *
+ * 1. **Checkpoint**: 현재 상태를 SessionPersistence에 저장
+ * 2. **Self-Verify**: 경량 LLM 호출(~200 토큰)로 방향 검증
+ * 3. **Context Monitor**: 컨텍스트 사용량 체크, 80%→비상 체크포인트, 95%→새 세션 스폰
+ *
+ * ESC로 토글 가능 (pause/resume). 순수 실행 모드.
+ * EventEmitter를 확장하여 reflection 이벤트를 외부에 전파.
+ */
+import { EventEmitter } from "node:events";
+import type { ContinuationCheckpoint } from "./types.js";
+/**
+ * 자기 검증 프롬프트 템플릿.
+ *
+ * 플레이스홀더는 실행 시 실제 값으로 치환된다:
+ * - {goal}: 현재 에이전트 목표
+ * - {iteration}: 현재 iteration 수
+ * - {maxIteration}: 최대 iteration 수
+ * - {changedFiles}: 변경된 파일 목록
+ * - {recentToolCalls}: 최근 3개 도구 호출
+ * - {errors}: 발생한 에러 목록
+ */
+export declare const SELF_VERIFY_PROMPT = "\uB2F9\uC2E0\uC740 \uD604\uC7AC \uC2E4\uD589 \uC911\uC778 \uC5D0\uC774\uC804\uD2B8\uC758 \uC9C4\uD589 \uC0C1\uD669\uC744 \uAC80\uC99D\uD558\uB294 \uC5ED\uD560\uC785\uB2C8\uB2E4.\n\n\uD604\uC7AC \uC0C1\uD0DC:\n- \uBAA9\uD45C: {goal}\n- \uC644\uB8CC\uB41C \uC774\uD130\uB808\uC774\uC158: {iteration}/{maxIteration}\n- \uBCC0\uACBD\uB41C \uD30C\uC77C: {changedFiles}\n- \uCD5C\uADFC 3\uAC1C \uB3C4\uAD6C \uD638\uCD9C: {recentToolCalls}\n- \uC5D0\uB7EC \uBC1C\uC0DD: {errors}\n\n\uB2E4\uC74C\uC744 \uD310\uB2E8\uD558\uC138\uC694:\n1. \uC62C\uBC14\uB978 \uBC29\uD5A5\uC73C\uB85C \uC9C4\uD589 \uC911\uC778\uAC00? (yes/no)\n2. \uC0BD\uC9C8 \uD328\uD134\uC774 \uBCF4\uC774\uB294\uAC00? (\uAC19\uC740 \uD30C\uC77C \uBC18\uBCF5 \uC218\uC815, \uAC19\uC740 \uC5D0\uB7EC \uBC18\uBCF5 \uB4F1)\n3. \uBC29\uD5A5 \uC804\uD658\uC774 \uD544\uC694\uD55C\uAC00?\n\nJSON\uC73C\uB85C \uC751\uB2F5:\n{\n  \"onTrack\": true/false,\n  \"needsCorrection\": true/false,\n  \"issue\": \"\uBB38\uC81C \uC124\uBA85 (\uC788\uC73C\uBA74)\",\n  \"suggestion\": \"\uC81C\uC548 (\uC788\uC73C\uBA74)\",\n  \"confidence\": 0.0~1.0\n}";
+/** Reflection 설정 */
+export interface ReflectionConfig {
+    /** 체크 간격 (ms). 기본 60_000 (1분). */
+    intervalMs: number;
+    /** Reflection 활성화 여부. ESC로 토글. */
+    enabled: boolean;
+    /** 체크포인트 저장 활성화 */
+    checkpointEnabled: boolean;
+    /** 자기 검증 (LLM 호출) 활성화 */
+    selfVerifyEnabled: boolean;
+    /** 컨텍스트 사용량 모니터 활성화 */
+    contextMonitorEnabled: boolean;
+}
+/** 자기 검증 LLM 응답 */
+export interface SelfVerifyVerdict {
+    /** 올바른 방향인가 */
+    onTrack: boolean;
+    /** 방향 전환이 필요한가 */
+    needsCorrection: boolean;
+    /** 문제 설명 (있으면) */
+    issue: string;
+    /** 수정 제안 (있으면) */
+    suggestion: string;
+    /** 판단 확신도 (0.0~1.0) */
+    confidence: number;
+}
+/** 에이전트 상태 스냅샷 — reflection이 접근하는 읽기 전용 정보 */
+export interface AgentStateSnapshot {
+    /** 현재 목표 */
+    goal: string;
+    /** 현재 iteration */
+    iteration: number;
+    /** 최대 iteration */
+    maxIteration: number;
+    /** 변경된 파일 목록 */
+    changedFiles: string[];
+    /** 최근 도구 호출 (최대 3개) */
+    recentToolCalls: Array<{
+        tool: string;
+        input: string;
+        output: string;
+    }>;
+    /** 발생한 에러 목록 */
+    errors: string[];
+    /** 컨텍스트 사용률 (0.0~1.0) */
+    contextUsagePercent: number;
+    /** 세션 ID */
+    sessionId: string;
+    /** 사용된 총 토큰 */
+    totalTokensUsed: number;
+    /** 작업 메모리 (압축 요약) */
+    workingMemory: string;
+    /** 완료된 태스크 목록 */
+    completedTasks: string[];
+    /** 현재 태스크 */
+    currentTask: string;
+    /** 남은 태스크 목록 */
+    remainingTasks: string[];
+}
+/**
+ * 자기 검증 LLM 호출 콜백.
+ *
+ * LLMClient를 직접 import하지 않고 의존성 주입으로 받는다.
+ * 호출 측에서 경량 모델(~200 토큰)로 호출하도록 구현한다.
+ *
+ * @param prompt - 치환된 검증 프롬프트
+ * @returns 검증 결과 JSON
+ */
+export type SelfVerifyFn = (prompt: string) => Promise<SelfVerifyVerdict>;
+/**
+ * 체크포인트 저장 콜백.
+ *
+ * SessionPersistence를 직접 import하지 않고 의존성 주입으로 받는다.
+ *
+ * @param state - 현재 에이전트 상태 스냅샷
+ * @param emergency - 비상 체크포인트 여부 (80%+ 컨텍스트)
+ */
+export type CheckpointFn = (state: AgentStateSnapshot, emergency: boolean) => Promise<void>;
+/**
+ * 에이전트 상태 제공 콜백.
+ *
+ * AgentLoop의 현재 상태를 읽기 전용으로 가져온다.
+ */
+export type GetStateFn = () => AgentStateSnapshot;
+/** ContinuousReflection 생성자 옵션 */
+export interface ContinuousReflectionOptions {
+    /** Reflection 설정 */
+    config?: Partial<ReflectionConfig>;
+    /** 자기 검증 LLM 호출 콜백 (DI) */
+    selfVerify?: SelfVerifyFn;
+    /** 체크포인트 저장 콜백 (DI) */
+    checkpoint?: CheckpointFn;
+    /** 에이전트 상태 제공 콜백 (DI) */
+    getState: GetStateFn;
+}
+/** ContinuousReflection이 발행하는 이벤트 맵 */
+export interface ReflectionEvents {
+    /** 체크포인트 저장 완료 */
+    "reflection:checkpoint": [state: AgentStateSnapshot];
+    /** 자기 검증 완료 */
+    "reflection:self_verify": [verdict: SelfVerifyVerdict];
+    /** 피드백 주입 요청 (방향 전환 필요 시) */
+    "reflection:feedback": [feedback: string];
+    /** 컨텍스트 80% 도달 — 비상 체크포인트 */
+    "reflection:context_warning": [usagePercent: number];
+    /** 컨텍스트 95% 도달 — 새 세션 스폰 요청 */
+    "reflection:context_overflow": [checkpoint: ContinuationCheckpoint];
+    /** Reflection 일시 정지 (ESC) */
+    "reflection:paused": [];
+    /** Reflection 재개 */
+    "reflection:resumed": [];
+    /** Reflection 에러 (비치명적, 다음 tick에서 재시도) */
+    "reflection:error": [error: Error];
+}
+/**
+ * Continuous Reflection.
+ *
+ * 1분 간격으로 체크포인트 저장, 자기 검증, 컨텍스트 모니터를 수행한다.
+ * ESC로 토글 가능 (pause/resume).
+ *
+ * LLM 호출과 체크포인트 저장은 의존성 주입으로 받아 결합도를 낮춘다.
+ * 컨텍스트 95% 도달 시 `reflection:context_overflow` 이벤트를 발행하며,
+ * 실제 세션 스폰은 부모(AgentRunner)가 처리한다.
+ *
+ * @example
+ * ```typescript
+ * const reflection = new ContinuousReflection({
+ *   getState: () => agentLoop.getStateSnapshot(),
+ *   selfVerify: async (prompt) => llm.complete(prompt, { maxTokens: 200 }),
+ *   checkpoint: async (state, emergency) => persistence.save(state, emergency),
+ * });
+ *
+ * reflection.on("reflection:context_overflow", (cp) => {
+ *   agentRunner.spawnContinuation(cp);
+ * });
+ *
+ * reflection.on("reflection:feedback", (feedback) => {
+ *   agentLoop.injectFeedback(feedback);
+ * });
+ *
+ * reflection.start();
+ * // ... agent loop runs ...
+ * reflection.stop();
+ * ```
+ */
+export declare class ContinuousReflection extends EventEmitter {
+    /** 주기적 타이머 */
+    private timer;
+    /** 현재 설정 */
+    private config;
+    /** 자기 검증 LLM 호출 콜백 */
+    private readonly selfVerifyFn;
+    /** 체크포인트 저장 콜백 */
+    private readonly checkpointFn;
+    /** 에이전트 상태 제공 콜백 */
+    private readonly getStateFn;
+    /** tick 실행 중 여부 (중복 방지) */
+    private ticking;
+    /** 컨텍스트 overflow가 이미 트리거됐는지 (중복 스폰 방지) */
+    private overflowTriggered;
+    constructor(options: ContinuousReflectionOptions);
+    /**
+     * Reflection 루프를 시작한다.
+     *
+     * config.intervalMs 간격으로 체크포인트, 자기 검증, 컨텍스트 모니터를 수행.
+     */
+    start(): void;
+    /**
+     * Reflection을 일시 정지한다 (ESC 토글).
+     *
+     * 타이머는 유지되지만 tick 내부에서 enabled=false이면 스킵.
+     */
+    pause(): void;
+    /**
+     * Reflection을 재개한다.
+     */
+    resume(): void;
+    /**
+     * Reflection 루프를 완전히 중지한다.
+     *
+     * 세션 종료 시 호출.
+     */
+    stop(): void;
+    /**
+     * Reflection이 현재 활성 상태인지 반환한다.
+     */
+    isEnabled(): boolean;
+    /**
+     * Reflection 루프가 실행 중인지 반환한다 (타이머 존재 여부).
+     */
+    isRunning(): boolean;
+    /**
+     * 비상 체크포인트를 즉시 수행한다.
+     *
+     * Hard interrupt 시 InterruptManager가 호출한다.
+     */
+    emergencyCheckpoint(): Promise<void>;
+    /**
+     * 현재 설정을 반환한다.
+     */
+    getConfig(): Readonly<ReflectionConfig>;
+    /**
+     * 설정을 부분 업데이트한다.
+     */
+    updateConfig(partial: Partial<ReflectionConfig>): void;
+    /**
+     * 1회 tick 실행.
+     *
+     * 중복 실행 방지 (이전 tick이 아직 진행 중이면 스킵).
+     * 각 단계에서 에러가 발생해도 다음 단계는 실행한다 (비치명적).
+     */
+    private tick;
+    /**
+     * [1] 체크포인트 저장.
+     *
+     * 현재 상태를 SessionPersistence에 저장한다.
+     */
+    private performCheckpoint;
+    /**
+     * [2] 자기 검증.
+     *
+     * 경량 LLM 호출(~200 토큰)로 현재 방향을 검증한다.
+     * 방향 전환이 필요하면 피드백을 에이전트 루프에 주입한다.
+     */
+    private performSelfVerify;
+    /**
+     * [3] 컨텍스트 사용량 모니터.
+     *
+     * - 80%: 비상 체크포인트
+     * - 95%: 새 세션 스폰 요청 (1회만)
+     */
+    private performContextMonitor;
+    /**
+     * 자기 검증 프롬프트를 빌드한다.
+     *
+     * SELF_VERIFY_PROMPT 템플릿의 플레이스홀더를 실제 값으로 치환한다.
+     */
+    private buildSelfVerifyPrompt;
+}
+//# sourceMappingURL=continuous-reflection.d.ts.map

package/dist/continuous-reflection.d.ts.map

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