사람 확인 화면과 실행 API

모델은 미리보기까지만 만들고, 이슈 게시·에이전트 ID 등록·MR 머지는 로그인한 사람이 화면 버튼을 눌렀을 때만 서버가 실행한다. 모델 도구에는 이 API 가 열리지 않는다(WorkspaceTools 의 허용 목록 밖).

1. 흐름

1.1 이슈 게시

1. 모델이 issue draft 로 초안을 만들고 issue publish --json 을 --yes 없이 실행한다(도구 승인 필요).
2. evo 가 status: blocked · finding not_confirmed 를 내면 서버가 초안 파일 내용과 SHA-256 을 대기 상태로 남긴다.
3. 화면 “확인할 작업” 에 초안 본문이 그대로 보인다. 사람이 “확인하고 실행” 을 누르면 서버가 초안을 다시 읽어 지문을 비교하고, 같을 때만 같은 입력에 --yes 를 붙여 실행한다.
4. 초안이 그 사이에 바뀌었으면 실행하지 않고 draft_changed(409)로 알린다 — 미리보기를 다시 만들어야 한다.
5. 대기 상태는 30분 뒤 만료된다. 새 이슈는 미리보기 직후 실행하므로 번호가 어긋나면 evo 가 issue_id_not_next 로 거절한다 (그때는 미리보기를 다시 만든다).

1.2 에이전트 ID 등록 (대문자·숫자 4자리)

1. 사용자가 ID 를 입력하면 서버가 일회용 worktree(work/agent-<UUID>/<프로젝트>, 브랜치 agent-id/<UUID>)를 최신 기본 브랜치에서 만들고 init --json(=--yes 없음) 미리보기를 보여 준다.
2. “확인하고 실행” → 같은 worktree 에서 init --yes --json. 이 시점에 사용자별 ID 를 workspace_agent_ids 에 저장해, 모델의 issue draft·publish 실행에 --session-agent 로 붙인다.
3. 서버가 ops 초안을 만든다: 제목 [Ops] <component>: 에이전트 ID <ID> 를 등록한다, 항목 operational_context·procedure_or_change·verification·rollback_or_recovery. issue draft 로 검증하고 issue publish --json 미리보기를 대기 상태로 올린다. 화면에서 제목·항목을 고칠 수 있고, 고치면 초안을 다시 만들어 다시 확인을 받는다(needs_review).
4. 확인하면 issue publish --yes. 이슈를 게시한 뒤 .evo/workflow.json 변경만 git add 하고 diff 를 보여 준다 (.evo/config.local.json 은 커밋하지 않는다).
5. 마지막 화면에서 커밋 메시지·MR 제목·설명·대상 브랜치(기본 main)를 고칠 수 있다. 확인하면 commit → agent-push (agent-id/<UUID> 만) → glab mr create 를 하고 일회용 worktree 를 지운다.
6. MR 이 머지돼야 다른 작업 트리에서도 그 ID 를 쓴다. 다른 사용자와 충돌(agent_id_taken)하면 최신 기본 브랜치에서 미리보기를 다시 만들어(같은 화면의 “다시 만들기”) 새 등록 MR 을 올린다.

1.3 MR 머지

• 이 대화의 기본 브랜치를 대상으로 한 열린 MR 을 glab mr list -F json 으로 보여 주고 파이프라인 상태를 함께 표시한다.
• 버튼을 누르면 목록을 다시 읽어 상태를 확인한다. failed·canceled·running·pending 이면 실행하지 않고 pipeline_failed·pipeline_running(409)으로 알린다.
• 통과(또는 파이프라인 없음)면 미리보기 때 본 커밋을 고정하려고 --sha <MR sha> 를 붙여 glab mr merge <iid> --yes --auto-merge=false 를 실행한다.

2. API

인증 필요(/api/**, Bearer). 대화 소유자가 아니면 404.

Method	Path	뜻
GET	/api/workspace/conversations/{conversationId}/actions	확인 대기 목록(초안 본문 포함)
POST	/api/workspace/actions/{id}/confirm	확인 실행. 본문은 아래 수정 값(선택)
DELETE	/api/workspace/actions/{id}	확인 취소(등록용 worktree 정리)
POST	/api/workspace/conversations/{conversationId}/agent-registrations	{"agentId":"ABCD"} — 등록 미리보기
GET	/api/workspace/conversations/{conversationId}/merge-requests	MR 후보·파이프라인 상태
POST	/api/workspace/conversations/{conversationId}/merge-requests/merge	{"iid":"7"} — 머지

확인 본문(모두 선택, 비우면 저장된 기본값):

{
  "issueTitle": "[Ops] api: 에이전트 ID ABCD 를 등록한다",
  "issueFields": {"operational_context": "...", "procedure_or_change": "...",
                  "verification": "...", "rollback_or_recovery": "..."},
  "commitMessage": "chore(ABCD): 에이전트 ID 등록",
  "mrTitle": "chore(ABCD): 에이전트 ID 등록",
  "mrDescription": "...",
  "targetBranch": "main"
}

응답(확인):

{"ok": true, "status": "passed", "message": "이슈 #510 를 게시했습니다", "output": "...", "next": null}

next 는 이어서 확인할 작업(등록 흐름의 다음 단계)이다. status: needs_review 면 내용을 고쳐 초안을 다시 만든 것이므로 next 를 다시 확인해야 한다.

3. 오류 코드

코드	HTTP	화면 안내
invalid_agent_id	400	대문자·숫자 4자리, 아무것도 쓰지 않음
agent_id_taken	409	다른 사용자가 등록한 ID — 다른 ID 또는 다시 만들기
agent_id_owner_mismatch	409	다른 사용자의 ID — 내 ID 로 다시 실행
agent_id_not_registered·agent_id_differs	409	프로젝트에 등록되지 않은 ID — 등록 먼저
draft_changed	409	초안이 바뀜 — 미리보기 다시
no_workspace	409	대화에 프로젝트 연결 없음
workspace_disabled·workspace_unavailable	503	실행기·GitLab 토큰 설정 없음
pipeline_failed·pipeline_running	409	파이프라인 상태 때문에 머지 불가
mr_not_open·mr_not_found	409/404	닫힘·목록에 없음 — 목록 다시
publish_failed·agent_init_failed·commit_failed·push_failed·mr_failed·merge_failed	422/502	output(가림 처리)에서 원인 확인

output 에는 토큰 모양 문자열을 가린 실행 출력만 담는다. 경로·토큰 원문은 응답·감사·로그에 남기지 않는다.

4. 저장

• workspace_actions(V29): 확인 대기 상태. 초안 경로·SHA-256·에이전트 ID·worktree·화면용 payload(JSON). 대화 삭제 시 함께 지워진다.
• workspace_agent_ids(V30): 사용자별 등록 ID. 소유권 최종 판단은 evo workflow(원격 등록 파일 + GitLab 사용자)가 한다. 원격이 소유자 불일치를 알리면 저장도 지운다.

5. 시험

• WorkspaceHumanServiceTest: 같은 초안에만 --yes·--sha, 초안 변경 거부, ID 형식·충돌, ops 초안 계약(state: draft), 제목 수정 시 재미리보기, 파이프라인 실패 시 머지 거부.
• WorkspaceToolsTest: 모델 도구가 --session-agent 를 직접 쓰지 못하고, 등록된 ID 는 issue draft·publish 에만 붙으며, issue publish 미리보기가 확인 대기로 기록되는지.