Cost Tracker

O Cost Tracker monitora e consolida os custos de cada sessao de trabalho. Rastreia tokens consumidos por skill, chamadas de API externas, tempo de execucao e modelo utilizado, gerando um relatorio detalhado de custo estimado ao final da sessao.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/persistence.md, policies/token-efficiency.md, policies/tool-safety.md, policies/handoffs.md, policies/evals.md, policies/memory-tiers.md e policies/memory-consolidation.md (sugerir /consolidate-memory quando vault crescer demais).

Quando Usar

• ao final de uma sessao para consolidar custos
• quando o usuario perguntar quanto custou ou qual o consumo
• quando o pipeline for longo e envolver multiplas skills
• quando o objetivo for otimizar gastos e identificar skills mais caras

Quando Nao Usar

• para decisoes de negocio baseadas em custo real de infra
• para substituir billing real de provedores (fal.ai, Brave, Firecrawl)
• para estimar custo de infraestrutura de deploy ou hosting

Entradas Esperadas

• pipeline executado e skills acionadas
• chamadas de API externas realizadas (fal.ai, Brave, Firecrawl)
• metadata de respostas LLM (tokens de entrada/saida)

Saidas Esperadas

• relatorio em docs/cost-reports/session-YYYY-MM-DD.md
• resumo de custo por skill
• total estimado da sessao

Responsabilidades

1. Rastrear tokens consumidos por skill durante o pipeline
2. Contabilizar chamadas de API externa (fal.ai, Brave Search, Firecrawl)
3. Calcular custo estimado com base no modelo usado e volume de tokens
4. Gerar relatorio estruturado de custo da sessao
5. Persistir historico de custos para comparacao entre sessoes

Metricas Rastreadas

Metrica	Fonte	Exemplo
Tokens consumidos	LLM response metadata	12.400 input / 3.200 output
Chamadas API fal.ai	Contagem por tool call	3 chamadas (image gen)
Chamadas API Brave	Contagem por tool call	5 chamadas (search)
Chamadas API Firecrawl	Contagem por tool call	2 chamadas (scrape)
Tempo de execucao	Timestamps inicio/fim	14min 32s
Modelo usado	Model Routing policy	claude-sonnet-4-20250514

Memory Tiers e Decay

O Cost Tracker também monitora a saúde dos tiers de memória ao final de cada sessão:

• Learned-skills com score baixo (< 0.3): listar para arquivamento
• Learned-skills candidatas à promoção (score ≥ 0.8): sinalizar para skill 35
• Tamanho do devkit_context_pack: alertar se exceder 500 tokens por entrada

Ver policies/memory-tiers.md para a lógica completa de score e decay.

Formato do Relatorio

# Relatorio de Custo — Sessao YYYY-MM-DD

## Pipeline Executado
[nome do pipeline ou descricao]

## Skills Acionadas
| Skill | Tokens (in/out) | API Calls | Custo Estimado |
|---|---|---|---|
| Repo Auditor | 8.000 / 2.100 | 0 | $0.03 |
| Frontend Integration | 15.000 / 5.200 | 2 fal.ai | $0.12 |

## Chamadas de API Externa
| Provedor | Quantidade | Custo Estimado |
|---|---|---|
| fal.ai | 2 | $0.08 |
| Brave Search | 5 | $0.01 |

## Resumo
- **Total de tokens**: 45.600 input / 14.300 output
- **Total de chamadas API**: 7
- **Custo total estimado**: $0.25
- **Duracao da sessao**: 14min 32s

Integracao com Outras Skills

• Orchestrator (09): aciona o Cost Tracker ao final do pipeline para gerar relatorio
• Model Routing (policy): fornece o tier de modelo usado por skill/subagent, impactando o calculo de custo. Ver policies/model-routing.md
• Todas as skills: reportam consumo de tokens e chamadas no handoff (bloco tokens_in/tokens_out/api_calls no handoff estruturado da skill, seguindo policies/handoffs.md) — sem isso o Cost Tracker não tem de onde puxar o número, e não deve inventar estimativa não-declarada

Checkpoint antes de gerar o relatório: somar os totais por skill e conferir contra o total geral — se a soma das partes não bater com o total (skill reportou tokens mas não entrou na soma, ou duplicou), corrigir a consolidação antes de persistir. Um relatório com totais que não fecham é pior que nenhum relatório.

Evidencia de Conclusao

• relatorio de custo gerado em docs/cost-reports/
• metricas de tokens e chamadas API coletadas
• historico de custos atualizado

Handoff

Entregar:

• caminho do relatorio de custo
• highlight das skills mais caras da sessao
• recomendacao de otimizacao (ex: usar modelo menor, reduzir chamadas)

Seguir policies/handoffs.md.

Codigo Limpo

Manter relatorios concisos, metricas precisas e formatos consistentes entre sessoes.