token-trace-manager 0.7.0

package/lib/report-data.mjs

@@ -0,0 +1,171 @@
+import { listUsageEvents, listRollups } from './db.mjs'
+
+function sinceToIso(since) {
+  if (!since || since === 'all') return null
+  if (/^\d{4}-\d{2}-\d{2}/.test(since)) return since
+  const m = /^(\d+)([dh])$/.exec(since)
+  if (!m) return null
+  const ms = m[2] === 'd' ? 86400000 : 3600000
+  return new Date(Date.now() - parseInt(m[1], 10) * ms).toISOString()
+}
+
+export async function buildReport({ since = '30d', label = null } = {}) {
+  if (label) label = label.toUpperCase() // labels são armazenados em maiúsculas
+  const sinceIso = sinceToIso(since)
+  const rows = await listUsageEvents({ since: sinceIso, label })
+
+  // Histórico agregado (traces já expirados pela retenção) entra como
+  // pseudo-eventos diários — sem risco de dupla contagem: um rollup só
+  // existe para eventos que JÁ foram apagados.
+  const rollups = await listRollups({
+    sinceDay: sinceIso ? sinceIso.slice(0, 10) : null,
+    label: label ?? undefined,
+  })
+  for (const r of rollups) {
+    rows.push({
+      ts: r.day + 'T12:00:00.000Z',
+      label: r.label || null,
+      target: r.target,
+      model: r.model || null,
+      client: r.client || null,
+      input_tokens: r.input_tokens,
+      cache_create_tokens: r.cache_create_tokens,
+      cache_create_1h_tokens: r.cache_create_1h_tokens,
+      cache_read_tokens: r.cache_read_tokens,
+      output_tokens: r.output_tokens,
+      reasoning_tokens: r.reasoning_tokens,
+      cost_usd: r.cost_known ? r.cost_usd : null,
+      _rollup: true,
+      _count: r.events,
+    })
+  }
+
+  let totalCost = 0
+  let totalTokens = 0
+  let tokensIn = 0 // "lidos": tudo que o modelo leu (entrada + cache lido + cache escrito)
+  let tokensOut = 0 // "escritos": tudo que o modelo gerou (inclui reasoning)
+  let costKnown = true
+  const byLabel = new Map()
+  const byTarget = new Map()
+  const byModel = new Map()
+  const byDay = new Map()
+  const byClient = new Map()
+  const tasks = new Map() // visão rica por tarefa — a razão do projeto existir
+
+  const rowTokens = r =>
+    (r.input_tokens || 0) + (r.cache_create_tokens || 0) + (r.cache_read_tokens || 0) + (r.output_tokens || 0)
+
+  const bump = (map, key, row) => {
+    const cur = map.get(key) || { cost: 0, tokens: 0, events: 0 }
+    cur.cost += row.cost_usd || 0
+    cur.tokens += rowTokens(row)
+    cur.events += row._count ?? 1
+    map.set(key, cur)
+  }
+
+  for (const r of rows) {
+    totalCost += r.cost_usd || 0
+    totalTokens += rowTokens(r)
+    tokensIn += (r.input_tokens || 0) + (r.cache_create_tokens || 0) + (r.cache_read_tokens || 0)
+    tokensOut += r.output_tokens || 0
+    if (r.cost_usd === null || r.cost_usd === undefined) costKnown = false
+
+    const labelKey = r.label || 'Sem label'
+    bump(byLabel, labelKey, r)
+    bump(byTarget, r.target, r)
+    bump(byModel, r.model || '(desconhecido)', r)
+    bump(byClient, (r.client || '(desconhecido)').split('/')[0].split(' ')[0], r)
+    bump(byDay, (r.ts || '').slice(0, 10), r)
+
+    let t = tasks.get(labelKey)
+    if (!t) {
+      t = {
+        key: labelKey,
+        tokens: 0,
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheCreate: 0,
+        reasoning: 0,
+        cost: 0,
+        events: 0,
+        firstTs: null,
+        lastTs: null,
+        byDay: new Map(),
+      }
+      tasks.set(labelKey, t)
+    }
+    t.tokens += rowTokens(r)
+    t.input += r.input_tokens || 0
+    t.output += r.output_tokens || 0
+    t.cacheRead += r.cache_read_tokens || 0
+    t.cacheCreate += r.cache_create_tokens || 0
+    t.reasoning += r.reasoning_tokens || 0
+    t.cost += r.cost_usd || 0
+    t.events += r._count ?? 1
+    if (r.ts) {
+      if (!t.firstTs || r.ts < t.firstTs) t.firstTs = r.ts
+      if (!t.lastTs || r.ts > t.lastTs) t.lastTs = r.ts
+      const day = r.ts.slice(0, 10)
+      t.byDay.set(day, (t.byDay.get(day) || 0) + rowTokens(r))
+    }
+  }
+
+  const toSorted = m =>
+    [...m.entries()]
+      .sort((a, b) => b[1].cost - a[1].cost || b[1].tokens - a[1].tokens)
+      .map(([key, v]) => ({ key, ...v }))
+
+  return {
+    generatedAt: new Date().toISOString(),
+    since,
+    label,
+    totalCost,
+    totalTokens,
+    tokensIn,
+    tokensOut,
+    costKnown,
+    eventCount: rows.reduce((n, r) => n + (r._count ?? 1), 0),
+    taskCount: tasks.size,
+    // tarefas ordenadas por TOKENS (a métrica que vai pro campo do Jira), não por custo
+    tasks: [...tasks.values()]
+      .sort((a, b) => b.tokens - a.tokens)
+      .map(t => ({
+        ...t,
+        tokensIn: t.input + t.cacheRead + t.cacheCreate,
+        tokensOut: t.output,
+        byDay: [...t.byDay.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([day, tokens]) => ({ day, tokens })),
+      })),
+    byLabel: toSorted(byLabel),
+    byTarget: toSorted(byTarget),
+    byModel: toSorted(byModel),
+    byClient: toSorted(byClient),
+    byDay: [...byDay.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([day, v]) => ({ day, ...v })),
+    // traces individuais (auditoria) — rows já vêm ordenadas por ts DESC
+    recentCalls: rows.filter(r => !r._rollup).slice(0, 50).map(r => {
+      let rates = null
+      try {
+        rates = r.rates ? JSON.parse(r.rates) : null
+      } catch {
+        /* evento antigo */
+      }
+      return {
+        ts: r.ts,
+        label: r.label,
+        target: r.target,
+        model: r.model,
+        providerId: r.provider_id ?? null,
+        input: r.input_tokens || 0,
+        cacheCreate: r.cache_create_tokens || 0,
+        cacheCreate1h: r.cache_create_1h_tokens || 0,
+        cacheRead: r.cache_read_tokens || 0,
+        output: r.output_tokens || 0,
+        cost: r.cost_usd,
+        rates,
+        durationMs: r.duration_ms,
+        client: r.client,
+        status: r.status,
+      }
+    }),
+  }
+}

package/lib/setup-snippets.mjs

@@ -0,0 +1,201 @@
+// Snippets de configuração por TUI, confirmados nas docs oficiais de cada
+// ferramenta (pesquisa 2026-07-06). Fonte da lista: agentes suportados no
+// skills.sh + principais TUIs de mercado.
+
+export function setupSnippet(tui, cfg) {
+  const P = `http://127.0.0.1:${cfg.port}`
+  const snippets = {
+    'claude-code': `Claude Code — caminho primário: auto-link (descobre seu redirect e se insere no meio):
+
+  ttm link claude-code [--label PROJ-123]
+  # depois reinicie o Claude Code (ele relê ANTHROPIC_BASE_URL no boot)
+
+  O que ele faz: lê sua base URL atual (env ANTHROPIC_BASE_URL,
+  ~/.claude/settings.json ou <repo>/.claude/settings.json), vira upstream
+  dela, e reescreve a config do Claude Code pra apontar pro ttm.
+  - Se você JÁ redireciona pra um compatível-anthropic (z.ai/GLM/...), o
+    ttm PRESERVA o redirect — continua batendo lá, com contagem de tokens.
+  - Se não tem redirect, o ttm usa o vendor real (api.anthropic.com).
+  - --repo escreve em <repo>/.claude/settings.json (útil p/ multi-ticket).
+  - --label seta o label padrão (atribuição de tarefa).
+  Para desfazer:  ttm unlink claude-code
+
+  Manual (sem auto-link): setar ANTHROPIC_BASE_URL=${P}/anthropic
+  (ou ${P}/anthropic/PROJ-123 p/ ticket embutido). Apontar pra host !=
+  api.anthropic.com desativa o Remote Control do Claude Code (v2.1.196+).
+  Auth continua passando intacta.`,
+
+    codex: `Codex (OpenAI) — caminho primário: auto-link:
+
+  ttm link codex [--label TICKET]
+  # reinicie o Codex depois
+
+  Lê ~/.codex/config.toml (model_providers.<ativo>.base_url), vira upstream,
+  reescreve o base_url pra apontar pro ttm. Preserva redirect prévio.
+
+  Manual: ~/.codex/config.toml:
+    model_provider = "ttm"
+    [model_providers.ttm]
+    name = "OpenAI via ttm"
+    base_url = "${P}/openai/v1"
+    wire_api = "responses"
+    env_key = "OPENAI_API_KEY"
+  (com ticket: base_url = "${P}/openai/PROJ-123/v1")
+  Prefira model_providers a openai_base_url/OPENAI_BASE_URL — há releases do
+  Codex com bug que ignora essas formas (issue #16719).`,
+
+    opencode: `OpenCode (sst) — caminho primário: auto-link:
+
+  ttm link opencode [--label TICKET]
+  # reinicie o OpenCode depois
+
+  Lê opencode.json (projeto) ou ~/.config/opencode/opencode.json, acha o
+  provider com baseURL, vira upstream e reescreve. Preserva redirect prévio.
+
+  Manual: opencode.json (projeto ou global):
+    {
+      "provider": {
+        "anthropic": { "options": { "baseURL": "${P}/anthropic" } },
+        "openai":    { "options": { "baseURL": "${P}/openai/v1" } }
+      }
+    }
+  (com ticket: "baseURL": "${P}/anthropic/PROJ-123")`,
+
+    'gemini-cli': `Gemini CLI (Google) — caminho primário: auto-link:
+
+  ttm link gemini-cli
+  # depois: export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:${cfg.port}/gemini
+  # (gemini-cli é só-env: o ttm imprime o export; rode no shell e reinicie)
+
+  Lê GOOGLE_GEMINI_BASE_URL (se setada), vira upstream, e instrui o export.
+  Preserva redirect prévio.
+
+  Manual: env vars (http:// permitido para 127.0.0.1):
+    export GEMINI_API_KEY=sua-chave
+    export GOOGLE_GEMINI_BASE_URL="${P}/gemini"
+  (com ticket: export GOOGLE_GEMINI_BASE_URL="${P}/gemini/PROJ-123")
+  Limitação: só o modo API key é rastreável. No login OAuth pessoal o Gemini
+  CLI usa o backend interno Code Assist, que essa variável não afeta.`,
+
+    kilo: `Kilo Code — kilo.jsonc (ou na extensão VS Code: Settings > Providers >
+  Custom Provider > Base URL, com Provider API = OpenAI Compatible):
+
+  {
+    "provider": {
+      "openai-compatible": {
+        "options": {
+          "apiKey": "{env:OPENAI_API_KEY}",
+          "baseURL": "${P}/openai/v1"
+        }
+      }
+    }
+  }`,
+
+    goose: `Goose (Block) — env vars (ou ~/.config/goose/config.yaml):
+
+  # provider OpenAI-compatible:
+  export OPENAI_HOST="${P}/openai"
+  # provider Anthropic:
+  export ANTHROPIC_HOST="${P}/anthropic"`,
+
+    crush: `Crush (Charm) — crush.json (ou ~/.config/crush/crush.json):
+
+  {
+    "providers": {
+      "ttm-anthropic": {
+        "type": "anthropic",
+        "base_url": "${P}/anthropic/v1",
+        "api_key": "$ANTHROPIC_API_KEY"
+      },
+      "ttm-openai": {
+        "type": "openai-compat",
+        "base_url": "${P}/openai/v1",
+        "api_key": "$OPENAI_API_KEY"
+      }
+    }
+  }`,
+
+    aider: `Aider — env var ou flag:
+
+  export OPENAI_API_BASE="${P}/openai/v1"
+  # ou: aider --openai-api-base ${P}/openai/v1
+  # ou em .aider.conf.yml:  openai-api-base: ${P}/openai/v1`,
+
+    cline: `Cline — só via interface (sem arquivo de config para isso):
+  Settings (engrenagem) > API Provider = "OpenAI Compatible"
+  > Base URL: ${P}/openai/v1`,
+
+    'roo-code': `Roo Code — só via interface:
+  Settings > Providers > API Provider = "OpenAI Compatible"
+  > Base URL: ${P}/openai/v1`,
+
+    droid: `Droid (Factory AI) — ~/.factory/settings.json:
+
+  {
+    "customModels": [{
+      "model": "claude-opus-4-8",
+      "provider": "anthropic",
+      "baseUrl": "${P}/anthropic",
+      "apiKey": "\${ANTHROPIC_API_KEY}"
+    }]
+  }`,
+
+    'copilot-cli': `GitHub Copilot CLI — modo BYOK via env vars:
+
+  export COPILOT_PROVIDER_BASE_URL="${P}/openai/v1"
+  export COPILOT_PROVIDER_TYPE=openai
+  export COPILOT_MODEL=gpt-5.5
+  export COPILOT_PROVIDER_API_KEY=sua-chave
+
+  Obs: o modo padrão (backend proprietário do Copilot) não é rastreável.`,
+
+    amp: `Amp (Sourcegraph) — NÃO suportado: o Amp roteia modelos pelo backend
+  proprietário (ampcode.com) e não documenta como redirecionar as chamadas
+  de modelo. HTTP_PROXY existe mas é só transporte, não muda o destino.`,
+
+    cursor: `Cursor CLI — NÃO suportado oficialmente: o cursor-agent fala com o
+  backend proprietário da Cursor e não há override de base URL documentado
+  para o CLI (o campo BYOK da IDE não se aplica ao agente headless).`,
+
+    kiro: `Kiro CLI (AWS) — NÃO suportado: não há mecanismo documentado de
+  override de base URL ou proxy para o backend de modelos.`,
+  }
+
+  const aliases = {
+    claude: 'claude-code',
+    claudecode: 'claude-code',
+    gemini: 'gemini-cli',
+    'kilo-code': 'kilo',
+    kilocode: 'kilo',
+    roo: 'roo-code',
+    roocode: 'roo-code',
+    copilot: 'copilot-cli',
+    factory: 'droid',
+  }
+
+  const key = aliases[tui] ?? tui
+  if (!key || !snippets[key]) {
+    return (
+      `TUIs suportados: ${Object.keys(snippets).join(', ')}\n\n` +
+      `Uso: ttm setup <tui>\n` +
+      `Padrão geral: aponte a base URL da ferramenta para ${P}/{target}[/{TICKET-123}]\n` +
+      `targets: ${Object.keys(cfg.targets).join(', ')}`
+    )
+  }
+  return snippets[key]
+}
+
+export const SUPPORTED_TUIS = [
+  'claude-code',
+  'codex',
+  'opencode',
+  'gemini-cli',
+  'kilo',
+  'goose',
+  'crush',
+  'aider',
+  'cline',
+  'roo-code',
+  'droid',
+  'copilot-cli',
+]

package/lib/traces-data.mjs

@@ -0,0 +1,155 @@
+import { listUsageEvents } from './db.mjs'
+
+// Sessionização agnóstica ao harness: o proxy não vê "sessão" no protocolo,
+// então agrupa por (cliente, label) com corte por inatividade — mesma técnica
+// de sessionização de analytics. Heurística honesta: duas janelas do MESMO
+// TUI na MESMA tarefa ao mesmo tempo viram uma sessão só (documentado).
+const DEFAULT_GAP_MIN = 30
+
+const clientShortOf = c => (c || '(desconhecido)').split('/')[0].split(' ')[0]
+
+function sinceToIso(since) {
+  if (!since || since === 'all') return null
+  if (/^\d{4}-\d{2}-\d{2}/.test(since)) return since
+  const m = /^(\d+)([dh])$/.exec(since)
+  if (!m) return null
+  const ms = m[2] === 'd' ? 86400000 : 3600000
+  return new Date(Date.now() - parseInt(m[1], 10) * ms).toISOString()
+}
+
+function shapeCall(r) {
+  let rates = null
+  try {
+    rates = r.rates ? JSON.parse(r.rates) : null
+  } catch {
+    /* evento antigo */
+  }
+  return {
+    id: r.id,
+    ts: r.ts,
+    label: r.label,
+    target: r.target,
+    model: r.model,
+    providerId: r.provider_id ?? null,
+    input: r.input_tokens || 0,
+    cacheCreate: r.cache_create_tokens || 0,
+    cacheCreate1h: r.cache_create_1h_tokens || 0,
+    cacheRead: r.cache_read_tokens || 0,
+    output: r.output_tokens || 0,
+    reasoning: r.reasoning_tokens || 0,
+    cost: r.cost_usd,
+    rates,
+    durationMs: r.duration_ms,
+    client: r.client,
+    status: r.status,
+    repo: r.repo ?? null,
+    branch: r.branch ?? null,
+    payload: Boolean(r.payload),
+  }
+}
+
+export async function buildTraces({
+  since = '7d',
+  label = null,
+  target = null,
+  model = null,
+  client = null,
+  gapMin = DEFAULT_GAP_MIN,
+  maxSessions = 200,
+} = {}) {
+  let rows = await listUsageEvents({ since: sinceToIso(since), label: label ? label.toUpperCase() : label })
+  if (target) rows = rows.filter(r => r.target === target)
+  if (model) rows = rows.filter(r => r.model === model)
+  // casa exatamente com o MESMO valor exibido no filtro (clientShort),
+  // inclusive '(desconhecido)' para cliente nulo
+  if (client) rows = rows.filter(r => clientShortOf(r.client) === client)
+
+  // opções de filtro (sobre o conjunto já recortado por período/label)
+  const opt = key => [...new Set(rows.map(r => r[key]).filter(Boolean))].sort()
+  const clientShort = clientShortOf
+  const filterOptions = {
+    targets: opt('target'),
+    models: opt('model'),
+    clients: [...new Set(rows.map(r => clientShort(r.client)))].sort(),
+  }
+
+  // sessioniza: ordena por (cliente, label, ts) e corta por gap de inatividade
+  const sorted = rows
+    .slice()
+    .sort((a, b) =>
+      (a.client || '').localeCompare(b.client || '') ||
+      (a.label || '').localeCompare(b.label || '') ||
+      a.ts.localeCompare(b.ts),
+    )
+  const gapMs = gapMin * 60000
+  const sessions = []
+  let cur = null
+  for (const r of sorted) {
+    const sameGroup =
+      cur &&
+      (cur.clientFull || '') === (r.client || '') &&
+      (cur.label || '') === (r.label || '') &&
+      Date.parse(r.ts) - Date.parse(cur.end) <= gapMs
+    if (!sameGroup) {
+      cur = {
+        label: r.label,
+        client: clientShort(r.client),
+        clientFull: r.client,
+        start: r.ts,
+        end: r.ts,
+        calls: [],
+        tokensIn: 0,
+        tokensOut: 0,
+        cost: 0,
+        costKnown: true,
+        targets: new Set(),
+        models: new Set(),
+        repo: null,
+        branch: null,
+      }
+      sessions.push(cur)
+    }
+    cur.end = r.ts
+    cur.calls.push(shapeCall(r))
+    cur.tokensIn += (r.input_tokens || 0) + (r.cache_create_tokens || 0) + (r.cache_read_tokens || 0)
+    cur.tokensOut += r.output_tokens || 0
+    cur.cost += r.cost_usd || 0
+    if (r.cost_usd === null || r.cost_usd === undefined) cur.costKnown = false
+    if (r.target) cur.targets.add(r.target)
+    if (r.model) cur.models.add(r.model)
+    if (r.repo && !cur.repo) cur.repo = r.repo
+    if (r.branch && !cur.branch) cur.branch = r.branch
+  }
+
+  sessions.sort((a, b) => b.end.localeCompare(a.end))
+  const truncated = sessions.length > maxSessions
+  return {
+    generatedAt: new Date().toISOString(),
+    since,
+    filters: { label, target, model, client },
+    filterOptions,
+    gapMin,
+    sessionCount: sessions.length,
+    callCount: rows.length,
+    callsShown: sessions.slice(0, maxSessions).reduce((n, s) => n + s.calls.length, 0),
+    truncated,
+    sessions: sessions.slice(0, maxSessions).map((s, i) => ({
+      id: `s${i + 1}`,
+      label: s.label,
+      client: s.client,
+      clientFull: s.clientFull,
+      start: s.start,
+      end: s.end,
+      durationMs: Date.parse(s.end) - Date.parse(s.start),
+      targets: [...s.targets],
+      models: [...s.models],
+      repo: s.repo,
+      branch: s.branch,
+      tokensIn: s.tokensIn,
+      tokensOut: s.tokensOut,
+      cost: s.cost,
+      costKnown: s.costKnown,
+      calls: s.calls,
+    })),
+  }
+}