@rigour-labs/core 6.4.3 → 6.4.4

package/dist/index.d.ts

@@ -52,6 +52,7 @@ export * from './context/index-bridge.js';
 export * from './context/automatic-index.js';
 export * from './context/dependency-graph.js';
 export * from './services/context-telemetry-service.js';
+export * from './services/observed-savings.js';
 export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';

package/dist/index.js

@@ -51,6 +51,7 @@ export * from './context/index-bridge.js';
 export * from './context/automatic-index.js';
 export * from './context/dependency-graph.js';
 export * from './services/context-telemetry-service.js';
+export * from './services/observed-savings.js';
 export * from './services/system-health.js';
 export * from './services/agent-history.js';
 export * from './services/engineering-knowledge-graph.js';

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

@@ -3,6 +3,7 @@
  * Calculates exact observed usage, avoided tokens, cache performance, and cost breakdowns.
  * Supports CSV/JSON Cursor usage imports.
  */
+import { type ObservedSavings } from './observed-savings.js';
 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;
@@ -57,6 +58,14 @@ export interface TaskCostStats {
         pricingSource: string;
         pricingEffectiveDate: string;
     };
+    /**
+     * Measured, not modelled: scoped files the agent's hook saw it never read,
+     * less the summaries it read instead. Only scopes followed by observed agent
+     * activity count (trackedScopes); the estimate above is an upper bound.
+     */
+    observed: ObservedSavings & {
+        avoidedCostUsd: number;
+    };
 }
 export interface CachePerformanceStats {
     exactCacheHits: number;

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

@@ -4,6 +4,7 @@
  * Supports CSV/JSON Cursor usage imports.
  */
 import { createHash } from 'crypto';
+import { observedSavings } from './observed-savings.js';
 import fs from 'fs-extra';
 import path from 'path';
 import { getContextEvents, getModelUsages, getCheckpointMetrics, recordModelUsage, } from '../storage/index.js';
@@ -110,6 +111,8 @@ export async function getTaskCostStats(taskId, cwd) {
         actualPricingBasis = 'observed-cursor-charged-cents';
     }
     const retrievalPricing = estimateAvoidedContextCostUsd(stats.potentialAvoidedTokens, usages);
+    const observed = observedSavings(cwd ?? process.cwd());
+    const observedPricing = estimateAvoidedContextCostUsd(observed.avoidedTokens, usages);
     const checkpointPricing = estimateAvoidedContextCostUsd(stats.checkpointReplayAvoided, usages);
     const unknownPricing = retrievalPricing.pricing.pricingBasis.includes('fallback');
     const range = (tokens) => ({
@@ -150,6 +153,7 @@ export async function getTaskCostStats(taskId, cwd) {
             pricingSource: MODEL_PRICING_SOURCE,
             pricingEffectiveDate: MODEL_PRICING_EFFECTIVE_DATE,
         },
+        observed: { ...observed, avoidedCostUsd: observedPricing.costUsd },
     };
 }
 /**

package/dist/services/observed-savings.d.ts

@@ -0,0 +1,36 @@
+export declare const OBSERVATION_WINDOW_MS: number;
+export interface ScopeOffer {
+    ts: number;
+    files: Array<{
+        path: string;
+        tokens: number;
+    }>;
+    summaryTokens: number;
+}
+export interface AgentActivity {
+    ts: number;
+    tool: string;
+    path?: string;
+}
+export interface ObservedSavings {
+    scopes: number;
+    /** Scopes followed by agent activity the hook saw: the only ones measured. */
+    trackedScopes: number;
+    offeredTokens: number;
+    /** Tokens of scoped files the agent read anyway. */
+    readBackTokens: number;
+    /** Tokens of scoped files never read, less the summaries, over tracked scopes. */
+    avoidedTokens: number;
+}
+export declare function recordScopeOffer(cwd: string, files: Array<{
+    path: string;
+    tokens: number;
+}>, summaryTokens: number, ts?: number): void;
+/** One tool call an agent hook saw. Read-like tools carry the file they read. */
+export declare function recordAgentActivity(cwd: string, tool: string, filePath?: string, ts?: number): void;
+/**
+ * A hook payload for one agent tool call (Claude Code PreToolUse sends tool_name,
+ * tool_input and cwd); anything else is ignored.
+ */
+export declare function recordHookPayload(payload: unknown, fallbackCwd: string, ts?: number): void;
+export declare function observedSavings(cwd: string, windowMs?: number): ObservedSavings;

package/dist/services/observed-savings.js

@@ -0,0 +1,94 @@
+/**
+ * Observed context savings: tokens an agent did not read because Rigour scoped its context.
+ *
+ * The estimate in context telemetry assumes the agent would otherwise read every
+ * scoped file whole, and does not read them afterwards anyway. Neither is
+ * measured. Here both sides are observed:
+ *
+ *   .rigour/context-scopes.jsonl   files rigour_context_scope summarised, with their tokens
+ *   .rigour/agent-activity.jsonl   every tool call the agent's hook saw (and the file it read)
+ *
+ * A scope is tracked when the hook recorded any agent activity after it, so
+ * "the agent read nothing" is told apart from "no hook is installed". For a
+ * tracked scope, the saving is the tokens of scoped files the agent did not
+ * read within the window, less the summary it read instead.
+ */
+import fs from 'fs';
+import path from 'path';
+const SCOPES = 'context-scopes.jsonl';
+const ACTIVITY = 'agent-activity.jsonl';
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+export const OBSERVATION_WINDOW_MS = 30 * 60 * 1000;
+const READ_TOOLS = /^(?:read|read_file|readfile|view|open_file|cat)$/i;
+export function recordScopeOffer(cwd, files, summaryTokens, ts = Date.now()) {
+    append(cwd, SCOPES, { ts, files: files.map(f => ({ path: normalize(cwd, f.path), tokens: f.tokens })), summaryTokens });
+}
+/** One tool call an agent hook saw. Read-like tools carry the file they read. */
+export function recordAgentActivity(cwd, tool, filePath, ts = Date.now()) {
+    const entry = { ts, tool };
+    if (filePath && READ_TOOLS.test(tool))
+        entry.path = normalize(cwd, filePath);
+    append(cwd, ACTIVITY, entry);
+}
+/**
+ * A hook payload for one agent tool call (Claude Code PreToolUse sends tool_name,
+ * tool_input and cwd); anything else is ignored.
+ */
+export function recordHookPayload(payload, fallbackCwd, ts = Date.now()) {
+    const event = payload;
+    if (!event || typeof event.tool_name !== 'string')
+        return;
+    const input = event.tool_input ?? {};
+    const file = [input.file_path, input.path, input.target_file].find((v) => typeof v === 'string');
+    recordAgentActivity(typeof event.cwd === 'string' ? event.cwd : fallbackCwd, event.tool_name, file, ts);
+}
+export function observedSavings(cwd, windowMs = OBSERVATION_WINDOW_MS) {
+    const scopes = readLog(cwd, SCOPES);
+    const activity = readLog(cwd, ACTIVITY).sort((a, b) => a.ts - b.ts);
+    const result = { scopes: scopes.length, trackedScopes: 0, offeredTokens: 0, readBackTokens: 0, avoidedTokens: 0 };
+    for (const scope of scopes) {
+        const after = activity.filter(a => a.ts >= scope.ts && a.ts <= scope.ts + windowMs);
+        if (after.length === 0)
+            continue;
+        result.trackedScopes++;
+        const read = new Set(after.filter(a => a.path).map(a => a.path));
+        const offered = scope.files.reduce((sum, f) => sum + f.tokens, 0);
+        const readBack = scope.files.filter(f => read.has(f.path)).reduce((sum, f) => sum + f.tokens, 0);
+        result.offeredTokens += offered;
+        result.readBackTokens += readBack;
+        result.avoidedTokens += Math.max(0, offered - readBack - scope.summaryTokens);
+    }
+    return result;
+}
+function normalize(cwd, file) {
+    return path.relative(cwd, path.resolve(cwd, file)).split(path.sep).join('/');
+}
+function append(cwd, name, entry) {
+    try {
+        const dir = path.join(cwd, '.rigour');
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, name);
+        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        if (fs.statSync(file).size > MAX_LOG_BYTES) {
+            const lines = fs.readFileSync(file, 'utf8').trimEnd().split('\n');
+            fs.writeFileSync(file, lines.slice(Math.floor(lines.length / 2)).join('\n') + '\n');
+        }
+    }
+    catch {
+        // Measurement must never break the agent's tool call.
+    }
+}
+function readLog(cwd, name) {
+    try {
+        return fs.readFileSync(path.join(cwd, '.rigour', name), 'utf8').split('\n').filter(Boolean)
+            .flatMap(line => { try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        } });
+    }
+    catch {
+        return [];
+    }
+}

package/dist/services/observed-savings.test.d.ts

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

package/dist/services/observed-savings.test.js

@@ -0,0 +1,37 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { observedSavings, recordAgentActivity, recordHookPayload, recordScopeOffer } from './observed-savings.js';
+let cwd;
+beforeEach(() => { cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'observed-savings-')); });
+afterEach(() => { fs.rmSync(cwd, { recursive: true, force: true }); });
+const T = 1_000_000;
+describe('observedSavings', () => {
+    it('counts only scoped files the agent did not read afterwards, less the summary', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }, { path: 'src/b.ts', tokens: 2000 }], 400, T);
+        recordAgentActivity(cwd, 'Read', path.join(cwd, 'src/a.ts'), T + 60_000); // read anyway
+        recordAgentActivity(cwd, 'Edit', path.join(cwd, 'src/b.ts'), T + 90_000); // an edit is not a read
+        expect(observedSavings(cwd)).toEqual({ scopes: 1, trackedScopes: 1, offeredTokens: 5000, readBackTokens: 3000, avoidedTokens: 1600 });
+    });
+    it('claims nothing for a scope no hook observed, so a missing hook never reads as a saving', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }], 400, T);
+        expect(observedSavings(cwd)).toMatchObject({ scopes: 1, trackedScopes: 0, avoidedTokens: 0 });
+    });
+    it('ignores activity outside the observation window', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }], 400, T);
+        recordAgentActivity(cwd, 'Read', 'src/a.ts', T + 2 * 60 * 60 * 1000);
+        expect(observedSavings(cwd).trackedScopes).toBe(0);
+    });
+    it('never claims more than was offered when the summary outweighs unread files', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 100 }], 400, T);
+        recordAgentActivity(cwd, 'Grep', undefined, T + 1000);
+        expect(observedSavings(cwd).avoidedTokens).toBe(0);
+    });
+    it('reads a Claude Code PreToolUse payload: the tool, the file it reads, and its working directory', () => {
+        recordScopeOffer(cwd, [{ path: 'src/a.ts', tokens: 3000 }], 400, T);
+        recordHookPayload({ tool_name: 'Read', tool_input: { file_path: path.join(cwd, 'src/a.ts') }, cwd }, '/elsewhere', T + 1000);
+        recordHookPayload({ hello: 'not a tool call' }, cwd, T + 2000);
+        expect(observedSavings(cwd)).toMatchObject({ trackedScopes: 1, readBackTokens: 3000, avoidedTokens: 0 });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigour-labs/core",
-  "version": "6.4.3",
+  "version": "6.4.4",
   "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#.",
   "engines": {
     "node": ">=22"
@@ -70,11 +70,11 @@
     "pg": "^8.16.3",
     "sqlite3": "^5.1.7",
     "openai": "^4.104.0",
-    "@rigour-labs/brain-darwin-x64": "6.4.3",
-    "@rigour-labs/brain-darwin-arm64": "6.4.3",
-    "@rigour-labs/brain-linux-arm64": "6.4.3",
-    "@rigour-labs/brain-linux-x64": "6.4.3",
-    "@rigour-labs/brain-win-x64": "6.4.3"
+    "@rigour-labs/brain-darwin-arm64": "6.4.4",
+    "@rigour-labs/brain-linux-arm64": "6.4.4",
+    "@rigour-labs/brain-win-x64": "6.4.4",
+    "@rigour-labs/brain-linux-x64": "6.4.4",
+    "@rigour-labs/brain-darwin-x64": "6.4.4"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",