@tokentop/agent-cursor 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,92 @@
+# @tokentop/agent-cursor
+
+[![npm](https://img.shields.io/npm/v/@tokentop/agent-cursor?style=flat-square&color=CB3837&logo=npm)](https://www.npmjs.com/package/@tokentop/agent-cursor)
+[![CI](https://img.shields.io/github/actions/workflow/status/tokentopapp/agent-cursor/ci.yml?style=flat-square&label=CI)](https://github.com/tokentopapp/agent-cursor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+
+[tokentop](https://github.com/tokentopapp/tokentop) agent plugin for **Cursor**. Parses Cursor's local SQLite session data and enriches it with server-side token counts for accurate usage tracking.
+
+## Capabilities
+
+| Capability | Status |
+|-----------|--------|
+| Session parsing | Yes |
+| Real-time tracking | Yes |
+| Server enrichment | Yes |
+| Multi-provider | No |
+
+## How It Works
+
+Cursor stores session data as "composers" in a SQLite KV table (`state.vscdb`). Each conversation turn is a "bubble" with token counts, model info, and timestamps.
+
+**Hybrid token strategy:**
+
+1. **Immediate** — Sessions appear within seconds using local token estimates (`text.length / 4`)
+2. **Enriched** — Accurate token counts (including cache read/write breakdown) are backfilled from Cursor's CSV server export
+
+Enriched data persists across app restarts via plugin storage.
+
+**Real-time activity detection:**
+
+The activity watcher uses a rowid-based cursor on the SQLite DB with a read-write connection (to avoid WAL snapshot isolation). New bubbles are detected via 1s polling + `fs.watch`, with a 500ms fast-poll for pending bubbles during streaming.
+
+## Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Server enrichment | boolean | `true` | Fetch accurate token counts from Cursor's server |
+| Server refresh interval | number | `5` | How often to refresh server data (minutes, 1–60) |
+| Estimate tokens | boolean | `true` | Show estimated tokens while server data loads |
+
+## Permissions
+
+| Type | Access | Details |
+|------|--------|---------|
+| Filesystem | Read | `~/.cursor`, `~/Library/Application Support/Cursor`, `~/.config/Cursor` |
+| Network | HTTPS | `cursor.com` (CSV usage export) |
+
+## Install
+
+This plugin is **bundled with tokentop** — no separate install needed. If you need it standalone:
+
+```bash
+bun add @tokentop/agent-cursor
+```
+
+## Requirements
+
+- [Cursor](https://cursor.com) installed
+- [Bun](https://bun.sh/) >= 1.0.0
+- `@tokentop/plugin-sdk` ^1.0.0 (peer dependency)
+
+## Development
+
+```bash
+bun install
+bun run build
+bun test
+bun run typecheck
+```
+
+## Project Structure
+
+| File | Responsibility |
+|------|----------------|
+| `src/index.ts` | Plugin entry — `createAgentPlugin()` wiring, config schema, exports |
+| `src/parser.ts` | Session parsing — SQLite reads, workspace mapping, token estimation |
+| `src/watcher.ts` | Activity detection — rowid cursor, WAL watching, pending bubbles |
+| `src/csv.ts` | Server enrichment — CSV fetch, parse, match, cache, persistent storage |
+| `src/auth.ts` | Auth — JWT decode, session cookie for CSV endpoint |
+| `src/storage.ts` | Persistence — PluginStorage bridge for enrichment cache |
+| `src/cache.ts` | Caching — TTL session cache, LRU aggregate cache, metadata index |
+| `src/paths.ts` | Paths — cross-platform Cursor config/data directories |
+| `src/types.ts` | Types — Cursor-specific interfaces |
+| `src/utils.ts` | SQLite helpers — DB open, KV reads, provider mapping |
+
+## Contributing
+
+See the [Contributing Guide](https://github.com/tokentopapp/.github/blob/main/CONTRIBUTING.md). Issues for this plugin should be [filed on the main tokentop repo](https://github.com/tokentopapp/tokentop/issues/new?template=bug_report.yml&labels=bug,agent-cursor).
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reads the Cursor access token from local SQLite and constructs the
+ * WorkosCursorSessionToken cookie needed for Cursor's dashboard API.
+ *
+ * Cookie format: `WorkosCursorSessionToken={userId}%3A%3A{accessToken}`
+ * where userId is the JWT `sub` claim (e.g. "google-oauth2|user_01K...").
+ *
+ * Returns null if credentials are unavailable or malformed.
+ */
+export declare function buildSessionCookie(): string | null;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAqCA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAgBlD"}

package/dist/cache.d.ts

@@ -0,0 +1,17 @@
+import type { SessionUsageData } from '@tokentop/plugin-sdk';
+import type { SessionAggregateCacheEntry } from './types.ts';
+export declare const sessionCache: {
+    lastCheck: number;
+    lastResult: SessionUsageData[];
+    lastLimit: number;
+    lastSince: number | undefined;
+};
+export declare const CACHE_TTL_MS = 2000;
+export declare const SESSION_AGGREGATE_CACHE_MAX = 10000;
+export declare const sessionAggregateCache: Map<string, SessionAggregateCacheEntry>;
+export declare function evictSessionAggregateCache(): void;
+export declare const composerMetadataIndex: Map<string, {
+    lastUpdatedAt: number;
+    composerId: string;
+}>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7D,eAAO,MAAM,YAAY,EAAE;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAM/B,CAAC;AAEF,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,eAAO,MAAM,qBAAqB,yCAAgD,CAAC;AAEnF,wBAAgB,0BAA0B,IAAI,IAAI,CAUjD;AAED,eAAO,MAAM,qBAAqB;mBACjB,MAAM;gBACT,MAAM;EAChB,CAAC"}

package/dist/csv.d.ts

@@ -0,0 +1,49 @@
+import type { AgentFetchContext, SessionUsageData } from '@tokentop/plugin-sdk';
+import type { CursorCsvUsageRow } from './types.ts';
+/** Default TTL for cached CSV data. Overridden by `csvRefreshMinutes` config. */
+export declare const CSV_CACHE_TTL_MS: number;
+/**
+ * Parse Cursor's CSV usage export into structured rows.
+ *
+ * CSV columns (in order):
+ *   Date, Kind, Model, Max Mode, Input (w/ Cache Write),
+ *   Input (w/o Cache Write), Cache Read, Output Tokens, Total Tokens, Cost
+ */
+export declare function parseUsageCsv(csvText: string): CursorCsvUsageRow[];
+/**
+ * Get cached CSV data, awaiting the fetch when the cache is stale or empty.
+ *
+ * Reads `csvEnrichment` and `csvRefreshMinutes` from `ctx.config`.
+ * When the cache is missing or expired, awaits the server fetch (~1-3s)
+ * so enriched data lands on the same parseSessions cycle. Fresh cache
+ * returns immediately with no network call.
+ */
+export declare function getCsvRows(ctx: AgentFetchContext): Promise<CursorCsvUsageRow[]>;
+/**
+ * Invalidate the CSV cache so the next `getCsvRows` call triggers a
+ * fresh background fetch. Does NOT clear the per-session enrichment
+ * cache — previously-enriched sessions keep their accurate data.
+ */
+export declare function invalidateCsvCache(): void;
+/**
+ * Enrich locally-parsed session rows with actual token data from the CSV export.
+ *
+ * The CSV contains per-session aggregates, not per-bubble data. This function:
+ * 1. Groups local rows by sessionId
+ * 2. Matches each session to a CSV row by timestamp proximity (±60s)
+ *    using sessionUpdatedAt — model matching is skipped because Cursor
+ *    reports "auto" in the CSV rather than the resolved model name
+ * 3. Distributes the CSV totals across the session's bubbles
+ *    proportionally based on each bubble's estimated output tokens
+ * 4. Caches enriched results per-session so they survive CSV cache
+ *    expiry and DB activity without regressing to estimates
+ * 5. Persists the enrichment cache to PluginStorage so data survives restarts
+ *
+ * When called with no CSV rows (cache miss / TTL expired / first call),
+ * returns previously-enriched data from the per-session cache for known
+ * sessions. New/unenriched sessions keep their local estimates.
+ */
+export declare function enrichWithCsvData(localRows: SessionUsageData[], csvRows: CursorCsvUsageRow[]): Promise<SessionUsageData[]>;
+/** Reset CSV cache and enrichment cache — for testing. */
+export declare function resetCsvCache(): void;
+//# sourceMappingURL=csv.d.ts.map

package/dist/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../src/csv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGhF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,QAAgB,CAAC;AAwB9C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAmClE;AA6BD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAoCrF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAqBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,iBAAiB,EAAE,GAC3B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqG7B;AA+BD,0DAA0D;AAC1D,wBAAgB,aAAa,IAAI,IAAI,CAIpC"}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+import { CACHE_TTL_MS, SESSION_AGGREGATE_CACHE_MAX, composerMetadataIndex, sessionAggregateCache, sessionCache } from './cache.ts';
+import { CURSOR_GLOBAL_STORAGE_PATH, CURSOR_HOME, CURSOR_STATE_DB_PATH, CURSOR_WORKSPACE_STORAGE_PATH } from './paths.ts';
+import { RECONCILIATION_INTERVAL_MS } from './watcher.ts';
+import { CSV_CACHE_TTL_MS, resetCsvCache } from './csv.ts';
 declare const cursorAgentPlugin: import("@tokentop/plugin-sdk").AgentPlugin;
+export { CACHE_TTL_MS, CSV_CACHE_TTL_MS, CURSOR_GLOBAL_STORAGE_PATH, CURSOR_HOME, CURSOR_STATE_DB_PATH, CURSOR_WORKSPACE_STORAGE_PATH, RECONCILIATION_INTERVAL_MS, SESSION_AGGREGATE_CACHE_MAX, composerMetadataIndex, resetCsvCache, sessionAggregateCache, sessionCache, };
 export default cursorAgentPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,QAAA,MAAM,iBAAiB,4CAuCrB,CAAC;AAEH,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEnI,OAAO,EAAE,0BAA0B,EAAE,WAAW,EAAE,oBAAoB,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAC1H,OAAO,EAAE,0BAA0B,EAAyC,MAAM,cAAc,CAAC;AACjG,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG3D,QAAA,MAAM,iBAAiB,4CAkFrB,CAAC;AAEH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,0BAA0B,EAC1B,WAAW,EACX,oBAAoB,EACpB,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,qBAAqB,EACrB,aAAa,EACb,qBAAqB,EACrB,YAAY,GACb,CAAC;AAEF,eAAe,iBAAiB,CAAC"}