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

스펙

RAWP-CRS

Compliance rendering specification for RAWP consumers.

변경 이력 전체 Markdown 목차 Markdown

5. 시스템 메시지 (System Message)

시스템 메시지의 설계 목표는 대화의 맥락과 상태를 빠짐없이, 직관적으로 전달하는 것이다. 시스템 메시지는 프로토콜 또는 클라이언트가 생성한 상태 안내로, 대화의 두 참여자(User, Agent) 사이의 메타 정보를 전달한다.

5.1. 레이아웃 원칙: 중앙 정렬, 생략 금지

중앙 정렬: 시스템 메시지는 대화 영역의 수평 중앙에 정렬해야 한다 (MUST).

내용 생략 절대 금지 (No Ellipsis, No Truncation): 시스템 메시지의 텍스트는 어떠한 경우에도 말줄임표나 텍스트 잘림으로 생략되어서는 안 된다 (MUST NOT).

짧고 직관적인 메시지: 시스템 메시지의 본문은 최대한 짧고 직관적으로 작성해야 한다 (MUST). 예: ⏹ 응답이 중지되었습니다, ⚠ 세션 연결이 끊어졌습니다.

긴 내용의 드롭다운 처리: 시스템 메시지가 한 줄로 표현하기 어려운 상세 정보를 포함하는 경우 다음의 드롭다운 패턴을 적용해야 한다 (MUST):

  • 요약 행: 항상 노출되는 한 줄의 핵심 메시지. 예: ⚠ 도구 실행 실패 — 상세 보기 ▾
  • 상세 영역: 요약 행 하단에 접힌 상태로 배치. 사용자가 클릭 시 펼쳐져 전체 내용을 표시한다. 펼침 상태에서도 모든 텍스트가 완전히 노출되어야 하며 (MUST), 내부 스크롤이나 추가 생략을 적용해서는 안 된다 (MUST NOT).
  • 펼침/접힘 토글: 요약 행 우측에 화살표(▾/▴)를 배치하여 상세 영역의 존재를 시각적으로 암시한다 (MUST).

시각적 비중 최소화: 시스템 메시지는 사용자 메시지나 에이전트 응답보다 시각적 비중이 낮아야 한다 (SHOULD). 작은 폰트 크기, 연한 텍스트 색상, 배경색 없음 등으로 존재감을 줄이되, 완전히 보이지 않을 정도로 숨겨서는 안 된다.

반응형 너비 확보: 시스템 메시지 컨테이너의 가용 너비는 대화 영역 전체 폭의 60% 이상을 확보해야 한다 (MUST). 최대 너비는 90% 이내로 제한해야 한다 (SHOULD). 뷰포트 너비가 480px 이하인 환경에서는 좌우 여백을 최소화(예: 좌우 각 8~12px)하여 텍스트 영역을 우선 확보해야 한다 (SHOULD). 드롭다운 상세 영역은 요약 행과 동일한 컨테이너 너비를 유지해야 한다 (MUST).

5.2. 사용자 중지 피드백 (Cancellation Feedback)

사용자가 중지 버튼을 눌러 진행 중인 Turn을 취소하면(control.prompt.cancel 발송), 클라이언트는 대화 이력에 시스템 메시지를 삽입하여 취소가 실행되었음을 명시적으로 기록해야 한다 (MUST). 이는 대화 이력에 영구적으로 남는 항목이다.

렌더링 규격: §5.1의 레이아웃 원칙에 따라 중앙 정렬, 연한 텍스트, 배경색 없음으로 표시한다. 간결한 메시지(예: ⏹ 응답이 중지되었습니다)를 사용한다.

삽입 위치 및 타이밍: 에이전트의 마지막 출력 바로 아래에 삽입해야 한다 (MUST). control.prompt.cancel 발송 직후 즉시 표시하여 사용자에게 지체 없이 피드백해야 한다 (SHOULD).

부분 응답 보존: 중지 이전까지 수신된 agent.text.delta 텍스트는 삭제하지 않고 그대로 유지해야 한다 (MUST).

에이전트 상태 정리와의 관계: 시스템 메시지가 삽입되면, §4.7의 에이전트 상태 표시줄은 즉시 제거되어야 한다 (MUST).

5.3. 에러 및 경고 메시지

에이전트 에러(agent.error), 세션 에러(session.error), 연결 단절, 토큰 만료 등의 시스템 이벤트는 시스템 메시지로 표시한다.

심각도별 시각 차등:

심각도 시각 표현 예시
info 기본 시스템 메시지 스타일 (연한 텍스트) ℹ 세션이 재연결되었습니다
warning 주황/노랑 계열 아이콘, 텍스트는 기본 색상 유지 ⚠ 연결이 불안정합니다
fatal 빨강 계열 아이콘, 텍스트도 강조 색상 적용 ❌ 세션이 비정상 종료되었습니다

에러 상세 정보: 에러 메시지에 기술적 상세가 포함되는 경우, §5.1의 드롭다운 패턴을 적용하여 요약 행 + 접이식 상세 영역으로 구성한다 (MUST).

5.4. 세션 이벤트 메시지 (Session Event Messages)

세션 수준의 상태 변경 이벤트(session.renamed, session.deleted)는 시스템 메시지로 대화 이력에 삽입하여 사용자에게 상태 변화를 명시적으로 전달해야 한다 (MUST). §5.1의 레이아웃 원칙(중앙 정렬, 생략 금지, 시각적 비중 최소화)을 따른다.

5.4.1. 세션 이름 변경 (session.renamed)

RAWP-DPS 1.0.1 §7.6.1의 session.renamed 이벤트 수신 시, 대화 이력에 시스템 메시지를 삽입해야 한다 (MUST).

렌더링 규격:

  • 메시지 형식: 세션 이름이 "{previous_name}"에서 "{name}"으로 변경되었습니다 형태로 표시한다. previous_name이 없으면 세션 이름이 "{name}"(으)로 변경되었습니다로 표시한다.
  • 심각도: info 수준. §5.3의 info 스타일(연한 텍스트)을 적용한다.
  • 대화 이력 기록: 영구적 항목으로 대화 이력에 기록한다. 세션 재연결 시에도 표시되어야 한다.
  • 변경 주체 표시: renamed_by 값에 따라 변경 주체를 괄호 안에 부기할 수 있다 (MAY). 예: 세션 이름이 "작업 A"(으)로 변경되었습니다 (원격).
  • UI 제목 반영: 대화 창의 제목 표시줄 또는 세션 목록에 세션 이름이 표시되는 경우, 해당 영역도 즉시 갱신해야 한다 (MUST).

5.4.2. 세션 종료 (session.deleted)

RAWP-DPS 1.0.1 §7.7.1의 session.deleted 이벤트 수신 시, 대화 이력에 시스템 메시지를 삽입하고 세션의 종료 상태를 시각적으로 확정해야 한다 (MUST).

렌더링 규격:

  • reason별 메시지:
reason 시스템 메시지 예시 심각도
user_request 세션이 종료되었습니다 info
master_request 세션이 원격에서 종료되었습니다 info
timeout 연결 시간 초과로 세션이 종료되었습니다 warning
error 오류로 인해 세션이 종료되었습니다 fatal
  • 심각도별 스타일: §5.3의 심각도별 시각 차등 규칙을 적용한다.
  • 입력 비활성화: 세션 종료 메시지 표시 후, 입력창을 비활성화하거나 "세션이 종료되었습니다" 플레이스홀더를 표시하여 추가 입력이 불가능함을 명확히 해야 한다 (MUST).
  • 에이전트 상태 정리: §4.7의 에이전트 상태 표시줄이 활성 상태이면 즉시 제거해야 한다 (MUST).
  • 진행 중 항목 시각 전환: 세션 종료 시점에 진행 중이었던 도구 호출 스피너(§4.5.2)가 존재하면, 스피너를 중단하고 cancelled 상태로 전환하여 표시해야 한다 (MUST). 이는 RAWP-DPS 1.0.1 §7.5.3에서 발송되는 tool.invoke.result (status: "cancelled") 수신과 연동된다.
  • 대화 이력 기록: 영구적 항목으로 대화 이력에 기록한다.

5.5. 연결 단절 및 복구 피드백 (Disconnect & Recovery Feedback)

WSS Connection이 비정상 종료되거나 재연결에 성공한 경우의 렌더링 규칙을 정의한다. RAWP-DPS 1.0.1 §7.8의 Finalization/Unfinalization 절차와 연동된다.

5.5.1. 연결 단절 시 렌더링 (Finalization)

WSS 단절이 감지되면(RAWP-DPS 1.0.1 §7.8.2) 다음을 수행해야 한다 (MUST):

시스템 메시지 삽입: ⚠ 연결이 끊어졌습니다를 §5.3의 warning 심각도 스타일로 대화 이력에 삽입한다. 영구적 항목으로 기록한다.

스트리밍 텍스트 중단: 활성 스트리밍 중이던 텍스트(agent.text.delta)는 수신된 지점까지 확정하고, 하단 경계 효과(§4.3)를 즉시 제거한다 (MUST). 텍스트 끝에 시각적 절단 표시(예: … 또는 흐린 경계선)를 추가하여 텍스트가 완전하지 않음을 나타낼 수 있다 (MAY).

도구 호출 스피너 전환: 진행 중이던 도구 호출 스피너를 즉시 중단하고, cancelled 상태 표시(§4.5.2의 에러 결과 표시)로 전환해야 한다 (MUST). 합성된 cancelled 결과(RAWP-DPS 1.0.1 §7.8.1의 synthetic: true)는 연한 회색 텍스트로 연결 끊김으로 취소됨 등의 메시지를 표시한다.

사고 과정 중단: 활성 Thinking Indicator(§4.4)를 즉시 중단하고 접힌 상태로 전환해야 한다 (MUST).

에이전트 상태 표시줄 제거: §4.7의 상태 표시줄을 즉시 제거하고 입력 가능 상태로 복원해야 한다 (MUST).

상호작용 요청 폐기: 활성 상태인 상호작용 UI(승인 버튼, 선택 팝업 등)를 즉시 닫고, 해당 영역에 연결 끊김으로 취소됨을 표시해야 한다 (MUST).

5.5.2. 재연결 시 렌더링 (Unfinalization)

WSS 재연결이 성공하고 session.history(RAWP-DPS 1.0.1 §7.1.1)를 수신하면 다음을 수행해야 한다 (MUST):

시스템 메시지 삽입: ℹ 연결이 복구되었습니다를 §5.3의 info 심각도 스타일로 대화 이력에 삽입한다.

합성 블록 제거: Finalization에서 삽입한 합성 cancelled 결과(synthetic: true)를 제거하고, session.history의 실제 프레임으로 대체한다 (MUST).

스트리밍 재개: session.history 재생 후 에이전트가 응답을 계속 생성 중이면(새 agent.text.delta 수신), 스트리밍 렌더링을 정상 재개한다.

복구 불가 시: session.history의 buffer_status.truncated가 true이면, ⚠ 일부 메시지가 유실되었습니다를 warning 심각도로 추가 표시해야 한다 (MUST). 합성 블록은 제거하지 않고 유지한다.

참조