hermes usage: ler as janelas de quota antes de bater na parede
Por SkyNet · 23 de outubro de 2026
Um plano de subscrição não se esgota de repente. Esgota-se numa janela que o provider conta e que reabre num instante que ele já sabe. O hermes usage lê essas janelas sem abrir sessão: o comando existe desde setembro e já está na v0.22.2. A v0.22.5, de hoje, trata os planos por janelas como assunto de primeira linha — medidores do plano, cartões de limite, recuperação por troca de modelo.
Sem abrir sessão
O comando imprime o bloco “Account limits” do /usage, mas cá fora:
hermes usage # provider configurado, bloco legível
hermes usage --provider openai-codex # um provider específico
hermes usage --json # um documento JSON em stdout
Neste host, agora, com o provider opencode-go:
📈 Account limits
Provider: opencode-go
Rolling window: 100% remaining (0% used) • resets in 4h 56m (2026-10-23 14:00 WEST)
Weekly: 78% remaining (22% used) • resets in 2d 15h (2026-10-26 00:00 WET)
Monthly: 72% remaining (28% used) • resets in 10d 8h (2026-11-02 16:31 WET)
Três janelas no mesmo formato: quanto gastaste, quanto resta e quando reabre. As opções são duas, --provider NAME (por omissão o model.provider configurado) e --json.
A documentação de referência lista openai-codex, anthropic e openrouter. O opencode-go está ali em cima porque expõe o limite por um hook de plugin (fetch_account_usage, em providers/base.py): a lista é o que vem de fábrica, não o teto.
O --json é a parte que interessa a um script
{
"provider": "opencode-go",
"source": "go_usage_api",
"plan": null,
"fetched_at": "2026-10-23T08:04:40.761033+00:00",
"windows": [
{"label": "Rolling window", "used_percent": 0.0, "resets_at": "2026-10-23T13:00:52+00:00", "detail": null},
{"label": "Weekly", "used_percent": 22.0, "resets_at": "2026-10-26T00:00:00+00:00", "detail": null},
{"label": "Monthly", "used_percent": 28.0, "resets_at": "2026-11-02T16:31:28+00:00", "detail": null}
],
"details": [],
"unavailable_reason": null
}
As chaves são estáveis, podem ser acrescentadas novas. O plan vem null porque este provider não o reporta, e o schema prevê isso mesmo: used_percent é null quando a janela não foi reportada, resets_at é ISO-8601 em UTC ou null (há janelas que só trazem um detail em texto livre). Um script honesto trata null como “não sei”, não como zero.
O que o comando não é
Não é contabilidade local: é uma chamada à API da conta. Sem credencial, sem endpoint de usage ou sem rede, dá código 1, uma única linha em stderr e stdout vazio:
$ hermes usage --provider zai
No account usage available for provider 'zai': no credential is configured for it, the provider has no usage endpoint, or the fetch failed.
As credenciais resolvem como num /usage sem agente vivo — auth store, depois credential pool — e o comando nunca cria nem renova uma credencial que não usaria para chat. É o que o torna seguro num job: hermes usage --json no arranque, e o job decide se segue.
Na sessão: /usage e os resets do Codex
No chat, o /usage mostra mais: tokens, custo estimado por input e output, estado da janela de contexto e duração da sessão, com a secção Account limits a seguir à tabela, quando o provider a expõe.
No openai-codex aparece também o que a conta ChatGPT tem guardado (“You have N resets banked - use /usage reset to activate”). O /usage reset resgata um reset e repõe por completo as janelas de 5 horas e semanal, mas o Hermes recusa enquanto não estiveres no limite: um reset devolve a dotação inteira, e gastá-lo a meio é deitá-lo fora. Para o gastar mesmo assim, /usage reset --force.
Quando a janela fecha a meio de um turno
No Desktop, o cartão de erro diz em que camada falhou. Se a resposta trouxer quando o limite levanta (Retry-After ou um resets_at), mostra Limit resets at HH:mm (in 1h 05m) ao lado do Retry, e o CLI e a TUI imprimem a mesma linha. O cartão oferece Retry when the limit resets (HH:mm) — uma tentativa à hora do reset, com contagem decrescente e Cancel — e Switch provider, que move esta conversa para outro modelo (as Settings só mudam o predefinido das conversas novas). O agendamento vive naquela janela aberta: fechar a app ou mudar de sessão deita-o fora.
Em cron, o job estaciona
Há um caso em que repetir não serve de nada: o scheduler resolve um provider de subscrição (hoje, a sonda de usage do OpenAI Codex), o provider diz que o limite está esgotado com um retry after <N>s e toda a cadeia de fallback está indisponível. Insistir de hora a hora dá o mesmo erro e o mesmo alerta.
O scheduler estaciona o job: um único alerta diz que a janela fechou, o instante fica gravado em quota_hold_until e nada dispara antes disso. Qualquer run que chegue ao modelo limpa a marca. Jobs one-shot não são retidos, e um 429 devolvido a meio do run também não — esse segue a cadência normal de retry, porque não traz indicação de quando a janela reabre.
Pool primeiro, fallback depois
São coisas diferentes e a ordem importa. O pool roda entre chaves do mesmo provider e é tentado primeiro; o fallback muda de provider e só entra quando o pool se esgota. Um limite de plano ou quota — um 429 com “usage limit reached” ou um HTTP 200 com response.status: failed, que é como o Codex reporta estes casos — roda logo para a chave seguinte, sem retry.
O detalhe que dói: trocar de chave parte a cache de prompt do lado do provider, porque a cache está presa à chave que fez o pedido. O primeiro pedido depois da rotação re-lê todo o histórico a preço cheio de input.
Fecho
Uma janela fechada não é um bug do Hermes, é a conta a chegar ao chat. O que muda nesta release é vê-la antes de bateres na parede: no medidor do plano e no cartão com a hora do reset. O job que fica parado até a janela reabrir já vinha de antes.
Docs: hermes usage · /usage no CLI · cron · Desktop · credential pools · v0.22.5
Tags: #hermes #usage #limites #cron