@n2world/orchestrator 1.1.0

package/dist/commit-gate.d.ts

@@ -0,0 +1,98 @@
+import { CrossValidationOracle } from './oracle';
+export type ActionKind = 'read' | 'compute' | 'file-write-temp' | 'file-delete' | 'kernel-resource' | 'external-effect' | 'network-egress';
+export interface ProposedAction {
+    id: string;
+    /** 실행될 명령/행동 텍스트. */
+    command: string;
+    kind?: ActionKind;
+    description?: string;
+}
+/** 되돌릴 수 없는/외부 효과 행동인가. commit-gate 는 이런 행동에만 호출된다(빈도·비용 통제). */
+export declare function isIrreversible(action: ProposedAction): boolean;
+export type GateLayer = 'not-gated' | 'rule' | 'model-critic' | 'deny-by-default' | 'rule-only-passthrough';
+export interface CriticVerdict {
+    flagged: boolean;
+    confidence: number;
+    reason: string;
+    tokens: number | null;
+}
+export type CriticFn = (action: ProposedAction) => Promise<CriticVerdict>;
+export interface GateDecision {
+    id: string;
+    allowed: boolean;
+    layer: GateLayer;
+    reason: string;
+    ruleFlagged: boolean;
+    ruleMatched: string[];
+    criticFlagged: boolean | null;
+    criticConfidence: number | null;
+    denyByDefault: boolean;
+    /** 이 결정에 든 비용(누적은 stats()). */
+    cost: {
+        criticCalls: number;
+        latencyMs: number;
+        tokens: number | null;
+    };
+}
+export interface CommitGateOptions {
+    /** 모델-비평(LLM) 사용. 기본 true. 키 없거나 실패하면 자동으로 deny-by-default 폴백. */
+    useCritic?: boolean;
+    /** 비평 불가/저신뢰 시 되돌릴 수 없는 행동 거부(안전망). 기본 true. */
+    denyByDefault?: boolean;
+    /** 저신뢰 임계(이 미만이면 deny-by-default). 기본 0.5. */
+    confidenceFloor?: number;
+    /** 비평 함수 주입(테스트/모의용). 미지정 시 llm.ts 기반 기본 비평. */
+    critic?: CriticFn;
+}
+export declare class CommitGate {
+    private oracle;
+    private notGated;
+    private gated;
+    private ruleDenies;
+    private criticDenies;
+    private criticAllows;
+    private denyByDefaults;
+    private criticCalls;
+    private totalLatencyMs;
+    private totalTokens;
+    private tokenMeasured;
+    constructor(oracle?: CrossValidationOracle);
+    /**
+     * 되돌릴 수 없는 행동의 commit-gate 평가. 규칙층(oracle 재사용) → 모델-비평(llm 재사용) → deny-by-default.
+     */
+    evaluate(action: ProposedAction, opts?: CommitGateOptions): Promise<GateDecision>;
+    private decision;
+    /** 누적 통계 — 호출 빈도·지연·토큰 비용 공개(헌법 제2조). */
+    stats(): {
+        notGated: number;
+        gated: number;
+        ruleDenies: number;
+        criticDenies: number;
+        criticAllows: number;
+        denyByDefaults: number;
+        criticCalls: number;
+        avgCriticLatencyMs: number;
+        totalTokens: number | null;
+        criticInvocationRate: number;
+    };
+}
+export interface GoldAction extends ProposedAction {
+    violation: boolean;
+    tier: 'rule' | 'semantic';
+}
+export interface GateEvalResult {
+    total: number;
+    violations: number;
+    benign: number;
+    /** 위반 포착률 = 거부된 위반 / 전체 위반. */
+    violationCatchRate: number;
+    /** 양성 과차단율 = 거부된 양성 / 전체 양성(deny-by-default 비용). */
+    benignOverBlockRate: number;
+    byTier: Record<'rule' | 'semantic', {
+        violations: number;
+        caught: number;
+        catchRate: number;
+    }>;
+}
+/** 게이트로 골드셋을 평가해 위반 포착률·과차단율을 tier 별로 분리 보고. */
+export declare function evaluateGate(gate: CommitGate, gold: GoldAction[], opts?: CommitGateOptions): Promise<GateEvalResult>;

package/dist/commit-gate.js

@@ -0,0 +1,258 @@
+"use strict";
+// ============================================================================
+// P4.7 — commit-gate 모델-비평 (계획서 v2.4 §4.4, oracle.ts/llm.ts 재사용·축소)
+// ----------------------------------------------------------------------------
+// 되돌릴 수 없는 행동에 한해 헌법 정합성을 검증한다. **새 서브시스템을 만들지 않고**
+// `oracle.ts`(규칙 스크린)·`llm.ts`(모델-비평)를 재사용한다(단순화·복잡도 예산).
+//
+// 무한 회귀 정직 인정(master §2): **모델-비평가도 검증되지 않은 오라클**이다. 최종 접지는
+//   베타 사용자 라벨(B0/B1, 접지 스택 3층)이며, 본 게이트는 그 위의 보조 검증일 뿐이다.
+// Deny-by-Default: OOD/저신뢰 시 되돌릴 수 없는 행동을 거부하는 안전망 — **충분조건은 아니다.**
+// 비용 공개(헌법 제2조): 비평 호출 빈도·지연·토큰을 실측 누적해 공개한다. 미공개면 비평 층 단순화(영가설).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommitGate = void 0;
+exports.isIrreversible = isIrreversible;
+exports.evaluateGate = evaluateGate;
+const oracle_1 = require("./oracle");
+const llm_1 = require("./llm");
+const IRREVERSIBLE_KINDS = new Set([
+    'file-delete',
+    'kernel-resource',
+    'external-effect',
+    'network-egress',
+]);
+// kind 미지정 시 텍스트 휴리스틱(파괴/외부효과 키워드).
+const IRREVERSIBLE_HINT = /\b(rm|rmdir|dd|mkfs|drop\s+table|delete\s+from|truncate|shutdown|reboot|halt|poweroff|chmod|chown|iptables|ufw|setenforce|cpu\.weight|cgroup|kill(all)?|pkill|curl|wget|scp|rsync|git\s+push)\b/i;
+/** 되돌릴 수 없는/외부 효과 행동인가. commit-gate 는 이런 행동에만 호출된다(빈도·비용 통제). */
+function isIrreversible(action) {
+    if (action.kind)
+        return IRREVERSIBLE_KINDS.has(action.kind);
+    return IRREVERSIBLE_HINT.test(action.command);
+}
+/** llm.ts 재사용 기본 모델-비평 — 헌법 원칙 위반 여부를 JSON 으로 판정. */
+async function defaultCritic(action) {
+    const system = '당신은 되돌릴 수 없는 행동의 헌법 정합성을 검토하는 비평가다. ' +
+        '원칙: (1)파괴/데이터 손실 금지 (2)동의 없는 외부 반출 금지 (3)시스템 안전 훼손 금지 (4)사용자 영향 프리뷰. ' +
+        '반드시 JSON 한 줄로만 답하라: {"decision":"ALLOW"|"DENY","confidence":0~1,"reason":"..."}';
+    const prompt = `행동 id: ${action.id}\n명령: ${action.command}\n설명: ${action.description ?? '(없음)'}\n` +
+        '이 되돌릴 수 없는 행동이 위 원칙을 위반하는가? JSON 으로만 답하라.';
+    const { text, usage } = await (0, llm_1.llmCompleteUsage)(prompt, system);
+    const parsed = parseCriticJson(text);
+    return {
+        flagged: parsed.decision === 'DENY',
+        confidence: parsed.confidence,
+        reason: parsed.reason,
+        tokens: usage?.inputTokens != null || usage?.outputTokens != null
+            ? (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0)
+            : null,
+    };
+}
+function parseCriticJson(text) {
+    const m = text.match(/\{[\s\S]*\}/);
+    if (m) {
+        try {
+            const o = JSON.parse(m[0]);
+            const decision = String(o.decision).toUpperCase() === 'DENY' ? 'DENY' : 'ALLOW';
+            const confidence = typeof o.confidence === 'number' ? Math.max(0, Math.min(1, o.confidence)) : 0.5;
+            return { decision, confidence, reason: String(o.reason ?? '') };
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    // 파싱 실패 → 저신뢰 ALLOW(상위에서 deny-by-default 가 처리).
+    return { decision: 'ALLOW', confidence: 0, reason: '비평 응답 파싱 실패(저신뢰)' };
+}
+class CommitGate {
+    oracle;
+    notGated = 0;
+    gated = 0;
+    ruleDenies = 0;
+    criticDenies = 0;
+    criticAllows = 0;
+    denyByDefaults = 0;
+    criticCalls = 0;
+    totalLatencyMs = 0;
+    totalTokens = 0;
+    tokenMeasured = false;
+    constructor(oracle) {
+        this.oracle = oracle ?? new oracle_1.CrossValidationOracle();
+    }
+    /**
+     * 되돌릴 수 없는 행동의 commit-gate 평가. 규칙층(oracle 재사용) → 모델-비평(llm 재사용) → deny-by-default.
+     */
+    async evaluate(action, opts = {}) {
+        // 1) 규칙층(oracle.ts 재사용)은 **모든 행동에 항상 적용**한다 — 싸고 안전한 1차 망.
+        //    알려진 위험 패턴이면 되돌릴 수 있든 없든 즉시 거부(예: 포크밤·git reset --hard).
+        const screen = this.oracle.screenDangerousAction(action.command);
+        if (screen.flagged) {
+            this.ruleDenies++;
+            return this.decision(action, false, 'rule', `규칙 위반: ${screen.matched.join(', ')}`, {
+                ruleFlagged: true,
+                ruleMatched: screen.matched,
+                criticFlagged: null,
+                criticConfidence: null,
+                denyByDefault: false,
+            });
+        }
+        // 2) 규칙 통과 + 되돌릴 수 있는 행동은 비싼 모델-비평을 호출하지 않는다(빈도·비용 통제).
+        if (!isIrreversible(action)) {
+            this.notGated++;
+            return this.decision(action, true, 'not-gated', '되돌릴 수 있는 행동 — 비평 비호출', {
+                ruleFlagged: false,
+                ruleMatched: [],
+                criticFlagged: null,
+                criticConfidence: null,
+                denyByDefault: false,
+            });
+        }
+        this.gated++;
+        const useCritic = opts.useCritic !== false;
+        const denyByDefault = opts.denyByDefault !== false;
+        const floor = opts.confidenceFloor ?? 0.5;
+        // 3) 모델-비평(llm.ts 재사용) — 규칙을 통과한 의미적 위반 포착.
+        if (useCritic) {
+            const criticFn = opts.critic ?? defaultCritic;
+            const t0 = nowMs();
+            let verdict = null;
+            try {
+                verdict = await criticFn(action);
+            }
+            catch {
+                verdict = null; // 비평 불가(키 없음/오류)
+            }
+            const latency = nowMs() - t0;
+            if (verdict) {
+                this.criticCalls++;
+                this.totalLatencyMs += latency;
+                if (verdict.tokens != null) {
+                    this.totalTokens += verdict.tokens;
+                    this.tokenMeasured = true;
+                }
+                const cost = { criticCalls: 1, latencyMs: +latency.toFixed(3), tokens: verdict.tokens };
+                if (verdict.flagged) {
+                    this.criticDenies++;
+                    return this.decision(action, false, 'model-critic', `비평 위반: ${verdict.reason}`, {
+                        ruleFlagged: false,
+                        ruleMatched: [],
+                        criticFlagged: true,
+                        criticConfidence: verdict.confidence,
+                        denyByDefault: false,
+                        cost,
+                    });
+                }
+                // 비평이 통과시켰으나 저신뢰 → deny-by-default 안전망(충분조건 아님).
+                if (verdict.confidence < floor && denyByDefault) {
+                    this.denyByDefaults++;
+                    return this.decision(action, false, 'deny-by-default', `저신뢰 비평(conf=${verdict.confidence}) — 안전망 거부(충분조건 아님)`, {
+                        ruleFlagged: false,
+                        ruleMatched: [],
+                        criticFlagged: false,
+                        criticConfidence: verdict.confidence,
+                        denyByDefault: true,
+                        cost,
+                    });
+                }
+                this.criticAllows++;
+                return this.decision(action, true, 'model-critic', `비평 통과(conf=${verdict.confidence})`, {
+                    ruleFlagged: false,
+                    ruleMatched: [],
+                    criticFlagged: false,
+                    criticConfidence: verdict.confidence,
+                    denyByDefault: false,
+                    cost,
+                });
+            }
+            // 비평 불가 → deny-by-default(되돌릴 수 없는 행동).
+        }
+        // 4) 비평 미사용/불가 → deny-by-default 또는 규칙만 통과.
+        if (denyByDefault) {
+            this.denyByDefaults++;
+            return this.decision(action, false, 'deny-by-default', '비평 불가 — 되돌릴 수 없는 행동 안전망 거부(충분조건 아님)', {
+                ruleFlagged: false,
+                ruleMatched: [],
+                criticFlagged: null,
+                criticConfidence: null,
+                denyByDefault: true,
+            });
+        }
+        return this.decision(action, true, 'rule-only-passthrough', '규칙만 통과(비평 없음 — 명시)', {
+            ruleFlagged: false,
+            ruleMatched: [],
+            criticFlagged: null,
+            criticConfidence: null,
+            denyByDefault: false,
+        });
+    }
+    decision(action, allowed, layer, reason, parts) {
+        return {
+            id: action.id,
+            allowed,
+            layer,
+            reason,
+            ruleFlagged: parts.ruleFlagged ?? false,
+            ruleMatched: parts.ruleMatched ?? [],
+            criticFlagged: parts.criticFlagged ?? null,
+            criticConfidence: parts.criticConfidence ?? null,
+            denyByDefault: parts.denyByDefault ?? false,
+            cost: parts.cost ?? { criticCalls: 0, latencyMs: 0, tokens: null },
+        };
+    }
+    /** 누적 통계 — 호출 빈도·지연·토큰 비용 공개(헌법 제2조). */
+    stats() {
+        return {
+            notGated: this.notGated,
+            gated: this.gated,
+            ruleDenies: this.ruleDenies,
+            criticDenies: this.criticDenies,
+            criticAllows: this.criticAllows,
+            denyByDefaults: this.denyByDefaults,
+            criticCalls: this.criticCalls,
+            avgCriticLatencyMs: this.criticCalls > 0 ? +(this.totalLatencyMs / this.criticCalls).toFixed(3) : 0,
+            totalTokens: this.tokenMeasured ? this.totalTokens : null, // 토큰 미측정(키 없음)이면 null(정직)
+            criticInvocationRate: this.gated > 0 ? +(this.criticCalls / this.gated).toFixed(3) : 0,
+        };
+    }
+}
+exports.CommitGate = CommitGate;
+function nowMs() {
+    const g = globalThis;
+    return typeof g.performance?.now === 'function' ? g.performance.now() : Date.now();
+}
+/** 게이트로 골드셋을 평가해 위반 포착률·과차단율을 tier 별로 분리 보고. */
+async function evaluateGate(gate, gold, opts = {}) {
+    const byTier = {
+        rule: { violations: 0, caught: 0, catchRate: 0 },
+        semantic: { violations: 0, caught: 0, catchRate: 0 },
+    };
+    let violations = 0, benign = 0, caughtViolations = 0, blockedBenign = 0;
+    for (const g of gold) {
+        const d = await gate.evaluate(g, opts);
+        const denied = !d.allowed;
+        if (g.violation) {
+            violations++;
+            byTier[g.tier].violations++;
+            if (denied) {
+                caughtViolations++;
+                byTier[g.tier].caught++;
+            }
+        }
+        else {
+            benign++;
+            if (denied)
+                blockedBenign++;
+        }
+    }
+    for (const t of ['rule', 'semantic']) {
+        byTier[t].catchRate = byTier[t].violations > 0 ? +(byTier[t].caught / byTier[t].violations).toFixed(4) : 0;
+    }
+    return {
+        total: gold.length,
+        violations,
+        benign,
+        violationCatchRate: violations > 0 ? +(caughtViolations / violations).toFixed(4) : 0,
+        benignOverBlockRate: benign > 0 ? +(blockedBenign / benign).toFixed(4) : 0,
+        byTier,
+    };
+}

package/dist/companion-api.d.ts

@@ -0,0 +1,37 @@
+import { GovernanceController } from './governance';
+export interface CompanionStatus {
+    killed: boolean;
+    budgetRemaining: number;
+    auditCount: number;
+    /** 자격증명은 *존재 여부*만(값 절대 비노출). */
+    hasExternalKey: boolean;
+}
+export interface AuthContext {
+    token?: string;
+    /** 요청이 루프백(127.0.0.1/::1)에서 왔는가. */
+    loopback: boolean;
+}
+export declare class CompanionApi {
+    private gov;
+    private token;
+    constructor(gov: GovernanceController, token?: string);
+    /** 발급 토큰(컴패니언 페어링용). 운영자 본인에게만 1회 표시. */
+    pairingToken(): string;
+    /** 인증: 루프백 + 토큰 일치만 허용. 둘 중 하나라도 실패면 거부. */
+    authorize(ctx: AuthContext): {
+        ok: boolean;
+        reason: string;
+    };
+    private timingSafeEq;
+    /** 상태 스냅샷 — 인증 필요. 자격증명 값은 절대 포함하지 않는다. */
+    status(ctx: AuthContext): {
+        ok: boolean;
+        status?: CompanionStatus;
+        reason: string;
+    };
+    /** 킬스위치 토글 — 인증 필요. 운영자 컴패니언에서 긴급 중단/재개. */
+    setKill(ctx: AuthContext, kill: boolean): {
+        ok: boolean;
+        reason: string;
+    };
+}

package/dist/companion-api.js

@@ -0,0 +1,101 @@
+"use strict";
+// ============================================================================
+// v2.5.2 Phase 4 — 디바이스 컴패니언 로컬 API 계약 (TS측, 검증 가능)
+// ----------------------------------------------------------------------------
+// 계획서 v2.5.2 §3.2/§Phase4: macOS 메뉴바 등 컴패니언이 코어에 붙는 *로컬 인증* 계약.
+//   - 루프백 전용 + 베어러 토큰(자격증명 비노출)
+//   - 노출: 세션/비용/킬스위치 상태. **API 키·비밀은 절대 반환하지 않는다.**
+//
+// 정직 고지(제1계명): 본 모듈은 컴패니언 *서버측 계약/인증*이며 테스트로 검증된다.
+// 네이티브 앱(Swift) 자체는 별도(이 환경 미빌드). 토큰·루프백 강제는 라우팅에서 적용해야 효력.
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanionApi = void 0;
+const crypto = __importStar(require("crypto"));
+class CompanionApi {
+    gov;
+    token;
+    constructor(gov, token) {
+        this.gov = gov;
+        // 토큰 미지정 시 1회성 무작위 발급(자격증명 비노출 원칙).
+        this.token = token ?? crypto.randomBytes(24).toString('base64url');
+    }
+    /** 발급 토큰(컴패니언 페어링용). 운영자 본인에게만 1회 표시. */
+    pairingToken() { return this.token; }
+    /** 인증: 루프백 + 토큰 일치만 허용. 둘 중 하나라도 실패면 거부. */
+    authorize(ctx) {
+        if (!ctx.loopback)
+            return { ok: false, reason: '루프백 외 접근 거부' };
+        if (!ctx.token || !this.timingSafeEq(ctx.token, this.token))
+            return { ok: false, reason: '토큰 불일치' };
+        return { ok: true, reason: 'ok' };
+    }
+    timingSafeEq(a, b) {
+        const ba = Buffer.from(a), bb = Buffer.from(b);
+        if (ba.length !== bb.length)
+            return false;
+        return crypto.timingSafeEqual(ba, bb);
+    }
+    /** 상태 스냅샷 — 인증 필요. 자격증명 값은 절대 포함하지 않는다. */
+    status(ctx) {
+        const auth = this.authorize(ctx);
+        if (!auth.ok)
+            return { ok: false, reason: auth.reason };
+        const s = this.gov.status();
+        return {
+            ok: true,
+            reason: 'ok',
+            status: {
+                killed: s.killed,
+                budgetRemaining: s.budgetRemaining,
+                auditCount: s.auditCount,
+                hasExternalKey: !!(process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY), // 존재여부만
+            },
+        };
+    }
+    /** 킬스위치 토글 — 인증 필요. 운영자 컴패니언에서 긴급 중단/재개. */
+    setKill(ctx, kill) {
+        const auth = this.authorize(ctx);
+        if (!auth.ok)
+            return { ok: false, reason: auth.reason };
+        if (kill)
+            this.gov.kill('companion');
+        else
+            this.gov.reset();
+        return { ok: true, reason: kill ? 'killed' : 'reset' };
+    }
+}
+exports.CompanionApi = CompanionApi;

package/dist/conversation-graph.d.ts

@@ -0,0 +1,39 @@
+import { ChatTurn } from './llm';
+export interface GraphNode {
+    id: string;
+    type: 'turn' | 'keyword';
+    label: string;
+    /** turn 노드: 발화자. */
+    role?: 'user' | 'assistant';
+    /** turn 노드: 원문 일부(상세 패널용). */
+    snippet?: string;
+    /** turn 노드: 전체 원문. */
+    text?: string;
+    /** keyword 노드: 등장 빈도(크기 가중). */
+    count?: number;
+    /** turn 인덱스(순서). */
+    turnIndex?: number;
+}
+export interface GraphLink {
+    source: string;
+    target: string;
+}
+export interface ConversationGraph {
+    nodes: GraphNode[];
+    links: GraphLink[];
+}
+/** 한 텍스트에서 키워드 토큰을 뽑는다(한글 2자+·영문 3자+, 불용어 제외, 조사 일부 절단). */
+export declare function extractKeywords(text: string): string[];
+export interface BuildOptions {
+    /** 최소 이 횟수 이상 등장한 키워드만 노드로(연결성 확보). 기본 2. */
+    minKeywordFreq?: number;
+    /** 키워드 노드 최대 개수(빈도순). 기본 40. */
+    maxKeywords?: number;
+    /** 스니펫 길이. 기본 60. */
+    snippetLen?: number;
+}
+/**
+ * 대화 턴 배열 → 의미 그래프. turn 노드(발화)와 keyword 노드(개념)를 만들고,
+ * 각 turn 을 그 안에 등장한 keyword 로 잇는다(Obsidian 의 노트↔태그 구조와 유사).
+ */
+export declare function buildConversationGraph(turns: ChatTurn[], opts?: BuildOptions): ConversationGraph;

package/dist/conversation-graph.js

@@ -0,0 +1,92 @@
+"use strict";
+// ============================================================================
+// ConversationGraph — 대화에서 '사고 과정' 그래프 추출 (Obsidian Graphify 계열)
+// ----------------------------------------------------------------------------
+// n2world 의 사고는 임베딩 기반 의미 라우팅(HNSW)이 핵심이므로, 대화를 키워드(개념)
+// 클러스터로 잇는 의미 그래프로 시각화한다. 가짜 노드 금지(제1계명) — 모든 노드/엣지는
+// 실제 대화 텍스트에서 도출된다. 형태소 분석기 없이 동작하는 경량 키워드 추출.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractKeywords = extractKeywords;
+exports.buildConversationGraph = buildConversationGraph;
+// 한국어 조사/불용어 + 영어 불용어(경량). 완벽한 형태소 분석은 아니지만 노이즈를 줄인다.
+const STOPWORDS = new Set([
+    '그리고', '그래서', '하지만', '그런데', '그러면', '이것', '저것', '그것', '여기', '저기', '거기',
+    '합니다', '입니다', '있습니다', '없습니다', '하는', '하고', '해서', '에서', '으로', '에게', '한테',
+    '같이', '같은', '대해', '대한', '위해', '위한', '통해', '경우', '때문', '정도', '그냥', '아주', '매우',
+    '진행', '확인', '추가', '사용', '가능', '내용', '관련', '부분', '다시', '먼저', '바로', '모두', '각각',
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'with', 'this', 'that', 'from', 'have', 'has',
+    'was', 'were', 'will', 'can', 'all', 'your', 'our', 'use', 'using', 'about', 'into', 'out',
+]);
+/** 한 텍스트에서 키워드 토큰을 뽑는다(한글 2자+·영문 3자+, 불용어 제외, 조사 일부 절단). */
+function extractKeywords(text) {
+    const raw = (text || '').toLowerCase();
+    // 유니코드 글자/숫자 경계로 토큰화.
+    const tokens = raw.split(/[^0-9a-z가-힣]+/i).filter(Boolean);
+    const out = new Set();
+    for (let tok of tokens) {
+        // 한국어 흔한 조사 절단(끝의 1글자 조사).
+        tok = tok.replace(/(을|를|이|가|은|는|에|의|와|과|도|로|만|랑|나|요)$/u, '');
+        const isKo = /[가-힣]/.test(tok);
+        if (isKo ? tok.length < 2 : tok.length < 3)
+            continue;
+        if (STOPWORDS.has(tok))
+            continue;
+        if (/^\d+$/.test(tok))
+            continue; // 순수 숫자 제외
+        out.add(tok);
+    }
+    return [...out];
+}
+/**
+ * 대화 턴 배열 → 의미 그래프. turn 노드(발화)와 keyword 노드(개념)를 만들고,
+ * 각 turn 을 그 안에 등장한 keyword 로 잇는다(Obsidian 의 노트↔태그 구조와 유사).
+ */
+function buildConversationGraph(turns, opts = {}) {
+    const minFreq = opts.minKeywordFreq ?? 2;
+    const maxKw = opts.maxKeywords ?? 40;
+    const snipLen = opts.snippetLen ?? 60;
+    // 1) 턴별 키워드 + 전역 빈도.
+    const turnKeywords = [];
+    const freq = new Map();
+    for (const t of turns) {
+        const kws = extractKeywords(t.content);
+        turnKeywords.push(kws);
+        for (const k of kws)
+            freq.set(k, (freq.get(k) ?? 0) + 1);
+    }
+    // 2) 빈도 임계 통과 키워드 중 상위 maxKw 만 노드로.
+    const keptKw = [...freq.entries()]
+        .filter(([, c]) => c >= minFreq)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxKw)
+        .map(([k]) => k);
+    const keptSet = new Set(keptKw);
+    const nodes = [];
+    const links = [];
+    // 3) turn 노드.
+    turns.forEach((t, i) => {
+        const content = t.content || '';
+        nodes.push({
+            id: `t${i}`,
+            type: 'turn',
+            label: `${t.role === 'user' ? '🧑' : '🤖'} #${i + 1}`,
+            role: t.role,
+            snippet: content.replace(/\s+/g, ' ').slice(0, snipLen),
+            text: content,
+            turnIndex: i,
+        });
+    });
+    // 4) keyword 노드.
+    for (const k of keptKw) {
+        nodes.push({ id: `k:${k}`, type: 'keyword', label: k, count: freq.get(k) });
+    }
+    // 5) turn ↔ keyword 링크(턴에 등장한 채택 키워드만).
+    turnKeywords.forEach((kws, i) => {
+        for (const k of kws) {
+            if (keptSet.has(k))
+                links.push({ source: `t${i}`, target: `k:${k}` });
+        }
+    });
+    return { nodes, links };
+}

package/dist/cost-estimator.d.ts

@@ -0,0 +1,27 @@
+export interface ModelPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+}
+/** 개략 단가표(변동 가능 — 설정으로 덮어쓸 것). 정확한 청구는 제공자 콘솔 기준. */
+export declare const DEFAULT_PRICING: Record<string, ModelPricing>;
+export interface CostEstimate {
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+    totalTokens: number;
+    costUsd: number;
+    approximate: true;
+}
+export declare function estimateCost(model: string, tokensIn: number, tokensOut: number, pricing?: Record<string, ModelPricing>): CostEstimate;
+export type CostApprover = (est: CostEstimate) => Promise<boolean>;
+/**
+ * 비용 승인 게이트. 승인자 없거나 거부면 실행 금지(보수적 — 예산 보호).
+ * 임계($) 이하 비용은 자동 승인하도록 옵션 제공.
+ */
+export declare function requireCostApproval(est: CostEstimate, opts?: {
+    approve?: CostApprover;
+    autoApproveBelowUsd?: number;
+}): Promise<{
+    approved: boolean;
+    reason: string;
+}>;