deel-local-cli 1.12.0 → 1.13.1

package/src/backend/cachemark.js

@@ -1,150 +1,223 @@
-import { estimateTokens } from './tokens.js';
-
-// 캐시 표식을 어디에 붙일까.
-//
-// ── 무엇이 문제였나 ─────────────────────────────────────────────────────
-//
-// 이 프로그램은 캐시 표식을 **어디에도 안 붙이고 있었다.** 그래서 서버가
-// 알아서 앞머리를 캐시해 주는 자리(Bedrock · OpenAI)에서는 정적 앞머리만
-// 잡혔고, 안 해 주는 자리(Anthropic 직통)에서는 하나도 안 잡혔다.
-//
-// 실제로 이런 모양이었다 — 열 번을 잇달아 부르는 동안 —
-//
-//   총 토큰   19,654 → 60,267   대화가 자란다
-//   캐시       5.9K  →  5.9K    앞머리에서 멈춰 있다
-//
-// 5.9K 는 시스템 프롬프트(약 4,045)와 도구 정의(약 1,800)를 합친 값이다.
-// 즉 **자라는 대화는 한 번도 캐시된 적이 없다.** 매 걸음 전액 다시 보내고
-// 전액 다시 냈다.
-//
-// ── 어디에 붙이나 ───────────────────────────────────────────────────────
-//
-// 규격이 정한 렌더 차례는 tools → system → messages 다. 표식 하나는 그
-// 자리까지의 앞머리를 통째로 잡는다. 그래서 두 자리면 충분하다.
-//
-//   1. 시스템의 **굳은 부분 끝**   — 도구까지 같이 잡힌다 (한 번 쓰고 계속 읽는다)
-//   2. 마지막 메시지 끝            — 걸음마다 앞으로 옮겨 간다 (자라는 대화를 잡는다)
-//
-// 2번이 이 파일의 핵심이다. 표식이 앞으로 옮겨 가면, 다음 요청은 지난번
-// 표식 자리까지를 **읽고** 그 뒤만 새로 쓴다. 안 옮기면 대화는 영영 캐시
-// 밖에 있다.
-//
-// ── 되돌아보기 창 ───────────────────────────────────────────────────────
-//
-// 표식은 뒤로 스무 자리까지만 지난 것을 찾는다. 도구를 길게 늘어놓는 턴은
-// 그 스무 자리를 넘길 수 있고, 그러면 **말없이** 캐시를 못 찾는다. 그래서
-// 대화가 길면 중간에 닻을 하나 더 박는다. 표식은 넷까지라 셋은 여유가 있다.
-//
-// ── 안 붙이는 자리 ──────────────────────────────────────────────────────
-//
-// 생각 블록에는 안 붙인다 — 우리가 나르기만 하는 블록이라 손대지 않는다.
-// 빈 글 블록에도 안 붙인다. 둘 다 거절당할 수 있고, 그 400 은 화면에서
-// 열쇠가 틀린 것과 구별이 안 된다.
-
-/** 표식 한 개. 기본 수명(5분)을 쓴다 — 한 시간짜리는 쓰기 값이 두 배다. */
-export const 표식 = { type: 'ephemeral' };
-
-/*
- * 시스템 글의 「굳은 부분 / 매 턴 바뀌는 부분」 을 나눠 담는 표.
- *
- * 왜 Symbol 인가: 이 표는 **우리끼리 쓰는 것**이라 전선에 나가면 안 된다.
- * JSON.stringify 는 Symbol 열쇠를 아예 안 본다. 보통 이름으로 달아 두면
- * openai 규격에서는 메시지가 그대로 몸통에 실려 나가므로, 모르는 칸 하나가
- * 그 게이트웨이에서 400 을 만든다.
- *
- * Symbol.for 를 쓰는 것은 같은 파일이 두 번 올라와도 같은 표가 되게 하려는
- * 것이다 (검사에서 모듈을 따로 불러오는 자리가 있다).
- */
-export const 조각표 = Symbol.for('deel.시스템조각');
-
-/** 표식을 붙여도 되는 블록인가. */
-const 붙일수있나 = (b) => {
-  const t = b?.type;
-  if (t === 'thinking' || t === 'redacted_thinking') return false;
-  if (t === 'text') return String(b.text ?? '').length > 0;
-  return t === 'tool_result' || t === 'tool_use' || t === 'image' || t === 'document';
-};
-
-/** 대화가 이보다 길면 중간에 닻을 하나 더 박는다 (되돌아보기 창 스무 자리). */
-export const 닻문턱 = 20;
-/** 닻은 끝에서 이만큼 앞에 박는다. */
-const 닻거리 = 12;
-
-/**
- * 메시지 하나의 **마지막 성한 블록**에 표식을 붙인 사본을 돌려준다.
- * 붙일 자리가 없으면 원본 그대로.
- */
-export function 블록에붙이기(msg) {
-  if (!msg) return msg;
-  const 본래 = Array.isArray(msg.content)
-    ? msg.content
-    : [{ type: 'text', text: String(msg.content ?? '') }];
-  let 자리 = -1;
-  for (let i = 본래.length - 1; i >= 0; i--) {
-    if (붙일수있나(본래[i])) { 자리 = i; break; }
-  }
-  if (자리 < 0) return msg;
-  const 새 = 본래.map((b, i) => (i === 자리 ? { ...b, cache_control: { ...표식 } } : b));
-  return { ...msg, content: 새 };
-}
-
-/**
- * 시스템 글 조각들을 블록 배열로 만든다.
- *
- * 첫 조각이 **굳은 부분**이다 (agent/session.js 의 시스템조각). 그 끝에
- * 표식을 박으면 도구 정의까지 같이 잡힌다 — 규격이 tools 를 system 앞에
- * 렌더하기 때문이다.
- *
- * 조각이 하나뿐이면 그 끝에 박는다. 그때는 모드가 바뀔 때마다 다시 쓰지만,
- * 안 박는 것보다는 낫다.
- *
- * @param {string[]} 조각들
- * @param {boolean} 표식쓰나
- */
-export function 시스템블록(조각들, 표식쓰나) {
-  const 있는것 = (조각들 ?? []).map((x) => String(x ?? '')).filter((x) => x.length);
-  if (!있는것.length) return null;
-  if (!표식쓰나) return 있는것.join('');
-  const 굳은끝 = 0;   // 첫 조각이 굳은 부분이다
-  return 있는것.map((text, i) => (
-    i === 굳은끝 ? { type: 'text', text, cache_control: { ...표식 } } : { type: 'text', text }
-  ));
-}
-
-/**
- * 메시지 배열에 옮겨 가는 표식을 붙인 **사본**을 돌려준다.
- *
- * @param {object[]} messages  차례합치기를 이미 거친 배열
- * @returns {object[]}
- */
-export function 메시지표식(messages) {
-  const ms = messages ?? [];
-  if (!ms.length) return ms;
-  const 붙일자리 = new Set([ms.length - 1]);
-  // 도구를 길게 늘어놓는 턴에서 되돌아보기 창을 넘기지 않게 닻을 하나 더.
-  if (ms.length > 닻문턱) 붙일자리.add(ms.length - 1 - 닻거리);
-  return ms.map((m, i) => (붙일자리.has(i) ? 블록에붙이기(m) : m));
-}
-
-/**
- * 이 요청에 표식을 붙일 만한가.
- *
- * 너무 작으면 서버가 안 잡는다. 붙여도 탈은 없지만, 안 잡히는 표식을 붙여
- * 놓고 「캐시를 켰다」 고 말하면 화면이 거짓말을 한다.
- *
- * 재는 자는 이 프로그램이 이미 쓰는 것으로 맞춘다(agent/session.js 의
- * estimateTokens). 여기는 **글자 수를 토큰의 두 배로** 치고 있었는데, 그건
- * 영어·코드에서만 맞는 셈이다. 한글은 글자당 1토큰이라 두 배로 나누면 절반이
- * 되고, Bedrock 처럼 최소가 4,096 인 창구에서는 실제로는 2,300 토큰밖에 안
- * 되는 대화에 「잡힐 만하다」 고 답했다. 그러면 안 잡힐 표식을 붙여 놓고
- * `/status` 가 「캐시 표식」 이라고 적는다 — 이 함수가 막겠다고 적어 둔 바로
- * 그 거짓말이다.
- */
-export function 잡힐만한가(messages, 최소토큰 = 1024) {
-  let 토큰 = 0;
-  for (const m of messages ?? []) {
-    토큰 += estimateTokens(typeof m?.content === 'string' ? m.content : JSON.stringify(m?.content ?? ''));
-    if (토큰 > 최소토큰) return true;
-  }
-  return false;
-}
+import { estimateTokens } from './tokens.js';
+
+// 캐시 표식을 어디에 붙일까.
+//
+// ── 무엇이 문제였나 ─────────────────────────────────────────────────────
+//
+// 이 프로그램은 캐시 표식을 **어디에도 안 붙이고 있었다.** 그래서 서버가
+// 알아서 앞머리를 캐시해 주는 자리(Bedrock · OpenAI)에서는 정적 앞머리만
+// 잡혔고, 안 해 주는 자리(Anthropic 직통)에서는 하나도 안 잡혔다.
+//
+// 실제로 이런 모양이었다 — 열 번을 잇달아 부르는 동안 —
+//
+//   총 토큰   19,654 → 60,267   대화가 자란다
+//   캐시       5.9K  →  5.9K    앞머리에서 멈춰 있다
+//
+// 5.9K 는 시스템 프롬프트(약 4,045)와 도구 정의(약 1,800)를 합친 값이다.
+// 즉 **자라는 대화는 한 번도 캐시된 적이 없다.** 매 걸음 전액 다시 보내고
+// 전액 다시 냈다.
+//
+// ── 어디에 붙이나 ───────────────────────────────────────────────────────
+//
+// 규격이 정한 렌더 차례는 tools → system → messages 다. 표식 하나는 그
+// 자리까지의 앞머리를 통째로 잡는다. 그래서 두 자리면 충분하다.
+//
+//   1. 시스템의 **굳은 부분 끝**   — 도구까지 같이 잡힌다 (한 번 쓰고 계속 읽는다)
+//   2. 마지막 메시지 끝            — 걸음마다 앞으로 옮겨 간다 (자라는 대화를 잡는다)
+//
+// 2번이 이 파일의 핵심이다. 표식이 앞으로 옮겨 가면, 다음 요청은 지난번
+// 표식 자리까지를 **읽고** 그 뒤만 새로 쓴다. 안 옮기면 대화는 영영 캐시
+// 밖에 있다.
+//
+// ── 되돌아보기 창 ───────────────────────────────────────────────────────
+//
+// 표식은 뒤로 스무 자리까지만 지난 것을 찾는다. 도구를 길게 늘어놓는 턴은
+// 그 스무 자리를 넘길 수 있고, 그러면 **말없이** 캐시를 못 찾는다. 그래서
+// 대화가 길면 중간에 닻을 하나 더 박는다. 표식은 넷까지라 셋은 여유가 있다.
+//
+// ── 안 붙이는 자리 ──────────────────────────────────────────────────────
+//
+// 생각 블록에는 안 붙인다 — 우리가 나르기만 하는 블록이라 손대지 않는다.
+// 빈 글 블록에도 안 붙인다. 둘 다 거절당할 수 있고, 그 400 은 화면에서
+// 열쇠가 틀린 것과 구별이 안 된다.
+
+/** 표식 한 개. 기본 수명(5분)을 쓴다 — 한 시간짜리는 쓰기 값이 두 배다. */
+export const 표식 = { type: 'ephemeral' };
+
+/**
+ * 표식을 적는 **칸 이름**들.
+ *
+ * 같은 뜻을 두 규격이 다른 이름으로 적는다. 어느 쪽인지는 창구가 아니라
+ * **규격**이 정하므로, 여기서는 이름만 알고 고르는 것은 카드가 한다
+ * (backend/wire.js 의 표식칸).
+ *
+ *   cache_control            Anthropic 규격의 칸. Claude 를 앞에 둔 창구는
+ *                            몸이 OpenAI 꼴이어도 이 칸으로 알아듣는다.
+ *   prompt_cache_breakpoint  OpenAI 규격의 칸. 규격 문서의 text 조각에
+ *                            정식으로 들어 있다.
+ *
+ * 어느 것도 「업체별 예외」 가 아니다. 둘 다 문서에 있는 칸이고, 안 받는
+ * 서버는 400 으로 말해 준다 — 그러면 카드가 배운다(backend/wire.js).
+ */
+export const 표식칸들 = ['cache_control', 'prompt_cache_breakpoint'];
+
+/** 그 칸에 적을 값. 칸마다 값의 모양이 다르다. */
+const 표식값 = (칸) => (칸 === 'prompt_cache_breakpoint'
+  ? { mode: 'explicit' }
+  : { ...표식 });
+
+/*
+ * 시스템 글의 「굳은 부분 / 매 턴 바뀌는 부분」 을 나눠 담는 표.
+ *
+ * 왜 Symbol 인가: 이 표는 **우리끼리 쓰는 것**이라 전선에 나가면 안 된다.
+ * JSON.stringify 는 Symbol 열쇠를 아예 안 본다. 보통 이름으로 달아 두면
+ * openai 규격에서는 메시지가 그대로 몸통에 실려 나가므로, 모르는 칸 하나가
+ * 그 게이트웨이에서 400 을 만든다.
+ *
+ * Symbol.for 를 쓰는 것은 같은 파일이 두 번 올라와도 같은 표가 되게 하려는
+ * 것이다 (검사에서 모듈을 따로 불러오는 자리가 있다).
+ */
+export const 조각표 = Symbol.for('deel.시스템조각');
+
+/** 표식을 붙여도 되는 블록인가. */
+const 붙일수있나 = (b) => {
+  const t = b?.type;
+  if (t === 'thinking' || t === 'redacted_thinking') return false;
+  if (t === 'text') return String(b.text ?? '').length > 0;
+  return t === 'tool_result' || t === 'tool_use' || t === 'image' || t === 'document';
+};
+
+/** 대화가 이보다 길면 중간에 닻을 하나 더 박는다 (되돌아보기 창 스무 자리). */
+export const 닻문턱 = 20;
+/** 닻은 끝에서 이만큼 앞에 박는다. */
+const 닻거리 = 12;
+
+/**
+ * 메시지 하나의 **마지막 성한 블록**에 표식을 붙인 사본을 돌려준다.
+ * 붙일 자리가 없으면 원본 그대로.
+ */
+export function 블록에붙이기(msg, 칸 = 'cache_control') {
+  if (!msg) return msg;
+  const 본래 = Array.isArray(msg.content)
+    ? msg.content
+    : [{ type: 'text', text: String(msg.content ?? '') }];
+  let 자리 = -1;
+  for (let i = 본래.length - 1; i >= 0; i--) {
+    if (붙일수있나(본래[i])) { 자리 = i; break; }
+  }
+  if (자리 < 0) return msg;
+  const 새 = 본래.map((b, i) => (i === 자리 ? { ...b, [칸]: 표식값(칸) } : b));
+  return { ...msg, content: 새 };
+}
+
+/**
+ * 시스템 글 조각들을 블록 배열로 만든다.
+ *
+ * 첫 조각이 **굳은 부분**이다 (agent/session.js 의 시스템조각). 그 끝에
+ * 표식을 박으면 도구 정의까지 같이 잡힌다 — 규격이 tools 를 system 앞에
+ * 렌더하기 때문이다.
+ *
+ * 조각이 하나뿐이면 그 끝에 박는다. 그때는 모드가 바뀔 때마다 다시 쓰지만,
+ * 안 박는 것보다는 낫다.
+ *
+ * @param {string[]} 조각들
+ * @param {boolean} 표식쓰나
+ */
+export function 시스템블록(조각들, 표식쓰나, 칸 = 'cache_control') {
+  const 있는것 = (조각들 ?? []).map((x) => String(x ?? '')).filter((x) => x.length);
+  if (!있는것.length) return null;
+  if (!표식쓰나) return 있는것.join('');
+  const 굳은끝 = 0;   // 첫 조각이 굳은 부분이다
+  return 있는것.map((text, i) => (
+    i === 굳은끝 ? { type: 'text', text, [칸]: 표식값(칸) } : { type: 'text', text }
+  ));
+}
+
+/**
+ * 메시지 배열에 옮겨 가는 표식을 붙인 **사본**을 돌려준다.
+ *
+ * @param {object[]} messages  차례합치기를 이미 거친 배열
+ * @returns {object[]}
+ */
+/**
+ * 그 자리에 표식을 **붙일 수 있나.** 없으면 한 칸씩 앞으로 물러선다.
+ *
+ * 도구만 부른 차례는 붙일 자리가 없다 — OpenAI 규격에서 그런 차례는
+ * `content: null` 이고(adapter.js 의 assistantMessage), 빈 글에는 표식을
+ * 못 붙인다(붙일수있나).
+ *
+ * 문제는 그때 `블록에붙이기` 가 **원본을 그대로 돌려준다**는 것이다. 아무
+ * 말도 안 하므로 그 요청은 닻 없이 나가고, 화면은 여전히 「캐시 표식」 이라고
+ * 적는다. 도구를 도는 턴은 `assistant(부름)` ↔ `tool(결과)` 이 번갈아 오므로
+ * **닻 자리가 절반 확률로 부름 차례에 떨어진다.** 하필 그 닻이 되돌아보기
+ * 창(스무 자리)을 넘기지 않으려고 박아 둔 것이라, 없어지면 앞이 통째로 다시 나간다.
+ *
+ * 그래서 못 붙이면 앞으로 물러서서 붙는 자리를 찾는다. 한 칸 앞이면 결과
+ * 차례라 거의 바로 걸린다.
+ */
+function 붙는자리(ms, 부터) {
+  for (let i = Math.min(부터, ms.length - 1); i >= 0; i--) {
+    const 그자리 = 블록에붙이기(ms[i], 'cache_control');
+    if (그자리 !== ms[i]) return i;
+  }
+  return -1;
+}
+
+export function 메시지표식(messages, 칸 = 'cache_control') {
+  const ms = messages ?? [];
+  if (!ms.length) return ms;
+  const 붙일자리 = new Set();
+  const 꼬리 = 붙는자리(ms, ms.length - 1);
+  if (꼬리 >= 0) 붙일자리.add(꼬리);
+  // 도구를 길게 늘어놓는 턴에서 되돌아보기 창을 넘기지 않게 닻을 하나 더.
+  if (ms.length > 닻문턱) {
+    const 닻 = 붙는자리(ms, ms.length - 1 - 닻거리);
+    // 꼬리와 같은 자리면 닻이 아니다 — 그건 표식 하나짜리다.
+    if (닻 >= 0 && 닻 !== 꼬리) 붙일자리.add(닻);
+  }
+  return ms.map((m, i) => (붙일자리.has(i) ? 블록에붙이기(m, 칸) : m));
+}
+
+/**
+ * 이 요청에 표식을 붙일 만한가.
+ *
+ * 너무 작으면 서버가 안 잡는다. 붙여도 탈은 없지만, 안 잡히는 표식을 붙여
+ * 놓고 「캐시를 켰다」 고 말하면 화면이 거짓말을 한다.
+ *
+ * 재는 자는 이 프로그램이 이미 쓰는 것으로 맞춘다(agent/session.js 의
+ * estimateTokens). 여기는 **글자 수를 토큰의 두 배로** 치고 있었는데, 그건
+ * 영어·코드에서만 맞는 셈이다. 한글은 글자당 1토큰이라 두 배로 나누면 절반이
+ * 되고, Bedrock 처럼 최소가 4,096 인 창구에서는 실제로는 2,300 토큰밖에 안
+ * 되는 대화에 「잡힐 만하다」 고 답했다. 그러면 안 잡힐 표식을 붙여 놓고
+ * `/status` 가 「캐시 표식」 이라고 적는다 — 이 함수가 막겠다고 적어 둔 바로
+ * 그 거짓말이다.
+ */
+export function 잡힐만한가(messages, 최소토큰 = 1024, 곁 = null) {
+  let 토큰 = 0;
+  /*
+   * 도구 정의도 **앞머리에 나가는 것**이다.
+   *
+   * 이 자가 메시지만 세고 있었다. 그런데 전선에 실릴 때 순서는
+   * `tools → system → messages` 라, 도구 스키마가 캐시 앞머리의 **맨 앞**
+   * 이다. 내장 도구 스무 개의 스키마는 1,800토큰쯤 된다.
+   *
+   * 그래서 시킴말과 사람말이 합쳐 500토큰인 판에서 이 자가 「문턱을 못
+   * 넘는다」 고 답했고, 표식을 하나도 안 붙였다. 실제로는 2,300토큰이라
+   * 넘고도 남는다. **덜 세서 캐시를 안 켠 것**인데, 화면에는 아무 말도
+   * 안 난다 — 그냥 매 턴 값이 더 나온다.
+   *
+   * 세는 것과 보내는 것이 다르면, 세는 쪽이 틀린 것이다.
+   */
+  if (곁) {
+    for (const 것 of [곁.tools, 곁.system]) {
+      if (것 == null) continue;
+      토큰 += estimateTokens(typeof 것 === 'string' ? 것 : JSON.stringify(것));
+      if (토큰 > 최소토큰) return true;
+    }
+  }
+  for (const m of messages ?? []) {
+    토큰 += estimateTokens(typeof m?.content === 'string' ? m.content : JSON.stringify(m?.content ?? ''));
+    if (토큰 > 최소토큰) return true;
+  }
+  return false;
+}