deel-local-cli 0.9.0 → 1.0.1

package/src/agent/memory.js

@@ -0,0 +1,152 @@
+/**
+ * 기억 — 대화가 끝나도 남는 것.
+ *
+ * 왜 필요한가:
+ *   대화는 켤 때마다 처음부터다. 그래서 매번 같은 것을 설명하게 된다 —
+ *   "우리 문서는 CP949 다", "검증 포트로 7080 은 쓰지 마라", "빌드는 npm run b".
+ *   /compact 로 접히면 그마저 사라진다. 사람은 두 번째부터 짜증이 나고,
+ *   세 번째부터는 그냥 안 쓴다.
+ *
+ *   지난 대화 찾기(recall.js)와는 다른 물건이다. 그쪽은 **찾아야** 나오고,
+ *   이쪽은 **처음부터 들어가 있다.** 매번 찾으라고 할 수 없는 것 —
+ *   지켜야 하는 규칙, 되풀이하면 안 되는 실수 — 이 여기 온다.
+ *
+ * 어디에 두나:
+ *   .deel/memory.md — 사람이 열어 고칠 수 있는 글이다. 데이터베이스가 아니다.
+ *   이게 중요하다. 모델이 잘못 적은 것을 사람이 지울 수 있어야 한다.
+ *   틀린 기억은 없느니만 못하다 — 매 요청에 실려 계속 틀리게 만든다.
+ *
+ * 왜 상한을 두나:
+ *   기억은 **매 요청마다** 통째로 나간다. 백 줄이면 백 줄이 매번 나간다.
+ *   그래서 자리를 정해 두고, 넘으면 넘었다고 말한다.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// 기억 전체가 차지할 수 있는 최대 글자. 대략 2,000 토큰쯤이다.
+export const 기억최대 = 6000;
+// 한 줄이 이보다 길면 자른다. 모델이 파일을 통째로 기억에 넣으려 드는 일이 있다.
+export const 한줄최대 = 400;
+// 줄 수 상한. 자리가 남아도 이보다 많으면 사람이 못 읽는다.
+export const 줄최대 = 60;
+
+export const 자리 = (root) => join(root, '.deel', 'memory.md');
+
+const 머리말 = `# 기억
+
+이 파일은 deel 이 대화 사이에 들고 다니는 메모입니다.
+매 요청마다 모델에게 통째로 실려 나갑니다 — 그러니 짧게, 오래 갈 것만 적습니다.
+
+직접 고치셔도 됩니다. 틀린 줄은 지우세요. 지우면 그걸로 끝입니다.
+`;
+
+/** 파일에서 기억 줄을 읽어 온다. 머리말과 빈 줄은 뺀다. */
+export function 읽기(root) {
+  const p = 자리(root);
+  if (!existsSync(p)) return { 줄들: [], 자리: p, 있음: false };
+  let 글;
+  try { 글 = readFileSync(p, 'utf8'); } catch { return { 줄들: [], 자리: p, 있음: false }; }
+  const 줄들 = [];
+  for (const raw of 글.split(/\r?\n/)) {
+    const l = raw.trim();
+    if (!l) continue;
+    if (l.startsWith('#')) continue;                 // 머리말
+    if (l.startsWith('이 파일은') || l.startsWith('매 요청마다')) continue;
+    if (l.startsWith('직접 고치셔도') || l.startsWith('직접 고치')) continue;
+    줄들.push(l.replace(/^[-*]\s*/, ''));            // 목록 표시는 떼고 담는다
+  }
+  return { 줄들, 자리: p, 있음: true };
+}
+
+/** 줄들을 파일로 되돌려 쓴다. */
+export function 쓰기(root, 줄들) {
+  const p = 자리(root);
+  mkdirSync(dirname(p), { recursive: true });
+  const 몸 = 줄들.map((l) => `- ${l}`).join('\n');
+  writeFileSync(p, `${머리말}\n${몸}\n`, 'utf8');
+  return p;
+}
+
+/**
+ * 한 줄을 더한다.
+ *
+ * 이미 있는 것과 거의 같으면 안 더한다. 안 그러면 같은 말이 조금씩 다른 꼴로
+ * 스무 줄 쌓인다 — 모델은 자기가 방금 적은 것을 기억 못 하기 때문이다.
+ *
+ * @returns {{ok: boolean, why?: string, 줄: string, 줄수: number, 넘침?: boolean}}
+ */
+export function 더하기(root, 글) {
+  const 줄 = 다듬기(글);
+  if (!줄) return { ok: false, why: '적을 내용이 비었습니다', 줄: '', 줄수: 0 };
+
+  const { 줄들 } = 읽기(root);
+  if (줄들.some((x) => 같은말(x, 줄))) {
+    return { ok: false, why: '이미 기억하고 있습니다', 줄, 줄수: 줄들.length };
+  }
+
+  const 새것 = [...줄들, 줄];
+  // 자리가 넘치면 **오래된 것부터** 뺀다. 최근에 정한 것이 대개 맞다.
+  let 넘침 = false;
+  while (새것.length > 줄최대 || 새것.join('\n').length > 기억최대) {
+    if (새것.length <= 1) break;
+    새것.shift();
+    넘침 = true;
+  }
+  쓰기(root, 새것);
+  return { ok: true, 줄, 줄수: 새것.length, 넘침 };
+}
+
+/** 번호로 지운다(1부터). 사람이 /memory 화면을 보고 고르는 자리다. */
+export function 지우기(root, 번호) {
+  const { 줄들 } = 읽기(root);
+  const i = Number(번호) - 1;
+  if (!Number.isInteger(i) || i < 0 || i >= 줄들.length) return { ok: false, why: '그런 번호가 없습니다' };
+  const 뺀것 = 줄들[i];
+  const 남은것 = 줄들.filter((_, n) => n !== i);
+  쓰기(root, 남은것);
+  return { ok: true, 뺀것, 줄수: 남은것.length };
+}
+
+/** 통째로 비운다. */
+export function 비우기(root) {
+  쓰기(root, []);
+  return { ok: true };
+}
+
+/** 한 줄로 다듬는다 — 줄바꿈을 없애고 길이를 자른다. */
+function 다듬기(글) {
+  let s = String(글 ?? '').replace(/\s+/g, ' ').trim();
+  s = s.replace(/^[-*]\s*/, '');
+  if (s.length > 한줄최대) s = s.slice(0, 한줄최대) + '…';
+  return s;
+}
+
+/**
+ * 두 줄이 사실상 같은 말인가.
+ *
+ * 글자 그대로 비교하면 "CP949 를 쓴다" 와 "CP949를 쓴다" 가 다른 줄이 된다.
+ * 공백·조사·문장부호를 털고 견준다. 완벽할 필요는 없다 —
+ * 여기서 하려는 것은 '똑같은 말이 쌓이는 것' 을 막는 것뿐이다.
+ */
+function 같은말(a, b) {
+  const 털기 = (s) => String(s).toLowerCase().replace(/[\s.,!?~·'"()[\]]/g, '');
+  const x = 털기(a);
+  const y = 털기(b);
+  if (x === y) return true;
+  // 한쪽이 다른 쪽을 통째로 품고 있고 길이 차가 크지 않으면 같은 말로 본다.
+  const [짧, 긴] = x.length <= y.length ? [x, y] : [y, x];
+  return 짧.length >= 8 && 긴.includes(짧) && 긴.length - 짧.length <= 짧.length * 0.5;
+}
+
+/**
+ * 시스템 프롬프트에 넣을 토막.
+ *
+ * 없으면 빈 글을 돌려준다 — "기억: (없음)" 같은 줄을 넣으면 그 자체가
+ * 매 요청마다 나가는 쓰레기가 된다.
+ */
+export function 프롬프트토막(root) {
+  const { 줄들 } = 읽기(root);
+  if (!줄들.length) return '';
+  return '\n--- 기억 (지난 대화에서 정한 것. 사용자가 다시 말하지 않아도 지킨다) ---\n'
+    + 줄들.map((l) => `- ${l}`).join('\n');
+}

package/src/agent/mention.js

@@ -0,0 +1,164 @@
+// @파일 지목 — 말 속에 @경로 를 쓰면 그 파일을 바로 붙여 보낸다.
+//
+// 왜 필요한가:
+//   지금은 파일 하나 보여주려면 모델이 Read 도구를 스스로 불러야 한다. 왕복이
+//   한 번 더 든다. 로컬 모델은 도구 호출이 약해서 그 한 번이 자주 헛돈다 —
+//   엉뚱한 경로를 부르거나, 아예 안 부르고 지어낸다. 사람은 이미 어느 파일인지
+//   알고 있는데 모델더러 찾아보라고 시키는 셈이다.
+//
+// 여기서 어려운 것은 붙이는 일이 아니라 '아닌 것을 파일로 오해하지 않기' 다.
+// @ 로 시작하는 것은 세상에 널렸다 — 이메일 주소, CSS 의 @media, 파이썬 장식자,
+// npm 의 @scope/pkg, 사람 아이디. 잘못 붙이면 엉뚱한 글이 대화에 섞여 들어가고,
+// 사람은 자기가 안 보낸 것이 왜 거기 있는지 모른다.
+//
+// 그래서 규칙을 하나로 뒀다: **실제로 있는 경로일 때만 붙인다.**
+// 없으면 아무 말 없이 글자 그대로 둔다. 지목이 아니었을 테니 조용한 편이 맞다.
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { readTextFull } from '../tools/fsutil.js';
+import { estimateTokens } from './session.js';
+
+// 붙일 수 있는 최대 토큰. 부르는 쪽에서 컨텍스트에 맞춰 넘겨준다.
+const 기본예산 = 6000;
+const 폴더최대 = 60;      // 폴더를 지목했을 때 늘어놓을 항목 수
+const 뒤에붙는것 = /[,.?!;:)\]}"'」』]+$/;
+
+/**
+ * 글에서 @지목을 찾는다. 붙일지 말지는 여기서 안 정한다 — 자리만 찾는다.
+ *
+ * @returns {Array<{path:string, start:number, end:number, raw:string}>}
+ */
+export function findMentions(text) {
+  const s = String(text ?? '');
+  const out = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] !== '@') continue;
+    // 앞이 글자면 지목이 아니다 — hong@example.com 의 @ 가 여기서 걸러진다.
+    const 앞 = i > 0 ? s[i - 1] : ' ';
+    if (!/[\s(\[{'"]/.test(앞)) continue;
+
+    // @"띄어쓰기 든 이름.txt" — 따옴표로 묶으면 통째로 하나다.
+    if (s[i + 1] === '"' || s[i + 1] === "'") {
+      const 따옴 = s[i + 1];
+      const 끝 = s.indexOf(따옴, i + 2);
+      if (끝 > i + 2) {
+        out.push({ path: s.slice(i + 2, 끝), start: i, end: 끝 + 1, raw: s.slice(i, 끝 + 1) });
+        i = 끝;
+        continue;
+      }
+    }
+
+    let j = i + 1;
+    while (j < s.length && !/[\s"'`]/.test(s[j])) j++;
+    if (j === i + 1) continue;                    // @ 뒤가 비었다
+    const raw = s.slice(i, j);
+    out.push({ path: s.slice(i + 1, j), start: i, end: j, raw });
+    i = j - 1;
+  }
+  return out;
+}
+
+/** 이 지목이 가리키는 실제 자리. 못 찾거나 범위 밖이면 왜인지 같이 준다. */
+function 찾아보기(m, scope) {
+  const 후보 = [m.path];
+  // 뒤에 붙은 문장부호를 떼고도 한 번 본다 — "@src/a.js, 이것" 처럼 쓴다.
+  const 뗀것 = m.path.replace(뒤에붙는것, '');
+  if (뗀것 && 뗀것 !== m.path) 후보.push(뗀것);
+
+  for (const p of 후보) {
+    if (!p) continue;
+    let abs;
+    try { abs = scope.resolve(p); }
+    catch (err) { return { why: 'blocked', note: err.message, path: p }; }
+    if (existsSync(abs)) return { abs, path: p };
+  }
+  return { why: 'missing', path: m.path };
+}
+
+function 폴더내용(abs, show) {
+  let 목록 = [];
+  try { 목록 = readdirSync(abs, { withFileTypes: true }); }
+  catch (err) { return `(폴더를 못 읽었습니다: ${err.message})`; }
+  const 줄들 = 목록.slice(0, 폴더최대).map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+  const 더 = 목록.length > 폴더최대 ? `\n… 전체 ${목록.length}개 중 ${폴더최대}개까지` : '';
+  return `${show} 는 폴더입니다. 안에 든 것:\n${줄들.join('\n')}${더}`;
+}
+
+/**
+ * @지목을 실제 내용으로 바꿔 붙인다.
+ *
+ * 글 자체는 안 건드린다 — 사람이 쓴 말은 그대로 두고, 뒤에 파일을 덧붙인다.
+ * 지목한 자리를 내용으로 갈아치우면 "@src/a.js 이거 왜 느려?" 가 코드 덩어리
+ * 한복판에서 끝나는 문장이 되어 버려서, 모델이 무엇을 물었는지 놓친다.
+ *
+ * @param {string} text
+ * @param {{scope?:object, budget?:number, seen?:Set<string>, onRead?:Function}} opts
+ *   seen 을 주면 통째로 붙은 파일을 '읽은 것' 으로 적어 둔다 — 그래야 Edit 이
+ *   'Read 부터 하라' 며 되돌려 보내지 않는다. 잘린 파일은 안 적는다.
+ *   안 본 데를 본 것으로 치면 그 자리를 그냥 고쳐 버린다.
+ */
+export function expand(text, { scope = null, budget = 기본예산, seen = null, onRead = null } = {}) {
+  const 원문 = String(text ?? '');
+  const 빈답 = { text: 원문, attached: [], missing: [], blocked: [] };
+  if (!원문.includes('@') || !scope?.resolve) return 빈답;
+
+  const 지목들 = findMentions(원문);
+  if (!지목들.length) return 빈답;
+
+  const attached = [];
+  const missing = [];
+  const blocked = [];
+  const 붙일것 = [];
+  const 본것 = new Set();
+  let 남은예산 = Math.max(200, Number(budget) || 기본예산);
+
+  for (const m of 지목들) {
+    const 자리 = 찾아보기(m, scope);
+    if (자리.why === 'blocked') { blocked.push({ path: 자리.path, why: 자리.note }); continue; }
+    if (자리.why === 'missing') { missing.push(자리.path); continue; }
+    if (본것.has(자리.abs)) continue;               // 같은 파일을 두 번 적지 않는다
+    본것.add(자리.abs);
+
+    const show = scope.show ? scope.show(자리.abs) : 자리.path;
+    let 몸통;
+    let 통째로 = true;
+
+    try {
+      if (statSync(자리.abs).isDirectory()) {
+        몸통 = 폴더내용(자리.abs, show);
+      } else {
+        // 사내 파일은 CP949 가 흔하다. 그냥 읽으면 통째로 깨진다.
+        const 읽음 = readTextFull(자리.abs);
+        const 줄들 = 읽음.text.split('\n');
+        const 붙은글 = 줄들.map((l, i) => `${String(i + 1).padStart(6)}\t${l}`).join('\n');
+        if (estimateTokens(붙은글) <= 남은예산) {
+          몸통 = 붙은글;
+        } else {
+          // 예산만큼만 앞에서 자른다. 글자 수로 어림잡되 남는 쪽으로 잡는다.
+          통째로 = false;
+          const 어림 = Math.max(1, Math.floor(남은예산 * 3));
+          const 자른것 = 붙은글.slice(0, 어림);
+          const 마지막줄 = 자른것.split('\n').length;
+          몸통 = `${자른것}\n… 전체 ${줄들.length}줄 중 ${마지막줄}줄까지만 붙였습니다 (나머지는 Read 로 읽으세요)`;
+        }
+        if (onRead) onRead(자리.abs, 읽음.text);
+        if (통째로 && seen) seen.add(자리.abs);
+      }
+    } catch (err) {
+      // 못 읽는 파일(바이너리 등)은 붙이지 않는다. 그렇다고 말은 해 준다.
+      몸통 = `(못 읽었습니다: ${err.message})`;
+      통째로 = false;
+    }
+
+    const 토막 = `\n\n--- ${show} ---\n${몸통}\n--- ${show} 끝 ---`;
+    남은예산 -= estimateTokens(토막);
+    붙일것.push(토막);
+    attached.push({ path: 자리.abs, show, full: 통째로 });
+    if (남은예산 <= 0) break;
+  }
+
+  if (!붙일것.length) return { text: 원문, attached, missing, blocked };
+  const 머리 = attached.length === 1
+    ? '아래는 사용자가 @ 로 지목한 파일입니다. 이미 읽은 것으로 치고 답하세요.'
+    : `아래는 사용자가 @ 로 지목한 파일 ${attached.length}개입니다. 이미 읽은 것으로 치고 답하세요.`;
+  return { text: `${원문}\n\n${머리}${붙일것.join('')}`, attached, missing, blocked };
+}

package/src/agent/modes.js

@@ -11,11 +11,19 @@
 //   오프라인일 때 웹 도구를 숨기는 것과 같은 방식이다.
 
 // 읽기만 하는 도구. 무엇을 바꾸지 않는다.
-const 읽기 = ['Read', 'Glob', 'Grep', 'WebFetch', 'Skill'];
+// Recall 은 지난 대화를 찾는다 — 파일은 안 건드리므로 읽기 쪽이다.
+// 묻기 모드에도 준다: "저번에 이거 어떻게 했더라" 가 딱 묻기 모드의 일이다.
+const 읽기 = ['Read', 'Glob', 'Grep', 'WebFetch', 'Skill', 'Recall'];
 // 계획을 적는 도구. 파일을 안 건드리므로 읽기 전용 모드에서도 준다.
-const 계획 = ['TodoWrite'];
+//
+// Remember 도 여기 있다. 기억은 사용자의 소스를 안 건드리고 .deel/memory.md
+// 한 줄을 더할 뿐이다. 오히려 계획·설계 모드에서 정한 것이야말로 다음에
+// 이어질 때 필요하다 — 거기서 못 적으면 정한 것이 그대로 날아간다.
+const 계획 = ['TodoWrite', 'Remember'];
 // 바꾸는 도구.
-const 쓰기 = ['Write', 'Edit', 'Bash'];
+// Append 는 Write 와 짝이다 — 출력 상한이 작은 모델이 큰 파일을 나눠 쓰는 길이다.
+// Write 를 주는 자리에는 반드시 같이 준다. 하나만 주면 나눠 쓸 방법이 없어진다.
+const 쓰기 = ['Write', 'Append', 'Edit', 'Bash'];
 
 export const MODES = {
   // 처음에는 여기서 시작한다.

package/src/agent/recall.js

@@ -0,0 +1,209 @@
+/**
+ * 지난 대화 찾기.
+ *
+ * 왜 필요한가:
+ *   deel 은 대화를 .deel/sessions/*.jsonl 로 꼬박꼬박 남긴다. 그런데 지금까지
+ *   할 수 있는 일은 목록을 보는 것(/sessions)과 통째로 이어받는 것(--continue)
+ *   뿐이었다. "저번에 그 인코딩 문제 어떻게 풀었더라" 를 찾을 방법이 없었다.
+ *   기록이 있는데 못 찾으면 없는 것과 같다.
+ *
+ * 왜 색인을 안 만드나:
+ *   FTS 색인을 두면 빠르지만, 색인은 반드시 낡는다 — 대화 파일은 매 턴 늘어나고,
+ *   딴 창에서도 늘어나고, 사람이 지우기도 한다. 낡은 색인은 **없는 것보다 나쁘다**:
+ *   "못 찾았습니다" 가 "없습니다" 로 읽히기 때문이다.
+ *   그래서 그때그때 읽는다. 대신 **얼마나 읽었고 무엇을 못 읽었는지 반드시 말한다.**
+ *
+ * 의존성 0 이라 점수도 직접 매긴다. 대단한 순위가 필요한 게 아니다 —
+ * 낱말이 많이 맞고, 다 맞고, 최근인 것이 위로 오면 된다.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { sessionsDir } from './store.js';
+
+// 한 번 찾을 때 읽을 최대 바이트. 넘으면 거기서 멈추고 **멈췄다고 말한다.**
+export const 읽기예산 = 64 * 1024 * 1024;
+// 한 메시지에서 볼 최대 길이. 파일을 통째로 붙인 도구 결과가 수 MB 씩 있다.
+const 메시지최대 = 200 * 1024;
+
+/**
+ * 물음을 낱말로 쪼갠다.
+ *
+ * 한국어는 띄어쓰기가 낱말 경계와 안 맞는다("인코딩을" ≠ "인코딩"). 그래서
+ * 조사처럼 보이는 꼬리를 떼어 **둘 다** 찾는다. 형태소 분석기를 붙일 수는 없다
+ * (의존성 0). 이 정도만 해도 "인코딩을 어떻게" 로 "인코딩" 을 찾아낸다.
+ */
+export function 낱말쪼개기(물음) {
+  const 조사 = /(을|를|이|가|은|는|에|에서|으로|로|와|과|의|도|만|까지|부터|에게|한테|보다|처럼|랑|이랑)$/;
+  const 본 = String(물음 ?? '').toLowerCase().split(/[\s,.;:!?()[\]{}"'`]+/).filter(Boolean);
+  const 낱말 = new Set();
+  for (const w of 본) {
+    if (w.length < 2) continue;         // 한 글자는 아무 데나 걸린다
+    낱말.add(w);
+    const 짧은 = w.replace(조사, '');
+    if (짧은.length >= 2 && 짧은 !== w) 낱말.add(짧은);
+  }
+  return [...낱말];
+}
+
+/** 맞은 자리 앞뒤를 잘라 보여 줄 토막을 만든다. */
+export function 토막내기(글, 낱말들, 폭 = 150) {
+  const s = String(글 ?? '').replace(/\s+/g, ' ').trim();
+  if (s.length <= 폭) return s;
+  const 낮은 = s.toLowerCase();
+  let 자리 = -1;
+  for (const w of 낱말들) {
+    const i = 낮은.indexOf(w);
+    if (i >= 0 && (자리 < 0 || i < 자리)) 자리 = i;
+  }
+  if (자리 < 0) return s.slice(0, 폭) + '…';
+  const 앞 = Math.max(0, 자리 - Math.floor(폭 / 3));
+  return (앞 > 0 ? '…' : '') + s.slice(앞, 앞 + 폭) + (앞 + 폭 < s.length ? '…' : '');
+}
+
+/** 메시지 하나를 사람이 읽을 글로. 도구 호출은 이름과 인자만 남긴다. */
+function 글로(m) {
+  if (typeof m?.content === 'string' && m.content) return m.content;
+  // 도구 호출은 content 가 비어 있고 tool_calls 에 들어 있다.
+  if (Array.isArray(m?.tool_calls) && m.tool_calls.length) {
+    return m.tool_calls.map((t) => `${t.function?.name ?? '도구'}(${t.function?.arguments ?? ''})`).join(' ');
+  }
+  if (Array.isArray(m?.content)) {
+    return m.content.map((p) => (typeof p === 'string' ? p : p?.text ?? '')).join(' ');
+  }
+  return '';
+}
+
+const 누구 = { user: '나', assistant: '모델', tool: '도구결과', system: '규칙' };
+
+/**
+ * 대화가 스스로 적어 둔 시각. 없거나 말이 안 되면 null 을 준다.
+ *
+ * 옛 기록에는 meta 줄이 아예 없고, 손으로 고치다 깨진 파일도 있다.
+ * 여기서 터지면 /recall 이 통째로 죽는다 — 못 읽은 날짜 하나 때문에.
+ */
+function 때(meta) {
+  const v = meta?.at;
+  if (!v) return null;
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * 지난 대화에서 찾는다.
+ *
+ * @param {string} root 작업 폴더
+ * @param {string} 물음
+ * @param {{limit?: number, 예산?: number, 지금세션?: string, 도구결과까지?: boolean}} o
+ * @returns {{맞은것: object[], 본파일: number, 전체파일: number, 읽은바이트: number, 예산초과: boolean, 낱말: string[]}}
+ */
+export function 찾기(root, 물음, o = {}) {
+  const limit = o.limit ?? 8;
+  const 예산 = o.예산 ?? 읽기예산;
+  const 도구결과까지 = o.도구결과까지 ?? false;
+  const 낱말 = 낱말쪼개기(물음);
+  const dir = sessionsDir(root);
+
+  const 빈결과 = { 맞은것: [], 본파일: 0, 전체파일: 0, 읽은바이트: 0, 예산초과: false, 낱말 };
+  if (!낱말.length || !existsSync(dir)) return 빈결과;
+
+  // 최근 것부터 본다. 예산이 모자라 멈추더라도 **쓸모 있는 쪽**에서 멈춘다.
+  const 파일들 = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.jsonl')) continue;
+    try {
+      const file = join(dir, name);
+      const st = statSync(file);
+      파일들.push({ id: name.slice(0, -6), file, at: st.mtime, bytes: st.size });
+    } catch { /* 지워지는 중이거나 권한이 없다 */ }
+  }
+  파일들.sort((a, b) => b.at - a.at);
+
+  const 맞은것 = [];
+  let 읽은바이트 = 0;
+  let 본파일 = 0;
+  let 예산초과 = false;
+  const 가장최근 = 파일들[0]?.at?.getTime?.() ?? Date.now();
+
+  for (const f of 파일들) {
+    if (읽은바이트 + f.bytes > 예산) { 예산초과 = true; break; }
+    let 원문;
+    try { 원문 = readFileSync(f.file, 'utf8'); } catch { continue; }
+    읽은바이트 += f.bytes;
+    본파일 += 1;
+
+    // 파일 전체에 낱말이 하나도 없으면 줄을 쪼갤 것도 없다. 큰 파일에서 크게 빠르다.
+    const 낮은전체 = 원문.toLowerCase();
+    if (!낱말.some((w) => 낮은전체.includes(w))) continue;
+
+    let 차례 = 0;
+    let meta = null;
+    for (const line of 원문.split('\n')) {
+      if (!line) continue;
+      let j;
+      try { j = JSON.parse(line); } catch { continue; }
+      if (j.t === 'meta') { meta = j; continue; }
+      차례 += 1;
+      if (j.role === 'system') continue;
+      if (!도구결과까지 && j.role === 'tool') continue;
+
+      const 글 = 글로(j).slice(0, 메시지최대);
+      if (!글) continue;
+      const 낮은 = 글.toLowerCase();
+
+      let 맞은낱말 = 0;
+      let 횟수 = 0;
+      for (const w of 낱말) {
+        let n = 0;
+        let i = 낮은.indexOf(w);
+        while (i >= 0 && n < 50) { n += 1; i = 낮은.indexOf(w, i + w.length); }
+        if (n) { 맞은낱말 += 1; 횟수 += n; }
+      }
+      if (!맞은낱말) continue;
+
+      /*
+       * 점수.
+       *   낱말이 **몇 개나** 맞았나가 제일 세다 — 두 낱말이 다 나오는 글이
+       *   한 낱말이 열 번 나오는 글보다 거의 언제나 원하는 것이다.
+       *   최근일수록 조금 올린다. 같은 것을 두 번 물어본 경우 최근 답이 낫다.
+       */
+      const 다맞음 = 맞은낱말 === 낱말.length ? 12 : 0;
+      const 오래됨 = Math.max(0, (가장최근 - f.at.getTime()) / (1000 * 60 * 60 * 24));
+      const 최근점 = Math.max(0, 6 - 오래됨 / 7);
+      맞은것.push({
+        세션: f.id,
+        // 화면에 적는 날짜는 **대화가 적어 둔 날**이지 파일이 만져진 날이 아니다.
+        //
+        // 이 도구는 오프라인 PC 로 폴더째 옮겨 다니는 것을 전제로 만들었다.
+        // 그렇게 옮기면 mtime 은 옮긴 날로 전부 바뀐다 — 반 년 치 대화가
+        // 하나같이 "오늘" 이 되고, 그러면 이 화면은 아무 말도 안 하는 셈이다.
+        //
+        // 점수(최근점)는 그대로 mtime 을 쓴다. 그건 파일을 읽기 전에 정해야
+        // 하는 값이고(예산 순서), 순서가 조금 흔들리는 것은 날짜가 통째로
+        // 거짓말하는 것과 무게가 다르다.
+        언제: 때(meta) ?? f.at,
+        model: meta?.model ?? null,
+        role: j.role,
+        누구: 누구[j.role] ?? j.role,
+        차례,
+        글,
+        토막: 토막내기(글, 낱말),
+        점수: 맞은낱말 * 10 + 다맞음 + Math.min(6, 횟수) + 최근점,
+      });
+    }
+  }
+
+  맞은것.sort((a, b) => b.점수 - a.점수 || b.언제 - a.언제);
+
+  // 한 대화에서 열 줄이 몰려 나오면 다른 대화를 못 본다. 세션당 셋까지만.
+  const 세션별 = new Map();
+  const 추린것 = [];
+  for (const h of 맞은것) {
+    const n = 세션별.get(h.세션) ?? 0;
+    if (n >= 3) continue;
+    세션별.set(h.세션, n + 1);
+    추린것.push(h);
+    if (추린것.length >= limit) break;
+  }
+
+  return { 맞은것: 추린것, 본파일, 전체파일: 파일들.length, 읽은바이트, 예산초과, 낱말, 전체맞음: 맞은것.length };
+}