Support Kiro CLI usage — investigation and options

[Greek-Cp]

Summary

Request: add Kiro CLI as a usage source in Burnly.

I did a deep investigation to scope this and hit a fundamental blocker worth
deciding on before any code: Kiro does not expose authoritative local token
usage. Kiro meters in credits (server-side), not tokens, so a faithful
token collector — the way Burnly models usage today — is not currently possible.
Filing this so maintainers can pick a direction.

Findings (evidence)

1. The bundled ccusage collector has no Kiro reader.
ccusage 20.0.14 exposes: claude, codex, opencode, amp, droid,
codebuff, hermes, pi, goose, kilo, copilot, gemini, kimi,
qwen, openclaw. There is no kiro command. (Note: kilo = Kilo Code, a
different tool — not Kiro.) So the existing sidecar path can't help.

2. Kiro stores no token usage locally.
On a machine with Kiro CLI installed:

• ~/.kiro/sessions/cli/*.jsonl records model / modelId per turn but has
  zero token/usage/cost fields (checked recursively across all key paths).
• ~/Library/Application Support/kiro-cli/data.sqlite3: the conversations,
  conversations_v2, and history tables were empty; state only holds auth +
  telemetry keys (e.g. api.codewhisperer.profile). Kiro CLI is built on the
  Amazon Q / CodeWhisperer backend, and usage is accounted server-side.

3. Kiro bills in credits, not tokens.
Official pricing is credit-based — Spec requests ($0.20) and Vibe requests
($0.04) — explicitly not token-based.
https://kiro.dev/blog/understanding-kiro-pricing-specs-vibes-usage-tracking/

4. Third-party token trackers only estimate.
kiro-usage (the main community tool) reports tokens, but its own docs state
the numbers are estimated: CacheWrite = "new tokens sent this turn (estimated,
chars ÷ 4)", CacheRead = "(estimated)", Output = captured by intercepting the
live response stream via a background archiver polling every 10s.
https://pypi.org/project/kiro-usage/

Why this conflicts with Burnly's current model

• Burnly is token + cost centric (the daily_usage model, ccusage
  envelopes). Kiro has no authoritative token data to map.
• Burnly's design avoids fabricated/estimated numbers (cf. the OpenCode
  per-model known limitation: estimating would be misleading). The only way to
  get Kiro "tokens" is estimation + live stream interception.
• Burnly runs collectors on-demand over stored data, not as a persistent
  background interceptor, so capturing Kiro's streamed output is out of the
  current architecture.

Options (maintainer decision)

1. Defer until Kiro exposes authoritative local token/credit data (or
   ccusage adds Kiro). Track as a documented known-limitation.
2. Activity collector — count requests / sessions / messages per day per
   model from the local JSONL (real data, no estimation), accepting that this is
   a different metric than tokens/cost and needs UI/model accommodation.
3. Estimated-token collector (kiro-usage style) — provides token-shaped
   numbers but conflicts with the no-fabrication principle and needs a
   background process for output capture.
4. Credits collector — track Kiro's real billing unit (credits / Spec+Vibe
   requests). Blocker: credits are server-side, not in local data, so this
   likely needs an API/login and breaks the local-first model.

Offer

Happy to implement whichever direction you pick, following the collector adapter
contract (docs/contracts/collector-adapter-contract-design.md). My read is
option 1 (defer + document) is the most honest today, with option 2 as a
possible "activity, not tokens" feature if you want Kiro visible sooner. Keen to
hear your preference before I open a PR.

[fikrilal]

thanks for the investigation. for kiro IDE, we're not implementing that for now. for kiro-cli, I did a separate local inspection on my machine that actively uses kiro-cli. there's a kiro-cli session metadata under ~/.local/share/kiro-cli/data.sqlite3, plus cli session metadata under ~/.kiro/sessions/cli/. the local token counter are still not authoritative, but the cli data is sufficient for an experimental estimated collector.

I wrote the engineering proposal here: /docs/planning/_WIP/kiro-collector-engineering-proposal.md. if you're interested in implementing this, the proposal can be used as the contract. otherwise, I'll pick it up in small chunks later.