5. Phase 3: 세션 라이프사이클 및 연결 (Session & I/O)
세션 생명주기: INIT → RUNNING → DETACHED(소켓 단절 시) → TERMINATED
5.1. 세션 초기화 및 재연결 (Session Initialization)
신규 에이전트 실행 또는 DETACHED 상태 프로세스에 WSS 바인딩을 위한 티켓을 발급한다.
Endpoint: POST /v1/session/init (Local Client 제공)
Request:
{
"session_id": "String (필수, UUID v4)",
"agent_id": "String (reattach: false 시 필수)",
"workspace_path": "String (reattach: false 시 필수)",
"ticket": "String (필수, WSS 연결 인증용 난수 티켓)",
"reattach": "Boolean (선택, 기본값 false. true 시 기존 구동 중 프로세스 바인딩)",
"last_sync_timestamp": "String (선택, ISO 8601)",
"last_message_id": "String (선택, UUID)"
}제약 조건: reattach: true이나 해당 session_id가 존재하지 않거나 종료된 경우 404 Not Found 반환 (MUST).
Config 바인딩 제약 조건: 마스터 서버는 reattach: false로 세션을 초기화할 때, §4.1.8에 따라 양쪽 Config Scope(limits, capabilities)의 최신 스냅샷을 해당 세션에 바인딩해야 한다 (MUST). 양쪽 스코프의 초기 동기화(§4.1.2)가 완료되지 않은 클라이언트에 대해서는 세션 초기화를 시도해서는 안 된다 (MUST NOT).
5.2. 세션 명시적 종료 (Session Termination)
Endpoint: DELETE /v1/session/{session_id} (Local Client 제공)
제약 조건: 클라이언트는 자식 프로세스에 SIGTERM을 전송하고, 5초 내 종료되지 않으면 SIGKILL로 강제 종료 후 메모리 버퍼 및 소켓을 파기해야 한다 (MUST).
WSS 알림 의무: 세션 종료 처리 후 WSS 연결을 닫기 전에, 해당 세션에 바인딩된 모든 WSS Connection에 RAWP-DPS 1.0.1 §7.7의 session.deleted 이벤트를 발송해야 한다 (MUST). 발송 순서는 RAWP-DPS 1.0.1 §7.5.3(진행 중 항목 정리) → session.deleted → WSS 종료이다.
5.3. WebSocket 연결 수립 (WebSocket Upgrade)
Connection URI: wss://{client_address}/v1/ws/stream?ticket={ticket}&session_id={session_id}
인가 절차 (MUST):
- 클라이언트는 HTTP Upgrade 요청 수신 시 HTTP 헤더의
Sec-WebSocket-Protocol을 확인해야 한다. RAWP-DPS 1.0.1 적용 시rawp-dps-1.0을 우선 수락하고, 미지원 시rawp-1.0으로 폴백한다. 양측 모두 미지원 시426또는400을 반환해야 한다. - Query Parameter의
ticket과session_id를 검증하고, 만료되거나 불일치 시401 Unauthorized를 반환 후 연결을 거절한다. - 사용된 티켓은 1회 사용 시 즉시 무효화(Burn)해야 한다.
5.4. 세션 이름 변경 (Session Rename)
세션에 사용자 친화적 이름을 부여하고, 변경 사항을 모든 참여자에게 전파한다.
SSOT (Single Source of Truth): 이름 변경의 권한 있는 요청은 반드시 HTTP 엔드포인트(§5.4.1, §5.4.2, §5.4.3)를 통해 수행해야 한다 (MUST). RAWP-DPS 1.0.1 §7.6의 session.renamed 이벤트는 HTTP 변경 후 발송되는 알림 전용이며, 엣지나 마스터가 DPS WSS를 통해 session.renamed를 직접 발송하여 이름 변경을 요청하는 것은 허용되지 않는다 (MUST NOT).
5.4.1. 마스터 → 클라이언트 이름 변경
Endpoint: PATCH /v1/session/{session_id} (Local Client 제공)
Request:
{
"name": "String (필수, 새 세션 이름. 최대 200자)"
}Response (200 OK):
{
"session_id": "String (필수)",
"name": "String (필수, 변경된 이름)",
"updated_at": "String (필수, ISO 8601)"
}제약 조건: 존재하지 않거나 TERMINATED 상태인 세션에 대한 요청은 404 Not Found를 반환한다 (MUST).
WSS 알림 의무: HTTP 응답 후, 클라이언트는 해당 세션에 바인딩된 모든 WSS Connection에 RAWP-DPS 1.0.1 §7.6의 session.renamed 이벤트를 발송해야 한다 (MUST). 이는 로컬 UI WSS(§10.6)와 마스터 WSS를 모두 포함한다.
5.4.2. 엣지 → 마스터 이름 변경
Endpoint: PATCH /v1/edge/sessions/{session_id} (Master Server 제공)
Request/Response: §5.4.1과 동일한 스키마.
마스터는 이름 변경 수신 시 대상 로컬 클라이언트의 PATCH /v1/session/{session_id}를 호출하여 전파하고, 해당 세션에 연결된 모든 엣지 WSS에 RAWP-DPS 1.0.1 §7.6의 session.renamed 이벤트를 브로드캐스트해야 한다 (MUST).
5.4.3. 로컬 세션 이름 변경
Endpoint: PATCH /local/v1/sessions/{session_id} (Local Client 제공)
Request/Response: §5.4.1과 동일한 스키마.
HTTP 응답 후, 클라이언트는 해당 세션에 바인딩된 모든 WSS Connection에 session.renamed 이벤트를 발송해야 한다 (MUST).
5.5. 세션 동기화 프로토콜 (Session Synchronization)
클라이언트가 보유한 열려있는 세션 목록을 마스터 서버에 체계적으로 동기화하기 위한 프로토콜이다. §4.3.1의 에이전트 동기화와 동일한 Push/Pull 패턴을 적용한다.
A) 클라이언트 → 마스터 세션 보고 (Push)
클라이언트가 자신의 활성 세션 목록을 마스터 서버에 전체 교체(Full Replacement) 방식으로 푸시한다.
Endpoint: PUT /v1/nodes/sessions (Master Server 제공)
Request (Client → Master):
{
"sessions": [
{
"session_id": "String (필수, UUID v4)",
"session_name": "String (필수)",
"agent_id": "String (필수)",
"workspace_path": "String (필수)",
"status": "String (필수, 'INIT' | 'RUNNING' | 'DETACHED')",
"origin": "String (필수, §10.3 참조)",
"created_at": "String (필수, ISO 8601)",
"last_activity_at": "String (필수, ISO 8601)",
"total_turns": "Number (필수)"
}
]
}Response: 204 No Content
트리거 조건: 클라이언트는 다음 시점에 세션 목록을 보고해야 한다 (MUST):
- 페어링 완료(§3.3) 직후 초기 보고
- 세션 생성, 종료, 상태 변경 시
- 구현체가 정의한 주기적 갱신 시점
디렉토리 필터링 (MUST): 클라이언트가 복수의 마스터에 연결된 경우, 각 마스터의 관할 디렉토리 범위에 해당하는 세션(workspace_path 기준)만 필터링하여 전달해야 한다. 관할 디렉토리 설정 방식은 프로토콜 범위 밖이다.
버전 관리: 세션 동기화는 §4.1의 Config Scope와 달리 config_version 기반 버전 관리를 사용하지 않는다. 매 요청이 전체 교체이며, 마스터는 수신한 목록으로 기존 캐시를 덮어쓴다.
TERMINATED 상태의 세션은 목록에 포함하지 않는다 (MUST NOT).
B) 마스터 → 클라이언트 세션 요청 (Pull)
마스터 서버가 최신 세션 목록이 필요할 때 온디맨드로 호출한다.
Endpoint: GET /v1/sessions (Local Client 제공)
트리거 조건: 엣지의 노드별 세션 조회 요청(§9.2.5) 수신 시 캐시 미스, 마스터가 최신 정보를 확보해야 하는 시점에 호출한다.
Response (200 OK): Push의 sessions 스키마와 동일한 배열을 반환한다.
이 엔드포인트는 마스터 전용이며, 마스터의 관할 디렉토리에 따른 필터링은 클라이언트가 수행한다.