/goal: objetivos persistentes no Hermes

Há tarefas que um agente não acaba num turno. Corrigir todos os erros de lint de uma pasta, portar uma funcionalidade com testes incluídos, investigar um bug que só aparece de vez em quando. O padrão habitual é conhecido: o agente faz uma parte, pára, diz o que falta, e tu escreves “continua”. Três vezes. Às vezes dez.

O /goal do Hermes existe para acabar com esse ritual. Defines um objetivo, e depois de cada turno um modelo auxiliar (o juiz) lê a última resposta e decide se o objetivo está cumprido. Se não estiver, o Hermes injeta sozinho uma mensagem de continuação na mesma sessão e segue para o passo seguinte. Pára quando o juiz diz que está feito, quando pausas, ou quando se esgota o orçamento de turnos.

A ideia não é original, e a documentação diz isso com todas as letras: é a versão do Hermes do chamado Ralph loop, inspirada no /goal do Codex CLI 0.128.0. A implementação é independente.

Como se usa

/goal Fix every failing test in tests/hermes_cli/ and make sure scripts/run_tests.sh passes for that directory

O primeiro turno arranca logo, não precisas de mandar outra mensagem. Vês ⊙ Goal set (20-turn budget), o agente trabalha, e a cada volta aparece ↻ Continuing toward goal (1/20): <razão do juiz>. No fim, ou ✓ Goal achieved, ou ⏸ Goal paused quando o orçamento acaba.

Os comandos que interessam no dia a dia:

Comando	O que faz
/goal <texto>	Define (ou substitui) o objetivo e arranca
/goal ou /goal status	Mostra o objetivo, o estado e os turnos gastos
/goal pause / /goal resume	Pára o ciclo sem perder o objetivo / retoma (o contador volta a zero)
/goal clear	Deita o objetivo fora
/subgoal <texto>	Acrescenta um critério a meio, sem reiniciar o ciclo

Funciona no CLI clássico, na TUI, no Desktop, no chat do dashboard e no gateway (Telegram, Discord e companhia), todos com o mesmo handler. O ACP, para já, fica de fora.

O juiz é o ponto fraco, por isso reforça-o

Um objetivo vago dá um juiz vago. O juiz só consegue verificar aquilo que lhe disseste que querias. Para isso há dois mecanismos, e na prática são eles que fazem a diferença.

O primeiro são os contratos de conclusão. Em vez de uma frase solta, escreves o objetivo com campos:

/goal Migrate auth to JWT
verify: pytest tests/auth passes
constraints: keep the /login response shape unchanged
boundaries: only touch services/auth and its tests
stop when: a DB schema migration is required

Com contrato, o juiz só marca done quando o critério de verify está cumprido com prova concreta (saída de um comando, excerto de ficheiro, resultado de testes), em vez de um “parece-me feito”. Se não te apetecer escrever os campos, /goal draft <texto> pede ao modelo auxiliar que redija o contrato por ti, e /goal show mostra-o para reveres.

O segundo são os quality gates, e são o que eu usaria sempre que houver um comando que responda à pergunta:

/goal Fix the flaky session tests
/goal gate add scripts/run_tests.sh tests/hermes_cli/test_goals.py

Um gate é um comando de shell que tem de sair com 0 antes de o objetivo poder ser dado como concluído. Corre antes do juiz: se falhar, o juiz nem é chamado, e o código de saída e o fim do output (cerca de 3 KB) passam a ser o prompt de continuação. O agente itera contra a falha real. Cada gate tem, por omissão, 3 tentativas e 5 minutos de timeout; esgotadas as tentativas, o objetivo pausa.

Pormenores que convém saber

• O orçamento por omissão é de 20 turnos de continuação, configurável em goals.max_turns no config.yaml. É a rede de segurança verdadeira: se o juiz falhar (erro de rede, resposta malformada), o Hermes trata isso como continue, e quem trava o ciclo é o orçamento.
• O juiz é conservador de propósito. Se o agente explicar que a tarefa é impossível ou precisa de ti, o veredicto é blocked e o objetivo pausa, em vez de ser dado como cumprido.
• Esperas longas não gastam turnos. Se o agente lançar um processo em background (um build, CI de um PR), o juiz pode devolver wait e o ciclo fica parado até o processo terminar, com um limite de 30 minutos. Há /goal wait <pid> e /goal unwait para forçar à mão.
• As tuas mensagens têm sempre prioridade sobre a continuação automática. Escreves a meio, és atendido primeiro, e o juiz volta a avaliar depois.
• No gateway, definir um objetivo novo enquanto o agente está a correr é recusado: primeiro /stop. Os comandos de controlo (status, pause, clear) funcionam a qualquer momento.
• O estado fica guardado na base de dados da sessão, por isso sobrevive a um /resume no dia seguinte.
• O juiz usa a tarefa auxiliar goal_judge, que por omissão é o teu modelo principal. Como a chamada é pequena (~200 tokens de saída por turno), faz sentido apontá-la para um modelo barato em auxiliary.goal_judge.

/goal não é Kanban

É fácil confundir os dois, porque ambos mantêm o Hermes a trabalhar sem ti. A fronteira é nítida: o /goal vive numa única sessão e nunca cria cartões nem distribui trabalho por outros perfis. O Kanban é um quadro de tarefas, cada uma com o seu worker. A única sobreposição é um cartão criado com --goal, que usa o mesmo motor de continuação dentro da sessão desse cartão.

Vale a pena?

Para perguntas de um turno, não. Para trabalho em que já sabes que ias escrever “continua” várias vezes, sim, com uma condição: dá-lhe uma forma de provar que acabou. Um /goal sem gate nem verify depende da opinião de um modelo sobre a resposta de outro modelo, e isso é pouco. Com um pytest ou um cargo test como gate, passa a ser algo que se pode deixar a correr enquanto vais buscar um café.