@n2world/orchestrator 1.1.0

package/dist/knowledge-graph.js

@@ -0,0 +1,156 @@
+"use strict";
+// ============================================================================
+// P2 — 자가연결 지식 그래프 파서 + 관계 평가 (계획서 v2.4 §4.5)
+// ----------------------------------------------------------------------------
+// 축적된 지식(.md) 항목 간 관계를 추출해 그래프로 잇는다. 세 종류의 관계:
+//   - reference  : 명시적 참조 — `[[id]]` 위키링크 · 마크다운 링크 · 다른 항목 파일명 언급
+//   - dependency : 의존 — 의존 큐(먼저 주입/선행/requires/depends…)와 함께 다른 항목 언급
+//   - similarity : 유사 — 해시 임베딩 코사인 유사도 ≥ 임계값(상위 K)
+//
+// 정직 고지(구현강도 상한): reference/dependency 는 **명시적 신호(파일명/위키링크/큐 단어)** 에
+//   기반한 규칙 추출이다(LLM 의미 추론 아님). 깔끔히 구조화된 지식(파일명 상호참조)에서 정확하며,
+//   자유 산문 일반으로 일반화하지 않는다. similarity 는 P1 과 동일한 **얕은 해시 임베딩** 기반.
+// 평가는 합성 코퍼스의 동어반복을 막기 위해 **실제 골드셋과 분리 보고**한다(§2.3).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKnowledgeGraph = parseKnowledgeGraph;
+exports.evaluateRelations = evaluateRelations;
+const text_embedding_1 = require("./text-embedding");
+// 의존 큐(한/영). 라인 단위로 이 단어와 다른 항목 언급이 함께 있으면 dependency.
+const DEPENDENCY_CUE = /(먼저\s*(주입|읽|통독|실행|선행)|선행\s*조건|필수\s*선행|prerequisite|pre-?req|\brequires?\b|\bdepends?\s+on\b|의존(?:한다|성|함)?|에\s*의존|기반(?:으로|한다))/i;
+const WIKILINK = /\[\[([^\]\[]+)\]\]/g;
+const MD_LINK = /\]\(([^)]+)\)/g;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** id 후보 해석: 정확 id, 확장자 보정(.md), basename 일치를 시도. 없으면 null. */
+function resolveId(mention, idSet) {
+    const m = mention.trim();
+    if (idSet.has(m))
+        return m;
+    if (idSet.has(m + '.md'))
+        return m + '.md';
+    const base = m.split(/[\\/]/).pop() ?? m;
+    if (idSet.has(base))
+        return base;
+    if (idSet.has(base + '.md'))
+        return base + '.md';
+    return null;
+}
+/**
+ * 지식 항목 배열에서 관계 그래프를 추출한다. 자기참조(X→X)는 제외, 같은 (source,target,type)는 1회.
+ */
+function parseKnowledgeGraph(items, opts = {}) {
+    const threshold = opts.similarityThreshold ?? 0.5;
+    const topK = opts.similarityTopK ?? 3;
+    const includeSim = opts.includeSimilarity ?? true;
+    const nodes = items.map((it) => it.id);
+    const idSet = new Set(nodes);
+    // 파일명 언급 탐지를 위해 id 별 정규식(자기 자신 제외는 호출부에서).
+    const idPatterns = nodes.map((id) => ({ id, re: new RegExp(escapeRegExp(id), 'i') }));
+    const seen = new Set(); // dedupe key: src→tgt|type
+    const edges = [];
+    const addEdge = (source, target, type, weight) => {
+        if (source === target)
+            return;
+        const key = `${source}->${target}|${type}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        edges.push({ source, target, type, weight });
+    };
+    // ── reference / dependency: 라인 단위 명시 신호 ──
+    for (const item of items) {
+        const lines = item.content.split(/\r?\n/);
+        for (const line of lines) {
+            const isDep = DEPENDENCY_CUE.test(line);
+            // 위키링크 [[X]] → reference(큐 있으면 dependency)
+            for (const m of line.matchAll(WIKILINK)) {
+                const tgt = resolveId(m[1], idSet);
+                if (tgt)
+                    addEdge(item.id, tgt, isDep ? 'dependency' : 'reference', 1);
+            }
+            // 마크다운 링크 ](X)
+            for (const m of line.matchAll(MD_LINK)) {
+                const tgt = resolveId(m[1], idSet);
+                if (tgt)
+                    addEdge(item.id, tgt, isDep ? 'dependency' : 'reference', 1);
+            }
+            // 파일명(=다른 항목 id) 직접 언급
+            for (const { id, re } of idPatterns) {
+                if (id === item.id)
+                    continue;
+                if (re.test(line))
+                    addEdge(item.id, id, isDep ? 'dependency' : 'reference', 1);
+            }
+        }
+    }
+    // ── similarity: 해시 임베딩 코사인 상위 K (무방향, canonical src<tgt) ──
+    if (includeSim && items.length > 1) {
+        const embs = items.map((it) => (0, text_embedding_1.textEmbedding)(it.content));
+        for (let i = 0; i < items.length; i++) {
+            const sims = [];
+            for (let j = 0; j < items.length; j++) {
+                if (i === j)
+                    continue;
+                const sim = (0, text_embedding_1.cosineSimilarity)(embs[i], embs[j]);
+                if (sim >= threshold)
+                    sims.push({ j, sim });
+            }
+            sims.sort((a, b) => b.sim - a.sim);
+            for (const { j, sim } of sims.slice(0, topK)) {
+                const a = items[i].id;
+                const b = items[j].id;
+                const [s, t] = a < b ? [a, b] : [b, a]; // canonical 무방향
+                addEdge(s, t, 'similarity', +sim.toFixed(4));
+            }
+        }
+    }
+    return { nodes, edges };
+}
+function ratio(num, den) {
+    return den > 0 ? +(num / den).toFixed(4) : null;
+}
+/**
+ * 예측 엣지 집합을 골드 라벨로 채점. 라벨된 (source,target,type) 쌍만 평가한다
+ * (열린세계 페널티 방지 — 라벨 외 엣지는 무시, 라벨된 음성으로 precision 측정).
+ * @param type 평가할 관계 종류(생략 시 'all' — 라벨 전체).
+ */
+function evaluateRelations(edges, gold, type) {
+    const predicted = new Set(edges.map((e) => `${e.source}->${e.target}|${e.type}`));
+    const labels = type ? gold.filter((g) => g.type === type) : gold;
+    let tp = 0, fp = 0, fn = 0, tn = 0, positives = 0;
+    for (const g of labels) {
+        const isPred = predicted.has(`${g.source}->${g.target}|${g.type}`);
+        if (g.present) {
+            positives++;
+            if (isPred)
+                tp++;
+            else
+                fn++;
+        }
+        else {
+            if (isPred)
+                fp++;
+            else
+                tn++;
+        }
+    }
+    const precision = ratio(tp, tp + fp);
+    const recall = ratio(tp, tp + fn);
+    const f1 = precision !== null && recall !== null && precision + recall > 0
+        ? +((2 * precision * recall) / (precision + recall)).toFixed(4)
+        : null;
+    return {
+        type: type ?? 'all',
+        labeled: labels.length,
+        positives,
+        tp,
+        fp,
+        fn,
+        tn,
+        precision,
+        recall,
+        f1,
+    };
+}

package/dist/llm.d.ts

@@ -0,0 +1,65 @@
+type ProviderId = 'anthropic' | 'google';
+export declare function askAgent(userInput: string, runShellCommand: (cmd: string) => Promise<string>): Promise<string>;
+/** 대화 메시지 한 턴(역할 + 텍스트). askAgentChat 가 히스토리로 유지한다. */
+export interface ChatTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * `askAgent` 의 **멀티턴(대화)** 버전. 호출자가 전체 히스토리를 넘기면 그 맥락 위에서 답한다.
+ * 도구(executeTerminalCommand)는 동일하게 제공된다(샌드박스 실행). 단발 askAgent 와 달리
+ * 이전 대화를 기억하므로 CLI `chat` 같은 연속 대화에 쓴다. 키 미설정 시 안내 문자열을 반환.
+ */
+/** 선택적 브라우저 도구 브리지(BrowserAgent.act 형태). 주어지면 controlBrowser 도구가 추가된다. */
+export type BrowserBridge = (action: {
+    verb: string;
+    url?: string;
+    ref?: string;
+    text?: string;
+    query?: string;
+}) => Promise<string>;
+export declare function askAgentChat(history: ChatTurn[], runShellCommand: (cmd: string) => Promise<string>, opts?: {
+    browser?: BrowserBridge;
+}): Promise<string>;
+/**
+ * 도구 없는 단발 텍스트 생성(구조화 후보 생성 등에 사용). 제공자 추상화 위에서 동작.
+ * 키 미설정 시 명확히 throw 한다.
+ */
+export declare function llmComplete(prompt: string, system?: string): Promise<string>;
+/**
+ * `llmComplete` 와 동일 경로지만 **제공자 실 토큰 usage** 도 반환한다(P3 토큰 절감 실측용).
+ * 새 제공자 경로를 만들지 않고 기존 generateText 경로를 재사용한다(단순화). 키 미설정 시 throw.
+ */
+export declare function llmCompleteUsage(prompt: string, system?: string): Promise<{
+    text: string;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    } | null;
+    provider: ProviderId;
+}>;
+/**
+ * 비전 그라운딩(#2 폴백) — 스크린샷에서 설명에 해당하는 요소의 정규화 좌표(0~1)를 찾는다.
+ * 멀티모달 모델(Gemini/Claude) 사용. 못 찾거나 키 없으면 null. 비용이 크므로 DOM(#3) 실패 시만.
+ */
+export declare function locateOnScreen(screenshotBase64: string, description: string): Promise<{
+    x: number;
+    y: number;
+} | null>;
+/** 현재 활성 제공자/모델 정보 (대시보드·진단용). */
+export declare function activeLlmInfo(): {
+    provider: ProviderId | null;
+    model: string | null;
+};
+export type LlmFetch = (url: string, init: any) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<any>;
+}>;
+/** 로컬(Ollama) 모델이 설정되었는가. OLLAMA_MODEL 명시 시에만 true(정직). */
+export declare function localLlmConfigured(): boolean;
+/** 로컬(Ollama) 멀티턴 호출. 미설정/미가동 시 명확히 throw(가짜 성공 금지). */
+export declare function localChat(history: ChatTurn[], system?: string, fetchFn?: LlmFetch): Promise<string>;
+/** 외부 제공자 식별(없으면 null). Tier 라우팅에서 외부 가용성 판단에 사용. */
+export declare function externalProviderId(): ProviderId | null;
+export {};

package/dist/llm.js

@@ -0,0 +1,357 @@
+"use strict";
+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.askAgent = askAgent;
+exports.askAgentChat = askAgentChat;
+exports.llmComplete = llmComplete;
+exports.llmCompleteUsage = llmCompleteUsage;
+exports.locateOnScreen = locateOnScreen;
+exports.activeLlmInfo = activeLlmInfo;
+exports.localLlmConfigured = localLlmConfigured;
+exports.localChat = localChat;
+exports.externalProviderId = externalProviderId;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+// Load env variables from multiple potential locations
+dotenv.config();
+dotenv.config({ path: path.join(__dirname, '..', '.env') });
+dotenv.config({ path: path.join(__dirname, '..', '..', '..', '.env') });
+// ============================================================================
+// 제공자 추상화 (Provider Abstraction)
+// ----------------------------------------------------------------------------
+// llm.ts 는 더 이상 특정 제공자(@ai-sdk/google)에 직접 종속되지 않는다.
+// LLM_PROVIDER 환경변수(anthropic|google) 또는 존재하는 키로 자동 선택하며,
+// Vercel AI SDK 의 제공자-중립 generateText() 인터페이스 위에서 동작한다.
+// 제공자 패키지는 "동적 import" 하므로, 한쪽만 설치돼 있어도 빌드가 깨지지 않는다.
+// ============================================================================
+const ANTHROPIC_KEY = process.env.ANTHROPIC_API_KEY;
+const GEMINI_KEY = process.env.GEMINI_API_KEY;
+const AGENT_NAME = process.env.AGENT_NAME || 'Ethan';
+function isUsable(key) {
+    return !!key && key.trim() !== '' && !key.startsWith('YOUR_');
+}
+/** LLM_PROVIDER 우선, 없으면 사용 가능한 키 기준으로 제공자 결정. */
+function resolveProvider() {
+    const explicit = (process.env.LLM_PROVIDER || '').toLowerCase();
+    if (explicit === 'anthropic' && isUsable(ANTHROPIC_KEY))
+        return 'anthropic';
+    if (explicit === 'google' && isUsable(GEMINI_KEY))
+        return 'google';
+    // 명시값이 없거나 해당 키가 없으면 가용한 것으로 폴백 (Anthropic 우선)
+    if (isUsable(ANTHROPIC_KEY))
+        return 'anthropic';
+    if (isUsable(GEMINI_KEY))
+        return 'google';
+    return null;
+}
+/** 선택된 제공자의 모델 객체를 동적 로드해 반환. */
+async function resolveModel(provider) {
+    // 간접 지정자(변수)로 동적 import → 미설치 제공자 패키지가 있어도 tsc 빌드가 깨지지 않는다.
+    if (provider === 'anthropic') {
+        const spec = '@ai-sdk/anthropic';
+        const { createAnthropic } = (await import(spec));
+        const anthropic = createAnthropic({ apiKey: ANTHROPIC_KEY });
+        return anthropic(process.env.ANTHROPIC_MODEL || 'claude-opus-4-8');
+    }
+    const spec = '@ai-sdk/google';
+    const { createGoogleGenerativeAI } = (await import(spec));
+    const google = createGoogleGenerativeAI({ apiKey: GEMINI_KEY });
+    return google(process.env.GEMINI_MODEL || 'gemini-flash-latest');
+}
+function systemPrompt() {
+    return `당신은 n2world (AnyWorld) 에이전트의 인공지능 두뇌인 '${AGENT_NAME}'입니다.
+사용자가 한글로 자연어 지시를 내리면, 필요에 따라 제공된 도구(executeTerminalCommand)를 사용하여 샌드박스 내부 터미널 명령어를 실행하고 결과를 분석하여 임무를 완수해야 합니다.
+중요: executeTerminalCommand 도구를 호출할 때는 반드시 'command' 인자 값에 실행할 터미널 명령어를 구체적인 문자열(예: 'dir', 'n2world bench' 등)로 지정해야 합니다. 절대 빈 문자열이나 빈 객체로 호출하지 마십시오.
+마지막에 수행한 작업의 결과를 깔끔한 한글 요약본으로 보고해 주세요.`;
+}
+/** 도구 호출 멀티스텝 상한. 행동형 과제(파일·디렉터리 생성 등)가 최종 요약까지 끝낼 여유를 준다. */
+const MAX_STEPS = 12;
+/**
+ * generateText 결과에서 **항상 비어 있지 않은** 최종 텍스트를 만든다.
+ * 빈 응답 원인(제1계명 정직 진단): 모델이 도구 호출로 단계를 소진하고 마지막 단계가 도구 호출이면
+ * `result.text` 가 ''(빈 문자열)가 된다(finishReason='tool-calls'). 아래 3단으로 방어한다:
+ *   1) 단계들에서 마지막 비지 않은 텍스트 회수
+ *   2) 도구 없이 "작업 요약" 한 번 더 생성(도구 메시지 맥락 전달)
+ *   3) 그래도 비면 사용자에게 다음 행동을 안내하는 비-빈 폴백(빈 말풍선 금지)
+ */
+async function finalizeText(result, model) {
+    if (result?.text && result.text.trim())
+        return result.text;
+    const steps = result?.steps ?? [];
+    for (let i = steps.length - 1; i >= 0; i--) {
+        if (steps[i]?.text && String(steps[i].text).trim())
+            return steps[i].text;
+    }
+    try {
+        const prior = result?.response?.messages ?? [];
+        const followup = await (0, ai_1.generateText)({
+            model,
+            messages: [
+                ...prior,
+                { role: 'user', content: '방금 수행한 작업의 결과를 한국어로 간결히 요약해 줘. 도구는 더 호출하지 말고 텍스트로만 답해.' },
+            ],
+        });
+        if (followup?.text && followup.text.trim())
+            return followup.text;
+    }
+    catch {
+        /* 요약 생성 실패 → 폴백 */
+    }
+    return '여러 단계로 작업을 수행했지만 최종 요약 생성에 실패했습니다(단계 한도/도구 호출 종료). "방금 한 작업 요약해줘" 또는 "계속"이라고 입력하시면 이어서 정리하겠습니다.';
+}
+async function askAgent(userInput, runShellCommand) {
+    const provider = resolveProvider();
+    if (!provider) {
+        return `[알림] LLM API 키가 설정되지 않았습니다.
+프로젝트 루트의 \`.env\` 파일에 \`ANTHROPIC_API_KEY\`(Claude) 또는 \`GEMINI_API_KEY\`(Gemini) 중 하나 이상을 입력해 주세요.
+(\`.env.example\` 을 복사해 사용하세요.)
+
+* 현재 입력된 명령어: "${userInput}"`;
+    }
+    let model;
+    try {
+        model = await resolveModel(provider);
+    }
+    catch (err) {
+        return `[에러] '${provider}' 제공자 패키지를 불러오지 못했습니다. 'npm install' 로 의존성을 설치했는지 확인하세요: ${err.message}`;
+    }
+    const messages = [{ role: 'user', content: userInput }];
+    try {
+        const result = await (0, ai_1.generateText)({
+            model,
+            system: systemPrompt(),
+            messages,
+            tools: {
+                executeTerminalCommand: {
+                    description: '노트북의 격리된 보안 샌드박스 내부에서 쉘 명령어를 실행합니다.',
+                    // AI SDK v6: 스키마 키는 inputSchema(과거 parameters). 잘못된 키면 스키마가 모델에
+                    // 전달되지 않아 command 가 undefined 로 호출된다(빈 응답·단계 낭비의 원인이었음).
+                    inputSchema: zod_1.z.object({
+                        command: zod_1.z.string().describe('실행할 터미널 명령어 (예: dir, n2world bench, node -v 등)'),
+                    }),
+                    execute: async (args) => {
+                        console.log(`[${AGENT_NAME} Tool Call] Received args:`, JSON.stringify(args));
+                        let command = args?.command;
+                        if (!command || command.trim() === '') {
+                            command = 'dir';
+                        }
+                        console.log(`[${AGENT_NAME} Tool Call] Command: ${command}`);
+                        return await runShellCommand(command);
+                    },
+                },
+            },
+            stopWhen: (0, ai_1.stepCountIs)(MAX_STEPS),
+        });
+        return await finalizeText(result, model);
+    }
+    catch (err) {
+        return `[에러] ${provider} LLM API 호출 중 오류가 발생했습니다: ${err.message}`;
+    }
+}
+async function askAgentChat(history, runShellCommand, opts = {}) {
+    const provider = resolveProvider();
+    if (!provider) {
+        return `[알림] LLM API 키가 설정되지 않았습니다. 프로젝트 루트 \`.env\` 에 ANTHROPIC_API_KEY 또는 GEMINI_API_KEY 를 입력하세요(.env.example 참고).`;
+    }
+    let model;
+    try {
+        model = await resolveModel(provider);
+    }
+    catch (err) {
+        return `[에러] '${provider}' 제공자 패키지를 불러오지 못했습니다('npm install' 확인): ${err.message}`;
+    }
+    const tools = {
+        executeTerminalCommand: {
+            description: '노트북의 격리된 보안 샌드박스 내부에서 쉘 명령어를 실행합니다.',
+            // AI SDK v6: inputSchema(과거 parameters). 잘못된 키면 command 가 undefined 로 옴.
+            inputSchema: zod_1.z.object({
+                command: zod_1.z.string().describe('실행할 터미널 명령어 (예: dir, node -v 등)'),
+            }),
+            execute: async (args) => {
+                let command = args?.command;
+                if (!command || command.trim() === '')
+                    command = 'dir';
+                return await runShellCommand(command);
+            },
+        },
+    };
+    // 선택적 브라우저 제어 도구(의미 DOM #3 + 자동화 #1). 보안 스크린은 브리지(BrowserAgent) 내부에서 적용.
+    if (opts.browser) {
+        tools.controlBrowser = {
+            description: '웹브라우저를 제어한다. verb: goto(url 이동)·read(현재 페이지의 [ref] 요소 목록)·click(ref)·type(ref,text)·extract(본문 텍스트)·back·' +
+                'vclick(비전 폴백 — read 로 안 잡히는 캔버스/이미지 요소를 query 설명으로 클릭). ' +
+                '먼저 goto/read 로 요소 ref 를 얻어 click/type 하고, read 에 없을 때만 vclick(query) 를 쓴다. 결제·구매·삭제·로그인 제출은 차단된다.',
+            inputSchema: zod_1.z.object({
+                verb: zod_1.z.enum(['goto', 'read', 'click', 'type', 'extract', 'back', 'vclick']),
+                url: zod_1.z.string().optional(),
+                ref: zod_1.z.string().optional(),
+                text: zod_1.z.string().optional(),
+                query: zod_1.z.string().optional(),
+            }),
+            execute: async (args) => opts.browser(args),
+        };
+    }
+    try {
+        const result = await (0, ai_1.generateText)({
+            model,
+            system: systemPrompt(),
+            messages: history.map((t) => ({ role: t.role, content: t.content })),
+            tools,
+            stopWhen: (0, ai_1.stepCountIs)(MAX_STEPS),
+        });
+        return await finalizeText(result, model);
+    }
+    catch (err) {
+        return `[에러] ${provider} LLM API 호출 중 오류: ${err.message}`;
+    }
+}
+/**
+ * 도구 없는 단발 텍스트 생성(구조화 후보 생성 등에 사용). 제공자 추상화 위에서 동작.
+ * 키 미설정 시 명확히 throw 한다.
+ */
+async function llmComplete(prompt, system) {
+    const provider = resolveProvider();
+    if (!provider) {
+        throw new Error('LLM API 키 미설정(.env 의 ANTHROPIC_API_KEY 또는 GEMINI_API_KEY).');
+    }
+    const model = await resolveModel(provider);
+    const result = await (0, ai_1.generateText)({
+        model,
+        system: system ?? '당신은 정확한 코드 수정 후보를 생성하는 도우미입니다.',
+        messages: [{ role: 'user', content: prompt }],
+    });
+    return result.text;
+}
+/**
+ * `llmComplete` 와 동일 경로지만 **제공자 실 토큰 usage** 도 반환한다(P3 토큰 절감 실측용).
+ * 새 제공자 경로를 만들지 않고 기존 generateText 경로를 재사용한다(단순화). 키 미설정 시 throw.
+ */
+async function llmCompleteUsage(prompt, system) {
+    const provider = resolveProvider();
+    if (!provider) {
+        throw new Error('LLM API 키 미설정(.env 의 ANTHROPIC_API_KEY 또는 GEMINI_API_KEY).');
+    }
+    const model = await resolveModel(provider);
+    const result = await (0, ai_1.generateText)({
+        model,
+        system: system ?? '당신은 지식을 압축·합성하는 도우미입니다.',
+        messages: [{ role: 'user', content: prompt }],
+    });
+    const u = result.usage ?? null;
+    const usage = u
+        ? { inputTokens: u.inputTokens ?? u.promptTokens ?? null, outputTokens: u.outputTokens ?? u.completionTokens ?? null }
+        : null;
+    return { text: result.text, usage, provider };
+}
+/**
+ * 비전 그라운딩(#2 폴백) — 스크린샷에서 설명에 해당하는 요소의 정규화 좌표(0~1)를 찾는다.
+ * 멀티모달 모델(Gemini/Claude) 사용. 못 찾거나 키 없으면 null. 비용이 크므로 DOM(#3) 실패 시만.
+ */
+async function locateOnScreen(screenshotBase64, description) {
+    const provider = resolveProvider();
+    if (!provider)
+        return null;
+    let model;
+    try {
+        model = await resolveModel(provider);
+    }
+    catch {
+        return null;
+    }
+    const prompt = `이 스크린샷에서 다음 UI 요소의 **중심 좌표**를 찾아줘: "${description}".\n` +
+        `좌표는 이미지 좌상단(0,0)~우하단(1,1) 정규화 비율로. 반드시 JSON 한 줄로만 답해:\n` +
+        `{"found":true,"x":0.0~1.0,"y":0.0~1.0} 또는 {"found":false}`;
+    try {
+        const result = await (0, ai_1.generateText)({
+            model,
+            messages: [{ role: 'user', content: [{ type: 'text', text: prompt }, { type: 'image', image: Buffer.from(screenshotBase64, 'base64') }] }],
+        });
+        const m = (result.text || '').match(/\{[\s\S]*\}/);
+        if (!m)
+            return null;
+        const o = JSON.parse(m[0]);
+        if (!o.found || typeof o.x !== 'number' || typeof o.y !== 'number')
+            return null;
+        return { x: o.x, y: o.y };
+    }
+    catch {
+        return null;
+    }
+}
+/** 현재 활성 제공자/모델 정보 (대시보드·진단용). */
+function activeLlmInfo() {
+    const provider = resolveProvider();
+    if (provider === 'anthropic')
+        return { provider, model: process.env.ANTHROPIC_MODEL || 'claude-opus-4-8' };
+    if (provider === 'google')
+        return { provider, model: process.env.GEMINI_MODEL || 'gemini-flash-latest' };
+    return { provider: null, model: null };
+}
+/** 로컬(Ollama) 모델이 설정되었는가. OLLAMA_MODEL 명시 시에만 true(정직). */
+function localLlmConfigured() {
+    return !!(process.env.OLLAMA_MODEL && process.env.OLLAMA_MODEL.trim());
+}
+/** 로컬(Ollama) 멀티턴 호출. 미설정/미가동 시 명확히 throw(가짜 성공 금지). */
+async function localChat(history, system, fetchFn) {
+    const model = (process.env.OLLAMA_MODEL || '').trim();
+    if (!model)
+        throw new Error('로컬 모델 미설정(OLLAMA_MODEL). Tier-0 로컬 처리를 위해 ollama 모델을 설정하세요.');
+    const base = (process.env.OLLAMA_BASE_URL || 'http://127.0.0.1:11434').replace(/\/$/, '');
+    const f = fetchFn ?? (globalThis.fetch);
+    if (!f)
+        throw new Error('global fetch 없음(Node 18+ 필요).');
+    const messages = [
+        ...(system ? [{ role: 'system', content: system }] : []),
+        ...history.map((t) => ({ role: t.role, content: t.content })),
+    ];
+    const res = await f(`${base}/api/chat`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model, messages, stream: false }),
+    });
+    if (!res.ok)
+        throw new Error(`Ollama 호출 실패: HTTP ${res.status} (ollama 실행/모델 수신 확인)`);
+    const body = await res.json();
+    const text = body?.message?.content;
+    if (typeof text !== 'string')
+        throw new Error('Ollama 응답 형식 오류(message.content 없음)');
+    return text;
+}
+/** 외부 제공자 식별(없으면 null). Tier 라우팅에서 외부 가용성 판단에 사용. */
+function externalProviderId() {
+    return resolveProvider();
+}

package/dist/mcp-client-guard.d.ts

@@ -0,0 +1,32 @@
+export declare function isSafeMcpUrl(url: string, allowHosts: string[]): {
+    ok: boolean;
+    reason: string;
+};
+/** M2 — IP 가 사설/루프백/링크로컬/메타데이터/유니크로컬인가(SSRF 표적). */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * M2 — DNS 리바인딩 방지: 호스트명을 *실제 resolve* 한 뒤 모든 IP가 공인인지 검사.
+ * 허용/공개 호스트명이 사설 IP로 가리켜도 차단. 외부 연결 직전 호출.
+ */
+export declare function isSafeResolvedUrl(url: string, allowHosts: string[], resolver?: (host: string) => Promise<string[]>): Promise<{
+    ok: boolean;
+    reason: string;
+}>;
+export interface SanitizeResult {
+    ok: boolean;
+    /** 스키마 검증 통과 데이터(통과 시). */
+    data?: unknown;
+    /** 탐지된 인젝션/위험 사유. */
+    flags: string[];
+}
+/**
+ * MCP 도구 출력 검증: (1) 기대 스키마 검증, (2) 프롬프트 인젝션 패턴 플래그.
+ * 인젝션 패턴이 있으면 ok=false(에이전트 컨텍스트로 환류 금지).
+ */
+export declare function sanitizeToolOutput(raw: string, isValid: (o: any) => boolean): SanitizeResult;
+/** 에이전트 생성 캔버스용 엄격 CSP — 인라인·eval·임의 네트워크 차단(허용 출처만). */
+export declare function a2uiCsp(allowConnect?: string[]): string;
+/** iframe sandbox 속성 — 동일출처/팝업/탑네비 차단(스크립트만 허용). */
+export declare const A2UI_SANDBOX = "allow-scripts";
+/** provenance 배너 마크업 — 사용자에게 "에이전트 생성" 출처를 명시(기만 방지). */
+export declare function provenanceBanner(): string;