<!-- task=m-embeddable-iop-console-workbench/02+01_client_integration plan=0 tag=API -->

# Plan - API Integration

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-cloud-G06.md`의 구현 에이전트 소유 섹션을 채우는 것이 구현의 마지막 단계다. 구현 후 검증을 실행하고 실제 출력, 계획 대비 변경 사항, 주요 설계 결정을 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 사용자 결정, 사용자 소유 외부 환경, scope 충돌 없이는 안전하게 진행할 수 없을 때만 review stub의 `사용자 리뷰 요청`을 근거와 함께 채우고 멈춘다. 명령 재실행이나 산출물 수집으로 해소 가능한 evidence 공백은 사용자 리뷰 요청이 아니다.

## 배경

`01_console_api`가 만든 package contract를 standalone client에 적용해 Milestone의 남은 UI/package 작업을 완료한다. Overview boundary, Execution/Logs route, IOP capability pack, config injection을 모두 같은 public API로 연결한다. 이 plan은 PASS 시 Roadmap Task 체크 대상이다.

## 사용자 리뷰 요청 흐름

구현 중 차단이 생기면 active `CODE_REVIEW-cloud-G06.md`의 `사용자 리뷰 요청` 섹션을 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 채운다. code-review가 정당성을 확인하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md`
- Task ids:
  - `overview-boundary`: Control Plane wire status overview boundary
  - `execution-logs`: Execution/Logs display route
  - `iop-capabilities`: IOP-scoped agent capabilities
  - `capability-api`: public capability pack API
  - `config-injection`: host config/theme/navigation injection
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/phase/control-plane-portal-ops/PHASE.md`
- `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md`
- `agent-ops/rules/project/domain/client/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/client-smoke.md`
- `packages/flutter/iop_console/lib/iop_console.dart`
- `packages/flutter/iop_console/lib/src/iop_console_shell.dart`
- `packages/flutter/iop_console/lib/src/iop_agent_panel.dart`
- `packages/flutter/iop_console/pubspec.yaml`
- `packages/flutter/iop_console/test/iop_console_shell_test.dart`
- `apps/client/lib/main.dart`
- `apps/client/test/widget_test.dart`
- `apps/client/pubspec.yaml`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`

### 테스트 환경 규칙

- test_env: `local`
- env rules: `agent-test/local/rules.md` present/read.
- matched profile: `agent-test/local/client-smoke.md` present/read.
- 적용 명령: `cd packages/flutter/iop_console && flutter test`, `cd apps/client && flutter test`.
- analyzer는 dependency/app shell public API 변경이 있으면 `cd apps/client && flutter analyze --no-fatal-infos`를 추가 실행한다.
- fallback: 없음.

### 테스트 커버리지 공백

- Client overview boundary: 기존 `apps/client/test/widget_test.dart`는 host private overview text만 확인한다. 새 package overview 사용 후 endpoint/status/handshake 표시를 유지하는 assertion이 필요하다.
- Execution/Logs route: 현재 client test 없음. Agent 또는 rail tap test에 route assertion을 추가한다.
- Config/capability injection: 현재 client test 없음. `IopClientApp` 또는 `ClientHomePage`가 package config/capability를 전달하는지 widget test가 확인해야 한다.

### 심볼 참조

- renamed/removed symbol은 plan 기준 없음.
- `IopConsoleShell` call site: `apps/client/lib/main.dart:195`.
- `IopAgentPanel` call site: `apps/client/lib/main.dart:197`, package shell default `packages/flutter/iop_console/lib/src/iop_console_shell.dart:100`.
- `ClientConfig` call sites: `apps/client/lib/main.dart:147`, `apps/client/lib/main.dart:156`, `apps/client/lib/main.dart:305`, `apps/client/lib/main.dart:310`, `apps/client/test/widget_test.dart:79`, `apps/client/test/widget_test.dart:83`.

### 분할 판단

- split decision policy를 먼저 평가했다.
- 이 subtask는 `02+01_client_integration`이며 predecessor index `01`은 `01_console_api`다.
- predecessor completion: 현재 active sibling plan exists, complete.log missing. Runtime must wait for `agent-task/m-embeddable-iop-console-workbench/01_console_api/complete.log` or matching archive complete.log before implementation.
- API/foundation과 app rollout이 분리되어야 하므로 single plan은 부적절하다.

### 범위 결정 근거

- Control Plane server, Edge/Node 상태 API, protobuf 변경은 제외한다.
- 실제 runtime log streaming 구현은 제외한다. 여기서는 UI route와 host-injected placeholder/status/capability surface를 완성한다.
- NomadCode product shell과 external consumer build 조립은 제외한다.

### 빌드 등급

- build lane: `cloud-G06`; review lane: `cloud-G06`.
- Public package API의 app rollout이고 roadmap completion target이 있어 review blast radius가 중간 이상이다.

## 구현 체크리스트

- [ ] `01_console_api` predecessor complete.log가 있음을 확인한다.
- [ ] `apps/client/lib/main.dart`가 package overview/config/capability API를 사용하도록 전환한다.
- [ ] client widget tests가 overview status, Execution/Logs route, Agent capability text를 검증하도록 갱신한다.
- [ ] `cd packages/flutter/iop_console && flutter test`와 `cd apps/client && flutter test`를 실행한다.
- [ ] 필요 시 `cd apps/client && flutter analyze --no-fatal-infos`를 실행하고 결과를 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

- Directory dependency: `02+01_client_integration` depends on predecessor `01_console_api`.
- 구현 시작 전 `agent-task/m-embeddable-iop-console-workbench/01_console_api/complete.log` 또는 matching archive complete.log를 확인한다.

## [API-1] Client Overview Boundary

### 문제

Overview UI는 `apps/client/lib/main.dart:201`의 private `_buildOverviewContent`에 남아 있어 package widget으로 재사용할 수 없다.

### 해결 방법

`01_console_api`의 package overview widget을 `apps/client/lib/main.dart:195`의 `IopConsoleShell`에 전달한다. Wire connection state와 reconnect callback은 host가 소유하고 package widget은 값과 callback만 받는다.

Before:

```dart
// apps/client/lib/main.dart:195
return IopConsoleShell(
  overview: _buildOverviewContent(),
  agent: const IopAgentPanel(),
);
```

After:

```dart
return IopConsoleShell(
  config: _consoleConfig,
  capabilities: iopDefaultCapabilityPack,
  overview: IopConsoleOverview(...),
  agent: IopAgentPanel(capabilities: iopDefaultCapabilityPack),
);
```

### 수정 파일 및 체크리스트

- [ ] `apps/client/lib/main.dart` overview private widget을 package overview 사용으로 축소.
- [ ] `apps/client/test/widget_test.dart` existing endpoint/status assertions 유지.

### 테스트 작성

기존 widget test를 갱신해 `ClientConfig` endpoint, handshake success/error가 package overview에서도 표시되는지 확인한다.

### 중간 검증

```bash
cd apps/client && flutter test
```

기대: 모든 client test 통과.

## [API-2] Execution/Logs And Capability Integration

### 문제

Milestone은 Execution/Logs 표시 경로와 IOP capability pack을 요구하지만 현재 shell에는 route가 없고 agent panel은 static intro만 표시한다. 관련 위치: `packages/flutter/iop_console/lib/src/iop_console_shell.dart:5`, `packages/flutter/iop_console/lib/src/iop_agent_panel.dart:9`, `apps/client/test/widget_test.dart:113`.

### 해결 방법

`01_console_api`의 Execution/Logs section과 default IOP capability pack을 app에 연결한다. Agent panel에는 Edge/Node/Runtime/Execution/Logs/Maintenance 같은 IOP 범위 capability만 표시한다.

### 수정 파일 및 체크리스트

- [ ] `apps/client/lib/main.dart`에 default capability pack 전달.
- [ ] `apps/client/test/widget_test.dart`에 Execution/Logs rail tap test 추가.
- [ ] Agent panel test가 IOP capability labels를 확인하도록 갱신.

### 테스트 작성

`Client App opens IOP agent panel from the left rail` test를 capability 표시까지 확장하고 Execution/Logs route test를 추가한다.

### 중간 검증

```bash
cd apps/client && flutter test
```

기대: 모든 client test 통과.

## [API-3] Config Injection

### 문제

Host가 Control Plane endpoint/auth/theme/navigation을 package에 주입한다는 Milestone task가 남아 있다. 현재 endpoint는 private app widget에서 직접 읽는다. 관련 위치: `apps/client/lib/main.dart:147`, `apps/client/lib/main.dart:305`.

### 해결 방법

`ClientConfig` 값을 `IopConsoleConfig`로 변환해 `IopConsoleShell`과 overview widget에 전달한다. Auth/token reference는 optional nullable field로 두고 secret 원문을 tracked 파일에 기록하지 않는다. Navigation callback은 route selection 또는 external host callback contract로 연결한다.

### 수정 파일 및 체크리스트

- [ ] `apps/client/lib/main.dart`에 config factory 또는 getter 추가.
- [ ] `apps/client/test/widget_test.dart`에서 HTTP/Wire URL 표시를 유지 확인.
- [ ] secret/token literal을 추가하지 않는다.

### 테스트 작성

기존 `ClientConfig` endpoint assertions를 유지하고 package config에서 렌더링되는지 확인한다.

### 중간 검증

```bash
cd apps/client && flutter test
```

기대: 모든 client test 통과.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/client/lib/main.dart` | API-1, API-2, API-3 |
| `apps/client/test/widget_test.dart` | API-1, API-2, API-3 |
| `packages/flutter/iop_console/test/iop_console_shell_test.dart` | API-2 regression as needed |
| `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md` | Roadmap update by runtime/update-roadmap after PASS only |

## 최종 검증

```bash
cd packages/flutter/iop_console && flutter test
cd apps/client && flutter test
cd apps/client && flutter analyze --no-fatal-infos
```

기대: package/client tests pass, analyzer has no fatal issues.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
