deel-local-cli 1.2.0 → 1.4.1

package/src/tools/index.js

@@ -1,4 +1,4 @@
-// 도구 6종. 이름과 인자를 Claude Code 와 같게 맞춘다 —
+// 도구. 이름과 인자를 Claude Code 와 같게 맞춘다 —
 // 그래야 그 관례로 쓰인 스킬·명령이 그대로 먹는다.
 import { writeFileSync, appendFileSync, readFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -14,11 +14,17 @@ import { TODO_TOOL } from './todo.js';
 import { TASK_TOOL } from './task.js';
 import { OUTLINE_TOOL } from './outline.js';
 import { VERIFY_TOOL } from './verify.js';
+import { DEF_TOOL, REFS_TOOL } from './lsp.js';
+import { 편집후진단, 붙이기 as 진단붙이기, 데우기 } from '../lsp/diag.js';
+import { 프로젝트갈래 } from '../lsp/servers.js';
 import { allow as allowedIn } from '../agent/modes.js';
 import { 도구정의, 이름풀기 } from '../backend/mcp.js';
 import { isExcelPath, readExcel, toText as excelText, summarize as excelSummary } from './excel.js';
+import { isDocPath, readDoc, toText as docText, summarize as docSummary, looksOldHwp, 옛hwp안내, 문서는못고침 } from './docs.js';
 import { diffLines } from '../ui/diff.js';
 import { 읽을줄수, 찾을개수, 찾을줄수, 설명길이 } from '../agent/budget.js';
+import { 도구설명EN } from './desc.en.js';
+import { 언어 } from '../i18n/index.js';
 
 /*
  * 한 번에 돌려줄 양은 **모델에 맞춰** 정한다 (agent/budget.js).
@@ -180,6 +186,26 @@ function 줄수(abs, 인코딩) {
   } catch { return 0; }
 }
 
+/**
+ * 그 줄과 앞뒤 몇 줄. Edit 이 빗나갔을 때 보여 줄 것.
+ *
+ * 줄 번호를 같이 붙인다 — 모델이 "몇 번 줄" 로 세어 다시 잡을 수 있어야 한다.
+ * 한 줄만 보여 주던 것을 넓힐 때, 넓힌 만큼 자리를 먹으니 짧게 자른다.
+ */
+function 둘레(text, 줄번호, 보일줄 = 1) {
+  const 줄들 = String(text ?? '').split('\n');
+  const 가운데 = Math.max(1, Number(줄번호) || 1);
+  const 반 = Math.floor(Math.max(1, 보일줄) / 2);
+  const 처음 = Math.max(1, 가운데 - 반);
+  const 끝 = Math.min(줄들.length, 처음 + Math.max(1, 보일줄) - 1);
+  const out = [];
+  for (let i = 처음; i <= 끝; i++) {
+    const 표 = i === 가운데 ? '→' : ' ';
+    out.push(`  ${표} ${String(i).padStart(5)} | ${줄들[i - 1].slice(0, 120)}`);
+  }
+  return out.join('\n');
+}
+
 function 엑셀은못고침(보인이름) {
   return `엑셀 파일은 이 도구로 고칠 수 없습니다: ${보인이름}\n`
     + '  읽기만 됩니다 (CSV 로 바꿔서 보여줍니다). 서식·수식·차트가 든 파일을\n'
@@ -210,6 +236,28 @@ async function 엑셀읽기(abs, args, ctx) {
 }
 
 
+/**
+ * 문서(hwpx·docx·pptx)를 글로 읽어 돌려준다.
+ *
+ * 엑셀읽기와 같은 규칙 — ctx.seen 에 안 넣는다. 넣으면 Edit 이 '이 파일 고칠
+ * 수 있다' 고 오해한다. 문서는 이 도구로 고치는 물건이 아니다.
+ */
+function 문서읽기(abs, ctx) {
+  const r = readDoc(abs);
+  if (!r.ok) return { error: r.error };
+  const { text, 잘림 } = docText(r.덩이들);
+  return {
+    content: clip(
+      `${text || '(빈 문서입니다 — 글이 없습니다.)'}
+
+(${r.갈래} 문서를 글로 바꿔서 보여준 것입니다. 이 파일은 Edit/Write 로 고칠 수 없습니다.)`
+      + (잘림.length ? `
+(${잘림.join(' · ')})` : ''),
+    ),
+    summary: docSummary(r) + (잘림.length ? ' · 일부만' : ''),
+  };
+}
+
 /**
  * 파일 하나를 쓴다 — Write 의 알맹이.
  *
@@ -227,6 +275,9 @@ function 한파일쓰기(args, ctx) {
     // 엑셀 파일을 통째로 덮어쓰면 xlsx 가 아니라 그냥 글 파일이 된다.
     // 열리지도 않는 파일이 되고, 원본은 이미 없다. 아예 막는다.
     if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
+    // 문서(hwpx·docx·pptx)도 같은 이유로 또렷하게 거절한다. 일반 '바이너리'
+    // 오류로 넘기면 왜 안 되는지가 안 실려서, 모델이 우회로를 찾는다.
+    if (isDocPath(abs)) return { error: 문서는못고침(args.file_path) };
     // 엑셀만 막아서는 모자란다. hwp·pdf·png·zip 도 똑같이 그 순간 끝난다.
     // 게다가 이런 파일은 되돌리기가 내용을 떠 놓지 못하는 종류라 되살릴 길이 없다.
     // 확장자로 고르지 않고 실제 내용으로 본다 — 사내 파일은 확장자가 제각각이다.
@@ -324,6 +375,7 @@ function 한군데고치기(args, ctx) {
   // 엑셀 파일은 Read 로 읽히긴 하지만 고칠 수 있는 물건이 아니다.
   // '먼저 Read 로 읽어야 합니다' 라고만 하면 이미 읽은 쪽은 계속 헛돈다.
   if (isExcelPath(abs)) return { error: 엑셀은못고침(args.file_path) };
+  if (isDocPath(abs)) return { error: 문서는못고침(args.file_path) };
   if (!ctx.seen.has(abs)) return { error: `먼저 Read 로 읽어야 합니다: ${args.file_path}` };
   if (args.old_string === args.new_string) return { error: 'old_string 과 new_string 이 같습니다' };
 
@@ -335,8 +387,16 @@ function 한군데고치기(args, ctx) {
     if (m.reason === 'ambiguous') {
       return { error: `${m.count}군데에서 발견됐습니다 (${TIER_LABELS[m.tier]}). 앞뒤로 더 넓게 잡아 하나만 가리키거나 replace_all 을 쓰세요.` };
     }
+    /*
+     * 비슷한 자리를 몇 줄이나 보여 줄까는 **이 모델을 겪어 본 만큼** 정한다
+     * (agent/card.js). Edit 이 자주 빗나가는 모델에는 한 줄만 보여 줘 봐야
+     * 다음 시도도 빗나간다 — 앞뒤를 같이 보여 주면 옮겨 담을 것이 분명해진다.
+     * 겪은 것이 모자라면 여태처럼 한 줄이다. 자리를 괜히 먹지 않는다.
+     */
+    const 보일줄 = Math.max(1, ctx?.카드?.조정?.빗나갔을때보일줄 ?? 1);
     const hint = m.near
-      ? `\n  파일의 ${m.near.line}번 줄이 가장 비슷합니다:\n    ${m.near.text.trim().slice(0, 120)}\n  이 줄을 그대로 옮겨 담아 다시 시도하세요.`
+      ? `\n  파일의 ${m.near.line}번 줄이 가장 비슷합니다:\n${둘레(text, m.near.line, 보일줄)}`
+        + '\n  이 줄을 그대로 옮겨 담아 다시 시도하세요.'
       : '\n  Read 로 다시 읽어 실제 내용을 확인하세요.';
     return { error: `찾지 못했습니다.${hint}` };
   }
@@ -435,7 +495,8 @@ export const TOOLS = {
       name: 'Read',
       description: '파일 하나를 읽는다. 줄 번호가 붙어 돌아온다. 고치기 전에는 반드시 먼저 읽어야 한다.'
         + ' 엑셀 파일(.xlsx/.xlsm/.xls)도 그대로 읽을 수 있다 — 시트별 CSV 로 바꿔서 돌려준다.'
-        + ' 사용자에게 CSV 로 내보내 달라고 할 필요가 없다. 다만 엑셀 파일은 읽기만 되고 고칠 수는 없다.',
+        + ' 한글·워드·파워포인트 문서(.hwpx/.docx/.pptx)도 그대로 읽는다 — 글로 바꿔서 돌려준다.'
+        + ' 사용자에게 다른 형식으로 내보내 달라고 할 필요가 없다. 다만 이런 파일들은 읽기만 되고 고칠 수는 없다.',
       parameters: {
         type: 'object',
         properties: {
@@ -457,6 +518,19 @@ export const TOOLS = {
       // 엑셀 파일은 글이 아니라 압축 꾸러미다. 그냥 읽으면 '바이너리' 로 끝난다.
       // 여기서 표로 바꿔 돌려준다 — 사람이 손으로 CSV 로 내보낼 일이 없게.
       if (isExcelPath(abs)) return 엑셀읽기(abs, args, ctx);
+      // hwpx·docx·pptx 도 같다 — 속이 ZIP+XML 이라 글로 바꿔 돌려준다 (docs.js).
+      if (isDocPath(abs)) return 문서읽기(abs, ctx);
+      /*
+       * 구형 hwp 는 '바이너리' 로 끝내지 않는다. 그 오류에는 길이 없어서
+       * 모델이 우회로(새로 쓰기)를 찾는다 — 실제로 그렇게 원본이 죽은 적이
+       * 있다. 여기서는 hwpx 로 저장하면 읽힌다는 길을 같이 준다.
+       */
+      if (abs.toLowerCase().endsWith('.hwp')) {
+        try {
+          const 머리 = readFileSync(abs);
+          if (looksOldHwp(abs, 머리)) return { error: 옛hwp안내(ctx.scope.show(abs)) };
+        } catch { /* 아래 일반 읽기가 제 오류를 낸다 */ }
+      }
 
       const 읽음 = readTextFull(abs);
       // 무엇으로 읽었는지 기억해 둔다. 나중에 고칠 때 같은 것으로 되돌려 써야 한다.
@@ -1111,6 +1185,16 @@ export const TOOLS = {
 
   // 뒤에서 도는 명령 보기·끝내기. Bash(background) 와 짝이다 — jobs.js 머리말 참고.
   Jobs: JOBS_TOOL,
+
+  /*
+   * 언어 서버에게 묻는 둘. Grep·Outline 을 밀어내지 않고 **더한다** —
+   * tools/lsp.js 머리말 참고.
+   *
+   * 언어 서버가 이 자리에 없으면 toolSchemas 가 목록에서 뺀다. 못 쓰는 도구를
+   * 세워 두면 모델은 그걸 부르고, 실패를 받고, 또 부른다.
+   */
+  Def: DEF_TOOL,
+  Refs: REFS_TOOL,
 };
 
 /**
@@ -1181,14 +1265,49 @@ export function 설명줄이기(schema, 한도) {
   };
 }
 
+/**
+ * 도구 설명을 지금 화면 말에 맞춘다.
+ *
+ * 표에 없는 도구·인자는 한글 설명이 그대로 나간다 — 화면 말과 같은 규칙이다.
+ * 빈 설명을 내보내지 않는다. 설명 없는 도구는 모델이 언제 쓰는지 모른 채로
+ * 목록에만 서 있게 되는데, 그건 없는 것보다 나쁘다.
+ */
+function 영어설명(schema, 이름) {
+  if (언어() !== 'en') return schema;
+  const 것 = 도구설명EN[이름];
+  if (!것) return schema;
+
+  const p = schema.parameters ?? {};
+  const 새속성 = {};
+  for (const [인자, 값] of Object.entries(p.properties ?? {})) {
+    const 글 = 것.params?.[인자];
+    새속성[인자] = 글 ? { ...값, description: 글 } : 값;
+  }
+  return {
+    ...schema,
+    description: 것.desc ?? schema.description,
+    parameters: { ...p, properties: 새속성 },
+  };
+}
+
 // 모델에게 넘길 도구 정의 목록.
 // 스킬이 없으면 Skill 도구는 빼서 자리를 아낀다.
-export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null } = {}) {
+export function toolSchemas(names = null, { hasSkills = false, web = true, work = null, mcp = null, ctx = null, lsp = false } = {}) {
   let list = names ?? Object.keys(TOOLS).filter((n) => {
     if (n === 'Skill') return hasSkills;
     if (n === 'WebFetch') return web;
+    // 언어 서버가 없는 자리에서는 Def·Refs 를 아예 안 보여 준다.
+    //
+    // 웹 도구를 오프라인에서 숨기는 것과 같은 이유다. 못 쓰는 도구를 목록에
+    // 세워 두면 모델은 그걸 부르고, "없습니다" 를 받고, 또 부른다. 그 왕복이
+    // 도구 설명으로 나가는 자리보다 비싸다.
+    if (n === 'Def' || n === 'Refs') return !!lsp;
     return true;
   });
+  // 이름을 직접 준 경우(하위 작업이 부모 것을 물려받을 때)에도 같은 규칙을 건다.
+  // 부모에게 있던 것이 하위에서 갑자기 못 쓰게 되지는 않지만, 시험·일회성 호출이
+  // 이름을 통째로 넘기는 길이 있어서 여기서 한 겹 더 막는다.
+  if (names && !lsp) list = list.filter((n) => n !== 'Def' && n !== 'Refs');
   // 작업 모드가 정해져 있으면 그 모드가 쓰는 것만 남긴다.
   //
   // 설계·계획·묻기 모드에서 파일을 바꾸면 안 된다고 프롬프트로 부탁할 수도 있다.
@@ -1202,7 +1321,20 @@ export function toolSchemas(names = null, { hasSkills = false, web = true, work
    * 이름과 인자는 그대로 남으므로 할 수 있는 일은 똑같다.
    */
   const 한도 = 설명길이(ctx);
-  const 우리것 = list.map((n) => ({ type: 'function', function: 설명줄이기(TOOLS[n].schema, 한도) }));
+  /*
+   * 화면 말이 영어면 도구 설명도 영어로 갈아 끼운다 (tools/desc.en.js).
+   *
+   * 줄이기 **전에** 갈아 끼운다. 순서가 반대면 한글 설명을 한도에 맞춰 자른
+   * 다음 영어로 통째로 바꾸는 셈이라, 자른 것이 아무 뜻이 없어지고 영어 글은
+   * 한도를 넘긴 채로 실린다.
+   *
+   * 이름과 인자 이름은 안 건드린다 — 그건 식별자다. Task 의 목적·할일처럼
+   * 한글로 된 인자 이름을 바꾸면 그 도구가 아예 안 불린다.
+   */
+  const 우리것 = list.map((n) => ({
+    type: 'function',
+    function: 설명줄이기(영어설명(TOOLS[n].schema, n), 한도),
+  }));
 
   /*
    * 밖에서 붙인 도구(MCP)를 뒤에 붙인다.
@@ -1215,6 +1347,58 @@ export function toolSchemas(names = null, { hasSkills = false, web = true, work
   return 우리것;
 }
 
+// 파일을 바꾸는 도구들. 이것만 고친 뒤 진단을 본다.
+const 고치는도구 = new Set(['Write', 'Append', 'Edit']);
+// 한 번에 볼 파일 수. 여덟 개를 한꺼번에 만들었다고 여덟 번 기다릴 수는 없다.
+const 진단볼파일 = 3;
+
+/**
+ * 고친 직후에 그 파일이 성한지 본다 — lsp/diag.js 머리말 참고.
+ *
+ * 여기서 절대 죽으면 안 되고, 늦어서도 안 된다. 파일은 이미 고쳐졌다.
+ * 진단은 **덤**이지 이 도구가 성공했는지의 판단 근거가 아니다. 그래서
+ * 통째로 감싸고, 이미 떠 있는 서버가 없으면 아무것도 안 하고 그냥 지나간다.
+ */
+async function 고친뒤진단(name, r, ctx) {
+  try {
+    if (!고치는도구.has(name) || !r || r.error) return r;
+    /*
+     * **부른 쪽이 켠 자리에서만** 한다. 기본은 꺼짐이다.
+     *
+     * 여기서 하는 일은 남의 프로세스를 하나 띄우는 것이다. 그건 띄운 쪽이
+     * 거둘 줄 알아야 한다 — 안 거두면 그 서버가 작업 폴더를 cwd 로 물고 있어서
+     * 윈도우에서는 폴더 이름조차 못 바꾼다. 그래서 끄는 자리를 갖춘 쪽(repl·
+     * oneshot)만 ctx.lsp.켬 을 켠다. 도구를 직접 부르는 자리는 안 켜진다.
+     */
+    if (ctx.lsp?.켬 !== true) return r;
+    const 뿌리 = ctx.scope?.root;
+    if (!뿌리) return r;
+
+    const 바뀐 = r.changed
+      ? [r.changed]
+      : (Array.isArray(r.여럿) ? r.여럿.filter((x) => x?.ok && x.path).map((x) => x.path) : []);
+    const 볼것 = [...new Set(바뀐)].slice(0, 진단볼파일);
+    if (!볼것.length) return r;
+
+    // 처음 고칠 때 뒤에서 하나 데워 둔다. 이번 것은 못 받아도 다음부터 받는다.
+    데우기(뿌리, 볼것[0]);
+
+    const 것들 = await Promise.all(볼것.map((abs) => 편집후진단(뿌리, abs)));
+    let 답 = r;
+    for (let i = 0; i < 볼것.length; i++) {
+      답 = 진단붙이기(답, 것들[i], ctx.scope.show(볼것[i]));
+    }
+    return 답;
+  } catch {
+    return r;   // 진단 보다 터져서 편집이 실패로 보이는 일은 없어야 한다
+  }
+}
+
+/** 이 폴더에서 언어 서버를 쓸 수 있나. repl 이 켤 때 한 번 물어본다. */
+export function 언어서버있나(뿌리) {
+  try { return !!프로젝트갈래(뿌리); } catch { return false; }
+}
+
 export async function runTool(name, args, ctx) {
   // 밖에서 붙인 도구(MCP)는 이름 앞머리로 갈린다.
   //
@@ -1228,7 +1412,7 @@ export async function runTool(name, args, ctx) {
   try {
     const r = await t.run(args ?? {}, ctx);
     ctx.audit.tool(name, args, r);
-    return r;
+    return await 고친뒤진단(name, r, ctx);
   } catch (err) {
     const r = { error: err.message };
     ctx.audit.tool(name, args, r);

package/src/tools/lsp.js

@@ -0,0 +1,327 @@
+/**
+ * Def · Refs — 언어 서버에게 "이게 어디 있나 / 어디서 쓰나" 를 묻는다.
+ *
+ * ── Grep 을 밀어내는 것이 아니다 ────────────────────────────────────────
+ *
+ * Grep 은 남는다. 언어 서버가 안 깔린 자리가 더 많고(사내망이 대개 그렇다),
+ * 깔려 있어도 못 읽는 파일이 있고, 무엇보다 Grep 은 **주석·설정·문서까지**
+ * 찾는다. 이름을 바꿀 때 정말 필요한 것은 그쪽까지다.
+ *
+ * 이 둘이 더해 주는 것은 딱 하나, **틀린 자리를 안 준다는 것**이다.
+ * `run` 을 Grep 으로 찾으면 수백 줄이 나오고 그중 진짜는 몇 개다. 모델은 그
+ * 수백 줄을 다 읽을 자리가 없어서 앞의 몇 개만 보고 고치기 시작한다. 놓친
+ * 자리는 돌려 본 뒤에야 드러나고, 그때는 이미 다른 것도 같이 고쳐 놓은 뒤다.
+ *
+ * ── 왜 자리(줄·칸)가 아니라 이름을 받나 ─────────────────────────────────
+ *
+ * LSP 는 "이 파일 이 줄 이 칸에 있는 것" 을 묻는 규약이다. 그런데 모델은
+ * 칸 번호를 모른다. 알려면 파일을 먼저 Read 해야 하는데, 그러면 이 도구를
+ * 쓰는 값(파일을 안 읽고도 안다)이 통째로 사라진다.
+ *
+ * 그래서 이름을 받아 **workspace/symbol 로 자리를 먼저 찾고**, 그 자리로
+ * 다시 묻는다. 사람이 하는 것과 같은 순서다. 이름이 여럿이면 그 목록을
+ * 그대로 보여 주고 고르게 한다 — 하나를 골라 주고 아닌 척하지 않는다.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { 얻기, 색인중일까 } from '../lsp/client.js';
+import { 갈래, 프로젝트갈래 } from '../lsp/servers.js';
+import { 찾을개수 } from '../agent/budget.js';
+
+/** 한 자리를 사람이 읽을 한 줄로. 그 줄의 글까지 붙여야 열어 보지 않고도 안다. */
+function 한줄(scope, uri, 범위) {
+  let abs;
+  try { abs = fileURLToPath(uri); } catch { abs = String(uri); }
+  const 줄번호 = (범위?.start?.line ?? 0) + 1;
+  let 글 = '';
+  try {
+    const 줄들 = readFileSync(abs, 'utf8').split(/\r?\n/);
+    글 = (줄들[줄번호 - 1] ?? '').trim();
+  } catch { /* 못 읽으면 자리만 준다 */ }
+  const 보일 = scope?.show ? (() => { try { return scope.show(abs); } catch { return abs; } })() : abs;
+  return { 파일: 보일, 줄: 줄번호, 글: 글.length > 160 ? 글.slice(0, 160) + '…' : 글, abs };
+}
+
+/** LSP 의 답은 하나일 수도, 목록일 수도, LocationLink 일 수도 있다. 다 같은 모양으로 편다. */
+function 자리들펴기(값) {
+  if (!값) return [];
+  const 목록 = Array.isArray(값) ? 값 : [값];
+  return 목록.map((it) => {
+    if (!it) return null;
+    if (it.targetUri) return { uri: it.targetUri, range: it.targetSelectionRange ?? it.targetRange };
+    if (it.uri) return { uri: it.uri, range: it.range };
+    if (it.location) return { uri: it.location.uri, range: it.location.range };
+    return null;
+  }).filter(Boolean);
+}
+
+/**
+ * 이름이 그 줄 어디쯤에 있는지.
+ *
+ * 낱말 경계를 본다. `run` 을 찾을 때 `runner` 를 짚으면 서버는 runner 의
+ * 정의를 준다 — 틀린 답인데 맞는 답처럼 생겨서 제일 나쁘다.
+ */
+function 칸찾기(줄글, 이름) {
+  if (!줄글 || !이름) return -1;
+  let i = 0;
+  for (;;) {
+    const p = 줄글.indexOf(이름, i);
+    if (p < 0) return -1;
+    const 앞 = 줄글[p - 1] ?? ' ';
+    const 뒤 = 줄글[p + 이름.length] ?? ' ';
+    const 낱말 = (ch) => /[\p{L}\p{N}_$]/u.test(ch);
+    if (!낱말(앞) && !낱말(뒤)) return p;
+    i = p + 1;
+  }
+}
+
+/**
+ * 이름으로 자리를 찾는다.
+ *
+ * @returns {{자리: {uri, position}, 후보: object[]}|{오류: string}}
+ */
+async function 자리잡기(서버, scope, { 이름, 파일, 줄 }) {
+  // 1) 파일과 줄을 준 경우. 그게 제일 정확하다 — 모델이 방금 Read 했거나
+  //    Grep 으로 좁혀 온 자리다.
+  if (파일) {
+    let abs;
+    try { abs = scope.resolve(파일); } catch (e) { return { 오류: e.message }; }
+    let 줄들;
+    try { 줄들 = readFileSync(abs, 'utf8').split(/\r?\n/); } catch { return { 오류: `못 읽었습니다: ${파일}` }; }
+    서버.보여주기(abs, 줄들.join('\n'));
+
+    const 볼줄 = Number.isFinite(줄) && 줄 > 0 ? [줄 - 1] : 줄들.map((_, i) => i);
+    for (const i of 볼줄) {
+      const 칸 = 칸찾기(줄들[i] ?? '', 이름);
+      if (칸 >= 0) return { 자리: { uri: pathToFileURL(abs).href, position: { line: i, character: 칸 } } };
+    }
+    return { 오류: `${파일}${Number.isFinite(줄) ? `:${줄}` : ''} 에서 ${이름} 을 못 찾았습니다` };
+  }
+
+  /*
+   * 2) 이름만 준 경우. 프로젝트 전체에서 그 이름을 찾는다.
+   *
+   * 방금 켠 서버는 빈손으로 답한다. 없어서가 아니라 아직 프로젝트를 다 못
+   * 훑어서다 — 악수는 몇십 ms 면 끝나지만 색인은 몇 초씩 걸린다. 실제로 켠 지
+   * 0.2초 만에 물었더니 없다고 했고, 0.5초 뒤에 물으니 나왔다.
+   *
+   * 이 둘을 구별 안 하면 "그런 이름 없습니다" 가 되고, 모델은 그 말을 믿고
+   * 이미 있는 것을 새로 만든다. 그래서 **켠 지 얼마 안 됐을 때만** 몇 번 더
+   * 물어본다. 오래 돈 서버에서 빈손이면 그건 정말 없는 것이라 안 기다린다.
+   */
+  let 답 = await 서버.물어보기('workspace/symbol', { query: 이름 });
+  for (const 쉼 of [400, 800, 1500]) {
+    if (답.오류 || (Array.isArray(답.값) && 답.값.length)) break;
+    if (!색인중일까(서버)) break;
+    // 이 시계는 unref 하지 않는다. 여기는 도구가 도는 한가운데라,
+    // 놔 버리면 기다리는 사이에 프로그램이 그냥 끝나 버린다.
+    await new Promise((r) => setTimeout(r, 쉼));
+    답 = await 서버.물어보기('workspace/symbol', { query: 이름 });
+  }
+  if (답.오류) return { 오류: 답.오류 };
+  const 것들 = (Array.isArray(답.값) ? 답.값 : []).filter((s) => s?.name);
+  // 이름이 똑같은 것만. 서버는 대개 부분 일치까지 준다.
+  const 딱맞는 = 것들.filter((s) => s.name === 이름);
+  const 쓸것 = 딱맞는.length ? 딱맞는 : 것들;
+  if (!쓸것.length) {
+    return {
+      오류: `${이름} 을(를) 못 찾았습니다`
+        + (색인중일까(서버) ? ' (언어 서버가 아직 프로젝트를 훑는 중일 수 있습니다)' : '')
+        + '. Grep 으로 한 번 더 보세요.',
+    };
+  }
+
+  const 후보 = 쓸것.map((s) => {
+    const loc = s.location ?? {};
+    return { 이름: s.name, 갈래: s.kind, uri: loc.uri, range: loc.range ?? null, 컨테이너: s.containerName ?? '' };
+  }).filter((x) => x.uri);
+  if (!후보.length) return { 오류: `${이름} 의 자리를 못 받았습니다` };
+
+  const 첫 = 후보[0];
+  // WorkspaceSymbol 은 range 없이 오기도 한다. 그럼 파일을 열어 직접 짚는다.
+  let position = 첫.range?.start;
+  if (!position) {
+    try {
+      const abs = fileURLToPath(첫.uri);
+      const 줄들 = readFileSync(abs, 'utf8').split(/\r?\n/);
+      for (let i = 0; i < 줄들.length; i++) {
+        const 칸 = 칸찾기(줄들[i], 이름);
+        if (칸 >= 0) { position = { line: i, character: 칸 }; break; }
+      }
+    } catch { /* 아래에서 걸린다 */ }
+  }
+  if (!position) return { 오류: `${이름} 의 자리를 못 짚었습니다` };
+
+  // 정확히 이름 글자 위를 짚어야 한다. 정의 줄 맨 앞(`export function`)을 짚으면
+  // 서버가 아무것도 못 준다.
+  try {
+    const abs = fileURLToPath(첫.uri);
+    const 줄글 = readFileSync(abs, 'utf8').split(/\r?\n/)[position.line] ?? '';
+    const 칸 = 칸찾기(줄글, 이름);
+    if (칸 >= 0) position = { line: position.line, character: 칸 };
+    서버.보여주기(abs);
+  } catch { /* 그대로 간다 */ }
+
+  return { 자리: { uri: 첫.uri, position }, 후보 };
+}
+
+/** 두 도구가 같은 앞머리를 쓴다 — 서버 얻고 자리 잡는 데까지. */
+async function 채비(args, ctx) {
+  const 이름 = String(args.name ?? '').trim();
+  if (!이름) return { 오류: 'name 이 비었습니다' };
+
+  const 파일 = args.file_path ? String(args.file_path) : null;
+  /*
+   * 어느 언어 서버에게 물을지.
+   *
+   * 파일을 줬으면 그 파일의 언어다. 안 줬으면 이 폴더에서 제일 많은 언어로
+   * 간다 — 모델은 `handleClick 어디 있어` 처럼 이름만 알고 부르는 것이 보통이라,
+   * 매번 파일을 요구하면 이 도구를 쓰는 값이 사라진다.
+   */
+  const 볼것 = 파일 ?? 프로젝트갈래(ctx.scope.root)?.대표파일 ?? null;
+  if (!볼것) return { 오류: '이 폴더에서 쓸 수 있는 언어 서버가 없습니다. Grep · Outline 을 쓰세요.' };
+  if (!갈래(볼것)) return { 오류: `언어 서버가 없는 갈래입니다: ${볼것}` };
+
+  const 서버 = await 얻기(ctx.scope.root, 볼것);
+  if (!서버) return { 오류: '언어 서버가 이 자리에 없습니다. Grep · Outline 을 쓰세요.' };
+
+  const 잡음 = await 자리잡기(서버, ctx.scope, {
+    이름, 파일, 줄: Number.isFinite(args.line) ? Number(args.line) : null,
+  });
+  if (잡음.오류) return { 오류: 잡음.오류 };
+  return { 이름, 서버, 자리: 잡음.자리, 후보: 잡음.후보 ?? [] };
+}
+
+/** 여러 곳에 같은 이름이 있으면 그대로 알려 준다. 하나를 골라 주고 아닌 척하지 않는다. */
+function 여럿이면(후보, scope) {
+  if (!Array.isArray(후보) || 후보.length < 2) return null;
+  const 파일들 = new Set(후보.map((c) => { try { return scope.show(fileURLToPath(c.uri)); } catch { return c.uri; } }));
+  if (파일들.size < 2) return null;
+  return `같은 이름이 ${파일들.size}곳에 있습니다: ${[...파일들].slice(0, 5).join(' · ')}`
+    + `${파일들.size > 5 ? ' …' : ''}. 다른 것을 뜻했다면 file_path 로 짚어 주세요.`;
+}
+
+export const DEF_TOOL = {
+  schema: {
+    name: 'Def',
+    description:
+      '이름 하나가 **어디에 정의돼 있는지** 언어 서버에게 묻는다. 파일을 안 읽고도 자리를 안다.'
+      + ' Grep 과 다른 점은 틀린 자리를 안 준다는 것이다 — 주석에 든 같은 이름, 남의 라이브러리의'
+      + ' 같은 이름, 문자열 안의 같은 이름을 안 섞어 준다.'
+      + ' 남이 쓴 코드를 고치기 전에 이걸 먼저 불러라. 자리를 안 다음에 그 파일만 Read 하면 된다.'
+      + ' 이름이 여러 곳에 있으면 그 목록을 준다. file_path 로 어느 것인지 짚어 주면 된다.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: '찾을 이름 (함수·클래스·변수)' },
+        file_path: { type: 'string', description: '그 이름이 쓰인 파일. 같은 이름이 여럿일 때 짚어 준다' },
+        line: { type: 'number', description: 'file_path 안에서 그 이름이 쓰인 줄 번호 (1부터)' },
+      },
+      required: ['name'],
+    },
+  },
+
+  async run(args, ctx) {
+    const 준비 = await 채비(args, ctx);
+    if (준비.오류) return { error: 준비.오류 };
+    const { 이름, 서버, 자리, 후보 } = 준비;
+
+    const 답 = await 서버.물어보기('textDocument/definition', {
+      textDocument: { uri: 자리.uri },
+      position: 자리.position,
+    });
+    if (답.오류) return { error: `언어 서버: ${답.오류}` };
+
+    let 곳들 = 자리들펴기(답.값).map((x) => 한줄(ctx.scope, x.uri, x.range));
+    // 서버가 정의를 못 주면(선언만 있는 자리 등) 심볼 검색으로 잡은 자리를 준다.
+    // 빈손으로 돌려보내는 것보다 낫고, 어디서 온 값인지 같이 말해 준다.
+    let 어디서 = 'definition';
+    if (!곳들.length && 후보.length) {
+      곳들 = 후보.map((c) => 한줄(ctx.scope, c.uri, c.range));
+      어디서 = 'workspace/symbol';
+    }
+    if (!곳들.length) return { summary: `${이름}: 정의를 못 찾았습니다. Grep 으로 찾아보세요.`, found: 0 };
+
+    const 여럿 = 여럿이면(후보, ctx.scope);
+    return {
+      summary: `${이름} — 정의 ${곳들.length}곳${여럿 ? `\n${여럿}` : ''}`,
+      found: 곳들.length,
+      source: 어디서,
+      locations: 곳들,
+      content: 곳들.map((l) => `${l.파일}:${l.줄}  ${l.글}`).join('\n'),
+    };
+  },
+};
+
+export const REFS_TOOL = {
+  schema: {
+    name: 'Refs',
+    description:
+      '이름 하나를 **어디서 쓰는지** 언어 서버에게 다 묻는다. 이름을 바꾸거나 함수를 고치기 전에'
+      + ' 불러라 — 몇 군데를 같이 고쳐야 하는지가 여기서 나온다.'
+      + ' Grep 이 주는 수백 줄과 달리 진짜 그것을 쓰는 자리만 나온다. 대신 Grep 은 주석·설정·문서까지'
+      + ' 찾으니, 이름을 통째로 바꿀 때는 이걸로 코드를 잡고 Grep 으로 나머지를 훑어라.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: '찾을 이름 (함수·클래스·변수)' },
+        file_path: { type: 'string', description: '그 이름이 정의된 파일. 같은 이름이 여럿일 때 짚어 준다' },
+        line: { type: 'number', description: 'file_path 안에서 그 이름이 있는 줄 번호 (1부터)' },
+        include_declaration: { type: 'boolean', description: '정의한 자리도 넣을지. 기본 false' },
+      },
+      required: ['name'],
+    },
+  },
+
+  async run(args, ctx) {
+    const 준비 = await 채비(args, ctx);
+    if (준비.오류) return { error: 준비.오류 };
+    const { 이름, 서버, 자리, 후보 } = 준비;
+
+    const 답 = await 서버.물어보기('textDocument/references', {
+      textDocument: { uri: 자리.uri },
+      position: 자리.position,
+      context: { includeDeclaration: args.include_declaration === true },
+    });
+    if (답.오류) return { error: `언어 서버: ${답.오류}` };
+
+    const 곳들 = 자리들펴기(답.값).map((x) => 한줄(ctx.scope, x.uri, x.range));
+    if (!곳들.length) {
+      return {
+        summary: `${이름}: 쓰는 자리가 없습니다.`
+          + ' 정말 안 쓰는 것일 수도 있고, 언어 서버가 아직 색인 중일 수도 있습니다 —'
+          + ' 지우기 전에 Grep 으로 한 번 더 보세요.',
+        found: 0,
+      };
+    }
+
+    // 창에 맞춰 자른다. 자른 것은 자랐다고 말한다 — 조용히 자르면 모델은
+    // 그게 전부인 줄 알고 나머지 자리를 안 고친다.
+    const 한도 = 찾을개수(ctx.모델컨텍스트 ?? null);
+    const 보일것 = 곳들.slice(0, 한도);
+    const 남은 = 곳들.length - 보일것.length;
+
+    // 파일별로 묶어야 읽힌다. 같은 파일 열 줄이 흩어져 있으면 몇 파일을
+    // 고쳐야 하는지가 안 보인다.
+    const 묶음 = new Map();
+    for (const l of 보일것) {
+      if (!묶음.has(l.파일)) 묶음.set(l.파일, []);
+      묶음.get(l.파일).push(l);
+    }
+    const 글 = [...묶음.entries()]
+      .map(([f, 줄들]) => `${f} (${줄들.length})\n` + 줄들.map((l) => `  ${l.줄}: ${l.글}`).join('\n'))
+      .join('\n');
+
+    const 여럿 = 여럿이면(후보, ctx.scope);
+    return {
+      summary: `${이름} — 쓰는 자리 ${곳들.length}곳 · 파일 ${묶음.size}개`
+        + (남은 ? ` (${남은}곳은 자리가 모자라 안 실었습니다)` : '')
+        + (여럿 ? `\n${여럿}` : ''),
+      found: 곳들.length,
+      files: 묶음.size,
+      truncated: 남은 > 0,
+      locations: 보일것,
+      content: 글,
+    };
+  },
+};