# pi-usage-panel

Extensão do [pi](https://github.com/earendil-works/pi-coding-agent) que registra o comando `/usage`: um painel agregado combinando **quota real do Kimi** (via API do Kimi) com o **consumo local das sessões pi** (lido dos seus próprios arquivos de sessão).

## Funcionalidades

- **`/usage`** — relatório agregado com duas seções:
  - **KIMI** — quota real (plano, janelas de uso, booster wallet, paralelismo) obtida de `GET https://api.kimi.com/coding/v1/usages`.
  - **PI-CODE** — consumo local de tokens/custo agregado dos arquivos de sessão do pi (`~/.pi/agent/sessions`), agrupado por hoje / semana / mês / total e por provider/modelo.
- **`/usage --json`** — saída JSON crua agregada (a chave da API nunca é incluída; redação profunda como defesa em profundidade).
- **`/usage --refresh`** — ignora o cache em memória.
- **Painel TUI** — no modo interativo (TUI), o resultado aparece num painel compacto e rolável com moldura caramelo (`↑`/`↓`/`PgUp`/`PgDn` para rolar, `Esc`/`q` para fechar). Nos modos RPC/print o mesmo conteúdo é exibido como texto simples. As janelas de uso são exibidas na maior unidade (ex.: `Janela 5h`), e períodos de agregação idênticos (ex.: semana = mês = total) são deduplicados.

## Instalação

Via GitHub:

```
pi install git:github.com/ProCleiton/pi-usage-panel
```

Via npm:

```
pi install npm:pi-usage-panel
```

Requer **Node.js >= 22** (a extensão e seus testes dependem do type-stripping nativo de TypeScript).

## Configuração

A configuração é feita exclusivamente por variáveis de ambiente. Não há fallback para arquivos de credenciais de nenhum tipo.

| Variável | Default | Descrição |
|---|---|---|
| `KIMI_CODE_API` | — | Chave da API Kimi. **Obrigatória** para a seção KIMI; sem ela, a seção mostra um aviso de indisponibilidade. |
| `PI_USAGE_CACHE_TTL_MS` | `60000` | TTL do cache em memória em milissegundos (lazy, sem timers). |
| `PI_SESSIONS_DIR` | `~/.pi/agent/sessions` | Diretório raiz das sessões pi (varredura recursiva de `*.jsonl`). |
| `PI_USAGE_TIMEZONE` | `America/Fortaleza` | Timezone IANA usado nos limites de período (hoje/semana/mês) e nas datas exibidas. |

A chave nunca é impressa, logada ou incluída em erros/saída `--json` — toda mensagem de erro e o payload JSON passam por um sanitizador que redige qualquer ocorrência acidental da chave.

## Fontes de dados & privacidade

Esta extensão lê de exatamente duas fontes:

1. **API Kimi** — um único `GET` autenticado para `https://api.kimi.com/coding/v1/usages`, usando a chave de `KIMI_CODE_API`. É a única chamada de rede e o único terceiro que recebe qualquer coisa (sua chave, como Bearer token, para o próprio Kimi).
2. **Arquivos de sessão locais** — varredura somente-leitura e em streaming de `$PI_SESSIONS_DIR/**/*.jsonl` (default `~/.pi/agent/sessions`). Apenas linhas com registros `usage` de assistant são parseadas; linhas malformadas e arquivos ilegíveis são ignorados.

- **Nenhum dado é enviado a lugar algum além da chamada à API Kimi descrita acima.** Sem telemetria, sem analytics, sem logs remotos.
- **Nenhuma credencial fica no código** e nenhum arquivo de credenciais é lido — a chave vem apenas da variável de ambiente.
- A varredura de sessões é local e somente-leitura; nada é escrito de volta.

## Desenvolvimento

Rode a suíte de testes (Node puro, sem dependências):

```
node test/run-tests.mjs
```

## Screenshots

- [ ] TODO: screenshot do painel TUI
- [ ] TODO: exemplo de saída `--json`
- [ ] TODO: exemplo de saída em modo print

## Licença

MIT — veja [LICENSE](LICENSE). Copyright (c) 2026 ProCleiton.