RAWP

4. Phase 2: 제어 및 모니터링 인터페이스 (Master → Client HTTP)

마스터 서버가 클라이언트를 호출할 때는 반드시 발급받은 access_token을 사용하며, 클라이언트는 서명을 검증해야 한다 (MUST).

4.1. 클라이언트 설정 동기화 (Client Configuration)

클라이언트는 시스템 한계치와 지원 능력을 서버에 동기화한다. 설정은 의미적 성격에 따라 독립된 Config Scope로 분리되며, 각 스코프는 전용 엔드포인트를 통해 전체 교체(Full Replacement) 방식으로 동기화된다. 마스터 서버는 수신한 설정 값으로 요청을 스로틀링하며, 보고되지 않은 기능을 요구해서는 안 된다 (MUST).

4.1.1. Config Scope 분리 원칙

클라이언트 설정은 다음 두 개의 Config Scope로 분리된다:

각 스코프는 독립된 config_version을 가지며, 한 스코프의 갱신이 다른 스코프의 버전에 영향을 주지 않는다 (MUST). 클라이언트는 변경이 발생한 스코프의 엔드포인트만 호출하면 되고, 변경되지 않은 스코프를 함께 재전송할 필요가 없다.

4.1.2. 초기 동기화 (Initial Synchronization)

클라이언트는 페어링 완료(§3.3) 직후 그리고 재기동 직후, 양쪽 Config Scope를 모두 동기화해야 한다 (MUST). 초기 동기화 시 config_version은 1로 시작한다. 서버는 양쪽 스코프의 초기 동기화가 완료되기 전까지 해당 클라이언트에 대한 세션 초기화(§5.1) 요청을 보류해야 한다 (MUST). 초기 동기화 미완료 상태에서 세션 초기화가 시도되면 서버는 503 Service Unavailable을 반환해야 한다 (MUST).

마스터 서버가 특정 스코프에 대한 설정을 보유하지 않은 상태에서 해당 클라이언트의 헬스 체크(§4.2) 또는 에이전트 탐색(§4.3)을 수행하는 것은 허용된다. 설정 동기화 보류 규칙은 세션 초기화에만 적용된다.

4.1.3. 런타임 설정 갱신 (Runtime Configuration Update)

클라이언트는 런타임 중 설정 변경이 발생할 때마다 해당 스코프의 엔드포인트를 호출하여 서버에 변경 사항을 동기화해야 한다 (MUST). 각 호출은 해당 스코프의 전체 필드를 포함하는 완전한 스냅샷이어야 하며, 부분 필드만 포함하는 것은 허용되지 않는다 (MUST NOT). 서버는 수신한 스냅샷으로 해당 스코프의 기존 상태를 전체 교체한다.

4.1.4. 설정 버전 관리 및 순서 보장 (Config Versioning)

모든 Config Scope 요청에는 config_version 필드가 포함되어야 한다 (MUST). 이 값은 각 스코프별로 독립적이며, 클라이언트가 해당 스코프의 설정을 변경할 때마다 반드시 1씩 단조 증가시켜야 한다 (MUST).

순서 보장 규칙: 마스터 서버는 수신한 config_version이 현재 보유한 해당 스코프의 버전보다 큰 경우에만 설정을 갱신해야 한다 (MUST). 현재 보유 버전 이하의 값이 수신되면 네트워크 지연에 의한 역전(stale update)으로 간주하고, 409 Conflict를 반환하여 거부해야 한다 (MUST). 이때 응답 바디에는 서버가 현재 보유 중인 config_version을 포함하여 클라이언트가 재동기화할 수 있도록 해야 한다 (MUST).

클라이언트 재기동 시 버전 처리: 클라이언트가 재기동될 때 이전 config_version을 영속적으로 보관하지 못하는 경우를 위해, 다음의 특수 규칙을 적용한다: config_version이 1인 요청은 서버가 보유한 버전과 무관하게 항상 수락해야 한다 (MUST). 이는 재기동 후 초기 동기화를 보장하기 위한 것이며, 서버는 config_version: 1 수신 시 내부 버전 카운터를 1로 리셋해야 한다. 단, 활성 세션이 존재하는 상태에서 config_version: 1이 수신되면, 서버는 이를 클라이언트 재기동 시그널로 해석하여 시스템 로그에 기록해야 한다 (MUST).

4.1.5. Resource Limits 동기화

클라이언트의 수량적 운영 제약을 서버에 동기화한다.

Endpoint: PUT /v1/nodes/config/limits (Master Server 제공)

Request (Client → Master):

{
  "config_version": "Number (필수, 이 스코프의 단조 증가 정수, 초기값 1)",
  "effective_at": "String (필수, ISO 8601, 클라이언트가 이 설정을 적용한 시각)",
  "reason": "String (선택, 변경 사유. 예: 'memory_pressure', 'scheduled_maintenance')",
  "limits": {
    "rate_limit": "Number (필수, 초당 처리 가능한 최대 HTTP 요청 수. 양의 정수)",
    "max_frame_size": "Number (필수, WSS 단일 프레임 최대 바이트. 최소 1024)",
    "reattach_window": "Number (필수, WSS 단절 시 DETACHED 상태 유지 시간 초. 0 이상 정수. 0이면 DETACHED 미지원으로, 단절 시 즉시 TERMINATED 전이)",
    "max_buffer_size": "Number (필수, 최대 메모리 버퍼 바이트. 양의 정수. max_frame_size 이상이어야 함)",
    "buffer_overflow_policy": "String (필수, 'RING' 또는 'DROP')"
  }
}

서버 검증 규칙 (MUST):

Response (200 OK):

{
  "config_version": "Number (수신한 버전 에코백)",
  "accepted_at": "String (ISO 8601, 서버가 설정을 수락하고 저장한 시각)",
  "active_sessions_affected": "Number (현재 RUNNING 또는 DETACHED 상태의 세션 수. 이 세션들은 이전 설정으로 계속 동작함. §4.1.8 참조)"
}

4.1.6. Capabilities 동기화

클라이언트가 지원하는 기능 목록을 서버에 동기화한다.

Endpoint: PUT /v1/nodes/config/capabilities (Master Server 제공)

Request (Client → Master):

{
  "config_version": "Number (필수, 이 스코프의 단조 증가 정수, 초기값 1)",
  "effective_at": "String (필수, ISO 8601, 클라이언트가 이 설정을 적용한 시각)",
  "reason": "String (선택, 변경 사유. 예: 'plugin_loaded: vision_v2', 'model_replaced: gpt4o')",
  "capabilities": [
    "String (지원 기능 식별자 배열. 예: 'vision_v1', 'tool_call_v2'. 빈 배열 허용)"
  ]
}

서버 검증 규칙 (MUST):

서버의 미인식 Capability 처리: 서버는 자신이 인식하지 못하는 capability 식별자를 수신하더라도, 형식 검증을 통과하면 거부 없이 저장해야 한다 (MUST). 이는 §1.3의 필드 무시 원칙(Postel's Law)과 일관되며, 클라이언트가 서버보다 먼저 새로운 기능을 탑재하는 시나리오를 허용하기 위함이다.

Response (200 OK):

{
  "config_version": "Number (수신한 버전 에코백)",
  "accepted_at": "String (ISO 8601, 서버가 설정을 수락하고 저장한 시각)",
  "active_sessions_affected": "Number (현재 RUNNING 또는 DETACHED 상태의 세션 수. 이 세션들은 이전 capabilities로 계속 동작함. §4.1.8 참조)"
}

4.1.7. 설정 갱신 에러 응답 (Config Update Errors)

설정 갱신 요청이 검증에 실패한 경우, 서버는 §7.1의 에러 응답 표준 규격을 확장한 다음 포맷으로 응답해야 한다 (MUST).

검증 실패 (422 Unprocessable Entity):

{
  "error_code": "String (에러 코드. 예: 'CONFIG_VALIDATION_FAILED')",
  "message": "String (휴먼 리더블 디버깅 메시지)",
  "field_errors": [
    {
      "field": "String (문제가 된 필드의 JSON Path. 예: 'limits.rate_limit', 'capabilities[2]')",
      "constraint": "String (위반된 제약 조건의 식별자. 예: 'POSITIVE_INTEGER', 'MIN_VALUE:1024', 'ENUM:RING|DROP')",
      "reason": "String (휴먼 리더블 설명. 예: 'MUST be a positive integer')"
    }
  ]
}

field_errors 배열에는 검증에 실패한 모든 필드가 포함되어야 한다 (MUST). 첫 번째 위반에서 중단하고 나머지를 생략해서는 안 된다. 이는 클라이언트가 한 번의 응답으로 모든 위반 사항을 파악하고 수정할 수 있도록 하기 위함이다.

버전 충돌 (409 Conflict):

{
  "error_code": "CONFIG_VERSION_CONFLICT",
  "message": "String (휴먼 리더블 디버깅 메시지)",
  "current_config_version": "Number (서버가 현재 보유 중인 해당 스코프의 config_version)"
}

current_config_version을 통해 클라이언트는 자신의 config_version을 서버 값 이상으로 재조정한 후 재시도할 수 있다.

4.1.8. 설정 적용 범위: Session-Pinned Config

런타임 설정 갱신은 새로 초기화되는 세션에만 적용되며, 이미 RUNNING 또는 DETACHED 상태인 세션에는 소급 적용되지 않는다 (MUST NOT). 이를 Session-Pinned Config라 한다.

바인딩 규칙:

• 신규 세션 (reattach: false): 마스터 서버가 POST /v1/session/init (§5.1)을 호출하는 시점에 보유한 각 스코프의 최신 설정 스냅샷을 해당 세션에 바인딩한다. 바인딩된 설정은 세션이 TERMINATED 상태로 전이될 때까지 불변이다 (MUST).
• 세션 재연결 (reattach: true): 원래 세션에 바인딩된 설정을 그대로 유지한다. 재연결 시점의 최신 설정으로 교체하지 않는다 (MUST NOT).

서버 추적 의무: 마스터 서버는 각 세션에 바인딩된 config_version 쌍(limits 스코프 버전 + capabilities 스코프 버전)을 세션 메타데이터로 보관해야 한다 (MUST). 이 정보는 세션의 행동을 예측하고 디버깅하는 데 필요하다.

활성 세션에 대한 서버의 행동 원칙: 설정 갱신 후에도 활성 세션은 바인딩된 이전 설정에 따라 동작하므로, 서버는 다음을 준수해야 한다 (MUST):

• 활성 세션에 대한 스로틀링은 해당 세션에 바인딩된 rate_limit 값을 기준으로 적용한다. 갱신된 값이 아니다.
• 활성 세션에 대한 기능 요구는 해당 세션에 바인딩된 capabilities 목록 내에서만 허용한다. 갱신 후 추가된 capability를 기존 세션에 요구해서는 안 된다.
• 갱신 후 제거된 capability가 활성 세션에 바인딩되어 있는 경우, 해당 세션은 정상적으로 계속 동작한다. 서버가 해당 세션을 강제 종료하거나 기능을 제한해서는 안 된다 (MUST NOT).

4.1.9. 레거시 호환: POST /v1/nodes/config (지원 종료)

POST /v1/nodes/config 엔드포인트는 지원이 종료되었다. 모든 클라이언트는 §4.1.5 및 §4.1.6의 분리된 PUT 엔드포인트를 사용해야 한다 (MUST).

4.2. 헬스 체크 (Health Check)

Endpoint: GET /v1/health (Local Client 제공)

Response:

{
  "status": "String (필수, 'online', 'busy', 'error')",
  "uptime": "Number (필수, 클라이언트 가동 초)",
  "active_sessions": "Number (선택, 현재 유지 중인 세션 수)"
}

상태 전이 규칙: 활성 세션이 0개면 즉시 online. 1개 이상 존재 시 busy. 세션이 0이 되면 즉시 online으로 복귀해야 한다 (MUST).

4.3. 에이전트 탐색 및 관리 (Agent Discovery & Management)

클라이언트 내 실행 가능한 에이전트 목록 조회 및 관리를 제공한다.

Endpoint: GET /v1/agents (Local Client 제공)

Response:

{
  "agents": [
    {
      "id": "String (필수, 고유 식별자)",
      "name": "String (필수, 세션 식별자로 사용될 이름)",
      "is_active": "Boolean (필수, 에이전트 활성화 상태)",
      "type": "String (필수, 'builtin' | 'custom')",
      "adapter_type": "String (필수, 'process' | 'sdk'. RAWP-DPS 1.0.1 §17.1 참조)",
      "supported_dps_versions": [
        "String (필수, 지원하는 DPS 프로토콜 버전. 예: 'rawp-dps-1.0')"
      ],
      "models": [
        {
          "id": "String (필수, 모델 식별자)",
          "name": "String (필수, 표시명)",
          "is_default": "Boolean (필수)"
        }
      ],
      "options": [
        {
          "name": "String (필수, 옵션 이름)",
          "type": "String (필수, 'string' | 'boolean' | 'number' | 'enum')",
          "required": "Boolean (필수)",
          "default": "Any (선택, 기본값)",
          "enum_values": ["String (선택, type이 'enum'일 때 허용 값 목록)"],
          "description": "String (선택, 옵션 설명)"
        }
      ],
      "single_turn_process": "Boolean (선택, 기본값 false. RAWP-DPS 1.0.1 §18 참조)",
      "description": "String (선택, 에이전트 설명)",
      "allowed_directories": [
        "String (선택, 에이전트가 실행 가능한 디렉토리 경로 목록)"
      ],
      "extensions": "Object (선택, 구현체별 확장 메타데이터를 위한 열린 객체)"
    }
  ]
}

type: "builtin"은 클라이언트에 사전 탑재된 에이전트, type: "custom"은 사용자가 등록한 커스텀 에이전트를 의미한다. models 배열이 비어 있으면 에이전트가 모델 선택을 지원하지 않음을 의미한다.

allowed_directories는 에이전트가 작업 가능한 디렉토리 경로의 목록이다. 미지정 시 디렉토리 제한이 없음을 의미한다. extensions는 프로토콜에 정의되지 않은 구현체별 메타데이터를 전달하기 위한 열린 객체이며, §1.3의 필드 무시 원칙을 따른다.

4.3.1. 에이전트 동기화 프로토콜 (Agent Synchronization)

클라이언트가 보유한 에이전트 목록을 마스터 서버에 체계적으로 동기화하기 위한 프로토콜이다.

A) 클라이언트 → 마스터 에이전트 보고 (Push)

클라이언트가 자신의 에이전트 목록을 마스터 서버에 전체 교체(Full Replacement) 방식으로 푸시한다.

Endpoint: PUT /v1/nodes/agents (Master Server 제공)

Request (Client → Master):

{
  "agents": ["Object (§4.3의 에이전트 스키마 배열)"]
}

Response: 204 No Content

트리거 조건: 클라이언트는 다음 시점에 에이전트 목록을 보고해야 한다 (MUST):

• 페어링 완료(§3.3) 직후 초기 보고
• 에이전트 추가, 수정, 삭제 시
• 구현체가 정의한 주기적 갱신 시점

버전 관리: 에이전트 동기화는 §4.1의 Config Scope와 달리 config_version 기반 버전 관리를 사용하지 않는다. 매 요청이 전체 교체이며, 마스터는 수신한 목록으로 기존 캐시를 덮어쓴다.

B) 마스터 → 클라이언트 에이전트 요청 (Pull)

마스터 서버가 최신 에이전트 목록이 필요할 때, 기존 GET /v1/agents(§4.3) 엔드포인트를 온디맨드로 호출하여 클라이언트로부터 직접 조회한다.

트리거 조건: 세션 생성(§5.1) 시 에이전트 캐시 미스, 엣지의 에이전트 목록 요청(§9.2 하위) 수신 시 등 마스터가 최신 정보를 확보해야 하는 시점에 호출한다.

C) 에이전트 삭제 시 세션 전파 (MUST)

클라이언트에서 에이전트가 삭제(§4.3.5)되면, 클라이언트는 해당 에이전트로 생성된 모든 활성 세션(INIT, RUNNING, DETACHED 상태)을 종료하고, 연결된 모든 마스터 서버에 해당 세션들이 삭제되었음을 전파해야 한다 (MUST). 세션 종료는 §5.2의 절차를 따르며, session.deleted WSS 알림 의무도 동일하게 적용된다. 클라이언트는 모든 관련 세션의 삭제 전파가 완료된 후에만 에이전트 삭제를 확정해야 한다 (MUST). 즉, 에이전트 레코드 제거는 세션 전파 완료 이후에 수행되어야 하며, 세션 전파가 실패한 경우 에이전트 삭제를 중단해야 한다.

4.3.2. 에이전트 상세 조회

Endpoint: GET /v1/agents/{agent_id} (Local Client 제공)

Response (200 OK): §4.3의 agents 배열 내 단일 에이전트 객체와 동일한 스키마.

에러: 존재하지 않는 agent_id 시 404 Not Found.

4.3.3. 커스텀 에이전트 등록

Endpoint: POST /v1/agents (Local Client 제공)

Request:

{
  "name": "String (필수, 최대 100자)",
  "adapter_type": "String (필수, 'process' | 'sdk')",
  "command": "String (adapter_type이 'process'일 때 필수, 실행 명령어)",
  "supported_dps_versions": ["String (필수)"],
  "models": ["Object (선택, §4.3의 모델 스키마)"],
  "options": ["Object (선택, §4.3의 옵션 스키마)"],
  "single_turn_process": "Boolean (선택)",
  "resume_flag": "String (선택, single_turn_process: true일 때. RAWP-DPS 1.0.1 §18.1 참조)",
  "description": "String (선택)"
}

Response (201 Created): 생성된 에이전트 객체 (type: "custom", is_active: true).

제약 조건: name이 기존 에이전트와 중복되면 409 Conflict를 반환한다 (MUST).

4.3.4. 커스텀 에이전트 수정

Endpoint: PATCH /v1/agents/{agent_id} (Local Client 제공)

Request: §4.3.3의 필드 중 변경할 필드만 포함. type: "builtin" 에이전트는 수정할 수 없다 (MUST NOT). 시도 시 403 Forbidden.

Response (200 OK): 수정된 에이전트 객체.

4.3.5. 커스텀 에이전트 삭제

Endpoint: DELETE /v1/agents/{agent_id} (Local Client 제공)

제약 조건: type: "builtin" 에이전트는 삭제할 수 없다 (MUST NOT). 시도 시 403 Forbidden. 해당 에이전트에 활성 세션이 존재하면 409 Conflict를 반환한다 (MUST).

Response: 204 No Content.

4.3.6. 에이전트 활성화/비활성화

Endpoint: PATCH /v1/agents/{agent_id}/status (Local Client 제공)

Request: {"is_active": "Boolean (필수)"}

Response (200 OK): {"id": "String", "is_active": "Boolean"}

비활성화된 에이전트(is_active: false)는 GET /v1/agents 목록에 포함되지만, 세션 초기화(§5.1)에서 해당 agent_id 사용이 거부된다 (MUST). 거부 시 400 Bad Request (error_code: "AGENT_INACTIVE").

4.4. 파일 탐색 (Directory Browsing)

인가된 작업 경로 내의 디렉토리를 조회한다. 세션 내 작업 경로 탐색은 본 절을, 세션 생성 전 파일시스템 브라우징은 §4.5를 참조한다.

Endpoint: POST /v1/fs/list (Local Client 제공)

Request: {"target_path": "String (필수, 조회할 절대 경로)"}

4.5. 파일시스템 브라우징 (Filesystem Browsing)

세션 생성 전에 마스터가 클라이언트의 파일시스템을 탐색하여 작업 디렉토리(workspace_path)를 선택하기 위한 엔드포인트다. §4.4의 POST /v1/fs/list는 세션 내 인가된 작업 경로 탐색 용도이며, 본 엔드포인트는 세션 생성 이전 단계에서 사용한다.

Endpoint: POST /v1/fs/browse (Local Client 제공)

Request:

{
  "agent_id": "String (필수, §4.3 에이전트 식별자)",
  "path": "String (선택, 탐색할 절대 경로. 생략 시 루트 탐색)",
  "include_files": "Boolean (선택, 기본값 true)",
  "include_hidden": "Boolean (선택, 기본값 false)"
}

깊이 규칙:

Response (200 OK):

{
  "agent_id": "String (필수)",
  "base_path": "String (필수, 루트 모드 시 빈 문자열)",
  "os_type": "String (필수, 'unix' | 'windows')",
  "entries": [
    {
      "name": "String (필수, 항목 이름)",
      "path": "String (필수, 절대 경로)",
      "type": "String (필수, 'directory' | 'file' | 'symlink_directory' | 'symlink_file')",
      "size": "Number (선택, 파일만. 바이트 단위)",
      "modified_at": "String (선택, ISO 8601)",
      "readable": "Boolean (필수, OS 읽기 권한 보유 여부)",
      "children": ["Entry (선택, 디렉토리만. 재귀 구조)"],
      "truncated": "Boolean (선택, 자식 목록 잘림 여부)",
      "total_children_count": "Number (선택, 잘림 시 실제 자식 수)",
      "error": "String (선택, OS 에러 메시지)"
    }
  ],
  "truncated": "Boolean (필수, 최상위 항목 목록 잘림 여부)",
  "total_entries_count": "Number (선택, 잘림 시 실제 항목 수)"
}

권한 모델:

• allowed_directories(§4.3) 범위 밖 경로 요청 시 403 Forbidden (PATH_NOT_ALLOWED)을 반환해야 한다 (MUST).
• path가 allowed_directories의 조상 경로인 경우, allowed_directories로 이어지는 디렉토리만 필터링하여 노출해야 한다 (MUST). 범위 밖 항목은 응답에 포함하지 않는다.
• 요청한 path 자체에 OS 읽기 권한이 없으면 403 Forbidden (PATH_NOT_READABLE)을 반환해야 한다 (MUST).
• 미등록 agent_id → 404 Not Found (AGENT_NOT_FOUND).
• 비활성 에이전트(is_active: false) → 400 Bad Request (AGENT_INACTIVE).

엣지 케이스:

• 심링크: symlink_directory/symlink_file 타입으로 구분한다. 심링크가 allowed_directories 범위 밖을 가리키면 readable: false로 표시해야 한다 (MUST). 순환 심링크 감지 시 해당 항목의 error에 원인을 명시하고 자식 탐색을 중단해야 한다 (MUST).
• 숨김 항목: include_hidden: false(기본값) 시 .으로 시작하는 항목을 제외한다.
• 정렬: 디렉토리 우선, 이름 사전순 (대소문자 무시).
• Truncation: 디렉토리당 최대 500개 항목. 초과 시 truncated: true와 total_children_count(또는 최상위의 total_entries_count)를 설정한다.
• 타임아웃: 10초 내 응답해야 하며 (MUST), 초과 시 수집된 부분 결과를 truncated: true로 반환한다.
• Windows: os_type: "windows", 드라이브 문자 루트(C:\ 등), \ 경로 구분자를 사용한다.

에러 응답: