@rigour-labs/core 5.3.3 → 5.4.0

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;

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

@@ -0,0 +1,102 @@
+/**
+ * Parse and normalize Cursor Admin API filtered usage events.
+ */
+import { createHash } from 'crypto';
+export const CURSOR_ADMIN_API_SOURCE = 'cursor-admin-api';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isCursorAdminApiEvent(value) {
+    if (!isRecord(value))
+        return false;
+    return value.tokenUsage !== undefined
+        || value.chargedCents !== undefined
+        || (value.timestamp !== undefined && value.model !== undefined);
+}
+function readNumber(value, fallback = 0) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+function readString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * Cursor reports costs in cents (`chargedCents`, `tokenUsage.totalCents`).
+ */
+export function centsToUsd(cents) {
+    return parseFloat((cents / 100).toFixed(6));
+}
+export function buildCursorEventFingerprint(event) {
+    const tokenUsage = isRecord(event.tokenUsage) ? event.tokenUsage : {};
+    const payload = [
+        readString(event.timestamp) ?? '',
+        readString(event.userEmail) ?? '',
+        readString(event.conversationId) ?? '',
+        readString(event.model) ?? '',
+        readNumber(event.chargedCents),
+        readNumber(tokenUsage.inputTokens),
+        readNumber(tokenUsage.outputTokens),
+        readNumber(tokenUsage.cacheReadTokens),
+        readNumber(tokenUsage.cacheWriteTokens),
+    ].join('|');
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}
+export function normalizeCursorUsageEvent(raw) {
+    if (!isRecord(raw))
+        return null;
+    const model = readString(raw.model) ?? 'unknown-model';
+    const timestamp = readString(raw.timestamp);
+    const conversationId = readString(raw.conversationId);
+    const tokenUsage = isRecord(raw.tokenUsage) ? raw.tokenUsage : undefined;
+    const inputTokens = tokenUsage ? readNumber(tokenUsage.inputTokens) : 0;
+    const outputTokens = tokenUsage ? readNumber(tokenUsage.outputTokens) : 0;
+    const cacheReadTokens = tokenUsage ? readNumber(tokenUsage.cacheReadTokens) : 0;
+    const cacheWriteTokens = tokenUsage ? readNumber(tokenUsage.cacheWriteTokens) : 0;
+    const chargedCents = readNumber(raw.chargedCents);
+    const tokenTotalCents = tokenUsage ? readNumber(tokenUsage.totalCents) : 0;
+    const observedCostUsd = chargedCents > 0
+        ? centsToUsd(chargedCents)
+        : tokenTotalCents > 0
+            ? centsToUsd(tokenTotalCents)
+            : 0;
+    const fingerprint = buildCursorEventFingerprint(raw);
+    const createdAt = timestamp ? readNumber(timestamp, Date.now()) : Date.now();
+    return {
+        id: `cursor-api-${fingerprint}`,
+        usage: {
+            id: `cursor-api-${fingerprint}`,
+            taskId: conversationId ?? 'cursor-imported',
+            sessionId: conversationId,
+            provider: 'cursor',
+            model,
+            inputTokens,
+            outputTokens,
+            cachedInputTokens: cacheReadTokens,
+            cacheWriteTokens,
+            observedCostUsd,
+            source: CURSOR_ADMIN_API_SOURCE,
+            createdAt,
+        },
+    };
+}
+export function parseCursorUsageApiResponse(body) {
+    if (!isRecord(body)) {
+        return {};
+    }
+    return {
+        totalUsageEventsCount: readNumber(body.totalUsageEventsCount),
+        usageEvents: Array.isArray(body.usageEvents) ? body.usageEvents : [],
+        pagination: isRecord(body.pagination) ? {
+            hasNextPage: Boolean(body.pagination.hasNextPage),
+            currentPage: readNumber(body.pagination.currentPage, 1),
+            numPages: readNumber(body.pagination.numPages, 1),
+            pageSize: readNumber(body.pagination.pageSize, 0),
+        } : undefined,
+    };
+}

package/dist/services/cursor-usage-sync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/cursor-usage-sync.test.js

@@ -0,0 +1,173 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import path from 'path';
+import os from 'os';
+import fs from 'fs-extra';
+vi.mock('../storage/db.js', () => ({
+    isSQLiteAvailable: () => false,
+    openDatabase: async () => null,
+    DB_PATH: '/tmp/rigour-test.db',
+    RIGOUR_DIR: '/tmp/.rigour',
+}));
+import { fetchCursorUsageFromAdminApi, syncCursorUsageFromAdminApi, getTaskCostStats, } from './context-telemetry-service.js';
+import { getModelUsages } from '../storage/context-telemetry.js';
+import { centsToUsd, normalizeCursorUsageEvent } from './cursor-usage-normalizer.js';
+import { CURSOR_FILTERED_USAGE_URL } from './cursor-usage-client.js';
+function buildUsageEvent(overrides = {}) {
+    return {
+        timestamp: '1750979225854',
+        userEmail: 'dev@example.com',
+        conversationId: 'conv-1',
+        model: 'composer-2.5-standard',
+        isTokenBasedCall: true,
+        tokenUsage: {
+            inputTokens: 100,
+            outputTokens: 50,
+            cacheWriteTokens: 10,
+            cacheReadTokens: 20,
+            totalCents: 12.5,
+        },
+        chargedCents: 15.25,
+        ...overrides,
+    };
+}
+describe('cursor admin usage sync', () => {
+    const testCwd = path.join(os.tmpdir(), `rigour-cursor-sync-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const apiKey = 'test-cursor-admin-key';
+    beforeEach(async () => {
+        await fs.ensureDir(path.join(testCwd, '.rigour'));
+    });
+    afterEach(async () => {
+        await fs.remove(testCwd);
+        vi.restoreAllMocks();
+    });
+    it('imports a single-page response with basic auth header', async () => {
+        const fetchImpl = vi.fn(async (_url, init) => ({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                usageEvents: [buildUsageEvent()],
+                pagination: { hasNextPage: false, currentPage: 1 },
+            }),
+        }));
+        const imported = await fetchCursorUsageFromAdminApi({
+            cwd: testCwd,
+            apiKey,
+            fetchImpl,
+        });
+        expect(imported).toBe(1);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+        const [, init] = fetchImpl.mock.calls[0];
+        expect(init.method).toBe('POST');
+        expect(init.headers.Authorization).toBe(`Basic ${Buffer.from(`${apiKey}:`, 'utf8').toString('base64')}`);
+        expect(init.headers['Content-Type']).toBe('application/json');
+        const body = JSON.parse(init.body);
+        expect(body.pageSize).toBeGreaterThan(0);
+        expect(body.startDate).toBeLessThan(body.endDate);
+    });
+    it('paginates until hasNextPage is false', async () => {
+        let page = 0;
+        const fetchImpl = vi.fn(async () => {
+            page += 1;
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    usageEvents: [buildUsageEvent({ conversationId: `conv-${page}` })],
+                    pagination: { hasNextPage: page < 2, currentPage: page },
+                }),
+            };
+        });
+        const result = await syncCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl });
+        expect(result.importedCount).toBe(2);
+        expect(result.totalEvents).toBe(2);
+        expect(fetchImpl).toHaveBeenCalledTimes(2);
+    });
+    it('converts cents to USD and stores token fields', async () => {
+        const normalized = normalizeCursorUsageEvent(buildUsageEvent());
+        expect(normalized?.usage.observedCostUsd).toBe(centsToUsd(15.25));
+        expect(normalized?.usage.inputTokens).toBe(100);
+        expect(normalized?.usage.outputTokens).toBe(50);
+        expect(normalized?.usage.cachedInputTokens).toBe(20);
+        expect(normalized?.usage.cacheWriteTokens).toBe(10);
+        expect(normalized?.usage.source).toBe('cursor-admin-api');
+    });
+    it('deduplicates repeated syncs', async () => {
+        const fetchImpl = vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                usageEvents: [buildUsageEvent()],
+                pagination: { hasNextPage: false },
+            }),
+        }));
+        const first = await fetchCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl });
+        const second = await fetchCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl });
+        expect(first).toBe(1);
+        expect(second).toBe(0);
+        const usages = await getModelUsages(undefined, testCwd);
+        expect(usages.filter(u => u.source === 'cursor-admin-api')).toHaveLength(1);
+    });
+    it('surfaces actionable non-2xx errors without exposing the API key', async () => {
+        const fetchImpl = vi.fn(async () => ({
+            ok: false,
+            status: 401,
+            text: async () => `Unauthorized for key ${apiKey}`,
+        }));
+        await expect(fetchCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl })).rejects.toThrow(/401/);
+        await expect(fetchCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl })).rejects.not.toThrow(apiKey);
+    });
+    it('skips malformed events and handles partial fields', async () => {
+        const fetchImpl = vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                usageEvents: [
+                    null,
+                    { model: 'composer-2.5-fast', chargedCents: 5 },
+                    buildUsageEvent(),
+                ],
+                pagination: { hasNextPage: false },
+            }),
+        }));
+        const imported = await fetchCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl });
+        expect(imported).toBe(2);
+    });
+    it('marks observed cost stats from imported admin API events', async () => {
+        const fetchImpl = vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                usageEvents: [buildUsageEvent({ conversationId: 'cost-task' })],
+                pagination: { hasNextPage: false },
+            }),
+        }));
+        await fetchCursorUsageFromAdminApi({ cwd: testCwd, apiKey, fetchImpl });
+        const cost = await getTaskCostStats('cost-task', testCwd);
+        expect(cost.actual.isEstimated).toBe(false);
+        expect(cost.actual.costUsd).toBeGreaterThan(0);
+        expect(cost.actual.pricingBasis).toBe('observed-cursor-charged-cents');
+    });
+    it('targets the filtered usage events endpoint', () => {
+        expect(CURSOR_FILTERED_USAGE_URL).toBe('https://api.cursor.com/teams/filtered-usage-events');
+    });
+    it('errors when pagination exceeds the defensive page limit', async () => {
+        let page = 0;
+        const fetchImpl = vi.fn(async () => {
+            page += 1;
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    usageEvents: [buildUsageEvent({ conversationId: `conv-page-${page}` })],
+                    pagination: { hasNextPage: true, currentPage: page },
+                }),
+            };
+        });
+        await expect(fetchCursorUsageFromAdminApi({
+            cwd: testCwd,
+            apiKey,
+            fetchImpl,
+            maxPages: 2,
+        })).rejects.toThrow(/truncated after 2 pages/);
+    });
+});

package/dist/services/model-pricing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Model-aware input pricing for context cost telemetry.
+ * Observed Cursor costs always take precedence; these rates estimate when absent.
+ */
+import type { ModelUsage } from '../storage/context-telemetry.js';
+export interface ModelPricingTier {
+    label: string;
+    inputPerMillionUsd: number;
+    outputPerMillionUsd: number;
+}
+/** Per-million-token USD rates. Input rates drive avoided-context estimates. */
+export declare const MODEL_PRICING: Record<string, ModelPricingTier>;
+/** Conservative fallback when model cannot be resolved (USD per 1M input tokens). */
+export declare const FALLBACK_INPUT_PRICE_PER_MILLION_USD = 3;
+export declare const FALLBACK_OUTPUT_PRICE_PER_MILLION_USD = 15;
+/**
+ * Normalize model identifiers from Cursor, CLI flags, or imports.
+ */
+export declare function normalizeModelKey(model: string | undefined): string;
+export declare function getModelPricing(model: string | undefined): ModelPricingTier | undefined;
+export declare function getInputPricePerMillionUsd(model: string | undefined): number;
+export declare function getOutputPricePerMillionUsd(model: string | undefined): number;
+export interface WeightedInputPricing {
+    inputPricePerMillionUsd: number;
+    pricingBasis: string;
+    isEstimated: boolean;
+}
+/**
+ * Input-token-weighted effective input price across observed model usages.
+ */
+export declare function computeWeightedInputPricePerMillion(usages: ModelUsage[]): WeightedInputPricing;
+export declare function estimateTokenCostUsd(inputTokens: number, outputTokens: number, model: string | undefined): number;
+export declare function estimateAvoidedContextCostUsd(avoidedInputTokens: number, usages: ModelUsage[]): {
+    costUsd: number;
+    pricing: WeightedInputPricing;
+};

package/dist/services/model-pricing.js

@@ -0,0 +1,137 @@
+/**
+ * Model-aware input pricing for context cost telemetry.
+ * Observed Cursor costs always take precedence; these rates estimate when absent.
+ */
+/** Per-million-token USD rates. Input rates drive avoided-context estimates. */
+export const MODEL_PRICING = {
+    'composer-2.5-standard': {
+        label: 'Composer 2.5 Standard',
+        inputPerMillionUsd: 0.5,
+        outputPerMillionUsd: 2.5,
+    },
+    'composer-2.5-fast': {
+        label: 'Composer 2.5 Fast',
+        inputPerMillionUsd: 3.0,
+        outputPerMillionUsd: 15.0,
+    },
+    'claude-3-5-sonnet': {
+        label: 'Claude 3.5 Sonnet',
+        inputPerMillionUsd: 3.0,
+        outputPerMillionUsd: 15.0,
+    },
+    'gpt-4o': {
+        label: 'GPT-4o',
+        inputPerMillionUsd: 2.5,
+        outputPerMillionUsd: 10.0,
+    },
+    'gpt-4o-mini': {
+        label: 'GPT-4o Mini',
+        inputPerMillionUsd: 0.15,
+        outputPerMillionUsd: 0.6,
+    },
+    'o1-preview': {
+        label: 'o1 Preview',
+        inputPerMillionUsd: 15.0,
+        outputPerMillionUsd: 60.0,
+    },
+};
+/** Conservative fallback when model cannot be resolved (USD per 1M input tokens). */
+export const FALLBACK_INPUT_PRICE_PER_MILLION_USD = 3.0;
+export const FALLBACK_OUTPUT_PRICE_PER_MILLION_USD = 15.0;
+const MODEL_ALIASES = {
+    'composer-2.5': 'composer-2.5-standard',
+    'composer-25-standard': 'composer-2.5-standard',
+    'composer-25-fast': 'composer-2.5-fast',
+    'composer-2-5-standard': 'composer-2.5-standard',
+    'composer-2-5-fast': 'composer-2.5-fast',
+    'composer25standard': 'composer-2.5-standard',
+    'composer25fast': 'composer-2.5-fast',
+};
+/**
+ * Normalize model identifiers from Cursor, CLI flags, or imports.
+ */
+export function normalizeModelKey(model) {
+    if (!model)
+        return 'unknown';
+    const lowered = model.trim().toLowerCase();
+    const compact = lowered
+        .replace(/[_\s]+/g, '-')
+        .replace(/[^a-z0-9.-]/g, '')
+        .replace(/-+/g, '-');
+    if (MODEL_ALIASES[compact]) {
+        return MODEL_ALIASES[compact];
+    }
+    if (compact.includes('composer') && compact.includes('fast')) {
+        return 'composer-2.5-fast';
+    }
+    if (compact.includes('composer')) {
+        return 'composer-2.5-standard';
+    }
+    if (compact.includes('claude') && compact.includes('sonnet')) {
+        return 'claude-3-5-sonnet';
+    }
+    if (compact.includes('gpt-4o-mini') || compact.includes('gpt4omini')) {
+        return 'gpt-4o-mini';
+    }
+    if (compact.includes('gpt-4o') || compact.includes('gpt4o')) {
+        return 'gpt-4o';
+    }
+    if (compact.includes('o1-preview') || compact.includes('o1preview')) {
+        return 'o1-preview';
+    }
+    return compact;
+}
+export function getModelPricing(model) {
+    const key = normalizeModelKey(model);
+    return MODEL_PRICING[key];
+}
+export function getInputPricePerMillionUsd(model) {
+    return getModelPricing(model)?.inputPerMillionUsd ?? FALLBACK_INPUT_PRICE_PER_MILLION_USD;
+}
+export function getOutputPricePerMillionUsd(model) {
+    return getModelPricing(model)?.outputPerMillionUsd ?? FALLBACK_OUTPUT_PRICE_PER_MILLION_USD;
+}
+/**
+ * Input-token-weighted effective input price across observed model usages.
+ */
+export function computeWeightedInputPricePerMillion(usages) {
+    const withInput = usages.filter(u => (u.inputTokens || 0) > 0 && u.model);
+    if (withInput.length === 0) {
+        return {
+            inputPricePerMillionUsd: FALLBACK_INPUT_PRICE_PER_MILLION_USD,
+            pricingBasis: 'conservative-fallback-unknown-model',
+            isEstimated: true,
+        };
+    }
+    let weightedSum = 0;
+    let totalInput = 0;
+    const modelsUsed = new Set();
+    for (const usage of withInput) {
+        const tokens = usage.inputTokens || 0;
+        const price = getInputPricePerMillionUsd(usage.model);
+        weightedSum += price * tokens;
+        totalInput += tokens;
+        modelsUsed.add(normalizeModelKey(usage.model));
+    }
+    const effective = totalInput > 0 ? weightedSum / totalInput : FALLBACK_INPUT_PRICE_PER_MILLION_USD;
+    const basis = modelsUsed.size === 1
+        ? `model:${Array.from(modelsUsed)[0]}`
+        : `mixed-model-weighted:${Array.from(modelsUsed).join(',')}`;
+    return {
+        inputPricePerMillionUsd: effective,
+        pricingBasis: basis,
+        isEstimated: true,
+    };
+}
+export function estimateTokenCostUsd(inputTokens, outputTokens, model) {
+    const inputPrice = getInputPricePerMillionUsd(model);
+    const outputPrice = getOutputPricePerMillionUsd(model);
+    const inputCost = (inputTokens / 1_000_000) * inputPrice;
+    const outputCost = (outputTokens / 1_000_000) * outputPrice;
+    return parseFloat((inputCost + outputCost).toFixed(4));
+}
+export function estimateAvoidedContextCostUsd(avoidedInputTokens, usages) {
+    const pricing = computeWeightedInputPricePerMillion(usages);
+    const costUsd = parseFloat(((avoidedInputTokens / 1_000_000) * pricing.inputPricePerMillionUsd).toFixed(4));
+    return { costUsd, pricing };
+}

package/dist/services/model-pricing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/model-pricing.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeModelKey, getInputPricePerMillionUsd, computeWeightedInputPricePerMillion, estimateAvoidedContextCostUsd, estimateTokenCostUsd, FALLBACK_INPUT_PRICE_PER_MILLION_USD, } from './model-pricing.js';
+describe('model-pricing', () => {
+    it('resolves Composer 2.5 Standard input pricing', () => {
+        expect(getInputPricePerMillionUsd('Composer 2.5 Standard')).toBe(0.5);
+        expect(normalizeModelKey('composer-2-5-standard')).toBe('composer-2.5-standard');
+    });
+    it('resolves Composer 2.5 Fast input pricing', () => {
+        expect(getInputPricePerMillionUsd('composer-2.5-fast')).toBe(3.0);
+        expect(normalizeModelKey('Composer 2.5 Fast')).toBe('composer-2.5-fast');
+    });
+    it('normalizes aliases with spaces and hyphens', () => {
+        expect(normalizeModelKey('Composer_2.5 FAST')).toBe('composer-2.5-fast');
+        expect(normalizeModelKey('composer 25 standard')).toBe('composer-2.5-standard');
+    });
+    it('uses conservative fallback for unknown models', () => {
+        expect(getInputPricePerMillionUsd('totally-unknown-model')).toBe(FALLBACK_INPUT_PRICE_PER_MILLION_USD);
+    });
+    it('computes mixed-model input-token-weighted pricing', () => {
+        const usages = [
+            { source: 'cursor-admin-api', model: 'composer-2.5-standard', inputTokens: 1000, outputTokens: 0 },
+            { source: 'cursor-admin-api', model: 'composer-2.5-fast', inputTokens: 3000, outputTokens: 0 },
+        ];
+        const weighted = computeWeightedInputPricePerMillion(usages);
+        expect(weighted.inputPricePerMillionUsd).toBeCloseTo(2.375, 3);
+        expect(weighted.pricingBasis).toContain('mixed-model-weighted');
+    });
+    it('prefers observed cost when estimating actual spend is unnecessary', () => {
+        const observed = 4.25;
+        expect(observed).toBeGreaterThan(0);
+    });
+    it('estimates actual token cost when observed cost is absent', () => {
+        const estimated = estimateTokenCostUsd(1_000_000, 0, 'composer-2.5-standard');
+        expect(estimated).toBe(0.5);
+    });
+    it('estimates avoided context using input pricing only', () => {
+        const usages = [
+            { source: 'cursor-admin-api', model: 'composer-2.5-standard', inputTokens: 100, outputTokens: 0 },
+        ];
+        const { costUsd, pricing } = estimateAvoidedContextCostUsd(2_000_000, usages);
+        expect(pricing.inputPricePerMillionUsd).toBe(0.5);
+        expect(costUsd).toBe(1.0);
+    });
+});

package/dist/storage/context-telemetry.d.ts

@@ -23,6 +23,7 @@ export interface ModelUsage {
     inputTokens: number;
     outputTokens: number;
     cachedInputTokens?: number;
+    cacheWriteTokens?: number;
     observedCostUsd?: number;
     source: string;
     createdAt?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "5.3.3",
+  "version": "5.4.0",
   "description": "AI-native quality gate engine with local Bayesian learning. AST analysis, drift detection, Fix Packet generation, and agent self-healing across TypeScript, JavaScript, Python, Go, Ruby, and C#.",
   "license": "MIT",
   "homepage": "https://rigour.run",
@@ -66,11 +66,11 @@
     "@xenova/transformers": "^2.17.2",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-arm64": "5.3.3",
-    "@rigour-labs/brain-linux-x64": "5.3.3",
-    "@rigour-labs/brain-linux-arm64": "5.3.3",
-    "@rigour-labs/brain-win-x64": "5.3.3",
-    "@rigour-labs/brain-darwin-x64": "5.3.3"
+    "@rigour-labs/brain-darwin-arm64": "5.4.0",
+    "@rigour-labs/brain-darwin-x64": "5.4.0",
+    "@rigour-labs/brain-linux-arm64": "5.4.0",
+    "@rigour-labs/brain-linux-x64": "5.4.0",
+    "@rigour-labs/brain-win-x64": "5.4.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",