agentlas 1.0.59 → 1.0.61

package/engine/hub/install.cjs

@@ -27,9 +27,13 @@ const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
 const { callHubTool } = require("../cloud/hub-client.cjs");
 
 // ── 패키지 상한/식별 상수 (서버 package-contract와 동일) ──
-const CLOUD_MAX_TOTAL_BYTES = 3 * 1024 * 1024;
-const CLOUD_MAX_FILE_BYTES = 512 * 1024;
-const CLOUD_MAX_FILES = 400;
+// 상한은 정본 하나(upload-scan-catalog.json)에서 생성돼 내려온다. 여기서 다시
+// 적으면 서버·엔진·데스크탑과 어긋나고, 어긋난 쪽은 파일 이름도 없는 코드로 거절한다.
+const {
+  PACKAGE_MAX_TOTAL_BYTES: CLOUD_MAX_TOTAL_BYTES,
+  PACKAGE_MAX_FILE_BYTES: CLOUD_MAX_FILE_BYTES,
+  PACKAGE_MAX_FILES: CLOUD_MAX_FILES,
+} = require("../cloud-assets/upload-scan-catalog.generated.cjs");
 const CLOUD_PACKAGE_HASH_V1 = "path-sha256-v1";
 const CLOUD_PACKAGE_HASH_V2 = "path-sha256-executable-v2";
 const CLOUD_RESTORE_MARKER_PATH = ".agentlas-cloud-package.json";

package/engine/hub/plugins.cjs

@@ -15,6 +15,9 @@
  *    런타임이 통째로 죽는다(Runtime Doctor가 반복해서 잡던 사고 계열).
  */
 const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
 const { callHubTool, fetchHub, parseHubJson, webBaseUrl } = require("../cloud/hub-client.cjs");
 
 // 레포/홈페이지 HTML 페이지는 문서지 MCP 연결이 아니다. 이 URL들을 transport:"http"로
@@ -193,6 +196,163 @@ function installPluginMcpRows(db, rows) {
   return { installed, reused, needsApproval };
 }
 
+// ── 스킬 번들 설치 (플러그인 = MCP와 별개의 능력 패키지, 오너 결정 2026-08-20) ──
+//
+// manifest.skills 행이 files[]에 실콘텐츠를 실으면 ~/.agentlas/plugins/<slug>/ 아래에
+// 파일로 착지시키고 plugin.json 마커(schema agentlas.local-plugin/v1)를 남긴다.
+// 이 규약은 데스크탑 electron/mcp-tools/hub-plugin-bridge.ts(installSkillBundle)와
+// Agentlas-OS agentlas_cloud/plugin_discovery.py 스캔이 공유한다 — mcp_servers 등록이
+// 아니라 파일시스템이 채널 간 공유 지점이다.
+
+const PLUGIN_SKILL_SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const PLUGIN_SKILL_FILE_MAX_BYTES = 512 * 1024;
+
+/** 세 채널이 공유하는 로컬 플러그인 저장소 루트. homeDir 주입은 테스트 격리용. */
+function agentlasPluginsDir({ homeDir } = {}) {
+  return path.join(homeDir || os.homedir(), ".agentlas", "plugins");
+}
+
+/** 스킬 파일 상대 경로 검증 — 절대경로·상위 탈출·널바이트·백슬래시 거부 (데스크탑 동형). */
+function pluginSkillSafeRelativePath(value) {
+  if (typeof value !== "string" || !value || value.length > 260) return false;
+  if (value.includes("\0") || value.includes("\\")) return false;
+  if (value.startsWith("/") || value.endsWith("/")) return false;
+  return value.split("/").every((part) => part.length > 0 && part !== "." && part !== ".." && !part.startsWith("~"));
+}
+
+/**
+ * manifest.skills 를 설치 계획으로 정규화: 실콘텐츠가 실린 스킬과 정직하게 거른 항목 분리.
+ * 이름뿐인 레거시 행({name}만)은 refused가 아니라 declaredOnly로 남긴다 — 결함이 아니라
+ * 과거 스키마의 정상 모양이다.
+ */
+function planPluginSkillInstall(slug, manifest) {
+  const entries = Array.isArray(manifest?.skills) ? manifest.skills : [];
+  const skills = [];
+  const declaredOnly = [];
+  const refused = [];
+  for (const entry of entries) {
+    const name = typeof entry?.name === "string" ? entry.name.trim() : "";
+    if (!name) continue;
+    const rawFiles = Array.isArray(entry?.files) ? entry.files : [];
+    if (rawFiles.length === 0) {
+      declaredOnly.push(name);
+      continue;
+    }
+    if (!PLUGIN_SKILL_SLUG_RE.test(name)) {
+      refused.push({ name, reason: "invalid skill name" });
+      continue;
+    }
+    const files = [];
+    let bad = null;
+    for (const file of rawFiles) {
+      const filePath = typeof file?.path === "string" ? file.path.trim() : "";
+      const content = typeof file?.content === "string" ? file.content : "";
+      if (!pluginSkillSafeRelativePath(filePath)) { bad = `unsafe file path "${filePath}"`; break; }
+      if (!content.trim()) { bad = `empty content for ${filePath}`; break; }
+      if (Buffer.byteLength(content, "utf8") > PLUGIN_SKILL_FILE_MAX_BYTES) { bad = `${filePath} exceeds the file size cap`; break; }
+      const sha256 = typeof file?.sha256 === "string" && /^[0-9a-f]{64}$/i.test(file.sha256)
+        ? file.sha256.toLowerCase()
+        : null;
+      files.push({ path: filePath, content, sha256 });
+    }
+    if (bad) { refused.push({ name, reason: bad }); continue; }
+    skills.push({ name, description: typeof entry?.description === "string" ? entry.description : null, files });
+  }
+  return { skills, declaredOnly, refused };
+}
+
+/**
+ * 계획된 스킬들을 ~/.agentlas/plugins/<slug>/skills/<name>/ 에 쓴다.
+ *
+ * 무결성: 행이 sha256을 선언하면 쓰기 전에 검증하고, 불일치 스킬은 설치하지 않는다.
+ * 해시와 콘텐츠가 같은 매니페스트 응답으로 오므로 이 검증은 전송 무결성이지 발행자
+ * 서명이 아니다 — 마커의 source.manifestUrl이 출처 기록이다(정직한 한계).
+ */
+function installPluginSkills(slug, plan, { homeDir, manifestUrl, meta } = {}) {
+  if (!PLUGIN_SKILL_SLUG_RE.test(String(slug || ""))) {
+    return { dir: "", installed: [], failed: [{ name: String(slug || ""), reason: "invalid plugin slug" }], verified: false };
+  }
+  const pluginDir = path.join(agentlasPluginsDir({ homeDir }), slug);
+  const installed = [];
+  const failed = [];
+  const markerSkills = [];
+  let allDeclared = true;
+  for (const skill of plan.skills || []) {
+    const written = [];
+    let mismatch = null;
+    for (const file of skill.files) {
+      const actual = crypto.createHash("sha256").update(file.content, "utf8").digest("hex");
+      if (file.sha256 && file.sha256 !== actual) { mismatch = `sha256 mismatch for ${file.path}`; break; }
+      if (!file.sha256) allDeclared = false;
+      written.push({ path: file.path, sha256: actual, verified: Boolean(file.sha256) });
+    }
+    if (mismatch) { failed.push({ name: skill.name, reason: mismatch }); continue; }
+    try {
+      const skillDir = path.join(pluginDir, "skills", skill.name);
+      for (const file of skill.files) {
+        const target = path.join(skillDir, file.path);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, file.content, "utf8");
+      }
+      installed.push(skill.name);
+      markerSkills.push({ name: skill.name, files: written });
+    } catch (e) {
+      failed.push({ name: skill.name, reason: String((e && e.message) || e).slice(0, 160) });
+    }
+  }
+  const verified = installed.length > 0 && allDeclared;
+  if (installed.length > 0) {
+    // 마커는 마지막에 쓴다 — 마커가 있으면 스킬 파일도 있다는 뜻이어야 한다.
+    const marker = {
+      schema: "agentlas.local-plugin/v1",
+      slug,
+      name: (meta && meta.name) || slug,
+      family: (meta && meta.family) || null,
+      version: (meta && meta.version) || null,
+      installedAt: new Date().toISOString(),
+      installedBy: "agentlas-terminal",
+      source: { manifestUrl: manifestUrl || null, contentVerification: verified ? "manifest-sha256" : "none" },
+      skills: markerSkills,
+    };
+    try {
+      fs.mkdirSync(pluginDir, { recursive: true });
+      fs.writeFileSync(path.join(pluginDir, "plugin.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+    } catch (e) {
+      failed.push({ name: "plugin.json", reason: String((e && e.message) || e).slice(0, 160) });
+    }
+  }
+  return { dir: pluginDir, installed, failed, verified };
+}
+
+/** ~/.agentlas/plugins/<slug>/plugin.json 마커들을 읽는다 — list의 설치 여부 표시용. */
+function listInstalledLocalPlugins({ homeDir } = {}) {
+  const root = agentlasPluginsDir({ homeDir });
+  let names;
+  try {
+    names = fs.readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (name.startsWith(".")) continue;
+    try {
+      const marker = JSON.parse(fs.readFileSync(path.join(root, name, "plugin.json"), "utf8"));
+      out.push({
+        slug: String(marker.slug || name),
+        name: String(marker.name || name),
+        installedAt: marker.installedAt || null,
+        installedBy: marker.installedBy || null,
+        skills: Array.isArray(marker.skills) ? marker.skills.map((s) => String(s?.name || "")).filter(Boolean) : [],
+        dir: path.join(root, name),
+      });
+    } catch {
+      // 마커 없는 디렉터리는 다른 도구의 산출물일 수 있다 — 조용히 건너뛴다.
+    }
+  }
+  return out;
+}
+
 /** Hub 플러그인 카탈로그 목록 (marketplace.list_plugins). 실패는 그대로 throw — 폴백 카탈로그 금지. */
 async function listHubPlugins({ callTool } = {}) {
   const call = callTool || callHubTool;
@@ -210,4 +370,9 @@ module.exports = {
   planPluginMcpInstall,
   installPluginMcpRows,
   listHubPlugins,
+  agentlasPluginsDir,
+  pluginSkillSafeRelativePath,
+  planPluginSkillInstall,
+  installPluginSkills,
+  listInstalledLocalPlugins,
 };

package/engine/mcp/consent.cjs

@@ -36,6 +36,82 @@ const {
 const MCP_CONSENT_STATE_SCHEMA = "agentlas.terminal-mcp-consents.v1";
 const MCP_CONSENT_RECEIPT_SCHEMA = "agentlas.terminal-mcp-consent.v1";
 
+/*
+ * ── 통합 능력 승인(데스크탑 capability_grants)과의 합류 ───────────────────────
+ *
+ * 이 파일의 v1 계약(지문 일치 영수증)은 그대로다. 그 **위에** 공유 능력 규칙이 얹힌다:
+ *   · 규칙이 deny 면 영수증이 있어도 붙이지 않는다(영구 거부는 어디서도 뚫리지 않는다).
+ *   · 규칙이 allow 면 다시 묻지 않는다(데스크탑에서 누른 "항상 허용"이 여기서도 항상).
+ *   · 규칙이 없으면 종전대로 1회 동의 프롬프트가 돈다.
+ * 터미널에서 "항상"을 고르면 같은 표에 써서 데스크탑에도 반영된다.
+ *
+ * MCP 서버를 붙이는 것은 외부 프로세스를 띄우는 일이라 능력 클래스는 execute 다.
+ * 규칙 키는 `tool:mcp:<catalogId>` + 패턴 없음(그 서버 전체) — 데스크탑의 도구 규칙과
+ * 같은 표·같은 판정 함수를 쓴다.
+ */
+const MCP_CAPABILITY_CLASS = "execute";
+
+function mcpCapabilityQuery(catalogId) {
+  return { capability: MCP_CAPABILITY_CLASS, tool: `mcp:${String(catalogId)}`, detail: String(catalogId) };
+}
+
+function capabilityGrantsModule() {
+  return require("../core/capability-grants.cjs");
+}
+
+/**
+ * 계획의 후보들을 공유 능력 규칙으로 미리 가른다.
+ * @returns {{available:string[], preApproved:string[], denied:string[],
+ *            grantsAvailable:boolean, fallbackReason:string|null}}
+ *   grantsAvailable=false 는 표가 없는 구버전 공유 DB — 사유를 담아 돌려주고 기존 동작으로 간다.
+ */
+function partitionMcpConsentByCapabilityGrants(db, catalogIds) {
+  const ids = [...new Set((catalogIds || []).map((id) => String(id)).filter(Boolean))];
+  const grants = capabilityGrantsModule();
+  if (!db || !grants.capabilityGrantsAvailable(db)) {
+    return {
+      available: ids,
+      preApproved: [],
+      denied: [],
+      grantsAvailable: false,
+      fallbackReason: db ? grants.UNAVAILABLE_REASON : null,
+    };
+  }
+  const available = [];
+  const preApproved = [];
+  const denied = [];
+  let fallbackReason = null;
+  for (const id of ids) {
+    let ruling;
+    try {
+      ruling = grants.readCapabilityDecision(db, mcpCapabilityQuery(id));
+    } catch (error) {
+      fallbackReason = `capability_grants read failed: ${(error && error.message) || error}`;
+      available.push(id);
+      continue;
+    }
+    if (!ruling.available) {
+      fallbackReason = fallbackReason || ruling.reason;
+      available.push(id);
+    } else if (ruling.decision === "deny") denied.push(id);
+    else if (ruling.decision === "allow") preApproved.push(id);
+    else available.push(id);
+  }
+  return { available, preApproved, denied, grantsAvailable: true, fallbackReason };
+}
+
+/** 터미널에서 고른 "항상"을 데스크탑과 같은 표에 남긴다. 표가 없으면 정직한 실패. */
+function rememberMcpCapabilityGrant(db, catalogId, decision = "allow") {
+  const grants = capabilityGrantsModule();
+  return grants.recordCapabilityGrant(db, {
+    capability: `tool:mcp:${String(catalogId)}`,
+    pattern: null,
+    decision: decision === "deny" ? "deny" : "allow",
+    scope: "global",
+    source: "terminal-mcp-consent",
+  });
+}
+
 function mcpConsentStatePath(userDataDir) {
   return path.join(userDataDir, "terminal", "mcp-consents-v1.json");
 }
@@ -113,10 +189,16 @@ function readConsentedSystemMcpServers(db, options = {}) {
   let state;
   try { state = loadMcpConsentState(options.userDataDir); }
   catch { return []; }
+  // 영구 거부(deny)는 옛 동의 영수증을 이긴다 — 규칙이 영수증보다 위다.
+  const partition = partitionMcpConsentByCapabilityGrants(
+    db,
+    state.receipts.map((receipt) => receipt.catalogId),
+  );
+  const denied = new Set(partition.denied);
   const servers = [];
   const seen = new Set();
   for (const receipt of state.receipts) {
-    if (seen.has(receipt.catalogId)) continue;
+    if (seen.has(receipt.catalogId) || denied.has(receipt.catalogId)) continue;
     let row = null;
     try {
       row = db.prepare(
@@ -134,26 +216,66 @@ function readConsentedSystemMcpServers(db, options = {}) {
   return servers;
 }
 
-function normalizeConsentAnswer(answer, availableIds) {
+/**
+ * 답 한 줄을 해석한다. `always`/`a` 는 "전부 붙이고 **다시는 묻지 마라**" — 그 선택만
+ * 공유 능력 규칙(capability_grants)에 영구 기록된다. y/n/ids 는 종전 그대로 1회 한정이다.
+ */
+function parseConsentAnswer(answer, availableIds) {
   const text = String(answer || "").trim();
-  if (/^(?:y|yes|all|전체)$/i.test(text)) return [...availableIds];
-  if (!text || /^(?:n|no|none|없이|아니)$/i.test(text)) return [];
-  const requested = parseIdList(text);
+  if (/^(?:a|always|항상)$/i.test(text)) return { ids: [...availableIds], always: true };
+  if (/^(?:y|yes|all|전체)$/i.test(text)) return { ids: [...availableIds], always: false };
+  if (!text || /^(?:n|no|none|없이|아니)$/i.test(text)) return { ids: [], always: false };
+  const requested = parseIdList(text.replace(/^always\s+/i, ""));
   const allowed = new Set(availableIds);
-  return requested.filter((id) => allowed.has(id));
+  return { ids: requested.filter((id) => allowed.has(id)), always: /^always\s+/i.test(text) };
+}
+
+function normalizeConsentAnswer(answer, availableIds) {
+  return parseConsentAnswer(answer, availableIds).ids;
 }
 
 function askMcpConsentOnce(plan, options = {}) {
   const input = options.input || process.stdin;
   const output = options.output || process.stderr;
-  // TTY가 아니면(파이프/자동화) 묻지 않고 빈 승인 — 조용한 전체 승인 금지.
-  if (!input.isTTY || !output.isTTY || !plan.availableCatalogIds.length) return Promise.resolve([]);
+  /*
+   * 공유 능력 규칙을 먼저 본다(오너 결정 2026-08-20):
+   *   deny → 후보에서 제외하고 묻지 않는다.  allow → 묻지 않고 통과.
+   * 남은 후보만 사람에게 묻는다. 규칙이 없으면 목록이 그대로라 종전 동작과 동일하다.
+   */
+  const partition = partitionMcpConsentByCapabilityGrants(options.db, plan.availableCatalogIds || []);
+  const askable = partition.available;
+  const preApproved = partition.preApproved;
+  const notify = typeof options.onNotice === "function" ? options.onNotice : null;
+  if (notify) {
+    if (partition.denied.length) {
+      notify(`MCP blocked by a shared capability rule (Desktop/Terminal): ${partition.denied.join(", ")}`);
+    }
+    if (preApproved.length) {
+      notify(`MCP already allowed always (shared capability rule): ${preApproved.join(", ")}`);
+    }
+    if (partition.fallbackReason) notify(partition.fallbackReason);
+  }
+  // TTY가 아니면(파이프/자동화) 묻지 않는다 — 조용한 전체 승인 금지.
+  // 이미 "항상 허용"된 것만은 사람에게 물을 필요가 없으므로 그대로 통과시킨다.
+  if (!input.isTTY || !output.isTTY || !askable.length) return Promise.resolve([...preApproved]);
   const rl = readline.createInterface({ input, output, terminal: true });
   return new Promise((resolve) => {
-    rl.question("Attach the available MCP recommendations? [y=all / n=none / comma-separated ids] ", (answer) => {
-      rl.close();
-      resolve(normalizeConsentAnswer(answer, plan.availableCatalogIds));
-    });
+    rl.question(
+      "Attach the available MCP recommendations? [y=once / a=always / n=none / comma-separated ids] ",
+      (answer) => {
+        rl.close();
+        const parsed = parseConsentAnswer(answer, askable);
+        if (parsed.always && parsed.ids.length && options.db) {
+          for (const id of parsed.ids) {
+            const written = rememberMcpCapabilityGrant(options.db, id, "allow");
+            if (!written.ok && notify) notify(`"always" was not persisted for ${id}: ${written.reason}`);
+          }
+        } else if (parsed.always && parsed.ids.length && notify) {
+          notify("\"always\" was not persisted: no shared database handle was given to the consent prompt.");
+        }
+        resolve([...new Set([...preApproved, ...parsed.ids])]);
+      },
+    );
   });
 }
 
@@ -284,6 +406,12 @@ module.exports = {
   persistMcpConsentReceipts,
   readConsentedSystemMcpServers,
   normalizeConsentAnswer,
+  parseConsentAnswer,
   askMcpConsentOnce,
   resolveApprovedMcpRuntimeAllowlist,
+  // 공유 능력 승인(데스크탑 capability_grants) 합류 표면.
+  MCP_CAPABILITY_CLASS,
+  mcpCapabilityQuery,
+  partitionMcpConsentByCapabilityGrants,
+  rememberMcpCapabilityGrant,
 };

package/engine/mcp/index.cjs

@@ -27,6 +27,7 @@ module.exports = {
   probeSystemMcpServerConnection: probe.probeSystemMcpServerConnection,
   // plan — 요구사항 해소 + 빌드 플랜 + 빌더 지시문
   resolveMcpRequirement: plan.resolveMcpRequirement,
+  inferRequirements: plan.inferRequirements,
   buildMcpPlan: plan.buildMcpPlan,
   renderMcpPlan: plan.renderMcpPlan,
   fitApprovedMcpIds: plan.fitApprovedMcpIds,

package/engine/mcp/plan.cjs

@@ -39,7 +39,10 @@ function syntheticRequirement(catalogId, required, priority) {
   };
 }
 
-// 이름 휴리스틱은 "추천 후보 회수"만 담당한다 — 최종 선택/attach 권한이 아니다.
+// 이름 휴리스틱은 "회수 힌트"로만 강등되었다(2026-08-20) — 판정기에 참고로 전달될 뿐,
+// 요구사항을 만들거나 선택 게이트로 동작하지 않는다. 데스크탑 need-resolver.ts가 폐기한
+// 것과 같은 계약: 선택은 판정기(engine/agentlas-judgment.cjs) 경유, 판정 불가면
+// 요구사항 없음(중립)이다.
 const HEURISTIC_GROUPS = [
   [/(browser|playwright|chrome|web)/i, /(?:browser|website|web page|웹|브라우저|사이트|페이지|로그인)/i],
   [/(github|gitlab|source)/i, /(?:github|gitlab|repository|pull request|issue|깃허브|레포|저장소)/i],
@@ -50,15 +53,56 @@ const HEURISTIC_GROUPS = [
   [/(search|research)/i, /(?:search|research|lookup|검색|리서치|조사)/i],
 ];
 
-function inferRequirements(request, inventory) {
-  const text = String(request || "");
-  const results = [];
+/** 회수 힌트: 판정기 guidance에만 실린다. 선택·attach 권한이 없다. */
+function lexicalRequirementHintIds(request, inventory) {
+  const text = String(request || "").toLowerCase();
+  const ids = [];
   for (const item of inventory) {
-    const direct = text.toLowerCase().includes(item.catalogId.toLowerCase()) || text.toLowerCase().includes(item.name.toLowerCase());
+    const direct = text.includes(String(item.catalogId).toLowerCase()) || text.includes(String(item.name || "").toLowerCase());
     const heuristic = HEURISTIC_GROUPS.some(([nameRe, taskRe]) => nameRe.test(`${item.catalogId} ${item.name}`) && taskRe.test(text));
-    if (direct || heuristic) results.push(syntheticRequirement(item.catalogId, false, results.length + 100));
+    if (direct || heuristic) ids.push(item.catalogId);
   }
-  return results.slice(0, 8);
+  return ids.slice(0, 8);
+}
+
+/**
+ * 요청 텍스트에서 MCP 요구사항을 추론한다 — 판정기(연결된 모델) 경유.
+ * 정규식/이름 매칭은 힌트로만 전달되며, 판정이 없으면 빈 목록(중립)이다.
+ * 반환: syntheticRequirement[] (전부 optional/recommended 등급).
+ */
+async function inferRequirements(request, inventory, options = {}) {
+  const text = String(request || "").trim();
+  const items = Array.isArray(inventory) ? inventory : [];
+  if (!text || !items.length) return [];
+  const judgment = options.judgment || require("../agentlas-judgment.cjs");
+  if (!judgment.hasJudgmentRunner()) return [];
+  const hintIds = lexicalRequirementHintIds(text, items);
+  const shelf = items
+    .map((item) => `- ${item.catalogId}: ${item.name || item.catalogId}`)
+    .join("\n");
+  const verdict = await judgment.judgeLabels({
+    kind: "terminal-mcp-need",
+    question:
+      "Which of the available MCP tools does this build request genuinely require in order to complete? Judge what the task actually does, not which words it contains.",
+    labels: items.map((item) => String(item.catalogId)),
+    input: `TASK:\n${text.slice(0, 4000)}\n\nAVAILABLE TOOLS:\n${shelf}`,
+    guidance: [
+      "Name a tool ONLY when the task cannot be completed without it.",
+      "Mentioning a topic is not a need: a task that says 'research'/'조사' in passing does not need a web-search tool.",
+      hintIds.length
+        ? `A deterministic name-heuristic suggested [${hintIds.join(", ")}] — treat that as a hint, never a gate.`
+        : "",
+      "An empty list is a valid and often correct answer. Err toward fewer tools.",
+    ].filter(Boolean).join(" "),
+    signal: options.signal,
+    timeoutMs: options.timeoutMs,
+  });
+  if (verdict.source !== "llm") return []; // 판정 불가 → 요구사항 없음(중립)
+  const known = new Set(items.map((item) => String(item.catalogId)));
+  return verdict.labels
+    .filter((catalogId) => known.has(catalogId))
+    .slice(0, 8)
+    .map((catalogId, index) => syntheticRequirement(catalogId, false, index + 100));
 }
 
 function indexInventory(inventory) {
@@ -119,7 +163,17 @@ function buildMcpPlan(options) {
     assertId(catalogId, "--recommend-mcp");
     if (!known.has(catalogId)) { requirements.push(syntheticRequirement(catalogId, false, 500)); known.add(catalogId); }
   }
-  if (!requirements.length) requirements.push(...inferRequirements(options.request, inventory));
+  // 2026-08-20: 휴리스틱 자동 추론이 여기서 직접 요구사항을 만들던 게이트를 제거.
+  // 추론은 비동기 판정(inferRequirements — 판정기 경유, 판정 불가면 빈 목록)을
+  // 호출자가 먼저 끝내고 그 결과를 넘긴다. 없으면 요구사항 없음(중립).
+  if (!requirements.length && Array.isArray(options.inferredRequirements)) {
+    for (const requirement of options.inferredRequirements.slice(0, 8)) {
+      if (requirement && requirement.catalogId && !known.has(requirement.catalogId)) {
+        requirements.push(requirement);
+        known.add(requirement.catalogId);
+      }
+    }
+  }
   const entries = requirements
     .map((requirement) => {
       const resolution = resolveMcpRequirement(requirement, inventoryById);
@@ -275,6 +329,7 @@ function renderBuildMcpResult(plan, approvedIds, runtimeAllowlist = null) {
 module.exports = {
   MAX_BUILD_DIRECTIVE_CHARS,
   syntheticRequirement,
+  lexicalRequirementHintIds,
   inferRequirements,
   indexInventory,
   resolveMcpRequirement,

package/engine/project/career-graph.cjs

@@ -173,7 +173,7 @@ function registerCareerGraphSourceCli(paths, source, kind, scope, cwd, lang) {
       ];
 }
 
-function runCareerGraphCli(args, opts) {
+async function runCareerGraphCli(args, opts) {
   opts = opts || {};
   const ko = opts.lang === "ko";
   const cwd = path.resolve(opts.cwd || process.cwd());
@@ -203,10 +203,8 @@ function runCareerGraphCli(args, opts) {
   }
   const directCareerCommand = ["open", "add"].includes(String(sub));
   if (!directCareerCommand) {
-    const parsed = parseOntologyNaturalArgsCli(normalizedArgs.join(" "), cwd);
-    if (!parsed) throw new Error(ko
-      ? "사용법: /career-graph status|list|open|add <경로>"
-      : "usage: /career-graph status|list|open|add <path>");
+    // 자연어는 판정기 경유로 액션을 정한다. 판정 불가면 ["help"](사용법 안내).
+    const parsed = await parseOntologyNaturalArgsCli(normalizedArgs.join(" "), cwd);
     return runCareerGraphCli(parsed, opts);
   }
   const paths = ensureCareerGraphCli(projectPath, opts.lang);
@@ -226,12 +224,9 @@ function runCareerGraphCli(args, opts) {
     : "usage: /career-graph status|list|open|add <path>");
 }
 
-function runCareerGraphNaturalCli(text, opts) {
+async function runCareerGraphNaturalCli(text, opts) {
   const cwd = path.resolve((opts && opts.cwd) || process.cwd());
-  const parsed = parseOntologyNaturalArgsCli(text, cwd);
-  if (!parsed) throw new Error((opts && opts.lang) === "ko"
-    ? "사용법: /career-graph status|list|open|add <경로>"
-    : "usage: /career-graph status|list|open|add <path>");
+  const parsed = await parseOntologyNaturalArgsCli(text, cwd);
   return runCareerGraphCli(parsed, { ...(opts || {}), cwd });
 }