axmap-cli 1.3.3 → 1.5.0

package/mcp/README.md

@@ -4,7 +4,7 @@
 있게 하는 규격**)로 axMap 을 AI CLI 에 붙인다.
 
 - 붙이면 AI 도구가 **"나는 이 파일들을 건드리겠다"를 선언**하게 된다. 겹치면 그 자리에서 거부당한다
-- 코드 충돌이 나기 전에 **의도 충돌**을 먼저 터뜨리는 것이고, 뷰어는 그 선언을 읽어 화면을 그린다
+- 코드 충돌이 나기 전에 **의도 충돌**을 먼저 터뜨리는 것이고, 다른 에이전트는 그 선언을 읽어 작업 범위를 조정한다
 - **한 번 설치하면 아무 저장소에서나 붙는다.** 작업할 저장소에는 파일을 하나도 남기지 않는다
 
 ---
@@ -39,6 +39,10 @@ https://github.com/rl2aderjoon/axmap/blob/main/mcp/SETUP-FOR-AI.md
 | `ax_release(paths?)` | 끝나면 즉시. 생략하면 전부 반납 |
 | `ax_renew()` | 길어지면 시간 연장 |
 | `ax_inbox(id?)` | 다른 에이전트가 나에게 보낸 쪽지를 읽는다 |
+| `ax_sessions()` | 같은 repo의 연결된 세션·역할·상태·사용량 |
+| `ax_dispatch(to, prompt)` / `ax_result(id)` | 연결된 세션에 단일 작업 전달·결과 조회 |
+| `ax_chat(left, right, prompt, maxTurns?, maxTokens?)` | 관리형 세션 두 개의 제한된 자동 대화를 백그라운드 접수 |
+| `ax_dialogue(id)` / `ax_chat_stop(id)` | 대화·토큰 조회 / 추가 중계 중단 |
 | `ax_send(to?, subject, body)` | 다른 에이전트에게 쪽지를 보낸다 |
 | `ax_init(remote?)` | 명시적 준비용. 조회·선점은 장부를 자동 준비하므로 먼저 부를 필요가 없다 |
 
@@ -133,7 +137,7 @@ CLI 를 부를 때마다 넘긴다. 앞 두 칸은 CLI 와 순서가 같아서,
 
 ### 🔴 `AXMAP_REPO` 는 비운다 — 대상은 부를 때마다 다시 정해진다
 
-서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 `AXMAP_REPO` → 도구의 절대 경로 `cwd` → 클라이언트 작업 폴더(roots) → 시작 폴더의 Git 루트다. 앱의 전역 `current.json`은 사용하지 않는다. 근거는 [DECISIONS.md의 D22](../docs/DECISIONS.md).
+서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 `AXMAP_REPO` → 도구의 절대 경로 `cwd` → 클라이언트 작업 폴더(roots) → 시작 폴더의 Git 루트다. 근거는 [DECISIONS.md의 D22](../docs/DECISIONS.md).
 
 장부가 없는 repo도 첫 조회·선점 때 자동으로 준비한다. 기존 원격 장부가 있으면 이어 사용하고, 원격 접근 실패는 빈 장부로 바꾸지 않는다. roots가 여러 repo를 가리켜 대상을 고를 수 없으면 도구의 `cwd`를 지정한다. roots 미지원 클라이언트에서 실행 중 폴더를 바꿀 때도 `cwd`를 전달한다. 서로 다른 MCP 세션의 타겟은 독립적이다.
 
@@ -193,10 +197,7 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 관문 1(push CAS — **"내가 읽은 뒤로 바뀐 게 없을 때만 쓴다"**. git push 가 원래
 이렇게 동작한다)과 관문 2(겹침 판정)가 CLI 와 완전히 동일하게 적용된다.
 
-전송은 stdio + 줄바꿈 구분 JSON-RPC 2.0 이다. SDK 의존성 없이 직접 구현했다 —
-폐쇄망에서 npm 설치 없이 돌아야 한다는 제약이 여기에도 적용된다.
-설치기가 `bin` `src` `mcp` `tools` `app` `package.json` `LICENSE` 만 복사하고
-`desktop/`(Electron 껍데기)을 빼는 것도 같은 이유다. 받아야 할 것이 없다.
+전송은 stdio + 줄바꿈 구분 JSON-RPC 2.0이다. MCP 서버는 SDK 없이 구현했다. 설치기는 `bin`, `src`, `mcp`, `tools`, `package.json`, `LICENSE`와 터미널 연결 의존성을 준비한다.
 
 ---
 
@@ -220,5 +221,4 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 
 **`doctor` 는 전역 등록을 검사하지 않는다.** 저장소의 `.mcp.json` 만 본다. 그래서
 전역으로 설치한 PC 에서 `MCP 설정` 줄이 `~~` 로 뜨는 것은 정상이다 — 무게가 전역
-등록으로 옮겨간 지금 그 줄은 거짓 보고에 가깝다. 배경은
-[docs/HANDOVER.md](../../docs/HANDOVER.md) 4.4 절과 4.5 절에 있다.
+등록으로 옮겨간 지금 그 줄은 거짓 보고에 가깝다. 설치 후에는 실제 전역 등록 경로도 함께 확인한다.

package/mcp/install.ps1

@@ -142,7 +142,7 @@ if (-not (Test-Path -LiteralPath (Join-Path $Source 'bin\axmap.mjs'))) {
   $inner = Join-Path $Source 'axmap'
   if (Test-Path -LiteralPath (Join-Path $inner 'bin\axmap.mjs')) { $Source = (Resolve-Path -LiteralPath $inner).Path }
 }
-foreach ($need in @('bin\axmap.mjs', 'mcp\server.mjs', 'src\protocol.mjs', 'tools\mcp-register.mjs', 'app\lib\agentcli.mjs', 'package.json')) {
+foreach ($need in @('bin\axmap.mjs', 'mcp\server.mjs', 'src\protocol.mjs', 'tools\mcp-register.mjs', 'src\agentcli.mjs', 'package.json')) {
   if (-not (Test-Path -LiteralPath (Join-Path $Source $need))) {
     Fail @"
 axMap 원본이 온전하지 않습니다. 없는 파일: $need
@@ -198,8 +198,8 @@ Say ''
 Say "복사합니다 -> $Dest"
 New-Item -ItemType Directory -Force -Path $Dest | Out-Null
 
-# desktop\ 은 뺀다. Electron 껍데기라 MCP 에 필요 없고 node_modules 가 수백 MB 다.
-foreach ($item in @('bin', 'src', 'mcp', 'tools', 'app', 'package.json', 'LICENSE')) {
+# Copy the CLI, MCP and their shared runtime sources.
+foreach ($item in @('bin', 'src', 'mcp', 'tools', 'package.json', 'LICENSE')) {
   $from = Join-Path $Source $item
   $to   = Join-Path $Dest $item
   if (-not (Test-Path -LiteralPath $from)) { Hm "$item 없음 — 건너뜁니다"; continue }
@@ -219,6 +219,9 @@ foreach ($item in @('bin', 'src', 'mcp', 'tools', 'app', 'package.json', 'LICENS
   }
 }
 
+& node (Join-Path $Dest 'tools\run.mjs') install-runtime $Source
+if ($LASTEXITCODE -ne 0) { Fail '터미널 런타임 설치에 실패했습니다.' }
+
 $server = Join-Path $Dest 'mcp\server.mjs'
 if (-not (Test-Path -LiteralPath $server)) { Fail "복사가 끝났는데 서버가 없습니다: $server" }
 

package/mcp/install.sh

@@ -144,7 +144,7 @@ SOURCE=$(cd "$SOURCE" && pwd)
 if [ ! -f "$SOURCE/bin/axmap.mjs" ] && [ -f "$SOURCE/axmap/bin/axmap.mjs" ]; then
   SOURCE=$(cd "$SOURCE/axmap" && pwd)
 fi
-for need in bin/axmap.mjs mcp/server.mjs src/protocol.mjs tools/mcp-register.mjs app/lib/agentcli.mjs package.json; do
+for need in bin/axmap.mjs mcp/server.mjs src/protocol.mjs tools/mcp-register.mjs src/agentcli.mjs package.json; do
   if [ ! -e "$SOURCE/$need" ]; then
     fail "axMap 원본이 온전하지 않습니다. 없는 파일: $need
   본 곳: $SOURCE
@@ -198,8 +198,8 @@ say ''
 say "복사합니다 -> $DEST"
 mkdir -p "$DEST" || fail "설치 폴더를 만들지 못했습니다: $DEST"
 
-# desktop/ 은 뺀다. Electron 껍데기라 MCP 에 필요 없고 node_modules 가 수백 MB 다.
-for item in bin src mcp tools app package.json LICENSE; do
+# Copy the CLI, MCP and their shared runtime sources.
+for item in bin src mcp tools package.json LICENSE; do
   from="$SOURCE/$item"
   to="$DEST/$item"
   if [ ! -e "$from" ]; then hm "$item 없음 — 건너뜁니다"; continue; fi
@@ -218,6 +218,8 @@ for item in bin src mcp tools app package.json LICENSE; do
   fi
 done
 
+node "$DEST/tools/run.mjs" install-runtime "$SOURCE" || fail "터미널 런타임 설치에 실패했습니다."
+
 SERVER="$DEST/mcp/server.mjs"
 [ -f "$SERVER" ] || fail "복사가 끝났는데 서버가 없습니다: $SERVER"
 

package/mcp/server.mjs

@@ -3,7 +3,7 @@
  * axMap MCP 서버.
  *
  * Claude Code 같은 AI 도구가 "나는 이 파일들을 건드리겠다"를 선언하게 만든다.
- * 그래야 뷰어가 지금 무슨 일이 일어나는지 보여줄 수 있다.
+ * 다른 에이전트가 작업 범위와 목적을 확인할 수 있다.
  *
  * 설정 (.mcp.json 또는 도구별 MCP 설정):
  *   {
@@ -212,6 +212,15 @@ const TTL = process.env.AXMAP_TTL ?? '45m'
  */
 const SESSION = process.env.AXMAP_SESSION || process.env.CLAUDE_CODE_SESSION_ID || `mcp-${process.pid}`
 
+const BRIDGE_TOOLS = new Set(['ax_sessions', 'ax_dispatch', 'ax_result', 'ax_chat', 'ax_dialogue', 'ax_chat_stop'])
+function bridge(args, input) {
+  const r = spawnSync(process.execPath, [path.join(SELF, 'tools', 'bridge.mjs'), ...args], {
+    cwd: REPO, input, encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, AXMAP_AGENT: AGENT }, timeout: 45000,
+  })
+  return { ok: r.status === 0, text: (r.stdout || '') + (r.stderr || '') + (r.error ? r.error.message : '') }
+}
+
 /**
  * 쪽지함 CLI 를 부른다. `cli` 와 달리 stdin 으로 본문을 넘긴다.
  *
@@ -376,6 +385,48 @@ function cli(args) {
 // ---------------------------------------------------------------------------
 
 const TOOLS = [
+  {
+    name: 'ax_sessions',
+    description: '현재 repo에 연결된 로컬 AI 세션, 역할, 상태와 측정 토큰 사용량을 확인한다. stdio는 사용자가 bridge serve로 시작한 관리형 세션이다. 등록만으로 연결 가능성이나 실행 성공을 보장하지 않는다.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'ax_dispatch',
+    description: '사용자가 허용한 작업을 연결된 상대 세션에 전달한다. 기존 맥락을 유지하며 새 모델 프로세스를 만들지 않는다. submitted는 완료가 아니다. unknown이면 자동 재시도하지 말고 ax_result로 확인한다. Codex/agy 관리형 stdio, 별도로 실행한 Windows agy console, 실험용 PTY/agentapi 연결을 지원한다.',
+    inputSchema: { type: 'object', properties: {
+      to: { type: 'string', description: 'ax_sessions에서 확인한 상대 세션 UUID' },
+      prompt: { type: 'string', description: '상대가 실행할 작업 요청' },
+    }, required: ['to', 'prompt'] },
+  },
+  {
+    name: 'ax_result',
+    description: '작업 요청의 제출/완료/불명 상태, 결과와 측정 사용량을 확인한다. 관리형 세션은 구조화된 완료 이벤트, PTY는 종료 훅, 독립 Windows console은 요청 UUID가 있는 대화 기록과 현재 빈 입력창의 대기 상태로 판정한다.',
+    inputSchema: { type: 'object', properties: {
+      id: { type: 'string', description: 'ax_dispatch가 반환한 요청 UUID' },
+    }, required: ['id'] },
+  },
+  {
+    name: 'ax_chat',
+    description: '사용자가 허용한 범위에서 대기 중인 관리형 세션 두 개의 자동 대화를 시작한다. 기본 최대 4회 실행, 측정 처리 토큰 50000, 메시지 2000자. 대기 중 모델 호출 없음. 한 번의 실행은 토큰 한도를 넘을 수 있으며 다음 실행 전에 검사한다. 접수는 완료가 아니다. ax_dialogue로 조회한다. 사용자 승인이나 연결 실패를 자동 우회하지 않는다.',
+    inputSchema: { type: 'object', properties: {
+      left: { type: 'string', description: '먼저 요청받을 stdio 세션 UUID' },
+      right: { type: 'string', description: '다른 stdio 세션 UUID' },
+      prompt: { type: 'string', description: '사용자가 부여한 작업과 종료 기준. 기본 2000자 이하' },
+      maxTurns: { type: 'integer', minimum: 1, maximum: 20 },
+      maxTokens: { type: 'integer', minimum: 1 },
+      maxMessageChars: { type: 'integer', minimum: 1, maximum: 8000 },
+    }, required: ['left', 'right', 'prompt'] },
+  },
+  {
+    name: 'ax_dialogue',
+    description: '자동 대화의 상태, 요청별 사용량과 누적 사용량을 확인한다. usage_unavailable는 측정 불가로 중단, token_limit는 다음 실행 시작을 막은 상태다.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  },
+  {
+    name: 'ax_chat_stop',
+    description: '자동 대화의 추가 중계를 중단한다. 이미 전달된 모델 요청은 계속 실행될 수 있다. 상대 CLI를 강제 종료하지 않는다.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  },
   {
     name: 'ax_brief',
     description:
@@ -493,7 +544,7 @@ for (const tool of TOOLS) {
 const readFrom = (base, rel) => {
   try { return fs.readFileSync(path.join(base, rel), 'utf8') } catch { return null }
 }
-/** axMap 자신의 파일. 코드 지도(`MAP`)처럼 **이 도구에 관한 것**만 여기서 읽는다. */
+/** axMap 자신의 파일. 구성 목록처럼 **이 도구에 관한 것**만 여기서 읽는다. */
 const readSelf = (rel) => readFrom(SELF, rel)
 /** 대상 저장소의 파일. 브리핑의 내용은 원칙적으로 전부 이쪽이어야 한다. */
 const readRepo = (rel) => readFrom(REPO, rel)
@@ -548,23 +599,19 @@ function gist(rel) {
  * 경로만 여기 적고 설명은 파일에서 가져온다.
  * 경로는 거의 안 바뀌고 설명은 자주 바뀌므로, 낡을 수 있는 쪽을 자동화한다.
  */
-const MAP = [
-  ['판정 (순수)', 'src/protocol.mjs'],
-  ['불변식 검사기 (공유)', 'src/invariants.mjs'],
-  ['CLI · git · 훅', 'bin/axmap.mjs'],
-  ['MCP 서버 (이 파일)', 'mcp/server.mjs'],
-  ['뷰어 서버 · API', 'app/server.mjs'],
-  ['대화 세션 = CLI 프로세스', 'app/lib/session.mjs'],
-  ['세션마다의 이름 (슬롯)', 'app/lib/slots.mjs'],
-  ['AI CLI 감지 · 로그인', 'app/lib/agentcli.mjs'],
-  ['사다리 배치', 'app/lib/ladder.mjs'],
-  ['화면 부트스트랩', 'app/web/shell.js'],
-  ['가운데 칸 그리기', 'app/web/stage.js'],
-  ['화면에 나가는 말 (어휘)', 'app/web/words.js'],
-  ['데스크톱 셸 (Electron)', 'desktop/main.mjs'],
+const COMPONENTS = [
+  ['선점 판정', 'src/protocol.mjs'],
+  ['불변식 검사', 'src/invariants.mjs'],
+  ['CLI · Git · 훅', 'bin/axmap.mjs'],
+  ['MCP 서버', 'mcp/server.mjs'],
+  ['AI CLI 탐지', 'src/agentcli.mjs'],
+  ['로컬 작업 요청', 'src/bridge.mjs'],
+  ['터미널 세션 연결', 'src/terminal-bridge.mjs'],
+  ['설치·설정', 'tools/setup.mjs'],
+  ['쪽지함', 'tools/bus.mjs'],
 ]
 
-/** axMap 자신을 겨눴을 때. 코드 지도가 있는 유일한 경우다. */
+/** axMap 자신을 겨눴을 때만 자체 구성 목록을 보여준다. */
 function briefSelf() {
   const out = []
   out.push('# axMap — 새로 들어온 에이전트를 위한 브리핑')
@@ -589,12 +636,11 @@ function briefSelf() {
   // 번호를 여기 적지 않는다. 늘릴 때마다 이 줄이 낡는다 — 실제로 I8 을 넣고 놓쳤다.
   out.push('| 지켜야 할 성질 | `docs/INVARIANTS.md` |')
   out.push('| 왜 파서인가 | `docs/EXPERIMENT.md` |')
-  out.push('| 무엇을 재는가 | `docs/BENCH.md` — M3 도달 호출 번호가 주 지표다 |')
   out.push('')
 
-  out.push('## 코드 지도')
+  out.push('## 주요 구성')
   out.push('')
-  for (const [role, rel] of MAP) out.push(`- **${role}** — \`${rel}\`\n  ${gist(rel)}`)
+  for (const [role, rel] of COMPONENTS) out.push(`- **${role}** — \`${rel}\`\n  ${gist(rel)}`)
   out.push('')
   return out
 }
@@ -605,7 +651,7 @@ function briefSelf() {
  * 🔴 여기서 **axMap 의 문서를 대신 보여주지 않는다.**
  *
  * 예전에는 브리핑이 통째로 `readSelf` 였다. 그래서 남의 프로젝트에 붙여도
- * `src/protocol.mjs` · `app/web/graph.js` 같은 **axMap 의 코드 지도**가 나왔고,
+ * `src/protocol.mjs` · `src/bridge.mjs` 같은 **axMap 의 주요 구성**이 나왔고,
  * 받는 쪽에는 자기 저장소를 설명하는 것처럼 보인다.
  *
  * 이 저장소는 "낡은 지도는 없는 지도보다 나쁘다" 고 적어 두었는데,
@@ -613,7 +659,7 @@ function briefSelf() {
  * 낡은 지도는 언젠가 맞았기라도 하다.
  *
  * 그래서 대상에 문서가 없으면 **없다고 말하고 끝낸다.** 채워 넣지 않는다.
- * 코드 지도는 아예 만들지 않는다 — 지어낸 지도가 정확히 그 실패이기 때문이다.
+ * 구성 목록을 추측해서 만들지 않는다.
  */
 function briefForeign() {
   const out = []
@@ -665,8 +711,8 @@ function brief() {
   /**
    * 🔴 검증 목록을 `package.json` 에서 뽑지 않는다.
    *
-   * scripts 에는 검사(`test` · `smoke` · `demo:*`)와 실행(`app` · `desktop`)이
-   * 섞여 있다. 전부 나열하면 새 에이전트가 앱을 띄워 놓고 "검증했다" 고 여긴다.
+   * scripts 에는 검사와 설치 같은 실행 명령이 섞일 수 있다.
+   * 전부 나열하면 새 에이전트가 실행만 해 놓고 "검증했다" 고 여긴다.
    * **무엇이 통과해야 하는지를 정한 곳은 규칙 문서의 「검증」 절**이므로
    * 거기서 읽어 온다. 규격이 진실이고 목록은 그 사본이다.
    *
@@ -698,12 +744,6 @@ function brief() {
     out.push('')
     for (const c of cmds) out.push(`- \`${c}\``)
     out.push('')
-    // axMap 자신에게만 해당하는 주의다. 남의 저장소에 붙여 말하지 않는다.
-    if (!isForeign()) {
-      out.push('🔴 `app/web/` 를 건드렸으면 `npm run smoke` 는 **선택이 아니다.**')
-      out.push('`npm test` 는 브라우저 코드를 실행하지 않으므로 화면이 죽어도 초록이다.')
-      out.push('')
-    }
   }
 
   out.push('장부는 선점·조회 시 자동으로 준비한다. 별도 `ax_init` 호출은 필요 없다.')
@@ -807,6 +847,14 @@ function dispatch(name, args = {}) {
   const paths = Array.isArray(args.paths) ? args.paths.map(String) : []
 
   switch (name) {
+    case 'ax_sessions': return bridge(['sessions'])
+    case 'ax_dispatch': return bridge(['send', '--to', args.to], args.prompt)
+    case 'ax_result': return bridge(['result', args.id])
+    case 'ax_chat': return bridge(['chat', '--background', '--left', args.left, '--right', args.right,
+      ...['maxTurns', 'maxTokens', 'maxMessageChars'].flatMap(key => args[key] === undefined ? [] :
+        [`--${key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}`, String(args[key])])], args.prompt)
+    case 'ax_dialogue': return bridge(['dialogue', args.id])
+    case 'ax_chat_stop': return bridge(['stop', args.id])
     case 'ax_brief':
       return { ok: true, text: brief() }
     case 'ax_init': {
@@ -1008,8 +1056,9 @@ async function handle(req) {
       do { task = rootsTask; await task } while (task !== rootsTask)
     }
     const r = callTool(params?.name, params?.arguments ?? {})
-    const warning = r.ok ? syncConfiguredProfile(REPO, BUS, { ...process.env, AXMAP_AGENT: AGENT }) : ''
-    return { content: [{ type: 'text', text: r.text + (warning ? '\n' + warning : '') + (r.ok ? unreadBanner(params?.name, r.text) : '') }], isError: !r.ok }
+    const localBridge = BRIDGE_TOOLS.has(params?.name)
+    const warning = r.ok && !localBridge ? syncConfiguredProfile(REPO, BUS, { ...process.env, AXMAP_AGENT: AGENT }) : ''
+    return { content: [{ type: 'text', text: r.text + (warning ? '\n' + warning : '') + (r.ok && !localBridge ? unreadBanner(params?.name, r.text) : '') }], isError: !r.ok }
   }
   if (method === 'ping') return {}
   return null // 알림이거나 지원하지 않는 메서드

package/package.json

@@ -1,14 +1,14 @@
 {
   "//name": "🔴 npm 의 'axmap' 은 2022년부터 남이 쓰고 있는 다른 꾸러미다(leozin_ 의 Map 라이브러리, 1.1.2). 그래서 `npx axmap` 은 우리 것이 아니고, 누구에게도 그렇게 안내하면 안 된다. 2026-08-28 에 axmap-cli 로 정했다 — 스코프(@사용자/이름)를 쓰지 않는 이유는 스코프가 npm 계정 이름에 묶여서 나중에 팀이나 조직으로 옮길 때 이름이 통째로 바뀌기 때문이다. 사람이 치는 **명령** 이름은 그대로 axmap 이다 (아래 bin) — 꾸러미 이름과 명령 이름은 달라도 된다.",
   "name": "axmap-cli",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "axMap — AI Experience 의 지도이자 개발 환경의 AI Transformation. AI 에이전트들이 서로의 작업 영역을 침범하지 않도록, 코드 충돌 대신 의도 충돌을 먼저 터뜨리는 git 위의 선점 프로토콜",
+  "description": "Coordinate AI agents in Git with path claims, messaging, commit verification and MCP.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,13 +26,12 @@
   "bin": {
     "axmap": "bin/axmap.mjs"
   },
-  "//files": "npm 꾸러미에 들어갈 것. 이 목록이 없으면 벤치 산출물·데모·테스트까지 실려 꾸러미가 수십 MB 가 된다. 여기서 빼는 것들(test·demo·corpus·desktop·docs)은 설치한 사람에게 필요 없다 — 그건 이 저장소를 clone 한 사람의 것이다.",
+  "//files": "Published CLI, MCP, collaboration tools and shared runtime sources. Development tests and documentation stay in the source repository.",
   "files": [
     "bin/",
     "src/",
     "mcp/",
     "tools/",
-    "app/",
     "governance/",
     ".claude/",
     "CLAUDE.md"
@@ -42,13 +41,7 @@
     "setup": "node tools/setup.mjs",
     "demo": "bash demo/run-demo.sh",
     "demo:compare": "bash demo/conflict-vs-parser.sh",
-    "demo:chaos": "bash demo/chaos.sh",
-    "app": "node app/server.mjs",
-    "smoke": "node tools/smoke.mjs",
-    "desktop": "npm --prefix desktop start",
-    "desktop:smoke": "npm --prefix desktop run selftest",
-    "dist": "npm --prefix desktop run dist",
-    "shortcut": "node tools/shortcut.mjs --dev"
+    "demo:chaos": "bash demo/chaos.sh"
   },
   "engines": {
     "node": ">=20"
@@ -56,5 +49,8 @@
   "homepage": "https://github.com/rl2aderjoon/axmap#readme",
   "bugs": {
     "url": "https://github.com/rl2aderjoon/axmap/issues"
+  },
+  "dependencies": {
+    "node-pty": "npm:@lydell/node-pty@1.1.0"
   }
 }

package/src/agentcli.mjs

@@ -0,0 +1,19 @@
+/** AI CLI executable discovery shared by setup and MCP registration. */
+import { spawnSync } from 'node:child_process'
+
+export const AGENTS = [
+  { id: 'claude', name: 'Claude Code', bin: 'claude' },
+  { id: 'agy', name: 'Antigravity', bin: 'agy' },
+  { id: 'codex', name: 'Codex CLI', bin: 'codex' },
+]
+
+/** Resolve the executable without a shell so paths and arguments stay intact. */
+export function resolveBin(bin) {
+  try {
+    const r = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', [bin], {
+      encoding: 'utf8', windowsHide: true,
+    })
+    if (r.status !== 0) return null
+    return r.stdout.split(/\r?\n/).map(s => s.trim()).find(Boolean) || null
+  } catch { return null }
+}

package/src/bridge.mjs

@@ -0,0 +1,257 @@
+/** Local sessions are attached by the provider's own hooks. Sending a message
+ * must never silently create/resume a second model process. */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { withRepoLock } from './repolock.mjs'
+import { submitConsole, checkConsole, validateConsolePrompt, findConsoleTranscript, externalStatus } from './external-console.mjs'
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const bridgeHome = () => path.join(process.env.AXMAP_STATE_DIR || path.join(os.homedir(), '.axmap'), 'bridge')
+const agyHome = () => process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli')
+const file = (kind, id) => {
+  if (!UUID.test(id || '')) throw new Error('세션/요청 ID는 UUID여야 합니다.')
+  return path.join(bridgeHome(), kind, `${id}.json`)
+}
+function readJSON(p) { return JSON.parse(fs.readFileSync(p, 'utf8')) }
+function writeJSON(p, data) {
+  fs.mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 })
+  const tmp = `${p}.${randomUUID()}.tmp`
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
+    fs.renameSync(tmp, p)
+  } finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp) }
+}
+function repoKey(cwd) {
+  const r = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    cwd, encoding: 'utf8', windowsHide: true,
+  })
+  if (r.status !== 0) throw new Error(`Git 작업 저장소를 확인하지 못했습니다: ${cwd}`)
+  const key = fs.realpathSync(r.stdout.trim())
+  return process.platform === 'win32' ? key.toLowerCase() : key
+}
+function addressError(address) {
+  // Only a loopback address exported by a local provider hook is accepted.
+  if (typeof address !== 'string' || !/^(?:https?:\/\/)?(?:127\.0\.0\.1|localhost|\[::1\]):[0-9]{1,5}$/.test(address)) {
+    throw new Error('공식 훅에서 받은 로컬 ANTIGRAVITY_LS_ADDRESS가 필요합니다.')
+  }
+  const port = Number(address.slice(address.lastIndexOf(':') + 1))
+  if (port < 1 || port > 65535) throw new Error('연결 포트가 잘못되었습니다.')
+}
+function runAPI(session, args) {
+  addressError(session.address)
+  const r = spawnSync(session.executable, ['agentapi', ...args], {
+    cwd: session.workspaces[0],
+    env: { ...process.env, ANTIGRAVITY_LS_ADDRESS: session.address },
+    encoding: 'utf8', windowsHide: true, timeout: 15000, maxBuffer: 1024 * 1024,
+  })
+  if (r.error || r.status !== 0) throw new Error(`열린 세션 연결 실패: ${r.error?.message || r.stderr?.trim() || r.stdout?.trim() || r.status}`)
+  const text = r.stdout.trim()
+  if (text) {
+    let data
+    try { data = JSON.parse(text) } catch { return text }
+    if (data?.error) throw new Error(`열린 세션 연결 실패: ${JSON.stringify(data.error)}`)
+    return data
+  }
+  return null
+}
+function transcript(session) {
+  const expected = path.join(agyHome(), 'brain', session.conversationId || session.id, '.system_generated', 'logs', 'transcript.jsonl')
+  if (session.transcript !== expected) throw new Error('등록된 대화 기록 경로가 올바르지 않습니다.')
+  const lines = fs.readFileSync(expected, 'utf8').split('\n')
+  // A trailing incomplete record may be in flight; malformed complete records fail.
+  lines.pop()
+  return lines.filter(s => s.trim()).map(s => JSON.parse(s))
+}
+function publicSession(s) {
+  return { id: s.id, provider: s.provider, workspaces: s.workspaces, model: s.model,
+    transport: s.transport || 'agentapi', state: s.state, pid: s.pid,
+    registeredAt: s.registeredAt, event: s.event, fullyIdle: s.fullyIdle,
+    role: s.role, usage: s.usage, usageKnown: s.usageKnown, maxTokens: s.maxTokens, pendingApproval: s.pendingApproval }
+}
+export function sessions(cwd) {
+  const dir = path.join(bridgeHome(), 'sessions')
+  if (!fs.existsSync(dir)) return []
+  const repo = repoKey(cwd)
+  return fs.readdirSync(dir).filter(n => UUID.test(n.replace(/\.json$/, '')) && n.endsWith('.json'))
+    .map(n => readJSON(path.join(dir, n))).filter(s => s.repos.includes(repo)).map(publicSession)
+}
+function sessionFor(id, cwd) {
+  const s = readJSON(file('sessions', id))
+  if (!s.repos.includes(repoKey(cwd))) throw new Error('이 세션은 현재 작업 저장소에 등록되지 않았습니다.')
+  if (s.provider !== 'agy' && !['pty', 'stdio'].includes(s.transport)) throw new Error('아직 지원하지 않는 수신 세션입니다.')
+  return s
+}
+
+/** Hook input and env come from Antigravity, not a remote message or repo file. */
+export function registerHook(input, event, env = process.env) {
+  if (!['SessionStart', 'PreInvocation', 'Stop'].includes(event)) throw new Error('지원하지 않는 훅 이벤트입니다.')
+  addressError(env.ANTIGRAVITY_LS_ADDRESS)
+  const id = input.conversationId
+  const target = file('sessions', id)
+  const workspaces = input.workspacePaths
+  if (!Array.isArray(workspaces) || !workspaces.length || workspaces.some(p => !path.isAbsolute(p))) {
+    throw new Error('훅의 작업 저장소 경로가 없습니다.')
+  }
+  const executable = env.AXMAP_AGY_EXECUTABLE
+  if (!executable || !path.isAbsolute(executable) || !fs.existsSync(executable)) throw new Error('등록된 agy 실행 파일이 없습니다.')
+  const expected = path.join(agyHome(), 'brain', id, '.system_generated', 'logs', 'transcript.jsonl')
+  if (path.resolve(input.transcriptPath || '') !== expected) throw new Error('Antigravity CLI 대화 기록 경로가 아닙니다.')
+  const s = { id, provider: 'agy', executable, address: env.ANTIGRAVITY_LS_ADDRESS,
+    transcript: expected, workspaces, repos: [...new Set(workspaces.map(repoKey))], model: input.modelName || null,
+    registeredAt: new Date().toISOString(), event, fullyIdle: event === 'Stop' && input.fullyIdle === true }
+  writeJSON(target, s)
+  return publicSession(s)
+}
+
+export function requestResult(id, cwd) {
+  const target = file('requests', id)
+  const request = readJSON(target)
+  if (request.repo !== repoKey(cwd)) throw new Error('이 요청은 현재 작업 저장소의 요청이 아닙니다.')
+  if (!['submitted', 'unknown'].includes(request.state)) return request
+  let s = sessionFor(request.to, cwd)
+  if (['pty', 'stdio'].includes(s.transport)) {
+    try { Object.assign(request, terminalRPC(s.id, { action: 'result', id })) }
+    catch (e) { request.state = 'unknown'; request.error = e.message }
+    writeJSON(target, request)
+    return request
+  }
+  if (s.transport === 'console') {
+    try { s.fullyIdle = externalStatus(s).state === 'idle' }
+    catch (e) {
+      request.state = 'unknown'; request.error = e.message
+      writeJSON(target, request)
+      return request
+    }
+    s = findConsoleTranscript(s, request)
+    if (!s.transcript) return request
+  }
+  const entries = transcript(s)
+  const marker = `[axMap request ${id}]`
+  const start = entries.findIndex((e, i) => i >= request.baseline && e.type === 'USER_INPUT' && String(e.content).includes(marker))
+  if (start < 0) return request
+  const tail = entries.slice(start + 1)
+  if (tail.some(e => e.type === 'USER_INPUT')) {
+    request.state = 'superseded'
+    request.error = '다른 사용자 입력이 이어져 이 요청의 완료를 확정할 수 없습니다.'
+  } else if (s.transport === 'console' ? s.fullyIdle : s.event === 'Stop' && s.fullyIdle && s.registeredAt > request.createdAt) {
+    const answer = tail.filter(e => e.source === 'MODEL' && e.type === 'PLANNER_RESPONSE' && e.status === 'DONE').at(-1)
+    if (answer) {
+      request.state = 'completed'
+      request.result = answer.content
+      request.completedAt = s.transport === 'console' ? new Date().toISOString() : s.registeredAt
+    }
+  }
+  if (['completed', 'superseded'].includes(request.state)) writeJSON(target, request)
+  return request
+}
+
+export function sessionLeasePath(id) {
+  if (!UUID.test(id || '')) throw new Error('세션 ID는 UUID여야 합니다.')
+  return path.join(bridgeHome(), 'dialogues', `session-${id}.lock`)
+}
+
+export function dispatchRequest({ to, prompt, cwd, from = 'axmap', dialogueId = null }) {
+  if (typeof prompt !== 'string' || !prompt.trim() || Buffer.byteLength(prompt) > 32768) throw new Error('요청 본문은 1~32768바이트여야 합니다.')
+  const s = sessionFor(to, cwd)
+  const lease = sessionLeasePath(to)
+  if (fs.existsSync(lease) && readJSON(lease).dialogueId !== dialogueId) throw new Error('이 세션은 자동 대화가 사용 중입니다. 해당 대화가 끝난 뒤 요청하세요.')
+  const dir = path.join(bridgeHome(), 'requests')
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return withRepoLock(path.join(dir, `${to}.lock`), () => {
+    if (fs.existsSync(lease) && readJSON(lease).dialogueId !== dialogueId) throw new Error('이 세션은 자동 대화가 사용 중입니다.')
+    for (const n of fs.readdirSync(dir).filter(n => n.endsWith('.json'))) {
+      const previous = readJSON(path.join(dir, n))
+      if (previous.to !== to || !['sending', 'submitted', 'unknown'].includes(previous.state)) continue
+      const latest = previous.state === 'sending' ? previous : requestResult(previous.id, cwd)
+      if (['sending', 'submitted', 'unknown'].includes(latest.state)) throw new Error(`이 세션의 이전 요청이 아직 확정되지 않았습니다: ${latest.id}`)
+    }
+    // No fallback to `agy -p` or --conversation: both would start a separate process.
+    if (s.transport === 'console') { validateConsolePrompt(prompt, from); checkConsole(s) }
+    if (!['pty', 'stdio', 'console'].includes(s.transport)) {
+      runAPI(s, ['get-conversation-metadata', to])
+      if (!s.fullyIdle || s.event !== 'Stop') throw new Error('상대 세션의 대기 상태를 아직 확인하지 못했습니다. 작업 종료 훅을 기다리세요.')
+    }
+    const request = { id: randomUUID(), to, from, repo: repoKey(cwd), prompt,
+      createdAt: new Date().toISOString(), baseline: ['pty', 'stdio'].includes(s.transport) ? null : s.transcript ? transcript(s).length : 0, state: 'sending' }
+    const target = file('requests', request.id)
+    writeJSON(target, request)
+    try {
+      request.receipt = s.transport === 'console' ? submitConsole(s, request) : ['pty', 'stdio'].includes(s.transport)
+        ? terminalRPC(to, { action: 'submit', request })
+        : runAPI(s, ['send-message', to, `[axMap request ${request.id}]\n요청자: ${from}\n${prompt}`])
+      request.state = 'submitted'
+    } catch (e) {
+      // A timeout may occur after delivery. Never retry automatically.
+      request.state = 'unknown'
+      request.error = e.message
+    }
+    writeJSON(target, request)
+    return request
+  })
+}
+
+function terminalRPC(id, message) {
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'tools', 'run.mjs'), 'rpc', id], {
+    input: JSON.stringify(message), encoding: 'utf8', windowsHide: true, timeout: 15000,
+  })
+  if (r.error || r.status !== 0) throw new Error(r.error?.message || r.stderr?.trim() || '터미널 세션에 연결하지 못했습니다.')
+  return JSON.parse(r.stdout)
+}
+
+export { bridgeHome, repoKey, readJSON, writeJSON }
+
+export function uninstallHooks(home = os.homedir()) {
+  const target = path.join(home, '.gemini', 'config', 'hooks.json')
+  if (!fs.existsSync(target)) return { removed: false }
+  const config = readJSON(target)
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('기존 hooks.json이 객체가 아닙니다. 변경하지 않았습니다.')
+  if (!Object.hasOwn(config, 'axmap-bridge')) return { removed: false }
+  delete config['axmap-bridge']
+  writeJSON(target, config)
+  // A running provider can retain the old hook command until exit. Make its
+  // wrapper harmless immediately, without requiring another session restart.
+  if (process.platform === 'win32') {
+    for (const event of ['SessionStart', 'PreInvocation', 'Stop']) {
+      const wrapper = path.join(home, '.axmap', 'bridge', `agy-${event}.cmd`)
+      if (fs.existsSync(wrapper)) fs.writeFileSync(wrapper, '@echo off\r\necho {}\r\n')
+    }
+  }
+  return { removed: true, hooks: target, note: '다른 훅은 유지합니다. 기존 CLI에 캐시된 훅은 정상 종료 시 해제됩니다.' }
+}
+
+export function installHooks({ executable, home = os.homedir() }) {
+  if (!path.isAbsolute(executable || '') || !fs.existsSync(executable)) throw new Error('agy 실행 파일의 절대 경로가 필요합니다.')
+  const target = path.join(home, '.gemini', 'config', 'hooks.json')
+  const original = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null
+  const config = original === null ? {} : JSON.parse(original)
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('기존 hooks.json이 객체가 아닙니다. 변경하지 않았습니다.')
+  const script = path.join(ROOT, 'tools', 'bridge.mjs')
+  if ([process.execPath, script, executable].some(s => /["\r\n%&|<>^]/.test(s))) throw new Error('훅 명령 경로에 지원하지 않는 셸 문자가 있습니다.')
+  const definition = {}
+  for (const event of ['SessionStart', 'PreInvocation', 'Stop']) {
+    let command = `"${process.execPath}" "${script}" hook --event ${event} --executable "${executable}"`
+    if (process.platform === 'win32') {
+      // Antigravity's command runner escapes a quoted executable incorrectly on
+      // Windows. A bare .cmd entry point matches its documented hook examples;
+      // quotes inside the wrapper are interpreted by cmd, not its command parser.
+      const wrapper = path.join(home, '.axmap', 'bridge', `agy-${event}.cmd`)
+      if (/[\s"%&|<>^]/.test(wrapper)) throw new Error('Windows 훅 실행 경로에는 공백이나 셸 특수 문자가 없어야 합니다. 설정을 변경하지 않았습니다.')
+      fs.mkdirSync(path.dirname(wrapper), { recursive: true })
+      fs.writeFileSync(wrapper, `@echo off\r\n${command}\r\n`, { mode: 0o600 })
+      command = wrapper
+    }
+    definition[event] = [{ type: 'command', command, timeout: 10 }]
+  }
+  config['axmap-bridge'] = definition
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  const backup = `${target}.axmap-${randomUUID()}.bak`
+  if (original !== null) fs.writeFileSync(backup, original, { flag: 'wx', mode: 0o600 })
+  writeJSON(target, config)
+  return { hooks: target, backup: original === null ? null : backup,
+    note: '기존 실행 중인 CLI가 새 훅을 읽지 않으면 같은 대화를 재개해 한 번 다시 열어야 합니다. Remote Control은 필요 없습니다.' }
+}