<!-- task=m-node-multi-target-serving-foundation/06+02,04_commands_caps plan=0 tag=API -->

# Plan - API

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

구현 완료 전 `CODE_REVIEW-local-G07.md`를 실제 변경 사항과 검증 출력으로 채운다. 사용자 전용 blocker는 review stub에 기록한다.

## 배경

멀티 adapter/profile/model target 환경에서는 `CAPABILITIES`, `SESSION_LIST`, `USAGE_STATUS`, provider passthrough command가 어떤 target에 대한 응답인지 명확해야 한다. 현재 command path는 adapter/target 문자열만 전달해 multi profile 결과가 모호해질 수 있다.

## 사용자 리뷰 요청 흐름

구현 중 차단은 active review stub에 기록한다. code-review가 후속 상태를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/node-multi-target-serving-foundation.md`
- Task ids:
  - `commands-caps`: `CAPABILITIES`, `SESSION_LIST`, `USAGE_STATUS`, provider passthrough command가 여러 adapter/profile/model target에서 모호하지 않은 결과를 반환한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-test/local/rules.md`
- `agent-test/local/node-smoke.md`
- `agent-test/local/edge-smoke.md`
- `apps/edge/internal/service/node_command.go`
- `apps/edge/internal/service/status_provider.go`
- `apps/edge/internal/service/service_test.go`
- `apps/node/internal/node/node.go`
- `apps/node/internal/node/node_test.go`
- `apps/node/internal/adapters/cli/cli.go`
- `apps/node/internal/runtime/types.go`
- `apps/node/internal/transport/session.go`
- `proto/iop/runtime.proto`

### 테스트 환경 규칙

- test_env: `local`
- command path는 node/edge 양쪽 단위 테스트와 최소 proto-socket command round-trip smoke가 필요하다. 이 plan은 `go test -count=1 ./apps/node/... ./apps/edge/internal/service/...`를 계약으로 둔다.

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

- CLI capabilities는 profile target list만 반환한다 (`apps/node/internal/adapters/cli/cli.go:182`).
- session list는 label 문자열 중심이라 adapter instance/profile identity가 확장될 때 모호해질 수 있다 (`apps/node/internal/adapters/cli/cli.go:356`).
- `NodeCommandRequest` listener는 typed request를 동기 처리하므로 long command가 command path를 막을 수 있다 (`apps/node/internal/transport/session.go:69`).

### 심볼 참조

- rename/remove 예정 심볼: 없음. `NodeCommandRequest`, `runtime.CommandRequest`, `Capabilities`, CLI `HandleCommand` 참조를 확인한다.

### 분할 판단

- predecessor `02`: adapter registry namespace 완료 필요. 현재 active plan, complete 없음.
- predecessor `04`: provider profile baseline 완료 필요. 현재 active plan, complete 없음.
- runtime concurrency scheduling은 `07`로 분리하고, 이 plan은 command result identity와 passthrough ambiguity만 다룬다.

### 범위 결정 근거

- OpenAI request routing과 provider execution은 선행 task에 있다.
- terminal gateway protocol 자체 변경은 필요할 때 별도 task로 분리한다.

### 빌드 등급

- build: `local-G07`, review: `local-G07`. command contract는 명확하고 단위 테스트로 방어 가능하다.

## 의존 관계 및 구현 순서

- `06+02,04_commands_caps`는 `02+01_adapter_registry`와 `04+01,02_engine_profiles` 완료 후 구현한다.

## 구현 체크리스트

- [ ] capabilities 응답이 adapter instance/profile/model target identity를 모호하지 않게 포함한다.
- [ ] session/usage/provider command가 target namespace를 정확히 보존한다.
- [ ] Edge service command DTO와 Node command handling 테스트를 갱신한다.
- [ ] 최종 검증 명령을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Command Identity Contract

- 문제: command request/response는 adapter/target/session 문자열을 전달하지만 multi profile에서 이 값이 adapter instance인지 model target인지 모호할 수 있다. CLI session list는 label 문자열만 기본 출력으로 제공한다 (`apps/node/internal/adapters/cli/cli.go:366`).
- 해결 방법: command request/response와 capabilities result에 route/profile namespace를 명확히 포함한다. Edge service DTO는 old fields를 유지하되 new identity fields를 채운다. CLI/session/provider command는 target namespace를 잃지 않고 반환한다.
- 수정 파일 및 체크리스트:
  - [ ] `proto/iop/runtime.proto`: command/capability identity 필드 보강 여부 확인.
  - [ ] `apps/node/internal/runtime/types.go`: command response/capability DTO 갱신.
  - [ ] `apps/node/internal/node/node.go`: command dispatch/result mapping 갱신.
  - [ ] `apps/node/internal/adapters/cli/cli.go`: session/usage result identity 보존.
  - [ ] `apps/edge/internal/service/node_command.go`: Edge command DTO 매핑 갱신.
- 테스트 작성: 추가한다. `node_test.go`에 multi adapter/profile command routing, `service_test.go`에 command request/response DTO, CLI 테스트에 session list identity 검증을 둔다.
- 중간 검증:
  - `go test -count=1 ./apps/node/... ./apps/edge/internal/service/...`

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `proto/iop/runtime.proto` | API-1 |
| `apps/node/internal/runtime/types.go` | API-1 |
| `apps/node/internal/node/node.go` | API-1 |
| `apps/node/internal/node/node_test.go` | API-1 |
| `apps/node/internal/adapters/cli/cli.go` | API-1 |
| `apps/edge/internal/service/node_command.go` | API-1 |
| `apps/edge/internal/service/status_provider.go` | API-1 |
| `apps/edge/internal/service/service_test.go` | API-1 |

## 최종 검증

```bash
go test -count=1 ./apps/node/... ./apps/edge/internal/service/...
```

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