code-agent: implement issue 6

Approval-Correlation: e5da4592756fb704256d8737d31662e5
Plan-SHA256: 0fbe8b996656fb908c513b31e30706f7521cf76eeac60778a1c28f46bfc19b46
Bundle-SHA256: 29ce1ef1917864f79938459725201e6e74d67e21b1f817ac53d7b294eca8f1a2
Base-SHA: cabd354d71

docs/interface-contract.md

@@ -1,38 +1,62 @@
+<!-- gitea-agent:documentation-template/interface-contract/v1 -->
 # 인터페이스 계약
 
-## 메시지 제출 이벤트
+## 목적과 범위
 
-Textual의 `Input.Submitted` 이벤트가 `#user-input`에서 발생하면 `ChatApp.on_input_submitted`가 처리한다.
+이 문서는 대화형 Textual 화면에서 사용자 메시지와 에이전트 응답을 작성자 역할, 라벨, 구조적 스타일 및 표시 순서로 구분하는 인터페이스를 정의한다. 메시지 역할과 본문은 표시 결과의 정본이며, 외부 API 연동이나 영속 저장은 범위에 포함하지 않는다.
 
-### 입력 정규화
+## 계약
 
-1. 이벤트의 `value`에 `strip()`을 적용한다.
-2. 입력 위젯의 값을 빈 문자열로 초기화한다.
-3. 정규화 결과가 빈 문자열이면 추가 처리를 중단한다.
+- 각 메시지는 작성자 역할과 본문을 함께 가져야 한다.
+- 사용자 역할은 `user`, 에이전트 역할은 `agent`로 표현한다.
+- 사용자 역할의 화면 라벨은 `사용자`, 에이전트 역할의 화면 라벨은 `에이전트`다.
+- 사용자 메시지는 `사용자: 본문` 형식으로, 에이전트 응답은 `에이전트: 본문` 형식으로 표시한다.
+- 사용자 메시지는 `chat-message user-message user-role` 클래스를 사용하고, 에이전트 응답은 `chat-message response-message agent-role` 클래스를 사용한다.
+- 사용자 메시지와 에이전트 응답은 각각 왼쪽과 오른쪽 정렬 및 서로 다른 측면 테두리로 구분한다.
+- 유효한 입력 하나는 사용자 메시지 다음에 에이전트 응답을 추가한다.
 
-공백만 포함한 입력은 사용자 메시지, 응답 선택, 대화 항목을 생성하지 않는다.
+### `conversation-message-rendering`
 
-### 유효한 입력 처리
+메시지 렌더링 인터페이스는 명시적인 역할을 가진 메시지 값을 화면 항목으로 변환한다.
 
-정규화 결과가 비어 있지 않으면 다음 순서로 처리한다.
+- 입력: 작성자 역할과 문자열 본문을 가진 메시지
+- 출력: 작성자 라벨과 본문을 결합한 라벨 위젯
+- 사용자 역할: `user` 값, `사용자` 라벨, `user-message` 및 `user-role` 클래스
+- 에이전트 역할: `agent` 값, `에이전트` 라벨, `response-message` 및 `agent-role` 클래스
+- 표시 형식: 역할 라벨, 콜론, 공백, 본문 순서
+- 구조적 표현: 사용자 항목은 왼쪽 정렬과 왼쪽 테두리, 에이전트 항목은 오른쪽 정렬과 오른쪽 테두리
+- 순서: 유효한 제출마다 사용자 메시지를 먼저 표시하고 대응하는 에이전트 응답을 바로 뒤에 표시
 
-1. 정규화된 사용자 메시지를 `submitted_inputs`에 추가한다.
-2. `random.choice(RESPONSE_MESSAGES)`로 응답을 선택한다.
-3. 선택 응답을 `selected_responses`에 추가한다.
-4. 대화 영역에 사용자 메시지 `Label`을 추가한다.
-5. 바로 이어서 응답 `Label`을 추가한다.
-6. 대화 영역을 마지막 항목까지 스크롤한다.
+역할과 본문은 하나의 메시지 의미로 취급하며, 라벨과 스타일은 역할에서 파생한다. 화면의 위치나 스타일만으로 작성자를 판정해서는 안 된다. 메시지 본문은 사용자 입력의 앞뒤 공백을 제거한 값 또는 고정 응답 목록에서 선택된 값이어야 한다.
 
-사용자 메시지와 응답은 별도 대화 항목이며, 화면 표시 순서는 항상 사용자 메시지 다음 응답이다.
+빈 입력이나 공백만 포함한 입력은 정상적인 렌더링 요청으로 간주하지 않는다. 이 경우 응답을 선택하지 않고 메시지 목록과 대화 영역을 변경하지 않으며, 입력창만 비운다.
 
-## 화면 위젯 계약
+호환성을 위해 기존 대화 영역과 입력창의 위젯 식별자, 사용자 및 응답 항목의 클래스, Enter 제출, 고정 응답 선택, Escape와 Ctrl+Q 종료 동작을 유지한다. 작성자 라벨과 역할 클래스는 기존 표시 항목에 추가되는 계약이며, 대화 영역 전체 레이아웃을 재설계하지 않는다.
 
-- 대화 영역은 `#conversation` 식별자의 `VerticalScroll`이다.
-- 입력창은 `#user-input` 식별자의 `Input`이다.
-- 사용자 메시지는 `user-message` 클래스를 사용한다.
-- 응답은 `response-message` 클래스를 사용한다.
-- 애플리케이션 마운트 시 입력창에 포커스를 둔다.
+검증에서는 정상 입력 두 건을 제출하여 역할, 본문, 라벨, 클래스 및 표시 순서를 함께 비교한다. 역할별 정렬과 테두리 규칙이 색상과 독립적으로 존재하는지 확인하고, 빈 입력과 공백 입력에서 응답 선택과 새 화면 항목이 발생하지 않는지 확인한다. 또한 표준 응답 선택 호출과 종료 동작이 기존 방식대로 유지되는지 확인한다.
 
-## 종료 계약
+## 호환성
 
-`Escape`와 `Ctrl+Q`는 기존 `quit` 바인딩을 통해 애플리케이션 종료를 요청한다.
+- Enter로 제출하는 기존 입력 방식을 유지한다.
+- 입력은 앞뒤 공백을 제거한 뒤 처리하며, 빈 입력이나 공백만 있는 입력은 응답 선택과 화면 변경 없이 무시한다.
+- 응답은 기존 고정 응답 목록에서 표준 무작위 선택 방식으로 생성한다.
+- 기존 대화 영역과 입력창의 위젯 식별자 및 메시지 표시 순서를 유지한다.
+- Escape와 Ctrl+Q 종료 동작을 유지한다.
+- 역할 의미는 화면 위치나 CSS 클래스만으로 추론하지 않고 메시지 데이터에서 직접 제공한다.
+
+## 예시
+
+- 입력값이 `  첫 번째 입력  `이면 `사용자: 첫 번째 입력`으로 표시한다.
+- 선택된 응답이 `맡겨만 주세요.`이면 `에이전트: 맡겨만 주세요.`로 표시한다.
+- 여러 제출은 각 제출마다 사용자 메시지와 에이전트 응답의 쌍을 만들며, 전체 순서는 제출 순서와 일치한다.
+- 사용자 항목에는 왼쪽 정렬과 왼쪽 테두리를 적용하고, 에이전트 항목에는 오른쪽 정렬과 오른쪽 테두리를 적용한다.
+- 빈 문자열 또는 공백 문자열을 제출하면 새 라벨과 응답이 생성되지 않는다.
+
+## 검증
+
+- 역할 값과 본문이 올바르게 결합되어 메모리의 메시지 목록에 보존되는지 확인한다.
+- 렌더링된 라벨이 역할별 접두사와 본문을 정확히 포함하는지 확인한다.
+- 역할별 CSS 클래스, 정렬 규칙 및 양쪽 테두리가 구현에 존재하는지 확인한다.
+- 여러 입력에서 사용자 메시지 뒤에 에이전트 응답이 표시되는지 확인한다.
+- 빈 입력과 공백 입력에서 응답 선택, 메시지 기록 및 라벨 추가가 발생하지 않는지 확인한다.
+- 기존 무작위 응답 선택과 종료 동작이 변경되지 않았는지 회귀 검증한다.