deel-local-cli 1.16.0 → 1.17.2

package/src/agent/outschema.js

@@ -0,0 +1,351 @@
+// 답을 **정해진 모양**으로 받는다 — `deel run --output-schema`.
+//
+// ── 왜 필요한가 ────────────────────────────────────────────────────────
+//
+// `deel run` 은 글을 낸다. 사람이 읽으면 그만이지만, 스크립트에 물리면
+// 거기서부터 일이 시작된다.
+//
+//     deel run "이 계약서에서 계약 기간과 해지 조건을 뽑아 줘" spec.hwpx | ???
+//
+// 뒤에 무엇을 붙일 수 있나. 답이 매번 다른 모양으로 오므로 `grep` 이나
+// `sed` 로 뜯어야 하고, 그 뜯는 코드는 모델이 다음번에 문장을 조금 다르게
+// 쓰는 날 조용히 틀린다. **조용히** 가 핵심이다 — 빈 값을 받은 스크립트는
+// 오류를 안 내고 그냥 빈 값으로 다음 단계에 넘긴다.
+//
+// 모양을 미리 못 박으면 이 문제가 통째로 사라진다.
+//
+//     deel run --output-schema 계약.schema.json "..." | jq -r .해지조건
+//
+// 그러면 이 프로그램은 **셸 파이프라인에서 부를 수 있는 함수**가 된다.
+// doc2md 와 붙이면 「hwpx 계약서 → 구조화 JSON」 이 되는데, 그건 지금
+// 어느 경쟁 도구도 못 한다.
+//
+// ── 왜 우리가 직접 재나 ────────────────────────────────────────────────
+//
+// 「JSON 으로 답해 줘」 라고 부탁만 하고 안 재는 길도 있다. 그런데 그러면
+// 지키는 날과 안 지키는 날이 생기고, 안 지킨 날에 스크립트가 깨진다 —
+// 그것도 우리가 아니라 **뒤에 붙은 남의 코드**에서 깨진다. 부탁은 계약이
+// 아니다. 계약이라고 부르려면 재야 한다.
+//
+// 그래서 받아 놓고 여기서 맞춰 본다. 안 맞으면 무엇이 어떻게 안 맞는지를
+// 모델에게 그대로 돌려주고 한 번 더 시킨다. 그래도 안 맞으면 **0 이 아닌
+// 값으로 끝낸다.** 모양이 안 맞는 JSON 을 표준출력으로 흘려보내는 것이
+// 여기서 할 수 있는 제일 나쁜 일이다.
+//
+// ── 무엇을 안 하나 ─────────────────────────────────────────────────────
+//
+// **`$ref` 로 바깥을 안 본다.** JSON Schema 는 `$ref` 에 주소를 적을 수 있고,
+// 검사기 대부분이 그걸 받아 온다. 우리는 안 받아 온다 — 스키마 파일 하나가
+// 이 프로그램의 「나가는 주소는 사람이 정한 하나뿐」 을 깨뜨리는 길이 되면
+// 안 된다. 같은 파일 안(`#/$defs/...`)만 따라간다.
+//
+// 규격을 다 받지도 않는다. 아래 목록에 없는 열쇠는 **본 척하지 않고 그냥
+// 넘긴다.** 모르는 규칙을 아는 척 통과시키는 것이 모르는 채로 두는 것보다
+// 나쁘다 — 사람은 잰 줄 알고 지낸다. 그래서 `모르는열쇠()` 로 무엇을 안
+// 봤는지 셀 수 있게 해 두고, 화면이 그것을 말한다.
+import { readFileSync } from 'node:fs';
+
+/** 우리가 실제로 재는 열쇠들. 여기 없는 것은 안 재고, 안 쟀다고 말한다. */
+export const 아는열쇠 = Object.freeze([
+  'type', 'enum', 'const',
+  'properties', 'required', 'additionalProperties',
+  'items', 'minItems', 'maxItems',
+  'minLength', 'maxLength', 'pattern',
+  'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+  'anyOf', 'oneOf', 'allOf', 'not',
+  '$ref', '$defs', 'definitions',
+  // 재는 것이 아니라 적어 두는 것들. 모델에게 보여 줄 때 쓴다.
+  '$schema', '$id', 'title', 'description', 'default', 'examples',
+]);
+
+const 아는것 = new Set(아는열쇠);
+// 그 아래 열쇠가 규격 낱말이 아니라 '사람이 지은 칸 이름' 인 자리.
+const 이름칸 = new Set(['properties', '$defs', 'definitions']);
+
+/**
+ * 이 스키마에서 우리가 안 보는 열쇠들.
+ *
+ * 조용히 넘기면 사람은 잰 줄 알고 지낸다. 세어서 화면이 말하게 한다.
+ */
+export function 모르는열쇠(스키마, 본것 = new Set()) {
+  const out = new Set();
+  const 훑기 = (s) => {
+    if (!s || typeof s !== 'object' || 본것.has(s)) return;
+    본것.add(s);
+    if (Array.isArray(s)) { for (const x of s) 훑기(x); return; }
+    for (const [k, v] of Object.entries(s)) {
+      if (!아는것.has(k)) out.add(k);
+      if (!v || typeof v !== 'object') continue;
+      /*
+       * `properties`·`$defs` 아래 열쇠는 **사람이 지은 칸 이름**이지 규격
+       * 낱말이 아니다. 그걸 세면 칸을 하나 만들 때마다 「안 재는 열쇠」 가
+       * 하나씩 늘어난다 — 그러면 이 경고는 아무도 안 읽는 소음이 되고,
+       * 진짜로 안 재는 낱말(format 같은 것)이 그 속에 묻힌다.
+       */
+      if (이름칸.has(k)) { for (const x of Object.values(v)) 훑기(x); }
+      else 훑기(v);
+    }
+  };
+  훑기(스키마);
+  return [...out].sort();
+}
+
+/**
+ * 스키마 파일을 읽는다.
+ *
+ * 못 읽으면 **일을 시작하지 않는다.** 스키마가 없는데 그냥 도는 것은
+ * 「모양을 못 박아 달라」 는 부탁을 조용히 무시하는 것이고, 그 결과는 파이프
+ * 뒤에서 터진다.
+ *
+ * @returns {{ok: true, 스키마: object, 모른것: string[]} | {ok: false, 왜: string}}
+ */
+export function 스키마읽기(경로) {
+  let 글;
+  try { 글 = readFileSync(경로, 'utf8'); }
+  catch (err) { return { ok: false, 왜: `스키마 파일을 못 읽었습니다: ${경로}\n  ${err?.message ?? err}` }; }
+  let s;
+  try { s = JSON.parse(글); }
+  catch (err) { return { ok: false, 왜: `스키마가 JSON 이 아닙니다: ${경로}\n  ${err?.message ?? err}` }; }
+  if (!s || typeof s !== 'object' || Array.isArray(s)) {
+    return { ok: false, 왜: `스키마는 객체여야 합니다: ${경로}` };
+  }
+  // 바깥을 가리키는 $ref 는 여기서 막는다. 읽고 나서 막으면 이미 늦다.
+  const 바깥 = 바깥ref찾기(s);
+  if (바깥.length) {
+    return {
+      ok: false,
+      왜: `스키마가 바깥을 가리킵니다: ${바깥.slice(0, 3).join(' · ')}\n`
+        + '  이 프로그램은 스키마를 받아 오지 않습니다 — 나가는 주소는 사람이 정한 하나뿐이어야 합니다.\n'
+        + '  같은 파일 안(#/$defs/...)으로 바꿔 주세요.',
+    };
+  }
+  return { ok: true, 스키마: s, 모른것: 모르는열쇠(s) };
+}
+
+/** 같은 파일 안(`#`으로 시작)이 아닌 `$ref` 를 다 찾는다. */
+export function 바깥ref찾기(스키마, 본것 = new Set()) {
+  const out = [];
+  const 훑기 = (s) => {
+    if (!s || typeof s !== 'object' || 본것.has(s)) return;
+    본것.add(s);
+    if (Array.isArray(s)) { for (const x of s) 훑기(x); return; }
+    if (typeof s.$ref === 'string' && !s.$ref.startsWith('#')) out.push(s.$ref);
+    for (const v of Object.values(s)) if (v && typeof v === 'object') 훑기(v);
+  };
+  훑기(스키마);
+  return [...new Set(out)];
+}
+
+/** `#/$defs/이름` 같은 자리를 뿌리에서 따라간다. 못 찾으면 null. */
+function ref따라가기(뿌리, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#')) return null;
+  const 길 = ref.slice(1).split('/').filter(Boolean)
+    .map((x) => decodeURIComponent(x.replace(/~1/g, '/').replace(/~0/g, '~')));
+  let 여기 = 뿌리;
+  for (const 조각 of 길) {
+    if (!여기 || typeof 여기 !== 'object') return null;
+    여기 = 여기[조각];
+  }
+  return 여기 && typeof 여기 === 'object' ? 여기 : null;
+}
+
+const 갈래 = (v) => {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (Number.isInteger(v)) return 'integer';
+  return typeof v === 'number' ? 'number' : typeof v;
+};
+
+const 갈래맞나 = (v, t) => {
+  if (t === 'integer') return Number.isInteger(v);
+  if (t === 'number') return typeof v === 'number' && Number.isFinite(v);
+  if (t === 'array') return Array.isArray(v);
+  if (t === 'null') return v === null;
+  if (t === 'object') return v !== null && typeof v === 'object' && !Array.isArray(v);
+  return typeof v === t;
+};
+
+/**
+ * 값이 스키마에 맞나.
+ *
+ * 탈은 **다 모아서** 준다. 하나만 주면 고치고 다시 돌리고를 반복하게 되는데,
+ * 그 한 바퀴가 모델 호출 한 번이라 값이 비싸다. 그리고 사람이 스키마를
+ * 잘못 적은 경우에도 한 번에 다 보이는 편이 낫다.
+ *
+ * @returns {{ok: boolean, 탈: string[]}}
+ */
+export function 맞나(값, 스키마, { 뿌리 = 스키마, 자리 = '' } = {}) {
+  const 탈 = [];
+  const 여기 = 자리 || '(뿌리)';
+  const s = 스키마;
+  if (!s || typeof s !== 'object') return { ok: true, 탈 };
+
+  // true/false 스키마와 $ref 를 먼저 푼다.
+  if (typeof s.$ref === 'string') {
+    const 간것 = ref따라가기(뿌리, s.$ref);
+    if (!간것) return { ok: false, 탈: [`${여기}: 스키마 안에 ${s.$ref} 가 없습니다`] };
+    return 맞나(값, 간것, { 뿌리, 자리 });
+  }
+
+  if (Array.isArray(s.type) ? !s.type.some((t) => 갈래맞나(값, t)) : (s.type && !갈래맞나(값, s.type))) {
+    탈.push(`${여기}: ${Array.isArray(s.type) ? s.type.join('|') : s.type} 이어야 하는데 ${갈래(값)} 입니다`);
+    // 갈래부터 틀리면 그 아래는 재 봐야 헛말만 늘어난다.
+    return { ok: false, 탈 };
+  }
+
+  if (Array.isArray(s.enum) && !s.enum.some((x) => JSON.stringify(x) === JSON.stringify(값))) {
+    탈.push(`${여기}: ${s.enum.map((x) => JSON.stringify(x)).join(' · ')} 중 하나여야 합니다`);
+  }
+  if ('const' in s && JSON.stringify(s.const) !== JSON.stringify(값)) {
+    탈.push(`${여기}: ${JSON.stringify(s.const)} 여야 합니다`);
+  }
+
+  if (typeof 값 === 'string') {
+    if (Number.isFinite(s.minLength) && [...값].length < s.minLength) 탈.push(`${여기}: ${s.minLength}자 이상이어야 합니다`);
+    if (Number.isFinite(s.maxLength) && [...값].length > s.maxLength) 탈.push(`${여기}: ${s.maxLength}자 이하여야 합니다`);
+    if (typeof s.pattern === 'string') {
+      // 스키마를 적은 사람의 정규식이 잘못됐을 수 있다. 그것도 탈로 말한다 —
+      // 조용히 통과시키면 안 재고 있는 규칙이 하나 생긴다.
+      try { if (!new RegExp(s.pattern).test(값)) 탈.push(`${여기}: ${s.pattern} 모양이어야 합니다`); }
+      catch { 탈.push(`${여기}: 스키마의 pattern 이 잘못된 정규식입니다 (${s.pattern})`); }
+    }
+  }
+
+  if (typeof 값 === 'number') {
+    if (Number.isFinite(s.minimum) && 값 < s.minimum) 탈.push(`${여기}: ${s.minimum} 이상이어야 합니다`);
+    if (Number.isFinite(s.maximum) && 값 > s.maximum) 탈.push(`${여기}: ${s.maximum} 이하여야 합니다`);
+    if (Number.isFinite(s.exclusiveMinimum) && 값 <= s.exclusiveMinimum) 탈.push(`${여기}: ${s.exclusiveMinimum} 보다 커야 합니다`);
+    if (Number.isFinite(s.exclusiveMaximum) && 값 >= s.exclusiveMaximum) 탈.push(`${여기}: ${s.exclusiveMaximum} 보다 작아야 합니다`);
+    if (Number.isFinite(s.multipleOf) && s.multipleOf > 0) {
+      const 나눈것 = 값 / s.multipleOf;
+      if (Math.abs(나눈것 - Math.round(나눈것)) > 1e-9) 탈.push(`${여기}: ${s.multipleOf} 의 배수여야 합니다`);
+    }
+  }
+
+  if (Array.isArray(값)) {
+    if (Number.isFinite(s.minItems) && 값.length < s.minItems) 탈.push(`${여기}: ${s.minItems}개 이상이어야 합니다`);
+    if (Number.isFinite(s.maxItems) && 값.length > s.maxItems) 탈.push(`${여기}: ${s.maxItems}개 이하여야 합니다`);
+    if (s.items && typeof s.items === 'object' && !Array.isArray(s.items)) {
+      값.forEach((v, i) => 탈.push(...맞나(v, s.items, { 뿌리, 자리: `${여기}[${i}]` }).탈));
+    }
+  }
+
+  if (값 !== null && typeof 값 === 'object' && !Array.isArray(값)) {
+    for (const k of Array.isArray(s.required) ? s.required : []) {
+      if (!Object.prototype.hasOwnProperty.call(값, k)) 탈.push(`${여기}: ${k} 칸이 없습니다`);
+    }
+    const 칸들 = s.properties && typeof s.properties === 'object' ? s.properties : {};
+    for (const [k, v] of Object.entries(값)) {
+      if (Object.prototype.hasOwnProperty.call(칸들, k)) {
+        탈.push(...맞나(v, 칸들[k], { 뿌리, 자리: 여기 === '(뿌리)' ? k : `${여기}.${k}` }).탈);
+      } else if (s.additionalProperties === false) {
+        탈.push(`${여기}: ${k} 는 적으면 안 되는 칸입니다`);
+      } else if (s.additionalProperties && typeof s.additionalProperties === 'object') {
+        탈.push(...맞나(v, s.additionalProperties, { 뿌리, 자리: 여기 === '(뿌리)' ? k : `${여기}.${k}` }).탈);
+      }
+    }
+  }
+
+  if (Array.isArray(s.allOf)) for (const x of s.allOf) 탈.push(...맞나(값, x, { 뿌리, 자리 }).탈);
+  if (Array.isArray(s.anyOf) && !s.anyOf.some((x) => 맞나(값, x, { 뿌리, 자리 }).ok)) {
+    탈.push(`${여기}: anyOf 중 어느 것에도 안 맞습니다`);
+  }
+  if (Array.isArray(s.oneOf)) {
+    const 맞은수 = s.oneOf.filter((x) => 맞나(값, x, { 뿌리, 자리 }).ok).length;
+    if (맞은수 !== 1) 탈.push(`${여기}: oneOf 중 정확히 하나에 맞아야 하는데 ${맞은수}개에 맞습니다`);
+  }
+  if (s.not && typeof s.not === 'object' && 맞나(값, s.not, { 뿌리, 자리 }).ok) {
+    탈.push(`${여기}: not 에 걸립니다`);
+  }
+
+  return { ok: 탈.length === 0, 탈 };
+}
+
+/**
+ * 모델이 낸 글에서 JSON 을 뽑는다.
+ *
+ * 「JSON 만 내라」 고 적어 둬도 모델은 ```json 울타리를 두르거나 앞에 한 줄
+ * 인사를 붙인다. 그걸 실패로 치면 멀쩡한 답을 버리게 되므로, **뽑을 수 있으면
+ * 뽑는다.** 다만 뽑아 놓고 아무 말도 안 하면 안 된다 — 무엇을 걷어냈는지
+ * 돌려줘서 화면이 말하게 한다.
+ *
+ * @returns {{ok: true, 값: any, 군말: boolean} | {ok: false, 왜: string}}
+ */
+export function 답에서JSON뽑기(글) {
+  const s = String(글 ?? '').trim();
+  if (!s) return { ok: false, 왜: '답이 비었습니다' };
+
+  const 해보기 = (t) => { try { return { ok: true, 값: JSON.parse(t) }; } catch { return null; } };
+
+  const 그대로 = 해보기(s);
+  if (그대로) return { ...그대로, 군말: false };
+
+  // ```json … ``` 울타리
+  const 울타리 = /```(?:json|jsonc)?\s*\n([\s\S]*?)\n?```/i.exec(s);
+  if (울타리) {
+    const r = 해보기(울타리[1].trim());
+    if (r) return { ...r, 군말: true };
+  }
+
+  /*
+   * 앞뒤에 말이 붙은 경우. 첫 `{`(또는 `[`)부터 짝이 맞는 자리까지 잘라 본다.
+   *
+   * 따옴표 안의 괄호를 안 세는 것이 중요하다 — `{"글": "}"}` 를 깊이로만
+   * 세면 첫 `}` 에서 끊긴다.
+   */
+  const 시작 = Math.min(...['{', '['].map((ch) => { const i = s.indexOf(ch); return i < 0 ? Infinity : i; }));
+  if (Number.isFinite(시작)) {
+    const 열림 = s[시작];
+    const 닫힘 = 열림 === '{' ? '}' : ']';
+    let 깊이 = 0;
+    let 글속 = false;
+    for (let i = 시작; i < s.length; i++) {
+      const ch = s[i];
+      if (글속) {
+        if (ch === '\\') { i++; continue; }
+        if (ch === '"') 글속 = false;
+        continue;
+      }
+      if (ch === '"') { 글속 = true; continue; }
+      if (ch === 열림) 깊이++;
+      else if (ch === 닫힘 && --깊이 === 0) {
+        const r = 해보기(s.slice(시작, i + 1));
+        if (r) return { ...r, 군말: true };
+        break;
+      }
+    }
+  }
+  return { ok: false, 왜: '답에서 JSON 을 못 찾았습니다' };
+}
+
+/**
+ * 모델에게 붙일 말.
+ *
+ * 스키마를 통째로 싣는다 — 줄여 적으면 모델이 못 본 규칙을 어기고, 그러면
+ * 우리가 재서 되돌리는 한 바퀴가 더 돈다. 그 한 바퀴가 모델 호출 한 번이라
+ * 스키마를 다 싣는 것보다 비싸다.
+ */
+export function 시킬말(스키마, { 다시 = null } = {}) {
+  const 몸 = [
+    '',
+    '── 답의 모양이 정해져 있습니다 ─────────────────────────────────',
+    '',
+    '마지막 답은 **JSON 하나**여야 하고, 아래 스키마에 맞아야 합니다.',
+    '설명·인사·```울타리를 붙이지 마세요. JSON 만 내세요.',
+    '',
+    '```json',
+    JSON.stringify(스키마, null, 2),
+    '```',
+    '',
+    '모르는 값은 지어내지 말고, 스키마가 허락하면 null 이나 빈 배열로 두세요.',
+    '지어낸 값 하나가 이 답을 받아 쓰는 쪽에서 조용히 틀린 결정이 됩니다.',
+  ];
+  if (다시?.length) {
+    몸.push(
+      '',
+      '방금 낸 답이 아래에서 안 맞았습니다. 그것만 고쳐서 JSON 을 다시 내세요.',
+      ...다시.map((x) => `  - ${x}`),
+    );
+  }
+  return 몸.join('\n');
+}

package/src/agent/session.js

@@ -346,7 +346,18 @@ export class Session {
   }
 
   /**
-   * 이 폴더의 규칙 파일. DEEL.md → CLAUDE.md → AGENTS.md 중 먼저 읽히는 하나.
+   * 이 폴더의 규칙 파일. DEEL.md → CLAUDE.md → AGENTS.md → GEMINI.md 중
+   * 먼저 읽히는 하나.
+   *
+   * 남의 이름을 읽는 것이 이 목록의 요점이다. 규칙 파일은 사람이 며칠에 걸쳐
+   * 다듬어 놓은 것이고, 옮겨 오는 사람에게 「그건 못 읽으니 다시 적으세요」
+   * 라고 하면 대부분 안 옮긴다. GEMINI.md 를 뒤에 붙인 것은 Gemini CLI 가
+   * 2026-06-18 로 개인 사용자를 안 받게 되면서 그 파일을 든 채로 갈 곳을
+   * 찾는 사람이 실제로 생겼기 때문이다.
+   *
+   * 순서는 **좁은 것부터**다. DEEL.md 는 우리한테 하는 말이라 제일 세고,
+   * GEMINI.md 는 남한테 하던 말이라 제일 약하다. 두 개가 같이 있는 폴더에서
+   * 우리 이름을 진 파일이 지는 일은 없어야 한다.
    *
    * 없는 것은 그냥 없는 것이라 아무 말도 안 한다. 그런데 **있는데 못 읽는**
    * 것까지 같이 삼키면 안 된다 — 권한이 막혔거나 같은 이름의 폴더가 있으면
@@ -356,7 +367,7 @@ export class Session {
    * 못 읽은 것은 적어 두고 /status 가 '없음' 대신 그 까닭을 말한다.
    */
   #loadRules() {
-    for (const name of ['DEEL.md', 'CLAUDE.md', 'AGENTS.md']) {
+    for (const name of ['DEEL.md', 'CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
       try { return { name, text: readFileSync(join(this.root, name), 'utf8').slice(0, 20000) }; }
       catch (err) {
         // 없으면 그냥 없는 것이다 — 말할 일이 아니다. existsSync 로 먼저 보지

package/src/backend/adapter.js

@@ -2,7 +2,7 @@
 // 진단(probe)과 에이전트 루프가 같은 함수를 쓴다.
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { req, headersFor, serverMessage, Aborted } from './http.js';
+import { req, headersFor, serverMessage, Aborted, 잠잠기본, 초로 } from './http.js';
 import { 할당량기억, 미리기다릴까, 마지막할당량, 할당량자리 } from './quota.js';
 import { 열쇠 as 열쇠받아오기, 쓸수있나 } from '../safety/authcmd.js';
 import { 말 } from '../i18n/index.js';
@@ -1110,7 +1110,13 @@ export async function* chatStream(conn, opts) {
       method: 'POST',
       headers: await 머리말짓기(conn, opts),
       body,
+      /*
+       * 흘려 받는 자리에서 `timeout` 은 **머리말까지**다. 그 뒤로는 잠잠한
+       * 시간을 잰다 (backend/http.js 의 잠잠감시). 안 그러면 오래 생각하는
+       * 모델의 답이 5분에서 잘리고, 멎어 버린 게이트웨이는 5분을 꽉 채운다.
+       */
       timeout: opts.timeout ?? 300000,
+      잠잠: conn.잠잠 ?? 잠잠기본,
       stream: true,
       signal: opts.signal ?? null,
     });
@@ -1175,7 +1181,26 @@ export async function* chatStream(conn, opts) {
     let done;
     let value;
     try { ({ done, value } = await reader.read()); }
-    catch (err) { if (opts.signal?.aborted) throw new Aborted(); throw err; }
+    catch (err) {
+      if (opts.signal?.aborted) throw new Aborted();
+      /*
+       * 흐름이 멎어서 우리가 끊은 것.
+       *
+       * 여기까지 온 글자는 **버리지 않는다.** 3천 자를 받아 놓고 마지막에
+       * 멎었다고 통째로 던지면, 사람은 아무것도 못 보고 같은 것을 다시
+       * 시킨다 — 같은 자리에서 또 멎는다. 받은 것은 주고, 왜 멎었는지에
+       * 이름을 붙여 화면이 사실대로 말하게 한다.
+       *
+       * 다만 한 글자도 못 받았으면 그건 그냥 실패다. 빈 답을 '답' 이라고
+       * 부르는 것이 이 파일에서 제일 하면 안 되는 일이다.
+       */
+      if (err?.code === 'STALL' && (acc.content || acc.thinking || acc.toolCalls.length)) {
+        acc.stopped = 흐름멎음;
+        acc.멎은초 = 초로(err.잠잠 ?? 잠잠기본);
+        break;
+      }
+      throw err;
+    }
     // 끝났으면 decoder 에 걸쳐 있던 마지막 글자까지 뱉게 한다(flush).
     buf += done ? dec.decode() : dec.decode(value, { stream: true });
 
@@ -1231,6 +1256,17 @@ export async function* chatStream(conn, opts) {
 /** 서버가 끝난 까닭을 안 주고 흘려보내기를 멈춘 것. 'stop' 과 구별해야 한다. */
 export const 말없이끝남 = '말없이끝남';
 
+/**
+ * 흘러오던 것이 **멎어서 우리가 끊은** 것. 말없이끝남 과 구별한다.
+ *
+ * 말없이끝남 은 상대가 연결을 곱게 닫은 것이고, 이쪽은 연결이 살아 있는 채로
+ * 아무것도 안 오는 것이다. 고칠 자리가 다르다 — 앞은 중계 프록시가 몸통을
+ * 자르는 것이고, 뒤는 게이트웨이가 답을 통째로 모았다가 한 번에 주려다
+ * 우리 시계를 넘긴 것(그때는 잠잠 상한을 올리는 것이 답이다).
+ */
+export const 흐름멎음 = '흐름멎음';
+
+
 // 조각 하나를 누적하고, 화면에 흘릴 것만 내보낸다.
 function absorb(shape, obj, acc) {
   const out = [];

package/src/backend/clientcert.js

@@ -0,0 +1,164 @@
+// 게이트웨이가 **우리 인증서**를 요구할 때 (mTLS).
+//
+// ── 왜 필요한가 ────────────────────────────────────────────────────────
+//
+// 금융·공공 쪽 사내 게이트웨이는 열쇠 하나로 안 열린다. 서버가 클라이언트에게도
+// 인증서를 내라고 한다 — 열쇠는 훔쳐 갈 수 있지만 기기에 발급한 인증서는 그
+// 기기를 벗어나지 못한다는 것이 그 요구의 요지다. 그 자리에서 우리가 인증서를
+// 못 내면 붙는 방법이 아예 없다. 「사내에서 못 씁니다」 가 되고, 그건 다른
+// 어떤 기능으로도 못 메운다.
+//
+// ── 왜 fetch 를 못 쓰나 ────────────────────────────────────────────────
+//
+// Node 의 `fetch` 에는 인증서를 실을 자리가 없다. 그 자리는 undici 의
+// dispatcher 인데, 그건 가져다 쓸 수 있는 이름이 아니다(그리고 이 프로그램은
+// 딸린 것을 안 쓴다). 그래서 인증서를 쓰는 요청은 `node:https` 로 보낸다 —
+// 프록시를 거치는 길에서 이미 그렇게 하고 있으므로 길이 하나 더 생기는 것이
+// 아니라, 이미 있던 길에 인증서를 얹는 것이다 (backend/http.js 의 노드로).
+//
+// ── 어디에 적나 ────────────────────────────────────────────────────────
+//
+// 프로필에 적는다. 파일 **경로**만 적는다 — 알맹이를 설정 파일에 넣으면 그
+// 파일이 곧 개인키가 되고, 그건 백업·동기화·화면 공유를 타고 아무 데나 간다.
+//
+//     "인증서": {
+//       "cert": "C:/certs/client.pem",     PEM 인증서
+//       "key":  "C:/certs/client.key",     PEM 개인키
+//       "ca":   "C:/certs/corp-ca.pem"     (선택) 사내 루트
+//     }
+//
+// PKCS#12 한 덩이(`.pfx`·`.p12`)도 받는다 — 윈도우에서 받아 오는 모양이다.
+//
+//     "인증서": { "pfx": "C:/certs/client.pfx" }
+//
+// 암호는 **설정에 안 적는 것을 기본으로** 한다. `DEEL_CERT_PASS` 환경변수를
+// 먼저 보고, 없을 때만 설정의 `passphrase` 를 쓴다. 어느 쪽이든 화면·기록에
+// 안 나간다 (safety/secrets.js 가 가리는 것과 같은 규칙).
+//
+// ── 어느 주소에 붙나 ───────────────────────────────────────────────────
+//
+// **주소(origin)로 기억한다.** 프로필에 적힌 게이트웨이 주소에만 붙고, 다른
+// 집으로는 절대 안 나간다. 되돌림(redirect)을 따라 남의 집으로 갈 때 우리
+// 인증서가 따라가면 그건 신원을 남에게 보여 주는 것이다 — 열쇠 머리말을 떼는
+// 것과 같은 까닭으로 여기서도 안 따라간다.
+import { readFileSync, statSync } from 'node:fs';
+
+/** 프로필에 적힌 것을 한 모양으로 편다. 없으면 null. */
+export function 인증서설정(prof) {
+  const 것 = prof?.인증서 ?? prof?.clientCert ?? null;
+  if (!것 || typeof 것 !== 'object') return null;
+  const 글 = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+  const 편것 = {
+    cert: 글(것.cert ?? 것.certFile ?? 것.인증서),
+    key: 글(것.key ?? 것.keyFile ?? 것.열쇠),
+    pfx: 글(것.pfx ?? 것.p12 ?? 것.pfxFile),
+    ca: 글(것.ca ?? 것.caFile ?? 것.뿌리),
+    // 암호만 값이다. 나머지는 전부 파일 경로다.
+    passphrase: 글(것.passphrase ?? 것.암호),
+  };
+  /*
+   * 아무것도 안 적었으면 없는 것으로 친다. 빈 껍데기를 들고 다니면 아래에서
+   * 「인증서를 쓴다」 고 판단해 놓고 실제로는 아무것도 안 싣는다.
+   *
+   * `ca` 만 적은 것도 받는다. 사내 루트만 필요하고 우리 인증서는 안 내는
+   * 게이트웨이가 흔한데, 여태 그 자리의 길은 NODE_EXTRA_CA_CERTS 환경변수
+   * 하나뿐이었다 — 그건 프로필마다 다르게 못 준다. 사내 게이트웨이와 로컬
+   * 모델을 오가는 사람에게는 그게 곧 못 쓰는 것이다.
+   */
+  if (!편것.cert && !편것.pfx && !편것.ca) return null;
+  return 편것;
+}
+
+// 주소 → 설정. 프로그램이 사는 동안만 있는다.
+const 등록부 = new Map();
+
+/** 주소를 origin 하나로. 못 읽으면 null. */
+function 집(주소) {
+  try { return new URL(String(주소)).origin; } catch { return null; }
+}
+
+/** 이 게이트웨이는 우리 인증서를 요구한다고 적어 둔다. */
+export function 인증서등록(주소, 설정) {
+  const o = 집(주소);
+  if (!o) return;
+  if (설정) 등록부.set(o, 설정);
+  else 등록부.delete(o);
+}
+
+/** 검사와 `/model` 갈아타기가 쓴다. */
+export function 인증서잊기() { 등록부.clear(); 읽은것.clear(); }
+
+// 파일 경로 → { 때, 알맹이 }. 요청마다 디스크를 읽지 않으려고 들고 있는다.
+// 파일이 바뀌면(인증서를 새로 받으면) 다시 읽는다 — 프로그램을 껐다 켜야
+// 새 인증서가 먹는다면 그건 하루짜리 인증서를 쓰는 자리에서 못 쓴다는 뜻이다.
+const 읽은것 = new Map();
+
+function 파일읽기(경로, 무엇) {
+  let 때;
+  try { 때 = statSync(경로).mtimeMs; }
+  catch (err) { throw 못읽음(무엇, 경로, err); }
+  const 있던것 = 읽은것.get(경로);
+  if (있던것 && 있던것.때 === 때) return 있던것.알맹이;
+  let 알맹이;
+  try { 알맹이 = readFileSync(경로); }
+  catch (err) { throw 못읽음(무엇, 경로, err); }
+  읽은것.set(경로, { 때, 알맹이 });
+  return 알맹이;
+}
+
+function 못읽음(무엇, 경로, err) {
+  return Object.assign(
+    new Error(`${무엇}를 못 읽었습니다: ${경로}\n  ${err?.message ?? err}`),
+    { code: 'CERT_READ' },
+  );
+}
+
+/**
+ * 이 주소에 실을 TLS 옵션. 등록된 것이 없으면 null.
+ *
+ * 파일을 여기서 읽는다 — 켤 때 한 번 읽어 두면 짧게 도는 인증서를 갈아 끼웠을
+ * 때 프로그램을 껐다 켜야 한다. 읽은 것은 파일이 그대로면 다시 안 읽는다.
+ *
+ * @throws 인증서 파일을 못 읽으면 던진다. 조용히 빼고 붙으면 서버가 주는
+ *         것은 TLS 악수 실패인데, 그 화면은 「인증서가 없다」 와 「인증서가
+ *         틀렸다」 를 구별해 주지 않는다.
+ */
+export function 인증서찾기(주소) {
+  const o = 집(주소);
+  const 설정 = o ? 등록부.get(o) : null;
+  if (!설정) return null;
+  const 옵션 = {};
+  if (설정.pfx) 옵션.pfx = 파일읽기(설정.pfx, '클라이언트 인증서(pfx)');
+  if (설정.cert) 옵션.cert = 파일읽기(설정.cert, '클라이언트 인증서');
+  if (설정.key) 옵션.key = 파일읽기(설정.key, '클라이언트 개인키');
+  if (설정.ca) 옵션.ca = 파일읽기(설정.ca, '사내 루트 인증서');
+  /*
+   * 암호는 환경변수가 먼저다.
+   *
+   * 설정 파일은 백업·동기화·화면 공유를 타고 아무 데나 간다. 환경변수는 그
+   * 프로세스에만 있다. 둘 다 있으면 환경변수를 쓴다 — 파일에 적힌 것을
+   * 「임시로 다른 것을 써 보기」 위해 고치지 않아도 되게.
+   */
+  const 암호 = process.env.DEEL_CERT_PASS || 설정.passphrase;
+  if (암호) 옵션.passphrase = 암호;
+  return Object.keys(옵션).length ? 옵션 : null;
+}
+
+/**
+ * 화면에 보여 줄 한 줄. **암호는 절대 안 들어간다.**
+ *
+ * 무엇을 쓰고 있는지 사람이 볼 수 있어야 한다 — 붙었는지 아닌지만 알고
+ * 무엇으로 붙었는지 모르면, 인증서를 두 개 가진 사람은 어느 것이 먹었는지
+ * 알 길이 없다.
+ */
+export function 인증서말(설정) {
+  if (!설정) return null;
+  const 조각 = [];
+  if (설정.pfx) 조각.push(`pfx ${설정.pfx}`);
+  if (설정.cert) 조각.push(`cert ${설정.cert}`);
+  if (설정.key) 조각.push('key(적힘)');
+  if (설정.ca) 조각.push(`ca ${설정.ca}`);
+  const 암호 = process.env.DEEL_CERT_PASS ? '환경변수' : (설정.passphrase ? '설정' : null);
+  if (암호) 조각.push(`암호 ${암호}에서`);
+  return 조각.join(' · ');
+}