cdsa-harness 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# CDSA Harness (Node.js CLI) ⌨️
+
+> Claude Code / Codex CLI / OpenCode 와 **똑같은 방식(npm/npx)** 으로 설치하는,
+> 좁은 의미의 AI 에이전트 하네스 교육용 터미널 앱.
+
+시작하면 ASCII 배너가 뜨고, **Agent Loop** 의 모든 단계가 색으로 흐릅니다.
+
+```
+입력 → 컨텍스트 구성 → LLM 호출 → 도구 판단 → 승인 → 실행 → 결과 반영 → 반복
+```
+
+- **의존성 0개** — Node 18+ 내장 기능만 사용(`fetch`/`readline`/`node:test`). `npx` 가 빠르고 설치 실패가 없습니다.
+- 같은 저장소의 Python 버전(Mini Harness GUI / CDSA Harness TUI)과 **동일한 하네스 구조**를 그대로 옮긴 것입니다.
+
+---
+
+## 설치 / 실행
+
+### npx (설치 없이 즉시)
+
+```bash
+# 로컬 체크아웃에서
+cd node-cli
+npx .                       # API Key 없으면 자동 mock 모드
+```
+
+### 전역 설치
+
+```bash
+cd node-cli
+npm install -g .            # 또는: npm link
+cdsa-harness                # 어디서나 실행 (별칭: cdsa)
+```
+
+### 그냥 node 로
+
+```bash
+cd node-cli
+node bin/cdsa-harness.js
+```
+
+> npm 레지스트리에 publish 하면 `npm install -g cdsa-harness` / `npx cdsa-harness` 로 바로 설치됩니다.
+
+---
+
+## 옵션 / 명령
+
+```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                                   # 승인 자동
+```
+
+터미널 슬래시 명령: `/help` · `/reset` · `/config` · `/sessions` · `/quit` (Ctrl+D 로도 종료)
+
+---
+
+## 설정 (config.json)
+
+`~/.cdsa_harness/config.json` 에 저장됩니다(실행 폴더에 `config.json` 이 있으면 우선).
+
+```json
+{
+  "provider": "openai",
+  "api_key": "",
+  "model": "gpt-4.1-mini",
+  "workspace": "./workspace",
+  "approval_mode": "manual",
+  "allow_shell": false,
+  "max_steps": 8,
+  "temperature": 0.2
+}
+```
+
+작업 폴더 상대경로는 **현재 폴더(cwd)** 기준으로 해석합니다(CLI 답게).
+
+---
+
+## 도구 & 안전장치
+
+| 도구 | 설명 | 승인 |
+|------|------|:----:|
+| `list_dir` | 폴더 나열 | 자동 |
+| `read_file` | 파일 읽기 | 자동 |
+| `write_file` | 파일 생성/수정 | **diff 승인** |
+| `run_shell` | 셸 실행 | **승인**(기본 차단) |
+
+모든 도구는 작업 폴더 밖으로 나갈 수 없습니다(경로 sandbox).
+
+---
+
+## 구조
+
+```
+node-cli/
+├── bin/cdsa-harness.js   # npm/npx 진입점 (#!/usr/bin/env node)
+├── src/
+│   ├── config.js         # 설정 로드/저장
+│   ├── llm.js            # OpenAI/OpenRouter(fetch) + 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/            # 샘플 작업 폴더
+└── test/core.test.js     # node --test
+```
+
+## 테스트
+
+```bash
+cd node-cli
+npm test        # node --test
+```

package/bin/cdsa-harness.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// CDSA Harness — npm/npx 진입점.
+//   npx cdsa-harness   또는   cdsa-harness (전역 설치 시)
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    console.error(err?.stack || String(err));
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "cdsa-harness",
+  "version": "0.1.0",
+  "description": "좁은 의미의 AI 에이전트 하네스를 터미널에서 체험하는 교육용 CLI (Claude Code / Codex / OpenCode 구조의 미니 런타임)",
+  "type": "module",
+  "bin": {
+    "cdsa-harness": "bin/cdsa-harness.js",
+    "cdsa": "bin/cdsa-harness.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/cdsa-harness.js",
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "workspace",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "harness",
+    "agent-loop",
+    "cli",
+    "tui",
+    "llm",
+    "education"
+  ],
+  "author": "cdsassj00",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cdsassj00/miniharness.git",
+    "directory": "node-cli"
+  },
+  "homepage": "https://github.com/cdsassj00/miniharness/tree/main/node-cli#readme",
+  "bugs": {
+    "url": "https://github.com/cdsassj00/miniharness/issues"
+  }
+}

package/src/banner.js

@@ -0,0 +1,19 @@
+// 시작 배너(ASCII 아트) — "CDSA HARNESS" (figlet slant 폰트로 미리 렌더, 하드코딩)
+import { hex } from "./ui.js";
+
+const ART = String.raw`   __________  _____ ___       __  _____    ____  _   __________________
+  / ____/ __ \/ ___//   |     / / / /   |  / __ \/ | / / ____/ ___/ ___/
+ / /   / / / /\__ \/ /| |    / /_/ / /| | / /_/ /  |/ / __/  \__ \\__ \
+/ /___/ /_/ /___/ / ___ |   / __  / ___ |/ _, _/ /|  / /___ ___/ /__/ /
+\____/_____//____/_/  |_|  /_/ /_/_/  |_/_/ |_/_/ |_/_____//____/____/`;
+
+const GRADIENT = ["#22d3ee", "#38bdf8", "#3b82f6", "#6366f1", "#8b5cf6"];
+
+export function bannerText() {
+  return ART;
+}
+
+export function renderBanner() {
+  const lines = ART.split("\n");
+  return lines.map((line, i) => hex(line, GRADIENT[i % GRADIENT.length])).join("\n") + "\n";
+}

package/src/cli.js

@@ -0,0 +1,235 @@
+// CDSA Harness TUI 본체 — 터미널 REPL.
+// Python 의 ui/tui 와 동일한 흐름을 Node 내장 모듈만으로 구현.
+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 { 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 STEP_STYLE = {
+  [Step.USER_INPUT]: ["🧑", "cyan"],
+  [Step.BUILD_CONTEXT]: ["🧱", "grey"],
+  [Step.MODEL_CALL]: ["🧠", "magenta"],
+  [Step.MODEL_REPLY]: ["🤖", "green"],
+  [Step.TOOL_DECISION]: ["🤔", "yellow"],
+  [Step.APPROVAL]: ["🔐", "yellow"],
+  [Step.TOOL_RUN]: ["🔧", "blue"],
+  [Step.TOOL_RESULT]: ["📄", "grey"],
+  [Step.DONE]: ["✅", "green"],
+  [Step.ERROR]: ["❌", "red"],
+};
+
+function makePrinter() {
+  return (ev) => {
+    const [icon, color] = STEP_STYLE[ev.step] || ["•", "cyan"];
+    const paint = c[color] || ((x) => x);
+
+    // 승인 단계 UI 는 approvalCallback 이 직접 그린다(자동 승인 안내만 출력)
+    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) {
+      console.log(panel((ev.detail || "완료").split("\n"), { title: "✅ 완료", color: "green" }));
+      return;
+    }
+    if (ev.step === 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);
+  };
+}
+
+function makeApproval(rl) {
+  return async (req) => {
+    if (req.toolName === "write_file") {
+      console.log(panel(renderDiff(req.diff || "(변경 미리보기 없음)"), {
+        title: `🔐 파일 수정 제안 — ${req.path}`,
+        color: "yellow",
+      }));
+    } else if (req.toolName === "run_shell") {
+      console.log(panel([req.command], { title: "🔐 셸 실행 제안", color: "red" }));
+    } else {
+      console.log(panel([JSON.stringify(req.args)], { title: `🔐 ${req.toolLabel}`, color: "yellow" }));
+    }
+    let ans = "";
+    try {
+      ans = (await rl.question(c.yellow("이 작업을 승인하시겠습니까? [y/N] "))).trim().toLowerCase();
+    } catch {
+      ans = "";
+    }
+    const approved = ans === "y" || ans === "yes";
+    return { approved, reason: approved ? "" : "사용자가 거부했습니다." };
+  };
+}
+
+function printIntro(cfg) {
+  console.log(renderBanner());
+  console.log(c.dim("좁은 의미의 하네스를 터미널에서 체험하는 미니 AI 에이전트 런타임"));
+  console.log();
+  const rows = [
+    ["버전", `v${VERSION}`],
+    ["provider", cfg.provider],
+    ["model", cfg.model],
+    ["작업 폴더", cfg.workspacePath()],
+    ["승인 모드", cfg.approval_mode],
+    ["셸 실행", cfg.allow_shell ? "허용" : "차단"],
+  ];
+  const lines = rows.map(([k, v]) => `${c.grey(k)}   ${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`
+  );
+}
+
+function printHelp() {
+  console.log(
+    panel(
+      [
+        c.bold("사용법"),
+        `그냥 시키고 싶은 일을 입력하면 됩니다. 예) ${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.bold("하네스 흐름 (각 단계가 색으로 표시됩니다)"),
+        "  입력 → 컨텍스트 구성 → LLM 호출 → 도구 판단 → 승인 → 실행 → 결과 반영 → 반복",
+      ],
+      { title: "도움말", color: "cyan" }
+    )
+  );
+}
+
+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 === "--provider") out.provider = argv[++i];
+    else if (a === "--model") out.model = argv[++i];
+    else if (a === "--workspace") out.workspace = argv[++i];
+    else out._.push(a);
+  }
+  return out;
+}
+
+export async function main(argv = []) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(
+      "CDSA Harness — 미니 AI 에이전트 하네스 (터미널)\n\n" +
+        "사용법: cdsa-harness [옵션]\n" +
+        "  --provider <openai|openrouter|mock>\n" +
+        "  --model <모델명>\n" +
+        "  --workspace <폴더경로>\n" +
+        "  --auto                 승인 자동(approval_mode=auto)\n" +
+        "  -h, --help             도움말\n"
+    );
+    return 0;
+  }
+
+  const cfg = loadConfig();
+  if (args.provider) cfg.provider = args.provider;
+  if (args.model) cfg.model = args.model;
+  if (args.workspace) cfg.workspace = args.workspace;
+  if (args.auto) cfg.approval_mode = "auto";
+
+  if (!cfg.isReady()) {
+    console.log(
+      c.yellow("API Key 가 없어 mock 모드로 실행합니다. ") +
+        `실제 LLM 을 쓰려면 ${configPath()} 에 provider/api_key 를 설정하세요.\n`
+    );
+    cfg.provider = "mock";
+    cfg.model = "mock-agent";
+  }
+
+  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,
+    toolbox,
+    onEvent: makePrinter(),
+    approvalCallback: makeApproval(rl),
+    session,
+  });
+  loop.reset();
+
+  const rule = () => console.log(c.grey("─".repeat(Math.min(80, stdout.columns || 80))));
+
+  while (true) {
+    let user;
+    try {
+      user = (await rl.question(c.bold(c.cyan("› ")))).trim();
+    } catch {
+      break; // Ctrl+D / 스트림 종료
+    }
+    if (!user) continue;
+    const low = user.toLowerCase();
+    if (["/quit", "/exit", "quit", "exit", ":q"].includes(low)) break;
+    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;
+    }
+
+    rule();
+    try {
+      await loop.run(user);
+    } catch (e) {
+      console.log(c.red(`실행 오류: ${e?.message || e}`));
+    }
+    rule();
+  }
+
+  rl.close();
+  session.close();
+  console.log(c.dim("\n종료합니다. 안녕히 가세요!"));
+  return 0;
+}

package/src/config.js

@@ -0,0 +1,86 @@
+// 앱 설정 로드/저장.
+// 설정은 ~/.cdsa_harness/config.json 에 저장한다(실행 폴더에 config.json 이 있으면 우선).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const PROVIDERS = ["openai", "openrouter", "mock"];
+
+export const SUGGESTED_MODELS = {
+  openai: ["gpt-4.1-mini", "gpt-4o-mini", "gpt-4.1"],
+  openrouter: [
+    "openai/gpt-4.1-mini",
+    "anthropic/claude-3.5-sonnet",
+    "google/gemini-2.5-flash",
+  ],
+  mock: ["mock-agent"],
+};
+
+export const APPROVAL_MODES = ["manual", "auto"];
+
+const DEFAULTS = {
+  provider: "mock",
+  api_key: "",
+  model: "mock-agent",
+  workspace: "./workspace",
+  approval_mode: "manual",
+  allow_shell: false,
+  max_steps: 8,
+  temperature: 0.2,
+};
+
+export function configDir() {
+  return path.join(os.homedir(), ".cdsa_harness");
+}
+
+export function configPath() {
+  const local = path.join(process.cwd(), "config.json");
+  if (fs.existsSync(local)) return local;
+  return path.join(configDir(), "config.json");
+}
+
+export class Config {
+  constructor(data = {}) {
+    Object.assign(this, DEFAULTS);
+    for (const key of Object.keys(DEFAULTS)) {
+      if (data[key] !== undefined) this[key] = data[key];
+    }
+  }
+
+  // CLI 도구이므로 작업 폴더 상대경로는 '현재 폴더' 기준으로 해석한다(직관적).
+  workspacePath() {
+    let p = this.workspace || "./workspace";
+    if (!path.isAbsolute(p)) p = path.resolve(process.cwd(), p);
+    return p;
+  }
+
+  isReady() {
+    if (this.provider === "mock") return true;
+    return Boolean((this.api_key || "").trim());
+  }
+
+  toJSON() {
+    const out = {};
+    for (const key of Object.keys(DEFAULTS)) out[key] = this[key];
+    return out;
+  }
+}
+
+export function loadConfig() {
+  const p = configPath();
+  try {
+    if (fs.existsSync(p)) {
+      return new Config(JSON.parse(fs.readFileSync(p, "utf8")));
+    }
+  } catch {
+    // 손상된 설정은 무시하고 기본값
+  }
+  return new Config();
+}
+
+export function saveConfig(cfg) {
+  const p = configPath();
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(cfg.toJSON(), null, 2), "utf8");
+  return p;
+}

package/src/llm.js

@@ -0,0 +1,146 @@
+// LLM 호출 계층. OpenAI / OpenRouter (OpenAI 호환) + 키 없이 체험하는 mock.
+// Node 18+ 내장 fetch 사용 → 외부 의존성 없음.
+
+export class LLMError extends Error {}
+
+const ENDPOINTS = {
+  openai: "https://api.openai.com/v1/chat/completions",
+  openrouter: "https://openrouter.ai/api/v1/chat/completions",
+};
+
+export class LLMClient {
+  constructor({ provider, apiKey, model, temperature = 0.2, timeout = 60000 }) {
+    this.provider = provider;
+    this.apiKey = apiKey;
+    this.model = model;
+    this.temperature = temperature;
+    this.timeout = timeout;
+  }
+
+  async chat(messages, tools) {
+    if (this.provider === "mock") return mockChat(messages);
+    if (!ENDPOINTS[this.provider]) {
+      throw new LLMError(`지원하지 않는 provider 입니다: ${this.provider}`);
+    }
+    return this._httpChat(messages, tools);
+  }
+
+  async _httpChat(messages, tools) {
+    const url = ENDPOINTS[this.provider];
+    const body = { model: this.model, messages, temperature: this.temperature };
+    if (tools && tools.length) {
+      body.tools = tools;
+      body.tool_choice = "auto";
+    }
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+    };
+    if (this.provider === "openrouter") {
+      headers["HTTP-Referer"] = "https://github.com/cdsa-harness";
+      headers["X-Title"] = "CDSA Harness";
+    }
+
+    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);
+    }
+
+    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);
+  }
+}
+
+function parseOpenAiReply(payload) {
+  const msg = payload?.choices?.[0]?.message;
+  if (!msg) {
+    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 || {};
+    } 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 };
+}
+
+// ---------------------------------------------------------------------------
+// Mock 에이전트: 키 없이 Agent Loop 전체를 체험.
+// 히스토리에 쌓인 tool 결과 개수로 '현재 단계'를 판단하는 결정형 에이전트.
+// ---------------------------------------------------------------------------
+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;
+
+  if (phase === 0) {
+    return {
+      content: "작업 폴더 구조부터 확인하겠습니다.",
+      toolCalls: [{ id: "mock_1", name: "list_dir", args: { path: "." } }],
+    };
+  }
+  if (phase === 1) {
+    const target = guessFile(toolMsgs[0].content || "", lastUser);
+    return {
+      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}\` 끝에 메모 한 줄을 추가하는 수정을 제안합니다.`,
+      toolCalls: [{ id: "mock_3", name: "write_file", args: { path: target, content: newContent } }],
+    };
+  }
+  return {
+    content:
+      "완료했습니다. 방금까지의 흐름이 바로 하네스의 Agent Loop 입니다:\n" +
+      "① 작업 폴더 보기 → ② 파일 읽기 → ③ 파일 수정 제안 → ④ 사용자 승인 → ⑤ 저장 → ⑥ 결과를 다시 모델에 전달.\n" +
+      "실제 LLM 을 쓰려면 --provider openai --model ... 와 API Key 를 설정하세요.",
+    toolCalls: [],
+  };
+}
+
+function guessFile(listing, userText) {
+  const files = [];
+  for (const line of listing.split("\n")) {
+    const t = line.trim();
+    if (t.startsWith("[FILE]")) {
+      const rest = t.slice("[FILE]".length).trim();
+      const name = rest.split("  ")[0].trim();
+      if (name) files.push(name);
+    }
+  }
+  for (const name of files) {
+    if (userText.includes(name)) return name;
+  }
+  return files[0] || "notes.txt";
+}

package/src/loop.js

@@ -0,0 +1,223 @@
+// Agent Loop — 하네스의 심장.
+//   입력 → 컨텍스트 구성 → 모델 호출 → 도구 판단 → (수정/셸이면) 승인
+//        → 도구 실행 → 결과를 다시 모델에 전달 → 완료까지 반복
+//
+// UI 를 모른다. 각 단계를 onEvent 로 방출하고, 승인은 approvalCallback 으로 위임한다.
+import fs from "node:fs";
+import path from "node:path";
+
+import { LLMError } from "./llm.js";
+import { MUTATING_TOOLS, TOOL_LABELS, ToolError, toolSchemas } from "./tools.js";
+
+// 단계(Step) 상수
+export const Step = {
+  USER_INPUT: "user_input",
+  BUILD_CONTEXT: "build_context",
+  MODEL_CALL: "model_call",
+  MODEL_REPLY: "model_reply",
+  TOOL_DECISION: "tool_decision",
+  APPROVAL: "approval",
+  TOOL_RUN: "tool_run",
+  TOOL_RESULT: "tool_result",
+  DONE: "done",
+  ERROR: "error",
+};
+
+export const STEP_LABELS = {
+  user_input: "사용자 입력",
+  build_context: "컨텍스트 구성",
+  model_call: "LLM 호출",
+  model_reply: "모델 응답",
+  tool_decision: "도구 판단",
+  approval: "사용자 승인",
+  tool_run: "도구 실행",
+  tool_result: "결과 반영",
+  done: "완료",
+  error: "오류",
+};
+
+const RULES_FILENAMES = ["AGENT.md", "AGENTS.md", "CLAUDE.md", "rules.md", "RULES.md"];
+
+function findRules(workspace) {
+  for (const name of RULES_FILENAMES) {
+    const p = path.join(workspace, name);
+    try {
+      if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+        return { name, text: fs.readFileSync(p, "utf8") };
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return { name: "", text: "" };
+}
+
+export class AgentLoop {
+  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null }) {
+    this.config = config;
+    this.client = client;
+    this.toolbox = toolbox;
+    this.onEvent = onEvent;
+    this.approvalCallback = approvalCallback;
+    this.session = session;
+    this.messages = [];
+  }
+
+  _emit(step, title = "", detail = "", data = {}) {
+    const ev = { step, title, detail, data };
+    if (this.session) this.session.record(ev);
+    this.onEvent(ev);
+  }
+
+  _systemPrompt() {
+    const ws = this.toolbox.workspace;
+    const { name: rulesName, text: rulesText } = findRules(ws);
+    let listing;
+    try {
+      listing = this.toolbox.listDir(".").output;
+    } catch {
+      listing = "(폴더를 읽을 수 없음)";
+    }
+    const toolNames = ["list_dir", "read_file", "write_file"].concat(
+      this.config.allow_shell ? ["run_shell"] : []
+    );
+    const toolsDesc = toolNames.map((n) => `${n}(${TOOL_LABELS[n]})`).join(", ");
+
+    const parts = [
+      "당신은 'CDSA Harness' 안에서 동작하는 소형 코딩 에이전트입니다.",
+      "당신은 직접 파일을 만질 수 없습니다. 반드시 제공된 도구로만 작업 폴더를 다룹니다.",
+      `사용 가능한 도구: ${toolsDesc}.`,
+      "파일을 수정할 때는 write_file 에 '파일 전체 내용'을 담아 호출하세요(부분 패치 아님).",
+      "추측하지 말고, 필요하면 먼저 read_file/list_dir 로 사실을 확인하세요.",
+      "작업이 끝나면 도구를 더 호출하지 말고 한국어로 결과를 요약하세요.",
+      `\n[작업 폴더 루트]\n${ws}`,
+      `\n[현재 폴더 내용]\n${listing}`,
+    ];
+    if (rulesText) parts.push(`\n[규칙 파일 ${rulesName}]\n${rulesText.trim()}`);
+    return parts.join("\n");
+  }
+
+  reset() {
+    this.messages = [{ role: "system", content: this._systemPrompt() }];
+  }
+
+  async run(userInput) {
+    if (this.messages.length === 0) this.reset();
+
+    this._emit(Step.USER_INPUT, "사용자 입력", userInput);
+    this.messages.push({ role: "user", content: userInput });
+
+    this._emit(
+      Step.BUILD_CONTEXT,
+      "컨텍스트 구성",
+      "규칙 파일 + 작업 폴더 내용을 시스템 프롬프트로 묶어 모델에 전달합니다."
+    );
+
+    const tools = toolSchemas(this.config.allow_shell);
+    let finalText = "";
+
+    for (let stepNo = 1; stepNo <= this.config.max_steps; stepNo++) {
+      this._emit(
+        Step.MODEL_CALL,
+        `LLM 호출 (반복 ${stepNo})`,
+        `메시지 ${this.messages.length}개를 모델에 전송합니다.`
+      );
+
+      let reply;
+      try {
+        reply = await this.client.chat(this.messages, tools);
+      } catch (e) {
+        if (e instanceof LLMError) {
+          this._emit(Step.ERROR, "LLM 오류", e.message);
+          return finalText;
+        }
+        throw e;
+      }
+
+      this._emit(Step.MODEL_REPLY, "모델 응답", reply.content || "(텍스트 없음)", {
+        toolCalls: reply.toolCalls.map((tc) => ({ name: tc.name, args: tc.args })),
+      });
+      if (reply.content) finalText = reply.content;
+
+      if (!reply.toolCalls.length) {
+        this._emit(Step.TOOL_DECISION, "도구 판단", "추가 도구 호출이 필요 없습니다. 작업을 마칩니다.");
+        this.messages.push({ role: "assistant", content: reply.content || "" });
+        this._emit(Step.DONE, "완료", reply.content || "");
+        return finalText;
+      }
+
+      const names = reply.toolCalls.map((tc) => `${tc.name}(${TOOL_LABELS[tc.name] || tc.name})`).join(", ");
+      this._emit(Step.TOOL_DECISION, "도구 판단", `모델이 도구 호출을 요청했습니다: ${names}`);
+
+      this.messages.push({
+        role: "assistant",
+        content: reply.content || "",
+        tool_calls: reply.toolCalls.map((tc) => ({
+          id: tc.id,
+          type: "function",
+          function: { name: tc.name, arguments: JSON.stringify(tc.args) },
+        })),
+      });
+
+      for (const tc of reply.toolCalls) {
+        const resultText = await this._handleToolCall(tc);
+        this.messages.push({ role: "tool", tool_call_id: tc.id, content: resultText });
+      }
+    }
+
+    this._emit(Step.DONE, "반복 한도 도달", `max_steps(${this.config.max_steps})에 도달해 종료했습니다.`);
+    return finalText;
+  }
+
+  async _handleToolCall(tc) {
+    const label = TOOL_LABELS[tc.name] || tc.name;
+    const needsApproval = MUTATING_TOOLS.has(tc.name);
+
+    if (needsApproval && this.config.approval_mode === "manual") {
+      const req = this._buildApprovalRequest(tc);
+      this._emit(
+        Step.APPROVAL,
+        `사용자 승인 대기: ${label}`,
+        req.diff || req.command || JSON.stringify(tc.args),
+        { tool: tc.name, path: req.path }
+      );
+      const decision = await this.approvalCallback(req);
+      if (!decision.approved) {
+        this._emit(Step.APPROVAL, `거부됨: ${label}`, decision.reason || "사용자가 거부함");
+        return `사용자가 '${label}' 실행을 거부했습니다. 사유: ${decision.reason || "(없음)"}`;
+      }
+      this._emit(Step.APPROVAL, `승인됨: ${label}`, "사용자가 승인했습니다.");
+    } else if (needsApproval) {
+      this._emit(Step.APPROVAL, `자동 승인: ${label}`, "approval_mode=auto 라 자동 승인되었습니다.");
+    }
+
+    this._emit(Step.TOOL_RUN, `도구 실행: ${label}`, JSON.stringify(tc.args).slice(0, 2000));
+    try {
+      const result = this.toolbox.execute(tc.name, tc.args);
+      this._emit(Step.TOOL_RESULT, `결과 반영: ${label}`, (result.output || "").slice(0, 4000));
+      return result.output;
+    } catch (e) {
+      if (e instanceof ToolError) {
+        this._emit(Step.TOOL_RESULT, `도구 오류: ${label}`, e.message);
+        return `도구 오류: ${e.message}`;
+      }
+      throw e;
+    }
+  }
+
+  _buildApprovalRequest(tc) {
+    if (tc.name === "write_file") {
+      const { path: p, diff } = this.toolbox.previewWrite(tc.args.path || "", tc.args.content || "");
+      return { toolName: "write_file", toolLabel: TOOL_LABELS.write_file, args: tc.args, path: p, diff };
+    }
+    if (tc.name === "run_shell") {
+      return {
+        toolName: "run_shell",
+        toolLabel: TOOL_LABELS.run_shell,
+        args: tc.args,
+        command: tc.args.command || "",
+      };
+    }
+    return { toolName: tc.name, toolLabel: TOOL_LABELS[tc.name] || tc.name, args: tc.args };
+  }
+}

package/src/session.js

@@ -0,0 +1,46 @@
+// 세션 로그(JSONL). 하네스는 "무슨 일이 있었는지"를 남긴다.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function sessionsDir() {
+  const d = path.join(os.homedir(), ".cdsa_harness", "sessions");
+  fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+export class SessionLog {
+  constructor(filePath) {
+    this.path = filePath;
+  }
+
+  static create() {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const log = new SessionLog(path.join(sessionsDir(), `session-${ts}.jsonl`));
+    log._append({ type: "session_start", time: Date.now() });
+    return log;
+  }
+
+  _append(obj) {
+    try {
+      fs.appendFileSync(this.path, JSON.stringify(obj) + "\n", "utf8");
+    } catch {
+      // 로그 실패가 앱을 멈추게 하지 않는다.
+    }
+  }
+
+  record(ev) {
+    this._append({
+      type: "event",
+      time: Date.now(),
+      step: ev.step,
+      title: ev.title,
+      detail: ev.detail,
+      data: ev.data || {},
+    });
+  }
+
+  close() {
+    this._append({ type: "session_end", time: Date.now() });
+  }
+}

package/src/tools.js

@@ -0,0 +1,220 @@
+// 하네스가 제공하는 도구들. 모두 작업 폴더(workspace) 안으로만 접근 제한(sandbox).
+// LLM 은 생각만 하고, 실제 파일 조작/명령 실행은 전부 여기서 이뤄진다.
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export const TOOL_LABELS = {
+  list_dir: "폴더 보기",
+  read_file: "파일 읽기",
+  write_file: "파일 수정",
+  run_shell: "셸 실행",
+};
+
+// 사용자 승인이 필요한(환경을 바꾸는) 도구
+export const MUTATING_TOOLS = new Set(["write_file", "run_shell"]);
+
+export class ToolError extends Error {}
+
+// 간단한 LCS 기반 unified diff (교육용 표시). +추가 / -삭제 / (공백)유지
+export function diffLines(oldText, newText) {
+  const a = oldText ? oldText.split("\n") : [];
+  const b = newText ? newText.split("\n") : [];
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      dp[i][j] =
+        a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < m && j < n) {
+    if (a[i] === b[j]) {
+      out.push(" " + a[i]);
+      i++;
+      j++;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      out.push("-" + a[i]);
+      i++;
+    } else {
+      out.push("+" + b[j]);
+      j++;
+    }
+  }
+  while (i < m) out.push("-" + a[i++]);
+  while (j < n) out.push("+" + b[j++]);
+  return out;
+}
+
+export class Toolbox {
+  constructor(workspace, allowShell = false) {
+    this.workspace = path.resolve(workspace);
+    fs.mkdirSync(this.workspace, { recursive: true });
+    this.allowShell = allowShell;
+  }
+
+  _resolve(rel) {
+    rel = (rel || ".").trim();
+    const candidate = path.resolve(this.workspace, rel);
+    const root = this.workspace + path.sep;
+    if (candidate !== this.workspace && !candidate.startsWith(root)) {
+      throw new ToolError(
+        `작업 폴더 밖 경로에는 접근할 수 없습니다: ${rel} (허용 루트: ${this.workspace})`
+      );
+    }
+    return candidate;
+  }
+
+  rel(p) {
+    const r = path.relative(this.workspace, p);
+    return r === "" ? "." : r;
+  }
+
+  listDir(rel = ".") {
+    const target = this._resolve(rel);
+    if (!fs.existsSync(target)) throw new ToolError(`경로가 없습니다: ${rel}`);
+    const stat = fs.statSync(target);
+    if (stat.isFile()) return { ok: true, output: `(파일) ${this.rel(target)}` };
+    const names = fs.readdirSync(target).sort();
+    if (names.length === 0) return { ok: true, output: "(빈 폴더)" };
+    const lines = names.map((name) => {
+      const full = path.join(target, name);
+      const s = fs.statSync(full);
+      const kind = s.isDirectory() ? "DIR " : "FILE";
+      const size = s.isDirectory() ? "" : `  ${s.size}B`;
+      return `[${kind}] ${this.rel(full)}${size}`;
+    });
+    return { ok: true, output: lines.join("\n") };
+  }
+
+  readFile(rel) {
+    const target = this._resolve(rel);
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+      throw new ToolError(`파일이 없습니다: ${rel}`);
+    }
+    let text = fs.readFileSync(target, "utf8");
+    if (text.length > 20000) text = text.slice(0, 20000) + "\n... (이후 생략)";
+    return { ok: true, output: text, detail: text };
+  }
+
+  // write_file 의 '제안' 미리보기. 실제로 쓰지는 않는다.
+  previewWrite(rel, content) {
+    const target = this._resolve(rel);
+    let old = "";
+    if (fs.existsSync(target) && fs.statSync(target).isFile()) {
+      old = fs.readFileSync(target, "utf8");
+    }
+    const diff = diffLines(old, content || "").join("\n") || "(내용 변화 없음)";
+    return { path: this.rel(target), diff };
+  }
+
+  writeFile(rel, content) {
+    const target = this._resolve(rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const existed = fs.existsSync(target);
+    fs.writeFileSync(target, content || "", "utf8");
+    const verb = existed ? "수정" : "생성";
+    return {
+      ok: true,
+      output: `${this.rel(target)} 파일을 ${verb}했습니다 (${(content || "").length}자).`,
+      detail: content || "",
+    };
+  }
+
+  runShell(command) {
+    if (!this.allowShell) {
+      throw new ToolError("셸 실행이 설정에서 비활성화되어 있습니다(allow_shell=false).");
+    }
+    if (!command || !command.trim()) throw new ToolError("실행할 명령이 비어 있습니다.");
+    let out;
+    let code = 0;
+    try {
+      out = execSync(command, {
+        cwd: this.workspace,
+        encoding: "utf8",
+        timeout: 30000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (e) {
+      code = e.status ?? 1;
+      out = (e.stdout || "") + (e.stderr ? "\n[stderr]\n" + e.stderr : "");
+    }
+    out = (out || "").trim() || "(출력 없음)";
+    if (out.length > 8000) out = out.slice(0, 8000) + "\n... (이후 생략)";
+    return { ok: code === 0, output: `$ ${command}\n(exit=${code})\n${out}` };
+  }
+
+  execute(name, args = {}) {
+    if (name === "list_dir") return this.listDir(args.path || ".");
+    if (name === "read_file") return this.readFile(args.path || "");
+    if (name === "write_file") return this.writeFile(args.path || "", args.content || "");
+    if (name === "run_shell") return this.runShell(args.command || "");
+    throw new ToolError(`알 수 없는 도구입니다: ${name}`);
+  }
+}
+
+export function toolSchemas(allowShell = false) {
+  const schemas = [
+    {
+      type: "function",
+      function: {
+        name: "list_dir",
+        description: "작업 폴더(workspace) 안의 폴더 내용을 나열한다.",
+        parameters: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "작업 폴더 기준 상대 경로. 루트는 '.'" },
+          },
+          required: [],
+        },
+      },
+    },
+    {
+      type: "function",
+      function: {
+        name: "read_file",
+        description: "작업 폴더 안의 텍스트 파일을 읽어 내용을 반환한다.",
+        parameters: {
+          type: "object",
+          properties: { path: { type: "string", description: "읽을 파일의 상대 경로" } },
+          required: ["path"],
+        },
+      },
+    },
+    {
+      type: "function",
+      function: {
+        name: "write_file",
+        description:
+          "작업 폴더 안의 파일을 새 내용으로 만들거나 덮어쓴다. 전체 파일 내용을 content 로 전달. 사용자 승인 후 적용된다.",
+        parameters: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "저장할 파일의 상대 경로" },
+            content: { type: "string", description: "파일 전체 내용" },
+          },
+          required: ["path", "content"],
+        },
+      },
+    },
+  ];
+  if (allowShell) {
+    schemas.push({
+      type: "function",
+      function: {
+        name: "run_shell",
+        description: "작업 폴더에서 셸 명령을 실행한다. 사용자 승인 후 실행된다.",
+        parameters: {
+          type: "object",
+          properties: { command: { type: "string", description: "실행할 명령" } },
+          required: ["command"],
+        },
+      },
+    });
+  }
+  return schemas;
+}

package/src/ui.js

@@ -0,0 +1,84 @@
+// 터미널 출력 헬퍼: ANSI 색, 박스 패널, diff 렌더. (외부 의존성 없음)
+
+const ESC = "\x1b[";
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+function wrap(open, close) {
+  return (s) => (useColor ? `${ESC}${open}m${s}${ESC}${close}m` : String(s));
+}
+
+export const c = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  italic: wrap(3, 23),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  magenta: wrap(35, 39),
+  cyan: wrap(36, 39),
+  grey: wrap(90, 39),
+};
+
+// 24bit truecolor (그라데이션 배너용). hex "#rrggbb"
+export function hex(s, hexColor) {
+  if (!useColor) return String(s);
+  const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hexColor);
+  if (!m) return String(s);
+  const [r, g, b] = [m[1], m[2], m[3]].map((x) => parseInt(x, 16));
+  return `${ESC}38;2;${r};${g};${b}m${s}${ESC}39m`;
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export function stripAnsi(s) {
+  return String(s).replace(ANSI_RE, "");
+}
+// 화면상 표시 폭(한글=2칸) 계산
+export function visibleWidth(s) {
+  const plain = stripAnsi(s);
+  let w = 0;
+  for (const ch of plain) {
+    const code = ch.codePointAt(0);
+    w += code > 0x1100 && isWide(code) ? 2 : 1;
+  }
+  return w;
+}
+function isWide(code) {
+  return (
+    (code >= 0x1100 && code <= 0x115f) || // 한글 자모
+    (code >= 0x2e80 && code <= 0xa4cf) || // CJK
+    (code >= 0xac00 && code <= 0xd7a3) || // 한글 음절
+    (code >= 0xf900 && code <= 0xfaff) ||
+    (code >= 0xff00 && code <= 0xff60) ||
+    (code >= 0x1f300 && code <= 0x1faff) // 이모지(대략)
+  );
+}
+
+// 둥근 박스 패널. lines: 문자열 배열(ANSI 포함 가능)
+export function panel(lines, { title = "", color = "cyan" } = {}) {
+  const paint = c[color] || ((x) => x);
+  const body = Array.isArray(lines) ? lines : String(lines).split("\n");
+  const contentWidth = Math.max(
+    visibleWidth(title) + 2,
+    ...body.map((l) => visibleWidth(l)),
+    10
+  );
+  const top = paint("╭─ ") + paint(c.bold(title)) + paint(" " + "─".repeat(Math.max(0, contentWidth - visibleWidth(title) - 2)) + "╮");
+  const bottom = paint("╰" + "─".repeat(contentWidth + 2) + "╯");
+  const mid = body.map((l) => {
+    const pad = " ".repeat(Math.max(0, contentWidth - visibleWidth(l)));
+    return paint("│ ") + l + pad + paint(" │");
+  });
+  const head = title ? top : paint("╭" + "─".repeat(contentWidth + 2) + "╮");
+  return [head, ...mid, bottom].join("\n");
+}
+
+// diff 문자열을 색으로 렌더 (+초록 / -빨강 / 그외 흐림)
+export function renderDiff(diff) {
+  return diff.split("\n").map((line) => {
+    if (line.startsWith("+")) return c.green(line);
+    if (line.startsWith("-")) return c.red(line);
+    if (line.startsWith("@")) return c.cyan(line);
+    return c.dim(line);
+  });
+}

package/workspace/AGENT.md

@@ -0,0 +1,17 @@
+# 작업 규칙 (AGENT.md)
+
+이 파일은 CDSA Harness 가 매 호출마다 읽어 모델의 시스템 프롬프트에 합치는 **규칙 파일**입니다.
+Claude Code 의 `CLAUDE.md`, Codex 의 `AGENTS.md` 와 같은 역할을 합니다.
+
+## 이 폴더에서의 규칙
+
+- 모든 답변과 파일 내용은 한국어로 작성한다.
+- 파일을 수정할 때는 기존 내용을 함부로 지우지 말고, 필요한 부분만 신중히 바꾼다.
+- 새 메모는 `notes.txt` 에 추가하는 것을 기본으로 한다.
+- 확실하지 않으면 먼저 파일을 읽어 사실을 확인한 뒤 작업한다.
+
+## 실험 아이디어
+
+1. "notes.txt 맨 아래에 오늘 할 일 3가지를 추가해줘"
+2. "이 폴더에 어떤 파일이 있는지 알려줘"
+3. "hello.js 라는 파일을 만들어 'Hello, Harness!' 를 출력하게 해줘"

package/workspace/notes.txt

@@ -0,0 +1,4 @@
+CDSA Harness 데모용 메모 파일입니다.
+
+이 파일은 에이전트가 read_file 로 읽고, write_file 로 수정 '제안'을 만들 때
+사용하는 연습용 텍스트입니다. 수정 제안은 승인 단계에서 diff 로 확인할 수 있습니다.