GBR: ADR-0005 Controle de Sessão e UX de Terminal via Máquina de Estados Finita (FSM)

• *Status:* Aceito
• *Data:* 2026-05-01

*Contexto:*

A aplicação de interface de linha de comandos (gleambrctl), concebida para atuar como o "Oráculo de Bolso" da comunidade Gleam, necessitava de controles de sessão rigorosos (/reset, /exit, /persona) e suporte para a inserção massiva de código ("multi-line paste") a partir de editores externos. Modelos imperativos tradicionais (ex: scripts Python que lidam com buffers de stdin manipulando variáveis globais) tendem a apresentar condições de corrida ou corrupção de estado interno quando submetidos a entradas caóticas ou comandos não lineares.

*Decisão:*

1. **Interceptor Estrito na FSM (AgentLoop):** Comandos de sistema que alteram o "estado da mente" da IA foram mapeados exclusivamente como transições explícitas na Máquina de Estados. A deteção do caractere de escape / é analisada matematicamente no passo UserQuery, interceptando o ciclo antes de qualquer delegação ao provedor externo (LLM) ou ao banco de dados vetorial (gbr_graph).
2. *Troca de Máscara (Dynamic Prompting):* O comando /persona altera a variável predefinida system_prompt dentro do AgentContext. A reinjeção deste contexto modificado nas chamadas subsequentes do provedor LLM garante que a IA obedeça à nova diretiva comportamental sem destruir a fita de eventos históricos processados pelo SessionActor.
3. *Buffer "Drafting" para Colagem Extensa:* Instituição do estado não-operacional Drafting(buffer: String). Quando ativado via comando /multiline, o Agente interrompe interações cognitivas (busca semântica / chamadas HTTP) e assume uma postura estritamente acumulativa para as diretivas do stdin. O fechamento explícito do buffer (/end) força o reingresso seguro do bloco concatenado no motor LSH/LLM.

*Consequências:*

• *Positivas:* Previsibilidade UX absoluta: é matematicamente garantido que comandos de gestão não vazarão para prompts do LLM consumindo tokens (faturação); prevenção de quebras de formatação no terminal causadas pelas chaves de linha (\n) simuladas como evento ENTER na maioria dos sistemas de janelas (Unix/Win).
• *Negativas/Riscos:* A necessidade do usuário informar manualmente os comandos demarcadores (/multiline e /end) introduz atrito tático no UX face a ferramentas IDE nativas (onde a colagem é gerida via clipboard bindings automáticos no GUI).