Cost Tracker

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

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.