v0.23.1: um teto de 2 MiB congelou em silêncio o seu catálogo de plugins no passado


Um colega joga o nome de um plugin no canal do time e diz “instala esse, é ótimo”. Você digita o comando de instalação e o Hermes responde que não encontra esse plugin. Você acha que errou o nome, tenta outra grafia, recebe a mesma resposta. Você abre a página do catálogo: está lá, com versão, repositório e descrição.

Não é a sua rede nem a sua grafia. Desde 9 de novembro, o arquivo do catálogo oficial publicado é maior do que o cliente aceita — e, quando o cliente decide que um arquivo é grande demais, ele não reclama. Ele volta, sem dizer nada, para a cópia que vem dentro da sua versão. O que você consegue buscar é um retrato do dia em que aquela release foi fechada. A v0.23.1 sobe o teto para que o catálogo ao vivo volte a ser usado.

Três coisas valem entender: como o teto morde, por que o “silencioso” é a parte cara aqui e como verificar a sua própria instalação. Mais o resto da janela.

A versão curta: atualize

hermes update

Depois disso, o cliente aceita até 16 MiB em vez de 2 MiB. O catálogo ao vivo carrega, então hermes plugins install enxerga plugins recém-listados, resolve os pins atuais em vez dos que vieram na sua release e respeita entradas removed mais novas.

Uma ressalva que importa: a correção está no cliente. Instalações que ficarem na v0.23.0 ou anterior continuam caindo até atualizarem. Então, quando alguém jurar que um plugin não existe, peça hermes version antes de depurar qualquer outra coisa.

Como um teto morde

O catálogo de plugins é um documento JSON público, buscado quando você navega ou instala e depois cacheado localmente por seis horas. Duas fontes, em ordem estrita de prioridade:

  1. O catálogo ao vivo (plugin-catalog.json), publicado pelo site de documentação — entradas mais novas, pins de versão mais novos, remoções mais novas;
  2. O catálogo embutido na árvore, que vem com a sua instalação — nunca atualizado, usado só quando o catálogo ao vivo não pode ser buscado.

O caminho de download tem uma checagem de tamanho. Acima do teto, a resposta é tratada como quebrada: lança erro, registra em nível debug, devolve “sem catálogo ao vivo”. Todo chamador na pilha vê “nada”, cai para a cópia embutida e não diz nada para você.

Em 9 de novembro o documento publicado media 2.109.306 bytes em 1.268 entradas — cerca de 1,7 KB cada — e cruzou a linha dos 2 MiB. A partir daí:

  • plugins recém-listados não existiam na sua máquina;
  • plugins que foram re-fixados em um commit mais novo instalavam no pin que a sua release trouxe;
  • entradas mais novas de “removido / sem manutenção” ficavam invisíveis.

A terceira é a que merece uma pausa. Um plugin formalmente retirado deixa de parecer retirado na sua instalação — ele continua parecendo instalável.

Medindo o documento ao vivo agora: 1.380 entradas, 2.310.445 bytes. Já está 10% acima do teto antigo. Sem a subida, isso só ficaria mais comum, não menos.

Por que o “silencioso” foi a parte cara

Visto com frieza, o bug é uma constante definida pequena demais. O difícil é o modo de falha: todo erro era engolido.

Esse desenho está correto nos próprios termos. Um catálogo ausente nunca deveria bloquear uma instalação — se a rede caiu ou o site de documentação está tendo um dia ruim, você ainda deveria conseguir instalar a partir da cópia que já tem. Cair para o fallback em qualquer falha é a política certa.

O problema é que “o documento é grande demais” e “não tenho rede” foram para o mesmo balde. O primeiro significa que o seu catálogo está velho e deveria te importar; o segundo significa espere um minuto e tente de novo. Para o usuário os dois pareciam idênticos, e as ações necessárias eram opostas. O bug sobreviveu nessa ambiguidade até alguém notar plugins faltando e seguir o rastro até a constante.

É o formato da maioria dos bugs de infraestrutura, na verdade: nada quebra, nada acorda ninguém, nenhuma linha de log fica vermelha — o mundo só vai ficando velho em silêncio. Você faz tudo certo e recebe a resposta errada.

O que mudou

A correção é a mudança de uma constante, mas o comentário que veio junto vale a leitura, porque ele declara o limite:

  • o teto vai de 2 * 1024 * 1024 para 16 * 1024 * 1024;
  • nos tamanhos atuais por entrada, em 16 MiB cabem cerca de 9.000 entradas;
  • o teto não sumiu. Ele continua limitando uma resposta hostil ou corrompida — só parou de punir o crescimento normal.

O mesmo arquivo carrega as regras de fallback em volta, e conhecê-las diz em qual catálogo você está:

Regra Valor O que significa
Cache normal 6 horas chamadas repetidas dentro da janela pulam o download
Cache antigo utilizável por 24 horas caches mais velhos descartam entradas e mantêm só a lista de remoções
Memória de falha 60 segundos depois de uma falha, não há nova tentativa por 60 s
Timeout da requisição 5 segundos timeout de rede por tentativa

Verificando a sua própria instalação

O teste honesto é comportamental: tente instalar um plugin listado há pouco e veja se ele resolve. A página de referência do hermes plugins lista o conjunto completo de subcomandos.

Dois hábitos valem manter:

  • quando um plugin “não existe”, rode hermes version primeiro — depois pense no catálogo;
  • quando um plugin se comporta como uma versão que você não instalou, confira o pin resolvido antes de culpar o plugin.

Se você leu o nosso texto anterior sobre como o catálogo de plugins funciona, isto é consequência direta daquele desenho: o catálogo é dado, não código, e o crescimento dos dados acaba pressionando as premissas do cliente. O mesmo raciocínio aparece na superfície pública da API de plugins: interfaces estáveis são o que deixa os dados crescerem, e os clientes precisam abrir espaço para esse crescimento.

O que mais tem na janela

A v0.23.1 é uma tag de patch: 618 PRs mesclados desde a v0.23.0, reunidos em uma release estável para o release do GitHub (CLI e instaladores), o app da Microsoft Store, o Docker e o Hermes Cloud. Medido no commit 3b421578588, a janela tem 2.578 commits não-merge em 2.781 arquivos alterados (+151.690 / −62.595) e 409 issues fechadas.

As notas da release dizem com clareza que um conjunto de recursos desta janela está sem documentação de propósito, com as notas curadas completas chegando junto com a v0.24.0. Na lista aparecem:

  • Esc backtrack na TUI e na CLI clássica, no lugar do seletor da lista de rewind;
  • chats em grupo que rodam em um gateway sem Desktop e que podem receber bots de outros computadores;
  • conexões de gateway salvas compartilhadas entre o Desktop e a Webapp;
  • o navegador integrado entrando com o seu perfil real de navegador e preenchendo logins salvos pela barra de endereços;
  • hermes gateway attach para clientes locais;
  • hermes clipboard image --json;
  • nova superfície de API de plugins: valores de ambiente por sessão, métodos e eventos JSON-RPC de plugins, tarefas auxiliares llm.oneshot, um conversation_id estável à compressão, um hook on_session_open no gateway e um hook post_curator_run;
  • leituras de transcript e de handoff mais rápidas, além de um lote grande de novas entradas no catálogo.

Já cobrimos a maior parte disso em textos separados: o fluxo de Esc backtrack em rebobinar uma conversa sem perdê-la, a manutenção do catálogo em como as entradas do catálogo são varridas em lote, e o panorama geral na página da v0.23.0.

Atualização

# CLI
hermes update

# ou rode de novo o instalador de uma linha
# Docker / Hermes Cloud: nousresearch/hermes-agent:stable

O app da Microsoft Store atualiza pela Store. Um app Desktop instalado pelo instalador .exe / .dmg não muda nesta release; ele pega a correção no próximo pacote.

Vale fazer uma coisa depois de atualizar: instalar o plugin que “não existia” e confirmar que ele resolve. Se ainda não resolver, confira hermes plugins list e a versão do seu cliente — nesse ponto o problema é a entrada do plugin ou o repositório, não o cache do catálogo.

Notas completas: a página da v0.23.1.