7. 세션 이벤트 (session.*)
7.1. 이력 복구
7.1.1. session.history (Client → Master)
재연결(reattach) 성공 직후 선제적으로 발송한다. RAWP-1.0-Legacy의 agent_session_history를 대체한다.
{
"type": "session.history",
"payload": {
"frames": [
"Object[] (필수, 단절 동안 버퍼에 쌓인 과거 프레임의 배열. 각 요소는 본 규격의 Envelope 전체)"
],
"buffer_status": {
"policy_applied": "String (필수, 'RING' | 'DROP' | 'NONE')",
"truncated": "Boolean (필수, 데이터 유실 발생 여부)",
"lost_frame_count": "Number (선택, 유실된 프레임 수 추정치)",
"buffer_high_watermark": "Number (선택, 버퍼 최대 사용량 바이트)"
},
"last_sync_timestamp": "String (필수, ISO 8601, 마지막 동기화 시각)",
"last_message_id": "String (필수, 마지막 동기화 message_id)"
}
}buffer_status.truncated가 true이면 마스터는 데이터 불완전성을 사용자에게 고지해야 한다 (MUST).
7.2. 컨텍스트 압축 보고
7.2.1. session.compacted (Client → Master)
에이전트가 자동 또는 수동 컨텍스트 압축을 수행한 후 결과를 보고한다.
{
"type": "session.compacted",
"payload": {
"summary": "String (필수, 압축 요약 텍스트)",
"previous_token_count": "Number (필수, 압축 전 토큰 수)",
"current_token_count": "Number (필수, 압축 후 토큰 수)",
"preserved_elements": {
"files_modified": ["String (선택, 수정된 파일 경로)"],
"decisions_made": ["String (선택, 주요 결정 사항)"],
"errors_encountered": ["String (선택, 미해결 에러)"],
"active_todos": ["Object (선택, 활성 TODO 항목)"]
},
"trigger": "String (필수, 'auto' | 'manual' | 'requested')"
}
}7.3. 사용량 지표
7.3.1. session.usage (양방향, 주로 Client → Master)
텍스트 생성 완료 시점(agent.text.done) 또는 Turn 종료 시 반드시 동반 발송해야 한다 (MUST). RAWP-1.0-Legacy의 agent_usage_metrics를 대체한다.
{
"type": "session.usage",
"payload": {
"turn_id": "String (선택, 사용량이 소속된 Turn)",
"token_usage": {
"input_tokens": "Number (필수)",
"output_tokens": "Number (필수)",
"cache_read_tokens": "Number (선택, 캐시 히트 토큰)",
"cache_write_tokens": "Number (선택, 캐시 기록 토큰)",
"thinking_tokens": "Number (선택, 사고 토큰)"
},
"cost_usage": {
"limit": "Number (필수, -1은 무제한)",
"used": "Number (필수)",
"unit": "String (필수, 'USD' 등)"
},
"message_usage": {
"limit": "Number (필수)",
"used": "Number (필수)",
"unit": "String (필수, 'COUNT')"
},
"context_window": {
"capacity": "Number (선택, 최대 토큰 윈도우)",
"used": "Number (선택, 현재 사용 중 토큰)",
"utilization": "Number (선택, 0.0–1.0, 사용률)"
},
"time_to_reset": "String (필수, ISO 8601)"
}
}7.4. 세션 에러
7.4.1. session.error (양방향)
세션 수준의 프로토콜 에러를 보고한다. 에이전트 수준 에러(agent.error)와 구분된다.
{
"type": "session.error",
"payload": {
"error_code": "String (필수)",
"message": "String (필수)",
"fatal": "Boolean (필수, true 시 세션 종료 절차 개시)"
}
}7.5. Turn 라이프사이클
7.5.1. session.turn.start (Client → Master)
에이전트가 새 Turn을 시작함을 알린다.
{
"type": "session.turn.start",
"payload": {
"turn_id": "String (필수, UUID v4)",
"turn_index": "Number (필수, 0-based 순번)",
"mode": "String (선택, 현재 동작 모드)"
}
}7.5.2. session.turn.end (Client → Master)
Turn이 완료되었음을 알린다. 이 이벤트 직후 session.usage가 동반되어야 한다 (MUST).
{
"type": "session.turn.end",
"payload": {
"turn_id": "String (필수)",
"stop_reason": "String (필수, 아래 열거 값)",
"tool_invocation_count": "Number (선택, 이 Turn에서의 도구 호출 횟수)"
}
}stop_reason 열거 값:
| 값 | 설명 |
|---|---|
end_turn |
정상 완료 |
max_tokens |
최대 토큰 도달 |
cancelled |
사용자/시스템 취소 |
error |
에러로 인한 중단 |
tool_use |
도구 사용 후 Turn 전환 (멀티턴) |
awaiting_input |
사용자 입력 대기 |