gitea-agent-testbed/docs/runtime-flow.md

<!-- gitea-agent:documentation-template/runtime-flow/v1 -->
# 런타임 흐름

## 목적과 범위

이 문서는 사용자가 입력을 제출한 시점부터 사용자 메시지와 에이전트 응답을 역할별로 생성하고 화면에 렌더링하는 실행 범위를 정의한다. 입력은 앞뒤 공백을 제거한 뒤 처리하며, 유효한 입력마다 고정 응답 목록에서 하나의 응답을 선택한다. 외부 API, LLM, 인증, 영속 저장 및 대화 기록 관리는 범위에 포함하지 않는다.

## 흐름

1. 입력창에서 제출 이벤트가 발생하면 입력값의 앞뒤 공백을 제거하고 입력창을 즉시 비운다.
2. 정규화된 값이 비어 있으면 후속 처리를 중단한다.
3. 값이 유효하면 고정된 응답 목록에서 표준 무작위 선택으로 에이전트 응답을 결정한다.
4. 정규화된 입력을 사용자 역할의 메시지로 만들고, 선택된 응답을 에이전트 역할의 메시지로 만든다.
5. 두 메시지를 제출 순서대로 메모리 목록에 추가한다. 한 번의 제출에서는 사용자 메시지가 먼저이고 에이전트 응답이 바로 뒤따른다.
6. 각 메시지의 역할에서 화면 라벨과 구조적 스타일 클래스를 파생한다. 사용자 메시지는 사용자 라벨과 왼쪽 정렬·왼쪽 테두리를 사용하고, 에이전트 응답은 에이전트 라벨과 오른쪽 정렬·오른쪽 테두리를 사용한다.
7. 대화 영역에 두 항목을 순서대로 마운트하고 마지막 항목이 보이도록 스크롤한다.
8. 종료 키 입력은 기존 종료 동작을 요청하며, 메시지 제출 흐름과 독립적으로 처리한다.

### `message-submission-and-rendering`

입력창의 제출 이벤트는 실행 흐름의 시작점이다. 이벤트 값을 앞뒤 공백 제거로 정규화하고 입력창을 비운 다음, 정규화된 결과가 비어 있는지 판정한다. 빈 결과는 정상적으로 무시하며 응답 선택이나 상태 변경을 수행하지 않는다.

유효한 입력이면 고정된 응답 목록을 표준 무작위 선택 함수에 전달하여 에이전트 응답을 하나 결정한다. 이후 정규화된 입력과 선택된 응답을 각각 사용자 역할과 에이전트 역할의 불변 메시지로 만든다. 제출 입력과 선택 응답의 기존 세션 기록도 함께 갱신하되, 응답 선택은 유효한 입력마다 한 번만 수행한다.

생성된 메시지는 사용자 메시지, 에이전트 응답 순서로 메시지 목록에 연속 추가한다. 여러 번 제출한 경우에도 각 제출의 두 항목이 제출 순서에 따라 누적되며, 이전 항목의 내용과 역할은 변경하지 않는다. 메시지의 역할과 본문은 화면 표현보다 우선하는 정본 값이다.

렌더링 단계에서는 역할에서 표시 라벨과 구조적 스타일을 파생한다. 사용자 메시지는 `사용자: 본문` 형식과 사용자용 메시지 클래스를 사용하고, 에이전트 응답은 `에이전트: 본문` 형식과 응답용 메시지 클래스를 사용한다. 사용자 항목은 왼쪽 정렬과 왼쪽 테두리, 에이전트 항목은 오른쪽 정렬과 오른쪽 테두리를 적용하여 색상에만 의존하지 않고 구분한다.

각 항목은 대화 영역에 생성 순서대로 추가하고, 두 항목을 모두 추가한 뒤 대화 영역의 끝으로 스크롤한다. 따라서 유효한 제출 하나의 화면 결과는 사용자 메시지가 먼저이고 대응하는 에이전트 응답이 바로 뒤따르는 형태가 된다. 종료 키 처리는 이 흐름과 별도로 애플리케이션 종료를 요청하며, 입력·응답 상태를 새로 만들지 않는다.

검증은 정규화된 입력과 응답 기록, 역할과 본문을 포함한 메시지 목록, 화면 라벨, 역할별 구조적 스타일 및 표시 순서를 함께 비교하여 수행한다. 빈 입력과 공백 입력에서는 응답 선택과 모든 메시지·화면 변경이 발생하지 않는지 확인하고, 여러 입력에서는 기존 항목을 보존한 채 사용자와 에이전트 쌍이 올바른 순서로 누적되는지 확인한다.

## 실패와 복구

- 빈 문자열이나 공백·탭·개행만 포함한 입력은 입력창을 비운 뒤 무시한다.
- 무시된 입력에서는 응답 선택, 제출 기록 추가, 메시지 생성 및 화면 항목 추가가 발생하지 않는다.
- 응답 선택이나 메시지 기록 전에 입력 유효성을 확인하므로 부분적인 사용자 메시지 또는 에이전트 응답이 남지 않는다.
- 단일 이벤트 루프에서 제출 이벤트 순서를 처리하며, 처리된 제출의 표시 순서를 자동으로 재배열하지 않는다.
- 렌더링 실패가 영속 데이터나 외부 시스템 상태를 변경하지 않도록 별도 저장·보상 절차를 두지 않는다.
- 역할 값은 명시적인 역할 모델에서 관리하며 화면 위치나 스타일 클래스만으로 작성자를 추론하지 않는다.

## 관찰 가능성

실행 중 확인할 수 있는 상태는 정규화된 제출 입력 목록, 선택된 응답 목록, 역할과 본문을 함께 가진 메시지 목록 및 대화 영역의 표시 항목이다. 각 유효한 제출에 대해 입력과 응답이 같은 순서로 기록되며, 메시지 목록에는 역할이 명시된다. 화면 텍스트에는 사용자 또는 에이전트 라벨이 포함되고, 구조적 스타일은 역할별 정렬과 테두리로 확인할 수 있다. 민감정보, 외부 호출 식별자 및 영속 저장 상태는 생성하지 않는다.

## 검증

- 정상 입력 하나와 여러 개를 제출하여 입력 정규화, 응답 선택, 역할 부여, 라벨 표시 및 전체 순서를 확인한다.
- 응답 선택을 고정하여 동일한 입력 흐름을 결정적으로 검증하고, 표준 응답 선택 호출이 기존 목록을 대상으로 한 번 수행되는지 확인한다.
- 빈 입력과 공백 입력을 제출하여 선택 함수가 호출되지 않고 메시지 목록과 화면 항목이 변경되지 않는지 확인한다.
- 사용자와 에이전트 항목의 라벨, 역할 클래스, 좌우 정렬 및 양쪽 테두리 규칙을 확인한다.
- 종료 키 입력이 애플리케이션 종료 요청으로 연결되는지 회귀 검증한다.
- 입력창이 모든 제출 뒤 비워지고, 유효한 제출의 사용자 메시지 뒤에 해당 에이전트 응답이 즉시 표시되는지 확인한다.