@rigour-labs/core 5.2.9 → 5.3.1

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

@@ -0,0 +1,121 @@
+/**
+ * High-Level Context Telemetry Service
+ * Calculates exact observed usage, avoided tokens, cache performance, and cost breakdowns.
+ * Supports CSV/JSON Cursor usage imports.
+ */
+/** Heuristic token counter (~4 chars per token for code/text) */
+export declare function estimateTokenCount(text: string): number;
+/** Default session token budgets */
+export declare const DEFAULT_SESSION_SOFT_LIMIT = 160000;
+export declare const DEFAULT_SESSION_HARD_LIMIT = 200000;
+export interface TaskContextStats {
+    taskId: string;
+    retrievals: number;
+    candidateTokens: number;
+    returnedTokens: number;
+    potentialAvoidedTokens: number;
+    cacheHitRate: number;
+    repeatedReadsPrevented: number;
+    checkpointReplayAvoided: number;
+    isEstimated: boolean;
+}
+export interface TaskCostStats {
+    actual: {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        source: string;
+        isEstimated: boolean;
+    };
+    estimated: {
+        potentialContextAvoided: number;
+        estimatedCostAvoidedUsd: number;
+        isEstimated: boolean;
+    };
+}
+export interface CachePerformanceStats {
+    exactCacheHits: number;
+    semanticCacheHits: number;
+    partialCacheHits: number;
+    cacheMisses: number;
+    hitRate: number;
+    tokensServedFromCache: number;
+    recomputationAvoided: number;
+    isEstimated: boolean;
+}
+export interface SessionBudgetStatus {
+    sessionId: string;
+    usedTokens: number;
+    softLimit: number;
+    hardLimit: number;
+    softLimitReached: boolean;
+    hardLimitReached: boolean;
+    remainingTokens: number;
+    isEstimated: boolean;
+}
+export interface ContextExplainResult {
+    fileOrService: string;
+    status: 'included' | 'excluded';
+    reason: string;
+    servedFromCache: boolean;
+    cacheStatus: string;
+    invalidationReason?: string;
+    priorAgentRequests: string[];
+}
+export interface ContextScopeSummary {
+    overlappingScopesResolved: number;
+    overlappingScopePairs: string[];
+    alwaysOnRuleTokens: number;
+    unusedToolsFiltered: number;
+    activeAgentCount: number;
+}
+export interface CheckpointSummary {
+    rawStateTokens: number;
+    checkpointTokens: number;
+    compressionRatio: number;
+    checkpointCount: number;
+    replayTokensAvoided: number;
+}
+/**
+ * Generate task-level context telemetry summary.
+ */
+export declare function getTaskContextStats(taskId?: string, cwd?: string): Promise<TaskContextStats>;
+/**
+ * Generate task-level cost summary (actual vs estimated avoided).
+ */
+export declare function getTaskCostStats(taskId?: string, cwd?: string): Promise<TaskCostStats>;
+/**
+ * Aggregate cache performance across events.
+ */
+export declare function getCacheStats(cwd?: string): Promise<CachePerformanceStats>;
+/**
+ * Report session token budget usage against soft and hard limits.
+ */
+export declare function getSessionBudgetStatus(sessionId: string, cwd?: string, softLimit?: number, hardLimit?: number): Promise<SessionBudgetStatus>;
+/**
+ * Explain context inclusion/exclusion and cache status for a given target file or query.
+ */
+export declare function explainContext(target: string, taskId?: string, cwd?: string): Promise<ContextExplainResult>;
+/**
+ * Import Cursor usage data from CSV format.
+ * Expects CSV format with columns: Date,Model,Input Tokens,Output Tokens,Cost
+ * Deduplicates rows by content hash before insert.
+ */
+export declare function importCursorUsageCsv(csvContent: string, cwd?: string): Promise<number>;
+/**
+ * Import Cursor usage data from JSON format (e.g. from Cursor Admin API).
+ */
+export declare function importCursorUsageJson(jsonData: unknown, cwd?: string): Promise<number>;
+/**
+ * Fetch Cursor usage from Admin API (stub — requires API key in settings).
+ * Returns number of records imported, or 0 if unavailable.
+ */
+export declare function fetchCursorUsageFromAdminApi(cwd?: string): Promise<number>;
+/**
+ * Summarize agent scope overlap and governance rule overhead for Studio.
+ */
+export declare function getContextScopeSummary(cwd?: string): Promise<ContextScopeSummary>;
+/**
+ * Aggregate checkpoint compression metrics for Studio.
+ */
+export declare function getCheckpointSummary(taskId?: string, cwd?: string): Promise<CheckpointSummary>;

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

@@ -0,0 +1,375 @@
+/**
+ * High-Level Context Telemetry Service
+ * Calculates exact observed usage, avoided tokens, cache performance, and cost breakdowns.
+ * Supports CSV/JSON Cursor usage imports.
+ */
+import { createHash } from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+import { getContextEvents, getModelUsages, getCheckpointMetrics, recordModelUsage, } from '../storage/index.js';
+import { getCursorApiKey } from '../settings.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;
+const GOVERNANCE_RULE_FILES = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', '.windsurfrules', '.clinerules'];
+function scopesOverlap(scope1, scope2) {
+    const overlapping = [];
+    for (const s1 of scope1) {
+        for (const s2 of scope2) {
+            if (s1 === s2 || s1.startsWith(s2.replace('**', '')) || s2.startsWith(s1.replace('**', ''))) {
+                overlapping.push(`${s1} ↔ ${s2}`);
+            }
+        }
+    }
+    return overlapping;
+}
+function hashCsvRow(line) {
+    return createHash('sha256').update(line.trim()).digest('hex').slice(0, 16);
+}
+/**
+ * Generate task-level context telemetry summary.
+ */
+export async function getTaskContextStats(taskId, cwd) {
+    const events = await getContextEvents(taskId, cwd);
+    const checkpoints = await getCheckpointMetrics(taskId, cwd);
+    const retrievals = events.length;
+    let candidateTokens = 0;
+    let returnedTokens = 0;
+    let cacheHits = 0;
+    let repeatedReads = 0;
+    for (const e of events) {
+        candidateTokens += e.candidateTokens || 0;
+        returnedTokens += e.returnedTokens || 0;
+        if (e.cacheStatus && e.cacheStatus !== 'miss' && e.cacheStatus !== 'none') {
+            cacheHits++;
+        }
+        const deduped = e.deduplicatedTokens ?? 0;
+        if (deduped > 0) {
+            repeatedReads += Math.ceil(deduped / 500);
+        }
+    }
+    const potentialAvoidedTokens = Math.max(0, candidateTokens - returnedTokens);
+    const cacheHitRate = retrievals > 0 ? parseFloat((cacheHits / retrievals).toFixed(2)) : 0;
+    const checkpointReplayAvoided = checkpoints.reduce((acc, c) => acc + (c.replayTokensAvoided || 0), 0);
+    return {
+        taskId: taskId || 'global',
+        retrievals,
+        candidateTokens,
+        returnedTokens,
+        potentialAvoidedTokens,
+        cacheHitRate,
+        repeatedReadsPrevented: repeatedReads,
+        checkpointReplayAvoided,
+        isEstimated: retrievals === 0,
+    };
+}
+/**
+ * Generate task-level cost summary (actual vs estimated avoided).
+ */
+export async function getTaskCostStats(taskId, cwd) {
+    const usages = await getModelUsages(taskId, cwd);
+    const stats = await getTaskContextStats(taskId, cwd);
+    let actualInputTokens = 0;
+    let actualOutputTokens = 0;
+    let actualCostUsd = 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;
+        if (u.source && u.source !== 'estimated') {
+            primarySource = u.source;
+        }
+    }
+    const pricePerM = DEFAULT_MODEL_PRICES['claude-3-5-sonnet'] || 3.0;
+    const totalPotentialAvoided = stats.potentialAvoidedTokens + stats.checkpointReplayAvoided;
+    const estimatedCostAvoidedUsd = parseFloat(((totalPotentialAvoided / 1_000_000) * pricePerM).toFixed(2));
+    return {
+        actual: {
+            inputTokens: actualInputTokens,
+            outputTokens: actualOutputTokens,
+            costUsd: parseFloat(actualCostUsd.toFixed(2)),
+            source: primarySource,
+            isEstimated: !hasObservedUsage,
+        },
+        estimated: {
+            potentialContextAvoided: totalPotentialAvoided,
+            estimatedCostAvoidedUsd,
+            isEstimated: true,
+        },
+    };
+}
+/**
+ * Aggregate cache performance across events.
+ */
+export async function getCacheStats(cwd) {
+    const events = await getContextEvents(undefined, cwd);
+    let exactHits = 0;
+    let semanticHits = 0;
+    let partialHits = 0;
+    let misses = 0;
+    let tokensServed = 0;
+    for (const e of events) {
+        if (e.cacheStatus === 'exact-hit') {
+            exactHits++;
+            tokensServed += e.returnedTokens || 0;
+        }
+        else if (e.cacheStatus === 'semantic-hit') {
+            semanticHits++;
+            tokensServed += e.returnedTokens || 0;
+        }
+        else if (e.cacheStatus === 'partial-hit') {
+            partialHits++;
+            tokensServed += e.returnedTokens || 0;
+        }
+        else {
+            misses++;
+        }
+    }
+    const totalHits = exactHits + semanticHits + partialHits;
+    const totalCalls = totalHits + misses;
+    const hitRate = totalCalls > 0 ? parseFloat((totalHits / totalCalls).toFixed(2)) : 0;
+    return {
+        exactCacheHits: exactHits,
+        semanticCacheHits: semanticHits,
+        partialCacheHits: partialHits,
+        cacheMisses: misses,
+        hitRate,
+        tokensServedFromCache: tokensServed,
+        recomputationAvoided: Math.max(0, tokensServed - 1000),
+        isEstimated: events.length === 0,
+    };
+}
+/**
+ * Report session token budget usage against soft and hard limits.
+ */
+export async function getSessionBudgetStatus(sessionId, cwd, softLimit = DEFAULT_SESSION_SOFT_LIMIT, hardLimit = DEFAULT_SESSION_HARD_LIMIT) {
+    const events = await getContextEvents(undefined, cwd);
+    const usages = await getModelUsages(undefined, cwd);
+    const sessionEvents = events.filter(e => e.sessionId === sessionId);
+    const sessionUsages = usages.filter(u => u.sessionId === sessionId);
+    let contextTokens = 0;
+    for (const e of sessionEvents) {
+        contextTokens += e.returnedTokens || 0;
+    }
+    let modelTokens = 0;
+    let hasObserved = sessionUsages.length > 0;
+    for (const u of sessionUsages) {
+        modelTokens += (u.inputTokens || 0) + (u.outputTokens || 0);
+    }
+    const usedTokens = modelTokens > 0 ? modelTokens : contextTokens;
+    const softLimitReached = usedTokens >= softLimit;
+    const hardLimitReached = usedTokens >= hardLimit;
+    return {
+        sessionId,
+        usedTokens,
+        softLimit,
+        hardLimit,
+        softLimitReached,
+        hardLimitReached,
+        remainingTokens: Math.max(0, hardLimit - usedTokens),
+        isEstimated: !hasObserved && sessionEvents.length > 0,
+    };
+}
+/**
+ * Explain context inclusion/exclusion and cache status for a given target file or query.
+ */
+export async function explainContext(target, taskId, cwd) {
+    const events = await getContextEvents(taskId, cwd);
+    const matchingEvents = events.filter(e => e.queryHash?.includes(target) || e.toolName.includes(target) || target === 'all');
+    const priorAgentRequests = events
+        .filter(e => e.agentId)
+        .map(e => `${e.agentId} called ${e.toolName} (${e.cacheStatus})`);
+    if (matchingEvents.length > 0) {
+        const lastEvt = matchingEvents[0];
+        const isHit = lastEvt.cacheStatus !== 'miss' && lastEvt.cacheStatus !== 'none';
+        const returnedFiles = lastEvt.returnedFiles ?? 0;
+        const returnedTokens = lastEvt.returnedTokens ?? 0;
+        return {
+            fileOrService: target,
+            status: returnedFiles > 0 || returnedTokens > 0 ? 'included' : 'excluded',
+            reason: isHit
+                ? `Served from ${lastEvt.cacheStatus} cache (reduced ${lastEvt.candidateTokens - returnedTokens} tokens)`
+                : 'Computed dynamically because no active cache entry matched',
+            servedFromCache: isHit,
+            cacheStatus: lastEvt.cacheStatus,
+            invalidationReason: isHit ? undefined : 'Source file or component contract was modified',
+            priorAgentRequests: Array.from(new Set(priorAgentRequests)).slice(0, 5),
+        };
+    }
+    return {
+        fileOrService: target,
+        status: 'excluded',
+        reason: 'Target was outside of defined task scope and AST dependency subgraph',
+        servedFromCache: false,
+        cacheStatus: 'miss',
+        invalidationReason: 'Not requested in current session scope',
+        priorAgentRequests: Array.from(new Set(priorAgentRequests)).slice(0, 5),
+    };
+}
+/**
+ * Import Cursor usage data from CSV format.
+ * Expects CSV format with columns: Date,Model,Input Tokens,Output Tokens,Cost
+ * Deduplicates rows by content hash before insert.
+ */
+export async function importCursorUsageCsv(csvContent, cwd) {
+    const lines = csvContent.trim().split('\n').filter(Boolean);
+    if (lines.length <= 1)
+        return 0;
+    const headers = lines[0].toLowerCase().split(',').map(h => h.trim().replace(/^"/, '').replace(/"$/, ''));
+    const inputIdx = headers.findIndex(h => h.includes('input'));
+    const outputIdx = headers.findIndex(h => h.includes('output'));
+    const costIdx = headers.findIndex(h => h.includes('cost') || h.includes('spend'));
+    const modelIdx = headers.findIndex(h => h.includes('model'));
+    const existingUsages = await getModelUsages(undefined, cwd);
+    const seenHashes = new Set(existingUsages
+        .filter(u => u.id?.startsWith('csv-'))
+        .map(u => u.id.slice(4)));
+    let importedCount = 0;
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        const rowHash = hashCsvRow(line);
+        if (seenHashes.has(rowHash))
+            continue;
+        seenHashes.add(rowHash);
+        const cols = line.split(',').map(c => c.trim().replace(/^"/, '').replace(/"$/, ''));
+        const inputTokens = inputIdx >= 0 ? parseInt(cols[inputIdx], 10) || 0 : 0;
+        const outputTokens = outputIdx >= 0 ? parseInt(cols[outputIdx], 10) || 0 : 0;
+        const observedCostUsd = costIdx >= 0 ? parseFloat(cols[costIdx]) || 0 : 0;
+        const model = modelIdx >= 0 ? cols[modelIdx] : 'cursor-model';
+        await recordModelUsage({
+            id: `csv-${rowHash}`,
+            taskId: 'cursor-imported',
+            provider: 'cursor',
+            model,
+            inputTokens,
+            outputTokens,
+            observedCostUsd,
+            source: 'cursor-dashboard-csv',
+        }, cwd);
+        importedCount++;
+    }
+    return importedCount;
+}
+/**
+ * Import Cursor usage data from JSON format (e.g. from Cursor Admin API).
+ */
+export async function importCursorUsageJson(jsonData, cwd) {
+    const payload = jsonData;
+    const records = Array.isArray(jsonData)
+        ? jsonData
+        : (payload.records || payload.usage || [jsonData]);
+    let importedCount = 0;
+    for (const r of records) {
+        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',
+        }, 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.
+ */
+export async function fetchCursorUsageFromAdminApi(cwd) {
+    const 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;
+}
+/**
+ * Summarize agent scope overlap and governance rule overhead for Studio.
+ */
+export async function getContextScopeSummary(cwd) {
+    const projectRoot = cwd || process.cwd();
+    const sessionPath = path.join(projectRoot, '.rigour', 'agent-session.json');
+    let overlappingScopesResolved = 0;
+    const overlappingScopePairs = [];
+    let activeAgentCount = 0;
+    if (await fs.pathExists(sessionPath)) {
+        const session = await fs.readJson(sessionPath);
+        const agents = session.agents || [];
+        activeAgentCount = agents.length;
+        for (let i = 0; i < agents.length; i++) {
+            for (let j = i + 1; j < agents.length; j++) {
+                const overlaps = scopesOverlap(agents[i].taskScope || [], agents[j].taskScope || []);
+                if (overlaps.length > 0) {
+                    overlappingScopesResolved += overlaps.length;
+                    overlappingScopePairs.push(...overlaps);
+                }
+            }
+        }
+    }
+    let alwaysOnRuleTokens = 0;
+    for (const fileName of GOVERNANCE_RULE_FILES) {
+        const filePath = path.join(projectRoot, fileName);
+        if (await fs.pathExists(filePath)) {
+            alwaysOnRuleTokens += estimateTokenCount(await fs.readFile(filePath, 'utf8'));
+        }
+    }
+    const events = await getContextEvents(undefined, cwd);
+    const unusedToolsFiltered = events.filter(e => e.toolName.includes('filtered')).length;
+    return {
+        overlappingScopesResolved,
+        overlappingScopePairs: Array.from(new Set(overlappingScopePairs)),
+        alwaysOnRuleTokens,
+        unusedToolsFiltered,
+        activeAgentCount,
+    };
+}
+/**
+ * Aggregate checkpoint compression metrics for Studio.
+ */
+export async function getCheckpointSummary(taskId, cwd) {
+    const metrics = await getCheckpointMetrics(taskId, cwd);
+    if (metrics.length === 0) {
+        return {
+            rawStateTokens: 0,
+            checkpointTokens: 0,
+            compressionRatio: 0,
+            checkpointCount: 0,
+            replayTokensAvoided: 0,
+        };
+    }
+    const rawStateTokens = metrics.reduce((acc, m) => acc + (m.rawStateTokens || 0), 0);
+    const checkpointTokens = metrics.reduce((acc, m) => acc + (m.checkpointTokens || 0), 0);
+    const replayTokensAvoided = metrics.reduce((acc, m) => acc + (m.replayTokensAvoided || 0), 0);
+    const compressionRatio = checkpointTokens > 0 ? Math.round(rawStateTokens / checkpointTokens) : 0;
+    return {
+        rawStateTokens,
+        checkpointTokens,
+        compressionRatio,
+        checkpointCount: metrics.length,
+        replayTokensAvoided,
+    };
+}

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

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

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

@@ -0,0 +1,130 @@
+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 { getTaskContextStats, getTaskCostStats, getCacheStats, importCursorUsageCsv, importCursorUsageJson, getContextScopeSummary, getCheckpointSummary, estimateTokenCount, } from './context-telemetry-service.js';
+import { recordContextEvent, recordCheckpointMetric } from '../storage/context-telemetry.js';
+describe('context-telemetry-service', () => {
+    const testCwd = path.join(os.tmpdir(), `rigour-ctx-service-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const taskId = `task-${Date.now()}`;
+    beforeEach(async () => {
+        await fs.ensureDir(path.join(testCwd, '.rigour'));
+    });
+    afterEach(async () => {
+        await fs.remove(testCwd);
+    });
+    it('returns zeroed stats when no telemetry exists for task', async () => {
+        const stats = await getTaskContextStats(taskId, testCwd);
+        expect(stats.retrievals).toBe(0);
+        expect(stats.candidateTokens).toBe(0);
+        expect(stats.potentialAvoidedTokens).toBe(0);
+        expect(stats.isEstimated).toBe(true);
+    });
+    it('calculates avoided context from recorded events', async () => {
+        await recordContextEvent({
+            taskId,
+            toolName: 'rigour_check_pattern',
+            cacheStatus: 'exact-hit',
+            candidateTokens: 10000,
+            returnedTokens: 2000,
+            deduplicatedTokens: 3000,
+        }, testCwd);
+        const stats = await getTaskContextStats(taskId, testCwd);
+        expect(stats.retrievals).toBe(1);
+        expect(stats.potentialAvoidedTokens).toBe(8000);
+        expect(stats.repeatedReadsPrevented).toBeGreaterThan(0);
+        expect(stats.isEstimated).toBe(false);
+    });
+    it('aggregates cache performance from events', async () => {
+        const cacheTaskId = `${taskId}-cache`;
+        await recordContextEvent({
+            taskId: cacheTaskId,
+            toolName: 'rigour_recall',
+            cacheStatus: 'exact-hit',
+            candidateTokens: 1000,
+            returnedTokens: 200,
+        }, testCwd);
+        await recordContextEvent({
+            taskId: cacheTaskId,
+            toolName: 'rigour_context_explain',
+            cacheStatus: 'miss',
+            candidateTokens: 500,
+            returnedTokens: 500,
+        }, testCwd);
+        const events = await import('../storage/context-telemetry.js').then(m => m.getContextEvents(cacheTaskId, testCwd));
+        const cache = await getCacheStats(testCwd);
+        const taskHits = events.filter(e => e.cacheStatus === 'exact-hit').length;
+        const taskMisses = events.filter(e => e.cacheStatus === 'miss').length;
+        expect(taskHits).toBe(1);
+        expect(taskMisses).toBe(1);
+        expect(cache.hitRate).toBe(0.5);
+        expect(cache.isEstimated).toBe(false);
+    });
+    it('imports CSV usage and marks cost stats as observed', async () => {
+        const csv = `Date,Model,Input Tokens,Output Tokens,Cost
+2026-08-05,claude-3-5-sonnet,510000,62000,4.83`;
+        const imported = await importCursorUsageCsv(csv, testCwd);
+        expect(imported).toBe(1);
+        const cost = await getTaskCostStats('cursor-imported', testCwd);
+        expect(cost.actual.inputTokens).toBe(510000);
+        expect(cost.actual.costUsd).toBe(4.83);
+        expect(cost.actual.isEstimated).toBe(false);
+    });
+    it('deduplicates CSV rows on re-import', async () => {
+        const csv = `Date,Model,Input Tokens,Output Tokens,Cost
+2026-08-05,claude-3-5-sonnet,1000,100,1.00`;
+        expect(await importCursorUsageCsv(csv, testCwd)).toBe(1);
+        expect(await importCursorUsageCsv(csv, testCwd)).toBe(0);
+    });
+    it('imports JSON usage records', async () => {
+        const jsonTaskId = `${taskId}-json-${Math.random().toString(36).slice(2)}`;
+        const imported = await importCursorUsageJson([{
+                taskId: jsonTaskId,
+                inputTokens: 2500,
+                outputTokens: 300,
+                observedCostUsd: 0.42,
+                model: 'gpt-4o',
+            }], testCwd);
+        expect(imported).toBe(1);
+        const cost = await getTaskCostStats(jsonTaskId, testCwd);
+        expect(cost.actual.inputTokens).toBe(2500);
+    });
+    it('summarizes agent scope overlap from session file', async () => {
+        await fs.writeJson(path.join(testCwd, '.rigour', 'agent-session.json'), {
+            agents: [
+                { agentId: 'agent-a', taskScope: ['src/api/**'] },
+                { agentId: 'agent-b', taskScope: ['src/api/**', 'tests/**'] },
+            ],
+        });
+        const scope = await getContextScopeSummary(testCwd);
+        expect(scope.activeAgentCount).toBe(2);
+        expect(scope.overlappingScopesResolved).toBeGreaterThan(0);
+    });
+    it('estimates governance rule token overhead from AGENTS.md', async () => {
+        await fs.writeFile(path.join(testCwd, 'AGENTS.md'), '# Agent rules\n'.repeat(40));
+        const scope = await getContextScopeSummary(testCwd);
+        expect(scope.alwaysOnRuleTokens).toBe(estimateTokenCount('# Agent rules\n'.repeat(40)));
+    });
+    it('aggregates checkpoint compression metrics', async () => {
+        const cpTaskId = `${taskId}-cp`;
+        await recordCheckpointMetric({
+            checkpointId: `checkpoint:${cpTaskId}:a1:phase`,
+            taskId: cpTaskId,
+            agentId: 'a1',
+            rawStateTokens: 10000,
+            checkpointTokens: 500,
+            replayTokensAvoided: 9500,
+        }, testCwd);
+        const summary = await getCheckpointSummary(cpTaskId, testCwd);
+        expect(summary.checkpointCount).toBe(1);
+        expect(summary.rawStateTokens).toBe(10000);
+        expect(summary.compressionRatio).toBe(20);
+        expect(summary.replayTokensAvoided).toBe(9500);
+    });
+});

package/dist/settings.d.ts

@@ -33,6 +33,9 @@ export interface RigourSettings {
         colorOutput?: boolean;
         verboseOutput?: boolean;
     };
+    cursor?: {
+        apiKey?: string;
+    };
 }
 /**
  * Resolved deep options from CLI flags merged with settings.json
@@ -102,3 +105,11 @@ export declare function updateProviderKey(provider: string, apiKey: string): voi
  * Remove a provider key from settings
  */
 export declare function removeProviderKey(provider: string): void;
+/**
+ * Get Cursor Admin API key from settings
+ */
+export declare function getCursorApiKey(): string | undefined;
+/**
+ * Update Cursor Admin API key in settings
+ */
+export declare function updateCursorApiKey(apiKey: string): void;

package/dist/settings.js

@@ -184,3 +184,21 @@ export function removeProviderKey(provider) {
         saveSettings(settings);
     }
 }
+/**
+ * Get Cursor Admin API key from settings
+ */
+export function getCursorApiKey() {
+    const settings = loadSettings();
+    return settings.cursor?.apiKey;
+}
+/**
+ * Update Cursor Admin API key in settings
+ */
+export function updateCursorApiKey(apiKey) {
+    const settings = loadSettings();
+    if (!settings.cursor) {
+        settings.cursor = {};
+    }
+    settings.cursor.apiKey = apiKey;
+    saveSettings(settings);
+}