cdsa-harness 0.1.1 → 0.2.0

package/README.md

@@ -1,81 +1,93 @@
-# CDSA Harness (Node.js CLI) ⌨️
+# CDSA Harness (Node.js CLI) 🎓⌨️
 
-> Claude Code / Codex CLI / OpenCode 와 **똑같은 방식(npm/npx)** 으로 설치하는,
-> 좁은 의미의 AI 에이전트 하네스 교육용 터미널 앱.
-
-시작하면 ASCII 배너가 뜨고, **Agent Loop** 의 모든 단계가 색으로 흐릅니다.
+> **AI 에이전트가 내부에서 실제로 뭘 하는지** 단계별로 드러내는 교육용 터미널 하네스.
+> Claude Code·Codex 는 과정을 숨기지만, CDSA Harness 는 **컨텍스트 구성 → API 요청 → 모델의 판단 → 토큰/응답시간 → 도구 실행 → 결과 되먹임**을 전부 펼쳐 보여줍니다.
 
 ```
-입력 → 컨텍스트 구성 → LLM 호출 → 도구 판단 → 승인 → 실행 → 결과 반영 → 반복
+① 입력 → ② LLM 호출(보낼 컨텍스트·도구) → ③ 모델 응답(토큰·지연·tool_call)
+      → ④ 도구 판단 → ⑤ 실행/승인 → ⑥ 결과 되먹임 → (반복)
 ```
 
-- **의존성 0개** — Node 18+ 내장 기능만 사용(`fetch`/`readline`/`node:test`). `npx` 가 빠르고 설치 실패가 없습니다.
-- 같은 저장소의 Python 버전(Mini Harness GUI / CDSA Harness TUI)과 **동일한 하네스 구조**를 그대로 옮긴 것입니다.
+- **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
+- **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
+- **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
 
 ---
 
 ## 설치 / 실행
 
-### npx (설치 없이 즉시)
-
 ```bash
-# 로컬 체크아웃에서
-cd node-cli
-npx .                       # API Key 없으면 자동 mock 모드
+npx cdsa-harness                 # 설치 없이 즉시 (키 없으면 mock)
+npm install -g cdsa-harness      # 전역 설치 → 'cdsa-harness' / 'cdsa'
 ```
 
-### 전역 설치
+## 실제 AI 연결하기
 
+가장 쉬운 길 — 실행 후 `/setup` 입력(대화형으로 제공자·키·모델 선택):
 ```bash
-cd node-cli
-npm install -g .            # 또는: npm link
-cdsa-harness                # 어디서나 실행 (별칭: cdsa)
+cdsa-harness
+› /setup
 ```
 
-### 그냥 node 로
-
+또는 플래그/환경변수로:
 ```bash
-cd node-cli
-node bin/cdsa-harness.js
-```
+cdsa-harness --provider openai --model gpt-4o-mini
+cdsa-harness --provider anthropic --model claude-3-5-haiku-latest
 
-> npm 레지스트리에 publish 하면 `npm install -g cdsa-harness` / `npx cdsa-harness` 로 바로 설치됩니다.
+# 키는 환경변수로도 자동 인식(파일에 저장 안 함)
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENROUTER_API_KEY=sk-or-...
+```
 
 ---
 
-## 옵션 / 명령
+## 슬래시 명령
 
-```bash
-cdsa-harness --provider openai --model gpt-4.1-mini   # 실제 LLM
-cdsa-harness --provider openrouter --model anthropic/claude-3.5-sonnet
-cdsa-harness --workspace ./my-project                 # 작업 폴더 지정
-cdsa-harness --auto                                   # 승인 자동
-```
+| 명령 | 설명 |
+|------|------|
+| `/setup` | 제공자·API 키·모델 대화형 연결 |
+| `/provider <이름>` | openai · anthropic · openrouter · mock 전환 |
+| `/model <이름>` | 모델 변경 |
+| `/teach` | 교육 모드 켜기/끄기 |
+| `/context` | 지금 모델에 보내는 컨텍스트 들여다보기 |
+| `/reset` | 대화/컨텍스트 초기화 |
+| `/config` | 현재 설정값 |
+| `/quit` | 종료 (Ctrl+D) |
+
+## 플래그
 
-터미널 슬래시 명령: `/help` · `/reset` · `/config` · `/sessions` · `/quit` (Ctrl+D 로도 종료)
+```
+--provider <openai|anthropic|openrouter|mock>
+--model <모델명>
+--workspace <폴더경로>
+--setup        대화형 연결 설정
+--no-teach     교육 모드 끄고 간결 출력
+--auto         승인 자동
+```
 
 ---
 
 ## 설정 (config.json)
 
-`~/.cdsa_harness/config.json` 에 저장됩니다(실행 폴더에 `config.json` 이 있으면 우선).
+`~/.cdsa_harness/config.json` (실행 폴더에 `config.json` 있으면 우선).
 
 ```json
 {
   "provider": "openai",
   "api_key": "",
-  "model": "gpt-4.1-mini",
+  "model": "gpt-4o-mini",
   "workspace": "./workspace",
   "approval_mode": "manual",
   "allow_shell": false,
   "max_steps": 8,
-  "temperature": 0.2
+  "temperature": 0.2,
+  "max_tokens": 1024,
+  "teach_mode": true
 }
 ```
 
-작업 폴더 상대경로는 **현재 폴더(cwd)** 기준으로 해석합니다(CLI 답게).
-
----
+> `api_key` 가 비어 있으면 해당 provider 의 환경변수를 자동으로 찾습니다.
 
 ## 도구 & 안전장치
 
@@ -94,23 +106,20 @@ cdsa-harness --auto                                   # 승인 자동
 
 ```
 node-cli/
-├── bin/cdsa-harness.js   # npm/npx 진입점 (#!/usr/bin/env node)
+├── bin/cdsa-harness.js   # npm/npx 진입점
 ├── src/
-│   ├── config.js         # 설정 로드/저장
-│   ├── llm.js            # OpenAI/OpenRouter(fetch) + mock
-│   ├── tools.js          # 도구 + sandbox + diff + 스키마
-│   ├── loop.js           # ⭐ Agent Loop
+│   ├── config.js         # 설정 + 환경변수 키 감지
+│   ├── llm.js            # OpenAI/Anthropic/OpenRouter + mock, 응답 정규화(토큰·지연)
+│   ├── tools.js          # 도구 + sandbox + diff
+│   ├── loop.js           # ⭐ Agent Loop + 교육용 이벤트(컨텍스트/되먹임)
 │   ├── session.js        # 세션 로그(JSONL)
-│   ├── banner.js         # CDSA HARNESS ASCII 배너
-│   ├── ui.js             # ANSI 색/박스/diff 렌더
-│   └── cli.js            # 터미널 REPL
-├── workspace/            # 샘플 작업 폴더
+│   ├── banner.js / ui.js # 배너 · ANSI/박스/diff 렌더
+│   └── cli.js            # REPL + 교육 모드 렌더 + /setup
 └── test/core.test.js     # node --test
 ```
 
 ## 테스트
 
 ```bash
-cd node-cli
 npm test        # node --test
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdsa-harness",
-  "version": "0.1.1",
-  "description": "좁은 의미의 AI 에이전트 하네스를 터미널에서 체험하는 교육용 CLI (Claude Code / Codex / OpenCode 구조의 미니 런타임)",
+  "version": "0.2.0",
+  "description": "AI 에이전트의 내부 동작(컨텍스트·API요청·토큰·도구·되먹임)을 단계별로 드러내는 교육용 터미널 하네스. OpenAI/Claude/OpenRouter 지원.",
   "type": "module",
   "bin": {
     "cdsa-harness": "bin/cdsa-harness.js",

package/src/cli.js

@@ -1,17 +1,25 @@
 // CDSA Harness TUI 본체 — 터미널 REPL.
-// Python 의 ui/tui 와 동일한 흐름을 Node 내장 모듈만으로 구현.
+// 핵심 차별점: '교육 모드' — 실제 API 를 붙여도 에이전트 내부에서 벌어지는 일
+// (컨텍스트 구성 → API 요청 → 모델 판단 → 토큰/지연 → 도구 실행 → 결과 되먹임)을 단계별로 드러낸다.
 import readline from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 
 import { renderBanner } from "./banner.js";
-import { Config, configPath, loadConfig, saveConfig } from "./config.js";
-import { AgentLoop, Step, STEP_LABELS } from "./loop.js";
+import {
+  ENV_KEYS,
+  PROVIDERS,
+  SUGGESTED_MODELS,
+  configPath,
+  loadConfig,
+  saveConfig,
+} from "./config.js";
+import { AgentLoop, Step } from "./loop.js";
 import { LLMClient } from "./llm.js";
 import { SessionLog, sessionsDir } from "./session.js";
 import { Toolbox } from "./tools.js";
 import { c, panel, renderDiff } from "./ui.js";
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 
 const STEP_STYLE = {
   [Step.USER_INPUT]: ["🧑", "cyan"],
@@ -22,39 +30,118 @@ const STEP_STYLE = {
   [Step.APPROVAL]: ["🔐", "yellow"],
   [Step.TOOL_RUN]: ["🔧", "blue"],
   [Step.TOOL_RESULT]: ["📄", "grey"],
+  [Step.FEEDBACK]: ["↩️", "grey"],
   [Step.DONE]: ["✅", "green"],
   [Step.ERROR]: ["❌", "red"],
 };
 
-function makePrinter() {
+function clip(s, n) {
+  s = String(s ?? "");
+  return s.length > n ? s.slice(0, n) + " …" : s;
+}
+
+// cfg.teach_mode 를 실행 중 토글할 수 있으므로 closure 로 cfg 를 잡아둔다.
+function makePrinter(cfg) {
   return (ev) => {
-    const [icon, color] = STEP_STYLE[ev.step] || ["•", "cyan"];
-    const paint = c[color] || ((x) => x);
+    if (cfg.teach_mode) return printTeach(ev);
+    return printCompact(ev);
+  };
+}
 
-    // 승인 단계 UI 는 approvalCallback 이 직접 그린다(자동 승인 안내만 출력)
-    if (ev.step === Step.APPROVAL && !ev.title.includes("자동 승인")) return;
+// ---- 교육(teach) 렌더: 내부 과정을 패널로 펼쳐 보여준다 ----
+function printTeach(ev) {
+  const d = ev.data || {};
+  switch (ev.step) {
+    case Step.USER_INPUT:
+      console.log(`${c.cyan("🧑 ①")} ${c.bold("사용자 입력")}  ${c.grey(clip(ev.detail, 200))}`);
+      return;
+
+    case Step.BUILD_CONTEXT:
+      console.log(`${c.grey("🧱")} ${c.dim(ev.detail)}`);
+      return;
 
-    if (ev.step === Step.MODEL_REPLY) {
-      if (ev.detail && ev.detail !== "(텍스트 없음)") {
-        console.log(panel(ev.detail.split("\n"), { title: "🤖 모델", color: "green" }));
+    case Step.MODEL_CALL: {
+      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}자`));
+      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 || ""}`)}`);
+      }
+      lines.push(c.grey(`제공 도구(${d.tools?.length || 0}): ${(d.tools || []).join(", ")}`));
+      console.log(panel(lines, { title: `🧠 ② LLM 호출 — 반복 ${d.iteration}`, color: "magenta" }));
+      if (d.systemPrompt) {
+        console.log(panel(clip(d.systemPrompt, 600).split("\n"), {
+          title: "📜 시스템 프롬프트 (규칙+폴더가 여기 주입됨)",
+          color: "grey",
+        }));
       }
       return;
     }
-    if (ev.step === Step.DONE) {
-      console.log(panel((ev.detail || "완료").split("\n"), { title: "✅ 완료", color: "green" }));
+
+    case Step.MODEL_REPLY: {
+      const lines = [];
+      if (ev.detail && ev.detail !== "(텍스트 없음)") lines.push(...clip(ev.detail, 1200).split("\n"));
+      for (const tc of d.toolCalls || []) {
+        lines.push(c.yellow(`↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
+      }
+      const meta = [];
+      if (d.latencyMs != null) meta.push(`응답 ${d.latencyMs}ms`);
+      if (d.usage) meta.push(`토큰 입력 ${d.usage.input ?? "?"}/출력 ${d.usage.output ?? "?"}/합계 ${d.usage.total ?? "?"}`);
+      if (d.request?.bodyBytes) meta.push(`요청 ${d.request.bodyBytes}B`);
+      if (meta.length) lines.push(c.grey("─ " + meta.join(" · ")));
+      else lines.push(c.dim("(mock: 토큰/지연 측정 없음)"));
+      console.log(panel(lines.length ? lines : ["(빈 응답)"], { title: "🤖 ③ 모델 응답 (원본 판단)", color: "green" }));
       return;
     }
-    if (ev.step === Step.ERROR) {
+
+    case Step.TOOL_DECISION:
+      console.log(`${c.yellow("🤔 ④")} ${c.bold("도구 판단")}  ${c.grey(clip(ev.detail, 200))}`);
+      return;
+
+    case Step.TOOL_RUN:
+      console.log(`${c.blue("🔧 ⑤")} ${c.bold(ev.title)}  ${c.grey(clip(ev.detail, 200))}`);
+      return;
+
+    case Step.TOOL_RESULT:
+      console.log(panel(clip(ev.detail, 1500).split("\n"), { title: `📄 ${ev.title}`, color: "grey" }));
+      return;
+
+    case Step.FEEDBACK:
+      console.log(`${c.grey("↩️  ⑥ 결과 되먹임")}  ${c.dim(clip(ev.detail, 200))}`);
+      console.log(c.dim("   └ 도구 결과가 컨텍스트에 더해진 채로 ②부터 다시 — 이 반복이 'Agent Loop' 입니다."));
+      return;
+
+    case Step.APPROVAL:
+      if (ev.title.includes("자동 승인")) console.log(`${c.yellow("🔓")} ${c.dim(ev.title)}`);
+      return;
+
+    case Step.DONE:
+      console.log(panel((ev.detail || "완료").split("\n"), { title: "✅ 완료", color: "green" }));
+      return;
+
+    case Step.ERROR:
       console.log(panel((ev.detail || "").split("\n"), { title: `❌ ${ev.title}`, color: "red" }));
       return;
-    }
+  }
+}
 
-    let detail = (ev.detail || "").trim().replace(/\s+/g, " ");
-    if (detail.length > 110) detail = detail.slice(0, 110) + " …";
-    let line = `${paint(icon)} ${paint(c.bold(ev.title))}`;
-    if (detail && ev.step !== Step.USER_INPUT) line += `  ${c.grey(detail)}`;
-    console.log(line);
-  };
+// ---- 간결(compact) 렌더: 한 줄 위주 ----
+function printCompact(ev) {
+  const [icon, color] = STEP_STYLE[ev.step] || ["•", "cyan"];
+  const paint = c[color] || ((x) => x);
+  if (ev.step === Step.APPROVAL && !ev.title.includes("자동 승인")) return;
+  if (ev.step === Step.MODEL_REPLY) {
+    if (ev.detail && ev.detail !== "(텍스트 없음)") console.log(panel(ev.detail.split("\n"), { title: "🤖 모델", color: "green" }));
+    return;
+  }
+  if (ev.step === Step.DONE) return console.log(panel((ev.detail || "완료").split("\n"), { title: "✅ 완료", color: "green" }));
+  if (ev.step === Step.ERROR) return console.log(panel((ev.detail || "").split("\n"), { title: `❌ ${ev.title}`, color: "red" }));
+  if (ev.step === Step.FEEDBACK) return;
+  let detail = clip((ev.detail || "").trim().replace(/\s+/g, " "), 110);
+  let line = `${paint(icon)} ${paint(c.bold(ev.title))}`;
+  if (detail && ev.step !== Step.USER_INPUT) line += `  ${c.grey(detail)}`;
+  console.log(line);
 }
 
 function makeApproval(rl) {
@@ -80,23 +167,36 @@ function makeApproval(rl) {
   };
 }
 
+function makeClient(cfg) {
+  return new LLMClient({
+    provider: cfg.provider,
+    apiKey: cfg.resolvedKey(),
+    model: cfg.model,
+    temperature: cfg.temperature,
+    maxTokens: cfg.max_tokens,
+  });
+}
+
 function printIntro(cfg) {
   console.log(renderBanner());
-  console.log(c.dim("좁은 의미의 하네스를 터미널에서 체험하는 미니 AI 에이전트 런타임"));
+  console.log(c.dim("AI 에이전트의 내부 동작을 단계별로 드러내는 교육용 하네스"));
   console.log();
+  const keySource = cfg.provider === "mock" ? "-" : cfg.api_key ? "config.json" : ENV_KEYS[cfg.provider] && process.env[ENV_KEYS[cfg.provider]] ? `환경변수 ${ENV_KEYS[cfg.provider]}` : c.red("없음");
   const rows = [
     ["버전", `v${VERSION}`],
     ["provider", cfg.provider],
     ["model", cfg.model],
+    ["API 키", keySource],
+    ["교육 모드", cfg.teach_mode ? c.green("ON (과정 펼쳐보기)") : "OFF"],
     ["작업 폴더", cfg.workspacePath()],
     ["승인 모드", cfg.approval_mode],
     ["셸 실행", cfg.allow_shell ? "허용" : "차단"],
   ];
-  const lines = rows.map(([k, v]) => `${c.grey(k)}   ${c.bold(v)}`);
+  const lines = rows.map(([k, v]) => `${c.grey(k.padEnd(9))}  ${c.bold(v)}`);
   console.log(panel(lines, { title: "⚙️  CDSA Harness 설정", color: "cyan" }));
   console.log(
     c.dim("명령: ") +
-      `${c.cyan("/help")} 도움말 · ${c.cyan("/reset")} 새 대화 · ${c.cyan("/config")} 설정값 · ${c.cyan("/quit")} 종료\n`
+      `${c.cyan("/setup")} 연결 · ${c.cyan("/teach")} 교육모드 · ${c.cyan("/context")} 컨텍스트 · ${c.cyan("/help")} 도움말 · ${c.cyan("/quit")} 종료\n`
   );
 }
 
@@ -105,29 +205,85 @@ function printHelp() {
     panel(
       [
         c.bold("사용법"),
-        `그냥 시키고 싶은 일을 입력하면 됩니다. 예) ${c.cyan("notes.txt 맨 아래에 할 일 3개 추가해줘")}`,
+        `시키고 싶은 일을 한국어로 입력하세요. 예) ${c.cyan("notes.txt 맨 아래에 할 일 3개 추가해줘")}`,
         "",
         c.bold("슬래시 명령"),
-        `  ${c.cyan("/help")}     이 도움말`,
-        `  ${c.cyan("/reset")}    대화/컨텍스트 초기화(새 세션)`,
-        `  ${c.cyan("/config")}   현재 설정값과 config.json 경로`,
-        `  ${c.cyan("/sessions")} 세션 로그 폴더 경로`,
-        `  ${c.cyan("/quit")}     종료 (Ctrl+D 도 가능)`,
+        `  ${c.cyan("/setup")}    제공자·API 키·모델 연결(대화형)`,
+        `  ${c.cyan("/provider")} <openai|anthropic|openrouter|mock> 제공자 변경`,
+        `  ${c.cyan("/model")} <이름>   모델 변경`,
+        `  ${c.cyan("/teach")}    교육 모드 켜기/끄기(내부 과정 펼쳐보기)`,
+        `  ${c.cyan("/context")}  지금 모델에 보내는 컨텍스트 들여다보기`,
+        `  ${c.cyan("/reset")}    대화/컨텍스트 초기화`,
+        `  ${c.cyan("/config")}   현재 설정값`,
+        `  ${c.cyan("/quit")}     종료 (Ctrl+D)`,
         "",
-        c.bold("하네스 흐름 (각 단계가 색으로 표시됩니다)"),
-        "  입력 → 컨텍스트 구성 → LLM 호출 → 도구 판단 → 승인 → 실행 → 결과 반영 → 반복",
+        c.bold("교육 모드에서 보이는 단계"),
+        "  ① 입력 → ② LLM 호출(컨텍스트·도구) → ③ 모델 응답(토큰·지연) →",
+        "  ④ 도구 판단 → ⑤ 실행/승인 → ⑥ 결과 되먹임 → (반복)",
       ],
       { title: "도움말", color: "cyan" }
     )
   );
 }
 
+// 대화형 연결 설정. 키는 환경변수가 있으면 그걸 우선 안내(파일 저장 안 함).
+async function runSetup(rl, cfg) {
+  console.log(panel(
+    [
+      "어떤 AI 에 연결할까요? 번호를 입력하세요.",
+      `  ${c.bold("1")}) openai      (GPT, 키: ${ENV_KEYS.openai})`,
+      `  ${c.bold("2")}) anthropic   (Claude, 키: ${ENV_KEYS.anthropic})`,
+      `  ${c.bold("3")}) openrouter  (여러 모델 중계, 키: ${ENV_KEYS.openrouter})`,
+      `  ${c.bold("4")}) mock        (키 없이 연습)`,
+    ],
+    { title: "🔌 연결 설정 (/setup)", color: "cyan" }
+  ));
+  const pick = (await rl.question(c.cyan("제공자 번호 [1-4]: "))).trim();
+  const provider = { "1": "openai", "2": "anthropic", "3": "openrouter", "4": "mock" }[pick];
+  if (!provider) {
+    console.log(c.yellow("취소했습니다."));
+    return false;
+  }
+  cfg.provider = provider;
+
+  if (provider === "mock") {
+    cfg.model = "mock-agent";
+  } else {
+    const envName = ENV_KEYS[provider];
+    const envVal = (process.env[envName] || "").trim();
+    if (envVal) {
+      const useEnv = (await rl.question(c.cyan(`환경변수 ${envName} 에서 키를 찾았어요. 사용할까요? [Y/n] `))).trim().toLowerCase();
+      if (useEnv === "" || useEnv === "y" || useEnv === "yes") {
+        cfg.api_key = ""; // 환경변수 사용 → 파일엔 저장 안 함
+      } else {
+        const k = (await rl.question(c.cyan("API 키 붙여넣기(입력이 보일 수 있음): "))).trim();
+        cfg.api_key = k;
+      }
+    } else {
+      console.log(c.dim(`(또는 종료 후 환경변수 ${envName} 에 키를 넣어두면 파일에 저장하지 않아도 됩니다)`));
+      const k = (await rl.question(c.cyan("API 키 붙여넣기(입력이 보일 수 있음): "))).trim();
+      cfg.api_key = k;
+    }
+    const sugg = SUGGESTED_MODELS[provider] || [];
+    const def = sugg[0] || "";
+    const m = (await rl.question(c.cyan(`모델 [${def}] (추천: ${sugg.join(", ")}): `))).trim();
+    cfg.model = m || def;
+  }
+
+  const saved = saveConfig(cfg);
+  console.log(c.green(`설정을 저장했습니다 → ${saved}`));
+  if (!cfg.isReady()) console.log(c.yellow("⚠️ 아직 키가 없어 호출이 실패할 수 있어요. 환경변수나 /setup 으로 키를 넣어주세요."));
+  return true;
+}
+
 function parseArgs(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--auto") out.auto = true;
     else if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--setup") out.setup = true;
+    else if (a === "--no-teach") out.noTeach = true;
     else if (a === "--provider") out.provider = argv[++i];
     else if (a === "--model") out.model = argv[++i];
     else if (a === "--workspace") out.workspace = argv[++i];
@@ -140,13 +296,16 @@ export async function main(argv = []) {
   const args = parseArgs(argv);
   if (args.help) {
     console.log(
-      "CDSA Harness — 미니 AI 에이전트 하네스 (터미널)\n\n" +
+      "CDSA Harness — AI 에이전트 내부를 드러내는 교육용 하네스 (터미널)\n\n" +
         "사용법: cdsa-harness [옵션]\n" +
-        "  --provider <openai|openrouter|mock>\n" +
+        "  --provider <openai|anthropic|openrouter|mock>\n" +
         "  --model <모델명>\n" +
         "  --workspace <폴더경로>\n" +
+        "  --setup                대화형 연결 설정 실행\n" +
+        "  --no-teach             교육 모드 끄고 간결하게\n" +
         "  --auto                 승인 자동(approval_mode=auto)\n" +
-        "  -h, --help             도움말\n"
+        "  -h, --help             도움말\n\n" +
+        "API 키는 환경변수로도 인식됩니다: OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY\n"
     );
     return 0;
   }
@@ -156,33 +315,26 @@ export async function main(argv = []) {
   if (args.model) cfg.model = args.model;
   if (args.workspace) cfg.workspace = args.workspace;
   if (args.auto) cfg.approval_mode = "auto";
+  if (args.noTeach) cfg.teach_mode = false;
 
-  if (!cfg.isReady()) {
-    console.log(
-      c.yellow("API Key 가 없어 mock 모드로 실행합니다. ") +
-        `실제 LLM 을 쓰려면 ${configPath()} 에 provider/api_key 를 설정하세요.\n`
-    );
-    cfg.provider = "mock";
-    cfg.model = "mock-agent";
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+
+  if (args.setup) {
+    await runSetup(rl, cfg);
+  } else if (!cfg.isReady() && cfg.provider !== "mock") {
+    console.log(c.yellow(`provider=${cfg.provider} 인데 API 키가 없습니다. 연결 설정을 시작합니다.\n`));
+    await runSetup(rl, cfg);
   }
 
   printIntro(cfg);
 
-  const client = new LLMClient({
-    provider: cfg.provider,
-    apiKey: cfg.api_key,
-    model: cfg.model,
-    temperature: cfg.temperature,
-  });
   const toolbox = new Toolbox(cfg.workspacePath(), cfg.allow_shell);
   const session = SessionLog.create();
-  const rl = readline.createInterface({ input: stdin, output: stdout });
-
   const loop = new AgentLoop({
     config: cfg,
-    client,
+    client: makeClient(cfg),
     toolbox,
-    onEvent: makePrinter(),
+    onEvent: makePrinter(cfg),
     approvalCallback: makeApproval(rl),
     session,
   });
@@ -195,27 +347,51 @@ export async function main(argv = []) {
     try {
       user = (await rl.question(c.bold(c.cyan("› ")))).trim();
     } catch {
-      break; // Ctrl+D / 스트림 종료
+      break;
     }
     if (!user) continue;
     const low = user.toLowerCase();
+
     if (["/quit", "/exit", "quit", "exit", ":q"].includes(low)) break;
-    if (low === "/help") {
-      printHelp();
+    if (low === "/help") { printHelp(); continue; }
+    if (low === "/reset") { loop.reset(); console.log(c.green("컨텍스트를 초기화했습니다.")); continue; }
+    if (low === "/config") { printIntro(cfg); console.log(c.dim(`config.json: ${configPath()}`)); continue; }
+    if (low === "/sessions") { console.log(c.dim(`세션 로그: ${sessionsDir()}`)); continue; }
+    if (low === "/teach") {
+      cfg.teach_mode = !cfg.teach_mode;
+      console.log(c.green(`교육 모드 ${cfg.teach_mode ? "ON" : "OFF"}.`));
+      continue;
+    }
+    if (low === "/setup" || low === "/login") {
+      await runSetup(rl, cfg);
+      loop.client = makeClient(cfg);
+      loop.reset();
       continue;
     }
-    if (low === "/reset") {
+    if (low.startsWith("/provider")) {
+      const p = user.split(/\s+/)[1];
+      if (!PROVIDERS.includes(p)) { console.log(c.yellow(`provider 는 ${PROVIDERS.join("/")} 중 하나.`)); continue; }
+      cfg.provider = p;
+      if (SUGGESTED_MODELS[p]?.length) cfg.model = SUGGESTED_MODELS[p][0];
+      loop.client = makeClient(cfg);
       loop.reset();
-      console.log(c.green("컨텍스트를 초기화했습니다(새 세션)."));
+      console.log(c.green(`provider=${p}, model=${cfg.model} (키: ${cfg.isReady() ? "OK" : c.red("없음 — /setup")})`));
       continue;
     }
-    if (low === "/config") {
-      printIntro(cfg);
-      console.log(c.dim(`config.json: ${configPath()}`));
+    if (low.startsWith("/model")) {
+      const m = user.split(/\s+/).slice(1).join(" ").trim();
+      if (!m) { console.log(c.dim(`현재 모델: ${cfg.model} · 추천: ${(SUGGESTED_MODELS[cfg.provider] || []).join(", ")}`)); continue; }
+      cfg.model = m;
+      loop.client = makeClient(cfg);
+      console.log(c.green(`model=${m}`));
       continue;
     }
-    if (low === "/sessions") {
-      console.log(c.dim(`세션 로그 폴더: ${sessionsDir()}`));
+    if (low === "/context") {
+      const ctx = loop.contextSummary();
+      const lines = [c.grey(`메시지 ${ctx.rows.length}개 · 추정 ${ctx.estTokens} 토큰 · ${ctx.totalChars}자`)];
+      for (const m of ctx.rows) lines.push(`  ${c.bold(m.role.padEnd(9))} ${c.grey(`${m.chars}자${m.extra || ""}`)}`);
+      console.log(panel(lines, { title: "🧩 현재 컨텍스트(다음 호출에 전송됨)", color: "magenta" }));
+      console.log(panel(clip(ctx.systemPrompt, 800).split("\n"), { title: "📜 시스템 프롬프트", color: "grey" }));
       continue;
     }
 

package/src/config.js

@@ -4,18 +4,26 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-export const PROVIDERS = ["openai", "openrouter", "mock"];
+export const PROVIDERS = ["openai", "anthropic", "openrouter", "mock"];
 
 export const SUGGESTED_MODELS = {
-  openai: ["gpt-4.1-mini", "gpt-4o-mini", "gpt-4.1"],
+  openai: ["gpt-4o-mini", "gpt-4.1-mini", "gpt-4.1"],
+  anthropic: ["claude-3-5-haiku-latest", "claude-3-5-sonnet-latest", "claude-sonnet-4-5"],
   openrouter: [
-    "openai/gpt-4.1-mini",
+    "openai/gpt-4o-mini",
     "anthropic/claude-3.5-sonnet",
     "google/gemini-2.5-flash",
   ],
   mock: ["mock-agent"],
 };
 
+// provider 별로 자동 감지하는 환경변수(파일에 키를 저장하지 않아도 됨)
+export const ENV_KEYS = {
+  openai: "OPENAI_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+};
+
 export const APPROVAL_MODES = ["manual", "auto"];
 
 const DEFAULTS = {
@@ -27,6 +35,8 @@ const DEFAULTS = {
   allow_shell: false,
   max_steps: 8,
   temperature: 0.2,
+  max_tokens: 1024,
+  teach_mode: true,
 };
 
 export function configDir() {
@@ -54,9 +64,17 @@ export class Config {
     return p;
   }
 
+  // 파일에 저장된 키가 없으면 환경변수에서 찾는다.
+  resolvedKey() {
+    const direct = (this.api_key || "").trim();
+    if (direct) return direct;
+    const envName = ENV_KEYS[this.provider];
+    return envName ? (process.env[envName] || "").trim() : "";
+  }
+
   isReady() {
     if (this.provider === "mock") return true;
-    return Boolean((this.api_key || "").trim());
+    return Boolean(this.resolvedKey());
   }
 
   toJSON() {

package/src/llm.js

@@ -1,31 +1,58 @@
-// LLM 호출 계층. OpenAI / OpenRouter (OpenAI 호환) + 키 없이 체험하는 mock.
+// LLM 호출 계층. OpenAI / OpenRouter (OpenAI 호환) / Anthropic(Claude) + mock.
 // Node 18+ 내장 fetch 사용 → 외부 의존성 없음.
+//
+// 모든 provider 의 응답을 아래 한 가지 형태로 정규화해서 돌려준다(교육 모드용 메타 포함):
+//   { content, toolCalls:[{id,name,args}], usage:{input,output,total}|null,
+//     latencyMs, request:{ provider, endpoint, model, temperature, toolCount, bodyBytes } }
 
 export class LLMError extends Error {}
 
 const ENDPOINTS = {
   openai: "https://api.openai.com/v1/chat/completions",
   openrouter: "https://openrouter.ai/api/v1/chat/completions",
+  anthropic: "https://api.anthropic.com/v1/messages",
 };
 
 export class LLMClient {
-  constructor({ provider, apiKey, model, temperature = 0.2, timeout = 60000 }) {
+  constructor({ provider, apiKey, model, temperature = 0.2, maxTokens = 1024, timeout = 60000 }) {
     this.provider = provider;
     this.apiKey = apiKey;
     this.model = model;
     this.temperature = temperature;
+    this.maxTokens = maxTokens;
     this.timeout = timeout;
   }
 
   async chat(messages, tools) {
     if (this.provider === "mock") return mockChat(messages);
-    if (!ENDPOINTS[this.provider]) {
-      throw new LLMError(`지원하지 않는 provider 입니다: ${this.provider}`);
+    if (this.provider === "anthropic") return this._anthropicChat(messages, tools);
+    if (ENDPOINTS[this.provider]) return this._openaiChat(messages, tools);
+    throw new LLMError(`지원하지 않는 provider 입니다: ${this.provider}`);
+  }
+
+  async _post(url, headers, body) {
+    const json = JSON.stringify(body);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeout);
+    const started = Date.now();
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers, body: json, signal: ctrl.signal });
+    } catch (e) {
+      throw new LLMError(`네트워크 오류: ${e.message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    const latencyMs = Date.now() - started;
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new LLMError(`API 오류 ${res.status}: ${trim(text) || res.statusText}`);
     }
-    return this._httpChat(messages, tools);
+    return { payload: await res.json(), latencyMs, bodyBytes: Buffer.byteLength(json, "utf8") };
   }
 
-  async _httpChat(messages, tools) {
+  // --- OpenAI / OpenRouter (chat/completions 형식) ---
+  async _openaiChat(messages, tools) {
     const url = ENDPOINTS[this.provider];
     const body = { model: this.model, messages, temperature: this.temperature };
     if (tools && tools.length) {
@@ -37,96 +64,206 @@ export class LLMClient {
       "Content-Type": "application/json",
     };
     if (this.provider === "openrouter") {
-      headers["HTTP-Referer"] = "https://github.com/cdsa-harness";
+      headers["HTTP-Referer"] = "https://github.com/cdsassj00/miniharness";
       headers["X-Title"] = "CDSA Harness";
     }
+    const { payload, latencyMs, bodyBytes } = await this._post(url, headers, body);
+    const parsed = parseOpenAiReply(payload);
+    return {
+      ...parsed,
+      latencyMs,
+      request: this._meta(url, tools, bodyBytes),
+    };
+  }
 
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeout);
-    let res;
-    try {
-      res = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        signal: ctrl.signal,
-      });
-    } catch (e) {
-      throw new LLMError(`네트워크 오류: ${e.message}`);
-    } finally {
-      clearTimeout(timer);
-    }
+  // --- Anthropic (messages 형식) ---
+  async _anthropicChat(messages, tools) {
+    const url = ENDPOINTS.anthropic;
+    const body = toAnthropicBody(messages, tools, this.model, this.temperature, this.maxTokens);
+    const headers = {
+      "x-api-key": this.apiKey,
+      "anthropic-version": "2023-06-01",
+      "Content-Type": "application/json",
+    };
+    const { payload, latencyMs, bodyBytes } = await this._post(url, headers, body);
+    const parsed = parseAnthropicReply(payload);
+    return {
+      ...parsed,
+      latencyMs,
+      request: this._meta(url, tools, bodyBytes),
+    };
+  }
 
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      throw new LLMError(`API 오류 ${res.status}: ${text || res.statusText}`);
-    }
-    const payload = await res.json();
-    return parseOpenAiReply(payload);
+  _meta(endpoint, tools, bodyBytes) {
+    return {
+      provider: this.provider,
+      endpoint,
+      model: this.model,
+      temperature: this.temperature,
+      toolCount: tools ? tools.length : 0,
+      bodyBytes,
+    };
   }
 }
 
+function trim(s) {
+  s = String(s || "");
+  return s.length > 400 ? s.slice(0, 400) + " …" : s;
+}
+
 function parseOpenAiReply(payload) {
   const msg = payload?.choices?.[0]?.message;
   if (!msg) {
-    throw new LLMError(
-      `예상치 못한 응답 형식입니다: ${JSON.stringify(payload).slice(0, 300)}`
-    );
+    throw new LLMError(`예상치 못한 응답 형식입니다: ${JSON.stringify(payload).slice(0, 300)}`);
   }
   const toolCalls = [];
   for (const tc of msg.tool_calls || []) {
     let args = {};
     try {
-      args = typeof tc.function?.arguments === "string"
-        ? JSON.parse(tc.function.arguments || "{}")
-        : tc.function?.arguments || {};
+      args =
+        typeof tc.function?.arguments === "string"
+          ? JSON.parse(tc.function.arguments || "{}")
+          : tc.function?.arguments || {};
     } catch {
       args = { _raw: tc.function?.arguments };
     }
     toolCalls.push({ id: tc.id || `call_${toolCalls.length}`, name: tc.function?.name || "", args });
   }
-  return { content: msg.content ?? null, toolCalls };
+  const u = payload.usage;
+  const usage = u
+    ? { input: u.prompt_tokens ?? null, output: u.completion_tokens ?? null, total: u.total_tokens ?? null }
+    : null;
+  return { content: msg.content ?? null, toolCalls, usage };
+}
+
+// 내부(OpenAI 형식) 메시지를 Anthropic messages 형식으로 변환.
+// - system 메시지 → 최상위 system 필드
+// - assistant tool_calls → content 의 tool_use 블록
+// - tool 메시지 → user 의 tool_result 블록 (연속된 것은 하나의 user 로 합침)
+export function toAnthropicBody(messages, tools, model, temperature, maxTokens) {
+  let system = "";
+  const out = [];
+  for (const m of messages) {
+    if (m.role === "system") {
+      system += (system ? "\n" : "") + (m.content || "");
+    } else if (m.role === "user") {
+      pushUserBlock(out, { type: "text", text: m.content || "" });
+    } else if (m.role === "assistant") {
+      const content = [];
+      if (m.content) content.push({ type: "text", text: m.content });
+      for (const tc of m.tool_calls || []) {
+        let input = {};
+        try {
+          input = JSON.parse(tc.function?.arguments || "{}");
+        } catch {
+          input = {};
+        }
+        content.push({ type: "tool_use", id: tc.id, name: tc.function?.name, input });
+      }
+      out.push({ role: "assistant", content: content.length ? content : [{ type: "text", text: "" }] });
+    } else if (m.role === "tool") {
+      pushUserBlock(out, { type: "tool_result", tool_use_id: m.tool_call_id, content: m.content || "" });
+    }
+  }
+  const body = { model, max_tokens: maxTokens, system, messages: out, temperature };
+  if (tools && tools.length) {
+    body.tools = tools.map((t) => ({
+      name: t.function.name,
+      description: t.function.description,
+      input_schema: t.function.parameters,
+    }));
+  }
+  return body;
+}
+
+// 직전 메시지가 user 면 블록을 이어붙이고, 아니면 새 user 메시지를 만든다.
+function pushUserBlock(out, block) {
+  const last = out[out.length - 1];
+  if (last && last.role === "user") last.content.push(block);
+  else out.push({ role: "user", content: [block] });
+}
+
+function parseAnthropicReply(payload) {
+  if (payload?.type === "error") {
+    throw new LLMError(`Anthropic 오류: ${payload.error?.message || JSON.stringify(payload)}`);
+  }
+  const blocks = payload?.content || [];
+  let text = "";
+  const toolCalls = [];
+  for (const b of blocks) {
+    if (b.type === "text") text += b.text;
+    else if (b.type === "tool_use") toolCalls.push({ id: b.id, name: b.name, args: b.input || {} });
+  }
+  const u = payload?.usage;
+  const usage = u
+    ? {
+        input: u.input_tokens ?? null,
+        output: u.output_tokens ?? null,
+        total: (u.input_tokens || 0) + (u.output_tokens || 0),
+      }
+    : null;
+  return { content: text || null, toolCalls, usage };
 }
 
 // ---------------------------------------------------------------------------
 // Mock 에이전트: 키 없이 Agent Loop 전체를 체험.
-// 히스토리에 쌓인 tool 결과 개수로 '현재 단계'를 판단하는 결정형 에이전트.
+// 인사/잡담엔 그냥 대화로 답하고, 파일 작업을 시킬 때만 도구 데모를 돌린다.
 // ---------------------------------------------------------------------------
+const FILE_TASK_RE =
+  /(파일|폴더|디렉|notes|\.txt|\.md|\.js|읽|쓰|수정|고치|만들|생성|추가|삭제|편집|list|read|write|만들어|적어|기록)/i;
+
+function mockReturn(extra) {
+  return { usage: null, latencyMs: 1, request: { provider: "mock", endpoint: "(mock)", model: "mock-agent", temperature: 0, toolCount: 0, bodyBytes: 0 }, ...extra };
+}
+
 function mockChat(messages) {
   const toolMsgs = messages.filter((m) => m.role === "tool");
   const lastUser = [...messages].reverse().find((m) => m.role === "user")?.content || "";
   const phase = toolMsgs.length;
 
+  // 아직 도구를 쓰기 전 + 파일 작업 요청이 아니면 → 그냥 대화로 응답(도구 X)
+  if (phase === 0 && !FILE_TASK_RE.test(lastUser)) {
+    return mockReturn({
+      content:
+        "안녕하세요! 저는 CDSA Harness 의 mock(연습) 에이전트예요. 실제 AI 는 아니고, " +
+        "에이전트가 도구로 파일을 다루는 흐름을 보여주는 데모입니다.\n" +
+        "예) \"notes.txt 맨 아래에 할 일 3개 추가해줘\" 처럼 파일 작업을 시켜보세요. " +
+        "진짜 AI 와 대화하려면 /setup 으로 OpenAI·Claude 키를 연결하면 됩니다.",
+      toolCalls: [],
+    });
+  }
+
   if (phase === 0) {
-    return {
+    return mockReturn({
       content: "작업 폴더 구조부터 확인하겠습니다.",
       toolCalls: [{ id: "mock_1", name: "list_dir", args: { path: "." } }],
-    };
+    });
   }
   if (phase === 1) {
     const target = guessFile(toolMsgs[0].content || "", lastUser);
-    return {
+    return mockReturn({
       content: `\`${target}\` 파일을 읽어 현재 내용을 확인하겠습니다.`,
       toolCalls: [{ id: "mock_2", name: "read_file", args: { path: target } }],
-    };
+    });
   }
   if (phase === 2) {
     const target = guessFile(toolMsgs[0].content || "", lastUser);
     const current = toolMsgs[1].content || "";
-    const addition = `\n\n# (CDSA Harness mock 에이전트가 추가) 요청: ${lastUser.trim().slice(0, 60)}`;
-    const newContent = current.replace(/\n+$/, "") + addition + "\n";
-    return {
-      content: `\`${target}\` 끝에 메모 한 줄을 추가하는 수정을 제안합니다.`,
+    const base = /파일이 없습니다|경로가 없습니다/.test(current) ? "" : current;
+    const addition = `# (CDSA Harness mock 에이전트가 추가) 요청: ${lastUser.trim().slice(0, 60)}`;
+    const newContent = (base.replace(/\n+$/, "") + "\n\n" + addition + "\n").replace(/^\n+/, "");
+    return mockReturn({
+      content: `\`${target}\` 에 메모 한 줄을 추가하는 수정을 제안합니다.`,
       toolCalls: [{ id: "mock_3", name: "write_file", args: { path: target, content: newContent } }],
-    };
+    });
   }
-  return {
+  return mockReturn({
     content:
       "완료했습니다. 방금까지의 흐름이 바로 하네스의 Agent Loop 입니다:\n" +
-      "① 작업 폴더 보기 → ② 파일 읽기 → ③ 파일 수정 제안 → ④ 사용자 승인 → ⑤ 저장 → ⑥ 결과를 다시 모델에 전달.\n" +
-      "실제 LLM 을 쓰려면 --provider openai --model ... 와 API Key 를 설정하세요.",
+      "① 폴더 보기 → ② 파일 읽기 → ③ 수정 제안 → ④ 승인 → ⑤ 저장 → ⑥ 결과를 다시 모델에 전달.\n" +
+      "실제 LLM 으로 같은 흐름을 보려면 /setup 으로 키를 연결하세요.",
     toolCalls: [],
-  };
+  });
 }
 
 function guessFile(listing, userText) {
@@ -142,5 +279,7 @@ function guessFile(listing, userText) {
   for (const name of files) {
     if (userText.includes(name)) return name;
   }
+  const m = userText.match(/[\w./-]+\.(txt|md|js|json|py|ts|csv)/i);
+  if (m) return m[0];
   return files[0] || "notes.txt";
 }

package/src/loop.js

@@ -19,6 +19,7 @@ export const Step = {
   APPROVAL: "approval",
   TOOL_RUN: "tool_run",
   TOOL_RESULT: "tool_result",
+  FEEDBACK: "feedback",
   DONE: "done",
   ERROR: "error",
 };
@@ -32,10 +33,35 @@ export const STEP_LABELS = {
   approval: "사용자 승인",
   tool_run: "도구 실행",
   tool_result: "결과 반영",
+  feedback: "결과 되먹임",
   done: "완료",
   error: "오류",
 };
 
+// 아주 거친 토큰 추정(영문 ~4자/토큰, 한글은 더 많지만 교육용 어림값).
+export function estimateTokens(text) {
+  return Math.max(1, Math.round((text || "").length / 4));
+}
+
+// messages 를 교육용으로 요약: 역할별 글자수 + 도구호출 수.
+function summarizeMessages(messages) {
+  let totalChars = 0;
+  const rows = messages.map((m) => {
+    const text = m.content || "";
+    let chars = text.length;
+    let extra = "";
+    if (m.tool_calls && m.tool_calls.length) {
+      const j = JSON.stringify(m.tool_calls);
+      chars += j.length;
+      extra = ` +tool_calls(${m.tool_calls.length})`;
+    }
+    if (m.role === "tool") extra = " (도구 결과)";
+    totalChars += chars;
+    return { role: m.role, chars, extra };
+  });
+  return { rows, totalChars, estTokens: estimateTokens(messages.map((m) => (m.content || "") + JSON.stringify(m.tool_calls || "")).join("")) };
+}
+
 const RULES_FILENAMES = ["AGENT.md", "AGENTS.md", "CLAUDE.md", "rules.md", "RULES.md"];
 
 function findRules(workspace) {
@@ -98,7 +124,13 @@ export class AgentLoop {
   }
 
   reset() {
-    this.messages = [{ role: "system", content: this._systemPrompt() }];
+    this.systemPromptText = this._systemPrompt();
+    this.messages = [{ role: "system", content: this.systemPromptText }];
+  }
+
+  // /context 명령용: 현재 대화 컨텍스트 요약.
+  contextSummary() {
+    return { ...summarizeMessages(this.messages), systemPrompt: this.systemPromptText };
   }
 
   async run(userInput) {
@@ -114,13 +146,26 @@ export class AgentLoop {
     );
 
     const tools = toolSchemas(this.config.allow_shell);
+    const toolNames = tools.map((t) => t.function.name);
     let finalText = "";
 
     for (let stepNo = 1; stepNo <= this.config.max_steps; stepNo++) {
+      // ② 모델에 보내는 컨텍스트를 그대로 드러낸다(교육 모드 핵심).
+      const ctx = summarizeMessages(this.messages);
       this._emit(
         Step.MODEL_CALL,
-        `LLM 호출 (반복 ${stepNo})`,
-        `메시지 ${this.messages.length}개를 모델에 전송합니다.`
+        `LLM 호출 (반복 ${stepNo}/${this.config.max_steps})`,
+        `메시지 ${this.messages.length}개(추정 ${ctx.estTokens} 토큰)를 모델에 전송합니다.`,
+        {
+          iteration: stepNo,
+          provider: this.config.provider,
+          model: this.config.model,
+          messages: ctx.rows,
+          totalChars: ctx.totalChars,
+          estTokens: ctx.estTokens,
+          tools: toolNames,
+          systemPrompt: stepNo === 1 ? this.systemPromptText : null,
+        }
       );
 
       let reply;
@@ -134,8 +179,12 @@ export class AgentLoop {
         throw e;
       }
 
+      // ③ 모델의 원본 판단 + 실측 메타(응답시간/토큰/요청크기)를 드러낸다.
       this._emit(Step.MODEL_REPLY, "모델 응답", reply.content || "(텍스트 없음)", {
         toolCalls: reply.toolCalls.map((tc) => ({ name: tc.name, args: tc.args })),
+        usage: reply.usage || null,
+        latencyMs: reply.latencyMs ?? null,
+        request: reply.request || null,
       });
       if (reply.content) finalText = reply.content;
 
@@ -163,6 +212,14 @@ export class AgentLoop {
         const resultText = await this._handleToolCall(tc);
         this.messages.push({ role: "tool", tool_call_id: tc.id, content: resultText });
       }
+
+      // ⑤ 도구 결과를 messages 에 넣고 다시 ②로 — 이 되먹임이 'Loop' 의 정체.
+      this._emit(
+        Step.FEEDBACK,
+        "결과 되먹임",
+        `도구 결과를 대화에 추가했습니다(현재 메시지 ${this.messages.length}개). 같은 컨텍스트로 다시 모델을 호출합니다.`,
+        { messageCount: this.messages.length }
+      );
     }
 
     this._emit(Step.DONE, "반복 한도 도달", `max_steps(${this.config.max_steps})에 도달해 종료했습니다.`);