AI CLI/TUI Status and Recap Hooks

mandatory

Standardizes terminal-based status lines (ANSI LEDs), turn-closing indicators, and mechanical recap logging for all CLI/TUI AI agent tools across the Koder Stack.

1. Princípios

  1. Transparência de Estado: O operador deve saber imediatamente se o agente está trabalhando, esperando um processo em segundo plano ou aguardando comandos.
  2. Rastreabilidade (Handoff): Cada encerramento de turno de IA deve deixar um rastro mecânico claro do trabalho realizado e da próxima ação recomendada.
  3. Independência de Provedor: A mecânica de exibição no terminal e os ganchos do ciclo de vida são agnósticos e devem se aplicar igualmente a qualquer CLI de agente (Claude Code, Antigravity CLI, etc.).
  4. Consumo Eficiente de Espaço: O rodapé da CLI deve se adaptar de forma compacta (2 ou 3 linhas), minimizando desperdício de tela em terminais estreitos.

2. A Convenção de Encerramento de Turno (Feito: / Próximo:)

Toda resposta do assistente de IA que devolva o controle para o operador humano (fechamento de turno) deve terminar obrigatoriamente com dois blocos destacados em negrito no corpo do chat:

* Feito: — Um resumo curto das ações realizadas no turno (commits, edições, correções). * Próximo: — A sugestão clara da próxima tarefa imediata a ser feita.

**Feito:**
- Implementada a spec do KVIQ em specs/ai/kviq.kmd.
- Registrado o termo em vocabulary.md.

**Próximo:**
Refatorar o resolver de rotas do gateway para suportar estratégias KVIQ.

3. O Ciclo de Vida dos Ganchos (Hooks Interface)

O motor do CLI/TUI deve interceptar as transições de estado do agente através dos seguintes ganchos de ciclo de vida (hooks):

Gancho Momento de Disparo Ação do Gancho
SessionStart Quando o terminal do agente é iniciado. Limpa sinalizações de travamento de estados anteriores e carrega o histórico/backlog ativo.
UserPromptSubmit Quando o usuário pressiona Enter para enviar um prompt. Define o sinalizador de atividade do agente como busy (ocupado).
Stop Quando o turno do agente termina e o controle retorna ao usuário. 1. Limpa o sinalizador de atividade para idle (ocioso).br2. Executa a varredura do histórico do chat para extrair a linha Próximo:.br3. Grava a próxima ação no arquivo de estado da sessão.br4. Registra a entrada mecânica de histórico em handoff/recaps/.
PreCompact Antes do motor compactar automaticamente o contexto do chat. Salva um snapshot de backup das variáveis de estado no diretório temporário para evitar perda de memória.
PostToolUse Imediatamente após a conclusão da execução de qualquer ferramenta (ex: write_to_file). Dispara gatilhos JIT (Just-In-Time) de validação de conformidade de arquivos modificados.

4. O Layout do Rodapé TUI/CLI (Status Line)

O rodapé do terminal deve renderizar uma área persistente (atualizada via timer de intervalo, ex: 1s) contendo 2 a 3 linhas formatadas em ANSI:

Linha 1: Contexto e Identidade

Exibe a localização do repositório/slug em foco, o usuário ativo e o consumo de créditos acumulado. * Formato: <repo>/<component-slug> · <user> · <usage-summary> * Exemplo: koder/kds · rodrigo · 5h: 0.12M tkn

Linha 2: LED de Status (Semáforo de Atividade)

Exibe uma bolinha colorida sinalizando o estado atual do processo: * 🔵 Ciano (Steady - Trabalhando): O agente está processando a resposta ou executando uma ferramenta local. * 🟡 Amarelo (Blinking - Aguardando): O agente concluiu sua vez de fala, mas há tarefas em segundo plano (builds, testes, compilações) ainda ativas no terminal do harness. A linha 3 exibe o comando ou label da tarefa. * 🟢 Verde (Steady - Sua Vez): O agente está ocioso e sem nenhuma tarefa pendente em segundo plano, aguardando entrada humana.

Linha 3: Mini-descrição Dinâmica

Exibida apenas quando há contexto relevante para relatar, usando o prefixo ↳ em cinza (se vazia, o rodapé recolhe para 2 linhas): * No estado Verde: Exibe o texto extraído da linha Próximo: para guiar o operador. * No estado Amarelo: Exibe o label do koder-job ou o comando que está executando no background. * No estado Ciano: Exibe a última ação realizada extraída dinamicamente do tail de logs (ex: $ go test ou editando layout.templ).

5. Histórico de Handoff (Recaps Log)

O gancho Stop deve alimentar um arquivo centralizado de auditoria em meta/context/handoff/recaps/YYYY-MM.md. Cada fechamento de turno anexa uma entrada formatada contendo:

  1. Timestamp (RFC3339).
  2. Session ID (identificador único da sessão).
  3. Git Branch e último commit durável na árvore.
  4. Worktree (lista curta de arquivos modificados).
  5. Next Action (o valor extraído do rótulo Próximo:).