cdsa-harness 0.5.1 → 0.6.0

package/README.md

@@ -9,6 +9,7 @@
 ```
 
 - **의존성 0개** — Node 18+ 내장 기능만(`fetch`/`readline`/`node:test`)
+- **실시간 스트리밍** — 모델 응답이 토큰 단위로 흐름(`/stream` 토글, OpenAI·Claude·mock)
 - **실제 LLM 연결** — OpenAI · Anthropic(Claude) · OpenRouter, 또는 키 없이 `mock`
 - **교육 모드** — 매 반복마다 모델에 보내는 메시지 구성·추정 토큰·시스템 프롬프트, 실제 토큰 사용량/응답시간까지 그대로 표시
 - **MCP 클라이언트** — Claude Code·Cursor 등과 **공용 표준**. MCP 서버를 그대로 붙여 도구로 사용
@@ -53,6 +54,7 @@ export OPENROUTER_API_KEY=sk-or-...
 | `/provider <이름>` | openai · anthropic · openrouter · mock 전환 |
 | `/model <이름>` | 모델 변경 |
 | `/teach` | 교육 모드 켜기/끄기 |
+| `/stream` | 실시간 스트리밍 출력 켜기/끄기 |
 | `/context` | 지금 모델에 보내는 컨텍스트 들여다보기 |
 | `/reset` | 대화/컨텍스트 초기화 |
 | `/config` | 현재 설정값 |

package/package.json

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

package/src/cli.js

@@ -46,15 +46,24 @@ function clip(s, n) {
 }
 
 // cfg.teach_mode 를 실행 중 토글할 수 있으므로 closure 로 cfg 를 잡아둔다.
-function makePrinter(cfg) {
+// stream.active 는 onToken 과 공유하는 스트리밍 상태.
+function makePrinter(cfg, stream) {
   return (ev) => {
-    if (cfg.teach_mode) return printTeach(ev);
-    return printCompact(ev);
+    if (cfg.teach_mode) return printTeach(ev, stream);
+    return printCompact(ev, stream);
   };
 }
 
+function replyMetaLine(d) {
+  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`);
+  return meta.length ? meta.join(" · ") : "";
+}
+
 // ---- 교육(teach) 렌더: 내부 과정을 패널로 펼쳐 보여준다 ----
-function printTeach(ev) {
+function printTeach(ev, stream) {
   const d = ev.data || {};
   switch (ev.step) {
     case Step.USER_INPUT:
@@ -85,16 +94,26 @@ function printTeach(ev) {
     }
 
     case Step.MODEL_REPLY: {
+      // 스트리밍으로 이미 본문이 출력된 경우: 줄바꿈 후 메타/도구호출만 덧붙인다.
+      if (d.streamed) {
+        if (stream && stream.active) {
+          process.stdout.write("\n");
+          stream.active = false;
+        }
+        for (const tc of d.toolCalls || []) {
+          console.log(c.yellow(`  ↳ 도구 호출 요청: ${c.bold(tc.name)}(${clip(JSON.stringify(tc.args), 200)})`));
+        }
+        const meta = replyMetaLine(d);
+        if (meta) console.log(c.grey("  ─ " + meta));
+        return;
+      }
       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(" · ")));
+      const meta = replyMetaLine(d);
+      if (meta) lines.push(c.grey("─ " + meta));
       else lines.push(c.dim("(mock: 토큰/지연 측정 없음)"));
       console.log(panel(lines.length ? lines : ["(빈 응답)"], { title: "🤖 ③ 모델 응답 (원본 판단)", color: "green" }));
       return;
@@ -132,11 +151,17 @@ function printTeach(ev) {
 }
 
 // ---- 간결(compact) 렌더: 한 줄 위주 ----
-function printCompact(ev) {
+function printCompact(ev, stream) {
   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) {
+    const d = ev.data || {};
+    if (d.streamed) {
+      if (stream && stream.active) { process.stdout.write("\n"); stream.active = false; }
+      for (const tc of d.toolCalls || []) console.log(c.yellow(`  ↳ ${tc.name}(${clip(JSON.stringify(tc.args), 120)})`));
+      return;
+    }
     if (ev.detail && ev.detail !== "(텍스트 없음)") console.log(panel(ev.detail.split("\n"), { title: "🤖 모델", color: "green" }));
     return;
   }
@@ -189,6 +214,7 @@ function printIntro(cfg) {
     ["model", cfg.model],
     ["API 키", keySource],
     ["교육 모드", cfg.teach_mode ? c.green("ON (과정 펼쳐보기)") : "OFF"],
+    ["스트리밍", cfg.stream ? c.green("ON (실시간)") : "OFF"],
     ["작업 폴더", cfg.workspacePath()],
     ["승인 모드", cfg.approval_mode],
     ["셸 실행", cfg.allow_shell ? "허용" : "차단"],
@@ -213,6 +239,7 @@ function printHelp() {
         `  ${c.cyan("/provider")} <openai|anthropic|openrouter|mock> 제공자 변경`,
         `  ${c.cyan("/model")} <이름>   모델 변경`,
         `  ${c.cyan("/teach")}    교육 모드 켜기/끄기(내부 과정 펼쳐보기)`,
+        `  ${c.cyan("/stream")}   실시간 스트리밍 출력 켜기/끄기`,
         `  ${c.cyan("/context")}  지금 모델에 보내는 컨텍스트 들여다보기`,
         `  ${c.cyan("/skills")}   스킬 목록(.cdsa/skills 의 /명령들)`,
         `  ${c.cyan("/plugins")}  플러그인 목록(파일·npm 추가 도구)`,
@@ -304,6 +331,7 @@ function parseArgs(argv) {
     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 === "--no-stream") out.noStream = 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];
@@ -324,6 +352,7 @@ export async function main(argv = []) {
         "  --workspace <폴더경로>\n" +
         "  --setup                대화형 연결 설정 실행\n" +
         "  --no-teach             교육 모드 끄고 간결하게\n" +
+        "  --no-stream            실시간 스트리밍 끄기\n" +
         "  --auto                 승인 자동(approval_mode=auto)\n" +
         "  -h, --help             도움말\n\n" +
         "API 키는 환경변수로도 인식됩니다: OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY\n"
@@ -355,6 +384,7 @@ export async function main(argv = []) {
   if (args.workspace) cfg.workspace = args.workspace;
   if (args.auto) cfg.approval_mode = "auto";
   if (args.noTeach) cfg.teach_mode = false;
+  if (args.noStream) cfg.stream = false;
 
   const rl = readline.createInterface({ input: stdin, output: stdout });
   let session = null;
@@ -418,13 +448,23 @@ export async function main(argv = []) {
   }
 
   session = SessionLog.create();
+  // 스트리밍: 토큰이 도착하는 대로 실시간 출력(첫 토큰에 헤더 1회).
+  const stream = { active: false };
+  const onToken = (chunk) => {
+    if (!stream.active) {
+      process.stdout.write("\n" + c.green("🤖 ③ 모델 응답 (스트리밍)") + "\n");
+      stream.active = true;
+    }
+    process.stdout.write(c.green(chunk));
+  };
   const loop = new AgentLoop({
     config: cfg,
     client: makeClient(cfg),
     toolbox,
-    onEvent: makePrinter(cfg),
+    onEvent: makePrinter(cfg, stream),
     approvalCallback: makeApproval(ask),
     session,
+    onToken,
   });
   loop.reset();
 
@@ -447,6 +487,11 @@ export async function main(argv = []) {
       console.log(c.green(`교육 모드 ${cfg.teach_mode ? "ON" : "OFF"}.`));
       continue;
     }
+    if (low === "/stream") {
+      cfg.stream = !cfg.stream;
+      console.log(c.green(`스트리밍 ${cfg.stream ? "ON (실시간 출력)" : "OFF"}.`));
+      continue;
+    }
     if (low === "/setup" || low === "/login") {
       await runSetup(ask, cfg);
       loop.client = makeClient(cfg);

package/src/config.js

@@ -38,6 +38,7 @@ const DEFAULTS = {
   temperature: 0.2,
   max_tokens: 1024,
   teach_mode: true,
+  stream: true, // 모델 응답을 실시간(토큰 단위)으로 출력
   plugins: [], // 추가로 불러올 npm 플러그인 패키지 이름(이름 규칙과 무관하게 강제 로드)
   mcpServers: {}, // MCP 서버 설정 (Claude Code/Cursor 와 동일한 형식)
 };

package/src/llm.js

@@ -23,13 +23,43 @@ export class LLMClient {
     this.timeout = timeout;
   }
 
-  async chat(messages, tools) {
-    if (this.provider === "mock") return mockChat(messages);
-    if (this.provider === "anthropic") return this._anthropicChat(messages, tools);
-    if (ENDPOINTS[this.provider]) return this._openaiChat(messages, tools);
+  // onToken(chunk) 를 주면 텍스트가 도착하는 대로 콜백한다(스트리밍).
+  async chat(messages, tools, onToken = null) {
+    if (this.provider === "mock") {
+      const r = mockChat(messages);
+      if (onToken && r.content) await streamText(r.content, onToken);
+      return r;
+    }
+    if (this.provider === "anthropic") {
+      return onToken ? this._anthropicStream(messages, tools, onToken) : this._anthropicChat(messages, tools);
+    }
+    if (ENDPOINTS[this.provider]) {
+      return onToken ? this._openaiStream(messages, tools, onToken) : this._openaiChat(messages, tools);
+    }
     throw new LLMError(`지원하지 않는 provider 입니다: ${this.provider}`);
   }
 
+  // 스트리밍용: 응답 객체(본문 스트림)를 그대로 받는다.
+  async _openStream(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) {
+      clearTimeout(timer);
+      throw new LLMError(`네트워크 오류: ${e.message}`);
+    }
+    if (!res.ok) {
+      clearTimeout(timer);
+      const text = await res.text().catch(() => "");
+      throw new LLMError(httpErrorMessage(res.status, text || res.statusText));
+    }
+    return { res, started, timer, bodyBytes: Buffer.byteLength(json, "utf8") };
+  }
+
   async _post(url, headers, body) {
     const json = JSON.stringify(body);
     const ctrl = new AbortController();
@@ -46,16 +76,7 @@ export class LLMClient {
     const latencyMs = Date.now() - started;
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      let msg = `API 오류 ${res.status}: ${trim(text) || res.statusText}`;
-      if (res.status === 404) {
-        msg += "\n  ↳ 모델 이름을 확인하세요. /model 로 변경 가능. " +
-          "OpenRouter 는 'provider/model' 형식이어야 합니다 (예: openai/gpt-4o-mini, anthropic/claude-3.7-sonnet).";
-      } else if (res.status === 401 || res.status === 403) {
-        msg += "\n  ↳ API 키가 잘못되었거나 권한이 없어요. /setup 으로 다시 연결하세요.";
-      } else if (res.status === 429) {
-        msg += "\n  ↳ 요청이 너무 많거나 크레딧이 부족할 수 있어요(잠시 후 재시도).";
-      }
-      throw new LLMError(msg);
+      throw new LLMError(httpErrorMessage(res.status, text || res.statusText));
     }
     return { payload: await res.json(), latencyMs, bodyBytes: Buffer.byteLength(json, "utf8") };
   }
@@ -103,6 +124,87 @@ export class LLMClient {
     };
   }
 
+  // --- OpenAI/OpenRouter 스트리밍 ---
+  async _openaiStream(messages, tools, onToken) {
+    const url = ENDPOINTS[this.provider];
+    const body = { model: this.model, messages, temperature: this.temperature, stream: true, stream_options: { include_usage: true } };
+    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/cdsassj00/miniharness";
+      headers["X-Title"] = "CDSA Harness";
+    }
+    const { res, started, timer, bodyBytes } = await this._openStream(url, headers, body);
+    let content = "";
+    const tcMap = new Map(); // index -> {id,name,args}
+    let usage = null;
+    try {
+      await readSSE(res, (data) => {
+        if (data === "[DONE]") return;
+        let json;
+        try { json = JSON.parse(data); } catch { return; }
+        if (json.usage) usage = { input: json.usage.prompt_tokens ?? null, output: json.usage.completion_tokens ?? null, total: json.usage.total_tokens ?? null };
+        const delta = json.choices?.[0]?.delta;
+        if (!delta) return;
+        if (delta.content) { content += delta.content; onToken(delta.content); }
+        for (const tc of delta.tool_calls || []) {
+          const i = tc.index ?? 0;
+          const cur = tcMap.get(i) || { id: tc.id || `call_${i}`, name: "", args: "" };
+          if (tc.id) cur.id = tc.id;
+          if (tc.function?.name) cur.name += tc.function.name;
+          if (tc.function?.arguments) cur.args += tc.function.arguments;
+          tcMap.set(i, cur);
+        }
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const toolCalls = [...tcMap.values()].map((t) => ({ id: t.id, name: t.name, args: safeParse(t.args) }));
+    return { content: content || null, toolCalls, usage, latencyMs: Date.now() - started, request: this._meta(url, tools, bodyBytes) };
+  }
+
+  // --- Anthropic 스트리밍 ---
+  async _anthropicStream(messages, tools, onToken) {
+    const url = ENDPOINTS.anthropic;
+    const body = toAnthropicBody(messages, tools, this.model, this.temperature, this.maxTokens);
+    body.stream = true;
+    const headers = { "x-api-key": this.apiKey, "anthropic-version": "2023-06-01", "Content-Type": "application/json" };
+    const { res, started, timer, bodyBytes } = await this._openStream(url, headers, body);
+    let content = "";
+    const blocks = new Map(); // index -> {type,name,id,json}
+    let usage = { input: null, output: null, total: 0 };
+    try {
+      await readSSE(res, (data) => {
+        let ev;
+        try { ev = JSON.parse(data); } catch { return; }
+        if (ev.type === "message_start" && ev.message?.usage) usage.input = ev.message.usage.input_tokens ?? null;
+        else if (ev.type === "content_block_start") {
+          const b = ev.content_block || {};
+          blocks.set(ev.index, { type: b.type, name: b.name, id: b.id, json: "" });
+        } else if (ev.type === "content_block_delta") {
+          const d = ev.delta || {};
+          if (d.type === "text_delta") { content += d.text; onToken(d.text); }
+          else if (d.type === "input_json_delta") {
+            const cur = blocks.get(ev.index);
+            if (cur) cur.json += d.partial_json || "";
+          }
+        } else if (ev.type === "message_delta" && ev.usage) {
+          usage.output = ev.usage.output_tokens ?? usage.output;
+        }
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    usage.total = (usage.input || 0) + (usage.output || 0);
+    const toolCalls = [...blocks.values()]
+      .filter((b) => b.type === "tool_use")
+      .map((b) => ({ id: b.id, name: b.name, args: safeParse(b.json) }));
+    return { content: content || null, toolCalls, usage, latencyMs: Date.now() - started, request: this._meta(url, tools, bodyBytes) };
+  }
+
   _meta(endpoint, tools, bodyBytes) {
     return {
       provider: this.provider,
@@ -120,6 +222,51 @@ function trim(s) {
   return s.length > 400 ? s.slice(0, 400) + " …" : s;
 }
 
+function safeParse(jsonStr) {
+  try {
+    return JSON.parse(jsonStr || "{}");
+  } catch {
+    return { _raw: jsonStr };
+  }
+}
+
+function httpErrorMessage(status, text) {
+  let msg = `API 오류 ${status}: ${trim(text)}`;
+  if (status === 404) {
+    msg += "\n  ↳ 모델 이름을 확인하세요. /model 로 변경 가능. " +
+      "OpenRouter 는 'provider/model' 형식이어야 합니다 (예: openai/gpt-4o-mini, anthropic/claude-3.7-sonnet).";
+  } else if (status === 401 || status === 403) {
+    msg += "\n  ↳ API 키가 잘못되었거나 권한이 없어요. /setup 으로 다시 연결하세요.";
+  } else if (status === 429) {
+    msg += "\n  ↳ 요청이 너무 많거나 크레딧이 부족할 수 있어요(잠시 후 재시도).";
+  }
+  return msg;
+}
+
+// SSE(data: ...) 본문 스트림을 줄 단위로 콜백. onEvent(dataString) 호출(‘[DONE]’ 포함).
+async function readSSE(res, onEvent) {
+  let buf = "";
+  for await (const chunk of res.body) {
+    buf += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    let nl;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (line.startsWith("data:")) onEvent(line.slice(5).trim());
+    }
+  }
+  if (buf.trim().startsWith("data:")) onEvent(buf.trim().slice(5).trim());
+}
+
+// mock/공통: 텍스트를 토큰처럼 쪼개 콜백(TTY 면 살짝 지연해 흐르는 효과).
+async function streamText(text, onToken) {
+  const parts = String(text).match(/\S+\s*|\s+/g) || [String(text)];
+  for (const p of parts) {
+    onToken(p);
+    if (process.stdout.isTTY) await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
 function parseOpenAiReply(payload) {
   const msg = payload?.choices?.[0]?.message;
   if (!msg) {

package/src/loop.js

@@ -79,13 +79,14 @@ function findRules(workspace) {
 }
 
 export class AgentLoop {
-  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null }) {
+  constructor({ config, client, toolbox, onEvent, approvalCallback, session = null, onToken = null }) {
     this.config = config;
     this.client = client;
     this.toolbox = toolbox;
     this.onEvent = onEvent;
     this.approvalCallback = approvalCallback;
     this.session = session;
+    this.onToken = onToken; // 스트리밍 토큰 콜백(있으면 실시간 출력)
     this.messages = [];
   }
 
@@ -168,9 +169,10 @@ export class AgentLoop {
         }
       );
 
+      const streaming = Boolean(this.onToken && this.config.stream);
       let reply;
       try {
-        reply = await this.client.chat(this.messages, tools);
+        reply = await this.client.chat(this.messages, tools, streaming ? this.onToken : null);
       } catch (e) {
         if (e instanceof LLMError) {
           this._emit(Step.ERROR, "LLM 오류", e.message);
@@ -180,11 +182,13 @@ export class AgentLoop {
       }
 
       // ③ 모델의 원본 판단 + 실측 메타(응답시간/토큰/요청크기)를 드러낸다.
+      // streamed=true 면 텍스트는 이미 실시간 출력됨 → UI 는 메타만 덧붙인다.
       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,
+        streamed: streaming && Boolean(reply.content),
       });
       if (reply.content) finalText = reply.content;