axmap-cli 1.5.0 → 1.7.0

package/src/terminal-bridge.mts

@@ -0,0 +1,235 @@
+/** The user launches an interactive CLI. axMap owns its PTY and a local,
+ * authenticated pipe; remote requests never launch/resume another model. */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import net from 'node:net'
+import { randomUUID, randomBytes, timingSafeEqual } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs'
+import { errorCode, errorMessage } from './session-types.mjs'
+import type { IPty } from 'node-pty'
+import type { Provider, SessionRecord, LocalMessage, JobRecord, RequestState, TranscriptEntry } from './session-types.mjs'
+
+interface TerminalOptions {
+  executable: string; args?: string[]; provider: Provider; cwd?: string; onData?: (data: string) => void; cols?: number; rows?: number
+}
+interface CommandHook { type: string; command: string; timeout: number; statusMessage?: string }
+interface HookGroup { hooks?: Array<{ statusMessage?: string; [key: string]: unknown }>; [key: string]: unknown }
+interface HookConfig { hooks?: Record<string, HookGroup[]>; [key: string]: unknown }
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const validID = (id: string | undefined) => /^[0-9a-f-]{36}$/i.test(id || '')
+const sessionFile = (id: string) => {
+  if (!validID(id)) throw new Error('잘못된 터미널 세션 ID입니다.')
+  return path.join(bridgeHome(), 'sessions', `${id}.json`)
+}
+const pipeFor = (id: string) => process.platform === 'win32'
+  ? `\\\\.\\pipe\\axmap-${id}` : path.join(bridgeHome(), `${id}.sock`)
+
+export function sendTerminal(id: string, message: LocalMessage, token: string | null = null, { timeoutMs = 10000 } = {}): Promise<unknown> {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new Error('양의 응답 시간 한도가 필요합니다.')
+  const s = readJSON<SessionRecord>(sessionFile(id))
+  if (!['pty', 'stdio'].includes(s.transport || '')) throw new Error('로컬 관리형 세션이 아닙니다.')
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(pipeFor(id))
+    socket.setEncoding('utf8')
+    let buffer = ''
+    const fail = (e: Error) => { socket.destroy(); reject(e) }
+    socket.setTimeout(timeoutMs, () => fail(new Error('로컬 세션 응답 시간 초과. 자동 재전송하지 마세요.')))
+    socket.on('error', fail)
+    socket.on('connect', () => socket.write(JSON.stringify({ ...message, token: token || s.token }) + '\n'))
+    socket.on('data', chunk => {
+      buffer += chunk
+      if (Buffer.byteLength(buffer) > 1024 * 1024) return fail(new Error('로컬 응답 크기 제한 초과'))
+      const end = buffer.indexOf('\n')
+      if (end < 0) return
+      socket.end()
+      try {
+        const response = JSON.parse(buffer.slice(0, end)) as { error?: string; result?: unknown }
+        if (response.error) reject(new Error(response.error)); else resolve(response.result)
+      } catch (e) { reject(e) }
+    })
+    socket.on('end', () => { if (!buffer.includes('\n')) reject(new Error('세션 연결이 응답 없이 종료됐습니다.')) })
+  })
+}
+
+export async function startTerminal({ executable, args = [], provider, cwd = process.cwd(), onData = () => {}, cols = 100, rows = 30 }: TerminalOptions) {
+  const { spawn } = await import('node-pty')
+  const id = randomUUID(), token = randomBytes(32).toString('hex')
+  const s: SessionRecord = { id, provider, transport: 'pty', token, workspaces: [cwd], repos: [repoKey(cwd)],
+    state: 'starting', fullyIdle: false, registeredAt: new Date().toISOString(), event: 'launch' }
+  const jobs = new Map<string, JobRecord>()
+  let pending: JobRecord | null = null, draft = false, term: IPty, closed = false, stopTimer: NodeJS.Timeout | undefined
+  const save = () => { s.registeredAt = new Date().toISOString(); writeJSON(sessionFile(id), s) }
+  const finish = (state: RequestState, result?: unknown, error?: string) => {
+    if (!pending) return
+    Object.assign(pending, { state, result, error, completedAt: new Date().toISOString() })
+    jobs.set(pending.id, { ...pending }); pending = null
+  }
+  const handle = (message: LocalMessage) => {
+    const offered = Buffer.from(typeof message.token === 'string' ? message.token : '')
+    const expected = Buffer.from(token)
+    if (offered.length !== expected.length || !timingSafeEqual(offered, expected)) throw new Error('로컬 세션 인증 실패')
+    if (message.action === 'status') return { state: s.state, id, provider }
+    if (message.action === 'result') {
+      const job = jobs.get(message.id)
+      if (!job) throw new Error('이 터미널에 해당 요청이 없습니다.')
+      return job
+    }
+    if (message.action === 'hook') {
+      clearTimeout(stopTimer)
+      const { input, event } = message
+      s.event = event; s.model = input.modelName || input.model || s.model
+      s.conversationId = input.conversationId || input.session_id || s.conversationId
+      if (event !== 'Stop') {
+        s.state = 'running'; s.fullyIdle = false
+        if (pending && event === 'UserPromptSubmit' && typeof input.prompt === 'string') {
+          pending.observed = input.prompt.includes(`[axMap request ${pending.id}]`)
+        }
+        save(); return {}
+      }
+      if (provider === 'agy' && input.fullyIdle !== true) { save(); return {} }
+      let answer = input.last_assistant_message
+      if (provider === 'agy') {
+        const log = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'),
+          'brain', s.conversationId || '', '.system_generated', 'logs', 'transcript.jsonl')
+        if (path.resolve(input.transcriptPath || '') !== log) throw new Error('종료 훅의 대화 기록 경로가 다릅니다.')
+        const lines = fs.readFileSync(log, 'utf8').trimEnd().split('\n').filter(Boolean).map(line => JSON.parse(line) as TranscriptEntry)
+        const lastUser = lines.findLast(e => e.type === 'USER_INPUT')
+        if (pending) pending.observed = String(lastUser?.content).includes(`[axMap request ${pending.id}]`)
+        answer = lines.findLast(e => e.type === 'PLANNER_RESPONSE' && e.source === 'MODEL' && e.status === 'DONE')?.content
+      }
+      if (pending) finish(pending.observed && !pending.interrupted && typeof answer === 'string' ? 'completed' : 'superseded',
+        pending.observed && !pending.interrupted ? answer : undefined,
+        pending.observed && !pending.interrupted ? undefined : '다른 입력이 섞였거나 이 요청의 응답을 확인하지 못했습니다.')
+      // Stop runs before the provider restores its input UI. Allow that handoff
+      // to finish before accepting another injected prompt.
+      s.state = 'settling'; s.fullyIdle = false; save()
+      stopTimer = setTimeout(() => { if (!closed && s.state === 'settling') { s.state = 'idle'; s.fullyIdle = true; draft = false; save() } }, 500)
+      return {}
+    }
+    if (message.action === 'submit') {
+      const request = message.request
+      if (closed || s.state !== 'idle' || draft || pending) throw new Error('상대가 대기 중이 아니거나 입력 중입니다. 작업을 전달하지 않았습니다.')
+      if (!validID(request?.id) || request.to !== id || typeof request.prompt !== 'string' || !request.prompt.trim() || Buffer.byteLength(request.prompt) > 32768) throw new Error('요청 형식이 올바르지 않습니다.')
+      const prompt = `[axMap request ${request.id}]\n요청자: ${String(request.from || 'axmap')}\n${request.prompt}`
+      if (/[\x00-\x08\x0b-\x1f\x7f]/.test(prompt)) throw new Error('터미널 제어 문자가 포함된 요청은 보낼 수 없습니다.')
+      pending = { id: request.id, to: id, state: 'submitted' }; jobs.set(request.id, pending)
+      s.state = 'running'; s.fullyIdle = false; save()
+      term.write(`\x1b[200~${prompt}\x1b[201~`)
+      setTimeout(() => { if (!closed) term.write('\r') }, 100)
+      return { accepted: true, session: id }
+    }
+    throw new Error('지원하지 않는 로컬 세션 요청입니다.')
+  }
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 })
+  const server = net.createServer(socket => {
+    socket.setEncoding('utf8')
+    let buffer = '', handled = false
+    socket.setTimeout(15000, () => socket.destroy())
+    socket.on('error', () => {})
+    socket.on('data', chunk => {
+      if (handled) return
+      buffer += chunk
+      if (Buffer.byteLength(buffer) > 65536) return socket.destroy()
+      const end = buffer.indexOf('\n'); if (end < 0) return
+      handled = true
+      try { socket.end(JSON.stringify({ result: handle(JSON.parse(buffer.slice(0, end))) }) + '\n') }
+      catch (e) { socket.end(JSON.stringify({ error: errorMessage(e) }) + '\n') }
+    })
+  })
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(pipeFor(id), resolve) })
+  if (process.platform !== 'win32') fs.chmodSync(pipeFor(id), 0o600)
+  save()
+  try {
+    term = spawn(executable, args, { name: 'xterm-256color', cols, rows, cwd, env: { ...process.env,
+      AXMAP_TERMINAL_SESSION: id, AXMAP_TERMINAL_TOKEN: token,
+      AXMAP_AGENT: `${provider}-${id.slice(0, 8)}`, AXMAP_SESSION: id,
+    }, useConpty: true, useConptyDll: process.platform === 'win32' })
+  } catch (e) { server.close(); s.state = 'closed'; save(); throw e }
+  term.onData(onData)
+  const exited = new Promise<{ exitCode: number; signal?: number }>(resolve => term.onExit(ev => {
+    if (closed) return
+    closed = true; clearTimeout(stopTimer)
+    // ConPTY may keep its input handle alive after a normal child exit.
+    if (process.platform === 'win32') { try { term.kill() } catch { /* already closed */ } }
+    finish('unknown', undefined, '요청의 완료를 확인하기 전에 세션이 종료됐습니다.')
+    s.state = 'closed'; s.fullyIdle = false; save(); server.close(); resolve(ev)
+  }))
+  return { id, pid: term.pid, exited,
+    input(data: string) {
+      const terminalReply = /^\x1b\[(?:\d+;\d+R|\?[^a-zA-Z]*[a-zA-Z])$/.test(String(data))
+      if (terminalReply) { term.write(data); return }
+      if (pending) pending.interrupted = true
+      draft = !String(data).includes('\r')
+      if (!draft) { s.state = 'running'; s.fullyIdle = false; save() }
+      term.write(data)
+    },
+    resize: (c: number, r: number) => term.resize(c, r),
+    close: () => term.kill(),
+  }
+}
+
+/** Copy only production dependencies from the npm package, not a developer's
+ * entire node_modules. This also keeps the setup copy independent of npm cache. */
+export function installTerminalRuntime(sourceRoot: string, destRoot = ROOT) {
+  const source = path.resolve(sourceRoot), dest = path.resolve(destRoot)
+  const require = createRequire(path.join(source, 'package.json'))
+  const copied = new Set<string>()
+  function copy(name: string): void {
+    if (copied.has(name)) return
+    const descriptor = require.resolve(`${name}/package.json`)
+    const pkg = readJSON<{ dependencies?: Record<string, string>; optionalDependencies?: Record<string, string> }>(descriptor)
+    const target = path.join(dest, 'node_modules', ...name.split('/'))
+    if (path.resolve(path.dirname(descriptor)) !== path.resolve(target)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.cpSync(path.dirname(descriptor), target, { recursive: true, force: true })
+    }
+    copied.add(name)
+    for (const dependency of Object.keys(pkg.dependencies || {})) copy(dependency)
+    for (const dependency of Object.keys(pkg.optionalDependencies || {})) {
+      try { require.resolve(`${dependency}/package.json`) }
+      catch (e) { if (errorCode(e) === 'MODULE_NOT_FOUND') continue; throw e }
+      copy(dependency)
+    }
+  }
+  copy('node-pty')
+  const installed = createRequire(path.join(dest, 'package.json'))('node-pty')
+  if (typeof installed.spawn !== 'function') throw new Error('설치된 터미널 라이브러리를 불러오지 못했습니다.')
+  return { packages: [...copied], destination: dest }
+}
+
+export function installTerminalHooks(home = os.homedir(), provider = 'agy') {
+  if (!['agy', 'codex'].includes(provider)) throw new Error('지원하지 않는 CLI 훅입니다.')
+  const target = provider === 'agy' ? path.join(home, '.gemini', 'config', 'hooks.json')
+    : path.join(home, '.codex', 'hooks.json')
+  const config = fs.existsSync(target) ? readJSON<HookConfig>(target) : {}
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('기존 hooks.json을 읽지 못했습니다.')
+  if (provider === 'codex' && config.hooks !== undefined && (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks))) throw new Error('기존 Codex hooks 설정이 객체가 아닙니다.')
+  const definition: Record<string, CommandHook[]> = {}
+  const script = path.join(ROOT, 'tools', 'run.mjs')
+  if ([process.execPath, script].some(p => /["\r\n%&|<>^]/.test(p))) throw new Error('훅 경로에 지원하지 않는 셸 문자가 있습니다.')
+  for (const event of provider === 'agy' ? ['SessionStart', 'PreInvocation', 'Stop'] : ['SessionStart', 'UserPromptSubmit', 'Stop']) {
+    let command = `"${process.execPath}" "${script}" hook ${event}`
+    if (process.platform === 'win32') {
+      const wrapper = path.join(home, '.axmap', 'bridge', `terminal-${provider}-${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`)
+      command = wrapper
+    }
+    if (provider === 'agy') definition[event] = [{ type: 'command', command, timeout: 10 }]
+    else {
+      config.hooks ||= {}
+      const existing = config.hooks[event] || []
+      if (!Array.isArray(existing)) throw new Error(`기존 Codex ${event} 설정이 배열이 아닙니다.`)
+      config.hooks[event] = existing.filter(group => !(Array.isArray(group.hooks) && group.hooks.some(h => h.statusMessage === 'axMap terminal bridge')))
+      config.hooks[event].push({ hooks: [{ type: 'command', command, timeout: 10, statusMessage: 'axMap terminal bridge' }] })
+    }
+  }
+  if (provider === 'agy') config['axmap-terminal'] = definition
+  writeJSON(target, config)
+  return target
+}

package/src/windows-console.mjs

@@ -0,0 +1,42 @@
+// Generated from src/windows-console.mts. Edit the .mts source and run npm run build.
+/** Cache a framework-only native helper; machines without csc keep the PS path. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const source = fileURLToPath(new URL('../tools/windows-console.cs', import.meta.url));
+export function nativeConsoleHelper() {
+    if (process.platform !== 'win32' || process.env.AXMAP_CONSOLE_HELPER === 'powershell')
+        return null;
+    const framework = path.join(process.env.WINDIR || 'C:\\Windows', 'Microsoft.NET');
+    const compiler = ['Framework64', 'Framework'].map(p => path.join(framework, p, 'v4.0.30319', 'csc.exe')).find(p => fs.existsSync(p));
+    if (!compiler || !fs.existsSync(source))
+        return null;
+    const hash = createHash('sha256').update(fs.readFileSync(source)).digest('hex').slice(0, 24);
+    const dir = path.join(process.env.AXMAP_STATE_DIR || path.join(os.homedir(), '.axmap'), 'bridge', 'native');
+    const executable = path.join(dir, `console-${hash}.exe`);
+    if (fs.existsSync(executable))
+        return executable;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const temporary = path.join(dir, `${hash}-${randomUUID()}.exe`);
+    try {
+        const r = spawnSync(compiler, ['/nologo', '/optimize+', '/target:exe', '/reference:System.Web.Extensions.dll',
+            '/reference:System.Management.dll', `/out:${temporary}`, source], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
+        if (r.error || r.status !== 0)
+            return null;
+        try {
+            fs.renameSync(temporary, executable);
+        }
+        catch (e) {
+            if (!fs.existsSync(executable))
+                throw e;
+        }
+        return executable;
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}

package/src/windows-console.mts

@@ -0,0 +1,29 @@
+/** Cache a framework-only native helper; machines without csc keep the PS path. */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const source = fileURLToPath(new URL('../tools/windows-console.cs', import.meta.url))
+export function nativeConsoleHelper() {
+  if (process.platform !== 'win32' || process.env.AXMAP_CONSOLE_HELPER === 'powershell') return null
+  const framework = path.join(process.env.WINDIR || 'C:\\Windows', 'Microsoft.NET')
+  const compiler = ['Framework64', 'Framework'].map(p => path.join(framework, p, 'v4.0.30319', 'csc.exe')).find(p => fs.existsSync(p))
+  if (!compiler || !fs.existsSync(source)) return null
+  const hash = createHash('sha256').update(fs.readFileSync(source)).digest('hex').slice(0, 24)
+  const dir = path.join(process.env.AXMAP_STATE_DIR || path.join(os.homedir(), '.axmap'), 'bridge', 'native')
+  const executable = path.join(dir, `console-${hash}.exe`)
+  if (fs.existsSync(executable)) return executable
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const temporary = path.join(dir, `${hash}-${randomUUID()}.exe`)
+  try {
+    const r = spawnSync(compiler, ['/nologo', '/optimize+', '/target:exe', '/reference:System.Web.Extensions.dll',
+      '/reference:System.Management.dll', `/out:${temporary}`, source], { encoding: 'utf8', windowsHide: true, timeout: 15000 })
+    if (r.error || r.status !== 0) return null
+    try { fs.renameSync(temporary, executable) }
+    catch (e) { if (!fs.existsSync(executable)) throw e }
+    return executable
+  } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary) }
+}

package/tools/bench-console.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/** Explicitly invoked real-console benchmark. Sends only the listed test prompts. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { consoleCall, attachConsole } from '../src/external-console.mjs'
+import { dispatchRequest, waitForRequest } from '../src/bridge.mjs'
+import { nativeConsoleHelper } from '../src/windows-console.mjs'
+
+const args = process.argv.slice(2)
+const option = n => { const i = args.indexOf(`--${n}`); return i < 0 ? undefined : args[i + 1] }
+const pid = Number(option('pid'))
+if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('Usage: node tools/bench-console.mjs --pid <agy PID> [--output file]')
+if (!nativeConsoleHelper()) throw new Error('Native helper is unavailable; refusing to label fallback timings as native.')
+const originalMode = process.env.AXMAP_CONSOLE_HELPER
+const report = { measuredAt: new Date().toISOString(), platform: process.platform, node: process.version,
+  pid, cwd: process.cwd(), snapshots: {}, requests: [], safetyChecks: {} }
+const median = values => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)]
+try {
+  for (const mode of ['powershell', 'native']) {
+    if (mode === 'powershell') process.env.AXMAP_CONSOLE_HELPER = mode
+    else delete process.env.AXMAP_CONSOLE_HELPER
+    const samples = []
+    for (let i = 0; i < 7; i++) {
+      const start = performance.now()
+      consoleCall(pid)
+      samples.push(Number((performance.now() - start).toFixed(2)))
+    }
+    report.snapshots[mode] = { samplesMs: samples, medianMs: median(samples) }
+    console.log(JSON.stringify({ event: 'snapshots', mode, ...report.snapshots[mode] }))
+  }
+  const live = consoleCall(pid)
+  report.startedAt = live.startedAt
+  for (const [name, payload] of Object.entries({ changedIdentity: { startedAt: 'invalid' }, changedScreen: { startedAt: live.startedAt, expectedScreen: 'invalid', text: 'MUST_NOT_BE_SENT' } })) {
+    try { consoleCall(pid, name === 'changedScreen' ? 'send' : 'snapshot', payload); throw new Error('Safety rejection missing') }
+    catch (e) {
+      const expected = name === 'changedScreen' ? /Console changed/ : /identity changed/
+      if (!expected.test(e.message)) throw e
+      report.safetyChecks[name] = e.message
+    }
+  }
+  const session = attachConsole({ pid, cwd: process.cwd() })
+  report.sessionId = session.id
+  const memory = randomUUID().slice(0, 8)
+  const prompts = [
+    { prompt: `Transport latency test 1. Remember the code ${memory} for the next message. Do not use tools, MCP, commands or files. Reply in this chat with exactly: AXMAP_LATENCY_READY`, expected: 'AXMAP_LATENCY_READY' },
+    { prompt: 'Transport latency test 2. Do not use tools, MCP, commands or files. Reply in this chat with only the code I asked you to remember in the previous message.', expected: memory },
+    { prompt: 'Transport latency test 3 (Unicode). Do not use tools, MCP, commands or files. Reply in this chat with exactly: 한글_왕복_OK', expected: '한글_왕복_OK' },
+  ]
+  for (const { prompt, expected } of prompts) {
+    const start = performance.now()
+    const request = dispatchRequest({ to: session.id, cwd: process.cwd(), from: 'codex-latency-benchmark', prompt })
+    const dispatchMs = performance.now() - start
+    const result = await waitForRequest(request.id, process.cwd(), 30000)
+    const entry = { id: request.id, dispatchMs: Number(dispatchMs.toFixed(2)), roundTripMs: Number((performance.now() - start).toFixed(2)),
+      state: result.state, expected, result: result.result, passed: result.state === 'completed' && String(result.result).includes(expected) }
+    report.requests.push(entry)
+    console.log(JSON.stringify({ event: 'reply', ...entry }))
+    if (!entry.passed) { process.exitCode = 1; break }
+  }
+  report.snapshotSpeedup = Number((report.snapshots.powershell.medianMs / report.snapshots.native.medianMs).toFixed(2))
+  if (option('output')) {
+    const output = path.resolve(option('output'))
+    fs.mkdirSync(path.dirname(output), { recursive: true })
+    fs.writeFileSync(output, JSON.stringify(report, null, 2) + '\n')
+  }
+} finally {
+  if (originalMode === undefined) delete process.env.AXMAP_CONSOLE_HELPER
+  else process.env.AXMAP_CONSOLE_HELPER = originalMode
+}

package/tools/bridge.mjs

@@ -2,12 +2,13 @@
 import fs from 'node:fs'
 import { resolveBin } from '../src/agentcli.mjs'
 import { codexInvocation } from './mcp-register.mjs'
-import { dispatchRequest, installHooks, registerHook, requestResult, sessions, uninstallHooks } from '../src/bridge.mjs'
+import { dispatchRequest, installHooks, registerHook, waitForRequest, sessions, uninstallHooks } from '../src/bridge.mjs'
 import { startManagedSession } from '../src/managed-session.mjs'
 import { runDialogue, startBackgroundDialogue, dialogueResult, stopDialogue } from '../src/session-dialogue.mjs'
 import { sendTerminal } from '../src/terminal-bridge.mjs'
 import { sessionStatus, formatSessionStatus } from '../src/session-status.mjs'
 import { attachConsole } from '../src/external-console.mjs'
+import { postMail, collectMail, flushMail } from '../src/session-mailbox.mjs'
 
 const args = process.argv.slice(2)
 const [command] = args
@@ -15,14 +16,31 @@ const option = (name) => { const i = args.indexOf(`--${name}`); return i < 0 ? u
 const output = (value) => console.log(JSON.stringify(value, null, 2))
 try {
   switch (command) {
+    case 'message': {
+      const r = postMail({ to: option('to'), cwd: process.cwd(), text: fs.readFileSync(0, 'utf8'),
+        priority: option('priority') || 'boundary', reason: option('reason'), topic: option('topic'), key: option('key'),
+        ttlSeconds: Number(option('ttl-seconds') || 3600) })
+      output(r)
+      if (r.delivery && !['submitted', 'empty'].includes(r.delivery.state)) process.exitCode = 2
+      break
+    }
+    case 'mailbox': output(collectMail({ to: option('to'), cwd: process.cwd(), at: option('at'), take: args.includes('--take'), all: args.includes('--all') })); break
+    case 'flush': {
+      const r = flushMail({ to: option('to'), cwd: process.cwd(), at: option('at') }); output(r)
+      if (['unknown', 'deferred'].includes(r.state)) process.exitCode = 2
+      break
+    }
     case 'attach': output(attachConsole({ pid: Number(option('pid')), cwd: process.cwd() })); break
+    case 'connect':
     case 'serve': {
       const provider = args[1]
       if (!['codex', 'agy'].includes(provider)) throw new Error('axmap bridge serve codex|agy를 사용하세요.')
       const binary = resolveBin(provider)
       if (!binary) throw new Error(`${provider} 실행 파일을 찾지 못했습니다.`)
       const [executable, ...prefix] = provider === 'codex' ? codexInvocation(binary) : [binary]
+      if (command === 'connect' && (!option('thread') || !option('socket'))) throw new Error('bridge connect codex --thread <기존 UUID> --socket <로컬 경로>가 필요합니다.')
       const session = await startManagedSession({ provider, executable, prefix, model: option('model'), role: option('role'),
+        ...(command === 'connect' ? { existingThreadId: option('thread'), socketPath: option('socket'), observeActive: args.includes('--observe') } : {}),
         maxTokens: Number(option('max-tokens') || 100000), onEvent: output })
       output({ event: 'connected', ...session, exited: undefined, close: undefined })
       process.once('SIGINT', session.close); process.once('SIGTERM', session.close)
@@ -41,6 +59,7 @@ try {
       break
     }
     case 'dialogue': output(dialogueResult(args[1])); break
+    case 'notice': output(await sendTerminal(option('to'), { action: 'notice', text: fs.readFileSync(0, 'utf8') })); break
     case 'stop': output(stopDialogue(args[1])); break
     case 'answer': output(await sendTerminal(option('to'), { action: 'answer', id: option('request'), decision: option('decision') })); break
     case 'install':
@@ -64,17 +83,23 @@ try {
       break
     }
     case 'send': {
+      const waitMs = Number(option('wait-ms') || 0)
+      if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 30000) throw new Error('wait-ms는 0~30000 정수여야 합니다.')
       const r = dispatchRequest({ to: option('to'), prompt: fs.readFileSync(0, 'utf8'), cwd: process.cwd(), from: process.env.AXMAP_AGENT || 'axmap' })
-      output(r)
-      if (r.state === 'unknown') process.exitCode = 2
+      const result = waitMs && r.state === 'submitted' ? await waitForRequest(r.id, process.cwd(), waitMs) : r
+      output(result)
+      if (result.state === 'unknown') process.exitCode = 2
       break
     }
-    case 'result': output(requestResult(args[1], process.cwd())); break
+    case 'result': output(await waitForRequest(args[1], process.cwd(), Number(option('wait-ms') || 0))); break
     case undefined:
     case '--help':
       console.log(`axMap 로컬 세션 연결 — 관리형 Codex/agy와 제한된 자동 대화
 axmap bridge serve codex|agy [--model 이름] [--role 역할] [--max-tokens 100000]
     명시적으로 새 관리형 CLI를 시작합니다. 기존 창에 임의로 붙지 않습니다.
+axmap bridge connect codex --thread <기존 UUID> --socket <로컬 socket> [--role 역할] [--observe]
+    실행 중인 공식 Codex daemon의 기존 idle 대화에 연결합니다. 새 모델/대화를 만들지 않습니다.
+    --observe는 active 대화에도 관측만 연결하며 idle 전환 전에는 새 요청을 거절합니다.
 axmap bridge chat --left <UUID> --right <UUID> [--max-turns 4] [--max-tokens 50000]
     stdin 작업을 자동 중계합니다. 기본 메시지 한도 2000자, 대기 중 모델 호출 없음.
 axmap bridge answer --to <UUID> --request <ID> --decision accept|decline|cancel
@@ -85,10 +110,20 @@ axmap bridge stop <대화 UUID>                        추가 중계 중단 (이
 axmap bridge install --experimental --executable <agy 절대 경로>   연결 훅 실험
 axmap bridge uninstall                             추가한 연결 훅 해제
 axmap bridge sessions                              이 repo에 연결된 세션
+axmap bridge notice --to <UUID>                    stdin 안내를 기존 Codex 문맥에 기록 (모델 호출 없음)
 axmap bridge attach --pid <PID>                    이미 실행한 Windows agy 콘솔을 현재 repo에 연결
 axmap bridge status [--json]                        로컬 연결·작업·승인 대기·종료 상태 조회 (모델 호출 없음)
-axmap bridge send --to <세션 UUID>                  본문은 stdin. 기존 세션에 전달
-axmap bridge result <요청 UUID>                     제출/완료/불명 상태와 결과
+axmap bridge send --to <세션 UUID> [--wait-ms 30000] 본문은 stdin. 전달 후 지정 시간까지 로컬에서 회신 대기
+    send는 실행용 저수준 명령입니다. 일반 협업 알림에는 message를 사용하세요.
+axmap bridge message --to <UUID> [--topic <갱신 주제>] [--key <중복 방지 키>] [--ttl-seconds 3600]
+    stdin 일반 메시지를 큐에 저장합니다. 모델 호출·새 턴 없음. 같은 발신자의 대기 중 topic만 최신으로 합칩니다.
+axmap bridge message --to <UUID> --priority immediate --reason stop|data-loss|work-invalidated
+    긴급 사유를 보존하고 즉시 전달을 시도합니다. busy면 deferred, unknown이면 재전송 금지.
+axmap bridge mailbox --to <UUID> [--all]
+    읽기만 합니다. --take --at checkpoint로 작업 경계에서 묶음 회수 (모델 호출 없음).
+axmap bridge flush --to <UUID> --at task-complete|test-complete|experiment-complete|checkpoint
+    필요할 때만 idle 수신자에게 큐를 한 요청으로 전달. 자동 감시·중단·재전송 없음.
+axmap bridge result <요청 UUID> [--wait-ms 30000]    제출/완료/불명 상태와 결과. 대기 중 모델 호출 없음
 관리형 stdio: Codex App Server / agy stream-json. PTY와 agentapi는 별도 실험 경로입니다.`)
       break
     default: throw new Error(`알 수 없는 bridge 명령: ${command}`)

package/tools/build.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/** TS owns migrated modules; checked-in JS keeps Node 20 and vendored installs usable. */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+const check = process.argv.includes('--check')
+// The stable CLI also works with TS 7's native compiler, without an unstable API.
+const compiler = path.join(path.dirname(createRequire(import.meta.url).resolve('typescript/package.json')), 'bin', 'tsc')
+const compiled = spawnSync(process.execPath, [compiler, '--project', path.join(root, 'tsconfig.json'), '--pretty', 'false'], {
+  cwd: root, stdio: 'inherit', windowsHide: true,
+})
+if (compiled.error) throw compiled.error
+if (compiled.status !== 0) process.exit(compiled.status ?? 1)
+const outputs = []
+function collect(directory) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const source = path.join(directory, entry.name)
+    if (entry.isDirectory()) { collect(source); continue }
+    if (!entry.name.endsWith('.mts')) continue
+    const relative = path.relative(root, source).replaceAll(path.sep, '/')
+    const text = fs.readFileSync(path.join(root, '.axmap', 'tsbuild', relative.replace(/\.mts$/, '.mjs')), 'utf8')
+    outputs.push({ target: source.replace(/\.mts$/, '.mjs'),
+      content: `// Generated from ${relative}. Edit the .mts source and run npm run build.\n${text}` })
+  }
+}
+collect(path.join(root, 'src'))
+if (!outputs.length) throw new Error('TypeScript emitted no migrated modules.')
+let stale = false
+for (const { target, content } of outputs) {
+  if (fs.existsSync(target) && fs.readFileSync(target, 'utf8').replaceAll('\r\n', '\n') === content.replaceAll('\r\n', '\n')) continue
+  if (check) { console.error(`Stale generated JavaScript: ${path.relative(root, target)} (run npm run build)`); stale = true }
+  else fs.writeFileSync(target, content)
+}
+if (stale) process.exit(1)
+console.log(`${check ? 'Checked' : 'Built'} ${outputs.length} TypeScript modules.`)

package/tools/monitor.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runMonitor } from '../src/monitor-cli.mjs'
+import { errorMessage } from '../src/session-types.mjs'
+try { await runMonitor(process.argv.slice(2)) }
+catch (e) { console.error(`axMap monitor: ${errorMessage(e)}`); process.exitCode = 1 }

package/tools/pipeline.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import { runPipelineOperation } from '../src/pipeline-mcp.mjs'
+import { errorMessage } from '../src/session-types.mjs'
+import { installPipelineStatusline, pipelineStatusline } from '../src/pipeline-statusline.mjs'
+import { runMonitor } from '../src/monitor-cli.mjs'
+import { startPipelineWeb } from '../src/pipeline-web.mjs'
+const output = value => process.stdout.write(JSON.stringify(value) + '\n')
+let cancelled = false
+process.on('message', message => { if (message?.type === 'cancel-observation') cancelled = true })
+try {
+  const action = process.argv[2]
+  const option = name => { const at = process.argv.indexOf(`--${name}`); return at < 0 ? undefined : process.argv[at + 1] }
+  if (process.argv.includes('--web')) {
+    const web = await startPipelineWeb(option('cwd') || process.cwd(), Number(option('port') || 0))
+    console.log(JSON.stringify({ url: web.url, mode: 'read-only-local-pipeline' }))
+    const close = () => { void web.close() }; process.once('SIGINT', close); process.once('SIGTERM', close)
+  } else if (!action || action === 'view' || action.startsWith('--') && !['--help', '-h'].includes(action)) {
+    await runMonitor(['--graph', ...process.argv.slice(action === 'view' ? 3 : 2)])
+  } else if (action === '--help' || action === '-h') {
+    console.log('axmap pipeline [view] [--cwd <repo>] [--once | --json]\naxmap pipeline --web [--cwd <repo>] [--port <local-port>]\n세션 그래프 · 역할 · 실제 요청/응답 · 토큰 · 이벤트를 표시합니다. TTY에서는 실시간 갱신합니다.\naxmap pipeline install-statusline --provider claude|agy\naxmap pipeline uninstall-statusline --provider claude|agy\n상태줄 설치는 기존 명령을 보존하며 새 창은 열지 않습니다.\n대화 안 패널은 MCP ax_pipeline, 진행 알림은 ax_pipeline_watch를 사용하세요.')
+  } else if (action === 'install-statusline' || action === 'uninstall-statusline') {
+    console.log(JSON.stringify(installPipelineStatusline(option('provider'), option('home'), action === 'uninstall-statusline'), null, 2))
+  } else if (action === 'statusline') {
+    process.stdout.write(await pipelineStatusline(option('provider'), fs.readFileSync(0, 'utf8'), option('home')))
+  } else {
+    const args = JSON.parse(fs.readFileSync(0, 'utf8'))
+    const result = await runPipelineOperation(action, args, message => output({ type: 'progress', message }), () => cancelled)
+    output({ type: 'result', result })
+  }
+} catch (e) {
+  if (process.argv[2] === 'statusline') console.log('axMap · 상태 확인 필요')
+  else output({ type: 'result', result: { content: [{ type: 'text', text: errorMessage(e) }], isError: true } })
+} finally { if (process.connected) process.disconnect() }

package/tools/run-tests.mjs

@@ -40,9 +40,10 @@ if (files.length === 0) {
 // Windows ConPTY owns native console workers. Exercise it after other test
 // processes have exited so temporary console teardown cannot race the suite's
 // many concurrent subprocess fixtures. Both batches remain mandatory.
-const native = process.platform === 'win32' ? files.filter(f => path.basename(f) === 'terminal-bridge.test.mjs') : []
+const nativeNames = new Set(['terminal-bridge.test.mjs', 'monitor-cli.test.mjs'])
+const native = process.platform === 'win32' ? files.filter(f => nativeNames.has(path.basename(f))) : []
 const ordinary = files.filter(f => !native.includes(f))
-for (const batch of [ordinary, native].filter(batch => batch.length)) {
+for (const batch of [ordinary, ...native.map(f => [f])].filter(batch => batch.length)) {
   const r = spawnSync(process.execPath, ['--test', ...batch], { stdio: 'inherit', cwd: root })
   if (r.status !== 0) process.exit(r.status ?? 1)
 }