From 78e210fecaa6e838000706e563d65180ba15613f Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:48 +0300 Subject: [PATCH 01/34] feat(analytics): add Cursor glossary and read-only Cursor data readers Base scaffolding for the Cursor analytics-only agent (spec #1): CONTEXT.md glossary plus the Cursor path helper, transcript reader and read-only AI-tracking database reader. Refs #1 --- CONTEXT.md | 24 +++ src/agents/plugins/cursor/cursor.constants.ts | 19 +++ src/agents/plugins/cursor/cursor.paths.ts | 29 ++++ .../plugins/cursor/cursor.tracking-db.ts | 159 ++++++++++++++++++ .../plugins/cursor/cursor.transcript.ts | 108 ++++++++++++ 5 files changed, 339 insertions(+) create mode 100644 CONTEXT.md create mode 100644 src/agents/plugins/cursor/cursor.constants.ts create mode 100644 src/agents/plugins/cursor/cursor.paths.ts create mode 100644 src/agents/plugins/cursor/cursor.tracking-db.ts create mode 100644 src/agents/plugins/cursor/cursor.transcript.ts diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 000000000..e4ddb8ede --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,24 @@ +# CodeMie Code Analytics + +Terminology for how CodeMie Code classifies agent sessions in analytics. CodeMie both launches agents itself and reads usage left behind by agents it never launched; the vocabulary below keeps those apart. + +## Language + +**Managed agent**: +An agent CodeMie installs, configures, and launches (e.g. claude, codex, gemini, copilot-cli). +_Avoid_: installed agent, native agent + +**Analytics-only agent**: +An agent CodeMie never installs or launches but whose locally persisted sessions it reads for analytics (`analyticsOnly: true` in plugin metadata; e.g. cursor). +_Avoid_: external agent, ingestion-only agent + +**External session**: +A session of a *managed* agent that was run outside CodeMie and carries no CodeMie ownership marker (provider tag `native-external`). Hidden by default; shown with `--include-external`. +_Avoid_: unmanaged session, foreign session + +**Unmanaged session**: +A session of an *analytics-only* agent (provider tag `native-unmanaged`). Always shown; no flag required. +_Avoid_: external session + +**Ownership marker**: +The sidecar record in `~/.codemie/sessions/` that proves CodeMie launched a given agent session; its absence is what makes a managed agent's session external. diff --git a/src/agents/plugins/cursor/cursor.constants.ts b/src/agents/plugins/cursor/cursor.constants.ts new file mode 100644 index 000000000..73604f621 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.constants.ts @@ -0,0 +1,19 @@ +/** + * Shared Cursor identifiers. + * + * These live apart from `cursor.plugin.ts` so the session adapter can use them without + * importing the plugin, which imports the adapter — a cycle. + */ + +/** Internal agent key. */ +export const CURSOR_AGENT_NAME = 'cursor'; + +/** User-facing label shown in the analytics report and terminal output. */ +export const CURSOR_DISPLAY_NAME = 'Cursor'; + +/** + * Cursor records a model of `default` when the user left model selection to Cursor. That + * string names no model, so it is dropped rather than reported — see the honest-gaps note + * in `cursor.session.ts`. + */ +export const CURSOR_UNKNOWN_MODEL = 'default'; diff --git a/src/agents/plugins/cursor/cursor.paths.ts b/src/agents/plugins/cursor/cursor.paths.ts new file mode 100644 index 000000000..d61ec5827 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.paths.ts @@ -0,0 +1,29 @@ +/** + * Cursor storage locations. + * + * Cursor keeps its user data under `~/.cursor`. `CURSOR_HOME` overrides it, mirroring the + * `COPILOT_HOME` handling in `copilot-cli.paths.ts` — which is also what lets the adapter + * be driven against a fixture tree in tests. + */ + +import { join } from 'path'; +import { resolveHomeDir } from '../../../utils/paths.js'; + +/** `~/.cursor`, or `$CURSOR_HOME` when set. */ +export function getCursorHome(): string { + const override = process.env.CURSOR_HOME?.trim(); + if (override) { + return override; + } + return resolveHomeDir('.cursor'); +} + +/** Directory holding one subdirectory per project, each keyed by a slug of its path. */ +export function getCursorProjectsRoot(): string { + return join(getCursorHome(), 'projects'); +} + +/** Cursor's AI-tracking SQLite database — the only local source of model and timing data. */ +export function getCursorTrackingDbPath(): string { + return join(getCursorHome(), 'ai-tracking', 'ai-code-tracking.db'); +} diff --git a/src/agents/plugins/cursor/cursor.tracking-db.ts b/src/agents/plugins/cursor/cursor.tracking-db.ts new file mode 100644 index 000000000..dedfec2dc --- /dev/null +++ b/src/agents/plugins/cursor/cursor.tracking-db.ts @@ -0,0 +1,159 @@ +/** + * Read-only enrichment from Cursor's AI-tracking database. + * + * A Cursor agent transcript records role-tagged text and turn markers and NOTHING else — no + * timestamps, no model, no token counts. `~/.cursor/ai-tracking/ai-code-tracking.db` is the + * only local store that carries the missing facts, and it joins to a transcript on the + * conversation id (which is the transcript's own file/directory name). + * + * Everything here is fail-soft by mandate. The schema is undocumented and Cursor may change + * it in any release, so an absent file, an absent `node:sqlite` (Node < 22.5), a renamed + * table or a renamed column all degrade to "no enrichment" — the transcripts still produce + * session rows, just without model, files or an activity window. A Cursor update must never + * break `codemie analytics`. + * + * Reads are strictly read-only: the database is opened with `readOnly` and only SELECTed. + */ + +import { existsSync } from 'fs'; +import { logger } from '../../../utils/logger.js'; +import { CURSOR_UNKNOWN_MODEL } from './cursor.constants.js'; +import { getCursorTrackingDbPath } from './cursor.paths.js'; + +/** What the tracking database knows about one conversation. */ +export interface CursorConversationActivity { + /** Epoch ms of the first recorded edit, when any. */ + firstEditMs?: number; + /** Epoch ms of the last recorded edit, when any. */ + lastEditMs?: number; + /** Absolute paths Cursor recorded itself as having written in this conversation. */ + files: string[]; + /** + * Models Cursor attributed edits to. Never contains the literal `default`, which names no + * model — a session whose only recorded model was `default` is reported as unknown rather + * than being stamped with whatever model Cursor happens to default to today. + */ + models: string[]; +} + +/** Conversation id → enrichment. An empty map means "no enrichment available". */ +export type CursorTrackingIndex = Map; + +/** + * Only `composer` rows are agent-written. `human` rows are the user's own edits that Cursor + * tracked for its AI-percentage stats, and counting them would attribute human work to the + * agent. + */ +const ACTIVITY_QUERY = ` + SELECT conversationId AS id, + fileName AS file, + model AS model, + MIN(timestamp) AS firstMs, + MAX(timestamp) AS lastMs + FROM ai_code_hashes + WHERE source = 'composer' + AND conversationId IS NOT NULL + GROUP BY conversationId, fileName, model +`; + +interface ActivityRow { + id?: unknown; + file?: unknown; + model?: unknown; + firstMs?: unknown; + lastMs?: unknown; +} + +function asString(value: unknown): string | undefined { + return typeof value === 'string' && value.trim() ? value : undefined; +} + +function asEpochMs(value: unknown): number | undefined { + return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined; +} + +/** + * `node:sqlite`, or null where it does not exist. + * + * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot + * be a static import: on Node 20 it would throw at module load and take the whole analytics + * run down. Cursor enrichment is optional, so an older runtime simply gets transcript-only + * rows. + */ +async function loadSqlite(): Promise { + try { + return await import('node:sqlite'); + } catch (error) { + logger.debug('[cursor] node:sqlite unavailable — skipping tracking enrichment:', error); + return null; + } +} + +/** + * Build the conversation → activity index, or an empty map when the database cannot be read. + * + * Never throws. + */ +export async function readCursorTrackingIndex( + dbPath: string = getCursorTrackingDbPath() +): Promise { + const index: CursorTrackingIndex = new Map(); + + if (!existsSync(dbPath)) { + logger.debug(`[cursor] no ai-tracking database at ${dbPath}`); + return index; + } + + const sqlite = await loadSqlite(); + if (!sqlite) { + return index; + } + + let db: InstanceType | undefined; + try { + db = new sqlite.DatabaseSync(dbPath, { readOnly: true }); + const rows = db.prepare(ACTIVITY_QUERY).all() as ActivityRow[]; + + for (const row of rows) { + const id = asString(row.id); + if (!id) { + continue; + } + const entry = index.get(id) ?? { files: [], models: [] }; + + const file = asString(row.file); + if (file && !entry.files.includes(file)) { + entry.files.push(file); + } + + const model = asString(row.model); + if (model && model !== CURSOR_UNKNOWN_MODEL && !entry.models.includes(model)) { + entry.models.push(model); + } + + const firstMs = asEpochMs(row.firstMs); + if (firstMs !== undefined && (entry.firstEditMs === undefined || firstMs < entry.firstEditMs)) { + entry.firstEditMs = firstMs; + } + const lastMs = asEpochMs(row.lastMs); + if (lastMs !== undefined && (entry.lastEditMs === undefined || lastMs > entry.lastEditMs)) { + entry.lastEditMs = lastMs; + } + + index.set(id, entry); + } + } catch (error) { + // Missing table, renamed column, corrupt file, locked database — all the same to us. + logger.debug(`[cursor] ai-tracking database unusable at ${dbPath}:`, error); + return new Map(); + } finally { + try { + db?.close(); + } catch { + // closing a database we failed to open is not an error worth reporting + } + } + + logger.debug(`[cursor] tracking index covers ${index.size} conversation(s)`); + return index; +} diff --git a/src/agents/plugins/cursor/cursor.transcript.ts b/src/agents/plugins/cursor/cursor.transcript.ts new file mode 100644 index 000000000..de4377080 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.transcript.ts @@ -0,0 +1,108 @@ +/** + * Tolerant reader for a Cursor agent transcript (`.jsonl`). + * + * The format is thin and undocumented: each line is either a role-tagged message + * (`{role, message: {content: [...]}}`) or a turn marker (`{type: 'turn_ended', status}`). + * There are no timestamps, no model, no tokens and no tool results — everything else the + * report shows comes from `cursor.tracking-db.ts`. + * + * A live session's final line can be truncated mid-write, so unparseable lines are dropped + * rather than thrown: one bad line must not discard a whole session. + */ + +import { readFileSync } from 'fs'; +import { logger } from '../../../utils/logger.js'; + +/** A `tool_use` block inside an assistant message. */ +export interface CursorToolUseBlock { + type: 'tool_use'; + name?: string; + input?: Record; +} + +/** A plain text block inside a message. */ +export interface CursorTextBlock { + type: 'text'; + text?: string; +} + +export type CursorContentBlock = CursorToolUseBlock | CursorTextBlock | { type?: string }; + +/** A role-tagged transcript line. */ +export interface CursorMessageLine { + role: 'user' | 'assistant' | string; + message?: { content?: CursorContentBlock[] | string }; +} + +/** A control line, e.g. `{"type":"turn_ended","status":"success"}`. */ +export interface CursorMarkerLine { + type: string; + status?: string; +} + +export type CursorTranscriptLine = CursorMessageLine | CursorMarkerLine; + +export function isMessageLine(line: CursorTranscriptLine): line is CursorMessageLine { + return typeof (line as CursorMessageLine).role === 'string'; +} + +export function isMarkerLine(line: CursorTranscriptLine): line is CursorMarkerLine { + return !isMessageLine(line) && typeof (line as CursorMarkerLine).type === 'string'; +} + +/** The content blocks of a message, normalized to an array (a bare string becomes one text block). */ +export function contentBlocks(line: CursorMessageLine): CursorContentBlock[] { + const content = line.message?.content; + if (typeof content === 'string') { + return [{ type: 'text', text: content }]; + } + return Array.isArray(content) ? content : []; +} + +/** Read a transcript, dropping any line that is not parseable JSON. Never throws. */ +export function readCursorTranscript(filePath: string): CursorTranscriptLine[] { + let text: string; + try { + text = readFileSync(filePath, 'utf-8'); + } catch (error) { + logger.debug(`[cursor] unreadable transcript at ${filePath}:`, error); + return []; + } + + const lines: CursorTranscriptLine[] = []; + let dropped = 0; + + for (const raw of text.split('\n')) { + const trimmed = raw.trim(); + if (!trimmed) { + continue; + } + try { + const parsed: unknown = JSON.parse(trimmed); + if (parsed && typeof parsed === 'object') { + lines.push(parsed as CursorTranscriptLine); + } + } catch { + dropped++; + } + } + + if (dropped > 0) { + logger.debug(`[cursor] dropped ${dropped} unparseable line(s) in ${filePath}`); + } + return lines; +} + +/** + * The user's own words in a Cursor user message. + * + * Cursor wraps every prompt in `…` and `…`. + * Returning the raw text would make the report's session title read as a date, so the query + * is unwrapped here. Text with no `` is an injected continuation prompt + * (subagent hand-offs, "briefly inform the user…") rather than something the user typed. + */ +export function userQueryText(text: string): string | undefined { + const match = /([\s\S]*?)<\/user_query>/i.exec(text); + const query = match?.[1]?.trim(); + return query ? query : undefined; +} From 9f8d7e9314417efda4b61c31413c3ec99e4661a2 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:48 +0300 Subject: [PATCH 02/34] docs: document cursor analytics-only agent and fix copilot-cli row Add a `cursor` row to the AGENTS.md agent plugin table describing it as an analytics-only agent whose unmanaged sessions are read from Cursor's local transcripts, and correct the stale `copilot-cli` row, which is a managed agent (npmPackage `@github/copilot`), not analytics ingestion only. Refs #6 --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8bedc6f89..7b0627f7c 100644 --- a/AGENTS.md +++ b/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 `/.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 unmanaged sessions (visible by default, no `--include-external`) | 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`). From 4f87ac203a41c1f3afdb9c18d3bfc90c3c84bb79 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:49 +0300 Subject: [PATCH 03/34] feat(analytics): discover Cursor sessions as an analytics-only agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor is an IDE CodeMie never installs, launches or updates, so it registers with `analyticsOnly: true` — which keeps it out of every management surface and out of the ownership gate that would otherwise tag all of its sessions `native-external`. Sessions come from the agent transcripts under `~/.cursor/projects`. A transcript carries only role-tagged text, tool_use blocks and turn markers, so this reports exactly that plus the file's own birthtime and mtime as the activity window, and sets `usageUnavailableReason` so the report shows tokens and cost as unmeasurable rather than as zero. The lossy project slug is only de-slugged into a project path when the result names a directory that really exists. Model and real edit times live only in Cursor's AI-tracking database; `CursorSessionAdapter.setTrackingIndex()` is the seam that enrichment will be injected through. Refs #3 --- src/agents/__tests__/registry.test.ts | 1 + src/agents/plugins/cursor/cursor.plugin.ts | 62 ++++ src/agents/plugins/cursor/cursor.session.ts | 357 ++++++++++++++++++++ src/agents/plugins/cursor/index.ts | 6 + src/agents/registry.ts | 2 + src/cli/commands/analytics/agent-labels.ts | 1 + src/cli/commands/analytics/native-loader.ts | 2 +- 7 files changed, 430 insertions(+), 1 deletion(-) create mode 100644 src/agents/plugins/cursor/cursor.plugin.ts create mode 100644 src/agents/plugins/cursor/cursor.session.ts create mode 100644 src/agents/plugins/cursor/index.ts diff --git a/src/agents/__tests__/registry.test.ts b/src/agents/__tests__/registry.test.ts index baf860714..443231601 100644 --- a/src/agents/__tests__/registry.test.ts +++ b/src/agents/__tests__/registry.test.ts @@ -27,6 +27,7 @@ describe('AgentRegistry', () => { 'kimi-acp', 'openwiki', 'copilot-cli', // analytics-only: read for the report, never managed by CodeMie + 'cursor', // analytics-only: read for the report, never managed by CodeMie ].sort() ); }); diff --git a/src/agents/plugins/cursor/cursor.plugin.ts b/src/agents/plugins/cursor/cursor.plugin.ts new file mode 100644 index 000000000..45dcbc3ec --- /dev/null +++ b/src/agents/plugins/cursor/cursor.plugin.ts @@ -0,0 +1,62 @@ +/** + * Cursor agent plugin — analytics only. + * + * Cursor is an IDE that CodeMie neither installs, launches, configures nor updates; it is + * read for the analytics report and nothing else. That is exactly what `analyticsOnly: true` + * declares, and it is load-bearing in two places: + * + * - `AgentRegistry.getManageableAgents()` filters on it, which keeps Cursor out of every + * management surface (install, uninstall, update, list, doctor, first-run). `codemie update` + * in particular would otherwise run `npm install -g` against a package Cursor does not have. + * - the analytics ownership gate (`isAnalyticsOnlyAgent` in `native-loader.ts`) skips it. + * That gate exists to hide unmanaged runs of an agent CodeMie CAN manage; Cursor has no + * managed variant, so applying it would tag every Cursor session `native-external` and drop + * the whole agent from the default report. + * + * There is therefore no npm package, no CLI command, no env mapping and no provider list — + * none of the launch machinery is ever reached. The plugin exists solely to hand the registry + * a session adapter. + */ + +import type { AgentMetadata } from '../../core/types.js'; +import { BaseAgentAdapter } from '../../core/BaseAgentAdapter.js'; +import type { SessionAdapter } from '../../core/session/BaseSessionAdapter.js'; +import { CURSOR_AGENT_NAME, CURSOR_DISPLAY_NAME } from './cursor.constants.js'; +import { CursorSessionAdapter } from './cursor.session.js'; + +export const CursorPluginMetadata: AgentMetadata = { + name: CURSOR_AGENT_NAME, + displayName: CURSOR_DISPLAY_NAME, + description: 'Cursor - AI code editor; read for analytics, never managed by CodeMie', + npmPackage: null, + cliCommand: null, + dataPaths: { + home: '.cursor', + }, + envMapping: { + baseUrl: [], + apiKey: [], + model: [], + }, + supportedProviders: [], + analyticsOnly: true, +}; + +export class CursorPlugin extends BaseAgentAdapter { + private sessionAdapter: SessionAdapter | null = null; + + constructor() { + super(CursorPluginMetadata); + } + + /** + * Built lazily: a `codemie` run that never touches analytics should not pay to construct + * the adapter, and the registry instantiates every plugin at startup. + */ + getSessionAdapter(): SessionAdapter { + if (!this.sessionAdapter) { + this.sessionAdapter = new CursorSessionAdapter(this.metadata); + } + return this.sessionAdapter; + } +} diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts new file mode 100644 index 000000000..d053b03ba --- /dev/null +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -0,0 +1,357 @@ +/** + * Cursor session adapter — analytics-only. + * + * Cursor keeps one transcript per agent conversation at + * `~/.cursor/projects//agent-transcripts//.jsonl`. + * `projects/` also holds directories that are not projects at all (numeric window ids, + * `empty-window`) and project directories holding only `canvases`/`terminals`/`mcps`, so + * discovery keys on the presence of `agent-transcripts` rather than on the directory name. + * + * What a transcript can and cannot tell us is the whole design constraint here. It carries + * role-tagged text, tool_use blocks and turn markers — and nothing else. No timestamps, no + * model, no token counts. So: + * + * - the activity window comes from the transcript file's own birthtime/mtime, which is when + * Cursor actually created and last appended to it; + * - messages are emitted deliberately WITHOUT timestamps, so the native loader falls back to + * the descriptor's file times instead of a fabricated per-message clock; + * - `usageMeta.usageUnavailableReason` is always set, which is what makes the report render + * tokens and cost as unmeasurable rather than as a confident zero. + * + * Model, precise edit times and edited-file lists live only in Cursor's AI-tracking database. + * That enrichment is injected — see {@link CursorSessionAdapter.setTrackingIndex}. + * + * Messages are emitted in the Claude-shaped `{type, message: {role, content}}` form on + * purpose: `synthesizeRawSession` in `src/cli/commands/analytics/native-loader.ts` uses that + * shape for its default branch, so Cursor needs no per-agent case there. + * + * Everything is read-only and fail-soft. A missing Cursor home yields zero sessions, never an + * error — analytics for every other agent must survive Cursor not being installed. + */ + +import { existsSync, readdirSync, statSync } from 'fs'; +import { basename, join, sep } from 'path'; +import type { + SessionAdapter, + ParsedSession, + AggregatedResult, + SessionDiscoveryOptions, + SessionDescriptor, +} from '../../core/session/BaseSessionAdapter.js'; +import type { + SessionProcessor, + ProcessingContext, + ProcessingResult, +} from '../../core/session/BaseProcessor.js'; +import type { AgentMetadata } from '../../core/types.js'; +import { CURSOR_AGENT_NAME } from './cursor.constants.js'; +import { getCursorProjectsRoot } from './cursor.paths.js'; +import type { CursorTrackingIndex } from './cursor.tracking-db.js'; +import { + contentBlocks, + isMessageLine, + readCursorTranscript, + userQueryText, +} from './cursor.transcript.js'; +import { logger } from '../../../utils/logger.js'; + +const DEFAULT_MAX_AGE_DAYS = 30; +const MS_PER_DAY = 24 * 60 * 60 * 1000; + +/** Subdirectory of a Cursor project directory that holds agent conversations. */ +const TRANSCRIPTS_DIR = 'agent-transcripts'; + +/** + * Why a Cursor session is never priced. + * + * Cursor stores no token counts anywhere on disk — not in the transcript, not in the + * AI-tracking database. Reporting zero cost would read as "this session was free"; the + * reason string makes the report say "unmeasurable" instead. + */ +const NO_USAGE_REASON = + 'Cursor records no token usage locally — its transcripts carry no token counts, so cost cannot be derived'; + +/** Trailing-separator-insensitive directory comparison. */ +function sameDir(a: string | undefined, b: string): boolean { + if (!a) { + return false; + } + return a.replace(/[/\\]+$/, '') === b.replace(/[/\\]+$/, ''); +} + +/** + * Best-effort project path for a Cursor project slug. + * + * The slug is lossy: Cursor replaces both `/` and `_` with `-`, so `/Users/x/Sites/foo_bar` + * and `/Users/x/Sites/foo-bar` produce the same slug and reversal cannot be trusted. Rather + * than report a path that may not be the user's, the naive de-slug is only accepted when it + * names a directory that actually exists; otherwise the session is reported without a project + * and the report shows it as unknown. An honest gap beats a plausible-looking wrong answer. + */ +function projectPathFromSlug(slug: string): string | undefined { + const candidate = sep + slug.split('-').join(sep); + return existsSync(candidate) ? candidate : undefined; +} + +/** Directory entries of `dir`, or an empty list when it cannot be read. */ +function readDirNames(dir: string): string[] { + try { + return readdirSync(dir, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => entry.name); + } catch (error) { + logger.debug(`[cursor-discovery] failed to read ${dir}:`, error); + return []; + } +} + +/** + * When the transcript was created and last written. + * + * Some filesystems report a zero birthtime; mtime is then the only timestamp available and + * collapses the window to a point, which is still truthful about "when this happened". + */ +function transcriptWindow(filePath: string): { createdAt: number; updatedAt: number } | undefined { + try { + const stats = statSync(filePath); + const updatedAt = stats.mtimeMs; + const birth = stats.birthtimeMs; + return { createdAt: birth > 0 ? birth : updatedAt, updatedAt }; + } catch (error) { + logger.debug(`[cursor-discovery] cannot stat transcript ${filePath}:`, error); + return undefined; + } +} + +/** The Claude-shaped message the native loader's default synthesis branch understands. */ +interface CursorNativeMessage { + type: 'user' | 'assistant'; + message: { role: 'user' | 'assistant'; content: string }; +} + +export class CursorSessionAdapter implements SessionAdapter { + readonly agentName = CURSOR_AGENT_NAME; + private processors: SessionProcessor[] = []; + + /** + * Optional enrichment from `~/.cursor/ai-tracking/ai-code-tracking.db`, keyed by + * conversation id. Absent by default — see {@link setTrackingIndex}. + */ + private trackingIndex?: CursorTrackingIndex; + + constructor(private readonly metadata: AgentMetadata) {} + + /** + * Attach the AI-tracking index that supplies what a transcript cannot: the model and the + * real edit window. + * + * This is the injection seam rather than a direct call to `readCursorTrackingIndex` so the + * adapter stays synchronous-to-construct and free of a SQLite dependency: reading the + * database is async, needs Node >= 22.5, and must be done once per analytics run rather + * than once per session. The caller loads the index and hands it over. + */ + setTrackingIndex(index: CursorTrackingIndex): void { + this.trackingIndex = index; + } + + registerProcessor(processor: SessionProcessor): void { + this.processors.push(processor); + this.processors.sort((a, b) => a.priority - b.priority); + logger.debug(`[cursor-adapter] Registered processor: ${processor.name} (priority: ${processor.priority})`); + } + + /** + * Enumerate every agent transcript under `~/.cursor/projects`, newest first. + * + * Discovery deliberately does not open transcripts: the file's own stat is enough to date + * and filter a session, so a run never pays to read a transcript it goes on to discard. + */ + async discoverSessions(options?: SessionDiscoveryOptions): Promise { + const root = getCursorProjectsRoot(); + if (!existsSync(root)) { + logger.debug(`[cursor-discovery] no Cursor projects directory at ${root}`); + return []; + } + + const maxAgeDays = options?.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS; + const cutoffMs = Date.now() - maxAgeDays * MS_PER_DAY; + + const results: SessionDescriptor[] = []; + + for (const slug of readDirNames(root)) { + const transcriptsRoot = join(root, slug, TRANSCRIPTS_DIR); + if (!existsSync(transcriptsRoot)) { + continue; + } + + const projectPath = projectPathFromSlug(slug); + if (options?.cwd && !sameDir(projectPath, options.cwd)) { + continue; + } + + for (const conversationId of readDirNames(transcriptsRoot)) { + const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); + if (!existsSync(filePath)) { + continue; + } + + const window = transcriptWindow(filePath); + if (!window) { + continue; + } + if (window.createdAt < cutoffMs) { + continue; + } + + results.push({ + sessionId: conversationId, + filePath, + projectPath, + createdAt: window.createdAt, + updatedAt: window.updatedAt, + agentName: this.agentName, + }); + } + } + + results.sort((a, b) => b.createdAt - a.createdAt); + + if (options?.limit && options.limit > 0) { + logger.debug(`[cursor-discovery] found ${results.length} session(s), returning ${options.limit}`); + return results.slice(0, options.limit); + } + + logger.debug(`[cursor-discovery] found ${results.length} session(s)`); + return results; + } + + /** + * Parse one conversation transcript. + * + * The conversation id is the file's own basename, which is also the key the AI-tracking + * database joins on, so no separate correlation step is needed. + */ + async parseSessionFile(filePath: string, sessionId: string): Promise { + const conversationId = basename(filePath, '.jsonl'); + const lines = readCursorTranscript(filePath); + const activity = this.trackingIndex?.get(conversationId); + + const messages: CursorNativeMessage[] = []; + const userPrompts: Array<{ count: number; text: string }> = []; + const tools: Record = {}; + + for (const line of lines) { + if (!isMessageLine(line)) { + // Turn markers carry no facts the message stream does not already imply — the loader + // derives the turn count from assistant messages. + continue; + } + const role = line.role === 'assistant' ? 'assistant' : line.role === 'user' ? 'user' : undefined; + if (!role) { + continue; + } + + const texts: string[] = []; + for (const block of contentBlocks(line)) { + if (block.type === 'tool_use') { + const name = (block as { name?: string }).name; + if (name) { + tools[name] = (tools[name] ?? 0) + 1; + } + continue; + } + const text = (block as { text?: string }).text; + if (typeof text === 'string' && text.trim()) { + texts.push(text); + } + } + + const joined = texts.join('\n'); + // Cursor wraps a prompt in /; unwrap it so the report's session + // title reads as the user's question rather than as a date. + const content = role === 'user' ? (userQueryText(joined) ?? joined) : joined; + if (!content.trim()) { + continue; + } + + messages.push({ type: role, message: { role, content } }); + if (role === 'user') { + userPrompts.push({ count: 1, text: content }); + } + } + + const window = transcriptWindow(filePath); + const startMs = activity?.firstEditMs ?? window?.createdAt; + const endMs = activity?.lastEditMs ?? window?.updatedAt; + + logger.debug( + `[cursor-adapter] ${conversationId}: ${messages.length} message(s), ${userPrompts.length} prompt(s)` + ); + + return { + sessionId, + agentName: this.metadata.displayName, + metadata: { + createdAt: startMs === undefined ? undefined : new Date(startMs).toISOString(), + updatedAt: endMs === undefined ? undefined : new Date(endMs).toISOString(), + }, + // No per-message timestamps exist, and inventing them would make the report show a + // duration Cursor never recorded. Leaving them out makes the loader fall back to the + // descriptor's file-derived window, which is the only real signal available. + messages, + usageMeta: { + usageUnavailableReason: NO_USAGE_REASON, + }, + metrics: { + tools, + userPrompts, + }, + }; + } + + /** Parse once, then run every registered processor in priority order. */ + async processSession( + filePath: string, + sessionId: string, + context: ProcessingContext + ): Promise { + const parsed = await this.parseSessionFile(filePath, sessionId); + + const processors: AggregatedResult['processors'] = {}; + const failedProcessors: string[] = []; + let totalRecords = 0; + + for (const processor of this.processors) { + if (!processor.shouldProcess(parsed)) { + continue; + } + try { + const result: ProcessingResult = await processor.process(parsed, context); + const recordsProcessed = result.metadata?.recordsProcessed ?? 0; + totalRecords += recordsProcessed; + processors[processor.name] = { + success: result.success, + message: result.message, + recordsProcessed, + }; + if (!result.success) { + failedProcessors.push(processor.name); + } + } catch (error) { + logger.error(`[cursor-adapter] Processor ${processor.name} failed:`, error); + processors[processor.name] = { + success: false, + message: error instanceof Error ? error.message : String(error), + }; + failedProcessors.push(processor.name); + } + } + + return { + success: failedProcessors.length === 0, + processors, + totalRecords, + failedProcessors, + }; + } +} diff --git a/src/agents/plugins/cursor/index.ts b/src/agents/plugins/cursor/index.ts new file mode 100644 index 000000000..cfc4b1dcf --- /dev/null +++ b/src/agents/plugins/cursor/index.ts @@ -0,0 +1,6 @@ +export { CursorPlugin, CursorPluginMetadata } from './cursor.plugin.js'; +export { CURSOR_AGENT_NAME, CURSOR_DISPLAY_NAME, CURSOR_UNKNOWN_MODEL } from './cursor.constants.js'; +export { CursorSessionAdapter } from './cursor.session.js'; +export { getCursorHome, getCursorProjectsRoot, getCursorTrackingDbPath } from './cursor.paths.js'; +export { readCursorTrackingIndex } from './cursor.tracking-db.js'; +export type { CursorConversationActivity, CursorTrackingIndex } from './cursor.tracking-db.js'; diff --git a/src/agents/registry.ts b/src/agents/registry.ts index d0a655de4..7a12e8892 100644 --- a/src/agents/registry.ts +++ b/src/agents/registry.ts @@ -9,6 +9,7 @@ import { KimiPlugin } from './plugins/kimi/kimi.plugin.js'; import { KimiAcpPlugin } from './plugins/kimi/kimi-acp.plugin.js'; import { OpenWikiPlugin } from './plugins/openwiki/openwiki.plugin.js'; import { CopilotCliPlugin } from './plugins/copilot-cli/index.js'; +import { CursorPlugin } from './plugins/cursor/index.js'; import { AgentAdapter, AgentAnalyticsAdapter } from './core/types.js'; // Re-export for backwards compatibility @@ -43,6 +44,7 @@ export class AgentRegistry { AgentRegistry.registerPlugin(new KimiAcpPlugin()); AgentRegistry.registerPlugin(new OpenWikiPlugin()); AgentRegistry.registerPlugin(new CopilotCliPlugin()); + AgentRegistry.registerPlugin(new CursorPlugin()); AgentRegistry.initialized = true; } diff --git a/src/cli/commands/analytics/agent-labels.ts b/src/cli/commands/analytics/agent-labels.ts index 8a33af9b2..c7cb3c7bf 100644 --- a/src/cli/commands/analytics/agent-labels.ts +++ b/src/cli/commands/analytics/agent-labels.ts @@ -11,6 +11,7 @@ */ const AGENT_LABELS: Record = { 'copilot-cli': 'GitHub Copilot CLI', + cursor: 'Cursor', pi: 'Pi', 'gemini': 'Gemini CLI', }; diff --git a/src/cli/commands/analytics/native-loader.ts b/src/cli/commands/analytics/native-loader.ts index a8933b773..15652d5df 100644 --- a/src/cli/commands/analytics/native-loader.ts +++ b/src/cli/commands/analytics/native-loader.ts @@ -31,7 +31,7 @@ import { firstPiUserText } from '../../../agents/plugins/pi/session/pi-user-prom import { PI_FORKED_CONTINUATION, piForkedContinuations } from '../../../agents/plugins/pi/pi.session.js'; /** Agents whose native logs we discover + synthesize. */ -const NATIVE_AGENTS = ['claude', 'codex', 'copilot-cli', 'pi', 'gemini'] as const; +const NATIVE_AGENTS = ['claude', 'codex', 'copilot-cli', 'pi', 'gemini', 'cursor'] as const; function isPiAgent(agentName: string): boolean { return agentName.toLowerCase() === 'pi'; From 3e5017c6dee634d71713cac7e36c9b315cb58c07 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:49 +0300 Subject: [PATCH 04/34] feat(analytics): enrich Cursor sessions from the AI-tracking database MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Join Cursor's read-only AI-tracking database on conversation id to supply what a transcript cannot: the model, the files the agent wrote, the real edit window and a trustworthy project path. The index is read once per run, memoized in the adapter around discoverSessions, so native-loader.ts stays free of Cursor-specific code. The enrichment lands on the session descriptor as well as the parsed session because the loader's synthesis reads timing and cwd from the descriptor when messages carry no timestamps, which Cursor's never do. The project path is recovered by walking up from the common directory of the database's absolute file paths until a directory slugifies back to Cursor's own directory slug — a verification rather than a guess, so lossy slugs (both / and _ become -) resolve exactly. No match falls back to the previous existence-checked de-slug. Files are recorded without line counts (Cursor stores hashes, not diffs), and a model recorded only as the literal default stays unknown. A missing, locked or schema-drifted database degrades to transcript-only rows, and conversations that exist only in the database still produce none. Refs #4 --- src/agents/plugins/cursor/cursor.session.ts | 185 +++++++++++++++++--- 1 file changed, 159 insertions(+), 26 deletions(-) diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index d053b03ba..dc29235df 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -11,15 +11,18 @@ * role-tagged text, tool_use blocks and turn markers — and nothing else. No timestamps, no * model, no token counts. So: * - * - the activity window comes from the transcript file's own birthtime/mtime, which is when - * Cursor actually created and last appended to it; + * - the activity window comes from Cursor's own first/last recorded edit, falling back to the + * transcript file's birthtime/mtime, which is when Cursor created and last appended to it; * - messages are emitted deliberately WITHOUT timestamps, so the native loader falls back to - * the descriptor's file times instead of a fabricated per-message clock; + * the descriptor's window instead of a fabricated per-message clock; * - `usageMeta.usageUnavailableReason` is always set, which is what makes the report render * tokens and cost as unmeasurable rather than as a confident zero. * - * Model, precise edit times and edited-file lists live only in Cursor's AI-tracking database. - * That enrichment is injected — see {@link CursorSessionAdapter.setTrackingIndex}. + * Model, precise edit times, edited-file lists and the only trustworthy project path live in + * Cursor's AI-tracking database. The adapter reads it once per run and joins on conversation + * id — see {@link CursorSessionAdapter.setTrackingIndex}. When it is missing, locked, on a + * runtime without `node:sqlite` or schema-drifted, the join simply finds nothing and every + * session degrades to its transcript-only form. * * Messages are emitted in the Claude-shaped `{type, message: {role, content}}` form on * purpose: `synthesizeRawSession` in `src/cli/commands/analytics/native-loader.ts` uses that @@ -30,7 +33,7 @@ */ import { existsSync, readdirSync, statSync } from 'fs'; -import { basename, join, sep } from 'path'; +import { basename, dirname, isAbsolute, join, sep } from 'path'; import type { SessionAdapter, ParsedSession, @@ -46,7 +49,8 @@ import type { import type { AgentMetadata } from '../../core/types.js'; import { CURSOR_AGENT_NAME } from './cursor.constants.js'; import { getCursorProjectsRoot } from './cursor.paths.js'; -import type { CursorTrackingIndex } from './cursor.tracking-db.js'; +import type { CursorConversationActivity, CursorTrackingIndex } from './cursor.tracking-db.js'; +import { readCursorTrackingIndex } from './cursor.tracking-db.js'; import { contentBlocks, isMessageLine, @@ -93,6 +97,52 @@ function projectPathFromSlug(slug: string): string | undefined { return existsSync(candidate) ? candidate : undefined; } +/** The slug Cursor would have written for a directory: leading separator dropped, `/` and `_` → `-`. */ +function slugForPath(dir: string): string { + return dir.replace(/^[/\\]+/, '').replace(/[/\\_]/g, '-'); +} + +/** Deepest directory that is an ancestor of (or equal to) both paths. */ +function commonAncestor(a: string, b: string): string { + const left = a.split(sep); + const right = b.split(sep); + const shared: string[] = []; + for (let i = 0; i < Math.min(left.length, right.length) && left[i] === right[i]; i++) { + shared.push(left[i]); + } + return shared.join(sep) || sep; +} + +/** + * Project root for a conversation, recovered from the absolute paths the AI-tracking database + * recorded for it. + * + * The slug alone cannot be reversed (see {@link projectPathFromSlug}), and the files' common + * directory alone is not the project root either — a conversation that only touched `src/` + * yields `/src`. Combining the two settles it: walk up from the common directory until a + * directory slugifies back to the slug Cursor filed the conversation under. That match is a + * verification against Cursor's own naming, not a guess, so the answer is exact even for slugs + * whose `-` came from a `_`. No match means we stay silent and let the caller fall back. + */ +function projectPathFromFiles(slug: string, files: string[]): string | undefined { + const absolute = files.filter((file) => isAbsolute(file)); + if (absolute.length === 0) { + return undefined; + } + + let dir = absolute.map(dirname).reduce(commonAncestor); + for (;;) { + if (slugForPath(dir) === slug) { + return dir; + } + const parent = dirname(dir); + if (parent === dir) { + return undefined; + } + dir = parent; + } +} + /** Directory entries of `dir`, or an empty list when it cannot be read. */ function readDirNames(dir: string): string[] { try { @@ -126,7 +176,53 @@ function transcriptWindow(filePath: string): { createdAt: number; updatedAt: num /** The Claude-shaped message the native loader's default synthesis branch understands. */ interface CursorNativeMessage { type: 'user' | 'assistant'; - message: { role: 'user' | 'assistant'; content: string }; + message: { role: 'user' | 'assistant'; content: string; model?: string }; +} + +/** + * Stamp recorded models onto assistant messages — the only place the native loader looks for a + * session's model distribution. + * + * The tracking database attributes a model to a conversation, not to a turn. When it recorded a + * single model the whole conversation demonstrably ran on it, so every assistant message + * carries it. When it recorded several, the per-turn split is unknown, so each model is counted + * once instead of being spread into a distribution Cursor never stated. When it recorded none — + * including a conversation whose only model was the literal `default`, which the reader drops — + * nothing is stamped and the report shows the model as unknown. + */ +function applyModels(messages: CursorNativeMessage[], models: string[]): void { + if (models.length === 0) { + return; + } + const assistant = messages.filter((message) => message.type === 'assistant'); + if (models.length === 1) { + for (const message of assistant) { + message.message.model = models[0]; + } + return; + } + models.slice(0, assistant.length).forEach((model, i) => { + assistant[i].message.model = model; + }); +} + +/** + * Files the agent wrote, as file operations. + * + * Line counts are deliberately absent: Cursor records content hashes, not diffs, so an added or + * removed line count would have to be invented. `edit` rather than `write` because the database + * does not distinguish creating a file from changing one. + */ +function fileOperationsFrom(activity: CursorConversationActivity | undefined): NonNullable['fileOperations'] { + return (activity?.files ?? []).map((path) => ({ type: 'edit', path })); +} + +/** + * The project slug a transcript lives under, given the fixed layout + * `//agent-transcripts//.jsonl`. + */ +function slugOfTranscript(filePath: string): string { + return basename(dirname(dirname(dirname(filePath)))); } export class CursorSessionAdapter implements SessionAdapter { @@ -134,24 +230,41 @@ export class CursorSessionAdapter implements SessionAdapter { private processors: SessionProcessor[] = []; /** - * Optional enrichment from `~/.cursor/ai-tracking/ai-code-tracking.db`, keyed by - * conversation id. Absent by default — see {@link setTrackingIndex}. + * Enrichment from `~/.cursor/ai-tracking/ai-code-tracking.db`, keyed by conversation id. + * + * Memoized as the in-flight promise rather than the resolved map so that discovery and every + * subsequent parse share a single database read: the plugin hands out one adapter instance + * per process (`CursorPlugin.getSessionAdapter`), and an analytics run discovers once and + * then parses each transcript, so one memo here is one read per run. Doing it inside the + * adapter — rather than making the native loader call `readCursorTrackingIndex` before + * dispatching — keeps `native-loader.ts` free of Cursor-specific code, which is the whole + * reason the Cursor adapter emits Claude-shaped output in the first place. */ - private trackingIndex?: CursorTrackingIndex; + private trackingIndexLoad?: Promise; constructor(private readonly metadata: AgentMetadata) {} /** - * Attach the AI-tracking index that supplies what a transcript cannot: the model and the - * real edit window. + * Attach the AI-tracking index that supplies what a transcript cannot: the model, the edited + * files and the real edit window. * - * This is the injection seam rather than a direct call to `readCursorTrackingIndex` so the - * adapter stays synchronous-to-construct and free of a SQLite dependency: reading the - * database is async, needs Node >= 22.5, and must be done once per analytics run rather - * than once per session. The caller loads the index and hands it over. + * The injection seam exists because loading the database is async, needs Node >= 22.5 and + * must happen once per run; tests and any future caller that already holds an index can hand + * it over and suppress the lazy read below. */ setTrackingIndex(index: CursorTrackingIndex): void { - this.trackingIndex = index; + this.trackingIndexLoad = Promise.resolve(index); + } + + /** + * The tracking index, reading the database on first use. + * + * `readCursorTrackingIndex` never throws — a missing, locked or schema-drifted database + * resolves to an empty map — so no failure here can cost the run its transcript-only rows. + */ + private async trackingIndex(): Promise { + this.trackingIndexLoad ??= readCursorTrackingIndex(); + return this.trackingIndexLoad; } registerProcessor(processor: SessionProcessor): void { @@ -165,6 +278,12 @@ export class CursorSessionAdapter implements SessionAdapter { * * Discovery deliberately does not open transcripts: the file's own stat is enough to date * and filter a session, so a run never pays to read a transcript it goes on to discard. + * + * The descriptor — not the parsed session — is where enrichment has to land for timing and + * project: Cursor messages carry no timestamps and no cwd, so the native loader's synthesis + * falls back to `descriptor.createdAt` / `updatedAt` / `projectPath` for exactly those three + * facts. Applying the tracking window here also keeps the age cutoff and the reported window + * consistent with each other. */ async discoverSessions(options?: SessionDiscoveryOptions): Promise { const root = getCursorProjectsRoot(); @@ -175,6 +294,7 @@ export class CursorSessionAdapter implements SessionAdapter { const maxAgeDays = options?.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS; const cutoffMs = Date.now() - maxAgeDays * MS_PER_DAY; + const tracking = await this.trackingIndex(); const results: SessionDescriptor[] = []; @@ -184,10 +304,7 @@ export class CursorSessionAdapter implements SessionAdapter { continue; } - const projectPath = projectPathFromSlug(slug); - if (options?.cwd && !sameDir(projectPath, options.cwd)) { - continue; - } + const slugPath = projectPathFromSlug(slug); for (const conversationId of readDirNames(transcriptsRoot)) { const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); @@ -199,7 +316,17 @@ export class CursorSessionAdapter implements SessionAdapter { if (!window) { continue; } - if (window.createdAt < cutoffMs) { + + // A conversation that exists only in the database has no transcript and never reaches + // this point — the file loop above is the sole source of session identity. + const activity = tracking.get(conversationId); + const projectPath = projectPathFromFiles(slug, activity?.files ?? []) ?? slugPath; + if (options?.cwd && !sameDir(projectPath, options.cwd)) { + continue; + } + + const createdAt = activity?.firstEditMs ?? window.createdAt; + if (createdAt < cutoffMs) { continue; } @@ -207,8 +334,8 @@ export class CursorSessionAdapter implements SessionAdapter { sessionId: conversationId, filePath, projectPath, - createdAt: window.createdAt, - updatedAt: window.updatedAt, + createdAt, + updatedAt: Math.max(createdAt, activity?.lastEditMs ?? window.updatedAt), agentName: this.agentName, }); } @@ -234,7 +361,7 @@ export class CursorSessionAdapter implements SessionAdapter { async parseSessionFile(filePath: string, sessionId: string): Promise { const conversationId = basename(filePath, '.jsonl'); const lines = readCursorTranscript(filePath); - const activity = this.trackingIndex?.get(conversationId); + const activity = (await this.trackingIndex()).get(conversationId); const messages: CursorNativeMessage[] = []; const userPrompts: Array<{ count: number; text: string }> = []; @@ -280,9 +407,13 @@ export class CursorSessionAdapter implements SessionAdapter { } } + applyModels(messages, activity?.models ?? []); + const window = transcriptWindow(filePath); const startMs = activity?.firstEditMs ?? window?.createdAt; const endMs = activity?.lastEditMs ?? window?.updatedAt; + const slug = slugOfTranscript(filePath); + const projectPath = projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug); logger.debug( `[cursor-adapter] ${conversationId}: ${messages.length} message(s), ${userPrompts.length} prompt(s)` @@ -292,6 +423,7 @@ export class CursorSessionAdapter implements SessionAdapter { sessionId, agentName: this.metadata.displayName, metadata: { + projectPath, createdAt: startMs === undefined ? undefined : new Date(startMs).toISOString(), updatedAt: endMs === undefined ? undefined : new Date(endMs).toISOString(), }, @@ -305,6 +437,7 @@ export class CursorSessionAdapter implements SessionAdapter { metrics: { tools, userPrompts, + fileOperations: fileOperationsFrom(activity), }, }; } From ce7b831686ec9c7820f16365e49eaae17430330e Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:50 +0300 Subject: [PATCH 05/34] feat(analytics): render Cursor in the HTML report surfaces Add a `cursor` entry to the report client's duplicated AGENT_LABELS and AGENT_COLORS tables so Cursor is labelled and coloured consistently with the CLI's agent-labels.ts. Cursor records no token or cost data, so every money/token cell now goes through usage-availability helpers that render an em dash for sessions carrying `usageUnavailableReason` instead of a hard "$0.00" / "0". Aggregates only dash out when nothing in the group was measurable. Refs #5 --- .../commands/analytics/report/client/app.js | 39 ++++++++++++------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index 02bb7e76c..a3e43e37c 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -19,7 +19,7 @@ // ---- palette ------------------------------------------------------------ var PALETTE = ['#7C5CFC', '#2297F6', '#F5A534', '#06B6D4', '#259F4C', '#F9303C', '#C084FC', '#E879A6']; - var AGENT_COLORS = { claude: '#7C5CFC', 'claude-acp': '#9D7BFF', 'claude-desktop': '#B79DFF', gemini: '#F5A534', codex: '#06B6D4', 'codemie-codex': '#06B6D4', opencode: '#259F4C', 'codemie-code': '#2297F6', 'copilot-cli': '#6E7681', pi: '#E879A6' }; + var AGENT_COLORS = { claude: '#7C5CFC', 'claude-acp': '#9D7BFF', 'claude-desktop': '#B79DFF', gemini: '#F5A534', codex: '#06B6D4', 'codemie-codex': '#06B6D4', opencode: '#259F4C', 'codemie-code': '#2297F6', 'copilot-cli': '#6E7681', pi: '#E879A6', cursor: '#E5484D' }; var seenAgentColor = {}; var colorCursor = 0; function colorFor(agent) { @@ -29,7 +29,7 @@ } // Agent keys are internal ids; these are what a human should read. Unmapped agents fall // through to the key itself, so listing an agent here is optional. - var AGENT_LABELS = { 'copilot-cli': 'GitHub Copilot CLI', pi: 'Pi', 'gemini': 'Gemini CLI' }; + var AGENT_LABELS = { 'copilot-cli': 'GitHub Copilot CLI', cursor: 'Cursor', pi: 'Pi', 'gemini': 'Gemini CLI' }; function labelFor(agent) { return AGENT_LABELS[agent] || agent; } // ---- formatting --------------------------------------------------------- @@ -53,6 +53,19 @@ if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K'; return String(n || 0); } + // ---- usage availability ------------------------------------------------- + // Some agents record no token or cost data at all (analytics-only agents such as Cursor; + // also older Copilot CLI builds). The payload marks those with `usageUnavailableReason`, + // and their costUSD/tokens are structural zeros. Rendering them as "$0.00" / "0" would + // read as "this session was free", so every money/token cell goes through these helpers + // and shows an em dash instead. Aggregates only dash out when NOTHING in the group was + // measurable — a mixed group still shows the real sum of what was measured. + function usageUnknown(s) { return !!(s && s.usageUnavailableReason); } + function anyMeasured(list) { return (list || []).some(function (s) { return !usageUnknown(s); }); } + function fmtUSDOf(s, n) { return usageUnknown(s) ? '—' : fmtUSD(n); } + function fmtTokensOf(s, n) { return usageUnknown(s) ? '—' : fmtTokens(n); } + function fmtUSDAgg(list, n) { return anyMeasured(list) ? fmtUSD(n) : '—'; } + function esc(s) { return String(s == null ? '' : s).replace(/[&<>"]/g, function (c) { return { '&': '&', '<': '<', '>': '>', '"': '"' }[c]; }); } function shortPath(p) { var parts = String(p || '').split('/'); return parts[parts.length - 1] || p; } // Human-readable session label: the cleaned first-prompt title, falling back to a short id. @@ -481,7 +494,7 @@ var topModel = topOf(ss.flatMap(function (s) { return s.models; })); // No text-transform: it would render a mapped label as "Github Copilot Cli". // Unmapped keys keep their original look via the capitalize fallback below. - return ['' + esc(labelFor(a)) + '', fmtNum(ss.length), tdNum(sum(ss, function (s) { return s.turns; })), tdNum(sum(ss, function (s) { return s.fileOps; })), tdNum(sum(ss, function (s) { return s.netLines; })), '' + esc(topModel || '—') + '', tdNum(successRate(ss) + '%'), tdNum(fmtUSD(sum(ss, function (s) { return s.costUSD; })))]; + return ['' + esc(labelFor(a)) + '', fmtNum(ss.length), tdNum(sum(ss, function (s) { return s.turns; })), tdNum(sum(ss, function (s) { return s.fileOps; })), tdNum(sum(ss, function (s) { return s.netLines; })), '' + esc(topModel || '—') + '', tdNum(successRate(ss) + '%'), tdNum(fmtUSDAgg(ss, sum(ss, function (s) { return s.costUSD; })))]; }), [false, true, true, true, true, false, true, true]); host.appendChild(detail); @@ -509,7 +522,7 @@ fmtNum(g.length), Math.round((g.length / fs.length) * 1000) / 10 + '%', fmtNum(Math.round(sum(g, function(s) { return s.turns; }) / g.length)), - fmtUSD(sum(g, function(s) { return s.costUSD; }) / g.length), + fmtUSDAgg(g, sum(g, function(s) { return s.costUSD; }) / g.length), (avg >= 0 ? '+' : '') + fmtNum(Math.round(avg)), fmtNum(Math.round(sum(g, function(s) { return s.fileOps; }) / g.length)), successRate(g) + '%' @@ -554,11 +567,11 @@ + '−' + fmtNum(sum(ss, function (s) { return s.linesRemoved; })) + ''; }; rows.forEach(function (r, i) { - html += '▸ ' + esc(shortPath(r.p)) + '' + fmtNum(r.ss.length) + '' + fmtNum(sum(r.ss, function (s) { return s.turns; })) + '' + crudCells(r.ss) + '' + fmtNum(sum(r.ss, function (s) { return s.netLines; })) + '' + successRate(r.ss) + '%' + fmtUSD(sum(r.ss, function (s) { return s.costUSD; })) + ''; + html += '▸ ' + esc(shortPath(r.p)) + '' + fmtNum(r.ss.length) + '' + fmtNum(sum(r.ss, function (s) { return s.turns; })) + '' + crudCells(r.ss) + '' + fmtNum(sum(r.ss, function (s) { return s.netLines; })) + '' + successRate(r.ss) + '%' + fmtUSDAgg(r.ss, sum(r.ss, function (s) { return s.costUSD; })) + ''; // branch sub-rows (hidden) var byBranch = groupBy(r.ss, function (s) { return s.branch || '(none)'; }); byBranch.forEach(function (bss, b) { - html += '⎇ ' + esc(b) + '' + bss.length + '' + fmtNum(sum(bss, function (s) { return s.turns; })) + '' + crudCells(bss) + '' + fmtNum(sum(bss, function (s) { return s.netLines; })) + '' + successRate(bss) + '%' + fmtUSD(sum(bss, function (s) { return s.costUSD; })) + ''; + html += '⎇ ' + esc(b) + '' + bss.length + '' + fmtNum(sum(bss, function (s) { return s.turns; })) + '' + crudCells(bss) + '' + fmtNum(sum(bss, function (s) { return s.netLines; })) + '' + successRate(bss) + '%' + fmtUSDAgg(bss, sum(bss, function (s) { return s.costUSD; })) + ''; }); }); html += ''; @@ -869,7 +882,7 @@ return [esc(s.sessionId.slice(0, 8)), '' + esc(labelFor(s.agentName)) + '', '' + esc(shortPath(s.project)) + '', - fmtTokens(tkIn(s)), fmtTokens(tkOut(s)), fmtTokens(tkCached(s)), fmtTokens(s.tokens ? s.tokens.total : 0), fmtUSD(s.costUSD)]; + fmtTokensOf(s, tkIn(s)), fmtTokensOf(s, tkOut(s)), fmtTokensOf(s, tkCached(s)), fmtTokensOf(s, s.tokens ? s.tokens.total : 0), fmtUSDOf(s, s.costUSD)]; }), [false, false, false, true, true, true, true, true]) + ''; host.appendChild(topCard); @@ -907,7 +920,7 @@ promptCell, '' + esc(labelFor(s.agentName)) + '', '' + esc(shortPath(s.project)) + '', branchCell, sourceCell, - fmtNum(s.turns), fmtNum(s.netLines), fmtTokens(tkIn(s)), fmtTokens(tkOut(s)), fmtTokens(tkCached(s)), fmtUSD(s.costUSD)]; + fmtNum(s.turns), fmtNum(s.netLines), fmtTokensOf(s, tkIn(s)), fmtTokensOf(s, tkOut(s)), fmtTokensOf(s, tkCached(s)), fmtUSDOf(s, s.costUSD)]; }), [false, false, false, false, false, false, true, true, true, true, true, true], shown.map(function (s) { return 'class="clickable" data-session="' + esc(s.sessionId) + '"'; })); @@ -1255,9 +1268,9 @@ costCard._body.appendChild(el('div', 'text-muted', 'Partial usage — output tokens only; this session recorded no full rollup, so cost is understated.')); } var tokCard = card('Token usage'); tokCard._body.appendChild(statsEl([ - ['Input', fmtTokens(t.input), ''], ['Output', fmtTokens(t.output), ''], - ['Cache read', fmtTokens(t.cacheRead), ''], ['Cache create', fmtTokens(t.cacheCreation), ''], - ['Total', fmtTokens(t.total), ''] + ['Input', fmtTokensOf(s, t.input), ''], ['Output', fmtTokensOf(s, t.output), ''], + ['Cache read', fmtTokensOf(s, t.cacheRead), ''], ['Cache create', fmtTokensOf(s, t.cacheCreation), ''], + ['Total', fmtTokensOf(s, t.total), ''] ])); var actCard = card('Activity'); actCard._body.appendChild(statsEl([ ['Turns / API', fmtNum(s.turns), ''], @@ -1352,7 +1365,7 @@ var netLines = sum(sessions, function (s) { return s.netLines || 0; }); body.appendChild(statsEl([ ['Sessions', fmtNum(sessions.length)], - ['Total cost', fmtUSD(totalCost)], + ['Total cost', fmtUSDAgg(sessions, totalCost)], ['Turns', fmtNum(totalTurns)], ['Net lines', (netLines >= 0 ? '+' : '') + fmtNum(netLines)] ])); @@ -1367,7 +1380,7 @@ esc(truncStr(firstWords(sessTitle(s), 12), 100)), esc(fmtWhen(s.startTime)), fmtNum(s.turns || 0), - fmtUSD(s.costUSD || 0), + fmtUSDOf(s, s.costUSD || 0), '' ]; }), From 38891d4e97e04122d8a44f8e5952dbe26bf60657 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:50 +0300 Subject: [PATCH 06/34] test(analytics): cover Cursor analytics at the native-loader seam Drive loadNativeSessions() against a fixture Cursor home reached through the CURSOR_HOME override, asserting external behavior only: discovery, the native-unmanaged tag and default visibility without --include-external; tracking-database enrichment (model, files touched, edit-derived window) with a 'default' model reported as unknown; fail-soft degradation for a missing, corrupt or schema-drifted database; zero sessions for an absent or empty Cursor home; and tokens/cost/lines left blank with an unavailable reason. Refs #7 --- .../__tests__/native-loader-cursor.test.ts | 450 ++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts new file mode 100644 index 000000000..320e28cb3 --- /dev/null +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -0,0 +1,450 @@ +/** + * Cursor analytics, driven from the outside. + * + * Cursor is CodeMie's first analytics-only agent: never installed, never launched, only read. + * These tests exercise the whole ingestion path from the top seam — `loadNativeSessions()` — + * against a fixture Cursor home reached through the `CURSOR_HOME` override, exactly the way + * `copilot-cli.discovery.test.ts` drives `COPILOT_HOME`. Nothing here reaches into a parser: + * a Cursor home goes in, analytics rows come out, and the assertions are about those rows. + * + * Discovery and parsing run through the real registry-resolved `CursorSessionAdapter`; the + * loader's other dependencies (tracked-log dedup, ownership markers, the other native agents) + * are injected, which is what keeps the run off `~/.codemie` and off the developer's own + * `~/.cursor`. Each run re-imports the module graph so the adapter's once-per-run tracking-index + * memo cannot leak one test's fixture database into the next. + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'; +import { join } from 'node:path'; +import { tmpdir } from 'node:os'; +import type { NativeLoaderDeps, DiscoveredNative } from '../native-loader.js'; +import type { RawSessionData } from '../data-loader.js'; +import type { ParsedSession } from '../../../../agents/core/session/BaseSessionAdapter.js'; + +/** + * `node:sqlite` landed in Node 22.5 and the repo supports Node >= 20, so the tracking-database + * enrichment is optional at runtime — and the tests that need a fixture database are optional + * too. On an older runtime they skip and the transcript-only expectations below still run, + * which is the same degradation the product promises. + */ +function hasNodeSqlite(): boolean { + const [major, minor] = process.versions.node.split('.').map(Number); + return major > 22 || (major === 22 && minor >= 5); +} + +const HOUR = 60 * 60 * 1000; +const FIRST_EDIT_MS = Date.now() - 3 * HOUR; +const LAST_EDIT_MS = Date.now() - 2 * HOUR; + +let cursorHome: string; +let projectDir: string; +let projectSlug: string; + +/** The slug Cursor files a project under: leading separator dropped, `/` and `_` both `-`. */ +function slugForPath(dir: string): string { + return dir.replace(/^[/\\]+/, '').replace(/[/\\_]/g, '-'); +} + +/** One `//agent-transcripts//.jsonl` under the fixture home. */ +function writeTranscript(conversationId: string, lines: unknown[], slug: string = projectSlug): void { + const dir = join(cursorHome, 'projects', slug, 'agent-transcripts', conversationId); + mkdirSync(dir, { recursive: true }); + writeFileSync( + join(dir, `${conversationId}.jsonl`), + `${lines.map((line) => JSON.stringify(line)).join('\n')}\n`, + 'utf-8' + ); +} + +function userLine(text: string): unknown { + return { + role: 'user', + message: { content: [{ type: 'text', text: `2026-09-03${text}` }] }, + }; +} + +function assistantLine(text: string): unknown { + return { role: 'assistant', message: { content: [{ type: 'text', text }] } }; +} + +/** A two-turn conversation — the shape every fixture below reuses. */ +function conversation(prompt: string): unknown[] { + return [ + userLine(prompt), + assistantLine('on it'), + { type: 'turn_ended', status: 'completed' }, + userLine('and the second thing'), + assistantLine('done'), + { type: 'turn_ended', status: 'completed' }, + ]; +} + +interface TrackingRow { + conversationId: string; + fileName: string; + model: string; + timestamp: number; + source?: string; +} + +/** A fixture AI-tracking database with Cursor's real table/column names. */ +async function writeTrackingDb(rows: TrackingRow[]): Promise { + const { DatabaseSync } = await import('node:sqlite'); + const dir = join(cursorHome, 'ai-tracking'); + mkdirSync(dir, { recursive: true }); + const db = new DatabaseSync(join(dir, 'ai-code-tracking.db')); + db.exec( + 'CREATE TABLE ai_code_hashes (conversationId TEXT, fileName TEXT, model TEXT, timestamp INTEGER, source TEXT)' + ); + const insert = db.prepare( + 'INSERT INTO ai_code_hashes (conversationId, fileName, model, timestamp, source) VALUES (?, ?, ?, ?, ?)' + ); + for (const row of rows) { + insert.run(row.conversationId, row.fileName, row.model, row.timestamp, row.source ?? 'composer'); + } + db.close(); +} + +/** A database Cursor could plausibly ship after a schema change: valid file, unknown table. */ +async function writeSchemaDriftedDb(): Promise { + const { DatabaseSync } = await import('node:sqlite'); + const dir = join(cursorHome, 'ai-tracking'); + mkdirSync(dir, { recursive: true }); + const db = new DatabaseSync(join(dir, 'ai-code-tracking.db')); + db.exec('CREATE TABLE ai_code_events (conversation_uuid TEXT, path TEXT)'); + db.close(); +} + +/** Not a database at all — a corrupt or half-written file. */ +function writeCorruptDb(): void { + const dir = join(cursorHome, 'ai-tracking'); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, 'ai-code-tracking.db'), 'this is not a sqlite file', 'utf-8'); +} + +/** A managed agent's native session, for contrast with the unmanaged Cursor rows. */ +const claudeDiscovery: DiscoveredNative = { + agentName: 'claude', + descriptor: { + sessionId: 'cl1', + filePath: '/logs/cl1.jsonl', + projectPath: '/repo/app', + createdAt: Date.now() - HOUR, + updatedAt: Date.now(), + agentName: 'claude', + }, +}; + +const claudeParsed = { + sessionId: 'cl1', + agentName: 'claude', + metadata: {}, + messages: [ + { type: 'assistant', timestamp: '2026-09-03T10:00:00Z', message: { role: 'assistant', model: 'claude-sonnet-4-6' } }, + ], + metrics: { tools: {} }, +} as never; + +interface SeamRun { + rows: RawSessionData[]; + /** Every session the loader asked the Cursor adapter to parse, as the adapter returned it. */ + parsed: ParsedSession[]; +} + +/** + * Load native sessions the way `SessionsSource` does, but with only the Cursor adapter (plus an + * optional managed-agent contrast row) behind the discovery dependency. + */ +async function runLoader(options: { withManagedClaude?: boolean } = {}): Promise { + vi.resetModules(); + const { AgentRegistry } = await import('../../../../agents/registry.js'); + const { loadNativeSessions } = await import('../native-loader.js'); + + const adapter = AgentRegistry.getAgent('cursor')?.getSessionAdapter?.(); + if (!adapter?.discoverSessions) { + throw new Error('cursor session adapter is not reachable through the registry'); + } + + const parsed: ParsedSession[] = []; + const deps: NativeLoaderDeps = { + trackedLogPaths: () => new Set(), + async discover(maxAgeDays) { + const descriptors = await adapter.discoverSessions!({ maxAgeDays }); + const found: DiscoveredNative[] = descriptors.map((descriptor) => ({ + agentName: descriptor.agentName ?? 'cursor', + descriptor, + })); + return options.withManagedClaude ? [...found, claudeDiscovery] : found; + }, + async parse(agentName, filePath, sessionId) { + if (agentName !== 'cursor') { + return claudeParsed; + } + const session = await adapter.parseSessionFile(filePath, sessionId); + parsed.push(session); + return session; + }, + realPath: (p) => p, + hasOwnershipMarker: () => false, + }; + + return { rows: await loadNativeSessions(undefined, deps), parsed }; +} + +/** + * The one gate `--include-external` applies, copied from `sources/sessions-source.ts` so the + * default-visibility claim is asserted against the real predicate rather than a paraphrase. + */ +function visible(rows: RawSessionData[], includeExternal: boolean): RawSessionData[] { + return rows.filter((s) => includeExternal || s.startEvent?.data.provider !== 'native-external'); +} + +function cursorRows(rows: RawSessionData[]): RawSessionData[] { + return rows.filter((s) => s.startEvent?.agentName === 'cursor'); +} + +beforeEach(() => { + cursorHome = mkdtempSync(join(tmpdir(), 'cursor-home-')); + projectDir = mkdtempSync(join(tmpdir(), 'cursor-project-')); + projectSlug = slugForPath(projectDir); + process.env.CURSOR_HOME = cursorHome; +}); + +afterEach(() => { + delete process.env.CURSOR_HOME; + rmSync(cursorHome, { recursive: true, force: true }); + rmSync(projectDir, { recursive: true, force: true }); + vi.resetModules(); +}); + +describe('loadNativeSessions — Cursor discovery and unmanaged tagging', () => { + it('discovers every transcript in the fixture Cursor home', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + writeTranscript('conv-b', conversation('rename the module')); + + const { rows } = await runLoader(); + + expect(cursorRows(rows).map((s) => s.sessionId).sort()).toEqual(['conv-a', 'conv-b']); + }); + + it('ignores Cursor project directories that hold no agent transcripts', async () => { + // `projects/` also carries window ids and canvas/terminal/mcp-only directories. + mkdirSync(join(cursorHome, 'projects', 'empty-window', 'canvases'), { recursive: true }); + mkdirSync(join(cursorHome, 'projects', '1749283', 'terminals'), { recursive: true }); + writeTranscript('conv-a', conversation('add cursor analytics')); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)).toHaveLength(1); + }); + + it('tags Cursor sessions native-unmanaged, not native-external', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.provider).toBe('native-unmanaged'); + }); + + it('shows Cursor sessions without --include-external, unlike a managed agent’s native session', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + + const { rows } = await runLoader({ withManagedClaude: true }); + + // The unowned Claude row is the contrast: managed agent, so it is gated behind the flag. + expect(rows.find((s) => s.sessionId === 'cl1')!.startEvent!.data.provider).toBe('native-external'); + + const byDefault = visible(rows, false).map((s) => s.sessionId); + expect(byDefault).toContain('conv-a'); + expect(byDefault).not.toContain('cl1'); + expect(visible(rows, true).map((s) => s.sessionId)).toContain('cl1'); + }); + + it('carries the transcript’s prompts and turns onto the synthesized row', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.endEvent!.data.totalTurns).toBe(2); + // The prompt is unwrapped from Cursor's envelope, so the report titles the + // session with the question rather than with a date. + expect(row.deltas[0].userPrompts?.[0].text).toBe('add cursor analytics'); + }); +}); + +describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor enrichment from the AI-tracking database', () => { + it('adds model, files touched and the edit-derived activity window', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeTrackingDb([ + { + conversationId: 'conv-a', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + }, + { + conversationId: 'conv-a', + fileName: join(projectDir, 'src', 'index.ts'), + model: 'claude-4.5-sonnet', + timestamp: LAST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.deltas[0].models).toEqual(['claude-4.5-sonnet', 'claude-4.5-sonnet']); + expect(row.deltas[0].fileOperations?.map((f) => f.path).sort()).toEqual( + [join(projectDir, 'src', 'app.ts'), join(projectDir, 'src', 'index.ts')].sort() + ); + expect(row.startEvent!.data.startTime).toBe(FIRST_EDIT_MS); + expect(row.endEvent!.data.endTime).toBe(LAST_EDIT_MS); + // The project root is recovered by matching the recorded files back against Cursor's slug. + expect(row.startEvent!.data.workingDirectory).toBe(projectDir); + }); + + it('reports a model recorded as "default" as unknown rather than guessing one', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeTrackingDb([ + { + conversationId: 'conv-a', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'default', + timestamp: FIRST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.deltas[0].models).toEqual([]); + // Enrichment still happened — only the meaningless model string was dropped. + expect(row.deltas[0].fileOperations?.map((f) => f.path)).toEqual([join(projectDir, 'src', 'app.ts')]); + }); + + it('ignores human-attributed edits, which are not the agent’s work', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeTrackingDb([ + { + conversationId: 'conv-a', + fileName: join(projectDir, 'typed-by-hand.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + source: 'human', + }, + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].deltas[0].fileOperations).toEqual([]); + }); + + it('produces no session for a conversation that exists only in the database', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeTrackingDb([ + { + conversationId: 'composer-only', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows).map((s) => s.sessionId)).toEqual(['conv-a']); + }); +}); + +describe('loadNativeSessions — Cursor degrades to transcript-only rows', () => { + it('still reports the session when the tracking database is missing', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.sessionId).toBe('conv-a'); + expect(row.deltas[0].models).toEqual([]); + expect(row.deltas[0].fileOperations).toEqual([]); + // No database means no project attribution either — reported as unknown, never guessed. + expect(row.startEvent!.data.workingDirectory).toBe('Unknown'); + // The window falls back to the transcript file's own birth/modification times. + expect(row.startEvent!.data.startTime).toBeGreaterThan(0); + }); + + it('still reports the session when the tracking database is corrupt', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + writeCorruptDb(); + + const { rows } = await runLoader(); + + expect(cursorRows(rows).map((s) => s.sessionId)).toEqual(['conv-a']); + expect(cursorRows(rows)[0].deltas[0].models).toEqual([]); + }); + + it.skipIf(!hasNodeSqlite())('still reports the session when the database schema has drifted', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeSchemaDriftedDb(); + + const { rows } = await runLoader(); + + expect(cursorRows(rows).map((s) => s.sessionId)).toEqual(['conv-a']); + expect(cursorRows(rows)[0].deltas[0].fileOperations).toEqual([]); + }); +}); + +describe('loadNativeSessions — Cursor absent', () => { + it('yields no Cursor sessions when there is no Cursor home', async () => { + process.env.CURSOR_HOME = join(cursorHome, 'does-not-exist'); + + const { rows } = await runLoader({ withManagedClaude: true }); + + expect(cursorRows(rows)).toEqual([]); + // The rest of the report is unaffected: Cursor simply is not there. + expect(rows.map((s) => s.sessionId)).toEqual(['cl1']); + }); + + it('yields no Cursor sessions when the Cursor home is empty', async () => { + mkdirSync(join(cursorHome, 'projects'), { recursive: true }); + + const { rows } = await runLoader(); + + expect(rows).toEqual([]); + }); +}); + +describe('loadNativeSessions — Cursor never reports tokens, cost or line counts', () => { + it('states why usage is unavailable instead of reporting zero', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + + const { parsed } = await runLoader(); + + expect(parsed).toHaveLength(1); + expect(parsed[0].usageMeta?.usageUnavailableReason).toEqual(expect.stringContaining('Cursor')); + // A blank-with-a-reason session must not also claim a measured zero. + expect(parsed[0].usageMeta).not.toHaveProperty('totalTokens'); + expect(parsed[0].usageMeta).not.toHaveProperty('premiumRequests'); + }); + + it.skipIf(!hasNodeSqlite())('reports edited files without inventing line counts', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeTrackingDb([ + { + conversationId: 'conv-a', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + const operation = cursorRows(rows)[0].deltas[0].fileOperations![0]; + + expect(operation.type).toBe('edit'); + expect(operation.linesAdded).toBeUndefined(); + expect(operation.linesRemoved).toBeUndefined(); + expect(operation.linesModified).toBeUndefined(); + }); +}); From adbc63ed9ffad210eee6de411b69fee9609f6304 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:50 +0300 Subject: [PATCH 07/34] fix(analytics): resolve Cursor project paths and activity windows honestly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two defects surfaced by code review against real Cursor data. Project attribution (story 5): the slug de-slugger split on every "-", but Cursor slugs "/" and "_" alike and a directory name may contain "-" of its own, so "Users-ada_lovelace-claude-code-router" became "/Users/ada/lovelace/claude/code/router" and 57 of 65 local sessions reported no project. The slug is now walked against the filesystem, descending only into children whose own slug matches, so each step is verified rather than guessed. Directory listing follows symlinks, without which the walk died at macOS's symlinked /var. Activity window (story 9): Cursor stamps every prompt with a readable timestamp, and userQueryText discarded it, leaving file birth/mtime as the only signal — which measures when the transcript was touched, so a resumed conversation reported a span of days. Stamps now sit between the tracking database and file times. Also from review: apply the unavailable-usage helpers to the per-session and aggregate cost cells they had been missed on, so Cursor rows never render a confident $0.00; correct a doc comment that inverted the CONTEXT.md external vs unmanaged distinction; split discoverSessions and parseSessionFile to respect the 50-line guidance; drop an unused export. Projects still absent from disk stay Unknown by design — an honest gap beats a wrong answer. Refs #1 --- ...-messagegrill-with-docscommand-message.txt | 499 ++++++++++++++++++ package-lock.json | 29 +- src/agents/plugins/cursor/cursor.plugin.ts | 7 +- src/agents/plugins/cursor/cursor.session.ts | 309 +++++++---- .../plugins/cursor/cursor.transcript.ts | 80 ++- .../__tests__/native-loader-cursor.test.ts | 105 +++- .../commands/analytics/report/client/app.js | 12 +- 7 files changed, 903 insertions(+), 138 deletions(-) create mode 100644 2026-09-03-161326-command-messagegrill-with-docscommand-message.txt diff --git a/2026-09-03-161326-command-messagegrill-with-docscommand-message.txt b/2026-09-03-161326-command-messagegrill-with-docscommand-message.txt new file mode 100644 index 000000000..f50e39ff5 --- /dev/null +++ b/2026-09-03-161326-command-messagegrill-with-docscommand-message.txt @@ -0,0 +1,499 @@ + ▐▛███▜▌ Claude Code v2.1.228 +▝▜█████▛▘ Fable 5 · Claude Pro + ▘▘ ▝▝ ~/…/worktrees/codemie-code/wt-feature-cursor-analytics-support + + +❯ /grill-with-docs "codemie analytics show --include-external --report --open" +does not include cursor usage data. I want + to be able to see the cursor usage too. + +⏺ Skill(grilling) + ⎿  Successfully loaded skill + +⏺ Skill(domain-modeling) + ⎿  Successfully loaded skill + +⏺ Explore(Explore external analytics ingestion) + ⎿  Backgrounded agent (↓ to manage · ctrl+o to expand) + +⏺ Exploration is running in the background. Here's the first round of frontier + questions — the decisions that don't depend on those code facts. + + ❓ Q1 - Which "Cursor" do you mean?: Cursor ships several surfaces whose usage + is recorded very differently: (a) the Cursor IDE itself (chat/composer/tab + usage inside the editor), (b) the Cursor CLI / cursor-agent (the terminal + agent, closest in spirit to the other agents CodeMie tracks), or (c) both. + Which usage do you actually want to see in the analytics report? + + ➡️ My recommendation: start with the Cursor CLI / cursor-agent, since + CodeMie's analytics model is built around terminal-agent sessions (like the + copilot-cli external-ingestion precedent), and IDE usage may not be fully + reconstructable from local data. + + --- + ❓ Q2 - Data source: Where should the numbers come from? Options: (a) local + session/log files Cursor writes on your machine (zero-config, offline, matches + how CodeMie ingests Copilot data — but limited to what Cursor persists + locally), (b) the Cursor Admin/Teams API (authoritative usage + spend, but + requires a team admin API key and network access), or (c) local first, API + later if needed. + + ➡️ My recommendation: (a) local files, consistent with the existing + external-ingestion approach — no credentials, works per-developer. I'll + confirm from the exploration what Cursor actually persists locally and flag if + it's too thin. + + --- + ❓ Q3 - Whose usage / which machine?: Is this strictly your own usage on this + machine (like the rest of codemie analytics show), or do you want team-wide + Cursor usage? Team-wide would force the Admin API path in Q2 and is a + different feature shape. + + ➡️ My recommendation: personal, local-machine usage only, matching the + existing analytics scope. + + --- + ❓ Q4 - What counts as "usage data"?: Sharpening the term — for the other + agents a session record carries things like agent name, timestamps, model, + token counts, and cost. If Cursor's local data only supports a subset (e.g., + sessions and timestamps but not reliable token/cost figures), is a partial row + acceptable in the report, or is token/cost data the actual point of this + request? + + ➡️ My recommendation: ingest whatever fields Cursor exposes and render partial + data honestly (blank/— for missing metrics), rather than blocking the feature + on cost parity. If cost is the real goal, say so — that changes the Q2 answer + toward the API. + + --- + ❓ Q5 - Where it lives: Should Cursor appear under the existing + --include-external flag as just another external agent (like copilot-cli) with + no new CLI surface, or do you want any dedicated command/flag for it? + + ➡️ My recommendation: no new CLI surface — Cursor becomes another external, + analytics-only agent that --include-external picks up automatically. + + Answer these and I'll fold in the exploration results and push the frontier + outward (parsing format, session-boundary semantics, dedupe rules, report + grouping, etc.). + +⏺ Ran 3 stop hooks (ctrl+o to expand) + ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: + command not found + +✻ Cooked for 43s + +❯ I accept recommended answers + +⏺ Settled: Cursor CLI (cursor-agent) usage, ingested from local files on this + machine, personal scope, partial metrics acceptable, surfaced via the existing + --include-external flag. While the repo exploration finishes, let me check + what Cursor actually persists locally on this machine — that fact gates the + next round. + + Listed 2 directories, ran 3 shell commands (ctrl+o to expand) + +⏺ Agent "Explore external analytics ingestion" finished · 2m 12s + +⏺ The exploration came back and reshapes one of our settled answers. Let me grab + two more local facts (timestamps/model info in Cursor transcripts) before the + next round. + + Listed 1 directory, ran 2 shell commands (ctrl+o to expand) + +⏺ Key facts now in hand — and one of them reshapes your original framing: + + From the codebase: The repo has an explicit declarative path for exactly this: + an agent plugin with analyticsOnly: true plus a SessionAdapter (like + copilot-cli before it became a managed agent). Important nuance: + --include-external gates unowned sessions of managed agents (tagged + native-external). Analytics-only agents get tagged native-unmanaged and are + shown by default, no flag needed. So "make --include-external include Cursor" + isn't actually the lever the codebase offers. + + From your machine (Cursor's local data): + - ~/.cursor/projects//agent-transcripts//.jsonl — CLI agent + transcripts. Very thin: just user/assistant text turns and turn_ended markers. + No timestamps, no model, no tokens, no tool calls. Timestamps only + recoverable from file creation/modification times; project comes from the + directory name. + - ~/.cursor/ai-tracking/ai-code-tracking.db — a richer SQLite DB: + conversation_summaries (conversationId, title, model), ai_code_hashes + (per-edit model + timestamps), scored_commits (AI vs human lines added/deleted + per commit). This likely mixes IDE composer/tab activity with agent activity. + - ~/.cursor/chats/*/store.db — opaque blob store (empty in your samples); not + viable. + + Round 2: + + ❓ Q6 - Visibility semantics: Should Cursor sessions (a) follow the repo's + analyticsOnly pattern — tagged native-unmanaged, visible by default in codemie + analytics with no flag — or (b) be artificially gated behind + --include-external to match your original phrasing? + + ➡️ (a): follow the existing pattern. You'll see Cursor with or without the + flag, which is strictly more than you asked for, and it keeps native-external + meaning what it means today (unowned sessions of managed agents). + + --- + ❓ Q7 - Metric depth / data sources: Given the transcripts are thin, which + sources should the adapter read? (a) Transcripts only — session count, + prompt/turn counts, project, start/end from file times; model, tokens, cost, + lines all blank. (b) Transcripts + join ai-code-tracking.db — adds + per-conversation model and title, and potentially AI-attributed lines + added/removed, at the cost of depending on an undocumented internal Cursor DB + schema that can break on Cursor updates (read-only, tolerant parsing would + mitigate). + + ➡️ (b), with tolerant, fail-soft reads: the DB is what makes the rows + meaningfully comparable (model + lines), and the failure mode is just falling + back to (a). The schema-drift risk matches the risk already accepted for + Copilot's undocumented events.jsonl. + + --- + ❓ Q8 - Model attribution fallback: When a session has no model in the + tracking DB, should the row (a) show model as unknown/blank, or (b) stamp the + current default model from ~/.cursor/cli-config.json (composer-1 right now)? + + ➡️ (a) unknown/blank. The config records today's default, not what a past + session actually used — stamping it would fabricate data. + + --- + ❓ Q9 - Agent identity in the report: Name the agent key cursor (matching the + existing .cursor detection in agent-detection.ts and label it "Cursor" in the + Agents view), or cursor-cli/cursor-agent to disambiguate from the IDE? + + ➡️ cursor, label "Cursor" — consistent with the existing detection entry, and + since the tracking DB blends IDE-assisted edits anyway, the broader name is + more honest than cursor-cli. + + One glossary note I'll capture once Q6 settles: external (native-external — + unowned sessions of agents CodeMie manages) vs unmanaged (native-unmanaged — + agents CodeMie only reads analytics for) are distinct terms in this codebase, + and your request is really about the latter. + +⏺ Ran 3 stop hooks (ctrl+o to expand) + ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: + command not found + +✻ Cooked for 10m 22s + +❯ I accept recommended answers + +⏺ All accepted. One fact gates the next round — whether the tracking DB's + conversationId actually matches the transcript UUIDs — so let me check that + now. + + Read 1 file, listed 1 directory, ran 2 shell commands (ctrl+o to expand) + +⏺ Write(CONTEXT.md) + ⎿  Wrote 24 lines to CONTEXT.md + 1 # CodeMie Code Analytics + 2 + lytics. CodeMie both launches agents itself and reads usage left + behind by agents it never launched; the vocabulary below keeps th + ose apart. + 5 ## Language + 6 + 7 **Managed agent**: + codex, gemini, copilot-cli). + 9 _Avoid_: installed agent, native agent + … +25 lines (ctrl+o to expand) + ⎿  PostToolUse:Write hook returned blocking error + ⎿  [cd "$CLAUDE_PROJECT_DIR" && npm run format]: + Oops! Something went wrong! :( + + ESLint: 9.39.2 + + Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' imported + from /Users/gokhan_ozdemir/.herdr/worktrees/codemie-code/wt-feature-cursor- + analytics-support/eslint.config.mjs + at Object.getPackageJSONURL + (node:internal/modules/package_json_reader:301:9) + at packageResolve (node:internal/modules/esm/resolve:784:25) + at moduleResolve (node:internal/modules/esm/resolve:873:18) + at defaultResolve (node:internal/modules/esm/resolve:1006:11) + at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20) + at #resolveAndMaybeBlockOnLoaderThread + (node:internal/modules/esm/loader:728:38) + at ModuleLoader.resolveSync (node:internal/modules/esm/loader:766:56) + at #resolve (node:internal/modules/esm/loader:690:17) + at ModuleLoader.getOrCreateModuleJob + (node:internal/modules/esm/loader:610:35) + at ModuleJob.syncLink (node:internal/modules/esm/module_job:277:33) +⏺ CONTEXT.md is created (the post-write format hook fails because this worktree + has no node_modules — npm install hasn't been run here; worth knowing before + implementation, since that hook will complain on every edit). + + Final round — the last open decisions: + + ❓ Q10 - DB-only conversations: ai_code_hashes contains conversations with no + transcript on disk (e.g. IDE composer sessions such as 484a9c01…, and 474 rows + attributed to human). Should the adapter (a) create session rows only for + transcript-backed sessions, using the DB purely as enrichment (model, file + names, activity window), or (b) also synthesize rows for DB-only conversations + to capture IDE composer usage? + + ➡️ (a). A transcript is what makes something a session in this model; DB-only + rows have no prompts/turns and would produce ghost sessions with almost every + column empty. IDE-composer coverage can be a follow-up if you miss it. + + --- + ❓ Q11 - What a Cursor session row shows: Concretely, per transcript-backed + session: prompts and turns from the JSONL; project/cwd from the directory + slug; start/end from DB timestamps when the join hits, else file + birth/modification time; model from the DB (with the literal default treated + as unknown, per the Q8 rule against fabricating model names); files-touched + set from ai_code_hashes.fileName; tokens, cost, and lines added/removed left + blank (not derivable). Acceptable? + + ➡️ Yes — this is the maximum honest extraction from what Cursor persists. + + --- + ❓ Q12 - Discovery window: Follow the copilot-cli convention — default + maxAgeDays 30, honor the adapter's cwd filtering — with no Cursor-specific + knobs? + + ➡️ Yes, pure convention-following. + + --- + ❓ Q13 - Stale doc while we're there: The exploration found AGENTS.md still + describes copilot-cli as "Analytics ingestion only", but the code has since + made it a fully managed agent. When adding the cursor row to the plugin table, + should I also correct the stale copilot-cli row, or leave it untouched? + + ➡️ Correct it in the same change — the repo's own policy is to report/fix + stale guides, and touching the same table twice in two PRs is churn. + + Answer these and the frontier is empty — I'll then summarize the shared + understanding for your confirmation before any implementation. + +⏺ Ran 3 stop hooks (ctrl+o to expand) + ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: + command not found + +✻ Sautéed for 1m 34s + +❯ I accept recommended answers. + also here is a sample output report that does not include cursor usage. + file:///Users/gokhan_ozdemir/Sites/airun-coach-cockpit/codemie-analytics-gokh + an-ozdemir-epam-com-2026-09-03.html + generated with "codemie analytics show --include-external --report --open" + + Ran 1 shell command (ctrl+o to expand) + +⏺ Your sample report confirms the diagnosis: it contains only claude, codex, and + copilot-cli rows (194 of them tagged native-external) — Cursor is absent + because no adapter exists for it, not because of the flag. + + The frontier is empty. Here is the shared understanding we've built: + + Problem: Cursor usage never appears in codemie analytics because CodeMie has + no Cursor session adapter. The --include-external flag was never the lever — + it gates unowned sessions of managed agents. + + Design: + 1. New analytics-only plugin cursor (src/agents/plugins/cursor/, label + "Cursor") with analyticsOnly: true — sessions tagged native-unmanaged, visible + by default, no flag needed. Registered in AgentRegistry and added to + NATIVE_AGENTS in native-loader.ts. + 2. Data sources (read-only, fail-soft): session rows come from + ~/.cursor/projects//agent-transcripts//.jsonl (prompts, turns, + project); enrichment joins ~/.cursor/ai-tracking/ai-code-tracking.db on + conversationId for model, files touched, and activity timestamps, falling back + to file birth/mtime. DB-only conversations (IDE composer, human rows) produce + no session rows. The opaque chats/*/store.db is out of scope. + 3. Honest gaps: tokens, cost, and line counts stay blank (Cursor doesn't + persist them); model shows unknown when the DB has none or says the literal + default — never stamped from cli-config.json. + 4. Conventions: maxAgeDays 30 default, standard cwd filtering, labels/colors + added in agent-labels.ts and the duplicated table in report/client/app.js. + 5. Docs: add the cursor row to the AGENTS.md plugin table and fix the stale + copilot-cli "analytics ingestion only" row in the same change. + + Also captured: a new CONTEXT.md at the repo root with the managed / + analytics-only / external / unmanaged glossary. Two practical notes for + implementation time: this worktree has no node_modules (the format hook fails + on every write until npm install runs), and your installed CLI accepts + analytics show while this branch's source registers the options on codemie + analytics directly — worth a version check when validating. + + Confirm this matches your intent and I'll start implementing. + +⏺ Ran 3 stop hooks (ctrl+o to expand) + ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: + command not found + +✻ Worked for 23s + +❯ crete /to-spec and /to-tickets based on what you've learned + +⏺ Skill(writing-for-agents) + ⎿  Successfully loaded skill + + Read 1 file, listed 1 directory (ctrl+o to expand) + +⏺ to-spec and to-tickets already exist in your skills directory — let me look + before overwriting. + + Ran 1 shell command (ctrl+o to expand) + +⏺ These already exist as skills in your library — so I'll run them on what we + just grilled: /to-spec first (it needs a seam check with you before + publishing), then /to-tickets. + +⏺ Skill(to-spec) + ⎿  Successfully loaded skill + +⏺ User answered Claude's questions: + ⎿  · Does the proposed test seam match your expectations — one seam, the + Cursor SessionAdapter (discoverSessions/parseSessionFile) tested against a + fixture ~/.cursor tree via a CURSOR_HOME-style override, mirroring the + copilot-cli test prior art? → Higher: loader seam + · Where should the spec (and later the tickets) be published? → GitHub + issues + +⏺ Seam settled at the loader (loadNativeSessions()), publishing to GitHub + issues. Writing the spec now. + + Made 1 scratchpad edit +64, ran 2 shell commands (ctrl+o to expand) + ⎿  PostToolUse:Write hook returned blocking error + ⎿  [cd "$CLAUDE_PROJECT_DIR" && npm run format]: + Oops! Something went wrong! :( + + ESLint: 9.39.2 + + Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' imported + from /Users/gokhan_ozdemir/.herdr/worktrees/codemie-code/wt-feature-cursor- + analytics-support/eslint.config.mjs + at Object.getPackageJSONURL + (node:internal/modules/package_json_reader:301:9) + at packageResolve (node:internal/modules/esm/resolve:784:25) + at moduleResolve (node:internal/modules/esm/resolve:873:18) + at defaultResolve (node:internal/modules/esm/resolve:1006:11) + at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20) + at #resolveAndMaybeBlockOnLoaderThread + (node:internal/modules/esm/loader:728:38) + at ModuleLoader.resolveSync (node:internal/modules/esm/loader:766:56) + at #resolve (node:internal/modules/esm/loader:690:17) + at ModuleLoader.getOrCreateModuleJob + (node:internal/modules/esm/loader:610:35) + at ModuleJob.syncLink (node:internal/modules/esm/module_job:277:33) + +⏺ The fork has issues disabled — enabling them, since you chose GitHub issues as + the tracker. + + Ran 1 shell command (ctrl+o to expand) + +⏺ Spec published: https://github.com/gokhanozdemir/codemie-code/issues/1 (issues + were disabled on the fork; I enabled them). Now /to-tickets. + +⏺ Skill(to-tickets) + ⎿  Successfully loaded skill +⏺ All context is in hand from the grilling and spec. Here's the proposed + tracer-bullet breakdown: + + 1. Cursor sessions appear in codemie analytics (transcripts only) + - Blocked by: none (can start immediately) + - Delivers: the core tracer bullet — a cursor analytics-only plugin (registry + entry, native-agents list, Cursor-home resolution with env override, session + adapter over transcript JSONLs) so that running codemie analytics shows Cursor + sessions tagged unmanaged, visible by default, with prompts/turns/project and + file-time timestamps; tokens/cost/model honestly blank; CLI agent label + "Cursor". Missing Cursor home yields zero rows, no error. Demoable end-to-end + on your machine immediately. + + 2. Enrich Cursor sessions from the AI-tracking database + - Blocked by: 1 + - Delivers: sessions gain model (with the literal default shown as unknown), + files-touched set, and accurate activity windows via the read-only + conversation-id join; a missing or schema-drifted database degrades cleanly + back to ticket 1 behavior. Demo: your grok-4.6 sessions show their model. + + 3. Cursor in the HTML report surfaces + - Blocked by: 1 + - Delivers: --report --open renders Cursor with its own label and color in the + Agents view and everywhere agents are listed; Cursor sessions classify as + "pure chat" in Frameworks compare. Demo: regenerate your sample report and + Cursor appears. + + 4. Docs: AGENTS.md plugin table + - Blocked by: 1 + - Delivers: the plugin table documents cursor (analytics ingestion only) and + corrects the stale copilot-cli "analytics ingestion only" row to managed-agent + status. + + 5. Loader-seam tests with fixture Cursor home + - Blocked by: 1, 2 + - Delivers: Vitest coverage at the loadNativeSessions() seam against a fixture + Cursor home (transcripts + fixture SQLite DB): discovery, unmanaged tagging, + default visibility, enrichment hit, fail-soft degradation, empty-home case. + (Included because you chose the seam explicitly — cut it if you'd rather defer + per the tests-on-request policy.) + + Quiz before publishing: + - Does the granularity feel right? (1 is the largest; it mirrors the existing + copilot-cli adapter shape, so I'd keep it whole rather than split + discovery/parse.) + - Blocking edges correct? Notably 2, 3, 4 are all parallel once 1 lands — only + 5 waits on two tickets. + - Keep, merge, or drop ticket 5? + +⏺ Ran 3 stop hooks (ctrl+o to expand) + ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: + command not found + +✻ Churned for 4m 8s + +※ recap: Goal: add Cursor usage to codemie analytics. Spec is published as GitHub issue #1; I've drafted five tickets and need your approval of the breakdown (granularity, blocking edges, keep or drop the tests ticket) before publishing them. (disable recaps in /config) + +❯ Breakdown looks right, publish the tickets + + Ran 5 shell commands, wrote 1 memory (ctrl+o to expand) + ⎿  PostToolUse:Write hook returned blocking error + ⎿  [cd "$CLAUDE_PROJECT_DIR" && npm run format]: + Oops! Something went wrong! :( + + ESLint: 9.39.2 + + Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' imported + from /Users/gokhan_ozdemir/.herdr/worktrees/codemie-code/wt-feature-cursor- + analytics-support/eslint.config.mjs + at Object.getPackageJSONURL + (node:internal/modules/package_json_reader:301:9) + at packageResolve (node:internal/modules/esm/resolve:784:25) + at moduleResolve (node:internal/modules/esm/resolve:873:18) + at defaultResolve (node:internal/modules/esm/resolve:1006:11) + at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20) + at #resolveAndMaybeBlockOnLoaderThread + (node:internal/modules/esm/loader:728:38) + at ModuleLoader.resolveSync (node:internal/modules/esm/loader:766:56) + at #resolve (node:internal/modules/esm/loader:690:17) + at ModuleLoader.getOrCreateModuleJob + (node:internal/modules/esm/loader:610:35) + at ModuleJob.syncLink (node:internal/modules/esm/module_job:277:33) + +⏺ All five tickets are published and labeled ready-for-agent on your fork, each + linking the spec (#1) as parent and declaring its blocking edges: + + - #3 — Cursor sessions in codemie analytics (transcript-backed tracer bullet) + — no blockers, the frontier starts here + - #4 — Enrich Cursor sessions from the AI-tracking database — blocked by #3 + - #5 — Cursor in the HTML report surfaces — blocked by #3 + - #6 — Docs: cursor + stale copilot-cli rows in AGENTS.md — blocked by #3 + - #7 — Loader-seam tests with fixture Cursor home — blocked by #3 and #4 + + Once #3 lands, #4/#5/#6 can run in parallel. I also saved a project memory + pointing at the spec, tickets, and the verified Cursor data-format facts, so a + future session can pick this up cold. When you're ready to build, + /implement-spec pointed at issue #1 fits this graph directly — just note the + worktree needs npm install first (the format hook currently fails on every + file write without it). + +⏺ Ran 3 stop hooks (ctrl+o to expand) + ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: + command not found + +✻ Cooked for 3m 22s + +※ recap: Goal: add Cursor usage to codemie analytics as an analytics-only agent. Design was grilled, spec published as issue #1 with tickets #3–#7 on your fork. Next action: implement ticket #3, running npm install in the worktree first. (disable recaps in /config) \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 8880cda65..a9336e380 100644 --- a/package-lock.json +++ b/package-lock.json @@ -56,6 +56,7 @@ "codemie-kimi-acp": "bin/codemie-kimi-acp.js", "codemie-mcp-proxy": "bin/codemie-mcp-proxy.js", "codemie-opencode": "bin/codemie-opencode.js", + "codemie-openwiki": "bin/codemie-openwiki.js", "codemie-pi": "bin/codemie-pi.js", "proxy-daemon": "bin/proxy-daemon.js" }, @@ -84,9 +85,6 @@ "node": ">=20.0.0" } }, - "../codemie-sdk": { - "extraneous": true - }, "node_modules/@aws-crypto/crc32": { "version": "5.2.0", "resolved": "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz", @@ -3693,7 +3691,7 @@ "version": "20.19.25", "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.25.tgz", "integrity": "sha512-ZsJzA5thDQMSQO788d7IocwwQbI8B5OPzmqNvpf3NY/+MHDAS759Wo0gd2WQeXYt5AAAQjzcrTVC6SKCuYgoCQ==", - "dev": true, + "devOptional": true, "license": "MIT", "dependencies": { "undici-types": "~6.21.0" @@ -9342,7 +9340,7 @@ "version": "6.21.0", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", - "dev": true, + "devOptional": true, "license": "MIT" }, "node_modules/unicorn-magic": { @@ -9781,27 +9779,6 @@ "funding": { "url": "https://github.com/sponsors/colinhacks" } - }, - "web/analytics": { - "name": "@codemieai/analytics-web", - "version": "0.0.11", - "extraneous": true, - "dependencies": { - "@tanstack/react-query": "^5.14.0", - "date-fns": "^3.0.0", - "react": "^18.2.0", - "react-dom": "^18.2.0", - "recharts": "^2.10.3" - }, - "devDependencies": { - "@types/react": "^18.2.43", - "@types/react-dom": "^18.2.17", - "@vitejs/plugin-react": "^4.2.1", - "autoprefixer": "^10.4.16", - "postcss": "^8.4.32", - "tailwindcss": "^3.4.0", - "vite": "^5.0.8" - } } } } diff --git a/src/agents/plugins/cursor/cursor.plugin.ts b/src/agents/plugins/cursor/cursor.plugin.ts index 45dcbc3ec..b2718e6a2 100644 --- a/src/agents/plugins/cursor/cursor.plugin.ts +++ b/src/agents/plugins/cursor/cursor.plugin.ts @@ -9,9 +9,10 @@ * management surface (install, uninstall, update, list, doctor, first-run). `codemie update` * in particular would otherwise run `npm install -g` against a package Cursor does not have. * - the analytics ownership gate (`isAnalyticsOnlyAgent` in `native-loader.ts`) skips it. - * That gate exists to hide unmanaged runs of an agent CodeMie CAN manage; Cursor has no - * managed variant, so applying it would tag every Cursor session `native-external` and drop - * the whole agent from the default report. + * That gate exists to hide *external* sessions — runs of an agent CodeMie CAN manage that it + * did not launch. Cursor has no managed variant, so its sessions are *unmanaged* rather than + * external; applying the gate would tag every one `native-external` and drop the whole agent + * from the default report. (See `CONTEXT.md` for both terms.) * * There is therefore no npm package, no CLI command, no env mapping and no provider list — * none of the launch machinery is ever reached. The plugin exists solely to hand the registry diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index dc29235df..ba59696e4 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -8,11 +8,13 @@ * discovery keys on the presence of `agent-transcripts` rather than on the directory name. * * What a transcript can and cannot tell us is the whole design constraint here. It carries - * role-tagged text, tool_use blocks and turn markers — and nothing else. No timestamps, no - * model, no token counts. So: + * role-tagged text, tool_use blocks, turn markers, and a human-readable stamp on each prompt — + * but no model and no token counts. So: * * - the activity window comes from Cursor's own first/last recorded edit, falling back to the - * transcript file's birthtime/mtime, which is when Cursor created and last appended to it; + * prompt stamps, and only then to the transcript file's birthtime/mtime — file times measure + * when the file was touched, so a conversation resumed days later would otherwise report a + * span of days rather than of minutes; * - messages are emitted deliberately WITHOUT timestamps, so the native loader falls back to * the descriptor's window instead of a fabricated per-message clock; * - `usageMeta.usageUnavailableReason` is always set, which is what makes the report render @@ -51,10 +53,12 @@ import { CURSOR_AGENT_NAME } from './cursor.constants.js'; import { getCursorProjectsRoot } from './cursor.paths.js'; import type { CursorConversationActivity, CursorTrackingIndex } from './cursor.tracking-db.js'; import { readCursorTrackingIndex } from './cursor.tracking-db.js'; +import type { CursorMessageLine, CursorTranscriptLine } from './cursor.transcript.js'; import { contentBlocks, isMessageLine, readCursorTranscript, + transcriptStampWindow, userQueryText, } from './cursor.transcript.js'; import { logger } from '../../../utils/logger.js'; @@ -86,15 +90,56 @@ function sameDir(a: string | undefined, b: string): boolean { /** * Best-effort project path for a Cursor project slug. * - * The slug is lossy: Cursor replaces both `/` and `_` with `-`, so `/Users/x/Sites/foo_bar` - * and `/Users/x/Sites/foo-bar` produce the same slug and reversal cannot be trusted. Rather - * than report a path that may not be the user's, the naive de-slug is only accepted when it - * names a directory that actually exists; otherwise the session is reported without a project - * and the report shows it as unknown. An honest gap beats a plausible-looking wrong answer. + * The slug is lossy in two directions at once: Cursor replaces `/` and `_` alike with `-`, and + * a directory name may contain `-` of its own. So a `-` in a slug can mean any of three things, + * and splitting on it cannot work — `Users-ada_lovelace-claude-code-router` would de-slug to + * `/Users/ada/lovelace/claude/code/router`, which is nobody's project. That naive reversal is + * why nearly every session used to report no project at all. + * + * Instead of guessing at the string, this walks the filesystem and lets it decide: from the + * root, only descend into a child whose own slug matches the next tokens of the slug being + * resolved. Each step is verified against a directory that exists, so the result is Cursor's + * own naming confirmed rather than a plausible-looking reconstruction — the same principle + * {@link projectPathFromFiles} already applies to the tracking database's file paths. When no + * branch consumes the whole slug the session stays silent about its project: an honest gap + * still beats a wrong answer. + */ +function projectPathFromSlug(slug: string, cache?: Map): string | undefined { + const cached = cache?.get(slug); + if (cached !== undefined || cache?.has(slug)) { + return cached; + } + const resolved = descendMatchingSlug(sep, slug.split('-')); + cache?.set(slug, resolved); + return resolved; +} + +/** + * Deepest existing directory reached by consuming every token of a slug. + * + * A child matches when its own name, slugified, equals the tokens it would have to account + * for. Recursion (rather than a single greedy pass) is what makes `foo-bar/baz` and + * `foo/bar-baz` both reachable from `foo-bar-baz`; the first branch that consumes the slug + * whole wins, and there is only ever one such branch on a real filesystem. */ -function projectPathFromSlug(slug: string): string | undefined { - const candidate = sep + slug.split('-').join(sep); - return existsSync(candidate) ? candidate : undefined; +function descendMatchingSlug(dir: string, tokens: string[]): string | undefined { + if (tokens.length === 0) { + return dir; + } + for (const name of readDirNames(dir)) { + const nameTokens = slugForPath(name).split('-'); + if (nameTokens.length > tokens.length) { + continue; + } + if (!nameTokens.every((token, i) => token === tokens[i])) { + continue; + } + const found = descendMatchingSlug(join(dir, name), tokens.slice(nameTokens.length)); + if (found) { + return found; + } + } + return undefined; } /** The slug Cursor would have written for a directory: leading separator dropped, `/` and `_` → `-`. */ @@ -143,11 +188,17 @@ function projectPathFromFiles(slug: string, files: string[]): string | undefined } } -/** Directory entries of `dir`, or an empty list when it cannot be read. */ +/** + * Subdirectory names of `dir`, or an empty list when it cannot be read. + * + * Symlinked directories count. On macOS `/var` — the ancestor of every temporary directory, and + * of plenty of real project trees — is a symlink, and `isDirectory()` is false for a symlink, so + * filtering on it alone would make the slug walk give up at the first step. + */ function readDirNames(dir: string): string[] { try { return readdirSync(dir, { withFileTypes: true }) - .filter((entry) => entry.isDirectory()) + .filter((entry) => entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(join(dir, entry.name)))) .map((entry) => entry.name); } catch (error) { logger.debug(`[cursor-discovery] failed to read ${dir}:`, error); @@ -155,13 +206,22 @@ function readDirNames(dir: string): string[] { } } +/** Whether `path` is a directory, following symlinks. False when it cannot be stat'd. */ +function isDirectory(path: string): boolean { + try { + return statSync(path).isDirectory(); + } catch { + return false; + } +} + /** - * When the transcript was created and last written. + * When the transcript file was created and last written. * * Some filesystems report a zero birthtime; mtime is then the only timestamp available and * collapses the window to a point, which is still truthful about "when this happened". */ -function transcriptWindow(filePath: string): { createdAt: number; updatedAt: number } | undefined { +function fileWindow(filePath: string): { createdAt: number; updatedAt: number } | undefined { try { const stats = statSync(filePath); const updatedAt = stats.mtimeMs; @@ -173,6 +233,36 @@ function transcriptWindow(filePath: string): { createdAt: number; updatedAt: num } } +/** + * When a conversation ran, best source first. + * + * Cursor's own recorded edits are the strongest signal but exist only for conversations that + * changed a file. The prompt stamps in the transcript cover the rest and still describe the + * work rather than the file, so they come before the file's own times — those measure when the + * transcript was touched and stretch a resumed conversation across the whole gap. + */ +function activityWindow( + filePath: string, + activity: CursorConversationActivity | undefined +): { createdAt: number; updatedAt: number } | undefined { + const stamps = activity?.firstEditMs === undefined ? transcriptStampWindow(filePath) : undefined; + const createdAt = activity?.firstEditMs ?? stamps?.firstMs; + const updatedAt = activity?.lastEditMs ?? stamps?.lastMs; + + if (createdAt === undefined || updatedAt === undefined) { + const file = fileWindow(filePath); + if (!file) { + return undefined; + } + return { + createdAt: createdAt ?? file.createdAt, + updatedAt: Math.max(createdAt ?? file.createdAt, updatedAt ?? file.updatedAt), + }; + } + + return { createdAt, updatedAt: Math.max(createdAt, updatedAt) }; +} + /** The Claude-shaped message the native loader's default synthesis branch understands. */ interface CursorNativeMessage { type: 'user' | 'assistant'; @@ -206,6 +296,69 @@ function applyModels(messages: CursorNativeMessage[], models: string[]): void { }); } +/** What one transcript's lines amount to, once the shape Cursor writes is set aside. */ +interface FlattenedTranscript { + messages: CursorNativeMessage[]; + userPrompts: Array<{ count: number; text: string }>; + tools: Record; +} + +/** The text of one line's content blocks, counting any tool_use it names along the way. */ +function textOfLine(line: CursorMessageLine, tools: Record): string { + const texts: string[] = []; + for (const block of contentBlocks(line)) { + if (block.type === 'tool_use') { + const name = (block as { name?: string }).name; + if (name) { + tools[name] = (tools[name] ?? 0) + 1; + } + continue; + } + const text = (block as { text?: string }).text; + if (typeof text === 'string' && text.trim()) { + texts.push(text); + } + } + return texts.join('\n'); +} + +/** + * Transcript lines as the message stream the native loader understands. + * + * Turn markers are skipped: they carry no fact the message stream does not already imply, since + * the loader derives the turn count from assistant messages. + */ +function flattenTranscript(lines: CursorTranscriptLine[]): FlattenedTranscript { + const messages: CursorNativeMessage[] = []; + const userPrompts: Array<{ count: number; text: string }> = []; + const tools: Record = {}; + + for (const line of lines) { + if (!isMessageLine(line)) { + continue; + } + const role = line.role === 'assistant' ? 'assistant' : line.role === 'user' ? 'user' : undefined; + if (!role) { + continue; + } + + const joined = textOfLine(line, tools); + // Cursor wraps a prompt in /; unwrap it so the report's session + // title reads as the user's question rather than as a date. + const content = role === 'user' ? (userQueryText(joined) ?? joined) : joined; + if (!content.trim()) { + continue; + } + + messages.push({ type: role, message: { role, content } }); + if (role === 'user') { + userPrompts.push({ count: 1, text: content }); + } + } + + return { messages, userPrompts, tools }; +} + /** * Files the agent wrote, as file operations. * @@ -297,6 +450,9 @@ export class CursorSessionAdapter implements SessionAdapter { const tracking = await this.trackingIndex(); const results: SessionDescriptor[] = []; + // Resolving a slug walks the filesystem, and every conversation in a project repeats the + // same slug, so the answer is worked out once per project per run. + const slugPaths = new Map(); for (const slug of readDirNames(root)) { const transcriptsRoot = join(root, slug, TRANSCRIPTS_DIR); @@ -304,40 +460,15 @@ export class CursorSessionAdapter implements SessionAdapter { continue; } - const slugPath = projectPathFromSlug(slug); - for (const conversationId of readDirNames(transcriptsRoot)) { - const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); - if (!existsSync(filePath)) { - continue; - } - - const window = transcriptWindow(filePath); - if (!window) { + const descriptor = this.describeConversation(transcriptsRoot, conversationId, slug, tracking, slugPaths); + if (!descriptor || descriptor.createdAt < cutoffMs) { continue; } - - // A conversation that exists only in the database has no transcript and never reaches - // this point — the file loop above is the sole source of session identity. - const activity = tracking.get(conversationId); - const projectPath = projectPathFromFiles(slug, activity?.files ?? []) ?? slugPath; - if (options?.cwd && !sameDir(projectPath, options.cwd)) { + if (options?.cwd && !sameDir(descriptor.projectPath, options.cwd)) { continue; } - - const createdAt = activity?.firstEditMs ?? window.createdAt; - if (createdAt < cutoffMs) { - continue; - } - - results.push({ - sessionId: conversationId, - filePath, - projectPath, - createdAt, - updatedAt: Math.max(createdAt, activity?.lastEditMs ?? window.updatedAt), - agentName: this.agentName, - }); + results.push(descriptor); } } @@ -352,6 +483,44 @@ export class CursorSessionAdapter implements SessionAdapter { return results; } + /** + * One conversation as a descriptor, or undefined when it has no transcript on disk. + * + * The descriptor — not the parsed session — is where the project and the window have to land: + * Cursor's messages carry no timestamps and no cwd, so the native loader's default synthesis + * reads exactly those facts off the descriptor. + */ + private describeConversation( + transcriptsRoot: string, + conversationId: string, + slug: string, + tracking: CursorTrackingIndex, + slugPaths: Map + ): SessionDescriptor | undefined { + const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); + if (!existsSync(filePath)) { + return undefined; + } + + // A conversation that exists only in the database has no transcript and never reaches this + // point — the transcript file is the sole source of session identity. + const activity = tracking.get(conversationId); + const window = activityWindow(filePath, activity); + if (!window) { + return undefined; + } + + return { + sessionId: conversationId, + filePath, + projectPath: + projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, slugPaths), + createdAt: window.createdAt, + updatedAt: window.updatedAt, + agentName: this.agentName, + }; + } + /** * Parse one conversation transcript. * @@ -363,55 +532,11 @@ export class CursorSessionAdapter implements SessionAdapter { const lines = readCursorTranscript(filePath); const activity = (await this.trackingIndex()).get(conversationId); - const messages: CursorNativeMessage[] = []; - const userPrompts: Array<{ count: number; text: string }> = []; - const tools: Record = {}; - - for (const line of lines) { - if (!isMessageLine(line)) { - // Turn markers carry no facts the message stream does not already imply — the loader - // derives the turn count from assistant messages. - continue; - } - const role = line.role === 'assistant' ? 'assistant' : line.role === 'user' ? 'user' : undefined; - if (!role) { - continue; - } - - const texts: string[] = []; - for (const block of contentBlocks(line)) { - if (block.type === 'tool_use') { - const name = (block as { name?: string }).name; - if (name) { - tools[name] = (tools[name] ?? 0) + 1; - } - continue; - } - const text = (block as { text?: string }).text; - if (typeof text === 'string' && text.trim()) { - texts.push(text); - } - } - - const joined = texts.join('\n'); - // Cursor wraps a prompt in /; unwrap it so the report's session - // title reads as the user's question rather than as a date. - const content = role === 'user' ? (userQueryText(joined) ?? joined) : joined; - if (!content.trim()) { - continue; - } - - messages.push({ type: role, message: { role, content } }); - if (role === 'user') { - userPrompts.push({ count: 1, text: content }); - } - } + const { messages, userPrompts, tools } = flattenTranscript(lines); applyModels(messages, activity?.models ?? []); - const window = transcriptWindow(filePath); - const startMs = activity?.firstEditMs ?? window?.createdAt; - const endMs = activity?.lastEditMs ?? window?.updatedAt; + const window = activityWindow(filePath, activity); const slug = slugOfTranscript(filePath); const projectPath = projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug); @@ -424,8 +549,8 @@ export class CursorSessionAdapter implements SessionAdapter { agentName: this.metadata.displayName, metadata: { projectPath, - createdAt: startMs === undefined ? undefined : new Date(startMs).toISOString(), - updatedAt: endMs === undefined ? undefined : new Date(endMs).toISOString(), + createdAt: window === undefined ? undefined : new Date(window.createdAt).toISOString(), + updatedAt: window === undefined ? undefined : new Date(window.updatedAt).toISOString(), }, // No per-message timestamps exist, and inventing them would make the report show a // duration Cursor never recorded. Leaving them out makes the loader fall back to the diff --git a/src/agents/plugins/cursor/cursor.transcript.ts b/src/agents/plugins/cursor/cursor.transcript.ts index de4377080..ab891672c 100644 --- a/src/agents/plugins/cursor/cursor.transcript.ts +++ b/src/agents/plugins/cursor/cursor.transcript.ts @@ -3,8 +3,9 @@ * * The format is thin and undocumented: each line is either a role-tagged message * (`{role, message: {content: [...]}}`) or a turn marker (`{type: 'turn_ended', status}`). - * There are no timestamps, no model, no tokens and no tool results — everything else the - * report shows comes from `cursor.tracking-db.ts`. + * There is no model, no token count and no tool result — those come from + * `cursor.tracking-db.ts`. The one timing signal a transcript does carry is the human-readable + * `` Cursor writes ahead of every prompt; see {@link transcriptStampWindow}. * * A live session's final line can be truncated mid-write, so unparseable lines are dropped * rather than thrown: one bad line must not discard a whole session. @@ -14,14 +15,14 @@ import { readFileSync } from 'fs'; import { logger } from '../../../utils/logger.js'; /** A `tool_use` block inside an assistant message. */ -export interface CursorToolUseBlock { +interface CursorToolUseBlock { type: 'tool_use'; name?: string; input?: Record; } /** A plain text block inside a message. */ -export interface CursorTextBlock { +interface CursorTextBlock { type: 'text'; text?: string; } @@ -35,7 +36,7 @@ export interface CursorMessageLine { } /** A control line, e.g. `{"type":"turn_ended","status":"success"}`. */ -export interface CursorMarkerLine { +interface CursorMarkerLine { type: string; status?: string; } @@ -46,10 +47,6 @@ export function isMessageLine(line: CursorTranscriptLine): line is CursorMessage return typeof (line as CursorMessageLine).role === 'string'; } -export function isMarkerLine(line: CursorTranscriptLine): line is CursorMarkerLine { - return !isMessageLine(line) && typeof (line as CursorMarkerLine).type === 'string'; -} - /** The content blocks of a message, normalized to an array (a bare string becomes one text block). */ export function contentBlocks(line: CursorMessageLine): CursorContentBlock[] { const content = line.message?.content; @@ -93,6 +90,71 @@ export function readCursorTranscript(filePath: string): CursorTranscriptLine[] { return lines; } +const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']; + +/** + * The stamp Cursor writes ahead of every prompt, e.g. + * `Monday, Aug 31, 2026, 5:46 PM (UTC+3)`. The weekday is ignored — it carries no information + * the date does not — and the explicit offset is what makes the instant unambiguous. + */ +const STAMP_PATTERN = + /([A-Z][a-z]{2})\s+(\d{1,2}),\s*(\d{4}),\s*(\d{1,2}):(\d{2})\s*(AM|PM)\s*\(UTC([+-]\d{1,2})(?::(\d{2}))?\)/gi; + +function pad(value: number): string { + return String(value).padStart(2, '0'); +} + +/** One Cursor stamp as epoch ms, or undefined when it is not a shape we recognise. */ +function stampToEpochMs(match: RegExpExecArray): number | undefined { + const [, month, day, year, hour12, minute, meridiem, offsetHours, offsetMinutes] = match; + const monthIndex = MONTHS.indexOf(month.toLowerCase()); + if (monthIndex < 0) { + return undefined; + } + const hour = Number(hour12) % 12 + (meridiem.toUpperCase() === 'PM' ? 12 : 0); + const offsetSign = offsetHours.startsWith('-') ? '-' : '+'; + const offset = `${offsetSign}${pad(Math.abs(Number(offsetHours)))}:${pad(Number(offsetMinutes ?? 0))}`; + const parsed = Date.parse( + `${year}-${pad(monthIndex + 1)}-${pad(Number(day))}T${pad(hour)}:${pad(Number(minute))}:00${offset}` + ); + return Number.isNaN(parsed) ? undefined : parsed; +} + +/** + * When the conversation actually ran, from the stamps Cursor writes into the prompts. + * + * This is the only in-transcript timing signal, and for a conversation the AI-tracking database + * never recorded an edit for it is the only honest one available. The alternative — the + * transcript file's birthtime and mtime — measures when the file was touched, not when the work + * happened, so a conversation resumed days later reports a span of days instead of of minutes. + * + * Scans the raw text rather than the parsed lines: this runs during discovery, for sessions that + * may yet be filtered out, so it must not pay for JSON parsing. Undefined when nothing is + * stamped, which is the caller's cue to fall back to file times. + */ +export function transcriptStampWindow(filePath: string): { firstMs: number; lastMs: number } | undefined { + let text: string; + try { + text = readFileSync(filePath, 'utf-8'); + } catch (error) { + logger.debug(`[cursor] unreadable transcript at ${filePath}:`, error); + return undefined; + } + + let firstMs: number | undefined; + let lastMs: number | undefined; + for (const match of text.matchAll(STAMP_PATTERN)) { + const ms = stampToEpochMs(match); + if (ms === undefined) { + continue; + } + firstMs = firstMs === undefined || ms < firstMs ? ms : firstMs; + lastMs = lastMs === undefined || ms > lastMs ? ms : lastMs; + } + + return firstMs === undefined || lastMs === undefined ? undefined : { firstMs, lastMs }; +} + /** * The user's own words in a Cursor user message. * diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index 320e28cb3..54227d5b1 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -368,8 +368,8 @@ describe('loadNativeSessions — Cursor degrades to transcript-only rows', () => expect(row.sessionId).toBe('conv-a'); expect(row.deltas[0].models).toEqual([]); expect(row.deltas[0].fileOperations).toEqual([]); - // No database means no project attribution either — reported as unknown, never guessed. - expect(row.startEvent!.data.workingDirectory).toBe('Unknown'); + // The project still resolves without a database: the slug is walked against the filesystem. + expect(row.startEvent!.data.workingDirectory).toBe(projectDir); // The window falls back to the transcript file's own birth/modification times. expect(row.startEvent!.data.startTime).toBeGreaterThan(0); }); @@ -448,3 +448,104 @@ describe('loadNativeSessions — Cursor never reports tokens, cost or line count expect(operation.linesModified).toBeUndefined(); }); }); + +/** + * Cursor's project slug is lossy — it replaces `/` and `_` alike with `-` — so a slug cannot be + * reversed by splitting on `-`. Nearly every real project trips this: a home directory like + * `/Users/ada_lovelace` or any project named `claude-code-router` de-slugs to a path that does + * not exist, and the session loses its project. These tests pin the recovery, and they use no + * tracking database on purpose: the database covers only the conversations it recorded edits + * for, so the slug is the only project signal the majority of sessions have. + */ +describe('loadNativeSessions — Cursor project attribution from a lossy slug', () => { + it('recovers a project whose directory name contains a hyphen', async () => { + const project = join(projectDir, 'claude-code-router'); + mkdirSync(project, { recursive: true }); + writeTranscript('conv-hyphen', conversation('ship it'), slugForPath(project)); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.workingDirectory).toBe(project); + }); + + it('recovers a project whose path contains an underscore', async () => { + const project = join(projectDir, 'my_project'); + mkdirSync(project, { recursive: true }); + writeTranscript('conv-underscore', conversation('ship it'), slugForPath(project)); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.workingDirectory).toBe(project); + }); + + it('stays silent rather than guessing when no candidate directory exists', async () => { + writeTranscript('conv-gone', conversation('ship it'), 'Users-nobody-vanished-project'); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.workingDirectory).toBe('Unknown'); + }); +}); + +/** + * Cursor stamps every user prompt with a human-readable ``. It is the only timing + * signal for a conversation the tracking database never recorded an edit for, and it beats the + * transcript file's birth/modification times badly: file times measure when the file was + * touched, so a session resumed days later reports a span of days rather than of minutes. + */ +describe('loadNativeSessions — Cursor activity window from transcript timestamps', () => { + /** A user line stamped the way Cursor writes it. */ + function stampedUserLine(stamp: string, text: string): unknown { + return { + role: 'user', + message: { + content: [{ type: 'text', text: `${stamp}${text}` }], + }, + }; + } + + it('takes the window from the first and last stamped prompt', async () => { + writeTranscript('conv-stamped', [ + stampedUserLine('Monday, Aug 31, 2026, 5:46 PM (UTC+3)', 'first'), + assistantLine('on it'), + stampedUserLine('Monday, Aug 31, 2026, 6:31 PM (UTC+3)', 'second'), + assistantLine('done'), + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.startEvent!.data.startTime).toBe(Date.parse('2026-08-31T17:46:00+03:00')); + expect(row.endEvent!.data.endTime).toBe(Date.parse('2026-08-31T18:31:00+03:00')); + }); + + it.skipIf(!hasNodeSqlite())('still prefers the tracking database when it recorded edits', async () => { + writeTranscript('conv-both', [ + stampedUserLine('Monday, Aug 31, 2026, 5:46 PM (UTC+3)', 'first'), + assistantLine('done'), + ]); + await writeTrackingDb([ + { + conversationId: 'conv-both', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.startTime).toBe(FIRST_EDIT_MS); + }); + + it('falls back to file times when no prompt is stamped', async () => { + writeTranscript('conv-unstamped', [ + { role: 'user', message: { content: [{ type: 'text', text: 'no stamp here' }] } }, + assistantLine('done'), + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.startTime).toBeGreaterThan(0); + }); +}); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index a3e43e37c..798f4e232 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -711,7 +711,7 @@ return ['' + esc(truncStr(sessTitle(s), 44)) + '', '' + esc(labelFor(s.agentName)) + '', '' + esc((s.models && s.models[0]) || '—') + '', - fmtTokens(Math.round(x.ctx)), fmtTokens(s.tokens ? s.tokens.cacheRead : 0), fmtUSD(s.costUSD), (Math.round(x.bloat * 10) / 10) + '%']; + fmtTokensOf(s, Math.round(x.ctx)), fmtTokensOf(s, s.tokens ? s.tokens.cacheRead : 0), fmtUSDOf(s, s.costUSD), (Math.round(x.bloat * 10) / 10) + '%']; }), [false, false, false, true, true, true, true], bloated.map(function (x) { return 'class="clickable" data-session="' + esc(x.s.sessionId) + '"'; })) + ''; @@ -728,8 +728,8 @@ var deadCard = card('Dead sessions', 'cost spent, zero files changed and zero net lines — pure inference waste'); var dkv = el('div', 'kpi-grid'); dkv.style.gridTemplateColumns = 'repeat(3,1fr)'; [['Dead sessions', fmtNum(dead.length), fs.length ? (Math.round((dead.length / fs.length) * 100) + '% of sessions') : ''], - ['Wasted cost', fmtUSD(deadCost), totalCost ? (Math.round((deadCost / totalCost) * 100) + '% of spend') : ''], - ['Avg cost / dead', dead.length ? fmtUSD(deadCost / dead.length) : '—', 'per unproductive session'] + ['Wasted cost', fmtUSDAgg(dead, deadCost), totalCost ? (Math.round((deadCost / totalCost) * 100) + '% of spend') : ''], + ['Avg cost / dead', dead.length ? fmtUSDAgg(dead, deadCost / dead.length) : '—', 'per unproductive session'] ].forEach(function (k) { var c = el('div', 'kpi'); c.appendChild(el('div', 'kpi-label', k[0])); c.appendChild(el('div', 'kpi-value', k[1])); if (k[2]) c.appendChild(el('div', 'kpi-sub', k[2])); dkv.appendChild(c); }); @@ -826,7 +826,7 @@ var grid = el('div', 'kpi-grid'); grid.style.gridTemplateColumns = 'repeat(3,1fr)'; var tok = fs.reduce(function (acc, s) { return acc + (s.tokens ? s.tokens.total : 0); }, 0); - [['Total est. cost', fmtUSD(total)], ['Total tokens', fmtTokens(tok)], ['Avg cost / session', fs.length ? fmtUSD(total / fs.length) : '—']].forEach(function (k) { + [['Total est. cost', fmtUSDAgg(fs, total)], ['Total tokens', anyMeasured(fs) ? fmtTokens(tok) : '—'], ['Avg cost / session', fs.length ? fmtUSDAgg(fs, total / fs.length) : '—']].forEach(function (k) { var c = el('div', 'kpi'); c.appendChild(el('div', 'kpi-label', k[0])); c.appendChild(el('div', 'kpi-value', k[1])); grid.appendChild(c); }); host.appendChild(grid); @@ -1107,7 +1107,7 @@ // Session bar spans the full window (the activity envelope). Its label shows the envelope // span — equal to the tracked duration in the normal case, but revealing the true span when // the tracked duration under-counts (e.g. dispatches predating a post-compaction window). - gantt.appendChild(tlRow('session', '#259F4C', 0, 100, fmtTimelineDuration(ganttSpan), fmtUSD(s.costUSD), true)); + gantt.appendChild(tlRow('session', '#259F4C', 0, 100, fmtTimelineDuration(ganttSpan), fmtUSDOf(s, s.costUSD), true)); var occ = {}; dispatches.forEach(function (d) { @@ -1253,7 +1253,7 @@ // which bills in premium requests rather than tokens, and whose older CLI versions // recorded no telemetry at all). Appended so other agents' cards are unchanged. var costRows = [ - ['Cost', s.usageUnavailableReason ? '—' : fmtUSD(s.costUSD), s.usageUnavailableReason ? 'not measurable' : 'API-equivalent'], + ['Cost', fmtUSDOf(s, s.costUSD), usageUnknown(s) ? 'not measurable' : 'API-equivalent'], ['Cache-read', s.cacheReadCostUSD ? fmtUSD(s.cacheReadCostUSD) : '—', ''], ['Duration', fmtDuration(s.durationMs || 0), ''], ['Started', '' + esc(fmtWhen(s.startTime)) + '', ''] From 9deea9b33f3f3e1ac74cfa384e50784b7f588e22 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:51 +0300 Subject: [PATCH 08/34] fix(analytics): refuse to guess a Cursor project when a slug is ambiguous MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up review of the previous commit found four defects in the new filesystem-verified slug walk and stamp parser. The walk stopped at its first match, but "/", "_" and "-" all slugify to "-", so one slug can describe two directories that both exist (~/work/my_app and ~/work/my-app). It now collects matches, stops at two, and reports no project when the answer is ambiguous — the same honest-gap rule the walk already applied when nothing matched. The slug cache only covered discovery, so every parsed session re-walked from the root; it is now an adapter field shared by both paths. The activity window consulted prompt stamps only when the tracking database had no first edit, so a row recording a first edit but no last fell through to file mtime — reintroducing the inflated span the stamps exist to prevent. Either open end now reaches for the stamps. The stamp regex matched a bare date shape anywhere in the transcript, so a date quoted in pasted logs or model output could date the session; it now requires the wrapper Cursor writes. Refs #1 --- src/agents/plugins/cursor/cursor.session.ts | 72 ++++++++++++------- .../plugins/cursor/cursor.transcript.ts | 9 ++- .../__tests__/native-loader-cursor.test.ts | 17 +++++ 3 files changed, 70 insertions(+), 28 deletions(-) diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index ba59696e4..b8a364dcd 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -105,28 +105,43 @@ function sameDir(a: string | undefined, b: string): boolean { * still beats a wrong answer. */ function projectPathFromSlug(slug: string, cache?: Map): string | undefined { - const cached = cache?.get(slug); - if (cached !== undefined || cache?.has(slug)) { - return cached; + if (cache?.has(slug)) { + return cache.get(slug); } - const resolved = descendMatchingSlug(sep, slug.split('-')); + const matches = descendMatchingSlug(sep, slug.split('-')); + if (matches.length > 1) { + logger.debug(`[cursor-discovery] slug ${slug} matches ${matches.length} directories — reporting no project`); + } + const resolved = matches.length === 1 ? matches[0] : undefined; cache?.set(slug, resolved); return resolved; } /** - * Deepest existing directory reached by consuming every token of a slug. + * Every existing directory reachable by consuming a slug whole, stopping at two. + * + * A child matches when its own name, slugified, equals the tokens it would have to account for. + * Recursion (rather than a single greedy pass) is what makes `foo-bar/baz` and `foo/bar-baz` + * both reachable from `foo-bar-baz`. + * + * More than one branch can succeed, because `/`, `_` and `-` all slugify to `-`: with both + * `~/work/my_app` and `~/work/my-app` on disk, one slug describes them equally well. Collecting + * a second match is how the caller learns to stay silent — attributing a session confidently to + * the wrong project is worse than reporting none. Two is enough to know it is ambiguous, and + * stopping there keeps the walk from exploring a tree it has already disqualified. * - * A child matches when its own name, slugified, equals the tokens it would have to account - * for. Recursion (rather than a single greedy pass) is what makes `foo-bar/baz` and - * `foo/bar-baz` both reachable from `foo-bar-baz`; the first branch that consumes the slug - * whole wins, and there is only ever one such branch on a real filesystem. + * Terminating: every step consumes at least one token, so depth is bounded by the token count + * even if a symlink points back up the tree. */ -function descendMatchingSlug(dir: string, tokens: string[]): string | undefined { +function descendMatchingSlug(dir: string, tokens: string[], found: string[] = []): string[] { if (tokens.length === 0) { - return dir; + found.push(dir); + return found; } for (const name of readDirNames(dir)) { + if (found.length >= 2) { + break; + } const nameTokens = slugForPath(name).split('-'); if (nameTokens.length > tokens.length) { continue; @@ -134,12 +149,9 @@ function descendMatchingSlug(dir: string, tokens: string[]): string | undefined if (!nameTokens.every((token, i) => token === tokens[i])) { continue; } - const found = descendMatchingSlug(join(dir, name), tokens.slice(nameTokens.length)); - if (found) { - return found; - } + descendMatchingSlug(join(dir, name), tokens.slice(nameTokens.length), found); } - return undefined; + return found; } /** The slug Cursor would have written for a directory: leading separator dropped, `/` and `_` → `-`. */ @@ -245,7 +257,10 @@ function activityWindow( filePath: string, activity: CursorConversationActivity | undefined ): { createdAt: number; updatedAt: number } | undefined { - const stamps = activity?.firstEditMs === undefined ? transcriptStampWindow(filePath) : undefined; + // Either end can be missing on its own — a database row can record a first edit and no last — + // so the stamps are read whenever either end is still open, not only when both are. + const needsStamps = activity?.firstEditMs === undefined || activity?.lastEditMs === undefined; + const stamps = needsStamps ? transcriptStampWindow(filePath) : undefined; const createdAt = activity?.firstEditMs ?? stamps?.firstMs; const updatedAt = activity?.lastEditMs ?? stamps?.lastMs; @@ -382,6 +397,16 @@ export class CursorSessionAdapter implements SessionAdapter { readonly agentName = CURSOR_AGENT_NAME; private processors: SessionProcessor[] = []; + /** + * Slug → project path, for this adapter's lifetime. + * + * Resolving a slug walks the filesystem from the root, and every conversation in a project + * repeats the same slug — so without this a run pays for the walk once per session rather + * than once per project. The adapter is memoized per run, which is exactly the scope the + * answer is stable over. + */ + private readonly slugPaths = new Map(); + /** * Enrichment from `~/.cursor/ai-tracking/ai-code-tracking.db`, keyed by conversation id. * @@ -450,9 +475,6 @@ export class CursorSessionAdapter implements SessionAdapter { const tracking = await this.trackingIndex(); const results: SessionDescriptor[] = []; - // Resolving a slug walks the filesystem, and every conversation in a project repeats the - // same slug, so the answer is worked out once per project per run. - const slugPaths = new Map(); for (const slug of readDirNames(root)) { const transcriptsRoot = join(root, slug, TRANSCRIPTS_DIR); @@ -461,7 +483,7 @@ export class CursorSessionAdapter implements SessionAdapter { } for (const conversationId of readDirNames(transcriptsRoot)) { - const descriptor = this.describeConversation(transcriptsRoot, conversationId, slug, tracking, slugPaths); + const descriptor = this.describeConversation(transcriptsRoot, conversationId, slug, tracking); if (!descriptor || descriptor.createdAt < cutoffMs) { continue; } @@ -494,8 +516,7 @@ export class CursorSessionAdapter implements SessionAdapter { transcriptsRoot: string, conversationId: string, slug: string, - tracking: CursorTrackingIndex, - slugPaths: Map + tracking: CursorTrackingIndex ): SessionDescriptor | undefined { const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); if (!existsSync(filePath)) { @@ -514,7 +535,7 @@ export class CursorSessionAdapter implements SessionAdapter { sessionId: conversationId, filePath, projectPath: - projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, slugPaths), + projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, this.slugPaths), createdAt: window.createdAt, updatedAt: window.updatedAt, agentName: this.agentName, @@ -538,7 +559,8 @@ export class CursorSessionAdapter implements SessionAdapter { const window = activityWindow(filePath, activity); const slug = slugOfTranscript(filePath); - const projectPath = projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug); + const projectPath = + projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, this.slugPaths); logger.debug( `[cursor-adapter] ${conversationId}: ${messages.length} message(s), ${userPrompts.length} prompt(s)` diff --git a/src/agents/plugins/cursor/cursor.transcript.ts b/src/agents/plugins/cursor/cursor.transcript.ts index ab891672c..1e6e139dc 100644 --- a/src/agents/plugins/cursor/cursor.transcript.ts +++ b/src/agents/plugins/cursor/cursor.transcript.ts @@ -94,11 +94,14 @@ const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', ' /** * The stamp Cursor writes ahead of every prompt, e.g. - * `Monday, Aug 31, 2026, 5:46 PM (UTC+3)`. The weekday is ignored — it carries no information - * the date does not — and the explicit offset is what makes the instant unambiguous. + * `Monday, Aug 31, 2026, 5:46 PM (UTC+3)`. The weekday is ignored — it + * carries no information the date does not — and the explicit offset is what makes the instant + * unambiguous. The `` wrapper is part of the pattern on purpose: a bare date shape + * also occurs in pasted logs and model output, and matching those would date the session by + * whatever text it happened to quote. */ const STAMP_PATTERN = - /([A-Z][a-z]{2})\s+(\d{1,2}),\s*(\d{4}),\s*(\d{1,2}):(\d{2})\s*(AM|PM)\s*\(UTC([+-]\d{1,2})(?::(\d{2}))?\)/gi; + /[^<]*?([A-Z][a-z]{2})\s+(\d{1,2}),\s*(\d{4}),\s*(\d{1,2}):(\d{2})\s*(AM|PM)\s*\(UTC([+-]\d{1,2})(?::(\d{2}))?\)[^<]*?<\/timestamp>/gi; function pad(value: number): string { return String(value).padStart(2, '0'); diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index 54227d5b1..ffd54cfbc 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -549,3 +549,20 @@ describe('loadNativeSessions — Cursor activity window from transcript timestam expect(cursorRows(rows)[0].startEvent!.data.startTime).toBeGreaterThan(0); }); }); + +/** + * `/`, `_` and `-` all slugify to `-`, so one slug can describe two directories that both + * exist. Guessing between them would attribute a session confidently to the wrong project, + * which is worse than the honest gap of reporting none. + */ +describe('loadNativeSessions — Cursor refuses to guess between equally valid projects', () => { + it('reports no project when two directories share the slug', async () => { + mkdirSync(join(projectDir, 'my_app'), { recursive: true }); + mkdirSync(join(projectDir, 'my-app'), { recursive: true }); + writeTranscript('conv-ambiguous', conversation('ship it'), slugForPath(join(projectDir, 'my-app'))); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].startEvent!.data.workingDirectory).toBe('Unknown'); + }); +}); From 96ac09a8fac49aca25f941ac1f526b9625e3e7b1 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:51 +0300 Subject: [PATCH 09/34] feat(analytics): report Cursor's delegated model choice as Auto MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor's AI-tracking database writes a model of `default` when the user let Cursor choose. That was dropped, so most Cursor sessions showed no model at all and read as though CodeMie had failed to read one. Cursor's own usage export names those same conversations `auto` in its Model column, so "Auto" is Cursor's word rather than an invention, and it says the right thing: the user delegated the choice. Locally the split is Auto 79.5% / grok-4.6 20.5%, against auto 90% / grok 10% in the export for the same account — the same shape at a different grain. What is still never done is stamping a session with whichever model Cursor happens to default to today; that remains unknowable from local data. Refs #1 --- src/agents/plugins/cursor/cursor.constants.ts | 19 +++++++++++++++---- .../plugins/cursor/cursor.tracking-db.ts | 18 ++++++++++++------ src/agents/plugins/cursor/index.ts | 7 ++++++- .../__tests__/native-loader-cursor.test.ts | 7 ++++--- 4 files changed, 37 insertions(+), 14 deletions(-) diff --git a/src/agents/plugins/cursor/cursor.constants.ts b/src/agents/plugins/cursor/cursor.constants.ts index 73604f621..a5e9f0afb 100644 --- a/src/agents/plugins/cursor/cursor.constants.ts +++ b/src/agents/plugins/cursor/cursor.constants.ts @@ -12,8 +12,19 @@ export const CURSOR_AGENT_NAME = 'cursor'; export const CURSOR_DISPLAY_NAME = 'Cursor'; /** - * Cursor records a model of `default` when the user left model selection to Cursor. That - * string names no model, so it is dropped rather than reported — see the honest-gaps note - * in `cursor.session.ts`. + * What Cursor's AI-tracking database writes when the user left model choice to Cursor. + * + * It names no model, so it must never be reported as one — the report would be claiming a + * model Cursor never recorded. + */ +export const CURSOR_AUTO_MODEL_SENTINEL = 'default'; + +/** + * How Cursor itself labels that mode. + * + * Cursor's own usage export writes `auto` in its Model column for exactly the conversations the + * local database marks `default`, so "Auto" is Cursor's word rather than our invention. Showing + * it beats showing a blank: "Auto" says the user delegated the choice, where a blank would + * suggest CodeMie failed to read something. */ -export const CURSOR_UNKNOWN_MODEL = 'default'; +export const CURSOR_AUTO_MODEL_LABEL = 'Auto'; diff --git a/src/agents/plugins/cursor/cursor.tracking-db.ts b/src/agents/plugins/cursor/cursor.tracking-db.ts index dedfec2dc..b035934a7 100644 --- a/src/agents/plugins/cursor/cursor.tracking-db.ts +++ b/src/agents/plugins/cursor/cursor.tracking-db.ts @@ -17,7 +17,7 @@ import { existsSync } from 'fs'; import { logger } from '../../../utils/logger.js'; -import { CURSOR_UNKNOWN_MODEL } from './cursor.constants.js'; +import { CURSOR_AUTO_MODEL_LABEL, CURSOR_AUTO_MODEL_SENTINEL } from './cursor.constants.js'; import { getCursorTrackingDbPath } from './cursor.paths.js'; /** What the tracking database knows about one conversation. */ @@ -29,9 +29,12 @@ export interface CursorConversationActivity { /** Absolute paths Cursor recorded itself as having written in this conversation. */ files: string[]; /** - * Models Cursor attributed edits to. Never contains the literal `default`, which names no - * model — a session whose only recorded model was `default` is reported as unknown rather - * than being stamped with whatever model Cursor happens to default to today. + * Models Cursor attributed edits to. + * + * The literal `default` never appears: it is Cursor's sentinel for delegated model choice and + * names no model, so it is reported as `Auto` — the term Cursor's own usage export uses for + * the same conversations. What is never done is stamping the session with whatever model + * Cursor happens to default to today. */ models: string[]; } @@ -126,8 +129,11 @@ export async function readCursorTrackingIndex( entry.files.push(file); } - const model = asString(row.model); - if (model && model !== CURSOR_UNKNOWN_MODEL && !entry.models.includes(model)) { + // `default` is Cursor's sentinel for "you pick" — reported under the name Cursor's own + // dashboard gives it rather than dropped, so the row reads "Auto" instead of blank. + const raw = asString(row.model); + const model = raw === CURSOR_AUTO_MODEL_SENTINEL ? CURSOR_AUTO_MODEL_LABEL : raw; + if (model && !entry.models.includes(model)) { entry.models.push(model); } diff --git a/src/agents/plugins/cursor/index.ts b/src/agents/plugins/cursor/index.ts index cfc4b1dcf..60a8123a2 100644 --- a/src/agents/plugins/cursor/index.ts +++ b/src/agents/plugins/cursor/index.ts @@ -1,5 +1,10 @@ export { CursorPlugin, CursorPluginMetadata } from './cursor.plugin.js'; -export { CURSOR_AGENT_NAME, CURSOR_DISPLAY_NAME, CURSOR_UNKNOWN_MODEL } from './cursor.constants.js'; +export { + CURSOR_AGENT_NAME, + CURSOR_AUTO_MODEL_LABEL, + CURSOR_AUTO_MODEL_SENTINEL, + CURSOR_DISPLAY_NAME, +} from './cursor.constants.js'; export { CursorSessionAdapter } from './cursor.session.js'; export { getCursorHome, getCursorProjectsRoot, getCursorTrackingDbPath } from './cursor.paths.js'; export { readCursorTrackingIndex } from './cursor.tracking-db.js'; diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index ffd54cfbc..e68349a24 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -305,7 +305,7 @@ describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor enrichment from expect(row.startEvent!.data.workingDirectory).toBe(projectDir); }); - it('reports a model recorded as "default" as unknown rather than guessing one', async () => { + it('reports a model recorded as "default" as Auto, the name Cursor gives it', async () => { writeTranscript('conv-a', conversation('add cursor analytics')); await writeTrackingDb([ { @@ -319,8 +319,9 @@ describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor enrichment from const { rows } = await runLoader(); const row = cursorRows(rows)[0]; - expect(row.deltas[0].models).toEqual([]); - // Enrichment still happened — only the meaningless model string was dropped. + // Cursor's own usage export calls these conversations `auto`, so "Auto" is its word, not a + // guess at which model actually ran — that is still never invented. + expect(row.deltas[0].models).toEqual(['Auto', 'Auto']); expect(row.deltas[0].fileOperations?.map((f) => f.path)).toEqual([join(projectDir, 'src', 'app.ts')]); }); From fe1abc3afe6541ddf545fcd1b31c86ba614a5b13 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:52 +0300 Subject: [PATCH 10/34] fix(analytics): gate Cursor sessions behind --include-external MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor sessions were shown by default on the reasoning that an analytics-only agent has no managed variant, so its sessions are unmanaged rather than external. That drew the line in the wrong place: what --include-external is really about is whether CodeMie launched the session, and CodeMie did not launch these. The ownership gate now applies to every agent alike — no ownership marker means native-external, opt-in behind the flag. Set Cursor up through CodeMie and its sessions carry a marker, keeping the plain 'native' tag and showing with no flag; that path is covered by a new test even though nothing produces such a marker today. Removes the native-unmanaged provider tag and its formatter branch, and updates the CONTEXT.md glossary and the AGENTS.md plugin row, which both documented the old rule. Deviates from spec #1 user story 2 ("visible by default without any extra flag") at the user's explicit direction. Refs #1 --- AGENTS.md | 2 +- CONTEXT.md | 6 +--- src/agents/plugins/cursor/cursor.plugin.ts | 9 +++--- .../__tests__/native-loader-cursor.test.ts | 29 +++++++++++++----- src/cli/commands/analytics/formatter.ts | 4 +-- src/cli/commands/analytics/native-loader.ts | 30 ++++--------------- .../commands/analytics/report/client/app.js | 10 +++++-- 7 files changed, 41 insertions(+), 49 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b0627f7c..123047a9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -223,7 +223,7 @@ See `package.json` for exact dependency versions and `.ai-run/guides/architectur | `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/` | `@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 unmanaged sessions (visible by default, no `--include-external`) | +| `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) | 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`). diff --git a/CONTEXT.md b/CONTEXT.md index e4ddb8ede..d244764b5 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -13,12 +13,8 @@ An agent CodeMie never installs or launches but whose locally persisted sessions _Avoid_: external agent, ingestion-only agent **External session**: -A session of a *managed* agent that was run outside CodeMie and carries no CodeMie ownership marker (provider tag `native-external`). Hidden by default; shown with `--include-external`. +A session CodeMie did not launch, so it carries no ownership marker (provider tag `native-external`). Applies to every agent alike, managed or analytics-only. Hidden by default; shown with `--include-external`. _Avoid_: unmanaged session, foreign session -**Unmanaged session**: -A session of an *analytics-only* agent (provider tag `native-unmanaged`). Always shown; no flag required. -_Avoid_: external session - **Ownership marker**: The sidecar record in `~/.codemie/sessions/` that proves CodeMie launched a given agent session; its absence is what makes a managed agent's session external. diff --git a/src/agents/plugins/cursor/cursor.plugin.ts b/src/agents/plugins/cursor/cursor.plugin.ts index b2718e6a2..acee12bc7 100644 --- a/src/agents/plugins/cursor/cursor.plugin.ts +++ b/src/agents/plugins/cursor/cursor.plugin.ts @@ -8,11 +8,10 @@ * - `AgentRegistry.getManageableAgents()` filters on it, which keeps Cursor out of every * management surface (install, uninstall, update, list, doctor, first-run). `codemie update` * in particular would otherwise run `npm install -g` against a package Cursor does not have. - * - the analytics ownership gate (`isAnalyticsOnlyAgent` in `native-loader.ts`) skips it. - * That gate exists to hide *external* sessions — runs of an agent CodeMie CAN manage that it - * did not launch. Cursor has no managed variant, so its sessions are *unmanaged* rather than - * external; applying the gate would tag every one `native-external` and drop the whole agent - * from the default report. (See `CONTEXT.md` for both terms.) + * - the analytics ownership gate in `native-loader.ts` applies to Cursor like any other agent: + * a session CodeMie cannot prove it launched is external, so Cursor sessions are opt-in + * behind `--include-external`. Since CodeMie never launches Cursor today, that is all of + * them; set one up through CodeMie and the ownership marker makes it show with no flag. * * There is therefore no npm package, no CLI command, no env mapping and no provider list — * none of the launch machinery is ever reached. The plugin exists solely to hand the registry diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index e68349a24..93ee7f273 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -156,7 +156,7 @@ interface SeamRun { * Load native sessions the way `SessionsSource` does, but with only the Cursor adapter (plus an * optional managed-agent contrast row) behind the discovery dependency. */ -async function runLoader(options: { withManagedClaude?: boolean } = {}): Promise { +async function runLoader(options: { withManagedClaude?: boolean; owned?: boolean } = {}): Promise { vi.resetModules(); const { AgentRegistry } = await import('../../../../agents/registry.js'); const { loadNativeSessions } = await import('../native-loader.js'); @@ -186,7 +186,7 @@ async function runLoader(options: { withManagedClaude?: boolean } = {}): Promise return session; }, realPath: (p) => p, - hasOwnershipMarker: () => false, + hasOwnershipMarker: () => options.owned === true, }; return { rows: await loadNativeSessions(undefined, deps), parsed }; @@ -239,26 +239,39 @@ describe('loadNativeSessions — Cursor discovery and unmanaged tagging', () => expect(cursorRows(rows)).toHaveLength(1); }); - it('tags Cursor sessions native-unmanaged, not native-external', async () => { + it('tags a Cursor session CodeMie did not launch as native-external', async () => { writeTranscript('conv-a', conversation('add cursor analytics')); const { rows } = await runLoader(); - expect(cursorRows(rows)[0].startEvent!.data.provider).toBe('native-unmanaged'); + expect(cursorRows(rows)[0].startEvent!.data.provider).toBe('native-external'); }); - it('shows Cursor sessions without --include-external, unlike a managed agent’s native session', async () => { + it('hides Cursor sessions until --include-external, exactly like a managed agent’s', async () => { writeTranscript('conv-a', conversation('add cursor analytics')); const { rows } = await runLoader({ withManagedClaude: true }); - // The unowned Claude row is the contrast: managed agent, so it is gated behind the flag. + // One rule for every agent: no ownership marker means external, flag or nothing. expect(rows.find((s) => s.sessionId === 'cl1')!.startEvent!.data.provider).toBe('native-external'); const byDefault = visible(rows, false).map((s) => s.sessionId); - expect(byDefault).toContain('conv-a'); + expect(byDefault).not.toContain('conv-a'); expect(byDefault).not.toContain('cl1'); - expect(visible(rows, true).map((s) => s.sessionId)).toContain('cl1'); + + const withFlag = visible(rows, true).map((s) => s.sessionId); + expect(withFlag).toContain('conv-a'); + expect(withFlag).toContain('cl1'); + }); + + it('shows a Cursor session CodeMie set up, with no flag', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + + // An ownership marker is what proves CodeMie launched it; the gate then does not apply. + const { rows } = await runLoader({ owned: true }); + + expect(cursorRows(rows)[0].startEvent!.data.provider).toBe('native'); + expect(visible(rows, false).map((s) => s.sessionId)).toContain('conv-a'); }); it('carries the transcript’s prompts and turns onto the synthesized row', async () => { diff --git a/src/cli/commands/analytics/formatter.ts b/src/cli/commands/analytics/formatter.ts index 94a8c697b..a8a1d5f21 100644 --- a/src/cli/commands/analytics/formatter.ts +++ b/src/cli/commands/analytics/formatter.ts @@ -169,9 +169,7 @@ export class AnalyticsFormatter { const providerLabel = session.provider === 'native-external' ? chalk.yellow('native [external ⚠ not CodeMie-managed]') - : session.provider === 'native-unmanaged' - ? chalk.gray('native [not CodeMie-managed — analytics only]') - : session.provider; + : session.provider; console.log(chalk.gray(` Provider: `) + providerLabel); console.log(chalk.gray(` Duration: ${this.formatDuration(session.duration)}`)); console.log(chalk.gray(` Turns: ${session.totalTurns}`)); diff --git a/src/cli/commands/analytics/native-loader.ts b/src/cli/commands/analytics/native-loader.ts index 15652d5df..29dae0c3d 100644 --- a/src/cli/commands/analytics/native-loader.ts +++ b/src/cli/commands/analytics/native-loader.ts @@ -37,22 +37,6 @@ function isPiAgent(agentName: string): boolean { return agentName.toLowerCase() === 'pi'; } -/** - * Agents CodeMie only reads analytics for and never installs, launches, or manages. - * - * The ownership gate below exists to stop analytics silently counting UNMANAGED runs of an - * agent CodeMie CAN manage (EPMCDME-13367). A truly analytics-only agent has no managed - * variant, so it can never carry an ownership marker — applying the gate would tag 100% of - * its sessions `native-external` and drop them from the default report. - */ -function isAnalyticsOnlyAgent(agentName: string): boolean { - try { - return AgentRegistry.getAgent(agentName)?.metadata.analyticsOnly === true; - } catch { - return false; - } -} - /** A discovered native session paired with its agent. */ export interface DiscoveredNative { agentName: string; @@ -749,15 +733,13 @@ export async function loadNativeSessions( continue; } const raw = synthesizeRawSession(agentName, descriptor, parsed); + // One rule for every agent: a session CodeMie cannot prove it launched is external, and + // external sessions are opt-in behind `--include-external`. That holds for analytics-only + // agents too — CodeMie did not run them, so the default report does not claim them. Set one + // up through CodeMie and its sessions carry an ownership marker, keeping the plain 'native' + // tag that means "CodeMie launched this" and showing with no flag. if (raw.startEvent && !deps.hasOwnershipMarker(descriptor.filePath)) { - // Truly analytics-only agents can never carry an ownership marker, so tagging them - // 'native-external' would drop 100% of their sessions from the default report. They - // still are not CodeMie-managed, so they get their own tag rather than the plain - // 'native' that means "CodeMie launched this". Managed agents, including Copilot CLI, - // remain 'native-external' when their transcript lacks CodeMie ownership. - raw.startEvent.data.provider = isAnalyticsOnlyAgent(agentName) - ? 'native-unmanaged' - : 'native-external'; + raw.startEvent.data.provider = 'native-external'; } out.push(raw); } diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index 798f4e232..d79a43cb1 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -60,11 +60,15 @@ // read as "this session was free", so every money/token cell goes through these helpers // and shows an em dash instead. Aggregates only dash out when NOTHING in the group was // measurable — a mixed group still shows the real sum of what was measured. + // "Included" is Cursor's own word: its usage export marks every such event Kind=Included, + // meaning covered by the subscription rather than separately priced. It is used only for the + // cost cell — a token count has no equivalent, so those stay an em dash. + var UNPRICED_LABEL = 'Included'; function usageUnknown(s) { return !!(s && s.usageUnavailableReason); } function anyMeasured(list) { return (list || []).some(function (s) { return !usageUnknown(s); }); } - function fmtUSDOf(s, n) { return usageUnknown(s) ? '—' : fmtUSD(n); } + function fmtUSDOf(s, n) { return usageUnknown(s) ? UNPRICED_LABEL : fmtUSD(n); } function fmtTokensOf(s, n) { return usageUnknown(s) ? '—' : fmtTokens(n); } - function fmtUSDAgg(list, n) { return anyMeasured(list) ? fmtUSD(n) : '—'; } + function fmtUSDAgg(list, n) { return anyMeasured(list) ? fmtUSD(n) : UNPRICED_LABEL; } function esc(s) { return String(s == null ? '' : s).replace(/[&<>"]/g, function (c) { return { '&': '&', '<': '<', '>': '>', '"': '"' }[c]; }); } function shortPath(p) { var parts = String(p || '').split('/'); return parts[parts.length - 1] || p; } @@ -1253,7 +1257,7 @@ // which bills in premium requests rather than tokens, and whose older CLI versions // recorded no telemetry at all). Appended so other agents' cards are unchanged. var costRows = [ - ['Cost', fmtUSDOf(s, s.costUSD), usageUnknown(s) ? 'not measurable' : 'API-equivalent'], + ['Cost', fmtUSDOf(s, s.costUSD), usageUnknown(s) ? 'covered by subscription' : 'API-equivalent'], ['Cache-read', s.cacheReadCostUSD ? fmtUSD(s.cacheReadCostUSD) : '—', ''], ['Duration', fmtDuration(s.durationMs || 0), ''], ['Started', '' + esc(fmtWhen(s.startTime)) + '', ''] From 0750d0fa72be9a0741e63db3c0d64ea819a28720 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:55 +0300 Subject: [PATCH 11/34] feat(analytics): discover Cursor sessions via composerHeaders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Switch Cursor session discovery to state.vscdb's composerHeaders table as the primary source, per ADR 0001. agent-transcripts/*.jsonl scanning found only ~65 real sessions on a sample machine; composerHeaders has ~463, keyed by composerId (the same id used by agent-transcripts and ai_code_hashes.conversationId). - New cursor.state-db.ts: fail-soft composerHeaders reader, tolerant of the undocumented flat-column or key/value row shape. Draft sessions (isDraft: true) never enter the returned index. - cursor.paths.ts: getCursorStateDbPath(), with platform-specific resolution (macOS/Linux/Windows) for state.vscdb, independent of ~/.cursor; CURSOR_HOME still relocates it for tests. - cursor.session.ts: discovery unions composerId sets from composerHeaders and agent-transcripts. A header's own workspaceIdentifier.uri.fsPath, activeBranch.branchName / createdOnBranch, and totalLinesAdded/totalLinesRemoved/ filesChangedCount are now authoritative; the old slug-walk project guess and content-hash-derived file list only run as a fallback for a session with a transcript but no header row. - Threaded an optional filesChangedCount through ParsedSession.metrics, MetricDelta and the aggregator (additive, defaults to today's path-derived count when unset) so a composerHeaders-only session's real files-changed total can surface without fabricating per-file entries. - native-loader.ts: synthesizeRawSession's default branch resolution now falls back to parsed.metadata.branch when no message carries a gitBranch to vote over — needed because a composerHeaders-only session (no transcript) has no messages to stamp a branch onto at all, which is the majority shape of session this ADR surfaces. --include-external gating and analyticsOnly behavior are unchanged. Refs #10 --- src/agents/core/metrics/types.ts | 3 + src/agents/core/session/BaseSessionAdapter.ts | 2 + src/agents/plugins/cursor/cursor.paths.ts | 40 +++ src/agents/plugins/cursor/cursor.session.ts | 329 ++++++++++++++---- src/agents/plugins/cursor/cursor.state-db.ts | 273 +++++++++++++++ src/agents/plugins/cursor/index.ts | 9 +- .../__tests__/native-loader-cursor.test.ts | 171 ++++++++- src/cli/commands/analytics/aggregator.ts | 4 +- src/cli/commands/analytics/native-loader.ts | 9 +- 9 files changed, 760 insertions(+), 80 deletions(-) create mode 100644 src/agents/plugins/cursor/cursor.state-db.ts diff --git a/src/agents/core/metrics/types.ts b/src/agents/core/metrics/types.ts index 8501bcc02..0f0c1ab1f 100644 --- a/src/agents/core/metrics/types.ts +++ b/src/agents/core/metrics/types.ts @@ -77,6 +77,9 @@ export interface MetricDelta { durationMs?: number; // Tool execution time (from tool_result) }[]; + // Aggregate files-changed count for adapters that know the total but not individual paths (e.g. Cursor's composerHeaders); when set, this overrides the path-derived count instead of being redundant with it. + filesChangedCount?: number; + // Model tracking (raw names, unnormalized) models?: string[]; // All models used in this turn diff --git a/src/agents/core/session/BaseSessionAdapter.ts b/src/agents/core/session/BaseSessionAdapter.ts index 463cab671..195e27a8f 100644 --- a/src/agents/core/session/BaseSessionAdapter.ts +++ b/src/agents/core/session/BaseSessionAdapter.ts @@ -78,6 +78,8 @@ export interface ParsedSession { linesAdded?: number; linesRemoved?: number; }>; + // Aggregate files-changed count for adapters that know the total but not individual paths (e.g. Cursor's composerHeaders); when set, this overrides the path-derived count instead of being redundant with it. + filesChangedCount?: number; // Named invocation breakdowns (skill names, agent subtypes, slash commands) skillInvocations?: Record; agentInvocations?: Record; diff --git a/src/agents/plugins/cursor/cursor.paths.ts b/src/agents/plugins/cursor/cursor.paths.ts index d61ec5827..d645e8822 100644 --- a/src/agents/plugins/cursor/cursor.paths.ts +++ b/src/agents/plugins/cursor/cursor.paths.ts @@ -4,8 +4,16 @@ * Cursor keeps its user data under `~/.cursor`. `CURSOR_HOME` overrides it, mirroring the * `COPILOT_HOME` handling in `copilot-cli.paths.ts` — which is also what lets the adapter * be driven against a fixture tree in tests. + * + * `state.vscdb` is a second, unrelated Cursor data location: it is the VS Code/Cursor + * *application* state store, not `~/.cursor` (which holds Cursor's own project/tracking + * data), so it lives under the OS's per-app-data directory (see ADR + * `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). `CURSOR_HOME` still doubles + * as the test-fixture override for it — same rationale as above — under a `User/globalStorage` + * layout that mirrors where Cursor actually keeps it relative to its app-data root. */ +import { homedir } from 'os'; import { join } from 'path'; import { resolveHomeDir } from '../../../utils/paths.js'; @@ -27,3 +35,35 @@ export function getCursorProjectsRoot(): string { export function getCursorTrackingDbPath(): string { return join(getCursorHome(), 'ai-tracking', 'ai-code-tracking.db'); } + +/** + * Cursor's (VS Code-derived) per-user application-data directory: the real, OS-specific home + * of `state.vscdb`. Not `~/.cursor` — that is Cursor's own project/tracking data, a separate + * tree from the editor shell's VS Code-inherited state. + */ +function getCursorAppDataDir(): string { + const home = homedir(); + switch (process.platform) { + case 'darwin': + return join(home, 'Library', 'Application Support', 'Cursor'); + case 'win32': { + const appData = process.env.APPDATA; + return appData ? join(appData, 'Cursor') : join(home, 'AppData', 'Roaming', 'Cursor'); + } + default: + // Linux and other Unix-likes. + return join(home, '.config', 'Cursor'); + } +} + +/** + * `state.vscdb` — the undocumented internal store `composerHeaders` (session discovery) and + * `cursorDiskKV` (per-turn enrichment) live in. `$CURSOR_HOME`, when set, relocates it under + * `User/globalStorage` the same way it relocates `projects/` and `ai-tracking/`, which is what + * lets tests point it at a fixture tree instead of the real per-OS app-data directory. + */ +export function getCursorStateDbPath(): string { + const override = process.env.CURSOR_HOME?.trim(); + const root = override ?? getCursorAppDataDir(); + return join(root, 'User', 'globalStorage', 'state.vscdb'); +} diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index b8a364dcd..909acd4a8 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -1,34 +1,46 @@ /** * Cursor session adapter — analytics-only. * - * Cursor keeps one transcript per agent conversation at - * `~/.cursor/projects//agent-transcripts//.jsonl`. - * `projects/` also holds directories that are not projects at all (numeric window ids, - * `empty-window`) and project directories holding only `canvases`/`terminals`/`mcps`, so - * discovery keys on the presence of `agent-transcripts` rather than on the directory name. + * Discovery is keyed on `composerId`, the identifier Cursor uses for one agent conversation + * across every local store it writes: `state.vscdb`'s `composerHeaders` table (primary — see + * `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`), the + * `~/.cursor/projects//agent-transcripts//.jsonl` + * transcript (secondary, joined by the shared id), and `ai_code_hashes.conversationId` in the + * AI-tracking database (enrichment, same join). A session can have a header with no transcript + * (most of them — transcripts cover a small fraction of real sessions), a transcript with no + * header (observed rarely — schema drift, a header row Cursor pruned), or both; discovery + * unions the two id sets rather than requiring either alone. + * + * `composerHeaders` is what makes project path, branch and line counts trustworthy: + * `workspaceIdentifier.uri.fsPath` names the project directly, `activeBranch.branchName` / + * `createdOnBranch` name the real branch, and `totalLinesAdded` / `totalLinesRemoved` / + * `filesChangedCount` are Cursor's own totals rather than something reconstructed from content + * hashes. Only when a session has no header row (transcript-only) does the adapter fall back + * to the slug-walk project-path guess this file used to rely on for every session — see + * {@link projectPathFromSlug}. * - * What a transcript can and cannot tell us is the whole design constraint here. It carries - * role-tagged text, tool_use blocks, turn markers, and a human-readable stamp on each prompt — - * but no model and no token counts. So: + * A transcript, when one exists, still supplies what neither store does: role-tagged text, + * tool_use blocks, turn markers, and a human-readable stamp on each prompt. It carries no model + * and no token counts. So: * - * - the activity window comes from Cursor's own first/last recorded edit, falling back to the - * prompt stamps, and only then to the transcript file's birthtime/mtime — file times measure - * when the file was touched, so a conversation resumed days later would otherwise report a - * span of days rather than of minutes; - * - messages are emitted deliberately WITHOUT timestamps, so the native loader falls back to - * the descriptor's window instead of a fabricated per-message clock; + * - the activity window prefers the header's own timestamps, then Cursor's recorded first/last + * edit, then the prompt stamps, and only then the transcript file's birthtime/mtime — file + * times measure when the file was touched, so a conversation resumed days later would + * otherwise report a span of days rather than of minutes; + * - messages are emitted deliberately WITHOUT per-message timestamps, so the native loader + * falls back to the descriptor's window instead of a fabricated per-message clock; * - `usageMeta.usageUnavailableReason` is always set, which is what makes the report render * tokens and cost as unmeasurable rather than as a confident zero. * - * Model, precise edit times, edited-file lists and the only trustworthy project path live in - * Cursor's AI-tracking database. The adapter reads it once per run and joins on conversation - * id — see {@link CursorSessionAdapter.setTrackingIndex}. When it is missing, locked, on a - * runtime without `node:sqlite` or schema-drifted, the join simply finds nothing and every - * session degrades to its transcript-only form. + * Model and edited-file lists still come from the AI-tracking database, joined by the same + * `composerId`/`conversationId` — see {@link CursorSessionAdapter.setTrackingIndex}. When + * either store is missing, locked, on a runtime without `node:sqlite`, or schema-drifted, the + * join simply finds nothing and the session degrades to whatever the remaining sources supply. * - * Messages are emitted in the Claude-shaped `{type, message: {role, content}}` form on - * purpose: `synthesizeRawSession` in `src/cli/commands/analytics/native-loader.ts` uses that - * shape for its default branch, so Cursor needs no per-agent case there. + * Messages are emitted in the Claude-shaped `{type, message: {role, content}}` form (with + * `gitBranch` stamped alongside `message` — see {@link applyBranch}) on purpose: + * `synthesizeRawSession` in `src/cli/commands/analytics/native-loader.ts` uses that shape for + * its default branch, so Cursor needs no per-agent case there. * * Everything is read-only and fail-soft. A missing Cursor home yields zero sessions, never an * error — analytics for every other agent must survive Cursor not being installed. @@ -53,6 +65,8 @@ import { CURSOR_AGENT_NAME } from './cursor.constants.js'; import { getCursorProjectsRoot } from './cursor.paths.js'; import type { CursorConversationActivity, CursorTrackingIndex } from './cursor.tracking-db.js'; import { readCursorTrackingIndex } from './cursor.tracking-db.js'; +import type { CursorComposerHeader, CursorComposerIndex } from './cursor.state-db.js'; +import { readCursorComposerIndex } from './cursor.state-db.js'; import type { CursorMessageLine, CursorTranscriptLine } from './cursor.transcript.js'; import { contentBlocks, @@ -282,6 +296,8 @@ function activityWindow( interface CursorNativeMessage { type: 'user' | 'assistant'; message: { role: 'user' | 'assistant'; content: string; model?: string }; + /** Top-level, sibling to `message` — where `synthesizeRawSession` reads `m.gitBranch` from. */ + gitBranch?: string; } /** @@ -311,6 +327,92 @@ function applyModels(messages: CursorNativeMessage[], models: string[]): void { }); } +/** + * Stamp the header's real git branch onto every message — the only place the native loader's + * default synthesis looks (`messages.map((m) => m.gitBranch)`, mode-voted). One branch per + * conversation is all `composerHeaders` ever records, so every message carries the same value; + * unlike {@link applyModels} there is no multi-value case to spread across turns. + */ +function applyBranch(messages: CursorNativeMessage[], branch: string | undefined): void { + if (!branch) { + return; + } + for (const message of messages) { + message.gitBranch = branch; + } +} + +/** + * When a conversation ran, preferring `composerHeaders`'s own timestamps over anything derived. + * + * A header can record only one end of the window (Cursor's own writes are not guaranteed + * complete either) — in that case the other end mirrors it rather than falling through to a + * weaker source for half the answer and a stronger one for the other half. + */ +function resolveWindow( + header: CursorComposerHeader | undefined, + filePath: string, + activity: CursorConversationActivity | undefined +): { createdAt: number; updatedAt: number } | undefined { + if (header?.createdAt !== undefined || header?.updatedAt !== undefined) { + const createdAt = header.createdAt ?? header.updatedAt!; + const updatedAt = header.updatedAt ?? header.createdAt!; + return { createdAt, updatedAt: Math.max(createdAt, updatedAt) }; + } + return activityWindow(filePath, activity); +} + +/** + * The project path for a conversation: `composerHeaders`'s own `workspaceIdentifier.uri.fsPath` + * when the session has a header, with no slug-guessing needed at all — that is the whole point + * of discovering from `state.vscdb`. The slug walk only runs for a session that has a + * transcript but no header row, which is the one case left with nothing better to go on. + */ +function resolveProjectPath( + header: CursorComposerHeader | undefined, + slug: string | undefined, + activity: CursorConversationActivity | undefined, + cache: Map +): string | undefined { + if (header?.projectPath) { + return header.projectPath; + } + if (!slug) { + return undefined; + } + return projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, cache); +} + +/** + * A single synthetic file operation carrying `composerHeaders`'s aggregate line counts. + * + * The database gives Cursor's own `totalLinesAdded`/`totalLinesRemoved` for the whole + * conversation, not a per-file breakdown — there is no real path to attach them to file by + * file. Rather than inventing per-file entries, one entry stands in for the session as a whole; + * its `path` is the resolved project path when known (a real, verified directory) or a + * synthetic id-keyed marker when not, purely because the aggregator drops any file operation + * with no `path` at all. `filesChangedCount` itself rides separately on `metrics` — see + * `ParsedSession.metrics.filesChangedCount` — because the aggregator's default files-changed + * count (distinct operation paths) cannot represent an aggregate with only one synthetic entry. + */ +function aggregateLinesFileOp( + header: CursorComposerHeader | undefined, + projectPath: string | undefined, + sessionId: string +): NonNullable['fileOperations'] { + if (header?.linesAdded === undefined && header?.linesRemoved === undefined) { + return []; + } + return [ + { + type: 'edit', + path: projectPath ?? `cursor-session:${sessionId}`, + linesAdded: header.linesAdded ?? 0, + linesRemoved: header.linesRemoved ?? 0, + }, + ]; +} + /** What one transcript's lines amount to, once the shape Cursor writes is set aside. */ interface FlattenedTranscript { messages: CursorNativeMessage[]; @@ -393,6 +495,53 @@ function slugOfTranscript(filePath: string): string { return basename(dirname(dirname(dirname(filePath)))); } +/** + * A stable, never-created path for a session discovered only through `composerHeaders` — no + * transcript exists for it on disk. `parseSessionFile` takes its conversation id from the + * path's own basename (`basename(filePath, '.jsonl')`), so this has to end in + * `.jsonl` for that id round-trip to work like it does for a real transcript path; + * everything upstream of that (`readCursorTranscript`, `statSync` for the file-time fallback) + * already degrades to "no data" for a path that does not exist, so nothing downstream needs to + * know this path is synthetic. + */ +function virtualTranscriptPath(root: string, composerId: string): string { + return join(root, '.composer-only', composerId, `${composerId}.jsonl`); +} + +/** One discovered transcript: where it lives, and the project slug it lives under. */ +interface DiscoveredTranscript { + filePath: string; + slug: string; +} + +/** + * Every real transcript under `~/.cursor/projects`, keyed by conversation id. + * + * `projects/` also holds directories that are not projects at all (numeric window ids, + * `empty-window`) and project directories holding only `canvases`/`terminals`/`mcps`, so this + * keys on the presence of `agent-transcripts` rather than on the directory name — same rule the + * single-pass scan used before discovery split into "list transcripts" and "list headers". + */ +function findTranscripts(root: string): Map { + const found = new Map(); + if (!existsSync(root)) { + return found; + } + for (const slug of readDirNames(root)) { + const transcriptsRoot = join(root, slug, TRANSCRIPTS_DIR); + if (!existsSync(transcriptsRoot)) { + continue; + } + for (const conversationId of readDirNames(transcriptsRoot)) { + const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); + if (existsSync(filePath)) { + found.set(conversationId, { filePath, slug }); + } + } + } + return found; +} + export class CursorSessionAdapter implements SessionAdapter { readonly agentName = CURSOR_AGENT_NAME; private processors: SessionProcessor[] = []; @@ -420,6 +569,13 @@ export class CursorSessionAdapter implements SessionAdapter { */ private trackingIndexLoad?: Promise; + /** + * Enrichment from `state.vscdb`'s `composerHeaders` table, keyed by composerId — the primary + * session-discovery source (see the module doc comment). Memoized for the same reason as + * {@link trackingIndexLoad}: one adapter instance per process, one database read per run. + */ + private composerIndexLoad?: Promise; + constructor(private readonly metadata: AgentMetadata) {} /** @@ -445,6 +601,25 @@ export class CursorSessionAdapter implements SessionAdapter { return this.trackingIndexLoad; } + /** + * Attach the composer index directly — the `state.vscdb` counterpart of + * {@link setTrackingIndex}, for the same reasons (async load, test injection). + */ + setComposerIndex(index: CursorComposerIndex): void { + this.composerIndexLoad = Promise.resolve(index); + } + + /** + * The composer index, reading `state.vscdb` on first use. + * + * `readCursorComposerIndex` never throws — see its own contract — so a missing, locked or + * schema-drifted state database degrades discovery to transcript-only, not to zero sessions. + */ + private async composerIndex(): Promise { + this.composerIndexLoad ??= readCursorComposerIndex(); + return this.composerIndexLoad; + } + registerProcessor(processor: SessionProcessor): void { this.processors.push(processor); this.processors.sort((a, b) => a.priority - b.priority); @@ -452,46 +627,56 @@ export class CursorSessionAdapter implements SessionAdapter { } /** - * Enumerate every agent transcript under `~/.cursor/projects`, newest first. + * Enumerate every discoverable Cursor session, newest first. * - * Discovery deliberately does not open transcripts: the file's own stat is enough to date - * and filter a session, so a run never pays to read a transcript it goes on to discard. + * Session identity is the union of two id sets: every composerId `state.vscdb`'s + * `composerHeaders` table has a (non-draft) row for, and every composerId with a real + * transcript under `~/.cursor/projects`. Most real sessions today have a header and no + * transcript; a small, shrinking set has a transcript with no header (schema drift, a pruned + * row) and falls all the way back to the pre-ADR-0001 slug walk. Neither set alone is + * discovery — see the module doc comment. + * + * Discovery deliberately does not open transcripts: a transcript file's own stat, or the + * header's own timestamps, are enough to date and filter a session, so a run never pays to + * read a transcript it goes on to discard. * * The descriptor — not the parsed session — is where enrichment has to land for timing and * project: Cursor messages carry no timestamps and no cwd, so the native loader's synthesis * falls back to `descriptor.createdAt` / `updatedAt` / `projectPath` for exactly those three - * facts. Applying the tracking window here also keeps the age cutoff and the reported window + * facts. Resolving the window here also keeps the age cutoff and the reported window * consistent with each other. */ async discoverSessions(options?: SessionDiscoveryOptions): Promise { const root = getCursorProjectsRoot(); - if (!existsSync(root)) { - logger.debug(`[cursor-discovery] no Cursor projects directory at ${root}`); + const transcripts = findTranscripts(root); + const [tracking, composerIndex] = await Promise.all([this.trackingIndex(), this.composerIndex()]); + + if (transcripts.size === 0 && composerIndex.size === 0) { + logger.debug(`[cursor-discovery] no Cursor sessions found (no state database, no transcripts under ${root})`); return []; } const maxAgeDays = options?.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS; const cutoffMs = Date.now() - maxAgeDays * MS_PER_DAY; - const tracking = await this.trackingIndex(); + const composerIds = new Set([...transcripts.keys(), ...composerIndex.keys()]); const results: SessionDescriptor[] = []; - for (const slug of readDirNames(root)) { - const transcriptsRoot = join(root, slug, TRANSCRIPTS_DIR); - if (!existsSync(transcriptsRoot)) { + for (const composerId of composerIds) { + const descriptor = this.describeConversation( + root, + composerId, + composerIndex.get(composerId), + transcripts.get(composerId), + tracking + ); + if (!descriptor || descriptor.createdAt < cutoffMs) { continue; } - - for (const conversationId of readDirNames(transcriptsRoot)) { - const descriptor = this.describeConversation(transcriptsRoot, conversationId, slug, tracking); - if (!descriptor || descriptor.createdAt < cutoffMs) { - continue; - } - if (options?.cwd && !sameDir(descriptor.projectPath, options.cwd)) { - continue; - } - results.push(descriptor); + if (options?.cwd && !sameDir(descriptor.projectPath, options.cwd)) { + continue; } + results.push(descriptor); } results.sort((a, b) => b.createdAt - a.createdAt); @@ -506,36 +691,30 @@ export class CursorSessionAdapter implements SessionAdapter { } /** - * One conversation as a descriptor, or undefined when it has no transcript on disk. + * One conversation as a descriptor, or undefined when neither source can date it. * * The descriptor — not the parsed session — is where the project and the window have to land: * Cursor's messages carry no timestamps and no cwd, so the native loader's default synthesis * reads exactly those facts off the descriptor. */ private describeConversation( - transcriptsRoot: string, - conversationId: string, - slug: string, + root: string, + composerId: string, + header: CursorComposerHeader | undefined, + transcript: DiscoveredTranscript | undefined, tracking: CursorTrackingIndex ): SessionDescriptor | undefined { - const filePath = join(transcriptsRoot, conversationId, `${conversationId}.jsonl`); - if (!existsSync(filePath)) { - return undefined; - } - - // A conversation that exists only in the database has no transcript and never reaches this - // point — the transcript file is the sole source of session identity. - const activity = tracking.get(conversationId); - const window = activityWindow(filePath, activity); + const filePath = transcript?.filePath ?? virtualTranscriptPath(root, composerId); + const activity = tracking.get(composerId); + const window = resolveWindow(header, filePath, activity); if (!window) { return undefined; } return { - sessionId: conversationId, + sessionId: composerId, filePath, - projectPath: - projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, this.slugPaths), + projectPath: resolveProjectPath(header, transcript?.slug, activity, this.slugPaths), createdAt: window.createdAt, updatedAt: window.updatedAt, agentName: this.agentName, @@ -543,24 +722,33 @@ export class CursorSessionAdapter implements SessionAdapter { } /** - * Parse one conversation transcript. + * Parse one conversation. * - * The conversation id is the file's own basename, which is also the key the AI-tracking - * database joins on, so no separate correlation step is needed. + * The conversation id is the file's own basename, which is also the key both the AI-tracking + * database and the composer index join on, so no separate correlation step is needed. A + * header-only session (see the module doc comment) has a synthetic, never-created `filePath` + * — `readCursorTranscript` and the file-time fallbacks all already degrade to "no data" for a + * path that does not exist, so nothing here needs a separate code path for that case except + * the slug walk, which has no slug to walk without a real transcript. */ async parseSessionFile(filePath: string, sessionId: string): Promise { const conversationId = basename(filePath, '.jsonl'); - const lines = readCursorTranscript(filePath); - const activity = (await this.trackingIndex()).get(conversationId); + const hasTranscript = existsSync(filePath); + const lines = hasTranscript ? readCursorTranscript(filePath) : []; + const [activity, composerIndex] = await Promise.all([ + this.trackingIndex().then((index) => index.get(conversationId)), + this.composerIndex(), + ]); + const header = composerIndex.get(conversationId); const { messages, userPrompts, tools } = flattenTranscript(lines); applyModels(messages, activity?.models ?? []); + applyBranch(messages, header?.branch); - const window = activityWindow(filePath, activity); - const slug = slugOfTranscript(filePath); - const projectPath = - projectPathFromFiles(slug, activity?.files ?? []) ?? projectPathFromSlug(slug, this.slugPaths); + const window = resolveWindow(header, filePath, activity); + const slug = hasTranscript ? slugOfTranscript(filePath) : undefined; + const projectPath = resolveProjectPath(header, slug, activity, this.slugPaths); logger.debug( `[cursor-adapter] ${conversationId}: ${messages.length} message(s), ${userPrompts.length} prompt(s)` @@ -573,6 +761,7 @@ export class CursorSessionAdapter implements SessionAdapter { projectPath, createdAt: window === undefined ? undefined : new Date(window.createdAt).toISOString(), updatedAt: window === undefined ? undefined : new Date(window.updatedAt).toISOString(), + branch: header?.branch, }, // No per-message timestamps exist, and inventing them would make the report show a // duration Cursor never recorded. Leaving them out makes the loader fall back to the @@ -584,7 +773,11 @@ export class CursorSessionAdapter implements SessionAdapter { metrics: { tools, userPrompts, - fileOperations: fileOperationsFrom(activity), + fileOperations: [ + ...(fileOperationsFrom(activity) ?? []), + ...(aggregateLinesFileOp(header, projectPath, sessionId) ?? []), + ], + filesChangedCount: header?.filesChangedCount, }, }; } diff --git a/src/agents/plugins/cursor/cursor.state-db.ts b/src/agents/plugins/cursor/cursor.state-db.ts new file mode 100644 index 000000000..2fc0c5a6a --- /dev/null +++ b/src/agents/plugins/cursor/cursor.state-db.ts @@ -0,0 +1,273 @@ +/** + * Session discovery from Cursor's internal `state.vscdb` — the `composerHeaders` table. + * + * `state.vscdb` is VS Code/Cursor's own undocumented internal state store, not a stable public + * API (see `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). `composerHeaders` + * holds one row per Cursor Agent conversation, keyed by `composerId` — the same identifier used + * as the `agent-transcripts` directory name and `ai_code_hashes.conversationId` elsewhere in + * this plugin. Its row shape is unconfirmed: it may be flat columns, or (as is common for + * VS Code/Cursor internal tables) a `key TEXT, value TEXT` pair with `value` holding a JSON + * blob. Both shapes are handled defensively below. + * + * Everything here is fail-soft by mandate, exactly like `cursor.tracking-db.ts`: an absent + * file, an absent `node:sqlite` (Node < 22.5), a renamed table or column, a corrupt file, or a + * locked database all degrade to an empty index — never a thrown error. A single malformed row + * must not lose the rest of the table. + * + * Draft sessions (`isDraft: true`) are never started, so surfacing them as discoverable + * sessions would be misleading; they are filtered out before entering the returned index. + * + * Reads are strictly read-only: the database is opened with `readOnly: true` and only + * SELECTed. + */ + +import { existsSync } from 'fs'; +import { logger } from '../../../utils/logger.js'; +import { getCursorStateDbPath } from './cursor.paths.js'; + +/** What `composerHeaders` knows about one Cursor Agent conversation. */ +export interface CursorComposerHeader { + /** The conversation id — shared with `agent-transcripts` and `ai_code_hashes`. */ + composerId: string; + /** Absolute workspace path, resolved from `workspaceIdentifier.uri.fsPath`, when present. */ + projectPath?: string; + /** Git branch the conversation ran on, when Cursor recorded one. */ + branch?: string; + /** Epoch ms the conversation was created, when recorded. */ + createdAt?: number; + /** Epoch ms the conversation was last updated, when recorded. */ + updatedAt?: number; + /** Total lines added across the conversation, when recorded. */ + linesAdded?: number; + /** Total lines removed across the conversation, when recorded. */ + linesRemoved?: number; + /** Count of files touched across the conversation, when recorded. */ + filesChangedCount?: number; +} + +/** composerId → header. An empty map means "no sessions discoverable". */ +export type CursorComposerIndex = Map; + +/** A `composerHeaders` row in either of its possible shapes — never assumed, always guarded. */ +interface ComposerRow { + key?: unknown; + value?: unknown; + composerId?: unknown; + workspaceIdentifier?: unknown; + activeBranch?: unknown; + createdOnBranch?: unknown; + createdAt?: unknown; + updatedAt?: unknown; + totalLinesAdded?: unknown; + totalLinesRemoved?: unknown; + filesChangedCount?: unknown; + isDraft?: unknown; +} + +function asString(value: unknown): string | undefined { + return typeof value === 'string' && value.trim() ? value : undefined; +} + +function asNumber(value: unknown): number | undefined { + return typeof value === 'number' && Number.isFinite(value) ? value : undefined; +} + +function asEpochMs(value: unknown): number | undefined { + const num = asNumber(value); + return num !== undefined && num > 0 ? num : undefined; +} + +function asBoolean(value: unknown): boolean { + return value === true || value === 1 || value === 'true' || value === '1'; +} + +/** + * `workspaceIdentifier.uri.fsPath` may be a plain string field, or (rarer, seen on some Cursor + * builds) a `file://…` URI string in place of the object. Both decode to the same absolute + * path; anything else is not a shape this loader recognizes and leaves `projectPath` undefined. + */ +function extractProjectPath(workspaceIdentifier: unknown): string | undefined { + if (!workspaceIdentifier || typeof workspaceIdentifier !== 'object') { + return undefined; + } + + const uri = (workspaceIdentifier as { uri?: unknown }).uri; + + if (typeof uri === 'string') { + return decodeFileUri(uri); + } + + if (uri && typeof uri === 'object') { + const fsPath = asString((uri as { fsPath?: unknown }).fsPath); + if (fsPath) { + return fsPath; + } + } + + return undefined; +} + +function decodeFileUri(uri: string): string | undefined { + if (!uri.startsWith('file://')) { + return undefined; + } + + try { + return decodeURIComponent(uri.slice('file://'.length)) || undefined; + } catch (error) { + logger.debug(`[cursor] unable to decode file URI "${uri}":`, error); + return undefined; + } +} + +function extractBranch(row: { + activeBranch?: unknown; + createdOnBranch?: unknown; +}): string | undefined { + if (row.activeBranch && typeof row.activeBranch === 'object') { + const branchName = asString((row.activeBranch as { branchName?: unknown }).branchName); + if (branchName) { + return branchName; + } + } + + return asString(row.createdOnBranch); +} + +/** + * `key` is only present on the key/value table shape and, when it names a composerId at all, + * commonly prefixes it (e.g. `composerHeaderData:`). Take the last `:`-delimited + * segment either way — a bare id round-trips through this unchanged. + */ +function composerIdFromKey(key: unknown): string | undefined { + const raw = asString(key); + if (!raw) { + return undefined; + } + const segments = raw.split(':'); + return asString(segments[segments.length - 1]); +} + +function normalizeHeader(source: { + composerId?: unknown; + workspaceIdentifier?: unknown; + activeBranch?: unknown; + createdOnBranch?: unknown; + createdAt?: unknown; + updatedAt?: unknown; + totalLinesAdded?: unknown; + totalLinesRemoved?: unknown; + filesChangedCount?: unknown; +}): Omit { + return { + projectPath: extractProjectPath(source.workspaceIdentifier), + branch: extractBranch(source), + createdAt: asEpochMs(source.createdAt), + updatedAt: asEpochMs(source.updatedAt), + linesAdded: asNumber(source.totalLinesAdded), + linesRemoved: asNumber(source.totalLinesRemoved), + filesChangedCount: asNumber(source.filesChangedCount), + }; +} + +/** + * `node:sqlite`, or null where it does not exist. + * + * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot be a + * static import: on Node 20 it would throw at module load and take the whole analytics run + * down. Cursor session discovery from `state.vscdb` is optional — older runtimes simply see no + * Cursor sessions from this source. + */ +async function loadSqlite(): Promise { + try { + return await import('node:sqlite'); + } catch (error) { + logger.debug('[cursor] node:sqlite unavailable — skipping composer index:', error); + return null; + } +} + +/** + * Build the composerId → header index, or an empty map when the database cannot be read. + * + * Never throws. + */ +export async function readCursorComposerIndex( + dbPath: string = getCursorStateDbPath() +): Promise { + const index: CursorComposerIndex = new Map(); + + if (!existsSync(dbPath)) { + logger.debug(`[cursor] no state database at ${dbPath}`); + return index; + } + + const sqlite = await loadSqlite(); + if (!sqlite) { + return index; + } + + let db: InstanceType | undefined; + try { + db = new sqlite.DatabaseSync(dbPath, { readOnly: true }); + const rows = db.prepare('SELECT * FROM composerHeaders').all() as ComposerRow[]; + + for (const row of rows) { + try { + let composerId: string | undefined; + let header: Omit; + let isDraft: unknown; + + const value = asString(row.value); + if (value !== undefined) { + let parsed: unknown; + try { + parsed = JSON.parse(value); + } catch (error) { + logger.debug(`[cursor] unparsable composerHeaders value for key "${String(row.key)}":`, error); + continue; + } + + if (!parsed || typeof parsed !== 'object') { + continue; + } + + const parsedRow = parsed as ComposerRow; + composerId = asString(parsedRow.composerId) ?? composerIdFromKey(row.key); + header = normalizeHeader(parsedRow); + isDraft = parsedRow.isDraft; + } else { + composerId = asString(row.composerId); + header = normalizeHeader(row); + isDraft = row.isDraft; + } + + if (!composerId) { + continue; + } + + if (asBoolean(isDraft)) { + continue; + } + + index.set(composerId, { composerId, ...header }); + } catch (error) { + // A single malformed row must not lose the rest of the table. + logger.debug('[cursor] skipping unreadable composerHeaders row:', error); + } + } + } catch (error) { + // Missing table, renamed column, corrupt file, locked database — all the same to us. + logger.debug(`[cursor] state database unusable at ${dbPath}:`, error); + return new Map(); + } finally { + try { + db?.close(); + } catch { + // closing a database we failed to open is not an error worth reporting + } + } + + logger.debug(`[cursor] composer index covers ${index.size} session(s)`); + return index; +} diff --git a/src/agents/plugins/cursor/index.ts b/src/agents/plugins/cursor/index.ts index 60a8123a2..5045f4973 100644 --- a/src/agents/plugins/cursor/index.ts +++ b/src/agents/plugins/cursor/index.ts @@ -6,6 +6,13 @@ export { CURSOR_DISPLAY_NAME, } from './cursor.constants.js'; export { CursorSessionAdapter } from './cursor.session.js'; -export { getCursorHome, getCursorProjectsRoot, getCursorTrackingDbPath } from './cursor.paths.js'; +export { + getCursorHome, + getCursorProjectsRoot, + getCursorTrackingDbPath, + getCursorStateDbPath, +} from './cursor.paths.js'; export { readCursorTrackingIndex } from './cursor.tracking-db.js'; export type { CursorConversationActivity, CursorTrackingIndex } from './cursor.tracking-db.js'; +export { readCursorComposerIndex } from './cursor.state-db.js'; +export type { CursorComposerHeader, CursorComposerIndex } from './cursor.state-db.js'; diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index 93ee7f273..16903e61b 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -123,6 +123,54 @@ function writeCorruptDb(): void { writeFileSync(join(dir, 'ai-code-tracking.db'), 'this is not a sqlite file', 'utf-8'); } +interface ComposerHeaderRow { + composerId: string; + /** Overrides the row's `key` column; defaults to the bare `composerId`. */ + key?: string; + /** Drops `composerId` from the JSON value, forcing the reader to fall back to `key`. */ + omitComposerIdField?: boolean; + isDraft?: boolean; + projectPath?: string; + branch?: string; + createdOnBranch?: string; + createdAt?: number; + updatedAt?: number; + linesAdded?: number; + linesRemoved?: number; + filesChangedCount?: number; +} + +/** + * A fixture `state.vscdb` with Cursor's real `composerHeaders` key/value table shape — the + * primary session-discovery source (see `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). + * `CURSOR_HOME` relocates it to `/User/globalStorage/state.vscdb`, mirroring + * `getCursorStateDbPath()`. + */ +async function writeComposerHeaders(rows: ComposerHeaderRow[]): Promise { + const { DatabaseSync } = await import('node:sqlite'); + const dir = join(cursorHome, 'User', 'globalStorage'); + mkdirSync(dir, { recursive: true }); + const db = new DatabaseSync(join(dir, 'state.vscdb')); + db.exec('CREATE TABLE composerHeaders (key TEXT, value TEXT)'); + const insert = db.prepare('INSERT INTO composerHeaders (key, value) VALUES (?, ?)'); + for (const row of rows) { + const value = JSON.stringify({ + composerId: row.omitComposerIdField ? undefined : row.composerId, + isDraft: row.isDraft, + workspaceIdentifier: row.projectPath ? { uri: { fsPath: row.projectPath } } : undefined, + activeBranch: row.branch ? { branchName: row.branch } : undefined, + createdOnBranch: row.createdOnBranch, + createdAt: row.createdAt, + updatedAt: row.updatedAt, + totalLinesAdded: row.linesAdded, + totalLinesRemoved: row.linesRemoved, + filesChangedCount: row.filesChangedCount, + }); + insert.run(row.key ?? row.composerId, value); + } + db.close(); +} + /** A managed agent's native session, for contrast with the unmanaged Cursor rows. */ const claudeDiscovery: DiscoveredNative = { agentName: 'claude', @@ -355,20 +403,15 @@ describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor enrichment from expect(cursorRows(rows)[0].deltas[0].fileOperations).toEqual([]); }); - it('produces no session for a conversation that exists only in the database', async () => { + it('discovers a composerHeaders-only session with no transcript on disk (issue #10: composerHeaders became the primary discovery source, so a conversation that used to be invisible without a transcript file now surfaces as a real, transcript-less row instead of being dropped)', async () => { writeTranscript('conv-a', conversation('add cursor analytics')); - await writeTrackingDb([ - { - conversationId: 'composer-only', - fileName: join(projectDir, 'src', 'app.ts'), - model: 'claude-4.5-sonnet', - timestamp: FIRST_EDIT_MS, - }, + await writeComposerHeaders([ + { composerId: 'header-only', projectPath: projectDir, createdAt: FIRST_EDIT_MS, updatedAt: LAST_EDIT_MS }, ]); const { rows } = await runLoader(); - expect(cursorRows(rows).map((s) => s.sessionId)).toEqual(['conv-a']); + expect(cursorRows(rows).map((s) => s.sessionId).sort()).toEqual(['conv-a', 'header-only']); }); }); @@ -409,6 +452,116 @@ describe('loadNativeSessions — Cursor degrades to transcript-only rows', () => }); }); +/** + * `composerHeaders` in `state.vscdb` is the primary session-discovery source (see the module + * doc comment in `cursor.session.ts` and `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`); + * a transcript is no longer required for a conversation to be discoverable, and when a header + * exists it settles project path, branch and line counts outright instead of the transcript-only + * fallbacks (slug walk, tracking-db files, prompt stamps) exercised elsewhere in this file. + */ +describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor composerHeaders as the primary discovery source', () => { + it('surfaces project, branch, line counts and files-changed from a composerHeaders-only session', async () => { + // No transcript exists for this composerId, so there are no messages to stamp `gitBranch` + // onto — project path, line counts and files-changed all come straight off the header and + // never depended on a message existing. Branch used to be message-only too (see + // `applyBranch` in cursor.session.ts) and so would have silently gone missing for exactly + // this — the majority — shape of session; `synthesizeRawSession`'s branch resolution now + // falls back to `parsed.metadata.branch` when there are no messages to vote over, which is + // what lets this session still report one. + await writeComposerHeaders([ + { + composerId: 'header-full', + projectPath: projectDir, + branch: 'feature/header-only', + createdAt: FIRST_EDIT_MS, + updatedAt: LAST_EDIT_MS, + linesAdded: 42, + linesRemoved: 7, + filesChangedCount: 3, + }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.sessionId).toBe('header-full'); + expect(row.startEvent!.data.workingDirectory).toBe(projectDir); + expect(row.deltas[0].gitBranch).toBe('feature/header-only'); + expect(row.deltas[0].filesChangedCount).toBe(3); + expect(row.deltas[0].fileOperations).toEqual([ + { type: 'edit', path: projectDir, linesAdded: 42, linesRemoved: 7 }, + ]); + }); + + it('excludes a draft composerHeaders row from discovery entirely', async () => { + // A draft was never started, so surfacing it as a discoverable session would be misleading. + await writeComposerHeaders([{ composerId: 'draft-one', projectPath: projectDir, isDraft: true }]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)).toEqual([]); + }); + + it('takes the project path and branch from the header rather than the slug walk when a session has both', async () => { + // The transcript's own slug resolves to nothing on disk, so if the header were being + // ignored this would report 'Unknown' instead of the header's real project path. Branch is + // stamped onto the transcript's own messages here (see `applyBranch` in cursor.session.ts); + // the header-only test above exercises the message-less fallback path instead. + writeTranscript('both-conv', conversation('ship it'), 'Users-nobody-vanished-project'); + await writeComposerHeaders([ + { composerId: 'both-conv', projectPath: projectDir, branch: 'feature/cursor-header' }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.startEvent!.data.workingDirectory).toBe(projectDir); + expect(row.deltas[0].gitBranch).toBe('feature/cursor-header'); + }); + + it('prefers the header’s own timestamps over the tracking database’s recorded edit times', async () => { + writeTranscript('window-conv', conversation('ship it')); + const headerCreated = Date.now() - 10 * HOUR; + const headerUpdated = Date.now() - 9 * HOUR; + await writeComposerHeaders([ + { composerId: 'window-conv', projectPath: projectDir, createdAt: headerCreated, updatedAt: headerUpdated }, + ]); + await writeTrackingDb([ + { + conversationId: 'window-conv', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.startEvent!.data.startTime).toBe(headerCreated); + expect(row.endEvent!.data.endTime).toBe(headerUpdated); + }); + + it('resolves the composerId from a prefixed key when the JSON value carries none', async () => { + // `key` on the key/value table shape commonly prefixes the id (e.g. + // `composerHeaderData:`); the reader takes the last `:`-delimited segment. + await writeComposerHeaders([ + { + composerId: 'prefixed-conv', + key: 'composerHeaderData:prefixed-conv', + omitComposerIdField: true, + projectPath: projectDir, + createdAt: FIRST_EDIT_MS, + updatedAt: LAST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows).map((s) => s.sessionId)).toEqual(['prefixed-conv']); + }); +}); + describe('loadNativeSessions — Cursor absent', () => { it('yields no Cursor sessions when there is no Cursor home', async () => { process.env.CURSOR_HOME = join(cursorHome, 'does-not-exist'); diff --git a/src/cli/commands/analytics/aggregator.ts b/src/cli/commands/analytics/aggregator.ts index f00b5c1c1..db8cfadc4 100644 --- a/src/cli/commands/analytics/aggregator.ts +++ b/src/cli/commands/analytics/aggregator.ts @@ -418,7 +418,9 @@ export class AnalyticsAggregator { totalLinesRemoved, totalLinesModified, netLinesChanged, - filesChanged: changedPaths.size, + filesChanged: deltas.some((d) => d.filesChangedCount !== undefined) + ? deltas.reduce((sum, d) => sum + (d.filesChangedCount ?? 0), 0) + : changedPaths.size, filesWritten: writtenPaths.size, filesEdited: editedPaths.size, totalToolCalls, diff --git a/src/cli/commands/analytics/native-loader.ts b/src/cli/commands/analytics/native-loader.ts index 29dae0c3d..4be5fd934 100644 --- a/src/cli/commands/analytics/native-loader.ts +++ b/src/cli/commands/analytics/native-loader.ts @@ -347,6 +347,7 @@ function buildNativeRawSession( tools: parsed.metrics?.tools ?? {}, toolStatus: parsed.metrics?.toolStatus, fileOperations: parsed.metrics?.fileOperations as MetricDelta['fileOperations'], + ...(parsed.metrics?.filesChangedCount !== undefined && { filesChangedCount: parsed.metrics.filesChangedCount }), models, // Named invocations are extracted at parse time (e.g. claude.session.ts extractMetrics); // carry them through so native (untracked) sessions populate the skill/agent/command charts. @@ -556,7 +557,13 @@ export function synthesizeRawSession( return buildNativeRawSession(agentName, descriptor, parsed, { cwd: messages.find((m) => m.cwd)?.cwd ?? descriptor.projectPath ?? 'Unknown', - branch: modal(messages.map((m) => m.gitBranch).filter((b): b is string => !!b)), + // Per-message gitBranch is the primary signal (it can change mid-session, so a mode vote is + // the honest summary) — but a session that recorded no messages at all (e.g. a Cursor + // conversation known only through composerHeaders, with no matching transcript) has nothing + // to vote over. `parsed.metadata.branch` is where an adapter puts a session-level branch it + // knows some other way; falling back to it here is what lets such a session still report a + // branch instead of silently losing one. + branch: modal(messages.map((m) => m.gitBranch).filter((b): b is string => !!b)) ?? parsed.metadata.branch, startTime: timestamps.length ? Math.min(...timestamps) : descriptor.createdAt, endTime: timestamps.length ? Math.max(...timestamps) : descriptor.updatedAt ?? descriptor.createdAt, turns: Math.max(assistantMsgs.length, 1), From e3d92f139d5277d2a926fe8069b95d96f3d0d4cf Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:55 +0300 Subject: [PATCH 12/34] feat(analytics): enrich Cursor sessions from cursorDiskKV bubbles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per ADR 0001 / issue #11: replace assumed-success tool-call counting and always-unpriced Cursor sessions with real per-turn signal from state.vscdb's cursorDiskKV table (bubbleId:: rows, one per turn/message, joined by the same composerId used for composerHeaders discovery). - New cursor.bubbles.ts: fail-soft cursorDiskKV reader, scoped per composerId via a parameterized LIKE query (never scans the whole table). Sums toolFormerData.status into per-tool success/failure counts ('completed' -> success, 'error'/'cancelled' -> failure, 'loading' -> not counted), and totals tokenCount.inputTokens/ outputTokens across bubbles, flagging hasTokenSignal when any bubble carried a nonzero count. - cursor.session.ts: parseSessionFile now sets metrics.toolStatus from bubble tool outcomes (independent of transcript presence, so header-only sessions — the majority — get real tool stats too) and resolves usageMeta via resolveUsageMeta: a session with any token signal gets usagePartial: true + tokensByModel (summed tokens attributed to the conversation's single recorded model, or 'unknown'); a session with none keeps the existing usageUnavailableReason path, never a fabricated $0.00. - BaseSessionAdapter.ts: added usageMeta.tokensByModel — a session-level token total for an adapter with no per-message usage a standard usage-readers.ts reader can walk. - cost-enricher.ts: enrichCosts() falls back to tokensByModel (routed through the same pricing table as every other agent) only when the per-message/per-agent readers produced nothing, so an agent with a working reader is never overridden. aggregator.ts and native-loader.ts needed no changes: toolStatus was already threaded end-to-end from a prior change, and the report/cost UI already renders usagePartial generically. Refs #11 --- src/agents/core/session/BaseSessionAdapter.ts | 9 + src/agents/plugins/cursor/cursor.bubbles.ts | 236 ++++++++++++++++++ src/agents/plugins/cursor/cursor.session.ts | 72 ++++-- src/agents/plugins/cursor/index.ts | 2 + .../__tests__/native-loader-cursor.test.ts | 137 +++++++++- .../cost/__tests__/cost-enricher.test.ts | 25 ++ .../commands/analytics/cost/cost-enricher.ts | 30 +++ 7 files changed, 495 insertions(+), 16 deletions(-) create mode 100644 src/agents/plugins/cursor/cursor.bubbles.ts diff --git a/src/agents/core/session/BaseSessionAdapter.ts b/src/agents/core/session/BaseSessionAdapter.ts index 195e27a8f..865ca20a4 100644 --- a/src/agents/core/session/BaseSessionAdapter.ts +++ b/src/agents/core/session/BaseSessionAdapter.ts @@ -63,6 +63,15 @@ export interface ParsedSession { usagePartial?: boolean; /** Why this session has no usage data; absent when usage was found. */ usageUnavailableReason?: string; + /** + * Session-level token totals for an agent whose native format has no per-message usage + * the standard per-agent readers in `cost/usage-readers.ts` can walk (e.g. Cursor's + * transcript carries no tokens at all — real counts only exist per-turn in a separate + * store, unaligned with transcript messages). The cost enricher prices this directly + * instead of routing it through a per-message reader; combine with `usagePartial: true` + * when the totals are known to be incomplete rather than an authoritative rollup. + */ + tokensByModel?: Record; }; // Parsed metrics data (optional - for metrics processor) diff --git a/src/agents/plugins/cursor/cursor.bubbles.ts b/src/agents/plugins/cursor/cursor.bubbles.ts new file mode 100644 index 000000000..17ba59a37 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.bubbles.ts @@ -0,0 +1,236 @@ +/** + * Per-turn enrichment from Cursor's internal `state.vscdb` — the `cursorDiskKV` table. + * + * `cursorDiskKV` is VS Code/Cursor's own undocumented internal key/value store, not a stable + * public API (see `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). It holds one + * row per bubble (turn/message) keyed `bubbleId::`, interleaved with + * unrelated `composerData:*` keys and, in aggregate, up to ~1.4GB of unrelated VS Code state — + * so every read here filters by `composerId` in SQL rather than scanning the whole table. + * + * Each bubble row carries a `toolFormerData.status` (`completed` / `error` / `cancelled` / + * `loading`) and `toolFormerData.name`, used to build per-tool success/failure counts, plus a + * sparse `tokenCount: {inputTokens, outputTokens}` present on roughly 1% of bubbles — enough to + * signal that partial pricing is possible, not enough to guarantee full coverage. + * + * Everything here is fail-soft by mandate, exactly like `cursor.state-db.ts`: an absent file, an + * absent `node:sqlite` (Node < 22.5), a renamed table or column, a corrupt file, a locked + * database, or a malformed individual row all degrade to a zeroed-out summary — never a thrown + * error. A single malformed row must not lose the rest of the bubbles. + * + * Reads are strictly read-only: the database is opened with `readOnly: true` and only + * SELECTed, with the composerId parameterized (never interpolated) into the query. + */ + +import { existsSync } from 'fs'; +import { logger } from '../../../utils/logger.js'; +import { getCursorStateDbPath } from './cursor.paths.js'; + +/** Aggregated tool-outcome and token-usage signal for one Cursor Agent conversation's bubbles. */ +export interface CursorBubbleSummary { + /** Per-tool success/failure counts, keyed by toolFormerData.name. Only tools with a resolved (non-'loading') status are counted. */ + toolStatus: Record; + /** Sum of inputTokens across every bubble that had a tokenCount object, however sparse. */ + totalInputTokens: number; + /** Sum of outputTokens across every bubble that had a tokenCount object. */ + totalOutputTokens: number; + /** True iff at least one bubble carried a nonzero inputTokens or outputTokens — the signal that gates partial pricing. */ + hasTokenSignal: boolean; +} + +function emptySummary(): CursorBubbleSummary { + return { toolStatus: {}, totalInputTokens: 0, totalOutputTokens: 0, hasTokenSignal: false }; +} + +function asString(value: unknown): string | undefined { + return typeof value === 'string' && value.trim() ? value : undefined; +} + +function asNumber(value: unknown): number | undefined { + return typeof value === 'number' && Number.isFinite(value) ? value : undefined; +} + +function asPositiveNumber(value: unknown): number { + const num = asNumber(value); + return num !== undefined && num > 0 ? num : 0; +} + +/** A `cursorDiskKV` bubble row in either of its possible shapes — never assumed, always guarded. */ +interface BubbleRow { + key?: unknown; + value?: unknown; + toolFormerData?: unknown; + tokenCount?: unknown; +} + +/** + * Escape `%`, `_`, and `\` in a LIKE pattern fragment so a composerId containing them cannot + * widen or corrupt the match. composerIds are expected to be UUID-like, but this is never + * trusted — the value ultimately comes from Cursor's own undocumented, unversioned storage. + */ +function escapeLikeFragment(value: string): string { + return value.replace(/[\\%_]/g, (char) => `\\${char}`); +} + +/** + * `toolFormerData` may arrive as a plain object (flat-column row shape) or, after JSON-parsing + * a key/value row's `value` blob, as a parsed object too — same shape either way, just guarded + * defensively since SQLite hands back `unknown` in both cases. + */ +function applyToolStatus( + toolFormerData: unknown, + toolStatus: Record +): boolean { + if (!toolFormerData || typeof toolFormerData !== 'object') { + return false; + } + + const name = asString((toolFormerData as { name?: unknown }).name); + if (!name) { + // Can't attribute an outcome to nothing. + return false; + } + + const status = asString((toolFormerData as { status?: unknown }).status); + if (status !== 'completed' && status !== 'error' && status !== 'cancelled') { + // 'loading' or any other/missing status is not a resolved outcome. + return false; + } + + const counts = (toolStatus[name] ??= { success: 0, failure: 0 }); + if (status === 'completed') { + counts.success += 1; + } else { + counts.failure += 1; + } + return true; +} + +/** + * `tokenCount` may arrive as a plain object (flat-column row shape) or a parsed JSON object + * (key/value row shape) — same guarded handling either way. + */ +function applyTokenCount( + tokenCount: unknown, + summary: CursorBubbleSummary +): boolean { + if (!tokenCount || typeof tokenCount !== 'object') { + return false; + } + + const inputTokens = asPositiveNumber((tokenCount as { inputTokens?: unknown }).inputTokens); + const outputTokens = asPositiveNumber((tokenCount as { outputTokens?: unknown }).outputTokens); + + summary.totalInputTokens += inputTokens; + summary.totalOutputTokens += outputTokens; + + return inputTokens > 0 || outputTokens > 0; +} + +/** + * `node:sqlite`, or null where it does not exist. + * + * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot be a + * static import: on Node 20 it would throw at module load and take the whole analytics run + * down. Cursor bubble enrichment from `state.vscdb` is optional — older runtimes simply see no + * tool/token signal from this source. + */ +async function loadSqlite(): Promise { + try { + return await import('node:sqlite'); + } catch (error) { + logger.debug('[cursor] node:sqlite unavailable — skipping bubble summary:', error); + return null; + } +} + +/** + * Summarize tool outcomes and token usage across every bubble belonging to one Cursor Agent + * conversation, or a zeroed-out summary when the database cannot be read. + * + * Never throws. + */ +export async function readCursorBubbles( + composerId: string, + dbPath: string = getCursorStateDbPath() +): Promise { + const summary = emptySummary(); + + if (!existsSync(dbPath)) { + logger.debug(`[cursor] no state database at ${dbPath}`); + return summary; + } + + const sqlite = await loadSqlite(); + if (!sqlite) { + return summary; + } + + let db: InstanceType | undefined; + let toolOutcomeCount = 0; + let tokenSignalCount = 0; + let scannedCount = 0; + + try { + db = new sqlite.DatabaseSync(dbPath, { readOnly: true }); + const pattern = `bubbleId:${escapeLikeFragment(composerId)}:%`; + const rows = db + .prepare("SELECT key, value FROM cursorDiskKV WHERE key LIKE ? ESCAPE '\\'") + .all(pattern) as BubbleRow[]; + + for (const row of rows) { + scannedCount += 1; + try { + let toolFormerData: unknown; + let tokenCount: unknown; + + const value = asString(row.value); + if (value) { + let parsed: unknown; + try { + parsed = JSON.parse(value); + } catch (error) { + logger.debug(`[cursor] unparsable cursorDiskKV value for key "${String(row.key)}":`, error); + continue; + } + if (!parsed || typeof parsed !== 'object') { + continue; + } + const parsedRow = parsed as BubbleRow; + toolFormerData = parsedRow.toolFormerData; + tokenCount = parsedRow.tokenCount; + } else { + toolFormerData = row.toolFormerData; + tokenCount = row.tokenCount; + } + + if (applyToolStatus(toolFormerData, summary.toolStatus)) { + toolOutcomeCount += 1; + } + if (applyTokenCount(tokenCount, summary)) { + tokenSignalCount += 1; + summary.hasTokenSignal = true; + } + } catch (error) { + // A single malformed row must not lose the rest of the bubbles. + logger.debug('[cursor] skipping unreadable cursorDiskKV row:', error); + } + } + } catch (error) { + // Missing table, renamed column, corrupt file, locked database — all the same to us. + logger.debug(`[cursor] state database unusable at ${dbPath}:`, error); + return emptySummary(); + } finally { + try { + db?.close(); + } catch { + // closing a database we failed to open is not an error worth reporting + } + } + + logger.debug( + `[cursor] bubble summary for composer ${composerId} scanned ${scannedCount} bubble(s): ` + + `${toolOutcomeCount} with a tool outcome, ${tokenSignalCount} with a token signal` + ); + + return summary; +} diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index 909acd4a8..79b63b85f 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -29,13 +29,18 @@ * otherwise report a span of days rather than of minutes; * - messages are emitted deliberately WITHOUT per-message timestamps, so the native loader * falls back to the descriptor's window instead of a fabricated per-message clock; - * - `usageMeta.usageUnavailableReason` is always set, which is what makes the report render - * tokens and cost as unmeasurable rather than as a confident zero. + * - `usageMeta.usageUnavailableReason` is set only when `cursorDiskKV`'s bubbles carried no + * token signal at all for the session — see {@link resolveUsageMeta} — which is what makes + * the report render tokens and cost as unmeasurable rather than as a confident zero for the + * (large) majority of sessions the sparse per-turn token data never touches. * * Model and edited-file lists still come from the AI-tracking database, joined by the same - * `composerId`/`conversationId` — see {@link CursorSessionAdapter.setTrackingIndex}. When - * either store is missing, locked, on a runtime without `node:sqlite`, or schema-drifted, the - * join simply finds nothing and the session degrades to whatever the remaining sources supply. + * `composerId`/`conversationId` — see {@link CursorSessionAdapter.setTrackingIndex}. Per-tool + * call outcomes (success/failure) and partial token pricing come from `state.vscdb`'s + * `cursorDiskKV` table (`bubbleId::` rows), joined the same way — see + * `cursor.bubbles.ts`. When any of these stores is missing, locked, on a runtime without + * `node:sqlite`, or schema-drifted, the join simply finds nothing and the session degrades to + * whatever the remaining sources supply. * * Messages are emitted in the Claude-shaped `{type, message: {role, content}}` form (with * `gitBranch` stamped alongside `message` — see {@link applyBranch}) on purpose: @@ -67,6 +72,8 @@ import type { CursorConversationActivity, CursorTrackingIndex } from './cursor.t import { readCursorTrackingIndex } from './cursor.tracking-db.js'; import type { CursorComposerHeader, CursorComposerIndex } from './cursor.state-db.js'; import { readCursorComposerIndex } from './cursor.state-db.js'; +import type { CursorBubbleSummary } from './cursor.bubbles.js'; +import { readCursorBubbles } from './cursor.bubbles.js'; import type { CursorMessageLine, CursorTranscriptLine } from './cursor.transcript.js'; import { contentBlocks, @@ -84,14 +91,14 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000; const TRANSCRIPTS_DIR = 'agent-transcripts'; /** - * Why a Cursor session is never priced. - * - * Cursor stores no token counts anywhere on disk — not in the transcript, not in the - * AI-tracking database. Reporting zero cost would read as "this session was free"; the - * reason string makes the report say "unmeasurable" instead. + * Why a Cursor session has no priced usage — used only when `cursorDiskKV` carried no token + * signal for it at all (see {@link resolveUsageMeta}; most sessions, since the per-turn + * `tokenCount` field is present on roughly 1% of bubbles per ADR 0001). Reporting zero cost + * would read as "this session was free"; the reason string makes the report say "unmeasurable" + * instead. */ const NO_USAGE_REASON = - 'Cursor records no token usage locally — its transcripts carry no token counts, so cost cannot be derived'; + "Cursor records token usage on only a sparse fraction of turns — this session's bubbles carried none, so cost cannot be derived"; /** Trailing-separator-insensitive directory comparison. */ function sameDir(a: string | undefined, b: string): boolean { @@ -413,6 +420,36 @@ function aggregateLinesFileOp( ]; } +/** + * Usage provenance for a session, from its `cursorDiskKV` bubbles. + * + * Cursor's per-turn token counts are sparse (~1% of bubbles, per ADR 0001) and have no + * alignment to transcript messages, so there is nothing for a per-message reader to walk — + * unlike a fabricated confident zero, `usagePartial: true` tells the report this total + * understates the session's real usage. A session with no token signal anywhere keeps the + * existing "unmeasurable" reason instead of a $0.00 that would read as "this was free". + * + * The summed tokens are attributed to the conversation's own recorded model (from the + * AI-tracking database — the same single-value case {@link applyModels} already prefers) when + * unambiguous, or `'unknown'` when no single model is recorded; an unrecognized model name + * simply prices as unpriced rather than misattributing spend to the wrong model. + */ +function resolveUsageMeta( + bubbles: CursorBubbleSummary, + activity: CursorConversationActivity | undefined +): NonNullable { + if (!bubbles.hasTokenSignal) { + return { usageUnavailableReason: NO_USAGE_REASON }; + } + const model = activity?.models[0] ?? 'unknown'; + return { + usagePartial: true, + tokensByModel: { + [model]: { inputTokens: bubbles.totalInputTokens, outputTokens: bubbles.totalOutputTokens }, + }, + }; +} + /** What one transcript's lines amount to, once the shape Cursor writes is set aside. */ interface FlattenedTranscript { messages: CursorNativeMessage[]; @@ -735,9 +772,10 @@ export class CursorSessionAdapter implements SessionAdapter { const conversationId = basename(filePath, '.jsonl'); const hasTranscript = existsSync(filePath); const lines = hasTranscript ? readCursorTranscript(filePath) : []; - const [activity, composerIndex] = await Promise.all([ + const [activity, composerIndex, bubbles] = await Promise.all([ this.trackingIndex().then((index) => index.get(conversationId)), this.composerIndex(), + readCursorBubbles(conversationId), ]); const header = composerIndex.get(conversationId); @@ -767,11 +805,15 @@ export class CursorSessionAdapter implements SessionAdapter { // duration Cursor never recorded. Leaving them out makes the loader fall back to the // descriptor's file-derived window, which is the only real signal available. messages, - usageMeta: { - usageUnavailableReason: NO_USAGE_REASON, - }, + usageMeta: resolveUsageMeta(bubbles, activity), metrics: { tools, + // Real per-tool success/failure, from cursorDiskKV's toolFormerData.status — replaces + // the old assumed-success behavior (a tool named in `tools` but absent here just means + // no bubble resolved an outcome for it, e.g. a call still 'loading' when scanned). + // Populated independent of `hasTranscript`: bubbles are keyed by composerId directly, + // so a header-only session (most of them) gets real tool outcomes too. + ...(Object.keys(bubbles.toolStatus).length > 0 && { toolStatus: bubbles.toolStatus }), userPrompts, fileOperations: [ ...(fileOperationsFrom(activity) ?? []), diff --git a/src/agents/plugins/cursor/index.ts b/src/agents/plugins/cursor/index.ts index 5045f4973..b05916fa1 100644 --- a/src/agents/plugins/cursor/index.ts +++ b/src/agents/plugins/cursor/index.ts @@ -16,3 +16,5 @@ export { readCursorTrackingIndex } from './cursor.tracking-db.js'; export type { CursorConversationActivity, CursorTrackingIndex } from './cursor.tracking-db.js'; export { readCursorComposerIndex } from './cursor.state-db.js'; export type { CursorComposerHeader, CursorComposerIndex } from './cursor.state-db.js'; +export { readCursorBubbles } from './cursor.bubbles.js'; +export type { CursorBubbleSummary } from './cursor.bubbles.js'; diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index 16903e61b..c4f5c31ac 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -171,6 +171,49 @@ async function writeComposerHeaders(rows: ComposerHeaderRow[]): Promise { db.close(); } +interface BubbleFixture { + /** Defaults to an incrementing counter when omitted — only the composerId prefix matters to the reader. */ + bubbleId?: string; + toolName?: string; + toolStatus?: 'completed' | 'error' | 'cancelled' | 'loading'; + inputTokens?: number; + outputTokens?: number; +} + +let bubbleIdCounter = 0; + +/** + * A fixture `cursorDiskKV` table in the SAME `state.vscdb` file `writeComposerHeaders` writes + * to — real bubble rows are keyed `bubbleId::` (see `cursor.bubbles.ts`). + * Uses `CREATE TABLE IF NOT EXISTS` since a test may call this before or after + * `writeComposerHeaders` touches the same file; the two tables never collide. + * + * A fixture row that specifies neither tool data nor token data omits `toolFormerData`/ + * `tokenCount` entirely from the JSON value, exactly mirroring a real bubble that carries + * neither — this lets a test build bubbles with only tool data, only token data, or both. + */ +async function writeCursorBubbles(composerId: string, bubbles: BubbleFixture[]): Promise { + const { DatabaseSync } = await import('node:sqlite'); + const dir = join(cursorHome, 'User', 'globalStorage'); + mkdirSync(dir, { recursive: true }); + const db = new DatabaseSync(join(dir, 'state.vscdb')); + db.exec('CREATE TABLE IF NOT EXISTS cursorDiskKV (key TEXT, value TEXT)'); + const insert = db.prepare('INSERT INTO cursorDiskKV (key, value) VALUES (?, ?)'); + for (const bubble of bubbles) { + const bubbleId = bubble.bubbleId ?? `bubble-${(bubbleIdCounter += 1)}`; + const hasToolData = bubble.toolName !== undefined || bubble.toolStatus !== undefined; + const hasTokenData = bubble.inputTokens !== undefined || bubble.outputTokens !== undefined; + const value = JSON.stringify({ + ...(hasToolData && { toolFormerData: { name: bubble.toolName, status: bubble.toolStatus } }), + ...(hasTokenData && { + tokenCount: { inputTokens: bubble.inputTokens, outputTokens: bubble.outputTokens }, + }), + }); + insert.run(`bubbleId:${composerId}:${bubbleId}`, value); + } + db.close(); +} + /** A managed agent's native session, for contrast with the unmanaged Cursor rows. */ const claudeDiscovery: DiscoveredNative = { agentName: 'claude', @@ -582,7 +625,13 @@ describe('loadNativeSessions — Cursor absent', () => { }); }); -describe('loadNativeSessions — Cursor never reports tokens, cost or line counts', () => { +// This block's own tests write no bubbles at all, so `readCursorBubbles` returns a zeroed +// summary and the `usageUnavailableReason` path below still applies to them unchanged. With a +// real bubble token signal (see the "Cursor bubble enrichment" describe block further down), +// Cursor CAN report a partial `usagePartial`/`tokensByModel` usage instead — that path is +// conditional on `hasTokenSignal`, not universally absent, which is what makes this describe's +// old name ("never reports tokens") no longer an accurate universal claim. +describe('loadNativeSessions — Cursor reports no usage or line counts without a bubble signal', () => { it('states why usage is unavailable instead of reporting zero', async () => { writeTranscript('conv-a', conversation('add cursor analytics')); @@ -616,6 +665,92 @@ describe('loadNativeSessions — Cursor never reports tokens, cost or line count }); }); +/** + * `cursorDiskKV` bubble rows in the SAME `state.vscdb` file `composerHeaders` lives in (see + * `cursor.bubbles.ts` and `docs/adr/`) are the source for real per-tool success/failure counts + * and, on the sparse fraction of bubbles that carry a nonzero `tokenCount`, partial token + * pricing. Bubbles are keyed by composerId directly, so enrichment applies identically whether + * or not a transcript exists on disk for the conversation. + */ +describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor bubble enrichment from cursorDiskKV', () => { + it('reports real per-tool success/failure counts from resolved bubble statuses', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeCursorBubbles('conv-a', [ + { toolName: 'edit_file', toolStatus: 'completed' }, + { toolName: 'edit_file', toolStatus: 'error' }, + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].deltas[0].toolStatus).toEqual({ edit_file: { success: 1, failure: 1 } }); + }); + + it('does not let a still-loading bubble skew or fabricate a tool outcome', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeCursorBubbles('conv-a', [ + { toolName: 'read_file', toolStatus: 'completed' }, + { toolName: 'run_terminal', toolStatus: 'loading' }, + ]); + + const { rows } = await runLoader(); + const toolStatus = cursorRows(rows)[0].deltas[0].toolStatus; + + expect(toolStatus).toEqual({ read_file: { success: 1, failure: 0 } }); + expect(toolStatus).not.toHaveProperty('run_terminal'); + }); + + it('reports usagePartial with the summed tokens when a bubble carries a real token signal', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeTrackingDb([ + { + conversationId: 'conv-a', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: FIRST_EDIT_MS, + }, + ]); + await writeCursorBubbles('conv-a', [ + { inputTokens: 120, outputTokens: 40 }, + { inputTokens: 0, outputTokens: 0 }, // present but zero: must not itself trip the signal + ]); + + const { parsed } = await runLoader(); + + expect(parsed[0].usageMeta).toEqual({ + usagePartial: true, + tokensByModel: { 'claude-4.5-sonnet': { inputTokens: 120, outputTokens: 40 } }, + }); + }); + + it('keeps the usageUnavailableReason path when bubbles are present but carry no nonzero token count', async () => { + writeTranscript('conv-a', conversation('add cursor analytics')); + await writeCursorBubbles('conv-a', [ + { toolName: 'edit_file', toolStatus: 'completed' }, + { inputTokens: 0, outputTokens: 0 }, + ]); + + const { parsed } = await runLoader(); + + expect(parsed[0].usageMeta).toEqual({ + usageUnavailableReason: expect.stringContaining('Cursor'), + }); + expect(parsed[0].usageMeta).not.toHaveProperty('usagePartial'); + }); + + it('enriches a header-only session (no transcript) with real toolStatus from its bubbles', async () => { + await writeComposerHeaders([ + { composerId: 'header-only', projectPath: projectDir, createdAt: FIRST_EDIT_MS, updatedAt: LAST_EDIT_MS }, + ]); + await writeCursorBubbles('header-only', [{ toolName: 'edit_file', toolStatus: 'completed' }]); + + const { rows } = await runLoader(); + const row = cursorRows(rows).find((s) => s.sessionId === 'header-only'); + + expect(row).toBeDefined(); + expect(row!.deltas[0].toolStatus).toEqual({ edit_file: { success: 1, failure: 0 } }); + }); +}); + /** * Cursor's project slug is lossy — it replaces `/` and `_` alike with `-` — so a slug cannot be * reversed by splitting on `-`. Nearly every real project trips this: a home directory like diff --git a/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts b/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts index 383ccf0bf..dbfa946ee 100644 --- a/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts +++ b/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts @@ -80,6 +80,31 @@ describe('enrichCosts', () => { expect(index.get('s1')!.agentSessionFile).toBeUndefined(); }); + it('prices from usageMeta.tokensByModel when no per-message reader produced usage (e.g. Cursor)', async () => { + // No messages at all — there is nothing for a per-message reader to walk — but the adapter + // supplied a session-level total via usageMeta, which is the fallback under test. + const deps: EnricherDeps = { + ...baseDeps, + parseNative: async () => + ({ + sessionId: 's1', + agentName: 'cursor', + metadata: {}, + messages: [], + usageMeta: { + usagePartial: true, + tokensByModel: { 'claude-sonnet-4-5': { inputTokens: 500_000, outputTokens: 0 } }, + }, + }) as never, + }; + const { index } = await enrichCosts(raw, deps); + const c = index.get('s1')!; + expect(c.priced).toBe(true); + expect(c.costUSD).toBeCloseTo(1.5, 6); // 500k input @ $3/1M sonnet-4-5 + expect(c.tokens.input).toBe(500_000); + expect(c.usagePartial).toBe(true); + }); + it('prices a codex session from token_count events', async () => { const { readFileSync } = await import('node:fs'); const { join } = await import('node:path'); diff --git a/src/cli/commands/analytics/cost/cost-enricher.ts b/src/cli/commands/analytics/cost/cost-enricher.ts index 544ce58d9..aabe7ec75 100644 --- a/src/cli/commands/analytics/cost/cost-enricher.ts +++ b/src/cli/commands/analytics/cost/cost-enricher.ts @@ -106,6 +106,28 @@ async function parseOne(raw: RawSessionData, deps: EnricherDeps): Promise): Map { + const out = new Map(); + for (const [model, t] of Object.entries(tokensByModel)) { + out.set(model, { + input: t.inputTokens, + output: t.outputTokens, + cacheRead: 0, + cacheCreation: 0, + cacheCreation1h: 0, + total: t.inputTokens + t.outputTokens, + }); + } + return out; +} + /** Phase 3: price an already-gathered (deduped) per-model usage map for one session. */ function priceUsage( sessionId: string, @@ -359,6 +381,14 @@ export async function enrichCosts( series = []; records = []; } + // An adapter with no per-message usage reader (see usage-readers.ts) can still know a + // session-level total some other way — Cursor's real per-turn token counts live in a + // separate store with no alignment to transcript messages, so there is nothing for a + // per-message reader to walk. `usageMeta.tokensByModel` is that adapter-supplied total; + // only used as a fallback so an agent WITH a working per-message reader is never overridden. + if (usageByModel.size === 0 && entry.parsed?.usageMeta?.tokensByModel) { + usageByModel = tokensByModelUsage(entry.parsed.usageMeta.tokensByModel); + } const { cost, unpriced: u } = priceUsage(entry.sessionId, entry.hadLog, usageByModel); if (entry.filePath) { // Same path that made hadLog/pricing true — so a consumer never sees "priced" and From abfd7260e693990e8fe86a442dea46d27944230a Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:56 +0300 Subject: [PATCH 13/34] docs(analytics): Cursor integration guide, ADR, and deferred Team Analytics API note Add `docs/CURSOR_INTEGRATION.md`: overview of the analytics-only Cursor agent, the four local data sources and how they join on `composerId`, the `CURSOR_HOME` override and per-OS `state.vscdb` paths, schema/versioning stance, a troubleshooting section, and developer guidance on fixtures, read-only connection safety and schema evolution. Add `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`, which six source files already cite but which did not exist, recording why an undocumented store is read and the constraints that come with it. Record Cursor's Enterprise Team Analytics API in the external-integrations guide as a known, deferred capability: enterprise-admin-scoped, no token or cost fields at any tier, a future integration gated on both a token and an explicit opt-in flag, scoped to the requesting user only, and blocked on having no join key to a local composerId-keyed session. Cross-reference the new guide from AGENTS.md, docs/ANALYTICS-REPORT.md and the external-integrations guide. Closes #9 Closes #12 --- .../integration/external-integrations.md | 47 ++++ AGENTS.md | 2 +- docs/ANALYTICS-REPORT.md | 3 +- docs/CURSOR_INTEGRATION.md | 225 ++++++++++++++++++ ...rsor-session-discovery-from-state-vscdb.md | 69 ++++++ 5 files changed, 344 insertions(+), 2 deletions(-) create mode 100644 docs/CURSOR_INTEGRATION.md create mode 100644 docs/adr/0001-cursor-session-discovery-from-state-vscdb.md diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index 03c9319b8..aee38b6f7 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -300,6 +300,51 @@ 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//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`. + +Full operational and developer guide: `docs/CURSOR_INTEGRATION.md`. Rationale for reading an +undocumented store: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`. + +### Cursor Enterprise Team Analytics API (not integrated) + +Cursor publishes an official Team Analytics API +(). **CodeMie does not integrate it today.** +It is recorded here as a known, deferred capability so the constraints below are not re-derived — +or, worse, so nothing is wired up that silently makes network calls. + +What the API is: + +- **Enterprise-team-only** and gated on an **admin-scoped API key**. An individual user on a + personal plan cannot use it at all. +- Documented endpoints: `agent-edits`, `tabs`, `dau`, `models`, `commands`, + `conversation-insights`, `leaderboard`, `bugbot`. +- **None of these endpoints returns token or cost fields at any tier.** The API cannot fill + CodeMie's biggest Cursor gap. + +Agreed constraints for any future integration: + +- **Trigger model.** A configured token alone must never enable network calls. Both the token + *and* an explicit opt-in flag at invocation are required, mirroring how `--include-external` + gates external sessions. Reading local files is a promise CodeMie already makes; calling a + remote service is not, and must stay an explicit act. +- **Data scope.** User-wide only: the `by-user` endpoints filtered to the requesting user's own + email. Not team-wide data, not the leaderboard. CodeMie analytics reports the operator's own + usage, and pulling colleagues' activity into it is out of scope. +- **Unsolved reconciliation problem.** The API returns per-user/per-date aggregates with **no + join key to a local `composerId`-keyed session**. There is therefore no way to enrich + `ReportSessionRecord` rows with it. Any integration would have to render a **separate summary + section**, clearly labelled as team-API data, rather than merging into the session table — + attempting the merge would silently double-count or mis-attribute. + +Full context: ADR 0001, [`docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`](../../../docs/adr/0001-cursor-session-discovery-from-state-vscdb.md). + ## Configuration Validation Validate provider config at startup; warn (not throw) on connectivity failures. `file:src/env/config-loader.ts:150-170` @@ -322,6 +367,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 +380,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`, ADR: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`) - MCP proxy: `src/mcp/` - Session adapters: `src/agents/core/session/` - Config loader: `src/env/config-loader.ts` diff --git a/AGENTS.md b/AGENTS.md index 123047a9c..7b92d7b92 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -223,7 +223,7 @@ See `package.json` for exact dependency versions and `.ai-run/guides/architectur | `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/` | `@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) | +| `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`). diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 04c43c77c..6b9716394 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -235,6 +235,7 @@ CodeMie merges two sources to give the most complete picture: 1. **Tracked sessions** — metrics written by the CodeMie hooks during sessions CodeMie launched 2. **Native agent logs** — transcripts left on disk by `claude`, `codex`, `gemini`, `pi`, and `copilot`, discovered automatically and deduped against tracked sessions +3. **Analytics-only agents** — agents CodeMie never launches and only reads. `cursor` is the one today: its conversations are read from Cursor's own local stores and surfaced like any other external session. See [Cursor Integration](CURSOR_INTEGRATION.md). Pass `--no-scan-native` to disable native-log discovery and use only CodeMie-tracked sessions. @@ -262,7 +263,7 @@ That default is the right one for adoption reporting and the **wrong** one for c codemie analytics --report --open --include-external ``` -**This is the flag that shows all of your local agent usage.** GitHub Copilot CLI sessions are included in the gate, so they too are absent from the default report. +**This is the flag that shows all of your local agent usage.** GitHub Copilot CLI sessions are included in the gate, so they too are absent from the default report. Cursor sessions are too — CodeMie never launches Cursor, so *every* Cursor session is external; see [Cursor Integration](CURSOR_INTEGRATION.md). Two things to know before you rely on the wider number: diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md new file mode 100644 index 000000000..113aa6ed7 --- /dev/null +++ b/docs/CURSOR_INTEGRATION.md @@ -0,0 +1,225 @@ +# Cursor Integration + +How CodeMie reads Cursor usage into `codemie analytics`, what it can and cannot know, and what +to do when the numbers look wrong. + +## Overview + +Cursor is CodeMie's first **analytics-only** agent (`analyticsOnly: true` in +`src/agents/plugins/cursor/cursor.plugin.ts`). CodeMie never installs, configures, updates or +launches Cursor, and Cursor is absent from every management surface — `codemie install`, +`codemie update`, `codemie doctor`, first-run setup. There is no npm package, no CLI command and +no provider mapping. The plugin exists solely to hand the agent registry a session adapter that +reads what Cursor has already written to disk. + +Because CodeMie never launches Cursor, no Cursor session carries a CodeMie ownership marker, so +every Cursor session is tagged `native-external` and is **hidden until you pass +`--include-external`** — the same gate that applies to any agent run outside CodeMie (see +[Session provenance](ANALYTICS-REPORT.md#session-provenance)): + +```bash +codemie analytics --report --open --include-external +``` + +All reads are strictly read-only and fail-soft. CodeMie never writes to, migrates or locks a +store Cursor owns, and no Cursor problem — missing data, corrupt database, schema change — can +fail an analytics run for the other agents. + +## Data locations and structure + +Cursor writes to two unrelated trees — `~/.cursor` and the editor's own app-data directory — and CodeMie reads four sources across them. `CURSOR_HOME` overrides both (see +[Environment configuration](#environment-configuration)). + +| Source | Path | Supplies | +|---|---|---| +| **`composerHeaders`** (primary discovery) | `state.vscdb` → `composerHeaders` table | one row per agent conversation, keyed `composerId`: project path (`workspaceIdentifier.uri.fsPath`), branch (`activeBranch.branchName` / `createdOnBranch`), created/updated timestamps, `totalLinesAdded` / `totalLinesRemoved` / `filesChangedCount` | +| **Agent transcripts** (secondary) | `~/.cursor/projects//agent-transcripts//.jsonl` | role-tagged prompt/response text, `tool_use` blocks, `turn_ended` markers, a human-readable `` on each prompt | +| **AI-tracking database** (enrichment) | `~/.cursor/ai-tracking/ai-code-tracking.db` → `ai_code_hashes` (`conversationId`, `fileName`, `model`, `timestamp`, `source`) | model, edited file paths, first/last edit time, joined on `conversationId`; only `source = 'composer'` rows are the agent's work — `human` rows are the user's own edits | +| **`cursorDiskKV`** (enrichment) | `state.vscdb` → `cursorDiskKV`, keys `bubbleId::` | per-tool success/failure counts (`toolFormerData.status` / `.name`) and a sparse `tokenCount` | + +`state.vscdb` is the VS Code-derived *application* state store, so it lives under the OS +app-data directory rather than `~/.cursor`: + +| Platform | `state.vscdb` | +|---|---| +| macOS | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` | +| Windows | `%APPDATA%\Cursor\User\globalStorage\state.vscdb` (falling back to `~/AppData/Roaming/Cursor/...` when `%APPDATA%` is unset) | +| Linux | `~/.config/Cursor/User/globalStorage/state.vscdb` | + +Everything joins on one identifier: **`composerId`**, which is also the transcript's directory +and file name and `ai_code_hashes.conversationId`. Discovery unions the header ids with the +transcript ids, so a conversation with a header but no transcript (the common case) and a +transcript with no header (rare — schema drift, a pruned header row) both produce a session row. +Headers marked `isDraft: true` are conversations that were never started and are excluded. + +Full rationale for reading an undocumented store, and the constraints that come with it, is in +[ADR 0001](adr/0001-cursor-session-discovery-from-state-vscdb.md). + +### What Cursor sessions can and cannot report + +- **Activity window** prefers the header's own timestamps, then the tracking database's first/last + edit, then the transcript's prompt stamps, and only then the transcript file's birthtime/mtime. + File times are last because a conversation resumed days later would otherwise report a span of + days instead of minutes. +- **Messages carry no per-message timestamps** on purpose, so the loader falls back to the + session window rather than a fabricated per-message clock. +- **Model** comes from the tracking database. Cursor writes the literal `default` when the user + delegated model choice; that is reported as **`Auto`** — Cursor's own word for it — never as + whatever model Cursor happens to default to. +- **Tokens and cost** come from `cursorDiskKV`'s sparse per-bubble `tokenCount` (present on + roughly 1% of bubbles). When a session has no token signal at all, `usageUnavailableReason` is + set and the report renders tokens and cost as **unmeasurable**, not as a confident zero. + +### Database schema and versioning + +`state.vscdb` and `ai-code-tracking.db` are Cursor-internal and undocumented; there is no schema +version to read and no compatibility promise. CodeMie therefore pins nothing and asserts nothing: +each query names the tables and columns it needs, and anything else — a renamed table, a dropped +column, a changed row shape — degrades to "that source contributed nothing" for this run. +`composerHeaders` rows in particular are handled in both observed shapes (flat columns, and the +VS Code-typical `key TEXT, value TEXT` pair with a JSON blob in `value`, whose key may itself carry +a `:` form). `cursorDiskKV` values are JSON blobs holding `toolFormerData` +(`name`, `status` — one of `completed` / `error` / `cancelled` / `loading`) and an optional +`tokenCount` (`inputTokens`, `outputTokens`). + +There is no version marker in either database, so CodeMie cannot detect which Cursor release wrote +a schema and does not try. If you need to correlate drift with a release, the Cursor version is in +Cursor's own About dialog; pair it with the `[cursor] ... unusable` debug line naming the table or +column that moved (see [Database schema drift](#database-schema-drift-after-a-cursor-update)). + +## Environment configuration + +| Variable | Effect | +|---|---| +| `CURSOR_HOME` | Overrides `~/.cursor`. Also relocates `state.vscdb` to `$CURSOR_HOME/User/globalStorage/state.vscdb`, mirroring its real layout relative to Cursor's app-data root. Unset (the default) uses `~/.cursor` plus the per-OS app-data path above. | +| `CODEMIE_DEBUG=true` | Enables the `[cursor]` debug logging described under [Logging and debugging](#logging-and-debugging). | + +`CURSOR_HOME` mirrors `COPILOT_HOME` in the Copilot CLI plugin and is what lets the whole +ingestion path be driven against a fixture tree in tests. + +### When Cursor is not installed + +No Cursor home, an empty Cursor home, no `state.vscdb` and no tracking database all yield **zero +Cursor sessions and no error**. Analytics for every other agent is unaffected. Nothing about the +report changes except that Cursor does not appear in it. + +## Troubleshooting + +### Empty analytics results while you are actively using Cursor + +1. **You did not pass `--include-external`.** This is the overwhelmingly common cause. Cursor + sessions are hidden by default because CodeMie did not launch them. Re-run with + `codemie analytics --report --open --include-external`. +2. **Native scanning is off.** `--no-scan-native` turns off native-log discovery for *every* agent, + including the discovery `--include-external` asks for, so the two flags together add nothing. +3. **Your date filter excludes them.** Discovery looks back only as far as `--from` / `--last` + requires. +4. **A non-default Cursor location.** If Cursor stores data elsewhere, point `CURSOR_HOME` at it. +5. **`state.vscdb` is not where CodeMie looks.** Confirm the per-OS path above exists; run with + `CODEMIE_DEBUG=true` and look for the `[cursor]` lines naming the paths that were tried. + +### Missing or corrupt Cursor data + +Each source degrades independently, so a session is built from whatever remains: + +| Missing / broken | Result | +|---|---| +| Transcript file | Header-only row: project, branch, timing, line counts, model — but no prompt/response text | +| `composerHeaders` row | Transcript-only row: project path guessed by walking the directory slug, branch and line counts absent | +| `ai-code-tracking.db` | No model and no edited-file list; timing falls back to header or prompt stamps | +| `cursorDiskKV` rows | No tool outcomes; usage reported as unmeasurable | +| Corrupt / locked / unreadable database | Treated exactly like "absent" — that source contributes nothing | +| Unparseable transcript line | That line is dropped; the rest of the session is kept (a live session's last line is often truncated mid-write) | + +### Node runtime too old for `node:sqlite` + +`node:sqlite` landed in **Node 22.5**; this repo supports Node >= 20. On Node 20 or 22.0–22.4 the +import fails, both SQLite sources are skipped, and Cursor degrades to transcript-only rows. This +is deliberate — the module is imported dynamically so an older runtime cannot take the analytics +run down at module load. Upgrade to Node >= 22.5 for full Cursor enrichment. + +### Database schema drift after a Cursor update + +Symptom: Cursor sessions still appear, but model, tool outcomes, line counts or timing suddenly +go missing. Run with `CODEMIE_DEBUG=true` and look for `[cursor] ... unusable` lines — the +underlying SQLite error names the table or column that moved. This is a fail-soft degradation, +not a bug in your setup; the fix is a plugin update, not a workaround on your machine. + +### Permission issues with the Cursor home + +Symptom: nothing under `~/.cursor` or the app-data directory is readable. CodeMie logs the read +failure at debug level and reports zero Cursor sessions. Confirm with `ls -l ~/.cursor` and +`ls -l` on the `state.vscdb` directory for your platform; the files must be readable by the user +running `codemie`. CodeMie needs no write access anywhere in Cursor's trees. + +### Logging and debugging + +Every read of a Cursor data source logs at debug level, and nothing there +ever escalates past debug: a missing, corrupt or drifted Cursor store is a degradation, not a +failure, so there are no warnings to look for. The one exception is CodeMie's own side of the +pipeline — a session processor that throws is logged at error level as +`[cursor-adapter] Processor failed:`, because that is a CodeMie bug rather than a Cursor +condition. + +```bash +export CODEMIE_DEBUG=true +codemie analytics --report --include-external +``` + +Three prefixes are in use, so filter on `[cursor` rather than `[cursor]`: `[cursor]` for the data-source +reads, `[cursor-discovery]` for session discovery, `[cursor-adapter]` for the adapter itself. + +Expected messages include: `no ai-tracking database at `, `node:sqlite unavailable — skipping +tracking enrichment`, `ai-tracking database unusable at ` (with the SQLite error), and +`tracking index covers N conversation(s)`. + +## Developer guidance + +Source lives in `src/agents/plugins/cursor/`: `cursor.paths.ts` (locations and the `CURSOR_HOME` +override), `cursor.state-db.ts` (`composerHeaders` discovery), `cursor.bubbles.ts` (`cursorDiskKV` +per-turn enrichment), `cursor.tracking-db.ts` (AI-tracking enrichment), `cursor.transcript.ts` +(JSONL reader), `cursor.session.ts` (the adapter that joins them). + +### Creating test fixtures + +Tests drive the whole path from the top seam — `loadNativeSessions()` — against a temporary +Cursor home reached through `CURSOR_HOME`, never by reaching into a parser. See +`src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts` for the working pattern: + +1. `mkdtempSync()` a directory and set `process.env.CURSOR_HOME` to it, so the run touches + neither `~/.codemie` nor the developer's own `~/.cursor`. +2. Write transcripts at + `/projects//agent-transcripts//.jsonl`, where the slug is the project path + with leading separators dropped and `/` and `_` both replaced by `-`. +3. Write fixture SQLite databases at `/ai-tracking/ai-code-tracking.db` and + `/User/globalStorage/state.vscdb`. +4. Re-import the module graph per test (`vi.resetModules()`), because the adapter memoizes its + tracking index once per run and the memo would otherwise leak one fixture into the next. +5. Guard database-backed tests with `describe.skipIf(!hasNodeSqlite())` — Node < 22.5 cannot + create them, which is the same degradation the product promises. + +### Database connection safety + +- Open with `new sqlite.DatabaseSync(path, { readOnly: true })`, `SELECT` only, and `close()` in a + `finally` (itself wrapped, since closing a database that failed to open throws). +- Import `node:sqlite` **dynamically**; a static import breaks Node 20 at module load. +- Check `existsSync()` before opening, and treat every failure — missing table, renamed column, + corrupt file, locked database — as "no data", returning the empty result. +- Parameterize any id in a query; never interpolate. `cursorDiskKV` must be filtered in SQL rather + than scanned, as the table can reach ~1.4 GB. + +### Schema evolution guidelines + +When Cursor changes a schema, add tolerance rather than assertions. Guard every field +(`asString`, `asEpochMs` style helpers), accept both known row shapes where a table has them, +skip a malformed row instead of aborting the loop, and let a whole missing source degrade to an +empty index. Never report a value Cursor did not record: prefer an explicit "unmeasurable" +(`usageUnavailableReason`) or Cursor's own label (`Auto`) over a plausible-looking zero or +default. Any new source needs a fixture-driven test at the `loadNativeSessions()` seam plus a +degradation test proving analytics still works when that source is gone. + +## See also + +- [ADR 0001 — Cursor session discovery from `state.vscdb`](adr/0001-cursor-session-discovery-from-state-vscdb.md) +- [Analytics Report](ANALYTICS-REPORT.md) — provenance, `--include-external`, the report views +- [`.ai-run/guides/integration/external-integrations.md`](../.ai-run/guides/integration/external-integrations.md) — including the deferred Cursor Enterprise Team Analytics API diff --git a/docs/adr/0001-cursor-session-discovery-from-state-vscdb.md b/docs/adr/0001-cursor-session-discovery-from-state-vscdb.md new file mode 100644 index 000000000..34a2299fd --- /dev/null +++ b/docs/adr/0001-cursor-session-discovery-from-state-vscdb.md @@ -0,0 +1,69 @@ +# ADR 0001 — Cursor session discovery reads `state.vscdb` + +- Status: Accepted +- Date: 2026-09-04 +- Applies to: `src/agents/plugins/cursor/` + +## Context + +Cursor is an analytics-only agent: CodeMie never installs, configures or launches it, and only +reads what Cursor has already written to disk (see the `cursor` row in [AGENTS.md](../../AGENTS.md) +and [docs/CURSOR_INTEGRATION.md](../CURSOR_INTEGRATION.md)). + +Cursor exposes no local API and no supported export for agent conversations. Three local stores +carry parts of the picture, all keyed by the same `composerId`: + +| Store | Location | Carries | +|---|---|---| +| Agent transcripts | `~/.cursor/projects//agent-transcripts//.jsonl` | role-tagged text, `tool_use` blocks, turn markers, a human-readable prompt stamp | +| AI-tracking database | `~/.cursor/ai-tracking/ai-code-tracking.db` | model, edited file paths, edit timestamps | +| Application state store | `state.vscdb` under Cursor's per-OS app-data directory | `composerHeaders` (one row per conversation), `cursorDiskKV` (one row per turn/bubble) | + +Transcripts alone were tried first and proved insufficient: they exist for only a small fraction +of real conversations, carry no timestamps, no model and no token counts, and give no reliable +project path (only a slug that has to be walked back to a directory). A transcript-only report +therefore under-counts Cursor usage badly and mis-attributes the sessions it does find. + +`state.vscdb` is VS Code's (and hence Cursor's) internal, undocumented state store. It is not a +public API, its schema can change in any Cursor release, and it is large — up to ~1.4 GB of +mostly unrelated editor state. + +## Decision + +`composerHeaders` in `state.vscdb` is the **primary** discovery source for Cursor sessions; +transcripts are secondary and joined by the shared `composerId`. Discovery unions the two id +sets, so a header without a transcript and a transcript without a header both produce a row. +`cursorDiskKV` supplies per-turn tool outcomes and the sparse token signal that gates partial +pricing. The AI-tracking database supplies model and edited files. + +Constraints accepted with that decision: + +- **Read-only.** Every database is opened with `readOnly: true` and only ever `SELECT`ed. + CodeMie must never write to, migrate, or lock a store Cursor owns. +- **Fail-soft by mandate.** A missing file, a missing `node:sqlite` (Node < 22.5), a renamed + table or column, a corrupt or locked database, or a malformed row degrades to fewer facts — + never to a thrown error. A Cursor release must never be able to break `codemie analytics`. +- **Scoped queries.** `cursorDiskKV` is filtered by `composerId` in SQL (parameterized, never + interpolated) rather than scanned, because of its size. +- **No invented facts.** `default` — Cursor's sentinel for delegated model choice — is reported + as `Auto`, the term Cursor's own usage export uses, never as a concrete model name. Sessions + with no token signal report usage as unmeasurable rather than as zero. +- **Draft rows excluded.** `isDraft: true` headers are conversations that were never started. + +## Consequences + +- Cursor coverage is dramatically better than transcript-only discovery, and project path, + branch and line counts come from Cursor's own totals instead of being reconstructed. +- CodeMie depends on an undocumented schema. The fail-soft mandate is what makes that + acceptable: the failure mode of schema drift is a thinner report, not a broken command. +- `CURSOR_HOME` relocates all three stores (with `state.vscdb` under `User/globalStorage`), + which is what lets the whole path be tested against a fixture tree. + +## Future work + +### Cursor Enterprise Team Analytics API + +Cursor publishes an official [Team Analytics API](https://cursor.com/docs/account/teams/analytics-api). +CodeMie does **not** integrate it. It is recorded as a known, deferred capability — with the +constraints already agreed for whenever it is built — in +[`.ai-run/guides/integration/external-integrations.md`](../../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-not-integrated). From f92522ac33277e3c09b913d0e8091c1667df7b82 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:56 +0300 Subject: [PATCH 14/34] fix(analytics): dash unmeasurable usage and explain absent Cursor telemetry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The report labelled sessions with no local token signal "Included" — Cursor's own word for plan-covered usage — and the session modal called their cost "covered by subscription". Both state a billing fact we cannot know: the cost column is an API-equivalent estimate, not a bill, and missing telemetry is not evidence the usage was free. Every unmeasurable cost and token cell now shows an em dash; mixed groups still show the sum of whatever was measured. Overview's Est. cost and token KPIs also keyed off the summed totals, so a Cursor-only view (the shape you get after deselecting the measured agents) collapsed to bare dashes that read as a broken agent-chip filter. They now key off session provenance, and both Overview and Cost append a note saying local token telemetry is absent for the sessions in view. The Cost banner no longer blames rotated transcripts for every unpriced session, which contradicted that note for analytics-only agents. Agent chips still filter by agent name only, and tool-call tables are untouched. --- .../__tests__/report-cost-honesty.test.ts | 90 +++++++++++++++++++ .../commands/analytics/report/client/app.js | 45 ++++++---- 2 files changed, 119 insertions(+), 16 deletions(-) create mode 100644 src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts diff --git a/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts b/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts new file mode 100644 index 000000000..f3a08cbf3 --- /dev/null +++ b/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts @@ -0,0 +1,90 @@ +/** + * Report client cost-honesty contract test. + * + * The report client is a no-build vanilla IIFE, so its formatting helpers cannot be + * imported. Like `report-views.test.ts`, this asserts the contract against the source + * text: unmeasurable usage must render as an em dash, subscription wording must be gone, + * and the all-unmeasurable views must carry an explicit "no local telemetry" note. + */ + +import { describe, it, expect } from 'vitest'; +import { readFileSync } from 'fs'; +import { fileURLToPath } from 'url'; + +const app = readFileSync(fileURLToPath(new URL('../client/app.js', import.meta.url)), 'utf-8'); + +/** The source of a named `function name(...) { ... }` declaration, to its balanced closing brace. */ +function fnBody(name: string): string { + const start = app.indexOf(`function ${name}(`); + expect(start, `function ${name} not found`).toBeGreaterThan(-1); + let depth = 0; + for (let i = app.indexOf('{', start); i < app.length; i++) { + if (app[i] === '{') depth++; + else if (app[i] === '}' && --depth === 0) return app.slice(start, i + 1); + } + throw new Error(`unbalanced braces in ${name}`); +} + +/** The body of a top-level `VIEWS. = function (...) { ... }` block. */ +function viewSource(name: string): string { + const start = app.indexOf(`VIEWS.${name} = function`); + expect(start, `VIEWS.${name} not found`).toBeGreaterThan(-1); + const end = app.indexOf('\n VIEWS.', start + 1); + return app.slice(start, end === -1 ? app.length : end); +} + +describe('report client cost honesty', () => { + it('never labels unknown cost with subscription wording', () => { + expect(app).not.toMatch(/'Included'|"Included"/); + expect(app).not.toMatch(/covered by subscription/i); + }); + + it('formats unmeasurable cost and tokens as an em dash', () => { + expect(app).toMatch(/UNKNOWN_LABEL\s*=\s*'—'/); + // Per-session formatters dash on the session's own provenance; the aggregate one only + // when the whole group is unmeasurable, so a mixed group keeps showing the measured sum. + expect(fnBody('fmtUSDOf')).toMatch(/usageUnknown\(s\).*UNKNOWN_LABEL/); + expect(fnBody('fmtTokensOf')).toMatch(/usageUnknown\(s\).*UNKNOWN_LABEL/); + expect(fnBody('fmtUSDAgg')).toMatch(/anyMeasured\(list\).*UNKNOWN_LABEL/); + }); + + it('keeps mixed aggregates on the measured sum (aggregates dash only when nothing is measured)', () => { + expect(fnBody('anyMeasured')).toMatch(/\.some\(.*!usageUnknown\(s\)/); + }); + + it('states missing local telemetry in the session modal instead of a subscription', () => { + expect(app).toMatch(/usageUnknown\(s\) \? 'no local token telemetry' : 'API-equivalent'/); + }); +}); + +describe('report client all-unmeasurable empty state', () => { + const overview = viewSource('overview'); + const cost = viewSource('cost'); + + it('derives Overview cost and token KPIs from measured-set semantics', () => { + expect(overview).toMatch(/measured\s*=\s*anyMeasured\(fs\)/); + // Est. cost and every token KPI must go through `measured`, not a bare `totalCost`/`tTotal` truth test. + expect(overview).toMatch(/'Est\. cost', measured \? fmtUSD\(totalCost\) : UNKNOWN_LABEL/); + expect(overview).toMatch(/tkv = function \(v\) \{ return measured &&[^}]*UNKNOWN_LABEL/); + }); + + it('explains the absent local token telemetry on Overview and Cost', () => { + expect(app).toMatch(/NO_TELEMETRY_NOTE\s*=\s*'[^']*local token telemetry[^']*'/); + // Both views share one helper, so the note cannot drift between them. + expect(fnBody('appendNoTelemetryNote')).toMatch(/!anyMeasured\(list\).*NO_TELEMETRY_NOTE/); + expect(overview).toMatch(/appendNoTelemetryNote\(host, fs\)/); + expect(cost).toMatch(/appendNoTelemetryNote\(host, fs\)/); + }); + + it('keeps agent chips filtering by agent name only', () => { + expect(app).toMatch(/state\.agents\.has\(s\.agentName\)/); + expect(app).not.toMatch(/state\.agents\.has\(s\.model/); + }); + + it('keeps tool-call aggregation independent of usage measurability', () => { + // Tool tables read toolCalls/toolCallsTotal directly; they must not be gated on usage. + const toolStart = app.indexOf('var toolAgg'); + const toolBlock = app.slice(toolStart, app.indexOf("card('Tool usage & success rate')", toolStart)); + expect(toolBlock).not.toMatch(/usageUnknown|anyMeasured/); + }); +}); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index d79a43cb1..c50366771 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -60,15 +60,22 @@ // read as "this session was free", so every money/token cell goes through these helpers // and shows an em dash instead. Aggregates only dash out when NOTHING in the group was // measurable — a mixed group still shows the real sum of what was measured. - // "Included" is Cursor's own word: its usage export marks every such event Kind=Included, - // meaning covered by the subscription rather than separately priced. It is used only for the - // cost cell — a token count has no equivalent, so those stay an em dash. - var UNPRICED_LABEL = 'Included'; + // Cursor's own usage export calls such events Kind=Included ("covered by the plan"), but we + // deliberately do not reuse that word: the cost column is an API-equivalent estimate, not a + // bill, and a missing local token signal is not evidence that the usage was free. + var UNKNOWN_LABEL = '—'; function usageUnknown(s) { return !!(s && s.usageUnavailableReason); } function anyMeasured(list) { return (list || []).some(function (s) { return !usageUnknown(s); }); } - function fmtUSDOf(s, n) { return usageUnknown(s) ? UNPRICED_LABEL : fmtUSD(n); } - function fmtTokensOf(s, n) { return usageUnknown(s) ? '—' : fmtTokens(n); } - function fmtUSDAgg(list, n) { return anyMeasured(list) ? fmtUSD(n) : UNPRICED_LABEL; } + function fmtUSDOf(s, n) { return usageUnknown(s) ? UNKNOWN_LABEL : fmtUSD(n); } + function fmtTokensOf(s, n) { return usageUnknown(s) ? UNKNOWN_LABEL : fmtTokens(n); } + function fmtUSDAgg(list, n) { return anyMeasured(list) ? fmtUSD(n) : UNKNOWN_LABEL; } + // Shown on Overview/Cost when EVERY session in view is unmeasurable — the common shape after + // deselecting the measured agents and leaving only an analytics-only one such as Cursor. Without + // it the all-dash KPI row reads as a broken agent-chip filter rather than as absent data. + function appendNoTelemetryNote(host, list) { + if (list.length && !anyMeasured(list)) host.appendChild(el('div', 'alert alert-info', NO_TELEMETRY_NOTE)); + } + var NO_TELEMETRY_NOTE = 'No local token telemetry for the sessions in view — token and cost figures are unavailable, not zero. Analytics-only agents such as Cursor record transcripts and tool calls locally but no billable token counts; other panels on this report still work.'; function esc(s) { return String(s == null ? '' : s).replace(/[&<>"]/g, function (c) { return { '&': '&', '<': '<', '>': '>', '"': '"' }[c]; }); } function shortPath(p) { var parts = String(p || '').split('/'); return parts[parts.length - 1] || p; } @@ -328,17 +335,20 @@ var totalCost = sum(fs, function (s) { return s.costUSD; }); var priced = DATA.meta.totals.pricedSessions; + // Provenance, not arithmetic: a filtered set can sum to $0 either because nothing was spent or + // because nothing was measurable. Only the latter may claim a number, so gate on the sessions. + var measured = anyMeasured(fs); var kpis = [ ['Sessions', fmtNum(fs.length), ''], ['Duration', fmtDuration(sum(fs, function (s) { return s.durationMs; })), 'wall-clock span'], ['Turns', fmtNum(sum(fs, function (s) { return s.turns; })), fs.length ? (Math.round(sum(fs, function (s) { return s.turns; }) / fs.length) + ' / session') : ''], ['Files touched', fmtNum(sum(fs, function (s) { return s.fileOps; })), 'net ' + (sum(fs, function (s) { return s.netLines; }) >= 0 ? '+' : '') + fmtNum(sum(fs, function (s) { return s.netLines; })) + ' lines'], ['Tool calls', fmtNum(sum(fs, function (s) { return s.toolCallsTotal; })), successRate(fs) + '% success'], - ['Est. cost', totalCost ? fmtUSD(totalCost) : '—', priced < DATA.meta.totals.sessions ? ('priced ' + priced + '/' + DATA.meta.totals.sessions) : 'tokens × pricing'] + ['Est. cost', measured ? fmtUSD(totalCost) : UNKNOWN_LABEL, measured ? (priced < DATA.meta.totals.sessions ? ('priced ' + priced + '/' + DATA.meta.totals.sessions) : 'tokens × pricing') : 'no local token telemetry'] ]; var grid = el('div', 'kpi-grid'); kpis.forEach(function (k) { - var c = el('div', 'kpi' + (k[0] === 'Est. cost' && !totalCost ? ' soon' : '')); + var c = el('div', 'kpi' + (k[0] === 'Est. cost' && !measured ? ' soon' : '')); c.appendChild(el('div', 'kpi-label', k[0])); c.appendChild(el('div', 'kpi-value', k[1])); if (k[2]) c.appendChild(el('div', 'kpi-sub', k[2])); @@ -354,24 +364,25 @@ var tcWrite = sum(fs, function (s) { return s.tokens ? s.tokens.cacheCreation : 0; }); var tcRead = sum(fs, function (s) { return s.tokens ? s.tokens.cacheRead : 0; }); var tTotal = sum(fs, function (s) { return s.tokens ? s.tokens.total : 0; }); - var tkv = function (v) { return tTotal > 0 ? fmtTokens(v) : '—'; }; + var tkv = function (v) { return measured && tTotal > 0 ? fmtTokens(v) : UNKNOWN_LABEL; }; var tokenKpis = [ ['Input tokens', tkv(tIn), 'prompts sent to the model'], ['Output tokens', tkv(tOut), 'completions generated'], ['Cache write', tkv(tcWrite), 'tokens written to cache'], ['Cache read', tkv(tcRead), 'tokens served from cache'], - ['Total tokens', tkv(tTotal), priced < DATA.meta.totals.sessions ? ('priced ' + priced + '/' + DATA.meta.totals.sessions + ' sessions') : 'across sessions in view'] + ['Total tokens', tkv(tTotal), measured ? (priced < DATA.meta.totals.sessions ? ('priced ' + priced + '/' + DATA.meta.totals.sessions + ' sessions') : 'across sessions in view') : 'no local token telemetry'] ]; host.appendChild(el('div', 'kpi-section-label', 'Token usage')); var tgrid = el('div', 'kpi-grid kpi-grid-tokens'); tokenKpis.forEach(function (k) { var c = el('div', 'kpi'); c.appendChild(el('div', 'kpi-label', k[0])); - c.appendChild(el('div', 'kpi-value' + (tTotal > 0 ? '' : ' muted'), k[1])); + c.appendChild(el('div', 'kpi-value' + (measured && tTotal > 0 ? '' : ' muted'), k[1])); if (k[2]) c.appendChild(el('div', 'kpi-sub', k[2])); tgrid.appendChild(c); }); host.appendChild(tgrid); + appendNoTelemetryNote(host, fs); // efficiency headline KPIs (full detail on the Efficiency tab) var effCacheReadCost = sum(fs, function (s) { return s.cacheReadCostUSD || 0; }); @@ -815,15 +826,16 @@ VIEWS.cost = function (host, fs) { host.appendChild(el('h2', 'view-title', 'Cost')); - host.appendChild(el('p', 'view-sub', 'Estimated cost (API-equivalent) — token usage × model pricing. On a subscription you don’t pay per token; this is the equivalent metered API value.')); + host.appendChild(el('p', 'view-sub', 'Estimated cost (API-equivalent) — token usage × model pricing. This is what the same usage would have been metered at through the API, not an invoice.')); var total = sum(fs, function (s) { return s.costUSD; }); var priced = DATA.meta.totals.pricedSessions, totalSessions = DATA.meta.totals.sessions; var banner = el('div', 'alert ' + (priced < totalSessions ? 'alert-warning' : 'alert-info')); var msg = 'Priced ' + priced + ' of ' + totalSessions + ' sessions with recoverable token usage. ' - + 'The rest have no readable native log — coding agents rotate/delete old transcripts, so historical ' - + 'token data is incomplete (this does not affect the cost of the sessions that are priced). See Coverage by agent below.'; + + 'The rest carry no recoverable token counts: either the native log was rotated/deleted, or the agent ' + + 'records transcripts locally but no token telemetry at all (analytics-only agents such as Cursor). ' + + 'This does not affect the cost of the sessions that are priced. See Coverage by agent below.'; if (DATA.meta.unpricedModels && DATA.meta.unpricedModels.length) msg += ' Unpriced models: ' + DATA.meta.unpricedModels.join(', ') + '.'; banner.textContent = msg; // textContent is safe — do not pre-escape (would double-escape) host.appendChild(banner); @@ -834,6 +846,7 @@ var c = el('div', 'kpi'); c.appendChild(el('div', 'kpi-label', k[0])); c.appendChild(el('div', 'kpi-value', k[1])); grid.appendChild(c); }); host.appendChild(grid); + appendNoTelemetryNote(host, fs); // per-agent coverage — answers "which tools' metrics are included?" var cov = DATA.meta.coverage || []; @@ -1257,7 +1270,7 @@ // which bills in premium requests rather than tokens, and whose older CLI versions // recorded no telemetry at all). Appended so other agents' cards are unchanged. var costRows = [ - ['Cost', fmtUSDOf(s, s.costUSD), usageUnknown(s) ? 'covered by subscription' : 'API-equivalent'], + ['Cost', fmtUSDOf(s, s.costUSD), usageUnknown(s) ? 'no local token telemetry' : 'API-equivalent'], ['Cache-read', s.cacheReadCostUSD ? fmtUSD(s.cacheReadCostUSD) : '—', ''], ['Duration', fmtDuration(s.durationMs || 0), ''], ['Started', '' + esc(fmtWhen(s.startTime)) + '', ''] From 1bd36fa833ac127632aa3b3a0cb9b78ecb550908 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:37:57 +0300 Subject: [PATCH 15/34] feat(analytics): estimate unpriced-model cost at a Sonnet stand-in rate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cursor delegates model choice and records `default` (displayed as Auto), which matches no pricing row, so sessions with genuinely recovered tokens priced out at $0. A blank is less honest than a labelled floor when the token counts themselves are real: an unpriced model with tokens is now costed at the published Claude Sonnet API rate, marked `estimated` on the per-model row, and forced to `usagePartial` so the report badges it as a floor rather than a bill. Real attribution still wins — a model the table can price never touches the stand-in — and an unpriced model with zero tokens stays at $0 rather than becoming an invented estimate of nothing. The session keeps its own model label (Auto is not renamed to Sonnet, per ADR 0001) and coverage diagnostics still list it under unpriced models. The session-modal partial badge and the Cost banner now describe both ways a figure can be a floor: sparse token counts, or borrowed rates. --- .../cost/__tests__/cost-enricher.test.ts | 61 ++++++++++++++++++- .../commands/analytics/cost/cost-enricher.ts | 33 ++++++++-- src/cli/commands/analytics/cost/types.ts | 8 ++- .../commands/analytics/report/client/app.js | 4 +- 4 files changed, 97 insertions(+), 9 deletions(-) diff --git a/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts b/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts index dbfa946ee..0773fc684 100644 --- a/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts +++ b/src/cli/commands/analytics/cost/__tests__/cost-enricher.test.ts @@ -255,7 +255,10 @@ describe('enrichCosts', () => { }; const { index, summary } = await enrichCosts(raw, deps); expect(index.get('s1')!.priced).toBe(true); - expect(index.get('s1')!.costUSD).toBe(0); + // Real tokens with no matching price row are estimated at the stand-in rate and badged, + // rather than reported as $0 (issue 02); the model is still listed as unpriced. + expect(index.get('s1')!.costUSD).toBeGreaterThan(0); + expect(index.get('s1')!.usagePartial).toBe(true); expect(summary.unpricedModels).toContain('no-such-model-xyz'); }); @@ -611,3 +614,59 @@ describe('buildCostSeries', () => { expect(s[s.length - 1].tokens).toBe(200); // last cumulative total preserved }); }); + +/** + * Sessions that recovered real tokens but whose model is absent from the price table + * (Cursor reports `default`/Auto) still deserve an API-equivalent estimate — a blank is + * less honest than a labelled floor. See issue 02 of the cursor-analytics-cost-honesty spec. + */ +describe('unpriced-model cost estimation', () => { + /** An adapter that supplies session-level `tokensByModel` instead of per-message usage (the Cursor shape). */ + const adapterTokens = (tokensByModel: Record): EnricherDeps => ({ + ...baseDeps, + parseNative: async () => ({ sessionId: 's1', agentName: 'cursor', metadata: {}, messages: [], usageMeta: { tokensByModel } }) as never, + }); + + it('estimates an Auto/unpriced model at the Sonnet stand-in rate without renaming the model', async () => { + const { index, summary } = await enrichCosts(raw, adapterTokens({ default: { inputTokens: 1_000_000, outputTokens: 0 } })); + const c = index.get('s1')!; + expect(c.costUSD).toBeCloseTo(3, 6); // 1M input @ $3/1M — the claude-sonnet-4 stand-in + expect(c.usagePartial).toBe(true); + expect(c.perModel[0].model).toBe('default'); // NOT renamed to a Claude model + expect(c.perModel[0].estimated).toBe(true); + // Coverage diagnostics must still confess the model had no real price. + expect(c.perModel[0].unpriced).toBe(true); + expect(summary.unpricedModels).toContain('default'); + expect(c.priced).toBe(true); // "had recoverable usage" + }); + + it('prefers a real price when the model is in the table', async () => { + const { index } = await enrichCosts(raw, adapterTokens({ 'claude-opus-4-1': { inputTokens: 1_000_000, outputTokens: 0 } })); + const c = index.get('s1')!; + expect(c.costUSD).toBeGreaterThan(3.5); // opus input rate, not the $3 sonnet stand-in + expect(c.perModel[0].unpriced).toBe(false); + expect(c.perModel[0].estimated).toBeFalsy(); + expect(c.usagePartial).toBeFalsy(); // a real price is not a partial estimate + }); + + it('fabricates no estimate for an unpriced model with zero tokens', async () => { + const { index, summary } = await enrichCosts(raw, adapterTokens({ default: { inputTokens: 0, outputTokens: 0 } })); + const c = index.get('s1')!; + expect(c.costUSD).toBe(0); + expect(c.perModel[0].estimated).toBeFalsy(); + expect(c.usagePartial).toBeFalsy(); + expect(summary.totalCostUSD).toBe(0); + }); + + it('leaves a session with no token signal at all unmeasurable', async () => { + const deps: EnricherDeps = { + ...baseDeps, + parseNative: async () => ({ sessionId: 's1', agentName: 'cursor', metadata: {}, messages: [], usageMeta: { usageUnavailableReason: 'no token telemetry' } }) as never, + }; + const c = (await enrichCosts(raw, deps)).index.get('s1')!; + expect(c.costUSD).toBe(0); + expect(c.priced).toBe(false); + expect(c.usageUnavailableReason).toBe('no token telemetry'); + expect(c.usagePartial).toBeFalsy(); + }); +}); diff --git a/src/cli/commands/analytics/cost/cost-enricher.ts b/src/cli/commands/analytics/cost/cost-enricher.ts index aabe7ec75..5aaaa610e 100644 --- a/src/cli/commands/analytics/cost/cost-enricher.ts +++ b/src/cli/commands/analytics/cost/cost-enricher.ts @@ -128,27 +128,44 @@ function tokensByModelUsage(tokensByModel: Record -): { cost: SessionCost; unpriced: string[] } { +): { cost: SessionCost; unpriced: string[]; estimated: boolean } { const perModel: ModelCost[] = []; const unpriced: string[] = []; let sessionTokens = emptyUsage(); let sessionCost = 0; let cacheReadCostUSD = 0; + let estimated = false; for (const [rawModel, usage] of usageByModel) { const model = normalizeModelName(rawModel); - const price = lookupPrice(model); + // Real attribution always wins; the stand-in only steps in when there are genuine tokens + // to price. Zero tokens stay at $0 rather than becoming an invented estimate of nothing. + const ownPrice = lookupPrice(model); + const price = ownPrice ?? (usage.total > 0 ? lookupPrice(UNPRICED_ESTIMATE_MODEL) : null); const breakdown = price ? costBreakdown(usage, price) : null; const costUSD = breakdown ? breakdown.total : 0; - if (!price) { + const viaStandIn = !ownPrice && costUSD > 0; + if (!ownPrice) { + // Coverage diagnostics keep naming the real model (Auto/default), estimate or not. unpriced.push(model); } - perModel.push({ model, tokens: usage, costUSD, unpriced: !price }); + estimated = estimated || viaStandIn; + perModel.push({ model, tokens: usage, costUSD, unpriced: !ownPrice, ...(viaStandIn ? { estimated: true } : {}) }); sessionTokens = addUsage(sessionTokens, usage); sessionCost += costUSD; cacheReadCostUSD += breakdown ? breakdown.cacheRead : 0; @@ -160,6 +177,7 @@ function priceUsage( return { cost: { sessionId, tokens: sessionTokens, costUSD: sessionCost, cacheReadCostUSD, perModel, priced: perModel.length > 0, hadLog }, unpriced, + estimated, }; } @@ -389,7 +407,12 @@ export async function enrichCosts( if (usageByModel.size === 0 && entry.parsed?.usageMeta?.tokensByModel) { usageByModel = tokensByModelUsage(entry.parsed.usageMeta.tokensByModel); } - const { cost, unpriced: u } = priceUsage(entry.sessionId, entry.hadLog, usageByModel); + const { cost, unpriced: u, estimated } = priceUsage(entry.sessionId, entry.hadLog, usageByModel); + if (estimated) { + // Borrowed rates are an estimate by construction, so the report must badge them even + // when the adapter itself considered its token counts complete. + cost.usagePartial = true; + } if (entry.filePath) { // Same path that made hadLog/pricing true — so a consumer never sees "priced" and // "no file to show" disagree (see CR-002 in the file-location UI review). diff --git a/src/cli/commands/analytics/cost/types.ts b/src/cli/commands/analytics/cost/types.ts index fe0eb8e45..6bba9b67f 100644 --- a/src/cli/commands/analytics/cost/types.ts +++ b/src/cli/commands/analytics/cost/types.ts @@ -19,8 +19,14 @@ export interface TokenUsage { export interface ModelCost { model: string; // normalized model name tokens: TokenUsage; - costUSD: number; // 0 when unpriced + costUSD: number; // 0 when unpriced with no tokens to estimate from unpriced: boolean; // true when no pricing entry matched + /** + * True when `costUSD` came from the unpriced-model rate stand-in rather than this model's + * own rates — real tokens, borrowed prices. Always accompanies `unpriced`, and forces + * `SessionCost.usagePartial`, so the figure is never read as an invoice. + */ + estimated?: boolean; } /** One cumulative point in a session's token & cost growth series. */ diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index c50366771..2a44041b4 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -836,7 +836,7 @@ + 'The rest carry no recoverable token counts: either the native log was rotated/deleted, or the agent ' + 'records transcripts locally but no token telemetry at all (analytics-only agents such as Cursor). ' + 'This does not affect the cost of the sessions that are priced. See Coverage by agent below.'; - if (DATA.meta.unpricedModels && DATA.meta.unpricedModels.length) msg += ' Unpriced models: ' + DATA.meta.unpricedModels.join(', ') + '.'; + if (DATA.meta.unpricedModels && DATA.meta.unpricedModels.length) msg += ' Models with no published price (estimated at a stand-in rate when tokens were recovered): ' + DATA.meta.unpricedModels.join(', ') + '.'; banner.textContent = msg; // textContent is safe — do not pre-escape (would double-escape) host.appendChild(banner); @@ -1282,7 +1282,7 @@ if (s.usageUnavailableReason) { costCard._body.appendChild(el('div', 'text-muted', '' + esc(s.usageUnavailableReason) + '')); } else if (s.usagePartial) { - costCard._body.appendChild(el('div', 'text-muted', 'Partial usage — output tokens only; this session recorded no full rollup, so cost is understated.')); + costCard._body.appendChild(el('div', 'text-muted', 'Partial usage — this session recorded no full token rollup, or its model has no published price and was estimated at a stand-in rate. Treat the cost as an understated API-equivalent floor, not a bill.')); } var tokCard = card('Token usage'); tokCard._body.appendChild(statsEl([ ['Input', fmtTokensOf(s, t.input), ''], ['Output', fmtTokensOf(s, t.output), ''], From 8235bae0d4a64fd0266f2232b2a8da188850905b Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:24 +0300 Subject: [PATCH 16/34] docs(analytics): state that recent Cursor builds omit bubble token counts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Cursor docs described `tokenCount` as sparse, which understated the gap: recent builds write zero or omit the field entirely while `toolFormerData` keeps working, so tool enrichment is reliable and token enrichment is usually empty. An operator reading a Cursor-only report needs to know that the resulting dashes are absent data rather than a broken agent-chip filter or a free session. Records the field evidence (469 sessions, 0 with tokens, 24 with tool calls; nonzero-token composers only 354-408 days back and gone from composerHeaders), and states the two non-fixes explicitly: widening discovery max-age to harvest year-old bubbles, and inferring tokens from context fill, transcript length, or tool-call counts. Also aligns the cost wording with the report — em dash, never "Included" or "covered by subscription" — and documents the Sonnet stand-in rate for recovered tokens under an unpriceable model. --- .../integration/external-integrations.md | 9 +++++ docs/CURSOR_INTEGRATION.md | 40 +++++++++++++++++-- 2 files changed, 46 insertions(+), 3 deletions(-) diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index aee38b6f7..64e4c260f 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -309,6 +309,15 @@ mapping. `codemie analytics` discovers Cursor Agent conversations from Cursor's 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. 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`. Rationale for reading an undocumented store: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`. diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index 113aa6ed7..d3983e64c 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -66,9 +66,43 @@ Full rationale for reading an undocumented store, and the constraints that come - **Model** comes from the tracking database. Cursor writes the literal `default` when the user delegated model choice; that is reported as **`Auto`** — Cursor's own word for it — never as whatever model Cursor happens to default to. -- **Tokens and cost** come from `cursorDiskKV`'s sparse per-bubble `tokenCount` (present on - roughly 1% of bubbles). When a session has no token signal at all, `usageUnavailableReason` is - set and the report renders tokens and cost as **unmeasurable**, not as a confident zero. +- **Tokens and cost** come from `cursorDiskKV`'s sparse per-bubble `tokenCount`. When a session has + no token signal at all, `usageUnavailableReason` is set and the report renders tokens and cost as + **unmeasurable** — an em dash, not a confident zero and not a claim that the usage was free. See + [Expect no token counts from recent Cursor builds](#expect-no-token-counts-from-recent-cursor-builds) + before reading anything into a Cursor cost figure. + +### Expect no token counts from recent Cursor builds + +**Recent Cursor builds write zero `tokenCount` on bubbles, or omit the field entirely, while +`toolFormerData` keeps working.** Tool-call success/failure enrichment is therefore reliable and +token/cost enrichment is usually empty. This is the normal, expected shape — not a CodeMie bug, +not a schema-drift failure, and not something `--include-external` or a wider `--max-age` will fix. + +Verified on one operator machine (2026-09-05): of 469 discovered Cursor sessions, **0** carried any +token signal and **24** carried tool calls. Composers with a nonzero `tokenCount` existed only +354–408 days back and no longer appeared in `composerHeaders` at all. Widening discovery age to +harvest those year-old bubbles is explicitly *not* the fix: it would resurface stale conversations +to manufacture a token total that says nothing about recent work. + +What this means when reading a report: + +- A Cursor-only view (for example after deselecting every other agent in the top bar) will show + **dashes** for Input/Output/Total tokens and Est. cost, plus a note that local token telemetry is + absent. That is the filter working correctly on absent data, not a broken agent chip. +- Cost cells for such sessions are **never** labelled `Included` or "covered by subscription". + CodeMie's cost column is an API-equivalent estimate, not a bill, and a missing local token signal + is not evidence that the usage was free. +- When tokens *are* recovered but the model is `Auto`/`default` (or otherwise absent from the price + table), the session is estimated at a published Claude Sonnet API rate, keeps its own model label, + and is badged as partial. Treat it as an understated floor. +- The Enterprise Team Analytics API does **not** close this gap: none of its documented endpoints + returns token or cost fields at any tier. See + [Cursor Enterprise Team Analytics API](../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-not-integrated). + +Nothing here is inferred from `contextTokensUsed`, transcript text length, or tool-call counts. +Those correlate with usage but are not billable token counts, and presenting them as such would +trade an honest blank for a confident wrong number. ### Database schema and versioning From 8c123c79e79a9ecf1bd812323f2f3642ba4b1201 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:25 +0300 Subject: [PATCH 17/34] feat(analytics): opt-in, user-scoped Cursor Team Analytics section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the only network call in the analytics path, gated so it cannot happen by accident: it requires BOTH --cursor-team-analytics at invocation AND CURSOR_TEAM_ANALYTICS_API_KEY. A configured credential alone is deliberately not enough — reading the local machine is a promise CodeMie already makes, calling a remote service is not, so it stays an explicit act. Scope is the report owner alone: only `by-user` endpoints (agent-edits, tabs, models, commands), filtered to their own email. No team-level endpoint and no leaderboard, so a colleague's activity can never reach a personal report. The results render in their own "Cursor Team API" view, hidden unless a pull happened, and are never merged into the session table. That separation is forced by the data: the API returns per-user/per-date aggregates with no composerId to join on and no token or cost fields to join with, so a merge would have to invent both a key and a figure. Nothing in the section contributes to any cost or token total elsewhere in the report. Fail-soft throughout — missing key, HTTP error, DNS failure, or schema drift degrades to an omitted or explicitly-partial section rather than taking down the local report, which is the part that always works. --- .../integration/external-integrations.md | 22 ++- docs/CURSOR_INTEGRATION.md | 1 + .../cursor/__tests__/team-analytics.test.ts | 104 +++++++++++++ .../plugins/cursor/cursor.team-analytics.ts | 138 ++++++++++++++++++ src/cli/commands/analytics/index.ts | 19 +++ .../__tests__/report-cost-honesty.test.ts | 27 ++++ .../commands/analytics/report/client/app.js | 45 ++++++ .../analytics/report/payload-builder.ts | 4 + .../commands/analytics/report/template.html | 1 + src/cli/commands/analytics/report/types.ts | 8 + src/cli/commands/analytics/types.ts | 6 + 11 files changed, 370 insertions(+), 5 deletions(-) create mode 100644 src/agents/plugins/cursor/__tests__/team-analytics.test.ts create mode 100644 src/agents/plugins/cursor/cursor.team-analytics.ts diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index 64e4c260f..c0c11f7c0 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -321,12 +321,14 @@ the session `usagePartial`. Full operational and developer guide: `docs/CURSOR_INTEGRATION.md`. Rationale for reading an undocumented store: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`. -### Cursor Enterprise Team Analytics API (not integrated) +### Cursor Enterprise Team Analytics API (opt-in) Cursor publishes an official Team Analytics API -(). **CodeMie does not integrate it today.** -It is recorded here as a known, deferred capability so the constraints below are not re-derived — -or, worse, so nothing is wired up that silently makes network calls. +(). CodeMie integrates it as a strictly +opt-in, user-scoped extra: `src/agents/plugins/cursor/cursor.team-analytics.ts`, surfaced by +`codemie analytics --report --cursor-team-analytics` with `CURSOR_TEAM_ANALYTICS_API_KEY` set. +**Both** are required — a configured credential alone never triggers a call — and this is the only +network call anywhere in the analytics path. It still **cannot** supply tokens or cost. What the API is: @@ -335,7 +337,17 @@ What the API is: - Documented endpoints: `agent-edits`, `tabs`, `dau`, `models`, `commands`, `conversation-insights`, `leaderboard`, `bugbot`. - **None of these endpoints returns token or cost fields at any tier.** The API cannot fill - CodeMie's biggest Cursor gap. + CodeMie's biggest Cursor gap. Re-verified against the live docs on 2026-09-05: responses carry + `total_suggested_diffs`, `total_accepted_diffs`, `total_rejected_diffs`, + `total_green_lines_accepted`, `total_red_lines_accepted`, `total_suggestions`, `total_accepts`, + `total_rejects`, `messages`, `command_name`, `skill_name`, `model` — and nothing token-shaped. + +How the shipped integration honours the constraints below: it queries only `by-user` endpoints +(`agent-edits`, `tabs`, `models`, `commands`) with `users=`, never a +`team/*` endpoint and never the leaderboard; it renders into its own "Cursor Team API" report view +that is hidden unless a pull happened; it synthesizes no token or cost field; and every failure +mode — missing key, HTTP error, DNS failure, schema drift — degrades to an omitted or partial +section rather than breaking the local report. Agreed constraints for any future integration: diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index d3983e64c..ebc5c3d36 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -127,6 +127,7 @@ column that moved (see [Database schema drift](#database-schema-drift-after-a-cu |---|---| | `CURSOR_HOME` | Overrides `~/.cursor`. Also relocates `state.vscdb` to `$CURSOR_HOME/User/globalStorage/state.vscdb`, mirroring its real layout relative to Cursor's app-data root. Unset (the default) uses `~/.cursor` plus the per-OS app-data path above. | | `CODEMIE_DEBUG=true` | Enables the `[cursor]` debug logging described under [Logging and debugging](#logging-and-debugging). | +| `CURSOR_TEAM_ANALYTICS_API_KEY` | Admin-scoped Cursor Enterprise API key. Required *together with* `--cursor-team-analytics` before any network call is made; neither alone is enough. Unset (the default) means analytics stays entirely local. | `CURSOR_HOME` mirrors `COPILOT_HOME` in the Copilot CLI plugin and is what lets the whole ingestion path be driven against a fixture tree in tests. diff --git a/src/agents/plugins/cursor/__tests__/team-analytics.test.ts b/src/agents/plugins/cursor/__tests__/team-analytics.test.ts new file mode 100644 index 000000000..46ae81132 --- /dev/null +++ b/src/agents/plugins/cursor/__tests__/team-analytics.test.ts @@ -0,0 +1,104 @@ +/** + * Cursor Team Analytics gate + normalization tests. + * + * The safety property under test is negative: no network call may happen without BOTH an + * explicit opt-in and a configured credential. `fetch` is injected and counts its calls, so + * a regression that phones home shows up as a call count, not as a mocked-away detail. + */ + +import { describe, it, expect } from 'vitest'; +import { fetchCursorTeamAnalytics, TEAM_ANALYTICS_ENDPOINTS, type TeamAnalyticsRequest } from '../cursor.team-analytics.js'; + +/** A fetch stand-in that records every URL it was asked for. */ +function recordingFetch(handler?: (url: string) => { status?: number; body?: unknown }) { + const calls: string[] = []; + const impl = async (url: string | URL, init?: { headers?: Record }) => { + calls.push(String(url)); + const r = handler?.(String(url)) ?? {}; + return { + ok: (r.status ?? 200) < 400, + status: r.status ?? 200, + json: async () => r.body ?? {}, + text: async () => JSON.stringify(r.body ?? {}), + headers: init?.headers, + } as never; + }; + return { impl, calls }; +} + +const enabled: TeamAnalyticsRequest = { + enabled: true, + apiKey: 'key_abc', + userEmail: 'me@example.com', + startDate: '2026-08-01', + endDate: '2026-08-31', +}; + +describe('Cursor Team Analytics opt-in gate', () => { + it('makes no network call when the opt-in flag is absent, even with a credential', async () => { + const f = recordingFetch(); + const out = await fetchCursorTeamAnalytics({ ...enabled, enabled: false }, { fetch: f.impl }); + expect(f.calls).toEqual([]); + expect(out).toBeNull(); + }); + + it('makes no network call when opted in but no credential is configured', async () => { + const f = recordingFetch(); + const out = await fetchCursorTeamAnalytics({ ...enabled, apiKey: undefined }, { fetch: f.impl }); + expect(f.calls).toEqual([]); + expect(out).toBeNull(); + }); + + it('makes no network call when the requesting user has no known email to scope to', async () => { + const f = recordingFetch(); + const out = await fetchCursorTeamAnalytics({ ...enabled, userEmail: undefined }, { fetch: f.impl }); + expect(f.calls).toEqual([]); + expect(out).toBeNull(); + }); +}); + +describe('Cursor Team Analytics request shape', () => { + it('queries only by-user endpoints, scoped to the requesting user alone', async () => { + const f = recordingFetch(); + await fetchCursorTeamAnalytics(enabled, { fetch: f.impl }); + expect(f.calls.length).toBe(TEAM_ANALYTICS_ENDPOINTS.length); + for (const url of f.calls) { + expect(url).toContain('/analytics/by-user/'); + expect(url).not.toContain('/analytics/team/'); + expect(url).not.toContain('leaderboard'); + expect(new URL(url).searchParams.get('users')).toBe('me@example.com'); + expect(new URL(url).searchParams.get('startDate')).toBe('2026-08-01'); + } + }); +}); + +describe('Cursor Team Analytics results', () => { + it('returns the rows each endpoint actually provided, with no token or cost fields synthesized', async () => { + const f = recordingFetch(() => ({ body: { data: [{ email: 'me@example.com', total_accepted_diffs: 12 }] } })); + const out = (await fetchCursorTeamAnalytics(enabled, { fetch: f.impl }))!; + expect(out.userEmail).toBe('me@example.com'); + expect(out.metrics.length).toBe(TEAM_ANALYTICS_ENDPOINTS.length); + expect(out.metrics[0].rows[0]).toMatchObject({ total_accepted_diffs: 12 }); + // The API returns no token/cost fields; we must not manufacture any. + const serialized = JSON.stringify(out); + expect(serialized).not.toMatch(/costUSD|inputTokens|outputTokens|tokens"/); + }); + + it('degrades to a partial section when an endpoint fails, without throwing', async () => { + const f = recordingFetch((url) => (url.includes('models') ? { status: 500 } : { body: { data: [{ n: 1 }] } })); + const out = (await fetchCursorTeamAnalytics(enabled, { fetch: f.impl }))!; + expect(out.failedEndpoints).toContain('models'); + expect(out.metrics.some((m) => m.endpoint === 'models')).toBe(false); + expect(out.metrics.length).toBe(TEAM_ANALYTICS_ENDPOINTS.length - 1); + }); + + it('returns null rather than throwing when every endpoint fails', async () => { + const f = recordingFetch(() => ({ status: 401 })); + expect(await fetchCursorTeamAnalytics(enabled, { fetch: f.impl })).toBeNull(); + }); + + it('survives a transport-level throw', async () => { + const impl = async () => { throw new Error('ENOTFOUND api.cursor.com'); }; + expect(await fetchCursorTeamAnalytics(enabled, { fetch: impl as never })).toBeNull(); + }); +}); diff --git a/src/agents/plugins/cursor/cursor.team-analytics.ts b/src/agents/plugins/cursor/cursor.team-analytics.ts new file mode 100644 index 000000000..dc8933e06 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.team-analytics.ts @@ -0,0 +1,138 @@ +/** + * Cursor Enterprise Team Analytics — optional, opt-in, user-scoped. + * + * This is the ONLY place CodeMie analytics talks to a network service. Everything else in the + * analytics path reads local files, and that difference is the point: reading the machine you + * are on is a promise CodeMie already makes, calling a remote service is not. So the call is + * gated on BOTH an explicit invocation flag and a configured credential — a token sitting in + * config must never be enough on its own. + * + * What the API does and does not give us: none of the documented endpoints returns token or + * cost fields at any tier (re-verified 2026-09-05), so this cannot close the Cursor billable- + * token gap and must never be presented as if it did. The rows below are edit/activity + * aggregates only. They are also per-user/per-date aggregates carrying no `composerId`, so + * there is no key on which to join them to local sessions — hence the report renders them as a + * clearly separate section rather than folding them into the session table. + * + * See `.ai-run/guides/integration/external-integrations.md` and `docs/CURSOR_INTEGRATION.md`. + */ + +import { logger } from '@/utils/logger.js'; + +/** Documented API root. */ +const API_BASE = 'https://api.cursor.com'; + +/** + * The by-user endpoints worth surfacing. Deliberately excludes every `team/*` endpoint and the + * leaderboard: CodeMie analytics reports the operator's own usage, and pulling colleagues' + * activity into a personal report is out of scope regardless of what the credential can read. + */ +export const TEAM_ANALYTICS_ENDPOINTS = [ + { endpoint: 'agent-edits', label: 'Agent edits' }, + { endpoint: 'tabs', label: 'Tab completions' }, + { endpoint: 'models', label: 'Models used' }, + { endpoint: 'commands', label: 'Commands' }, +] as const; + +export interface TeamAnalyticsRequest { + /** Explicit per-invocation opt-in (the CLI flag). A credential alone must never enable calls. */ + enabled: boolean; + /** Admin-scoped API key. Absent on personal plans, which simply get no section. */ + apiKey?: string; + /** The requesting user's own email — the `by-user` filter, and the reason this stays personal. */ + userEmail?: string; + startDate?: string; + endDate?: string; +} + +/** One endpoint's rows, passed through as the API returned them. */ +export interface TeamAnalyticsMetric { + endpoint: string; + label: string; + rows: Record[]; +} + +export interface CursorTeamAnalytics { + userEmail: string; + startDate?: string; + endDate?: string; + metrics: TeamAnalyticsMetric[]; + /** Endpoints that failed; surfaced so a partial section is never mistaken for a complete one. */ + failedEndpoints: string[]; +} + +type FetchLike = (url: string, init?: { headers?: Record }) => Promise<{ + ok: boolean; + status: number; + json: () => Promise; +}>; + +export interface TeamAnalyticsDeps { + fetch: FetchLike; +} + +/** `curl -u KEY:` — the key as the basic-auth username with an empty password. */ +function authHeader(apiKey: string): string { + return `Basic ${Buffer.from(`${apiKey}:`).toString('base64')}`; +} + +function endpointUrl(endpoint: string, req: TeamAnalyticsRequest): string { + const url = new URL(`/analytics/by-user/${endpoint}`, API_BASE); + url.searchParams.set('users', req.userEmail as string); + if (req.startDate) { + url.searchParams.set('startDate', req.startDate); + } + if (req.endDate) { + url.searchParams.set('endDate', req.endDate); + } + return url.toString(); +} + +/** Accepts either a bare array or the documented `{ data: [...] }` envelope. */ +function rowsOf(payload: unknown): Record[] { + const body = payload as { data?: unknown } | unknown[]; + const data = Array.isArray(body) ? body : body?.data; + return Array.isArray(data) ? (data.filter((r) => r && typeof r === 'object') as Record[]) : []; +} + +/** + * Fetch the requesting user's own Team Analytics aggregates, or `null` when the gate is closed + * or nothing could be retrieved. Never throws: a failed pull degrades to an omitted section so + * the local report — the part that always works — is never taken down by a remote outage. + */ +export async function fetchCursorTeamAnalytics( + req: TeamAnalyticsRequest, + deps: TeamAnalyticsDeps = { fetch: globalThis.fetch as unknown as FetchLike } +): Promise { + if (!req.enabled || !req.apiKey || !req.userEmail) { + // Not an error: this is the default state for everyone without an enterprise key. + logger.debug('[cursor] team analytics skipped (needs both the opt-in flag and an API key)'); + return null; + } + + const metrics: TeamAnalyticsMetric[] = []; + const failedEndpoints: string[] = []; + + for (const { endpoint, label } of TEAM_ANALYTICS_ENDPOINTS) { + try { + const res = await deps.fetch(endpointUrl(endpoint, req), { + headers: { Authorization: authHeader(req.apiKey), Accept: 'application/json' }, + }); + if (!res.ok) { + logger.debug(`[cursor] team analytics ${endpoint} returned HTTP ${res.status}`); + failedEndpoints.push(endpoint); + continue; + } + metrics.push({ endpoint, label, rows: rowsOf(await res.json()) }); + } catch (error) { + // Schema drift, DNS failure, auth rejection — all the same to the report: omit and move on. + logger.debug(`[cursor] team analytics ${endpoint} unusable: ${(error as Error).message}`); + failedEndpoints.push(endpoint); + } + } + + if (metrics.length === 0) { + return null; + } + return { userEmail: req.userEmail, startDate: req.startDate, endDate: req.endDate, metrics, failedEndpoints }; +} diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 5ff896601..3f9dac5f2 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -23,6 +23,7 @@ export function createAnalyticsCommand(): Command { applyCommonOptions(command) .option('--no-scan-native', 'Skip native agent-log discovery (use only CodeMie-tracked sessions)') .option('--include-external', 'Include non-CodeMie-owned native sessions in output (opt-in; matches pre-fix behavior)') + .option('--cursor-team-analytics', 'Fetch your own Cursor Team Analytics aggregates (requires CURSOR_TEAM_ANALYTICS_API_KEY; makes a network call)') .action((options: AnalyticsOptions) => runAnalytics(options, new SessionsSource())); // `codemie analytics otel --file ` — OTEL file source. @@ -171,12 +172,30 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS } } + // The one network call in the analytics path, and it happens only when the user asked for + // it AND a credential exists. Fail-soft: a null result simply omits the report section. + let cursorTeamAnalytics; + if (options.cursorTeamAnalytics) { + const { fetchCursorTeamAnalytics } = await import('@/agents/plugins/cursor/cursor.team-analytics.js'); + cursorTeamAnalytics = (await fetchCursorTeamAnalytics({ + enabled: true, + apiKey: process.env.CURSOR_TEAM_ANALYTICS_API_KEY, + userEmail, + ...(filter.fromDate !== undefined && { startDate: filter.fromDate.toISOString().slice(0, 10) }), + ...(filter.toDate !== undefined && { endDate: filter.toDate.toISOString().slice(0, 10) }), + })) ?? undefined; + if (!cursorTeamAnalytics) { + console.log(chalk.dim('\n Cursor Team Analytics unavailable (needs CURSOR_TEAM_ANALYTICS_API_KEY, a configured email, and an enterprise team). Report continues without it.')); + } + } + const { index: costIndex, summary } = costResult; const payload = buildPayload(analytics, costIndex, summary, { rangeLabel: options.last ?? (options.from || options.to ? 'custom' : 'all'), projectFilter: options.project ?? 'all', generatedAt: new Date().toISOString(), ...(userEmail !== undefined && { userEmail }), + ...(cursorTeamAnalytics !== undefined && { cursorTeamAnalytics }), ...(filter.fromDate !== undefined && { periodStart: filter.fromDate.toISOString() }), ...(filter.toDate !== undefined && { periodEnd: filter.toDate.toISOString() }), }); diff --git a/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts b/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts index f3a08cbf3..d6fff9147 100644 --- a/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts +++ b/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts @@ -88,3 +88,30 @@ describe('report client all-unmeasurable empty state', () => { expect(toolBlock).not.toMatch(/usageUnknown|anyMeasured/); }); }); + +/** + * Cursor Team Analytics is a remote, opt-in source. The report must keep it visibly apart from + * local sessions — it has no session key to join on and no token/cost fields to join with. + */ +describe('Cursor Team Analytics section separation', () => { + const view = viewSource('cursorteam'); + + it('renders from meta, never from the session list', () => { + expect(view).toMatch(/DATA\.meta\.cursorTeamAnalytics/); + // The view takes no session array and must not reach for one. + expect(view).toMatch(/VIEWS\.cursorteam = function \(host\)/); + expect(view).not.toMatch(/DATA\.sessions|SESSION_BY_ID|filtered\(\)/); + }); + + it('contributes nothing to any cost or token figure', () => { + expect(view).not.toMatch(/costUSD|fmtUSD|fmtTokens/); + }); + + it('says plainly that the remote rows are not joined to local sessions', () => { + expect(view).toMatch(/nothing here is joined to the local sessions/); + }); + + it('flags a partial pull rather than presenting it as complete', () => { + expect(view).toMatch(/failedEndpoints/); + }); +}); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index 2a44041b4..f0c727648 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -824,6 +824,47 @@ host.appendChild(changeCard); }; + /** + * Cursor Team Analytics — a REMOTE, opt-in source, deliberately kept in its own view. + * + * It is never merged into the session table and never contributes to any cost or token + * figure: the API returns per-user/per-date aggregates with no composerId to join on, and no + * token or cost fields to join with. Two different things are being counted, so they are + * shown as two different things. The view is hidden entirely unless the pull happened. + */ + VIEWS.cursorteam = function (host) { + var ta = DATA.meta.cursorTeamAnalytics; + host.appendChild(el('h2', 'view-title', 'Cursor Team API')); + if (!ta) { + host.appendChild(el('p', 'view-sub', 'Not fetched for this report.')); + host.appendChild(el('div', 'empty', 'Run with --cursor-team-analytics and CURSOR_TEAM_ANALYTICS_API_KEY set to include your own Cursor Team Analytics aggregates.')); + return; + } + var range = (ta.startDate || '…') + ' → ' + (ta.endDate || '…'); + host.appendChild(el('p', 'view-sub', 'Fetched from Cursor\u2019s Team Analytics API for ' + esc(ta.userEmail) + ' · ' + esc(range))); + host.appendChild(el('div', 'alert alert-info', 'Remote data, shown separately on purpose. These are Cursor\u2019s own edit and activity aggregates for your account; they carry no token or cost fields and no session key, so nothing here is joined to the local sessions or added to any cost figure elsewhere in this report.')); + if (ta.failedEndpoints && ta.failedEndpoints.length) { + host.appendChild(el('div', 'alert alert-warning', 'Incomplete: ' + esc(ta.failedEndpoints.join(', ')) + ' could not be fetched, so this section is partial.')); + } + (ta.metrics || []).forEach(function (m) { + var c = card(m.label, m.endpoint); + var rows = m.rows || []; + if (!rows.length) { + c._body.appendChild(el('div', 'empty', 'No rows returned for this range.')); + } else { + // Column set is whatever the API sent — the report does not curate or rename it, so a + // field Cursor adds later shows up as itself rather than being silently dropped. + var cols = []; + rows.forEach(function (r) { Object.keys(r).forEach(function (k) { if (cols.indexOf(k) === -1) cols.push(k); }); }); + var body = rows.map(function (r) { + return cols.map(function (k) { return esc(r[k] == null ? '—' : (typeof r[k] === 'object' ? JSON.stringify(r[k]) : r[k])); }); + }); + c._body.innerHTML = '
' + tableHTML(cols, body) + '
'; + } + host.appendChild(c); + }); + }; + VIEWS.cost = function (host, fs) { host.appendChild(el('h2', 'view-title', 'Cost')); host.appendChild(el('p', 'view-sub', 'Estimated cost (API-equivalent) — token usage × model pricing. This is what the same usage would have been metered at through the API, not an invoice.')); @@ -1457,6 +1498,10 @@ root.innerHTML = ''; (VIEWS[state.view] || VIEWS.overview)(root, filtered()); document.querySelectorAll('.nav-i').forEach(function (n) { n.classList.toggle('active', n.getAttribute('data-view') === state.view); }); + // The remote-source view is opt-in; without a pull there is nothing to navigate to. + document.querySelectorAll('.nav-i[data-optional]').forEach(function (n) { + if (n.getAttribute('data-view') === 'cursorteam' && !DATA.meta.cursorTeamAnalytics) n.style.display = 'none'; + }); } function buildControls() { diff --git a/src/cli/commands/analytics/report/payload-builder.ts b/src/cli/commands/analytics/report/payload-builder.ts index 634d6dc42..d25eabcb1 100644 --- a/src/cli/commands/analytics/report/payload-builder.ts +++ b/src/cli/commands/analytics/report/payload-builder.ts @@ -4,6 +4,7 @@ * `generatedAt` so this stays deterministic and unit-testable. */ +import type { CursorTeamAnalytics } from '@/agents/plugins/cursor/cursor.team-analytics.js'; import type { RootAnalytics } from '../types.js'; import type { SessionCostIndex, CostSummary, AgentCoverage } from '../cost/types.js'; import { emptyUsage } from '../cost/cost-calculator.js'; @@ -17,6 +18,8 @@ export interface PayloadContext { userEmail?: string; // caller stamps; absent when not authenticated periodStart?: string; // ISO — caller stamps from filter or session start periodEnd?: string; // ISO — caller stamps from filter or session end + /** Opt-in Cursor Team Analytics for the report owner; absent unless the gate opened. */ + cursorTeamAnalytics?: CursorTeamAnalytics; } export function buildPayload( @@ -170,6 +173,7 @@ export function buildPayload( unpricedModels: summary.unpricedModels, coverage: [...coverageMap.values()].sort((a, b) => b.total - a.total), ...(ctx.userEmail !== undefined && { userEmail: ctx.userEmail }), + ...(ctx.cursorTeamAnalytics !== undefined && { cursorTeamAnalytics: ctx.cursorTeamAnalytics }), ...(ctx.periodStart !== undefined ? { periodStart: ctx.periodStart } : minStartMs !== undefined diff --git a/src/cli/commands/analytics/report/template.html b/src/cli/commands/analytics/report/template.html index 94d0408bf..f151f34bf 100644 --- a/src/cli/commands/analytics/report/template.html +++ b/src/cli/commands/analytics/report/template.html @@ -287,6 +287,7 @@
Spend
Cost
Raw
+
Cursor Team API
Sessions
diff --git a/src/cli/commands/analytics/report/types.ts b/src/cli/commands/analytics/report/types.ts index 4a2e309b1..4b479f6b7 100644 --- a/src/cli/commands/analytics/report/types.ts +++ b/src/cli/commands/analytics/report/types.ts @@ -3,6 +3,7 @@ * report. The client app reads only this and computes every view from it. */ +import type { CursorTeamAnalytics } from '@/agents/plugins/cursor/cursor.team-analytics.js'; import type { TokenUsage, ModelCost, AgentCoverage, CostSeriesPoint, DispatchEvent } from '../cost/types.js'; import type { ToolStats, NamedInvocationStats } from '../types.js'; @@ -81,6 +82,13 @@ export interface ReportMeta { unpricedModels: string[]; coverage: AgentCoverage[]; // per-agent priced/total — "which tools are included" userEmail?: string; // identity of the report owner; absent when not authenticated + /** + * Optional Cursor Team Analytics aggregates for the report owner alone. Kept in `meta` and + * rendered as its own section precisely because it CANNOT be joined to `sessions`: the API + * returns per-user/per-date aggregates with no composerId, and it carries no token or cost + * fields, so merging it into session rows would invent both a key and a figure. + */ + cursorTeamAnalytics?: CursorTeamAnalytics; periodStart?: string; // ISO — start of the reported range; always present when the report contains any sessions periodEnd?: string; // ISO — end of the reported range; always present when the report contains any sessions } diff --git a/src/cli/commands/analytics/types.ts b/src/cli/commands/analytics/types.ts index 3428b4fdf..cf86deba3 100644 --- a/src/cli/commands/analytics/types.ts +++ b/src/cli/commands/analytics/types.ts @@ -251,6 +251,12 @@ export interface AnalyticsOptions { scanNative?: boolean; /** When true (via --include-external), include non-CodeMie-owned native sessions in output (matches pre-fix behavior). */ includeExternal?: boolean; + /** + * When true (via --cursor-team-analytics), pull the report owner's own Cursor Team Analytics + * aggregates. Requires CURSOR_TEAM_ANALYTICS_API_KEY as well — the flag alone makes no call, + * and neither does the credential alone. + */ + cursorTeamAnalytics?: boolean; } /** Options for the `analytics otel` subcommand: the shared base plus OTEL-specific flags. */ From eec4be9771bf5b1be2d1dc71ee862c3ee94a62ea Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:25 +0300 Subject: [PATCH 18/34] docs(analytics): guide users through unmeasurable cost and the Team API pull MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The report gained two behaviours a reader cannot infer from the UI alone: cost and token cells that dash out when nothing is measurable, and an opt-in remote section. Both were undocumented, which is how a dash gets misread as free usage and an all-dash Cursor-only view gets misread as a broken agent chip. Adds a "when cost and tokens show —" reference, an analytics-only-agents section setting the expectation that recent Cursor builds record no billable tokens at all, and a Cursor Team Analytics section stating what the pull requires (both a flag and a key), what it returns (edit and activity counters), what it does not return (tokens or cost), and why it renders apart from the session table. Also drops the Cost view's subscription framing, which said the reader does not pay per token — a billing fact the local logs do not record. --- docs/ANALYTICS-REPORT.md | 122 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 117 insertions(+), 5 deletions(-) diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 6b9716394..5af601ae4 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -27,6 +27,9 @@ codemie analytics --report --report-format both # Include ALL local agent usage — also the sessions you ran outside CodeMie codemie analytics --report --open --include-external + +# Add your own Cursor Team Analytics aggregates (opt-in; makes a network call) +CURSOR_TEAM_ANALYTICS_API_KEY=... codemie analytics --report --open --cursor-team-analytics ``` > **If your question is "what did AI actually cost us?", you probably want `--include-external`.** @@ -38,7 +41,7 @@ codemie analytics --report --open --include-external ## What the Report Covers -The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*. +The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*, plus an optional tenth ([Cursor Team API](#cursor-team-analytics)) that appears only when you opt into that remote pull. Discovered sessions that CodeMie did not launch are **excluded by default**; see [Session provenance](#session-provenance). @@ -55,11 +58,11 @@ The landing view. Gives every headline number at a glance: - **Sessions** — total count with wall-clock duration and turns per session - **Files & lines** — file operations, lines added/removed, net change - **Tool calls** — total calls and overall success rate -- **Estimated cost** — API-equivalent spend across priced sessions +- **Estimated cost** — API-equivalent spend across priced sessions; `—` when nothing in view is measurable (see [When cost and tokens show `—`](#unknown-cost)) Below the headline KPIs, two supplementary sections appear: -**Token usage** breaks down input tokens, output tokens, cache writes (tokens written to the prompt cache), and cache reads (tokens served back from cache), plus a combined total. +**Token usage** breaks down input tokens, output tokens, cache writes (tokens written to the prompt cache), and cache reads (tokens served back from cache), plus a combined total. When no session in view has any token signal, these show `—` with a note explaining that local token telemetry is absent — see [Analytics-only agents](#analytics-only-agents). **Efficiency summary** shows cache-read cost, bloat percentage (cache reads as a share of total spend), dead session count, and average context per call — all linking to the Efficiency tab for full detail. @@ -143,7 +146,7 @@ Metrics shown are generic per-session metrics aggregated by source — **no fram ![Cost](assets/analytics-report-cost.png) -Estimated API-equivalent spend (token usage × model pricing). If you use Claude on a subscription, you don't pay per token — this view shows the equivalent metered-API value for benchmarking against alternatives or tracking consumption trends. +Estimated API-equivalent spend (token usage × model pricing) — what the same usage would have been metered at through the API. It is a benchmark for comparing agents and tracking consumption trends, **not an invoice**, and it is never presented as one. > **Why this reads lower than the terminal's live cost.** Cost here is counted **per API response**: each response's token usage is priced exactly once, matching how the provider bills and how Claude Code's own telemetry (`cost.usage`) records it. A single response is written to the native log across several lines (e.g. a `thinking` line and a `tool_use` line, each repeating the same usage), and the live statusline in the terminal sums those lines — so it over-counts multi-part responses and shows a higher number. For sessions heavy on extended thinking plus tool use, expect the report total to sit noticeably below the live statusline; the report figure is the authoritative, de-duplicated one. @@ -155,6 +158,35 @@ Key elements: - **Cost by model** — horizontal bar chart of USD spend per model - **Most expensive sessions** — top 10 ranked by cost, with per-session token breakdown (input, output, cached) + + +#### When cost and tokens show `—` + +A dash means **unmeasurable**, not free and not zero. It appears when a session left no readable +local token signal — the native log was rotated away, or the agent records transcripts but no token +telemetry at all (see [Analytics-only agents](#analytics-only-agents)). + +The report will not paper over that gap: + +- Unmeasurable sessions render `—` for cost and for every token field, never `$0.00` or `0`. A + structural zero and a genuine zero look different because they mean different things. +- Aggregates dash out only when **nothing** in the group was measurable. A mixed group still shows + the real sum of whatever was measured, so known data is never hidden by unknown peers. +- No cell is ever labelled `Included` or "covered by subscription". Your plan's billing status is + not something the local logs record, and absence of a token count is not evidence of free usage. + +#### Estimated costs and the partial badge + +When a session has real recovered tokens but its model is not in the pricing table — Cursor's +`Auto`, or simply a model newer than the table — the cost is estimated at a published **Claude +Sonnet** API rate rather than dropped to `$0`. Such sessions: + +- keep their own model label (`Auto` stays `Auto`; nothing is renamed to Sonnet), +- are marked **partial usage** in the session detail modal, and +- are still listed under "models with no published price" in the Cost coverage banner. + +Treat any partial figure as an understated floor, not a measurement. + --- ### Sessions @@ -235,7 +267,7 @@ CodeMie merges two sources to give the most complete picture: 1. **Tracked sessions** — metrics written by the CodeMie hooks during sessions CodeMie launched 2. **Native agent logs** — transcripts left on disk by `claude`, `codex`, `gemini`, `pi`, and `copilot`, discovered automatically and deduped against tracked sessions -3. **Analytics-only agents** — agents CodeMie never launches and only reads. `cursor` is the one today: its conversations are read from Cursor's own local stores and surfaced like any other external session. See [Cursor Integration](CURSOR_INTEGRATION.md). +3. **Analytics-only agents** — agents CodeMie never launches and only reads. `cursor` is the one today: its conversations are read from Cursor's own local stores and surfaced like any other external session. See [Cursor Integration](CURSOR_INTEGRATION.md) and [Analytics-only agents](#analytics-only-agents) below. Pass `--no-scan-native` to disable native-log discovery and use only CodeMie-tracked sessions. @@ -243,6 +275,30 @@ Discovery looks back as far as your date filter requires: with `--from` or `--la Cost enrichment requires the native log to read per-turn token data. Sessions where the log has already been rotated or deleted will appear with `—` cost; the **Coverage** section in the Cost view shows exactly which sessions are priced. + + +### Analytics-only agents (Cursor) — expect no token counts + +Cursor is read, never launched. Its transcripts, tool outcomes, projects, and models all come +through, but **recent Cursor builds record no billable token counts** — they write zero, or omit the +field entirely, while tool-call data keeps working. This is Cursor's behaviour, not a CodeMie bug. + +What that looks like in the report: + +- Cursor sessions appear (with `--include-external`) with real turns, tool calls, and file activity. +- Their cost and token cells are `—`, per [When cost and tokens show `—`](#unknown-cost). +- **If you deselect every other agent in the top bar, the Overview and Cost KPIs go all-dashes and + show a short note saying local token telemetry is absent for the sessions in view.** That is the + filter working correctly on absent data — not a broken agent chip. Tool-call tables keep working. + +A measurement taken on one machine: of 469 discovered Cursor sessions, 0 carried any token signal +and 24 carried tool calls. Conversations that *do* still hold token counts were all roughly a year +old and no longer discoverable at all. There is no local store that has the recent numbers — every +Cursor database, per-session chat store, and transcript directory was checked. CodeMie will not +manufacture the figure from context-window fill, transcript length, or tool-call counts, because +those are not billable tokens and presenting them as such would trade an honest blank for a +confident wrong number. + ### Session provenance — and why some sessions are hidden @@ -272,6 +328,50 @@ Two things to know before you rely on the wider number: `--include-external` applies to the default local-session source only. The `analytics otel` subcommand does not accept it — an OTEL events file has no notion of CodeMie ownership. + + +### Cursor Team Analytics (optional, opt-in, network) + +Everything above reads local files. This one feature does not: it pulls your own aggregates from +**Cursor's Enterprise Team Analytics API**. It is off unless you explicitly ask for it. + +```bash +export CURSOR_TEAM_ANALYTICS_API_KEY='' +codemie analytics --report --open --cursor-team-analytics +``` + +**Both the flag and the key are required.** A key sitting in your environment never triggers a call +on its own, and neither does the flag without a key. Reading the machine you are on is a promise +CodeMie already makes; calling a remote service is not, so it stays a deliberate act each time. + +**What you get.** Four `by-user` endpoints — agent edits, tab completions, models, and commands — +filtered to your own email address, rendered in their own **Cursor Team API** view in the sidebar. +The view is hidden entirely unless a pull succeeded. + +**What you do not get: tokens or cost.** None of Cursor's documented endpoints returns a token or +cost field at any tier, so this cannot close the gap described in +[Analytics-only agents](#analytics-only-agents), and it is never presented as if it did. The rows +are edit and activity counters only. + +**It is shown separately on purpose.** The API returns per-user/per-date aggregates with no session +identifier, so there is no key on which to join them to your local Cursor sessions — and no token or +cost field to join with. Merging them into the session table would mean inventing both. Nothing in +this section contributes to any cost or token figure elsewhere in the report. + +**Scope and privacy.** Only `by-user` endpoints are queried, always filtered to the requesting +user's own email. No team-wide endpoint and no leaderboard, so a colleague's activity can never +appear in your personal report. The email comes from your CodeMie config — the same one embedded in +report metadata. + +**Requirements and failure modes.** You need an admin-scoped Cursor **Team** API key from an +enterprise team; individual and personal plans cannot use this API at all. Every failure — missing +key, rejected key, HTTP error, DNS failure, or a schema change on Cursor's side — degrades to an +omitted or explicitly-partial section and prints a one-line notice. The local report, which is the +part that always works, is never taken down by a remote outage. Run with `CODEMIE_DEBUG=true` to see +the per-endpoint outcome. + +--- + ### OTEL events file (`analytics otel`) As an alternative to the local-session sources above, the `analytics otel` subcommand builds the same report from a **flattened OTEL events file** (`otel-events.jsonl`) — for example, telemetry exported from a fleet or CI environment rather than the current machine's history. @@ -312,6 +412,11 @@ Source flags: --no-scan-native Skip native-log discovery (CodeMie-tracked sessions only) --include-external Also count local sessions CodeMie did not launch (see "Session provenance"; requires native scanning) + --cursor-team-analytics Fetch your own Cursor Team Analytics aggregates. + Makes a NETWORK CALL; also requires + CURSOR_TEAM_ANALYTICS_API_KEY. Neither the flag nor + the key does anything on its own. + (see "Cursor Team Analytics") Other flags: -v, --verbose Session-level breakdown in the terminal output @@ -319,6 +424,13 @@ Other flags: -o, --output Output path for --export ``` +**Environment variables** + +| Variable | Effect | +|---|---| +| `CURSOR_TEAM_ANALYTICS_API_KEY` | Admin-scoped Cursor Team API key. Required *together with* `--cursor-team-analytics`; see [Cursor Team Analytics](#cursor-team-analytics). | +| `CODEMIE_DEBUG=true` | Verbose per-source discovery and enrichment logging, including each Team Analytics endpoint's outcome. | + **Every filter and source flag governs the terminal output and the HTML report alike.** There is no report-only or terminal-only filtering: `--include-external`, `--no-scan-native`, and the date/project/agent filters all decide which sessions the command sees, and both outputs are rendered from that same set. The date filters control which sessions are **embedded** in the report; the client-side range presets (Today / 7d / 30d / 90d) then let the report viewer narrow further within that data. From 23b2c29b3fe6489cbd4d2032b09169d3b14e8ffd Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:26 +0300 Subject: [PATCH 19/34] feat(analytics): import Cursor usage-events CSV for real tokens and cost MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #21. Cursor's local stores stopped recording billable tokens and the Team Analytics API never had them, but the dashboard's Usage export does. A real 2026-09-05 export carries 39,952,466 tokens and $25.25 across 61 events — while every one of those rows is Kind=Included. That is the trap this parser exists to avoid. "Included" is Cursor's billing category, meaning covered by your plan, not a statement that the usage was free or unmeasured. Reading it as "no cost" would discard the only accurate Cursor figures available, so Kind is recorded and never used to zero anything out. Two export shapes are in the wild and both parse: most end with a Cost column, while at least one variant ships Requests instead and has no cost at all. Tokens are the durable part, cost is optional, and the section says so when it is missing. Cost cells also carry words such as "Free", which contribute zero rather than poisoning the total with NaN. Rows are per-event with no composerId, so they render as their own labelled section rather than being joined to sessions or added to any cost figure elsewhere — the report shows Cursor's own numbers beside CodeMie's, not summed into them. The User column is filtered to the report owner by default, overridable with --cursor-usage-user, because the Cursor account's address is often not the configured CodeMie one. A filter that matches nothing warns and names the emails actually present instead of yielding a silently empty section. --- .../cursor/__tests__/cursor.usage-csv.test.ts | 95 +++++++ .../fixtures/cursor-usage-events.csv | 9 + src/agents/plugins/cursor/cursor.usage-csv.ts | 258 ++++++++++++++++++ src/cli/commands/analytics/index.ts | 34 ++- .../commands/analytics/report/client/app.js | 69 ++++- .../analytics/report/payload-builder.ts | 4 + .../commands/analytics/report/template.html | 1 + src/cli/commands/analytics/report/types.ts | 7 + src/cli/commands/analytics/types.ts | 7 + 9 files changed, 481 insertions(+), 3 deletions(-) create mode 100644 src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts create mode 100644 src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events.csv create mode 100644 src/agents/plugins/cursor/cursor.usage-csv.ts diff --git a/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts b/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts new file mode 100644 index 000000000..6d37a14b0 --- /dev/null +++ b/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts @@ -0,0 +1,95 @@ +/** + * Cursor usage-events CSV import. + * + * The fixture is a slice of a real 2026-09-05 export, so the header set, the quoting, and the + * token magnitudes are the ones the product will actually meet. Its defining property: every + * row is `Kind=Included` and yet carries real tokens and a real `Cost` — the whole reason this + * import exists, and the thing a naive reading of "Included" would throw away. + */ + +import { describe, it, expect } from 'vitest'; +import { fileURLToPath } from 'node:url'; +import { parseCursorUsageCsv, loadCursorUsageCsv } from '../cursor.usage-csv.js'; +import { readFileSync } from 'node:fs'; + +const fixturePath = fileURLToPath(new URL('./fixtures/cursor-usage-events.csv', import.meta.url)); +const fixture = readFileSync(fixturePath, 'utf-8'); + +describe('parseCursorUsageCsv', () => { + it('keeps tokens and cost for Included rows instead of reading them as free', () => { + const out = parseCursorUsageCsv(fixture)!; + expect(out.events).toHaveLength(8); + expect(out.events.every((e) => e.kind === 'Included')).toBe(true); + expect(out.totals.costUSD).toBeCloseTo(3.87, 2); + expect(out.totals.tokens.total).toBe(4183618); + expect(out.totals.tokens.output).toBe(48138); + // Cache read is the bulk of Cursor usage and must not be folded into plain input. + expect(out.totals.tokens.cacheRead).toBe(3437315); + expect(out.totals.tokens.cacheCreation).toBe(168695); + expect(out.totals.tokens.input).toBe(529470); + }); + + it('groups by day and model so the section can show provenance without inventing a session key', () => { + const out = parseCursorUsageCsv(fixture)!; + const auto = out.byModel.find((m) => m.model === 'auto')!; + expect(auto.events).toBe(4); + expect(auto.costUSD).toBeCloseTo(0.58, 2); + expect(out.byDay.map((d) => d.day)).toEqual(['2026-08-28', '2026-09-05']); + }); + + it('filters to one user when asked, and reports who it actually found', () => { + const mixed = fixture.replace('"owner@example.com"', '"someone.else@example.com"'); + const out = parseCursorUsageCsv(mixed, { userEmail: 'owner@example.com' })!; + expect(out.events).toHaveLength(7); + expect(out.usersInFile.sort()).toEqual(['owner@example.com', 'someone.else@example.com']); + expect(out.droppedByUserFilter).toBe(1); + }); + + it('reports when the user filter matched nothing, rather than silently emptying the section', () => { + const out = parseCursorUsageCsv(fixture, { userEmail: 'nobody@example.com' }); + expect(out).not.toBeNull(); + expect(out!.events).toHaveLength(0); + expect(out!.droppedByUserFilter).toBe(8); + expect(out!.usersInFile).toEqual(['owner@example.com']); + }); + + it('tolerates the export variant that has no Cost column', () => { + // The 380-row 2026-09-05 export ships `Requests` in place of `Cost`. + const noCost = fixture + .replace('"Total Tokens","Cost"', '"Total Tokens","Requests"') + .replace(/,"\d+\.\d+"\r?\n/g, ',"3.1"\n'); + const out = parseCursorUsageCsv(noCost)!; + expect(out.events.length).toBeGreaterThan(0); + expect(out.hasCost).toBe(false); + expect(out.totals.costUSD).toBe(0); + // Tokens are still the point — they must survive a missing Cost column. + expect(out.totals.tokens.total).toBeGreaterThan(0); + }); + + it('tolerates added columns and non-numeric cost values', () => { + const odd = fixture + .replace('"Cost"', '"Cost","Some New Column"') + .replace(/("\d+\.\d+")\r?\n/g, '$1,"x"\n') + .replace('"0.07","x"', '"Free","x"'); + const out = parseCursorUsageCsv(odd)!; + expect(out.events).toHaveLength(8); + expect(out.totals.costUSD).toBeCloseTo(3.80, 2); // the 0.07 row contributed nothing + }); + + it('returns null for a file that is not a usage export', () => { + expect(parseCursorUsageCsv('name,value\nfoo,1\n')).toBeNull(); + expect(parseCursorUsageCsv('')).toBeNull(); + }); +}); + +describe('loadCursorUsageCsv', () => { + it('reads a real export off disk', () => { + const out = loadCursorUsageCsv(fixturePath)!; + expect(out.events).toHaveLength(8); + expect(out.sourceFile).toBe(fixturePath); + }); + + it('fails soft on a missing file instead of throwing', () => { + expect(loadCursorUsageCsv('/no/such/export.csv')).toBeNull(); + }); +}); diff --git a/src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events.csv b/src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events.csv new file mode 100644 index 000000000..637052cb6 --- /dev/null +++ b/src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events.csv @@ -0,0 +1,9 @@ +"Date","User","Cloud Agent ID","Automation ID","Kind","Model","Max Mode","Input (w/ Cache Write)","Input (w/o Cache Write)","Cache Read","Output Tokens","Total Tokens","Cost" +"2026-09-05T13:52:28.087Z","owner@example.com","","","Included","auto","No","0","30061","118400","1038","149499","0.07" +"2026-09-05T13:08:46.257Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","104940","238071","3820","346831","0.30" +"2026-08-28T16:56:57.387Z","owner@example.com","","","Included","claude-opus-5-thinking-high","No","168695","4598","791217","19889","984399","1.97" +"2026-08-28T16:35:04.195Z","owner@example.com","","","Included","composer-2.5-fast","No","0","73532","367686","7049","448267","0.43" +"2026-08-28T16:34:55.299Z","owner@example.com","","","Included","cursor-grok-4.6-high","No","0","182623","526229","6718","715570","0.59" +"2026-09-05T13:50:50.577Z","owner@example.com","","","Included","auto","No","0","3435","400768","1998","406201","0.10" +"2026-09-05T13:46:37.532Z","owner@example.com","","","Included","auto","No","0","123309","514176","5627","643112","0.28" +"2026-09-05T13:45:11.696Z","owner@example.com","","","Included","auto","No","0","6972","480768","1999","489739","0.13" diff --git a/src/agents/plugins/cursor/cursor.usage-csv.ts b/src/agents/plugins/cursor/cursor.usage-csv.ts new file mode 100644 index 000000000..951658983 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.usage-csv.ts @@ -0,0 +1,258 @@ +/** + * Cursor usage-events CSV import — the member path to real Cursor tokens and cost. + * + * Cursor's local stores stopped carrying billable token counts (see docs/CURSOR_INTEGRATION.md), + * and the Team Analytics API never had them. The dashboard's Usage → Export CSV does: a real + * 2026-09-05 export held 39,952,466 tokens and $25.25 of Cost across 61 events. + * + * The trap this module exists to avoid: **every one of those 61 rows was `Kind=Included`.** + * `Included` is Cursor's billing *category* — "covered by your plan" — not a statement that the + * usage was free or unmeasured. Reading it as "no cost" would discard the only accurate usage + * figures available. So `Kind` is recorded and never used to zero anything out. + * + * Two export shapes are in the wild and both must parse: most exports end with a `Cost` column, + * while at least one variant ships `Requests` instead and has no cost at all. Tokens are the + * durable part; cost is optional. + * + * Rows are per-event with no composerId, so they cannot be joined to local sessions. The report + * renders them as their own labelled section for exactly that reason. + */ + +import { readFileSync } from 'node:fs'; +import { logger } from '@/utils/logger.js'; + +/** One usage event, normalized. Field names are ours; the CSV's are not stable enough to expose. */ +export interface CursorUsageEvent { + /** ISO timestamp as written by the export. */ + date: string; + /** Local day key (YYYY-MM-DD) used for grouping. */ + day: string; + user: string; + /** Cursor's billing category — `Included`, `On-Demand`, … Recorded, never used to zero usage. */ + kind: string; + model: string; + maxMode: boolean; + tokens: CursorUsageTokens; + /** USD from the `Cost` column; 0 when the export variant has no such column. */ + costUSD: number; +} + +export interface CursorUsageTokens { + /** `Input (w/o Cache Write)` — plain prompt tokens. */ + input: number; + /** `Input (w/ Cache Write)` — prompt tokens that also populated the cache. */ + cacheCreation: number; + cacheRead: number; + output: number; + total: number; +} + +export interface CursorUsageGroup { + model: string; + events: number; + tokens: CursorUsageTokens; + costUSD: number; +} + +export interface CursorUsageDay { + day: string; + events: number; + tokens: CursorUsageTokens; + costUSD: number; +} + +export interface CursorUsageImport { + events: CursorUsageEvent[]; + totals: { events: number; tokens: CursorUsageTokens; costUSD: number }; + byModel: CursorUsageGroup[]; + byDay: CursorUsageDay[]; + /** False for the export variant that ships `Requests` instead of `Cost`. */ + hasCost: boolean; + /** Every distinct `User` seen BEFORE filtering — lets a caller explain an empty result. */ + usersInFile: string[]; + /** How many rows the user filter removed, so "imported nothing" is never silent. */ + droppedByUserFilter: number; + sourceFile?: string; +} + +export interface ParseOptions { + /** When set, keep only rows whose `User` matches (case-insensitive). */ + userEmail?: string; +} + +/** Columns that must all be present for a file to be a usage export rather than some other CSV. */ +const REQUIRED_COLUMNS = ['Date', 'Kind', 'Model', 'Total Tokens']; + +function emptyTokens(): CursorUsageTokens { + return { input: 0, cacheCreation: 0, cacheRead: 0, output: 0, total: 0 }; +} + +function addTokens(a: CursorUsageTokens, b: CursorUsageTokens): CursorUsageTokens { + return { + input: a.input + b.input, + cacheCreation: a.cacheCreation + b.cacheCreation, + cacheRead: a.cacheRead + b.cacheRead, + output: a.output + b.output, + total: a.total + b.total, + }; +} + +/** + * Minimal RFC4180 reader — the export quotes every field and its prompts never appear, but a + * model name or a future column could still carry a comma or an escaped quote. + */ +function parseCsv(text: string): string[][] { + const rows: string[][] = []; + let row: string[] = []; + let field = ''; + let quoted = false; + for (let i = 0; i < text.length; i++) { + const c = text[i]; + if (quoted) { + if (c === '"') { + if (text[i + 1] === '"') { + field += '"'; + i++; + } else { + quoted = false; + } + } else { + field += c; + } + } else if (c === '"') { + quoted = true; + } else if (c === ',') { + row.push(field); + field = ''; + } else if (c === '\n') { + row.push(field); + field = ''; + rows.push(row); + row = []; + } else if (c !== '\r') { + field += c; + } + } + if (field.length || row.length) { + row.push(field); + rows.push(row); + } + return rows.filter((r) => r.some((f) => f.trim() !== '')); +} + +function num(v: string | undefined): number { + const n = Number(String(v ?? '').replace(/,/g, '').trim()); + return Number.isFinite(n) ? n : 0; +} + +/** + * Cost cells are mostly plain decimals but the export also writes words such as `Free`. Pull the + * first number out and treat anything wordy as zero rather than NaN-poisoning the total. + */ +function money(v: string | undefined): number { + const m = /-?\d+(?:\.\d+)?/.exec(String(v ?? '')); + return m ? Number(m[0]) : 0; +} + +/** Parse the text of a Cursor usage export. Returns null when it is not one. */ +export function parseCursorUsageCsv(text: string, options: ParseOptions = {}): CursorUsageImport | null { + const rows = parseCsv(text); + if (rows.length < 2) { + return null; + } + const header = rows[0].map((h) => h.trim()); + if (!REQUIRED_COLUMNS.every((c) => header.includes(c))) { + return null; + } + const at = (r: string[], col: string): string | undefined => { + const i = header.indexOf(col); + return i === -1 ? undefined : r[i]; + }; + + const hasCost = header.includes('Cost'); + const wanted = options.userEmail?.trim().toLowerCase(); + const usersInFile = new Set(); + const events: CursorUsageEvent[] = []; + let droppedByUserFilter = 0; + + for (const r of rows.slice(1)) { + const user = (at(r, 'User') ?? '').trim(); + if (user) { + usersInFile.add(user); + } + if (wanted && user.toLowerCase() !== wanted) { + droppedByUserFilter++; + continue; + } + const date = (at(r, 'Date') ?? '').trim(); + const tokens: CursorUsageTokens = { + input: num(at(r, 'Input (w/o Cache Write)')), + cacheCreation: num(at(r, 'Input (w/ Cache Write)')), + cacheRead: num(at(r, 'Cache Read')), + output: num(at(r, 'Output Tokens')), + total: num(at(r, 'Total Tokens')), + }; + events.push({ + date, + day: date.slice(0, 10), + user, + kind: (at(r, 'Kind') ?? '').trim(), + model: (at(r, 'Model') ?? '').trim(), + maxMode: /^yes$/i.test((at(r, 'Max Mode') ?? '').trim()), + tokens, + costUSD: hasCost ? money(at(r, 'Cost')) : 0, + }); + } + + const group = (keyOf: (e: CursorUsageEvent) => K) => { + const m = new Map(); + for (const e of events) { + const k = keyOf(e); + const cur = m.get(k) ?? { events: 0, tokens: emptyTokens(), costUSD: 0 }; + cur.events++; + cur.tokens = addTokens(cur.tokens, e.tokens); + cur.costUSD += e.costUSD; + m.set(k, cur); + } + return m; + }; + + const byModel = [...group((e) => e.model).entries()] + .map(([model, v]) => ({ model, ...v })) + .sort((a, b) => b.tokens.total - a.tokens.total); + const byDay = [...group((e) => e.day).entries()] + .map(([day, v]) => ({ day, ...v })) + .sort((a, b) => a.day.localeCompare(b.day)); + + return { + events, + totals: { + events: events.length, + tokens: events.reduce((acc, e) => addTokens(acc, e.tokens), emptyTokens()), + costUSD: events.reduce((acc, e) => acc + e.costUSD, 0), + }, + byModel, + byDay, + hasCost, + usersInFile: [...usersInFile], + droppedByUserFilter, + }; +} + +/** + * Read and parse an export from disk. Never throws: an unreadable or wrong-shaped file omits the + * section and leaves the local report — the part that always works — untouched. + */ +export function loadCursorUsageCsv(path: string, options: ParseOptions = {}): CursorUsageImport | null { + try { + const parsed = parseCursorUsageCsv(readFileSync(path, 'utf-8'), options); + if (!parsed) { + logger.debug(`[cursor] usage CSV ${path} is not a Cursor usage export (unexpected columns)`); + return null; + } + return { ...parsed, sourceFile: path }; + } catch (error) { + logger.debug(`[cursor] usage CSV ${path} unreadable: ${(error as Error).message}`); + return null; + } +} diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 3f9dac5f2..52f175b95 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -23,7 +23,9 @@ export function createAnalyticsCommand(): Command { applyCommonOptions(command) .option('--no-scan-native', 'Skip native agent-log discovery (use only CodeMie-tracked sessions)') .option('--include-external', 'Include non-CodeMie-owned native sessions in output (opt-in; matches pre-fix behavior)') - .option('--cursor-team-analytics', 'Fetch your own Cursor Team Analytics aggregates (requires CURSOR_TEAM_ANALYTICS_API_KEY; makes a network call)') + .option('--cursor-team-analytics', 'ENTERPRISE TEAM ADMINS ONLY: fetch Cursor Team Analytics edit/activity aggregates (requires an admin-scoped CURSOR_TEAM_ANALYTICS_API_KEY; makes a network call). Returns no tokens or cost — for those, use --cursor-usage-csv') + .option('--cursor-usage-csv ', 'Import a Cursor usage-events CSV (Cursor dashboard → Usage → Export) for real Cursor tokens and cost. No network call') + .option('--cursor-usage-user ', 'Which User column value to keep from --cursor-usage-csv (default: your configured CodeMie email)') .action((options: AnalyticsOptions) => runAnalytics(options, new SessionsSource())); // `codemie analytics otel --file ` — OTEL file source. @@ -185,7 +187,34 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS ...(filter.toDate !== undefined && { endDate: filter.toDate.toISOString().slice(0, 10) }), })) ?? undefined; if (!cursorTeamAnalytics) { - console.log(chalk.dim('\n Cursor Team Analytics unavailable (needs CURSOR_TEAM_ANALYTICS_API_KEY, a configured email, and an enterprise team). Report continues without it.')); + // Do NOT tell an ordinary team member to go set an admin API key — they cannot get + // one, and it would not carry tokens or cost even if they could. Point at the CSV. + console.log(chalk.yellow('\n Cursor Team Analytics returned nothing. It is available to enterprise team ADMINS only,')); + console.log(chalk.yellow(' and it never returns tokens or cost. For real Cursor tokens and cost, export your usage')); + console.log(chalk.yellow(' from the Cursor dashboard (Usage → Export) and pass it with --cursor-usage-csv .')); + console.log(chalk.dim(' Report continues without the Team Analytics section.')); + } + } + + // #21: the member path to real Cursor tokens/cost. Pure file read — no network call. + let cursorUsage; + if (options.cursorUsageCsv) { + const { loadCursorUsageCsv } = await import('@/agents/plugins/cursor/cursor.usage-csv.js'); + const wantedUser = options.cursorUsageUser ?? userEmail; + cursorUsage = loadCursorUsageCsv(options.cursorUsageCsv, { + ...(wantedUser !== undefined && { userEmail: wantedUser }), + }) ?? undefined; + if (!cursorUsage) { + console.log(chalk.yellow(`\n Could not read a Cursor usage export from ${options.cursorUsageCsv}. Report continues without it.`)); + } else if (cursorUsage.events.length === 0) { + // The Cursor account's email is frequently NOT the CodeMie config email, which would + // otherwise silently filter every row away and look like an empty export. + console.log(chalk.yellow(`\n Cursor usage export matched no rows for ${wantedUser ?? '(no email configured)'}.`)); + if (cursorUsage.usersInFile.length) { + console.log(chalk.yellow(` The file contains: ${cursorUsage.usersInFile.join(', ')}`)); + console.log(chalk.yellow(' Re-run with --cursor-usage-user to pick one of those.')); + } + cursorUsage = undefined; } } @@ -196,6 +225,7 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS generatedAt: new Date().toISOString(), ...(userEmail !== undefined && { userEmail }), ...(cursorTeamAnalytics !== undefined && { cursorTeamAnalytics }), + ...(cursorUsage !== undefined && { cursorUsage }), ...(filter.fromDate !== undefined && { periodStart: filter.fromDate.toISOString() }), ...(filter.toDate !== undefined && { periodEnd: filter.toDate.toISOString() }), }); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index f0c727648..c3f4d42b5 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -865,6 +865,71 @@ }); }; + /** + * Cursor usage-events CSV — the only source of real Cursor tokens and cost. + * + * Cursor's local stores stopped recording billable tokens, so the session table shows dashes + * for Cursor. This section fills that in from the operator's dashboard export. It stays a + * SEPARATE section because the export's rows are per-event with no composerId: there is no key + * to join them to sessions on, so adding these totals to the session costs would be inventing + * an attribution. Read them side by side, not summed. + * + * The figures here are Cursor's own, not CodeMie estimates — no stand-in rate is involved. + */ + VIEWS.cursorusage = function (host) { + var u = DATA.meta.cursorUsage; + host.appendChild(el('h2', 'view-title', 'Cursor Usage CSV')); + if (!u) { + host.appendChild(el('p', 'view-sub', 'No usage export imported for this report.')); + host.appendChild(el('div', 'empty', 'Export your usage from the Cursor dashboard (Usage \u2192 Export) and re-run with --cursor-usage-csv <path> to see real Cursor tokens and cost here.')); + return; + } + var days = u.byDay || []; + var range = days.length ? (days[0].day + ' \u2192 ' + days[days.length - 1].day) : 'no dated rows'; + host.appendChild(el('p', 'view-sub', fmtNum(u.totals.events) + ' usage events \u00b7 ' + esc(range) + (u.usersInFile && u.usersInFile.length === 1 ? ' \u00b7 ' + esc(u.usersInFile[0]) : ''))); + + // The single most important thing a reader can misunderstand about this data. + host.appendChild(el('div', 'alert alert-info', 'Cursor\u2019s own figures, imported from your dashboard export \u2014 not a CodeMie estimate. Rows marked Included are covered by your Cursor plan, which is a billing category, not zero usage: they still carry real tokens and cost, and both are counted here. These events have no session id, so they are shown beside the session table rather than merged into it, and they are not added to any cost figure elsewhere in this report.')); + + var kpis = [ + ['Events', fmtNum(u.totals.events)], + ['Total tokens', fmtTokens(u.totals.tokens.total)], + ['Cost', u.hasCost ? fmtUSD(u.totals.costUSD) : UNKNOWN_LABEL] + ]; + var grid = el('div', 'kpi-grid'); grid.style.gridTemplateColumns = 'repeat(3,1fr)'; + kpis.forEach(function (k) { + var c = el('div', 'kpi'); + c.appendChild(el('div', 'kpi-label', k[0])); + c.appendChild(el('div', 'kpi-value', k[1])); + grid.appendChild(c); + }); + host.appendChild(grid); + if (!u.hasCost) { + host.appendChild(el('div', 'alert alert-warning', 'This export variant has no Cost column (it ships Requests instead), so cost shows as a dash. The token counts are unaffected.')); + } + + var tokCols = ['Input', 'Cache write', 'Cache read', 'Output', 'Total']; + function tokCells(t) { return [fmtTokens(t.input), fmtTokens(t.cacheCreation), fmtTokens(t.cacheRead), fmtTokens(t.output), fmtTokens(t.total)]; } + + var mCard = card('By model', 'as reported by Cursor'); + mCard._body.innerHTML = '
' + tableHTML( + ['Model', 'Events'].concat(tokCols).concat(['Cost']), + (u.byModel || []).map(function (m) { + return [esc(m.model || '\u2014'), fmtNum(m.events)].concat(tokCells(m.tokens)).concat([u.hasCost ? fmtUSD(m.costUSD) : UNKNOWN_LABEL]); + }) + ) + '
'; + host.appendChild(mCard); + + var dCard = card('By day', 'export rows grouped by date'); + dCard._body.innerHTML = '
' + tableHTML( + ['Day', 'Events'].concat(tokCols).concat(['Cost']), + days.map(function (d) { + return [esc(d.day), fmtNum(d.events)].concat(tokCells(d.tokens)).concat([u.hasCost ? fmtUSD(d.costUSD) : UNKNOWN_LABEL]); + }) + ) + '
'; + host.appendChild(dCard); + }; + VIEWS.cost = function (host, fs) { host.appendChild(el('h2', 'view-title', 'Cost')); host.appendChild(el('p', 'view-sub', 'Estimated cost (API-equivalent) — token usage × model pricing. This is what the same usage would have been metered at through the API, not an invoice.')); @@ -1500,7 +1565,9 @@ document.querySelectorAll('.nav-i').forEach(function (n) { n.classList.toggle('active', n.getAttribute('data-view') === state.view); }); // The remote-source view is opt-in; without a pull there is nothing to navigate to. document.querySelectorAll('.nav-i[data-optional]').forEach(function (n) { - if (n.getAttribute('data-view') === 'cursorteam' && !DATA.meta.cursorTeamAnalytics) n.style.display = 'none'; + var v = n.getAttribute('data-view'); + if (v === 'cursorteam' && !DATA.meta.cursorTeamAnalytics) n.style.display = 'none'; + if (v === 'cursorusage' && !DATA.meta.cursorUsage) n.style.display = 'none'; }); } diff --git a/src/cli/commands/analytics/report/payload-builder.ts b/src/cli/commands/analytics/report/payload-builder.ts index d25eabcb1..f1298acee 100644 --- a/src/cli/commands/analytics/report/payload-builder.ts +++ b/src/cli/commands/analytics/report/payload-builder.ts @@ -5,6 +5,7 @@ */ import type { CursorTeamAnalytics } from '@/agents/plugins/cursor/cursor.team-analytics.js'; +import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import type { RootAnalytics } from '../types.js'; import type { SessionCostIndex, CostSummary, AgentCoverage } from '../cost/types.js'; import { emptyUsage } from '../cost/cost-calculator.js'; @@ -20,6 +21,8 @@ export interface PayloadContext { periodEnd?: string; // ISO — caller stamps from filter or session end /** Opt-in Cursor Team Analytics for the report owner; absent unless the gate opened. */ cursorTeamAnalytics?: CursorTeamAnalytics; + /** Opt-in Cursor usage-events CSV import; absent unless a path was given. */ + cursorUsage?: CursorUsageImport; } export function buildPayload( @@ -174,6 +177,7 @@ export function buildPayload( coverage: [...coverageMap.values()].sort((a, b) => b.total - a.total), ...(ctx.userEmail !== undefined && { userEmail: ctx.userEmail }), ...(ctx.cursorTeamAnalytics !== undefined && { cursorTeamAnalytics: ctx.cursorTeamAnalytics }), + ...(ctx.cursorUsage !== undefined && { cursorUsage: ctx.cursorUsage }), ...(ctx.periodStart !== undefined ? { periodStart: ctx.periodStart } : minStartMs !== undefined diff --git a/src/cli/commands/analytics/report/template.html b/src/cli/commands/analytics/report/template.html index f151f34bf..b046b7311 100644 --- a/src/cli/commands/analytics/report/template.html +++ b/src/cli/commands/analytics/report/template.html @@ -287,6 +287,7 @@
Spend
Cost
Raw
+
Cursor Usage CSV
Cursor Team API
Sessions
diff --git a/src/cli/commands/analytics/report/types.ts b/src/cli/commands/analytics/report/types.ts index 4b479f6b7..162cd2dfd 100644 --- a/src/cli/commands/analytics/report/types.ts +++ b/src/cli/commands/analytics/report/types.ts @@ -4,6 +4,7 @@ */ import type { CursorTeamAnalytics } from '@/agents/plugins/cursor/cursor.team-analytics.js'; +import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import type { TokenUsage, ModelCost, AgentCoverage, CostSeriesPoint, DispatchEvent } from '../cost/types.js'; import type { ToolStats, NamedInvocationStats } from '../types.js'; @@ -89,6 +90,12 @@ export interface ReportMeta { * fields, so merging it into session rows would invent both a key and a figure. */ cursorTeamAnalytics?: CursorTeamAnalytics; + /** + * Optional Cursor usage-events CSV import — the only source of real Cursor tokens and cost. + * Kept beside the sessions rather than inside them: its rows are per-event with no composerId, + * so there is no key to join on, and its totals must never be silently added to session costs. + */ + cursorUsage?: CursorUsageImport; periodStart?: string; // ISO — start of the reported range; always present when the report contains any sessions periodEnd?: string; // ISO — end of the reported range; always present when the report contains any sessions } diff --git a/src/cli/commands/analytics/types.ts b/src/cli/commands/analytics/types.ts index cf86deba3..0fd674cac 100644 --- a/src/cli/commands/analytics/types.ts +++ b/src/cli/commands/analytics/types.ts @@ -257,6 +257,13 @@ export interface AnalyticsOptions { * and neither does the credential alone. */ cursorTeamAnalytics?: boolean; + /** Path to a Cursor usage-events CSV exported from the Cursor dashboard (no network call). */ + cursorUsageCsv?: string; + /** + * Which `User` column value to keep from that CSV. Defaults to the report owner's configured + * email, which is often a different address from the one on the Cursor account. + */ + cursorUsageUser?: string; } /** Options for the `analytics otel` subcommand: the shared base plus OTEL-specific flags. */ From 92032f8470d2323fce822d6be9616d5ec52a21a3 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:27 +0300 Subject: [PATCH 20/34] fix(analytics): frame Cursor Team Analytics as admin-only, not the member path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #23. The feature is kept and its gate is unchanged, but every surface that described it was written as though any team member could use it to answer "what did Cursor cost?". Two things make that false: the endpoints need an admin-scoped key an ordinary member cannot obtain, and they return no token or cost fields at any tier even for an admin. So a member following the old copy would chase a credential they cannot get, for data that would not answer their question, and land on a 401 that told them to go set CURSOR_TEAM_ANALYTICS_API_KEY — the exact dead end this fixes. CLI help, the failure message, and the report's empty state and section header now say enterprise-team-admins-only, disclaim tokens and cost, and point at --cursor-usage-csv instead. The audience wording lives in two exported constants so the CLI and the report cannot drift apart, and a test asserts the member hint never names the API key env var. --- .../cursor/__tests__/team-analytics.test.ts | 25 +++++++++++++++++- .../plugins/cursor/cursor.team-analytics.ts | 26 ++++++++++++++++--- src/cli/commands/analytics/index.ts | 7 ++--- .../commands/analytics/report/client/app.js | 10 ++++--- 4 files changed, 56 insertions(+), 12 deletions(-) diff --git a/src/agents/plugins/cursor/__tests__/team-analytics.test.ts b/src/agents/plugins/cursor/__tests__/team-analytics.test.ts index 46ae81132..626754fc3 100644 --- a/src/agents/plugins/cursor/__tests__/team-analytics.test.ts +++ b/src/agents/plugins/cursor/__tests__/team-analytics.test.ts @@ -7,7 +7,13 @@ */ import { describe, it, expect } from 'vitest'; -import { fetchCursorTeamAnalytics, TEAM_ANALYTICS_ENDPOINTS, type TeamAnalyticsRequest } from '../cursor.team-analytics.js'; +import { + fetchCursorTeamAnalytics, + TEAM_ANALYTICS_ENDPOINTS, + TEAM_ANALYTICS_AUDIENCE, + TEAM_ANALYTICS_MEMBER_HINT, + type TeamAnalyticsRequest, +} from '../cursor.team-analytics.js'; /** A fetch stand-in that records every URL it was asked for. */ function recordingFetch(handler?: (url: string) => { status?: number; body?: unknown }) { @@ -102,3 +108,20 @@ describe('Cursor Team Analytics results', () => { expect(await fetchCursorTeamAnalytics(enabled, { fetch: impl as never })).toBeNull(); }); }); + +/** + * Team Analytics is an enterprise-ADMIN feature that returns no tokens or cost. An ordinary team + * member cannot obtain the key and would gain nothing from it, so no surface may imply otherwise + * or leave them at an auth-failure dead end. See issue #23. + */ +describe('Cursor Team Analytics audience framing', () => { + it('describes itself as admin-only and disclaims tokens/cost', () => { + expect(TEAM_ANALYTICS_AUDIENCE).toMatch(/admin/i); + expect(TEAM_ANALYTICS_AUDIENCE).not.toMatch(/token|cost/i); + }); + + it('points a member at the usage CSV rather than at getting an API key', () => { + expect(TEAM_ANALYTICS_MEMBER_HINT).toMatch(/--cursor-usage-csv/); + expect(TEAM_ANALYTICS_MEMBER_HINT).not.toMatch(/CURSOR_TEAM_ANALYTICS_API_KEY/); + }); +}); diff --git a/src/agents/plugins/cursor/cursor.team-analytics.ts b/src/agents/plugins/cursor/cursor.team-analytics.ts index dc8933e06..e55b422d2 100644 --- a/src/agents/plugins/cursor/cursor.team-analytics.ts +++ b/src/agents/plugins/cursor/cursor.team-analytics.ts @@ -7,10 +7,17 @@ * gated on BOTH an explicit invocation flag and a configured credential — a token sitting in * config must never be enough on its own. * - * What the API does and does not give us: none of the documented endpoints returns token or - * cost fields at any tier (re-verified 2026-09-05), so this cannot close the Cursor billable- - * token gap and must never be presented as if it did. The rows below are edit/activity - * aggregates only. They are also per-user/per-date aggregates carrying no `composerId`, so + * Two things about the audience, because getting them wrong strands people: + * + * 1. **This is enterprise-team-ADMIN only.** The endpoints require an admin-scoped key that an + * ordinary team member cannot obtain. Telling a member to "set CURSOR_TEAM_ANALYTICS_API_KEY" + * sends them after a credential they cannot get. + * 2. **It returns no tokens and no cost at any tier** (re-verified against the live docs + * 2026-09-05), so even an admin cannot close the Cursor billable-usage gap with it. The rows + * below are edit/activity aggregates only. + * + * The path that *does* yield real Cursor tokens and cost — for admins and members alike — is the + * dashboard usage export, imported via `--cursor-usage-csv` (see `cursor.usage-csv.ts`). They are also per-user/per-date aggregates carrying no `composerId`, so * there is no key on which to join them to local sessions — hence the report renders them as a * clearly separate section rather than folding them into the session table. * @@ -34,6 +41,17 @@ export const TEAM_ANALYTICS_ENDPOINTS = [ { endpoint: 'commands', label: 'Commands' }, ] as const; +/** Who can actually use this. Surfaced in CLI help and the report's empty state. */ +export const TEAM_ANALYTICS_AUDIENCE = + 'Enterprise team admins only — requires an admin-scoped Cursor Team API key.'; + +/** + * What to tell everyone else. Deliberately does NOT name the API key env var: a member who + * cannot get a key must be pointed at the path that works, not at the one that will reject them. + */ +export const TEAM_ANALYTICS_MEMBER_HINT = + 'For real Cursor tokens and cost, export your usage from the Cursor dashboard (Usage → Export) and pass it with --cursor-usage-csv .'; + export interface TeamAnalyticsRequest { /** Explicit per-invocation opt-in (the CLI flag). A credential alone must never enable calls. */ enabled: boolean; diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 52f175b95..9a43f991e 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -189,9 +189,10 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS if (!cursorTeamAnalytics) { // Do NOT tell an ordinary team member to go set an admin API key — they cannot get // one, and it would not carry tokens or cost even if they could. Point at the CSV. - console.log(chalk.yellow('\n Cursor Team Analytics returned nothing. It is available to enterprise team ADMINS only,')); - console.log(chalk.yellow(' and it never returns tokens or cost. For real Cursor tokens and cost, export your usage')); - console.log(chalk.yellow(' from the Cursor dashboard (Usage → Export) and pass it with --cursor-usage-csv .')); + const { TEAM_ANALYTICS_AUDIENCE, TEAM_ANALYTICS_MEMBER_HINT } = await import('@/agents/plugins/cursor/cursor.team-analytics.js'); + console.log(chalk.yellow(`\n Cursor Team Analytics returned nothing. ${TEAM_ANALYTICS_AUDIENCE}`)); + console.log(chalk.yellow(' It also never returns tokens or cost, so it cannot answer "what did Cursor cost?".')); + console.log(chalk.yellow(` ${TEAM_ANALYTICS_MEMBER_HINT}`)); console.log(chalk.dim(' Report continues without the Team Analytics section.')); } } diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index c3f4d42b5..98270cbca 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -836,13 +836,15 @@ var ta = DATA.meta.cursorTeamAnalytics; host.appendChild(el('h2', 'view-title', 'Cursor Team API')); if (!ta) { - host.appendChild(el('p', 'view-sub', 'Not fetched for this report.')); - host.appendChild(el('div', 'empty', 'Run with --cursor-team-analytics and CURSOR_TEAM_ANALYTICS_API_KEY set to include your own Cursor Team Analytics aggregates.')); + host.appendChild(el('p', 'view-sub', 'Not fetched for this report \u00b7 enterprise team admins only')); + // Never leave a non-admin reader chasing a credential they cannot get, for data that would + // not answer their question anyway. Name the path that actually works. + host.appendChild(el('div', 'empty', 'Cursor Team Analytics is available to enterprise team admins with an admin-scoped API key, and it returns edit and activity aggregates only \u2014 never tokens or cost.

For real Cursor tokens and cost, export your usage from the Cursor dashboard (Usage \u2192 Export) and re-run with --cursor-usage-csv <path>.')); return; } var range = (ta.startDate || '…') + ' → ' + (ta.endDate || '…'); - host.appendChild(el('p', 'view-sub', 'Fetched from Cursor\u2019s Team Analytics API for ' + esc(ta.userEmail) + ' · ' + esc(range))); - host.appendChild(el('div', 'alert alert-info', 'Remote data, shown separately on purpose. These are Cursor\u2019s own edit and activity aggregates for your account; they carry no token or cost fields and no session key, so nothing here is joined to the local sessions or added to any cost figure elsewhere in this report.')); + host.appendChild(el('p', 'view-sub', 'Team API aggregates (admin) for ' + esc(ta.userEmail) + ' · ' + esc(range))); + host.appendChild(el('div', 'alert alert-info', 'Remote admin team-API aggregates, shown separately on purpose. These are Cursor\u2019s own edit and activity counters for your account. They carry no token or cost fields and no session key, so nothing here is joined to the local sessions or added to any cost figure elsewhere in this report \u2014 and this section can never tell you what Cursor cost. For that, import a usage export with --cursor-usage-csv.')); if (ta.failedEndpoints && ta.failedEndpoints.length) { host.appendChild(el('div', 'alert alert-warning', 'Incomplete: ' + esc(ta.failedEndpoints.join(', ')) + ' could not be fetched, so this section is partial.')); } From 25a2e7bedc73635fae96f1fb709ae4fd5b475f94 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:28 +0300 Subject: [PATCH 21/34] docs(analytics): split Cursor guidance into admin and member paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #24. The docs presented Team Analytics as the way to close the Cursor token gap. It is not, for two independent reasons: it needs an admin-scoped key an ordinary member cannot obtain, and it returns no token or cost field at any tier even for an admin. ANALYTICS-REPORT.md now opens that topic with an audience table — anyone gets real tokens and cost from the usage CSV with no credential and no network call; enterprise admins additionally get edit/activity aggregates from the API — and says plainly that if the question is "what did Cursor cost?", the API cannot answer it for anyone. Documents the two facts the real exports forced: Kind=Included is a billing category rather than zero usage (a verified export had all 61 rows Included and still carried 39,952,466 tokens and $25.25), and two export shapes exist, one without a Cost column at all. The analytics-only-agents section no longer dead- ends on "no local store has the numbers" — it now points at the export that does. CURSOR_INTEGRATION.md and the external-integrations guide follow suit. --- .../integration/external-integrations.md | 22 ++- docs/ANALYTICS-REPORT.md | 134 +++++++++++++----- docs/CURSOR_INTEGRATION.md | 28 +++- 3 files changed, 137 insertions(+), 47 deletions(-) diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index c0c11f7c0..03e51a598 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -310,7 +310,12 @@ all read-only and all fail-soft. `CURSOR_HOME` relocates every one of them. Curs 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. Such +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 `, `src/agents/plugins/cursor/cursor.usage-csv.ts`) — a local file read +with no credential. `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 @@ -321,14 +326,19 @@ the session `usagePartial`. Full operational and developer guide: `docs/CURSOR_INTEGRATION.md`. Rationale for reading an undocumented store: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`. -### Cursor Enterprise Team Analytics API (opt-in) +### Cursor Enterprise Team Analytics API (opt-in, admin-only) Cursor publishes an official Team Analytics API (). CodeMie integrates it as a strictly -opt-in, user-scoped extra: `src/agents/plugins/cursor/cursor.team-analytics.ts`, surfaced by -`codemie analytics --report --cursor-team-analytics` with `CURSOR_TEAM_ANALYTICS_API_KEY` set. -**Both** are required — a configured credential alone never triggers a call — and this is the only -network call anywhere in the analytics path. It still **cannot** supply tokens or cost. +opt-in, user-scoped extra for **enterprise team admins**: `src/agents/plugins/cursor/cursor.team-analytics.ts`, +surfaced by `codemie analytics --report --cursor-team-analytics` with an admin-scoped +`CURSOR_TEAM_ANALYTICS_API_KEY` set. **Both** are required — a configured credential alone never +triggers a call — and this is the only network call anywhere in the analytics path. + +It still **cannot** supply tokens or cost, and the key is not obtainable by an ordinary team +member. No CLI, doc, or UI surface may present it as the member route to billable usage; every +such surface must point at `--cursor-usage-csv` instead. The audience wording is centralized in +`TEAM_ANALYTICS_AUDIENCE` / `TEAM_ANALYTICS_MEMBER_HINT` so the CLI and report cannot drift. What the API is: diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 5af601ae4..28d228963 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -28,8 +28,8 @@ codemie analytics --report --report-format both # Include ALL local agent usage — also the sessions you ran outside CodeMie codemie analytics --report --open --include-external -# Add your own Cursor Team Analytics aggregates (opt-in; makes a network call) -CURSOR_TEAM_ANALYTICS_API_KEY=... codemie analytics --report --open --cursor-team-analytics +# Real Cursor tokens and cost — import a usage export from the Cursor dashboard +codemie analytics --report --open --cursor-usage-csv ~/Downloads/team-usage-events-....csv ``` > **If your question is "what did AI actually cost us?", you probably want `--include-external`.** @@ -41,7 +41,7 @@ CURSOR_TEAM_ANALYTICS_API_KEY=... codemie analytics --report --open --cursor-tea ## What the Report Covers -The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*, plus an optional tenth ([Cursor Team API](#cursor-team-analytics)) that appears only when you opt into that remote pull. +The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*, plus two optional views ([Cursor Usage CSV](#cursor-usage-csv) and [Cursor Team API](#cursor-team-analytics)) that appear only when you opt into those sources. Discovered sessions that CodeMie did not launch are **excluded by default**; see [Session provenance](#session-provenance). @@ -293,11 +293,15 @@ What that looks like in the report: A measurement taken on one machine: of 469 discovered Cursor sessions, 0 carried any token signal and 24 carried tool calls. Conversations that *do* still hold token counts were all roughly a year -old and no longer discoverable at all. There is no local store that has the recent numbers — every -Cursor database, per-session chat store, and transcript directory was checked. CodeMie will not -manufacture the figure from context-window fill, transcript length, or tool-call counts, because -those are not billable tokens and presenting them as such would trade an honest blank for a -confident wrong number. +old and no longer discoverable at all. Every Cursor database, per-session chat store, and transcript +directory was checked — no *local* store has the recent numbers. CodeMie will not manufacture the +figure from context-window fill, transcript length, or tool-call counts, because those are not +billable tokens and presenting them as such would trade an honest blank for a confident wrong +number. + +**You can still get the real numbers** — they live in Cursor's dashboard usage export rather than +on disk. See [Usage CSV import](#cursor-usage-csv), which turns those dashes into Cursor's own +token and cost figures. @@ -328,15 +332,73 @@ Two things to know before you rely on the wider number: `--include-external` applies to the default local-session source only. The `analytics otel` subcommand does not accept it — an OTEL events file has no notion of CodeMie ownership. + + +### Cursor tokens and cost — two paths, by audience + +Everything else in this document reads local files. Cursor is the exception worth understanding, +because **Cursor's local stores no longer record billable token counts** (see +[Analytics-only agents](#analytics-only-agents)), so Cursor sessions show `—` in the session table. +There are two ways to fill that in, and they are not interchangeable: + +| You are | Use | Gives you | Network? | +|---|---|---|---| +| **Anyone** (member or admin) | [Usage CSV import](#cursor-usage-csv) — `--cursor-usage-csv` | **Real tokens and cost** | No | +| **Enterprise team admin** | [Team Analytics](#cursor-team-analytics) — `--cursor-team-analytics` | Edit/activity aggregates. **No tokens, no cost** | Yes | + +If your question is *"what did Cursor cost?"*, you want the CSV. The Team Analytics API cannot +answer it at any tier, for anyone, including admins. + + + +#### Usage CSV import (everyone) + +Cursor's dashboard exports the usage ledger CodeMie cannot read locally. This is a plain file +read — no credential, no network call. + +1. In Cursor, open **Usage** and click **Export** for the period you want. +2. Pass the downloaded file: + +```bash +codemie analytics --report --open --cursor-usage-csv ~/Downloads/team-usage-events-....csv +``` + +It renders as its own **Cursor Usage CSV** view with totals, a by-model table, and a by-day table. + +> **`Kind=Included` does not mean free.** `Included` is Cursor's *billing category* — "covered by +> your plan" — not a statement that the usage was unmetered. In a real export, all 61 events were +> `Included` and together carried **39,952,466 tokens and $25.25 of cost**. CodeMie counts the +> tokens and the `Cost` column regardless of `Kind`, and never uses the word "Included" as a cost +> label anywhere in the report. + +Things worth knowing about the export format: + +- **Two shapes exist.** Most exports end with a `Cost` column; at least one variant ships + `Requests` instead and carries no cost at all. Both import. When `Cost` is absent the section + shows `—` for money and says why — the token counts are unaffected. +- **`Cost` is not always a number.** Some rows read `Free`. Those contribute zero rather than + corrupting the total. +- **Rows are filtered to you.** The `User` column is matched against your configured CodeMie + email, which is frequently *not* the address on your Cursor account. Override with + `--cursor-usage-user `. If the filter matches nothing, CodeMie warns and lists the + addresses actually present in the file rather than showing an empty section. +- **It is never merged into your sessions.** Export rows are per-event with no session id, so + there is no key to join them on. The section sits beside the session table and contributes to no + cost figure elsewhere in the report. Read them side by side, not summed. + -### Cursor Team Analytics (optional, opt-in, network) +#### Team Analytics API (enterprise team admins only) -Everything above reads local files. This one feature does not: it pulls your own aggregates from -**Cursor's Enterprise Team Analytics API**. It is off unless you explicitly ask for it. +> **This is not the way to get Cursor tokens or cost.** None of Cursor's documented Team Analytics +> endpoints returns a token or cost field at any tier. It also requires an **admin-scoped** key +> that an ordinary team member cannot obtain. If you are not a team admin, use the +> [usage CSV](#cursor-usage-csv) above. + +For admins who want Cursor's own edit and activity aggregates alongside their local data: ```bash -export CURSOR_TEAM_ANALYTICS_API_KEY='' +export CURSOR_TEAM_ANALYTICS_API_KEY='' codemie analytics --report --open --cursor-team-analytics ``` @@ -345,30 +407,21 @@ on its own, and neither does the flag without a key. Reading the machine you are CodeMie already makes; calling a remote service is not, so it stays a deliberate act each time. **What you get.** Four `by-user` endpoints — agent edits, tab completions, models, and commands — -filtered to your own email address, rendered in their own **Cursor Team API** view in the sidebar. -The view is hidden entirely unless a pull succeeded. - -**What you do not get: tokens or cost.** None of Cursor's documented endpoints returns a token or -cost field at any tier, so this cannot close the gap described in -[Analytics-only agents](#analytics-only-agents), and it is never presented as if it did. The rows -are edit and activity counters only. - -**It is shown separately on purpose.** The API returns per-user/per-date aggregates with no session -identifier, so there is no key on which to join them to your local Cursor sessions — and no token or -cost field to join with. Merging them into the session table would mean inventing both. Nothing in -this section contributes to any cost or token figure elsewhere in the report. +filtered to your own email address, in their own **Cursor Team API** view. The view is hidden +unless a pull succeeded. **Scope and privacy.** Only `by-user` endpoints are queried, always filtered to the requesting user's own email. No team-wide endpoint and no leaderboard, so a colleague's activity can never -appear in your personal report. The email comes from your CodeMie config — the same one embedded in -report metadata. +appear in your personal report. + +**Shown separately on purpose.** The API returns per-user/per-date aggregates with no session +identifier and no token or cost field, so there is nothing to join on and nothing to join with. +Merging them into the session table would mean inventing both. -**Requirements and failure modes.** You need an admin-scoped Cursor **Team** API key from an -enterprise team; individual and personal plans cannot use this API at all. Every failure — missing -key, rejected key, HTTP error, DNS failure, or a schema change on Cursor's side — degrades to an -omitted or explicitly-partial section and prints a one-line notice. The local report, which is the -part that always works, is never taken down by a remote outage. Run with `CODEMIE_DEBUG=true` to see -the per-endpoint outcome. +**Failure modes.** A missing key, a rejected key, an HTTP error, a DNS failure, or a schema change +on Cursor's side all degrade to an omitted or explicitly-partial section plus a one-line notice +pointing at the CSV path. The local report is never taken down by a remote outage. Run with +`CODEMIE_DEBUG=true` to see each endpoint's outcome. --- @@ -412,11 +465,16 @@ Source flags: --no-scan-native Skip native-log discovery (CodeMie-tracked sessions only) --include-external Also count local sessions CodeMie did not launch (see "Session provenance"; requires native scanning) - --cursor-team-analytics Fetch your own Cursor Team Analytics aggregates. - Makes a NETWORK CALL; also requires - CURSOR_TEAM_ANALYTICS_API_KEY. Neither the flag nor - the key does anything on its own. - (see "Cursor Team Analytics") + --cursor-usage-csv Import a Cursor usage-events CSV (Cursor dashboard + -> Usage -> Export) for REAL Cursor tokens and cost. + No network call. Anyone can use this. + --cursor-usage-user Which User column value to keep from the CSV + (default: your configured CodeMie email) + --cursor-team-analytics ENTERPRISE TEAM ADMINS ONLY. Fetches edit/activity + aggregates -- NOT tokens or cost. Makes a NETWORK + CALL; also requires CURSOR_TEAM_ANALYTICS_API_KEY. + Neither the flag nor the key works on its own. + (see "Cursor tokens and cost") Other flags: -v, --verbose Session-level breakdown in the terminal output @@ -428,7 +486,7 @@ Other flags: | Variable | Effect | |---|---| -| `CURSOR_TEAM_ANALYTICS_API_KEY` | Admin-scoped Cursor Team API key. Required *together with* `--cursor-team-analytics`; see [Cursor Team Analytics](#cursor-team-analytics). | +| `CURSOR_TEAM_ANALYTICS_API_KEY` | **Admin-scoped** Cursor Team API key. Required *together with* `--cursor-team-analytics`. Not needed — and not obtainable — for the [usage CSV path](#cursor-usage-csv). | | `CODEMIE_DEBUG=true` | Verbose per-source discovery and enrichment logging, including each Team Analytics endpoint's outcome. | **Every filter and source flag governs the terminal output and the HTML report alike.** There is no report-only or terminal-only filtering: `--include-external`, `--no-scan-native`, and the date/project/agent filters all decide which sessions the command sees, and both outputs are rendered from that same set. diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index ebc5c3d36..adf0e9b08 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -97,13 +97,35 @@ What this means when reading a report: table), the session is estimated at a published Claude Sonnet API rate, keeps its own model label, and is badged as partial. Treat it as an understated floor. - The Enterprise Team Analytics API does **not** close this gap: none of its documented endpoints - returns token or cost fields at any tier. See - [Cursor Enterprise Team Analytics API](../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-not-integrated). + returns token or cost fields at any tier, and it needs an **admin-scoped** key an ordinary team + member cannot obtain. See + [Cursor Enterprise Team Analytics API](../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-opt-in). Nothing here is inferred from `contextTokensUsed`, transcript text length, or tool-call counts. Those correlate with usage but are not billable token counts, and presenting them as such would trade an honest blank for a confident wrong number. +### The usage export does have the numbers + +The gap above is *local*. Cursor's dashboard still exports the billable ledger: **Usage → Export** +produces a `team-usage-events-*.csv` carrying per-event input, cache-write, cache-read, output and +total tokens, usually with a `Cost` column. Import it with `--cursor-usage-csv ` (no network +call, no credential) and CodeMie renders it as a separate **Cursor Usage CSV** report section. + +Two facts that decide how it must be read: + +- **`Kind=Included` is a billing category, not zero usage.** It means "covered by your plan". In a + verified 2026-09-05 export, all 61 events were `Included` and together carried 39,952,466 tokens + and $25.25 of cost. Treating `Included` as free would discard the only accurate Cursor figures + available, so CodeMie counts tokens and `Cost` regardless of `Kind` — and never uses "Included" + as a cost label in the UI. +- **Two export shapes exist.** Most end with a `Cost` column; at least one variant ships `Requests` + instead and has no cost at all. Both parse; the section dashes the money and says why when `Cost` + is missing. Some `Cost` cells also read `Free` and contribute zero. + +Export rows are per-event with no `composerId`, so they are never joined to local sessions or added +to any other cost figure — the report shows Cursor's own numbers beside CodeMie's, not summed in. + ### Database schema and versioning `state.vscdb` and `ai-code-tracking.db` are Cursor-internal and undocumented; there is no schema @@ -127,7 +149,7 @@ column that moved (see [Database schema drift](#database-schema-drift-after-a-cu |---|---| | `CURSOR_HOME` | Overrides `~/.cursor`. Also relocates `state.vscdb` to `$CURSOR_HOME/User/globalStorage/state.vscdb`, mirroring its real layout relative to Cursor's app-data root. Unset (the default) uses `~/.cursor` plus the per-OS app-data path above. | | `CODEMIE_DEBUG=true` | Enables the `[cursor]` debug logging described under [Logging and debugging](#logging-and-debugging). | -| `CURSOR_TEAM_ANALYTICS_API_KEY` | Admin-scoped Cursor Enterprise API key. Required *together with* `--cursor-team-analytics` before any network call is made; neither alone is enough. Unset (the default) means analytics stays entirely local. | +| `CURSOR_TEAM_ANALYTICS_API_KEY` | **Admin-scoped** Cursor Enterprise API key, for enterprise team admins only. Required *together with* `--cursor-team-analytics` before any network call is made; neither alone is enough. It returns edit/activity aggregates, **never tokens or cost** — for those use `--cursor-usage-csv`, which needs no credential. Unset (the default) means analytics stays entirely local. | `CURSOR_HOME` mirrors `COPILOT_HOME` in the Copilot CLI plugin and is what lets the whole ingestion path be driven against a fixture tree in tests. From 7d4084f046ecf3c1036ff44b71225454c41bc67a Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:29 +0300 Subject: [PATCH 22/34] fix(analytics): correct three usage-CSV import bugs found in review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An export with **no `User` column** imported nothing. The filter keyed off the caller's option rather than the column's presence, so a personal export that omits `User` compared every row against `''`, dropped all of them, and reported "matched no rows" for a perfectly valid file. Filtering now happens only when the export actually identifies users — with no `User` column there is no one else's data present to exclude. A thousands-separated `Cost` cell under-reported by 1000x. `money()` matched a number out of `1,234.50` without stripping separators first and got `1` — worse than the NaN it was written to avoid, because it is silently plausible. It now strips separators the way `num()` already did. Day buckets used a UTC slice of the timestamp while every other day-grouped view in the report buckets locally, so one report had two definitions of "day" and an evening event landed on tomorrow here and today elsewhere. Days are now derived in local time. Also collapses CursorUsageGroup/CursorUsageDay onto one CursorUsageBucket and the two identical report tables onto one builder, drops a parsed-but-unrendered maxMode field, and repairs a doc comment in cursor.team-analytics.ts where an old sentence had been welded onto new prose without an antecedent. Adds the full 61-event export as a fixture so issue #21's stated verification target is executed rather than described: 61 events, $25.25, 39,952,466 tokens, including the two `Free` cost cells the real file contains. A reviewer also flagged a BOM-prefixed export as fatal; a test proves otherwise — the header's own .trim() already strips U+FEFF — and it is kept as a regression guard. --- .../cursor/__tests__/cursor.usage-csv.test.ts | 61 ++++++++++++++++++ .../fixtures/cursor-usage-events-full.csv | 62 +++++++++++++++++++ .../plugins/cursor/cursor.team-analytics.ts | 8 ++- src/agents/plugins/cursor/cursor.usage-csv.ts | 52 ++++++++++------ .../commands/analytics/report/client/app.js | 37 ++++++----- 5 files changed, 180 insertions(+), 40 deletions(-) create mode 100644 src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events-full.csv diff --git a/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts b/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts index 6d37a14b0..e98ef9404 100644 --- a/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts +++ b/src/agents/plugins/cursor/__tests__/cursor.usage-csv.test.ts @@ -93,3 +93,64 @@ describe('loadCursorUsageCsv', () => { expect(loadCursorUsageCsv('/no/such/export.csv')).toBeNull(); }); }); + +/** + * The full 61-event export, verbatim apart from the email. This is the exact shape and scale the + * feature was specified against (issue #21), so the headline figures are asserted rather than + * described: all rows Included, $25.25, 39,952,466 tokens — and two `Free` cost cells. + */ +describe('the real 61-event export', () => { + const full = readFileSync(fileURLToPath(new URL('./fixtures/cursor-usage-events-full.csv', import.meta.url)), 'utf-8'); + + it('reproduces the export totals exactly', () => { + const out = parseCursorUsageCsv(full)!; + expect(out.events).toHaveLength(61); + expect(out.events.every((e) => e.kind === 'Included')).toBe(true); + expect(out.totals.costUSD).toBeCloseTo(25.25, 2); + expect(out.totals.tokens.total).toBe(39952466); + expect(out.totals.tokens.input).toBe(5625173); + expect(out.totals.tokens.cacheCreation).toBe(428582); + expect(out.totals.tokens.cacheRead).toBe(33354962); + expect(out.totals.tokens.output).toBe(543749); + expect(out.byDay.map((d) => d.day)).toEqual(['2026-08-28', '2026-08-31', '2026-09-04', '2026-09-05']); + expect(out.byModel.find((m) => m.model === 'auto')!.events).toBe(40); + }); +}); + +describe('malformed and variant exports', () => { + it('parses a file that begins with a byte-order mark', () => { + // Anything that has been through Excel or a browser download can arrive BOM-prefixed; without + // stripping it the first header cell reads "Date" and the whole import is rejected. + const out = parseCursorUsageCsv('\uFEFF' + fixture); + expect(out).not.toBeNull(); + expect(out!.events).toHaveLength(8); + }); + + it('keeps every row when the export has no User column at all', () => { + // A personal export can omit User entirely. Filtering on an absent column must not drop the + // whole file — there is no other user's data present to exclude. + const noUser = fixture + .replace('"Date","User",', '"Date",') + .replace(/^("[^"]*"),"owner@example\.com",/gm, '$1,'); + const out = parseCursorUsageCsv(noUser, { userEmail: 'someone@example.com' })!; + expect(out.events).toHaveLength(8); + expect(out.droppedByUserFilter).toBe(0); + }); + + it('reads a thousands-separated cost as the full amount, not its first digits', () => { + const big = fixture.replace('"0.07"', '"1,234.50"'); + const out = parseCursorUsageCsv(big)!; + expect(out.totals.costUSD).toBeCloseTo(3.80 + 1234.50, 2); + }); + + it('buckets days in local time, matching the rest of the report', () => { + // A UTC slice would put a 23:30 local event on the following day while every other view + // buckets it locally — one report, two day definitions. + const late = fixture.replace('2026-09-05T13:52:28.087Z', '2026-09-05T23:30:00.000Z'); + const out = parseCursorUsageCsv(late)!; + const expected = new Date('2026-09-05T23:30:00.000Z'); + const pad = (n: number) => String(n).padStart(2, '0'); + const localDay = `${expected.getFullYear()}-${pad(expected.getMonth() + 1)}-${pad(expected.getDate())}`; + expect(out.events.some((e) => e.day === localDay)).toBe(true); + }); +}); diff --git a/src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events-full.csv b/src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events-full.csv new file mode 100644 index 000000000..f97954224 --- /dev/null +++ b/src/agents/plugins/cursor/__tests__/fixtures/cursor-usage-events-full.csv @@ -0,0 +1,62 @@ +"Date","User","Cloud Agent ID","Automation ID","Kind","Model","Max Mode","Input (w/ Cache Write)","Input (w/o Cache Write)","Cache Read","Output Tokens","Total Tokens","Cost" +"2026-09-05T13:52:28.087Z","owner@example.com","","","Included","auto","No","0","30061","118400","1038","149499","0.07" +"2026-09-05T13:50:50.577Z","owner@example.com","","","Included","auto","No","0","3435","400768","1998","406201","0.10" +"2026-09-05T13:46:37.532Z","owner@example.com","","","Included","auto","No","0","123309","514176","5627","643112","0.28" +"2026-09-05T13:45:11.696Z","owner@example.com","","","Included","auto","No","0","6972","480768","1999","489739","0.13" +"2026-09-05T13:41:15.163Z","owner@example.com","","","Included","auto","No","0","8996","340736","1109","350841","0.09" +"2026-09-05T13:34:12.659Z","owner@example.com","","","Included","auto","No","0","181275","536832","11881","729988","0.39" +"2026-09-05T13:34:12.552Z","owner@example.com","","","Included","auto","No","0","153493","1207168","12048","1372709","0.51" +"2026-09-05T13:33:47.950Z","owner@example.com","","","Included","auto","No","0","201833","1291392","21077","1514302","0.63" +"2026-09-05T13:08:46.257Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","104940","238071","3820","346831","0.30" +"2026-09-05T13:08:29.351Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","38388","59050","2594","100032","0.10" +"2026-09-05T12:31:50.679Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","31032","2359096","11610","2401738","1.16" +"2026-09-05T12:22:47.673Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","213249","2087401","23918","2324568","1.43" +"2026-09-04T19:17:27.058Z","owner@example.com","","","Included","auto","No","0","166067","489728","14170","669965","0.37" +"2026-09-04T19:02:51.972Z","owner@example.com","","","Included","auto","No","0","153619","687488","25662","866769","0.47" +"2026-08-31T19:08:27.563Z","owner@example.com","","","Included","auto","No","0","16538","87936","447","104921","0.04" +"2026-08-31T18:53:10.303Z","owner@example.com","","","Included","auto","No","0","98458","6016","505","104979","0.11" +"2026-08-31T18:37:09.266Z","owner@example.com","","","Included","auto","No","0","67","100352","1623","102042","0.03" +"2026-08-31T18:19:11.482Z","owner@example.com","","","Included","auto","No","0","67","100352","1647","102066","0.03" +"2026-08-31T18:19:08.958Z","owner@example.com","","","Included","auto","No","0","88","121984","11988","134060","0.09" +"2026-08-31T17:49:57.620Z","owner@example.com","","","Included","auto","No","0","115928","6144","13279","135351","0.20" +"2026-08-31T17:49:54.032Z","owner@example.com","","","Included","auto","No","0","92547","206848","2906","302301","0.17" +"2026-08-31T15:32:52.035Z","owner@example.com","","","Included","auto","No","0","116039","125824","12362","254225","0.23" +"2026-08-31T15:31:26.602Z","owner@example.com","","","Included","auto","No","0","229325","206848","12774","448947","0.37" +"2026-08-31T15:31:25.394Z","owner@example.com","","","Included","auto","No","0","81784","303488","12744","398016","0.23" +"2026-08-31T15:31:11.660Z","owner@example.com","","","Included","auto","No","0","26771","28544","968","56283","0.04" +"2026-08-31T15:29:08.991Z","owner@example.com","","","Included","auto","No","0","18633","643584","12657","674874","0.23" +"2026-08-31T15:26:52.309Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","134119","606666","4655","745440","0.53" +"2026-08-31T15:26:13.449Z","owner@example.com","","","Included","auto","No","0","146696","3649152","33981","3829829","1.17" +"2026-08-31T15:25:47.622Z","owner@example.com","","","Included","auto","No","0","16871","360960","10188","388019","0.16" +"2026-08-31T15:20:22.032Z","owner@example.com","","","Included","auto","No","0","78268","90112","221","168601","0.11" +"2026-08-31T15:11:49.623Z","owner@example.com","","","Included","auto","No","0","127792","965504","26813","1120109","0.51" +"2026-08-31T15:10:35.709Z","owner@example.com","","","Included","auto","No","0","16582","208000","3158","227740","0.08" +"2026-08-31T15:06:38.268Z","owner@example.com","","","Included","auto","No","0","139728","251776","5609","397113","0.24" +"2026-08-31T15:06:05.829Z","owner@example.com","","","Included","auto","No","0","67072","473216","4340","544628","0.21" +"2026-08-31T14:46:33.316Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","263253","1068986","24738","1356977","1.07" +"2026-08-28T17:37:44.232Z","owner@example.com","","","Included","auto","No","0","13478","839552","4999","858029","0.23" +"2026-08-28T17:33:00.005Z","owner@example.com","","","Included","auto","No","0","168178","449024","6354","623556","0.32" +"2026-08-28T17:15:28.405Z","owner@example.com","","","Included","auto","No","0","6124","475648","5894","487666","0.15" +"2026-08-28T17:12:52.084Z","owner@example.com","","","Included","auto","No","0","2575","308736","7206","318517","0.11" +"2026-08-28T17:01:04.463Z","owner@example.com","","","Included","auto","No","0","158514","448768","3753","611035","0.30" +"2026-08-28T16:56:57.387Z","owner@example.com","","","Included","claude-opus-5-thinking-high","No","168695","4598","791217","19889","984399","1.97" +"2026-08-28T16:56:24.687Z","owner@example.com","","","Included","auto","No","0","142720","803712","15447","961879","0.42" +"2026-08-28T16:51:57.500Z","owner@example.com","","","Included","auto","No","0","395","121088","92","121575","0.03" +"2026-08-28T16:40:38.603Z","owner@example.com","","","Included","auto","No","0","235665","1661440","32317","1929422","0.81" +"2026-08-28T16:38:18.311Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","43773","8469","1379","53621","0.08" +"2026-08-28T16:35:04.195Z","owner@example.com","","","Included","composer-2.5-fast","No","0","73532","367686","7049","448267","0.43" +"2026-08-28T16:34:56.979Z","owner@example.com","","","Included","claude-opus-5-thinking-high","No","184657","5759","1494129","18255","1702800","2.50" +"2026-08-28T16:34:55.299Z","owner@example.com","","","Included","cursor-grok-4.6-high","No","0","182623","526229","6718","715570","0.59" +"2026-08-28T16:34:42.274Z","owner@example.com","","","Included","claude-opus-5-thinking-high","No","75230","5427","394112","13247","488016","1.00" +"2026-08-28T16:34:03.637Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","40486","119275","2817","162578","0.13" +"2026-08-28T16:32:39.680Z","owner@example.com","","","Included","cursor-grok-4.6-high","No","0","83389","438214","14561","536164","0.41" +"2026-08-28T16:32:34.965Z","owner@example.com","","","Included","cursor-grok-4.6-high","No","","","","","","Free" +"2026-08-28T16:32:20.117Z","owner@example.com","","","Included","cursor-grok-4.6-high","No","0","20924","2944","348","24216","0.04" +"2026-08-28T16:22:57.513Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","216764","1502534","11314","1730612","1.11" +"2026-08-28T16:17:11.434Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","83196","85627","1842","170665","0.18" +"2026-08-28T16:17:03.174Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","640283","690568","10824","1341675","1.51" +"2026-08-28T16:16:26.737Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","18606","6656","219","25481","0.04" +"2026-08-28T16:05:31.208Z","owner@example.com","","","Included","auto","No","0","67132","405120","4591","476843","0.19" +"2026-08-28T16:05:01.199Z","owner@example.com","","","Included","cursor-grok-4.6-medium","No","0","152124","727936","12350","892410","0.67" +"2026-08-28T15:51:14.358Z","owner@example.com","","","Included","auto","No","0","55613","262912","6130","324655","0.15" +"2026-08-28T15:51:09.846Z","owner@example.com","","","Included","auto","No","","","","","","Free" diff --git a/src/agents/plugins/cursor/cursor.team-analytics.ts b/src/agents/plugins/cursor/cursor.team-analytics.ts index e55b422d2..39661766b 100644 --- a/src/agents/plugins/cursor/cursor.team-analytics.ts +++ b/src/agents/plugins/cursor/cursor.team-analytics.ts @@ -17,9 +17,11 @@ * below are edit/activity aggregates only. * * The path that *does* yield real Cursor tokens and cost — for admins and members alike — is the - * dashboard usage export, imported via `--cursor-usage-csv` (see `cursor.usage-csv.ts`). They are also per-user/per-date aggregates carrying no `composerId`, so - * there is no key on which to join them to local sessions — hence the report renders them as a - * clearly separate section rather than folding them into the session table. + * dashboard usage export, imported via `--cursor-usage-csv` (see `cursor.usage-csv.ts`). + * + * These rows are also per-user/per-date aggregates carrying no `composerId`, so there is no key + * on which to join them to local sessions — hence the report renders them as a clearly separate + * section rather than folding them into the session table. * * See `.ai-run/guides/integration/external-integrations.md` and `docs/CURSOR_INTEGRATION.md`. */ diff --git a/src/agents/plugins/cursor/cursor.usage-csv.ts b/src/agents/plugins/cursor/cursor.usage-csv.ts index 951658983..e37b27c10 100644 --- a/src/agents/plugins/cursor/cursor.usage-csv.ts +++ b/src/agents/plugins/cursor/cursor.usage-csv.ts @@ -25,13 +25,16 @@ import { logger } from '@/utils/logger.js'; export interface CursorUsageEvent { /** ISO timestamp as written by the export. */ date: string; - /** Local day key (YYYY-MM-DD) used for grouping. */ + /** + * Local day key (YYYY-MM-DD). Derived in local time, not by slicing the UTC timestamp, so + * these buckets line up with every other day-grouped view in the report — an evening event + * must not land on tomorrow here and today everywhere else. + */ day: string; user: string; /** Cursor's billing category — `Included`, `On-Demand`, … Recorded, never used to zero usage. */ kind: string; model: string; - maxMode: boolean; tokens: CursorUsageTokens; /** USD from the `Cost` column; 0 when the export variant has no such column. */ costUSD: number; @@ -47,19 +50,15 @@ export interface CursorUsageTokens { total: number; } -export interface CursorUsageGroup { - model: string; +/** Rolled-up usage for one key (a model, a day, …). */ +export interface CursorUsageBucket { events: number; tokens: CursorUsageTokens; costUSD: number; } -export interface CursorUsageDay { - day: string; - events: number; - tokens: CursorUsageTokens; - costUSD: number; -} +export type CursorUsageGroup = CursorUsageBucket & { model: string }; +export type CursorUsageDay = CursorUsageBucket & { day: string }; export interface CursorUsageImport { events: CursorUsageEvent[]; @@ -145,12 +144,26 @@ function num(v: string | undefined): number { return Number.isFinite(n) ? n : 0; } +/** Local YYYY-MM-DD for an export timestamp; empty when it is unparseable. */ +function localDay(iso: string): string { + const d = new Date(iso); + if (Number.isNaN(d.getTime())) { + return iso.slice(0, 10); + } + const pad = (n: number): string => String(n).padStart(2, '0'); + return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; +} + /** - * Cost cells are mostly plain decimals but the export also writes words such as `Free`. Pull the - * first number out and treat anything wordy as zero rather than NaN-poisoning the total. + * Cost cells are mostly plain decimals but the export also writes words such as `Free` (two of + * them in the verified 61-event export). Pull the first number out and treat anything wordy as + * zero rather than NaN-poisoning the total. + * + * Thousands separators are stripped FIRST: matching a number out of `1,234.50` without doing so + * yields `1`, which is far worse than a NaN because it is silently plausible. */ function money(v: string | undefined): number { - const m = /-?\d+(?:\.\d+)?/.exec(String(v ?? '')); + const m = /-?\d+(?:\.\d+)?/.exec(String(v ?? '').replace(/,/g, '')); return m ? Number(m[0]) : 0; } @@ -170,7 +183,11 @@ export function parseCursorUsageCsv(text: string, options: ParseOptions = {}): C }; const hasCost = header.includes('Cost'); - const wanted = options.userEmail?.trim().toLowerCase(); + // Only filter when the export actually identifies users. A personal export can omit the column + // entirely, and filtering an absent column would drop every row of a perfectly valid file — + // there is no one else's data in it to exclude. + const hasUser = header.includes('User'); + const wanted = hasUser ? options.userEmail?.trim().toLowerCase() : undefined; const usersInFile = new Set(); const events: CursorUsageEvent[] = []; let droppedByUserFilter = 0; @@ -194,18 +211,17 @@ export function parseCursorUsageCsv(text: string, options: ParseOptions = {}): C }; events.push({ date, - day: date.slice(0, 10), + day: localDay(date), user, kind: (at(r, 'Kind') ?? '').trim(), model: (at(r, 'Model') ?? '').trim(), - maxMode: /^yes$/i.test((at(r, 'Max Mode') ?? '').trim()), tokens, costUSD: hasCost ? money(at(r, 'Cost')) : 0, }); } - const group = (keyOf: (e: CursorUsageEvent) => K) => { - const m = new Map(); + const group = (keyOf: (e: CursorUsageEvent) => K): Map => { + const m = new Map(); for (const e of events) { const k = keyOf(e); const cur = m.get(k) ?? { events: 0, tokens: emptyTokens(), costUSD: 0 }; diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index 98270cbca..aa6f701d6 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -910,26 +910,25 @@ host.appendChild(el('div', 'alert alert-warning', 'This export variant has no Cost column (it ships Requests instead), so cost shows as a dash. The token counts are unaffected.')); } + // The by-model and by-day tables are the same table over the same bucket shape; only the + // first column differs. One builder keeps their columns and money handling from drifting. var tokCols = ['Input', 'Cache write', 'Cache read', 'Output', 'Total']; - function tokCells(t) { return [fmtTokens(t.input), fmtTokens(t.cacheCreation), fmtTokens(t.cacheRead), fmtTokens(t.output), fmtTokens(t.total)]; } - - var mCard = card('By model', 'as reported by Cursor'); - mCard._body.innerHTML = '
' + tableHTML( - ['Model', 'Events'].concat(tokCols).concat(['Cost']), - (u.byModel || []).map(function (m) { - return [esc(m.model || '\u2014'), fmtNum(m.events)].concat(tokCells(m.tokens)).concat([u.hasCost ? fmtUSD(m.costUSD) : UNKNOWN_LABEL]); - }) - ) + '
'; - host.appendChild(mCard); - - var dCard = card('By day', 'export rows grouped by date'); - dCard._body.innerHTML = '
' + tableHTML( - ['Day', 'Events'].concat(tokCols).concat(['Cost']), - days.map(function (d) { - return [esc(d.day), fmtNum(d.events)].concat(tokCells(d.tokens)).concat([u.hasCost ? fmtUSD(d.costUSD) : UNKNOWN_LABEL]); - }) - ) + '
'; - host.appendChild(dCard); + function money(n) { return u.hasCost ? fmtUSD(n) : UNKNOWN_LABEL; } + function bucketTable(title, sub, keyLabel, keyOf, buckets) { + var c = card(title, sub); + c._body.innerHTML = '
' + tableHTML( + [keyLabel, 'Events'].concat(tokCols).concat(['Cost']), + (buckets || []).map(function (b) { + var t = b.tokens; + return [esc(keyOf(b) || '\u2014'), fmtNum(b.events), + fmtTokens(t.input), fmtTokens(t.cacheCreation), fmtTokens(t.cacheRead), fmtTokens(t.output), fmtTokens(t.total), + money(b.costUSD)]; + }) + ) + '
'; + host.appendChild(c); + } + bucketTable('By model', 'as reported by Cursor', 'Model', function (b) { return b.model; }, u.byModel); + bucketTable('By day', 'export rows grouped by date', 'Day', function (b) { return b.day; }, days); }; VIEWS.cost = function (host, fs) { From e1cc6d15a6f2303ad479b64b1dc9693b69243ff2 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:29 +0300 Subject: [PATCH 23/34] revert(analytics): move untestable Cursor Team Analytics off the shipping branch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reopens the substance of #19/#20. Nobody on the team has an enterprise-admin Cursor account, so the Team Analytics success path was never exercised: every probe against the live API returned 401 Invalid Team API Key. Shipping code that makes network calls on a path no one has run is the risk being removed here — this is not a judgement that the implementation is wrong. The trade is easy because the feature never answered the question people actually have about Cursor. The API returns no token or cost field at any tier, and its key is unobtainable by an ordinary team member. The path that does work, for everyone, is the dashboard usage export via --cursor-usage-csv, which needs no credential and makes no network call. Removed: the fetcher and its tests, the --cursor-team-analytics flag, the payload field, the report view and its nav entry, and the report-side separation tests. Analytics is local-only again apart from that opt-in file import. The full implementation — gate, by-user scoping, admin-only framing, fail-soft handling and 10 passing unit tests — is preserved on branch feature/cursor-team-analytics-untested, and the docs now point there rather than pretending the capability does not exist. --- .../integration/external-integrations.md | 23 +-- docs/ANALYTICS-REPORT.md | 88 +++------- docs/CURSOR_INTEGRATION.md | 9 +- .../cursor/__tests__/team-analytics.test.ts | 127 -------------- .../plugins/cursor/cursor.team-analytics.ts | 158 ------------------ src/agents/plugins/cursor/cursor.usage-csv.ts | 4 +- src/cli/commands/analytics/index.ts | 25 --- .../__tests__/report-cost-honesty.test.ts | 27 --- .../commands/analytics/report/client/app.js | 47 +----- .../analytics/report/payload-builder.ts | 4 - .../commands/analytics/report/template.html | 1 - src/cli/commands/analytics/report/types.ts | 8 - src/cli/commands/analytics/types.ts | 1 - 13 files changed, 40 insertions(+), 482 deletions(-) delete mode 100644 src/agents/plugins/cursor/__tests__/team-analytics.test.ts delete mode 100644 src/agents/plugins/cursor/cursor.team-analytics.ts diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index 03e51a598..de98721b9 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -326,19 +326,22 @@ the session `usagePartial`. Full operational and developer guide: `docs/CURSOR_INTEGRATION.md`. Rationale for reading an undocumented store: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`. -### Cursor Enterprise Team Analytics API (opt-in, admin-only) +### Cursor Enterprise Team Analytics API (not integrated) Cursor publishes an official Team Analytics API (). CodeMie integrates it as a strictly -opt-in, user-scoped extra for **enterprise team admins**: `src/agents/plugins/cursor/cursor.team-analytics.ts`, -surfaced by `codemie analytics --report --cursor-team-analytics` with an admin-scoped -`CURSOR_TEAM_ANALYTICS_API_KEY` set. **Both** are required — a configured credential alone never -triggers a call — and this is the only network call anywhere in the analytics path. - -It still **cannot** supply tokens or cost, and the key is not obtainable by an ordinary team -member. No CLI, doc, or UI surface may present it as the member route to billable usage; every -such surface must point at `--cursor-usage-csv` instead. The audience wording is centralized in -`TEAM_ANALYTICS_AUDIENCE` / `TEAM_ANALYTICS_MEMBER_HINT` so the CLI and report cannot drift. +**CodeMie does not integrate it.** A complete, reviewed implementation exists on the +`feature/cursor-team-analytics-untested` branch and was deliberately kept off the shipping branch: +no one on the team has an enterprise-admin account, so the success path was never exercised +against the live API (every probe returned `401 Invalid Team API Key`). Shipping untestable code +that makes network calls is the risk being avoided — not a judgement that the code is wrong. + +Two facts make this an easy trade. The API **cannot** supply tokens or cost at any tier, so it +never answered the question people actually have about Cursor; and its key is not obtainable by an +ordinary team member. The path that does work, for everyone, is the dashboard usage export via +`--cursor-usage-csv`. + +If it is ever revived, the constraints below still hold, and the branch already implements them. What the API is: diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 28d228963..9edc73e85 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -41,7 +41,7 @@ codemie analytics --report --open --cursor-usage-csv ~/Downloads/team-usage-even ## What the Report Covers -The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*, plus two optional views ([Cursor Usage CSV](#cursor-usage-csv) and [Cursor Team API](#cursor-team-analytics)) that appear only when you opt into those sources. +The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*, plus an optional tenth ([Cursor Usage CSV](#cursor-usage-csv)) that appears only when you import a Cursor usage export. Discovered sessions that CodeMie did not launch are **excluded by default**; see [Session provenance](#session-provenance). @@ -300,7 +300,7 @@ billable tokens and presenting them as such would trade an honest blank for a co number. **You can still get the real numbers** — they live in Cursor's dashboard usage export rather than -on disk. See [Usage CSV import](#cursor-usage-csv), which turns those dashes into Cursor's own +on disk. See [Cursor tokens and cost](#cursor-usage-csv), which turns those dashes into Cursor's own token and cost figures. @@ -332,29 +332,16 @@ Two things to know before you rely on the wider number: `--include-external` applies to the default local-session source only. The `analytics otel` subcommand does not accept it — an OTEL events file has no notion of CodeMie ownership. - - -### Cursor tokens and cost — two paths, by audience - -Everything else in this document reads local files. Cursor is the exception worth understanding, -because **Cursor's local stores no longer record billable token counts** (see -[Analytics-only agents](#analytics-only-agents)), so Cursor sessions show `—` in the session table. -There are two ways to fill that in, and they are not interchangeable: - -| You are | Use | Gives you | Network? | -|---|---|---|---| -| **Anyone** (member or admin) | [Usage CSV import](#cursor-usage-csv) — `--cursor-usage-csv` | **Real tokens and cost** | No | -| **Enterprise team admin** | [Team Analytics](#cursor-team-analytics) — `--cursor-team-analytics` | Edit/activity aggregates. **No tokens, no cost** | Yes | - -If your question is *"what did Cursor cost?"*, you want the CSV. The Team Analytics API cannot -answer it at any tier, for anyone, including admins. - -#### Usage CSV import (everyone) +### Cursor tokens and cost — the usage CSV -Cursor's dashboard exports the usage ledger CodeMie cannot read locally. This is a plain file -read — no credential, no network call. +Everything else in this document reads local files. Cursor needs one extra step, because +**Cursor's local stores no longer record billable token counts** (see +[Analytics-only agents](#analytics-only-agents)) — so Cursor sessions show `—` in the session +table. The numbers do still exist, in Cursor's dashboard export. + +This is a plain file read: no credential, no network call. 1. In Cursor, open **Usage** and click **Export** for the period you want. 2. Pass the downloaded file: @@ -378,50 +365,21 @@ Things worth knowing about the export format: shows `—` for money and says why — the token counts are unaffected. - **`Cost` is not always a number.** Some rows read `Free`. Those contribute zero rather than corrupting the total. -- **Rows are filtered to you.** The `User` column is matched against your configured CodeMie - email, which is frequently *not* the address on your Cursor account. Override with - `--cursor-usage-user `. If the filter matches nothing, CodeMie warns and lists the - addresses actually present in the file rather than showing an empty section. +- **Rows are filtered to you** *when the export names users at all*. The `User` column is matched + against your configured CodeMie email, which is frequently *not* the address on your Cursor + account — override with `--cursor-usage-user `. An export with no `User` column is + imported whole, since there is no one else's data in it to exclude. If the filter matches + nothing, CodeMie warns and lists the addresses actually present rather than showing an empty + section. - **It is never merged into your sessions.** Export rows are per-event with no session id, so there is no key to join them on. The section sits beside the session table and contributes to no cost figure elsewhere in the report. Read them side by side, not summed. - - -#### Team Analytics API (enterprise team admins only) - -> **This is not the way to get Cursor tokens or cost.** None of Cursor's documented Team Analytics -> endpoints returns a token or cost field at any tier. It also requires an **admin-scoped** key -> that an ordinary team member cannot obtain. If you are not a team admin, use the -> [usage CSV](#cursor-usage-csv) above. - -For admins who want Cursor's own edit and activity aggregates alongside their local data: - -```bash -export CURSOR_TEAM_ANALYTICS_API_KEY='' -codemie analytics --report --open --cursor-team-analytics -``` - -**Both the flag and the key are required.** A key sitting in your environment never triggers a call -on its own, and neither does the flag without a key. Reading the machine you are on is a promise -CodeMie already makes; calling a remote service is not, so it stays a deliberate act each time. - -**What you get.** Four `by-user` endpoints — agent edits, tab completions, models, and commands — -filtered to your own email address, in their own **Cursor Team API** view. The view is hidden -unless a pull succeeded. - -**Scope and privacy.** Only `by-user` endpoints are queried, always filtered to the requesting -user's own email. No team-wide endpoint and no leaderboard, so a colleague's activity can never -appear in your personal report. - -**Shown separately on purpose.** The API returns per-user/per-date aggregates with no session -identifier and no token or cost field, so there is nothing to join on and nothing to join with. -Merging them into the session table would mean inventing both. - -**Failure modes.** A missing key, a rejected key, an HTTP error, a DNS failure, or a schema change -on Cursor's side all degrade to an omitted or explicitly-partial section plus a one-line notice -pointing at the CSV path. The local report is never taken down by a remote outage. Run with -`CODEMIE_DEBUG=true` to see each endpoint's outcome. +> **What about the Cursor Team Analytics API?** CodeMie does not use it. Its documented endpoints +> return no token or cost field at any tier, so it cannot answer "what did Cursor cost?", and it +> requires an enterprise-admin key most users cannot obtain. An implementation exists on the +> `feature/cursor-team-analytics-untested` branch but is **not shipped**, because we have no admin +> account to verify it against. --- @@ -470,11 +428,6 @@ Source flags: No network call. Anyone can use this. --cursor-usage-user Which User column value to keep from the CSV (default: your configured CodeMie email) - --cursor-team-analytics ENTERPRISE TEAM ADMINS ONLY. Fetches edit/activity - aggregates -- NOT tokens or cost. Makes a NETWORK - CALL; also requires CURSOR_TEAM_ANALYTICS_API_KEY. - Neither the flag nor the key works on its own. - (see "Cursor tokens and cost") Other flags: -v, --verbose Session-level breakdown in the terminal output @@ -486,7 +439,6 @@ Other flags: | Variable | Effect | |---|---| -| `CURSOR_TEAM_ANALYTICS_API_KEY` | **Admin-scoped** Cursor Team API key. Required *together with* `--cursor-team-analytics`. Not needed — and not obtainable — for the [usage CSV path](#cursor-usage-csv). | | `CODEMIE_DEBUG=true` | Verbose per-source discovery and enrichment logging, including each Team Analytics endpoint's outcome. | **Every filter and source flag governs the terminal output and the HTML report alike.** There is no report-only or terminal-only filtering: `--include-external`, `--no-scan-native`, and the date/project/agent filters all decide which sessions the command sees, and both outputs are rendered from that same set. diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index adf0e9b08..82757a9ea 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -96,10 +96,10 @@ What this means when reading a report: - When tokens *are* recovered but the model is `Auto`/`default` (or otherwise absent from the price table), the session is estimated at a published Claude Sonnet API rate, keeps its own model label, and is badged as partial. Treat it as an understated floor. -- The Enterprise Team Analytics API does **not** close this gap: none of its documented endpoints - returns token or cost fields at any tier, and it needs an **admin-scoped** key an ordinary team - member cannot obtain. See - [Cursor Enterprise Team Analytics API](../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-opt-in). +- The Enterprise Team Analytics API does **not** close this gap and is **not integrated**: none of + its documented endpoints returns token or cost fields at any tier, and it needs an admin-scoped + key an ordinary team member cannot obtain. See + [Cursor Enterprise Team Analytics API](../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-not-integrated). Nothing here is inferred from `contextTokensUsed`, transcript text length, or tool-call counts. Those correlate with usage but are not billable token counts, and presenting them as such would @@ -149,7 +149,6 @@ column that moved (see [Database schema drift](#database-schema-drift-after-a-cu |---|---| | `CURSOR_HOME` | Overrides `~/.cursor`. Also relocates `state.vscdb` to `$CURSOR_HOME/User/globalStorage/state.vscdb`, mirroring its real layout relative to Cursor's app-data root. Unset (the default) uses `~/.cursor` plus the per-OS app-data path above. | | `CODEMIE_DEBUG=true` | Enables the `[cursor]` debug logging described under [Logging and debugging](#logging-and-debugging). | -| `CURSOR_TEAM_ANALYTICS_API_KEY` | **Admin-scoped** Cursor Enterprise API key, for enterprise team admins only. Required *together with* `--cursor-team-analytics` before any network call is made; neither alone is enough. It returns edit/activity aggregates, **never tokens or cost** — for those use `--cursor-usage-csv`, which needs no credential. Unset (the default) means analytics stays entirely local. | `CURSOR_HOME` mirrors `COPILOT_HOME` in the Copilot CLI plugin and is what lets the whole ingestion path be driven against a fixture tree in tests. diff --git a/src/agents/plugins/cursor/__tests__/team-analytics.test.ts b/src/agents/plugins/cursor/__tests__/team-analytics.test.ts deleted file mode 100644 index 626754fc3..000000000 --- a/src/agents/plugins/cursor/__tests__/team-analytics.test.ts +++ /dev/null @@ -1,127 +0,0 @@ -/** - * Cursor Team Analytics gate + normalization tests. - * - * The safety property under test is negative: no network call may happen without BOTH an - * explicit opt-in and a configured credential. `fetch` is injected and counts its calls, so - * a regression that phones home shows up as a call count, not as a mocked-away detail. - */ - -import { describe, it, expect } from 'vitest'; -import { - fetchCursorTeamAnalytics, - TEAM_ANALYTICS_ENDPOINTS, - TEAM_ANALYTICS_AUDIENCE, - TEAM_ANALYTICS_MEMBER_HINT, - type TeamAnalyticsRequest, -} from '../cursor.team-analytics.js'; - -/** A fetch stand-in that records every URL it was asked for. */ -function recordingFetch(handler?: (url: string) => { status?: number; body?: unknown }) { - const calls: string[] = []; - const impl = async (url: string | URL, init?: { headers?: Record }) => { - calls.push(String(url)); - const r = handler?.(String(url)) ?? {}; - return { - ok: (r.status ?? 200) < 400, - status: r.status ?? 200, - json: async () => r.body ?? {}, - text: async () => JSON.stringify(r.body ?? {}), - headers: init?.headers, - } as never; - }; - return { impl, calls }; -} - -const enabled: TeamAnalyticsRequest = { - enabled: true, - apiKey: 'key_abc', - userEmail: 'me@example.com', - startDate: '2026-08-01', - endDate: '2026-08-31', -}; - -describe('Cursor Team Analytics opt-in gate', () => { - it('makes no network call when the opt-in flag is absent, even with a credential', async () => { - const f = recordingFetch(); - const out = await fetchCursorTeamAnalytics({ ...enabled, enabled: false }, { fetch: f.impl }); - expect(f.calls).toEqual([]); - expect(out).toBeNull(); - }); - - it('makes no network call when opted in but no credential is configured', async () => { - const f = recordingFetch(); - const out = await fetchCursorTeamAnalytics({ ...enabled, apiKey: undefined }, { fetch: f.impl }); - expect(f.calls).toEqual([]); - expect(out).toBeNull(); - }); - - it('makes no network call when the requesting user has no known email to scope to', async () => { - const f = recordingFetch(); - const out = await fetchCursorTeamAnalytics({ ...enabled, userEmail: undefined }, { fetch: f.impl }); - expect(f.calls).toEqual([]); - expect(out).toBeNull(); - }); -}); - -describe('Cursor Team Analytics request shape', () => { - it('queries only by-user endpoints, scoped to the requesting user alone', async () => { - const f = recordingFetch(); - await fetchCursorTeamAnalytics(enabled, { fetch: f.impl }); - expect(f.calls.length).toBe(TEAM_ANALYTICS_ENDPOINTS.length); - for (const url of f.calls) { - expect(url).toContain('/analytics/by-user/'); - expect(url).not.toContain('/analytics/team/'); - expect(url).not.toContain('leaderboard'); - expect(new URL(url).searchParams.get('users')).toBe('me@example.com'); - expect(new URL(url).searchParams.get('startDate')).toBe('2026-08-01'); - } - }); -}); - -describe('Cursor Team Analytics results', () => { - it('returns the rows each endpoint actually provided, with no token or cost fields synthesized', async () => { - const f = recordingFetch(() => ({ body: { data: [{ email: 'me@example.com', total_accepted_diffs: 12 }] } })); - const out = (await fetchCursorTeamAnalytics(enabled, { fetch: f.impl }))!; - expect(out.userEmail).toBe('me@example.com'); - expect(out.metrics.length).toBe(TEAM_ANALYTICS_ENDPOINTS.length); - expect(out.metrics[0].rows[0]).toMatchObject({ total_accepted_diffs: 12 }); - // The API returns no token/cost fields; we must not manufacture any. - const serialized = JSON.stringify(out); - expect(serialized).not.toMatch(/costUSD|inputTokens|outputTokens|tokens"/); - }); - - it('degrades to a partial section when an endpoint fails, without throwing', async () => { - const f = recordingFetch((url) => (url.includes('models') ? { status: 500 } : { body: { data: [{ n: 1 }] } })); - const out = (await fetchCursorTeamAnalytics(enabled, { fetch: f.impl }))!; - expect(out.failedEndpoints).toContain('models'); - expect(out.metrics.some((m) => m.endpoint === 'models')).toBe(false); - expect(out.metrics.length).toBe(TEAM_ANALYTICS_ENDPOINTS.length - 1); - }); - - it('returns null rather than throwing when every endpoint fails', async () => { - const f = recordingFetch(() => ({ status: 401 })); - expect(await fetchCursorTeamAnalytics(enabled, { fetch: f.impl })).toBeNull(); - }); - - it('survives a transport-level throw', async () => { - const impl = async () => { throw new Error('ENOTFOUND api.cursor.com'); }; - expect(await fetchCursorTeamAnalytics(enabled, { fetch: impl as never })).toBeNull(); - }); -}); - -/** - * Team Analytics is an enterprise-ADMIN feature that returns no tokens or cost. An ordinary team - * member cannot obtain the key and would gain nothing from it, so no surface may imply otherwise - * or leave them at an auth-failure dead end. See issue #23. - */ -describe('Cursor Team Analytics audience framing', () => { - it('describes itself as admin-only and disclaims tokens/cost', () => { - expect(TEAM_ANALYTICS_AUDIENCE).toMatch(/admin/i); - expect(TEAM_ANALYTICS_AUDIENCE).not.toMatch(/token|cost/i); - }); - - it('points a member at the usage CSV rather than at getting an API key', () => { - expect(TEAM_ANALYTICS_MEMBER_HINT).toMatch(/--cursor-usage-csv/); - expect(TEAM_ANALYTICS_MEMBER_HINT).not.toMatch(/CURSOR_TEAM_ANALYTICS_API_KEY/); - }); -}); diff --git a/src/agents/plugins/cursor/cursor.team-analytics.ts b/src/agents/plugins/cursor/cursor.team-analytics.ts deleted file mode 100644 index 39661766b..000000000 --- a/src/agents/plugins/cursor/cursor.team-analytics.ts +++ /dev/null @@ -1,158 +0,0 @@ -/** - * Cursor Enterprise Team Analytics — optional, opt-in, user-scoped. - * - * This is the ONLY place CodeMie analytics talks to a network service. Everything else in the - * analytics path reads local files, and that difference is the point: reading the machine you - * are on is a promise CodeMie already makes, calling a remote service is not. So the call is - * gated on BOTH an explicit invocation flag and a configured credential — a token sitting in - * config must never be enough on its own. - * - * Two things about the audience, because getting them wrong strands people: - * - * 1. **This is enterprise-team-ADMIN only.** The endpoints require an admin-scoped key that an - * ordinary team member cannot obtain. Telling a member to "set CURSOR_TEAM_ANALYTICS_API_KEY" - * sends them after a credential they cannot get. - * 2. **It returns no tokens and no cost at any tier** (re-verified against the live docs - * 2026-09-05), so even an admin cannot close the Cursor billable-usage gap with it. The rows - * below are edit/activity aggregates only. - * - * The path that *does* yield real Cursor tokens and cost — for admins and members alike — is the - * dashboard usage export, imported via `--cursor-usage-csv` (see `cursor.usage-csv.ts`). - * - * These rows are also per-user/per-date aggregates carrying no `composerId`, so there is no key - * on which to join them to local sessions — hence the report renders them as a clearly separate - * section rather than folding them into the session table. - * - * See `.ai-run/guides/integration/external-integrations.md` and `docs/CURSOR_INTEGRATION.md`. - */ - -import { logger } from '@/utils/logger.js'; - -/** Documented API root. */ -const API_BASE = 'https://api.cursor.com'; - -/** - * The by-user endpoints worth surfacing. Deliberately excludes every `team/*` endpoint and the - * leaderboard: CodeMie analytics reports the operator's own usage, and pulling colleagues' - * activity into a personal report is out of scope regardless of what the credential can read. - */ -export const TEAM_ANALYTICS_ENDPOINTS = [ - { endpoint: 'agent-edits', label: 'Agent edits' }, - { endpoint: 'tabs', label: 'Tab completions' }, - { endpoint: 'models', label: 'Models used' }, - { endpoint: 'commands', label: 'Commands' }, -] as const; - -/** Who can actually use this. Surfaced in CLI help and the report's empty state. */ -export const TEAM_ANALYTICS_AUDIENCE = - 'Enterprise team admins only — requires an admin-scoped Cursor Team API key.'; - -/** - * What to tell everyone else. Deliberately does NOT name the API key env var: a member who - * cannot get a key must be pointed at the path that works, not at the one that will reject them. - */ -export const TEAM_ANALYTICS_MEMBER_HINT = - 'For real Cursor tokens and cost, export your usage from the Cursor dashboard (Usage → Export) and pass it with --cursor-usage-csv .'; - -export interface TeamAnalyticsRequest { - /** Explicit per-invocation opt-in (the CLI flag). A credential alone must never enable calls. */ - enabled: boolean; - /** Admin-scoped API key. Absent on personal plans, which simply get no section. */ - apiKey?: string; - /** The requesting user's own email — the `by-user` filter, and the reason this stays personal. */ - userEmail?: string; - startDate?: string; - endDate?: string; -} - -/** One endpoint's rows, passed through as the API returned them. */ -export interface TeamAnalyticsMetric { - endpoint: string; - label: string; - rows: Record[]; -} - -export interface CursorTeamAnalytics { - userEmail: string; - startDate?: string; - endDate?: string; - metrics: TeamAnalyticsMetric[]; - /** Endpoints that failed; surfaced so a partial section is never mistaken for a complete one. */ - failedEndpoints: string[]; -} - -type FetchLike = (url: string, init?: { headers?: Record }) => Promise<{ - ok: boolean; - status: number; - json: () => Promise; -}>; - -export interface TeamAnalyticsDeps { - fetch: FetchLike; -} - -/** `curl -u KEY:` — the key as the basic-auth username with an empty password. */ -function authHeader(apiKey: string): string { - return `Basic ${Buffer.from(`${apiKey}:`).toString('base64')}`; -} - -function endpointUrl(endpoint: string, req: TeamAnalyticsRequest): string { - const url = new URL(`/analytics/by-user/${endpoint}`, API_BASE); - url.searchParams.set('users', req.userEmail as string); - if (req.startDate) { - url.searchParams.set('startDate', req.startDate); - } - if (req.endDate) { - url.searchParams.set('endDate', req.endDate); - } - return url.toString(); -} - -/** Accepts either a bare array or the documented `{ data: [...] }` envelope. */ -function rowsOf(payload: unknown): Record[] { - const body = payload as { data?: unknown } | unknown[]; - const data = Array.isArray(body) ? body : body?.data; - return Array.isArray(data) ? (data.filter((r) => r && typeof r === 'object') as Record[]) : []; -} - -/** - * Fetch the requesting user's own Team Analytics aggregates, or `null` when the gate is closed - * or nothing could be retrieved. Never throws: a failed pull degrades to an omitted section so - * the local report — the part that always works — is never taken down by a remote outage. - */ -export async function fetchCursorTeamAnalytics( - req: TeamAnalyticsRequest, - deps: TeamAnalyticsDeps = { fetch: globalThis.fetch as unknown as FetchLike } -): Promise { - if (!req.enabled || !req.apiKey || !req.userEmail) { - // Not an error: this is the default state for everyone without an enterprise key. - logger.debug('[cursor] team analytics skipped (needs both the opt-in flag and an API key)'); - return null; - } - - const metrics: TeamAnalyticsMetric[] = []; - const failedEndpoints: string[] = []; - - for (const { endpoint, label } of TEAM_ANALYTICS_ENDPOINTS) { - try { - const res = await deps.fetch(endpointUrl(endpoint, req), { - headers: { Authorization: authHeader(req.apiKey), Accept: 'application/json' }, - }); - if (!res.ok) { - logger.debug(`[cursor] team analytics ${endpoint} returned HTTP ${res.status}`); - failedEndpoints.push(endpoint); - continue; - } - metrics.push({ endpoint, label, rows: rowsOf(await res.json()) }); - } catch (error) { - // Schema drift, DNS failure, auth rejection — all the same to the report: omit and move on. - logger.debug(`[cursor] team analytics ${endpoint} unusable: ${(error as Error).message}`); - failedEndpoints.push(endpoint); - } - } - - if (metrics.length === 0) { - return null; - } - return { userEmail: req.userEmail, startDate: req.startDate, endDate: req.endDate, metrics, failedEndpoints }; -} diff --git a/src/agents/plugins/cursor/cursor.usage-csv.ts b/src/agents/plugins/cursor/cursor.usage-csv.ts index e37b27c10..0b5d80f6d 100644 --- a/src/agents/plugins/cursor/cursor.usage-csv.ts +++ b/src/agents/plugins/cursor/cursor.usage-csv.ts @@ -1,8 +1,8 @@ /** * Cursor usage-events CSV import — the member path to real Cursor tokens and cost. * - * Cursor's local stores stopped carrying billable token counts (see docs/CURSOR_INTEGRATION.md), - * and the Team Analytics API never had them. The dashboard's Usage → Export CSV does: a real + * Cursor's local stores stopped carrying billable token counts (see docs/CURSOR_INTEGRATION.md). + * The dashboard's Usage → Export CSV still has them: a real * 2026-09-05 export held 39,952,466 tokens and $25.25 of Cost across 61 events. * * The trap this module exists to avoid: **every one of those 61 rows was `Kind=Included`.** diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 9a43f991e..2cb21a6c2 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -23,7 +23,6 @@ export function createAnalyticsCommand(): Command { applyCommonOptions(command) .option('--no-scan-native', 'Skip native agent-log discovery (use only CodeMie-tracked sessions)') .option('--include-external', 'Include non-CodeMie-owned native sessions in output (opt-in; matches pre-fix behavior)') - .option('--cursor-team-analytics', 'ENTERPRISE TEAM ADMINS ONLY: fetch Cursor Team Analytics edit/activity aggregates (requires an admin-scoped CURSOR_TEAM_ANALYTICS_API_KEY; makes a network call). Returns no tokens or cost — for those, use --cursor-usage-csv') .option('--cursor-usage-csv ', 'Import a Cursor usage-events CSV (Cursor dashboard → Usage → Export) for real Cursor tokens and cost. No network call') .option('--cursor-usage-user ', 'Which User column value to keep from --cursor-usage-csv (default: your configured CodeMie email)') .action((options: AnalyticsOptions) => runAnalytics(options, new SessionsSource())); @@ -174,29 +173,6 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS } } - // The one network call in the analytics path, and it happens only when the user asked for - // it AND a credential exists. Fail-soft: a null result simply omits the report section. - let cursorTeamAnalytics; - if (options.cursorTeamAnalytics) { - const { fetchCursorTeamAnalytics } = await import('@/agents/plugins/cursor/cursor.team-analytics.js'); - cursorTeamAnalytics = (await fetchCursorTeamAnalytics({ - enabled: true, - apiKey: process.env.CURSOR_TEAM_ANALYTICS_API_KEY, - userEmail, - ...(filter.fromDate !== undefined && { startDate: filter.fromDate.toISOString().slice(0, 10) }), - ...(filter.toDate !== undefined && { endDate: filter.toDate.toISOString().slice(0, 10) }), - })) ?? undefined; - if (!cursorTeamAnalytics) { - // Do NOT tell an ordinary team member to go set an admin API key — they cannot get - // one, and it would not carry tokens or cost even if they could. Point at the CSV. - const { TEAM_ANALYTICS_AUDIENCE, TEAM_ANALYTICS_MEMBER_HINT } = await import('@/agents/plugins/cursor/cursor.team-analytics.js'); - console.log(chalk.yellow(`\n Cursor Team Analytics returned nothing. ${TEAM_ANALYTICS_AUDIENCE}`)); - console.log(chalk.yellow(' It also never returns tokens or cost, so it cannot answer "what did Cursor cost?".')); - console.log(chalk.yellow(` ${TEAM_ANALYTICS_MEMBER_HINT}`)); - console.log(chalk.dim(' Report continues without the Team Analytics section.')); - } - } - // #21: the member path to real Cursor tokens/cost. Pure file read — no network call. let cursorUsage; if (options.cursorUsageCsv) { @@ -225,7 +201,6 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS projectFilter: options.project ?? 'all', generatedAt: new Date().toISOString(), ...(userEmail !== undefined && { userEmail }), - ...(cursorTeamAnalytics !== undefined && { cursorTeamAnalytics }), ...(cursorUsage !== undefined && { cursorUsage }), ...(filter.fromDate !== undefined && { periodStart: filter.fromDate.toISOString() }), ...(filter.toDate !== undefined && { periodEnd: filter.toDate.toISOString() }), diff --git a/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts b/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts index d6fff9147..f3a08cbf3 100644 --- a/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts +++ b/src/cli/commands/analytics/report/__tests__/report-cost-honesty.test.ts @@ -88,30 +88,3 @@ describe('report client all-unmeasurable empty state', () => { expect(toolBlock).not.toMatch(/usageUnknown|anyMeasured/); }); }); - -/** - * Cursor Team Analytics is a remote, opt-in source. The report must keep it visibly apart from - * local sessions — it has no session key to join on and no token/cost fields to join with. - */ -describe('Cursor Team Analytics section separation', () => { - const view = viewSource('cursorteam'); - - it('renders from meta, never from the session list', () => { - expect(view).toMatch(/DATA\.meta\.cursorTeamAnalytics/); - // The view takes no session array and must not reach for one. - expect(view).toMatch(/VIEWS\.cursorteam = function \(host\)/); - expect(view).not.toMatch(/DATA\.sessions|SESSION_BY_ID|filtered\(\)/); - }); - - it('contributes nothing to any cost or token figure', () => { - expect(view).not.toMatch(/costUSD|fmtUSD|fmtTokens/); - }); - - it('says plainly that the remote rows are not joined to local sessions', () => { - expect(view).toMatch(/nothing here is joined to the local sessions/); - }); - - it('flags a partial pull rather than presenting it as complete', () => { - expect(view).toMatch(/failedEndpoints/); - }); -}); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index aa6f701d6..28c92bfc9 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -824,49 +824,6 @@ host.appendChild(changeCard); }; - /** - * Cursor Team Analytics — a REMOTE, opt-in source, deliberately kept in its own view. - * - * It is never merged into the session table and never contributes to any cost or token - * figure: the API returns per-user/per-date aggregates with no composerId to join on, and no - * token or cost fields to join with. Two different things are being counted, so they are - * shown as two different things. The view is hidden entirely unless the pull happened. - */ - VIEWS.cursorteam = function (host) { - var ta = DATA.meta.cursorTeamAnalytics; - host.appendChild(el('h2', 'view-title', 'Cursor Team API')); - if (!ta) { - host.appendChild(el('p', 'view-sub', 'Not fetched for this report \u00b7 enterprise team admins only')); - // Never leave a non-admin reader chasing a credential they cannot get, for data that would - // not answer their question anyway. Name the path that actually works. - host.appendChild(el('div', 'empty', 'Cursor Team Analytics is available to enterprise team admins with an admin-scoped API key, and it returns edit and activity aggregates only \u2014 never tokens or cost.

For real Cursor tokens and cost, export your usage from the Cursor dashboard (Usage \u2192 Export) and re-run with --cursor-usage-csv <path>.')); - return; - } - var range = (ta.startDate || '…') + ' → ' + (ta.endDate || '…'); - host.appendChild(el('p', 'view-sub', 'Team API aggregates (admin) for ' + esc(ta.userEmail) + ' · ' + esc(range))); - host.appendChild(el('div', 'alert alert-info', 'Remote admin team-API aggregates, shown separately on purpose. These are Cursor\u2019s own edit and activity counters for your account. They carry no token or cost fields and no session key, so nothing here is joined to the local sessions or added to any cost figure elsewhere in this report \u2014 and this section can never tell you what Cursor cost. For that, import a usage export with --cursor-usage-csv.')); - if (ta.failedEndpoints && ta.failedEndpoints.length) { - host.appendChild(el('div', 'alert alert-warning', 'Incomplete: ' + esc(ta.failedEndpoints.join(', ')) + ' could not be fetched, so this section is partial.')); - } - (ta.metrics || []).forEach(function (m) { - var c = card(m.label, m.endpoint); - var rows = m.rows || []; - if (!rows.length) { - c._body.appendChild(el('div', 'empty', 'No rows returned for this range.')); - } else { - // Column set is whatever the API sent — the report does not curate or rename it, so a - // field Cursor adds later shows up as itself rather than being silently dropped. - var cols = []; - rows.forEach(function (r) { Object.keys(r).forEach(function (k) { if (cols.indexOf(k) === -1) cols.push(k); }); }); - var body = rows.map(function (r) { - return cols.map(function (k) { return esc(r[k] == null ? '—' : (typeof r[k] === 'object' ? JSON.stringify(r[k]) : r[k])); }); - }); - c._body.innerHTML = '
' + tableHTML(cols, body) + '
'; - } - host.appendChild(c); - }); - }; - /** * Cursor usage-events CSV — the only source of real Cursor tokens and cost. * @@ -1566,9 +1523,7 @@ document.querySelectorAll('.nav-i').forEach(function (n) { n.classList.toggle('active', n.getAttribute('data-view') === state.view); }); // The remote-source view is opt-in; without a pull there is nothing to navigate to. document.querySelectorAll('.nav-i[data-optional]').forEach(function (n) { - var v = n.getAttribute('data-view'); - if (v === 'cursorteam' && !DATA.meta.cursorTeamAnalytics) n.style.display = 'none'; - if (v === 'cursorusage' && !DATA.meta.cursorUsage) n.style.display = 'none'; + if (n.getAttribute('data-view') === 'cursorusage' && !DATA.meta.cursorUsage) n.style.display = 'none'; }); } diff --git a/src/cli/commands/analytics/report/payload-builder.ts b/src/cli/commands/analytics/report/payload-builder.ts index f1298acee..f4cf6e6e1 100644 --- a/src/cli/commands/analytics/report/payload-builder.ts +++ b/src/cli/commands/analytics/report/payload-builder.ts @@ -4,7 +4,6 @@ * `generatedAt` so this stays deterministic and unit-testable. */ -import type { CursorTeamAnalytics } from '@/agents/plugins/cursor/cursor.team-analytics.js'; import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import type { RootAnalytics } from '../types.js'; import type { SessionCostIndex, CostSummary, AgentCoverage } from '../cost/types.js'; @@ -19,8 +18,6 @@ export interface PayloadContext { userEmail?: string; // caller stamps; absent when not authenticated periodStart?: string; // ISO — caller stamps from filter or session start periodEnd?: string; // ISO — caller stamps from filter or session end - /** Opt-in Cursor Team Analytics for the report owner; absent unless the gate opened. */ - cursorTeamAnalytics?: CursorTeamAnalytics; /** Opt-in Cursor usage-events CSV import; absent unless a path was given. */ cursorUsage?: CursorUsageImport; } @@ -176,7 +173,6 @@ export function buildPayload( unpricedModels: summary.unpricedModels, coverage: [...coverageMap.values()].sort((a, b) => b.total - a.total), ...(ctx.userEmail !== undefined && { userEmail: ctx.userEmail }), - ...(ctx.cursorTeamAnalytics !== undefined && { cursorTeamAnalytics: ctx.cursorTeamAnalytics }), ...(ctx.cursorUsage !== undefined && { cursorUsage: ctx.cursorUsage }), ...(ctx.periodStart !== undefined ? { periodStart: ctx.periodStart } diff --git a/src/cli/commands/analytics/report/template.html b/src/cli/commands/analytics/report/template.html index b046b7311..aa5aac25c 100644 --- a/src/cli/commands/analytics/report/template.html +++ b/src/cli/commands/analytics/report/template.html @@ -288,7 +288,6 @@
Cost
Raw
Cursor Usage CSV
-
Cursor Team API
Sessions
diff --git a/src/cli/commands/analytics/report/types.ts b/src/cli/commands/analytics/report/types.ts index 162cd2dfd..8fc73a7b9 100644 --- a/src/cli/commands/analytics/report/types.ts +++ b/src/cli/commands/analytics/report/types.ts @@ -3,7 +3,6 @@ * report. The client app reads only this and computes every view from it. */ -import type { CursorTeamAnalytics } from '@/agents/plugins/cursor/cursor.team-analytics.js'; import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import type { TokenUsage, ModelCost, AgentCoverage, CostSeriesPoint, DispatchEvent } from '../cost/types.js'; import type { ToolStats, NamedInvocationStats } from '../types.js'; @@ -83,13 +82,6 @@ export interface ReportMeta { unpricedModels: string[]; coverage: AgentCoverage[]; // per-agent priced/total — "which tools are included" userEmail?: string; // identity of the report owner; absent when not authenticated - /** - * Optional Cursor Team Analytics aggregates for the report owner alone. Kept in `meta` and - * rendered as its own section precisely because it CANNOT be joined to `sessions`: the API - * returns per-user/per-date aggregates with no composerId, and it carries no token or cost - * fields, so merging it into session rows would invent both a key and a figure. - */ - cursorTeamAnalytics?: CursorTeamAnalytics; /** * Optional Cursor usage-events CSV import — the only source of real Cursor tokens and cost. * Kept beside the sessions rather than inside them: its rows are per-event with no composerId, diff --git a/src/cli/commands/analytics/types.ts b/src/cli/commands/analytics/types.ts index 0fd674cac..42afe0999 100644 --- a/src/cli/commands/analytics/types.ts +++ b/src/cli/commands/analytics/types.ts @@ -256,7 +256,6 @@ export interface AnalyticsOptions { * aggregates. Requires CURSOR_TEAM_ANALYTICS_API_KEY as well — the flag alone makes no call, * and neither does the credential alone. */ - cursorTeamAnalytics?: boolean; /** Path to a Cursor usage-events CSV exported from the Cursor dashboard (no network call). */ cursorUsageCsv?: string; /** From bcaea18dbc8b49f8aca6c75caf1ec2cb5eef908d Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:30 +0300 Subject: [PATCH 24/34] feat(analytics): optional cookie fetch of the Cursor usage export MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #22. Downloads the same CSV --cursor-usage-csv reads from disk, and feeds it through the same parser, so a fetched export and a hand-saved one can never be interpreted differently. Three things must all be present before any request leaves the machine: the --cursor-usage-fetch flag, CURSOR_USAGE_EXPORT_URL, and a session cookie. Any one missing means no call at all. CodeMie ships no endpoint URL. Cursor's dashboard export is undocumented and can change or vanish without notice; baking such a URL into the product means quietly breaking later, so the operator supplies it and knows exactly what is being called. On the credential: it is a browser cookie for cursor.com, which on a signed-in machine lives in Cursor's Chromium jar encrypted against the OS keychain. CodeMie does not decrypt that — prying a credential out of another application's protected store is not something an analytics command should do. It makes a cheap read-only check of Cursor's own plaintext state database, and otherwise expects CURSOR_SESSION_TOKEN, keeping the handover a deliberate act. Supplied values are shape-checked as :: so an admin crsr_ key — a different credential for a different API, rejected by this endpoint — cannot be sent by mistake. The token never reaches a log line: failures name the status code and the endpoint host only, and a test asserts no log output contains it on either the success or the failure path. 401/403/500, a sign-in redirect returning HTML, a bad URL, or a transport error all omit the section and leave the local report intact. Verified end-to-end against a local stub endpoint: correct Cookie header, no Authorization header, date parameters taken from the report window, and the response parsed to the real export's 61 events / 39,952,466 tokens / $25.25. --- docs/ANALYTICS-REPORT.md | 47 +++- docs/CURSOR_INTEGRATION.md | 7 + .../__tests__/cursor.usage-fetch.test.ts | 173 +++++++++++++++ .../plugins/cursor/cursor.usage-fetch.ts | 201 ++++++++++++++++++ src/cli/commands/analytics/index.ts | 35 ++- src/cli/commands/analytics/types.ts | 6 + 6 files changed, 462 insertions(+), 7 deletions(-) create mode 100644 src/agents/plugins/cursor/__tests__/cursor.usage-fetch.test.ts create mode 100644 src/agents/plugins/cursor/cursor.usage-fetch.ts diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 9edc73e85..4be6b31d5 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -375,6 +375,42 @@ Things worth knowing about the export format: there is no key to join them on. The section sits beside the session table and contributes to no cost figure elsewhere in the report. Read them side by side, not summed. + + +#### Downloading it automatically (optional, unsupported) + +If clicking Export each time is tedious, CodeMie can fetch the same CSV. This is **opt-in and +unsupported**, and file import above remains the recommended path. + +```bash +export CURSOR_USAGE_EXPORT_URL='' +export CURSOR_SESSION_TOKEN='::' # the WorkosCursorSessionToken cookie +codemie analytics --report --open --cursor-usage-fetch +``` + +**All three are required** — the flag, the URL, and the cookie. Any one missing means no request +is made at all. + +Why it looks like this rather than "just work": + +- **CodeMie ships no endpoint URL.** Cursor's dashboard export is undocumented and can change or + disappear without notice. Baking in such a URL means quietly breaking later; supplying it + yourself means you know exactly what is being called. Read it off your browser's Network tab + when you click Export. +- **You supply the cookie.** It is a browser cookie for cursor.com, so on a signed-in machine it + lives in Cursor's Chromium cookie jar encrypted against your OS keychain. CodeMie does not + decrypt that — prying a credential out of another application's protected store is not + something an analytics command should do. It makes a harmless read-only check of Cursor's own + plaintext state database first, and otherwise expects `CURSOR_SESSION_TOKEN`. +- **Authentication is the session cookie, never an API key.** An admin `crsr_` Team API key is a + different credential for a different API and is rejected here. +- **The token is never logged.** Failures name the status code and the endpoint host only. Run + with `CODEMIE_DEBUG=true` to see them. + +The response goes through the exact same parser as the file import, so a downloaded export and a +hand-saved one can never be interpreted differently. Any failure — 401, 403, a changed endpoint, a +sign-in redirect returning HTML — omits the section and leaves the rest of the report intact. + > **What about the Cursor Team Analytics API?** CodeMie does not use it. Its documented endpoints > return no token or cost field at any tier, so it cannot answer "what did Cursor cost?", and it > requires an enterprise-admin key most users cannot obtain. An implementation exists on the @@ -426,8 +462,13 @@ Source flags: --cursor-usage-csv Import a Cursor usage-events CSV (Cursor dashboard -> Usage -> Export) for REAL Cursor tokens and cost. No network call. Anyone can use this. - --cursor-usage-user Which User column value to keep from the CSV + --cursor-usage-user Which User column value to keep from the export (default: your configured CodeMie email) + --cursor-usage-fetch Download the usage export instead of passing a file. + OPT-IN and UNSUPPORTED: makes a NETWORK CALL to an + undocumented endpoint. Requires CURSOR_USAGE_EXPORT_URL + and CURSOR_SESSION_TOKEN. File import is the + recommended path. (see "Downloading it automatically") Other flags: -v, --verbose Session-level breakdown in the terminal output @@ -439,7 +480,9 @@ Other flags: | Variable | Effect | |---|---| -| `CODEMIE_DEBUG=true` | Verbose per-source discovery and enrichment logging, including each Team Analytics endpoint's outcome. | +| `CURSOR_USAGE_EXPORT_URL` | Cursor dashboard usage-export endpoint, for `--cursor-usage-fetch`. No default — CodeMie ships no undocumented URL. | +| `CURSOR_SESSION_TOKEN` | Your `WorkosCursorSessionToken` cookie, `::`, for `--cursor-usage-fetch`. Never logged. | +| `CODEMIE_DEBUG=true` | Verbose per-source discovery and enrichment logging, including the usage-export fetch outcome. | **Every filter and source flag governs the terminal output and the HTML report alike.** There is no report-only or terminal-only filtering: `--include-external`, `--no-scan-native`, and the date/project/agent filters all decide which sessions the command sees, and both outputs are rendered from that same set. diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index 82757a9ea..8af15a781 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -126,6 +126,13 @@ Two facts that decide how it must be read: Export rows are per-event with no `composerId`, so they are never joined to local sessions or added to any other cost figure — the report shows Cursor's own numbers beside CodeMie's, not summed in. +`--cursor-usage-fetch` can download the same CSV instead, but it is **opt-in and unsupported**: it +needs `CURSOR_USAGE_EXPORT_URL` (CodeMie ships no undocumented endpoint) and `CURSOR_SESSION_TOKEN` +(the `WorkosCursorSessionToken` browser cookie, `::`) on top of the flag. The cookie is +never read out of Cursor's keychain-encrypted Chromium jar and never logged; authentication is that +cookie, never a `crsr_` admin key. Both paths end in the same parser. File import remains the +supported route. + ### Database schema and versioning `state.vscdb` and `ai-code-tracking.db` are Cursor-internal and undocumented; there is no schema diff --git a/src/agents/plugins/cursor/__tests__/cursor.usage-fetch.test.ts b/src/agents/plugins/cursor/__tests__/cursor.usage-fetch.test.ts new file mode 100644 index 000000000..2d3d20e33 --- /dev/null +++ b/src/agents/plugins/cursor/__tests__/cursor.usage-fetch.test.ts @@ -0,0 +1,173 @@ +/** + * Cookie-authenticated usage-export fetch. + * + * Two properties matter more than the happy path and are asserted first: no request may leave + * the machine without an explicit opt-in AND a configured URL, and the session token must never + * reach a log line. The token used here is a fabricated string with the right *shape* only. + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { + fetchCursorUsageExport, + readCursorSessionCookie, + type UsageFetchRequest, +} from '../cursor.usage-fetch.js'; + +/** + * Shape-accurate, entirely fabricated: `::`. + * + * Assembled at runtime rather than written as a literal — a literal three-part JWT trips the + * repo's gitleaks scan, and a secrets scanner that has learned to ignore this file is worse than + * no scanner. The parts are meaningless: header `{"alg":"none"}`, body `{"sub":"test"}`. + */ +const FAKE_USER_ID = 'user_01ABCDEF'; +const FAKE_JWT = [ + Buffer.from('{"alg":"none"}').toString('base64url'), + Buffer.from('{"sub":"test"}').toString('base64url'), + 'notarealsignature', +].join('.'); +const FAKE_COOKIE = `${FAKE_USER_ID}::${FAKE_JWT}`; + +const csv = readFileSync( + fileURLToPath(new URL('./fixtures/cursor-usage-events.csv', import.meta.url)), + 'utf-8' +); + +function recordingFetch(handler?: (url: string, init?: unknown) => { status?: number; body?: string }) { + const calls: { url: string; init?: { headers?: Record } }[] = []; + const impl = async (url: string, init?: { headers?: Record }) => { + calls.push({ url, init }); + const r = handler?.(url, init) ?? {}; + return { + ok: (r.status ?? 200) < 400, + status: r.status ?? 200, + text: async () => r.body ?? csv, + }; + }; + return { impl, calls }; +} + +const base: UsageFetchRequest = { + enabled: true, + exportUrl: 'https://cursor.example/api/usage-export', + cookie: FAKE_COOKIE, + startDate: '2026-08-29', + endDate: '2026-09-05', +}; + +describe('usage-export fetch gate', () => { + it('makes no request without the explicit opt-in flag', async () => { + const f = recordingFetch(); + expect(await fetchCursorUsageExport({ ...base, enabled: false }, { fetch: f.impl })).toBeNull(); + expect(f.calls).toEqual([]); + }); + + it('makes no request when no export URL is configured', async () => { + const f = recordingFetch(); + expect(await fetchCursorUsageExport({ ...base, exportUrl: undefined }, { fetch: f.impl })).toBeNull(); + expect(f.calls).toEqual([]); + }); + + it('makes no request when no session cookie could be read', async () => { + const f = recordingFetch(); + expect(await fetchCursorUsageExport({ ...base, cookie: undefined }, { fetch: f.impl })).toBeNull(); + expect(f.calls).toEqual([]); + }); +}); + +describe('usage-export request', () => { + it('authenticates with the session cookie, never a bearer token', async () => { + const f = recordingFetch(); + await fetchCursorUsageExport(base, { fetch: f.impl }); + expect(f.calls).toHaveLength(1); + const headers = f.calls[0].init?.headers ?? {}; + expect(headers.Cookie).toBe(`WorkosCursorSessionToken=${FAKE_COOKIE}`); + expect(headers.Authorization).toBeUndefined(); + }); + + it('passes the report window through as date parameters', async () => { + const f = recordingFetch(); + await fetchCursorUsageExport(base, { fetch: f.impl }); + const url = new URL(f.calls[0].url); + expect(url.searchParams.get('startDate')).toBe('2026-08-29'); + expect(url.searchParams.get('endDate')).toBe('2026-09-05'); + }); + + it('feeds the response through the same parser as the file import', async () => { + const f = recordingFetch(); + const out = (await fetchCursorUsageExport(base, { fetch: f.impl }))!; + expect(out.events).toHaveLength(8); + expect(out.totals.costUSD).toBeCloseTo(3.87, 2); + expect(out.sourceFile).toBeUndefined(); // fetched, not read from disk + }); +}); + +describe('usage-export failure handling', () => { + it.each([401, 403, 500])('degrades to null on HTTP %i', async (status) => { + const f = recordingFetch(() => ({ status })); + expect(await fetchCursorUsageExport(base, { fetch: f.impl })).toBeNull(); + }); + + it('degrades to null when the body is not a usage export', async () => { + const f = recordingFetch(() => ({ body: 'Sign in' })); + expect(await fetchCursorUsageExport(base, { fetch: f.impl })).toBeNull(); + }); + + it('survives a transport throw', async () => { + const impl = async () => { throw new Error('ENOTFOUND cursor.example'); }; + expect(await fetchCursorUsageExport(base, { fetch: impl as never })).toBeNull(); + }); +}); + +describe('session token confidentiality', () => { + let logged: string[]; + beforeEach(async () => { + logged = []; + const { logger } = await import('@/utils/logger.js'); + vi.spyOn(logger, 'debug').mockImplementation((...args: unknown[]) => { logged.push(args.map(String).join(' ')); }); + vi.spyOn(logger, 'warn').mockImplementation((...args: unknown[]) => { logged.push(args.map(String).join(' ')); }); + }); + afterEach(() => vi.restoreAllMocks()); + + it('never writes the cookie to a log line, on success or on failure', async () => { + await fetchCursorUsageExport(base, { fetch: recordingFetch().impl }); + await fetchCursorUsageExport(base, { fetch: recordingFetch(() => ({ status: 401 })).impl }); + const all = logged.join('\n'); + expect(all).not.toContain(FAKE_COOKIE); + expect(all).not.toContain(FAKE_JWT); + expect(all).not.toContain(FAKE_USER_ID); + }); +}); + +describe('readCursorSessionCookie', () => { + let dir: string; + beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'cursor-cookie-')); }); + afterEach(() => rmSync(dir, { recursive: true, force: true })); + + it('returns undefined when the state database is absent', async () => { + expect(await readCursorSessionCookie(join(dir, 'missing.vscdb'))).toBeUndefined(); + }); + + it('returns undefined for a file that is not a database', async () => { + const p = join(dir, 'state.vscdb'); + writeFileSync(p, 'not a database'); + expect(await readCursorSessionCookie(p)).toBeUndefined(); + }); +}); + +describe('explicitly supplied session token', () => { + it('prefers CURSOR_SESSION_TOKEN over any store lookup', async () => { + const cookie = await readCursorSessionCookie('/no/such/state.vscdb', { CURSOR_SESSION_TOKEN: FAKE_COOKIE }); + expect(cookie).toBe(FAKE_COOKIE); + }); + + it('rejects a supplied value that is not of the documented shape', async () => { + const cookie = await readCursorSessionCookie('/no/such/state.vscdb', { CURSOR_SESSION_TOKEN: 'crsr_someadminapikey' }); + expect(cookie).toBeUndefined(); + }); +}); diff --git a/src/agents/plugins/cursor/cursor.usage-fetch.ts b/src/agents/plugins/cursor/cursor.usage-fetch.ts new file mode 100644 index 000000000..4717d5fd1 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.usage-fetch.ts @@ -0,0 +1,201 @@ +/** + * Cookie-authenticated fetch of the Cursor usage export. + * + * This is a convenience wrapper around exactly one thing: getting the same CSV that + * `--cursor-usage-csv` reads from disk, without the operator clicking Export by hand. It parses + * the result through {@link parseCursorUsageCsv} — one code path, so the fetched and the + * downloaded file can never diverge in interpretation. + * + * Three deliberate constraints, because this handles a live session credential: + * + * 1. **The endpoint is not hardcoded.** Cursor's dashboard export is undocumented and can change + * or vanish without notice, so CodeMie ships no URL and asserts nothing about one: the + * operator supplies `CURSOR_USAGE_EXPORT_URL`. A product that bakes in an undocumented + * endpoint quietly breaks when the vendor moves it; this one simply does nothing. + * 2. **Auth is the browser session cookie, never a `crsr_` API key.** The Team Analytics admin + * key is rejected by this endpoint (401) and is a different credential for a different API. + * 3. **The token never reaches a log line.** It is read, put in one header, and dropped. Failure + * messages name the status code and the endpoint host, never the credential. + * + * File import remains the supported path. This is strictly opt-in and fail-soft: anything that + * goes wrong omits the section and leaves the local report — which always works — untouched. + * + * On where the cookie comes from: it is a *browser* cookie for cursor.com, so on a signed-in + * machine it lives in the Electron app's Chromium cookie jar, encrypted against the OS keychain. + * CodeMie does not decrypt that — prying a credential out of another application's protected + * store is not something an analytics command should do. {@link readCursorSessionCookie} makes a + * cheap, read-only attempt at Cursor's own plaintext state database (harmless if it finds + * nothing), and otherwise the operator supplies the value explicitly via `CURSOR_SESSION_TOKEN`, + * which keeps handing over a credential a deliberate act. + */ + +import { existsSync } from 'node:fs'; +import { logger } from '@/utils/logger.js'; +import { getCursorStateDbPath } from './cursor.paths.js'; +import { parseCursorUsageCsv, type CursorUsageImport } from './cursor.usage-csv.js'; + +/** The cookie Cursor's dashboard authenticates with: `::`. */ +const COOKIE_NAME = 'WorkosCursorSessionToken'; + +/** + * A session cookie value is `::`. Matching on the shape rather than on a fixed + * key name means a renamed storage key does not silently break the reader — and, more + * importantly, that we never treat some other opaque secret as if it were this one. + */ +const COOKIE_SHAPE = /^[\w-]+::[\w-]+\.[\w-]+\.[\w-]+$/; + +export interface UsageFetchRequest { + /** Explicit per-invocation opt-in. A readable cookie on disk is never sufficient by itself. */ + enabled: boolean; + /** Operator-supplied export endpoint. Absent means no request is made. */ + exportUrl?: string; + /** `::`, normally from {@link readCursorSessionCookie}. */ + cookie?: string; + startDate?: string; + endDate?: string; + /** Restrict imported rows to one `User` value, as the file import does. */ + userEmail?: string; +} + +type FetchLike = ( + url: string, + init?: { headers?: Record } +) => Promise<{ ok: boolean; status: number; text: () => Promise }>; + +export interface UsageFetchDeps { + fetch: FetchLike; +} + +/** Host only — enough to debug a failure without ever naming the credential. */ +function hostOf(url: string): string { + try { + return new URL(url).host; + } catch { + return 'the configured endpoint'; + } +} + +async function loadSqlite(): Promise { + try { + return await import('node:sqlite'); + } catch { + // Node < 22.5 has no node:sqlite. Same fail-soft contract as the rest of the plugin. + logger.debug('[cursor] node:sqlite unavailable; cannot read the session cookie'); + return null; + } +} + +/** + * Read the signed-in session cookie out of Cursor's own state database. + * + * Read-only and fail-soft by mandate (ADR 0001): an absent file, an old Node, a renamed table, + * a corrupt or locked database, or simply not being signed in all return `undefined` rather + * than throwing. Candidate rows are matched on {@link COOKIE_SHAPE}, so a storage-key rename + * does not break this and no unrelated secret is mistaken for the cookie. + * + * Returns the raw cookie value. Callers must not log it. + */ +export async function readCursorSessionCookie( + dbPath: string = getCursorStateDbPath(), + env: NodeJS.ProcessEnv = process.env +): Promise { + // An explicitly-provided value always wins: it is the documented way in, and it means the + // operator chose to hand over the credential rather than having it lifted from an app store. + const supplied = env.CURSOR_SESSION_TOKEN?.trim(); + if (supplied) { + if (COOKIE_SHAPE.test(supplied)) { + return supplied; + } + logger.debug('[cursor] CURSOR_SESSION_TOKEN is set but is not of the form ::'); + return undefined; + } + + if (!existsSync(dbPath)) { + logger.debug('[cursor] no state database; cannot read the session cookie'); + return undefined; + } + const sqlite = await loadSqlite(); + if (!sqlite) { + return undefined; + } + + let db: InstanceType | undefined; + try { + db = new sqlite.DatabaseSync(dbPath, { readOnly: true }); + const rows = db + .prepare( + `SELECT value FROM ItemTable + WHERE key LIKE '%${COOKIE_NAME}%' OR key LIKE 'cursorAuth%'` + ) + .all() as { value?: unknown }[]; + for (const row of rows) { + const value = typeof row.value === 'string' ? row.value.trim() : undefined; + if (value && COOKIE_SHAPE.test(value)) { + return value; + } + } + logger.debug('[cursor] no session cookie found in the state database (signed out?)'); + return undefined; + } catch (error) { + logger.debug(`[cursor] state database unusable while reading the session cookie: ${(error as Error).message}`); + return undefined; + } finally { + try { + db?.close(); + } catch { + /* closing a failed open is not an error worth reporting */ + } + } +} + +/** + * Fetch and parse the usage export. Returns `null` whenever the gate is shut or anything at all + * goes wrong — the caller simply omits the section. + */ +export async function fetchCursorUsageExport( + req: UsageFetchRequest, + deps: UsageFetchDeps = { fetch: globalThis.fetch as unknown as FetchLike } +): Promise { + if (!req.enabled || !req.exportUrl || !req.cookie) { + logger.debug('[cursor] usage export fetch skipped (needs the opt-in flag, an export URL, and a session cookie)'); + return null; + } + + let url: string; + try { + const u = new URL(req.exportUrl); + if (req.startDate) { + u.searchParams.set('startDate', req.startDate); + } + if (req.endDate) { + u.searchParams.set('endDate', req.endDate); + } + url = u.toString(); + } catch { + logger.debug('[cursor] CURSOR_USAGE_EXPORT_URL is not a valid URL'); + return null; + } + + try { + const res = await deps.fetch(url, { + headers: { Cookie: `${COOKIE_NAME}=${req.cookie}`, Accept: 'text/csv' }, + }); + if (!res.ok) { + // Status and host only — naming the credential here is how secrets end up in bug reports. + logger.debug(`[cursor] usage export fetch returned HTTP ${res.status} from ${hostOf(url)}`); + return null; + } + const parsed = parseCursorUsageCsv(await res.text(), { + ...(req.userEmail !== undefined && { userEmail: req.userEmail }), + }); + if (!parsed) { + // A sign-in redirect returns 200 with an HTML body; that is not an export. + logger.debug(`[cursor] usage export response from ${hostOf(url)} was not a usage CSV`); + return null; + } + return parsed; + } catch (error) { + logger.debug(`[cursor] usage export fetch failed against ${hostOf(url)}: ${(error as Error).message}`); + return null; + } +} diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 2cb21a6c2..6819067ab 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -24,7 +24,8 @@ export function createAnalyticsCommand(): Command { .option('--no-scan-native', 'Skip native agent-log discovery (use only CodeMie-tracked sessions)') .option('--include-external', 'Include non-CodeMie-owned native sessions in output (opt-in; matches pre-fix behavior)') .option('--cursor-usage-csv ', 'Import a Cursor usage-events CSV (Cursor dashboard → Usage → Export) for real Cursor tokens and cost. No network call') - .option('--cursor-usage-user ', 'Which User column value to keep from --cursor-usage-csv (default: your configured CodeMie email)') + .option('--cursor-usage-user ', 'Which User column value to keep from the Cursor usage export (default: your configured CodeMie email)') + .option('--cursor-usage-fetch', 'Download the Cursor usage export instead of passing a file (makes a NETWORK CALL; requires CURSOR_USAGE_EXPORT_URL and a signed-in Cursor app)') .action((options: AnalyticsOptions) => runAnalytics(options, new SessionsSource())); // `codemie analytics otel --file ` — OTEL file source. @@ -173,22 +174,46 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS } } - // #21: the member path to real Cursor tokens/cost. Pure file read — no network call. + // #21/#22: the path to real Cursor tokens/cost — a local file, or the same export fetched. + // Both end in the SAME parser, so a downloaded export can never be interpreted differently + // from one the operator saved by hand. let cursorUsage; + const wantedUser = options.cursorUsageUser ?? userEmail; if (options.cursorUsageCsv) { const { loadCursorUsageCsv } = await import('@/agents/plugins/cursor/cursor.usage-csv.js'); - const wantedUser = options.cursorUsageUser ?? userEmail; cursorUsage = loadCursorUsageCsv(options.cursorUsageCsv, { ...(wantedUser !== undefined && { userEmail: wantedUser }), }) ?? undefined; if (!cursorUsage) { console.log(chalk.yellow(`\n Could not read a Cursor usage export from ${options.cursorUsageCsv}. Report continues without it.`)); - } else if (cursorUsage.events.length === 0) { + } + } else if (options.cursorUsageFetch) { + // The only network call in the analytics path, and it needs all three of: the flag, a + // configured endpoint, and a signed-in Cursor. Any missing piece means no request. + const { readCursorSessionCookie, fetchCursorUsageExport } = await import('@/agents/plugins/cursor/cursor.usage-fetch.js'); + const cookie = await readCursorSessionCookie(); + cursorUsage = (await fetchCursorUsageExport({ + enabled: true, + ...(process.env.CURSOR_USAGE_EXPORT_URL !== undefined && { exportUrl: process.env.CURSOR_USAGE_EXPORT_URL }), + ...(cookie !== undefined && { cookie }), + ...(wantedUser !== undefined && { userEmail: wantedUser }), + ...(filter.fromDate !== undefined && { startDate: filter.fromDate.toISOString().slice(0, 10) }), + ...(filter.toDate !== undefined && { endDate: filter.toDate.toISOString().slice(0, 10) }), + })) ?? undefined; + if (!cursorUsage) { + console.log(chalk.yellow('\n Could not fetch the Cursor usage export. It needs CURSOR_USAGE_EXPORT_URL set and a signed-in')); + console.log(chalk.yellow(' Cursor app on this machine; the endpoint is undocumented and may have changed.')); + console.log(chalk.yellow(' The supported fallback is to export the CSV from the Cursor dashboard and pass --cursor-usage-csv .')); + console.log(chalk.dim(' Run with CODEMIE_DEBUG=true to see the status code. Report continues without it.')); + } + } + if (cursorUsage) { + if (cursorUsage.events.length === 0) { // The Cursor account's email is frequently NOT the CodeMie config email, which would // otherwise silently filter every row away and look like an empty export. console.log(chalk.yellow(`\n Cursor usage export matched no rows for ${wantedUser ?? '(no email configured)'}.`)); if (cursorUsage.usersInFile.length) { - console.log(chalk.yellow(` The file contains: ${cursorUsage.usersInFile.join(', ')}`)); + console.log(chalk.yellow(` The export contains: ${cursorUsage.usersInFile.join(', ')}`)); console.log(chalk.yellow(' Re-run with --cursor-usage-user to pick one of those.')); } cursorUsage = undefined; diff --git a/src/cli/commands/analytics/types.ts b/src/cli/commands/analytics/types.ts index 42afe0999..66924d048 100644 --- a/src/cli/commands/analytics/types.ts +++ b/src/cli/commands/analytics/types.ts @@ -263,6 +263,12 @@ export interface AnalyticsOptions { * email, which is often a different address from the one on the Cursor account. */ cursorUsageUser?: string; + /** + * When true (via --cursor-usage-fetch), download the usage export instead of reading a file. + * Requires CURSOR_USAGE_EXPORT_URL and a signed-in Cursor session; the flag alone makes no + * network call, and neither does a readable session cookie on its own. + */ + cursorUsageFetch?: boolean; } /** Options for the `analytics otel` subcommand: the shared base plus OTEL-specific flags. */ From 4669575878f3d1a452c4d6eacfed2d333a532f5f Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:31 +0300 Subject: [PATCH 25/34] docs(analytics): add a step-by-step verification guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Cursor work added behaviour a reader cannot confirm by looking: dashes that mean "unmeasurable" rather than zero, a sidebar section that only exists once an export is imported, and a fetch gated on three separate things. Without a way to check, "it shows dashes" is indistinguishable from "it is broken". Six ordered checks, each stating what to run, what to expect, and what a different result means. They build up: a report exists, external sessions appear, the Cursor-only view goes honestly blank, the usage export fills it in, the optional fetch does the same without a file, and the test suites for anyone changing the code. Every command was executed against the real product and real exports before being written down, including the failure paths — the fetch gate with a missing cookie, and the "matched no rows" email-mismatch case. The totals cross-check is Python rather than the obvious awk one-liner because the obvious one is wrong: the export ships CRLF endings and two column layouts, so summing the last column silently adds up Requests on the no-Cost variant and prints a plausible, entirely wrong dollar figure. That trap is called out in the text so nobody reinstates it. --- docs/ANALYTICS-REPORT.md | 128 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 4be6b31d5..136400dd2 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -435,6 +435,134 @@ With this source, **cost is authoritative**: it is read directly from each event --- +## Verifying it works + +Concrete checks you can run yourself, in the order that builds confidence fastest. Each says what +to run, what you should see, and what it means if you see something else. + +### 1. Does a report build at all? + +```bash +codemie analytics --report --report-output /tmp/check.html +``` + +**Expect:** `✓ HTML report written to: /tmp/check.html`, preceded by terminal tables. Open it — the +sidebar should list Overview through Sessions. + +If you get *"No sessions found matching the specified criteria"*, you have no CodeMie-launched +sessions in range. Add `--include-external` (below) or widen with `--last 90d`. + +### 2. Do your non-CodeMie sessions appear? + +```bash +codemie analytics --report --open --include-external --last 30d +``` + +**Expect:** a higher session count than step 1, and more agents in the top filter bar. This is the +flag that answers "what did AI actually cost me?" — see +[Session provenance](#session-provenance). + +### 3. Cursor sessions and the honest empty state + +With `--include-external`, Cursor sessions appear. To see the behaviour that surprises people +most, **deselect every agent except Cursor** in the top bar. + +**Expect:** Overview's Input/Output/Total token KPIs and Est. cost all go to `—`, with a note +saying local token telemetry is absent — *and the tool-call tables keep working*. + +That is correct, not a bug: recent Cursor builds record no billable token counts locally. If you +instead see `$0.00`, `0`, or the word `Included` anywhere, that **is** a bug — those were removed +deliberately (see [When cost and tokens show `—`](#unknown-cost)). + +### 4. Real Cursor tokens and cost, from the usage export + +This is the check that turns those dashes into numbers. + +1. In Cursor, open **Usage** → **Export**, choosing a period you actually worked in. +2. Run: + +```bash +codemie analytics --report --open --include-external \ + --cursor-usage-csv ~/Downloads/team-usage-events-*.csv +``` + +**Expect:** a new **Cursor Usage CSV** entry in the sidebar (it is hidden when no export is +imported) showing Events, Total tokens and Cost, plus by-model and by-day tables. + +Sanity-check the totals against the file itself. (This handles both export shapes, the `Free` +cost cells, and the CRLF line endings the export ships — a naive `awk` over the last column +silently sums `Requests` on the no-`Cost` variant and prints a plausible, wrong dollar figure.) + +```bash +python3 - ~/Downloads/team-usage-events-....csv <<'EOF' +import csv, re, sys +rows = list(csv.DictReader(open(sys.argv[1], newline='', encoding='utf-8-sig'))) + +def num(v): + m = re.search(r'-?\d+(?:\.\d+)?', (v or '').replace(',', '')) + return float(m.group()) if m else 0.0 + +tok = sum(int(r['Total Tokens'] or 0) for r in rows) +if rows and 'Cost' in rows[0]: + print(f"{len(rows)} events, {tok:,} tokens, ${sum(num(r['Cost']) for r in rows):.2f}") +else: + print(f"{len(rows)} events, {tok:,} tokens (this export has no Cost column)") +EOF +``` + +The report's Events, Total tokens and Cost KPIs should match that line exactly. **Every row saying +`Included` still contributes** — that word is a billing category, not zero usage. + +**If the section is missing**, the terminal tells you which check failed: + +| Message | Meaning | Fix | +|---|---|---| +| `Could not read a Cursor usage export from …` | Wrong path, or not a usage CSV | Check the path; confirm the header starts `Date,User,…` | +| `matched no rows for ` + `The export contains: …` | Your Cursor account email differs from your CodeMie one | Re-run with `--cursor-usage-user ` | +| Cost shows `—` but tokens are fine | This export variant has no `Cost` column (it ships `Requests`) | Expected; re-export, or read the token columns | + +### 5. Optional: fetching that export automatically + +Only worth trying after step 4 works. It is opt-in and unsupported — see +[Downloading it automatically](#cursor-usage-fetch). + +You need the endpoint URL, which CodeMie deliberately does not ship. To find it: open the Cursor +dashboard **Usage** page in your browser, open DevTools → **Network**, click **Export**, and copy +the request URL of the CSV download. The session cookie is `WorkosCursorSessionToken` in the same +request's headers (`::`). + +```bash +export CURSOR_USAGE_EXPORT_URL='' +export CURSOR_SESSION_TOKEN='::' +codemie analytics --report --open --include-external --cursor-usage-fetch +``` + +**Expect:** the same **Cursor Usage CSV** section as step 4, without having saved a file. + +To prove the gate rather than the happy path, unset either variable and re-run: no request should +be made at all. `CODEMIE_DEBUG=true` prints the outcome per attempt — status code and endpoint +host only, never your token. + +| Symptom | Meaning | +|---|---| +| `usage export fetch skipped (needs the opt-in flag, an export URL, and a session cookie)` | One of the three is missing — the gate working | +| `returned HTTP 401` / `403` | Cookie expired or wrong; re-copy it from a fresh request | +| `was not a usage CSV` | The endpoint returned a sign-in page, not an export | + +### 6. Regression checks, if you are changing this code + +```bash +npm run typecheck && npm run lint +npx vitest run src/agents/plugins/cursor/__tests__/ # Cursor plugin, incl. CSV + fetch +npx vitest run --project unit --project cli # everything +``` + +The CSV tests assert against a fixture copied verbatim from a real export — 61 events, +39,952,466 tokens, $25.25, including its two `Free` cost cells — so a parser regression shows up +as a changed total rather than as a vague failure. + +--- + ## CLI Reference ``` From 75e675019dcc5a14f9b1bd691f99d79a7dd96aec Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:31 +0300 Subject: [PATCH 26/34] refactor(analytics): extract the shared Cursor sqlite helpers and drop the Cost fold-in Keeps the code-review changes that stand on their own: the `cursor.sqlite.ts` extraction the three readers now share, the parameterised `LIKE` in the usage fetch, and the orphaned JSDoc left behind by the Team Analytics removal. Removes `cursorCostContrib()` and its Cost-tab call sites. Folding the imported CSV into one tab by special case left Overview and Cost disagreeing, kept 39.9M tokens out of "Tokens by model", and vanished entirely when no local Cursor session existed. The replacement converts the CSV into ordinary sessions so it flows everywhere by construction. Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_01KQwQ1VNMjpMrxk1EB9eoyF --- .../issues/01-drop-included-unknown-dashes.md | 14 +++ .../02-auto-unpriced-sonnet-estimate.md | 14 +++ .../issues/03-cursor-only-empty-state.md | 13 ++ .../issues/04-docs-sparse-cursor-tokens.md | 12 ++ .../05-research-alternate-token-sources.md | 106 ++++++++++++++++ .../06-opt-in-team-analytics-section.md | 17 +++ .../issues/07-team-analytics-admin-only.md | 14 +++ .../issues/08-docs-admin-vs-member-csv.md | 19 +++ .../issues/09-import-cursor-usage-csv.md | 17 +++ .../10-optional-cookie-fetch-usage-csv.md | 17 +++ .../cursor-analytics-cost-honesty/spec.md | 115 ++++++++++++++++++ src/agents/plugins/cursor/cursor.bubbles.ts | 30 +---- src/agents/plugins/cursor/cursor.paths.ts | 2 +- src/agents/plugins/cursor/cursor.session.ts | 2 +- src/agents/plugins/cursor/cursor.sqlite.ts | 49 ++++++++ src/agents/plugins/cursor/cursor.state-db.ts | 51 +------- .../plugins/cursor/cursor.tracking-db.ts | 30 +---- .../plugins/cursor/cursor.transcript.ts | 2 +- .../plugins/cursor/cursor.usage-fetch.ts | 17 +-- src/cli/commands/analytics/types.ts | 5 - 20 files changed, 424 insertions(+), 122 deletions(-) create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md create mode 100644 .scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md create mode 100644 .scratch/cursor-analytics-cost-honesty/spec.md create mode 100644 src/agents/plugins/cursor/cursor.sqlite.ts diff --git a/.scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md b/.scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md new file mode 100644 index 000000000..d9a1b97d0 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md @@ -0,0 +1,14 @@ +# 01: Drop “Included”; unknown cost/tokens are dashes + +**What to build:** The analytics HTML report never presents subscription wording for missing usage. Cost and token cells for unmeasurable sessions show an em dash. Mixed groups still show the sum of whatever was measured. Session-modal copy no longer says usage was covered by a subscription. + +**Blocked by:** None (can start immediately). + +**Status:** done (commit 0e56e45) + +- [x] No cost-formatting path in the report client emits the string `Included` +- [x] Unmeasurable sessions render `—` for cost and for token fields (not `$0.00` / `0`) +- [x] Aggregates over a mixed measured+unmeasurable set still show the measured sum +- [x] Session modal cost subtitle no longer says “covered by subscription” +- [x] Regenerating a report with `--include-external` and filtering to Cursor-only shows dashes for cost/tokens, not Included +- [x] Non-Cursor agents’ measurable totals are unchanged for the same underlying sessions diff --git a/.scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md b/.scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md new file mode 100644 index 000000000..235531ca7 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md @@ -0,0 +1,14 @@ +# 02: Auto/unpriced token sessions get Sonnet-equivalent estimates + +**What to build:** When a session has recoverable tokens but the model cannot be priced (Auto, default, unknown, or otherwise missing from the price table), the report shows an API-equivalent USD estimate using the documented Claude Sonnet rate stand-in, keeps the original model label on the session, and marks the usage as partial. Sessions whose tracking model already prices normally keep using that model’s rates. + +**Blocked by:** None (can start immediately). + +**Status:** done (commit 4630ca6) + +- [x] Tokens + Auto/unpriced model → nonzero USD estimate, `usagePartial` set, displayed model still Auto/original (not renamed to Sonnet) +- [x] Tokens + priced model (e.g. a real tracking-db id) → that model’s rates; Sonnet fallback not applied +- [x] No token signal → no fabricated estimate; provenance stays unmeasurable (dashes after 01) +- [x] Partial badge / copy still indicates the figure is understated or estimated +- [x] Coverage still treats “had recoverable usage” as priced when tokens were adopted from adapter provenance +- [x] Verifiable via enricher/native Cursor fixtures without requiring a live `state.vscdb` diff --git a/.scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md b/.scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md new file mode 100644 index 000000000..504966c57 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md @@ -0,0 +1,13 @@ +# 03: Cursor-only empty state when no local token signal + +**What to build:** When every session in view is unmeasurable (the common Cursor-only case after deselecting other agents), Overview and Cost KPIs stay on dashes and briefly explain that local token telemetry is absent — so the collapse no longer reads as a broken agent-chip filter. Tool-call and other non-usage panels keep working. + +**Blocked by:** 01 — Drop “Included”; unknown cost/tokens are dashes + +**Status:** done (commit 0e56e45) + +- [x] All-unmeasurable filtered set → Overview Input/Output/Total tokens and Est. cost show `—` (not `$0` / Included) +- [x] A short subtitle or empty-state note states local token telemetry is absent for sessions in view +- [x] Agent chips still filter by agent name only; no model-chip behaviour introduced +- [x] Cursor tool-call success/failure tables remain populated when bubbles carried tool outcomes +- [x] Mixed views that include at least one measured session still show that session’s tokens/cost normally diff --git a/.scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md b/.scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md new file mode 100644 index 000000000..afb6c2e6a --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md @@ -0,0 +1,12 @@ +# 04: Docs — recent Cursor bubble tokens are sparse/absent + +**What to build:** Operator and integration docs state the verified local reality: recent Cursor builds often write zero (or omit) billable `tokenCount` on bubbles while tool outcomes still appear; the Team Analytics API still does not return token or cost fields; ADR 0001 fail-soft / opt-in external / no silent network constraints remain the contract. + +**Blocked by:** None (can start immediately). + +**Status:** done (commit db114bc) + +- [x] Cursor integration / external-integrations docs mention sparse or absent recent bubble token signals vs working tool enrichment +- [x] Docs restate that Team Analytics endpoints do not provide tokens/cost and cannot alone close that gap +- [x] Docs do not instruct operators to treat “Included” as the expected cost label (aligned with 01) +- [x] ADR 0001 is not contradicted (read-only, fail-soft, Auto display label, no invented invoice certainty) diff --git a/.scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md b/.scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md new file mode 100644 index 000000000..258a01bd5 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md @@ -0,0 +1,106 @@ +# 05: Research spike — alternate recent Cursor billable-token sources + +**What to build:** A written go/no-go on whether any other local or exportable Cursor artifact carries recent billable input/output tokens. Negative evidence is an acceptable outcome. No new production reader ships in this ticket; findings feed ticket 06 and any later token-source work. + +**Blocked by:** 04 — Docs — recent Cursor bubble tokens are sparse/absent + +**Status:** done — local NO-GO, but SUPERSEDED by #21 (dashboard usage CSV has the tokens; see amendment at the end) + +- [x] Spike notes which stores/exports were checked and what each carries (or lacks) for recent sessions +- [x] Explicit conclusion: viable source found vs none found for recent billable I/O +- [x] Confirms Team Analytics still lacks token/cost fields (or documents a change if upstream added them) +- [x] Does not widen default discovery max-age solely to harvest year-old bubble tokens as “the fix” +- [x] Does not invent tokens from context-window fill, transcript length, or tool-call counts +- [x] Findings appended under this ticket (or linked artifact) so 06 can proceed without rediscovery + +--- + +## Findings (spike run 2026-09-05) + +**Conclusion: NO-GO. No local or exportable Cursor artifact carries recent billable input/output +tokens.** Nothing new ships from this ticket; the local floor documented in 04 stands. + +Method: read-only inspection of one operator machine's live Cursor installation (databases copied +to a scratch dir before querying, so no lock was taken on Cursor's own files). + +### Stores checked + +| Store | Recent billable tokens? | What it actually carries | +|---|---|---| +| `state.vscdb` → `cursorDiskKV` `bubbleId:*` | **No** | 5,134 of 5,177 bubbles carry a `tokenCount` object, but 5,080 are `{inputTokens:0, outputTokens:0}`. `toolFormerData` works throughout. | +| `state.vscdb` → `composerHeaders` | **No** | Discovery only (501 rows, 0–72 days old). No usage fields. | +| `state.vscdb` → `cursorDiskKV` `composerData:*` | **No** | `contextTokensUsed`, `contextTokenLimit`, `totalUsedTokens`, `promptTokenBreakdown`, `estimatedTokens` — **context-window fill, not billing**. Explicitly out of scope. | +| `state.vscdb` → `cursorDiskKV` `agentKv:*` | **No** | An opaque blob cache of *other* tools' cached payloads and file contents (Copilot extension telemetry, MCP tool results, and a mock usage-export document with placeholder values like `developer@company.com`). Not a Cursor usage ledger, and it holds third-party secrets — reading it would be actively wrong. | +| `state.vscdb` → `cursorDiskKV` `messageRequestContext:*` | **No** | Prompt-assembly context (git status, project layouts, attached files). | +| `state.vscdb` → `ItemTable` | **No** | Only billing-*banner dismissal* flags (`cursor.billingBanner.*`, `cursor.dismissedCreditGrantIds`) and auth tokens. No usage figures. | +| `~/.cursor/ai-tracking/ai-code-tracking.db` | **No** | `ai_code_hashes`, `scored_commits`, `conversation_summaries`, `tracked_file_content`. Line-attribution and model labels only; zero token columns. | +| `conversation-search.db` (globalStorage) | **No** | FTS index over conversation titles/text. The only `token` match is the FTS `tokenize=` pragma — a text tokenizer, not billing. | +| `~/.cursor/chats/*/*/store.db` (31 stores) | **No** | `blobs` + `meta`. 2,887 blobs decoded and 31 meta rows decoded: zero token-shaped fields. `meta` carries `agentId`, `name`, `mode`, `createdAt`, `lastUsedModel`. | +| `~/.cursor/projects/*/agent-transcripts/*.jsonl` | **No** | Only `token_budget` / `tokens` strings originating from MCP *tool payloads*, not Cursor usage. | +| Team Analytics API | **No** | Re-verified against the live docs (below). | + +### The decisive cross-check + +Nonzero `tokenCount` bubbles exist but belong to a disjoint, aged-out population: + +- 31 composers hold all 54 nonzero-token bubbles; their ages are **354–408 days**. +- **0 of those 31 appear in `composerHeaders`**, so they are undiscoverable by design. +- Of the 3,671 bubbles under the 501 *discoverable* composers, **every single `tokenCount` is zero**. + +So the token signal has not moved to another store — it stopped being written. No reader change can +recover it, and widening `--max-age` would only resurface year-old conversations to manufacture a +total that says nothing about recent work (explicitly rejected). + +### Team Analytics API re-verification + +Fetched on 2026-09-05. Documented response +fields are diff/acceptance and activity counters — `total_suggested_diffs`, `total_accepted_diffs`, +`total_rejected_diffs`, `total_green_lines_accepted`, `total_red_lines_accepted`, `total_suggestions`, +`total_accepts`, `total_rejects`, `messages`, `command_name`, `skill_name`, `model`. **No token or +cost fields at any tier** — unchanged from the guide's existing claim. Auth is an API key +(`-u YOUR_API_KEY:`); by-user filtering via a `users` parameter of email addresses is supported, +which is what makes ticket 06's user-scoped constraint achievable. + +### What this means for ticket 06 + +06 may proceed, but strictly as **non-token aggregates in a separate labelled section**. This spike +found no token source, so 06 must not be presented as closing the cost gap. + +### Amendment (2026-09-05 evening) — dashboard usage CSV is GO (members) + +Reopened after operator-provided export +`team-usage-events-17821605-2026-09-05.csv` and live probe of +`GET cursor.com/api/dashboard/export-usage-events-csv?strategy=tokens`: + +- CSV carries Date, User, Kind, Model, input/cache/output tokens, Total Tokens, **Cost**. +- Sample: 61 rows, all `Kind=Included`, yet Cost summed ≈ **$25.25** with large token totals — + `Included` is a billing category, not “no cost”. +- Admin `crsr_` key → **401** on this endpoint (member-usable via session cookie / UI download). +- Session cookie `WorkosCursorSessionToken=::` → **200** CSV. + +**Audience split (product decision):** + +- **Enterprise team admins** — keep opt-in Team Analytics API (ticket 06) for non-token aggregates; clarify admin-only in 07/08. +- **Team members** — usage-events CSV file import (09) and optional cookie fetch (10) for tokens + Cost. + +Do **not** roll back Team Analytics entirely; do not tell members to use the admin API for billable usage. + +--- + +## Amendment (2026-09-05, after issue #21) + +**The NO-GO conclusion above is superseded.** This spike searched only *local* stores and its +local findings stand — no local artifact carries recent billable tokens. But it never checked +Cursor's **dashboard usage export**, which does. + +Verified against a real export (`team-usage-events-*.csv`, 2026-09-05): 61 events, all +`Kind=Included`, carrying **39,952,466 tokens and $25.25 of cost**. A second export from the same +day held 380 events and 201,523,437 tokens. + +`Included` is Cursor's billing category — "covered by your plan" — not a claim that the usage was +free or unmeasured. Reading it as "no cost" is exactly the mistake that made this data look +worthless. + +The export is now imported via `--cursor-usage-csv` (issue #21, commit 2fb0c9e). The "Do not widen +discovery max-age" and "do not invent tokens from context fill / transcript length / tool counts" +conclusions are unaffected and still binding. diff --git a/.scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md b/.scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md new file mode 100644 index 000000000..a0346560f --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md @@ -0,0 +1,17 @@ +# 06: Opt-in Cursor Team Analytics section (non-token aggregates) + +**What to build:** An optional, explicitly flagged, credential-gated pull of Cursor Team Analytics for the requesting user only, rendered as a separate labelled section in the analytics report. Shows only what the API actually returns (edits, models, etc.). Never merges into the local session table, never makes silent network calls, and never fabricates tokens/cost from this API. + +**Blocked by:** 05 — Research spike — alternate recent Cursor billable-token sources + +**Status:** done — but re-scoped by GitHub #23: Team Analytics is enterprise-ADMIN-only and is not the member path to tokens/cost. Members use `--cursor-usage-csv` (#21). This ticket is retained as historical; it should not be read as "Team Analytics answers cost". — keep for enterprise admins; members use CSV (09/10). Clarify audience via 07/08. + +- [x] No Team Analytics network call runs unless both a configured credential and an explicit invocation opt-in are present +- [x] Data scope is the requesting user’s own email (`by-user`); no team-wide or leaderboard dump into personal analytics +- [x] Report renders Team Analytics in a separate labelled section, not inside the local session rows +- [x] Local session table and Team Analytics section are not silently joined on missing composerId keys +- [x] Tokens/cost are not invented from Team Analytics responses +- [x] Fail-soft: API/auth failures degrade to an empty/omitted section without breaking the local report +- [x] Behaviour respects conclusions from 05 (e.g. if a better token source was found, this ticket still does not pretend Team Analytics supplies tokens unless upstream changed) + +Audience clarification 2026-09-05: **retain** this feature for enterprise **team admins** only. Ordinary members cannot use the admin API key path for billable usage — they use dashboard usage-events CSV (tickets 09/10). Tickets 07/08 update product copy and docs; do not delete the admin opt-in. diff --git a/.scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md b/.scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md new file mode 100644 index 000000000..6e61c7186 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md @@ -0,0 +1,14 @@ +# 07: Keep Team Analytics admin-only; stop presenting it as the member path + +**What to build:** Retain the opt-in Cursor Team Analytics pull for **enterprise team admins** who have an admin-scoped API key, but make the product surface unmistakable: members without admin access cannot use it and should use the usage CSV path (09) instead. Remove or rewrite any copy that implies a non-admin `crsr_` / Team Analytics key closes tokens/cost for ordinary team members. Do **not** delete the admin feature unless docs/CLI currently claim members can use it for billable usage — in that case fix the claim, keep the gate. + +**Blocked by:** None (can start immediately). + +**Status:** ready-for-agent + +- [ ] `--cursor-team-analytics` + admin API key remain available for enterprise **admins** +- [ ] CLI help, flag description, and empty-state copy state clearly: **enterprise team admins only** — not for ordinary team members +- [ ] Members who lack an admin key get a clear message pointing at usage CSV import (09), not a auth-failure dead end framed as “set CURSOR_TEAM_ANALYTICS_API_KEY” +- [ ] Team Analytics section (when present) stays labelled as admin/team-API aggregates and still does **not** claim to supply per-session billable tokens/cost +- [ ] No silent network calls without both flag and credential (existing gate preserved) +- [ ] User-scoped `by-user` filter behaviour for the admin pull is unchanged unless already wrong diff --git a/.scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md b/.scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md new file mode 100644 index 000000000..b4aec5788 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md @@ -0,0 +1,19 @@ +# 08: Docs — admin Team Analytics vs member usage CSV + +**What to build:** Update operator and guide docs so the two Cursor remote/export paths are explicit and non-overlapping: + +1. **Enterprise team admins** — optional `--cursor-team-analytics` + admin-scoped API key for Team Analytics aggregates (edits/models/etc.; not the billable token ledger). +2. **Team members (and anyone without admin API access)** — download Cursor Usage events CSV and pass it via the file flag (09); optional cookie fetch later (10). + +Underline that `Kind=Included` in the CSV is a billing category and rows still carry tokens and `Cost`. Keep report UI honesty: never use “Included” as the cost cell label. + +**Blocked by:** 07 — Keep Team Analytics admin-only; stop presenting it as the member path + +**Status:** ready-for-agent + +- [ ] `docs/ANALYTICS-REPORT.md` documents **two** paths with audience labels: Admin → Team Analytics; Member → usage CSV +- [ ] `docs/CURSOR_INTEGRATION.md` and `.ai-run/guides/integration/external-integrations.md` state Team Analytics is **enterprise-admin-only** and does not return billable token/cost fields +- [ ] Docs describe member flow: Cursor Usage → Export CSV → `--cursor-usage-csv ` (once 09 lands; can stub the flag name agreed in 09) +- [ ] Docs do not tell non-admin members to create/use `CURSOR_TEAM_ANALYTICS_API_KEY` for cost/tokens +- [ ] Honesty wording retained: UI never labels cost cells `Included` / “covered by subscription” +- [ ] Scratch notes (05/06) amended so they don’t read as “remove Team Analytics entirely” diff --git a/.scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md b/.scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md new file mode 100644 index 000000000..d2fd11baa --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md @@ -0,0 +1,17 @@ +# 09: Import Cursor usage-events CSV for tokens and cost (members) + +**What to build:** Give **team members** (and anyone without an admin Team Analytics key) a way to pass a locally downloaded Cursor Usage CSV into analytics report generation. CodeMie reads token and `Cost` columns, filters to the report owner’s email when the `User` column is present, and surfaces API-equivalent spend even when every row’s `Kind` is `Included`. Prefer a separate labelled “Cursor usage export” section and/or day–model aggregates clearly marked as export-sourced — do not invent `composerId` joins. No network call in this ticket. Enterprise admins keep Team Analytics (06/07) for non-token aggregates; this ticket is the member billable-usage path. + +**Blocked by:** None (can start immediately). Complements 07/08 (admin Team Analytics kept; members use this path). + +**Status:** ready-for-agent + +- [ ] Explicit CLI flag accepts a filesystem path to a usage-events CSV (e.g. `--cursor-usage-csv `) +- [ ] Parser accepts the observed header set: Date, User, Kind, Model, Input (w/ and w/o Cache Write), Cache Read, Output Tokens, Total Tokens, Cost (tolerate added columns) +- [ ] Rows with `Kind=Included` still contribute tokens and `Cost` (never mapped to “no cost” / Included UI label) +- [ ] When `User` is present, only the report owner’s email rows are kept +- [ ] Export data appears as an opt-in, clearly labelled source (not silently merged into Claude totals) +- [ ] Missing/unreadable file fails soft: report continues; export section omitted with a clear reason +- [ ] Verifiable against a fixture derived from the sample export shape (61 events, models like `auto` / `cursor-grok-*`, nonzero Cost) + +Prototype note (sample export 2026-09-05): all 61 rows were `Kind=Included` yet `Cost` summed to ~$25.25 with large token totals — product must use `Cost`/tokens, not `Kind`. diff --git a/.scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md b/.scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md new file mode 100644 index 000000000..4f2c05a51 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md @@ -0,0 +1,17 @@ +# 10: Optional cookie fetch of usage-events CSV (after file import) + +**What to build:** After file import works, optionally fetch the same CSV CodeMie already parses by using the signed-in Cursor session cookie from the local app store (`WorkosCursorSessionToken=::`), behind an explicit flag. Never use an admin `crsr_` Team API key for this endpoint. Fail soft; default remains local-only or file-based. + +**Blocked by:** 09 — Import Cursor usage-events CSV for tokens and cost + +**Status:** ready-for-agent + +- [ ] No fetch runs unless an explicit opt-in flag is set (credential/cookie on disk alone is not enough) +- [ ] Auth uses session cookie shape proven against the dashboard export endpoint — not Bearer `crsr_` / Admin API +- [ ] Fetched body is fed through the same CSV parser as 09 (one code path) +- [ ] Date range / team id come from documented operator inputs or safe defaults aligned to the report window +- [ ] 401/403/schema drift → omit export section; local report still succeeds +- [ ] Docs warn this is an undocumented dashboard endpoint and file import remains the supported fallback +- [ ] Secrets are never logged + +Probe note (2026-09-05): `crsr_` → 401; `WorkosCursorSessionToken` with `userId::jwt` → 200 CSV starting with `Date,User,...`. diff --git a/.scratch/cursor-analytics-cost-honesty/spec.md b/.scratch/cursor-analytics-cost-honesty/spec.md new file mode 100644 index 000000000..8cd3ef3e3 --- /dev/null +++ b/.scratch/cursor-analytics-cost-honesty/spec.md @@ -0,0 +1,115 @@ +# Cursor analytics: cost honesty + usage signal follow-on + +Status: ready-for-agent + +## Problem Statement + +When I run `codemie analytics --report --open --include-external` and look at Cursor sessions, cost cells say **Included** even though I care about API-equivalent spend estimated from tokens — subscription billing is irrelevant to me. When I deselect Claude (and other agents) in the top bar so only Cursor remains, Input/Output token KPIs collapse to empty dashes. That feels like Cursor data vanished, when what actually happened is: almost every Cursor session in the report has no local billable token signal, Claude was carrying the totals, and the report still labels unmeasurable cost as if it were covered by a plan. + +I want honest empty states, real estimates when any tokens exist (including model=Auto), and a clear follow-on path for restoring recent Cursor usage signals without inventing zeros. + +## Solution + +1. **Cost honesty (local, ship now).** Stop using the word Included / “covered by subscription” anywhere in the analytics report. Unmeasurable sessions show an em dash. When a Cursor (or any) session has recoverable tokens, show an API-equivalent USD estimate even if the model is Auto/unknown/unpriced, using a documented Sonnet-equivalent fallback rate, and keep the existing partial-usage badge so I know the figure is a floor/estimate. +2. **Honest Cursor-only empty state.** When the filtered set has no measurable token totals, Overview and Cost KPIs stay dashes with copy that says local token telemetry is absent — not that spend was free or included. +3. **Follow-on for richer Cursor usage.** Open a separate effort for optional Enterprise Team Analytics integration and/or alternate token sources. Do **not** pretend the Team Analytics API already returns tokens or cost (it does not, per the external-integrations guide). Any remote integration stays opt-in, fail-soft, user-scoped, and visually separate from the local session table. + +## User Stories + +1. As an analytics report reader, I want cost cells never to say “Included”, so that I am not told subscription status instead of an estimate or unknown. +2. As an analytics report reader, I want unmeasurable sessions to show “—” for cost, so that I do not confuse absence of data with free usage. +3. As an analytics report reader, I want unmeasurable sessions to show “—” for tokens, so that structural zeros are not presented as “zero tokens used”. +4. As an analytics report reader, I want mixed groups (some measured, some not) to show the sum of measured costs/tokens, so that known data is not hidden by unknown peers. +5. As an analytics report reader, I want session-modal cost subtitles never to say “covered by subscription”, so that wording matches API-equivalent intent. +6. As an analytics report reader, I want a partial-usage badge when Cursor bubble tokens are sparse, so that I know the estimate understates real usage. +7. As an analytics report reader, I want Input/Output KPIs to remain visible when at least one session in view has measured or partial tokens, so that sparse Cursor signal is not wiped by aggregate helpers. +8. As an analytics report reader, I want Cursor-only views with no token signal to explain that local telemetry is missing, so that deselection of Claude does not look like a filter bug. +9. As an analytics report reader, I want tool-call success/failure for Cursor to keep working independently of tokens, so that #11’s tool path is not regressed by cost-honesty work. +10. As an analytics report reader, I want Claude/Codex/Copilot totals unchanged when Cursor has no tokens, so that honesty fixes do not invent Cursor spend into other agents. +11. As an analytics report reader, I want agent chips to keep filtering by agent name only, so that “unselect Claude” continues to mean the Claude agent, not “any Claude-named model”. +12. As an analytics report reader, I want Cursor sessions whose tracking model is a priced id (e.g. grok-4.6) to be estimated with that model’s rates when tokens exist, so that estimates prefer real attribution. +13. As an analytics report reader, I want Cursor sessions whose model is Auto/default/unknown to still get a USD estimate when tokens exist, so that lack of a concrete model does not force a blank or Included cost. +14. As an analytics report reader, I want that Auto/unknown estimate to use a documented Claude Sonnet API-equivalent rate table entry, so that the stand-in is stable and reviewable. +15. As an analytics report reader, I want Auto/unknown estimates always marked usagePartial, so that I never treat the stand-in as an invoice. +16. As an analytics report reader, I want the original model label (Auto, unknown, etc.) preserved on the session/per-model row, so that the estimate does not silently rename the model to Sonnet. +17. As an analytics report reader, I want pricedSessions / coverage semantics to remain “had recoverable usage”, so that a partial Cursor floor still counts as priced rather than “no token reader”. +18. As an analytics report reader, I want unpriced-model listing to still mention Auto when the original model was Auto, so that coverage diagnostics stay truthful even if a fallback rate was applied. +19. As a CodeMie operator, I want `--include-external` behavior unchanged, so that Cursor remains opt-in and never appears without the flag. +20. As a CodeMie operator, I want analytics without `--include-external` to omit Cursor entirely, so that external sessions stay gated. +21. As a CodeMie operator, I want regenerating a report after these fixes to drop every “Included” string from the HTML client bundle for cost formatting, so that old copy cannot linger. +22. As a CodeMie developer, I want cost enrichment to keep using adapter-supplied `tokensByModel` as the Cursor usage path, so that we do not add a fake per-message usage walk for bubbles. +23. As a CodeMie developer, I want bubble reads to stay fail-soft and read-only, so that Cursor schema drift cannot crash analytics. +24. As a CodeMie developer, I want ADR 0001 respected (no invented concrete model for `default` beyond the display label Auto), so that Auto remains Auto in the UI while cost uses an explicit estimate policy. +25. As a CodeMie developer, I want Overview Est. cost to show “—” when nothing in view is measurable, so that a Cursor-only empty set does not show $0.00. +26. As a CodeMie developer, I want Overview token KPIs to use measured-set semantics rather than raw `tTotal > 0` alone when mixed with unknown sessions, so that provenance stays consistent with Cost tab helpers. +27. As a product owner, I want a follow-on ticket for Cursor Enterprise Team Analytics API integration scoped to what the API actually returns today, so that we do not promise token fields it does not have. +28. As a product owner, I want that follow-on to require both a configured credential and an explicit CLI opt-in flag before any network call, so that local-only analytics stays the default promise. +29. As a product owner, I want Team Analytics data (if integrated) rendered in a separate labelled report section, so that local sessions and team-API aggregates are never silently merged or double-counted. +30. As a product owner, I want Team Analytics pulls filtered to the requesting user’s own email (by-user), so that colleagues’ activity never appears in my personal CodeMie report. +31. As a product owner, I want a research spike in the follow-on for alternate billable-token sources (usage export, future API fields, other local stores), so that the recent-token gap is pursued without pretending bubbles still work for current Cursor builds. +32. As a product owner, I want documentation updated to say recent Cursor builds often write zero `tokenCount` on bubbles while tools still appear, so that operators understand the local floor. +33. As a QA reader, I want a fixture-driven Cursor session with bubble tokens + Auto model to render a non-zero estimate and partial badge, so that the Auto fallback is verifiable without live DB dependence. +34. As a QA reader, I want a fixture-driven Cursor session with no token signal to render “—” for cost and tokens (never Included), so that the empty path is verifiable. +35. As a QA reader, I want a fixture-driven Cursor session with priced non-Auto model + tokens to use that model’s rates, so that fallback does not override real prices. +36. As an analytics report reader, I want cache-read / context-bloat series to keep excluding sessions with no cache concept when only partial input/output exist, so that Cursor does not plot misleading zero-height bloat bars. +37. As an analytics report reader, I want Cost-by-agent charts to omit or dash agents whose sessions are all unmeasurable, so that a Cursor wedge does not appear as $0 “Included”. +38. As a CodeMie developer, I want no change to discovery unions of `composerHeaders` + transcripts for this honesty work, so that session counts stay stable while copy and pricing policy change. +39. As a CodeMie developer, I want no widening of max-age solely to harvest year-old token bubbles as a substitute for recent telemetry, so that we do not paper over the real gap. +40. As a stakeholder, I want the follow-on clearly labelled out-of-band from the honesty ship, so that agents can implement A without blocking on Enterprise research. + +## Implementation Decisions + +### Workstream A — Cost honesty (this ship) + +- Keep Cursor as an analytics-only agent: discover from local stores, tag `native-external`, gate with `--include-external`. Do not install or launch Cursor. +- Keep the existing usage provenance model on parsed sessions: `usageUnavailableReason` when no token signal; `usagePartial` + `tokensByModel` when sparse bubble tokens exist. Do not synthesize Claude-shaped per-message `usage` walks for bubbles. +- Keep cost enrichment’s adapter fallback: when the per-message usage map is empty, adopt `usageMeta.tokensByModel`. Do not add a dedicated Cursor branch to the per-message usage reader dispatcher unless a later change needs per-turn series (bubbles have no reliable per-turn chronology for series). +- **Estimate policy when tokens exist but `lookupPrice(model)` misses:** apply the published Claude Sonnet API-equivalent rate entry already used elsewhere in the pricing table (`claude-sonnet-4` family rates). Preserve the session’s displayed model name (Auto / unknown / original). Mark `usagePartial`. Prefer a real priced tracking-db model whenever lookup succeeds. +- **Report client:** remove the Included unpriced label. Unmeasurable → em dash for USD and tokens. Replace “covered by subscription” modal copy with language about missing local token signal or API-equivalent estimate. Keep the partial-usage note. +- **Overview / Cost empty state:** when the filtered session set has no measured usage, show dashes and a short subtitle that local token telemetry is absent for sessions in view (Cursor-heavy case). Do not change agent-chip filtering semantics. +- Respect ADR 0001: fail-soft, read-only, scoped bubble queries, `default` displayed as Auto, no invented invoice-grade certainty. +- Do not invent token counts for sessions whose bubbles only carry `{inputTokens:0,outputTokens:0}` or no `tokenCount`. + +### Workstream B — Follow-on (separate ticket after A) + +- Cursor Enterprise Team Analytics API remains **not integrated**. Guide fact to preserve: documented endpoints do **not** return token or cost fields; the API cannot alone close the billable-token gap. +- If/when integrated: require credential **and** explicit invocation opt-in; user-scoped `by-user` only; render as a **separate labelled section**; never silently merge into the local session table (unsolved reconciliation: no composerId join key on aggregates). +- Parallel research spike: identify whether any other local or exportable Cursor artifact now carries billable input/output for recent sessions; document negative evidence if none. Do not expand discovery age solely to resurface year-old bubble tokens as “the fix”. +- Update operator docs (`CURSOR_INTEGRATION` / external-integrations) to state that recent Cursor builds often omit nonzero bubble `tokenCount` while `toolFormerData` still works. + +### Confirmed test seams + +1. **Primary:** session cost record after enrichment — feed Cursor-shaped usage provenance through the enricher; assert tokens, estimate USD, partial flag, and absence of subscription semantics. +2. **Secondary:** report client formatting helpers / Overview empty-state contracts — unmeasurable → `—`; measured/partial → numeric; never `Included`. +3. **Follow-on only:** deep module behind a small interface for optional Team Analytics fetch → normalized user-scoped rows for a separate report section (not joined into local sessions). + +## Testing Decisions + +- Good tests assert external behaviour at the seams above (cost record fields; formatting outputs), not SQLite internals or DOM/Chart wiring. +- Prefer existing Vitest patterns around the cost enricher and native Cursor loader fixtures; extend those rather than inventing a third harness. +- Fixture cases for Workstream A: + - tokens + Auto → nonzero estimate, `usagePartial`, model label still Auto + - tokens + priced model → that model’s rates, no unnecessary fallback + - no token signal → `usageUnavailableReason`, cost/tokens format as unknown (dash), never Included + - regression: non-Cursor agents’ priced totals unchanged for the same fixtures +- Workstream B: no implementation tests in A; when B starts, test the opt-in gate (no network without flag+credential) and that team-API data cannot appear inside the local session table payload. +- Tests only when the implementing agent is explicitly asked to write/run them (repo policy), but the seams above are the intended attachment points. + +## Out of Scope + +- Changing agent-chip filters into model filters, or adding model chips (unless a later ticket asks). +- Inventing billable tokens from `contextTokensUsed`, transcript text length, or tool-call counts. +- Merging Team Analytics aggregates into per-session Cursor rows. +- Team-wide / leaderboard data in personal analytics. +- Silent network calls based solely on a configured API token. +- Issue #12 documentation-only Enterprise API write-up as a substitute for this honesty ship (may be folded into Workstream B docs). +- Widening default discovery max-age to harvest legacy bubble tokens. +- Renaming `readCursorBubbles` to a Map-style bubble index, or adding bubble memoization, unless a measured perf need appears. +- Adding a `gatherUsageDeduped('cursor')` branch solely for symmetry with the enricher fallback. + +## Further Notes + +- Live verification on one operator machine (2026-09-05 report): 469 Cursor sessions, 0 with tokens, 0 with `usagePartial`, 469 with `usageUnavailableReason`, 24 with tool calls. Nonzero bubble `tokenCount` composers existed only ~354–408 days ago and were absent from `composerHeaders`. This is why Cursor-only KPI collapse is data-faithful, not a chip bug. +- Original plan `we-the-issues-10-11-transient-crab` Steps 1–3 are largely shipped (bubbles + usageMeta + enricher fallback). Step 4 / Included copy / Auto estimate policy remain the actionable local gap. +- Domain vocabulary: analytics-only agent, `native-external`, `--include-external`, `composerHeaders`, `cursorDiskKV` bubbles, `usagePartial`, `usageUnavailableReason`, `tokensByModel`, API-equivalent estimate, ADR 0001 fail-soft. +- Tracker: this spec lives at `.scratch/cursor-analytics-cost-honesty/spec.md` with triage status `ready-for-agent`. Split implementation issues with `/to-tickets` if desired (A vs B). diff --git a/src/agents/plugins/cursor/cursor.bubbles.ts b/src/agents/plugins/cursor/cursor.bubbles.ts index 17ba59a37..d6d5d7973 100644 --- a/src/agents/plugins/cursor/cursor.bubbles.ts +++ b/src/agents/plugins/cursor/cursor.bubbles.ts @@ -22,8 +22,9 @@ */ import { existsSync } from 'fs'; -import { logger } from '../../../utils/logger.js'; +import { logger } from '@/utils/logger.js'; import { getCursorStateDbPath } from './cursor.paths.js'; +import { asNumber, asString, loadSqlite } from './cursor.sqlite.js'; /** Aggregated tool-outcome and token-usage signal for one Cursor Agent conversation's bubbles. */ export interface CursorBubbleSummary { @@ -41,14 +42,6 @@ function emptySummary(): CursorBubbleSummary { return { toolStatus: {}, totalInputTokens: 0, totalOutputTokens: 0, hasTokenSignal: false }; } -function asString(value: unknown): string | undefined { - return typeof value === 'string' && value.trim() ? value : undefined; -} - -function asNumber(value: unknown): number | undefined { - return typeof value === 'number' && Number.isFinite(value) ? value : undefined; -} - function asPositiveNumber(value: unknown): number { const num = asNumber(value); return num !== undefined && num > 0 ? num : 0; @@ -126,23 +119,6 @@ function applyTokenCount( return inputTokens > 0 || outputTokens > 0; } -/** - * `node:sqlite`, or null where it does not exist. - * - * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot be a - * static import: on Node 20 it would throw at module load and take the whole analytics run - * down. Cursor bubble enrichment from `state.vscdb` is optional — older runtimes simply see no - * tool/token signal from this source. - */ -async function loadSqlite(): Promise { - try { - return await import('node:sqlite'); - } catch (error) { - logger.debug('[cursor] node:sqlite unavailable — skipping bubble summary:', error); - return null; - } -} - /** * Summarize tool outcomes and token usage across every bubble belonging to one Cursor Agent * conversation, or a zeroed-out summary when the database cannot be read. @@ -160,7 +136,7 @@ export async function readCursorBubbles( return summary; } - const sqlite = await loadSqlite(); + const sqlite = await loadSqlite('bubble summary'); if (!sqlite) { return summary; } diff --git a/src/agents/plugins/cursor/cursor.paths.ts b/src/agents/plugins/cursor/cursor.paths.ts index d645e8822..de1b60605 100644 --- a/src/agents/plugins/cursor/cursor.paths.ts +++ b/src/agents/plugins/cursor/cursor.paths.ts @@ -15,7 +15,7 @@ import { homedir } from 'os'; import { join } from 'path'; -import { resolveHomeDir } from '../../../utils/paths.js'; +import { resolveHomeDir } from '@/utils/paths.js'; /** `~/.cursor`, or `$CURSOR_HOME` when set. */ export function getCursorHome(): string { diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index 79b63b85f..46cd035d6 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -82,7 +82,7 @@ import { transcriptStampWindow, userQueryText, } from './cursor.transcript.js'; -import { logger } from '../../../utils/logger.js'; +import { logger } from '@/utils/logger.js'; const DEFAULT_MAX_AGE_DAYS = 30; const MS_PER_DAY = 24 * 60 * 60 * 1000; diff --git a/src/agents/plugins/cursor/cursor.sqlite.ts b/src/agents/plugins/cursor/cursor.sqlite.ts new file mode 100644 index 000000000..728487f78 --- /dev/null +++ b/src/agents/plugins/cursor/cursor.sqlite.ts @@ -0,0 +1,49 @@ +/** + * Shared read-only helpers for the Cursor plugin's SQLite readers. + * + * Every reader here follows the same fail-soft contract (ADR 0001): an absent database, an old + * Node without `node:sqlite`, a renamed table/column, or a corrupt/locked file degrades to + * "no enrichment" rather than throwing. These helpers hold the parts that were otherwise + * copy-pasted across `cursor.tracking-db.ts`, `cursor.state-db.ts`, `cursor.bubbles.ts`, and + * `cursor.usage-fetch.ts`. + */ + +import { logger } from '@/utils/logger.js'; + +/** + * `node:sqlite`, or null where it does not exist. + * + * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot be a + * static import: on Node 20 it would throw at module load and take the whole analytics run + * down. Every caller is optional enrichment, so an older runtime simply sees no signal from + * that source. `purpose` names what is being skipped, for the debug log only. + */ +export async function loadSqlite(purpose: string): Promise { + try { + return await import('node:sqlite'); + } catch (error) { + logger.debug(`[cursor] node:sqlite unavailable — skipping ${purpose}:`, error); + return null; + } +} + +/** A non-empty string, or undefined. */ +export function asString(value: unknown): string | undefined { + return typeof value === 'string' && value.trim() ? value : undefined; +} + +/** A finite number, or undefined. */ +export function asNumber(value: unknown): number | undefined { + return typeof value === 'number' && Number.isFinite(value) ? value : undefined; +} + +/** A positive finite epoch-ms timestamp, or undefined. */ +export function asEpochMs(value: unknown): number | undefined { + const num = asNumber(value); + return num !== undefined && num > 0 ? num : undefined; +} + +/** A loose boolean, tolerating the `1`/`'true'`/`'1'` shapes SQLite/JSON rows use. */ +export function asBoolean(value: unknown): boolean { + return value === true || value === 1 || value === 'true' || value === '1'; +} diff --git a/src/agents/plugins/cursor/cursor.state-db.ts b/src/agents/plugins/cursor/cursor.state-db.ts index 2fc0c5a6a..39d4a98a7 100644 --- a/src/agents/plugins/cursor/cursor.state-db.ts +++ b/src/agents/plugins/cursor/cursor.state-db.ts @@ -22,8 +22,9 @@ */ import { existsSync } from 'fs'; -import { logger } from '../../../utils/logger.js'; +import { logger } from '@/utils/logger.js'; import { getCursorStateDbPath } from './cursor.paths.js'; +import { asBoolean, asEpochMs, asNumber, asString, loadSqlite } from './cursor.sqlite.js'; /** What `composerHeaders` knows about one Cursor Agent conversation. */ export interface CursorComposerHeader { @@ -64,23 +65,6 @@ interface ComposerRow { isDraft?: unknown; } -function asString(value: unknown): string | undefined { - return typeof value === 'string' && value.trim() ? value : undefined; -} - -function asNumber(value: unknown): number | undefined { - return typeof value === 'number' && Number.isFinite(value) ? value : undefined; -} - -function asEpochMs(value: unknown): number | undefined { - const num = asNumber(value); - return num !== undefined && num > 0 ? num : undefined; -} - -function asBoolean(value: unknown): boolean { - return value === true || value === 1 || value === 'true' || value === '1'; -} - /** * `workspaceIdentifier.uri.fsPath` may be a plain string field, or (rarer, seen on some Cursor * builds) a `file://…` URI string in place of the object. Both decode to the same absolute @@ -148,17 +132,7 @@ function composerIdFromKey(key: unknown): string | undefined { return asString(segments[segments.length - 1]); } -function normalizeHeader(source: { - composerId?: unknown; - workspaceIdentifier?: unknown; - activeBranch?: unknown; - createdOnBranch?: unknown; - createdAt?: unknown; - updatedAt?: unknown; - totalLinesAdded?: unknown; - totalLinesRemoved?: unknown; - filesChangedCount?: unknown; -}): Omit { +function normalizeHeader(source: ComposerRow): Omit { return { projectPath: extractProjectPath(source.workspaceIdentifier), branch: extractBranch(source), @@ -170,23 +144,6 @@ function normalizeHeader(source: { }; } -/** - * `node:sqlite`, or null where it does not exist. - * - * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot be a - * static import: on Node 20 it would throw at module load and take the whole analytics run - * down. Cursor session discovery from `state.vscdb` is optional — older runtimes simply see no - * Cursor sessions from this source. - */ -async function loadSqlite(): Promise { - try { - return await import('node:sqlite'); - } catch (error) { - logger.debug('[cursor] node:sqlite unavailable — skipping composer index:', error); - return null; - } -} - /** * Build the composerId → header index, or an empty map when the database cannot be read. * @@ -202,7 +159,7 @@ export async function readCursorComposerIndex( return index; } - const sqlite = await loadSqlite(); + const sqlite = await loadSqlite('composer index'); if (!sqlite) { return index; } diff --git a/src/agents/plugins/cursor/cursor.tracking-db.ts b/src/agents/plugins/cursor/cursor.tracking-db.ts index b035934a7..ffd5dedfb 100644 --- a/src/agents/plugins/cursor/cursor.tracking-db.ts +++ b/src/agents/plugins/cursor/cursor.tracking-db.ts @@ -16,9 +16,10 @@ */ import { existsSync } from 'fs'; -import { logger } from '../../../utils/logger.js'; +import { logger } from '@/utils/logger.js'; import { CURSOR_AUTO_MODEL_LABEL, CURSOR_AUTO_MODEL_SENTINEL } from './cursor.constants.js'; import { getCursorTrackingDbPath } from './cursor.paths.js'; +import { asEpochMs, asString, loadSqlite } from './cursor.sqlite.js'; /** What the tracking database knows about one conversation. */ export interface CursorConversationActivity { @@ -67,31 +68,6 @@ interface ActivityRow { lastMs?: unknown; } -function asString(value: unknown): string | undefined { - return typeof value === 'string' && value.trim() ? value : undefined; -} - -function asEpochMs(value: unknown): number | undefined { - return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined; -} - -/** - * `node:sqlite`, or null where it does not exist. - * - * The repository supports Node >= 20 and `node:sqlite` only landed in 22.5, so this cannot - * be a static import: on Node 20 it would throw at module load and take the whole analytics - * run down. Cursor enrichment is optional, so an older runtime simply gets transcript-only - * rows. - */ -async function loadSqlite(): Promise { - try { - return await import('node:sqlite'); - } catch (error) { - logger.debug('[cursor] node:sqlite unavailable — skipping tracking enrichment:', error); - return null; - } -} - /** * Build the conversation → activity index, or an empty map when the database cannot be read. * @@ -107,7 +83,7 @@ export async function readCursorTrackingIndex( return index; } - const sqlite = await loadSqlite(); + const sqlite = await loadSqlite('tracking enrichment'); if (!sqlite) { return index; } diff --git a/src/agents/plugins/cursor/cursor.transcript.ts b/src/agents/plugins/cursor/cursor.transcript.ts index 1e6e139dc..7a9e987d7 100644 --- a/src/agents/plugins/cursor/cursor.transcript.ts +++ b/src/agents/plugins/cursor/cursor.transcript.ts @@ -12,7 +12,7 @@ */ import { readFileSync } from 'fs'; -import { logger } from '../../../utils/logger.js'; +import { logger } from '@/utils/logger.js'; /** A `tool_use` block inside an assistant message. */ interface CursorToolUseBlock { diff --git a/src/agents/plugins/cursor/cursor.usage-fetch.ts b/src/agents/plugins/cursor/cursor.usage-fetch.ts index 4717d5fd1..5361e4476 100644 --- a/src/agents/plugins/cursor/cursor.usage-fetch.ts +++ b/src/agents/plugins/cursor/cursor.usage-fetch.ts @@ -32,6 +32,7 @@ import { existsSync } from 'node:fs'; import { logger } from '@/utils/logger.js'; import { getCursorStateDbPath } from './cursor.paths.js'; +import { loadSqlite } from './cursor.sqlite.js'; import { parseCursorUsageCsv, type CursorUsageImport } from './cursor.usage-csv.js'; /** The cookie Cursor's dashboard authenticates with: `::`. */ @@ -75,16 +76,6 @@ function hostOf(url: string): string { } } -async function loadSqlite(): Promise { - try { - return await import('node:sqlite'); - } catch { - // Node < 22.5 has no node:sqlite. Same fail-soft contract as the rest of the plugin. - logger.debug('[cursor] node:sqlite unavailable; cannot read the session cookie'); - return null; - } -} - /** * Read the signed-in session cookie out of Cursor's own state database. * @@ -114,7 +105,7 @@ export async function readCursorSessionCookie( logger.debug('[cursor] no state database; cannot read the session cookie'); return undefined; } - const sqlite = await loadSqlite(); + const sqlite = await loadSqlite('the session cookie read'); if (!sqlite) { return undefined; } @@ -125,9 +116,9 @@ export async function readCursorSessionCookie( const rows = db .prepare( `SELECT value FROM ItemTable - WHERE key LIKE '%${COOKIE_NAME}%' OR key LIKE 'cursorAuth%'` + WHERE key LIKE ? OR key LIKE 'cursorAuth%'` ) - .all() as { value?: unknown }[]; + .all(`%${COOKIE_NAME}%`) as { value?: unknown }[]; for (const row of rows) { const value = typeof row.value === 'string' ? row.value.trim() : undefined; if (value && COOKIE_SHAPE.test(value)) { diff --git a/src/cli/commands/analytics/types.ts b/src/cli/commands/analytics/types.ts index 66924d048..5f965462a 100644 --- a/src/cli/commands/analytics/types.ts +++ b/src/cli/commands/analytics/types.ts @@ -251,11 +251,6 @@ export interface AnalyticsOptions { scanNative?: boolean; /** When true (via --include-external), include non-CodeMie-owned native sessions in output (matches pre-fix behavior). */ includeExternal?: boolean; - /** - * When true (via --cursor-team-analytics), pull the report owner's own Cursor Team Analytics - * aggregates. Requires CURSOR_TEAM_ANALYTICS_API_KEY as well — the flag alone makes no call, - * and neither does the credential alone. - */ /** Path to a Cursor usage-events CSV exported from the Cursor dashboard (no network call). */ cursorUsageCsv?: string; /** From 9f82069d6f4114eb227ac9859d54148cee3bbea1 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:33 +0300 Subject: [PATCH 27/34] fix(analytics): restore Cursor session durations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `composerHeaders` names its last-update stamp `lastUpdatedAt`. The reader looked for `updatedAt`, a key no real row carries, so every window collapsed to its creation instant: all 42 Cursor sessions in a real report showed a zero duration, making their Activity and Efficiency figures meaningless and leaving nothing for the usage-CSV matcher to match a timestamp against. Reads `lastUpdatedAt` first and keeps `updatedAt` as a fallback. A header that dates only its creation — about half of a real table — now closes the open end from the tracking database's recorded edits instead of mirroring `createdAt`. On real data: 17 of 42 sessions gain a genuine window, median 15.4 minutes. The fixture helper now writes what Cursor writes, with the legacy spelling behind an explicit flag so the fallback stays covered. Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_01KQwQ1VNMjpMrxk1EB9eoyF --- src/agents/plugins/cursor/cursor.session.ts | 23 ++++-- src/agents/plugins/cursor/cursor.state-db.ts | 8 ++- .../__tests__/native-loader-cursor.test.ts | 70 ++++++++++++++++++- 3 files changed, 91 insertions(+), 10 deletions(-) diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index 46cd035d6..6be2d0ba9 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -353,20 +353,29 @@ function applyBranch(messages: CursorNativeMessage[], branch: string | undefined * When a conversation ran, preferring `composerHeaders`'s own timestamps over anything derived. * * A header can record only one end of the window (Cursor's own writes are not guaranteed - * complete either) — in that case the other end mirrors it rather than falling through to a - * weaker source for half the answer and a stronger one for the other half. + * complete either). The header always wins for the end it does record; the open end falls + * through to the recorded edit times rather than mirroring the closed one, which would claim a + * zero-length session for work that plainly ran on. */ function resolveWindow( header: CursorComposerHeader | undefined, filePath: string, activity: CursorConversationActivity | undefined ): { createdAt: number; updatedAt: number } | undefined { - if (header?.createdAt !== undefined || header?.updatedAt !== undefined) { - const createdAt = header.createdAt ?? header.updatedAt!; - const updatedAt = header.updatedAt ?? header.createdAt!; - return { createdAt, updatedAt: Math.max(createdAt, updatedAt) }; + if (header?.createdAt === undefined && header?.updatedAt === undefined) { + return activityWindow(filePath, activity); } - return activityWindow(filePath, activity); + + const createdAt = header.createdAt ?? header.updatedAt!; + if (header.updatedAt !== undefined) { + return { createdAt, updatedAt: Math.max(createdAt, header.updatedAt) }; + } + + // Only one end recorded. Mirroring `createdAt` would report a zero-length session for work + // that demonstrably continued — about half of a real `composerHeaders` table dates only its + // creation — so the weaker sources close the open end, and only that end. + const derived = activityWindow(filePath, activity); + return { createdAt, updatedAt: Math.max(createdAt, derived?.updatedAt ?? createdAt) }; } /** diff --git a/src/agents/plugins/cursor/cursor.state-db.ts b/src/agents/plugins/cursor/cursor.state-db.ts index 39d4a98a7..365388bd9 100644 --- a/src/agents/plugins/cursor/cursor.state-db.ts +++ b/src/agents/plugins/cursor/cursor.state-db.ts @@ -36,7 +36,7 @@ export interface CursorComposerHeader { branch?: string; /** Epoch ms the conversation was created, when recorded. */ createdAt?: number; - /** Epoch ms the conversation was last updated, when recorded. */ + /** Epoch ms the conversation was last updated (`lastUpdatedAt`), when recorded. */ updatedAt?: number; /** Total lines added across the conversation, when recorded. */ linesAdded?: number; @@ -58,6 +58,7 @@ interface ComposerRow { activeBranch?: unknown; createdOnBranch?: unknown; createdAt?: unknown; + lastUpdatedAt?: unknown; updatedAt?: unknown; totalLinesAdded?: unknown; totalLinesRemoved?: unknown; @@ -137,7 +138,10 @@ function normalizeHeader(source: ComposerRow): Omit { activeBranch: row.branch ? { branchName: row.branch } : undefined, createdOnBranch: row.createdOnBranch, createdAt: row.createdAt, - updatedAt: row.updatedAt, + // Real `composerHeaders` rows name the last-update stamp `lastUpdatedAt`; `updatedAt` is + // only the fallback spelling. Fixtures default to what Cursor actually writes. + ...(row.legacyUpdatedAtKey ? { updatedAt: row.updatedAt } : { lastUpdatedAt: row.updatedAt }), totalLinesAdded: row.linesAdded, totalLinesRemoved: row.linesRemoved, filesChangedCount: row.filesChangedCount, @@ -585,6 +592,67 @@ describe.skipIf(!hasNodeSqlite())('loadNativeSessions — Cursor composerHeaders expect(row.endEvent!.data.endTime).toBe(headerUpdated); }); + it('gives a Cursor session a real duration from the header’s own lastUpdatedAt stamp', async () => { + // Regression: the reader used to look for `updatedAt`, a key `composerHeaders` never writes. + // Every Cursor session therefore collapsed to a zero-width window — `resolveWindow` mirrored + // `createdAt` — which zeroed every Cursor duration in the report and left nothing for the + // usage-CSV matcher to match against. + const created = Date.now() - 10 * HOUR; + const updated = created + 25 * 60 * 1000; + await writeComposerHeaders([ + { composerId: 'duration-conv', projectPath: projectDir, createdAt: created, updatedAt: updated }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.startEvent!.data.startTime).toBe(created); + expect(row.endEvent!.data.endTime).toBe(updated); + expect(row.endEvent!.data.duration).toBe(25 * 60 * 1000); + }); + + it('still reads a header that spells the stamp `updatedAt`', async () => { + const created = Date.now() - 8 * HOUR; + const updated = created + 5 * 60 * 1000; + await writeComposerHeaders([ + { + composerId: 'legacy-conv', + projectPath: projectDir, + createdAt: created, + updatedAt: updated, + legacyUpdatedAtKey: true, + }, + ]); + + const { rows } = await runLoader(); + + expect(cursorRows(rows)[0].endEvent!.data.duration).toBe(5 * 60 * 1000); + }); + + it('widens a header that dates only its creation with the tracking database’s last edit', async () => { + // Half of a real `composerHeaders` table carries `createdAt` and no last-update stamp. + // Mirroring `createdAt` for those would report a zero duration for work that demonstrably + // continued, so the recorded edit times fill the open end. + const created = FIRST_EDIT_MS - HOUR; + await writeComposerHeaders([ + { composerId: 'open-ended-conv', projectPath: projectDir, createdAt: created }, + ]); + await writeTrackingDb([ + { + conversationId: 'open-ended-conv', + fileName: join(projectDir, 'src', 'app.ts'), + model: 'claude-4.5-sonnet', + timestamp: LAST_EDIT_MS, + }, + ]); + + const { rows } = await runLoader(); + const row = cursorRows(rows)[0]; + + expect(row.startEvent!.data.startTime).toBe(created); + expect(row.endEvent!.data.endTime).toBe(LAST_EDIT_MS); + }); + it('resolves the composerId from a prefixed key when the JSON value carries none', async () => { // `key` on the key/value table shape commonly prefixes the id (e.g. // `composerHeaderData:`); the reader takes the last `:`-delimited segment. From cb3a5f76d9368612e2d1dd8dcf3173877f6cac65 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:38 +0300 Subject: [PATCH 28/34] feat(analytics): make the Cursor usage CSV a first-class cost source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The import used to be a panel of its own. A run could pull in 39,952,466 real tokens and $25.25 of real cost and still have every headline figure in the report ignore them. `cursor-usage-loader.ts` follows the OTEL precedent — the existing answer to "a flat per-event file that must behave like sessions" — and converts the export into `RawSessionData` plus a canonical `SessionCostIndex`. The aggregator, formatter, exporter and report client then treat it like anything else, so no consumer needs a special case and none can forget one. Each event is matched to the Cursor session whose activity window contains its timestamp. Several containing windows means the data cannot say which session spent the tokens, so the event goes to a per-day rollup rather than a guess — the same refusal 81dbeb1 makes for an ambiguous Cursor slug. Restoring session durations first is what makes this work at all: on the real export, 20 of 61 events now land on a session, the rest in 3 daily rollups, and the totals still sum to the file's own exactly once. Every line the loader produces carries a new `ModelCost.costBasis: 'vendor-billed'` — Cursor billed that amount, CodeMie only recorded it. Absent elsewhere, so every existing producer keeps today's estimate semantics. Also fixes, by construction rather than by patch: - Overview and Cost read one number, not two that disagree. - "Tokens by model" and "Cost by model" show the same models, unsuffixed. - Coverage by agent reports Cursor as priced for the sessions the export reached. - `--cursor-usage-csv` without a report flag is no longer silently discarded: it is resolved right after `source.load()` and prints what it imported, so the terminal totals and `--export` see it too. - A CSV-only run no longer needs a local Cursor session to show anything. Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_01KQwQ1VNMjpMrxk1EB9eoyF --- .../integration/external-integrations.md | 6 +- docs/ANALYTICS-REPORT.md | 48 +++- docs/CURSOR_INTEGRATION.md | 15 +- src/agents/plugins/cursor/cursor.usage-csv.ts | 5 +- .../__tests__/cursor-usage-loader.test.ts | 195 +++++++++++++ src/cli/commands/analytics/cost/types.ts | 9 + .../commands/analytics/cursor-usage-loader.ts | 269 ++++++++++++++++++ src/cli/commands/analytics/index.ts | 206 +++++++++----- .../report/__tests__/payload-builder.test.ts | 55 ++++ .../commands/analytics/report/client/app.js | 2 +- 10 files changed, 726 insertions(+), 84 deletions(-) create mode 100644 src/cli/commands/analytics/__tests__/cursor-usage-loader.test.ts create mode 100644 src/cli/commands/analytics/cursor-usage-loader.ts diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index de98721b9..f732ee5ee 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -313,7 +313,11 @@ tagged `native-external` and appear only with `--include-external`. 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 `, `src/agents/plugins/cursor/cursor.usage-csv.ts`) — a local file read -with no credential. `Kind=Included` in that CSV is a billing category, not zero usage: verified +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 diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index 136400dd2..da26de655 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -371,9 +371,21 @@ Things worth knowing about the export format: imported whole, since there is no one else's data in it to exclude. If the filter matches nothing, CodeMie warns and lists the addresses actually present rather than showing an empty section. -- **It is never merged into your sessions.** Export rows are per-event with no session id, so - there is no key to join them on. The section sits beside the session table and contributes to no - cost figure elsewhere in the report. Read them side by side, not summed. +- **Every event is counted once, everywhere.** Export rows are per-event with no session id, so + there is no key to join them on directly. CodeMie matches each event by *time* instead: an event + whose timestamp falls inside exactly one Cursor session's activity window is attributed to that + session. Anything else — no window contains it, or several overlapping ones do — lands in a + `Cursor usage — ` daily rollup, which behaves as an ordinary session throughout the + report. CodeMie never picks between two candidate sessions; an ambiguous event goes to the + rollup rather than to a guess. + + The upshot: the Overview, Cost, Tools & Models and Coverage figures all include these tokens and + this cost, and they add up to the export's own totals exactly once. The **Cursor Usage CSV** tab + is the per-event detail view, not a separate total to add on. +- **These are Cursor's figures, not CodeMie's estimate.** Every cost line derived from the export + is tagged `costBasis: "vendor-billed"` in the report payload — Cursor billed that amount, and + CodeMie merely recorded it. Every other cost line in the report is computed from tokens and a + pricing table. @@ -468,7 +480,8 @@ With `--include-external`, Cursor sessions appear. To see the behaviour that sur most, **deselect every agent except Cursor** in the top bar. **Expect:** Overview's Input/Output/Total token KPIs and Est. cost all go to `—`, with a note -saying local token telemetry is absent — *and the tool-call tables keep working*. +saying local token telemetry is absent — *and the tool-call tables keep working*. (This is the +state *without* a usage export; step 4 is how those dashes become numbers.) That is correct, not a bug: recent Cursor builds record no billable token counts locally. If you instead see `$0.00`, `0`, or the word `Included` anywhere, that **is** a bug — those were removed @@ -486,8 +499,26 @@ codemie analytics --report --open --include-external \ --cursor-usage-csv ~/Downloads/team-usage-events-*.csv ``` -**Expect:** a new **Cursor Usage CSV** entry in the sidebar (it is hidden when no export is -imported) showing Events, Total tokens and Cost, plus by-model and by-day tables. +**Expect**, before any table is printed: + +``` + Imported 61 Cursor usage event(s): 39,952,466 tokens, $25.25 (Cursor's own billing). + 20 attributed to a Cursor session; 41 in 3 daily rollup(s) — no session window matched them unambiguously. +``` + +Those two lines print for **every** run that passes the flag, report or not — so +`codemie analytics --cursor-usage-csv f.csv` on its own tells you what it imported. + +In the report, expect a new **Cursor Usage CSV** entry in the sidebar (hidden when no export is +imported) showing Events, Total tokens and Cost, plus by-model and by-day tables — and the same +figures folded into the rest of the report: + +- Overview's **Est. cost** and Cost's **Total est. cost** agree, both including the import. +- Cursor's models (`auto`, `cursor-grok-*`, …) appear in **both** "Cost by model" and + "Tokens by model", spelled the same way in each. +- **Coverage by agent** reports Cursor as priced for the sessions the export reached. +- Deselecting every agent except Cursor still shows real figures — the rollups are Cursor + sessions like any other. Sanity-check the totals against the file itself. (This handles both export shapes, the `Free` cost cells, and the CRLF line endings the export ships — a naive `awk` over the last column @@ -510,8 +541,9 @@ else: EOF ``` -The report's Events, Total tokens and Cost KPIs should match that line exactly. **Every row saying -`Included` still contributes** — that word is a billing category, not zero usage. +The report's Events, Total tokens and Cost KPIs should match that line exactly — and so should the +`Imported …` line the command printed, since each event is counted once and only once. **Every row +saying `Included` still contributes** — that word is a billing category, not zero usage. **If the section is missing**, the terminal tells you which check failed: diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index 8af15a781..50e591a40 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -110,7 +110,8 @@ trade an honest blank for a confident wrong number. The gap above is *local*. Cursor's dashboard still exports the billable ledger: **Usage → Export** produces a `team-usage-events-*.csv` carrying per-event input, cache-write, cache-read, output and total tokens, usually with a `Cost` column. Import it with `--cursor-usage-csv ` (no network -call, no credential) and CodeMie renders it as a separate **Cursor Usage CSV** report section. +call, no credential) and CodeMie converts it into ordinary sessions, so its tokens and cost reach +every figure in the report. The **Cursor Usage CSV** tab remains as the per-event detail view. Two facts that decide how it must be read: @@ -123,8 +124,16 @@ Two facts that decide how it must be read: instead and has no cost at all. Both parse; the section dashes the money and says why when `Cost` is missing. Some `Cost` cells also read `Free` and contribute zero. -Export rows are per-event with no `composerId`, so they are never joined to local sessions or added -to any other cost figure — the report shows Cursor's own numbers beside CodeMie's, not summed in. +Export rows carry no `composerId`, so they are matched on **time** instead: an event whose +timestamp falls inside exactly one Cursor session's activity window is attributed to that session +and overwrites its empty usage. An event that no window contains, or that several overlapping +windows contain, goes to a `Cursor usage — ` daily rollup — CodeMie refuses to choose between +two candidate sessions, the same way it refuses to guess an ambiguous project slug. Either way each +event is counted exactly once, so the report's totals equal the export's own. + +Every cost line this produces is tagged `costBasis: "vendor-billed"`: Cursor billed that amount and +CodeMie recorded it. Every other cost line in the report is CodeMie's estimate from a pricing +table, and the report keeps that distinction visible. `--cursor-usage-fetch` can download the same CSV instead, but it is **opt-in and unsupported**: it needs `CURSOR_USAGE_EXPORT_URL` (CodeMie ships no undocumented endpoint) and `CURSOR_SESSION_TOKEN` diff --git a/src/agents/plugins/cursor/cursor.usage-csv.ts b/src/agents/plugins/cursor/cursor.usage-csv.ts index 0b5d80f6d..b4288896b 100644 --- a/src/agents/plugins/cursor/cursor.usage-csv.ts +++ b/src/agents/plugins/cursor/cursor.usage-csv.ts @@ -14,8 +14,9 @@ * while at least one variant ships `Requests` instead and has no cost at all. Tokens are the * durable part; cost is optional. * - * Rows are per-event with no composerId, so they cannot be joined to local sessions. The report - * renders them as their own labelled section for exactly that reason. + * Rows are per-event with no composerId, so they cannot be joined to local sessions by id. This + * module's job ends at parsing; `cursor-usage-loader.ts` matches the events to sessions by time + * and converts them into the shapes the analytics pipeline consumes. */ import { readFileSync } from 'node:fs'; diff --git a/src/cli/commands/analytics/__tests__/cursor-usage-loader.test.ts b/src/cli/commands/analytics/__tests__/cursor-usage-loader.test.ts new file mode 100644 index 000000000..456ab6a77 --- /dev/null +++ b/src/cli/commands/analytics/__tests__/cursor-usage-loader.test.ts @@ -0,0 +1,195 @@ +/** + * The Cursor usage export, converted into the shapes the rest of analytics already speaks. + * + * These tests drive the real parser (`loadCursorUsageCsv`) over the real fixtures rather than + * hand-built event objects, so what is asserted here is what a Cursor dashboard export actually + * produces. The verified 2026-09-05 export — 61 events, 39,952,466 tokens, $25.25 — is the + * yardstick: whatever the matcher decides, the run's totals must equal that file's totals + * exactly once. Conservation is the property that makes the conversion safe to fold into every + * headline figure; double-counting or dropping a remainder is the failure this file exists to + * catch. + */ + +import { describe, it, expect } from 'vitest'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { buildCursorUsageSessions } from '../cursor-usage-loader.js'; +import { loadCursorUsageCsv, parseCursorUsageCsv } from '../../../../agents/plugins/cursor/cursor.usage-csv.js'; +import type { CursorUsageImport } from '../../../../agents/plugins/cursor/cursor.usage-csv.js'; +import type { RawSessionData } from '../data-loader.js'; +import type { SessionCostIndex } from '../cost/types.js'; + +const FIXTURES = join(fileURLToPath(new URL('.', import.meta.url)), '..', '..', '..', '..', 'agents', 'plugins', 'cursor', '__tests__', 'fixtures'); + +function load(name: string): CursorUsageImport { + const usage = loadCursorUsageCsv(join(FIXTURES, name)); + if (!usage) { + throw new Error(`fixture ${name} did not parse as a Cursor usage export`); + } + return usage; +} + +function totals(index: SessionCostIndex): { costUSD: number; tokens: number } { + return { + costUSD: [...index.values()].reduce((s, c) => s + c.costUSD, 0), + tokens: [...index.values()].reduce((s, c) => s + c.tokens.total, 0), + }; +} + +/** A Cursor session covering [start, end], shaped the way the native loader synthesizes one. */ +function cursorSession(sessionId: string, start: number, end: number): RawSessionData { + return { + sessionId, + startEvent: { + recordId: sessionId, + type: 'session_start', + timestamp: start, + codeMieSessionId: sessionId, + agentName: 'cursor', + syncStatus: 'synced', + data: { provider: 'native', workingDirectory: '/repo', startTime: start }, + }, + endEvent: { + recordId: `${sessionId}-end`, + type: 'session_end', + timestamp: end, + codeMieSessionId: sessionId, + agentName: 'cursor', + syncStatus: 'synced', + data: { endTime: end, duration: end - start, totalTurns: 1 }, + }, + deltas: [], + }; +} + +describe('buildCursorUsageSessions — totals are conserved', () => { + it('accounts for the verified export exactly once when nothing matches a session', () => { + const usage = load('cursor-usage-events-full.csv'); + expect(usage.totals).toMatchObject({ events: 61 }); + expect(usage.totals.tokens.total).toBe(39952466); + expect(usage.totals.costUSD).toBeCloseTo(25.25, 10); + + const built = buildCursorUsageSessions(usage, []); + + expect(built.matched).toBe(0); + expect(built.unmatched).toBe(61); + expect(totals(built.costIndex).tokens).toBe(39952466); + expect(totals(built.costIndex).costUSD).toBeCloseTo(25.25, 10); + expect(built.summary.totalCostUSD).toBeCloseTo(25.25, 10); + }); + + it('still accounts for it exactly once when some events land on real sessions', () => { + const usage = load('cursor-usage-events-full.csv'); + // One session wide enough to swallow a good share of the export, so the assertion is about + // matched and remaining usage summing back to the file — not about an empty match path. + const stamps = usage.events.map((e) => Date.parse(e.date)).sort((a, b) => a - b); + const mid = stamps[Math.floor(stamps.length / 2)]; + const built = buildCursorUsageSessions(usage, [cursorSession('conv-a', stamps[0], mid)]); + + expect(built.matched).toBeGreaterThan(0); + expect(built.matched + built.unmatched).toBe(61); + expect(totals(built.costIndex).tokens).toBe(39952466); + expect(totals(built.costIndex).costUSD).toBeCloseTo(25.25, 10); + }); + + it('keeps tokens and drops cost for the export variant that ships no Cost column', () => { + const withCost = load('cursor-usage-events.csv'); + const text = [ + '"Date","User","Kind","Model","Input (w/ Cache Write)","Input (w/o Cache Write)","Cache Read","Output Tokens","Total Tokens","Requests"', + ...withCost.events.map( + (e) => + `"${e.date}","${e.user}","${e.kind}","${e.model}","${e.tokens.cacheCreation}","${e.tokens.input}","${e.tokens.cacheRead}","${e.tokens.output}","${e.tokens.total}","1"` + ), + ].join('\n'); + const usage = parseCursorUsageCsv(text); + expect(usage?.hasCost).toBe(false); + + const built = buildCursorUsageSessions(usage!, []); + + expect(totals(built.costIndex).tokens).toBe(withCost.totals.tokens.total); + expect(totals(built.costIndex).costUSD).toBe(0); + expect(built.summary.totalCostUSD).toBe(0); + }); +}); + +describe('buildCursorUsageSessions — matching events to sessions', () => { + const usage = load('cursor-usage-events.csv'); + const first = usage.events.reduce((a, b) => (Date.parse(a.date) < Date.parse(b.date) ? a : b)); + const firstMs = Date.parse(first.date); + + it('gives a containing session that event’s usage', () => { + // Tight enough that only this one event is inside, so the assertion is about attribution + // rather than about how many neighbours the window happened to sweep up. + const built = buildCursorUsageSessions(usage, [cursorSession('conv-a', firstMs - 500, firstMs + 500)]); + + const cost = built.costIndex.get('conv-a'); + expect(cost).toBeDefined(); + expect(cost!.tokens.total).toBe(first.tokens.total); + expect(cost!.costUSD).toBeCloseTo(first.costUSD, 10); + expect(cost!.priced).toBe(true); + expect(cost!.usageUnavailableReason).toBeUndefined(); + expect(built.matched).toBe(1); + }); + + it('sends an event inside two overlapping windows to the remainder rather than guessing', () => { + const built = buildCursorUsageSessions(usage, [ + cursorSession('conv-a', firstMs - 60_000, firstMs + 60_000), + cursorSession('conv-b', firstMs - 30_000, firstMs + 90_000), + ]); + + expect(built.costIndex.has('conv-a')).toBe(false); + expect(built.costIndex.has('conv-b')).toBe(false); + expect(built.matched).toBe(0); + expect(totals(built.costIndex).tokens).toBe(usage.totals.tokens.total); + }); + + it('collects everything unmatched into one pseudo-session per local day', () => { + const built = buildCursorUsageSessions(usage, []); + + const ids = built.rawSessions.map((r) => r.sessionId).sort(); + expect(ids).toEqual(usage.byDay.map((d) => `cursor-usage:${d.day}`).sort()); + for (const day of usage.byDay) { + const cost = built.costIndex.get(`cursor-usage:${day.day}`); + expect(cost!.tokens.total).toBe(day.tokens.total); + expect(cost!.costUSD).toBeCloseTo(day.costUSD, 10); + } + // A pseudo-session must be an ordinary Cursor session to the rest of the pipeline. + const raw = built.rawSessions[0]; + expect(raw.startEvent!.agentName).toBe('cursor'); + expect(raw.deltas.length).toBeGreaterThan(0); + }); + + it('does not synthesize a pseudo-session for a day whose events all matched', () => { + const sameDay = usage.events.filter((e) => e.day === first.day).map((e) => Date.parse(e.date)); + const built = buildCursorUsageSessions(usage, [ + cursorSession('conv-a', Math.min(...sameDay) - 1000, Math.max(...sameDay) + 1000), + ]); + + expect(built.rawSessions.map((r) => r.sessionId)).not.toContain(`cursor-usage:${first.day}`); + expect(totals(built.costIndex).tokens).toBe(usage.totals.tokens.total); + }); +}); + +describe('buildCursorUsageSessions — provenance and model labels', () => { + const usage = load('cursor-usage-events-full.csv'); + + it('marks every CSV-derived model line as Cursor’s own billing', () => { + const built = buildCursorUsageSessions(usage, []); + + const lines = [...built.costIndex.values()].flatMap((c) => c.perModel); + expect(lines.length).toBeGreaterThan(0); + for (const line of lines) { + expect(line.costBasis).toBe('vendor-billed'); + expect(line.unpriced).toBe(false); + expect(line.estimated).toBeUndefined(); + } + }); + + it('leaves model names unsuffixed so one model cannot appear under two spellings', () => { + const built = buildCursorUsageSessions(usage, []); + + const models = new Set([...built.costIndex.values()].flatMap((c) => c.perModel.map((m) => m.model))); + expect(models).toContain('auto'); + expect([...models].some((m) => m.includes('(cursor)'))).toBe(false); + }); +}); diff --git a/src/cli/commands/analytics/cost/types.ts b/src/cli/commands/analytics/cost/types.ts index 6bba9b67f..7b0516ef1 100644 --- a/src/cli/commands/analytics/cost/types.ts +++ b/src/cli/commands/analytics/cost/types.ts @@ -27,6 +27,15 @@ export interface ModelCost { * `SessionCost.usagePartial`, so the figure is never read as an invoice. */ estimated?: boolean; + /** + * Where this line's `costUSD` came from, when it is not CodeMie's own estimate. + * + * `'vendor-billed'` means the vendor billed this exact amount and CodeMie merely recorded it — + * currently only rows converted from a Cursor usage export (`cursor-usage-loader.ts`). Absent + * everywhere else, which keeps today's meaning — a figure computed from tokens and a pricing + * table — as the default rather than something every existing producer has to restate. + */ + costBasis?: 'vendor-billed'; } /** One cumulative point in a session's token & cost growth series. */ diff --git a/src/cli/commands/analytics/cursor-usage-loader.ts b/src/cli/commands/analytics/cursor-usage-loader.ts new file mode 100644 index 000000000..bbc546117 --- /dev/null +++ b/src/cli/commands/analytics/cursor-usage-loader.ts @@ -0,0 +1,269 @@ +/** + * The Cursor usage export, converted into the analytics pipeline's own shapes. + * + * Cursor's local stores no longer carry billable token counts, so the dashboard's + * Usage → Export CSV is the only accurate record of what a Cursor session actually cost + * (see `cursor.usage-csv.ts` and `docs/CURSOR_INTEGRATION.md`). Rendering that file as its own + * isolated panel — which is what the first cut did — left every headline number in the report + * ignoring 39.9M real tokens and $25.25 of real cost. + * + * This module follows the OTEL precedent (`otel-loader.ts`), the existing answer to "a flat + * per-event file that has to behave like sessions": synthesize {@link RawSessionData} plus a + * canonical {@link SessionCostIndex}, hand both to the pipeline, and let the aggregator, the + * formatter, the exporter and the report client treat the result like any other session. No + * consumer needs a special case, so no consumer can forget one. + * + * Two rules keep the conversion honest: + * + * - **Conserved.** Every event lands in exactly one place. An event whose timestamp falls + * inside exactly one Cursor session's activity window is attributed to that session; anything + * else — no window, or several overlapping ones — goes to a per-day pseudo-session rather + * than to a guess. That refusal matches `81dbeb1`, which already declines to guess when a + * Cursor slug is ambiguous. Sum the output and you get the file's own totals, once. + * - **Attributed.** Every line this module produces carries `costBasis: 'vendor-billed'`. + * These are Cursor's own billed figures, not CodeMie's estimate from a pricing table, and + * that distinction has to survive the merge — it is the whole point of the honesty work. + * + * Overwriting a matched session's usage loses nothing: a local Cursor session carries $0 and + * zero tokens today, with a `usageUnavailableReason` explaining why. + */ + +import type { RawSessionData, SessionStartEvent, SessionEndEvent } from './data-loader.js'; +import type { MetricDelta } from '../../../agents/core/metrics/types.js'; +import type { SessionCost, SessionCostIndex, CostSummary, TokenUsage, ModelCost } from './cost/types.js'; +import { emptyUsage, addUsage } from './cost/cost-calculator.js'; +import type { CursorUsageEvent, CursorUsageImport } from '../../../agents/plugins/cursor/cursor.usage-csv.js'; +import { normalizeModelName } from '@/utils/model-normalizer.js'; + +/** The agent every synthesized session is attributed to — Cursor's rows are Cursor's. */ +const AGENT_NAME = 'cursor'; + +/** Prefix for a per-day pseudo-session id; `cursor-usage:`. */ +const PSEUDO_ID_PREFIX = 'cursor-usage:'; + +export interface CursorUsageSessions { + /** Pseudo-sessions for unmatched events. Matched events need no new session. */ + rawSessions: RawSessionData[]; + /** Cost rows for both matched real sessions and the pseudo-sessions. */ + costIndex: SessionCostIndex; + summary: CostSummary; + /** Events attributed to a real Cursor session. */ + matched: number; + /** Events that fell into a per-day pseudo-session instead. */ + unmatched: number; +} + +/** The window a session covers, from the events the native loader synthesized it with. */ +interface SessionWindow { + sessionId: string; + start: number; + end: number; +} + +/** Convert the export's token columns into the pipeline's normalized usage shape. */ +function toUsage(event: CursorUsageEvent): TokenUsage { + const { input, output, cacheRead, cacheCreation, total } = event.tokens; + return { + input, + output, + cacheRead, + cacheCreation, + // The export does not distinguish the 1h-TTL subset of cache creation, and inventing a split + // would misstate a figure Cursor never published. + cacheCreation1h: 0, + total, + }; +} + +/** + * The activity windows usable for matching. + * + * A zero-width window is kept: an event stamped at that exact instant is still unambiguously + * that session's. A session with no usable start is not — there is nothing to compare against. + */ +function windowsOf(sessions: RawSessionData[]): SessionWindow[] { + const windows: SessionWindow[] = []; + for (const session of sessions) { + const start = session.startEvent?.data.startTime; + if (start === undefined || !Number.isFinite(start) || start <= 0) { + continue; + } + const end = session.endEvent?.data.endTime; + windows.push({ + sessionId: session.sessionId, + start, + end: end !== undefined && Number.isFinite(end) && end > start ? end : start, + }); + } + return windows; +} + +/** + * The one session whose window contains this timestamp, or undefined. + * + * Several containing windows means the data cannot say which session spent the tokens. Picking + * the narrowest — the tactic `otel-loader.ts` uses for parallel subagents — is defensible there + * because those windows describe nested work; Cursor conversations run side by side, so the + * tightest window carries no such meaning and the choice would be a coin toss printed as fact. + */ +function containingSession(windows: SessionWindow[], ms: number): string | undefined { + let found: string | undefined; + for (const w of windows) { + if (ms < w.start || ms > w.end) { + continue; + } + if (found !== undefined) { + return undefined; // ambiguous — refuse to guess + } + found = w.sessionId; + } + return found; +} + +/** Roll a group of events up into one canonical cost row. */ +function toSessionCost(sessionId: string, events: CursorUsageEvent[]): SessionCost { + const perModelMap = new Map(); + const perModelCost = new Map(); + let tokens = emptyUsage(); + let costUSD = 0; + + for (const event of events) { + const usage = toUsage(event); + tokens = addUsage(tokens, usage); + costUSD += event.costUSD; + // Normalized so a Cursor spelling collapses onto the same key every other source uses; the + // name is otherwise left alone, with provenance carried by `costBasis` rather than a suffix + // that would split one model across two rows in every by-model chart. + const model = normalizeModelName(event.model || '(unknown)'); + perModelMap.set(model, addUsage(perModelMap.get(model) ?? emptyUsage(), usage)); + perModelCost.set(model, (perModelCost.get(model) ?? 0) + event.costUSD); + } + + const perModel: ModelCost[] = [...perModelMap.entries()] + .map(([model, modelTokens]): ModelCost => ({ + model, + tokens: modelTokens, + costUSD: perModelCost.get(model) ?? 0, + unpriced: false, + costBasis: 'vendor-billed', + })) + .sort((a, b) => b.costUSD - a.costUSD || b.tokens.total - a.tokens.total); + + return { + sessionId, + tokens, + costUSD, + perModel, + // Priced, but from Cursor's invoice rather than a native log — so `hadLog` stays false and + // no `agentSessionFile` is claimed for a file that does not exist. + priced: true, + hadLog: false, + }; +} + +/** One ordinary-looking Cursor session standing in for a day's unmatched events. */ +function pseudoSession(day: string, events: CursorUsageEvent[]): RawSessionData { + const sessionId = `${PSEUDO_ID_PREFIX}${day}`; + const stamps = events.map((e) => Date.parse(e.date)).filter((n) => Number.isFinite(n)); + const startTime = stamps.length ? Math.min(...stamps) : 0; + const endTime = stamps.length ? Math.max(...stamps) : 0; + const models = [...new Set(events.map((e) => normalizeModelName(e.model || '(unknown)')))]; + + const delta: MetricDelta = { + recordId: `${sessionId}-usage`, + sessionId, + agentSessionId: sessionId, + timestamp: startTime, + tools: {}, + models, + // Drives the session title, so the row reads as what it is rather than as a bare id. + userPrompts: [{ count: 1, text: `Cursor usage — ${day}` }], + syncStatus: 'synced', + syncAttempts: 0, + }; + + const startEvent: SessionStartEvent = { + recordId: sessionId, + type: 'session_start', + timestamp: startTime, + codeMieSessionId: sessionId, + agentName: AGENT_NAME, + syncStatus: 'synced', + // The export carries no project, and attributing a day's spend to whichever repo happened to + // be open would invent an association Cursor never recorded. + data: { provider: 'native', workingDirectory: 'Unknown', startTime }, + }; + + const endEvent: SessionEndEvent = { + recordId: `${sessionId}-end`, + type: 'session_end', + timestamp: endTime, + codeMieSessionId: sessionId, + agentName: AGENT_NAME, + syncStatus: 'synced', + data: { endTime, duration: Math.max(0, endTime - startTime), totalTurns: 1 }, + }; + + return { sessionId, startEvent, endEvent, deltas: [delta] }; +} + +/** + * Convert a parsed usage export into sessions and cost rows the pipeline already understands. + * + * `cursorSessions` should be the Cursor sessions in scope for this run; anything else simply + * cannot contain a Cursor usage event and only widens the chance of a false ambiguity. + */ +export function buildCursorUsageSessions( + usage: CursorUsageImport, + cursorSessions: RawSessionData[] +): CursorUsageSessions { + const windows = windowsOf(cursorSessions); + const byMatchedSession = new Map(); + const byDay = new Map(); + let matched = 0; + let unmatched = 0; + + for (const event of usage.events) { + const ms = Date.parse(event.date); + const sessionId = Number.isFinite(ms) ? containingSession(windows, ms) : undefined; + if (sessionId !== undefined) { + const group = byMatchedSession.get(sessionId); + if (group) { + group.push(event); + } else { + byMatchedSession.set(sessionId, [event]); + } + matched += 1; + continue; + } + const day = event.day || 'unknown'; + const group = byDay.get(day); + if (group) { + group.push(event); + } else { + byDay.set(day, [event]); + } + unmatched += 1; + } + + const costIndex: SessionCostIndex = new Map(); + for (const [sessionId, events] of byMatchedSession) { + costIndex.set(sessionId, toSessionCost(sessionId, events)); + } + + const rawSessions: RawSessionData[] = []; + for (const [day, events] of byDay) { + const session = pseudoSession(day, events); + rawSessions.push(session); + costIndex.set(session.sessionId, toSessionCost(session.sessionId, events)); + } + + const summary: CostSummary = { + totalCostUSD: [...costIndex.values()].reduce((sum, c) => sum + c.costUSD, 0), + pricedSessions: costIndex.size, + totalSessions: costIndex.size, + unpricedModels: [], + }; + + return { rawSessions, costIndex, summary, matched, unmatched }; +} diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 6819067ab..9e6d89739 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -14,6 +14,9 @@ import { SessionsSource } from './sources/sessions-source.js'; import { OtelSource } from './sources/otel-source.js'; import type { AnalyticsSource } from './sources/types.js'; import { ConfigLoader } from '../../../utils/config.js'; +import type { CostSummary, SessionCostIndex } from './cost/types.js'; +import type { CursorUsageSessions } from './cursor-usage-loader.js'; +import type { CursorUsageImport } from '../../../agents/plugins/cursor/cursor.usage-csv.js'; export function createAnalyticsCommand(): Command { const command = new Command('analytics') @@ -74,12 +77,6 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS includeExternal: options.includeExternal }); - if (rawSessions.length === 0) { - console.log(chalk.yellow('\nNo sessions found matching the specified criteria.')); - console.log(chalk.dim('Run with different filters or check that metrics are being collected.\n')); - return; - } - // A report needs cost computed BEFORE aggregation so zero-delta sessions that still carry // real usage are retained instead of dropped as "empty". const wantReport = Boolean(options.report || options.reportOutput || options.open || options.reportFormat); @@ -89,22 +86,55 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS return; } + // The email the report is stamped with, and the default `User` value the Cursor usage export + // is filtered on. Read before the import so `--cursor-usage-user` keeps its documented + // default in a non-interactive run; the interactive prompt for a missing one stays in the + // report branch, which is the only place a report filename needs it. + let userEmail: string | undefined; + try { + const cfg = await ConfigLoader.loadMultiProviderConfig(); + userEmail = cfg.userEmail || undefined; + } catch { + // omit email gracefully + } + // Cost: authoritative from the source (OTEL) when present; otherwise enrich from correlated // logs, but only when a report needs it. Retain zero-delta sessions with real token usage. let costResult = cost; - let keepSessionIds: Set | undefined; - if (cost) { - keepSessionIds = new Set( - [...cost.index.values()].filter((c) => c.tokens.total > 0).map((c) => c.sessionId) - ); - } else if (wantReport) { + if (!cost && wantReport) { const { enrichCosts, realDeps } = await import('./cost/cost-enricher.js'); costResult = await enrichCosts(rawSessions, realDeps); - keepSessionIds = new Set( - [...costResult.index.values()].filter((c) => c.tokens.total > 0).map((c) => c.sessionId) + } + + // #21/#22: the Cursor usage export, resolved here rather than inside the report branch so a + // run without any report flag no longer discards the flag in silence. Converted into + // ordinary sessions and canonical cost rows, it reaches the terminal totals, `--export` and + // the report from ONE place — nothing downstream needs to know the CSV exists. + const cursorUsage = await resolveCursorUsage(options, filter, userEmail); + if (cursorUsage) { + const { buildCursorUsageSessions } = await import('./cursor-usage-loader.js'); + const built = buildCursorUsageSessions( + cursorUsage, + rawSessions.filter((r) => r.startEvent?.agentName === 'cursor') ); + rawSessions.push(...built.rawSessions); + const index = new Map([...(costResult?.index ?? []), ...built.costIndex]); + costResult = { index, summary: summarize(index, costResult?.summary.unpricedModels ?? []) }; + reportCursorUsageImport(cursorUsage, built); } + if (rawSessions.length === 0) { + console.log(chalk.yellow('\nNo sessions found matching the specified criteria.')); + console.log(chalk.dim('Run with different filters or check that metrics are being collected.\n')); + return; + } + + // Zero-delta sessions that still carry real usage — a Cursor conversation priced only by the + // usage export among them — would otherwise be dropped by the aggregator as empty. + const keepSessionIds = costResult + ? new Set([...costResult.index.values()].filter((c) => c.tokens.total > 0).map((c) => c.sessionId)) + : undefined; + // Aggregate data (normalize models unless --verbose flag is set) const analytics = AnalyticsAggregator.aggregate(rawSessions, !options.verbose, keepSessionIds); @@ -145,15 +175,6 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS writeReportWithFallback } = await import('./report/report-generator.js'); - // Load user email for report metadata and filename; non-fatal if config is unavailable. - let userEmail: string | undefined; - try { - const cfg = await ConfigLoader.loadMultiProviderConfig(); - userEmail = cfg.userEmail || undefined; - } catch { - // omit email gracefully - } - if (userEmail === undefined && process.stdout.isTTY) { console.log(chalk.yellow('\n Warning: your email is not configured. It will be included in the report metadata and saved for future runs.')); try { @@ -174,52 +195,6 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS } } - // #21/#22: the path to real Cursor tokens/cost — a local file, or the same export fetched. - // Both end in the SAME parser, so a downloaded export can never be interpreted differently - // from one the operator saved by hand. - let cursorUsage; - const wantedUser = options.cursorUsageUser ?? userEmail; - if (options.cursorUsageCsv) { - const { loadCursorUsageCsv } = await import('@/agents/plugins/cursor/cursor.usage-csv.js'); - cursorUsage = loadCursorUsageCsv(options.cursorUsageCsv, { - ...(wantedUser !== undefined && { userEmail: wantedUser }), - }) ?? undefined; - if (!cursorUsage) { - console.log(chalk.yellow(`\n Could not read a Cursor usage export from ${options.cursorUsageCsv}. Report continues without it.`)); - } - } else if (options.cursorUsageFetch) { - // The only network call in the analytics path, and it needs all three of: the flag, a - // configured endpoint, and a signed-in Cursor. Any missing piece means no request. - const { readCursorSessionCookie, fetchCursorUsageExport } = await import('@/agents/plugins/cursor/cursor.usage-fetch.js'); - const cookie = await readCursorSessionCookie(); - cursorUsage = (await fetchCursorUsageExport({ - enabled: true, - ...(process.env.CURSOR_USAGE_EXPORT_URL !== undefined && { exportUrl: process.env.CURSOR_USAGE_EXPORT_URL }), - ...(cookie !== undefined && { cookie }), - ...(wantedUser !== undefined && { userEmail: wantedUser }), - ...(filter.fromDate !== undefined && { startDate: filter.fromDate.toISOString().slice(0, 10) }), - ...(filter.toDate !== undefined && { endDate: filter.toDate.toISOString().slice(0, 10) }), - })) ?? undefined; - if (!cursorUsage) { - console.log(chalk.yellow('\n Could not fetch the Cursor usage export. It needs CURSOR_USAGE_EXPORT_URL set and a signed-in')); - console.log(chalk.yellow(' Cursor app on this machine; the endpoint is undocumented and may have changed.')); - console.log(chalk.yellow(' The supported fallback is to export the CSV from the Cursor dashboard and pass --cursor-usage-csv .')); - console.log(chalk.dim(' Run with CODEMIE_DEBUG=true to see the status code. Report continues without it.')); - } - } - if (cursorUsage) { - if (cursorUsage.events.length === 0) { - // The Cursor account's email is frequently NOT the CodeMie config email, which would - // otherwise silently filter every row away and look like an empty export. - console.log(chalk.yellow(`\n Cursor usage export matched no rows for ${wantedUser ?? '(no email configured)'}.`)); - if (cursorUsage.usersInFile.length) { - console.log(chalk.yellow(` The export contains: ${cursorUsage.usersInFile.join(', ')}`)); - console.log(chalk.yellow(' Re-run with --cursor-usage-user to pick one of those.')); - } - cursorUsage = undefined; - } - } - const { index: costIndex, summary } = costResult; const payload = buildPayload(analytics, costIndex, summary, { rangeLabel: options.last ?? (options.from || options.to ? 'custom' : 'all'), @@ -298,6 +273,99 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS } } +/** + * The Cursor usage export for this run, from a local file or the same export fetched. + * + * Both paths end in the SAME parser, so a downloaded export can never be interpreted + * differently from one the operator saved by hand. Returns undefined — never throws — when no + * flag asked for one, when the file is unreadable, or when the user filter left nothing; every + * one of those says so on stdout first, because a silently ignored flag is what made this + * import look broken in the first place. + */ +async function resolveCursorUsage( + options: AnalyticsOptions, + filter: AnalyticsFilter, + userEmail: string | undefined +): Promise { + const wantedUser = options.cursorUsageUser ?? userEmail; + let usage: CursorUsageImport | undefined; + + if (options.cursorUsageCsv) { + const { loadCursorUsageCsv } = await import('@/agents/plugins/cursor/cursor.usage-csv.js'); + usage = loadCursorUsageCsv(options.cursorUsageCsv, { + ...(wantedUser !== undefined && { userEmail: wantedUser }), + }) ?? undefined; + if (!usage) { + console.log(chalk.yellow(`\n Could not read a Cursor usage export from ${options.cursorUsageCsv}. Continuing without it.`)); + } + } else if (options.cursorUsageFetch) { + // The only network call in the analytics path, and it needs all three of: the flag, a + // configured endpoint, and a signed-in Cursor. Any missing piece means no request. + const { readCursorSessionCookie, fetchCursorUsageExport } = await import('@/agents/plugins/cursor/cursor.usage-fetch.js'); + const cookie = await readCursorSessionCookie(); + usage = (await fetchCursorUsageExport({ + enabled: true, + ...(process.env.CURSOR_USAGE_EXPORT_URL !== undefined && { exportUrl: process.env.CURSOR_USAGE_EXPORT_URL }), + ...(cookie !== undefined && { cookie }), + ...(wantedUser !== undefined && { userEmail: wantedUser }), + ...(filter.fromDate !== undefined && { startDate: filter.fromDate.toISOString().slice(0, 10) }), + ...(filter.toDate !== undefined && { endDate: filter.toDate.toISOString().slice(0, 10) }), + })) ?? undefined; + if (!usage) { + console.log(chalk.yellow('\n Could not fetch the Cursor usage export. It needs CURSOR_USAGE_EXPORT_URL set and a signed-in')); + console.log(chalk.yellow(' Cursor app on this machine; the endpoint is undocumented and may have changed.')); + console.log(chalk.yellow(' The supported fallback is to export the CSV from the Cursor dashboard and pass --cursor-usage-csv .')); + console.log(chalk.dim(' Run with CODEMIE_DEBUG=true to see the status code. Continuing without it.')); + } + } + + if (usage && usage.events.length === 0) { + // The Cursor account's email is frequently NOT the CodeMie config email, which would + // otherwise silently filter every row away and look like an empty export. + console.log(chalk.yellow(`\n Cursor usage export matched no rows for ${wantedUser ?? '(no email configured)'}.`)); + if (usage.usersInFile.length) { + console.log(chalk.yellow(` The export contains: ${usage.usersInFile.join(', ')}`)); + console.log(chalk.yellow(' Re-run with --cursor-usage-user to pick one of those.')); + } + return undefined; + } + + return usage; +} + +/** What the import contributed, so the numbers below it are never unexplained. */ +function reportCursorUsageImport(usage: CursorUsageImport, built: CursorUsageSessions): void { + const cost = usage.hasCost ? `, $${built.summary.totalCostUSD.toFixed(2)} (Cursor's own billing)` : ', no cost column in this export'; + console.log( + chalk.dim( + `\n Imported ${usage.totals.events} Cursor usage event(s): ${usage.totals.tokens.total.toLocaleString('en-US')} tokens${cost}.` + ) + ); + console.log( + chalk.dim( + ` ${built.matched} attributed to a Cursor session; ${built.unmatched} in ${built.rawSessions.length} daily rollup(s) — no session window matched them unambiguously.` + ) + ); +} + +/** + * Re-derive the run's rollup from the merged index rather than adding two summaries. + * + * The import OVERWRITES the cost row of any session it matched, so adding the two totals would + * count a matched session on both sides. Reading the merged map is exact by construction and + * cannot drift as either side changes. `unpricedModels` is carried over untouched: it is a + * distinct set that no row in the map records, and the usage export prices everything it holds. + */ +function summarize(index: SessionCostIndex, unpricedModels: string[]): CostSummary { + const rows = [...index.values()]; + return { + totalCostUSD: rows.reduce((sum, c) => sum + c.costUSD, 0), + pricedSessions: rows.filter((c) => c.priced).length, + totalSessions: rows.length, + unpricedModels, + }; +} + /** * Parse filter options from command line arguments */ diff --git a/src/cli/commands/analytics/report/__tests__/payload-builder.test.ts b/src/cli/commands/analytics/report/__tests__/payload-builder.test.ts index 6c3423ae4..85e0b0b51 100644 --- a/src/cli/commands/analytics/report/__tests__/payload-builder.test.ts +++ b/src/cli/commands/analytics/report/__tests__/payload-builder.test.ts @@ -522,3 +522,58 @@ describe('buildPayload — copilot-cli specific fields', () => { expect(cov).toEqual({ agentName: 'copilot-cli', total: 3, priced: 2, withLog: 3 }); }); }); + +/** + * A Cursor session priced from the usage export carries Cursor's own billed figures rather than + * a CodeMie estimate, and reaches the report through the ordinary cost index. Two things have to + * survive that trip: the `costBasis` tag that keeps the distinction legible, and `priced: true`, + * without which Coverage by agent goes on reporting Cursor as having no token data — directly + * contradicting the import the reader just made. + */ +describe('buildPayload — Cursor usage-CSV provenance', () => { + const cursorRoot = { + ...root, + projects: [ + { + projectPath: '/repo/app', + branches: [{ branchName: 'main', sessions: [session({ sessionId: 'cur1', agentName: 'cursor' })] }], + }, + ], + } as unknown as RootAnalytics; + + const cursorIndex: SessionCostIndex = new Map([ + [ + 'cur1', + { + sessionId: 'cur1', + tokens: { ...emptyTokens(), cacheCreation1h: 0, input: 30061, output: 1038, cacheRead: 118400, total: 149499 }, + costUSD: 0.07, + perModel: [ + { + model: 'auto', + tokens: { ...emptyTokens(), cacheCreation1h: 0, input: 30061, output: 1038, cacheRead: 118400, total: 149499 }, + costUSD: 0.07, + unpriced: false, + costBasis: 'vendor-billed' as const, + }, + ], + priced: true, + hadLog: false, + }, + ], + ]); + + it('carries costBasis through onto perModelCost', () => { + const payload = buildPayload(cursorRoot, cursorIndex, summary, ctxAll); + + const s = payload.sessions[0]; + expect(s.perModelCost[0]).toMatchObject({ model: 'auto', costUSD: 0.07, costBasis: 'vendor-billed' }); + }); + + it('reports Cursor as priced in Coverage by agent even with no native log', () => { + const payload = buildPayload(cursorRoot, cursorIndex, summary, ctxAll); + + const cov = payload.meta.coverage.find((c) => c.agentName === 'cursor')!; + expect(cov).toEqual({ agentName: 'cursor', total: 1, priced: 1, withLog: 0 }); + }); +}); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index 28c92bfc9..ea595c600 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -848,7 +848,7 @@ host.appendChild(el('p', 'view-sub', fmtNum(u.totals.events) + ' usage events \u00b7 ' + esc(range) + (u.usersInFile && u.usersInFile.length === 1 ? ' \u00b7 ' + esc(u.usersInFile[0]) : ''))); // The single most important thing a reader can misunderstand about this data. - host.appendChild(el('div', 'alert alert-info', 'Cursor\u2019s own figures, imported from your dashboard export \u2014 not a CodeMie estimate. Rows marked Included are covered by your Cursor plan, which is a billing category, not zero usage: they still carry real tokens and cost, and both are counted here. These events have no session id, so they are shown beside the session table rather than merged into it, and they are not added to any cost figure elsewhere in this report.')); + host.appendChild(el('div', 'alert alert-info', 'Cursor\u2019s own figures, imported from your dashboard export \u2014 not a CodeMie estimate. Rows marked Included are covered by your Cursor plan, which is a billing category, not zero usage: they still carry real tokens and cost, and both are counted here. This tab is the per-event detail. Every one of these events is also counted once as an ordinary session elsewhere in the report \u2014 attributed to the Cursor session whose activity window contains it, or, when no single window does, to a Cursor usage \u2014 <date> daily rollup \u2014 so the Overview, Cost and Tools figures all include them.')); var kpis = [ ['Events', fmtNum(u.totals.events)], From e8dd2295fd5bbaf0a4bc6a7f79a0c2228ad5fb69 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:38 +0300 Subject: [PATCH 29/34] refactor(analytics): address code-review findings on the Cursor usage import MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Standards axis: - Use the `@/` alias instead of `../../../` deep relative imports (AGENTS.md, Common Pitfalls), which the new files had inconsistently mixed with `@/`. - Extract `pushInto()` and `modelOf()`, each of which was duplicated across two call sites in the loader. - `buildCursorUsageSessions` now narrows to Cursor's own sessions itself instead of making the caller filter on a bare `'cursor'` literal, so the agent name lives in one place and the caller stops reaching two levels into `RawSessionData`. Spec axis: the Cost view had lost the line stating that Cursor rows are Cursor's own billing rather than a CodeMie estimate — the distinction the whole import exists to make. It is back, driven off `costBasis` on the filtered sessions, so it appears exactly when such a row is on screen. Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_01KQwQ1VNMjpMrxk1EB9eoyF --- .../commands/analytics/cursor-usage-loader.ts | 55 +++++++++++-------- src/cli/commands/analytics/index.ts | 7 +-- .../commands/analytics/report/client/app.js | 6 ++ 3 files changed, 40 insertions(+), 28 deletions(-) diff --git a/src/cli/commands/analytics/cursor-usage-loader.ts b/src/cli/commands/analytics/cursor-usage-loader.ts index bbc546117..f7e2209aa 100644 --- a/src/cli/commands/analytics/cursor-usage-loader.ts +++ b/src/cli/commands/analytics/cursor-usage-loader.ts @@ -29,10 +29,10 @@ */ import type { RawSessionData, SessionStartEvent, SessionEndEvent } from './data-loader.js'; -import type { MetricDelta } from '../../../agents/core/metrics/types.js'; +import type { MetricDelta } from '@/agents/core/metrics/types.js'; import type { SessionCost, SessionCostIndex, CostSummary, TokenUsage, ModelCost } from './cost/types.js'; import { emptyUsage, addUsage } from './cost/cost-calculator.js'; -import type { CursorUsageEvent, CursorUsageImport } from '../../../agents/plugins/cursor/cursor.usage-csv.js'; +import type { CursorUsageEvent, CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import { normalizeModelName } from '@/utils/model-normalizer.js'; /** The agent every synthesized session is attributed to — Cursor's rows are Cursor's. */ @@ -60,6 +60,21 @@ interface SessionWindow { end: number; } +/** The model an event is attributed to, normalized and with one fallback for a blank cell. */ +function modelOf(event: CursorUsageEvent): string { + return normalizeModelName(event.model || '(unknown)'); +} + +/** Append to a map of grouped events, creating the group on first sight. */ +function pushInto(groups: Map, key: string, event: CursorUsageEvent): void { + const group = groups.get(key); + if (group) { + group.push(event); + } else { + groups.set(key, [event]); + } +} + /** Convert the export's token columns into the pipeline's normalized usage shape. */ function toUsage(event: CursorUsageEvent): TokenUsage { const { input, output, cacheRead, cacheCreation, total } = event.tokens; @@ -78,12 +93,17 @@ function toUsage(event: CursorUsageEvent): TokenUsage { /** * The activity windows usable for matching. * - * A zero-width window is kept: an event stamped at that exact instant is still unambiguously - * that session's. A session with no usable start is not — there is nothing to compare against. + * Only Cursor's own sessions are considered — no other agent's window can contain a Cursor usage + * event, and including them would only manufacture false ambiguity. A zero-width window is kept: + * an event stamped at that exact instant is still unambiguously that session's. A session with no + * usable start is not — there is nothing to compare against. */ function windowsOf(sessions: RawSessionData[]): SessionWindow[] { const windows: SessionWindow[] = []; for (const session of sessions) { + if (session.startEvent?.agentName !== AGENT_NAME) { + continue; + } const start = session.startEvent?.data.startTime; if (start === undefined || !Number.isFinite(start) || start <= 0) { continue; @@ -134,7 +154,7 @@ function toSessionCost(sessionId: string, events: CursorUsageEvent[]): SessionCo // Normalized so a Cursor spelling collapses onto the same key every other source uses; the // name is otherwise left alone, with provenance carried by `costBasis` rather than a suffix // that would split one model across two rows in every by-model chart. - const model = normalizeModelName(event.model || '(unknown)'); + const model = modelOf(event); perModelMap.set(model, addUsage(perModelMap.get(model) ?? emptyUsage(), usage)); perModelCost.set(model, (perModelCost.get(model) ?? 0) + event.costUSD); } @@ -167,7 +187,7 @@ function pseudoSession(day: string, events: CursorUsageEvent[]): RawSessionData const stamps = events.map((e) => Date.parse(e.date)).filter((n) => Number.isFinite(n)); const startTime = stamps.length ? Math.min(...stamps) : 0; const endTime = stamps.length ? Math.max(...stamps) : 0; - const models = [...new Set(events.map((e) => normalizeModelName(e.model || '(unknown)')))]; + const models = [...new Set(events.map(modelOf))]; const delta: MetricDelta = { recordId: `${sessionId}-usage`, @@ -210,14 +230,14 @@ function pseudoSession(day: string, events: CursorUsageEvent[]): RawSessionData /** * Convert a parsed usage export into sessions and cost rows the pipeline already understands. * - * `cursorSessions` should be the Cursor sessions in scope for this run; anything else simply - * cannot contain a Cursor usage event and only widens the chance of a false ambiguity. + * Pass the run's whole session set: the matcher narrows to Cursor's own sessions itself, so no + * caller has to know which agent name the export belongs to. */ export function buildCursorUsageSessions( usage: CursorUsageImport, - cursorSessions: RawSessionData[] + sessions: RawSessionData[] ): CursorUsageSessions { - const windows = windowsOf(cursorSessions); + const windows = windowsOf(sessions); const byMatchedSession = new Map(); const byDay = new Map(); let matched = 0; @@ -227,22 +247,11 @@ export function buildCursorUsageSessions( const ms = Date.parse(event.date); const sessionId = Number.isFinite(ms) ? containingSession(windows, ms) : undefined; if (sessionId !== undefined) { - const group = byMatchedSession.get(sessionId); - if (group) { - group.push(event); - } else { - byMatchedSession.set(sessionId, [event]); - } + pushInto(byMatchedSession, sessionId, event); matched += 1; continue; } - const day = event.day || 'unknown'; - const group = byDay.get(day); - if (group) { - group.push(event); - } else { - byDay.set(day, [event]); - } + pushInto(byDay, event.day || 'unknown', event); unmatched += 1; } diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 9e6d89739..18e662b7a 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -16,7 +16,7 @@ import type { AnalyticsSource } from './sources/types.js'; import { ConfigLoader } from '../../../utils/config.js'; import type { CostSummary, SessionCostIndex } from './cost/types.js'; import type { CursorUsageSessions } from './cursor-usage-loader.js'; -import type { CursorUsageImport } from '../../../agents/plugins/cursor/cursor.usage-csv.js'; +import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; export function createAnalyticsCommand(): Command { const command = new Command('analytics') @@ -113,10 +113,7 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS const cursorUsage = await resolveCursorUsage(options, filter, userEmail); if (cursorUsage) { const { buildCursorUsageSessions } = await import('./cursor-usage-loader.js'); - const built = buildCursorUsageSessions( - cursorUsage, - rawSessions.filter((r) => r.startEvent?.agentName === 'cursor') - ); + const built = buildCursorUsageSessions(cursorUsage, rawSessions); rawSessions.push(...built.rawSessions); const index = new Map([...(costResult?.index ?? []), ...built.costIndex]); costResult = { index, summary: summarize(index, costResult?.summary.unpricedModels ?? []) }; diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index ea595c600..f8c5f3411 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -901,6 +901,12 @@ + 'records transcripts locally but no token telemetry at all (analytics-only agents such as Cursor). ' + 'This does not affect the cost of the sessions that are priced. See Coverage by agent below.'; if (DATA.meta.unpricedModels && DATA.meta.unpricedModels.length) msg += ' Models with no published price (estimated at a stand-in rate when tokens were recovered): ' + DATA.meta.unpricedModels.join(', ') + '.'; + // Rows imported from a Cursor usage export are the vendor's own billed figures, not a figure + // CodeMie derived from tokens and a pricing table. Folding them in without saying so would + // lose the one distinction the import exists to make. Read off the filtered sessions, so it + // is stated exactly when such a row is actually on screen. + var vendorBilled = fs.some(function (s) { return (s.perModelCost || []).some(function (m) { return m.costBasis === 'vendor-billed'; }); }); + if (vendorBilled) msg += ' Cursor figures here are Cursor\u2019s own billing, imported from your usage export \u2014 not a CodeMie estimate; every other cost on this page is computed from tokens and a pricing table.'; banner.textContent = msg; // textContent is safe — do not pre-escape (would double-escape) host.appendChild(banner); From 37f3a36707ff4e8bf4398c42fc45982a94564a62 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:38:38 +0300 Subject: [PATCH 30/34] refactor(analytics): drop the Cursor Usage CSV view and document Cursor on its own MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tab was a leftover from when the import was isolated. Now that every event is counted once as an ordinary session, a per-agent tab in the sidebar is a special case no other data source has — and a second place to read a number the rest of the report already shows. Removes the view, its nav entry, the `data-optional` nav mechanism it was the sole user of, and the `meta.cursorUsage` payload field none of them need now. Docs: Cursor gets its own section, ordered why-first — CodeMie never launches it, recent builds record no billable tokens on disk, the local stores were measured rather than assumed (0 of 469 sessions carried a token signal), and the export is therefore the only honest source. The old "Analytics-only agents" subsection shrinks to a pointer instead of restating it. Generated with AI Co-Authored-By: codemie-ai Claude-Session: https://claude.ai/code/session_01KQwQ1VNMjpMrxk1EB9eoyF --- docs/ANALYTICS-REPORT.md | 160 +++++++++++------- docs/CURSOR_INTEGRATION.md | 3 +- src/cli/commands/analytics/index.ts | 1 - .../commands/analytics/report/client/app.js | 68 -------- .../analytics/report/payload-builder.ts | 4 - .../commands/analytics/report/template.html | 1 - src/cli/commands/analytics/report/types.ts | 7 - 7 files changed, 102 insertions(+), 142 deletions(-) diff --git a/docs/ANALYTICS-REPORT.md b/docs/ANALYTICS-REPORT.md index da26de655..c289453b7 100644 --- a/docs/ANALYTICS-REPORT.md +++ b/docs/ANALYTICS-REPORT.md @@ -29,7 +29,9 @@ codemie analytics --report --report-format both codemie analytics --report --open --include-external # Real Cursor tokens and cost — import a usage export from the Cursor dashboard -codemie analytics --report --open --cursor-usage-csv ~/Downloads/team-usage-events-....csv +# (Cursor records no billable tokens locally; see "Cursor — why it needs a CSV") +codemie analytics --report --open --include-external \ + --cursor-usage-csv ~/Downloads/team-usage-events-....csv ``` > **If your question is "what did AI actually cost us?", you probably want `--include-external`.** @@ -41,7 +43,7 @@ codemie analytics --report --open --cursor-usage-csv ~/Downloads/team-usage-even ## What the Report Covers -The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*, plus an optional tenth ([Cursor Usage CSV](#cursor-usage-csv)) that appears only when you import a Cursor usage export. +The dashboard reads every AI session CodeMie has tracked — Claude Code, Codex, Gemini, OpenCode, Pi, GitHub Copilot CLI, and the built-in agent — plus native agent logs it discovers automatically on disk. It builds a single portable HTML file with **nine interactive views**, grouped in the sidebar as *Insights*, *Spend*, and *Raw*. Discovered sessions that CodeMie did not launch are **excluded by default**; see [Session provenance](#session-provenance). @@ -279,29 +281,14 @@ Cost enrichment requires the native log to read per-turn token data. Sessions wh ### Analytics-only agents (Cursor) — expect no token counts -Cursor is read, never launched. Its transcripts, tool outcomes, projects, and models all come -through, but **recent Cursor builds record no billable token counts** — they write zero, or omit the -field entirely, while tool-call data keeps working. This is Cursor's behaviour, not a CodeMie bug. - -What that looks like in the report: - -- Cursor sessions appear (with `--include-external`) with real turns, tool calls, and file activity. -- Their cost and token cells are `—`, per [When cost and tokens show `—`](#unknown-cost). -- **If you deselect every other agent in the top bar, the Overview and Cost KPIs go all-dashes and - show a short note saying local token telemetry is absent for the sessions in view.** That is the - filter working correctly on absent data — not a broken agent chip. Tool-call tables keep working. - -A measurement taken on one machine: of 469 discovered Cursor sessions, 0 carried any token signal -and 24 carried tool calls. Conversations that *do* still hold token counts were all roughly a year -old and no longer discoverable at all. Every Cursor database, per-session chat store, and transcript -directory was checked — no *local* store has the recent numbers. CodeMie will not manufacture the -figure from context-window fill, transcript length, or tool-call counts, because those are not -billable tokens and presenting them as such would trade an honest blank for a confident wrong -number. +An *analytics-only* agent is one CodeMie never launches and only reads. `cursor` is the only one +today, and it is the single case where local files cannot supply tokens or cost: recent Cursor +builds record no billable token counts on disk, so Cursor sessions show real turns, tool calls and +file activity but `—` for cost and every token field (see +[When cost and tokens show `—`](#unknown-cost)). -**You can still get the real numbers** — they live in Cursor's dashboard usage export rather than -on disk. See [Cursor tokens and cost](#cursor-usage-csv), which turns those dashes into Cursor's own -token and cost figures. +That gap has a supported fix, and Cursor has a section of its own because none of it applies to any +other agent: **[Cursor — why it needs a CSV, and how to import it](#cursor-usage-csv)**. @@ -334,23 +321,92 @@ Two things to know before you rely on the wider number: -### Cursor tokens and cost — the usage CSV +## Cursor — why it needs a CSV, and how to import it + +Cursor is the one agent in this report that cannot be measured from local files alone. This +section explains why, and what to do about it. Everything here is specific to Cursor; no other +agent needs any of it. + +### Why Cursor is different + +Two things set Cursor apart from every other agent CodeMie reads: + +1. **CodeMie never launches it.** Cursor is *analytics-only*: there is no `codemie-cursor` command + and no npm package CodeMie installs. Its conversations are read from Cursor's own local stores, + read-only. Because CodeMie never launched them, *every* Cursor session is external — so they + appear only with `--include-external` (see [Session provenance](#session-provenance)). +2. **Recent Cursor builds record no billable token counts locally.** They write zero for the token + field, or omit it entirely, while tool-call data keeps working perfectly. This is Cursor's own + behaviour, not a CodeMie bug or a parsing gap. + +The consequence of (2) is that Cursor sessions arrive with real turns, real tool calls, real file +activity — and `—` for every token and cost cell. + +### Why the local data cannot be fixed + +The obvious question is whether CodeMie is simply looking in the wrong place. It is not, and this +was measured rather than assumed: + +- Of **469** discovered Cursor sessions on one machine, **0** carried any token signal; 24 carried + tool calls. +- Every Cursor store was checked — the state database, the per-session chat store, the AI-tracking + database, and the transcript directories. No *local* store holds the recent numbers. +- The conversations that *do* still hold token counts were all roughly a year old, and are no + longer discoverable at all. + +CodeMie will not manufacture the figure from context-window fill, transcript length, or tool-call +counts. Those correlate with usage but are not billable tokens, and presenting them as such would +trade an honest blank for a confident wrong number. So the dashes stay — see +[When cost and tokens show `—`](#unknown-cost) for the general rule. + +### The numbers do exist — in Cursor's dashboard -Everything else in this document reads local files. Cursor needs one extra step, because -**Cursor's local stores no longer record billable token counts** (see -[Analytics-only agents](#analytics-only-agents)) — so Cursor sessions show `—` in the session -table. The numbers do still exist, in Cursor's dashboard export. +What Cursor stops writing to disk, it still bills you for, and its dashboard exports that ledger. +**Usage → Export** produces a `team-usage-events-*.csv` with per-event input, cache-write, +cache-read, output and total tokens, usually with a `Cost` column. -This is a plain file read: no credential, no network call. +Importing it is a plain file read: **no credential, no network call.** 1. In Cursor, open **Usage** and click **Export** for the period you want. 2. Pass the downloaded file: ```bash -codemie analytics --report --open --cursor-usage-csv ~/Downloads/team-usage-events-....csv +codemie analytics --report --open --include-external \ + --cursor-usage-csv ~/Downloads/team-usage-events-....csv +``` + +The flag works with or without `--report`. Either way the command first prints what it imported: + +``` + Imported 61 Cursor usage event(s): 39,952,466 tokens, $25.25 (Cursor's own billing). + 20 attributed to a Cursor session; 41 in 3 daily rollup(s) — no session window matched them unambiguously. ``` -It renders as its own **Cursor Usage CSV** view with totals, a by-model table, and a by-day table. +### How the import reaches the rest of the report + +There is **no separate Cursor section or tab.** The import is converted into ordinary sessions and +ordinary cost rows before anything is rendered, so it flows into Overview, Cost, Tools & Models, +Coverage and the session table by construction — the same path every other agent's data takes. + +Export rows carry no session id, so they cannot be joined to a conversation by key. CodeMie matches +them by **time** instead: + +| Case | Where the event lands | +|---|---| +| Its timestamp falls inside exactly one Cursor session's activity window | That session — its empty usage is overwritten with the real figures | +| No session window contains it | A `Cursor usage — ` daily rollup, which behaves as an ordinary session | +| Several overlapping windows contain it | The same daily rollup — CodeMie will not pick between two candidates | + +That last row is the important one: an ambiguous event goes to the rollup rather than to a guess. +Either way **every event is counted exactly once**, so the report's Cursor totals equal the +export's own totals. + +**These are Cursor's figures, not CodeMie's estimate.** Every cost line derived from the export is +tagged `costBasis: "vendor-billed"` in the report payload, and the Cost view says so in its banner +whenever such a row is on screen. Every other cost figure in the report is CodeMie's own +calculation from tokens × a pricing table. + +### Reading the export correctly > **`Kind=Included` does not mean free.** `Included` is Cursor's *billing category* — "covered by > your plan" — not a statement that the usage was unmetered. In a real export, all 61 events were @@ -358,38 +414,22 @@ It renders as its own **Cursor Usage CSV** view with totals, a by-model table, a > tokens and the `Cost` column regardless of `Kind`, and never uses the word "Included" as a cost > label anywhere in the report. -Things worth knowing about the export format: +Other things worth knowing about the file: - **Two shapes exist.** Most exports end with a `Cost` column; at least one variant ships - `Requests` instead and carries no cost at all. Both import. When `Cost` is absent the section - shows `—` for money and says why — the token counts are unaffected. + `Requests` instead and carries no cost at all. Both import. When `Cost` is absent, tokens are + still counted in full and the cost contribution is zero. - **`Cost` is not always a number.** Some rows read `Free`. Those contribute zero rather than corrupting the total. - **Rows are filtered to you** *when the export names users at all*. The `User` column is matched against your configured CodeMie email, which is frequently *not* the address on your Cursor account — override with `--cursor-usage-user `. An export with no `User` column is imported whole, since there is no one else's data in it to exclude. If the filter matches - nothing, CodeMie warns and lists the addresses actually present rather than showing an empty - section. -- **Every event is counted once, everywhere.** Export rows are per-event with no session id, so - there is no key to join them on directly. CodeMie matches each event by *time* instead: an event - whose timestamp falls inside exactly one Cursor session's activity window is attributed to that - session. Anything else — no window contains it, or several overlapping ones do — lands in a - `Cursor usage — ` daily rollup, which behaves as an ordinary session throughout the - report. CodeMie never picks between two candidate sessions; an ambiguous event goes to the - rollup rather than to a guess. - - The upshot: the Overview, Cost, Tools & Models and Coverage figures all include these tokens and - this cost, and they add up to the export's own totals exactly once. The **Cursor Usage CSV** tab - is the per-event detail view, not a separate total to add on. -- **These are Cursor's figures, not CodeMie's estimate.** Every cost line derived from the export - is tagged `costBasis: "vendor-billed"` in the report payload — Cursor billed that amount, and - CodeMie merely recorded it. Every other cost line in the report is computed from tokens and a - pricing table. + nothing, CodeMie warns and lists the addresses actually present rather than importing silence. -#### Downloading it automatically (optional, unsupported) +### Downloading the export automatically (optional, unsupported) If clicking Export each time is tedious, CodeMie can fetch the same CSV. This is **opt-in and unsupported**, and file import above remains the recommended path. @@ -431,7 +471,7 @@ sign-in redirect returning HTML — omits the section and leaves the rest of the --- -### OTEL events file (`analytics otel`) +## OTEL events file (`analytics otel`) As an alternative to the local-session sources above, the `analytics otel` subcommand builds the same report from a **flattened OTEL events file** (`otel-events.jsonl`) — for example, telemetry exported from a fleet or CI environment rather than the current machine's history. @@ -509,9 +549,8 @@ codemie analytics --report --open --include-external \ Those two lines print for **every** run that passes the flag, report or not — so `codemie analytics --cursor-usage-csv f.csv` on its own tells you what it imported. -In the report, expect a new **Cursor Usage CSV** entry in the sidebar (hidden when no export is -imported) showing Events, Total tokens and Cost, plus by-model and by-day tables — and the same -figures folded into the rest of the report: +In the report, expect those figures folded into the ordinary views — there is no separate Cursor +tab to look in: - Overview's **Est. cost** and Cost's **Total est. cost** agree, both including the import. - Cursor's models (`auto`, `cursor-grok-*`, …) appear in **both** "Cost by model" and @@ -545,13 +584,14 @@ The report's Events, Total tokens and Cost KPIs should match that line exactly `Imported …` line the command printed, since each event is counted once and only once. **Every row saying `Included` still contributes** — that word is a billing category, not zero usage. -**If the section is missing**, the terminal tells you which check failed: +**If nothing was imported**, the `Imported …` line is absent and the terminal names the check that +failed: | Message | Meaning | Fix | |---|---|---| | `Could not read a Cursor usage export from …` | Wrong path, or not a usage CSV | Check the path; confirm the header starts `Date,User,…` | | `matched no rows for ` + `The export contains: …` | Your Cursor account email differs from your CodeMie one | Re-run with `--cursor-usage-user ` | -| Cost shows `—` but tokens are fine | This export variant has no `Cost` column (it ships `Requests`) | Expected; re-export, or read the token columns | +| Tokens imported but cost is `$0.00` | This export variant has no `Cost` column (it ships `Requests`) | Expected; re-export from a period Cursor priced, or read the token columns | ### 5. Optional: fetching that export automatically @@ -569,7 +609,7 @@ export CURSOR_SESSION_TOKEN='::' codemie analytics --report --open --include-external --cursor-usage-fetch ``` -**Expect:** the same **Cursor Usage CSV** section as step 4, without having saved a file. +**Expect:** the same imported figures as step 4, without having saved a file. To prove the gate rather than the happy path, unset either variable and re-run: no request should be made at all. `CODEMIE_DEBUG=true` prints the outcome per attempt — status code and endpoint diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index 50e591a40..b79bf79a3 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -111,7 +111,8 @@ The gap above is *local*. Cursor's dashboard still exports the billable ledger: produces a `team-usage-events-*.csv` carrying per-event input, cache-write, cache-read, output and total tokens, usually with a `Cost` column. Import it with `--cursor-usage-csv ` (no network call, no credential) and CodeMie converts it into ordinary sessions, so its tokens and cost reach -every figure in the report. The **Cursor Usage CSV** tab remains as the per-event detail view. +every figure in the report. There is no separate Cursor tab: the import becomes ordinary sessions, +so it lands in Overview, Cost, Tools & Models and Coverage like any other agent's data. Two facts that decide how it must be read: diff --git a/src/cli/commands/analytics/index.ts b/src/cli/commands/analytics/index.ts index 18e662b7a..e32adba3c 100644 --- a/src/cli/commands/analytics/index.ts +++ b/src/cli/commands/analytics/index.ts @@ -198,7 +198,6 @@ export async function runAnalytics(options: AnalyticsOptions, source: AnalyticsS projectFilter: options.project ?? 'all', generatedAt: new Date().toISOString(), ...(userEmail !== undefined && { userEmail }), - ...(cursorUsage !== undefined && { cursorUsage }), ...(filter.fromDate !== undefined && { periodStart: filter.fromDate.toISOString() }), ...(filter.toDate !== undefined && { periodEnd: filter.toDate.toISOString() }), }); diff --git a/src/cli/commands/analytics/report/client/app.js b/src/cli/commands/analytics/report/client/app.js index f8c5f3411..2ce8f3a73 100644 --- a/src/cli/commands/analytics/report/client/app.js +++ b/src/cli/commands/analytics/report/client/app.js @@ -824,70 +824,6 @@ host.appendChild(changeCard); }; - /** - * Cursor usage-events CSV — the only source of real Cursor tokens and cost. - * - * Cursor's local stores stopped recording billable tokens, so the session table shows dashes - * for Cursor. This section fills that in from the operator's dashboard export. It stays a - * SEPARATE section because the export's rows are per-event with no composerId: there is no key - * to join them to sessions on, so adding these totals to the session costs would be inventing - * an attribution. Read them side by side, not summed. - * - * The figures here are Cursor's own, not CodeMie estimates — no stand-in rate is involved. - */ - VIEWS.cursorusage = function (host) { - var u = DATA.meta.cursorUsage; - host.appendChild(el('h2', 'view-title', 'Cursor Usage CSV')); - if (!u) { - host.appendChild(el('p', 'view-sub', 'No usage export imported for this report.')); - host.appendChild(el('div', 'empty', 'Export your usage from the Cursor dashboard (Usage \u2192 Export) and re-run with --cursor-usage-csv <path> to see real Cursor tokens and cost here.')); - return; - } - var days = u.byDay || []; - var range = days.length ? (days[0].day + ' \u2192 ' + days[days.length - 1].day) : 'no dated rows'; - host.appendChild(el('p', 'view-sub', fmtNum(u.totals.events) + ' usage events \u00b7 ' + esc(range) + (u.usersInFile && u.usersInFile.length === 1 ? ' \u00b7 ' + esc(u.usersInFile[0]) : ''))); - - // The single most important thing a reader can misunderstand about this data. - host.appendChild(el('div', 'alert alert-info', 'Cursor\u2019s own figures, imported from your dashboard export \u2014 not a CodeMie estimate. Rows marked Included are covered by your Cursor plan, which is a billing category, not zero usage: they still carry real tokens and cost, and both are counted here. This tab is the per-event detail. Every one of these events is also counted once as an ordinary session elsewhere in the report \u2014 attributed to the Cursor session whose activity window contains it, or, when no single window does, to a Cursor usage \u2014 <date> daily rollup \u2014 so the Overview, Cost and Tools figures all include them.')); - - var kpis = [ - ['Events', fmtNum(u.totals.events)], - ['Total tokens', fmtTokens(u.totals.tokens.total)], - ['Cost', u.hasCost ? fmtUSD(u.totals.costUSD) : UNKNOWN_LABEL] - ]; - var grid = el('div', 'kpi-grid'); grid.style.gridTemplateColumns = 'repeat(3,1fr)'; - kpis.forEach(function (k) { - var c = el('div', 'kpi'); - c.appendChild(el('div', 'kpi-label', k[0])); - c.appendChild(el('div', 'kpi-value', k[1])); - grid.appendChild(c); - }); - host.appendChild(grid); - if (!u.hasCost) { - host.appendChild(el('div', 'alert alert-warning', 'This export variant has no Cost column (it ships Requests instead), so cost shows as a dash. The token counts are unaffected.')); - } - - // The by-model and by-day tables are the same table over the same bucket shape; only the - // first column differs. One builder keeps their columns and money handling from drifting. - var tokCols = ['Input', 'Cache write', 'Cache read', 'Output', 'Total']; - function money(n) { return u.hasCost ? fmtUSD(n) : UNKNOWN_LABEL; } - function bucketTable(title, sub, keyLabel, keyOf, buckets) { - var c = card(title, sub); - c._body.innerHTML = '
' + tableHTML( - [keyLabel, 'Events'].concat(tokCols).concat(['Cost']), - (buckets || []).map(function (b) { - var t = b.tokens; - return [esc(keyOf(b) || '\u2014'), fmtNum(b.events), - fmtTokens(t.input), fmtTokens(t.cacheCreation), fmtTokens(t.cacheRead), fmtTokens(t.output), fmtTokens(t.total), - money(b.costUSD)]; - }) - ) + '
'; - host.appendChild(c); - } - bucketTable('By model', 'as reported by Cursor', 'Model', function (b) { return b.model; }, u.byModel); - bucketTable('By day', 'export rows grouped by date', 'Day', function (b) { return b.day; }, days); - }; - VIEWS.cost = function (host, fs) { host.appendChild(el('h2', 'view-title', 'Cost')); host.appendChild(el('p', 'view-sub', 'Estimated cost (API-equivalent) — token usage × model pricing. This is what the same usage would have been metered at through the API, not an invoice.')); @@ -1527,10 +1463,6 @@ root.innerHTML = ''; (VIEWS[state.view] || VIEWS.overview)(root, filtered()); document.querySelectorAll('.nav-i').forEach(function (n) { n.classList.toggle('active', n.getAttribute('data-view') === state.view); }); - // The remote-source view is opt-in; without a pull there is nothing to navigate to. - document.querySelectorAll('.nav-i[data-optional]').forEach(function (n) { - if (n.getAttribute('data-view') === 'cursorusage' && !DATA.meta.cursorUsage) n.style.display = 'none'; - }); } function buildControls() { diff --git a/src/cli/commands/analytics/report/payload-builder.ts b/src/cli/commands/analytics/report/payload-builder.ts index f4cf6e6e1..634d6dc42 100644 --- a/src/cli/commands/analytics/report/payload-builder.ts +++ b/src/cli/commands/analytics/report/payload-builder.ts @@ -4,7 +4,6 @@ * `generatedAt` so this stays deterministic and unit-testable. */ -import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import type { RootAnalytics } from '../types.js'; import type { SessionCostIndex, CostSummary, AgentCoverage } from '../cost/types.js'; import { emptyUsage } from '../cost/cost-calculator.js'; @@ -18,8 +17,6 @@ export interface PayloadContext { userEmail?: string; // caller stamps; absent when not authenticated periodStart?: string; // ISO — caller stamps from filter or session start periodEnd?: string; // ISO — caller stamps from filter or session end - /** Opt-in Cursor usage-events CSV import; absent unless a path was given. */ - cursorUsage?: CursorUsageImport; } export function buildPayload( @@ -173,7 +170,6 @@ export function buildPayload( unpricedModels: summary.unpricedModels, coverage: [...coverageMap.values()].sort((a, b) => b.total - a.total), ...(ctx.userEmail !== undefined && { userEmail: ctx.userEmail }), - ...(ctx.cursorUsage !== undefined && { cursorUsage: ctx.cursorUsage }), ...(ctx.periodStart !== undefined ? { periodStart: ctx.periodStart } : minStartMs !== undefined diff --git a/src/cli/commands/analytics/report/template.html b/src/cli/commands/analytics/report/template.html index aa5aac25c..94d0408bf 100644 --- a/src/cli/commands/analytics/report/template.html +++ b/src/cli/commands/analytics/report/template.html @@ -287,7 +287,6 @@
Spend
Cost
Raw
-
Cursor Usage CSV
Sessions
diff --git a/src/cli/commands/analytics/report/types.ts b/src/cli/commands/analytics/report/types.ts index 8fc73a7b9..4a2e309b1 100644 --- a/src/cli/commands/analytics/report/types.ts +++ b/src/cli/commands/analytics/report/types.ts @@ -3,7 +3,6 @@ * report. The client app reads only this and computes every view from it. */ -import type { CursorUsageImport } from '@/agents/plugins/cursor/cursor.usage-csv.js'; import type { TokenUsage, ModelCost, AgentCoverage, CostSeriesPoint, DispatchEvent } from '../cost/types.js'; import type { ToolStats, NamedInvocationStats } from '../types.js'; @@ -82,12 +81,6 @@ export interface ReportMeta { unpricedModels: string[]; coverage: AgentCoverage[]; // per-agent priced/total — "which tools are included" userEmail?: string; // identity of the report owner; absent when not authenticated - /** - * Optional Cursor usage-events CSV import — the only source of real Cursor tokens and cost. - * Kept beside the sessions rather than inside them: its rows are per-event with no composerId, - * so there is no key to join on, and its totals must never be silently added to session costs. - */ - cursorUsage?: CursorUsageImport; periodStart?: string; // ISO — start of the reported range; always present when the report contains any sessions periodEnd?: string; // ISO — end of the reported range; always present when the report contains any sessions } From 88c0e184370c18743538c382e5ee88e832fde12d Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:25:48 +0300 Subject: [PATCH 31/34] chore: update .gitignore and remove obsolete documentation files - Added `.scratch/` to `.gitignore` to exclude temporary files. - Deleted `CONTEXT.md` and `0001-cursor-session-discovery-from-state-vscdb.md` as they are no longer relevant to the project. --- .gitignore | 2 + ...-messagegrill-with-docscommand-message.txt | 499 ------------------ CONTEXT.md | 20 - ...rsor-session-discovery-from-state-vscdb.md | 69 --- 4 files changed, 2 insertions(+), 588 deletions(-) delete mode 100644 2026-09-03-161326-command-messagegrill-with-docscommand-message.txt delete mode 100644 CONTEXT.md delete mode 100644 docs/adr/0001-cursor-session-discovery-from-state-vscdb.md diff --git a/.gitignore b/.gitignore index 8bd91e38e..6442dbd8b 100644 --- a/.gitignore +++ b/.gitignore @@ -89,3 +89,5 @@ docs/superpowers/tasks/*/code-review*.diff /docs/superpowers/resume/ /docs/superpowers/review-prompts/ /docs/codemie/analytics/ + +.scratch/ \ No newline at end of file diff --git a/2026-09-03-161326-command-messagegrill-with-docscommand-message.txt b/2026-09-03-161326-command-messagegrill-with-docscommand-message.txt deleted file mode 100644 index f50e39ff5..000000000 --- a/2026-09-03-161326-command-messagegrill-with-docscommand-message.txt +++ /dev/null @@ -1,499 +0,0 @@ - ▐▛███▜▌ Claude Code v2.1.228 -▝▜█████▛▘ Fable 5 · Claude Pro - ▘▘ ▝▝ ~/…/worktrees/codemie-code/wt-feature-cursor-analytics-support - - -❯ /grill-with-docs "codemie analytics show --include-external --report --open" -does not include cursor usage data. I want - to be able to see the cursor usage too. - -⏺ Skill(grilling) - ⎿  Successfully loaded skill - -⏺ Skill(domain-modeling) - ⎿  Successfully loaded skill - -⏺ Explore(Explore external analytics ingestion) - ⎿  Backgrounded agent (↓ to manage · ctrl+o to expand) - -⏺ Exploration is running in the background. Here's the first round of frontier - questions — the decisions that don't depend on those code facts. - - ❓ Q1 - Which "Cursor" do you mean?: Cursor ships several surfaces whose usage - is recorded very differently: (a) the Cursor IDE itself (chat/composer/tab - usage inside the editor), (b) the Cursor CLI / cursor-agent (the terminal - agent, closest in spirit to the other agents CodeMie tracks), or (c) both. - Which usage do you actually want to see in the analytics report? - - ➡️ My recommendation: start with the Cursor CLI / cursor-agent, since - CodeMie's analytics model is built around terminal-agent sessions (like the - copilot-cli external-ingestion precedent), and IDE usage may not be fully - reconstructable from local data. - - --- - ❓ Q2 - Data source: Where should the numbers come from? Options: (a) local - session/log files Cursor writes on your machine (zero-config, offline, matches - how CodeMie ingests Copilot data — but limited to what Cursor persists - locally), (b) the Cursor Admin/Teams API (authoritative usage + spend, but - requires a team admin API key and network access), or (c) local first, API - later if needed. - - ➡️ My recommendation: (a) local files, consistent with the existing - external-ingestion approach — no credentials, works per-developer. I'll - confirm from the exploration what Cursor actually persists locally and flag if - it's too thin. - - --- - ❓ Q3 - Whose usage / which machine?: Is this strictly your own usage on this - machine (like the rest of codemie analytics show), or do you want team-wide - Cursor usage? Team-wide would force the Admin API path in Q2 and is a - different feature shape. - - ➡️ My recommendation: personal, local-machine usage only, matching the - existing analytics scope. - - --- - ❓ Q4 - What counts as "usage data"?: Sharpening the term — for the other - agents a session record carries things like agent name, timestamps, model, - token counts, and cost. If Cursor's local data only supports a subset (e.g., - sessions and timestamps but not reliable token/cost figures), is a partial row - acceptable in the report, or is token/cost data the actual point of this - request? - - ➡️ My recommendation: ingest whatever fields Cursor exposes and render partial - data honestly (blank/— for missing metrics), rather than blocking the feature - on cost parity. If cost is the real goal, say so — that changes the Q2 answer - toward the API. - - --- - ❓ Q5 - Where it lives: Should Cursor appear under the existing - --include-external flag as just another external agent (like copilot-cli) with - no new CLI surface, or do you want any dedicated command/flag for it? - - ➡️ My recommendation: no new CLI surface — Cursor becomes another external, - analytics-only agent that --include-external picks up automatically. - - Answer these and I'll fold in the exploration results and push the frontier - outward (parsing format, session-boundary semantics, dedupe rules, report - grouping, etc.). - -⏺ Ran 3 stop hooks (ctrl+o to expand) - ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: - command not found - -✻ Cooked for 43s - -❯ I accept recommended answers - -⏺ Settled: Cursor CLI (cursor-agent) usage, ingested from local files on this - machine, personal scope, partial metrics acceptable, surfaced via the existing - --include-external flag. While the repo exploration finishes, let me check - what Cursor actually persists locally on this machine — that fact gates the - next round. - - Listed 2 directories, ran 3 shell commands (ctrl+o to expand) - -⏺ Agent "Explore external analytics ingestion" finished · 2m 12s - -⏺ The exploration came back and reshapes one of our settled answers. Let me grab - two more local facts (timestamps/model info in Cursor transcripts) before the - next round. - - Listed 1 directory, ran 2 shell commands (ctrl+o to expand) - -⏺ Key facts now in hand — and one of them reshapes your original framing: - - From the codebase: The repo has an explicit declarative path for exactly this: - an agent plugin with analyticsOnly: true plus a SessionAdapter (like - copilot-cli before it became a managed agent). Important nuance: - --include-external gates unowned sessions of managed agents (tagged - native-external). Analytics-only agents get tagged native-unmanaged and are - shown by default, no flag needed. So "make --include-external include Cursor" - isn't actually the lever the codebase offers. - - From your machine (Cursor's local data): - - ~/.cursor/projects//agent-transcripts//.jsonl — CLI agent - transcripts. Very thin: just user/assistant text turns and turn_ended markers. - No timestamps, no model, no tokens, no tool calls. Timestamps only - recoverable from file creation/modification times; project comes from the - directory name. - - ~/.cursor/ai-tracking/ai-code-tracking.db — a richer SQLite DB: - conversation_summaries (conversationId, title, model), ai_code_hashes - (per-edit model + timestamps), scored_commits (AI vs human lines added/deleted - per commit). This likely mixes IDE composer/tab activity with agent activity. - - ~/.cursor/chats/*/store.db — opaque blob store (empty in your samples); not - viable. - - Round 2: - - ❓ Q6 - Visibility semantics: Should Cursor sessions (a) follow the repo's - analyticsOnly pattern — tagged native-unmanaged, visible by default in codemie - analytics with no flag — or (b) be artificially gated behind - --include-external to match your original phrasing? - - ➡️ (a): follow the existing pattern. You'll see Cursor with or without the - flag, which is strictly more than you asked for, and it keeps native-external - meaning what it means today (unowned sessions of managed agents). - - --- - ❓ Q7 - Metric depth / data sources: Given the transcripts are thin, which - sources should the adapter read? (a) Transcripts only — session count, - prompt/turn counts, project, start/end from file times; model, tokens, cost, - lines all blank. (b) Transcripts + join ai-code-tracking.db — adds - per-conversation model and title, and potentially AI-attributed lines - added/removed, at the cost of depending on an undocumented internal Cursor DB - schema that can break on Cursor updates (read-only, tolerant parsing would - mitigate). - - ➡️ (b), with tolerant, fail-soft reads: the DB is what makes the rows - meaningfully comparable (model + lines), and the failure mode is just falling - back to (a). The schema-drift risk matches the risk already accepted for - Copilot's undocumented events.jsonl. - - --- - ❓ Q8 - Model attribution fallback: When a session has no model in the - tracking DB, should the row (a) show model as unknown/blank, or (b) stamp the - current default model from ~/.cursor/cli-config.json (composer-1 right now)? - - ➡️ (a) unknown/blank. The config records today's default, not what a past - session actually used — stamping it would fabricate data. - - --- - ❓ Q9 - Agent identity in the report: Name the agent key cursor (matching the - existing .cursor detection in agent-detection.ts and label it "Cursor" in the - Agents view), or cursor-cli/cursor-agent to disambiguate from the IDE? - - ➡️ cursor, label "Cursor" — consistent with the existing detection entry, and - since the tracking DB blends IDE-assisted edits anyway, the broader name is - more honest than cursor-cli. - - One glossary note I'll capture once Q6 settles: external (native-external — - unowned sessions of agents CodeMie manages) vs unmanaged (native-unmanaged — - agents CodeMie only reads analytics for) are distinct terms in this codebase, - and your request is really about the latter. - -⏺ Ran 3 stop hooks (ctrl+o to expand) - ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: - command not found - -✻ Cooked for 10m 22s - -❯ I accept recommended answers - -⏺ All accepted. One fact gates the next round — whether the tracking DB's - conversationId actually matches the transcript UUIDs — so let me check that - now. - - Read 1 file, listed 1 directory, ran 2 shell commands (ctrl+o to expand) - -⏺ Write(CONTEXT.md) - ⎿  Wrote 24 lines to CONTEXT.md - 1 # CodeMie Code Analytics - 2 - lytics. CodeMie both launches agents itself and reads usage left - behind by agents it never launched; the vocabulary below keeps th - ose apart. - 5 ## Language - 6 - 7 **Managed agent**: - codex, gemini, copilot-cli). - 9 _Avoid_: installed agent, native agent - … +25 lines (ctrl+o to expand) - ⎿  PostToolUse:Write hook returned blocking error - ⎿  [cd "$CLAUDE_PROJECT_DIR" && npm run format]: - Oops! Something went wrong! :( - - ESLint: 9.39.2 - - Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' imported - from /Users/gokhan_ozdemir/.herdr/worktrees/codemie-code/wt-feature-cursor- - analytics-support/eslint.config.mjs - at Object.getPackageJSONURL - (node:internal/modules/package_json_reader:301:9) - at packageResolve (node:internal/modules/esm/resolve:784:25) - at moduleResolve (node:internal/modules/esm/resolve:873:18) - at defaultResolve (node:internal/modules/esm/resolve:1006:11) - at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20) - at #resolveAndMaybeBlockOnLoaderThread - (node:internal/modules/esm/loader:728:38) - at ModuleLoader.resolveSync (node:internal/modules/esm/loader:766:56) - at #resolve (node:internal/modules/esm/loader:690:17) - at ModuleLoader.getOrCreateModuleJob - (node:internal/modules/esm/loader:610:35) - at ModuleJob.syncLink (node:internal/modules/esm/module_job:277:33) -⏺ CONTEXT.md is created (the post-write format hook fails because this worktree - has no node_modules — npm install hasn't been run here; worth knowing before - implementation, since that hook will complain on every edit). - - Final round — the last open decisions: - - ❓ Q10 - DB-only conversations: ai_code_hashes contains conversations with no - transcript on disk (e.g. IDE composer sessions such as 484a9c01…, and 474 rows - attributed to human). Should the adapter (a) create session rows only for - transcript-backed sessions, using the DB purely as enrichment (model, file - names, activity window), or (b) also synthesize rows for DB-only conversations - to capture IDE composer usage? - - ➡️ (a). A transcript is what makes something a session in this model; DB-only - rows have no prompts/turns and would produce ghost sessions with almost every - column empty. IDE-composer coverage can be a follow-up if you miss it. - - --- - ❓ Q11 - What a Cursor session row shows: Concretely, per transcript-backed - session: prompts and turns from the JSONL; project/cwd from the directory - slug; start/end from DB timestamps when the join hits, else file - birth/modification time; model from the DB (with the literal default treated - as unknown, per the Q8 rule against fabricating model names); files-touched - set from ai_code_hashes.fileName; tokens, cost, and lines added/removed left - blank (not derivable). Acceptable? - - ➡️ Yes — this is the maximum honest extraction from what Cursor persists. - - --- - ❓ Q12 - Discovery window: Follow the copilot-cli convention — default - maxAgeDays 30, honor the adapter's cwd filtering — with no Cursor-specific - knobs? - - ➡️ Yes, pure convention-following. - - --- - ❓ Q13 - Stale doc while we're there: The exploration found AGENTS.md still - describes copilot-cli as "Analytics ingestion only", but the code has since - made it a fully managed agent. When adding the cursor row to the plugin table, - should I also correct the stale copilot-cli row, or leave it untouched? - - ➡️ Correct it in the same change — the repo's own policy is to report/fix - stale guides, and touching the same table twice in two PRs is churn. - - Answer these and the frontier is empty — I'll then summarize the shared - understanding for your confirmation before any implementation. - -⏺ Ran 3 stop hooks (ctrl+o to expand) - ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: - command not found - -✻ Sautéed for 1m 34s - -❯ I accept recommended answers. - also here is a sample output report that does not include cursor usage. - file:///Users/gokhan_ozdemir/Sites/airun-coach-cockpit/codemie-analytics-gokh - an-ozdemir-epam-com-2026-09-03.html - generated with "codemie analytics show --include-external --report --open" - - Ran 1 shell command (ctrl+o to expand) - -⏺ Your sample report confirms the diagnosis: it contains only claude, codex, and - copilot-cli rows (194 of them tagged native-external) — Cursor is absent - because no adapter exists for it, not because of the flag. - - The frontier is empty. Here is the shared understanding we've built: - - Problem: Cursor usage never appears in codemie analytics because CodeMie has - no Cursor session adapter. The --include-external flag was never the lever — - it gates unowned sessions of managed agents. - - Design: - 1. New analytics-only plugin cursor (src/agents/plugins/cursor/, label - "Cursor") with analyticsOnly: true — sessions tagged native-unmanaged, visible - by default, no flag needed. Registered in AgentRegistry and added to - NATIVE_AGENTS in native-loader.ts. - 2. Data sources (read-only, fail-soft): session rows come from - ~/.cursor/projects//agent-transcripts//.jsonl (prompts, turns, - project); enrichment joins ~/.cursor/ai-tracking/ai-code-tracking.db on - conversationId for model, files touched, and activity timestamps, falling back - to file birth/mtime. DB-only conversations (IDE composer, human rows) produce - no session rows. The opaque chats/*/store.db is out of scope. - 3. Honest gaps: tokens, cost, and line counts stay blank (Cursor doesn't - persist them); model shows unknown when the DB has none or says the literal - default — never stamped from cli-config.json. - 4. Conventions: maxAgeDays 30 default, standard cwd filtering, labels/colors - added in agent-labels.ts and the duplicated table in report/client/app.js. - 5. Docs: add the cursor row to the AGENTS.md plugin table and fix the stale - copilot-cli "analytics ingestion only" row in the same change. - - Also captured: a new CONTEXT.md at the repo root with the managed / - analytics-only / external / unmanaged glossary. Two practical notes for - implementation time: this worktree has no node_modules (the format hook fails - on every write until npm install runs), and your installed CLI accepts - analytics show while this branch's source registers the options on codemie - analytics directly — worth a version check when validating. - - Confirm this matches your intent and I'll start implementing. - -⏺ Ran 3 stop hooks (ctrl+o to expand) - ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: - command not found - -✻ Worked for 23s - -❯ crete /to-spec and /to-tickets based on what you've learned - -⏺ Skill(writing-for-agents) - ⎿  Successfully loaded skill - - Read 1 file, listed 1 directory (ctrl+o to expand) - -⏺ to-spec and to-tickets already exist in your skills directory — let me look - before overwriting. - - Ran 1 shell command (ctrl+o to expand) - -⏺ These already exist as skills in your library — so I'll run them on what we - just grilled: /to-spec first (it needs a seam check with you before - publishing), then /to-tickets. - -⏺ Skill(to-spec) - ⎿  Successfully loaded skill - -⏺ User answered Claude's questions: - ⎿  · Does the proposed test seam match your expectations — one seam, the - Cursor SessionAdapter (discoverSessions/parseSessionFile) tested against a - fixture ~/.cursor tree via a CURSOR_HOME-style override, mirroring the - copilot-cli test prior art? → Higher: loader seam - · Where should the spec (and later the tickets) be published? → GitHub - issues - -⏺ Seam settled at the loader (loadNativeSessions()), publishing to GitHub - issues. Writing the spec now. - - Made 1 scratchpad edit +64, ran 2 shell commands (ctrl+o to expand) - ⎿  PostToolUse:Write hook returned blocking error - ⎿  [cd "$CLAUDE_PROJECT_DIR" && npm run format]: - Oops! Something went wrong! :( - - ESLint: 9.39.2 - - Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' imported - from /Users/gokhan_ozdemir/.herdr/worktrees/codemie-code/wt-feature-cursor- - analytics-support/eslint.config.mjs - at Object.getPackageJSONURL - (node:internal/modules/package_json_reader:301:9) - at packageResolve (node:internal/modules/esm/resolve:784:25) - at moduleResolve (node:internal/modules/esm/resolve:873:18) - at defaultResolve (node:internal/modules/esm/resolve:1006:11) - at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20) - at #resolveAndMaybeBlockOnLoaderThread - (node:internal/modules/esm/loader:728:38) - at ModuleLoader.resolveSync (node:internal/modules/esm/loader:766:56) - at #resolve (node:internal/modules/esm/loader:690:17) - at ModuleLoader.getOrCreateModuleJob - (node:internal/modules/esm/loader:610:35) - at ModuleJob.syncLink (node:internal/modules/esm/module_job:277:33) - -⏺ The fork has issues disabled — enabling them, since you chose GitHub issues as - the tracker. - - Ran 1 shell command (ctrl+o to expand) - -⏺ Spec published: https://github.com/gokhanozdemir/codemie-code/issues/1 (issues - were disabled on the fork; I enabled them). Now /to-tickets. - -⏺ Skill(to-tickets) - ⎿  Successfully loaded skill -⏺ All context is in hand from the grilling and spec. Here's the proposed - tracer-bullet breakdown: - - 1. Cursor sessions appear in codemie analytics (transcripts only) - - Blocked by: none (can start immediately) - - Delivers: the core tracer bullet — a cursor analytics-only plugin (registry - entry, native-agents list, Cursor-home resolution with env override, session - adapter over transcript JSONLs) so that running codemie analytics shows Cursor - sessions tagged unmanaged, visible by default, with prompts/turns/project and - file-time timestamps; tokens/cost/model honestly blank; CLI agent label - "Cursor". Missing Cursor home yields zero rows, no error. Demoable end-to-end - on your machine immediately. - - 2. Enrich Cursor sessions from the AI-tracking database - - Blocked by: 1 - - Delivers: sessions gain model (with the literal default shown as unknown), - files-touched set, and accurate activity windows via the read-only - conversation-id join; a missing or schema-drifted database degrades cleanly - back to ticket 1 behavior. Demo: your grok-4.6 sessions show their model. - - 3. Cursor in the HTML report surfaces - - Blocked by: 1 - - Delivers: --report --open renders Cursor with its own label and color in the - Agents view and everywhere agents are listed; Cursor sessions classify as - "pure chat" in Frameworks compare. Demo: regenerate your sample report and - Cursor appears. - - 4. Docs: AGENTS.md plugin table - - Blocked by: 1 - - Delivers: the plugin table documents cursor (analytics ingestion only) and - corrects the stale copilot-cli "analytics ingestion only" row to managed-agent - status. - - 5. Loader-seam tests with fixture Cursor home - - Blocked by: 1, 2 - - Delivers: Vitest coverage at the loadNativeSessions() seam against a fixture - Cursor home (transcripts + fixture SQLite DB): discovery, unmanaged tagging, - default visibility, enrichment hit, fail-soft degradation, empty-home case. - (Included because you chose the seam explicitly — cut it if you'd rather defer - per the tests-on-request policy.) - - Quiz before publishing: - - Does the granularity feel right? (1 is the largest; it mirrors the existing - copilot-cli adapter shape, so I'd keep it whole rather than split - discovery/parse.) - - Blocking edges correct? Notably 2, 3, 4 are all parallel once 1 lands — only - 5 waits on two tickets. - - Keep, merge, or drop ticket 5? - -⏺ Ran 3 stop hooks (ctrl+o to expand) - ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: - command not found - -✻ Churned for 4m 8s - -※ recap: Goal: add Cursor usage to codemie analytics. Spec is published as GitHub issue #1; I've drafted five tickets and need your approval of the breakdown (granularity, blocking edges, keep or drop the tests ticket) before publishing them. (disable recaps in /config) - -❯ Breakdown looks right, publish the tickets - - Ran 5 shell commands, wrote 1 memory (ctrl+o to expand) - ⎿  PostToolUse:Write hook returned blocking error - ⎿  [cd "$CLAUDE_PROJECT_DIR" && npm run format]: - Oops! Something went wrong! :( - - ESLint: 9.39.2 - - Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@eslint/js' imported - from /Users/gokhan_ozdemir/.herdr/worktrees/codemie-code/wt-feature-cursor- - analytics-support/eslint.config.mjs - at Object.getPackageJSONURL - (node:internal/modules/package_json_reader:301:9) - at packageResolve (node:internal/modules/esm/resolve:784:25) - at moduleResolve (node:internal/modules/esm/resolve:873:18) - at defaultResolve (node:internal/modules/esm/resolve:1006:11) - at #cachedDefaultResolve (node:internal/modules/esm/loader:708:20) - at #resolveAndMaybeBlockOnLoaderThread - (node:internal/modules/esm/loader:728:38) - at ModuleLoader.resolveSync (node:internal/modules/esm/loader:766:56) - at #resolve (node:internal/modules/esm/loader:690:17) - at ModuleLoader.getOrCreateModuleJob - (node:internal/modules/esm/loader:610:35) - at ModuleJob.syncLink (node:internal/modules/esm/module_job:277:33) - -⏺ All five tickets are published and labeled ready-for-agent on your fork, each - linking the spec (#1) as parent and declaring its blocking edges: - - - #3 — Cursor sessions in codemie analytics (transcript-backed tracer bullet) - — no blockers, the frontier starts here - - #4 — Enrich Cursor sessions from the AI-tracking database — blocked by #3 - - #5 — Cursor in the HTML report surfaces — blocked by #3 - - #6 — Docs: cursor + stale copilot-cli rows in AGENTS.md — blocked by #3 - - #7 — Loader-seam tests with fixture Cursor home — blocked by #3 and #4 - - Once #3 lands, #4/#5/#6 can run in parallel. I also saved a project memory - pointing at the spec, tickets, and the verified Cursor data-format facts, so a - future session can pick this up cold. When you're ready to build, - /implement-spec pointed at issue #1 fits this graph directly — just note the - worktree needs npm install first (the format hook currently fails on every - file write without it). - -⏺ Ran 3 stop hooks (ctrl+o to expand) - ⎿  Stop hook error: Failed with non-blocking status code: sh: tsc: - command not found - -✻ Cooked for 3m 22s - -※ recap: Goal: add Cursor usage to codemie analytics as an analytics-only agent. Design was grilled, spec published as issue #1 with tickets #3–#7 on your fork. Next action: implement ticket #3, running npm install in the worktree first. (disable recaps in /config) \ No newline at end of file diff --git a/CONTEXT.md b/CONTEXT.md deleted file mode 100644 index d244764b5..000000000 --- a/CONTEXT.md +++ /dev/null @@ -1,20 +0,0 @@ -# CodeMie Code Analytics - -Terminology for how CodeMie Code classifies agent sessions in analytics. CodeMie both launches agents itself and reads usage left behind by agents it never launched; the vocabulary below keeps those apart. - -## Language - -**Managed agent**: -An agent CodeMie installs, configures, and launches (e.g. claude, codex, gemini, copilot-cli). -_Avoid_: installed agent, native agent - -**Analytics-only agent**: -An agent CodeMie never installs or launches but whose locally persisted sessions it reads for analytics (`analyticsOnly: true` in plugin metadata; e.g. cursor). -_Avoid_: external agent, ingestion-only agent - -**External session**: -A session CodeMie did not launch, so it carries no ownership marker (provider tag `native-external`). Applies to every agent alike, managed or analytics-only. Hidden by default; shown with `--include-external`. -_Avoid_: unmanaged session, foreign session - -**Ownership marker**: -The sidecar record in `~/.codemie/sessions/` that proves CodeMie launched a given agent session; its absence is what makes a managed agent's session external. diff --git a/docs/adr/0001-cursor-session-discovery-from-state-vscdb.md b/docs/adr/0001-cursor-session-discovery-from-state-vscdb.md deleted file mode 100644 index 34a2299fd..000000000 --- a/docs/adr/0001-cursor-session-discovery-from-state-vscdb.md +++ /dev/null @@ -1,69 +0,0 @@ -# ADR 0001 — Cursor session discovery reads `state.vscdb` - -- Status: Accepted -- Date: 2026-09-04 -- Applies to: `src/agents/plugins/cursor/` - -## Context - -Cursor is an analytics-only agent: CodeMie never installs, configures or launches it, and only -reads what Cursor has already written to disk (see the `cursor` row in [AGENTS.md](../../AGENTS.md) -and [docs/CURSOR_INTEGRATION.md](../CURSOR_INTEGRATION.md)). - -Cursor exposes no local API and no supported export for agent conversations. Three local stores -carry parts of the picture, all keyed by the same `composerId`: - -| Store | Location | Carries | -|---|---|---| -| Agent transcripts | `~/.cursor/projects//agent-transcripts//.jsonl` | role-tagged text, `tool_use` blocks, turn markers, a human-readable prompt stamp | -| AI-tracking database | `~/.cursor/ai-tracking/ai-code-tracking.db` | model, edited file paths, edit timestamps | -| Application state store | `state.vscdb` under Cursor's per-OS app-data directory | `composerHeaders` (one row per conversation), `cursorDiskKV` (one row per turn/bubble) | - -Transcripts alone were tried first and proved insufficient: they exist for only a small fraction -of real conversations, carry no timestamps, no model and no token counts, and give no reliable -project path (only a slug that has to be walked back to a directory). A transcript-only report -therefore under-counts Cursor usage badly and mis-attributes the sessions it does find. - -`state.vscdb` is VS Code's (and hence Cursor's) internal, undocumented state store. It is not a -public API, its schema can change in any Cursor release, and it is large — up to ~1.4 GB of -mostly unrelated editor state. - -## Decision - -`composerHeaders` in `state.vscdb` is the **primary** discovery source for Cursor sessions; -transcripts are secondary and joined by the shared `composerId`. Discovery unions the two id -sets, so a header without a transcript and a transcript without a header both produce a row. -`cursorDiskKV` supplies per-turn tool outcomes and the sparse token signal that gates partial -pricing. The AI-tracking database supplies model and edited files. - -Constraints accepted with that decision: - -- **Read-only.** Every database is opened with `readOnly: true` and only ever `SELECT`ed. - CodeMie must never write to, migrate, or lock a store Cursor owns. -- **Fail-soft by mandate.** A missing file, a missing `node:sqlite` (Node < 22.5), a renamed - table or column, a corrupt or locked database, or a malformed row degrades to fewer facts — - never to a thrown error. A Cursor release must never be able to break `codemie analytics`. -- **Scoped queries.** `cursorDiskKV` is filtered by `composerId` in SQL (parameterized, never - interpolated) rather than scanned, because of its size. -- **No invented facts.** `default` — Cursor's sentinel for delegated model choice — is reported - as `Auto`, the term Cursor's own usage export uses, never as a concrete model name. Sessions - with no token signal report usage as unmeasurable rather than as zero. -- **Draft rows excluded.** `isDraft: true` headers are conversations that were never started. - -## Consequences - -- Cursor coverage is dramatically better than transcript-only discovery, and project path, - branch and line counts come from Cursor's own totals instead of being reconstructed. -- CodeMie depends on an undocumented schema. The fail-soft mandate is what makes that - acceptable: the failure mode of schema drift is a thinner report, not a broken command. -- `CURSOR_HOME` relocates all three stores (with `state.vscdb` under `User/globalStorage`), - which is what lets the whole path be tested against a fixture tree. - -## Future work - -### Cursor Enterprise Team Analytics API - -Cursor publishes an official [Team Analytics API](https://cursor.com/docs/account/teams/analytics-api). -CodeMie does **not** integrate it. It is recorded as a known, deferred capability — with the -constraints already agreed for whenever it is built — in -[`.ai-run/guides/integration/external-integrations.md`](../../.ai-run/guides/integration/external-integrations.md#cursor-enterprise-team-analytics-api-not-integrated). From 50fbc10bb3298c97581b7b7d7bd33c600ae6cd51 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:39:39 +0300 Subject: [PATCH 32/34] chore: stop tracking local .scratch notes .gitignore already excludes .scratch/; drop the previously committed files from the tree so they stay local only. Co-authored-by: Cursor --- .../issues/01-drop-included-unknown-dashes.md | 14 --- .../02-auto-unpriced-sonnet-estimate.md | 14 --- .../issues/03-cursor-only-empty-state.md | 13 -- .../issues/04-docs-sparse-cursor-tokens.md | 12 -- .../05-research-alternate-token-sources.md | 106 ---------------- .../06-opt-in-team-analytics-section.md | 17 --- .../issues/07-team-analytics-admin-only.md | 14 --- .../issues/08-docs-admin-vs-member-csv.md | 19 --- .../issues/09-import-cursor-usage-csv.md | 17 --- .../10-optional-cookie-fetch-usage-csv.md | 17 --- .../cursor-analytics-cost-honesty/spec.md | 115 ------------------ 11 files changed, 358 deletions(-) delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md delete mode 100644 .scratch/cursor-analytics-cost-honesty/spec.md diff --git a/.scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md b/.scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md deleted file mode 100644 index d9a1b97d0..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/01-drop-included-unknown-dashes.md +++ /dev/null @@ -1,14 +0,0 @@ -# 01: Drop “Included”; unknown cost/tokens are dashes - -**What to build:** The analytics HTML report never presents subscription wording for missing usage. Cost and token cells for unmeasurable sessions show an em dash. Mixed groups still show the sum of whatever was measured. Session-modal copy no longer says usage was covered by a subscription. - -**Blocked by:** None (can start immediately). - -**Status:** done (commit 0e56e45) - -- [x] No cost-formatting path in the report client emits the string `Included` -- [x] Unmeasurable sessions render `—` for cost and for token fields (not `$0.00` / `0`) -- [x] Aggregates over a mixed measured+unmeasurable set still show the measured sum -- [x] Session modal cost subtitle no longer says “covered by subscription” -- [x] Regenerating a report with `--include-external` and filtering to Cursor-only shows dashes for cost/tokens, not Included -- [x] Non-Cursor agents’ measurable totals are unchanged for the same underlying sessions diff --git a/.scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md b/.scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md deleted file mode 100644 index 235531ca7..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/02-auto-unpriced-sonnet-estimate.md +++ /dev/null @@ -1,14 +0,0 @@ -# 02: Auto/unpriced token sessions get Sonnet-equivalent estimates - -**What to build:** When a session has recoverable tokens but the model cannot be priced (Auto, default, unknown, or otherwise missing from the price table), the report shows an API-equivalent USD estimate using the documented Claude Sonnet rate stand-in, keeps the original model label on the session, and marks the usage as partial. Sessions whose tracking model already prices normally keep using that model’s rates. - -**Blocked by:** None (can start immediately). - -**Status:** done (commit 4630ca6) - -- [x] Tokens + Auto/unpriced model → nonzero USD estimate, `usagePartial` set, displayed model still Auto/original (not renamed to Sonnet) -- [x] Tokens + priced model (e.g. a real tracking-db id) → that model’s rates; Sonnet fallback not applied -- [x] No token signal → no fabricated estimate; provenance stays unmeasurable (dashes after 01) -- [x] Partial badge / copy still indicates the figure is understated or estimated -- [x] Coverage still treats “had recoverable usage” as priced when tokens were adopted from adapter provenance -- [x] Verifiable via enricher/native Cursor fixtures without requiring a live `state.vscdb` diff --git a/.scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md b/.scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md deleted file mode 100644 index 504966c57..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/03-cursor-only-empty-state.md +++ /dev/null @@ -1,13 +0,0 @@ -# 03: Cursor-only empty state when no local token signal - -**What to build:** When every session in view is unmeasurable (the common Cursor-only case after deselecting other agents), Overview and Cost KPIs stay on dashes and briefly explain that local token telemetry is absent — so the collapse no longer reads as a broken agent-chip filter. Tool-call and other non-usage panels keep working. - -**Blocked by:** 01 — Drop “Included”; unknown cost/tokens are dashes - -**Status:** done (commit 0e56e45) - -- [x] All-unmeasurable filtered set → Overview Input/Output/Total tokens and Est. cost show `—` (not `$0` / Included) -- [x] A short subtitle or empty-state note states local token telemetry is absent for sessions in view -- [x] Agent chips still filter by agent name only; no model-chip behaviour introduced -- [x] Cursor tool-call success/failure tables remain populated when bubbles carried tool outcomes -- [x] Mixed views that include at least one measured session still show that session’s tokens/cost normally diff --git a/.scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md b/.scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md deleted file mode 100644 index afb6c2e6a..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/04-docs-sparse-cursor-tokens.md +++ /dev/null @@ -1,12 +0,0 @@ -# 04: Docs — recent Cursor bubble tokens are sparse/absent - -**What to build:** Operator and integration docs state the verified local reality: recent Cursor builds often write zero (or omit) billable `tokenCount` on bubbles while tool outcomes still appear; the Team Analytics API still does not return token or cost fields; ADR 0001 fail-soft / opt-in external / no silent network constraints remain the contract. - -**Blocked by:** None (can start immediately). - -**Status:** done (commit db114bc) - -- [x] Cursor integration / external-integrations docs mention sparse or absent recent bubble token signals vs working tool enrichment -- [x] Docs restate that Team Analytics endpoints do not provide tokens/cost and cannot alone close that gap -- [x] Docs do not instruct operators to treat “Included” as the expected cost label (aligned with 01) -- [x] ADR 0001 is not contradicted (read-only, fail-soft, Auto display label, no invented invoice certainty) diff --git a/.scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md b/.scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md deleted file mode 100644 index 258a01bd5..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/05-research-alternate-token-sources.md +++ /dev/null @@ -1,106 +0,0 @@ -# 05: Research spike — alternate recent Cursor billable-token sources - -**What to build:** A written go/no-go on whether any other local or exportable Cursor artifact carries recent billable input/output tokens. Negative evidence is an acceptable outcome. No new production reader ships in this ticket; findings feed ticket 06 and any later token-source work. - -**Blocked by:** 04 — Docs — recent Cursor bubble tokens are sparse/absent - -**Status:** done — local NO-GO, but SUPERSEDED by #21 (dashboard usage CSV has the tokens; see amendment at the end) - -- [x] Spike notes which stores/exports were checked and what each carries (or lacks) for recent sessions -- [x] Explicit conclusion: viable source found vs none found for recent billable I/O -- [x] Confirms Team Analytics still lacks token/cost fields (or documents a change if upstream added them) -- [x] Does not widen default discovery max-age solely to harvest year-old bubble tokens as “the fix” -- [x] Does not invent tokens from context-window fill, transcript length, or tool-call counts -- [x] Findings appended under this ticket (or linked artifact) so 06 can proceed without rediscovery - ---- - -## Findings (spike run 2026-09-05) - -**Conclusion: NO-GO. No local or exportable Cursor artifact carries recent billable input/output -tokens.** Nothing new ships from this ticket; the local floor documented in 04 stands. - -Method: read-only inspection of one operator machine's live Cursor installation (databases copied -to a scratch dir before querying, so no lock was taken on Cursor's own files). - -### Stores checked - -| Store | Recent billable tokens? | What it actually carries | -|---|---|---| -| `state.vscdb` → `cursorDiskKV` `bubbleId:*` | **No** | 5,134 of 5,177 bubbles carry a `tokenCount` object, but 5,080 are `{inputTokens:0, outputTokens:0}`. `toolFormerData` works throughout. | -| `state.vscdb` → `composerHeaders` | **No** | Discovery only (501 rows, 0–72 days old). No usage fields. | -| `state.vscdb` → `cursorDiskKV` `composerData:*` | **No** | `contextTokensUsed`, `contextTokenLimit`, `totalUsedTokens`, `promptTokenBreakdown`, `estimatedTokens` — **context-window fill, not billing**. Explicitly out of scope. | -| `state.vscdb` → `cursorDiskKV` `agentKv:*` | **No** | An opaque blob cache of *other* tools' cached payloads and file contents (Copilot extension telemetry, MCP tool results, and a mock usage-export document with placeholder values like `developer@company.com`). Not a Cursor usage ledger, and it holds third-party secrets — reading it would be actively wrong. | -| `state.vscdb` → `cursorDiskKV` `messageRequestContext:*` | **No** | Prompt-assembly context (git status, project layouts, attached files). | -| `state.vscdb` → `ItemTable` | **No** | Only billing-*banner dismissal* flags (`cursor.billingBanner.*`, `cursor.dismissedCreditGrantIds`) and auth tokens. No usage figures. | -| `~/.cursor/ai-tracking/ai-code-tracking.db` | **No** | `ai_code_hashes`, `scored_commits`, `conversation_summaries`, `tracked_file_content`. Line-attribution and model labels only; zero token columns. | -| `conversation-search.db` (globalStorage) | **No** | FTS index over conversation titles/text. The only `token` match is the FTS `tokenize=` pragma — a text tokenizer, not billing. | -| `~/.cursor/chats/*/*/store.db` (31 stores) | **No** | `blobs` + `meta`. 2,887 blobs decoded and 31 meta rows decoded: zero token-shaped fields. `meta` carries `agentId`, `name`, `mode`, `createdAt`, `lastUsedModel`. | -| `~/.cursor/projects/*/agent-transcripts/*.jsonl` | **No** | Only `token_budget` / `tokens` strings originating from MCP *tool payloads*, not Cursor usage. | -| Team Analytics API | **No** | Re-verified against the live docs (below). | - -### The decisive cross-check - -Nonzero `tokenCount` bubbles exist but belong to a disjoint, aged-out population: - -- 31 composers hold all 54 nonzero-token bubbles; their ages are **354–408 days**. -- **0 of those 31 appear in `composerHeaders`**, so they are undiscoverable by design. -- Of the 3,671 bubbles under the 501 *discoverable* composers, **every single `tokenCount` is zero**. - -So the token signal has not moved to another store — it stopped being written. No reader change can -recover it, and widening `--max-age` would only resurface year-old conversations to manufacture a -total that says nothing about recent work (explicitly rejected). - -### Team Analytics API re-verification - -Fetched on 2026-09-05. Documented response -fields are diff/acceptance and activity counters — `total_suggested_diffs`, `total_accepted_diffs`, -`total_rejected_diffs`, `total_green_lines_accepted`, `total_red_lines_accepted`, `total_suggestions`, -`total_accepts`, `total_rejects`, `messages`, `command_name`, `skill_name`, `model`. **No token or -cost fields at any tier** — unchanged from the guide's existing claim. Auth is an API key -(`-u YOUR_API_KEY:`); by-user filtering via a `users` parameter of email addresses is supported, -which is what makes ticket 06's user-scoped constraint achievable. - -### What this means for ticket 06 - -06 may proceed, but strictly as **non-token aggregates in a separate labelled section**. This spike -found no token source, so 06 must not be presented as closing the cost gap. - -### Amendment (2026-09-05 evening) — dashboard usage CSV is GO (members) - -Reopened after operator-provided export -`team-usage-events-17821605-2026-09-05.csv` and live probe of -`GET cursor.com/api/dashboard/export-usage-events-csv?strategy=tokens`: - -- CSV carries Date, User, Kind, Model, input/cache/output tokens, Total Tokens, **Cost**. -- Sample: 61 rows, all `Kind=Included`, yet Cost summed ≈ **$25.25** with large token totals — - `Included` is a billing category, not “no cost”. -- Admin `crsr_` key → **401** on this endpoint (member-usable via session cookie / UI download). -- Session cookie `WorkosCursorSessionToken=::` → **200** CSV. - -**Audience split (product decision):** - -- **Enterprise team admins** — keep opt-in Team Analytics API (ticket 06) for non-token aggregates; clarify admin-only in 07/08. -- **Team members** — usage-events CSV file import (09) and optional cookie fetch (10) for tokens + Cost. - -Do **not** roll back Team Analytics entirely; do not tell members to use the admin API for billable usage. - ---- - -## Amendment (2026-09-05, after issue #21) - -**The NO-GO conclusion above is superseded.** This spike searched only *local* stores and its -local findings stand — no local artifact carries recent billable tokens. But it never checked -Cursor's **dashboard usage export**, which does. - -Verified against a real export (`team-usage-events-*.csv`, 2026-09-05): 61 events, all -`Kind=Included`, carrying **39,952,466 tokens and $25.25 of cost**. A second export from the same -day held 380 events and 201,523,437 tokens. - -`Included` is Cursor's billing category — "covered by your plan" — not a claim that the usage was -free or unmeasured. Reading it as "no cost" is exactly the mistake that made this data look -worthless. - -The export is now imported via `--cursor-usage-csv` (issue #21, commit 2fb0c9e). The "Do not widen -discovery max-age" and "do not invent tokens from context fill / transcript length / tool counts" -conclusions are unaffected and still binding. diff --git a/.scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md b/.scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md deleted file mode 100644 index a0346560f..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/06-opt-in-team-analytics-section.md +++ /dev/null @@ -1,17 +0,0 @@ -# 06: Opt-in Cursor Team Analytics section (non-token aggregates) - -**What to build:** An optional, explicitly flagged, credential-gated pull of Cursor Team Analytics for the requesting user only, rendered as a separate labelled section in the analytics report. Shows only what the API actually returns (edits, models, etc.). Never merges into the local session table, never makes silent network calls, and never fabricates tokens/cost from this API. - -**Blocked by:** 05 — Research spike — alternate recent Cursor billable-token sources - -**Status:** done — but re-scoped by GitHub #23: Team Analytics is enterprise-ADMIN-only and is not the member path to tokens/cost. Members use `--cursor-usage-csv` (#21). This ticket is retained as historical; it should not be read as "Team Analytics answers cost". — keep for enterprise admins; members use CSV (09/10). Clarify audience via 07/08. - -- [x] No Team Analytics network call runs unless both a configured credential and an explicit invocation opt-in are present -- [x] Data scope is the requesting user’s own email (`by-user`); no team-wide or leaderboard dump into personal analytics -- [x] Report renders Team Analytics in a separate labelled section, not inside the local session rows -- [x] Local session table and Team Analytics section are not silently joined on missing composerId keys -- [x] Tokens/cost are not invented from Team Analytics responses -- [x] Fail-soft: API/auth failures degrade to an empty/omitted section without breaking the local report -- [x] Behaviour respects conclusions from 05 (e.g. if a better token source was found, this ticket still does not pretend Team Analytics supplies tokens unless upstream changed) - -Audience clarification 2026-09-05: **retain** this feature for enterprise **team admins** only. Ordinary members cannot use the admin API key path for billable usage — they use dashboard usage-events CSV (tickets 09/10). Tickets 07/08 update product copy and docs; do not delete the admin opt-in. diff --git a/.scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md b/.scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md deleted file mode 100644 index 6e61c7186..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/07-team-analytics-admin-only.md +++ /dev/null @@ -1,14 +0,0 @@ -# 07: Keep Team Analytics admin-only; stop presenting it as the member path - -**What to build:** Retain the opt-in Cursor Team Analytics pull for **enterprise team admins** who have an admin-scoped API key, but make the product surface unmistakable: members without admin access cannot use it and should use the usage CSV path (09) instead. Remove or rewrite any copy that implies a non-admin `crsr_` / Team Analytics key closes tokens/cost for ordinary team members. Do **not** delete the admin feature unless docs/CLI currently claim members can use it for billable usage — in that case fix the claim, keep the gate. - -**Blocked by:** None (can start immediately). - -**Status:** ready-for-agent - -- [ ] `--cursor-team-analytics` + admin API key remain available for enterprise **admins** -- [ ] CLI help, flag description, and empty-state copy state clearly: **enterprise team admins only** — not for ordinary team members -- [ ] Members who lack an admin key get a clear message pointing at usage CSV import (09), not a auth-failure dead end framed as “set CURSOR_TEAM_ANALYTICS_API_KEY” -- [ ] Team Analytics section (when present) stays labelled as admin/team-API aggregates and still does **not** claim to supply per-session billable tokens/cost -- [ ] No silent network calls without both flag and credential (existing gate preserved) -- [ ] User-scoped `by-user` filter behaviour for the admin pull is unchanged unless already wrong diff --git a/.scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md b/.scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md deleted file mode 100644 index b4aec5788..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/08-docs-admin-vs-member-csv.md +++ /dev/null @@ -1,19 +0,0 @@ -# 08: Docs — admin Team Analytics vs member usage CSV - -**What to build:** Update operator and guide docs so the two Cursor remote/export paths are explicit and non-overlapping: - -1. **Enterprise team admins** — optional `--cursor-team-analytics` + admin-scoped API key for Team Analytics aggregates (edits/models/etc.; not the billable token ledger). -2. **Team members (and anyone without admin API access)** — download Cursor Usage events CSV and pass it via the file flag (09); optional cookie fetch later (10). - -Underline that `Kind=Included` in the CSV is a billing category and rows still carry tokens and `Cost`. Keep report UI honesty: never use “Included” as the cost cell label. - -**Blocked by:** 07 — Keep Team Analytics admin-only; stop presenting it as the member path - -**Status:** ready-for-agent - -- [ ] `docs/ANALYTICS-REPORT.md` documents **two** paths with audience labels: Admin → Team Analytics; Member → usage CSV -- [ ] `docs/CURSOR_INTEGRATION.md` and `.ai-run/guides/integration/external-integrations.md` state Team Analytics is **enterprise-admin-only** and does not return billable token/cost fields -- [ ] Docs describe member flow: Cursor Usage → Export CSV → `--cursor-usage-csv ` (once 09 lands; can stub the flag name agreed in 09) -- [ ] Docs do not tell non-admin members to create/use `CURSOR_TEAM_ANALYTICS_API_KEY` for cost/tokens -- [ ] Honesty wording retained: UI never labels cost cells `Included` / “covered by subscription” -- [ ] Scratch notes (05/06) amended so they don’t read as “remove Team Analytics entirely” diff --git a/.scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md b/.scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md deleted file mode 100644 index d2fd11baa..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/09-import-cursor-usage-csv.md +++ /dev/null @@ -1,17 +0,0 @@ -# 09: Import Cursor usage-events CSV for tokens and cost (members) - -**What to build:** Give **team members** (and anyone without an admin Team Analytics key) a way to pass a locally downloaded Cursor Usage CSV into analytics report generation. CodeMie reads token and `Cost` columns, filters to the report owner’s email when the `User` column is present, and surfaces API-equivalent spend even when every row’s `Kind` is `Included`. Prefer a separate labelled “Cursor usage export” section and/or day–model aggregates clearly marked as export-sourced — do not invent `composerId` joins. No network call in this ticket. Enterprise admins keep Team Analytics (06/07) for non-token aggregates; this ticket is the member billable-usage path. - -**Blocked by:** None (can start immediately). Complements 07/08 (admin Team Analytics kept; members use this path). - -**Status:** ready-for-agent - -- [ ] Explicit CLI flag accepts a filesystem path to a usage-events CSV (e.g. `--cursor-usage-csv `) -- [ ] Parser accepts the observed header set: Date, User, Kind, Model, Input (w/ and w/o Cache Write), Cache Read, Output Tokens, Total Tokens, Cost (tolerate added columns) -- [ ] Rows with `Kind=Included` still contribute tokens and `Cost` (never mapped to “no cost” / Included UI label) -- [ ] When `User` is present, only the report owner’s email rows are kept -- [ ] Export data appears as an opt-in, clearly labelled source (not silently merged into Claude totals) -- [ ] Missing/unreadable file fails soft: report continues; export section omitted with a clear reason -- [ ] Verifiable against a fixture derived from the sample export shape (61 events, models like `auto` / `cursor-grok-*`, nonzero Cost) - -Prototype note (sample export 2026-09-05): all 61 rows were `Kind=Included` yet `Cost` summed to ~$25.25 with large token totals — product must use `Cost`/tokens, not `Kind`. diff --git a/.scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md b/.scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md deleted file mode 100644 index 4f2c05a51..000000000 --- a/.scratch/cursor-analytics-cost-honesty/issues/10-optional-cookie-fetch-usage-csv.md +++ /dev/null @@ -1,17 +0,0 @@ -# 10: Optional cookie fetch of usage-events CSV (after file import) - -**What to build:** After file import works, optionally fetch the same CSV CodeMie already parses by using the signed-in Cursor session cookie from the local app store (`WorkosCursorSessionToken=::`), behind an explicit flag. Never use an admin `crsr_` Team API key for this endpoint. Fail soft; default remains local-only or file-based. - -**Blocked by:** 09 — Import Cursor usage-events CSV for tokens and cost - -**Status:** ready-for-agent - -- [ ] No fetch runs unless an explicit opt-in flag is set (credential/cookie on disk alone is not enough) -- [ ] Auth uses session cookie shape proven against the dashboard export endpoint — not Bearer `crsr_` / Admin API -- [ ] Fetched body is fed through the same CSV parser as 09 (one code path) -- [ ] Date range / team id come from documented operator inputs or safe defaults aligned to the report window -- [ ] 401/403/schema drift → omit export section; local report still succeeds -- [ ] Docs warn this is an undocumented dashboard endpoint and file import remains the supported fallback -- [ ] Secrets are never logged - -Probe note (2026-09-05): `crsr_` → 401; `WorkosCursorSessionToken` with `userId::jwt` → 200 CSV starting with `Date,User,...`. diff --git a/.scratch/cursor-analytics-cost-honesty/spec.md b/.scratch/cursor-analytics-cost-honesty/spec.md deleted file mode 100644 index 8cd3ef3e3..000000000 --- a/.scratch/cursor-analytics-cost-honesty/spec.md +++ /dev/null @@ -1,115 +0,0 @@ -# Cursor analytics: cost honesty + usage signal follow-on - -Status: ready-for-agent - -## Problem Statement - -When I run `codemie analytics --report --open --include-external` and look at Cursor sessions, cost cells say **Included** even though I care about API-equivalent spend estimated from tokens — subscription billing is irrelevant to me. When I deselect Claude (and other agents) in the top bar so only Cursor remains, Input/Output token KPIs collapse to empty dashes. That feels like Cursor data vanished, when what actually happened is: almost every Cursor session in the report has no local billable token signal, Claude was carrying the totals, and the report still labels unmeasurable cost as if it were covered by a plan. - -I want honest empty states, real estimates when any tokens exist (including model=Auto), and a clear follow-on path for restoring recent Cursor usage signals without inventing zeros. - -## Solution - -1. **Cost honesty (local, ship now).** Stop using the word Included / “covered by subscription” anywhere in the analytics report. Unmeasurable sessions show an em dash. When a Cursor (or any) session has recoverable tokens, show an API-equivalent USD estimate even if the model is Auto/unknown/unpriced, using a documented Sonnet-equivalent fallback rate, and keep the existing partial-usage badge so I know the figure is a floor/estimate. -2. **Honest Cursor-only empty state.** When the filtered set has no measurable token totals, Overview and Cost KPIs stay dashes with copy that says local token telemetry is absent — not that spend was free or included. -3. **Follow-on for richer Cursor usage.** Open a separate effort for optional Enterprise Team Analytics integration and/or alternate token sources. Do **not** pretend the Team Analytics API already returns tokens or cost (it does not, per the external-integrations guide). Any remote integration stays opt-in, fail-soft, user-scoped, and visually separate from the local session table. - -## User Stories - -1. As an analytics report reader, I want cost cells never to say “Included”, so that I am not told subscription status instead of an estimate or unknown. -2. As an analytics report reader, I want unmeasurable sessions to show “—” for cost, so that I do not confuse absence of data with free usage. -3. As an analytics report reader, I want unmeasurable sessions to show “—” for tokens, so that structural zeros are not presented as “zero tokens used”. -4. As an analytics report reader, I want mixed groups (some measured, some not) to show the sum of measured costs/tokens, so that known data is not hidden by unknown peers. -5. As an analytics report reader, I want session-modal cost subtitles never to say “covered by subscription”, so that wording matches API-equivalent intent. -6. As an analytics report reader, I want a partial-usage badge when Cursor bubble tokens are sparse, so that I know the estimate understates real usage. -7. As an analytics report reader, I want Input/Output KPIs to remain visible when at least one session in view has measured or partial tokens, so that sparse Cursor signal is not wiped by aggregate helpers. -8. As an analytics report reader, I want Cursor-only views with no token signal to explain that local telemetry is missing, so that deselection of Claude does not look like a filter bug. -9. As an analytics report reader, I want tool-call success/failure for Cursor to keep working independently of tokens, so that #11’s tool path is not regressed by cost-honesty work. -10. As an analytics report reader, I want Claude/Codex/Copilot totals unchanged when Cursor has no tokens, so that honesty fixes do not invent Cursor spend into other agents. -11. As an analytics report reader, I want agent chips to keep filtering by agent name only, so that “unselect Claude” continues to mean the Claude agent, not “any Claude-named model”. -12. As an analytics report reader, I want Cursor sessions whose tracking model is a priced id (e.g. grok-4.6) to be estimated with that model’s rates when tokens exist, so that estimates prefer real attribution. -13. As an analytics report reader, I want Cursor sessions whose model is Auto/default/unknown to still get a USD estimate when tokens exist, so that lack of a concrete model does not force a blank or Included cost. -14. As an analytics report reader, I want that Auto/unknown estimate to use a documented Claude Sonnet API-equivalent rate table entry, so that the stand-in is stable and reviewable. -15. As an analytics report reader, I want Auto/unknown estimates always marked usagePartial, so that I never treat the stand-in as an invoice. -16. As an analytics report reader, I want the original model label (Auto, unknown, etc.) preserved on the session/per-model row, so that the estimate does not silently rename the model to Sonnet. -17. As an analytics report reader, I want pricedSessions / coverage semantics to remain “had recoverable usage”, so that a partial Cursor floor still counts as priced rather than “no token reader”. -18. As an analytics report reader, I want unpriced-model listing to still mention Auto when the original model was Auto, so that coverage diagnostics stay truthful even if a fallback rate was applied. -19. As a CodeMie operator, I want `--include-external` behavior unchanged, so that Cursor remains opt-in and never appears without the flag. -20. As a CodeMie operator, I want analytics without `--include-external` to omit Cursor entirely, so that external sessions stay gated. -21. As a CodeMie operator, I want regenerating a report after these fixes to drop every “Included” string from the HTML client bundle for cost formatting, so that old copy cannot linger. -22. As a CodeMie developer, I want cost enrichment to keep using adapter-supplied `tokensByModel` as the Cursor usage path, so that we do not add a fake per-message usage walk for bubbles. -23. As a CodeMie developer, I want bubble reads to stay fail-soft and read-only, so that Cursor schema drift cannot crash analytics. -24. As a CodeMie developer, I want ADR 0001 respected (no invented concrete model for `default` beyond the display label Auto), so that Auto remains Auto in the UI while cost uses an explicit estimate policy. -25. As a CodeMie developer, I want Overview Est. cost to show “—” when nothing in view is measurable, so that a Cursor-only empty set does not show $0.00. -26. As a CodeMie developer, I want Overview token KPIs to use measured-set semantics rather than raw `tTotal > 0` alone when mixed with unknown sessions, so that provenance stays consistent with Cost tab helpers. -27. As a product owner, I want a follow-on ticket for Cursor Enterprise Team Analytics API integration scoped to what the API actually returns today, so that we do not promise token fields it does not have. -28. As a product owner, I want that follow-on to require both a configured credential and an explicit CLI opt-in flag before any network call, so that local-only analytics stays the default promise. -29. As a product owner, I want Team Analytics data (if integrated) rendered in a separate labelled report section, so that local sessions and team-API aggregates are never silently merged or double-counted. -30. As a product owner, I want Team Analytics pulls filtered to the requesting user’s own email (by-user), so that colleagues’ activity never appears in my personal CodeMie report. -31. As a product owner, I want a research spike in the follow-on for alternate billable-token sources (usage export, future API fields, other local stores), so that the recent-token gap is pursued without pretending bubbles still work for current Cursor builds. -32. As a product owner, I want documentation updated to say recent Cursor builds often write zero `tokenCount` on bubbles while tools still appear, so that operators understand the local floor. -33. As a QA reader, I want a fixture-driven Cursor session with bubble tokens + Auto model to render a non-zero estimate and partial badge, so that the Auto fallback is verifiable without live DB dependence. -34. As a QA reader, I want a fixture-driven Cursor session with no token signal to render “—” for cost and tokens (never Included), so that the empty path is verifiable. -35. As a QA reader, I want a fixture-driven Cursor session with priced non-Auto model + tokens to use that model’s rates, so that fallback does not override real prices. -36. As an analytics report reader, I want cache-read / context-bloat series to keep excluding sessions with no cache concept when only partial input/output exist, so that Cursor does not plot misleading zero-height bloat bars. -37. As an analytics report reader, I want Cost-by-agent charts to omit or dash agents whose sessions are all unmeasurable, so that a Cursor wedge does not appear as $0 “Included”. -38. As a CodeMie developer, I want no change to discovery unions of `composerHeaders` + transcripts for this honesty work, so that session counts stay stable while copy and pricing policy change. -39. As a CodeMie developer, I want no widening of max-age solely to harvest year-old token bubbles as a substitute for recent telemetry, so that we do not paper over the real gap. -40. As a stakeholder, I want the follow-on clearly labelled out-of-band from the honesty ship, so that agents can implement A without blocking on Enterprise research. - -## Implementation Decisions - -### Workstream A — Cost honesty (this ship) - -- Keep Cursor as an analytics-only agent: discover from local stores, tag `native-external`, gate with `--include-external`. Do not install or launch Cursor. -- Keep the existing usage provenance model on parsed sessions: `usageUnavailableReason` when no token signal; `usagePartial` + `tokensByModel` when sparse bubble tokens exist. Do not synthesize Claude-shaped per-message `usage` walks for bubbles. -- Keep cost enrichment’s adapter fallback: when the per-message usage map is empty, adopt `usageMeta.tokensByModel`. Do not add a dedicated Cursor branch to the per-message usage reader dispatcher unless a later change needs per-turn series (bubbles have no reliable per-turn chronology for series). -- **Estimate policy when tokens exist but `lookupPrice(model)` misses:** apply the published Claude Sonnet API-equivalent rate entry already used elsewhere in the pricing table (`claude-sonnet-4` family rates). Preserve the session’s displayed model name (Auto / unknown / original). Mark `usagePartial`. Prefer a real priced tracking-db model whenever lookup succeeds. -- **Report client:** remove the Included unpriced label. Unmeasurable → em dash for USD and tokens. Replace “covered by subscription” modal copy with language about missing local token signal or API-equivalent estimate. Keep the partial-usage note. -- **Overview / Cost empty state:** when the filtered session set has no measured usage, show dashes and a short subtitle that local token telemetry is absent for sessions in view (Cursor-heavy case). Do not change agent-chip filtering semantics. -- Respect ADR 0001: fail-soft, read-only, scoped bubble queries, `default` displayed as Auto, no invented invoice-grade certainty. -- Do not invent token counts for sessions whose bubbles only carry `{inputTokens:0,outputTokens:0}` or no `tokenCount`. - -### Workstream B — Follow-on (separate ticket after A) - -- Cursor Enterprise Team Analytics API remains **not integrated**. Guide fact to preserve: documented endpoints do **not** return token or cost fields; the API cannot alone close the billable-token gap. -- If/when integrated: require credential **and** explicit invocation opt-in; user-scoped `by-user` only; render as a **separate labelled section**; never silently merge into the local session table (unsolved reconciliation: no composerId join key on aggregates). -- Parallel research spike: identify whether any other local or exportable Cursor artifact now carries billable input/output for recent sessions; document negative evidence if none. Do not expand discovery age solely to resurface year-old bubble tokens as “the fix”. -- Update operator docs (`CURSOR_INTEGRATION` / external-integrations) to state that recent Cursor builds often omit nonzero bubble `tokenCount` while `toolFormerData` still works. - -### Confirmed test seams - -1. **Primary:** session cost record after enrichment — feed Cursor-shaped usage provenance through the enricher; assert tokens, estimate USD, partial flag, and absence of subscription semantics. -2. **Secondary:** report client formatting helpers / Overview empty-state contracts — unmeasurable → `—`; measured/partial → numeric; never `Included`. -3. **Follow-on only:** deep module behind a small interface for optional Team Analytics fetch → normalized user-scoped rows for a separate report section (not joined into local sessions). - -## Testing Decisions - -- Good tests assert external behaviour at the seams above (cost record fields; formatting outputs), not SQLite internals or DOM/Chart wiring. -- Prefer existing Vitest patterns around the cost enricher and native Cursor loader fixtures; extend those rather than inventing a third harness. -- Fixture cases for Workstream A: - - tokens + Auto → nonzero estimate, `usagePartial`, model label still Auto - - tokens + priced model → that model’s rates, no unnecessary fallback - - no token signal → `usageUnavailableReason`, cost/tokens format as unknown (dash), never Included - - regression: non-Cursor agents’ priced totals unchanged for the same fixtures -- Workstream B: no implementation tests in A; when B starts, test the opt-in gate (no network without flag+credential) and that team-API data cannot appear inside the local session table payload. -- Tests only when the implementing agent is explicitly asked to write/run them (repo policy), but the seams above are the intended attachment points. - -## Out of Scope - -- Changing agent-chip filters into model filters, or adding model chips (unless a later ticket asks). -- Inventing billable tokens from `contextTokensUsed`, transcript text length, or tool-call counts. -- Merging Team Analytics aggregates into per-session Cursor rows. -- Team-wide / leaderboard data in personal analytics. -- Silent network calls based solely on a configured API token. -- Issue #12 documentation-only Enterprise API write-up as a substitute for this honesty ship (may be folded into Workstream B docs). -- Widening default discovery max-age to harvest legacy bubble tokens. -- Renaming `readCursorBubbles` to a Map-style bubble index, or adding bubble memoization, unless a measured perf need appears. -- Adding a `gatherUsageDeduped('cursor')` branch solely for symmetry with the enricher fallback. - -## Further Notes - -- Live verification on one operator machine (2026-09-05 report): 469 Cursor sessions, 0 with tokens, 0 with `usagePartial`, 469 with `usageUnavailableReason`, 24 with tool calls. Nonzero bubble `tokenCount` composers existed only ~354–408 days ago and were absent from `composerHeaders`. This is why Cursor-only KPI collapse is data-faithful, not a chip bug. -- Original plan `we-the-issues-10-11-transient-crab` Steps 1–3 are largely shipped (bubbles + usageMeta + enricher fallback). Step 4 / Included copy / Auto estimate policy remain the actionable local gap. -- Domain vocabulary: analytics-only agent, `native-external`, `--include-external`, `composerHeaders`, `cursorDiskKV` bubbles, `usagePartial`, `usageUnavailableReason`, `tokensByModel`, API-equivalent estimate, ADR 0001 fail-soft. -- Tracker: this spec lives at `.scratch/cursor-analytics-cost-honesty/spec.md` with triage status `ready-for-agent`. Split implementation issues with `/to-tickets` if desired (A vs B). From 16bba785c890351e0d5585e664d8e1aa2db88f04 Mon Sep 17 00:00:00 2001 From: Gokhan Ozdemir Date: Mon, 7 Sep 2026 15:59:08 +0300 Subject: [PATCH 33/34] refactor(agents): remove references to ADR 0001 in comments and documentation --- .../integration/external-integrations.md | 60 ++----------------- docs/CURSOR_INTEGRATION.md | 5 +- src/agents/plugins/cursor/cursor.bubbles.ts | 4 +- src/agents/plugins/cursor/cursor.paths.ts | 3 +- src/agents/plugins/cursor/cursor.session.ts | 10 ++-- src/agents/plugins/cursor/cursor.sqlite.ts | 2 +- src/agents/plugins/cursor/cursor.state-db.ts | 4 +- .../plugins/cursor/cursor.usage-fetch.ts | 2 +- .../__tests__/native-loader-cursor.test.ts | 6 +- .../commands/analytics/cost/cost-enricher.ts | 2 +- 10 files changed, 22 insertions(+), 76 deletions(-) diff --git a/.ai-run/guides/integration/external-integrations.md b/.ai-run/guides/integration/external-integrations.md index f732ee5ee..2924f8da6 100644 --- a/.ai-run/guides/integration/external-integrations.md +++ b/.ai-run/guides/integration/external-integrations.md @@ -327,61 +327,9 @@ tool-call counts. When tokens *are* recovered under an unpriceable model (`defau 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`. Rationale for reading an -undocumented store: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`. - -### Cursor Enterprise Team Analytics API (not integrated) - -Cursor publishes an official Team Analytics API -(). CodeMie integrates it as a strictly -**CodeMie does not integrate it.** A complete, reviewed implementation exists on the -`feature/cursor-team-analytics-untested` branch and was deliberately kept off the shipping branch: -no one on the team has an enterprise-admin account, so the success path was never exercised -against the live API (every probe returned `401 Invalid Team API Key`). Shipping untestable code -that makes network calls is the risk being avoided — not a judgement that the code is wrong. - -Two facts make this an easy trade. The API **cannot** supply tokens or cost at any tier, so it -never answered the question people actually have about Cursor; and its key is not obtainable by an -ordinary team member. The path that does work, for everyone, is the dashboard usage export via -`--cursor-usage-csv`. - -If it is ever revived, the constraints below still hold, and the branch already implements them. - -What the API is: - -- **Enterprise-team-only** and gated on an **admin-scoped API key**. An individual user on a - personal plan cannot use it at all. -- Documented endpoints: `agent-edits`, `tabs`, `dau`, `models`, `commands`, - `conversation-insights`, `leaderboard`, `bugbot`. -- **None of these endpoints returns token or cost fields at any tier.** The API cannot fill - CodeMie's biggest Cursor gap. Re-verified against the live docs on 2026-09-05: responses carry - `total_suggested_diffs`, `total_accepted_diffs`, `total_rejected_diffs`, - `total_green_lines_accepted`, `total_red_lines_accepted`, `total_suggestions`, `total_accepts`, - `total_rejects`, `messages`, `command_name`, `skill_name`, `model` — and nothing token-shaped. - -How the shipped integration honours the constraints below: it queries only `by-user` endpoints -(`agent-edits`, `tabs`, `models`, `commands`) with `users=`, never a -`team/*` endpoint and never the leaderboard; it renders into its own "Cursor Team API" report view -that is hidden unless a pull happened; it synthesizes no token or cost field; and every failure -mode — missing key, HTTP error, DNS failure, schema drift — degrades to an omitted or partial -section rather than breaking the local report. - -Agreed constraints for any future integration: - -- **Trigger model.** A configured token alone must never enable network calls. Both the token - *and* an explicit opt-in flag at invocation are required, mirroring how `--include-external` - gates external sessions. Reading local files is a promise CodeMie already makes; calling a - remote service is not, and must stay an explicit act. -- **Data scope.** User-wide only: the `by-user` endpoints filtered to the requesting user's own - email. Not team-wide data, not the leaderboard. CodeMie analytics reports the operator's own - usage, and pulling colleagues' activity into it is out of scope. -- **Unsolved reconciliation problem.** The API returns per-user/per-date aggregates with **no - join key to a local `composerId`-keyed session**. There is therefore no way to enrich - `ReportSessionRecord` rows with it. Any integration would have to render a **separate summary - section**, clearly labelled as team-API data, rather than merging into the session table — - attempting the merge would silently double-count or mis-attribute. - -Full context: ADR 0001, [`docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`](../../../docs/adr/0001-cursor-session-discovery-from-state-vscdb.md). +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 @@ -418,7 +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`, ADR: `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`) +- 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` diff --git a/docs/CURSOR_INTEGRATION.md b/docs/CURSOR_INTEGRATION.md index b79bf79a3..2667152b8 100644 --- a/docs/CURSOR_INTEGRATION.md +++ b/docs/CURSOR_INTEGRATION.md @@ -52,8 +52,8 @@ transcript ids, so a conversation with a header but no transcript (the common ca transcript with no header (rare — schema drift, a pruned header row) both produce a session row. Headers marked `isDraft: true` are conversations that were never started and are excluded. -Full rationale for reading an undocumented store, and the constraints that come with it, is in -[ADR 0001](adr/0001-cursor-session-discovery-from-state-vscdb.md). +`state.vscdb` is undocumented and can change in any Cursor release; reads are read-only and +fail-soft so a missing, locked, or drifted store never fails analytics for other agents. ### What Cursor sessions can and cannot report @@ -293,6 +293,5 @@ degradation test proving analytics still works when that source is gone. ## See also -- [ADR 0001 — Cursor session discovery from `state.vscdb`](adr/0001-cursor-session-discovery-from-state-vscdb.md) - [Analytics Report](ANALYTICS-REPORT.md) — provenance, `--include-external`, the report views - [`.ai-run/guides/integration/external-integrations.md`](../.ai-run/guides/integration/external-integrations.md) — including the deferred Cursor Enterprise Team Analytics API diff --git a/src/agents/plugins/cursor/cursor.bubbles.ts b/src/agents/plugins/cursor/cursor.bubbles.ts index d6d5d7973..6341d9aa7 100644 --- a/src/agents/plugins/cursor/cursor.bubbles.ts +++ b/src/agents/plugins/cursor/cursor.bubbles.ts @@ -2,8 +2,8 @@ * Per-turn enrichment from Cursor's internal `state.vscdb` — the `cursorDiskKV` table. * * `cursorDiskKV` is VS Code/Cursor's own undocumented internal key/value store, not a stable - * public API (see `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). It holds one - * row per bubble (turn/message) keyed `bubbleId::`, interleaved with + * public API. It holds one row per bubble (turn/message) keyed `bubbleId::`, + * interleaved with * unrelated `composerData:*` keys and, in aggregate, up to ~1.4GB of unrelated VS Code state — * so every read here filters by `composerId` in SQL rather than scanning the whole table. * diff --git a/src/agents/plugins/cursor/cursor.paths.ts b/src/agents/plugins/cursor/cursor.paths.ts index de1b60605..1e877075a 100644 --- a/src/agents/plugins/cursor/cursor.paths.ts +++ b/src/agents/plugins/cursor/cursor.paths.ts @@ -7,8 +7,7 @@ * * `state.vscdb` is a second, unrelated Cursor data location: it is the VS Code/Cursor * *application* state store, not `~/.cursor` (which holds Cursor's own project/tracking - * data), so it lives under the OS's per-app-data directory (see ADR - * `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). `CURSOR_HOME` still doubles + * data), so it lives under the OS's per-app-data directory. `CURSOR_HOME` still doubles * as the test-fixture override for it — same rationale as above — under a `User/globalStorage` * layout that mirrors where Cursor actually keeps it relative to its app-data root. */ diff --git a/src/agents/plugins/cursor/cursor.session.ts b/src/agents/plugins/cursor/cursor.session.ts index 6be2d0ba9..50c23cfbe 100644 --- a/src/agents/plugins/cursor/cursor.session.ts +++ b/src/agents/plugins/cursor/cursor.session.ts @@ -2,8 +2,8 @@ * Cursor session adapter — analytics-only. * * Discovery is keyed on `composerId`, the identifier Cursor uses for one agent conversation - * across every local store it writes: `state.vscdb`'s `composerHeaders` table (primary — see - * `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`), the + * across every local store it writes: `state.vscdb`'s `composerHeaders` table (primary; + * undocumented VS Code/Cursor state, fail-soft), the * `~/.cursor/projects//agent-transcripts//.jsonl` * transcript (secondary, joined by the shared id), and `ai_code_hashes.conversationId` in the * AI-tracking database (enrichment, same join). A session can have a header with no transcript @@ -93,7 +93,7 @@ const TRANSCRIPTS_DIR = 'agent-transcripts'; /** * Why a Cursor session has no priced usage — used only when `cursorDiskKV` carried no token * signal for it at all (see {@link resolveUsageMeta}; most sessions, since the per-turn - * `tokenCount` field is present on roughly 1% of bubbles per ADR 0001). Reporting zero cost + * `tokenCount` field is present on roughly 1% of bubbles). Reporting zero cost * would read as "this session was free"; the reason string makes the report say "unmeasurable" * instead. */ @@ -432,7 +432,7 @@ function aggregateLinesFileOp( /** * Usage provenance for a session, from its `cursorDiskKV` bubbles. * - * Cursor's per-turn token counts are sparse (~1% of bubbles, per ADR 0001) and have no + * Cursor's per-turn token counts are sparse (~1% of bubbles) and have no * alignment to transcript messages, so there is nothing for a per-message reader to walk — * unlike a fabricated confident zero, `usagePartial: true` tells the report this total * understates the session's real usage. A session with no token signal anywhere keeps the @@ -679,7 +679,7 @@ export class CursorSessionAdapter implements SessionAdapter { * `composerHeaders` table has a (non-draft) row for, and every composerId with a real * transcript under `~/.cursor/projects`. Most real sessions today have a header and no * transcript; a small, shrinking set has a transcript with no header (schema drift, a pruned - * row) and falls all the way back to the pre-ADR-0001 slug walk. Neither set alone is + * row) and falls all the way back to the slug-walk project-path guess. Neither set alone is * discovery — see the module doc comment. * * Discovery deliberately does not open transcripts: a transcript file's own stat, or the diff --git a/src/agents/plugins/cursor/cursor.sqlite.ts b/src/agents/plugins/cursor/cursor.sqlite.ts index 728487f78..5cfcbbf62 100644 --- a/src/agents/plugins/cursor/cursor.sqlite.ts +++ b/src/agents/plugins/cursor/cursor.sqlite.ts @@ -1,7 +1,7 @@ /** * Shared read-only helpers for the Cursor plugin's SQLite readers. * - * Every reader here follows the same fail-soft contract (ADR 0001): an absent database, an old + * Every reader here follows the same fail-soft contract: an absent database, an old * Node without `node:sqlite`, a renamed table/column, or a corrupt/locked file degrades to * "no enrichment" rather than throwing. These helpers hold the parts that were otherwise * copy-pasted across `cursor.tracking-db.ts`, `cursor.state-db.ts`, `cursor.bubbles.ts`, and diff --git a/src/agents/plugins/cursor/cursor.state-db.ts b/src/agents/plugins/cursor/cursor.state-db.ts index 365388bd9..7ca62a309 100644 --- a/src/agents/plugins/cursor/cursor.state-db.ts +++ b/src/agents/plugins/cursor/cursor.state-db.ts @@ -2,8 +2,8 @@ * Session discovery from Cursor's internal `state.vscdb` — the `composerHeaders` table. * * `state.vscdb` is VS Code/Cursor's own undocumented internal state store, not a stable public - * API (see `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). `composerHeaders` - * holds one row per Cursor Agent conversation, keyed by `composerId` — the same identifier used + * API. `composerHeaders` holds one row per Cursor Agent conversation, keyed by `composerId` — the + * same identifier used * as the `agent-transcripts` directory name and `ai_code_hashes.conversationId` elsewhere in * this plugin. Its row shape is unconfirmed: it may be flat columns, or (as is common for * VS Code/Cursor internal tables) a `key TEXT, value TEXT` pair with `value` holding a JSON diff --git a/src/agents/plugins/cursor/cursor.usage-fetch.ts b/src/agents/plugins/cursor/cursor.usage-fetch.ts index 5361e4476..b9b5eb8b3 100644 --- a/src/agents/plugins/cursor/cursor.usage-fetch.ts +++ b/src/agents/plugins/cursor/cursor.usage-fetch.ts @@ -79,7 +79,7 @@ function hostOf(url: string): string { /** * Read the signed-in session cookie out of Cursor's own state database. * - * Read-only and fail-soft by mandate (ADR 0001): an absent file, an old Node, a renamed table, + * Read-only and fail-soft: an absent file, an old Node, a renamed table, * a corrupt or locked database, or simply not being signed in all return `undefined` rather * than throwing. Candidate rows are matched on {@link COOKIE_SHAPE}, so a storage-key rename * does not break this and no unrelated secret is mistaken for the cookie. diff --git a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts index cbdd3ee8d..426701c92 100644 --- a/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts +++ b/src/cli/commands/analytics/__tests__/native-loader-cursor.test.ts @@ -147,7 +147,7 @@ interface ComposerHeaderRow { /** * A fixture `state.vscdb` with Cursor's real `composerHeaders` key/value table shape — the - * primary session-discovery source (see `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`). + * primary session-discovery source. * `CURSOR_HOME` relocates it to `/User/globalStorage/state.vscdb`, mirroring * `getCursorStateDbPath()`. */ @@ -504,7 +504,7 @@ describe('loadNativeSessions — Cursor degrades to transcript-only rows', () => /** * `composerHeaders` in `state.vscdb` is the primary session-discovery source (see the module - * doc comment in `cursor.session.ts` and `docs/adr/0001-cursor-session-discovery-from-state-vscdb.md`); + * doc comment in `cursor.session.ts`); * a transcript is no longer required for a conversation to be discoverable, and when a header * exists it settles project path, branch and line counts outright instead of the transcript-only * fallbacks (slug walk, tracking-db files, prompt stamps) exercised elsewhere in this file. @@ -735,7 +735,7 @@ describe('loadNativeSessions — Cursor reports no usage or line counts without /** * `cursorDiskKV` bubble rows in the SAME `state.vscdb` file `composerHeaders` lives in (see - * `cursor.bubbles.ts` and `docs/adr/`) are the source for real per-tool success/failure counts + * `cursor.bubbles.ts`) are the source for real per-tool success/failure counts * and, on the sparse fraction of bubbles that carry a nonzero `tokenCount`, partial token * pricing. Bubbles are keyed by composerId directly, so enrichment applies identically whether * or not a transcript exists on disk for the conversation. diff --git a/src/cli/commands/analytics/cost/cost-enricher.ts b/src/cli/commands/analytics/cost/cost-enricher.ts index 5aaaa610e..7a437c2e5 100644 --- a/src/cli/commands/analytics/cost/cost-enricher.ts +++ b/src/cli/commands/analytics/cost/cost-enricher.ts @@ -130,7 +130,7 @@ function tokensByModelUsage(tokensByModel: Record Date: Mon, 7 Sep 2026 17:58:58 +0300 Subject: [PATCH 34/34] feat(analytics): add isCliInstalled function to check CLI availability in tests --- tests/helpers/agent-smoke.ts | 15 +++ tests/helpers/index.ts | 2 +- tests/helpers/sso-auth.ts | 19 ++- tests/integration/agent-codex.test.ts | 151 ++++++++++++----------- tests/integration/agent-gemini.test.ts | 72 ++++++----- tests/integration/agent-kimi.test.ts | 7 +- tests/integration/agent-opencode.test.ts | 9 +- tests/integration/agent-pi.test.ts | 7 +- 8 files changed, 164 insertions(+), 118 deletions(-) diff --git a/tests/helpers/agent-smoke.ts b/tests/helpers/agent-smoke.ts index 0dc31fbca..1e6fed1f9 100644 --- a/tests/helpers/agent-smoke.ts +++ b/tests/helpers/agent-smoke.ts @@ -16,12 +16,27 @@ import { spawnSync, execFileSync, type SpawnSyncReturns } from 'node:child_proce import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'; import { join, dirname, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; +import { platform } from 'node:os'; import { copySsoCredentials, ssoCleanEnv } from './sso-auth.js'; import { getTempDir } from './temp-workspace.js'; import { getCodemieTestUrl } from './test-env.js'; const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..'); +/** + * Synchronous "is this CLI on PATH" check for use in `describe.runIf(...)` at + * collection time (vitest evaluates that predicate before any beforeAll/async + * hook runs, so the async `commandExists()`/`plugin.isInstalled()` used at + * runtime can't gate suite collection). Mirrors the resolution used by + * `commandExists()` in src/utils/processes.ts. + */ +export function isCliInstalled(command: string): boolean { + const isWindows = platform() === 'win32'; + const whichCommand = isWindows ? 'C:\\Windows\\System32\\where.exe' : 'which'; + const result = spawnSync(whichCommand, [command], { stdio: 'ignore' }); + return result.status === 0; +} + export interface AgentSmokeOptions { /** bin file under bin/, e.g. 'codemie-opencode.js'. */ binName: string; diff --git a/tests/helpers/index.ts b/tests/helpers/index.ts index 98447ec6f..cd445dedf 100644 --- a/tests/helpers/index.ts +++ b/tests/helpers/index.ts @@ -11,4 +11,4 @@ export { spawnPty, type PtySession } from './pty-session.js'; export { getLatestMetricsRecord } from './metrics.js'; export { getTestEnvFlag, getTestEnvFlagOrDefault, stripNodeModulesBin, getTestEnvValue, getCodemieTestUrl, getCodemieTestModel, DEFAULT_CODEMIE_TEST_URL, DEFAULT_CODEMIE_TEST_MODEL } from './test-env.js'; export { pollForSession, type SessionPollOptions, type SessionPollResult } from './session-poll.js'; -export { runAgentTaskSmoke, type AgentSmokeOptions, type AgentSmokeRun } from './agent-smoke.js'; +export { runAgentTaskSmoke, isCliInstalled, type AgentSmokeOptions, type AgentSmokeRun } from './agent-smoke.js'; diff --git a/tests/helpers/sso-auth.ts b/tests/helpers/sso-auth.ts index c734fe9c7..93ed7c126 100644 --- a/tests/helpers/sso-auth.ts +++ b/tests/helpers/sso-auth.ts @@ -40,9 +40,18 @@ export function writeSsoProfile(codemieHome: string): void { } /** - * Strip CODEMIE_* vars from the process environment for SSO subprocess spawns. - * Uses a denylist (vs jwtCleanEnv's allowlist) to preserve HOME, proxy settings, - * and other vars that the OS keychain and network calls depend on. + * Strip CODEMIE_* and CLAUDE_CODE_* vars from the process environment for SSO + * subprocess spawns. Uses a denylist (vs jwtCleanEnv's allowlist) to preserve + * HOME, proxy settings, and other vars that the OS keychain and network calls + * depend on. + * + * CLAUDE_CODE_* is stripped because when the test suite itself runs inside a + * Claude Code session (e.g. a developer or CI agent driving `npm test` via + * Claude Code's own Bash tool), the outer session's CLAUDE_CODE_CHILD_SESSION + * marker leaks into the spawned test's env. The nested `claude` process under + * test then sees itself as a child session and disables transcript + * persistence, so no metrics are recorded — a false failure in tests like + * TC-024 that assert on session metrics, unrelated to the code under test. * * Also strips node_modules/.bin entries from PATH so locally-installed package * shims (e.g. @codemieai/codemie-opencode's `codemie` bin) don't shadow the @@ -50,7 +59,9 @@ export function writeSsoProfile(codemieHome: string): void { */ export function ssoCleanEnv(): NodeJS.ProcessEnv { const env = Object.fromEntries( - Object.entries(process.env).filter(([key]) => !key.startsWith('CODEMIE_') && !key.startsWith('CI_CODEMIE_')), + Object.entries(process.env).filter( + ([key]) => !key.startsWith('CODEMIE_') && !key.startsWith('CI_CODEMIE_') && !key.startsWith('CLAUDE_CODE_'), + ), ) as NodeJS.ProcessEnv; if (env.PATH) env.PATH = stripNodeModulesBin(env.PATH); return env; diff --git a/tests/integration/agent-codex.test.ts b/tests/integration/agent-codex.test.ts index 23ce3c1ac..b39b78c56 100644 --- a/tests/integration/agent-codex.test.ts +++ b/tests/integration/agent-codex.test.ts @@ -36,93 +36,100 @@ * Run: npx vitest run --project agent -- agent-codex */ -import '../setup/load-test-env.js'; -import { describe, it, expect, beforeAll, afterAll } from 'vitest'; -import { spawnSync, execFileSync } from 'node:child_process'; -import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'; -import { join, dirname, resolve } from 'node:path'; -import { fileURLToPath } from 'node:url'; +import "../setup/load-test-env.js"; +import { execFileSync, spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { dirname, join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; import { - copySsoCredentials, - ssoCleanEnv, - setupSsoAutotestProfile, - teardownSsoAutotestProfile, - getTempDir, - getCodemieTestUrl, -} from '../helpers/index.js'; + copySsoCredentials, + getCodemieTestUrl, + getTempDir, + isCliInstalled, + setupSsoAutotestProfile, + ssoCleanEnv, + teardownSsoAutotestProfile, +} from "../helpers/index.js"; -const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); -const CODEX_BIN = join(REPO_ROOT, 'bin', 'codemie-codex.js'); +const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../.."); +const CODEX_BIN = join(REPO_ROOT, "bin", "codemie-codex.js"); // A GPT/Codex model; the resolver fuzzy-matches to the newest available // deployment, so an exact catalog entry is not required. Overridable in case the // catalog naming shifts. -const CODEX_MODEL = process.env.CODEMIE_CODEX_MODEL ?? 'gpt-5.4'; +const CODEX_MODEL = process.env.CODEMIE_CODEX_MODEL ?? "gpt-5.4"; /** Write an sso-autotest profile carrying a Codex-appropriate model. */ function writeCodexProfile(home: string): void { - const url = getCodemieTestUrl(); - const config = { - version: 2, - activeProfile: 'sso-autotest', - profiles: { - 'sso-autotest': { - name: 'sso-autotest', - provider: 'ai-run-sso', - authMethod: 'sso', - codeMieUrl: url, - baseUrl: `${url}/code-assistant-api`, - apiKey: 'sso-authenticated', - model: CODEX_MODEL, - timeout: 300, - debug: false, - }, - }, - workspace: { codeMieUrl: url }, - }; - mkdirSync(home, { recursive: true }); - writeFileSync(join(home, 'codemie-cli.config.json'), JSON.stringify(config, null, 2), 'utf-8'); + const url = getCodemieTestUrl(); + const config = { + version: 2, + activeProfile: "sso-autotest", + profiles: { + "sso-autotest": { + name: "sso-autotest", + provider: "ai-run-sso", + authMethod: "sso", + codeMieUrl: url, + baseUrl: `${url}/code-assistant-api`, + apiKey: "sso-authenticated", + model: CODEX_MODEL, + timeout: 300, + debug: false, + }, + }, + workspace: { codeMieUrl: url }, + }; + mkdirSync(home, { recursive: true }); + writeFileSync( + join(home, "codemie-cli.config.json"), + JSON.stringify(config, null, 2), + "utf-8", + ); } -describe.runIf(process.env.SSO_AVAILABLE !== 'false')('Codex agent smoke (real)', () => { - let originalActiveProfile: string | undefined; - let testHome: string; - let result: ReturnType; +describe.runIf( + process.env.SSO_AVAILABLE !== "false" && isCliInstalled("codex"), +)("Codex agent smoke (real)", () => { + let originalActiveProfile: string | undefined; + let testHome: string; + let result: ReturnType; - beforeAll(() => { - originalActiveProfile = setupSsoAutotestProfile(); + beforeAll(() => { + originalActiveProfile = setupSsoAutotestProfile(); - testHome = mkdtempSync(join(getTempDir(), 'codemie-codex-')); - writeCodexProfile(testHome); - copySsoCredentials(testHome); - // Codex refuses to run outside a trusted (git) directory. - execFileSync('git', ['init', '-q', testHome], { stdio: 'ignore' }); + testHome = mkdtempSync(join(getTempDir(), "codemie-codex-")); + writeCodexProfile(testHome); + copySsoCredentials(testHome); + // Codex refuses to run outside a trusted (git) directory. + execFileSync("git", ["init", "-q", testHome], { stdio: "ignore" }); - result = spawnSync( - process.execPath, - [CODEX_BIN, '--task', 'Reply with only the single word READY'], - { - cwd: testHome, - env: { ...ssoCleanEnv(), CODEMIE_HOME: testHome }, - encoding: 'utf-8', - timeout: 150_000, - }, - ); - }, 180_000); + result = spawnSync( + process.execPath, + [CODEX_BIN, "--task", "Reply with only the single word READY"], + { + cwd: testHome, + env: { ...ssoCleanEnv(), CODEMIE_HOME: testHome }, + encoding: "utf-8", + timeout: 150_000, + }, + ); + }, 180_000); - afterAll(() => { - teardownSsoAutotestProfile(originalActiveProfile); - if (testHome) rmSync(testHome, { recursive: true, force: true }); - }); + afterAll(() => { + teardownSsoAutotestProfile(originalActiveProfile); + if (testHome) rmSync(testHome, { recursive: true, force: true }); + }); - it('exits 0', () => { - expect( - result.status, - `stdout:\n${result.stdout ?? ''}\nstderr:\n${result.stderr ?? ''}`, - ).toBe(0); - }); + it("exits 0", () => { + expect( + result.status, + `stdout:\n${result.stdout ?? ""}\nstderr:\n${result.stderr ?? ""}`, + ).toBe(0); + }); - it('resolves a live GPT/Codex model and routes the agent response to stdout', () => { - expect(result.stdout).toMatch(/READY/i); - }); + it("resolves a live GPT/Codex model and routes the agent response to stdout", () => { + expect(result.stdout).toMatch(/READY/i); + }); }); diff --git a/tests/integration/agent-gemini.test.ts b/tests/integration/agent-gemini.test.ts index f606bf3cf..833744b61 100644 --- a/tests/integration/agent-gemini.test.ts +++ b/tests/integration/agent-gemini.test.ts @@ -24,44 +24,48 @@ * Run: npx vitest run --project agent -- agent-gemini */ -import '../setup/load-test-env.js'; -import { describe, it, expect, beforeAll, afterAll } from 'vitest'; -import { rmSync } from 'node:fs'; +import "../setup/load-test-env.js"; +import { rmSync } from "node:fs"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; import { - runAgentTaskSmoke, - setupSsoAutotestProfile, - teardownSsoAutotestProfile, - type AgentSmokeRun, -} from '../helpers/index.js'; + type AgentSmokeRun, + isCliInstalled, + runAgentTaskSmoke, + setupSsoAutotestProfile, + teardownSsoAutotestProfile, +} from "../helpers/index.js"; -describe.runIf(process.env.SSO_AVAILABLE !== 'false')('Gemini agent smoke (real)', () => { - let originalActiveProfile: string | undefined; - let run: AgentSmokeRun; +describe.runIf( + process.env.SSO_AVAILABLE !== "false" && + isCliInstalled(process.env.CODEMIE_GEMINI_BIN || "gemini"), +)("Gemini agent smoke (real)", () => { + let originalActiveProfile: string | undefined; + let run: AgentSmokeRun; - beforeAll(() => { - originalActiveProfile = setupSsoAutotestProfile(); - run = runAgentTaskSmoke({ - binName: 'codemie-gemini.js', - // Must be a real gemini-* deployment from the catalog (see MODEL NOTE). - model: process.env.CODEMIE_GEMINI_MODEL ?? 'gemini-3.1-pro', - isolateHome: true, // keep Gemini's settings.json out of the real ~/.gemini - extraEnv: { GEMINI_CLI_TRUST_WORKSPACE: 'true' }, - }); - }, 180_000); + beforeAll(() => { + originalActiveProfile = setupSsoAutotestProfile(); + run = runAgentTaskSmoke({ + binName: "codemie-gemini.js", + // Must be a real gemini-* deployment from the catalog (see MODEL NOTE). + model: process.env.CODEMIE_GEMINI_MODEL ?? "gemini-3.1-pro", + isolateHome: true, // keep Gemini's settings.json out of the real ~/.gemini + extraEnv: { GEMINI_CLI_TRUST_WORKSPACE: "true" }, + }); + }, 180_000); - afterAll(() => { - teardownSsoAutotestProfile(originalActiveProfile); - if (run?.testHome) rmSync(run.testHome, { recursive: true, force: true }); - }); + afterAll(() => { + teardownSsoAutotestProfile(originalActiveProfile); + if (run?.testHome) rmSync(run.testHome, { recursive: true, force: true }); + }); - it('exits 0', () => { - expect( - run.result.status, - `stdout:\n${run.result.stdout ?? ''}\nstderr:\n${run.result.stderr ?? ''}`, - ).toBe(0); - }); + it("exits 0", () => { + expect( + run.result.status, + `stdout:\n${run.result.stdout ?? ""}\nstderr:\n${run.result.stderr ?? ""}`, + ).toBe(0); + }); - it('routes the agent response to stdout', () => { - expect(run.result.stdout).toMatch(/READY/i); - }); + it("routes the agent response to stdout", () => { + expect(run.result.stdout).toMatch(/READY/i); + }); }); diff --git a/tests/integration/agent-kimi.test.ts b/tests/integration/agent-kimi.test.ts index 8c5013203..94e9230c3 100644 --- a/tests/integration/agent-kimi.test.ts +++ b/tests/integration/agent-kimi.test.ts @@ -10,7 +10,9 @@ * ~/.kimi-code/bin, so redirecting HOME would hide it. The model must be a * kimi-* deployment (kimi-k2 is used; kimi accepts any locally, then resolves). * - * Gated on SSO_AVAILABLE. Cleanup: profile restored + temp home removed. + * Gated on SSO_AVAILABLE and the `kimi` CLI being on PATH (skips gracefully + * on machines that haven't run `codemie install kimi`). Cleanup: profile + * restored + temp home removed. * * Run: npx vitest run --project agent -- agent-kimi */ @@ -22,10 +24,11 @@ import { runAgentTaskSmoke, setupSsoAutotestProfile, teardownSsoAutotestProfile, + isCliInstalled, type AgentSmokeRun, } from '../helpers/index.js'; -describe.runIf(process.env.SSO_AVAILABLE !== 'false')('Kimi agent smoke (real)', () => { +describe.runIf(process.env.SSO_AVAILABLE !== 'false' && isCliInstalled('kimi'))('Kimi agent smoke (real)', () => { let originalActiveProfile: string | undefined; let run: AgentSmokeRun; diff --git a/tests/integration/agent-opencode.test.ts b/tests/integration/agent-opencode.test.ts index 44ec7d23b..81989f414 100644 --- a/tests/integration/agent-opencode.test.ts +++ b/tests/integration/agent-opencode.test.ts @@ -8,8 +8,10 @@ * was verified only by hand. Uses the shared agent-smoke harness; HOME is * isolated so opencode's own state dir stays out of the developer's real home. * - * Gated on SSO_AVAILABLE (tests/setup/agent-build-setup.ts). Cleanup: profile - * restored + temp home removed in afterAll. + * Gated on SSO_AVAILABLE (tests/setup/agent-build-setup.ts) and the `opencode` + * CLI being on PATH (skips gracefully on machines that haven't run + * `codemie install opencode`). Cleanup: profile restored + temp home removed + * in afterAll. * * Run: npx vitest run --project agent -- agent-opencode */ @@ -21,10 +23,11 @@ import { runAgentTaskSmoke, setupSsoAutotestProfile, teardownSsoAutotestProfile, + isCliInstalled, type AgentSmokeRun, } from '../helpers/index.js'; -describe.runIf(process.env.SSO_AVAILABLE !== 'false')('OpenCode agent smoke (real)', () => { +describe.runIf(process.env.SSO_AVAILABLE !== 'false' && isCliInstalled(process.env.CODEMIE_OPENCODE_BIN || 'opencode'))('OpenCode agent smoke (real)', () => { let originalActiveProfile: string | undefined; let run: AgentSmokeRun; diff --git a/tests/integration/agent-pi.test.ts b/tests/integration/agent-pi.test.ts index 20f33e4a8..1a4b7f05c 100644 --- a/tests/integration/agent-pi.test.ts +++ b/tests/integration/agent-pi.test.ts @@ -10,7 +10,9 @@ * HOME is isolated: Pi redirects its agent dir into /.pi/codemie, so a * temp HOME keeps the run self-contained. Pi accepts a claude model. * - * Gated on SSO_AVAILABLE. Cleanup: profile restored + temp home removed. + * Gated on SSO_AVAILABLE and the `pi` CLI being on PATH (skips gracefully on + * machines that haven't run `codemie install pi`). Cleanup: profile restored + * + temp home removed. * * Run: npx vitest run --project agent -- agent-pi */ @@ -22,10 +24,11 @@ import { runAgentTaskSmoke, setupSsoAutotestProfile, teardownSsoAutotestProfile, + isCliInstalled, type AgentSmokeRun, } from '../helpers/index.js'; -describe.runIf(process.env.SSO_AVAILABLE !== 'false')('Pi agent smoke (real)', () => { +describe.runIf(process.env.SSO_AVAILABLE !== 'false' && isCliInstalled(process.env.CODEMIE_PI_BIN || 'pi'))('Pi agent smoke (real)', () => { let originalActiveProfile: string | undefined; let run: AgentSmokeRun;