Atualização do cron do Hermes Agent: monitor-mode, notepad e validação preflight

Tarefas agendadas são um dos recursos de automação mais práticos do Hermes Agent: pegar a primeira página do Hacker News às 9h, checar o build a cada 30 minutos, resumir o seu feed a cada hora. Mas quanto mais jobs você roda, mais óbvios ficam os problemas — a maioria dos ticks gasta tokens com pura repetição, um job mal configurado desperdiça uma chamada inteira de LLM antes de falhar, e passar estado entre execuções (“onde eu parei da última vez?”) significa improvisar com arquivos externos.

O lote que chegou à main no início de agosto de 2026 dá ao cron três equipamentos críticos:

  1. monitor-mode — um script barato ou uma URL roda primeiro em cada tick; se o hash da saída não mudou, toda a execução do agente é suprimida a custo zero de LLM;
  2. notepad — um bloco de rascunho chave/valor durável por job, que sobrevive entre execuções agendadas (cursores, watermarks, listas de monitoramento);
  3. preflight — valida a configuração do job antes de qualquer maquinário do agente ser construído; um job quebrado é marcado como blocked_config, avisa uma vez e nunca gasta um token.

Além disso, um logger usage_audit.jsonl que registra honestamente o gasto de tokens de cada execução do cron. Este post cobre os quatro, com exemplos reais de CLI e chaves de configuração.

1. monitor-mode: cheire primeiro, rode apenas quando algo mudou

Por que ele existe

O job de monitoramento canônico se parece com: “a cada 5 minutos, verifique se o feed tem itens novos e os resuma se tiver.” Sem o monitor-mode, o Hermes constrói o agente completo e chama o LLM em todo tick — ou seja, você paga por um resultado “não aconteceu nada” toda vez que o feed está quieto.

O monitor-mode tira a detecção de mudanças do agente: a cada tick, um script barato (ou uma requisição GET limitada) busca a saída da fonte do monitor, que é transformada em hash como bytes exatos:

  • Hash inalterado → toda a execução do agente é suprimida e registrada como um tick silencioso de no_change (sem gasto de LLM, sem entrega);
  • Hash alterado → um bloco MONITOR CHANGE DETECTED (um diff unificado limitado + a nova saída) é injetado no prompt e o agente roda normalmente;
  • O primeiro tick sempre roda (estabelece a linha de base);
  • Uma fonte de monitor com falha é tratada como erro de configuração — o job nunca pula silenciosamente.

Uso

Criação pela CLI:

# Monitor source = a script (resolved relative to ~/.hermes/scripts/, or absolute path)
hermes cron create "every 5m" \
  "Summarize any new items on the page" \
  --monitor-script feed_watch.sh

# Monitor source = a URL (one bounded GET per tick)
hermes cron create "every 5m" \
  "Summarize changes on the status page" \
  --monitor-url https://status.example.com/api/health

# Update an existing job
hermes cron edit <job_id> --monitor-script feeds.sh

No chat, por meio da ferramenta cronjob:

cronjob(
    action="create",
    schedule="every 5m",
    prompt="Summarize any new items on the page",
    monitor_script="feed_watch.sh",
)

Três restrições (aplicadas na criação, no código-fonte)

  • monitor_script e monitor_url são mutuamente exclusivos — uma fonte de monitor por job;
  • o monitor mode é incompatível com no_agent=True — o objetivo é suprimir ou acordar o agente; jobs puramente de script devem usar o modo script normal;
  • o script de monitor deve emitir saída estável (sem timestamps), senão cada hash difere e o job dispara a cada tick.

O --monitor-script segue as mesmas regras de resolução do script: caminhos relativos são resolvidos em ~/.hermes/scripts/, .sh/.bash rodam via bash e qualquer outra coisa roda como Python. A implementação vive em create_job, e o caminho de supressão por hash do agendador está em cron/jobs.py.

2. notepad: estado durável entre execuções, sem arquivos externos

Por que ele existe

Jobs com estado têm um ponto de dor clássico: o job A ingere dados às 2h, o job B processa “só o que é novo” às 8h — onde mora o cursor de “último visto”? Historicamente você escrevia num arquivo local e lidava sozinho com concorrência e limpeza. O notepad torna isso um cidadão de primeira classe: um bloco de rascunho chave/valor durável por job, armazenado no próprio banco SQLite (~/.hermes/cron/notepad.db). A cada execução, o agendador renderiza um notepad não vazio no prompt do job — o agente vê o estado deixado pelas execuções anteriores e o atualiza via CLI durante a execução.

Uso

# List the job's notepad (default action)
hermes cron notepad <job_id>

# Read one key
hermes cron notepad <job_id> get cursor

# Write one key
hermes cron notepad <job_id> set cursor 128

# Delete one key
hermes cron notepad <job_id> delete cursor

É uma combinação natural com o monitor-mode: após uma mudança detectada, o job grava “processado até o item N” no seu notepad, então o próximo tick sabe exatamente onde continuar. Limites de capacidade — uma escrita grande demais falha ruidosamente em vez de truncar silenciosamente:

  • 16 KB por valor;
  • chaves de até 128 caracteres;
  • 64 KB no total por job.

O caminho de leitura injeta o conteúdo do notepad no prompt do job na mesma emenda que a saída do context_from; o caminho de escrita é o agente em execução chamando hermes cron notepad ... set. Os detalhes de implementação estão em cron/notepad.py, que segue o mesmo padrão de conexão/pragma de cron/executions.py.

3. preflight: um job quebrado avisa uma vez e nunca gasta um token

Por que ele existe

O jeito mais comum de jobs do cron quebrarem não é código ruim — é o ambiente à deriva: a API key de um provider expirou, uma skill anexada está sem uma env var, credenciais de entrega ficaram obsoletas. O comportamento antigo: o tick roda, o agente é construído, o LLM é chamado e só então a falha acontece — dinheiro gasto, e o erro muitas vezes é opaco.

O preflight valida a configuração do job antes de qualquer maquinário do agente ser construído (segundo o código-fonte e a documentação oficial cron.md):

  • a API key do provider é resolvível (pulada quando uma cadeia de fallback_providers está configurada, já que o caminho de fallback pode resgatar uma chave primária ausente);
  • as skills anexadas estão prontas (sem variáveis de ambiente, comandos ou arquivos de credenciais obrigatórios faltando);
  • os alvos da plataforma de entrega são conhecidos e têm credenciais de gateway (alvos local/origin nunca são verificados).

Em caso de falha:

  • o last_status do job vira blocked_config;
  • exatamente um alerta é entregue (um marcador de deduplicação preflight_alerted — sem bombardeio por tick), limpo na recuperação para que uma futura quebra alerte novamente;
  • zero chamadas de LLM — um job mal configurado nunca gasta tokens.

Ligado por padrão via cron.preflight: true. Para restaurar o comportamento antigo:

# config.yaml
cron:
  preflight: false

# or on the command line
hermes config set cron.preflight false

Todas as verificações falham de forma aberta (fail open) — um problema de preflight nunca bloqueia uma execução, então um job saudável não é morto acidentalmente.

4. usage_audit: um livro-caixa de tokens para o cron

O mesmo lote também entregou parte da mitigação de vazamento de tokens do cron: sessões de cron não criam mais uma revisão em segundo plano (skip_background_review), e um log de auditoria do gasto de tokens por disparo agora vive em ~/.hermes/cron/usage_audit.jsonl — uma linha JSONL por execução. Se você quer quantificar quanto o monitor-mode realmente economizou, este arquivo é a resposta.

5. Juntando tudo: um job barato de monitoramento ciente de mudanças

Encaixando as três peças em um job típico de “monitor de mudanças do site + resumo incremental”:

# 1) Monitor script: stable output (e.g. the feed's item titles)
cat > ~/.hermes/scripts/feed_watch.sh <<'EOF'
#!/bin/bash
curl -s https://example.com/feed.xml | grep -o '<title>[^<]*</title>'
EOF
chmod +x ~/.hermes/scripts/feed_watch.sh

# 2) Create the monitor job: unchanged hash → silent skip
hermes cron create "every 5m" \
  "Summarize new feed items and remember the last seen count in the notepad" \
  --monitor-script feed_watch.sh \
  --deliver telegram

Daí em diante: feed inalterado → tick silencioso de no_change, zero tokens; feed alterado → o agente acorda, lê o cursor do seu notepad, resume os itens novos, atualiza o cursor e entrega no Telegram. Usuários preocupados com orçamento podem conferir o usage_audit.jsonl no fim do mês.

6. Quando NÃO usar estes recursos

  • Jobs que precisam rodar em todo tick (sinalizadores horários, keep-alives de heartbeat) não precisam de monitor-mode — ele só adiciona uma checagem de mudança sem sentido;
  • o notepad é por job, não um armazenamento entre jobs — encadeie jobs com context_from ou armazenamento externo quando dados precisarem fluir entre tarefas;
  • jobs puramente de script que devem pular o agente por completo: use o no_agent=True + script existentes, não force o monitor mode neles.

Resumo

Essas três peças transformam o cron de um “queimador de dinheiro agendado” em um “despertador sob demanda”: monitor-mode economiza (custo zero quando nada mudou), notepad lembra (o estado sobrevive entre execuções), preflight estabiliza (sem queima de tokens em configuração quebrada, um aviso só). Para quem roda uma frota de jobs agendados, isso é uma redução real na conta e uma vitória operacional.

Novo no cron? Comece com o nosso guia completo de automação de cron do Hermes Agent; evite que tarefas longas em segundo plano fiquem travadas com o guia de configuração para tarefas longas; mais dicas de produtividade diária estão na nossa coleção de dicas de produtividade do Hermes Agent. Ainda não instalou? O guia de instalação deixa você rodando em cinco minutos.