iop/agent-spec/index.md

spec_doc_type	status
index	활성

구현 스펙 색인

목적

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

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

읽기 규칙

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

영역별 요약

• 실행 경로: Edge와 Node 사이의 등록, 실행, 이벤트, provider raw tunnel, 취소, command 흐름은 runtime/edge-node-execution에서 본다.
• 런타임 라우팅/설정: provider-pool, models[], nodes[].providers[], live config refresh는 runtime/provider-pool-config-refresh에서 본다.
• 외부 HTTP 입력: OpenAI-compatible 호출, model-driven raw tunnel은 input/openai-compatible-surface, A2A JSON-RPC 호출은 input/a2a-json-rpc-surface에서 본다.
• 운영 제어: Control Plane, Edge enrollment, fleet/edge status, Flutter Client 상태 소비는 control/control-plane-operations에서 본다.

스펙 목록

id	상태	언제 읽나	path	주요 근거
runtime/edge-node-execution	부분	Edge-Node TCP/protobuf transport, Node 등록, run/cancel/command, provider raw tunnel, adapter 실행, Node local run store를 확인할 때	agent-spec/runtime/edge-node-execution.md	agent-contract/inner/edge-node-runtime-wire.md, apps/edge/internal/service/run_submit.go, apps/node/internal/node/run_handler.go
runtime/provider-pool-config-refresh	부분	models[], nodes[].providers[], provider-pool dispatch, long-context admission, Edge/Node config refresh를 확인할 때	agent-spec/runtime/provider-pool-config-refresh.md	agent-contract/inner/edge-config-runtime-refresh.md, packages/go/config/provider_types.go, apps/edge/internal/configrefresh/classify.go
input/openai-compatible-surface	부분	/v1/models, /v1/chat/completions, /v1/responses, OpenAI-compatible auth/metadata/workspace/tool handling, model-driven raw tunnel, usage metric, 외부 model route를 확인할 때	agent-spec/input/openai-compatible-surface.md	agent-contract/outer/openai-compatible-api.md, apps/edge/internal/openai/chat_handler.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	부분	Control Plane-Edge 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

작성 규칙

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