deel-local-cli 1.1.1 → 1.4.0

package/src/safety/secrets.js

@@ -0,0 +1,205 @@
+// 비밀이 모델에게, 그리고 디스크에 남는 대화 기록에 끼어드는 것을 막는다.
+//
+// ── 어디서 새나 ────────────────────────────────────────────────────────
+//
+// 사람이 열쇠를 붙여 넣는 일은 드물다. 새는 자리는 거의 항상 **명령 출력**이다.
+//
+//   env · printenv · set              환경변수를 통째로 찍는다
+//   git remote -v                     https://사람:토큰@github.com/... 이 그대로
+//   docker inspect · kubectl get -o   설정에 박힌 열쇠가 그대로
+//   curl -v                           Authorization 헤더가 그대로
+//   검사 실패 로그                     연결 문자열이 통째로
+//
+// 이게 왜 문제인가. 그 글은 모델에게 실려 가고 — 사내 게이트웨이라 해도
+// 그쪽 로그에 남는다 — 동시에 `.deel/sessions/*.jsonl` 로 디스크에 적힌다.
+// 그 파일은 나중에 `/recall` 로 다시 읽히고, `deel pack` 에 딸려 갈 수도 있다.
+// 한 번 새면 여러 벌이 된다.
+//
+// ── 파일 내용은 안 가린다 ───────────────────────────────────────────────
+//
+// 여기서 제일 중요한 결정이다. **읽은 파일은 손대지 않는다.**
+//
+// 가리고 싶은 마음이 드는 자리가 바로 `.env` 인데, 거기를 가리면 이렇게 된다 —
+// 모델이 가려진 글을 보고, 그걸 고쳐서 Write 로 되돌려 쓴다. 그러면 진짜
+// 열쇠가 있던 자리에 `«가림»` 이 적힌다. **사람의 열쇠가 우리 손에 지워진다.**
+// 비밀을 지키려다 비밀을 파괴하는 셈이다.
+//
+// 그래서 파일 쪽은 가리는 대신 **알린다** — 감사기록에 남기고 화면에 띄운다.
+// 무엇을 못 막는지 분명히 말하는 편이, 막았다고 해 놓고 파일을 망가뜨리는 것보다
+// 언제나 낫다.
+//
+// 가리는 것은 **한 번 쓰고 버려지는 출력**뿐이다. 명령 출력·웹에서 받아온 글은
+// 모델이 그대로 되돌려 쓸 일이 없다.
+
+/** 가려진 자리에 남는 표. 종류를 같이 적어 무엇이 가려졌는지 알 수 있게 한다. */
+const 표 = (종류) => `«가림:${종류}»`;
+
+/**
+ * 찾는 것들.
+ *
+ * 순서가 뜻을 갖는다 — 좁은 것을 먼저 본다. `sk-ant-...` 를 `sk-...` 가 먼저
+ * 집어삼키면 무엇이 가려졌는지가 뭉개진다.
+ *
+ * 넓게 잡지 않는다. 코드에 흔한 글자를 비밀로 오인해 가려 버리면, 모델이 보는
+ * 코드가 조용히 달라진다. 그건 여기서 막으려는 것보다 더 나쁜 고장이다.
+ */
+export const 갈래 = [
+  {
+    id: '사설키',
+    re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  },
+  { id: 'anthropic', re: /\bsk-ant-[A-Za-z0-9_-]{16,}/g },
+  { id: 'openai', re: /\bsk-[A-Za-z0-9_-]{20,}/g },
+  { id: 'github', re: /\b(?:gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{20,})\b/g },
+  { id: 'slack', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { id: 'aws', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  { id: 'google', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  {
+    // 머리.몸통.서명 세 토막. 안에 무엇이 들었는지 우리는 안 열어 본다.
+    id: 'jwt',
+    re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+  },
+  {
+    // https://사람:토큰@호스트 — git remote -v 가 이 모양으로 찍는다.
+    // 사람 이름은 남긴다. 무슨 계정인지 모르면 사람이 손을 못 쓴다.
+    id: '주소속열쇠',
+    re: /([a-z][a-z0-9+.-]*:\/\/)([^\s/:@]{1,64}):([^\s/@]{1,256})@/gi,
+    바꾸기: (m, 앞, 사람) => `${앞}${사람}:${표('주소속열쇠')}@`,
+  },
+  {
+    /*
+     * 줄 끝까지 가린다.
+     *
+     * `Authorization: Bearer eyJ…` 에서 `\S+` 만 잡으면 'Bearer' 만 가려지고
+     * 진짜 값은 그 뒤에 그대로 남는다. 앞의 낱말을 가리고 뒤의 열쇠를 남기는
+     * 것은 안 가린 것만 못하다 — 가렸다고 믿게 만들기 때문이다.
+     *
+     * 이미 가린 자리는 다시 안 건드린다. 두 번 가리면 무엇이 가려졌는지가
+     * 뭉개지고 셈도 부풀려진다.
+     */
+    id: '헤더',
+    re: /\b(Authorization|Proxy-Authorization|X-Api-Key|Api-Key|X-Auth-Token)(\s*[:=]\s*)(?!«)([^\r\n]+)/gi,
+    바꾸기: (m, 이름, 사이) => `${이름}${사이}${표('헤더')}`,
+  },
+  {
+    /*
+     * 이름이 열쇠라고 말하는 환경변수.
+     *
+     * 값이 비었거나 이미 가려진 것은 그냥 둔다 — `API_KEY=` 만 있는 줄까지
+     * 손대면 화면에 «가림» 만 늘어나고 알아볼 것이 없어진다.
+     */
+    id: '환경변수',
+    re: /\b([A-Z][A-Z0-9_]{2,}(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD|CREDENTIALS?))(\s*[:=]\s*)(["']?)(?!«)([^\s"']{4,})\3/g,
+    바꾸기: (m, 이름, 사이) => `${이름}${사이}${표('환경변수')}`,
+  },
+];
+
+/**
+ * 안 고치고 세기만 한다.
+ *
+ * 파일을 읽었을 때 쓰는 길이다. 무엇이 들어왔는지는 알려야 하고, 글자는
+ * 건드리면 안 된다.
+ *
+ * @returns {Array<{종류: string, 몇번: number}>}
+ */
+export function 훑기(글, { 열쇠들 = [] } = {}) {
+  /*
+   * 가려 보고 그 결과만 센다. 글은 안 돌려준다.
+   *
+   * 세는 길을 따로 두면 두 벌이 되고, 두 벌은 언젠가 어긋난다 — "가릴 때는
+   * 3군데였는데 셀 때는 5군데" 같은 식으로. 겹치는 규칙 때문에 실제로 그렇게
+   * 된다. 한 길로만 간다.
+   */
+  return 가리기(글, { 열쇠들 }).가린것;
+}
+
+/**
+ * 가린다.
+ *
+ * @param {string} 글
+ * @param {object} o
+ * @param {string[]} o.열쇠들  정확히 아는 비밀 (설정에 든 게이트웨이 열쇠 등).
+ *                             이건 짐작이 아니라 아는 값이라 언제나 먼저 지운다.
+ * @returns {{글: string, 가린것: Array<{종류, 몇번}>}}
+ */
+export function 가리기(글, { 열쇠들 = [] } = {}) {
+  const 원본 = String(글 ?? '');
+  if (!원본) return { 글: 원본, 가린것: [] };
+
+  let s = 원본;
+
+  // 아는 값부터. 짐작보다 아는 것이 먼저다.
+  for (const 열쇠 of 아는열쇠(열쇠들)) {
+    if (s.includes(열쇠)) s = s.split(열쇠).join(표('설정한열쇠'));
+  }
+
+  for (const g of 갈래) {
+    g.re.lastIndex = 0;
+    s = s.replace(g.re, (...인자) => (g.바꾸기 ? g.바꾸기(...인자) : 표(g.id)));
+  }
+
+  return { 글: s, 가린것: 남은표세기(s) };
+}
+
+/*
+ * 몇 군데를 가렸는지는 **결과를 보고** 센다. 바꾼 횟수를 세면 안 된다.
+ *
+ * 규칙끼리 겹치기 때문이다 — `Authorization: Bearer eyJ…` 는 jwt 가 먼저
+ * 가리고 헤더가 그 위를 다시 가린다. 바꾼 횟수로 세면 "2군데를 가렸습니다"
+ * 가 되는데 글에는 표가 하나뿐이다. 사람이 세어 보면 안 맞는다.
+ */
+function 남은표세기(글) {
+  const 센것 = new Map();
+  for (const m of String(글).matchAll(/«가림:([^»]+)»/g)) {
+    센것.set(m[1], (센것.get(m[1]) ?? 0) + 1);
+  }
+  return [...센것].map(([종류, 몇번]) => ({ 종류, 몇번 }));
+}
+
+/**
+ * 모델에게 붙일 한마디.
+ *
+ * 표만 남기고 말이 없으면 모델은 «가림:openai» 를 진짜 값으로 알고 그걸
+ * 명령에 다시 써 넣는다. 그러면 명령이 실패하고, 왜 실패했는지 모른 채
+ * 같은 것을 되풀이한다. 한 줄이면 그 고리가 안 생긴다.
+ */
+export function 가렸다는말(가린것) {
+  if (!가린것?.length) return '';
+  const 셈 = 가린것.reduce((a, x) => a + x.몇번, 0);
+  const 종류 = 가린것.map((x) => x.종류).join(' · ');
+  return `\n\n(deel 이 이 출력에서 비밀로 보이는 값 ${셈}군데를 가렸습니다: ${종류}.`
+    + ' 「«가림:…»」 은 진짜 값이 아닙니다 — 명령에 그대로 써 넣지 마세요.'
+    + ' 그 값이 꼭 필요하면 사용자에게 물어보세요.)';
+}
+
+/** 사람에게 보일 한 줄. 파일 쪽에서는 이것만 하고 글은 안 건드린다. */
+export function 봤다는말(가린것) {
+  if (!가린것?.length) return '';
+  const 셈 = 가린것.reduce((a, x) => a + x.몇번, 0);
+  return `비밀로 보이는 값 ${셈}군데가 대화에 들어갔습니다 (${가린것.map((x) => x.종류).join(' · ')})`;
+}
+
+/**
+ * 지금 설정에서 '정확히 아는 비밀' 을 모은다.
+ *
+ * 짧은 것은 뺀다. 세 글자짜리 열쇠를 그대로 찾아 지우면 멀쩡한 글에서
+ * 그 세 글자가 든 자리가 전부 뭉개진다 — 열쇠가 'test' 인 시험 설정에서
+ * 실제로 그럴 수 있다.
+ */
+export function 아는열쇠(것들) {
+  const out = [];
+  for (const v of Array.isArray(것들) ? 것들 : [것들]) {
+    const s = typeof v === 'string' ? v.trim() : '';
+    if (s.length >= 8 && !out.includes(s)) out.push(s);
+  }
+  // 긴 것부터 지운다. 짧은 것이 긴 것의 일부일 때 순서가 뒤바뀌면 반쪽만 지워진다.
+  return out.sort((a, b) => b.length - a.length);
+}
+
+/**
+ * 이 도구의 결과를 가려도 되는가.
+ *
+ * 한 번 쓰고 버려지는 출력만 가린다. 파일에서 읽어 온 글은 모델이 그대로
+ * 되돌려 쓸 수 있으므로 절대 안 가린다 — 위 머리말 참고.
+ */
+export const 가릴도구 = new Set(['Bash', 'Verify', 'Jobs', 'WebFetch']);

package/src/safety/undo.js

@@ -1,7 +1,7 @@
 // 되돌리기. 승인 프롬프트를 안 쓰는 대신 이게 안전망이다.
 // 파일을 고치기 전에 항상 이전 내용을 떠 놓고, /undo 로 턴 단위로 되돌린다.
 import { join } from 'node:path';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, appendFileSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, appendFileSync, statSync } from 'node:fs';
 import { looksBinary } from '../tools/encoding.js';
 
 // 되돌리기 이력은 파일 내용을 통째로 담는다. 이만큼 커지면 오래된 턴을 버린다.
@@ -131,11 +131,18 @@ export class History {
     return seen;
   }
 
-  // 최근 n 개 턴을 되돌린다. 되돌린 파일 목록을 반환.
+  /**
+   * 최근 n 개 턴을 되돌린다. 되돌린 파일 목록을 반환.
+   *
+   * turnIds 를 같이 준다 — **어느** 턴을 되돌렸는지 부르는 쪽이 알아야 한다.
+   * 파일만 되돌리고 대화는 그대로 두면, 모델은 지워진 코드가 아직 있는 줄 알고
+   * 그 위에 이어서 일한다. 그 거짓말을 걷어내려면 개수가 아니라 번호가 필요하다.
+   * (session.되감기 를 볼 것.)
+   */
   undo(n = 1) {
     const recs = this.all();
     const turns = this.turns().slice(-n);
-    if (!turns.length) return { restored: [], turns: 0 };
+    if (!turns.length) return { restored: [], turns: 0, turnIds: [] };
 
     const target = recs.filter((r) => turns.includes(r.turn));
     // 같은 파일이 여러 번 바뀌었으면 가장 이른 상태로 되돌려야 한다.
@@ -173,7 +180,7 @@ export class History {
     // 되돌린 기록은 잘라낸다.
     const keep = recs.filter((r) => !turns.includes(r.turn));
     writeFileSync(this.file, keep.map((r) => JSON.stringify(r)).join('\n') + (keep.length ? '\n' : ''), 'utf8');
-    return { restored, turns: turns.length };
+    return { restored, turns: turns.length, turnIds: turns.slice() };
   }
 }
 

package/src/setup.js

@@ -1,6 +1,6 @@
 // 첫 실행 마법사 + 진단 실행.
-import { c, say, rule, mark, width } from './ui/ansi.js';
-import { ask, pick, confirm } from './ui/prompt.js';
+import { c, say, rule, mark } from './ui/ansi.js';
+import { ask, pick } from './ui/prompt.js';
 import { spin } from './ui/spinner.js';
 import { detect } from './backend/detect.js';
 import { probe } from './backend/probe.js';

package/src/skills/discover.js

@@ -7,7 +7,7 @@
 // 플러그인도 없다 — 거기서는 방법론이 0개였고, 모델은 매번 제 나름대로 했다.
 // 시킨 것만 겨우 하고 끝나는 얄팍한 결과가 거기서 나온다.
 // 품고 다니는 것은 **가장 낮은 자리**에 둔다. 같은 이름을 사용자가 만들면 그쪽이 이긴다.
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';

package/src/tools/desc.en.js

@@ -0,0 +1,219 @@
+/**
+ * 도구 설명 영어판 — 모델이 읽는 글이다.
+ *
+ * ── 왜 여기 따로 두나 ───────────────────────────────────────────────────
+ *
+ * index.js 의 한글 설명은 손대지 않는다. 저 글은 오래 겪으면서 한 문장씩
+ * 눌러 온 것이라(“앞부분을 다시 보내지 마라”, “파일 목록만 봐서는 안 보인다”),
+ * 그 파일을 두 언어로 갈라 놓으면 다음에 한쪽만 고치게 된다. 여기 표에
+ * 없는 것은 한글 설명이 그대로 나간다 — 화면 말과 같은 규칙이다.
+ *
+ * ── 왜 옮기나 ───────────────────────────────────────────────────────────
+ *
+ * 두 가지다. 하나는 영어로 켠 사람이 한국어 도구 설명을 받으면, 모델이
+ * 무엇을 골라야 할지를 못 읽는다는 것. 다른 하나는 **토큰**이다.
+ * 도구 정의는 매 요청에 통째로 실리는 고정 몫인데, 한글은 글자당 약 1토큰이고
+ * 영문은 약 3.6자당 1토큰이다. 32k 창에서 이 몫이 10% 를 넘게 먹고 있었다.
+ *
+ * ── 옮길 때 지킨 것 ─────────────────────────────────────────────────────
+ *
+ * 규칙을 한 줄도 안 뺐다. 특히 이런 줄들은 글자 그대로 옮겼다 —
+ * 빠지면 그 모델만 조용히 다르게 굴고, 그 차이는 몇 걸음 뒤에야 드러난다.
+ *
+ *   Edit  “먼저 Read 로 읽어야 한다”      · 안 읽고 고치는 것을 막는 자리
+ *   Append“앞부분을 다시 보내지 마라”     · 같은 자리에서 또 잘리는 것을 막는 자리
+ *   Bash  “끝나지 않는 것은 background”   · 시간 초과로 죽는 것을 막는 자리
+ *   Verify“확인 못 한 것은 못 했다고”     · 이 프로그램이 거짓말을 안 하게 하는 자리
+ *
+ * 도구 이름과 인자 이름은 **안 옮긴다.** 그건 식별자다. Task 의 목적·할일처럼
+ * 한글로 된 인자 이름도 그대로 둔다 — 이름을 바꾸면 그 도구가 아예 안 불린다.
+ */
+export const 도구설명EN = {
+  Read: {
+    desc: 'Read one file. Line numbers come back with it. You must read a file before editing it.'
+      + ' Excel files (.xlsx/.xlsm/.xls) can be read directly too — they come back as CSV per sheet,'
+      + ' so there is no need to ask the user to export anything. Excel files are read-only here, though.',
+    params: {
+      file_path: 'path of the file to read',
+      offset: 'first line (1-based). Only for large files',
+      limit: 'how many lines to read',
+    },
+  },
+  Write: {
+    desc: 'Create a file, or overwrite one completely. Use Edit to change part of a file.'
+      + ' **You can create several files in one call** — pass them as an array in files.'
+      + ' Do that when you are laying out a folder structure. One call per file means one model'
+      + ' round trip per file, and an eight-file skeleton loses minutes to that.',
+    params: {
+      file_path: 'path to write (single file)',
+      content: 'the whole file content (single file)',
+      files: 'several files at once. When you use this, leave file_path and content out.',
+    },
+  },
+  Append: {
+    desc: 'Append to the end of a file. This is how you build a large file — Write the first part,'
+      + ' then call Append repeatedly until it is complete. Splitting it and landing it for certain'
+      + ' beats trying to fit it in one call and getting cut off. No Read needed first — you are only'
+      + ' adding to the end, so there is nothing to read.',
+    params: {
+      file_path: 'path of the file to append to',
+      content: 'what to add at the end',
+    },
+  },
+  Edit: {
+    desc: 'Replace an exactly matching string in a file. You must Read it first.'
+      + ' **If there are several places to change, send them in one call as the edits array** —'
+      + ' they may even be in different files. One call per place means one model round trip per'
+      + ' place, and a six-place cleanup loses minutes to that.',
+    params: {
+      file_path: 'path of the file to edit (single edit)',
+      old_string: 'what to replace. Must be unique within the file',
+      new_string: 'what to replace it with',
+      replace_all: 'true to replace every occurrence',
+      edits: 'several places at once, applied in the order given. When you use this, leave the arguments above out.',
+    },
+  },
+  Glob: {
+    desc: 'Find files by name pattern. e.g. **/*.js, src/**/*.{ts,tsx}',
+    params: {
+      pattern: 'glob pattern',
+      path: 'folder to start from. Defaults to the whole working folder',
+    },
+  },
+  Grep: {
+    desc: 'Search file contents with a regular expression.',
+    params: {
+      pattern: 'regular expression',
+      path: 'folder or file to search',
+      glob: 'restrict which files. e.g. **/*.js',
+      output_mode: 'defaults to files_with_matches',
+      '-i': 'ignore case',
+      '-n': 'show line numbers',
+      head_limit: 'cap the number of results',
+    },
+  },
+  Skill: {
+    desc: 'Open one skill and read it. The list carries only names and descriptions,'
+      + ' so pick the one you need and pull its body with this.',
+    params: { name: 'skill name, exactly as listed' },
+  },
+  Bash: {
+    desc: 'Run a command. Commands that cannot be undone are blocked.'
+      + ' **Anything that never ends (dev servers, watch) must be started with background: true** —'
+      + ' called plainly it dies on timeout. After starting one, read its output with Jobs.',
+    params: {
+      command: 'the command to run',
+      description: 'one line on what this command does',
+      timeout: 'time limit in ms. Default 120000',
+      background: 'true for a command that never ends. Returns immediately; read it with Jobs',
+    },
+  },
+  WebFetch: {
+    desc: 'Read a web page. Read-only — nothing is sent. Use it to check documentation, an error'
+      + ' message, or how a library is used. Addresses on this machine or an internal network are'
+      + ' not read. Several calls to the same site go out one after another, so they cost that much'
+      + ' more time — fetch only what you need. Truncated JSON cannot be read, so if it comes back'
+      + ' cut, narrow the request or raise max_chars and call again.',
+    params: {
+      url: 'address to read (http/https)',
+      max_chars: 'maximum characters to pull. Left out, it is sized to the model. Raise it if the'
+        + ' material comes back cut (max 120000)',
+    },
+  },
+  Recall: {
+    desc: 'Search past sessions in this folder. When the user points back ("last time"), use this'
+      + ' instead of asking again. This does not search file contents — that is Grep.',
+    params: {
+      query: 'what to look for. Two or three words (e.g. "CP949 encoding")',
+      limit: 'how many to bring back (default 8)',
+      tools: 'also dig through tool results (default false)',
+    },
+  },
+  Remember: {
+    desc: 'Write one line that outlives this session. Rules the user set, promises made, mistakes'
+      + ' not to repeat. Do not record anything that only applies to this job, or anything a file'
+      + ' would tell you. This line rides on every later request — keep it to one sentence.',
+    params: { text: 'one line (e.g. "internal documents are read as CP949 and written back as CP949")' },
+  },
+  TodoWrite: {
+    desc: 'Create and update the todo list. For anything that takes several steps, build the list'
+      + ' first and update it the moment each step finishes. Always send the whole list. state is'
+      + ' one of todo / doing / done, and only one item may be doing at a time. The number of steps'
+      + ' is set by the size of the job — there is no fixed count and no cap. Do not squeeze unrelated'
+      + ' work into one line to hit a number. Write each step small enough to check on its own.',
+    params: { todos: 'the whole todo list. No cap — as many as the job needs' },
+  },
+  Verify: {
+    desc: 'Check that what you made actually works. Call this **before** you finish, without fail.'
+      + ' A file existing and a file working are different things — an unclosed tag, a src pointing'
+      + ' at a file that is not there, one missing bracket in JS: none of that shows in a file listing.'
+      + ' What can be run gets run (node --check, py_compile); what cannot gets read (HTML tag pairs,'
+      + ' missing references, CSS braces, JSON). Whatever it could not check, it tells you it could not.'
+      + ' Running tests or a build is Bash — that goes through the user for approval.',
+    params: { paths: 'files to check. Left out, it checks everything checkable in the working folder.' },
+  },
+  Outline: {
+    desc: 'See only the **skeleton** of a folder or file — per file, the names and line numbers of'
+      + ' functions, classes, types, and headings. Call this before touching code you did not write.'
+      + ' It tells you what is where for a fraction of what reading whole files costs. Pick the places'
+      + ' to change here, then Read **only those files**. Reads js/ts, py, java/kotlin, go, rust, c#,'
+      + ' md, html, css, sh, json.',
+    params: {
+      path: 'folder or file path. Defaults to the whole working folder',
+      pattern: 'narrow by name (e.g. **/*.js). Left out, everything',
+    },
+  },
+  Task: {
+    desc: 'Split a chunk of a large job off as a subtask and **run it separately.** The subtask works'
+      + ' start to finish in its own conversation and returns only a summary — the files it read do'
+      + ' not pile up in your window. That is why work that creates or edits several files has to be'
+      + ' divided this way to get to the end. One chunk must be finishable on its own (e.g. "create'
+      + ' index.html and style.css"). The subtask cannot see your conversation — put everything it'
+      + ' needs into 할일. Do not use this for one short job. Doing it yourself is faster.',
+    params: {
+      목적: 'this chunk in one line (e.g. "build the dashboard page skeleton")',
+      할일: 'everything the subtask has to do. It cannot see this conversation, so put the background,'
+        + ' the decisions, and the file paths here. Say what counts as done, too.',
+      모드: 'how the subtask works: code (builds and edits) · debug (finds causes) · ask (reads and'
+        + ' answers only). Defaults to code.',
+      모델: 'hand this chunk to a **different model**. Only profile names the user has configured'
+        + ' work (do not invent an address — it will not be accepted). Left out, it stays on the model'
+        + ' you are using. Handing routine work (formatting, repetitive edits, short summaries) to a'
+        + ' small model keeps your window from filling. Do the work that needs judgement yourself.',
+    },
+  },
+  Def: {
+    desc: 'Ask the language server **where a name is defined.** You get the location without reading'
+      + ' the file. Unlike Grep it does not hand you the wrong places — not the same name in a comment,'
+      + ' not the same name in a third-party library, not the same name inside a string.'
+      + ' Call this before touching code you did not write. Once you know where it is, Read only that file.'
+      + ' If the name exists in several places you get the list, and file_path picks one.',
+    params: {
+      name: 'the name to find (function, class, variable)',
+      file_path: 'the file the name is used in. Use it when the same name exists in several places',
+      line: 'line number inside file_path where the name appears (1-based)',
+    },
+  },
+  Refs: {
+    desc: 'Ask the language server for **every place a name is used.** Call it before you rename'
+      + ' something or change a function — this is what tells you how many places have to change together.'
+      + ' Unlike the hundreds of lines Grep gives you, only the places that really use it come back.'
+      + ' Grep still finds comments, config and docs, though: use this for the code and Grep for the rest'
+      + ' when you rename something outright.',
+    params: {
+      name: 'the name to find (function, class, variable)',
+      file_path: 'the file the name is defined in. Use it when the same name exists in several places',
+      line: 'line number inside file_path where the name appears (1-based)',
+      include_declaration: 'include the definition itself. Default false',
+    },
+  },
+  Jobs: {
+    desc: 'List, read, and end background commands (Bash with background). Called with no number,'
+      + ' you get the list. Given a number, you get whatever output arrived since last time.'
+      + ' If you started a server, you must end it when the job is done.',
+    params: {
+      번호: 'job number to look at. Left out, the list',
+      끝내기: 'true to end that job (stop)',
+    },
+  },
+};

package/src/tools/edit-match.js

@@ -46,11 +46,22 @@ function findAll(text, needle, tier) {
   let re;
   try { re = new RegExp(p, 'g'); } catch { return []; }
   const out = [];
-  for (const m of text.matchAll(re)) {
-    if (m[0].length === 0) continue;
-    out.push({ start: m.index, end: m.index + m[0].length });
-    if (out.length > 50) break;   // 너무 많으면 어차피 모호하다
-  }
+  // 만들 때 말고 **돌릴 때** 터지는 것이 있다.
+  //
+  // 모델은 큰 파일을 고칠 때 덩이를 통째로 old_string 에 담아 보낸다. 4만 자쯤
+  // 넘어가면 new RegExp 는 멀쩡히 만들어지는데(패턴만 훑는다) 실제로 돌릴 때
+  // 프로그램 크기 한도에 걸려 SyntaxError 가 난다. 위의 try 는 만들 때만 감싸므로
+  // 그 오류가 그대로 튀어나가서 "찾지 못했습니다" 대신 도구가 죽었다.
+  //
+  // 여기서는 못 찾은 것으로 친다. 정확히 일치하는 경우는 위에서 indexOf 로 이미
+  // 처리했으니, 느슨하게 맞춰 보는 이 길만 포기하는 것이다.
+  try {
+    for (const m of text.matchAll(re)) {
+      if (m[0].length === 0) continue;
+      out.push({ start: m.index, end: m.index + m[0].length });
+      if (out.length > 50) break;   // 너무 많으면 어차피 모호하다
+    }
+  } catch { return []; }
   return out;
 }
 

package/src/tools/excel-com.js

@@ -17,7 +17,7 @@
 //   2) 엑셀은 바쁘면 호출을 거절한다(0x80010001, 0x800AC472). 잘못된 호출이
 //      아니라 '지금은 말고' 라는 뜻이라, 쉬었다 다시 부르면 된다.
 import { spawn } from 'node:child_process';
-import { mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { decode } from './encoding.js';

package/src/tools/excel.js

@@ -5,7 +5,7 @@
 //
 // 부르는 쪽은 어느 갈래인지 몰라도 된다. 다만 암호가 필요할 때는 물어볼 수
 // 있어야 하므로, 물어보는 방법을 받아 온다(askPassword).
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
 import { readXlsx, toCsv, looksXlsx, looksOle } from './xlsx.js';
 import { excelToTables, canUseExcel } from './excel-com.js';

package/src/tools/fsutil.js

@@ -171,14 +171,6 @@ export function walk(root, { limit = 20000, skipDirs = SKIP_DIRS } = {}) {
   return out;
 }
 
-// 텍스트 파일인지 — 앞부분에 NUL 이 있으면 바이너리로 본다.
-export function isText(path) {
-  try {
-    const fd = readFileSync(path);
-    return !fd.subarray(0, 8000).includes(0);
-  } catch { return false; }
-}
-
 /**
  * 글 파일을 읽는다. 무엇으로 쓰여 있든 알아보고 읽는다.
  *