[1123] feature: local-usage-stats (1/4)

[myk1yt]

Stack Position

• Feature Branch: feature/local-usage-stats
• Stage: 1/4
• Depends on: None

Description

https://www.youtube.com/shorts/UHnnOCM1_f0

Full Feature Description

• Feature Branch: feature/local-usage-stats
• Feature Name: Local Usage Statistics
• Purpose: Resolves the problem where users cannot locally view token usage, cache effects, cost, and period-based trends by provider, and where differing usage formats across providers make consistent aggregation difficult. Provides a privacy-preserving dashboard that collects only numeric usage and non-secret identifiers locally, without collecting prompts, responses, or credentials.
• Full Change Description: B13 adds data-minimized event/query contracts and an append-only NDJSON event store. B14 adds aggregation by date, provider, model, and mode, cache ratio, and provider-aware cost recalculation. B15 records final usage exactly once from the API attempt completion path, including success/error/cancel/retry. B16 adds transactional SQLite projection, idempotent migration, local-day rollup, query/stream IPC, stale epoch prevention, and dashboard summary/session/heatmap UI.
• Impact Scope: Affects usage-stats.ts, src/services/stats, the provider/task capture paths Task.ts, the stats IPC usageStatsMessageHandler.ts, and the UI DashboardView.tsx and useDashboardStatsStream.ts.
• Errors and Edge Cases: Raw events are append-only and derived rollups must be reconstructable. Duplicate idempotency keys are not re-recorded. Corrupt tails preserve the valid prefix and leave only a hash in the quarantine report instead of the original text. Migrations must be transactional/idempotent. Local day and DST boundaries are calculated per-timestamp by offset. Previous subscription epochs must not overwrite new range results. The store must not contain prompts, responses, API keys, endpoint credentials, or workspace paths.
• Testing Method: Run contract/store, aggregation/cost, exactly-once capture, database/migration/projection/stream, IPC, dashboard reducer/component, performance, locale, and visual tests step by step. Manually create complete/cancel/retry attempts, verify event counts, then rapidly switch ranges in two dashboard windows and add events, verifying convergence without stale loading or duplicate totals. Inspect stored files to confirm no sensitive fields are present.

Why Split Into 17 PRs

Instead of submitting this feature as a single unified PR, it was split into individual PRs because as code size grows, safely reviewing a PR becomes very difficult. The feature was broken into mutually exclusive individual PRs so that each can be reviewed independently.

What This PR Specifically Changes

Adds minimal-field usage event/query contracts, append-only segmented NDJSON store, lock/queue, idempotency, rotation/hard cap, and corrupt-line quarantine. Does not include aggregation, capture, or UI.

Included Files

• packages/types/src/usage-stats.ts
• src/services/stats/UsageEventStore.ts
• src/services/stats/index.ts
• packages/types/src/__tests__/usage-stats.spec.ts
• src/services/stats/__tests__/UsageEventStore.spec.ts

Exclusion Scope

• Aggregation/service calculation
• Task/provider live capture
• Database projection/migration/IPC/dashboard
• Prompt, response, API key, endpoint credential fields
• All items in the common removal rules

Summary by CodeRabbit

• New Features

  • Added usage statistics tracking for task and API activity, including tokens, costs, status, providers, models, and modes.
  • Added statistics views with date ranges, timezone-aware daily/weekly/monthly grouping, filters, and multi-axis breakdowns.
  • Added JSON and CSV export capabilities.
  • Added controls to clear recorded statistics and report storage-capacity status.
  • Added cancellation filtering and coverage metadata for more transparent reporting.

• Tests

  • Added comprehensive validation and coverage for tracking, aggregation, storage, querying, exporting, and clearing statistics.

---

Upstream PR: Zoo-Code-Org#1123