실행 계약
외부 Agent Loop는 계획, 모델 문맥, 완료 판단을 담당합니다. CodeSpace는 정해진 도구 동작을 수행하고 상태를 제공합니다. 실행 기능을 추가하더라도 내부 모델 호출이나 Codex 에이전트 세션이 필수 조건이 되어서는 안 됩니다.
정책과 실행 구현
게이트웨이는 등록된 작업 공간에서 요청한 행동이 허용되는지 결정합니다. Runner 요청은 CodeSpace 타입으로 전달하고, 어댑터가 이를 Codex 실행 타입으로 변환합니다. 핵심 계층의 의존성 선언과 인터페이스에 Codex crate나 타입을 직접 추가하지 않습니다. 다만 어댑터의 간접 의존성이 빌드 그래프에 포함될 수 있습니다.
운영자 레지스트리의 read-only와 workspace-write를 실제 권한에 대응시키고, 네트워크는 restricted 또는 enabled로 선택합니다. 내부 정책 타입에는 세밀한 경로 규칙을 표현할 수 있는 glob 필드가 있지만, 이를 외부에서 설정하고 모든 작업에 적용하는 기능은 제공하지 않습니다. 클라이언트 인자로 권한을 높일 수 없습니다.
실행 환경과 식별자
| 개념 | 현재 용도 |
|---|---|
| 실행 환경 | 운영자가 선택하는 실행 위치. 호스트는 구현되어 있으며 등록된 컨테이너 백엔드는 사용 불가 |
| 작업 공간 | workspace_id로 선택하는 등록 루트. MCP 파일 경로는 상대 경로 |
| 권한 프로필 | 파일·프로세스 행동의 허용 범위를 게이트웨이가 결정 |
| 패치 작업 | operation_id와 선택적 중복 실행 방지 키, files/changes 해시, minted/finished 이벤트로 저장하는 패치 원장. operation_status로 조회. 명령 실행은 추적하지 않음 |
| 프로세스 | 서버가 발급하는 명령 핸들. 메모리에만 보관 |
| 확인 홀드 | 운영자 approvals 설정. approvals 테이블 행(pending/granted/resuming, 단말 결과가 있을 때까지). 패치 작업이 아니며 권한 부여나 격리 경계도 아님 |
| 논리적 작업 | 작업과 사용자 지시 큐. 전송 세션과 별개 |
environment_id는 MCP 도구 인자가 아닙니다. 모델이 전달한 프록시 URL이나 Codex 사용자 설정이 실행 권한의 근거가 되지 않습니다.
실행과 결과 관측
게이트웨이는 내부 Runner 요청에 작업 공간 루트 cwd, 러너 환경 기본값, 시간·출력 제한, PTY 선택, 정책을 채웁니다. spawn 시 공개된 터미널 옵션은 tty뿐입니다. tty_size는 spawn 인자가 아닙니다. 실행 중인 PTY는 process_resize로 크기를 바꿉니다. 공개 호출은 임의의 cwd·환경변수·제한 시간 변경을 받지 않습니다. 기본값은 운영, 결과 처리는 Agent Loop 연동을 참고하세요.
exec_command는 디스패치 식별(process_id, dispatch_status)만 반환합니다. 종료 판정은 process_status의 running/exited와 termination 메타데이터를 사용합니다. 실행 중인 PTY 크기는 process_resize로 바꿉니다. read_process는 output_lost와 retained_from을 포함한 출력을 반환합니다. EOF는 성공이 아닙니다. 핸들이 만료된 뒤의 조회는 새 상태가 아니라 PROCESS_NOT_FOUND입니다. 파이프 프로세스의 크기 변경은 PROCESS_NOT_TTY, 종료된 핸들은 PROCESS_NOT_RUNNING입니다. Linux 샌드박스에서 wait 상태는 관리 자식(헬퍼 argv)의 코드이며, 사용자 argv와 동일하다고 문서화하지 않습니다.
작업 공간 잠금은 패치와 명령이 동시에 파일을 변경하지 못하게 합니다. 명령 실행 중에도 읽기와 검색은 가능하므로 파일 I/O는 사전 경로 검사에만 의존하지 않고 파일을 여는 시점의 심볼릭 링크 변경도 거부해야 합니다. Runner 파일 작업은 codespace-fs, 패치 적용은 별도 패치 도우미를 사용합니다. operation_status는 기록된 패치 원장(kind는 patch)을 조회하며, 실행 중인 명령은 process_id로만 다루고 이 조회로 복구하지 않습니다.
UDS 전송과 Linux 샌드박스 준비는 서로 다른 프로토콜과 실패 경계를 가집니다. UDS 변경 요청이 일부만 전달되면 결과가 불확실할 수 있습니다. 연결이 끊겼다는 이유만으로 새 변경 요청을 보내지 마세요. 프로세스 수명은 러너 인스턴스가 소유합니다. MCP/HTTP 클라이언트 끊김은 프로세스를 유지하고, UDS 게이트웨이↔worker 단절이나 게이트웨이 종료는 소유 서브트리를 종료합니다. 영속적인 프로세스 복구는 없습니다. 프로세스·격리 규칙 전체는 러너 격리에 설명합니다.
파일 시스템 관측
Runner는 해당 작업 공간에서 처음 read·find·version·apply_patch가 호출될 때 재귀 파일 감시자를 시작할 수 있습니다. 이벤트는 작업 공간 상대 경로의 무효화 힌트(Create, Modify, Remove, Rename, ResyncRequired)이며 epoch와 전달 순서 seq를 가집니다. MCP 도구가 아니고, 권한 결정도 아니며, 변경 전제도 아닙니다. watch 경로는 작업 공간 상대 무효화 이름입니다. 경로가 방출되어도 그 경로가 읽기·쓰기 가능하거나 일반 파일·비심링크라는 뜻은 아닙니다. 실제 접근은 계속 PathSandbox가 강제합니다.
변경 전제는 여전히 expected_versions와 VERSION_CONFLICT입니다. 놓친·합쳐진·재시작된 watch 이벤트 때문에 디스크 해시가 달라진 apply_patch가 성공해서는 안 됩니다. 오버플로, 수신 실패(뒤처진 구독자 포함), 분류할 수 없는 이벤트는 같은 epoch에서 ResyncRequired를 내며 소비자 캐시 전체를 신뢰하지 않아야 합니다. 감시자를 다시 시작할 때는 교체 감시자가 살아 있는 뒤에만 epoch가 증가하고 ResyncRequired를 냅니다. 이 기반은 자체 apply와 외부 편집을 구분하지 않고, 손실 없는 이벤트 원장을 두지 않으며, UDS로 watch 이벤트를 보내지 않습니다.
find는 제한된 glob 탐색입니다. watch API가 아닙니다.
확인 홀드
approval_create, approval_resolve, operation_resume을 호출할 수 있습니다. 작업 공간 프로필이 이미 허용한 변경을 홀드가 승인될 때까지 멈춥니다. 보안 경계가 아닙니다. 권한을 높이거나 { "network": true }·ClientClaims.approved를 적용하거나 패치 원장에 V4A 스냅샷을 넣지 않습니다. 같은 MCP 호출자가 grant할 수 있습니다.
운영자가 작업 공간 approvals를 confirm으로 두면, 정책이 허용한 apply_patch와 exec_command는 begin()이나 프로세스 시작 전에 APPROVAL_REQUIRED와 approval_id를 반환합니다. 같은 논리 요청을 다시 보내면 그 활성 홀드를 재사용합니다. 기본값 off에서는 해당 도구가 바로 실행됩니다. 세 도구는 목록에 남아 있으므로 명시적 approval_create로 홀드를 만들 수 있습니다. grant는 프로필을 바꾸지 않습니다. 재개는 granted를 resuming으로 옮긴 뒤 allow()를 다시 검사하고 기존 패치·실행 내부 경로를 돌립니다. consumed는 단말 결과와 함께만 기록됩니다. 이후 재개는 그 결과, 패치 원장 복구, 또는 APPROVAL_AMBIGUOUS를 반환합니다. 중단된 exec는 다시 spawn하지 않습니다. 정책 거절은 그대로 UNAUTHORIZED입니다. 명령은 process_id로 다룹니다. v1은 호스트와 모델을 구분하지 않습니다. 서버가 보장하는 것은 재개 시 정책 재검사와 이 내구성 계약입니다.
아직 제공하지 않는 기능
파일 범위·페이지 인자, 영속적인 프로세스 복구, 컨테이너·원격 실행, 자원 큐 스케줄러도 제공하지 않습니다. MCP fs/watch, UDS watch 이벤트, 쓰기 원인 분류도 제공하지 않습니다. 내부 타입이나 협상된 프로토콜 플래그가 존재한다고 해당 기능을 호출할 수 있는 것은 아닙니다.
구현 경계 유지
check-no-model-deps.sh는 핵심 계층의 의존성 선언과 일부 소스 패턴, 어댑터 의존성 허용 목록을 검사합니다. 업스트림 소스 전체를 검사하거나 가능한 모든 모델 호출의 부재를 증명하는 도구는 아닙니다. CI는 Codex 고정 커밋, 어댑터 빌드·테스트, Runner에서 샌드박스 도우미 라이브러리로 향하는 금지된 의존성도 확인합니다. 릴리스 검증은 업스트림 업데이트를 참고하세요.