Importando um interno do Hermes? Agora existe uma lista publicada do que um plugin pode importar

Seu plugin está em uso há três meses sem uma reclamação. Aí uma release nova do Hermes sai, um usuário atualiza e o plugin falha ao carregar com um ImportError. Você passa pelo changelog: nada menciona o seu plugin. Você passa pelo seu código, e o culpado é uma linha que você escreveu meio ano atrás — from hermes_cli.cli_config_load import _parse_service_tier_config — apontando para uma função interna que desde então mudou de lugar.
O que torna esse tipo de acidente tão desagradável é que nada dá errado no momento em que você escreve. O plugin instala, roda e passa nos testes. É uma cobrança adiada, e a mudança abaixo é sobre expô-la cedo.
Por que um import privado é sempre uma quebra futura
O Hermes já tem uma checagem em runtime, a regra de core override: um plugin não pode reatribuir uma função dentro de um módulo core em runtime. Mas essa checagem governa substituir, não referenciar. Importar um interno passa por ela — e aí você está preso à implementação privada de alguém, que não carrega promessa de compatibilidade: pode ser renomeada, movida ou removida em um refactor do qual você nunca vai ouvir falar.
Para quem escreve o plugin, o custo chega tarde; para um revisor, é quase invisível em algumas centenas de linhas. O problema na verdade pede uma fronteira estática, mecanicamente decidível: a coisa que você importou está na lista publicada?
A lista saiu do código
Ela costumava ser um frozenset fixo em hermes_cli/plugin_validate_private_imports.py. Funcionava, mas era invisível para quem escreve plugin — você descobria o que estava nela quando o CI apontava para a sua linha.
A mudança de 5 de novembro moveu a lista, sem alterações, para hermes_cli/data/plugin_api.json (já distribuído como package data), e o validador lê de lá. Um script gerador renderiza a página de docs developer-guide/plugins/public-api.md a partir do mesmo arquivo e — a parte importante — um teste falha quando a página fica desatualizada. A lista não pode derivar em silêncio: mudá-la obriga a docs a mudar junto.
Um dia depois a lista ganhou sua primeira entrada que é exatamente “o que um plugin deveria chamar”: agent.redact.redact_sensitive_text, coberta abaixo.
Três veredictos
A regra é curta:
- Uma linha de módulo inteiro (digamos
agent.memory_provider) permite aquele módulo e todo nome nele que não comece com underscore. - Uma linha de nome único (digamos
hermes_cli.auth_model_picker:prompt_model_selection) permite só aquele nome. - Um módulo do Hermes fora da lista: um aviso, nunca um bloqueio.
Não bloquear é deliberado. Isto é a dica do portão de admissão (regra 9 do catálogo, apenas superfícies públicas), não um compilador: o plugin continua instalando e continua rodando, e tanto quem escreveu quanto quem revisa conseguem ver “isso provavelmente vai quebrar um dia”.
Quatro categorias nunca são sinalizadas: a biblioteca padrão, pacotes de terceiros, os módulos do próprio plugin e imports sob if TYPE_CHECKING:. Esse último é genuinamente útil — quando uma anotação de tipo precisa de um tipo interno, embrulhar o import em TYPE_CHECKING é o movimento limpo. Imports por string via importlib.import_module("hermes_cli.…") também são resolvidos, então uma grafia diferente não é uma escapatória.
Como o aviso aparece
Os achados são impressos como relative/path.py:line module[.name]:
myplugin/tools.py:41 hermes_cli.cli_config_load._parse_service_tier_config
Um detalhe vale saber: o relatório lista o primeiro site de cada módulo distinto antes dos sites restantes. Quando a lista é truncada, você ainda vê a amplitude — quantos módulos internos você toca — em vez de dez linhas do mesmo. No CI, --json te dá um relatório legível por máquina; --install-deps instala as dependências declaradas antes da sonda de capacidade, que é como o portão do catálogo o executa.
A nova entrada: redact_sensitive_text
Esta merece seção própria, porque responde a uma pergunta que quem escreve plugin faz o tempo todo: quero mandar texto do usuário para um modelo. Como mascaro os segredos antes?
A resposta antiga era from agent.redact import redact_sensitive_text — funcionava, mas o validador te avisava, porque era privado. Agora é API pública:
from agent.redact import redact_sensitive_text
text = redact_sensitive_text(user_text, force=True)
Por que uma função em vez de um parâmetro redact= no ctx.llm? Porque um plugin pode lidar com o mesmo texto várias vezes — fatiar, concatenar, colar em um prompt — e redigir só na chamada final não basta. Com a função na mão, você limpa onde precisar limpar.
A semântica de force=True é a parte a lembrar: é o interruptor que não te deixa saída. Por padrão a redação segue a configuração security.redact_secrets do operador, então com ela desligada a função devolve o texto sem alteração. Texto destinado a um modelo é uma fronteira de segurança, e ali a configuração não deveria decidir — daí o force=True. A formulação oficial é que você o usa onde segredos nunca podem sair da máquina.
Mais dois parâmetros importam. code_file=True pula as passagens de atribuição de ENV/JSON para código-fonte conhecido, então um fixture como MAX_TOKENS=*** sobrevive. file_read=True é para conteúdo de arquivo devolvido ao agent: credenciais com prefixo conhecido, como ghp_…, viram um sentinela não reutilizável em vez de uma máscara de início/fim, porque uma máscara de início/fim parece uma chave real porém truncada — e um agent pode muito bem gravar isso de volta no config.yaml.
Conferindo o seu próprio plugin
hermes plugins validate ./my-plugin
hermes plugins validate ./my-plugin --json
Procure imports que comecem com os pacotes core — hermes_cli., agent., gateway., tools.. Se achar um, há três saídas: trocar por uma entrada pública na lista; se ela existe só para uma anotação de tipo, colocá-la sob TYPE_CHECKING; ou aceitar que você precisa de um interno e planejar seguir o core — pelo menos agora você sabe onde está pisando.
Para o quadro mais amplo de como plugins são admitidos, instalados e organizados, o guia do catálogo de plugins cobre isso. Se o seu interesse é como segredos são tratados no caminho, as três lanes de redação olham para a mesma maquinaria pelo outro extremo.
Dá para usar hoje
A mudança da lista e a nova entrada estão no main (5 e 6 de novembro) e não estão na tag v0.23.0. Em um build estável, hermes plugins validate ainda lê a lista fixa no código, e redact_sensitive_text ainda é um import privado.
Atualização (10/11/2026): essas mudanças saíram na v0.23.1 (9 de novembro): basta um
hermes update. O « não está na v0.23.0 » acima continua correto; a v0.23.1 fecha a lacuna.
O valor disso, porém, não depende da versão: escreva contra a página publicada agora. O que está na lista é estável; o que está fora dela é emprestado. Essa regra não muda com uma release.
A lição
Nenhum recurso foi adicionado aqui. Visibilidade foi. Uma regra que sempre existiu, e que só os revisores carregavam na cabeça, agora é um arquivo que você pode ler, uma página que você pode buscar e uma checagem que o seu CI pode rodar — com um teste que mantém a página honesta. Não vai deixar um plugin mais rápido, mas é o tipo de alicerce que o mantém instalável dez releases daqui.