스펙들 3
탐색 1.0.2 문서
버전
문서 변경 이력
섹션 12
현재 페이지 10
1.0.2 ko public

스펙

RAWP

Current RAWP specification.

변경 이력 전체 Markdown 목차 Markdown

10. 로컬 세션 관리 (Local Session Management)

본 장은 사용자가 데스크톱 앱에서 마스터 서버 없이 직접 에이전트와 대화하기 위한 로컬 세션 프로토콜을 정의한다. 로컬 세션은 §5의 원격 세션과 동일한 세션 상태 머신(INIT → RUNNING → DETACHED → TERMINATED)과 RAWP-DPS 1.0.1 프로토콜을 공유하되, 인증과 보안 모델이 다르다.

10.1. 로컬 세션 엔드포인트

로컬 세션 전용 엔드포인트는 /local/v1/ 접두사를 사용하여 원격(마스터 발) 엔드포인트(/v1/)와 네임스페이스를 분리한다.

10.1.1. 로컬 세션 생성

Endpoint: POST /local/v1/sessions (Local Client 제공)

Request:

{
  "agent_name": "String (필수, 실행할 에이전트 이름. §4.3의 에이전트 목록 참조)",
  "workspace_path": "String (필수, 작업 디렉토리 절대 경로)",
  "session_name": "String (선택, 세션 표시명. 생략 시 agent_name + 생성 시각으로 자동 생성)"
}

Response (201 Created):

{
  "session_id": "String (필수, UUID v4)",
  "ws_ticket": "String (필수, 1회용 WSS 연결 티켓)",
  "status": "String (필수, 'INIT')"
}

WSS 연결: ws://127.0.0.1:{port}/v1/ws/stream?ticket={ws_ticket}&session_id={session_id}

10.1.2. 로컬 세션 재개

Endpoint: POST /local/v1/sessions/{session_id}/resume (Local Client 제공)

Request:

{
  "last_sync_timestamp": "String (선택, ISO 8601)",
  "last_message_id": "String (선택, UUID)"
}

Response (200 OK):

{
  "session_id": "String (필수)",
  "ws_ticket": "String (필수, 1회용 WSS 연결 티켓)",
  "status": "String (필수, 'RUNNING')"
}

제약 조건: 존재하지 않거나 TERMINATED 상태인 세션에 대한 요청은 404 Not Found를 반환한다 (MUST).

10.1.3. 로컬 세션 종료

Endpoint: DELETE /local/v1/sessions/{session_id} (Local Client 제공)

제약 조건: §5.2와 동일한 종료 절차를 따른다. session.deleted WSS 알림 의무(§5.2)도 동일하게 적용된다.

Response: 204 No Content.

10.1.4. 로컬 세션 목록 조회

Endpoint: GET /local/v1/sessions (Local Client 제공)

Query Parameters:

파라미터 타입 필수 설명
status String 선택 'INIT', 'RUNNING', 'DETACHED' 중 하나. 미지정 시 모든 활성 세션 반환.
origin String 선택 'local' 또는 'remote'. §10.3 참조. 미지정 시 모든 origin의 세션 반환.

Response (200 OK):

{
  "sessions": [
    {
      "session_id": "String (필수)",
      "agent_name": "String (필수)",
      "workspace_path": "String (필수)",
      "session_name": "String (필수)",
      "status": "String (필수, 'INIT' | 'RUNNING' | 'DETACHED')",
      "origin": "String (필수, §10.3 참조)",
      "created_at": "String (필수, ISO 8601)",
      "last_activity_at": "String (필수, ISO 8601)"
    }
  ]
}

10.2. 로컬 인증 면제

  • 클라이언트의 HTTP/WSS 서버가 루프백 주소(127.0.0.1 또는 ::1)에 바인딩된 경우, /local/v1/ 접두 엔드포인트에 대해 Authorization 헤더 검증을 면제해야 한다 (MUST).
  • 클라이언트가 외부 네트워크 주소에 바인딩된 경우, /local/v1/ 엔드포인트를 노출해서는 안 된다 (MUST NOT). 이는 인증 없는 외부 접근을 차단하기 위함이다.

10.3. 세션 식별 (Session Origin)

모든 세션은 origin 속성을 가진다:

origin 값 설명
"local" §10.1.1을 통해 로컬에서 생성된 세션
"remote:{server_id}" §5.1을 통해 마스터 서버가 생성한 원격 세션. server_id는 마스터의 고유 식별자.

origin은 세션 생성 시 결정되며 변경할 수 없다 (MUST NOT).

10.4. 로컬 세션 보안 모델

  • 경로 검증 면제: 로컬 세션(origin: "local")은 §7.2의 경로 검증(workspace_path 범위 제한)을 적용하지 않는다. 사용자가 직접 조작하는 환경이므로 파일시스템 접근 범위를 제한하지 않는다.
  • 도구 승인: 로컬 세션에서의 도구 승인 요청은 RAWP-DPS 1.0.1 §4.3.1의 agent.interaction.request를 통해 사용자에게 직접 표시된다. 마스터를 경유하지 않는다.

10.5. 로컬-원격 세션 공존

  • 동일 에이전트에 대해 로컬 세션과 원격 세션이 동시에 존재할 수 있다 (MUST 지원).
  • 각 세션은 독립된 에이전트 프로세스 또는 SDK 인스턴스를 가진다. 세션 간 에이전트 상태를 공유하지 않는다 (MUST NOT).

10.6. 원격 세션 로컬 감지

마스터가 POST /v1/session/init(§5.1)로 원격 세션을 생성하면, 클라이언트는 해당 세션을 origin: "remote:{server_id}"로 등록한다. 이 세션은 GET /local/v1/sessions(§10.1.4) 응답에 포함되어야 한다 (MUST).

로컬 UI가 원격 세션에 연결할 때는 동일 클라이언트의 로컬 WSS 엔드포인트를 사용한다:

ws://127.0.0.1:{port}/v1/ws/stream?ticket={local_ticket}&session_id={session_id}

이때 local_ticket은 /local/v1/sessions/{session_id}/resume(§10.1.2)을 통해 발급받는다. 로컬 UI WSS 연결과 마스터 WSS 연결은 독립적이며, 에이전트의 DPS 이벤트는 양쪽 소켓 모두에 전달되어야 한다 (MUST).

참조