feat(analytics): make the Cursor usage CSV a first-class cost source

.ai-run/guides/integration/external-integrations.md

@@ -300,6 +300,37 @@ Catalog-agnostic thin wrapper around the upstream `skills` npm CLI. Discovery, r
 
 ---
 
+## Cursor Integration (analytics-only)
+
+Cursor is read, never managed: `analyticsOnly: true`, no npm package, no CLI command, no provider
+mapping. `codemie analytics` discovers Cursor Agent conversations from Cursor's local stores —
+`state.vscdb` (`composerHeaders` for discovery, `cursorDiskKV` for per-turn enrichment),
+`~/.cursor/projects/<slug>/agent-transcripts/`, and `~/.cursor/ai-tracking/ai-code-tracking.db` —
+all read-only and all fail-soft. `CURSOR_HOME` relocates every one of them. Cursor sessions are
+tagged `native-external` and appear only with `--include-external`.
+
+**Recent Cursor builds write zero `tokenCount` on bubbles, or omit it, while `toolFormerData` still
+works** — so tool-call enrichment is reliable and token/cost enrichment is usually empty. The
+supported way to recover real Cursor tokens and cost is the **dashboard usage export**
+(`--cursor-usage-csv <path>`, `src/agents/plugins/cursor/cursor.usage-csv.ts`) — a local file read
+with no credential. `cursor-usage-loader.ts` converts it into `RawSessionData` + a canonical
+`SessionCostIndex` — the OTEL-loader pattern — matching each event to the session whose activity
+window contains it and rolling the rest up per day, so its tokens and cost reach every report
+figure once. Those rows carry `costBasis: 'vendor-billed'` (Cursor's own billing, not a CodeMie
+estimate). `Kind=Included` in that CSV is a billing category, not zero usage: verified
+export rows marked `Included` carried 39,952,466 tokens and $25.25. Team Analytics is **not** the
+answer here and never was. Such
+sessions carry `usageUnavailableReason` and render as an em dash, never as `$0`, `Included`, or
+"covered by subscription". Do not widen the default discovery max-age to harvest year-old bubbles
+that still have tokens, and do not infer tokens from `contextTokensUsed`, transcript length, or
+tool-call counts. When tokens *are* recovered under an unpriceable model (`default`/Auto), the cost
+enricher estimates at a published Claude Sonnet rate, preserves the original model label, and marks
+the session `usagePartial`.
+
+Full operational and developer guide: `docs/CURSOR_INTEGRATION.md`. `state.vscdb` is
+undocumented VS Code/Cursor application state; `composerHeaders` is primary session discovery
+and all reads are fail-soft.
+
 ## Configuration Validation
 
 Validate provider config at startup; warn (not throw) on connectivity failures. `file:src/env/config-loader.ts:150-170`
@@ -322,6 +353,7 @@ Validate provider config at startup; warn (not throw) on connectivity failures.
 | LiteLLM connection error | Proxy not running | `litellm --port 4000` |
 | OpenCode not found | Not installed | `codemie install opencode` |
 | OpenCode sessions not syncing | Metrics processing failed | `codemie opencode-metrics --discover --verbose` |
+| No Cursor sessions in analytics | Cursor sessions are external | Re-run with `--include-external`; see `docs/CURSOR_INTEGRATION.md` |
 | Codex sessions stuck `status: active` | Hard kill skipped `onSessionEnd` | Auto-reconciled on next codex run via `codex.reconciliation.ts` |
 | Codex `money_spent` is 0 | Backend `cost_config` missing model entry | Add model pricing in backend `cost_config` |
 
@@ -334,6 +366,7 @@ Validate provider config at startup; warn (not throw) on connectivity failures.
 - OpenCode plugin: `src/agents/plugins/opencode/`
 - Codex plugin: `src/agents/plugins/codex/`
 - Claude plugin: `src/agents/plugins/claude/`
+- Cursor plugin: `src/agents/plugins/cursor/` (guide: `docs/CURSOR_INTEGRATION.md`)
 - MCP proxy: `src/mcp/`
 - Session adapters: `src/agents/core/session/`
 - Config loader: `src/env/config-loader.ts`

.gitignore

@@ -89,3 +89,5 @@ docs/superpowers/tasks/*/code-review*.diff
 /docs/superpowers/resume/
 /docs/superpowers/review-prompts/
 /docs/codemie/analytics/
+
+.scratch/

AGENTS.md

@@ -128,7 +128,7 @@ Ask the user when:
 | Keywords | P0 Guide | P1 Guide |
 |---|---|---|
 | `plugin`, `registry`, `agent`, `adapter` | architecture | external-integrations |
-| `claude`, `codex`, `gemini`, `opencode`, `pi`, `kimi`, `copilot`, `acp` | architecture | external-integrations |
+| `claude`, `codex`, `gemini`, `opencode`, `pi`, `kimi`, `copilot`, `cursor`, `acp` | architecture | external-integrations |
 | `session`, `metrics`, `analytics`, `transcript`, `sync` | architecture | external-integrations |
 | `architecture`, `layer`, `structure`, `pattern` | architecture | development-practices |
 | `test`, `vitest`, `mock`, `coverage` | testing-patterns | development-practices |
@@ -222,7 +222,8 @@ See `package.json` for exact dependency versions and `.ai-run/guides/architectur
 | `pi` | `pi/` | `@earendil-works/pi-coding-agent` | Redirects `PI_CODING_AGENT_DIR` to `<cwd>/.pi/codemie/agent`; metrics via injected extension + run ledger |
 | `kimi` / `kimi-acp` | `kimi/` | `@moonshot-ai/kimi-code` | ACP variant prepends `acp` to argv |
 | `openwiki` | `openwiki/` | `openwiki` | Docs/wiki tool, not a chat agent; declarative-only adapter — `envMapping` feeds the profile's base URL/key/model to `OPENAI_COMPATIBLE_*`/`OPENWIKI_MODEL_ID`, SSO/JWT goes through the local proxy |
-| `copilot-cli` | `copilot-cli/` | none | Analytics ingestion only — never installed or launched by CodeMie |
+| `copilot-cli` | `copilot-cli/` | `@github/copilot` | Managed agent (installed, configured, and launched by CodeMie); session metrics + backend conversation sync via its own processors |
+| `cursor` | `cursor/` | none | Analytics-only agent (`analyticsOnly: true`) — never installed or launched by CodeMie; reads Cursor's locally persisted agent transcripts, enriched read-only from Cursor's AI-tracking database, and surfaces them as external sessions (opt-in behind `--include-external`, like any session CodeMie did not launch). See `docs/CURSOR_INTEGRATION.md` |
 
 Not agent adapters, but injected runtime plugins under the same tree: `codemie-code-hooks/` (injected into `codemie-code` and `opencode`) and `reasoning-sanitizer/` (injected into `codemie-code`).