@yuaone/core 0.1.0

package/dist/constants.js

@@ -0,0 +1,141 @@
+/**
+ * @module constants
+ * @description YUAN Agent 상수 정의.
+ *
+ * 보안 관련 패턴(DANGEROUS_PATTERNS, SENSITIVE_FILE_PATTERNS, ALLOWED_EXECUTABLES)은
+ * security.ts가 SSOT이며, 여기서는 re-export만 한다.
+ */
+// Security constants (DANGEROUS_PATTERNS, SENSITIVE_FILE_PATTERNS, ALLOWED_EXECUTABLES)
+// are defined in security.ts (SSOT) and exported directly from index.ts.
+// Do NOT re-export them here to avoid duplicate export paths.
+/**
+ * 플랜별 리소스 제한 (SSOT — 설계 문서 11.2 기준)
+ */
+export const PLAN_LIMITS = {
+    FREE: {
+        dailyExecutions: 3,
+        maxIterations: 5,
+        maxParallelAgents: 1,
+        tokensPerRequest: 20_000,
+        sessionTtlMs: 5 * 60 * 1000, // 5분
+        concurrentSessions: 1,
+    },
+    PRO: {
+        dailyExecutions: 15,
+        maxIterations: 25,
+        maxParallelAgents: 3,
+        tokensPerRequest: 72_000,
+        sessionTtlMs: 30 * 60 * 1000, // 30분
+        concurrentSessions: 2,
+    },
+    BUSINESS: {
+        dailyExecutions: 50,
+        maxIterations: 50,
+        maxParallelAgents: 7,
+        tokensPerRequest: 140_000,
+        sessionTtlMs: 2 * 60 * 60 * 1000, // 2시간
+        concurrentSessions: 5,
+    },
+    ENTERPRISE: {
+        dailyExecutions: 150,
+        maxIterations: 100,
+        maxParallelAgents: Infinity,
+        tokensPerRequest: 240_000,
+        sessionTtlMs: 8 * 60 * 60 * 1000, // 8시간
+        concurrentSessions: 20,
+    },
+};
+/**
+ * 프로바이더별 기본 모델
+ */
+export const MODEL_DEFAULTS = {
+    openai: "gpt-4o",
+    anthropic: "claude-sonnet-4-20250514",
+    google: "gemini-2.5-flash",
+    yua: "yua-pro",
+    deepseek: "deepseek-chat",
+};
+/**
+ * 프로바이더별 API Base URL
+ */
+export const PROVIDER_BASE_URLS = {
+    openai: "https://api.openai.com/v1",
+    anthropic: "https://api.anthropic.com",
+    google: "https://generativelanguage.googleapis.com/v1beta/openai",
+    yua: "https://yuaone.com/api/v1",
+    deepseek: "https://api.deepseek.com/v1",
+};
+/**
+ * 도구 결과 크기 제한 (바이트)
+ */
+export const TOOL_RESULT_LIMITS = {
+    file_read: 50_000,
+    shell_exec: 100_000,
+    grep: 10_000,
+    glob: 5_000,
+    test_run: 20_000,
+};
+/**
+ * 히스토리 압축 설정
+ */
+export const HISTORY_COMPACTION = {
+    /** 원본 유지하는 최근 iteration 수 */
+    recentWindow: 5,
+    /** 도구 결과만 요약으로 교체하는 범위 */
+    summaryWindow: 10,
+};
+/**
+ * YUAN.md 탐색 경로 (우선순위 순)
+ */
+export const YUAN_MD_SEARCH_PATHS = [
+    "YUAN.md",
+    ".yuan/config.md",
+    ".yuan/YUAN.md",
+    "docs/YUAN.md",
+];
+/**
+ * 기본 AgentLoop 설정값
+ */
+export const DEFAULT_LOOP_CONFIG = {
+    maxIterations: 25,
+    maxTokensPerIteration: 8_000,
+    totalTokenBudget: 200_000,
+};
+/** Design Mode: allowed edit paths (Governor enforced) */
+export const DESIGN_ALLOWED_PATHS = [
+    "src/",
+    "app/",
+    "components/",
+    "styles/",
+    "pages/",
+    "public/",
+    "assets/",
+];
+/** Design Mode: blocked edit paths */
+export const DESIGN_BLOCKED_PATHS = [
+    "node_modules/",
+    ".env",
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    ".git/",
+];
+/** Design Mode: security scan patterns */
+export const DESIGN_SECURITY_PATTERNS = {
+    xss: [
+        /dangerouslySetInnerHTML/,
+        /\bonclick\s*=/i,
+        /\bonerror\s*=/i,
+        /\bonload\s*=/i,
+        /javascript:/i,
+    ],
+    csp: [
+        /style\s*=\s*["']/,
+        /<script[^>]*>/i,
+    ],
+    injection: [
+        /\$\{[^}]*(?:user|input|query|param)/i,
+    ],
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

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

package/dist/context-budget.d.ts

@@ -0,0 +1,435 @@
+/**
+ * @module context-budget
+ * @description 컨텍스트 윈도우 예산 관리자.
+ *
+ * LLM 컨텍스트 오버플로우를 방지하기 위한 고급 예산 관리 시스템.
+ * - 카테고리별 토큰 예산 배분 및 강제
+ * - 우선순위 기반 선택적 유지/제거
+ * - LLM 기반 요약을 통한 오래된 메시지 압축
+ * - 관련성 기반 검색으로 필요한 컨텍스트만 로드
+ * - 슬라이딩 윈도우 + 체크포인트로 핵심 결정 보존
+ *
+ * @example
+ * ```typescript
+ * const budget = new ContextBudgetManager({ totalBudget: 128_000 });
+ *
+ * budget.addItem({
+ *   category: "systemPrompt",
+ *   priority: "critical",
+ *   content: systemPrompt,
+ *   role: "system",
+ * });
+ *
+ * budget.addItem({
+ *   category: "conversationHistory",
+ *   priority: "high",
+ *   content: userMessage,
+ *   role: "user",
+ * });
+ *
+ * // Auto-manage when nearing limits
+ * await budget.autoManage(async (text) => llm.summarize(text));
+ *
+ * // Build context for LLM call
+ * const messages = budget.toMessages();
+ * ```
+ */
+import { EventEmitter } from "node:events";
+import type { Message } from "./types.js";
+/** 카테고리별 토큰 예산 배분 (합계 = 100) */
+export interface BudgetAllocation {
+    /** 시스템 프롬프트 비율 (기본 15%) */
+    systemPrompt: number;
+    /** 프로젝트 컨텍스트 비율 — YUAN.md, 파일 컨텍스트 (기본 10%) */
+    projectContext: number;
+    /** 대화 히스토리 비율 (기본 40%) */
+    conversationHistory: number;
+    /** 도구 결과 비율 (기본 25%) */
+    toolResults: number;
+    /** 워킹 메모리 비율 (기본 10%) */
+    workingMemory: number;
+}
+/** 컨텍스트 아이템 우선순위 */
+export type ContextPriority = "critical" | "high" | "medium" | "low" | "ephemeral";
+/** 컨텍스트 아이템 — 예산 관리의 최소 단위 */
+export interface ContextItem {
+    /** 고유 ID */
+    id: string;
+    /** 소속 카테고리 */
+    category: keyof BudgetAllocation;
+    /** 우선순위 */
+    priority: ContextPriority;
+    /** 콘텐츠 문자열 */
+    content: string;
+    /** 추정 토큰 수 */
+    tokenCount: number;
+    /** 생성 시각 (epoch ms) */
+    timestamp: number;
+    /** 메시지 역할 */
+    role?: "system" | "user" | "assistant" | "tool";
+    /** 도구 이름 (role=tool 일 때) */
+    toolName?: string;
+    /** 연관 파일 경로 */
+    file?: string;
+    /** 이미 요약되었는지 여부 */
+    summarized?: boolean;
+    /** 이 아이템이 요약한 원본 아이템 ID 목록 */
+    summaryOf?: string[];
+    /** 사용자가 수동으로 고정했는지 여부 */
+    pinned?: boolean;
+}
+/** 요약 결과 */
+export interface ContextSummary {
+    /** 요약된 원본 아이템 ID 목록 */
+    originalIds: string[];
+    /** 원본 총 토큰 수 */
+    originalTokens: number;
+    /** 요약된 콘텐츠 */
+    summarizedContent: string;
+    /** 요약 토큰 수 */
+    summarizedTokens: number;
+    /** 압축률 (요약/원본) */
+    compressionRatio: number;
+    /** 생성 시각 (epoch ms) */
+    createdAt: number;
+}
+/** 검색 쿼리 — 관련성 기반 컨텍스트 필터링 */
+export interface RetrievalQuery {
+    /** 현재 태스크 목표 */
+    goal: string;
+    /** 현재 작업 중인 파일 */
+    currentFiles: string[];
+    /** 최근 사용한 도구 */
+    recentTools: string[];
+    /** 추출된 키워드 */
+    keywords: string[];
+}
+/** 검색 결과 */
+export interface RetrievalResult {
+    /** 검색된 아이템 목록 */
+    items: ContextItem[];
+    /** 총 토큰 수 */
+    totalTokens: number;
+    /** 예산 초과로 잘렸는지 여부 */
+    truncated: boolean;
+    /** 평균 관련성 점수 (0-1) */
+    retrievalScore: number;
+}
+/** ContextBudgetManager 설정 */
+export interface ContextBudgetConfig {
+    /** 총 토큰 예산 (기본 128,000) */
+    totalBudget: number;
+    /** 카테고리별 예산 배분 */
+    allocation: BudgetAllocation;
+    /** 요약 기능 활성화 (기본 true) */
+    enableSummarization: boolean;
+    /** 요약 트리거 사용률 (기본 0.75) */
+    summarizationThreshold: number;
+    /** 최소 요약 배치 크기 (기본 5) */
+    minItemsToSummarize: number;
+    /** 요약 최대 토큰 수 (기본 500) */
+    maxSummaryLength: number;
+    /** 검색 기능 활성화 (기본 true) */
+    enableRetrieval: boolean;
+    /** 검색 시 최대 반환 아이템 수 (기본 20) */
+    retrievalTopK: number;
+    /** 체크포인트 기능 활성화 (기본 true) */
+    enableCheckpoints: boolean;
+    /** 체크포인트 생성 간격 (메시지 수, 기본 10) */
+    checkpointInterval: number;
+    /** 최대 유지 체크포인트 수 (기본 5) */
+    maxCheckpoints: number;
+    /** 제거 전략 (기본 "hybrid") */
+    evictionStrategy: "lru" | "priority" | "hybrid";
+}
+/** 예산 현황 */
+export interface BudgetStatus {
+    /** 총 예산 */
+    totalBudget: number;
+    /** 사용 중인 토큰 수 */
+    usedTokens: number;
+    /** 사용률 (0-1) */
+    usagePercent: number;
+    /** 카테고리별 현황 */
+    byCategory: Record<keyof BudgetAllocation, {
+        budget: number;
+        used: number;
+        percent: number;
+        itemCount: number;
+    }>;
+    /** 요약 수행 횟수 */
+    summarizationCount: number;
+    /** 제거된 아이템 수 */
+    evictionCount: number;
+    /** 체크포인트 수 */
+    checkpointCount: number;
+    /** 건강 상태 */
+    health: "healthy" | "warning" | "critical" | "overflow";
+}
+/** ContextBudgetManager의 직렬화 스냅샷 — 세션 영속성용 */
+export interface ContextBudgetSnapshot {
+    /** 모든 컨텍스트 아이템 (Map → 배열 변환) */
+    items: Array<{
+        key: string;
+        item: ContextItem;
+    }>;
+    /** 요약 기록 */
+    summaries: ContextSummary[];
+    /** 체크포인트 목록 */
+    checkpoints: ContextCheckpoint[];
+    /** 내부 ID 카운터 */
+    idCounter: number;
+    /** 요약 수행 횟수 */
+    summarizationCount: number;
+    /** 제거된 아이템 수 */
+    evictionCount: number;
+}
+/** 컨텍스트 체크포인트 — 슬라이딩 윈도우의 스냅샷 */
+export interface ContextCheckpoint {
+    /** 체크포인트 ID */
+    id: string;
+    /** 생성 시각 (epoch ms) */
+    timestamp: number;
+    /** 메시지 인덱스 */
+    messageIndex: number;
+    /** 축약된 요약 */
+    summary: string;
+    /** 핵심 결정 목록 */
+    keyDecisions: string[];
+    /** 현재 작업 중인 파일 목록 */
+    activeFiles: string[];
+    /** 토큰 수 */
+    tokenCount: number;
+}
+/**
+ * ContextBudgetManager — LLM 컨텍스트 윈도우 예산을 지능적으로 관리.
+ *
+ * 핵심 기능:
+ * - 카테고리별 토큰 예산 배분 및 강제
+ * - 우선순위 기반 아이템 제거 (hybrid LRU + priority)
+ * - LLM 기반 요약을 통한 오래된 메시지 압축
+ * - 관련성 점수 기반 검색으로 필요한 컨텍스트만 로드
+ * - 슬라이딩 윈도우 + 체크포인트로 핵심 결정 보존
+ *
+ * 이벤트:
+ * - `budget:warning` — 사용률 > 75%
+ * - `budget:critical` — 사용률 > 90%
+ * - `budget:overflow` — 사용률 > 100%, 강제 제거 수행
+ * - `summarize:start` — 요약 시작
+ * - `summarize:complete` — 요약 완료 (압축률 포함)
+ * - `evict:items` — 아이템 제거됨
+ * - `checkpoint:created` — 체크포인트 저장됨
+ */
+export declare class ContextBudgetManager extends EventEmitter {
+    private readonly config;
+    private items;
+    private summaries;
+    private checkpoints;
+    private idCounter;
+    private summarizationCount;
+    private evictionCount;
+    constructor(config?: Partial<ContextBudgetConfig>);
+    /**
+     * 컨텍스트 아이템을 추가하고 자동으로 예산을 강제한다.
+     * 추가 후 전체 사용률이 90%를 넘으면 `budget:critical` 이벤트를 발생시킨다.
+     *
+     * @param item - 아이템 메타데이터 (id, tokenCount, timestamp 자동 생성)
+     * @param content - 아이템 콘텐츠
+     * @returns 생성된 ContextItem
+     */
+    addItem(item: Omit<ContextItem, "id" | "tokenCount" | "timestamp">, content: string): ContextItem;
+    /**
+     * 기존 아이템의 콘텐츠를 업데이트한다.
+     * @param id - 아이템 ID
+     * @param content - 새 콘텐츠
+     */
+    updateItem(id: string, content: string): void;
+    /**
+     * 아이템을 제거한다.
+     * @param id - 제거할 아이템 ID
+     */
+    removeItem(id: string): void;
+    /**
+     * 아이템을 고정/해제한다. 고정된 아이템은 절대 제거되지 않는다.
+     * @param id - 아이템 ID
+     * @param pinned - 고정 여부 (기본 true)
+     */
+    pinItem(id: string, pinned?: boolean): void;
+    /**
+     * 현재 예산 현황을 반환한다.
+     * @returns 카테고리별 사용량, 건강 상태 등
+     */
+    getStatus(): BudgetStatus;
+    /**
+     * 특정 카테고리의 예산 토큰 수를 반환한다.
+     * @param category - 카테고리 이름
+     * @returns 해당 카테고리의 토큰 예산
+     */
+    getCategoryBudget(category: keyof BudgetAllocation): number;
+    /**
+     * 지정된 토큰 수를 추가할 공간이 있는지 확인한다.
+     * @param tokens - 필요한 토큰 수
+     * @param category - 특정 카테고리 체크 (미지정 시 전체)
+     * @returns 공간 있으면 true
+     */
+    hasRoom(tokens: number, category?: keyof BudgetAllocation): boolean;
+    /**
+     * 카테고리의 남은 토큰 수를 반환한다.
+     * 카테고리 간 차용을 허용하여 소프트 예산의 20% 오버플로우까지 허용한다.
+     * @param category - 카테고리 이름
+     * @returns 남은 토큰 수
+     */
+    getRemainingTokens(category: keyof BudgetAllocation): number;
+    /**
+     * LLM 호출을 위한 최종 컨텍스트를 구축한다.
+     * 예산 내에서 우선순위 순으로 아이템을 정렬하여 반환한다.
+     * @returns 예산 내의 ContextItem 배열
+     */
+    buildContext(): ContextItem[];
+    /**
+     * 관련성 기반 검색으로 컨텍스트를 구축한다.
+     * 현재 작업과 관련 없는 아이템은 제외하여 토큰을 절약한다.
+     * @param query - 검색 쿼리
+     * @returns 검색 결과
+     */
+    buildContextWithRetrieval(query: RetrievalQuery): RetrievalResult;
+    /**
+     * 카테고리별 아이템을 우선순위 → 최신순으로 정렬하여 반환한다.
+     * @param category - 카테고리 이름
+     * @returns 정렬된 ContextItem 배열
+     */
+    getItemsByCategory(category: keyof BudgetAllocation): ContextItem[];
+    /**
+     * 오래된 medium 우선순위 메시지를 LLM으로 요약한다.
+     * 연속된 medium 아이템을 그룹화하여 하나의 요약으로 교체한다.
+     *
+     * @param summarizeFn - LLM 요약 호출 함수
+     * @returns 요약 결과 또는 null (요약 불필요 시)
+     */
+    summarize(summarizeFn: (messages: string) => Promise<string>): Promise<ContextSummary | null>;
+    /**
+     * 요약이 필요한지 확인한다.
+     * 전체 사용률이 summarizationThreshold를 초과하고
+     * 요약 가능한 medium 아이템이 충분하면 true.
+     * @returns 요약 필요 여부
+     */
+    needsSummarization(): boolean;
+    /**
+     * 지정된 토큰 수를 확보하기 위해 아이템을 제거한다.
+     *
+     * Hybrid 전략:
+     * 1. ephemeral 아이템 먼저 제거
+     * 2. low 우선순위 아이템 제거 (LRU 순)
+     * 3. medium 우선순위 아이템 제거 (LRU 순)
+     * 4. high는 최후의 수단으로만
+     * 5. critical/pinned는 절대 제거 불가
+     *
+     * @param tokensNeeded - 확보해야 할 토큰 수
+     * @returns 제거된 아이템 목록
+     */
+    evict(tokensNeeded: number): ContextItem[];
+    /**
+     * 예산을 자동으로 관리한다.
+     * 사용률에 따라 요약 → 제거 순서로 토큰을 확보한다.
+     *
+     * @param summarizeFn - LLM 요약 호출 함수 (선택)
+     * @returns 요약/제거된 아이템 수
+     */
+    autoManage(summarizeFn?: (messages: string) => Promise<string>): Promise<{
+        summarized: number;
+        evicted: number;
+    }>;
+    /**
+     * 현재 상태의 체크포인트를 생성한다.
+     * 체크포인트는 전체 컨텍스트의 축약 요약 + 핵심 결정 목록을 포함한다.
+     *
+     * @param messageIndex - 현재 메시지 인덱스
+     * @param summarizeFn - LLM 요약 호출 함수
+     * @returns 생성된 체크포인트
+     */
+    createCheckpoint(messageIndex: number, summarizeFn: (text: string) => Promise<string>): Promise<ContextCheckpoint>;
+    /**
+     * 체크포인트에서 복원한다.
+     * 현재 아이템을 모두 지우고 체크포인트 요약을 시스템 메시지로 추가한다.
+     *
+     * @param checkpoint - 복원할 체크포인트
+     */
+    restoreFromCheckpoint(checkpoint: ContextCheckpoint): void;
+    /**
+     * 모든 체크포인트를 반환한다.
+     * @returns 읽기 전용 체크포인트 배열
+     */
+    getCheckpoints(): readonly ContextCheckpoint[];
+    /**
+     * 아이템의 현재 작업에 대한 관련성 점수를 계산한다.
+     *
+     * 점수 구성:
+     * - fileMatch (0.3): 현재 작업 파일과 일치
+     * - keywordMatch (0.25): 키워드 겹침
+     * - recencyScore (0.2): 최신일수록 높음
+     * - priorityScore (0.15): 높은 우선순위일수록 높음
+     * - toolMatch (0.1): 최근 사용 도구와 일치
+     *
+     * @param item - 평가할 아이템
+     * @param query - 검색 쿼리
+     * @returns 관련성 점수 (0-1)
+     */
+    scoreRelevance(item: ContextItem, query: RetrievalQuery): number;
+    /**
+     * JSON 직렬화 — 세션 영속성을 위해 전체 상태를 스냅샷으로 변환한다.
+     * Map/Set → 배열 변환을 수행한다.
+     *
+     * @returns ContextBudgetSnapshot
+     */
+    toJSON(): ContextBudgetSnapshot;
+    /**
+     * JSON에서 ContextBudgetManager를 복구한다.
+     * 기존 config를 유지하면서 저장된 런타임 상태를 복원한다.
+     *
+     * @param snapshot - 저장된 스냅샷
+     * @param config - 예산 설정 (미지정 시 기본값)
+     * @returns 복원된 ContextBudgetManager
+     */
+    static fromJSON(snapshot: ContextBudgetSnapshot, config?: Partial<ContextBudgetConfig>): ContextBudgetManager;
+    /**
+     * 문자열의 대략적인 토큰 수를 추정한다.
+     *
+     * CJK 문자가 30% 이상이면 CJK 모드 (~2 chars/token),
+     * 그 외에는 영어 모드 (~3.5 chars/token).
+     *
+     * @param text - 추정할 문자열
+     * @returns 추정 토큰 수
+     */
+    estimateTokens(text: string): number;
+    /**
+     * 현재 아이템을 LLM 호출용 Message[] 로 변환한다.
+     * 예산 내의 아이템만 포함하며, timestamp 순으로 정렬한다.
+     *
+     * @returns Message 배열
+     */
+    toMessages(): Message[];
+    /**
+     * 기존 Message[] 히스토리를 아이템으로 임포트한다.
+     * 각 메시지를 적절한 카테고리와 우선순위로 분류한다.
+     *
+     * @param messages - 임포트할 메시지 배열
+     */
+    importMessages(messages: Message[]): void;
+    /**
+     * 전체 사용 중인 토큰 수를 계산한다.
+     */
+    private getTotalUsedTokens;
+    /**
+     * 예산 건강 상태를 확인하고 필요 시 이벤트를 발생시킨다.
+     */
+    private checkBudgetHealth;
+    /**
+     * 제거 전략에 따라 아이템을 정렬한다.
+     * 제거 순서: ephemeral → low → medium → high (oldest first within each)
+     *
+     * @param items - 정렬할 아이템 배열
+     * @returns 제거 우선순위 순으로 정렬된 배열
+     */
+    private sortForEviction;
+}
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/context-budget.d.ts.map

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