@rigour-labs/core 5.3.3 → 5.5.0

package/dist/context/cache-engine.d.ts

@@ -68,6 +68,31 @@ export declare function setComponentCache(componentName: string, commitSha: stri
 export declare function normalizeQuery(query: string): string;
 export declare function getSemanticQueryCache(query: string, commitSha: string, cwd?: string): Promise<SemanticQueryEntry | null>;
 export declare function setSemanticQueryCache(query: string, commitSha: string, entry: SemanticQueryEntry, cwd?: string): Promise<void>;
+/** Jaccard similarity of normalized query tokens — used for quality-safe partial reuse. */
+export declare function queryTokenOverlap(a: string, b: string): number;
+/**
+ * Distinctive tokens (len >= 5) must mostly agree — blocks "task service" ≈ "payment service".
+ */
+export declare function distinctiveTokenAgreement(a: string, b: string): number;
+export interface RelatedSemanticHit {
+    entry: SemanticQueryEntry;
+    overlap: number;
+    sourceQuery: string;
+}
+/**
+ * Quality-safe partial semantic reuse: same commit only.
+ * Requires high Jaccard (>= 0.75) AND distinctive-token agreement (>= 0.67).
+ * Never crosses commits — avoids stale scopes after code moves.
+ * File existence is re-validated by the caller before serving.
+ */
+export declare function findRelatedSemanticQueryCache(query: string, commitSha: string, cwd?: string, minOverlap?: number, minDistinctive?: number): Promise<RelatedSemanticHit | null>;
+/**
+ * Drop cached scopes that point at files no longer on disk (quality guard).
+ */
+export declare function filterExistingEditScope(editScope: string[], cwd: string): Promise<{
+    valid: string[];
+    missing: string[];
+}>;
 /**
  * Layer 4: Task Checkpoint Cache
  */

package/dist/context/cache-engine.js

@@ -8,7 +8,9 @@
  * 4. Task checkpoint cache (Subagent handoff packets)
  */
 import { createHash } from 'crypto';
-import { setContextCacheRecord, getContextCacheRecord, recordCheckpointMetric } from '../storage/index.js';
+import fs from 'fs-extra';
+import path from 'path';
+import { setContextCacheRecord, getContextCacheRecord, listContextCacheRecords, recordCheckpointMetric } from '../storage/index.js';
 /**
  * Generate SHA-256 content hash.
  */
@@ -114,6 +116,82 @@ export async function setSemanticQueryCache(query, commitSha, entry, cwd) {
         payloadTokens,
     }, cwd);
 }
+function queryTokenSet(query) {
+    return new Set(normalizeQuery(query).split(' ').filter((t) => t.length > 1));
+}
+/** Jaccard similarity of normalized query tokens — used for quality-safe partial reuse. */
+export function queryTokenOverlap(a, b) {
+    const left = queryTokenSet(a);
+    const right = queryTokenSet(b);
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of left) {
+        if (right.has(t))
+            inter++;
+    }
+    const union = left.size + right.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Distinctive tokens (len >= 5) must mostly agree — blocks "task service" ≈ "payment service".
+ */
+export function distinctiveTokenAgreement(a, b) {
+    const left = [...queryTokenSet(a)].filter((t) => t.length >= 5);
+    const right = new Set([...queryTokenSet(b)].filter((t) => t.length >= 5));
+    if (left.length === 0 || right.size === 0)
+        return 0;
+    const hits = left.filter((t) => right.has(t)).length;
+    return hits / Math.max(left.length, right.size);
+}
+/**
+ * Quality-safe partial semantic reuse: same commit only.
+ * Requires high Jaccard (>= 0.75) AND distinctive-token agreement (>= 0.67).
+ * Never crosses commits — avoids stale scopes after code moves.
+ * File existence is re-validated by the caller before serving.
+ */
+export async function findRelatedSemanticQueryCache(query, commitSha, cwd, minOverlap = 0.75, minDistinctive = 0.67) {
+    const records = await listContextCacheRecords({ cacheType: 'semantic', commitSha, limit: 80 }, cwd);
+    let best = null;
+    for (const record of records) {
+        try {
+            const entry = JSON.parse(record.payloadJson);
+            const sourceQuery = entry.query || '';
+            const overlap = queryTokenOverlap(query, sourceQuery);
+            const distinctive = distinctiveTokenAgreement(query, sourceQuery);
+            if (overlap < minOverlap || distinctive < minDistinctive)
+                continue;
+            if (normalizeQuery(query) === normalizeQuery(sourceQuery))
+                continue; // exact path uses getSemanticQueryCache
+            if (!best || overlap > best.overlap) {
+                best = { entry, overlap, sourceQuery };
+            }
+        }
+        catch {
+            // skip bad payloads
+        }
+    }
+    return best;
+}
+/**
+ * Drop cached scopes that point at files no longer on disk (quality guard).
+ */
+export async function filterExistingEditScope(editScope, cwd) {
+    const valid = [];
+    const missing = [];
+    for (const file of editScope) {
+        try {
+            if (await fs.pathExists(path.join(cwd, file)))
+                valid.push(file);
+            else
+                missing.push(file);
+        }
+        catch {
+            missing.push(file);
+        }
+    }
+    return { valid, missing };
+}
 /**
  * Layer 4: Task Checkpoint Cache
  */

package/dist/context/cache-engine.test.js

@@ -8,7 +8,7 @@ vi.mock('./db.js', () => ({
     DB_PATH: '/tmp/rigour-test.db',
     RIGOUR_DIR: '/tmp/.rigour',
 }));
-import { getStaticCache, setStaticCache, getComponentCache, setComponentCache, getSemanticQueryCache, setSemanticQueryCache, getTaskCheckpointCache, setTaskCheckpointCache, hashContent, normalizeQuery } from './cache-engine.js';
+import { getStaticCache, setStaticCache, getComponentCache, setComponentCache, getSemanticQueryCache, setSemanticQueryCache, findRelatedSemanticQueryCache, queryTokenOverlap, distinctiveTokenAgreement, filterExistingEditScope, getTaskCheckpointCache, setTaskCheckpointCache, hashContent, normalizeQuery } from './cache-engine.js';
 describe('4-Layer Context Cache Engine', () => {
     const testCwd = path.join(os.tmpdir(), `rigour-cache-test-${Date.now()}`);
     beforeEach(async () => {
@@ -89,6 +89,42 @@ describe('4-Layer Context Cache Engine', () => {
         expect(retrieved?.taskId).toBe('CTP-142');
         expect(retrieved?.decisions).toContain('Added priority field');
     });
+    it('Layer 3: finds related semantic queries at same commit for partial reuse', async () => {
+        expect(queryTokenOverlap('task priority persistence service', 'task priority persistence service layer')).toBeGreaterThan(0.7);
+        expect(distinctiveTokenAgreement('task service', 'payment service')).toBeLessThan(0.67);
+        await setSemanticQueryCache('task priority persistence service', 'commit-rel', {
+            query: 'task priority persistence service',
+            resolvedOwner: 'task-team',
+            editScope: ['services/task.ts'],
+            validationScope: ['npm test'],
+            evidence: ['related'],
+            commitSha: 'commit-rel',
+            confidence: 0.9,
+        }, testCwd);
+        const related = await findRelatedSemanticQueryCache('task priority persistence service layer', 'commit-rel', testCwd);
+        expect(related).not.toBeNull();
+        expect(related?.entry.editScope).toContain('services/task.ts');
+        // Same generic stem, different distinctive noun → reject
+        await setSemanticQueryCache('payment service billing', 'commit-rel', {
+            query: 'payment service billing',
+            resolvedOwner: 'pay',
+            editScope: ['services/pay.ts'],
+            validationScope: [],
+            evidence: [],
+            commitSha: 'commit-rel',
+            confidence: 0.9,
+        }, testCwd);
+        const crossDomain = await findRelatedSemanticQueryCache('task service billing', 'commit-rel', testCwd);
+        expect(crossDomain).toBeNull();
+        const otherCommit = await findRelatedSemanticQueryCache('task priority persistence service layer', 'commit-other', testCwd);
+        expect(otherCommit).toBeNull();
+    });
+    it('filters missing edit-scope files for quality', async () => {
+        await fs.writeFile(path.join(testCwd, 'alive.ts'), 'export const ok = 1;\n');
+        const result = await filterExistingEditScope(['alive.ts', 'gone.ts'], testCwd);
+        expect(result.valid).toEqual(['alive.ts']);
+        expect(result.missing).toEqual(['gone.ts']);
+    });
     it('Layer 1: invalidates static cache when file content changes', async () => {
         const originalContent = 'export function processTask() { return true; }';
         const entry = {

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export * from './utils/logger.js';
 export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
-export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, updateCursorApiKey } from './settings.js';
+export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, isCursorApiKeyConfigured, getCursorApiKeyHint, updateCursorApiKey, removeCursorApiKey, } from './settings.js';
 export type { RigourSettings, ResolvedDeepOptions, CLIDeepOptions } from './settings.js';
 export { DeepAnalysisGate } from './gates/deep-analysis.js';
 export { createProvider } from './inference/index.js';

package/dist/index.js

@@ -13,7 +13,7 @@ export { FileScanner } from './utils/scanner.js';
 export * from './services/score-history.js';
 export * from './hooks/index.js';
 // Settings Module (Global user config at ~/.rigour/settings.json)
-export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, updateCursorApiKey } from './settings.js';
+export { loadSettings, saveSettings, getSettingsPath, resolveDeepOptions, getProviderKey, getAgentConfig, getCliPreferences, updateProviderKey, removeProviderKey, getCursorApiKey, isCursorApiKeyConfigured, getCursorApiKeyHint, updateCursorApiKey, removeCursorApiKey, } from './settings.js';
 // Deep Analysis Pipeline (v4.0+)
 export { DeepAnalysisGate } from './gates/deep-analysis.js';
 export { createProvider } from './inference/index.js';

package/dist/services/context-telemetry-service.d.ts

@@ -3,6 +3,7 @@
  * Calculates exact observed usage, avoided tokens, cache performance, and cost breakdowns.
  * Supports CSV/JSON Cursor usage imports.
  */
+import { type CursorUsageSyncOptions } from './cursor-usage-client.js';
 /** Heuristic token counter (~4 chars per token for code/text) */
 export declare function estimateTokenCount(text: string): number;
 /** Default session token budgets */
@@ -26,11 +27,14 @@ export interface TaskCostStats {
         costUsd: number;
         source: string;
         isEstimated: boolean;
+        pricingBasis?: string;
     };
     estimated: {
         potentialContextAvoided: number;
         estimatedCostAvoidedUsd: number;
         isEstimated: boolean;
+        inputPricePerMillionUsd?: number;
+        pricingBasis?: string;
     };
 }
 export interface CachePerformanceStats {
@@ -106,11 +110,17 @@ export declare function importCursorUsageCsv(csvContent: string, cwd?: string):
  * Import Cursor usage data from JSON format (e.g. from Cursor Admin API).
  */
 export declare function importCursorUsageJson(jsonData: unknown, cwd?: string): Promise<number>;
+export interface CursorAdminSyncResult {
+    importedCount: number;
+    totalEvents: number;
+}
 /**
- * Fetch Cursor usage from Admin API (stub — requires API key in settings).
- * Returns number of records imported, or 0 if unavailable.
+ * Fetch Cursor usage from Admin API and import token-based events.
+ * Costs are reported in cents by Cursor (`chargedCents`) and converted to USD.
  */
-export declare function fetchCursorUsageFromAdminApi(cwd?: string): Promise<number>;
+export declare function fetchCursorUsageFromAdminApi(cwdOrOptions?: string | CursorUsageSyncOptions): Promise<number>;
+export declare function syncCursorUsageFromAdminApi(cwdOrOptions?: string | CursorUsageSyncOptions): Promise<CursorAdminSyncResult>;
+export declare function countCursorAdminImportedEvents(cwd?: string): Promise<number>;
 /**
  * Summarize agent scope overlap and governance rule overhead for Studio.
  */

package/dist/services/context-telemetry-service.js

@@ -8,20 +8,15 @@ import fs from 'fs-extra';
 import path from 'path';
 import { getContextEvents, getModelUsages, getCheckpointMetrics, recordModelUsage, } from '../storage/index.js';
 import { getCursorApiKey } from '../settings.js';
+import { estimateAvoidedContextCostUsd, estimateTokenCostUsd, computeWeightedInputPricePerMillion, } from './model-pricing.js';
+import { fetchCursorUsagePages } from './cursor-usage-client.js';
+import { CURSOR_ADMIN_API_SOURCE, centsToUsd, isCursorAdminApiEvent, normalizeCursorUsageEvent } from './cursor-usage-normalizer.js';
 /** Heuristic token counter (~4 chars per token for code/text) */
 export function estimateTokenCount(text) {
     if (!text)
         return 0;
     return Math.ceil(text.length / 4);
 }
-/** Default Model Input Rates (per million tokens) */
-const DEFAULT_MODEL_PRICES = {
-    'claude-3-5-sonnet': 3.0,
-    'gpt-4o': 2.5,
-    'gpt-4o-mini': 0.15,
-    'o1-preview': 15.0,
-    'default': 3.0,
-};
 /** Default session token budgets */
 export const DEFAULT_SESSION_SOFT_LIMIT = 160_000;
 export const DEFAULT_SESSION_HARD_LIMIT = 200_000;
@@ -85,32 +80,46 @@ export async function getTaskCostStats(taskId, cwd) {
     const stats = await getTaskContextStats(taskId, cwd);
     let actualInputTokens = 0;
     let actualOutputTokens = 0;
-    let actualCostUsd = 0;
+    let observedCostUsd = 0;
     let primarySource = 'estimated';
     const hasObservedUsage = usages.length > 0;
     for (const u of usages) {
         actualInputTokens += u.inputTokens || 0;
         actualOutputTokens += u.outputTokens || 0;
-        actualCostUsd += u.observedCostUsd || 0;
+        observedCostUsd += u.observedCostUsd || 0;
         if (u.source && u.source !== 'estimated') {
             primarySource = u.source;
         }
     }
-    const pricePerM = DEFAULT_MODEL_PRICES['claude-3-5-sonnet'] || 3.0;
+    const hasObservedCost = observedCostUsd > 0;
+    let actualCostUsd = observedCostUsd;
+    let actualIsEstimated = !hasObservedUsage;
+    let actualPricingBasis;
+    if (!hasObservedCost && hasObservedUsage) {
+        actualCostUsd = usages.reduce((sum, usage) => sum + estimateTokenCostUsd(usage.inputTokens || 0, usage.outputTokens || 0, usage.model), 0);
+        actualIsEstimated = true;
+        actualPricingBasis = computeWeightedInputPricePerMillion(usages).pricingBasis;
+    }
+    else if (hasObservedCost) {
+        actualPricingBasis = 'observed-cursor-charged-cents';
+    }
     const totalPotentialAvoided = stats.potentialAvoidedTokens + stats.checkpointReplayAvoided;
-    const estimatedCostAvoidedUsd = parseFloat(((totalPotentialAvoided / 1_000_000) * pricePerM).toFixed(2));
+    const avoidedPricing = estimateAvoidedContextCostUsd(totalPotentialAvoided, usages);
     return {
         actual: {
             inputTokens: actualInputTokens,
             outputTokens: actualOutputTokens,
-            costUsd: parseFloat(actualCostUsd.toFixed(2)),
+            costUsd: parseFloat(actualCostUsd.toFixed(4)),
             source: primarySource,
-            isEstimated: !hasObservedUsage,
+            isEstimated: actualIsEstimated,
+            pricingBasis: actualPricingBasis,
         },
         estimated: {
             potentialContextAvoided: totalPotentialAvoided,
-            estimatedCostAvoidedUsd,
+            estimatedCostAvoidedUsd: avoidedPricing.costUsd,
             isEstimated: true,
+            inputPricePerMillionUsd: avoidedPricing.pricing.inputPricePerMillionUsd,
+            pricingBasis: avoidedPricing.pricing.pricingBasis,
         },
     };
 }
@@ -274,38 +283,95 @@ export async function importCursorUsageJson(jsonData, cwd) {
     const records = Array.isArray(jsonData)
         ? jsonData
         : (payload.records || payload.usage || [jsonData]);
+    const existingUsages = await getModelUsages(undefined, cwd);
+    const seenIds = new Set(existingUsages.map(u => u.id).filter(Boolean));
     let importedCount = 0;
     for (const r of records) {
+        const normalized = isCursorAdminApiEvent(r) ? normalizeCursorUsageEvent(r) : null;
+        if (normalized) {
+            if (seenIds.has(normalized.id))
+                continue;
+            seenIds.add(normalized.id);
+            await recordModelUsage(normalized.usage, cwd);
+            importedCount++;
+            continue;
+        }
+        const row = r;
+        const id = row.id
+            ?? `json-${hashCsvRow(JSON.stringify(row))}`;
+        if (seenIds.has(id))
+            continue;
+        seenIds.add(id);
+        const tokenUsage = row.tokenUsage;
+        const chargedCents = Number(row.chargedCents ?? tokenUsage?.totalCents ?? 0);
+        const observedFromRow = Number(row.observedCostUsd ?? row.cost_usd ?? row.cost ?? 0);
+        const observedCostUsd = observedFromRow > 0
+            ? observedFromRow
+            : chargedCents > 0
+                ? centsToUsd(chargedCents)
+                : 0;
         await recordModelUsage({
-            taskId: (r.taskId || r.task_id || 'cursor-imported'),
-            sessionId: (r.sessionId || r.session_id),
-            agentId: (r.agentId || r.agent_id),
-            provider: (r.provider || 'cursor'),
-            model: (r.model || 'claude-3-5-sonnet'),
-            inputTokens: (r.inputTokens || r.input_tokens || 0),
-            outputTokens: (r.outputTokens || r.output_tokens || 0),
-            cachedInputTokens: (r.cachedInputTokens || r.cached_input_tokens || 0),
-            observedCostUsd: (r.observedCostUsd || r.cost_usd || r.cost || 0),
-            source: 'cursor-admin-api',
+            id,
+            taskId: (row.taskId || row.task_id || 'cursor-imported'),
+            sessionId: (row.sessionId || row.session_id),
+            agentId: (row.agentId || row.agent_id),
+            provider: (row.provider || 'cursor'),
+            model: (row.model || 'claude-3-5-sonnet'),
+            inputTokens: (row.inputTokens || row.input_tokens || tokenUsage?.inputTokens || 0),
+            outputTokens: (row.outputTokens || row.output_tokens || tokenUsage?.outputTokens || 0),
+            cachedInputTokens: (row.cachedInputTokens || row.cached_input_tokens || row.cacheReadTokens || tokenUsage?.cacheReadTokens || 0),
+            cacheWriteTokens: (row.cacheWriteTokens || row.cache_write_tokens || tokenUsage?.cacheWriteTokens || 0),
+            observedCostUsd,
+            source: row.source || 'cursor-admin-api',
+            createdAt: row.createdAt ? Number(row.createdAt) : undefined,
         }, cwd);
         importedCount++;
     }
     return importedCount;
 }
+async function persistCursorUsageEvents(events, cwd) {
+    const existingUsages = await getModelUsages(undefined, cwd);
+    const seenIds = new Set(existingUsages.map(u => u.id).filter(Boolean));
+    let importedCount = 0;
+    for (const event of events) {
+        if (seenIds.has(event.id))
+            continue;
+        seenIds.add(event.id);
+        await recordModelUsage(event.usage, cwd);
+        importedCount++;
+    }
+    return importedCount;
+}
 /**
- * Fetch Cursor usage from Admin API (stub — requires API key in settings).
- * Returns number of records imported, or 0 if unavailable.
+ * Fetch Cursor usage from Admin API and import token-based events.
+ * Costs are reported in cents by Cursor (`chargedCents`) and converted to USD.
  */
-export async function fetchCursorUsageFromAdminApi(cwd) {
-    const apiKey = getCursorApiKey();
+export async function fetchCursorUsageFromAdminApi(cwdOrOptions) {
+    const options = typeof cwdOrOptions === 'string'
+        ? { cwd: cwdOrOptions }
+        : (cwdOrOptions ?? {});
+    const apiKey = options.apiKey ?? getCursorApiKey();
     if (!apiKey) {
         return 0;
     }
-    // Stub: Cursor Admin API integration pending official endpoint documentation.
-    // When available, fetch usage records and delegate to importCursorUsageJson.
-    void apiKey;
-    void cwd;
-    return 0;
+    const events = await fetchCursorUsagePages(options);
+    return persistCursorUsageEvents(events, options.cwd);
+}
+export async function syncCursorUsageFromAdminApi(cwdOrOptions) {
+    const options = typeof cwdOrOptions === 'string'
+        ? { cwd: cwdOrOptions }
+        : (cwdOrOptions ?? {});
+    const apiKey = options.apiKey ?? getCursorApiKey();
+    if (!apiKey) {
+        return { importedCount: 0, totalEvents: 0 };
+    }
+    const events = await fetchCursorUsagePages(options);
+    const importedCount = await persistCursorUsageEvents(events, options.cwd);
+    return { importedCount, totalEvents: events.length };
+}
+export async function countCursorAdminImportedEvents(cwd) {
+    const usages = await getModelUsages(undefined, cwd);
+    return usages.filter(u => u.source === CURSOR_ADMIN_API_SOURCE).length;
 }
 /**
  * Summarize agent scope overlap and governance rule overhead for Studio.

package/dist/services/context-telemetry-service.test.js

@@ -95,6 +95,20 @@ describe('context-telemetry-service', () => {
         const cost = await getTaskCostStats(jsonTaskId, testCwd);
         expect(cost.actual.inputTokens).toBe(2500);
     });
+    it('imports Admin API JSON events with chargedCents and dedupes against sync IDs', async () => {
+        const adminEvent = {
+            timestamp: '1750979225854',
+            conversationId: 'conv-dedupe',
+            model: 'composer-2.5-standard',
+            chargedCents: 42.5,
+            tokenUsage: { inputTokens: 100, outputTokens: 50 },
+        };
+        expect(await importCursorUsageJson([adminEvent], testCwd)).toBe(1);
+        expect(await importCursorUsageJson([adminEvent], testCwd)).toBe(0);
+        const cost = await getTaskCostStats('conv-dedupe', testCwd);
+        expect(cost.actual.costUsd).toBeCloseTo(0.425, 3);
+        expect(cost.actual.isEstimated).toBe(false);
+    });
     it('summarizes agent scope overlap from session file', async () => {
         await fs.writeJson(path.join(testCwd, '.rigour', 'agent-session.json'), {
             agents: [
@@ -127,4 +141,29 @@ describe('context-telemetry-service', () => {
         expect(summary.compressionRatio).toBe(20);
         expect(summary.replayTokensAvoided).toBe(9500);
     });
+    it('marks observed cost from usages and estimates avoided cost by model', async () => {
+        const jsonTaskId = `${taskId}-composer-${Math.random().toString(36).slice(2)}`;
+        await importCursorUsageJson([{
+                id: `json-composer-${jsonTaskId}`,
+                taskId: jsonTaskId,
+                inputTokens: 2_000_000,
+                outputTokens: 0,
+                observedCostUsd: 1.25,
+                model: 'composer-2.5-standard',
+                source: 'cursor-admin-api',
+            }], testCwd);
+        await recordContextEvent({
+            taskId: jsonTaskId,
+            toolName: 'rigour_context_scope',
+            cacheStatus: 'miss',
+            candidateTokens: 3_000_000,
+            returnedTokens: 1_000_000,
+        }, testCwd);
+        const cost = await getTaskCostStats(jsonTaskId, testCwd);
+        expect(cost.actual.isEstimated).toBe(false);
+        expect(cost.actual.costUsd).toBe(1.25);
+        expect(cost.estimated.isEstimated).toBe(true);
+        expect(cost.estimated.inputPricePerMillionUsd).toBe(0.5);
+        expect(cost.estimated.estimatedCostAvoidedUsd).toBeGreaterThan(0);
+    });
 });

package/dist/services/cursor-usage-client.d.ts

@@ -0,0 +1,19 @@
+import { type NormalizedCursorUsageEvent } from './cursor-usage-normalizer.js';
+export declare const CURSOR_FILTERED_USAGE_URL = "https://api.cursor.com/teams/filtered-usage-events";
+export declare const DEFAULT_CURSOR_SYNC_DAYS = 30;
+export declare const DEFAULT_CURSOR_PAGE_SIZE = 100;
+export declare const MAX_CURSOR_SYNC_PAGES = 50;
+export interface CursorUsageSyncOptions {
+    cwd?: string;
+    apiKey?: string;
+    startDate?: number;
+    endDate?: number;
+    pageSize?: number;
+    maxPages?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare class CursorUsageApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function fetchCursorUsagePages(options?: CursorUsageSyncOptions): Promise<NormalizedCursorUsageEvent[]>;

package/dist/services/cursor-usage-client.js

@@ -0,0 +1,73 @@
+/**
+ * Cursor Admin API client for filtered usage events.
+ */
+import { getCursorApiKey } from '../settings.js';
+import { normalizeCursorUsageEvent, parseCursorUsageApiResponse, } from './cursor-usage-normalizer.js';
+export const CURSOR_FILTERED_USAGE_URL = 'https://api.cursor.com/teams/filtered-usage-events';
+export const DEFAULT_CURSOR_SYNC_DAYS = 30;
+export const DEFAULT_CURSOR_PAGE_SIZE = 100;
+export const MAX_CURSOR_SYNC_PAGES = 50;
+export class CursorUsageApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'CursorUsageApiError';
+        this.status = status;
+    }
+}
+function buildBasicAuthHeader(apiKey) {
+    const token = Buffer.from(`${apiKey}:`, 'utf8').toString('base64');
+    return `Basic ${token}`;
+}
+function defaultDateRange() {
+    const endDate = Date.now();
+    const startDate = endDate - DEFAULT_CURSOR_SYNC_DAYS * 24 * 60 * 60 * 1000;
+    return { startDate, endDate };
+}
+export async function fetchCursorUsagePages(options = {}) {
+    const apiKey = options.apiKey ?? getCursorApiKey();
+    if (!apiKey) {
+        return [];
+    }
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new CursorUsageApiError(0, 'Fetch is not available in this environment');
+    }
+    const range = defaultDateRange();
+    const startDate = options.startDate ?? range.startDate;
+    const endDate = options.endDate ?? range.endDate;
+    const pageSize = options.pageSize ?? DEFAULT_CURSOR_PAGE_SIZE;
+    const maxPages = options.maxPages ?? MAX_CURSOR_SYNC_PAGES;
+    const events = [];
+    let page = 1;
+    let hasNextPage = true;
+    while (hasNextPage && page <= maxPages) {
+        const response = await fetchImpl(CURSOR_FILTERED_USAGE_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: buildBasicAuthHeader(apiKey),
+            },
+            body: JSON.stringify({ startDate, endDate, page, pageSize }),
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => '');
+            const safeDetail = detail.replace(apiKey, '[REDACTED]').slice(0, 200);
+            throw new CursorUsageApiError(response.status, `Cursor Admin API request failed (${response.status}). ${safeDetail || 'Check API key scope and date range.'}`);
+        }
+        const json = await response.json();
+        const parsed = parseCursorUsageApiResponse(json);
+        for (const rawEvent of parsed.usageEvents ?? []) {
+            const normalized = normalizeCursorUsageEvent(rawEvent);
+            if (normalized) {
+                events.push(normalized);
+            }
+        }
+        hasNextPage = Boolean(parsed.pagination?.hasNextPage);
+        page += 1;
+    }
+    if (hasNextPage) {
+        throw new CursorUsageApiError(413, `Cursor usage sync truncated after ${maxPages} pages. Narrow the date range or contact support.`);
+    }
+    return events;
+}

package/dist/services/cursor-usage-normalizer.d.ts

@@ -0,0 +1,24 @@
+import type { ModelUsage } from '../storage/context-telemetry.js';
+export declare const CURSOR_ADMIN_API_SOURCE = "cursor-admin-api";
+export interface NormalizedCursorUsageEvent {
+    id: string;
+    usage: ModelUsage;
+}
+export interface CursorUsageApiResponse {
+    totalUsageEventsCount?: number;
+    usageEvents?: unknown[];
+    pagination?: {
+        hasNextPage?: boolean;
+        currentPage?: number;
+        numPages?: number;
+        pageSize?: number;
+    };
+}
+export declare function isCursorAdminApiEvent(value: unknown): value is Record<string, unknown>;
+/**
+ * Cursor reports costs in cents (`chargedCents`, `tokenUsage.totalCents`).
+ */
+export declare function centsToUsd(cents: number): number;
+export declare function buildCursorEventFingerprint(event: Record<string, unknown>): string;
+export declare function normalizeCursorUsageEvent(raw: unknown): NormalizedCursorUsageEvent | null;
+export declare function parseCursorUsageApiResponse(body: unknown): CursorUsageApiResponse;