스펙들 3
탐색 1.0.1 문서
버전
문서 변경 이력
섹션 20
현재 페이지 9
1.0.1 ko public

스펙

RAWP-DPS

Data processing specification for RAWP integrations.

변경 이력 전체 Markdown 목차 Markdown

6. 제어 이벤트 (control.*)

마스터 서버가 클라이언트(에이전트)로 전달하는 제어 명령이다.

6.1. 프롬프트/입력 전달

6.1.1. control.prompt.request (Master → Client)

{
  "type": "control.prompt.request",
  "payload": {
    "prompt_text": "String (필수, 사용자 입력. 파일 참조 토큰 포함 가능, §16.2 참조)",
    "input_type": "String (선택, 기본값 'text'. 아래 열거 값)",
    "context_files": [
      {
        "file_url": "String (필수, 참조 파일 URL)",
        "file_name": "String (필수)",
        "mime_type": "String (선택)",
        "intent": "String (선택, 'reference' | 'edit_target' | 'context')"
      }
    ],
    "file_references": [
      {
        "ref_id": "String (필수, prompt_text 내 토큰의 ref_id와 일치)",
        "path": "String (필수, workspace 기준 상대 경로)",
        "name": "String (필수, 파일명)",
        "extension": "String (선택, 확장자)",
        "mime_type": "String (선택, IANA MIME 타입)",
        "size_bytes": "Number (선택)",
        "workspace_relative_path": "String (필수, 워크스페이스 기준 상대 경로)"
      }
    ],
    "config_overrides": {
      "output_format": "String (선택, 'text' | 'json' | 'stream-json')",
      "json_schema": "Object (선택, 구조화 출력 스키마)",
      "max_turns": "Number (선택, 최대 Turn 수 제한)",
      "allowed_tools": ["String (선택, 허용 도구 목록)"],
      "denied_tools": ["String (선택, 금지 도구 목록)"]
    }
  }
}

input_type 열거 값:

값 설명
text 일반 텍스트 프롬프트
slash_command 슬래시 명령 (예: /compact, /cost)
continuation 이전 Turn에 이어지는 후속 입력
piped_stdin 파이프된 표준 입력 (headless 모드)

6.1.2. control.prompt.cancel (Master → Client)

진행 중인 에이전트 Turn을 취소한다. 수신 시 클라이언트는 현재 실행 중인 도구를 가능한 한 빨리 중단하고, agent.text.done(is_cancelled: true)을 발송해야 한다 (MUST).

{
  "type": "control.prompt.cancel",
  "payload": {
    "target_turn_id": "String (필수, 취소 대상 turn_id)",
    "reason": "String (선택, 'user_cancelled' | 'timeout' | 'quota_exceeded')"
  }
}

6.2. 상호작용 응답

6.2.1. control.interaction.response (Master → Client)

{
  "type": "control.interaction.response",
  "payload": {
    "interaction_id": "String (필수, 대응하는 agent.interaction.request의 interaction_id)",
    "selected_value": "String | [String] (필수, 단일 선택 또는 복수 선택 값)",
    "text_input": "String (선택, TEXT_INPUT 타입의 사용자 자유 입력)"
  }
}

6.2.2. control.interaction.timeout (Master → Client)

{
  "type": "control.interaction.timeout",
  "payload": {
    "interaction_id": "String (필수)"
  }
}

6.3. 세션 제어 명령

6.3.1. control.session.compact (Master → Client)

마스터가 컨텍스트 압축을 요청한다 (사용자의 /compact 명령 등).

{
  "type": "control.session.compact",
  "payload": {
    "instruction": "String (선택, 압축 시 보존할 내용 지시)",
    "target_token_ratio": "Number (선택, 0.0–1.0, 목표 압축 비율)"
  }
}

자동 압축 트리거 조건:

에이전트는 session.capabilities에서 context_compaction: true를 고지한 경우에 한하여 자동 압축을 수행할 수 있다 (MAY). 자동 압축의 트리거 조건은 다음을 따른다:

  • context_window.utilization ≥ 0.80이면 압축을 고려해야 한다 (SHOULD).
  • context_window.utilization ≥ 0.95이면 압축을 수행해야 한다 (MUST).
  • 자동 압축 시 session.compacted(§7.2.1)의 trigger 필드는 "auto"로 설정한다.
  • 마스터의 control.session.compact 없이 에이전트가 자체적으로 수행한다.

target_token_ratio 필드 의미:

  • target_token_ratio는 압축 후 목표 컨텍스트 윈도우 사용률을 의미한다. 값 범위: 0.0(최대 압축) ~ 1.0(압축하지 않음).
  • 예: target_token_ratio: 0.5이면 컨텍스트 윈도우의 50% 이하로 압축을 목표로 한다.
  • 이 값은 best-effort이다. 에이전트가 정확한 비율 달성을 보장하지 않는다.
  • 필드가 생략되면 에이전트의 기본 압축 전략을 따른다.

압축 미지원 시 동작:

session.capabilities에서 context_compaction: false이거나 미고지인 클라이언트가 control.session.compact를 수신하면, session.error (error_code: "COMPACTION_NOT_SUPPORTED", fatal: false)를 반환해야 한다 (MUST).

6.3.2. control.mode.switch (Master → Client)

에이전트 동작 모드를 전환한다.

{
  "type": "control.mode.switch",
  "payload": {
    "mode": "String (필수, 아래 열거 값)",
    "config": "Object (선택, 모드별 추가 설정)"
  }
}

mode 열거 값:

값 설명
default 기본 실행 모드 (읽기/쓰기/실행 모두 가능)
plan 계획 모드 (읽기/검색만 허용, 쓰기/실행 차단)
review 코드 리뷰 모드

모드별 도구 사용 제한:

모드 허용 도구 카테고리 금지 도구 카테고리
default 모든 카테고리 없음
plan search, filesystem(읽기 전용: Read, Glob, LS, Grep), web filesystem(쓰기: Write, Edit, MultiEdit), shell
review search, filesystem(읽기 전용), web filesystem(쓰기), shell

금지된 카테고리의 도구가 에이전트에 의해 호출 시도되면, 클라이언트는 해당 tool.invoke.request를 차단하고 tool.invoke.result (status: "error", output: "Tool not allowed in current mode")를 에이전트에 반환해야 한다 (MUST).

모드 전환 규칙:

  • Turn 진행 중(session.turn.start 수신 후 session.turn.end 수신 전)에는 모드를 전환할 수 없다 (MUST NOT). 진행 중에 control.mode.switch를 수신하면 session.error (error_code: "MODE_SWITCH_DURING_TURN", fatal: false)를 반환해야 한다 (MUST).
  • 모드 전환 성공 시 agent.state.changed (reason: "mode_switch")를 발송해야 한다 (MUST).
  • 전환 후 첫 Turn의 session.turn.start에 변경된 mode 필드를 포함해야 한다 (MUST).

미지원 시 동작:

session.capabilities에서 plan_mode: false이거나 미고지인 클라이언트가 control.mode.switch를 수신하면, session.error (error_code: "MODE_NOT_SUPPORTED", fatal: false)를 반환해야 한다 (MUST). 마스터는 plan_mode 미지원 클라이언트에 control.mode.switch를 발송해서는 안 된다 (MUST NOT).

참조