feat: Cost & Usage Report should cover all Local CLI and API code agents

[moose-lab]

背景

Issue #49 修复的是 Cost & Usage 页面在大历史量下卡死的问题。后续 PR #56 给 Codex session cost scan 加了 (path, mtimeMs, size) 增量缓存，PR #57 进一步把当前 Cost Report 覆盖范围显式化：

• 已支持：Claude Code、Codex
• 未支持但已被 DevLog 作为 code agent/runtime 暴露：其它 Local CLI agents 和 API 接入 agents

现在需要把产品能力从“明确声明未支持”推进到“真正支持所有 code agents 的 Cost/Usage Report”。

目标

DevLog 的 Cost & Usage Report 应覆盖所有 code agents，无论它们通过哪种方式接入：

1. Local CLI agents
2. API/BYOK 接入 agents
3. 后续新增的 code agent/runtime

每个 agent 的 cost/usage 都应能进入统一报表，并且不能重现 #49 的大历史量同步全量扫描卡死问题。

当前已知范围

Local CLI agents

DevLog 当前 local CLI registry 包括：

• Claude Code (claude)
• Codex CLI (codex)
• Gemini CLI (gemini)
• Cursor Agent (cursor-agent)
• GitHub Copilot CLI (copilot)
• Kimi CLI (kimi)
• Qwen Code (qwen)
• Hermes (hermes)
• Pi (pi)
• OpenCode (opencode)

API/BYOK 接入

DevLog 当前 API protocol surface 包括：

• Anthropic API
• OpenAI-compatible API
• Azure OpenAI
• Google Gemini
• Ollama Cloud API
• SenseAudio / other supported provider protocol entries where present

需求

1. 统一 Cost/Usage 数据模型

为所有 code agents 定义统一的 usage record schema，至少包含：

• agent/runtime id
• provider/protocol
• model
• project/session/task attribution
• timestamp
• input tokens
• cached input tokens where available
• output tokens
• reasoning/output details where available
• request count / usage event count
• estimated API cost USD where pricing is known
• subscription/credit usage where applicable
• source and confidence metadata, because some agents may not expose full token/cost data

2. Local CLI agent 数据采集

每个 Local CLI agent 都需要明确一种可复用的数据来源策略：

• 读取 agent 自身 durable history / log / transcript / usage file；或
• 从 DevLog 启动和 stream 管道中捕获 usage event 并持久化；或
• 明确标记该 agent 当前无法提供 token/cost，展示为 partial/unknown，而不是静默缺失。

不能在 Cost Usage 页面请求时同步全量重扫大历史目录。

3. API/BYOK agent 数据采集

DevLog 直连 API runtime 应在每次 provider response 返回时记录 usage：

• Anthropic usage
• OpenAI-compatible usage
• Azure OpenAI usage
• Google Gemini usage
• Ollama / other protocol usage where available

对于不返回 token usage 的 provider，应记录 request/session attribution，并在报表中清晰展示 unknown/partial，而不是计算假数据。

4. 性能约束

必须避免 #49 复发：

• 不允许每次 /api/devlog?command=cost 对所有 agent 历史做同步全量扫描。
• 每个历史文件读取路径都必须有 (path, mtimeMs, size) 或等价 fingerprint 缓存。
• 对大目录扫描必须 bounded concurrency。
• API/runtime 新产生的 usage 应优先写入 DevLog 自己的持久层或增量 cache。
• refresh=1 可以绕过 response cache，但不能无条件丢弃每个未变化历史文件的 parse cache。

5. UI/CLI 呈现

Cost & Usage Dashboard 和 devlog cost 应展示：

• by provider/protocol
• by agent runtime
• by model
• by project
• by period: today/week/month/all time
• known cost vs unknown/partial usage
• clear source/caveat when an agent does not expose cost/token data

6. Guardrails

PR #57 已新增 COST_REPORT_AGENT_COVERAGE guardrail。完成本 issue 时应把它从“unsupported reason”推进为真实支持策略：

• 新增 Local CLI agent 时，如果没有 cost/usage coverage，应有测试失败。
• 新增 API protocol 时，如果没有 usage extraction strategy，应有测试失败。
• 新增 CostProvider 时，如果没有 cache/performance strategy，应有测试失败。

验收标准

• 所有 Local CLI agents 都在 Cost/Usage Report 中有明确状态：supported、partial、or unsupported-with-visible-reason。
• 所有 API/BYOK protocol responses 都尽可能提取 usage 并进入 report。
• Cost Usage 页面不会因为大历史量重新出现 30s+ 骨架屏卡死。
• devlog cost --json 输出包含 agent/protocol/model attribution。
• 有回归测试覆盖：
  • Local CLI coverage completeness
  • API protocol coverage completeness
  • no repeated full-history rescan on second report build
  • changed/deleted historical usage source invalidates cache correctly
  • unknown/partial usage is shown honestly
• 通过 bun run typecheck、TZ=Asia/Shanghai bun run test、CI、CodeQL。

非目标

• 不要求为没有公开 token/cost 数据的 agent 编造价格或 token 数。
• 不要求一次 PR 完成所有 provider 的精确价格表；可以先建立 schema、capture path、partial display，再逐步补价格。
• 不应为了覆盖所有 agents 而引入 UI-time 大扫描。

相关

• perf: Cost & Usage 页在大量历史会话下会卡死 — 成本报表扫描未走增量缓存 #49: Cost & Usage 大历史量卡死根因
• perf: cache Codex cost session scans #56: Codex cost session scan cache
• test: guard cost report agent coverage #57: Cost Report agent coverage guardrail