axmap-cli 1.4.0 → 1.6.0

package/src/bridge.mts

@@ -0,0 +1,281 @@
+/** 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'
+import { errorCode, errorMessage } from './session-types.mjs'
+import type { SessionRecord, PublicSession, RequestRecord, DispatchOptions, HookInput, TranscriptEntry } from './session-types.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: string, id: string) => {
+  if (!UUID.test(id || '')) throw new Error('세션/요청 ID는 UUID여야 합니다.')
+  return path.join(bridgeHome(), kind, `${id}.json`)
+}
+// Disk schemas are supplied by callers; invalid JSON still fails closed.
+function readJSON<T = unknown>(p: string): T { return JSON.parse(fs.readFileSync(p, 'utf8')) as T }
+function writeJSON(p: string, data: unknown): void {
+  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 })
+    // Windows readers/AV can briefly deny replacement. Keep atomic rename and
+    // a bounded retry; never unlink the old record or retry a model submission.
+    for (let attempt = 0; ; attempt++) {
+      try { fs.renameSync(tmp, p); break }
+      catch (e) {
+        if (process.platform !== 'win32' || !['EPERM', 'EBUSY'].includes(errorCode(e) || '') || attempt >= 10) throw e
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5)
+      }
+    }
+  } finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp) }
+}
+function repoKey(cwd: string): string {
+  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: unknown): asserts address is string {
+  // 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: SessionRecord, args: string[]): unknown {
+  addressError(session.address)
+  if (!session.executable) throw new Error('등록된 agy 실행 파일이 없습니다.')
+  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: { error?: unknown }
+    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: SessionRecord): TranscriptEntry[] {
+  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) as TranscriptEntry)
+}
+function publicSession(s: SessionRecord): PublicSession {
+  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: string): PublicSession[] {
+  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<SessionRecord>(path.join(dir, n))).filter(s => s.repos.includes(repo)).map(publicSession)
+}
+function sessionFor(id: string, cwd: string): SessionRecord {
+  const s = readJSON<SessionRecord>(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: HookInput, event: string, env: NodeJS.ProcessEnv = process.env): PublicSession {
+  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: SessionRecord = { 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: string, cwd: string): RequestRecord {
+  const target = file('requests', id)
+  const request = readJSON<RequestRecord>(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 = errorMessage(e) }
+    writeJSON(target, request)
+    return request
+  }
+  if (s.transport === 'console') {
+    try { s.fullyIdle = externalStatus(s).state === 'idle' }
+    catch (e) {
+      request.state = 'unknown'; request.error = errorMessage(e)
+      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 ?? 0) && 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
+}
+
+/** Wait locally, without spending model turns on repeated status tool calls. */
+export async function waitForRequest(id: string, cwd: string, timeoutMs = 30000): Promise<RequestRecord> {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 30000) throw new Error('wait-ms는 0~30000 정수여야 합니다.')
+  const deadline = performance.now() + timeoutMs
+  for (;;) {
+    const result = requestResult(id, cwd)
+    if (result.state !== 'submitted' || performance.now() >= deadline) return result
+    await new Promise(resolve => setTimeout(resolve, Math.min(100, Math.max(0, deadline - performance.now()))))
+  }
+}
+
+export function sessionLeasePath(id: string): string {
+  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 }: DispatchOptions): RequestRecord {
+  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<{ dialogueId: string }>(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<{ dialogueId: string }>(lease).dialogueId !== dialogueId) throw new Error('이 세션은 자동 대화가 사용 중입니다.')
+    for (const n of fs.readdirSync(dir).filter(n => n.endsWith('.json'))) {
+      const previous = readJSON<RequestRecord>(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.
+    let consolePreflight
+    if (s.transport === 'console') { validateConsolePrompt(prompt, from); consolePreflight = 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: RequestRecord = { 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, consolePreflight) : ['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 = errorMessage(e)
+    }
+    writeJSON(target, request)
+    return request
+  })
+}
+
+function terminalRPC(id: string, message: unknown): unknown {
+  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<Record<string, unknown>>(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() }: { executable: string; home?: string }) {
+  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: Record<string, Array<{ type: string; command: string; timeout: number }>> = {}
+  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은 필요 없습니다.' }
+}

package/src/external-console.mjs

@@ -0,0 +1,159 @@
+// Generated from src/external-console.mts. Edit the .mts source and run npm run build.
+/** Attach to an existing Windows console; never launch or resume a model. */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs';
+import { nativeConsoleHelper } from './windows-console.mjs';
+const helper = fileURLToPath(new URL('../tools/windows-console.ps1', import.meta.url));
+export function consoleCall(pid, action = 'snapshot', payload = {}) {
+    if (process.platform !== 'win32')
+        throw new Error('독립 agy 콘솔 연결은 현재 Windows에서 지원합니다.');
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new Error('양의 정수 PID가 필요합니다.');
+    const native = nativeConsoleHelper();
+    const r = spawnSync(native || 'powershell.exe', native ? [String(pid), action] : ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+        '-File', helper, '-TargetPid', String(pid), '-Action', action], {
+        input: JSON.stringify(payload), encoding: 'utf8', windowsHide: true, timeout: 8000, maxBuffer: 1024 * 1024,
+    });
+    let data;
+    try {
+        data = JSON.parse(r.stdout);
+    }
+    catch { /* report the underlying failure */ }
+    if (r.error || r.status !== 0 || data?.error || !data)
+        throw new Error(data?.error || r.error?.message || r.stderr?.trim() || '기존 콘솔 연결 실패');
+    if (action === 'ancestor' && data.ignored)
+        return { ignored: true };
+    if (typeof data.pid !== 'number' || typeof data.startedAt !== 'string' || (action !== 'ancestor' && typeof data.screen !== 'string'))
+        throw new Error('기존 콘솔 응답 형식이 올바르지 않습니다.');
+    return data;
+}
+function identityID({ pid, startedAt }) {
+    const hex = createHash('sha256').update(`agy-console:${pid}:${startedAt}`).digest('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+const target = (id) => path.join(bridgeHome(), 'sessions', `${id}.json`);
+export function consoleIdle(screen) {
+    // Use the last input box only. Old answers may contain quoted prompt boxes.
+    const borders = [...screen.matchAll(/^[─━]{10,}\r?$/gm)];
+    if (borders.length < 2)
+        return false;
+    const top = borders.at(-2), bottom = borders.at(-1);
+    if (!top || !bottom)
+        return false;
+    const input = screen.slice(top.index + top[0].length, bottom.index).trim();
+    const footer = screen.slice(bottom.index + bottom[0].length);
+    return input === '>' && /\? for shortcuts/.test(footer) && !/esc to cancel/i.test(footer);
+}
+export function attachConsole({ pid, cwd }) {
+    const live = consoleCall(pid);
+    const id = identityID(live);
+    const previous = fs.existsSync(target(id)) ? readJSON(target(id)) : {};
+    const repo = repoKey(cwd);
+    if (previous.repos && !previous.repos.includes(repo))
+        throw new Error('이 프로세스는 다른 저장소에 등록되어 있습니다.');
+    const idle = consoleIdle(live.screen);
+    const s = { ...previous, id, provider: 'agy', transport: 'console', pid, startedAt: live.startedAt,
+        workspaces: previous.workspaces || [path.resolve(cwd)], repos: previous.repos || [repo],
+        state: idle ? 'idle' : 'unknown', fullyIdle: idle, registeredAt: new Date().toISOString(), event: previous.event || 'attach' };
+    writeJSON(target(id), s);
+    return { id, provider: s.provider, transport: s.transport, pid, state: s.state, workspaces: s.workspaces };
+}
+export function registerExternalHook(input, event) {
+    if (!['SessionStart', 'PreInvocation', 'Stop'].includes(event))
+        throw new Error('지원하지 않는 훅 이벤트입니다.');
+    const identity = consoleCall(process.pid, 'ancestor');
+    if (identity.ignored)
+        return {};
+    const id = identityID(identity);
+    const previous = fs.existsSync(target(id)) ? readJSON(target(id)) : {};
+    const workspaces = input.workspacePaths || previous.workspaces;
+    if (!Array.isArray(workspaces) || !workspaces.length || workspaces.some(p => !path.isAbsolute(p)))
+        throw new Error('훅의 작업 저장소 경로가 없습니다.');
+    const conversationId = input.conversationId;
+    if (typeof conversationId !== 'string' || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(conversationId))
+        throw new Error('훅의 대화 UUID가 없습니다.');
+    const transcript = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'), 'brain', conversationId, '.system_generated', 'logs', 'transcript.jsonl');
+    if (path.resolve(input.transcriptPath || '') !== transcript)
+        throw new Error('훅의 대화 기록 경로가 다릅니다.');
+    const idle = event === 'Stop' && input.fullyIdle === true;
+    writeJSON(target(id), { ...previous, ...identity, id, provider: 'agy', transport: 'console', conversationId,
+        transcript, workspaces, repos: [...new Set(workspaces.map(repoKey))], model: input.modelName || previous.model,
+        event, state: idle ? 'idle' : 'running', fullyIdle: idle, registeredAt: new Date().toISOString() });
+    return { id };
+}
+export function externalStatus(session) {
+    const s = readJSON(target(session.id));
+    const live = consoleCall(consolePID(s), 'snapshot', { startedAt: s.startedAt });
+    const state = consoleIdle(live.screen) ? 'idle' : 'unknown';
+    writeJSON(target(s.id), { ...readJSON(target(s.id)), state, fullyIdle: state === 'idle' });
+    return { id: s.id, state };
+}
+function consolePID(s) {
+    if (!s.pid || !s.startedAt)
+        throw new Error('등록된 콘솔 프로세스 신원이 없습니다.');
+    return s.pid;
+}
+export function checkConsole(s) {
+    const live = consoleCall(consolePID(s), 'snapshot', { startedAt: s.startedAt });
+    if (!consoleIdle(live.screen))
+        throw new Error('상대 콘솔이 빈 입력창에서 대기 중이지 않습니다. 입력을 보내지 않았습니다.');
+    return live;
+}
+export function validateConsolePrompt(prompt, from) {
+    if (/[\x00-\x08\x0b-\x1f\x7f]/.test(prompt.replace(/\r\n/g, '\n')) || /[\x00-\x1f\x7f]/.test(from))
+        throw new Error('콘솔 요청에는 제어 문자를 포함할 수 없습니다.');
+}
+export function findConsoleTranscript(s, request) {
+    if (s.transcript)
+        return s;
+    const brain = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'), 'brain');
+    if (!fs.existsSync(brain))
+        return s;
+    const marker = `[axMap request ${request.id}]`;
+    const matches = [];
+    for (const entry of fs.readdirSync(brain, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/i.test(entry.name))
+            continue;
+        const log = path.join(brain, entry.name, '.system_generated', 'logs', 'transcript.jsonl');
+        let stat;
+        try {
+            stat = fs.statSync(log);
+        }
+        catch {
+            continue;
+        }
+        if (stat.mtimeMs < Date.parse(request.createdAt) || stat.size > 32 * 1024 * 1024)
+            continue;
+        const records = fs.readFileSync(log, 'utf8').split('\n').slice(0, -1);
+        if (records.some(line => {
+            try {
+                const e = JSON.parse(line);
+                return e.type === 'USER_INPUT' && String(e.content).includes(marker);
+            }
+            catch {
+                return false;
+            }
+        }))
+            matches.push({ conversationId: entry.name, transcript: log });
+    }
+    if (matches.length !== 1)
+        return s;
+    const updated = { ...readJSON(target(s.id)), ...matches[0] };
+    writeJSON(target(s.id), updated);
+    return updated;
+}
+export function submitConsole(s, request, preflight) {
+    validateConsolePrompt(request.prompt, request.from);
+    const live = preflight || checkConsole(s);
+    // Bracketed paste preserves multiline prompts and prevents embedded Enter keys
+    // from becoming separate submissions. Only the final CR submits the message.
+    const text = `\x1b[200~[axMap request ${request.id}]\n요청자: ${request.from}\n${request.prompt.replace(/\r\n/g, '\n')}\x1b[201~\r`;
+    consoleCall(consolePID(s), 'send', { startedAt: s.startedAt, expectedScreen: live.screen, text });
+    writeJSON(target(s.id), { ...readJSON(target(s.id)), state: 'running', fullyIdle: false });
+    return { accepted: true, pid: s.pid };
+}

package/src/external-console.mts

@@ -0,0 +1,128 @@
+/** Attach to an existing Windows console; never launch or resume a model. */
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { bridgeHome, repoKey, readJSON, writeJSON } from './bridge.mjs'
+import { nativeConsoleHelper } from './windows-console.mjs'
+import type { SessionRecord, RequestRecord, ConsoleSnapshot, HookInput, TranscriptEntry } from './session-types.mjs'
+
+const helper = fileURLToPath(new URL('../tools/windows-console.ps1', import.meta.url))
+export function consoleCall(pid: number, action?: 'snapshot' | 'send', payload?: Record<string, unknown>): ConsoleSnapshot
+export function consoleCall(pid: number, action: 'ancestor', payload?: Record<string, unknown>): ConsoleSnapshot | { ignored: true }
+export function consoleCall(pid: number, action = 'snapshot', payload: Record<string, unknown> = {}): ConsoleSnapshot | { ignored: true } {
+  if (process.platform !== 'win32') throw new Error('독립 agy 콘솔 연결은 현재 Windows에서 지원합니다.')
+  if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('양의 정수 PID가 필요합니다.')
+  const native = nativeConsoleHelper()
+  const r = spawnSync(native || 'powershell.exe', native ? [String(pid), action] : ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+    '-File', helper, '-TargetPid', String(pid), '-Action', action], {
+    input: JSON.stringify(payload), encoding: 'utf8', windowsHide: true, timeout: 8000, maxBuffer: 1024 * 1024,
+  })
+  let data: (Omit<Partial<ConsoleSnapshot>, 'ignored'> & { error?: string; ignored?: boolean }) | undefined
+  try { data = JSON.parse(r.stdout) } catch { /* report the underlying failure */ }
+  if (r.error || r.status !== 0 || data?.error || !data) throw new Error(data?.error || r.error?.message || r.stderr?.trim() || '기존 콘솔 연결 실패')
+  if (action === 'ancestor' && data.ignored) return { ignored: true }
+  if (typeof data.pid !== 'number' || typeof data.startedAt !== 'string' || (action !== 'ancestor' && typeof data.screen !== 'string')) throw new Error('기존 콘솔 응답 형식이 올바르지 않습니다.')
+  return data as ConsoleSnapshot
+}
+function identityID({ pid, startedAt }: Pick<ConsoleSnapshot, 'pid' | 'startedAt'>): string {
+  const hex = createHash('sha256').update(`agy-console:${pid}:${startedAt}`).digest('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`
+}
+const target = (id: string) => path.join(bridgeHome(), 'sessions', `${id}.json`)
+export function consoleIdle(screen: string): boolean {
+  // Use the last input box only. Old answers may contain quoted prompt boxes.
+  const borders = [...screen.matchAll(/^[─━]{10,}\r?$/gm)]
+  if (borders.length < 2) return false
+  const top = borders.at(-2), bottom = borders.at(-1)
+  if (!top || !bottom) return false
+  const input = screen.slice(top.index + top[0].length, bottom.index).trim()
+  const footer = screen.slice(bottom.index + bottom[0].length)
+  return input === '>' && /\? for shortcuts/.test(footer) && !/esc to cancel/i.test(footer)
+}
+export function attachConsole({ pid, cwd }: { pid: number; cwd: string }) {
+  const live = consoleCall(pid)
+  const id = identityID(live)
+  const previous = fs.existsSync(target(id)) ? readJSON<Partial<SessionRecord>>(target(id)) : {}
+  const repo = repoKey(cwd)
+  if (previous.repos && !previous.repos.includes(repo)) throw new Error('이 프로세스는 다른 저장소에 등록되어 있습니다.')
+  const idle = consoleIdle(live.screen)
+  const s: SessionRecord = { ...previous, id, provider: 'agy', transport: 'console', pid, startedAt: live.startedAt,
+    workspaces: previous.workspaces || [path.resolve(cwd)], repos: previous.repos || [repo],
+    state: idle ? 'idle' : 'unknown', fullyIdle: idle, registeredAt: new Date().toISOString(), event: previous.event || 'attach' }
+  writeJSON(target(id), s)
+  return { id, provider: s.provider, transport: s.transport, pid, state: s.state, workspaces: s.workspaces }
+}
+export function registerExternalHook(input: HookInput, event: string) {
+  if (!['SessionStart', 'PreInvocation', 'Stop'].includes(event)) throw new Error('지원하지 않는 훅 이벤트입니다.')
+  const identity = consoleCall(process.pid, 'ancestor')
+  if (identity.ignored) return {}
+  const id = identityID(identity)
+  const previous = fs.existsSync(target(id)) ? readJSON<Partial<SessionRecord>>(target(id)) : {}
+  const workspaces = input.workspacePaths || previous.workspaces
+  if (!Array.isArray(workspaces) || !workspaces.length || workspaces.some(p => !path.isAbsolute(p))) throw new Error('훅의 작업 저장소 경로가 없습니다.')
+  const conversationId = input.conversationId
+  if (typeof conversationId !== 'string' || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(conversationId)) throw new Error('훅의 대화 UUID가 없습니다.')
+  const transcript = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'),
+    'brain', conversationId, '.system_generated', 'logs', 'transcript.jsonl')
+  if (path.resolve(input.transcriptPath || '') !== transcript) throw new Error('훅의 대화 기록 경로가 다릅니다.')
+  const idle = event === 'Stop' && input.fullyIdle === true
+  writeJSON(target(id), { ...previous, ...identity, id, provider: 'agy', transport: 'console', conversationId,
+    transcript, workspaces, repos: [...new Set(workspaces.map(repoKey))], model: input.modelName || previous.model,
+    event, state: idle ? 'idle' : 'running', fullyIdle: idle, registeredAt: new Date().toISOString() })
+  return { id }
+}
+export function externalStatus(session: Pick<SessionRecord, 'id'>) {
+  const s = readJSON<SessionRecord>(target(session.id))
+  const live = consoleCall(consolePID(s), 'snapshot', { startedAt: s.startedAt })
+  const state: 'idle' | 'unknown' = consoleIdle(live.screen) ? 'idle' : 'unknown'
+  writeJSON(target(s.id), { ...readJSON<SessionRecord>(target(s.id)), state, fullyIdle: state === 'idle' })
+  return { id: s.id, state }
+}
+function consolePID(s: SessionRecord): number {
+  if (!s.pid || !s.startedAt) throw new Error('등록된 콘솔 프로세스 신원이 없습니다.')
+  return s.pid
+}
+export function checkConsole(s: SessionRecord): ConsoleSnapshot {
+  const live = consoleCall(consolePID(s), 'snapshot', { startedAt: s.startedAt })
+  if (!consoleIdle(live.screen)) throw new Error('상대 콘솔이 빈 입력창에서 대기 중이지 않습니다. 입력을 보내지 않았습니다.')
+  return live
+}
+export function validateConsolePrompt(prompt: string, from: string): void {
+  if (/[\x00-\x08\x0b-\x1f\x7f]/.test(prompt.replace(/\r\n/g, '\n')) || /[\x00-\x1f\x7f]/.test(from)) throw new Error('콘솔 요청에는 제어 문자를 포함할 수 없습니다.')
+}
+export function findConsoleTranscript(s: SessionRecord, request: RequestRecord): SessionRecord {
+  if (s.transcript) return s
+  const brain = path.join(process.env.AXMAP_AGY_HOME || path.join(os.homedir(), '.gemini', 'antigravity-cli'), 'brain')
+  if (!fs.existsSync(brain)) return s
+  const marker = `[axMap request ${request.id}]`
+  const matches = []
+  for (const entry of fs.readdirSync(brain, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^[0-9a-f-]{36}$/i.test(entry.name)) continue
+    const log = path.join(brain, entry.name, '.system_generated', 'logs', 'transcript.jsonl')
+    let stat
+    try { stat = fs.statSync(log) } catch { continue }
+    if (stat.mtimeMs < Date.parse(request.createdAt) || stat.size > 32 * 1024 * 1024) continue
+    const records = fs.readFileSync(log, 'utf8').split('\n').slice(0, -1)
+    if (records.some(line => {
+      try { const e = JSON.parse(line) as TranscriptEntry; return e.type === 'USER_INPUT' && String(e.content).includes(marker) }
+      catch { return false }
+    })) matches.push({ conversationId: entry.name, transcript: log })
+  }
+  if (matches.length !== 1) return s
+  const updated = { ...readJSON<SessionRecord>(target(s.id)), ...matches[0] }
+  writeJSON(target(s.id), updated)
+  return updated
+}
+export function submitConsole(s: SessionRecord, request: RequestRecord, preflight?: ConsoleSnapshot) {
+  validateConsolePrompt(request.prompt, request.from)
+  const live = preflight || checkConsole(s)
+  // Bracketed paste preserves multiline prompts and prevents embedded Enter keys
+  // from becoming separate submissions. Only the final CR submits the message.
+  const text = `\x1b[200~[axMap request ${request.id}]\n요청자: ${request.from}\n${request.prompt.replace(/\r\n/g, '\n')}\x1b[201~\r`
+  consoleCall(consolePID(s), 'send', { startedAt: s.startedAt, expectedScreen: live.screen, text })
+  writeJSON(target(s.id), { ...readJSON<SessionRecord>(target(s.id)), state: 'running', fullyIdle: false })
+  return { accepted: true, pid: s.pid }
+}