token-trace-manager 0.7.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "token-trace-manager",
+  "owner": {
+    "name": "Mpaape"
+  },
+  "metadata": {
+    "description": "Proxy local universal de rastreio de tokens/custo para TUIs de código, com labels por ticket e dashboard local",
+    "version": "0.7.0"
+  },
+  "plugins": [
+    {
+      "name": "ttm",
+      "source": "./",
+      "description": "Proxy local universal de rastreio de tokens/custo para TUIs de código (Claude Code, Codex, OpenCode, Gemini CLI, Kilo...), com labels por ticket e dashboard local.",
+      "version": "0.7.0",
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "ttm",
+  "version": "0.7.0",
+  "description": "Proxy local universal de rastreio de tokens/custo para TUIs de código (Claude Code, Codex, OpenCode, Gemini CLI, Kilo...), com labels por ticket e dashboard local.",
+  "author": {
+    "name": "Mpaape"
+  },
+  "homepage": "https://github.com/cloud104/token-trace-manager",
+  "repository": "https://github.com/cloud104/token-trace-manager",
+  "license": "MIT",
+  "keywords": ["tokens", "custo", "proxy", "dashboard", "jira", "mcp", "opencode", "codex"],
+  "mcpServers": {
+    "ttm": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/lib/mcp-server.mjs"]
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "ttm": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/lib/mcp-server.mjs"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+Mudanças notáveis deste projeto. Formato: [Keep a Changelog](https://keepachangelog.com/), [semver](https://semver.org/).
+
+## [0.7.0] - 2026-07-08
+
+### Added
+- **`ttm link <tui>` / `ttm unlink <tui>`** — auto-link que descobre a base URL que o TUI já usa (env var, `~/.claude/settings.json`, `~/.codex/config.toml`, `opencode.json`), vira upstream dela, e reescreve a config do TUI pra apontar pro ttm. **Preserva redirect prévio** p/ compat-anthropic (z.ai/GLM/...) — não re-routa pro vendor real. Suporta `claude-code`, `codex`, `opencode`, `gemini-cli`. Idempotente, `--force` p/ relinkar, `--repo`, `--label`.
+- **`ttm config target <name> <url> [--protocol P] [--env VAR]`** — fallback manual ao auto-link; `--list`/`--remove`.
+- **Validação de protocolo** (allow-list `anthropic`/`openai`/`openai-responses`/`gemini`) em `readConfig`; protocolo inválido → 400 no proxy, **sem fabricar evento fantasma de 0 tokens**.
+- **Acurácia de tokens em compat parciais**: extratores registram `usage_fields` (quais campos o upstream reportou) e `usage_unknown`; `sawUsage` só é `true` quando um campo reconhecido está presente — subcontagem fica visível, não silenciosa.
+- **`targetUrlEnv`** — target segue uma env var em runtime (env-following); troca de redirect sem reconfig.
+- **Aviso de `targetUrl` com sufixo `/v1`** (colisão/dobramento de path no upstream).
+- **Snippets redirect-aware** (`claude-code`/`codex`/`opencode`/`gemini-cli`) com `ttm link` como caminho primário.
+- **Suporte Windows**: escrita atômica cross-platform (fallback `unlink+rename` no `fs.renameSync` que falha com EPERM), `pathToFileURL` no import dinâmico, `USERPROFILE` no teste, cleanup tolerante a arquivos abertos.
+- **CI** em matriz (ubuntu/windows/macos × Node 22/24).
+- `LICENSE` MIT, `files` explícito no `package.json`, `prepublishOnly` rodando os testes, `engines` honesto (`>=22.5`).
+
+### Changed
+- `package.json`: `private: false`, `repository`/`homepage`/`bugs` → `cloud104/token-trace-manager`, `keywords`, `author`.
+- `.claude-plugin/plugin.json` + `marketplace.json`: v0.7.0, `homepage`/`repository` → cloud104.
+- README: seção de Instalação reescrita (`npm i -g token-trace-manager` + `ttm link` + plugin marketplace cloud104 + nota sobre preservar redirect z.ai/GLM).
+
+### Fixed
+- Bug do Codex review: `ttm link` (auto-link) agora preserva o redirect prévio em vez de re-rotar pro vendor real.
+
+## [0.6.0] e anteriores
+
+Ver histórico de commits: `git log --oneline`. Destaques: payloads inspecionáveis (0.6.0), traces estilo Langfuse + retenção com rollups (0.5.0), auditoria agnóstica ao harness + export OTLP (0.4.0), proxy universal multi-TUI + MCP (0.2.0).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mpaape
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,380 @@
+# token-trace-manager (`ttm`)
+
+Proxy local **universal** de rastreio de tokens e custo para TUIs de código — Claude Code, Codex, OpenCode, Gemini CLI, Kilo Code, Goose, Crush, Aider, Cline, Roo Code, Droid, Copilot CLI e qualquer ferramenta que permita trocar a base URL do provedor.
+
+Um único daemon local intercepta as chamadas de API de todas as suas ferramentas, extrai o uso de tokens (streaming ou não), atribui a um **label/ticket** (ex: `PROJ-123`) e mostra tudo num **dashboard local**. Um **servidor MCP** embutido deixa o próprio agente consultar e controlar o rastreio de dentro de qualquer TUI compatível com MCP.
+
+## Regras de ouro
+
+- **Escuta só em `127.0.0.1`** (porta padrão **25519**, configurável) — nunca exposto na rede.
+- **Nunca toca nas chaves**: os headers de autenticação (`x-api-key`, `Authorization`) são repassados intactos ao provedor real e **jamais gravados** — em nenhum arquivo, nem nos payloads.
+- **Conteúdo é seu, e fica local**: por padrão, request/response de cada chamada são guardados em JSONs locais (`payloads/`) para inspeção mensagem a mensagem na página Traces — seguindo a mesma retenção (24h) e com botão de desligar na `/config` para quem não quiser conteúdo em disco.
+
+## Arquitetura
+
+```
+ Claude Code ──┐                          ┌──> api.anthropic.com
+ Codex ────────┤   proxyURL               ├──> api.openai.com
+ OpenCode ─────┼─> http://127.0.0.1:25519 ┼──> generativelanguage.googleapis.com
+ Gemini CLI ───┤   /{target}/{TICKET?}/…  ├──> openrouter.ai/api
+ Kilo, etc ────┘        │                 └──> (targets customizados)
+                        │ tee (só metadados de usage)
+                        v
+                SQLite local ──> dashboard http://127.0.0.1:25519/dashboard
+                        ^
+                servidor MCP (ttm_status, ttm_set_label, ttm_usage_summary, ...)
+```
+
+- **targetUrl** — a URL real do provedor que o TUI chamaria sem proxy (já vem preenchida para `anthropic`, `openai`, `gemini` e `openrouter`; adicione outras no config).
+- **proxyURL** — `http://127.0.0.1:25519`. O primeiro segmento do path escolhe o target; um segundo segmento opcional no formato `TICKET-123` vira o label daquela chamada.
+
+## Instalação
+
+Escolha o caminho pelo seu caso — cada um é completo e autossuficiente.
+
+### Caminho A — uso o Claude Code (plugin, recomendado)
+
+```
+1.  /plugin marketplace add cloud104/token-trace-manager
+2.  /plugin install ttm@token-trace-manager
+3.  Reinicie o Claude Code                                (plugins carregam na inicialização)
+4.  /ttm:setup                                            (sobe o daemon e, com sua aprovação,
+                                                            aponta o ANTHROPIC_BASE_URL pro proxy)
+5.  Reinicie o Claude Code de novo                        (a env var só vale pra sessão nova)
+```
+
+São **dois reinícios** mesmo — um para o plugin carregar, outro para a env var valer. Só na primeira vez; depois é só usar. Valide com `/ttm:status`: se aparecer o daemon rodando e as chamadas contando, está pronto. Os comandos disponíveis: `/ttm:setup`, `/ttm:status`, `/ttm:link`, `/ttm:dashboard`, `/ttm:config`.
+
+Quer rastrear outros TUIs além do Claude Code? O daemon já é o mesmo — só falta apontar cada ferramenta: `/ttm:setup codex` (ou `opencode`, `gemini-cli`...) mostra o snippet.
+
+### Caminho B — qualquer outro TUI (standalone, sem Claude Code)
+
+```bash
+npm install -g token-trace-manager   # instala o bin `ttm` (Node ≥ 22.5)
+
+ttm start                            # 1. sobe o daemon (idempotente)
+ttm link claude-code                 # 2. descobre a base URL do TUI e se insere no meio
+                                     #    (use: claude-code, codex, opencode, gemini-cli)
+ttm status                           # 3. confirma que está de pé
+```
+
+> **Já redireciona pra um compatível-anthropic (z.ai/GLM/...)?** O `ttm link` **preserva** o seu redirect — ele descobre pra onde você aponta, vira upstream disso, e reescreve a config do TUI pra passar pelo ttm. Continua batendo no mesmo lugar, só que com contagem de tokens.
+
+Sem npm? Funciona pelo git também:
+```bash
+git clone https://github.com/cloud104/token-trace-manager
+cd token-trace-manager
+npm link                             # deixa `ttm` no PATH (sem isso, use `node bin/ttm.mjs`)
+```
+
+Requer Node ≥ 22.5 (SQLite nativo via `node:sqlite`). Sem dependências — é Node puro.
+
+## No dia a dia
+
+```bash
+ttm summary --since 7d     # resumo no terminal        (ou /ttm:status no Claude Code)
+ttm dashboard              # abre o dashboard ao vivo   (ou /ttm:dashboard)
+ttm label PROJ-123         # muda o ticket padrão       (ou /ttm:link PROJ-123)
+ttm tokens PROJ-123        # SÓ a quantidade de tokens da tarefa — pronta pra colar no Jira
+```
+
+### Fechando a tarefa: preenchendo o campo "tokens gastos" do ticket
+
+A métrica é **tokens lidos / escritos** (como no Langfuse): *lidos* = tudo que o modelo leu (entrada + cache lido + cache escrito); *escritos* = tudo que gerou (inclui reasoning). Sai de dois jeitos:
+
+- **No dashboard**: a tabela "Tokens por tarefa" tem colunas Lidos/Escritos/Total e um botão **copiar** por linha — copia `4831207 lidos / 152030 escritos` pronto pra colar no campo do ticket. A busca no topo acha a tarefa na hora.
+- **No terminal**: `ttm tokens TCW-142 --since all` imprime `lidos=... escritos=... total=...`; com `--raw`, só o total inteiro (para scripts).
+
+O envio automático para o campo do Jira é a fase 2 (a base já guarda tudo por tarefa; com o MCP do Jira conectado é um comando a mais).
+
+## Auditabilidade — como confiar nos números
+
+Os **tokens não são estimados**: o proxy lê o objeto `usage` que o próprio provedor devolve em cada resposta (o mesmo dado que fatura sua conta). O **custo** é a única coisa calculada localmente: tokens × tabela de preços. Para isso ser verificável (estilo Langfuse, só que 100% local), cada chamada grava:
+
+- **`provider_id`** — o id da resposta no provedor (`msg_...`, `chatcmpl-...`, `resp_...`): o elo para reconciliar com qualquer outra fonte.
+- **`rates`** — o "recibo" das taxas aplicadas ($/1M por tipo de token, com a data da tabela): o custo é re-multiplicável para sempre, mesmo que a tabela mude depois.
+- O split de cache-write **1h vs 5m** da Anthropic (TTL 1h custa 2×, não 1.25× — sem capturar isso o custo sai ~35% menor em sessões do Claude Code, que usam cache de 1h).
+
+Duas ferramentas de verificação:
+
+```bash
+ttm audit --since 7d
+```
+
+1. **Matemática interna** (universal, qualquer TUI/provedor): re-multiplica tokens × taxas gravadas de cada evento e compara com o custo armazenado — divergência zero ou o comando falha.
+2. **Reconciliação com fontes independentes** — agnóstica ao harness, via adaptadores plugáveis. Cada TUI que mantém contabilidade local própria vira uma fonte; hoje:
+   - **Claude Code**: transcripts em `~/.claude/projects/` — casa **id a id** (`msg_...` = `provider_id`), token a token.
+   - **OpenCode**: `opencode.db` local — o OpenCode não guarda o id da resposta, então casa por **impressão digital** (tupla exata de tokens + mesma janela de tempo, 1:1).
+   - Eventos sem fonte local que os cubra (TUIs que não logam usage) aparecem listados como "sem fonte" — nunca somem. Novos harnesses = um adaptador novo em `lib/audit.mjs`, nada mais muda.
+
+No dashboard, o card **"Chamadas individuais (auditoria)"** mostra cada request com a conta aberta no hover: `7.213 × $10/M = $0.072130 (entrada)`, linha a linha. A verificação externa final é a página de usage do próprio provedor (Console da Anthropic / dashboard da OpenAI), que deve bater com os agregados do período.
+
+### Exportar para Langfuse (ou qualquer backend OTel) — opcional
+
+Rodar um Langfuse self-hosted é pesado (Postgres + ClickHouse + Redis); acoplá-lo quebraria a premissa de plugin pequeno. Em vez disso, o daemon tem um **exportador OTLP nativo (~100 linhas, sem dependências, desligado por padrão)**: um span GenAI por chamada, com `usage_details`/`cost_details` no formato que o Langfuse ingere. Funciona com o endpoint OTel do Langfuse (cloud ou self-hosted) e com qualquer collector OTel (Grafana, Jaeger...). Para ligar, no `config.json` do diretório de dados:
+
+```jsonc
+{
+  "otel": {
+    "endpoint": "https://cloud.langfuse.com/api/public/otel",
+    "headers": { "Authorization": "Basic <base64(pk-lf-...:sk-lf-...)>" }
+  }
+}
+```
+
+Fire-and-forget: exportar nunca atrasa nem derruba o proxy, e sem o bloco `otel` nenhum byte sai da máquina.
+
+> Caso real que motivou isso: a primeira chamada de teste registrou $0.52; a auditoria contra o log do Claude Code confirmou os 42.880 tokens **exatos**, mas revelou que o cache-write era todo TTL 1h — custo verdadeiro $0.79. O split passou a ser capturado desde a v0.3.0. Eventos antigos (sem recibo/provider_id) aparecem marcados como tal no audit, nunca silenciosamente.
+
+## Testando a instalação (30 segundos, com tráfego real)
+
+Sem mexer em nenhuma configuração: uma única chamada real do Claude Code, roteada pelo proxy só naquela invocação (a env var vale só para aquele comando), com um label de teste:
+
+```bash
+ttm start
+ANTHROPIC_BASE_URL=http://127.0.0.1:25519/anthropic/TESTE-1 claude -p "responda somente: ok"
+ttm summary --since 24h
+```
+
+Saída esperada — a resposta `ok` do Claude e, no summary, o label `TESTE-1` com tokens e custo reais:
+
+```
+período: 24h — 1 chamadas, 42.9k tokens, $0.52
+  TESTE-1                  42.9k tok      $0.52  (1 chamadas)
+```
+
+Se apareceu, está tudo validado de uma vez: daemon de pé, passthrough com sua autenticação intacta, extração de usage, atribuição por label e custo calculado. Abra `http://127.0.0.1:25519/dashboard` para ver no navegador. (Para testar os internos sem rede: `npm test` — 40 asserções contra um upstream fake.)
+
+## Configurando cada TUI
+
+O padrão é sempre o mesmo: trocar a base URL da ferramenta de `targetUrl` (a URL padrão do provedor) para `proxyURL/{target}`. Com um ticket no path (`proxyURL/{target}/PROJ-123`), todo o tráfego daquela configuração é atribuído ao ticket. `ttm setup <tui>` imprime o snippet da sua porta atual.
+
+### Claude Code
+`targetUrl` padrão: `https://api.anthropic.com` — override por env var `ANTHROPIC_BASE_URL` (precisa existir **antes** do processo iniciar):
+
+```jsonc
+// ~/.claude/settings.json (todas as sessões) ou .claude/settings.json do repo:
+{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:25519/anthropic" } }
+
+// por repositório, com ticket embutido:
+{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:25519/anthropic/PROJ-123" } }
+```
+
+> Atenção: desde a v2.1.196, apontar `ANTHROPIC_BASE_URL` para fora de `api.anthropic.com` desativa o Remote Control do Claude Code. A autenticação (inclusive OAuth de assinatura) continua funcionando — o proxy repassa tudo intacto. E o `/ttm:setup` faz essa edição para você, com sua aprovação.
+
+### Codex (OpenAI)
+`targetUrl` padrão: `https://api.openai.com/v1`, protocolo Responses API — override no `~/.codex/config.toml` (o config de projeto ignora esta chave):
+
+```toml
+model_provider = "ttm"
+
+[model_providers.ttm]
+name = "OpenAI via ttm"
+base_url = "http://127.0.0.1:25519/openai/v1"       # com ticket: /openai/PROJ-123/v1
+wire_api = "responses"
+env_key = "OPENAI_API_KEY"
+```
+
+> Prefira `model_providers` a `openai_base_url`/`OPENAI_BASE_URL`: há releases do Codex com bug que ignora essas formas (issue #16719).
+
+### OpenCode (sst)
+Multi-provider — override no `opencode.json` (projeto ou global):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": { "options": { "baseURL": "http://127.0.0.1:25519/anthropic" } },
+    "openai":    { "options": { "baseURL": "http://127.0.0.1:25519/openai/v1" } }
+  }
+}
+```
+
+O OpenCode também suporta MCP — aponte para `node <repo>/lib/mcp-server.mjs` no bloco `mcp` do `opencode.json` e ganhe as mesmas tools `ttm_*` lá dentro.
+
+### Gemini CLI (Google)
+`targetUrl` padrão: `https://generativelanguage.googleapis.com` — override por env var (http permitido para 127.0.0.1):
+
+```bash
+export GEMINI_API_KEY=sua-chave
+export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:25519/gemini"
+```
+
+> Limitação: só o modo **API key** é rastreável. No login OAuth pessoal, o Gemini CLI usa o backend interno Code Assist (`cloudcode-pa.googleapis.com`), que essa variável não afeta.
+
+### Kilo Code
+`targetUrl` padrão: gateway próprio (`api.kilo.ai`) — para rastrear, use um provider OpenAI-compatible no `kilo.jsonc` ou na UI (Settings → Providers → Custom Provider → Base URL):
+
+```jsonc
+{
+  "provider": {
+    "openai-compatible": {
+      "options": { "apiKey": "{env:OPENAI_API_KEY}", "baseURL": "http://127.0.0.1:25519/openai/v1" }
+    }
+  }
+}
+```
+
+### Goose (Block)
+```bash
+export OPENAI_HOST="http://127.0.0.1:25519/openai"        # provider OpenAI-compatible
+export ANTHROPIC_HOST="http://127.0.0.1:25519/anthropic"  # provider Anthropic
+```
+
+### Crush (Charm)
+`crush.json` (ou `~/.config/crush/crush.json`):
+
+```jsonc
+{
+  "providers": {
+    "ttm-anthropic": { "type": "anthropic", "base_url": "http://127.0.0.1:25519/anthropic/v1", "api_key": "$ANTHROPIC_API_KEY" },
+    "ttm-openai": { "type": "openai-compat", "base_url": "http://127.0.0.1:25519/openai/v1", "api_key": "$OPENAI_API_KEY" }
+  }
+}
+```
+
+### Aider
+```bash
+export OPENAI_API_BASE="http://127.0.0.1:25519/openai/v1"
+# ou: aider --openai-api-base http://127.0.0.1:25519/openai/v1
+```
+
+### Cline / Roo Code
+Só via interface: Settings → API Provider = "OpenAI Compatible" → Base URL = `http://127.0.0.1:25519/openai/v1`.
+
+### Droid (Factory AI)
+`~/.factory/settings.json`:
+
+```jsonc
+{ "customModels": [{ "model": "claude-opus-4-8", "provider": "anthropic", "baseUrl": "http://127.0.0.1:25519/anthropic", "apiKey": "${ANTHROPIC_API_KEY}" }] }
+```
+
+### GitHub Copilot CLI (modo BYOK)
+```bash
+export COPILOT_PROVIDER_BASE_URL="http://127.0.0.1:25519/openai/v1"
+export COPILOT_PROVIDER_TYPE=openai
+export COPILOT_MODEL=gpt-5.5
+export COPILOT_PROVIDER_API_KEY=sua-chave
+```
+O modo padrão (backend proprietário do Copilot) não é rastreável.
+
+### Não suportados (sem override documentado de base URL)
+- **Amp (Sourcegraph)** — roteia modelos pelo backend proprietário; `HTTP_PROXY` é só transporte.
+- **Cursor CLI** — o `cursor-agent` fala com o backend da Cursor; o BYOK da IDE não vale para o CLI.
+- **Kiro CLI (AWS)** — nenhum mecanismo documentado.
+
+## Labels (atribuição por ticket)
+
+Duas formas, combináveis:
+
+1. **Na URL** (recomendado, por repo/branch): `http://127.0.0.1:25519/anthropic/PROJ-123` — tudo que passar por essa configuração cai no `PROJ-123`. Ideal via `.claude/settings.json` por repositório, ou um `opencode.json` por projeto.
+2. **Label padrão global**: `ttm label PROJ-123` (ou tool MCP `ttm_set_label`, ou `/ttm:link PROJ-123` no Claude Code) — vale para todo tráfego **sem** label na URL, de qualquer TUI, até trocar. `ttm label none` limpa.
+
+Chamadas sem nenhum label aparecem no dashboard como "Sem label" — nada se perde.
+
+> A ideia é fechar custo por tarefa localmente. Enviar os agregados para o campo do ticket no Jira é uma fase futura (a base já registra tudo por label).
+
+## As páginas do proxy (ao vivo, só em 127.0.0.1)
+
+| Página | O que tem |
+|---|---|
+| `/dashboard` | Visão geral: KPIs lidos/escritos, tabela "Tokens por tarefa" (share, sparkline, botão copiar no hover), quebras por provedor/modelo/cliente/dia, chamadas recentes. |
+| `/traces` | **Inspetor estilo Langfuse**: sessões (agrupadas por cliente + tarefa + janela de inatividade de 30min) → expande para as mensagens uma a uma — entrada, cache escrito (5m/1h), cache lido, saída, custo com o recibo aberto no hover, duração, id no provedor (clique copia) e o botão **conteúdo**, que abre o payload da chamada: sistema, mensagens (papel a papel) e a resposta do modelo. Filtros por período, provedor, modelo, cliente e tarefa. |
+| `/config` | Retenção dos traces (padrão **24h**, editável; `0` = nunca apagar), botões de limpeza/deleção e resumo da configuração. |
+
+APIs JSON para automações: `GET /api/summary` (com `tasks`), `/api/traces`, `/api/events`, `/api/payload?id=N` (request/response da chamada), `/api/label`, `/api/config`, `/healthz`; `POST /api/retention`, `/api/purge`, `/api/settings`. `ttm dashboard --out relatorio.html` exporta a visão geral como HTML estático.
+
+## Retenção e histórico
+
+Tudo fica num **SQLite interno** (`~/.claude/plugins/data/token-trace-manager/ttm.sqlite`), que sobrevive a upgrades do plugin. Duas camadas com vidas diferentes:
+
+- **Traces detalhados** (mensagem a mensagem): retidos por **24h por padrão** — ajuste na página `/config` (até 1 ano, ou `0` para nunca apagar). Um job de hora em hora expira os antigos.
+- **Histórico por tarefa**: ao expirar, cada trace é **somado num rollup diário por tarefa/modelo/provedor antes de ser apagado** — o total que vai pro campo do Jira nunca se perde, só o detalhe individual. O dashboard mistura as duas camadas automaticamente, sem dupla contagem (um rollup só existe para traces já apagados).
+- **Conteúdo das chamadas** (`payloads/<id>.json`): request completo (sistema + mensagens) e o texto da resposta, para o drill-down da página Traces. Vive e morre com o trace correspondente (retenção e deleções removem os JSONs juntos). Toggle na `/config`.
+- **Deleção sob demanda** na `/config`: apagar todos os traces (mantendo o histórico), ou apagar tudo — inclusive por tarefa específica via `POST /api/purge {"mode": "...", "label": "PROJ-123"}`.
+
+## Servidor MCP
+
+O mesmo servidor funciona em qualquer cliente MCP e **sobe o daemon sozinho** quando necessário:
+
+| Tool | O que faz |
+|---|---|
+| `ttm_status` | daemon rodando?, porta, label padrão, targets, URL do dashboard |
+| `ttm_set_label` | define/limpa o label padrão |
+| `ttm_usage_summary` | resumo por label/provedor/modelo/dia (`since`, `label`) |
+| `ttm_dashboard_url` | garante o daemon de pé e retorna a URL do dashboard |
+
+No Claude Code vem junto com o plugin. No OpenCode:
+
+```jsonc
+// opencode.json
+{ "mcp": { "ttm": { "type": "local", "command": ["node", "/caminho/do/repo/lib/mcp-server.mjs"] } } }
+```
+
+## CLI
+
+```
+ttm start | stop | status         gerencia o daemon
+ttm label <TICKET-123|none>       label padrão
+ttm summary [--since 7d]          resumo no terminal
+ttm dashboard [--since 7d] [--out arquivo.html]
+ttm tokens <TICKET> [--since] [--raw]   lidos/escritos da tarefa (--raw: só o total)
+ttm audit [--since 7d]            auditoria: matemática interna + fontes independentes
+ttm targets                       lista os upstreams registrados
+ttm config [porta <n>]            mostra config / troca a porta
+ttm setup <tui>                   snippet de configuração por ferramenta
+```
+
+## Configuração avançada
+
+Arquivo: `~/.claude/plugins/data/token-trace-manager/config.json` (criado sob demanda):
+
+```jsonc
+{
+  "port": 25519,
+  "injectUsage": true,   // injeta include_usage em streams OpenAI sem usage (e filtra o chunk extra)
+  "targets": {
+    "meugateway": { "targetUrl": "https://llm.minhaempresa.com/api", "protocol": "openai" }
+  }
+}
+```
+
+- **Protocolos suportados**: `anthropic`, `openai` (chat completions **e** Responses API, detectado pelo path), `openai-responses`, `gemini`.
+- **`injectUsage`**: streams de chat completions sem `stream_options.include_usage` não trazem usage. O proxy injeta a opção na request e **remove o chunk extra da resposta** antes de repassar (SDKs oficiais toleram o chunk, mas wrappers comuns — LangChain, Haystack — quebram; por isso o filtro). Se o cliente já pediu `include_usage`, nada é alterado.
+- **Preços**: tabela em `lib/pricing.mjs` (Anthropic/OpenAI/Gemini, coletados das páginas oficiais em 2026-07-06). Modelos fora da tabela têm custo `null` — os tokens são registrados mesmo assim e o dashboard sinaliza custo parcial. Override sem tocar em código: `pricing.override.json` no diretório de dados, ex: `{ "meu-modelo": { "input": 2.0, "output": 8.0 } }` (USD/1M tokens).
+
+## Comandos do plugin (Claude Code)
+
+| Comando | O que faz |
+|---|---|
+| `/ttm:setup [tui]` | configura o Claude Code para passar pelo proxy (edita settings com sua aprovação) ou mostra o snippet de outro TUI |
+| `/ttm:status` | estado do daemon + resumo de uso/custo |
+| `/ttm:link PROJ-123` | define o label padrão |
+| `/ttm:dashboard` | abre o dashboard local |
+| `/ttm:config` | mostra porta, targets e label; explica como ajustar |
+
+## Testes
+
+```bash
+node test/e2e.mjs
+```
+
+Sobe um upstream fake + o daemon real e valida: passthrough de streaming e não-streaming nos 4 protocolos, labels por URL e por padrão, normalização de tokens (cache/reasoning), cálculo de custo, injeção+filtragem de `include_usage`, endpoints locais, dashboard, privacidade (nenhuma chave ou conteúdo persistido) e as regressões da revisão adversarial (XSS via User-Agent, corrupção por `$'` no template, rotas herdadas de protótipo, erros de protocolo MCP). 81+ asserções, cobrindo também retenção/rollups, contexto repo/branch, relabel retroativo, sessionização de traces e o exportador OTel.
+
+## Upgrade
+
+Versionamento semver em `.claude-plugin/plugin.json`. Como plugin:
+
+```
+/plugin update ttm            (reinicie o Claude Code para aplicar)
+```
+
+Standalone: `git pull` e `ttm stop && ttm start`.
+
+## Limitações conhecidas
+
+- O TUI precisa suportar override de base URL (ver lista de não suportados acima).
+- Se o daemon estiver parado, o TUI configurado fica sem resposta — `ttm start` resolve; o servidor MCP e o CLI sobem o daemon automaticamente.
+- Preços de modelos mudam; a tabela é estática com data marcada (`ttm config` mostra) e override via `pricing.override.json`.
+- Gemini CLI: só modo API key (OAuth usa backend interno não roteável).
+- O custo do Sonnet 5 usa o preço introdutório ($2/$10) válido até 2026-08-31 — atualizar para $3/$15 depois disso.