toki
5b95208f4c
- Update control-plane edge wire and edge-node runtime wire contracts - Refactor model queue service with admission control - Update chat handler and responses handler for edge - Modify run dispatch and status provider logic - Add/modify runtime proto definitions - Move G07 status logs to archive
71 lines
5.4 KiB
Markdown
71 lines
5.4 KiB
Markdown
# Edge-Node Runtime Wire Contract
|
|
|
|
## 계약 메타
|
|
|
|
- id: `iop.edge-node-runtime-wire`
|
|
- boundary: `inner`
|
|
- status: active
|
|
- 원본 경로:
|
|
- `proto/iop/runtime.proto`
|
|
- `apps/edge/internal/transport/server.go`
|
|
- `apps/node/internal/transport/client.go`
|
|
- `apps/node/internal/transport/session.go`
|
|
- `apps/node/internal/transport/parser.go`
|
|
- `apps/edge/internal/node/mapper.go`
|
|
- `apps/node/internal/adapters/config_set.go`
|
|
- human docs:
|
|
- `apps/edge/README.md`
|
|
- `apps/node/README.md`
|
|
|
|
## 읽는 조건
|
|
|
|
- Edge-Node TCP/protobuf transport, register handshake, run stream, cancel, node command, node config refresh를 바꿀 때
|
|
- `RunRequest`, `RunEvent`, `CancelRequest`, `NodeCommandRequest`, `NodeCommandResponse`, `NodeConfigPayload`, `NodeConfigRefresh*` 필드를 바꿀 때
|
|
- node adapter 설정 payload나 runtime config가 Edge에서 Node로 전달되는 방식을 바꿀 때
|
|
|
|
## 범위
|
|
|
|
이 계약은 Edge와 Node 사이의 내부 TCP proto-socket 경계다.
|
|
Edge는 Node 연결을 수락하고, Node는 연결 직후 등록 요청을 보낸다.
|
|
실행 요청과 이벤트 스트림, 취소, 조회성 명령, 설정 refresh는 같은 내부 wire 계열에서 처리한다.
|
|
|
|
## 주요 흐름
|
|
|
|
- register: Node가 `RegisterRequest`를 보내고 Edge가 `RegisterResponse`로 수락 여부와 `NodeConfigPayload`를 돌려준다.
|
|
- execution: Edge가 `RunRequest`를 보내고 Node가 `RunEvent` stream으로 실행 상태를 보낸다.
|
|
- cancel: Edge가 `CancelRequest`를 보내며 `CANCEL_RUN`과 `TERMINATE_SESSION`을 구분한다.
|
|
- command: Edge가 `NodeCommandRequest`를 보내고 Node가 `NodeCommandResponse`로 usage/capabilities/session/transport/provider 상태를 응답한다.
|
|
- refresh: Edge가 `NodeConfigRefreshRequest`로 새 config payload를 보내고 Node가 `NodeConfigRefreshResponse`로 적용/재시작 필요/실패를 응답한다.
|
|
|
|
## 필드 의미
|
|
|
|
- `RunRequest.adapter`, `RunRequest.target`: 내부 실행 식별자다. 외부 OpenAI-compatible `model`은 Edge 입력 표면에서 이 둘로 변환되어야 한다.
|
|
- `RunRequest.workspace`: CLI agent route 같은 workspace-bound 실행의 작업 디렉터리다.
|
|
- `RunRequest.input`: adapter가 해석할 실행 입력이다. CLI 실행에서는 prompt 계열 입력으로 변환된다.
|
|
- `RunRequest.metadata`: caller-defined 실행 metadata다. workspace 자체는 별도 `workspace` 필드로 전달한다.
|
|
- `RunEvent.type`: `start`, `delta`, `complete`, `error`, `cancelled` 같은 실행 이벤트 종류다.
|
|
- `RunEvent.metadata["openai_tool_calls"]`: OpenAI-compatible provider adapter가 native `tool_calls`를 반환했을 때 완료 이벤트에 싣는 JSON 배열이다. Edge OpenAI-compatible 표면은 이 값을 `message.tool_calls` 또는 stream `delta.tool_calls`로 복원한다. provider assistant content 텍스트를 이 값으로 파싱/합성하지 않는다.
|
|
- `RunEvent.metadata["openai_text_tool_fallback"]`: OpenAI-compatible provider adapter가 backend native tool API 거부 후 `tools`/`tool_choice`를 제거하고 text tool-call instruction으로 재시도했을 때 `"true"`를 싣는다. 이 instruction은 backend가 system role 위치를 거부하지 않도록 leading system message에 병합한다. Edge는 이 표시가 있는 실행에서만 assistant content의 text tool-call을 OpenAI-compatible `tool_calls`로 복원할 수 있다.
|
|
- `NodeCommandRequest.type`: 실행이 아닌 조회/제어성 명령이다. adapter execution 요청과 섞지 않는다.
|
|
- `NodeConfigPayload.adapters`: Edge가 Node에 내려주는 adapter instance 설정이다.
|
|
- `AdapterConfig.name`: node 내부 stable adapter instance identity다. 비어 있으면 legacy single-instance type 이름과 동등하다.
|
|
- `NodeRuntimeConfig.concurrency`: legacy compatibility runtime metadata다. 실행 admission은 이 값을 node-wide global gate로 사용하지 않고 provider/resource capacity를 기준으로 한다. Node store 위치나 CLI 실행 작업 디렉터리는 이 runtime payload에 싣지 않는다.
|
|
- `ProviderSnapshot`: legacy wire name을 유지하지만 Node 아래 resource/provider 상태 snapshot으로 해석한다. `category`가 `api`, `cli`, `local_inference` resource kind를 나타내며, provider-pool dispatch 대상은 Edge config `models[].providers`가 참조한 resource뿐이다. 또한 `long_context_capacity`, `long_in_flight`, `long_queued` 필드는 long-context admission 제어를 위해 사용되며, provider가 확보한 long slot 용량과 현재 점유 중인 long slot 수, 대기 중인 long 요청 수를 나타낸다.
|
|
|
|
## 금지 사항
|
|
|
|
- Control Plane이나 Client가 Node에 직접 연결하거나 직접 스케줄링하는 계약을 만들지 않는다.
|
|
- 외부 API의 `model` 용어를 이 내부 경계의 대표 실행 식별자로 되살리지 않는다.
|
|
- `proto/gen/iop/*.pb.go` 생성물을 직접 수정하지 않는다.
|
|
- transport handler에서 console/HTTP/A2A 표면 응답을 직접 만들지 않는다. 표면별 변환은 Edge service/input 계층에 둔다.
|
|
- Node address, token, transport internals를 Control Plane status 계약으로 노출하지 않는다.
|
|
|
|
## 변경 시 확인할 코드/테스트
|
|
|
|
- `proto/iop/runtime.proto`
|
|
- `apps/edge/internal/transport/*_test.go`
|
|
- `apps/node/internal/transport/*_test.go`
|
|
- `apps/edge/internal/node/mapper_test.go`
|
|
- `apps/node/internal/adapters/config_set_test.go`
|
|
- `apps/node/internal/adapters/adapters_blackbox_test.go`
|
|
- proto 변경 시 `make proto`, Client가 소비하면 `make proto-dart`
|