7. 세션 이벤트 (session.*)
7.1. 이력 복구
7.1.1. session.history (Client → Master)
재연결(reattach) 성공 직후 선제적으로 발송한다.
{
"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).
{
"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 |
사용자 입력 대기 |
7.5.3. 세션 종료 시 진행 중 항목 처리
세션이 종료(RAWP 1.0.2 §5.2 DELETE /v1/session/{session_id} 또는 session.error (fatal: true))될 때, 진행 중인 Turn이 존재하면 다음 순서로 정리 프레임을 발송해야 한다 (MUST):
- 모든 미완료 도구 호출에 대해
tool.invoke.result(status:"cancelled")를 발송한다. session.turn.end(stop_reason:"error")를 발송한다.- WSS 연결을 종료한다.
위 프레임들은 WSS 연결 종료 전에 모두 발송 완료되어야 한다 (MUST). 진행 중인 Turn이 없으면 즉시 WSS를 종료한다.
7.6. 세션 이름 변경
7.6.1. session.renamed (양방향)
{
"type": "session.renamed",
"payload": {
"session_id": "String (필수, 대상 세션 식별자)",
"name": "String (필수, 변경된 세션 이름)",
"previous_name": "String (선택, 변경 전 세션 이름)",
"renamed_by": "String (필수, 'edge' | 'client' | 'master')"
}
}renamed_by는 이름 변경을 요청한 주체를 식별한다. 마스터는 이 이벤트를 해당 세션에 연결된 모든 엣지 WSS로 브로드캐스트해야 한다 (MUST).
7.7. 세션 삭제
7.7.1. session.deleted (양방향)
세션이 삭제(RAWP 1.0.2 §5.2 또는 §10.1.3)되었음을 통보한다. 마스터 또는 로컬 UI가 연결된 모든 참여자에게 세션 종료를 알리는 데 사용된다.
{
"type": "session.deleted",
"payload": {
"session_id": "String (필수, 삭제된 세션 식별자)",
"reason": "String (필수, 'user_request' | 'master_request' | 'timeout' | 'error')",
"deleted_by": "String (필수, 'edge' | 'client' | 'master' | 'system')"
}
}reason 열거 값:
| 값 | 설명 |
|---|---|
user_request |
사용자가 UI에서 명시적으로 세션 삭제 |
master_request |
마스터 서버가 DELETE /v1/session/{session_id}로 종료 |
timeout |
reattach_window 초과로 DETACHED 세션이 만료 |
error |
복구 불가능한 에러로 세션 강제 종료 |
이 이벤트는 §7.5.3의 종료 정리 프레임 이후, WSS 연결 종료 직전에 발송해야 한다 (MUST). 마스터는 이 이벤트를 해당 세션에 연결된 모든 엣지 WSS로 브로드캐스트해야 한다 (MUST).
7.8. WSS 연결 단절 복구 (Disconnect Recovery)
WSS Connection이 비정상적으로 종료(네트워크 단절, 서버 셧다운 등)된 후 클라이언트 또는 엣지 노드의 미완료 메시지 정리(Finalization) 및 재연결 시 복구(Unfinalization) 절차를 정의한다.
7.8.1. Finalization (미완료 메시지 정리)
WSS Connection의 close 또는 error 이벤트를 수신하면, 수신 측은 해당 세션의 미완료 상태를 다음 규칙에 따라 즉시 정리해야 한다 (MUST):
| 미완료 상태 | Finalization 동작 |
|---|---|
스트리밍 중인 텍스트 블록 (agent.text.delta 수신 후 agent.text.done 미수신) |
스트리밍을 종료하고, 수신된 텍스트까지를 확정한다. |
스트리밍 중인 사고 블록 (agent.thinking.delta 수신 후 agent.thinking.done 미수신) |
사고 스트리밍을 종료한다. |
미완료 도구 호출 (tool.invoke.request 수신 후 tool.invoke.result 미수신) |
로컬에서 tool.invoke.result (status: "cancelled", output: "Connection lost")를 합성하여 쌍을 완성한다. 합성된 결과에는 synthetic: true 플래그를 포함해야 한다 (MUST). |
미완료 Turn (session.turn.start 수신 후 session.turn.end 미수신) |
Turn을 종료 처리한다. stop_reason은 "disconnected"로 간주한다. |
대기 중인 상호작용 (agent.interaction.request 수신 후 control.interaction.response 미발송) |
상호작용 요청을 폐기하여 UI 블로킹을 해제한다. |
에이전트 상태 (thinking, tool_calling 등 비유휴 상태) |
idle 상태로 전환하여 입력 가능 상태를 복원한다. |
합성 블록의 식별: 로컬에서 합성한 모든 블록(cancelled tool-result, 종료된 Turn 등)은 synthetic: true 플래그를 Envelope의 metadata 객체에 포함해야 한다 (MUST). 이 플래그는 §7.8.2의 Unfinalization에서 합성 블록을 정확히 식별하고 제거하기 위해 필요하다.
{
"metadata": {
"synthetic": true
}
}7.8.2. Finalization 트리거 시점
다음 이벤트가 발생하면 Finalization을 수행해야 한다 (MUST):
- WSS close/error 이벤트 수신: 네트워크 단절, 서버 셧다운, 타임아웃 등으로 WSS Connection이 비정상 종료된 경우.
- 앱 재시작 후 영속 상태 복원: 앱이 재시작되어 이전 세션의 영속 상태를 복원할 때, 해당 세션의 WSS Connection이 이미 존재하지 않는 경우.
- 세션 명시적 종료: §7.5.3 및 §7.7의 절차가 우선 적용된다. 서버 측에서 정리 프레임이 정상 발송된 경우 Finalization은 불필요하다. 정리 프레임 없이 연결이 끊어진 경우에만 Finalization을 수행한다.
7.8.3. Unfinalization (재연결 복구)
reattach_window(RAWP 1.0.2 §4.1.5) 내에 WSS 재연결(reattach)이 성공하고 session.history(§7.1.1)를 수신한 경우, 이전에 수행한 Finalization을 되돌려야 한다 (MUST):
metadata.synthetic: true가 포함된 로컬 합성 블록(cancelled tool-result 등)을 식별하여 제거한다.session.history의frames배열에 포함된 프레임을 순서대로 재생하여 실제 서버 측 상태로 복원한다.session.history재생 완료 후, 정상 메시지 수신을 재개한다.
Unfinalization 불가 판정: 다음의 경우 Unfinalization을 수행하지 않고 Finalization 상태를 유지한다:
session.history의buffer_status.truncated가true인 경우. 데이터 유실이 발생했으므로 완전한 복구가 불가능하다.session.deleted이벤트가session.history의frames에 포함된 경우. 세션이 이미 종료되었으므로 복구 대상이 아니다.