deel-local-cli 1.2.0 → 1.4.1

package/bin/deel.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 // deel 진입점. 외부 의존성 없음 — Node 표준 기능만 씁니다.
 import { join } from 'node:path';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { c, say, mark, rule } from '../src/ui/ansi.js';
 import { runSetup, runDiagnose, showStatus, banner } from '../src/setup.js';
 import { chatLoop } from '../src/repl.js';
 import { runOnce } from '../src/oneshot.js';
 import { packSelf, audit, reviewSheet } from '../src/pack/selfpack.js';
+import { sbom, 심사명세, 명세요약 } from '../src/pack/sbom.js';
 import { runScan } from '../src/backend/scanui.js';
 import { closeConnections } from '../src/backend/http.js';
 import { parseSize } from '../src/backend/ctxsize.js';
 import { runSessions } from '../src/agent/sessionui.js';
+import { acp } from '../src/acp/serve.js';
 
 const MIN_NODE = 20;
 
@@ -47,7 +49,8 @@ function runPack(flags) {
   say(`  ${c.gray('네트워크 호출')}   ${a.calls.net.length}곳 ${c.gray('(설정한 주소로만)')}`);
   say(`  ${c.gray('포트 열기')}       ${a.calls.listen.length === 0 ? c.green('없음') : c.red(a.calls.listen.length + '곳')}`);
   say('');
-  say(`  ${c.gray('안에 반입심사서.txt 가 같이 들어 있습니다 — 그대로 제출하시면 됩니다.')}`);
+  say(`  ${c.gray('안에 반입심사서.txt · sbom.cdx.json · 심사명세.json 이 같이 들어 있습니다.')}`);
+  say(`  ${c.gray('사람이 읽을 것 한 장, 스캐너에 넣을 것 두 장입니다 — 그대로 제출하시면 됩니다.')}`);
   say(`  ${c.gray('내용만 먼저 보시려면')} ${c.cyan('deel audit')}`);
   say('');
   return 0;
@@ -60,6 +63,43 @@ function runAudit() {
   return 0;
 }
 
+/*
+ * 기계가 읽는 심사 서류만 따로 뽑기.
+ *
+ * 반입 심사는 사람만 보는 절차가 아니다. 보안팀은 SBOM 을 스캐너에 먹이고,
+ * 운영팀은 감사기록 사양을 보고 수집 규칙을 짠다. zip 을 통째로 만들지 않고
+ * 그 두 장만 필요할 때가 실제로 더 잦다 — 심사 양식에 첨부하는 자리다.
+ */
+function runSbom(flags) {
+  const a = audit();
+  const at = new Date();
+  const 어느것 = String(flags.only ?? '').toLowerCase();
+  const 낼것 = 어느것 === 'sbom' ? sbom(a, { at })
+    : 어느것 === '명세' || 어느것 === 'spec' ? 심사명세(a, { at })
+      : { sbom: sbom(a, { at }), 심사명세: 심사명세(a, { at }) };
+  const 글 = JSON.stringify(낼것, null, 2);
+
+  if (flags.out) {
+    const 자리 = String(flags.out);
+    writeFileSync(자리, 글, 'utf8');
+    say('');
+    say(`  ${mark.ok} ${c.bold(자리)}`);
+    say('');
+    for (const 줄 of 명세요약(심사명세(a, { at })).split('\n')) say(`  ${c.gray(줄)}`);
+    say('');
+    return 0;
+  }
+
+  /*
+   * 표준출력으로 그냥 흘린다.
+   *
+   * `deel sbom > sbom.json` 이나 `deel sbom | jq` 로 쓰는 자리다. 여기에
+   * 안내 글을 섞으면 그 파이프가 통째로 깨진다 — say() 를 쓰지 않는 이유다.
+   */
+  process.stdout.write(글 + '\n');
+  return 0;
+}
+
 // 값을 안 받는 깃발. 뒤에 오는 낱말을 제 값으로 삼키지 않게 여기 적어 둔다.
 //
 // 실제로 이랬다 — deel run --json "검사 돌려줘" 를 쳤더니 --json 이 뒤의 말을
@@ -107,10 +147,19 @@ function help() {
   say(`    ${c.gray('--key <키>')}          키가 필요한 로컬 서버일 때`);
   say(`    ${c.gray('대화 중')} ${c.cyan('/model')} ${c.gray('로 서버·모델을 골라 바꿉니다.')}`);
   say('');
+  say(`  ${c.bold('에디터 안에서 쓰기')} ${c.gray('— Zed · JetBrains · Neovim · Emacs')}`);
+  say('');
+  say(`    ${c.cyan('deel acp')}                    에디터가 띄우는 자리 (ACP). 사람이 직접 칠 명령은 아닙니다`);
+  say(`    ${c.gray('에디터 설정에 이 명령을 적어 두면 그 안에서 deel 이 돕니다.')}`);
+  say(`    ${c.gray('승인 창·모드 고르개·고친 파일 링크가 에디터 것으로 그려집니다.')}`);
+  say('');
   say(`  ${c.bold('사내 반입')}`);
   say('');
-  say(`    ${c.cyan('deel audit')}                  의존성·네트워크 호출 자리 심사서 보기`);
-  say(`    ${c.cyan('deel pack')}                   심사서 + 소스를 zip 하나로 묶기`);
+  say(`    ${c.cyan('deel audit')}                  의존성·네트워크 호출 자리 심사서 ${c.gray('(사람이 읽는 글)')}`);
+  say(`    ${c.cyan('deel sbom')}                   SBOM·통신 목록·감사 사양 ${c.gray('(기계가 읽는 JSON)')}`);
+  say(`    ${c.gray('--out <파일>')}       파일로 적기. 안 주면 표준출력 — ${c.cyan('deel sbom | jq')}`);
+  say(`    ${c.gray('--only sbom|명세')}   한 장만`);
+  say(`    ${c.cyan('deel pack')}                   위 셋 + 소스를 zip 하나로 묶기`);
   say(`    ${c.gray('--out <파일>')}       묶음 파일 이름. 기본은 deel-반입.zip`);
   say('');
   say(`  ${c.bold('대화 시작 옵션')}`);
@@ -213,6 +262,24 @@ async function main() {
         continue: flags.continue === true || flags.c === true,
         sessionId: typeof flags.resume === 'string' ? flags.resume : (flags.resume === true ? null : undefined),
       });
+    /*
+     * 에디터가 자식 프로세스로 띄우는 자리 (ACP).
+     *
+     * 사람이 직접 칠 명령이 아니다. 쳐도 안 죽고 그냥 기다리는데, 그건 규격이
+     * 그렇게 정한 것이라 맞다 — 에디터가 표준입력으로 말을 걸어 주기를 기다린다.
+     * 왜 아무 반응이 없는지는 표준오류에 적어 둔다.
+     */
+    case 'acp':
+      return acp({
+        root: flags.root ? String(flags.root) : undefined,
+        mode: flags.mode ? String(flags.mode) : undefined,
+        work: flags.work ? String(flags.work) : undefined,
+        ctx: flags.ctx ? parseSize(String(flags.ctx)) : undefined,
+        maxTokens: flags['max-tokens'] ? parseSize(String(flags['max-tokens'])) : undefined,
+        think: flags.think ? String(flags.think) : undefined,
+        effort: flags.effort ? String(flags.effort) : undefined,
+        offline: flags.offline === true || flags.offline === 'true',
+      });
     case 'status':
       return showStatus();
     case 'setup':
@@ -224,6 +291,8 @@ async function main() {
       return runPack(flags);
     case 'audit':
       return runAudit();
+    case 'sbom':
+      return runSbom(flags);
     case 'scan':
       return runScan(flags);
     case 'sessions':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deel-local-cli",
-  "version": "1.2.0",
+  "version": "1.4.1",
   "description": "로컬 모델·사내 게이트웨이 전용 코딩 에이전트 CLI — 외부 의존성 0개 / Zero-dependency coding agent CLI for local LLMs and private gateways",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,11 @@
     "offline",
     "air-gapped",
     "zero-dependency",
-    "agent"
+    "agent",
+    "acp",
+    "agent-client-protocol",
+    "zed",
+    "korean"
   ],
   "repository": {
     "type": "git",
@@ -43,10 +47,11 @@
     "diagnose": "node bin/deel.js diagnose",
     "chat": "node bin/deel.js",
     "test": "node test/run.mjs",
+    "docs": "node tools/check-docs.mjs",
     "verify": "node test/no-bundle.test.js && node test/network.test.js && node test/web.test.js",
     "bench": "node test/edit-bench.js",
     "demo": "node test/demo.js",
-    "check": "node --check bin/deel.js && node --check src/repl.js && node --check src/oneshot.js && node --check src/commands.js && node --check src/agent/loop.js && node --check src/agent/session.js && node --check src/agent/effort.js && node --check src/agent/modes.js && node --check src/agent/route.js && node --check src/agent/mention.js && node --check src/agent/project.js && node --check src/tools/encoding.js && node --check src/tools/excel-com.js && node --check src/tools/excel.js && node --check src/tools/xlsx.js && node --check src/agent/compact.js && node --check src/agent/store.js && node --check src/agent/sessionui.js && node --check src/backend/adapter.js && node --check src/backend/ctxsize.js && node --check src/backend/probe.js && node --check src/backend/detect.js && node --check src/backend/http.js && node --check src/backend/scan.js && node --check src/backend/scanui.js && node --check src/tools/index.js && node --check src/tools/fsutil.js && node --check src/tools/edit-match.js && node --check src/tools/webfetch.js && node --check src/tools/todo.js && node --check src/tools/jobs.js && node --check src/skills/discover.js && node --check src/plugins/manage.js && node --check src/pack/zip.js && node --check src/pack/tar.js && node --check src/pack/selfpack.js && node --check src/safety/guard.js && node --check src/safety/undo.js && node --check src/safety/audit.js && node --check src/safety/network.js && node --check src/setup.js && node --check src/report.js && node --check src/config.js && node --check src/ui/diff.js && node --check src/ui/ansi.js && node --check src/ui/status.js && node --check src/ui/level.js && node --check src/ui/prompt.js && node --check src/ui/spinner.js && node --check src/ui/motion.js && node --check src/preview/serve.js && node --check src/ui/working.js && node --check src/ui/inputbox.js && node --check src/ui/md.js && node --check src/agent/threads.js && node --check src/agent/evolve.js && echo OK",
+    "check": "node --check bin/deel.js && node --check src/repl.js && node --check src/oneshot.js && node --check src/commands.js && node --check src/agent/loop.js && node --check src/agent/session.js && node --check src/agent/effort.js && node --check src/agent/modes.js && node --check src/agent/route.js && node --check src/agent/models.js && node --check src/agent/grade.js && node --check src/agent/mention.js && node --check src/agent/project.js && node --check src/tools/encoding.js && node --check src/tools/excel-com.js && node --check src/tools/excel.js && node --check src/tools/xlsx.js && node --check src/tools/docs.js && node --check src/agent/compact.js && node --check src/agent/store.js && node --check src/agent/sessionui.js && node --check src/backend/adapter.js && node --check src/backend/ctxsize.js && node --check src/backend/probe.js && node --check src/backend/detect.js && node --check src/backend/http.js && node --check src/backend/scan.js && node --check src/backend/scanui.js && node --check src/tools/index.js && node --check src/tools/desc.en.js && node --check src/tools/lsp.js && node --check src/lsp/rpc.js && node --check src/lsp/servers.js && node --check src/lsp/client.js && node --check src/lsp/diag.js && node --check src/tools/fsutil.js && node --check src/tools/edit-match.js && node --check src/tools/webfetch.js && node --check src/tools/todo.js && node --check src/tools/jobs.js && node --check src/skills/discover.js && node --check src/plugins/manage.js && node --check src/pack/zip.js && node --check src/pack/tar.js && node --check src/pack/selfpack.js && node --check src/safety/guard.js && node --check src/safety/undo.js && node --check src/safety/audit.js && node --check src/safety/network.js && node --check src/setup.js && node --check src/report.js && node --check src/config.js && node --check src/ui/diff.js && node --check src/ui/ansi.js && node --check src/ui/status.js && node --check src/ui/level.js && node --check src/ui/prompt.js && node --check src/ui/spinner.js && node --check src/ui/motion.js && node --check src/ui/notify.js && node --check src/ui/intro.js && node --check src/ui/banner.js && node --check src/ui/export.js && node --check src/i18n/index.js && node --check src/i18n/ko.js && node --check src/i18n/en.js && node --check src/preview/serve.js && node --check src/ui/working.js && node --check src/ui/inputbox.js && node --check src/ui/md.js && node --check src/agent/threads.js && node --check src/agent/evolve.js && node --check src/agent/pins.js && node --check src/agent/card.js && node --check src/agent/preset.js && node --check src/agent/evidence.js && node --check src/acp/jsonrpc.js && node --check src/acp/map.js && node --check src/acp/serve.js && node --check src/pack/sbom.js && node --check src/safety/secrets.js && echo OK",
     "coverage": "node test/coverage.mjs",
     "prepublishOnly": "npm run check && npm test"
   },

package/src/acp/jsonrpc.js

@@ -0,0 +1,230 @@
+// JSON-RPC 2.0 을 줄 단위로 주고받는 관. ACP 가 표준입출력에서 쓰는 그 방식이다.
+//
+// ── 왜 따로 냈나 ────────────────────────────────────────────────────────
+//
+// 이 파일에는 deel 이야기가 한 줄도 없다. 넣을 수 있었지만 안 넣었다.
+//
+// 붙이는 쪽(serve.js)은 진짜 프로세스를 띄우고, 진짜 파이프로 주고받고, 진짜
+// 모델을 부른다. 그 안에서 "덩이가 반 토막 나서 왔을 때 잘 붙이는가" 를 재려면
+// 대화 한 판을 통째로 돌려야 한다. 그러면 검사가 느려지고, 무엇보다 **틀린 자리를
+// 짚어 주지 못한다** — 화면에는 "답이 안 왔습니다" 만 남는다.
+//
+// 관을 따로 떼어 두면 그 자리를 함수 하나로 잴 수 있다. 실제로 이 파일에서
+// 잡은 것들이다:
+//
+//   · 한 덩이에 메시지가 두 개 실려 온다 (파이프는 줄 단위로 안 끊어 준다)
+//   · 한 메시지가 세 덩이로 쪼개져 온다 (한글이 섞이면 더 잘 그런다)
+//   · id 가 0 인 요청 — `if (msg.id)` 로 보면 알림으로 오해한다. ACP 는 0부터 센다
+//   · 다루는 함수가 늦게 끝나는 사이에 취소가 들어온다
+//
+// ── 지켜야 하는 것 ──────────────────────────────────────────────────────
+//
+// ACP 규격은 "메시지는 개행으로 나뉘며 **개행을 품어서는 안 된다**" 고 못 박는다.
+// JSON.stringify 는 문자열 안의 개행을 \n 두 글자로 바꾸므로 이 조건은 저절로
+// 지켜진다 — 대신 여기 말고 다른 데서 표준출력에 무언가를 적으면 그 순간
+// 관이 깨진다. 그 자리는 serve.js 가 막는다.
+import { EOL } from 'node:os';
+import { StringDecoder } from 'node:string_decoder';
+
+/** 규격이 정한 오류 번호. 우리가 새로 지어내면 클라이언트가 못 알아본다. */
+export const 오류번호 = {
+  파싱: -32700,
+  잘못된요청: -32600,
+  모르는방법: -32601,
+  잘못된인자: -32602,
+  안쪽오류: -32603,
+};
+
+/**
+ * 이어 붙여 오는 바이트를 줄 단위로 끊어 준다.
+ *
+ * 왜 직접 만드나: readline 을 쓰면 될 것 같지만, readline 은 스트림 하나를
+ * 통째로 물고 자기 방식으로 끝을 판단한다. 검사에서 문자열을 조각내 밀어 넣는
+ * 식으로 흉내 내기가 어렵고, 무엇보다 관을 닫는 시점을 우리가 못 정한다.
+ * 하는 일이 이만큼이라면 직접 두는 편이 읽기 쉽다.
+ *
+ * @param {(줄: string) => void} 한줄  완성된 줄 하나가 나올 때마다 불린다
+ * @returns {(덩이: Buffer|string) => void}
+ */
+export function 줄나누기(한줄) {
+  let 남은것 = '';
+  /*
+   * 덩이마다 toString('utf8') 하면 안 된다.
+   *
+   * 파이프는 글자 단위가 아니라 바이트 단위로 끊긴다. '녕' 한가운데서 끊기면
+   * 앞 덩이의 남은 바이트와 뒤 덩이의 첫 바이트가 각자 U+FFFD 로 바뀐다.
+   * JSON 은 여전히 파싱되므로 오류가 안 나고 **글자만 조용히 뭉개진다** —
+   * 프롬프트도 파일 내용도 도구 결과도 전부 한글인 이 프로그램에서는
+   * 반드시 밟는 자리다. StringDecoder 는 잘린 바이트를 물고 있다가 다음
+   * 덩이와 붙여 준다.
+   */
+  const 해독기 = new StringDecoder('utf8');
+  return (덩이) => {
+    남은것 += typeof 덩이 === 'string' ? 덩이 : 해독기.write(덩이);
+    /*
+     * \r\n 도 받는다.
+     *
+     * 규격은 \n 만 말하지만, 윈도우에서 다른 언어로 짠 클라이언트가 줄을 쓸 때
+     * \r 이 딸려 오는 일이 실제로 있다. 여기서 한 글자 지워 주는 값이
+     * "왜 아무 반응이 없지" 를 며칠 파는 값보다 훨씬 싸다.
+     */
+    let 자리;
+    while ((자리 = 남은것.indexOf('\n')) >= 0) {
+      const 줄 = 남은것.slice(0, 자리).replace(/\r$/, '');
+      남은것 = 남은것.slice(자리 + 1);
+      if (줄.trim()) 한줄(줄);   // 빈 줄은 그냥 넘긴다. 오류로 칠 것이 아니다
+    }
+  };
+}
+
+/**
+ * 한쪽 끝. 요청을 받아 답하고, 저쪽에 요청을 걸어 답을 기다린다.
+ *
+ * ACP 에서는 에이전트와 클라이언트가 **둘 다** 요청을 건다. 에이전트가
+ * "이 명령을 돌려도 되나" 하고 되묻는 자리가 그것이다. 그래서 이 물건은
+ * 서버도 클라이언트도 아니고 그냥 '한쪽 끝' 이다.
+ */
+export class 연결 {
+  /**
+   * @param {object} o
+   * @param {(줄: string) => void} o.보내기  한 줄을 저쪽으로 내보낸다 (개행은 여기서 붙인다)
+   * @param {(방법: string, 인자: object) => any} o.다루기
+   *        저쪽에서 온 요청·알림을 처리한다. 값을 돌려주면 그것이 답이 된다.
+   *        모르는 방법이면 모르는방법오류() 를 던진다.
+   */
+  constructor({ 보내기, 다루기 }) {
+    this.보내기줄 = 보내기;
+    this.다루기 = 다루기;
+    this.다음번호 = 1;
+    this.기다리는것 = new Map();   // 번호 → {풀기, 깨기}
+    this.닫혔나 = false;
+  }
+
+  #쓰기(덩이) {
+    if (this.닫혔나) return;
+    // 개행을 여기 한 곳에서만 붙인다. 붙이는 자리가 둘이 되면 언젠가
+    // 빈 줄이 하나 더 나가고, 그건 저쪽에서 파싱 오류로 보인다.
+    this.보내기줄(JSON.stringify(덩이) + '\n');
+  }
+
+  /** 저쪽에 요청을 걸고 답을 기다린다. */
+  요청(방법, 인자) {
+    const id = this.다음번호++;
+    return new Promise((풀기, 깨기) => {
+      if (this.닫혔나) { 깨기(new Error('관이 닫혔습니다')); return; }
+      this.기다리는것.set(id, { 풀기, 깨기 });
+      this.#쓰기({ jsonrpc: '2.0', id, method: 방법, params: 인자 ?? {} });
+    });
+  }
+
+  /** 답을 안 받는 한마디. */
+  알림(방법, 인자) {
+    this.#쓰기({ jsonrpc: '2.0', method: 방법, params: 인자 ?? {} });
+  }
+
+  /**
+   * 저쪽에서 온 줄 하나.
+   *
+   * 일부러 await 하지 않는다. 여기서 기다리면 앞의 요청이 끝날 때까지 다음
+   * 줄을 못 읽는데, 그러면 **취소가 영영 안 닿는다** — 취소는 늘 무언가가
+   * 돌고 있는 중에 온다. 그게 취소의 정의다.
+   */
+  받았다(줄) {
+    let 온것;
+    try {
+      온것 = JSON.parse(줄);
+    } catch {
+      // id 를 모르니 null 로 답한다. 규격이 그렇게 하라고 적어 두었다.
+      this.#쓰기({ jsonrpc: '2.0', id: null, error: { code: 오류번호.파싱, message: '읽을 수 없는 JSON 입니다' } });
+      return;
+    }
+    if (!온것 || typeof 온것 !== 'object') {
+      this.#쓰기({ jsonrpc: '2.0', id: null, error: { code: 오류번호.잘못된요청, message: '객체가 아닙니다' } });
+      return;
+    }
+
+    // 저쪽이 우리 요청에 답한 것.
+    //
+    // 'id' in 온것 으로 본다. id 가 0 일 수 있기 때문이다 — ACP 클라이언트는
+    // 실제로 0번부터 센다. 여기서 truthy 로 보면 첫 요청의 답을 통째로 잃는다.
+    if ('id' in 온것 && !온것.method) {
+      const 기다림 = this.기다리는것.get(온것.id);
+      if (!기다림) return;   // 이미 포기한 것. 늦게 온 답은 조용히 버린다
+      this.기다리는것.delete(온것.id);
+      if (온것.error) {
+        const e = new Error(온것.error?.message ?? '저쪽에서 오류로 답했습니다');
+        e.code = 온것.error?.code;
+        e.data = 온것.error?.data;
+        기다림.깨기(e);
+      } else {
+        기다림.풀기(온것.result);
+      }
+      return;
+    }
+
+    if (typeof 온것.method !== 'string') {
+      if ('id' in 온것) {
+        this.#쓰기({ jsonrpc: '2.0', id: 온것.id, error: { code: 오류번호.잘못된요청, message: 'method 가 없습니다' } });
+      }
+      return;
+    }
+
+    const 알림인가 = !('id' in 온것) || 온것.id === null;
+
+    Promise.resolve()
+      .then(() => this.다루기(온것.method, 온것.params ?? {}))
+      .then((결과) => {
+        if (알림인가) return;   // 알림에는 답하지 않는다. 답하면 저쪽이 짝 없는 답을 받는다
+        this.#쓰기({ jsonrpc: '2.0', id: 온것.id, result: 결과 ?? {} });
+      })
+      .catch((err) => {
+        /*
+         * 알림을 다루다 터진 것은 답할 데가 없다.
+         *
+         * 그렇다고 삼키면 무엇이 터졌는지 아무도 모른다. 표준오류에 적는다 —
+         * ACP 는 에이전트가 stderr 에 로그를 적어도 된다고 분명히 허락한다.
+         */
+        if (알림인가) {
+          try { process.stderr.write(`[acp] ${온것.method} 처리 중 오류: ${err?.message ?? err}${EOL}`); } catch { /* 여기서 또 터지면 할 게 없다 */ }
+          return;
+        }
+        this.#쓰기({
+          jsonrpc: '2.0',
+          id: 온것.id,
+          error: {
+            code: Number.isInteger(err?.code) ? err.code : 오류번호.안쪽오류,
+            message: String(err?.message ?? err ?? '알 수 없는 오류'),
+            ...(err?.data !== undefined ? { data: err.data } : {}),
+          },
+        });
+      });
+  }
+
+  /**
+   * 관을 닫는다. 아직 답을 기다리던 요청은 전부 깨뜨린다.
+   *
+   * 안 깨뜨리면 그 프라미스를 붙들고 있던 자리가 영영 안 끝난다. 사람 눈에는
+   * "에디터가 멈췄다" 로 보인다 — 원인은 이미 죽은 프로세스라 어디에도 안 남는다.
+   */
+  닫기(왜 = '관이 닫혔습니다') {
+    this.닫혔나 = true;
+    for (const [, 기다림] of this.기다리는것) {
+      try { 기다림.깨기(new Error(왜)); } catch { /* 이미 정리된 것 */ }
+    }
+    this.기다리는것.clear();
+  }
+}
+
+/** 모르는 방법이라고 답하게 하는 오류. 다루기 함수가 이걸 던지면 된다. */
+export function 모르는방법오류(방법) {
+  const e = new Error(`모르는 방법입니다: ${방법}`);
+  e.code = 오류번호.모르는방법;
+  return e;
+}
+
+/** 인자가 틀렸다고 답하게 하는 오류. */
+export function 잘못된인자오류(무엇) {
+  const e = new Error(무엇);
+  e.code = 오류번호.잘못된인자;
+  return e;
+}

package/src/acp/map.js

@@ -0,0 +1,219 @@
+// deel 이 흘리는 것을 ACP 가 아는 모양으로 옮긴다.
+//
+// ── 왜 옮기는 자리를 따로 두나 ──────────────────────────────────────────
+//
+// 붙이는 일의 값어치는 대부분 여기 있다. 관을 잇는 것은 한 시간이면 되지만,
+// **에디터가 무엇을 보여 줄 수 있는가** 는 전부 이 표에서 갈린다.
+//
+//   갈래(kind)를 안 주면 → 전부 똑같은 회색 점으로 그려진다
+//   자리(locations)를 안 주면 → 고친 파일을 눌러도 안 열린다
+//   상태(status)를 안 주면 → 도는 중인지 끝났는지 안 보인다
+//
+// 이 셋은 있어도 없어도 규격에는 안 걸린다. 그래서 대충 붙인 구현은 죄다
+// 안 준다. 여기서만 챙기면 같은 프로토콜을 쓰고도 화면이 달라진다.
+//
+// ── 순수하게 둔다 ───────────────────────────────────────────────────────
+//
+// 이 파일은 아무것도 안 부르고 아무 데도 안 쓴다. 값을 넣으면 값이 나온다.
+// 그래야 진짜 에디터 없이 검사할 수 있다 — 붙인 것이 맞는지 확인하려고
+// Zed 를 띄워야 한다면 아무도 확인 안 하게 된다.
+
+/**
+ * 도구 이름 → ACP 갈래.
+ *
+ * 규격이 정한 낱말만 쓴다: read·edit·delete·move·search·execute·think·fetch·
+ * switch_mode·other. 모르는 것은 other 다 — 지어내면 클라이언트가 못 알아본다.
+ */
+const 갈래표 = {
+  Read: 'read',
+  Outline: 'read',
+  Write: 'edit',
+  Append: 'edit',
+  Edit: 'edit',
+  Glob: 'search',
+  Grep: 'search',
+  Recall: 'search',
+  Bash: 'execute',
+  Jobs: 'execute',
+  Verify: 'execute',
+  WebFetch: 'fetch',
+  Task: 'think',
+  TodoWrite: 'think',
+  Skill: 'think',
+  Remember: 'other',
+};
+
+export function 도구갈래(이름) {
+  return 갈래표[String(이름 ?? '')] ?? 'other';
+}
+
+/**
+ * 사람이 읽을 한 줄.
+ *
+ * `Read` 만 적으면 열 줄이 전부 `Read` 다. 무엇을 읽었는지가 빠지면 목록을
+ * 훑어보는 뜻이 없어진다 — 그럴 거면 아예 안 보여 주는 편이 낫다.
+ */
+export function 도구이름표(이름, 인자) {
+  const a = 인자 ?? {};
+  const 첫 = a.file_path ?? a.pattern ?? a.path ?? a.url ?? a.name ?? a.목적
+    ?? (a.command ? String(a.command).replace(/\s+/g, ' ') : null)
+    ?? (Array.isArray(a.files) && a.files.length
+      ? `${a.files[0]?.file_path ?? '?'}${a.files.length > 1 ? ` 외 ${a.files.length - 1}개` : ''}`
+      : null)
+    ?? (Array.isArray(a.edits) && a.edits.length
+      ? `${a.edits[0]?.file_path ?? '?'}${a.edits.length > 1 ? ` 외 ${a.edits.length - 1}군데` : ''}`
+      : null)
+    ?? (Array.isArray(a.paths) && a.paths.length ? `${a.paths.length}개` : null)
+    ?? (Array.isArray(a.todos) ? `${a.todos.length}건` : null);
+  const 안 = 첫 == null ? '' : 자르기(String(첫), 80);
+  return 안 ? `${이름}(${안})` : String(이름 ?? '도구');
+}
+
+/**
+ * 이 호출이 건드린 파일 자리.
+ *
+ * 결과에 실린 실제 경로(changed)를 먼저 본다. 인자에 적힌 것은 상대 경로일 수
+ * 있는데, 에디터는 절대 경로라야 연다. 인자만 보고 넘기면 눌러도 안 열리는
+ * 링크가 되고, 그건 없느니만 못하다.
+ */
+export function 도구자리(이름, 인자, 결과) {
+  const 모은것 = [];
+  const 넣기 = (p) => {
+    const s = typeof p === 'string' ? p.trim() : '';
+    if (s && !모은것.includes(s)) 모은것.push(s);
+  };
+
+  넣기(결과?.changed);
+  for (const x of 결과?.여럿 ?? []) 넣기(x?.changed);
+
+  const a = 인자 ?? {};
+  넣기(a.file_path);
+  넣기(a.path);
+  for (const f of Array.isArray(a.files) ? a.files : []) 넣기(f?.file_path);
+  for (const e of Array.isArray(a.edits) ? a.edits : []) 넣기(e?.file_path);
+  for (const p of Array.isArray(a.paths) ? a.paths : []) 넣기(p);
+
+  return 모은것.slice(0, 20).map((path) => ({ path }));
+}
+
+/**
+ * 도구가 실제로 탈이 났는가.
+ *
+ * `error` 만 보면 안 된다. Bash 는 종료코드를, Verify 는 "탈 2개" 를 요약에
+ * 담아 돌려준다 — 그것들을 성공으로 칠하면 화면에서 성공과 구별되지 않는다.
+ * `deel run` 쪽에서 이미 한 번 데인 자리라 여기서도 같은 눈으로 본다.
+ */
+export function 도구탈났나(결과) {
+  return !!(결과?.error || 결과?.failed);
+}
+
+/**
+ * 도구 결과를 ACP 가 그릴 수 있는 내용으로.
+ *
+ * 모델에게 가는 본문을 그대로 실으면 안 된다. 파일 하나를 읽어도 수만 자가
+ * 오는데, 그것이 전부 에디터 창으로 흘러가면 사람이 아무것도 못 읽는다.
+ * 보여 줄 만큼만 자른다 — 모델이 받는 양은 이것과 무관하게 그대로다.
+ */
+export function 도구내용(결과, 최대 = 2000) {
+  const r = 결과 ?? {};
+  const 글 = r.error
+    ? String(r.error)
+    : (r.content != null ? String(r.content) : (r.summary != null ? String(r.summary) : ''));
+  if (!글.trim()) return [];
+  return [{ type: 'content', content: { type: 'text', text: 자르기(글, 최대) } }];
+}
+
+/**
+ * 한 걸음 끝난 도구 호출을 ACP 한 덩이로.
+ *
+ * @param {string} 아이디  이 세션 안에서 유일한 번호
+ * @param {object} ev      loop.js 가 흘린 `tool` 이벤트
+ */
+export function 도구끝남(아이디, ev) {
+  return {
+    sessionUpdate: 'tool_call_update',
+    toolCallId: 아이디,
+    title: 도구이름표(ev?.name, ev?.args),
+    kind: 도구갈래(ev?.name),
+    status: 도구탈났나(ev?.result) ? 'failed' : 'completed',
+    content: 도구내용(ev?.result),
+    locations: 도구자리(ev?.name, ev?.args, ev?.result),
+  };
+}
+
+/** 이제 막 시작한 도구 호출. */
+export function 도구시작(아이디, 이름, 인자) {
+  return {
+    sessionUpdate: 'tool_call',
+    toolCallId: 아이디,
+    title: 도구이름표(이름, 인자),
+    kind: 도구갈래(이름),
+    status: 'in_progress',
+    content: [],
+    locations: 도구자리(이름, 인자, null),
+  };
+}
+
+/**
+ * deel 이 턴을 끝낸 까닭 → ACP 가 아는 낱말.
+ *
+ * 규격이 가진 낱말은 다섯뿐이다: end_turn·max_tokens·max_turn_requests·
+ * refusal·cancelled. deel 의 '헛돎' 은 여기 딱 맞는 것이 없다.
+ *
+ * refusal 로 보내고 싶은 마음이 들지만 그러면 안 된다 — 규격은 refusal 일 때
+ * "그 사용자 말과 그 뒤의 것은 다음 프롬프트에 넣지 말라" 고 적어 두었다.
+ * deel 은 헛돌았을 때 대화를 버리지 않는다. 그래서 end_turn 으로 보내고,
+ * **왜 멈췄는지는 말로 따로 흘려 준다**. 낱말이 안 맞으면 낱말을 억지로 맞추는
+ * 대신 사람이 읽을 것을 준다.
+ */
+export function 멈춘까닭(까닭) {
+  switch (까닭) {
+    case 'aborted': return 'cancelled';
+    case 'limit': return 'max_turn_requests';
+    case 'stuck': return 'end_turn';
+    default: return 'end_turn';
+  }
+}
+
+/**
+ * 프롬프트로 온 덩이들에서 글만 뽑는다.
+ *
+ * resource 는 알맹이가 실려 오므로 그대로 쓴다. resource_link 는 주소만 오는데,
+ * 그래도 주소를 적어 준다 — 모델이 그 자리를 Read 로 열어 볼 수 있다.
+ * 그림·소리는 읽을 방법이 없다. 조용히 버리지 않고 무엇을 못 읽었는지 적는다.
+ */
+export function 프롬프트글(덩이들) {
+  const 조각 = [];
+  for (const b of Array.isArray(덩이들) ? 덩이들 : []) {
+    if (!b || typeof b !== 'object') continue;
+    switch (b.type) {
+      case 'text':
+        if (typeof b.text === 'string' && b.text) 조각.push(b.text);
+        break;
+      case 'resource': {
+        const r = b.resource ?? {};
+        if (typeof r.text === 'string' && r.text) {
+          조각.push(`--- ${r.uri ?? '붙임'} ---\n${r.text}`);
+        } else if (r.uri) {
+          조각.push(`(붙임: ${r.uri} — 글이 아니라 못 읽었습니다)`);
+        }
+        break;
+      }
+      case 'resource_link':
+        if (b.uri) 조각.push(`(붙임: ${b.uri})`);
+        break;
+      case 'image':
+      case 'audio':
+        조각.push(`(${b.type === 'image' ? '그림' : '소리'}이 붙어 왔지만 이 모델로는 못 읽습니다)`);
+        break;
+      default:
+        break;
+    }
+  }
+  return 조각.join('\n\n').trim();
+}
+
+function 자르기(s, n) {
+  const t = String(s ?? '');
+  return t.length > n ? `${t.slice(0, n)}\n… (${t.length - n}자 줄임)` : t;
+}