# PLAN: bootstrap 생성 설정의 runner/node 연결 smoke ## 이 파일을 읽는 구현 에이전트에게 이 계획은 `[node-connect]` 완료만 목표로 하며 `01_core_command`, `02_unix_bootstrap`, `03+01_windows_bootstrap` 완료 후 실행해야 한다. 연결 smoke는 기존 agent 설정 의미를 보존하면서 최소 등록/heartbeat 계약을 검증해야 한다. ## 배경 bootstrap script는 agent config를 생성하고 `oto agent run`을 시작하거나 안내한다. 마일스톤 완료를 위해 이 설정이 OTO Core runner registry에 runner/node로 등록 또는 연결되는 최소 흐름을 보장해야 한다. ## Roadmap Targets - Milestone: `agent-roadmap/phase/control-plane-product-surface/milestones/cross-os-runner-bootstrap.md` - Epic: `[bootstrap-platforms] Cross-OS bootstrap contract` - Task id: `[node-connect]` - Completion mode: check-on-pass ## 분석 결과 ### 읽은 파일 - `apps/runner/lib/oto/agent/agent_config.dart` - `apps/runner/lib/oto/agent/agent_runner.dart` - `apps/runner/lib/oto/agent/registration_client.dart` - `apps/runner/lib/oto/agent/oto_server_job_client.dart` - `apps/runner/lib/cli/commands/command_agent.dart` - `apps/runner/test/oto_agent_config_test.dart` - `apps/runner/test/oto_agent_registration_test.dart` - `apps/runner/test/oto_server_connection_smoke_test.dart` - `services/core/internal/runnerregistry/registry.go` - `services/core/internal/runnerregistry/registry_test.go` - `services/core/internal/httpserver/runner_handlers.go` - `services/core/internal/httpserver/server_test.go` - `agent-test/local/rules.md` - `agent-test/local/agent-smoke.md` ### 테스트 환경 규칙 기본 환경은 local이다. agent smoke는 runner analyze와 agent 관련 Dart tests, Core Go tests를 요구한다. ### 테스트 커버리지 공백 기존 테스트는 agent config parsing, registration client, server connection smoke를 다루지만 bootstrap script가 생성한 config와 `oto agent run` 사이의 end-to-end 최소 계약은 명시적으로 묶여 있지 않다. ### 심볼 참조 `AgentConfig`, `RegistrationClient`, `AgentRunner`, `handleRunnerRegistration`, runner registry store가 연결 지점이다. bootstrap script가 쓰는 YAML key와 Dart parser의 기대 key가 일치해야 한다. ### 분할 판단 이 작업은 `05+01,02,03_node_connect`로 API contract와 양쪽 platform bootstrap이 모두 준비된 뒤 수행한다. binary version check와는 병렬 가능하지만 실제 연결 흐름의 안정성을 위해 script 생성 config가 선행되어야 한다. ### 범위 결정 근거 실제 장기 실행 daemon/service manager는 범위 제외다. local fake Core 또는 in-process test server에서 등록/연결 최소 경로를 검증한다. ### 빌드 등급 `cloud-G07`: Dart runner와 Go Core의 cross-domain smoke이며 process/HTTP 상태 전이를 함께 검증한다. ## 의존 관계 및 구현 순서 - 선행: `agent-task/m-cross-os-runner-bootstrap/01_core_command/complete.log` - 선행: `agent-task/m-cross-os-runner-bootstrap/02_unix_bootstrap/complete.log` - 선행: `agent-task/m-cross-os-runner-bootstrap/03+01_windows_bootstrap/complete.log` ## 구현 체크리스트 - [ ] bootstrap-generated YAML key가 `AgentConfig` parser와 정확히 일치하는지 fixture로 고정한다. - [ ] `oto agent run` 또는 대응 runner flow가 Core runner registry에 등록/연결되는 최소 smoke를 추가한다. - [ ] enrollment token validation 실패와 성공 경로를 구분하고 token 출력 노출을 피한다. - [ ] Go Core registry tests와 Dart agent smoke를 모두 통과시킨다. - [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. ### [CONNECT-1] bootstrap config fixture 연결 문제: script가 쓰는 YAML과 Dart parser가 같은 의미인지 별도 fixture로 묶여 있지 않다. 해결 방법: bootstrap script가 생성하는 config shape를 테스트 fixture에 반영하고 `AgentConfig`가 해당 값을 그대로 읽는지 검증한다. 수정 파일 및 체크리스트: - `apps/runner/test/oto_agent_config_test.dart` - `apps/runner/test/oto_agent_bootstrap_script_test.dart` - 필요 시 `apps/runner/lib/oto/agent/agent_config.dart` 테스트 작성: `agent.id`, `agent.enrollment_token`, `server.url`, `runtime.install_dir`, `runtime.workspace_root`, `runtime.log_dir` key를 확인한다. 중간 검증: `cd apps/runner && dart test test/oto_agent_config_test.dart test/oto_agent_bootstrap_script_test.dart` ### [CONNECT-2] runner registry 연결 smoke 문제: bootstrap 이후 `oto agent run`이 Core registry에 연결되는 최소 흐름이 마일스톤 target으로 고정되어 있지 않다. 해결 방법: existing smoke를 확장하거나 새 fixture를 추가해 registration endpoint, status/heartbeat, registry 상태를 함께 검증한다. 수정 파일 및 체크리스트: - `apps/runner/test/oto_agent_registration_test.dart` - `apps/runner/test/oto_server_connection_smoke_test.dart` - `services/core/internal/runnerregistry/registry_test.go` - `services/core/internal/httpserver/server_test.go` 테스트 작성: 성공 등록, invalid token, status visibility를 검증한다. 중간 검증: `cd apps/runner && dart test test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart` ## 수정 파일 요약 | 경로 | 목적 | |------|------| | runner agent config/tests | bootstrap config와 parser 연결 | | runner registration/smoke tests | `oto agent run` 최소 연결 검증 | | Core registry/httpserver tests | registry 상태와 endpoint 회귀 검증 | ## 최종 검증 - `cd apps/runner && dart analyze` - `cd apps/runner && dart test test/oto_agent_config_test.dart test/oto_agent_registration_test.dart test/oto_server_connection_smoke_test.dart` - `cd services/core && go test ./...` 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.