deel-local-cli 0.8.0 → 1.0.0

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 };
+}

package/src/agent/route.js

@@ -0,0 +1,156 @@
+// 사용자가 무엇을 시켰는지 보고 알맞은 작업 모드를 고른다.
+//
+// 왜 규칙으로 하나:
+//   모델에게 "이건 무슨 일이냐" 고 한 번 더 물을 수도 있다. 그런데 그러면
+//   한마디 할 때마다 왕복이 하나 늘고, 작은 로컬 모델은 이런 분류를 잘 못한다.
+//   느려지고 틀리기까지 하면 자동으로 하는 의미가 없다.
+//
+//   그래서 낱말로 고른다. 대신 두 가지를 지킨다.
+//     1) 애매하면 안 바꾼다. 종합 모드에 그대로 둔다.
+//        잘못 바꾸는 것보다 안 바꾸는 편이 낫다 — 특히 읽기 전용 모드로
+//        잘못 보내면 사용자는 "왜 파일을 안 고쳐?" 하고 막힌다.
+//     2) 왜 그렇게 봤는지 남긴다. 화면에 그 이유가 같이 뜬다.
+//
+// 사용자가 직접 모드를 고르면 이건 아예 안 돈다. 사람이 고른 것을 뒤집지 않는다.
+
+// 낱말과 점수. 큰 점수일수록 그 모드라는 증거가 강하다는 뜻이다.
+//
+// 한국어를 먼저 두되 영어도 같이 본다 — 오류 메시지를 그대로 붙여넣는 일이 흔하다.
+const 표 = {
+  debug: [
+    // 고장은 신호가 뚜렷하다. 그리고 디버그는 파일을 고칠 수 있으므로
+    // 잘못 골라도 막히지 않는다. 그래서 세게 준다.
+    [/왜\s*안\s*(되|돼|됨)/, 5], [/안\s*(되는|돼는|됩니다|되네|돼네|돼요|되요)/, 4],
+    [/작동\s*안/, 4], [/동작\s*안/, 4],
+    [/에러|오류|예외|익셉션/, 4], [/버그/, 4],
+    [/실패/, 3], [/터(져|졌|진다)/, 3], [/죽(어|었|는다|네)/, 3],
+    [/멈(춰|췄|춘다|추)/, 3], [/먹통/, 3], [/이상(해|하다|한데)/, 3],
+    [/재현/, 3], [/스택\s*트레이스|stack\s*trace|traceback/i, 4],
+    // 'TypeError' 처럼 앞에 글자가 붙어 오는 일이 훨씬 흔하다.
+    // \berror\b 로 잡으면 정작 붙여넣은 진짜 오류 메시지를 놓친다.
+    [/error/i, 3], [/\bexception\b|\bcrash|\bfail(s|ed|ing)?\b|\bbroken\b/i, 3],
+    [/고장/, 3], [/왜\s*이(래|러|렇게\s*나)/, 2],
+    [/왜\s*(못|안)/, 3], [/뭐\s*때문(이|에)/, 3],
+  ],
+
+  plan: [
+    // '먼저' 와 붙어야 계획이다. 그냥 '어떻게' 는 설명일 수도 있다.
+    [/계획/, 5], [/플랜|\bplan\b/i, 5],
+    [/먼저\s*(정리|생각|살펴|파악|검토|짜|세)/, 4],
+    [/어떤\s*순서/, 4], [/순서(를|대로)?\s*(정|짜|잡)/, 3],
+    [/단계(를|로)?\s*(나눠|쪼개|정리)/, 3],
+    [/로드맵|\broadmap\b/i, 5],
+    [/방향(을|만)?\s*(잡|정)/, 3],
+    [/하기\s*전에\s*(정리|살펴|검토)/, 3],
+    [/무엇부터|뭐부터/, 3],
+  ],
+
+  architect: [
+    [/설계/, 5], [/아키텍(처|쳐)|architecture/i, 5],
+    [/구조(를|가|는)?\s*(어떻게|바꾸|잡|짜|개선)/, 5],
+    [/어떻게\s*(나누|쪼개|짜)/, 5],
+    [/모듈(로|을)?\s*(나누|분리)/, 3],
+    [/의존(성|\s*방향)/, 3], [/레이어|계층/, 3],
+    [/어느\s*(쪽|것)이\s*(나을|좋을)/, 3], [/선택지|대안/, 3],
+    [/패턴(을|이)?\s*(쓰|적용|고르)/, 2],
+    [/\bdesign\b|\bstructure\b|\brefactor(ing)?\s*(방향|plan)/i, 3],
+  ],
+
+  ask: [
+    // 설명은 아무것도 안 바꾸는 모드라 잘못 고르면 답답해진다. 신호를 엄격히 본다.
+    [/뭐(야|예요|입니까|지)\s*\??$/m, 5], [/무엇(인가|입니까|이야)/, 5],
+    [/설명(해|좀|을)/, 5], [/알려\s*(줘|주세요|줄래)/, 3],
+    [/어떻게\s*(동작|작동|돌아가)/, 5],
+    [/무슨\s*(뜻|의미)|의미(가|는)\s*뭐/, 5],
+    [/차이(가|는|점)/, 3],
+    [/궁금/, 3], [/왜\s*이렇게\s*(만들|짰|되어)/, 3],
+    [/\bwhat\s+is\b|\bexplain\b|\bhow\s+does\b/i, 4],
+    [/읽어(만)?\s*보고\s*(설명|알려)/, 4],
+  ],
+
+  orchestrator: [
+    // 총괄의 신호는 낱말 하나가 아니라 '넓이' 다. 그래서 하나하나는 약하게 두고
+    // 여럿이 겹칠 때 문턱을 넘게 한다 — 실제로 큰 일에는 이런 말이 같이 나온다.
+    // "전체 로그 형식을 다 통일해줘" 는 '전체' 와 '통일' 이 겹쳐야 총괄이 된다.
+    [/전부|모두|싹\s*다|통째로/, 3],
+    [/전체/, 3],
+    [/하나씩/, 3],
+    [/끝까지/, 3], [/마무리까지/, 3],
+    [/여러\s*(개|군데|파일|단계|곳)/, 3],
+    [/순서대로/, 3],
+    [/통일(해|시켜|좀)|일괄/, 2],
+    [/흩어진|여기저기/, 2],
+    [/\bend[- ]?to[- ]?end\b/i, 3],
+  ],
+
+  code: [
+    [/고쳐|고쳐줘|수정(해|좀)/, 4],
+    [/만들어|추가(해|좀)|넣어(줘|주세요)/, 4],
+    [/구현(해|좀)/, 5],
+    [/바꿔(줘|주세요)?|변경(해|좀)/, 3],
+    [/지워(줘)?|삭제(해|좀)/, 3],
+    [/이름\s*바꿔|리네임|rename/i, 3],
+    [/옮겨(줘)?/, 2],
+    [/리팩터(링)?(해|좀)/, 3],
+    [/\bimplement\b|\badd\b|\bfix\b|\bwrite\b/i, 2],
+    [/써(줘|주세요)/, 3],
+  ],
+};
+
+// 이만큼은 되어야 바꾼다. 못 미치면 종합 모드 그대로 둔다.
+//
+// 읽기 전용 모드는 문턱을 높인다. 잘못 보내면 파일을 못 고쳐서 사용자가 막힌다.
+// 파일을 고칠 수 있는 모드는 잘못 골라도 일이 막히지는 않으므로 낮게 둔다.
+const 문턱 = {
+  debug: 3,
+  code: 3,
+  orchestrator: 4,
+  plan: 5,
+  architect: 5,
+  ask: 5,
+};
+
+/**
+ * 이 한마디가 무슨 일인지 고른다.
+ *
+ * @param {string} text 사용자가 친 말
+ * @returns {{ mode: string|null, score: number, why: string, 점수들: object }}
+ *          mode 가 null 이면 '모르겠다' 는 뜻이다 — 종합 모드에 그대로 둔다.
+ */
+export function route(text) {
+  const s = String(text ?? '');
+  const 점수들 = {};
+  const 근거 = {};
+
+  for (const [mode, 규칙들] of Object.entries(표)) {
+    let 합 = 0;
+    const 걸린것 = [];
+    for (const [re, 점] of 규칙들) {
+      const m = s.match(re);
+      if (!m) continue;
+      합 += 점;
+      걸린것.push(m[0].trim());
+    }
+    점수들[mode] = 합;
+    근거[mode] = 걸린것;
+  }
+
+  const 순위 = Object.entries(점수들).sort((a, b) => b[1] - a[1]);
+  const [으뜸, 점수] = 순위[0] ?? [null, 0];
+  if (!으뜸 || 점수 < (문턱[으뜸] ?? 4)) {
+    return { mode: null, score: 점수, why: '무슨 일인지 뚜렷하지 않음', 점수들 };
+  }
+
+  // 1·2등이 붙으면 고르지 않는다. 반반인 것을 억지로 정하면 절반은 틀린다.
+  const 둘째 = 순위[1]?.[1] ?? 0;
+  if (점수 - 둘째 < 2 && 둘째 >= (문턱[순위[1][0]] ?? 4)) {
+    return { mode: null, score: 점수, why: `${으뜸} 과 ${순위[1][0]} 가 비슷함`, 점수들 };
+  }
+
+  return {
+    mode: 으뜸,
+    score: 점수,
+    why: 근거[으뜸].slice(0, 2).map((x) => `'${x}'`).join(', '),
+    점수들,
+  };
+}

package/src/agent/salvage.js

@@ -0,0 +1,182 @@
+// 잘려 온 도구 호출에서 **건질 수 있는 만큼 건진다.**
+//
+// 무슨 일이 있었나:
+//   대시보드 HTML 한 장을 만들라고 시켰다. 모델이 Write 를 부르는데 인자 JSON 이
+//   출력 상한에서 잘렸다. 잘린 JSON 은 읽을 수 없으니 통째로 버렸다. 모델은
+//   똑같이 다시 시도했고, 또 같은 자리에서 잘렸다. 13번 만에 컨텍스트가 다 찼다.
+//   71초를 쓰고 **파일은 한 글자도 안 생겼다.**
+//
+//   그런데 잘린 그 JSON 안에는 이미 받아 놓은 250줄이 들어 있었다. 경로도 온전했다.
+//   버릴 이유가 없다. 250줄을 쓰고 "여기까지 썼으니 이어 붙여라" 라고 하면
+//   그 다음 호출은 나머지만 보내면 된다 — 잘릴 일이 없다.
+//
+// 왜 JSON.parse 로는 안 되나:
+//   JSON.parse 는 전부 맞거나 전부 틀리거나 둘 중 하나다. 마지막 따옴표가 없다는
+//   이유로 앞의 250줄까지 같이 버린다. 그래서 앞에서부터 읽어 나가다가 더 못
+//   읽는 자리에서 멈추는 방식으로 따로 만든다.
+//
+// 조심할 것:
+//   여기서 건진 값은 **완전하지 않다.** 마지막 값은 잘려 있다. 그래서 이 결과를
+//   쓰는 쪽은 어느 값이 잘렸는지(truncatedKey) 반드시 보고 판단해야 한다.
+//   Edit 의 old_string 을 반쪽만 건져 쓰면 엉뚱한 자리를 고친다. loop.js 가
+//   Write·Append 만 살리는 이유다.
+
+/**
+ * 잘린 JSON 에서 읽히는 데까지 읽는다.
+ *
+ * @returns {{args: object, keys: string[], truncatedKey: string|null, complete: boolean}}
+ *   args         온전히 읽은 값들 (+ 잘린 값 하나는 받은 데까지)
+ *   truncatedKey 잘린 값의 이름. null 이면 잘린 값 없이 그냥 끝난 것
+ *   complete     닫는 괄호까지 제대로 나왔나
+ */
+export function partialParse(raw) {
+  const s = String(raw ?? '');
+  const 빈것 = { args: {}, keys: [], truncatedKey: null, complete: false };
+  let i = 0;
+
+  const 공백건너뛰기 = () => { while (i < s.length && /\s/.test(s[i])) i++; };
+
+  공백건너뛰기();
+  if (s[i] !== '{') return 빈것;
+  i++;
+
+  const args = {};
+  const keys = [];
+
+  for (;;) {
+    공백건너뛰기();
+    if (i >= s.length) return { args, keys, truncatedKey: null, complete: false };
+    if (s[i] === '}') return { args, keys, truncatedKey: null, complete: true };
+    if (s[i] === ',') { i++; continue; }
+    if (s[i] !== '"') return { args, keys, truncatedKey: null, complete: false };
+
+    const k = 글읽기(s, i);
+    if (!k.complete) return { args, keys, truncatedKey: null, complete: false };  // 이름이 잘렸으면 값도 없다
+    i = k.end;
+    공백건너뛰기();
+    if (s[i] !== ':') return { args, keys, truncatedKey: null, complete: false };
+    i++;
+    공백건너뛰기();
+    if (i >= s.length) return { args, keys, truncatedKey: null, complete: false };
+
+    if (s[i] === '"') {
+      const v = 글읽기(s, i);
+      args[k.text] = v.text;
+      keys.push(k.text);
+      if (!v.complete) return { args, keys, truncatedKey: k.text, complete: false };
+      i = v.end;
+    } else if (s[i] === '{' || s[i] === '[') {
+      const end = 짝찾기(s, i);
+      // 안 닫힌 덩어리는 통째로 버린다. 반쪽 객체는 건져도 쓸 데가 없고,
+      // 잘못 건지면 있지도 않은 값이 있는 것처럼 보인다.
+      if (end < 0) return { args, keys, truncatedKey: null, complete: false };
+      try { args[k.text] = JSON.parse(s.slice(i, end + 1)); keys.push(k.text); } catch { /* 못 읽으면 버린다 */ }
+      i = end + 1;
+    } else {
+      // 숫자·true·false·null
+      let j = i;
+      while (j < s.length && !',}'.includes(s[j])) j++;
+      const 조각 = s.slice(i, j).trim();
+      if (j >= s.length) return { args, keys, truncatedKey: null, complete: false };   // 값이 잘렸다
+      try { args[k.text] = JSON.parse(조각); keys.push(k.text); } catch { /* 버린다 */ }
+      i = j;
+    }
+  }
+}
+
+/**
+ * JSON 문자열 하나를 읽는다. 끝까지 못 읽어도 읽은 데까지 돌려준다.
+ *
+ * 이 함수가 이 파일의 핵심이다. \n · \" · \\ 는 물론 \uXXXX 도 풀어야 한다 —
+ * 한글이 그 모양으로 오는 게이트웨이가 있다. 실제로 사용자 게이트웨이가 그랬다.
+ * 마지막에 escape 가 반토막 나 있으면(\ 하나만, 또는 \u12) 그건 버린다.
+ */
+function 글읽기(s, start) {
+  let i = start + 1;      // 여는 따옴표 다음
+  let out = '';
+  while (i < s.length) {
+    const ch = s[i];
+    if (ch === '"') return { text: out, end: i + 1, complete: true };
+    if (ch !== '\\') { out += ch; i++; continue; }
+
+    const n = s[i + 1];
+    if (n === undefined) break;                    // \ 하나만 남고 끝났다 — 버린다
+    if (n === 'u') {
+      const hex = s.slice(i + 2, i + 6);
+      if (hex.length < 4 || !/^[0-9a-fA-F]{4}$/.test(hex)) break;   // \u12 에서 끊겼다
+      out += String.fromCharCode(parseInt(hex, 16));
+      i += 6;
+      continue;
+    }
+    const 표 = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', '"': '"', '\\': '\\', '/': '/' };
+    if (n in 표) { out += 표[n]; i += 2; continue; }
+    out += n; i += 2;                              // 모르는 escape 는 글자 그대로
+  }
+  return { text: out, end: s.length, complete: false };
+}
+
+/** 여는 괄호에 맞는 닫는 괄호 자리. 없으면 -1. 따옴표 안은 안 센다. */
+function 짝찾기(s, start) {
+  const 열림 = s[start];
+  const 닫힘 = 열림 === '{' ? '}' : ']';
+  let depth = 0;
+  let 글속 = false;
+  for (let i = start; i < s.length; i++) {
+    const ch = s[i];
+    if (글속) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === '"') 글속 = false;
+      continue;
+    }
+    if (ch === '"') { 글속 = true; continue; }
+    if (ch === 열림) depth++;
+    else if (ch === 닫힘) { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+/**
+ * 잘린 Write 호출을 '지금 바로 쓸 수 있는 것' 으로 바꾼다.
+ *
+ * 마지막 줄은 버린다. 반쪽 줄(`<div class="ca`)로 끝나 있으면 이어 붙이는 쪽이
+ * 그 반쪽에 정확히 맞춰 이어야 하는데, 약한 모델은 그걸 못 한다. 온전한 줄까지만
+ * 남기고 "그 다음 줄부터 쓰라" 고 하면 훨씬 쉬운 문제가 된다.
+ *
+ * @returns {{path: string, content: string, lines: number, lastLine: string}|null}
+ */
+export function 살린쓰기(raw) {
+  const r = partialParse(raw);
+  const path = r.args.file_path ?? r.args.path ?? r.args.filePath;
+  const body = r.args.content;
+  if (typeof path !== 'string' || !path.trim()) return null;
+  if (typeof body !== 'string' || !body) return null;
+  // 경로 자체가 잘렸으면 엉뚱한 자리에 쓴다. 그건 안 건진다.
+  if (r.truncatedKey === 'file_path' || r.truncatedKey === 'path') return null;
+
+  // 내용이 온전히 다 왔는데도 JSON 이 깨진 것이라면(뒤쪽 다른 인자에서 잘림)
+  // 마지막 줄을 버릴 이유가 없다.
+  const 내용잘림 = r.truncatedKey === 'content';
+  let content = body;
+  if (내용잘림) {
+    const 끝 = body.lastIndexOf('\n');
+    // 줄바꿈이 한 번도 없으면 **아무것도 안 건진다.**
+    //
+    // 이어 붙이라고 하려면 '어디까지 썼는지' 를 줄 단위로 말해 줄 수 있어야 한다.
+    // 온전한 줄이 하나도 없으면 반쪽 줄에 정확히 이어 붙이라고 부탁하는 셈인데,
+    // 약한 모델은 그걸 못 한다 — 앞을 다시 쓰거나 이음매가 어긋난다.
+    // 그럴 바에는 안 쓰고 '나눠 보내라' 고 하는 편이 낫다.
+    if (끝 < 0) return null;
+    content = body.slice(0, 끝 + 1);
+  }
+  if (!content) return null;
+
+  const lines = content.split('\n');
+  const 마지막 = [...lines].reverse().find((l) => l.trim()) ?? '';
+  return {
+    path: path.trim(),
+    content,
+    lines: content.endsWith('\n') ? lines.length - 1 : lines.length,
+    lastLine: 마지막.trim().slice(0, 60),
+    cut: 내용잘림,
+  };
+}