nomadcode/agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md

Milestone: Proto-Socket Infrastructure Communication Rail

위치

• Roadmap: agent-roadmap/ROADMAP.md
• Phase: agent-roadmap/phase/workflow-core/PHASE.md

목표

NomadCode 내부 런타임 간 신규 통신을 proto-socket 중심으로 통일하는 기반을 만든다. 모든 내부 인프라 통신 후보를 대상으로 REST/HTTP 예외를 분리하고, 첫 구현 축은 Flutter client와 Core가 같은 레일로 task 조회, 실행 요청, 상태 이벤트를 주고받을 수 있게 한다.

상태

[진행중]

승격 조건

• 없음

구현 잠금

• 상태: 해제
• 결정 필요: 없음

범위

• 내부 런타임 간 통신 표준을 proto-socket 기본, REST/HTTP 예외 방식으로 정리
• apps/client와 services/core 사이의 client-core 통신 레일 구현 준비
• packages/contracts에 proto-socket channel, message envelope, error/heartbeat/auth 후보를 정리
• 기존 core REST task API를 proto-socket channel 후보로 매핑하고 전환 경계를 기록
• Core의 proto-socket endpoint와 Flutter client connector의 최소 구현 단위 정의
• health/readiness, 외부 provider 호환 API, 운영 smoke/curl, public callback, 단순 정적 조회 같은 REST/HTTP 예외 목록 관리

기능

Epic: [protocol] Internal communication contract

내부 인프라 통신을 proto-socket 중심으로 통일하기 위한 계약과 예외 경계를 정리한다.

• [standard-boundary] 내부 런타임 간 신규 통신은 proto-socket을 기본으로 삼고 REST/HTTP 예외 조건을 contracts 또는 domain rule에서 추적한다.
• [message-envelope] request, response, event, error, heartbeat, auth metadata를 포함한 최소 message envelope 후보를 정리한다.
• [rest-compat-map] 현재 core REST task API와 health/readiness endpoint를 proto-socket channel 후보와 REST 예외 목록으로 매핑한다.

Epic: [core-rail] Core proto-socket rail

Core가 내부 런타임 통신용 proto-socket endpoint와 task channel을 제공할 수 있게 한다.

• [core-endpoint] services/core에 proto-socket endpoint 구성 위치와 lifecycle을 추가한다. 검증: Core가 기존 REST health/readiness를 유지하면서 proto-socket 연결 endpoint를 노출한다.
• [task-channels] task create/list/get/enqueue와 task status event를 proto-socket channel로 제공한다. 검증: REST task API와 같은 의미의 요청/응답이 proto-socket 경로에서 동작한다.
• [core-contract-tests] core proto-socket channel, auth, error, heartbeat 동작을 테스트로 고정한다.

Epic: [client-rail] Flutter client-core rail

Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전환한다.

• [client-connector] apps/client의 NoopProtoSocketConnector를 대체할 concrete connector를 추가한다. 검증: 설정된 endpoint로 연결 상태가 connected까지 전이된다.
• [client-task-api] workspace/task 화면이 mock 데이터 대신 Core proto-socket task channel을 소비할 수 있는 client service 경계를 만든다.
• [client-tests] proto-socket endpoint 설정, reconnect/failure lifecycle, client task service를 Flutter test로 검증한다.

Epic: [ops] Observability and rollout

내부 통신 레일을 운영 가능하게 만들고 예외 프로토콜이 다시 기본값으로 새지 않게 한다.

• [diagnostics] connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인할 수 있게 한다. 검증: client diagnostics 구현은 반영되었고, 허용된 검증 환경에서 Flutter test/analyze와 code-review PASS가 필요하다.
• [rollout-docs] 새 내부 통신을 추가할 때 proto-socket 우선 여부와 REST/HTTP 예외 사유를 확인하는 운영 체크를 문서화한다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 없음
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 없음

범위 제외

• Mattermost, Plane, Jira 같은 외부 provider의 native REST API 자체를 proto-socket으로 대체하지 않는다.
• health/readiness, 운영 smoke/curl, public callback, 단순 정적 조회 REST 예외를 제거하지 않는다.
• ../nexo/packages/messaging_flutter의 native push 처리 로직을 수정하지 않는다.
• IOP native protocol, A2A JSON-RPC, OpenAI-compatible Responses 같은 외부 실행 표면을 이 Milestone에서 재설계하지 않는다.
• 전체 프로젝트 관리 UX 완성은 후속 Project Workspace Management UX 범위로 둔다.

작업 컨텍스트

• 관련 경로: services/core/internal/http/, services/core/internal/workflow/, services/core/internal/scheduler/, apps/client/lib/src/integrations/proto_socket/, apps/client/lib/src/features/workspaces/, packages/contracts/
• 표준선(선택): 내부 런타임 간 신규 통신은 proto-socket을 기본 표준으로 삼고, REST/HTTP는 명시된 예외 조건에서만 유지한다.
• 선행 작업: Mattermost Nexo Messaging Alignment, Client Integration Standardization, 프로젝트 룰의 proto-socket 표준 규약
• 후속 작업: Workflow Core, External Integration, Project Workspace Management UX
• 현재 지점: Core proto-socket endpoint, task channel, Flutter concrete connector, client task service boundary, workspace/task 화면 소비 경계, client diagnostics snapshot/debug surface 구현은 반영되었고, 다음 작업은 허용된 검증 환경에서 Flutter test/analyze 실행과 code-review PASS로 diagnostics 항목을 닫는 것이다.
• 반영 근거: packages/contracts/notes/flutter-core-api-candidates.md에 내부 통신 원칙, proto-socket semantic envelope 후보, REST compatibility map 후보를 추가했다.
• Core 반영 근거: services/core/internal/protosocket/, services/core/internal/http/router.go, services/core/cmd/server/main.go에 proto-socket server, task channel, task status event broadcaster, authenticated route 연결과 contract tests가 추가되었다.
• Client connector 반영 근거: apps/client/lib/src/integrations/proto_socket/proto_socket_client.dart, apps/client/lib/src/app/bootstrap.dart, apps/client/lib/src/app/nomadcode_client_app.dart에 RealProtoSocketConnector, endpoint-config 기반 connect, task service wiring이 추가되었다.
• Client task/test 반영 근거: apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart, apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart, apps/client/test/integrations/proto_socket_*_test.dart, apps/client/test/widget_test.dart에 task channel 소비 경계와 endpoint/lifecycle/task service/widget 검증이 추가되었다.
• Client diagnostics 반영 근거: apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart에 ProtoSocketDiagnostics snapshot/stream과 response/event diagnostics recording을 추가했고, apps/client/lib/src/app/nomadcode_client_app.dart, apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart, apps/client/test/integrations/proto_socket_lifecycle_test.dart, apps/client/test/widget_test.dart에 payload/auth/raw error message 없이 connection id, protocol version, channel/action, error code, timestamp를 확인하는 debug surface와 테스트를 추가했다.
• 운영 체크 근거: packages/contracts/notes/flutter-core-api-candidates.md에 새 내부 통신 추가 시 proto-socket 우선 여부, REST/HTTP 예외 기록, channel/action 문서화, 검증 항목을 확인하는 운영 체크를 추가했다.
• 확인 필요: 허용된 원격/검증 환경에서 cd apps/client && flutter test, cd apps/client && flutter analyze --no-fatal-infos를 실행하고, agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/ code-review PASS 후 [diagnostics] 완료 처리 여부를 반영한다.