deel-local-cli 1.20.12 → 2.0.0

package/src/tools/webfetch.js

@@ -11,7 +11,9 @@
 //   · 사설·로컬 주소는 거절. 사내 서버를 모델이 긁어 오게 두지 않는다.
 //   · 오프라인이면 아예 거절.
 //   · 받은 것은 글자만 뽑고 길이를 자른다.
-import { allowTemporarily, isOffline, isLocalHost, 사설로풀리나 } from '../safety/network.js';
+// isLocalHost 가 아니라 안쪽주소인가 로 막는다 — 봉인이 열어 주는 「이 안」 보다 막을 곳이 넓다
+// (100.64/10 의 클라우드 메타데이터 · fec0::/10 · IPv4 를 싼 IPv6). network.js 머리말 참고.
+import { allowTemporarily, isOffline, 안쪽주소인가, 사설로풀리나 } from '../safety/network.js';
 import { 원시요청, 몸읽기 } from '../backend/http.js';
 import { decode as decodeBytes } from './encoding.js';
 import { 웹글자수 } from '../agent/budget.js';
@@ -28,6 +30,33 @@ function 웹글읽기(buf, 머리글) {
     try { return new TextDecoder(머리글, { fatal: false }).decode(buf); }
     catch { /* 이 Node 가 모르는 이름이면 아래에서 알아서 본다 */ }
   }
+  /*
+   * ── utf-8 이라고 **적어 둔** 페이지 (사냥4 W4) ──────────────────────────
+   *
+   * 여기는 머리글이 utf-8 이면 곧장 내용 짐작(encoding.js)으로 넘겼다. 그런데 짐작은
+   * 엄격하다 — UTF-8 로 **한 바이트라도** 어긋나면 UTF-8 이 아니라고 보고 다른
+   * 인코딩을 고른다. 멀쩡한 한글 UTF-8 페이지에 깨진 바이트 하나(잘린 광고 조각,
+   * 옛 글 붙여넣기)가 섞이면 페이지 **전체가** windows-1252 로 읽혀 `안녕` 이 됐다.
+   * 아래 webFetch 의 되읽기(깨진 글자 세기)도 못 잡는다 — 1252 는 � 를 안 내놓는다.
+   *
+   * 그래서 적힌 utf-8 을 먼저 믿어 본다. 어긋난 바이트는 � 로 바꾸고, 그 수가 제대로
+   * 읽힌 UTF-8 글자에 비해 **드물면**(스무 자에 하나 이하) 그대로 쓴다.
+   *
+   * 「적힌 대로」 만 믿지 않는 까닭 — 머리글만 utf-8 이고 알맹이는 EUC-KR 인 옛 사내
+   * 위키가 흔하다(서버 기본값이 붙는다). 거기서는 거의 모든 바이트가 어긋나서 비율로
+   * 갈린다. 그때만 여태처럼 내용 짐작으로 넘어간다.
+   */
+  if (머리글) {
+    const 읽은것 = new TextDecoder('utf-8', { fatal: false }).decode(buf);
+    let 깨진 = 0;
+    let 멀쩡한 = 0;
+    for (const 글자 of 읽은것) {
+      const n = 글자.codePointAt(0);
+      if (n === 0xfffd) 깨진 += 1;
+      else if (n >= 0x80) 멀쩡한 += 1;
+    }
+    if (깨진 === 0 || 깨진 * 20 <= 멀쩡한) return 읽은것;
+  }
   // euc-kr 인 페이지를 위해 힌트를 준다. 내용이 분명하면 내용이 이긴다.
   return decodeBytes(buf, { fallback: 'euc-kr' }).text;
 }
@@ -130,6 +159,45 @@ function 얼마나쉬라나(머리, 회차) {
   return Math.min(초, 10);
 }
 
+/*
+ * 이름으로 적힌 글자(&middot; 같은 것). 번호로 둔다 — 글자를 소스에 박으면 보이지 않는
+ * 글자(nbsp)가 섞여도 눈으로 못 가린다.
+ *
+ * 여태는 nbsp·amp·lt·gt·quot·apos 여섯만 풀었다(사냥4 W16). 그래서 흔한 `&middot;`
+ * `&hellip;` `&copy;` 가 원문 그대로 모델에게 가서, 목록의 가운뎃점·말줄임표 자리가 전부
+ * `&middot;` 로 찍혔다. 모르는 이름은 여전히 **손대지 않는다.**
+ *
+ * 뿌리 없는 객체다(8회차 · 바깥). 보통 객체면 `&toString;` `&constructor;` `&valueOf;`
+ * 같은 이름이 **Object.prototype 의 함수**를 집는다. 그것을 글자 번호로 쓰려다
+ * `RangeError: Invalid code point NaN` 이 나고, 그 예외는 태그벗기기 밖으로 새서
+ * **페이지 전체가 오류 한 줄**이 됐다 — 남의 페이지에 한 낱말 적혀 있으면 되는 일이다.
+ * 뿌리가 없으면 그런 이름도 그냥 없는 이름이라, 위 규칙(손대지 않는다)이 그대로 산다.
+ */
+const 이름글자 = Object.assign(Object.create(null), {
+  nbsp: 0x20, amp: 0x26, lt: 0x3c, gt: 0x3e, quot: 0x22, apos: 0x27,
+  middot: 0xb7, hellip: 0x2026, copy: 0xa9, reg: 0xae, trade: 0x2122,
+  mdash: 0x2014, ndash: 0x2013, lsquo: 0x2018, rsquo: 0x2019, ldquo: 0x201c, rdquo: 0x201d,
+  laquo: 0xab, raquo: 0xbb, bull: 0x2022, euro: 0x20ac, times: 0xd7, divide: 0xf7, deg: 0xb0,
+  plusmn: 0xb1, sect: 0xa7, para: 0xb6, cent: 0xa2, pound: 0xa3, yen: 0xa5,
+  larr: 0x2190, rarr: 0x2192, uarr: 0x2191, darr: 0x2193,
+});
+
+/*
+ * 번호로 적혀 와도 **모델에게 넘기지 않을** 글자 (사냥4 W16).
+ *
+ * 여기는 32 밑만 막았다. 그래서 이런 것이 번호 한 줄로 그대로 풀려 들어갔다:
+ *   · C1 제어(0x80–0x9F) · DEL — `&#x9b;31m` 은 터미널에서 CSI 다. 대화 기록을 cat 하면 색이 바뀐다
+ *   · 방향 뒤집기(U+202A–202E · U+2066–2069) — 글이 보이는 순서와 읽히는 순서를 갈라놓는다.
+ *     「파일을 지우지 마세요」 가 사람 눈에는 반대로 보이게 만드는 데 쓰는 글자다
+ *   · 외톨이 대리쌍(D800–DFFF) — 글자가 아니다. JSON 으로 게이트웨이에 실으면 넘어지는 곳이 있다
+ * 못 넣을 번호는 여태처럼 원문(`&#x202e;`)을 그대로 둔다 — 보이는 글자로 남으니 안전하다.
+ */
+const 못넣을번호 = (n) => n < 32 || n > 0x10ffff
+  || (n >= 0x7f && n <= 0x9f)
+  || (n >= 0xd800 && n <= 0xdfff)
+  || (n >= 0x202a && n <= 0x202e)
+  || (n >= 0x2066 && n <= 0x2069);
+
 function 태그벗기기(html) {
   let 글 = String(html);
   // script·style·주석을 겹쳐 쓰거나 안 닫은 모양으로 흘려 보내는 페이지가
@@ -138,31 +206,44 @@ function 태그벗기기(html) {
   // 화면에 그리지 않으니, 여기서 다 못 걸러도 실행되는 것은 아니다.
   for (let i = 0; i < 5; i += 1) {
     const 전 = 글;
-    글 = 글
-      .replace(/<script[\s\S]*?<\/script\s*>/gi, ' ')
-      .replace(/<style[\s\S]*?<\/style\s*>/gi, ' ')
-      .replace(/<!--[\s\S]*?-->/g, ' ');
+    /*
+     * 셋을 **한 무늬로, 왼쪽부터** 지운다 (6회차 Gemini 웹받기 W4).
+     *
+     * script → style → 주석 차례로 따로 지웠더니, 주석 안에 적힌 `<script>` 가 뒤에 오는
+     * 진짜 `</script>` 까지 본문을 통째로 먹고 `<!--` 만 남겼다. 브라우저는 **먼저 열린 쪽**을
+     * 따른다 — 한 무늬의 갈래로 두면 정규식도 왼쪽에서 먼저 걸리는 쪽을 따른다.
+     */
+    글 = 글.replace(/<!--[\s\S]*?-->|<script\b[\s\S]*?<\/script\s*>|<style\b[\s\S]*?<\/style\s*>/gi, ' ');
     if (글 === 전) break;
   }
+  /*
+   * 안 닫힌 script·style·주석은 **끝까지**다 (W3). 브라우저도 닫는 태그가 안 오면 나머지를 전부
+   * 그 안으로 읽는다. 상한에서 잘린 페이지가 흔히 이 꼴이라, 안 지우면 스크립트 본문이 글로 간다.
+   */
+  글 = 글.replace(/<!--[\s\S]*$|<(?:script|style)\b[\s\S]*$/i, ' ');
   return 글
     // 닫는 태그만 줄로 바꾸면, 닫는 태그를 안 적은 페이지가 통째로 한 줄이
     // 된다 — `<p>첫째<p>둘째` 나 `<ul><li>하나<li>둘</ul>` 이 흔하다.
     // HTML 이 그것을 허락하므로 옛 사내 페이지에는 정말로 그렇게 적혀 있다.
     // 여는 태그도 같이 줄로 바꾼다.
     .replace(/<\/?(p|div|section|article|li|tr|h[1-6]|br)\b[^>]*>/gi, '\n')
-    .replace(/<[^>]+>/g, ' ')
+    // 태그는 `<` 바로 뒤가 글자(·`/`·`!`·`?`)일 때만이다 (W5). `1 < 5 && 10 > 2` 의 `< 5 … >` 는
+    // HTML 에서도 글이다 — 태그로 보고 지우면 식이 `1 2` 가 된다.
+    .replace(/<\/?[a-z!?][^>]*>/gi, ' ')
     // 한 번에 찾아서 한 번에 바꾼다 — 차례로 바꾸면(`&amp;` 를 먼저 `&` 로
     // 풀고 나서 `&lt;` 를 다시 찾는 식) `&amp;lt;` 처럼 두 겹 씌운 것이
     // 두 번 풀려서 `<` 로 튀어나온다(글자로 남아야 하는데 태그처럼 보이게 됨).
     // 숫자 꼴(`&#48712;` · `&#x27;`)과 `&apos;` 도 같은 한 판에서 푼다.
     // 안 풀면 한글 페이지 하나가 통째로 숫자 나열로 모델에게 간다.
-    .replace(/&(nbsp|amp|lt|gt|quot|apos|#\d{1,7}|#x[0-9a-f]{1,6});/gi, (온것, 이름) => {
-      const 표 = { nbsp: ' ', amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+    .replace(/&(#\d{1,7}|#x[0-9a-f]{1,6}|[a-z][a-z0-9]{1,7});/gi, (온것, 이름) => {
       const 키 = 이름.toLowerCase();
-      if (표[키] !== undefined) return 표[키];
+      if (!키.startsWith('#')) {
+        const 번 = 이름글자[이름] ?? 이름글자[키];
+        return 번 === undefined ? 온것 : String.fromCodePoint(번);
+      }
       const 번호 = 키.startsWith('#x') ? parseInt(키.slice(2), 16) : parseInt(키.slice(1), 10);
-      // 못 읽을 번호면 **손대지 않는다.** 지어낸 글자를 넣느니 원문이 낫다.
-      if (!Number.isFinite(번호) || 번호 < 32 || 번호 > 0x10ffff) return 온것;
+      // 못 읽을 번호·못 넣을 번호면 **손대지 않는다.** 지어낸 글자를 넣느니 원문이 낫다.
+      if (!Number.isFinite(번호) || 못넣을번호(번호)) return 온것;
       try { return String.fromCodePoint(번호); } catch { return 온것; }
     })
     .replace(/[ \t]+/g, ' ')
@@ -200,7 +281,8 @@ export function 웹되돌림(다음, { allowPrivate = false } = {}) {
   if (다음.protocol !== 'http:' && 다음.protocol !== 'https:') {
     throw new Error(`${다음.protocol} 로 되돌립니다 — 따라가지 않습니다`);
   }
-  if (isLocalHost(다음.hostname) && !allowPrivate) {
+  // 안쪽주소인가 — 100.100.100.200(알리바바 메타데이터)·fec0::/10 까지 본다 (사냥4 W9).
+  if (안쪽주소인가(다음.hostname) && !allowPrivate) {
     throw new Error(`이 컴퓨터·사내망 주소(${다음.hostname})로 되돌립니다 — 따라가지 않습니다`);
   }
 }
@@ -248,7 +330,7 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
     return { error: `${u.protocol} 는 읽지 않습니다. http/https 만 됩니다.` };
   }
   // 사내망·로컬을 모델이 훑게 두지 않는다. 웹을 읽는 도구지 내부 정찰 도구가 아니다.
-  if (isLocalHost(u.hostname) && !allowPrivate) {
+  if (안쪽주소인가(u.hostname) && !allowPrivate) {
     return { error: `이 컴퓨터·사내망 주소는 이 도구로 읽지 않습니다: ${u.hostname}\n  파일은 Read, 사내 서버는 사람이 직접 확인하세요.` };
   }
   /*
@@ -280,6 +362,10 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
     let res = null;
     let 쉰시간 = 0;
     for (let 회차 = 0; ; 회차++) {
+      // 회차마다 처음 주소부터 다시 간다. 여기서 안 되돌리면, 앞 회차에만 되돌림이
+      // 있었을 때 되돌림이 **없던** 회차까지 앞 회차의 주소로 기록·보고된다 —
+      // 심사서의 「어디로 나갔나」 와 오류 문구가 가 본 적 없는 집을 가리킨다.
+      닿은곳 = u;
       res = await 한집씩(u.origin, () => 원시요청(u.href, {
         method: 'GET',                            // 보내는 건 없다
         headers: { 'User-Agent': 'deel/cli', Accept: 'text/html,text/plain,application/json;q=0.9,*/*;q=0.5' },
@@ -338,7 +424,12 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
         return { error: `HTTP ${res.status} — ${집} 가 지금 힘들어합니다.`
           + `\n  ${다시횟수}번 다시 불러 봤습니다(${쉰시간}초). 잠시 뒤에 다시 해 보세요.` };
       }
-      return { error: `HTTP ${res.status} — ${닿은곳.href}` };
+      /*
+       * 되돌림을 못 따라간 까닭이 있으면 같이 말한다 (사냥4 W19 · http.js 의 되돌림탈).
+       * 「HTTP 302 — 주소」 한 줄로는 제자리를 도는 서버인지, Location 이 깨졌는지 모른다 —
+       * 모델은 같은 주소를 또 부른다.
+       */
+      return { error: `HTTP ${res.status} — ${닿은곳.href}${res.되돌림탈 ? `\n  ${res.되돌림탈}` : ''}` };
     }
 
     const type = (res.headers.get('content-type') ?? '').toLowerCase();
@@ -354,14 +445,46 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
     const 뒷말 = 갈래.split('/')[1] ?? '';
     const 글인가 = /^text\//.test(갈래)
       || /(^|[-+.])(json|xml|javascript|ecmascript|yaml|toml|csv|ndjson|graphql)$/.test(뒷말);
-    if (!글인가) {
+    // 갈래가 **아예 없는** 답은 여기서 거절하지 않는다 — 아래에서 알맹이를 보고 가른다.
+    if (!글인가 && 갈래) {
       await res.버리기?.();
-      return { error: `글이 아닌 내용입니다 (${type || '알 수 없음'}). 이 도구는 글만 읽습니다.` };
+      return { error: `글이 아닌 내용입니다 (${type}). 이 도구는 글만 읽습니다.` };
     }
 
     const buf = await 몸읽기(res.res.body, MAX_BYTES);
     if (!buf) return { error: `너무 큽니다 (${MAX_BYTES / 1024 / 1024}MB 넘음) — 받다 말았습니다. 범위를 좁힌 주소를 쓰세요.` };
 
+    /*
+     * ── Content-Type 이 없는 200 (사냥4 W18) ──────────────────────────────
+     *
+     * 여태는 「글이 아닌 내용입니다 (알 수 없음)」 으로 거절했다. 옛 사내 서버·정적 파일
+     * 서버·짧은 CGI 가 머리글을 안 붙이는 일이 흔해서, 멀쩡한 글 페이지가 통째로 막혔다.
+     * 브라우저도 이때는 알맹이를 보고 가른다(MIME sniffing). 앞 8KB 에 NUL 이 있거나
+     * PDF 머리면 바이너리로 보고 거절하고, 아니면 글로 읽는다. `<html` 로 시작하면
+     * 태그를 벗긴다. 상한(MAX_BYTES)은 위에서 이미 걸렸다 — 보고 나서 버려도 크게 안 받는다.
+     */
+    /*
+     * 볼갈래도 **낱말**이다 (8회차 · 바깥). 여기에 머리글 원문을 담았더니
+     * `application/json; name="index.html"` 이 아래 `/html/` 에 걸려서 **JSON
+     * 본문의 태그를 벗겼다** — `{"a":"<b>굵게</b>"}` 가 `{"a":" 굵게 "}` 가 되고,
+     * 값이 깎였다는 말은 어디에도 안 나온다. 위에서 이미 갈래를 낱말로 갈라 뒀다.
+     */
+    let 볼갈래 = 갈래;
+    if (!갈래) {
+      const 앞 = buf.subarray(0, 8192);
+      if (앞.includes(0) || 앞.subarray(0, 5).toString('latin1') === '%PDF-') {
+        return { error: '글이 아닌 내용입니다 (Content-Type 이 없고 알맹이가 바이너리입니다). 이 도구는 글만 읽습니다.' };
+      }
+      const 머리떼고 = 앞.subarray(앞[0] === 0xef && 앞[1] === 0xbb && 앞[2] === 0xbf ? 3 : 0).toString('latin1');
+      /*
+       * 엿보는 목록은 WHATWG MIME Sniffing 표준의 「HTML 서명」 그대로다 (6회차 Gemini 웹받기 W9).
+       * doctype·html·head·body 넷만 봐서, 주석이나 `<div>` 로 시작하는 옛 페이지는 태그·스크립트째
+       * 글로 넘어갔다. 표준처럼 이름 뒤에 빈칸이나 `>` 가 와야 한다 — `<a` 가 `<abc` 에 걸리지 않게.
+       */
+      볼갈래 = /^\s*(?:<!--|<(?:!doctype\s+html|html|head|script|iframe|h1|div|font|table|a|style|title|b|body|br|p)[\s>])/i.test(머리떼고)
+        ? 'text/html' : 'text/plain';
+    }
+
     /*
      * 무엇으로 쓰여 있는지 알아보고 읽는다.
      *
@@ -375,7 +498,7 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
      */
     const 머리글 = /charset=["']?([\w-]+)/i.exec(type)?.[1]?.toLowerCase() ?? null;
     let text = 웹글읽기(buf, 머리글);
-    if (/html/.test(type)) text = 태그벗기기(text);
+    if (/html/.test(볼갈래)) text = 태그벗기기(text);
     /*
      * `<meta charset>` 이 머리글과 **다르게** 적혀 있는 페이지가 있다.
      *
@@ -386,13 +509,25 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
      *
      * 다시 읽어서 **덜 깨진 쪽**을 쓴다. 세어 보고 고르니 더 나빠질 일이 없다.
      */
+    /*
+     * 그런데 문을 여는 조건이 `깨진수(text)` 하나라, **정작 그 판에서 한 번도 안 돌았다**
+     * (막판 훑기). 한 바이트짜리 인코딩(`iso-8859-1` · `windows-1252` · `us-ascii`)은
+     * 모든 바이트에 글자가 있어서, 아무리 엉뚱하게 읽어도 � 가 0 이다 — 이 파일이 위
+     * 웹글읽기 머리말에서 스스로 「1252 는 � 를 안 내놓는다」 고 적어 둔 그것이다.
+     * 그리고 서버 기본값으로 제일 흔히 붙는 것이 바로 그 이름들이다.
+     *
+     * 그러니 머리글이 그 부류면 � 수는 아무것도 안 말해 준다. 그때는 문을 열고,
+     * 같은 수로 나와도 **문서가 제 입으로 적어 둔 쪽**을 쓴다. 더 깨지면 안 쓴다 —
+     * 세어 보고 고르는 것은 그대로다.
+     */
     const 깨진수 = (그것) => (그것.match(/�/g) ?? []).length;
-    if (깨진수(text)) {
+    const 셀수없나 = !!머리글 && /^(iso-?8859-\d+|windows-125\d|cp125\d|us-ascii|ascii|latin1)$/i.test(머리글);
+    if (깨진수(text) || 셀수없나) {
       const meta = /<meta[^>]+charset=["']?([\w-]+)/i.exec(buf.toString('latin1').slice(0, 2000))?.[1]?.toLowerCase();
       if (meta && meta !== 머리글) {
         let 다시 = 웹글읽기(buf, meta);
-        if (/html/.test(type)) 다시 = 태그벗기기(다시);
-        if (깨진수(다시) < 깨진수(text)) text = 다시;
+        if (/html/.test(볼갈래)) 다시 = 태그벗기기(다시);
+        if (깨진수(다시) < 깨진수(text) || (셀수없나 && 깨진수(다시) === 깨진수(text))) text = 다시;
       }
     }
     /*
@@ -409,7 +544,7 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
      *   2) 그래도 넘치면 **깨진 JSON 이라고 분명히 말한다.** 그리고 무엇을
      *      하면 되는지 — 범위를 좁히거나 max_chars 를 올리거나 — 같이 준다.
      */
-    const json쪽 = /json/.test(type);
+    const json쪽 = /json/.test(볼갈래);
     let 눌렀나 = false;
     if (json쪽 && text.length > max) {
       try {
@@ -420,11 +555,20 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
 
     const 원래길이 = text.length;
     const cut = 원래길이 > max;
-    if (cut) text = text.slice(0, max);
+    if (cut) {
+      /*
+       * 자르는 자리가 **대리쌍 한가운데**면 한 칸 앞에서 자른다 (사냥4 W17).
+       * `slice` 는 UTF-16 칸으로 자른다. 이모지·옛 한자처럼 두 칸짜리 글자가 경계에
+       * 걸리면 앞 반쪽(D800–DBFF)만 남는데, 그건 글자가 아니다 — JSON 으로 게이트웨이에
+       * 실으면 넘어지는 곳이 있고, 화면에는 � 로 찍힌다.
+       */
+      const 앞칸 = text.charCodeAt(max - 1);
+      text = text.slice(0, 앞칸 >= 0xd800 && 앞칸 <= 0xdbff ? max - 1 : max);
+    }
 
     let 꼬리 = '';
     if (cut) {
-      const 남은것 = (원래길이 - max).toLocaleString();
+      const 남은것 = (원래길이 - text.length).toLocaleString();
       꼬리 = json쪽
         ? `\n\n(여기서 잘렸습니다 — ${남은것}자가 더 있습니다.`
           + '\n 잘린 JSON 은 그대로 읽을 수 없습니다. 다음 중 하나를 하세요:'
@@ -442,7 +586,20 @@ export async function webFetch(args, { allowPrivate = false, 모델컨텍스트
         + (cut ? ` (잘림 — ${원래길이.toLocaleString()}자 중)` : ''),
     };
   } catch (err) {
-    const m = String(err?.message ?? err);
+    /*
+     * 넘어진 까닭은 **속에** 있다 (8회차 · 바깥).
+     *
+     * fetch 는 무엇이 잘못됐든 겉으로는 `TypeError: fetch failed` 한 줄이고, 진짜
+     * 까닭(getaddrinfo ENOTFOUND · connect ECONNREFUSED · 인증서)은 `err.cause` 에
+     * 들어 있다. 겉만 보던 때는 아래 DNS 갈래가 한 번도 안 걸렸고, 사람과 모델은
+     * 「fetch failed」 만 받아 주소가 틀렸는지 문이 닫혔는지 모른 채 같은 주소를 또 불렀다.
+     */
+    const 까닭들 = [];
+    for (let e = err; e && 까닭들.length < 4; e = e.cause) {
+      const 한줄 = String(e?.message ?? e);
+      if (한줄 && !까닭들.includes(한줄)) 까닭들.push(한줄);
+    }
+    const m = 까닭들.join(' — ') || String(err);
     /*
      * 멈춤이 먼저다.
      *
@@ -471,7 +628,9 @@ export const WEB_FETCH_TOOL = {
       type: 'object',
       properties: {
         url: { type: 'string', description: '읽을 주소 (http/https)' },
-        max_chars: { type: 'number', description: '가져올 최대 글자 수. 안 주면 모델 크기에 맞춰 정해진다. 자료가 잘리면 여기를 올린다 (최대 120000)' },
+        // 상한은 **첫 문장**에 둔다. 좁은 창에서는 설명을 문장 단위로 줄이는데(tools/index.js 의
+        // 설명줄이기) 끝에 붙여 두면 그 수가 먼저 잘려, 모델이 상한을 모른 채 max_chars 를 정했다.
+        max_chars: { type: 'number', description: '가져올 최대 글자 수 (최대 120000). 안 주면 모델 크기에 맞춰 정해진다. 자료가 잘리면 여기를 올린다' },
       },
       required: ['url'],
     },