cdsa-harness 0.22.4 → 0.22.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdsa-harness",
-  "version": "0.22.4",
+  "version": "0.22.6",
   "description": "AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 터미널 하네스. 실시간 스트리밍 + OpenAI/Claude/OpenRouter + MCP + npm 플러그인·크로스포맷 스킬.",
   "type": "module",
   "bin": {

package/src/builtins.js

@@ -2,7 +2,7 @@
 // 스킬/플러그인/버전을 바꾼 뒤 `node scripts/gen-builtins.mjs` 로 재생성하세요.
 import p0 from "../plugins/hwpx_read.mjs";
 
-export const VERSION = "0.22.4";
+export const VERSION = "0.22.6";
 
 export const BUILTIN_PLUGINS = [p0];
 

package/src/cli.js

@@ -81,14 +81,27 @@ function printTeach(ev, stream) {
       return;
 
     case Step.MODEL_CALL: {
+      // 실제 값은 흰색, 초보자용 설명(←)은 노란색으로 구분해 가독성을 높인다.
+      const why = (t) => c.yellow(`← ${t}`);
+      const ROLE_DESC = {
+        system: "하네스가 자동으로 넣는 규칙·정체성·작업폴더 안내문",
+        user: "내가 입력한 메시지",
+        assistant: "모델(AI)이 이전에 한 답변",
+        tool: "도구 실행 결과 — 모델에게 되돌려주는 값",
+      };
       const lines = [];
-      lines.push(`${c.grey("provider/model")}  ${c.bold(`${d.provider} · ${d.model}`)}`);
-      lines.push(c.grey(`모델에 보내는 메시지 ${d.messages?.length || 0}개 · 추정 ${d.estTokens} 토큰 · ${d.totalChars}자`));
+      lines.push(`${c.grey("provider/model")}  ${c.white(c.bold(`${d.provider} · ${d.model}`))}  ${why("어느 회사의 어떤 모델을 호출하는지")}`);
+      lines.push(`${c.white(`모델에 보내는 메시지 ${d.messages?.length || 0}개 · 추정 ${d.estTokens} 토큰 · ${d.totalChars}자`)}`);
+      lines.push(`  ${why("모델은 기억이 없어서, 지금까지의 대화 전체를 매번 처음부터 다시 보냅니다")}`);
       for (const m of d.messages || []) {
         const roleColor = m.role === "system" ? c.magenta : m.role === "user" ? c.cyan : m.role === "assistant" ? c.green : c.yellow;
-        lines.push(`  ${roleColor(m.role.padEnd(9))} ${c.grey(`${m.chars}자${m.extra || ""}`)}`);
+        const desc = ROLE_DESC[m.role]
+          ? `  ${why(ROLE_DESC[m.role] + (m.extra && m.role === "assistant" ? " (도구를 써달라는 요청 포함)" : ""))}`
+          : "";
+        lines.push(`  ${roleColor(m.role.padEnd(9))} ${c.white(`${m.chars}자${m.extra || ""}`)}${desc}`);
       }
-      lines.push(c.grey(`제공 도구(${d.tools?.length || 0}): ${(d.tools || []).join(", ")}`));
+      lines.push(`${c.white(`제공 도구(${d.tools?.length || 0})`)}${c.grey(`: ${(d.tools || []).join(", ")}`)}`);
+      lines.push(`  ${why("모델이 쓸 수 있는 '손'(함수) 목록 — 모델이 이름과 인자로 요청하면 하네스가 대신 실행")}`);
       console.log(panel(lines, { title: `${d.sub ? "┆ " : ""}🧠 ② LLM 호출 — 반복 ${d.iteration}`, color: "magenta" }));
       if (d.systemPrompt && !d.sub) {
         console.log(panel(clip(d.systemPrompt, 600).split("\n"), {
@@ -297,7 +310,12 @@ async function fetchProviderModels(cfg, query = "") {
   try {
     if (cfg.provider === "openrouter") {
       const r = await fetchJson("https://openrouter.ai/api/v1/models");
-      let ids = (r.data || []).map((m) => m.id).sort();
+      // 하네스는 항상 도구(tools)를 함께 보내므로, 도구를 지원하지 않는 모델은 어차피
+      // "No endpoints found that support tool use" 로 실패한다 — 목록에서 미리 제외.
+      let ids = (r.data || [])
+        .filter((m) => !Array.isArray(m.supported_parameters) || m.supported_parameters.includes("tools"))
+        .map((m) => m.id)
+        .sort();
       if (q) ids = ids.filter((id) => id.toLowerCase().includes(q));
       return { list: ids, live: true };
     }

package/src/llm.js

@@ -346,6 +346,15 @@ function safeParse(jsonStr) {
 
 function httpErrorMessage(status, text) {
   let msg = `API 오류 ${status}: ${trim(text)}`;
+  // 도구(tool use) 미지원 모델/엔드포인트 — 모델명 오타 힌트는 오답이므로 여기서 끝낸다.
+  if (/tool[ _]use|support tools?/i.test(text)) {
+    msg +=
+      "\n  ↳ 이 모델(또는 이 모델의 제공 엔드포인트)이 도구 호출(tool use)을 지원하지 않아요. " +
+      "에이전트 하네스는 파일 도구가 필수라 도구 지원 모델이 필요합니다." +
+      "\n  ↳ /models 로 다른 모델을 고르세요 — OpenRouter 목록은 도구 지원 모델만 표시됩니다 " +
+      "(예: anthropic/claude-sonnet-4.5, openai/gpt-4o-mini).";
+    return msg;
+  }
   if (status === 404) {
     msg += "\n  ↳ 모델 이름을 확인하세요. /model 로 변경 가능. " +
       "OpenRouter 는 'provider/model' 형식이어야 합니다 (예: openai/gpt-4o-mini, anthropic/claude-3.7-sonnet).";

package/src/ui.js

@@ -25,6 +25,7 @@ export const c = {
   magenta: wrap(35, 39),
   cyan: wrap(36, 39),
   grey: wrap(90, 39),
+  white: wrap(97, 39), // 밝은 흰색 — 교육모드에서 '실제 값'을 또렷하게
 };
 
 // 24bit truecolor (그라데이션 배너용). hex "#rrggbb"