cdsa-harness 0.1.1 → 0.4.0

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

@@ -7,7 +7,7 @@ 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";
+import { TOOL_LABELS, ToolError, toolSchemas } from "./tools.js";
 
 // 단계(Step) 상수
 export const Step = {
@@ -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) {
@@ -113,14 +145,27 @@ export class AgentLoop {
       "규칙 파일 + 작업 폴더 내용을 시스템 프롬프트로 묶어 모델에 전달합니다."
     );
 
-    const tools = toolSchemas(this.config.allow_shell);
+    const tools = toolSchemas(this.config.allow_shell, this.toolbox.plugins);
+    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})에 도달해 종료했습니다.`);
@@ -170,8 +227,8 @@ export class AgentLoop {
   }
 
   async _handleToolCall(tc) {
-    const label = TOOL_LABELS[tc.name] || tc.name;
-    const needsApproval = MUTATING_TOOLS.has(tc.name);
+    const label = this.toolbox.label ? this.toolbox.label(tc.name) : TOOL_LABELS[tc.name] || tc.name;
+    const needsApproval = this.toolbox.isMutating(tc.name);
 
     if (needsApproval && this.config.approval_mode === "manual") {
       const req = this._buildApprovalRequest(tc);
@@ -193,7 +250,7 @@ export class AgentLoop {
 
     this._emit(Step.TOOL_RUN, `도구 실행: ${label}`, JSON.stringify(tc.args).slice(0, 2000));
     try {
-      const result = this.toolbox.execute(tc.name, tc.args);
+      const result = await this.toolbox.execute(tc.name, tc.args);
       this._emit(Step.TOOL_RESULT, `결과 반영: ${label}`, (result.output || "").slice(0, 4000));
       return result.output;
     } catch (e) {

package/src/plugins.js

@@ -0,0 +1,191 @@
+// 플러그인 시스템 — OpenCode 스타일 확장성.
+// `.cdsa/plugins/` (작업 폴더) 와 `~/.cdsa_harness/plugins/` (전역) 의 .js/.mjs 파일을
+// 불러와 '새 도구'로 등록한다. 각 파일은 아래 형태의 객체를 default export 한다:
+//
+//   export default {
+//     name: "word_count",
+//     description: "텍스트 파일의 글자/줄 수를 센다",
+//     parameters: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+//     mutating: false,                  // true 면 실행 전 사용자 승인 필요
+//     async handler(args, ctx) { ... }  // ctx = { workspace }
+//   }
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export function pluginDirs(workspace) {
+  return [
+    path.join(os.homedir(), ".cdsa_harness", "plugins"),
+    path.join(workspace, ".cdsa", "plugins"),
+  ];
+}
+
+export async function loadPlugins(workspace) {
+  const plugins = [];
+  for (const dir of pluginDirs(workspace)) {
+    let files = [];
+    try {
+      if (!fs.existsSync(dir)) continue;
+      files = fs.readdirSync(dir).filter((f) => /\.(mjs|js)$/.test(f)).sort();
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const full = path.join(dir, f);
+      try {
+        const mod = await import(pathToFileURL(full).href);
+        const def = mod.default || mod.plugin || mod;
+        if (!def || !def.name || typeof def.handler !== "function") {
+          plugins.push({ error: `${f}: name/handler 가 없습니다` });
+          continue;
+        }
+        plugins.push({
+          name: def.name,
+          description: def.description || "",
+          parameters: def.parameters || { type: "object", properties: {} },
+          mutating: Boolean(def.mutating),
+          handler: def.handler,
+          source: full,
+        });
+      } catch (e) {
+        plugins.push({ error: `${f}: ${e.message}` });
+      }
+    }
+  }
+  return plugins;
+}
+
+// ---------------------------------------------------------------------------
+// npm 패키지로 설치한 플러그인 자동 발견.
+//   - 이름이 `cdsa-harness-plugin-*` (또는 `@scope/cdsa-harness-plugin-*`)
+//   - 또는 package.json 에 keywords: ["cdsa-harness-plugin"] / "cdsaHarness" 필드
+//   인 패키지를 node_modules 에서 찾아 불러온다.
+// 패키지는 다음 중 하나를 default export:
+//   · 플러그인 def 객체  · def 배열  · { tools:[...], skills:[{name,description,body}] }
+// ---------------------------------------------------------------------------
+function isPluginPackage(pkgJson, name) {
+  if (/^(@[^/]+\/)?cdsa-harness-plugin-/.test(name)) return true;
+  if (pkgJson && pkgJson.cdsaHarness) return true;
+  const kw = (pkgJson && pkgJson.keywords) || [];
+  return Array.isArray(kw) && kw.includes("cdsa-harness-plugin");
+}
+
+async function importPackage(nmDir, name) {
+  const req = createRequire(path.join(nmDir, "__cdsa_resolve__.js"));
+  const entry = req.resolve(name);
+  return import(pathToFileURL(entry).href);
+}
+
+function normalizeModule(mod, source) {
+  const out = { plugins: [], skills: [] };
+  const def = (mod && (mod.default ?? mod)) || null;
+  if (!def) return out;
+  let tools = [];
+  let skills = [];
+  if (Array.isArray(def)) tools = def;
+  else if (def.tools || def.skills) {
+    tools = def.tools || [];
+    skills = def.skills || [];
+  } else if (def.name && typeof def.handler === "function") tools = [def];
+  for (const t of tools) {
+    if (t && t.name && typeof t.handler === "function") {
+      out.plugins.push({
+        name: t.name,
+        description: t.description || "",
+        parameters: t.parameters || { type: "object", properties: {} },
+        mutating: Boolean(t.mutating),
+        handler: t.handler,
+        source,
+      });
+    }
+  }
+  for (const s of skills) if (s && s.name && s.body) out.skills.push(s);
+  return out;
+}
+
+// 한 node_modules 디렉터리를 훑어 플러그인 패키지를 모은다.
+export async function scanNodeModules(nmDir) {
+  const result = { plugins: [], skills: [], errors: [] };
+  let entries = [];
+  try {
+    if (!fs.existsSync(nmDir)) return result;
+    entries = fs.readdirSync(nmDir);
+  } catch {
+    return result;
+  }
+  const names = [];
+  for (const e of entries) {
+    if (e.startsWith(".")) continue;
+    if (e.startsWith("@")) {
+      try {
+        for (const sub of fs.readdirSync(path.join(nmDir, e))) names.push(`${e}/${sub}`);
+      } catch {
+        /* ignore */
+      }
+    } else names.push(e);
+  }
+  for (const name of names) {
+    let pkgJson = {};
+    try {
+      pkgJson = JSON.parse(fs.readFileSync(path.join(nmDir, name, "package.json"), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!isPluginPackage(pkgJson, name)) continue;
+    try {
+      const mod = await importPackage(nmDir, name);
+      const norm = normalizeModule(mod, name);
+      result.plugins.push(...norm.plugins);
+      result.skills.push(...norm.skills);
+    } catch (e) {
+      result.errors.push(`${name}: ${e.message}`);
+    }
+  }
+  return result;
+}
+
+// cwd 의 node_modules + cdsa-harness 자신의 node_modules(전역 설치 시 형제 패키지) 를 훑고,
+// config.plugins 에 적힌 패키지는 이름 규칙과 무관하게 강제로 불러온다.
+export async function discoverNpmExtensions(cwd, explicitNames = []) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const nmDirs = [];
+  const add = (d) => {
+    const r = path.resolve(d);
+    if (!nmDirs.includes(r)) nmDirs.push(r);
+  };
+  add(path.join(cwd, "node_modules"));
+  add(path.resolve(here, "..", "..")); // .../node_modules/cdsa-harness/src → .../node_modules
+
+  const merged = { plugins: [], skills: [], errors: [] };
+  for (const nm of nmDirs) {
+    const r = await scanNodeModules(nm);
+    merged.plugins.push(...r.plugins);
+    merged.skills.push(...r.skills);
+    merged.errors.push(...r.errors);
+  }
+  for (const name of explicitNames) {
+    if (merged.plugins.some((p) => p.source === name)) continue;
+    let loaded = false;
+    for (const nm of nmDirs) {
+      try {
+        const norm = normalizeModule(await importPackage(nm, name), name);
+        if (norm.plugins.length || norm.skills.length) {
+          merged.plugins.push(...norm.plugins);
+          merged.skills.push(...norm.skills);
+          loaded = true;
+          break;
+        }
+      } catch {
+        /* try next dir */
+      }
+    }
+    if (!loaded) merged.errors.push(`${name}: 불러올 수 없음(설치되어 있나요? npm i ${name})`);
+  }
+  // 이름 중복 제거(먼저 발견된 것 우선)
+  const byName = new Map();
+  for (const p of merged.plugins) if (!byName.has(p.name)) byName.set(p.name, p);
+  merged.plugins = [...byName.values()];
+  return merged;
+}