위키 · 구현 참조
요청과 응답
매니저와 워커는 요청서·응답서 파일로 한 번의 시도와 그 결과를 연결합니다. 이 문서는 사람이 읽는 Markdown handoff와 공개 저장소의 JSON 예시 계약을 구분해 설명합니다.
실제 로컬 요청은 설치의 파일 통신 절차를 따릅니다. 구성요소와 로컬 운영·공개 구현의 경계는 구성과 범위에서 확인합니다.
요청서의 내용과 네 가지 정보
실제 요청서는 registrar가 부여한 식별 헤더와 사람이 읽는 본문으로 구성됩니다. 본문은 목표, 완성 기준, 참조 경로, 금지 범위를 분명히 하며, 이를 독립 항목으로 분리하면 수행 경계와 판정 기준을 찾기 쉽습니다.
| 항목 | 기록할 내용 | 읽는 이유 |
|---|---|---|
| 목표 | 요청한 변경 또는 결과 | 작업의 의도와 대상 페이지·파일을 확인합니다. |
| 완성 기준 | 확인할 수 있는 결과와 필수 조건 | 무엇을 완료로 판정할지 정합니다. |
| 참조 경로 | 현재 기준으로 읽을 파일·디렉터리 | 판단 근거와 소유 문서를 추적합니다. |
| 금지 범위 | 수정하지 않을 파일이나 실행하지 않을 조치 | 허용 범위 밖 변경을 구분합니다. |
요청서에는 보통 request_id, goal_id, intent_revision, 생성 주체와 제목이 함께 실립니다. 등록기가 소유하는 식별 헤더를 본문에 수동 복제하지 않습니다. 요청서 전체가 JSON schema로 검증되는 것은 아닙니다.
세 식별자의 역할
| 식별자 | 범위 | 동작 |
|---|---|---|
request_id | 한 번의 불변 시도 | inbox 요청 파일명과 outbox 응답 파일을 연결합니다. 변경된 요청을 같은 ID로 덮어쓰지 않고 새 ID를 씁니다. |
goal_id | 여러 시도에 걸친 결과 목표 | 후속 요청을 같은 목표에 연결합니다. 유효한 기존 요청이 있으면 재사용할 수 있습니다. |
intent_revision | 사용자 의도 버전 | 같은 목표의 요청 범위가 갱신되었는지 구분합니다. 등록기는 revision을 과거 값으로 되돌리지 않으며, 높아진 revision은 새 시도를 만들어 이전 시도와 분리합니다. |
등록 결과
ensure_request.py는 본문을 검증하고 목표 기록과 요청서를 갱신하며 결과를 JSON으로 출력합니다. 등록은 dispatcher 실행과 다릅니다.
| 결과 | 의미 |
|---|---|
created | 새 goal에 첫 요청 파일을 만들었습니다. |
reused | 유효한 lease 또는 이미 등록된 동일 목표 요청을 다시 가리킵니다. 새 시도가 시작됐다는 뜻은 아닙니다. |
superseded | 기존 목표에 새 요청 파일을 만들었습니다. 응답 후속 시도나 더 높은 revision은 새 request_id를 받으며 과거 이력은 유지됩니다. |
실행 상태와 시간 초과
dispatcher는 허용된 inbox 파일을 읽고 중복 실행을 방지하며 시도 기록을 남깁니다. 상태형 경로는 orchestration/tasks/<request_id>/state.json에 작업 상태와 attempt 정보를 둡니다. 주요 전이는 queued → running → verifying → succeeded이며, 이어갈 결과는 waiting, 실패·차단은 failed로 기록될 수 있습니다. partial은 응답서에만 쓰는 결과값이며 state machine에는 없습니다.
dispatcher에는 실행 시간 제한이 있습니다. timeout 시 이미 존재하는 응답은 partial로 정산될 수 있고, checkpoint에 확인 가능한 산출이 있으면 partial-with-artifacts로 보존합니다. 유효한 산출이 없는 timeout은 failed가 됩니다. queued 상태와 살아 있는 dispatcher/워커를 구분해 재시작 여부를 판단하며, 완료 응답이 이미 있으면 중복 실행하지 않습니다. 재시작은 dispatcher가 판단하며, 워커는 스스로 다시 실행하지 않습니다.
Markdown 응답서와 terminal 판정
사람이 읽는 로컬 응답서는 Markdown 텍스트입니다. 최소 상단 필드는 요청과 같은 request_id와 실제 결과를 나타내는 status입니다. 본문에는 2~3줄 요약, 산출 경로, 수정 파일과 백업, 확인 방법, 적용한 교훈, 참고 근거, 남은 항목을 기록할 수 있습니다. 이는 공개 JSON 객체를 그대로 직렬화한 것이 아니며 로컬 문서 전체가 JSON 스키마를 따르지 않습니다.
| status | 판정 기준 |
|---|---|
done | 요청의 필수 완료 조건을 충족했고 산출을 확인했습니다. |
partial | 산출 일부는 보존했지만 핵심 완료 조건이 빠졌거나 완성되지 않았습니다. |
failed | 시도가 끝났지만 보존된 deliverable이 없습니다. |
blocked | 필수 입력·권한·승인 경계 또는 검증 문제로 수행을 진행할 수 없습니다. |
워커는 지정 outbox에 응답서를 씁니다. dispatcher는 그 응답과 실행 상태를 읽어 정산하며, 응답이 없거나 정산 오류가 있으면 대체 terminal 응답을 남길 수 있습니다. 결과 파일이 있다고 완료 조건이 자동 충족되지는 않습니다. 요청한 파일과 내용을 다시 열어 응답을 확인합니다.
재시도와 공개 JSON 계약
같은 goal을 이어갈 때는 원 목표와 이력을 보존하고 새 요청 ID를 발급합니다. 변경된 의도는 intent_revision을 높여 식별하며, 이미 terminal 응답이 있는 ID를 새 요청에 재사용하지 않습니다. 매니저는 이전 시도의 산출을 확인한 뒤 필요한 잔여 범위만 등록합니다.
공개 저장소의 content/reference/contracts.md는 교육용 JSON 계약입니다. 요청 JSON에는 request_id, goal_id, intent_revision, inputs, acceptance, policy가 있고, 응답 JSON에는 request_id, goal_id, intent_revision, status, request_sha256, artifacts가 있으며 result와 error는 선택입니다. JSON의 request_sha256는 워커가 읽은 원 요청 바이트를 묶는 digest입니다. 로컬 Markdown 요청서·응답서에서 이 JSON 필드 전부를 요구하거나 자동 변환하지 않습니다.
| 표현 | 정본·용도 | 파일에서 기대하는 것 |
|---|---|---|
| 공개 JSON | content/reference/contracts.md, 독립 교육용 참조 | 고정 필드·자료형·digest·산출 목록 및 terminal status |
| 로컬 Markdown | orchestration/WORKER.md와 요청서별 참조 | 사람이 읽는 경계·근거·요약·남은 일; 최소한 일치하는 요청 ID와 status |
근거 파일
| 내용 | 정본 경로 |
|---|---|
| 응답서 작성·워커 상태 판정 | <로컬 운영 루트>/orchestration/WORKER.md |
| 등록기와 goal/revision 처리 | <로컬 운영 루트>/orchestration/glm/scripts/ensure_request.py |
| dispatcher·timeout·outbox 정산 | <로컬 운영 루트>/orchestration/worker_dispatch.py |
| 상태 스키마·전이 | <로컬 운영 루트>/orchestration/glm/executor/state.py, orchestration/tasks/<request_id>/state.json |
| 공개 JSON 계약 | content/reference/contracts.md, reference/orchestrator.py, reference/worker.py |
확인 기준: 2026-10-13. 로컬 요청·응답과 JSON 계약은 각각 현재 정본에서 확인했습니다.