Ficar sem cota é chato. Não saber quanto resta é pior. Você está no meio de um prazo, a última resposta foi bem, e a próxima é recusada: limite atingido. Qual limite? O de hoje ou o do mês? A allowance de modelos grandes é um balde separado? Quando ela volta? Essas respostas ficavam num painel web. O PR #142308, mesclado em 22 de outubro de 2026, as leva para o terminal.

Duas formas diferentes de pagar

O Hermes cresceu com um saldo de credit: recarrega, gasta, para no zero. Algumas assinaturas funcionam com usage windows — um dia, uma semana, um mês, mais uma allowance separada para modelos grandes. Isso não é um saldo que se esvazia; é uma cota que se recompõe.

A diferença decide a interface. Um saldo é um número; uma cota é um conjunto de gauges. Por isso essa mudança não modela planos dentro do Hermes. Ela desenha o que o servidor envia.

Tantas barras quantas o servidor enviar

As allowances chegam de dois lugares, com o mesmo formato:

• usage_window.gauges no snapshot da conta do Portal;
• o cabeçalho de resposta x-nous-credits-window-gauges, que também viaja na recusa 402.

Cada gauge carrega um scope que diz o que um gauge cheio bloqueia:

• scope: all — bloqueia todos os modelos pagos (dia, semana, mês, e qualquer allowance adicionada depois pode usar esse scope);
• scope: top_tier — bloqueia apenas os modelos que o gateway marca como top tier.

Um modelo gratuito nunca é bloqueado: ele não consome nada. Essa regra fica no topo de agent/plan_limits.py, porque o aviso de “esgotado” do seletor, a sugestão do cartão de limite e o botão de troca em um toque precisam concordar — uma regra, uma fonte.

Um comentário em agent/usage_gauges.py vale ser citado: o Hermes mantém palavras próprias apenas para os ids que conhece (elas são traduzidas e ajustadas a cada superfície); qualquer outro id exibe o label do servidor. Uma nova allowance no servidor não exige release do Hermes.

Como o /usage está agora

/usage já era o comando de “quanto esta session custou” — tokens, custo estimado, janela de contexto, duração e uma seção de limites da conta quando o provider expõe uma. Num plano por janelas ele agora mostra uma barra por allowance, com percentual usado e tempo até o reset.

No app Desktop os mesmos dados aparecem em Settings → Billing como gauges, ao lado de um interruptor Keep going on credits: quando uma allowance acaba, os credits de recarga podem assumir? Esse interruptor é a mesma configuração de conta do toggle Billing → Topup do Portal — o Desktop é só outra entrada para ela. Alterá-lo exige Remote Spending (billing:manage) naquele terminal; sem isso, o clique inicia a própria aprovação, o interruptor fica na posição solicitada e a mudança vale quando for aprovada. Sem loop de recusar, verificar, clicar de novo.

Os seletores de modelo voltam a ter etiquetas de preço

Num plano por janelas, todo modelo listado está incluído, então um preço por token seria ruído. Em vez disso, cada linha leva uma palavra: Free, Small, Medium, Large. O gateway envia a palavra por chamador como usage_level em /v1/models; o Hermes apenas traduz.

Em volta disso:

• Os modelos recomendados vêm primeiro; o seletor do CLI divide a lista em “Recommended” e “Other models”, enquanto os seletores das plataformas de mensagem apenas põem os recomendados na frente;
• Quando uma allowance acaba, o seletor avisa uma vez e mostra quando ela reseta; os modelos bloqueados ficam esmaecidos onde a plataforma permite;
• Escolher um modelo Large dá um aviso único de que ele usa mais da allowance mensal de modelos grandes.

Qualquer outra conta — credit-grant, pagamento por uso, plano gratuito — não ganha nada deste módulo. Os caminhos de código delas seguem iguais.

No limite, três respostas em vez de uma

A recusa costumava ser um genérico “limite de uso atingido”. Agora ela diz qual allowance acabou, quando reseta e o que ainda funciona: até dois modelos da lista de recomendados do plano que ainda conseguem rodar. Plataformas que já têm botões os renderizam como botões; o resto recebe uma frase.

Uma decisão de design vale ser copiada em qualquer produto de agente: o Hermes nunca troca de modelo sozinho. Um limite de usage window não percorre a cadeia de fallback — a cadeia de fallback existe para “este provider caiu”, não para “você estourou seu plano”. Ou você escolhe um modelo disponível, ou espera o reset.

Dois detalhes por canal: as plataformas de mensagem apontam para o Portal em vez de /topup (um botão no chat poderia gastar o dinheiro do dono da sala), e com um pool de credenciais apenas o modelo recusado fica de fora até o reset — não a credencial inteira. Os demais modelos naquela key continuam funcionando.

Compatibilidade e limites

Do PR:

• Sem plano por janelas, todo caminho de código é igual ao de antes;
• cabeçalhos de resposta de usage window e códigos de recusa só são respeitados em rotas Nous, então outro upstream não pode disparar esta UI;
• apenas aditivo: nenhum comportamento existente de config, API ou CLI é removido.

Status da release

O PR #142308 foi mesclado na main em 22 de outubro de 2026 — mais de 200 arquivos, passando por CLI, TUI, gateway e Desktop. A release mais recente continua sendo a v0.22.4 de 21 de outubro, então isso está só na main até a próxima release chegar ao canal estável.

Para não confundir os vizinhos: /usage reset resgata resets de Codex acumulados (veja esse post), o Resetwatch é um plugin de Desktop de terceiros que coloca a cota restante de 14 plataformas numa única tela (veja esse post), e esta mudança é o suporte oficial a planos por allowance em si. Para o resto do comportamento do seletor de modelos, a referência de hermes model cobre as flags.