AI CLI/TUI Status and Recap Hooks

ai-ui specs/ai-ui/agent-cli-status-and-recap.kmd

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.

Quando esta spec se aplica

Triggers primários

Todos os triggers

Spec — AI CLI/TUI Status and Recap Hooks

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):

GanchoMomento de DisparoAção do Gancho
SessionStartQuando o terminal do agente é iniciado.Limpa sinalizações de travamento de estados anteriores e carrega o histórico/backlog ativo.
UserPromptSubmitQuando o usuário pressiona Enter para enviar um prompt.Define o sinalizador de atividade do agente como busy (ocupado).
StopQuando o turno do agente termina e o controle retorna ao usuário.1. Limpa o sinalizador de atividade para idle (ocioso).
2. Executa a varredura do histórico do chat para extrair a linha Próximo:.
3. Grava a próxima ação no arquivo de estado da sessão.
4. Registra a entrada mecânica de histórico em handoff/recaps/.
PreCompactAntes 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.
PostToolUseImediatamente 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:).

Referências