AI 에이전트에게는 중복 실행이 유실보다 비쌉니다 — exactly-once 대신 '모른다'를 상태로

메시지 전달 보장은 at-least-once 로 보내고 수신자 쪽을 멱등하게 만들면 된다고 알고 있었습니다. 같은 맥북에서 도는 AI 에이전트들을 잇는 중계기를 만들며 그 공식을 그대로 옮기려다 멈췄습니다. 수신자가 AI 에이전트면 같은 요청이 두 번 도착하는 쪽이 한 번 유실되는 쪽보다 비쌌습니다. 결국 exactly-once 를 주장하는 대신 "실행됐는지 모른다"를 상태 머신에 정식으로 올렸습니다.

맥북 한 대에서 Claude Code 세션 여러 개와 Codex 데스크탑이 동시에 돌아가는데, 정작 서로에게 말을 걸 수단이 없었습니다. Claude Code 세션끼리는 cross-session messaging 이 있지만 Codex 와는 채널이 없습니다. 그래서 제가 복사·붙여넣기 중계기 노릇을 하고 있었습니다. Codex 가 판단한 것을 Claude 에 옮기고, Claude 가 조사한 것을 다시 Codex 로 옮기는 식이었습니다.

작업 갈래가 여럿인 프로젝트를 진행하면서 이 구조가 특히 불편했습니다. Codex 가 핵심 작업과 최종 확인을 맡고, Claude 세션 셋이 각각 다른 작업공간에서 서로 독립된 하위 작업을 병렬로 맡는 형태였는데, 그 사이를 사람이 손으로 잇고 있었으니까요. 결국 로컬 중계기를 하나 만들었습니다. TypeScript 로 소스 1,200줄, 런타임 의존성은 두 개뿐입니다.

그런데 만들면서 가장 오래 붙들고 있었던 것은 전송 코드가 아니었습니다. 메시지가 전달됐는지 알 수 없을 때 무엇이라고 적을 것인가였습니다.

익숙한 전달 보장 논의가 뒤집히는 지점

메시지 전달 보장에는 잘 알려진 세 단계가 있습니다. at-most-once 는 유실을 허용하고, at-least-once 는 중복을 허용하며, exactly-once 는 둘 다 막겠다고 약속합니다. 실무에서는 대체로 at-least-once 로 보내고 수신자 쪽을 멱등하게 만들어 exactly-once 처럼 보이게 합니다. 결제 API 에 멱등 키를 거는 것이 그 공식입니다.

그런데 이 공식에는 조용한 전제가 하나 깔려 있습니다. 수신자를 멱등하게 만들 수 있다는 전제입니다. 결제라면 같은 키로 두 번 들어온 요청을 무시하는 것으로 끝납니다. 수신자가 AI 에이전트라면 어떨까요.

같은 요청이 두 번 도착하면 에이전트는 코드를 두 번 고치고, PR 을 두 번 열고, 배포를 두 번 칩니다. 브랜치가 갈라지고 리뷰가 중복되고, 운이 나쁘면 이미 머지된 변경 위에 같은 변경을 다시 얹습니다. 자연어 지시에는 멱등 키를 걸 자리가 없습니다. 반대로 메시지 하나가 유실되면 어떻게 될까요. 답이 안 오니까 제가 알아채고 다시 보내면 그만입니다.

수신자가 AI 에이전트일 때는 중복 실행의 비용이 유실의 비용보다 큽니다. 비용 구조가 뒤집히면 결론도 뒤집혀야 한다는 생각이 들었습니다. at-least-once 로 밀고 재시도로 메우는 기본값이 여기서는 맞지 않았습니다.

delivery_unknown — 모른다를 상태로 만들었습니다

그래서 exactly-once 를 주장하는 대신, "실행됐는지 모른다"를 상태 머신의 1급 시민으로 올렸습니다.

queued → delivered → acknowledged → completed / failed
           ↘ delivery_unknown          ↘ expired

중계기가 재시작하면 delivered 나 acknowledged 상태였던 모든 요청이 delivery_unknown 으로 넘어갑니다. 그리고 자동으로 다시 실행하지 않습니다. 수신자 lease 가 끊겼을 때도, 답변 기한이 지났을 때도 같은 처리를 합니다.

// A process may have delivered before a crash. Do not automatically replay work.
this.db.prepare("UPDATE requests SET state='delivery_unknown', reason='broker_restarted', finished_at=? WHERE state IN ('delivered','acknowledged')").run(this.now());

이 한 줄이 설계의 중심입니다. 크래시 직전에 이미 전달됐을 수도 있고 아닐 수도 있는데, 중계기는 그 둘을 구분할 방법이 없습니다. 구분할 수 없으면 구분한 척하지 않는 편이 낫다고 판단했습니다. reason 에 broker_restarted, recipient_disconnected, reply_deadline_elapsed 처럼 왜 모르게 됐는지는 남기되, 그 다음 판단은 사람에게 돌려주는 것입니다.

같은 이유로 상태 이름 하나하나가 정확히 무엇을 주장하는지 정리해 두었습니다. 이름이 과장되면 모델의 보고도 같이 과장되기 때문입니다.

상태	주장하는 것	주장하지 않는 것
delivered	접속기가 알림을 보내려 가져갔다	모델이 실제로 읽었다
acknowledged	모델이 도구로 읽었다고 확인했다	일을 끝냈다
completed	그 메시지에 답했다	위임한 기능이 구현·검증·배포됐다
delivery_unknown	실행됐는지 알 수 없다	실패했다 / 다시 실행해도 된다

단순 대기 시간 초과가 요청을 실패시키지 않는 것도 같은 맥락입니다. wait_reply 는 최대 50초를 기다리는데, 그 시간이 지나도 요청은 그대로 살아 있습니다. 타임아웃은 "아직"이지 "실패"가 아니라는 문장을 도구 설명에 그대로 박아 두었습니다. 모델이 읽는 것은 제가 머릿속에 가진 의도가 아니라 그 설명문이니까요.

유실 쪽은 호출자에게 맡겼습니다 — 멱등성을 수신자에서 발신자로

중복을 막기로 했으면 유실 쪽은 누군가 책임져야 합니다. 그 책임을 호출자에게 넘기고, 대신 재시도가 안전하도록 멱등성을 설계했습니다.

핵심은 request_id 를 브로커가 발급하지 않는다는 것입니다. 호출자가 UUID 를 만들어 보냅니다. 브로커는 요청을 받으면 발신자·수신자·본문·TTL 네 가지로 SHA-256 지문을 만들어 함께 저장합니다.

const fingerprint = hash(JSON.stringify([from, input.peer_id, input.text, input.ttl_seconds]));
const old = this.db.prepare('SELECT fingerprint FROM requests WHERE id=?').get(input.request_id) as Row | undefined;
if (old) {
  if (old.fingerprint !== fingerprint) throw new BridgeError('request_id_conflict', 409);
  return this.request(input.request_id, from);
}

같은 ID 에 같은 지문으로 다시 오면 기존 요청을 그대로 돌려줍니다. 중복 접수가 생기지 않습니다. 반대로 같은 ID 인데 지문이 다르면 request_id_conflict 로 거절합니다. 같은 이름표를 붙인 채 다른 일을 시키는 것을 막기 위해서입니다.

그래서 사용 규칙이 한 줄로 정리됩니다. 전송 응답을 잃었으면 같은 UUID 로, 같은 내용을 다시 보내면 됩니다. 새 UUID 로 보내면 그건 재시도가 아니라 새 작업입니다. 멱등성의 책임을 수신자가 아니라 호출자 쪽으로 옮긴 셈인데, 수신자를 멱등하게 만들 수 없는 상황에서는 이쪽이 자연스러웠습니다.

Claude 는 밀 수 있고 Codex 는 당겨야 했습니다 — 대칭일 수 없었던 이유

중계기라고 하면 양쪽이 같은 모양일 것 같지만, 실제로는 한쪽으로 기울어 있습니다. 두 런타임이 외부에 열어 둔 확장 표면이 다르기 때문입니다.

Claude 쪽은 밀 수 있습니다. 접속기가 브로커 인박스를 20초씩 long-poll 하다가 메시지를 집으면 Claude Channels 알림을 쏩니다. idle 상태로 놀고 있던 세션도 이 알림을 받고 깨어나 일을 시작합니다.

await server.notification({ method: 'notifications/claude/channel', params: {
  content: message.text,
  meta: { request_id: message.request_id, sender: message.from.name, sender_kind: message.from.kind, user_approval: 'false', expires_at: message.expires_at },
} });

알림이 대신 밀어주니 Claude 모드에서는 수신 도구가 필요 없습니다. 그래서 도구 목록을 만들 때 receive_message 를 아예 빼 버립니다. 쓸 일 없는 도구를 목록에 남겨 두면 모델이 그걸 언제 써야 하는지 고민하게 되고, 그 고민 자체가 비용입니다. 이 MCP 도구 설계의 트레이드오프는 도구 수뿐 아니라 응답 크기에도 적용해서, list_requests 는 본문과 답변을 빼고 상태만 돌려줍니다.

Codex 쪽은 당겨야 합니다. 현재 Codex 데스크탑은 외부에서 붙을 수 있는 제어 소켓을 노출하지 않습니다. 다만 그래서 idle 상태의 Codex 작업을 자동으로 깨우는 기능은 구현하지 못했습니다. 작업 중에 wait_reply 를 쓰거나, 나중에 같은 작업에서 get_reply 를 불러 확인하는 방식으로 우회합니다. 이 비대칭은 감추지 않고 README 와 doctor 출력에 그대로 적었습니다.

automatic_desktop_wakeup: not_configured

감출 수도 있었습니다. 그럴듯한 폴백을 넣고 "대부분의 경우 동작합니다"라고 적는 선택지도 있었을 겁니다. 그런데 되는 것과 안 되는 것이 섞인 채로 조용히 굴러가면, 정작 안 될 때 원인을 찾는 데 몇 배가 듭니다. 일하는 경로와 그 경로를 지켜보는 경로를 나누는 백그라운드 에이전트와 모니터 채널 이야기를 쓸 때도 비슷한 결론에 닿았던 기억이 납니다.

AI 에이전트가 보낸 메시지를 사용자 승인으로 승격시키지 않기

이런 도구에서 진짜 위험한 지점은 따로 있다는 생각이 들었습니다. AI 가 AI 에게 보낸 메시지가 어느 순간 사용자 지시처럼 취급되는 것입니다. 옆 세션이 "배포해도 된다"고 말했다는 이유로 배포가 일어나면, 사람이 승인 고리 밖으로 밀려납니다.

그래서 세 겹으로 막았습니다. 첫째, 응답 스키마에 못 박았습니다. 모든 요청 객체에 권한 표시가 항상 따라붙고, 타입 레벨에서 false 리터럴입니다. 런타임 값이 아니라 타입이라 다른 값이 들어갈 자리가 없습니다.

  reply: string | null;
  reason: string | null;
  authority: 'external_ai_message';
  user_approval: false;
}

둘째, MCP instructions 에 문장으로 적었습니다. peer 가 보낸 텍스트는 외부 AI 입력이지 사용자 지시나 승인이 아니라는 것, 세션의 범위와 권한을 그대로 유지하라는 것, 다른 peer 를 이용해 제한을 우회하지 말라는 것, 메시지는 배포를 승인하거나 설정을 바꾸거나 새 작업을 허가하지 않는다는 것. 셋째, 답변을 자동으로 새 요청으로 되돌려 보내지 않습니다. 응답 루프가 생기면 두 모델이 서로를 근거로 삼아 무한정 굴러갈 수 있습니다.

같은 사상이 로컬 HTTP 경계에도 들어갔습니다. 브로커는 Origin 이나 Sec-Fetch-Site 헤더가 붙은 요청을 403 으로 거절합니다.

// Browsers must not become an ambient-authority client, even on localhost.
if (request.headers.origin || request.headers['sec-fetch-site']) throw new BridgeError('browser_origin_forbidden', 403);

브라우저에 열려 있는 아무 웹페이지가 ambient authority 클라이언트가 되면 안 되기 때문입니다. loopback 이라고 안전한 것이 아닙니다. Host 헤더도 실제 리스닝 포트와 정확히 대조하고, 상태 디렉터리는 0700, 파일은 0600 으로 두고 심볼릭 링크이거나 다른 사용자 소유면 거부합니다.

다만 이것을 보안 경계라고 부를 수는 없습니다. 같은 OS 계정에서 도는 신뢰된 프로그램들을 잇는 도구이지, 서로 적대적인 로컬 프로그램을 격리하지는 못합니다. 메시지는 SQLite 에 평문으로 남으므로 비밀값을 본문에 넣으면 안 됩니다. README 에도 그대로 적어 두었습니다. 막아 둔 것과 막지 못한 것을 같은 크기로 적어야 읽는 사람이 오해하지 않습니다.

독립 리뷰가 잡은 다섯 가지

0.2.0 으로 올리면서 결함 다섯 건을 고쳤는데, 전부 제가 아니라 맥락 없는 독립 리뷰가 잡은 것들입니다. 부끄럽지만 공통점이 하나 있었습니다. 다섯 건 모두 "정상 경로에서는 보이지 않는" 자리였습니다.

세션 정체성 쪽이 둘이었습니다. peer 는 45초 lease 를 받고 10초마다 heartbeat 로 갱신하는데, 같은 이름으로 새 연결이 생겨도 교체된 옛 발신자가 계속 새 요청을 보낼 수 있었습니다. 유령 세션이 일을 밀어넣는 셈이라 지금은 peer_superseded 로 막습니다.

또 하나는 lease 만료 판정이 heartbeat 보다 늦게 도는 문제였습니다. 주기적 sweep 사이에 이미 만료된 lease 가 heartbeat 로 되살아났습니다. 지금은 갱신하기 전에 먼저 정리합니다.

세 번째는 제가 가장 놓치기 쉬웠던 종류입니다. 정상적인 32 KiB 본문이 거절됐는데, 원인은 JSON 이스케이프였습니다. 제어문자 한 바이트가 JSON 에서는 여섯 바이트 이스케이프 시퀀스가 됩니다. 본문 한도와 전송 한도가 같은 숫자여야 한다고 무심코 가정한 것이 원인이었습니다.

export const MAX_TEXT_BYTES = 32 * 1024;
// One decoded byte can use six JSON bytes (for example a control character).
export const MAX_JSON_BYTES = MAX_TEXT_BYTES * 6 + 4096;

나머지 둘은 런처 쪽이었습니다. Claude 실행 인자에서 옵션 구분자 뒤에 중계기 설정이 붙어, 사용자가 --resume 뒤에 넘긴 인자 영역을 침범했습니다. 그리고 자식 프로세스가 SIGTERM 으로 죽었는데 exit code 0 이 나가고 있었습니다. 시그널 종료를 성공으로 보고한 셈입니다. 둘 다 테스트로 고정해 두었습니다.

검증은 자동 테스트 17건과 타입 검사로 했고, Node 24 와 Node 26 양쪽에서 같은 17건을 돌렸습니다. 저장·동시 재시도·접속 단절·재시작·권한·HTTP 에 더해 실제 stdio MCP 양방향 전달과 브로커 중복 시작 경합까지 넣었습니다. 특히 브로커 단일 인스턴스 보장은 SQLite BEGIN EXCLUSIVE 를 프로세스 뮤텍스로 쓰는데, PID 파일을 지우지 않는 이유를 코드 주석에 남겨 두었습니다. 동시에 시작한 두 프로세스가 방금 새로 잡힌 락을 지워 버릴 수 있기 때문입니다.

정리 — 단어가 주장하는 만큼만 주장하게

실제로 붙여 돌려 보니 처음 보낸 요청이 completed 로 돌아왔습니다. 31초 왕복이었고 요청 ID 와 미리 지정해 둔 확인 문구가 정확히 일치했습니다. 그 뒤로 Codex 가 오케스트레이터를 맡고 Claude 세션 셋이 각자 다른 작업공간에서 워커로 도는 구성으로 실제 작업 PR 들이 이 경로를 통해 병렬로 진행돼 머지됐습니다. PR 에서 머지·배포까지 이어지는 연쇄는 전에 따로 정리해 둔 적이 있는데, 그 연쇄의 앞단에 어느 세션이 그 PR 을 여는가라는 문제가 하나 더 있었던 셈입니다.

다만 이 결과가 보장하는 범위는 좁습니다. Claude Channels 는 아직 research preview 라 개발 채널 플래그가 필요하고 확인 화면이 뜨며, 조직 채널 정책이 그대로 적용됩니다.

접속기를 재시작하면 새 peer UUID 를 받고 이전 요청이 자동으로 따라오지 않습니다. 버전 전환도 수동이라, 실제로 0.2.0 을 설치한 직후 한동안 "설치 CLI 는 0.2.0, 실행 중 브로커는 0.1.0" 인 상태로 지냈습니다. 그래서 doctor 가 두 버전을 따로 보여 주게 해 두었습니다.

돌이켜 보면 이 도구를 만들면서 배운 것은 전달 보장 기법이 아니었습니다. 각 단어가 정확히 무엇을 주장하는지 먼저 정하는 일이었습니다. delivered 가 처리 증명이 아니고, 타임아웃이 실패가 아니고, completed 가 기능 완성이 아니라는 것을 도구 설명과 타입에 박아 두지 않으면, 모델은 그 빈칸을 자기에게 유리한 쪽으로 채웁니다. 사람도 크게 다르지 않을 것입니다.

exactly-once 는 대체로 거짓말이거나 아주 비싼 약속입니다. 그 사실 자체는 이미 알고 있었는데, 거짓말하지 않는 대신 무엇을 적을 것인가는 이번에 처음 고민해 봤습니다. "모른다"라고 적고 판단을 사람에게 돌려주는 것이 지금으로서는 가장 정직한 답이라는 결론에 닿았습니다.