iop/agent-spec/index.md

---
spec_doc_type: index
status: 활성
---

# 구현 스펙 색인

## 목적

이 디렉터리는 IOP의 현재 구현을 빠르게 파악하기 위한 living spec이다.
AI agent가 작업 전에 읽는 지도이기도 하지만, 사람도 "지금 무엇이 어디까지 구현됐는지" 확인할 수 있어야 한다.

로드맵 완료 이력, SDD 설계 논의, 계약 원문, 사람용 가이드를 대체하지 않는다. 최종 기준은 항상 코드, `agent-contract/`, 테스트, 설정 예시다.

## 읽기 규칙

- 먼저 아래 "영역별 요약"으로 현재 찾는 주제를 고른다.
- 필요한 작업에서만 이 index를 읽고, 매칭되는 spec 문서만 읽는다.
- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다.
- API, wire protocol, config/event schema, 프로세스 간 계약 원문은 `agent-contract/`를 따른다.
- 코드 배치, 구현 진입점, 도메인 간 상세 책임 경계는 domain rule을 따른다.

## 영역별 요약

- 실행 경로: Edge와 Node 사이의 TLS identity, 등록, 실행, 이벤트, provider raw tunnel, transport heartbeat/reconnect, sealed credential lease consumption, 취소, command 흐름은 `runtime/edge-node-execution`에서 본다.
- 런타임 라우팅/설정: provider-pool, managed credential mode, `models[]`, top-level `protocol_profiles`, `nodes[].providers[].profile`, 그리고 refresh classification은 `runtime/provider-pool-config-refresh`에서 본다.
- 출력 검증 런타임: staged response-start, evidence hold/release, filter arbitration, bounded recovery/rebuild, raw-free observation은 `runtime/stream-evidence-gate`에서 본다.
- 외부 HTTP 입력: OpenAI-compatible 호출, Anthropic-compatible Messages 호출, managed principal route/slot binding, model-driven raw tunnel은 `input/openai-compatible-surface`, A2A JSON-RPC 호출은 `input/a2a-json-rpc-surface`에서 본다.
- 운영 제어: Control Plane, credential HTTPS/host-local bootstrap, mTLS Edge enrollment, projection/lease flow, fleet/edge status, Flutter Client 상태 소비는 `control/control-plane-operations`에서 본다.

## 스펙 목록

| id | 상태 | 언제 읽나 | path | 주요 근거 |
|----|------|-----------|------|-----------|
| `runtime/edge-node-execution` | 구현됨 | Edge-Node mTLS/protobuf transport, Node 등록, transport heartbeat/reconnect, provider run/cancel/command, provider raw tunnel, signed/sealed credential lease consumption, single-request Plan/Review effective template 적용을 확인할 때 | `agent-spec/runtime/edge-node-execution.md` | `agent-contract/inner/execution-runtime.md`, `agent-contract/inner/edge-node-runtime-wire.md`, `apps/edge/internal/transport/server.go`, `apps/node/internal/transport/client.go`, `packages/go/singlerequesttemplate/template.go` |
| `runtime/stream-evidence-gate` | 구현됨 | Stream Evidence Gate의 normalized event, evidence hold/release, filter registry, recovery coordinator, OpenAI request rebuild와 observation을 확인할 때 | `agent-spec/runtime/stream-evidence-gate.md` | `packages/go/streamgate/runtime.go`, `apps/edge/internal/openai/stream_gate_runtime.go`, `agent-contract/outer/openai-compatible-api.md` |
| `runtime/provider-pool-config-refresh` | 부분 | `credential_plane`, managed/legacy exclusivity, TLS/key references, `models[]`, top-level `protocol_profiles`, `nodes[].providers[].profile`, provider-pool dispatch, long-context admission, `execution_presets[].single_request.templates`의 relative-only 로딩과 admission freeze, and restart/applied refresh classification을 확인할 때 | `agent-spec/runtime/provider-pool-config-refresh.md` | `agent-contract/inner/edge-config-runtime-refresh.md`, `packages/go/config/provider_types.go`, `packages/go/config/validate.go`, `packages/go/config/load.go`, `apps/edge/internal/configrefresh/classify.go` |
| `input/openai-compatible-surface` | 부분 | `/v1/models`, `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/messages/count_tokens`, `/anthropic/v1/models`, managed projection/slot routing, OpenAI-compatible auth/metadata/tool handling, selected-profile Chat token-limit normalization, unmarked caller-workspace upstream 400 projection, Anthropic bearer/`X-Api-Key` auth, provider-pool native/bridge admission, safe slot attribution, marked single-request 내부 stage template과 caller-visible I/O 경계, and OpenAI-only usage metrics를 확인할 때 | `agent-spec/input/openai-compatible-surface.md` | `agent-contract/outer/openai-compatible-api.md`, `agent-contract/outer/anthropic-compatible-api.md`, `apps/edge/internal/openai/chat_handler.go`, `apps/edge/internal/openai/anthropic_handler.go`, `apps/edge/internal/openai/anthropic_bridge.go`, `apps/edge/internal/openai/normalized_sse.go`, `apps/edge/internal/openai/usage_metrics.go` |
| `input/a2a-json-rpc-surface` | 부분 | Edge A2A JSON-RPC, `message/send`, `tasks/get`, `tasks/cancel`, A2A task store와 bearer auth를 확인할 때 | `agent-spec/input/a2a-json-rpc-surface.md` | `agent-contract/outer/a2a-json-rpc-api.md`, `apps/edge/internal/input/a2a/server.go`, `apps/edge/internal/input/a2a/task_store.go` |
| `control/control-plane-operations` | 부분 | credential HTTPS and host-local bootstrap, Control Plane-Edge mTLS projection/lease wire, Client-Control Plane wire, Control Plane HTTP Edge/fleet status view, Flutter Client status consumer를 확인할 때 | `agent-spec/control/control-plane-operations.md` | `agent-contract/inner/control-plane-edge-wire.md`, `agent-contract/inner/client-control-plane-wire.md`, `apps/control-plane/internal/wire/edge_server.go`, `apps/control-plane/internal/credentiallease/service.go` |

## 작성 규칙

- 한국어 설명을 우선하고, 코드/계약 식별자는 원문을 유지한다.
- 현재 구현 기준으로 작성한다.
- 기능 목록과 주요 흐름을 먼저 파악할 수 있게 작성한다.
- 코드/계약/테스트 evidence를 우선한다.
- 계약 원문은 복제하지 않고 링크한다.
- 코드 진입점과 도메인룰 성격의 상세 경계는 반복하지 않는다.
- 불확실한 내용은 단정하지 않고 `부분`, `불명확`, `확인 필요`로 남긴다.