아키텍처

CodeSpace는 에이전트의 판단과 작업 공간의 실행을 분리합니다. MCP 서버가 권한과 작업 기록을 관리하고, Runner가 허용된 파일·프로세스 작업을 수행합니다. Codex 라이브러리는 어댑터 뒤에서 사용합니다.

현재 실행 구조

외부 Agent Loop
  → MCP 서버: 등록 정보, 권한, 패치 기록, 작업·지시 큐
  → Runner
      ├─ InProcessRunner (기본값)
      └─ UdsRunner → codespace-codex-runtime → InProcessRunner
           ├─ 파일 작업 → codespace-fs
           ├─ 패치 처리 → codespace-patch
           └─ 프로세스 관리
                ├─ 파이프 / codespace-pty
                └─ 사용 가능한 Linux 도우미 → 샌드박스 / 관리 프록시

UDS worker와 기본 러너는 모두 같은 호스트에서 실행합니다. 두 방식 모두 명령 시작 시 Linux 샌드박스를 적용할 수 있습니다. Compose의 컨테이너 실험 구성으로 실행을 전달하는 경로는 없습니다.

구성 요소의 책임과 상태

구성 요소	책임
server	MCP 전송, HTTP 인증·inbox, 요청 검증과 실행 연결
domain	CodeSpace 도구 인자·결과, ID, 오류·실행 타입
policy	등록 경로, 환경, 권한 프로필, 네트워크 정책
store	SQLite의 패치 작업·확인 홀드·논리적 작업·사용자 지시, 메모리의 점유 상태
runner	실행 데이터 타입, 파일 범위, 패치 처리, 프로세스 관리, UDS 통신
분리된 어댑터	Codex 패치·PTY·파일 시스템·worker 보호와 소켓·Linux 샌드박스 구현 연결

패치 작업, 확인 홀드, 작업·지시 큐는 SQLite 파일을 설정한 경우에만 재시작 후 유지됩니다. 프로세스 핸들과 점유 상태는 메모리에만 있습니다. operation_status는 명령 실행을 조회하지 않습니다. 전송 요청 ID, 패치 작업 ID, 프로세스 ID, 작업 ID, 지시 ID, 승인 ID는 서로 다른 대상을 가리킵니다.

패치 처리 과정

게이트웨이는 작업 공간 권한을 확인하고 쓰기 점유를 확보한 다음 작업 키를 검사합니다. 이후 Runner에 패치 요청 하나를 전달하고 결과를 기록합니다. Runner는 예상 버전 확인, 사전 검증, 파일 스냅샷 저장, 패치 도우미 호출, 실제 디스크 해시 검증을 수행합니다.

도우미의 적용 호출이 실패하면 파일별 스냅샷 복원을 시도합니다. 현재 적용 후 검증 오류는 이 복원 분기를 거치지 않고 반환됩니다. 따라서 파일 시스템 전체의 원자적 트랜잭션을 보장하지 않습니다. 클라이언트 처리에 미치는 영향은 패치 동작에 설명합니다.

프로세스 수명

MCP 요청이 끝나도 관리 중인 프로세스는 유지됩니다. 클라이언트는 process_id로 후속 호출을 수행합니다. 서버 재시작 후에는 핸들이 사라집니다. UDS 모드에서는 게이트웨이가 worker를 관리하므로 내부 연결 종료나 서버 종료 시 worker와 자식 프로세스가 종료되며 재접속은 지원하지 않습니다. 러너 격리에서 전송 경계와 격리 경계를 구분해 설명합니다.

확장 시 유지할 경계

핵심 계층은 Codex 타입을 직접 가져오지 않습니다. 어댑터가 여러 Codex 실행 구성 요소에 의존할 수는 있지만 게이트웨이가 Codex 에이전트가 되는 것은 아닙니다. 실행 환경은 운영자가 설정하고, MCP 클라이언트는 등록된 작업 공간만 선택합니다. 컨테이너 실행, 원격 러너, 자원 스케줄러는 아직 구현되지 않았습니다.

확인 홀드 도구(approval_create, approval_resolve, operation_resume)는 구현되어 있습니다. 프로필이 이미 허용한 변경을 홀드가 승인될 때까지 멈춥니다. 보안 경계가 아닙니다. read-only를 쓰기·실행으로 올리거나 ClientClaims.approved를 인정하거나 프로필을 바꾸지 않습니다. 같은 MCP 호출자가 grant할 수 있습니다. 재개 시 정책을 다시 검사합니다. v1은 호스트와 모델을 구분하지 않습니다.

새 전송 방식을 추가하더라도 패치 처리는 하나의 Runner 호출로 유지합니다. Codex 사용자·세션 권한을 실행 허용의 근거로 가져오지 않고 게이트웨이에서 결정합니다. 현재 불변 조건은 실행 계약, 연결된 어댑터는 Codex 재사용 범위에 정리되어 있습니다.

도구와 프로토콜 참고

호출할 도구와 연동 예시는 Agent Loop 연동을, 버전 협상과 전송 테스트는 프로토콜 호환성을 참고하세요. 아키텍처 문서에 도구 명세를 중복해서 관리하지 않습니다.