@rigour-labs/core 5.5.4 → 6.1.0-beta.1

package/dist/hooks/checker.d.ts

@@ -13,6 +13,8 @@ interface CheckerOptions {
     files: string[];
     timeout_ms?: number;
     block_on_failure?: boolean;
+    /** Bound writer identity — required when agent scopes are registered */
+    agentId?: string;
 }
 /**
  * Run fast gates on a set of files.

package/dist/hooks/checker.js

@@ -12,6 +12,7 @@ import path from 'path';
 import yaml from 'yaml';
 import { ConfigSchema } from '../types/index.js';
 import { scanInputForCredentials } from './input-validator.js';
+import { evaluateWriteScope, loadAgentScopesFromDisk } from '../firewall/scope-enforcement.js';
 const JS_TS_PATTERN = /\.(ts|tsx|js|jsx|mts|mjs)$/;
 /**
  * Check if a file matches any ignore pattern from rigour.yml.
@@ -92,14 +93,17 @@ function checkFile(content, relPath, cwd, config) {
  */
 export async function runHookChecker(options) {
     const start = Date.now();
-    const { cwd, files, timeout_ms = 5000 } = options;
+    const { cwd, files, timeout_ms = 5000, agentId } = options;
     const failures = [];
+    let timedOut = false;
     try {
         const config = await loadConfig(cwd);
         const deadline = start + timeout_ms;
         const ignorePatterns = config.ignore ?? [];
+        const agentScopes = await loadAgentScopesFromDisk(cwd);
         for (const filePath of files) {
             if (Date.now() > deadline) {
+                timedOut = true;
                 break;
             }
             const resolved = await resolveFile(filePath, cwd);
@@ -110,9 +114,29 @@ export async function runHookChecker(options) {
             if (isIgnored(resolved.relPath, ignorePatterns)) {
                 continue;
             }
+            if (agentScopes.length > 0) {
+                const scopeEv = evaluateWriteScope(cwd, resolved.relPath, agentScopes, agentId);
+                if (scopeEv.decision !== 'allow') {
+                    failures.push({
+                        gate: 'agent-scope',
+                        file: resolved.relPath,
+                        message: scopeEv.reason,
+                        severity: 'critical',
+                    });
+                    continue;
+                }
+            }
             const fileFailures = checkFile(resolved.content, resolved.relPath, cwd, config);
             failures.push(...fileFailures);
         }
+        if (timedOut) {
+            failures.push({
+                gate: 'hook-timeout',
+                file: '',
+                message: `Hook checker exceeded ${timeout_ms}ms before all files were scanned (fail-closed)`,
+                severity: 'critical',
+            });
+        }
         return {
             status: failures.length > 0 ? 'fail' : 'pass',
             failures,

package/dist/hooks/standalone-checker.js

@@ -89,7 +89,11 @@ async function main() {
         process.stdout.write(EMPTY_RESULT);
         return;
     }
-    const result = await runHookChecker({ cwd, files });
+    const result = await runHookChecker({
+        cwd,
+        files,
+        agentId: process.env.RIGOUR_AGENT_ID || undefined,
+    });
     process.stdout.write(JSON.stringify(result));
     if (result.status === 'fail') {
         logFailures(result.failures);

package/dist/hooks/templates.js

@@ -82,6 +82,7 @@ process.stdin.on('end', async () => {
         const result = await runHookChecker({
             cwd: process.cwd(),
             files: [payload.file_path],
+            agentId: process.env.RIGOUR_AGENT_ID || undefined,
         });
 
         // Write result to stdout for Cursor to consume
@@ -148,6 +149,7 @@ process.stdin.on('end', async () => {
         const result = await runHookChecker({
             cwd: process.cwd(),
             files: [filePath],
+            agentId: process.env.RIGOUR_AGENT_ID || undefined,
         });
 
         if (result.status === 'fail') {
@@ -206,6 +208,7 @@ process.stdin.on('end', async () => {
         const result = await runHookChecker({
             cwd: process.cwd(),
             files: [payload.file_path],
+            agentId: process.env.RIGOUR_AGENT_ID || undefined,
         });
 
         if (result.status === 'fail') {

package/dist/index.d.ts

@@ -24,6 +24,10 @@ export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, rese
 export type { RigourDB, CompactResult } from './storage/index.js';
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
 export type { ProjectStats } from './storage/index.js';
+export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId } from './storage/index.js';
+export type { ApplicableLessons, InteractionEvidence, LessonRecord, LessonState, LessonVisibility } from './storage/index.js';
+export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './storage/index.js';
+export type { TeamConfiguration, TeamSemanticConfiguration, TeamModeStatus, TeamDoctorResult, SemanticKnowledgeCandidate, SemanticKnowledgeResult, } from './storage/index.js';
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
 export type { TemporalDriftReport, ProvenanceStream, MonthlyBucket, WeeklyBucket, DriftDirection } from './services/temporal-drift.js';
 export { getProvenanceTrends, getQualityTrend } from './services/adaptive-thresholds.js';
@@ -35,5 +39,11 @@ export type { RenderOptions, GateResult } from './services/terminal-renderer.js'
 export * from './context/cache-engine.js';
 export * from './context/context-session.js';
 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/system-health.js';
+export * from './services/agent-history.js';
+export * from './services/engineering-knowledge-graph.js';
+export * from './firewall/index.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';

package/dist/index.js

@@ -24,6 +24,8 @@ export { extractFacts, factsToPromptString } from './deep/fact-extractor.js';
 export { openDatabase, isSQLiteAvailable, compactDatabase, getDatabaseSize, resetDatabase, insertScan, insertFindings, getRecentScans, getScoreTrendFromDB, getTopIssues, reinforcePattern, getStrongPatterns } from './storage/index.js';
 // Local Project Memory (hybrid intelligence — SQLite-backed per-project learning)
 export { checkLocalPatterns, persistAndReinforce, getProjectStats } from './storage/index.js';
+export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId } from './storage/index.js';
+export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './storage/index.js';
 // Temporal Drift Engine (v5 — cross-session trend analysis + per-provenance EWMA)
 export { generateTemporalDriftReport, formatDriftSummary } from './services/temporal-drift.js';
 // Adaptive Thresholds (v5 — Z-score + per-provenance trends)
@@ -36,7 +38,13 @@ export { renderScoreGauge, renderSeveritySection, renderGateGrid, renderBrainSta
 export * from './context/cache-engine.js';
 export * from './context/context-session.js';
 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/system-health.js';
+export * from './services/agent-history.js';
+export * from './services/engineering-knowledge-graph.js';
+export * from './firewall/index.js';
 export { recordContextEvent, recordModelUsage, recordCheckpointMetric, getContextEvents, getModelUsages, getCheckpointMetrics, } from './storage/index.js';
 // Pattern Index is intentionally NOT exported here to prevent
 // native dependency issues (sharp/transformers) from leaking into

package/dist/pattern-index/embeddings.js

@@ -7,6 +7,7 @@
  * Singleton for the embedding pipeline to avoid re-loading the model.
  */
 let embeddingPipeline = null;
+let embeddingUnavailable = false;
 /**
  * Get or initialize the embedding pipeline.
  */
@@ -21,6 +22,8 @@ async function getPipeline() {
             return { data: new Float32Array(vector) };
         };
     }
+    if (embeddingUnavailable)
+        return null;
     if (!embeddingPipeline) {
         try {
             // Dynamic import to isolate native dependency issues (like sharp)
@@ -29,8 +32,9 @@ async function getPipeline() {
             embeddingPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
         }
         catch (error) {
-            console.error('Failed to initialize embedding pipeline:', error);
-            throw error;
+            embeddingUnavailable = true;
+            console.warn('Semantic enrichment is degraded; structural and text retrieval remain available.');
+            return null;
         }
     }
     return embeddingPipeline;
@@ -41,11 +45,14 @@ async function getPipeline() {
 export async function generateEmbedding(text) {
     try {
         const extractor = await getPipeline();
+        if (!extractor)
+            return [];
         const output = await extractor(text, { pooling: 'mean', normalize: true });
         return Array.from(output.data);
     }
     catch (error) {
-        console.warn('Semantic reasoning disabled: Embedding generation failed.', error);
+        embeddingUnavailable = true;
+        console.warn('Semantic enrichment is degraded; structural and text retrieval remain available.');
         return [];
     }
 }

package/dist/pattern-index/indexer.d.ts

@@ -15,6 +15,8 @@ export declare class PatternIndexer {
     constructor(rootDir: string, config?: Partial<PatternIndexConfig>);
     buildIndex(): Promise<PatternIndex>;
     updateIndex(existingIndex: PatternIndex): Promise<PatternIndex>;
+    updateFiles(existingIndex: PatternIndex, changedFiles: string[]): Promise<PatternIndex>;
+    enrichIndex(existingIndex: PatternIndex): Promise<PatternIndex>;
     private findFiles;
     private extractPatterns;
     private getScriptKind;

package/dist/pattern-index/indexer.js

@@ -12,6 +12,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { globby } from 'globby';
 import ts from 'typescript';
+import micromatch from 'micromatch';
 import { generateEmbedding } from './embeddings.js';
 import { hashContent } from './indexer-helpers.js';
 import { extractGoPatterns, extractRustPatterns, extractJVMStylePatterns, extractPythonPatterns, extractGenericCPatterns, } from './indexer-lang.js';
@@ -156,6 +157,77 @@ export class PatternIndexer {
             files: updatedFiles,
         };
     }
+    async updateFiles(existingIndex, changedFiles) {
+        const startTime = Date.now();
+        const root = path.resolve(this.rootDir);
+        const changed = new Set(changedFiles.flatMap(file => {
+            const absolute = path.resolve(root, file);
+            const relative = path.relative(root, absolute);
+            if (!relative || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+                return [];
+            return [relative.split(path.sep).join('/')];
+        }));
+        const patterns = existingIndex.patterns.filter(pattern => !changed.has(pattern.file));
+        const files = existingIndex.files.filter(file => !changed.has(file.path));
+        for (const relativePath of changed) {
+            const absolutePath = path.join(root, relativePath);
+            const supported = this.config.extensions.includes(path.extname(relativePath).toLowerCase());
+            const included = micromatch.isMatch(relativePath.replace(/\\/g, '/'), this.config.include, { dot: false });
+            const excluded = micromatch.isMatch(relativePath.replace(/\\/g, '/'), this.config.exclude, { dot: true });
+            if (!supported || !included || excluded)
+                continue;
+            try {
+                const content = await fs.readFile(absolutePath, 'utf-8');
+                const filePatterns = await this.extractPatterns(absolutePath, content);
+                if (this.config.useEmbeddings) {
+                    await Promise.all(filePatterns.map(async (pattern) => {
+                        pattern.embedding = await generateEmbedding(`${pattern.name} ${pattern.type} ${pattern.description}`);
+                    }));
+                }
+                patterns.push(...filePatterns);
+                files.push({
+                    path: relativePath,
+                    hash: hashContent(content),
+                    patternCount: filePatterns.length,
+                    indexedAt: new Date().toISOString(),
+                });
+            }
+            catch (error) {
+                if (error?.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return {
+            version: INDEX_VERSION,
+            lastUpdated: new Date().toISOString(),
+            rootDir: this.rootDir,
+            patterns,
+            files,
+            stats: this.calculateStats(patterns, files, Date.now() - startTime),
+        };
+    }
+    async enrichIndex(existingIndex) {
+        const startTime = Date.now();
+        const patterns = existingIndex.patterns.map(pattern => ({ ...pattern }));
+        const pending = patterns.filter(pattern => !pattern.embedding?.length);
+        if (pending.length > 0) {
+            pending[0].embedding = await generateEmbedding(`${pending[0].name} ${pending[0].type} ${pending[0].description}`);
+            if (!pending[0].embedding.length)
+                return existingIndex;
+        }
+        const batchSize = 10;
+        for (let i = 1; i < pending.length; i += batchSize) {
+            await Promise.all(pending.slice(i, i + batchSize).map(async (pattern) => {
+                pattern.embedding = await generateEmbedding(`${pattern.name} ${pattern.type} ${pattern.description}`);
+            }));
+        }
+        return {
+            ...existingIndex,
+            lastUpdated: new Date().toISOString(),
+            patterns,
+            stats: this.calculateStats(patterns, existingIndex.files, Date.now() - startTime),
+        };
+    }
     // -------------------------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------------------------

package/dist/services/agent-history.d.ts

@@ -0,0 +1,76 @@
+export type AgentEventOutcome = 'success' | 'error' | 'rejected' | 'unknown';
+export interface AgentGuidance {
+    kind: 'context-scope' | 'pattern' | 'memory';
+    recommendation: string;
+    patternRefs: Array<{
+        id: string;
+        label: string;
+        file?: string;
+    }>;
+    lessonRefs: Array<{
+        id: string;
+        label: string;
+        visibility?: string;
+    }>;
+    memoryRefs: Array<{
+        id: string;
+        label: string;
+    }>;
+    selectedFiles: string[];
+    excludedFileCount: number;
+    conflicts: number;
+}
+export interface AgentImpact {
+    guidanceCount: number;
+    knowledgeItems: number;
+    candidateTokens: number;
+    returnedTokens: number;
+    avoidedTokens: number;
+    candidateFiles: number;
+    returnedFiles: number;
+    excludedFiles: number;
+    cacheHits: number;
+    recommendations: string[];
+}
+export interface AgentHistoryEvent {
+    id: string;
+    timestamp: string;
+    type: string;
+    agentId: string;
+    taskId?: string;
+    sessionId?: string;
+    requestId?: string;
+    tool?: string;
+    outcome: AgentEventOutcome;
+    files: string[];
+    summary: string;
+    guidance?: AgentGuidance;
+    telemetry?: {
+        candidateTokens: number;
+        returnedTokens: number;
+        candidateFiles: number;
+        returnedFiles: number;
+        cacheStatus: string;
+        classification: 'observed' | 'measured estimate' | 'modelled estimate';
+    };
+}
+export interface AgentRun {
+    id: string;
+    agentId: string;
+    taskId?: string;
+    sessionId?: string;
+    startedAt: string;
+    endedAt: string;
+    status: AgentEventOutcome | 'active';
+    eventCount: number;
+    files: string[];
+    tools: string[];
+    impact?: AgentImpact;
+}
+export declare function normalizeAgentEvent(input: unknown, index?: number): AgentHistoryEvent;
+/**
+ * Normalizes a page as a unit so a response inherits identity and scope from its
+ * matching request. Older event logs often stored those fields only on tool_call.
+ */
+export declare function normalizeAgentEvents(inputs: unknown[]): AgentHistoryEvent[];
+export declare function buildAgentRuns(events: AgentHistoryEvent[]): AgentRun[];

package/dist/services/agent-history.js

@@ -0,0 +1,201 @@
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function validDate(value) {
+    const candidate = text(value);
+    return candidate && !Number.isNaN(Date.parse(candidate)) ? candidate : new Date(0).toISOString();
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.length > 0) : [];
+}
+function number(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function refs(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap(item => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const record = item;
+        const id = text(record.id);
+        const label = text(record.label);
+        return id && label ? [{ id, label, file: text(record.file), visibility: text(record.visibility) }] : [];
+    });
+}
+function eventGuidance(event) {
+    const value = event.guidance ?? event._guidance;
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const recommendation = text(record.recommendation);
+    const kind = text(record.kind);
+    if (!recommendation || !['context-scope', 'pattern', 'memory'].includes(kind ?? ''))
+        return undefined;
+    return {
+        kind: kind,
+        recommendation,
+        patternRefs: refs(record.patternRefs),
+        lessonRefs: refs(record.lessonRefs),
+        memoryRefs: refs(record.memoryRefs),
+        selectedFiles: strings(record.selectedFiles),
+        excludedFileCount: number(record.excludedFileCount),
+        conflicts: number(record.conflicts),
+    };
+}
+function eventTelemetry(event) {
+    const value = event.telemetry ?? event._telemetry;
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const classification = text(record.classification);
+    return {
+        candidateTokens: number(record.candidateTokens),
+        returnedTokens: number(record.returnedTokens),
+        candidateFiles: number(record.candidateFiles),
+        returnedFiles: number(record.returnedFiles),
+        cacheStatus: text(record.cacheStatus) ?? 'none',
+        classification: classification === 'observed' || classification === 'modelled estimate'
+            ? classification
+            : 'measured estimate',
+    };
+}
+function emptyImpact() {
+    return {
+        guidanceCount: 0,
+        knowledgeItems: 0,
+        candidateTokens: 0,
+        returnedTokens: 0,
+        avoidedTokens: 0,
+        candidateFiles: 0,
+        returnedFiles: 0,
+        excludedFiles: 0,
+        cacheHits: 0,
+        recommendations: [],
+    };
+}
+function eventFiles(event) {
+    const args = event.arguments && typeof event.arguments === 'object' ? event.arguments : {};
+    const report = event._rigour_report && typeof event._rigour_report === 'object'
+        ? event._rigour_report
+        : {};
+    const failures = Array.isArray(report.failures) ? report.failures : [];
+    const reported = failures.flatMap((failure) => failure && typeof failure === 'object'
+        ? strings(failure.files)
+        : []);
+    return [...new Set([
+            ...strings(event.files),
+            ...strings(args.files),
+            ...reported,
+            text(event.file),
+            text(event.path),
+        ].filter((file) => Boolean(file)))];
+}
+function eventOutcome(event) {
+    const value = String(event.outcome ?? event.status ?? '').toLowerCase();
+    const type = String(event.type ?? '').toLowerCase();
+    if (value.includes('reject') || type.includes('reject') || type.includes('deny'))
+        return 'rejected';
+    if (value.includes('error') || value.includes('fail') || type.includes('error') || type.includes('fail'))
+        return 'error';
+    if (value.includes('success') || value === 'pass' || type.includes('success') || type.includes('completed'))
+        return 'success';
+    return 'unknown';
+}
+export function normalizeAgentEvent(input, index = 0) {
+    const event = input && typeof input === 'object' ? input : {};
+    const type = text(event.type) ?? 'unknown';
+    const tool = text(event.tool ?? event.toolName);
+    const outcome = eventOutcome(event);
+    const summary = text(event.summary ?? event.message ?? event.description)
+        ?? `${tool ?? type}${outcome === 'unknown' ? '' : ` · ${outcome}`}`;
+    return {
+        id: text(event.id) ?? text(event.requestId) ?? `legacy-event-${index + 1}`,
+        timestamp: validDate(event.timestamp ?? event.createdAt),
+        type,
+        agentId: text(event.agentId ?? event.agent_id) ?? 'unknown-agent',
+        taskId: text(event.taskId ?? event.task_id),
+        sessionId: text(event.sessionId ?? event.session_id),
+        requestId: text(event.requestId ?? event.request_id),
+        tool,
+        outcome,
+        files: eventFiles(event),
+        summary,
+        guidance: eventGuidance(event),
+        telemetry: eventTelemetry(event),
+    };
+}
+/**
+ * Normalizes a page as a unit so a response inherits identity and scope from its
+ * matching request. Older event logs often stored those fields only on tool_call.
+ */
+export function normalizeAgentEvents(inputs) {
+    const requestContext = new Map();
+    for (const input of inputs) {
+        const event = input && typeof input === 'object' ? input : {};
+        const requestId = text(event.requestId ?? event.request_id);
+        if (!requestId || String(event.type) !== 'tool_call')
+            continue;
+        const args = event.arguments && typeof event.arguments === 'object'
+            ? event.arguments
+            : {};
+        requestContext.set(requestId, {
+            agentId: event.agentId ?? event.agent_id ?? args.agentId ?? args.agent_id ?? args.agent
+                ?? args.fromAgentId ?? args.toAgentId,
+            taskId: event.taskId ?? event.task_id ?? args.taskId ?? args.task_id,
+            sessionId: event.sessionId ?? event.session_id ?? args.sessionId ?? args.session_id,
+            files: event.files ?? args.files ?? args.filesChanged ?? args.filesInScope,
+        });
+    }
+    return inputs.map((input, index) => {
+        const event = input && typeof input === 'object' ? input : {};
+        const requestId = text(event.requestId ?? event.request_id);
+        return normalizeAgentEvent(requestId ? { ...requestContext.get(requestId), ...event } : event, index);
+    });
+}
+export function buildAgentRuns(events) {
+    const runs = new Map();
+    for (const event of [...events].sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))) {
+        const day = event.timestamp.slice(0, 10);
+        const id = event.sessionId ?? event.taskId ?? event.requestId ?? `${event.agentId}:${day}`;
+        const current = runs.get(id) ?? {
+            id,
+            agentId: event.agentId,
+            taskId: event.taskId,
+            sessionId: event.sessionId,
+            startedAt: event.timestamp,
+            endedAt: event.timestamp,
+            status: 'active',
+            eventCount: 0,
+            files: [],
+            tools: [],
+            impact: emptyImpact(),
+        };
+        current.endedAt = event.timestamp;
+        current.eventCount++;
+        current.files = [...new Set([...current.files, ...event.files])];
+        if (event.tool)
+            current.tools = [...new Set([...current.tools, event.tool])];
+        if (event.guidance) {
+            current.impact ??= emptyImpact();
+            const telemetry = event.telemetry;
+            current.impact.guidanceCount++;
+            current.impact.knowledgeItems += event.guidance.patternRefs.length
+                + event.guidance.lessonRefs.length
+                + event.guidance.memoryRefs.length;
+            current.impact.candidateTokens += telemetry?.candidateTokens ?? 0;
+            current.impact.returnedTokens += telemetry?.returnedTokens ?? 0;
+            current.impact.avoidedTokens += Math.max(0, (telemetry?.candidateTokens ?? 0) - (telemetry?.returnedTokens ?? 0));
+            current.impact.candidateFiles += telemetry?.candidateFiles ?? 0;
+            current.impact.returnedFiles += telemetry?.returnedFiles ?? 0;
+            current.impact.excludedFiles += event.guidance.excludedFileCount;
+            if (telemetry?.cacheStatus && !['none', 'miss'].includes(telemetry.cacheStatus))
+                current.impact.cacheHits++;
+            current.impact.recommendations = [...new Set([...current.impact.recommendations, event.guidance.recommendation])];
+        }
+        if (event.outcome !== 'unknown')
+            current.status = event.outcome;
+        runs.set(id, current);
+    }
+    return [...runs.values()].sort((a, b) => Date.parse(b.endedAt) - Date.parse(a.endedAt));
+}

package/dist/services/agent-history.test.d.ts

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

package/dist/services/agent-history.test.js

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { buildAgentRuns, normalizeAgentEvent, normalizeAgentEvents } from './agent-history.js';
+describe('agent history', () => {
+    it('normalizes incomplete historical records without dropping them', () => {
+        const event = normalizeAgentEvent({ type: 'tool_error', arguments: { files: ['src/a.ts'] } });
+        expect(event.agentId).toBe('unknown-agent');
+        expect(event.outcome).toBe('error');
+        expect(event.files).toEqual(['src/a.ts']);
+    });
+    it('groups events into stable runs and retains outcomes', () => {
+        const events = [
+            normalizeAgentEvent({ id: '1', sessionId: 's1', agentId: 'a1', timestamp: '2026-01-01T00:00:00Z', tool: 'read' }),
+            normalizeAgentEvent({ id: '2', sessionId: 's1', agentId: 'a1', timestamp: '2026-01-01T00:01:00Z', type: 'completed', files: ['src/a.ts'] }),
+        ];
+        expect(buildAgentRuns(events)).toMatchObject([{ id: 's1', eventCount: 2, status: 'success', files: ['src/a.ts'] }]);
+    });
+    it('normalizes guidance safely and builds an honest impact receipt', () => {
+        const events = [normalizeAgentEvent({
+                id: 'response-1', requestId: 'request-1', agentId: 'agent-1', timestamp: '2026-01-01T00:00:00Z',
+                type: 'tool_response', status: 'success',
+                guidance: {
+                    kind: 'context-scope',
+                    recommendation: 'Read only the two evidence-backed files.',
+                    patternRefs: [{ id: 'p1', label: 'withTransaction' }, { bad: true }],
+                    lessonRefs: [{ id: 'l1', label: 'Bound retries' }],
+                    selectedFiles: ['src/a.ts', 42],
+                    excludedFileCount: 18,
+                },
+                telemetry: {
+                    candidateTokens: 2400,
+                    returnedTokens: 400,
+                    candidateFiles: 20,
+                    returnedFiles: 2,
+                    cacheStatus: 'exact-hit',
+                    classification: 'measured estimate',
+                },
+            })];
+        expect(events[0].guidance?.selectedFiles).toEqual(['src/a.ts']);
+        expect(buildAgentRuns(events)[0].impact).toMatchObject({
+            guidanceCount: 1,
+            knowledgeItems: 2,
+            avoidedTokens: 2000,
+            excludedFiles: 18,
+            cacheHits: 1,
+        });
+    });
+    it('ignores malformed guidance rather than breaking legacy history', () => {
+        const event = normalizeAgentEvent({ guidance: { kind: 'context-scope', recommendation: 42 }, telemetry: 'bad' });
+        expect(event.guidance).toBeUndefined();
+        expect(event.telemetry).toBeUndefined();
+    });
+});
+describe('normalizeAgentEvents', () => {
+    it('carries request identity into the matching response', () => {
+        const events = normalizeAgentEvents([
+            {
+                type: 'tool_call', requestId: 'request-1', tool: 'rigour_checkpoint',
+                timestamp: '2026-09-10T00:00:00Z',
+                arguments: { agentId: 'agent-a', taskId: 'task-a', filesChanged: ['src/a.ts'] },
+            },
+            {
+                type: 'tool_response', requestId: 'request-1', tool: 'rigour_checkpoint', status: 'success',
+                timestamp: '2026-09-10T00:00:01Z',
+            },
+        ]);
+        expect(events[1]).toMatchObject({ agentId: 'agent-a', taskId: 'task-a', files: ['src/a.ts'] });
+        expect(buildAgentRuns(events)).toHaveLength(1);
+    });
+});