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