Merge pull request '에이전트 런타임 검증 기준 정리' (#6) from forge/runtime-review-001-attempt-2-run-bf2423062d52 into main

.forge/runtime-analysis-001-attempt-2-run-53557bb0b282.md

@@ -0,0 +1,3 @@
+# runtime-analysis-001-attempt-2-run-53557bb0b282
+
+Forge 이슈 작업 브랜치 `forge/runtime-analysis-001-attempt-2-run-53557bb0b282`.

runtime-analysis/AGENT_RUNTIME_ANALYSIS.md

@@ -0,0 +1,186 @@
+# Agent Runtime Analysis
+
+## 1. MiniMax 연결 아키텍처
+
+### 1.1 연결 관리 구조
+
+| 구성 요소 | 역할 | 의존성 |
+|-----------|------|--------|
+| MiniMaxConnector | MiniMax API와의 HTTP/WebSocket 연결 수립 및 관리 | ConnectionPool, RetryHandler |
+| ConnectionPool | 연결 풀링 및 리소스 관리 | - |
+| HealthChecker | 연결 상태 모니터링 및 헬스 체크 | MetricsCollector |
+
+### 1.2 연결 생명주기
+
+```
+[연결 요청] → [Pool 검증] → [연결 획득] → [API 호출] → [연결 반환]
+     ↓              ↓             ↓            ↓            ↓
+  timeout      pool_size     connection.   request.    connection.
+  check        check         acquired      duration    released
+```
+
+### 1.3 연결 풀 파라미터
+
+| 파라미터 | 기본값 | 설명 |
+|----------|--------|------|
+| pool_size | 10 | 최대 동시 연결 수 |
+| connection_timeout | 30s | 연결 수립 타임아웃 |
+| idle_timeout | 300s | 유휴 연결 유지 시간 |
+| max_retries | 3 | 최대 재시도 횟수 |
+
+---
+
+## 2. 출력 계약 (Output Contract)
+
+### 2.1 계약 검증 흐름
+
+```
+[API 응답] → [ContractEmitter] → [스키마 검증] → [타입 체크] → [출력 반환]
+                ↓                   ↓              ↓
+           contract.            contract.      contract.
+           validation          validation      validation
+           (counter)           (histogram)     (gauge)
+```
+
+### 2.2 계약 검증 규칙
+
+| 규칙 | 설명 | 메트릭 |
+|------|------|--------|
+| required_fields | 필수 필드 존재 여부 | contract.validation.required |
+| type_check | 데이터 타입 일치 여부 | contract.validation.type |
+| range_check |数值 범위 유효성 | contract.validation.range |
+| format_check | 문자열 포맷 검증 | contract.validation.format |
+
+### 2.3 계약 상태
+
+| 상태 | 코드 | 설명 |
+|------|------|------|
+| VALID | 200 | 계약 검증 통과 |
+| INVALID_SCHEMA | 400 | 스키마 불일치 |
+| VALIDATION_ERROR | 422 | 검증 실패 |
+| INTERNAL_ERROR | 500 | 내부 오류 |
+
+---
+
+## 3. 재시도 메커니즘 (Retry)
+
+### 3.1 재시도 정책
+
+| 항목 | 설정값 | 설명 |
+|------|--------|------|
+| max_attempts | 3 | 최대 재시도 횟수 |
+| initial_delay | 1s | 초기 지연 시간 |
+| max_delay | 30s | 최대 지연 시간 |
+| backoff_multiplier | 2.0 | 지연 증가 배율 |
+| jitter | true | 랜덤 지터 적용 |
+
+### 3.2 재시도 조건
+
+| 조건 | HTTP 코드 | 설명 |
+|------|-----------|------|
+| transient_error | 408, 429, 500, 502, 503, 504 | 일시적 오류 |
+| network_error | - | 네트워크 연결 실패 |
+| timeout | - | 요청 타임아웃 |
+
+### 3.3 재시도 메트릭
+
+| 메트릭 | 타입 | 라벨 | 설명 |
+|--------|------|------|------|
+| retry.attempt | Counter | endpoint, error_type | 재시도 발생 횟수 |
+| retry.success | Counter | endpoint | 재시도 후 성공 횟수 |
+| retry.exhausted | Counter | endpoint | 재시도 횟수 소진 횟수 |
+
+---
+
+## 4. 관측 지점 (Observation Points)
+
+### 4.1 관측 컴포넌트
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Observability Layer                       │
+├─────────────┬─────────────┬─────────────┬──────────────────┤
+│   Tracer    │  Metrics    │   Log       │   Alert          │
+│             │  Collector  │   Emitter   │   Manager        │
+├─────────────┴─────────────┴─────────────┴──────────────────┤
+│                    Agent Runtime Core                        │
+├─────────────┬─────────────┬─────────────┬──────────────────┤
+│ MiniMax     │ Connection  │ Contract    │   Retry          │
+│ Connector   │ Pool        │ Emitter     │   Handler        │
+└─────────────┴─────────────┴─────────────┴──────────────────┘
+```
+
+### 4.2 관측 포인트 매핑
+
+| 포인트 | 수집 데이터 | 출력 |
+|--------|------------|------|
+| request.start | 타임스탬프, 엔드포인트 | trace_id, span |
+| request.duration | 소요 시간 | histogram |
+| connection.acquired | 풀 이름, 대기 시간 | gauge, histogram |
+| connection.wait_time | 대기 시간, 풀 이름 | histogram |
+| connection.released | 풀 이름 | gauge |
+| contract.validation | 검증 결과, 스키마 버전 | counter, histogram |
+| circuit.state | 회로 차단기 상태 | gauge |
+| retry.attempt | 재시도 횟수, 오류 유형 | counter |
+
+### 4.3 메트릭 수집 파이프라인
+
+```
+[애플리케이션] → [Instrumentation] → [MetricsCollector] → [Prometheus]
+     ↓              ↓                   ↓                ↓
+  events        metrics            aggregation       scrape
+```
+
+---
+
+## 5. 서킷 브레이커 (Circuit Breaker)
+
+### 5.1 상태 전이
+
+```
+CLOSED ──[실패율 초과]──→ OPEN ──[시간 경과]──→ HALF_OPEN
+   ↑                         │                        │
+   └─────[재시도 성공]───────┴─────[성공 임계값]──────┘
+```
+
+### 5.2 설정 파라미터
+
+| 파라미터 | 기본값 | 설명 |
+|----------|--------|------|
+| failure_threshold | 50% | OPEN 전환 실패율 |
+| success_threshold | 2 | HALF_OPEN → CLOSED 성공 횟수 |
+| timeout | 60s | OPEN 상태 유지 시간 |
+
+### 5.3 서킷 브레이커 메트릭
+
+| 메트릭 | 타입 | 설명 |
+|--------|------|------|
+| circuit.state | Gauge | 현재 상태 (0=CLOSED, 1=OPEN, 2=HALF_OPEN) |
+| circuit.transitions | Counter | 상태 전이 횟수 |
+| circuit.rejected | Counter | 차단된 요청 수 |
+
+---
+
+## 6. 통합 메트릭 요약
+
+| 메트릭명 | 타입 | 라벨 | 출처 |
+|----------|------|------|------|
+| request.start | Counter | endpoint, method | MiniMaxConnector |
+| request.duration | Histogram | endpoint, status | MiniMaxConnector |
+| connection.acquired | Gauge | pool_name | ConnectionPool |
+| connection.wait_time | Histogram | pool_name | ConnectionPool |
+| connection.released | Gauge | pool_name | ConnectionPool |
+| retry.attempt | Counter | endpoint, error_type | RetryHandler |
+| retry.success | Counter | endpoint | RetryHandler |
+| retry.exhausted | Counter | endpoint | RetryHandler |
+| contract.validation | Counter | schema_version, result | ContractEmitter |
+| circuit.state | Gauge | endpoint | CircuitBreaker |
+| circuit.transitions | Counter | from_state, to_state | CircuitBreaker |
+| health.status | Gauge | component | HealthChecker |
+
+---
+
+## 7. 참조 문서
+
+- SPECIFICATION.md: 런타임 컴포넌트 및 의존성 정의
+- INVENTORY.json: 메트릭 및 컴포넌트 인벤토리

runtime-analysis/INVENTORY.json

@@ -0,0 +1,140 @@
+{
+  "inventory_version": "1.0.0",
+  "last_updated": "2026-07-10",
+  "components": {
+    "MiniMaxConnector": {
+      "type": "connector",
+      "description": "MiniMax API와의 HTTP/WebSocket 연결 관리",
+      "dependencies": ["ConnectionPool", "RetryHandler"],
+      "observation_points": ["request.start", "request.duration"]
+    },
+    "ConnectionPool": {
+      "type": "pool",
+      "description": "연결 풀링 및 리소스 관리",
+      "dependencies": [],
+      "observation_points": ["connection.acquired", "connection.wait_time", "connection.released"]
+    },
+    "HealthChecker": {
+      "type": "monitor",
+      "description": "연결 상태 모니터링 및 헬스 체크",
+      "dependencies": ["MetricsCollector"],
+      "observation_points": ["health.status"]
+    },
+    "ContractEmitter": {
+      "type": "validator",
+      "description": "출력 계약 검증 및 에미터",
+      "dependencies": [],
+      "observation_points": ["contract.validation"]
+    },
+    "RetryHandler": {
+      "type": "handler",
+      "description": "재시도 정책 및 지연 관리",
+      "dependencies": [],
+      "observation_points": ["retry.attempt", "retry.success", "retry.exhausted"]
+    },
+    "CircuitBreaker": {
+      "type": "protection",
+      "description": "서킷 브레이커 상태 관리",
+      "dependencies": ["MiniMaxConnector"],
+      "observation_points": ["circuit.state", "circuit.transitions", "circuit.rejected"]
+    }
+  },
+  "metrics": [
+    {
+      "name": "request.start",
+      "type": "Counter",
+      "labels": ["endpoint", "method"],
+      "description": "API 요청 시작 카운터"
+    },
+    {
+      "name": "request.duration",
+      "type": "Histogram",
+      "labels": ["endpoint", "status"],
+      "description": "API 요청 소요 시간"
+    },
+    {
+      "name": "connection.acquired",
+      "type": "Gauge",
+      "labels": ["pool_name"],
+      "description": "현재 획득된 연결 수"
+    },
+    {
+      "name": "connection.wait_time",
+      "type": "Histogram",
+      "labels": ["pool_name"],
+      "description": "연결 대기 시간"
+    },
+    {
+      "name": "connection.released",
+      "type": "Gauge",
+      "labels": ["pool_name"],
+      "description": "반환된 연결 수"
+    },
+    {
+      "name": "retry.attempt",
+      "type": "Counter",
+      "labels": ["endpoint", "error_type"],
+      "description": "재시도 발생 횟수"
+    },
+    {
+      "name": "retry.success",
+      "type": "Counter",
+      "labels": ["endpoint"],
+      "description": "재시도 후 성공 횟수"
+    },
+    {
+      "name": "retry.exhausted",
+      "type": "Counter",
+      "labels": ["endpoint"],
+      "description": "재시도 횟수 소진 횟수"
+    },
+    {
+      "name": "contract.validation",
+      "type": "Counter",
+      "labels": ["schema_version", "result"],
+      "description": "계약 검증 결과 카운터"
+    },
+    {
+      "name": "circuit.state",
+      "type": "Gauge",
+      "labels": ["endpoint"],
+      "description": "서킷 브레이커 상태 (0=CLOSED, 1=OPEN, 2=HALF_OPEN)"
+    },
+    {
+      "name": "circuit.transitions",
+      "type": "Counter",
+      "labels": ["from_state", "to_state"],
+      "description": "서킷 브레이커 상태 전이 횟수"
+    },
+    {
+      "name": "circuit.rejected",
+      "type": "Counter",
+      "labels": ["endpoint"],
+      "description": "차단된 요청 수"
+    },
+    {
+      "name": "health.status",
+      "type": "Gauge",
+      "labels": ["component"],
+      "description": "컴포넌트 헬스 상태"
+    }
+  ],
+  "observation_points": {
+    "Tracer": {
+      "description": "분산 추적 수집기",
+      "spans": ["request.start", "connection.acquired", "contract.validation"]
+    },
+    "MetricsCollector": {
+      "description": "메트릭 수집 및 집계",
+      "metrics": ["request.*", "connection.*", "retry.*", "contract.*", "circuit.*", "health.*"]
+    },
+    "LogEmitter": {
+      "description": "로그 출력",
+      "events": ["request.start", "retry.attempt", "contract.validation"]
+    },
+    "AlertManager": {
+      "description": "알림 및 경고 관리",
+      "triggers": ["circuit.state", "retry.exhausted", "health.status"]
+    }
+  }
+}

runtime-analysis/SPECIFICATION.md

@@ -0,0 +1,165 @@
+# Agent Runtime Specification
+
+## 1. 개요
+
+본 문서는 Agent Runtime의 컴포넌트 구조, 의존성, 메트릭 명명 규칙을 정의한다.
+
+## 2. 컴포넌트 의존성 다이어그램
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Agent Runtime                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────┐     ┌─────────────────┐                   │
+│  │ MiniMaxConnector │────▶│  ConnectionPool │                   │
+│  └────────┬────────┘     └─────────────────┘                   │
+│           │                                                       │
+│           ▼                                                       │
+│  ┌─────────────────┐     ┌─────────────────┐                   │
+│  │  RetryHandler   │     │  CircuitBreaker │                   │
+│  └─────────────────┘     └─────────────────┘                   │
+│                                                                 │
+│  ┌─────────────────┐     ┌─────────────────┐                   │
+│  │  HealthChecker  │────▶│ MetricsCollector│                   │
+│  └─────────────────┘     └─────────────────┘                   │
+│                                                                 │
+│  ┌─────────────────┐                                           │
+│  │ ContractEmitter │                                           │
+│  └─────────────────┘                                           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 3. 컴포넌트 정의
+
+### 3.1 MiniMaxConnector
+
+| 속성 | 값 |
+|------|-----|
+| 타입 | connector |
+| 설명 | MiniMax API와의 HTTP/WebSocket 연결 관리 |
+| 의존성 | ConnectionPool, RetryHandler |
+
+### 3.2 ConnectionPool
+
+| 속성 | 값 |
+|------|-----|
+| 타입 | pool |
+| 설명 | 연결 풀링 및 리소스 관리 |
+| 의존성 | 없음 |
+
+### 3.3 RetryHandler
+
+| 속성 | 값 |
+|------|-----|
+| 타입 | handler |
+| 설명 | 재시도 정책 및 지연 관리 |
+| 의존성 | 없음 |
+
+### 3.4 CircuitBreaker
+
+| 속성 | 값 |
+|------|-----|
+| 타입 | protection |
+| 설명 | 서킷 브레이커 상태 관리 |
+| 의존성 | MiniMaxConnector |
+
+### 3.5 HealthChecker
+
+| 속성 | 값 |
+|------|-----|
+| 타입 | monitor |
+| 설명 | 연결 상태 모니터링 및 헬스 체크 |
+| 의존성 | MetricsCollector |
+
+### 3.6 ContractEmitter
+
+| 속성 | 값 |
+|------|-----|
+| 타입 | validator |
+| 설명 | 출력 계약 검증 및 에미터 |
+| 의존성 | 없음 |
+
+## 4. 메트릭 명명 규칙
+
+### 4.1 명명 체계
+
+모든 메트릭은 **dot-notation** 형식을 사용한다:
+
+```
+{domain}.{subdomain}.{name}
+```
+
+### 4.2 도메인 분류
+
+| 도메인 | 설명 | 예시 |
+|--------|------|------|
+| request | 요청 관련 | request.start, request.duration |
+| connection | 연결 관련 | connection.acquired, connection.wait_time |
+| retry | 재시도 관련 | retry.attempt, retry.success |
+| contract | 계약 관련 | contract.validation |
+| circuit | 서킷 브레이커 관련 | circuit.state, circuit.transitions |
+| health | 헬스 체크 관련 | health.status |
+
+### 4.3 메트릭 정의
+
+| 메트릭명 | 타입 | 라벨 | 설명 |
+|----------|------|------|------|
+| request.start | Counter | endpoint, method | API 요청 시작 카운터 |
+| request.duration | Histogram | endpoint, status | API 요청 소요 시간 |
+| connection.acquired | Gauge | pool_name | 현재 획득된 연결 수 |
+| connection.wait_time | Histogram | pool_name | 연결 대기 시간 |
+| connection.released | Gauge | pool_name | 반환된 연결 수 |
+| retry.attempt | Counter | endpoint, error_type | 재시도 발생 횟수 |
+| retry.success | Counter | endpoint | 재시도 후 성공 횟수 |
+| retry.exhausted | Counter | endpoint | 재시도 횟수 소진 횟수 |
+| contract.validation | Counter | schema_version, result | 계약 검증 결과 카운터 |
+| circuit.state | Gauge | endpoint | 서킷 브레이커 상태 |
+| circuit.transitions | Counter | from_state, to_state | 서킷 브레이커 상태 전이 횟수 |
+| circuit.rejected | Counter | endpoint | 차단된 요청 수 |
+| health.status | Gauge | component | 컴포넌트 헬스 상태 |
+
+## 5. 관측 가능성 (Observability)
+
+### 5.1 관측 컴포넌트
+
+| 컴포넌트 | 설명 | 수집 데이터 |
+|----------|------|-------------|
+| Tracer | 분산 추적 수집기 | request.start, connection.acquired, contract.validation |
+| MetricsCollector | 메트릭 수집 및 집계 | request.*, connection.*, retry.*, contract.*, circuit.*, health.* |
+| LogEmitter | 로그 출력 | request.start, retry.attempt, contract.validation |
+| AlertManager | 알림 및 경고 관리 | circuit.state, retry.exhausted, health.status |
+
+### 5.2 데이터 흐름
+
+```
+[애플리케이션] → [Instrumentation] → [MetricsCollector] → [Prometheus]
+     ↓              ↓                   ↓                ↓
+  events        metrics            aggregation       scrape
+```
+
+## 6. 재시도 정책
+
+| 파라미터 | 기본값 | 설명 |
+|----------|--------|------|
+| max_attempts | 3 | 최대 재시도 횟수 |
+| initial_delay | 1s | 초기 지연 시간 |
+| max_delay | 30s | 최대 지연 시간 |
+| backoff_multiplier | 2.0 | 지연 증가 배율 |
+| jitter | true | 랜덤 지터 적용 |
+
+## 7. 서킷 브레이커 설정
+
+| 파라미터 | 기본값 | 설명 |
+|----------|--------|------|
+| failure_threshold | 50% | OPEN 전환 실패율 |
+| success_threshold | 2 | HALF_OPEN → CLOSED 성공 횟수 |
+| timeout | 60s | OPEN 상태 유지 시간 |
+
+## 8. 버전 정보
+
+| 항목 | 값 |
+|------|-----|
+| 스키마 버전 | 1.0.0 |
+| 문서 업데이트 | 2026-07-10 |