@rigour-labs/core 5.3.3 → 5.5.0

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/settings.d.ts

@@ -106,10 +106,23 @@ export declare function updateProviderKey(provider: string, apiKey: string): voi
  */
 export declare function removeProviderKey(provider: string): void;
 /**
- * Get Cursor Admin API key from settings
+ * Get Cursor Admin API key — prefer env over file-stored secret.
+ * Env: RIGOUR_CURSOR_API_KEY or CURSOR_ADMIN_API_KEY
  */
 export declare function getCursorApiKey(): string | undefined;
 /**
- * Update Cursor Admin API key in settings
+ * Whether a Cursor vendor adapter key is available (env or file).
+ */
+export declare function isCursorApiKeyConfigured(): boolean;
+/**
+ * Last-4 hint for UI status — never return the full key.
+ */
+export declare function getCursorApiKeyHint(): string | undefined;
+/**
+ * Persist Cursor Admin API key to settings (optional; prefer env in production).
  */
 export declare function updateCursorApiKey(apiKey: string): void;
+/**
+ * Remove file-stored Cursor Admin API key (env vars are untouched).
+ */
+export declare function removeCursorApiKey(): void;

package/dist/settings.js

@@ -45,10 +45,22 @@ export function saveSettings(settings) {
     const settingsPath = getSettingsPath();
     const settingsDir = path.dirname(settingsPath);
     try {
-        // Ensure directory exists
+        // Ensure directory exists with owner-only access
         fs.ensureDirSync(settingsDir);
+        try {
+            fs.chmodSync(settingsDir, 0o700);
+        }
+        catch {
+            // ignore chmod failures on platforms that do not support it
+        }
         // Write with pretty formatting (2-space indent)
-        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        try {
+            fs.chmodSync(settingsPath, 0o600);
+        }
+        catch {
+            // ignore chmod failures on platforms that do not support it
+        }
         Logger.debug(`Settings saved to ${settingsPath}`);
     }
     catch (error) {
@@ -185,20 +197,58 @@ export function removeProviderKey(provider) {
     }
 }
 /**
- * Get Cursor Admin API key from settings
+ * Get Cursor Admin API key — prefer env over file-stored secret.
+ * Env: RIGOUR_CURSOR_API_KEY or CURSOR_ADMIN_API_KEY
  */
 export function getCursorApiKey() {
+    const fromEnv = process.env.RIGOUR_CURSOR_API_KEY?.trim() ||
+        process.env.CURSOR_ADMIN_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
     const settings = loadSettings();
-    return settings.cursor?.apiKey;
+    const fromFile = settings.cursor?.apiKey?.trim();
+    return fromFile || undefined;
+}
+/**
+ * Whether a Cursor vendor adapter key is available (env or file).
+ */
+export function isCursorApiKeyConfigured() {
+    return Boolean(getCursorApiKey());
 }
 /**
- * Update Cursor Admin API key in settings
+ * Last-4 hint for UI status — never return the full key.
+ */
+export function getCursorApiKeyHint() {
+    const key = getCursorApiKey();
+    if (!key || key.length < 4)
+        return undefined;
+    return `••••${key.slice(-4)}`;
+}
+/**
+ * Persist Cursor Admin API key to settings (optional; prefer env in production).
  */
 export function updateCursorApiKey(apiKey) {
+    const trimmed = apiKey.trim();
+    if (!trimmed || trimmed.length > 512) {
+        throw new Error('Invalid Cursor Admin API key');
+    }
     const settings = loadSettings();
     if (!settings.cursor) {
         settings.cursor = {};
     }
-    settings.cursor.apiKey = apiKey;
+    settings.cursor.apiKey = trimmed;
     saveSettings(settings);
 }
+/**
+ * Remove file-stored Cursor Admin API key (env vars are untouched).
+ */
+export function removeCursorApiKey() {
+    const settings = loadSettings();
+    if (settings.cursor?.apiKey) {
+        delete settings.cursor.apiKey;
+        if (Object.keys(settings.cursor).length === 0) {
+            delete settings.cursor;
+        }
+        saveSettings(settings);
+    }
+}

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;
@@ -61,6 +62,14 @@ export declare function recordModelUsage(usage: ModelUsage, cwd?: string): Promi
  * Insert or update cache entry.
  */
 export declare function setContextCacheRecord(record: ContextCacheRecord, cwd?: string): Promise<void>;
+/**
+ * List cache records by type (and optional commit). Does not increment hit counts.
+ */
+export declare function listContextCacheRecords(opts: {
+    cacheType?: ContextCacheRecord['cacheType'];
+    commitSha?: string;
+    limit?: number;
+}, cwd?: string): Promise<ContextCacheRecord[]>;
 /**
  * Fetch cached context record by cache key. Increments hit count.
  */