agentic-qe 3.8.14 → 3.9.1

package/dist/kernel/hnsw-shadow-validator.js

@@ -0,0 +1,139 @@
+/**
+ * HNSW Shadow Validator (ADR-071 Phase 2C)
+ *
+ * Runs search queries against both the old HNSW implementation (brute-force
+ * or InMemoryHNSWIndex) and the unified HnswAdapter backend, then compares
+ * results to detect divergences before fully decommissioning old code.
+ *
+ * Use HnswShadowValidator.validate() to run a batch of queries and get a
+ * divergence report. A divergence rate <2% is the go-criteria for enabling
+ * the useUnifiedHnsw flag.
+ *
+ * @module kernel/hnsw-shadow-validator
+ */
+import { cosineSimilarity } from '../shared/utils/vector-math.js';
+// ============================================================================
+// Brute-Force Reference Implementation
+// ============================================================================
+/**
+ * Simple brute-force cosine search used as ground-truth reference.
+ * O(n) per query — accurate but slow.
+ */
+function bruteForceSearch(vectors, query, k) {
+    const scored = [];
+    for (const [id, vec] of vectors) {
+        scored.push({ id, score: cosineSimilarity(query, vec) });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, k);
+}
+// ============================================================================
+// Shadow Validator
+// ============================================================================
+/**
+ * Validates that the unified HnswAdapter produces results consistent
+ * with a brute-force reference search.
+ *
+ * @example
+ * ```typescript
+ * const validator = new HnswShadowValidator(adapter);
+ *
+ * // Add vectors to both the adapter and the validator's reference store
+ * validator.addVector('doc-1', embedding1);
+ * validator.addVector('doc-2', embedding2);
+ *
+ * // Run validation queries
+ * const queries = [randomEmbedding(), randomEmbedding()];
+ * const result = validator.validate(queries);
+ *
+ * console.log(`Divergence: ${(result.divergenceRate * 100).toFixed(1)}%`);
+ * console.log(`Passes: ${result.passesGoGate}`);
+ * ```
+ */
+export class HnswShadowValidator {
+    adapter;
+    referenceVectors = new Map();
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /**
+     * Add a vector to both the unified adapter and the brute-force reference.
+     */
+    addVector(id, vector) {
+        this.adapter.addByStringId(id, vector);
+        this.referenceVectors.set(id, vector);
+    }
+    /**
+     * Remove a vector from both stores.
+     */
+    removeVector(id) {
+        this.adapter.removeByStringId(id);
+        this.referenceVectors.delete(id);
+    }
+    /**
+     * Get the number of vectors in the reference store.
+     */
+    get size() {
+        return this.referenceVectors.size;
+    }
+    /**
+     * Run N queries against both implementations and compare results.
+     *
+     * @param queries - Array of query vectors
+     * @param options - Validation options
+     * @returns Validation result with divergence metrics
+     */
+    validate(queries, options = {}) {
+        const k = options.k ?? 10;
+        const threshold = options.threshold ?? 0.02;
+        const divergences = [];
+        let totalJaccard = 0;
+        let totalScoreDelta = 0;
+        let maxScoreDelta = 0;
+        for (let qi = 0; qi < queries.length; qi++) {
+            const query = queries[qi];
+            // Reference: brute-force
+            const refResults = bruteForceSearch(this.referenceVectors, query, k);
+            const refIds = refResults.map(r => r.id);
+            const refTop1Score = refResults.length > 0 ? refResults[0].score : 0;
+            // Unified: HnswAdapter
+            const adapterResults = this.adapter.searchByArray(query, k);
+            const adapterIds = adapterResults.map(r => r.id);
+            const adapterTop1Score = adapterResults.length > 0 ? adapterResults[0].score : 0;
+            // Compute Jaccard overlap
+            const refSet = new Set(refIds);
+            const adapterSet = new Set(adapterIds);
+            const intersection = new Set([...refSet].filter(id => adapterSet.has(id)));
+            const union = new Set([...refSet, ...adapterSet]);
+            const jaccard = union.size > 0 ? intersection.size / union.size : 1;
+            const scoreDelta = Math.abs(refTop1Score - adapterTop1Score);
+            totalJaccard += jaccard;
+            totalScoreDelta += scoreDelta;
+            maxScoreDelta = Math.max(maxScoreDelta, scoreDelta);
+            // Track divergence if sets don't fully overlap
+            if (jaccard < 1.0) {
+                divergences.push({
+                    queryIndex: qi,
+                    oldTopK: refIds,
+                    newTopK: adapterIds,
+                    jaccardOverlap: jaccard,
+                    top1ScoreDelta: scoreDelta,
+                });
+            }
+        }
+        const divergenceRate = queries.length > 0
+            ? divergences.length / queries.length
+            : 0;
+        return {
+            totalQueries: queries.length,
+            divergentQueries: divergences.length,
+            divergenceRate,
+            avgJaccardOverlap: queries.length > 0 ? totalJaccard / queries.length : 1,
+            avgTop1ScoreDelta: queries.length > 0 ? totalScoreDelta / queries.length : 0,
+            maxTop1ScoreDelta: maxScoreDelta,
+            passesGoGate: divergenceRate <= threshold,
+            divergences,
+        };
+    }
+}
+//# sourceMappingURL=hnsw-shadow-validator.js.map

package/dist/kernel/index.d.ts

@@ -3,7 +3,7 @@
  */
 export * from './interfaces';
 export { InMemoryEventBus } from './event-bus';
-export { DefaultAgentCoordinator } from './agent-coordinator';
+export { DefaultAgentCoordinator, ProgressiveContextLoader } from './agent-coordinator';
 export { DefaultPluginLoader } from './plugin-loader';
 export { InMemoryBackend } from './memory-backend';
 export { QEKernelImpl, createKernel } from './kernel';

package/dist/kernel/index.js

@@ -5,7 +5,7 @@
 export * from './interfaces';
 // Implementations
 export { InMemoryEventBus } from './event-bus';
-export { DefaultAgentCoordinator } from './agent-coordinator';
+export { DefaultAgentCoordinator, ProgressiveContextLoader } from './agent-coordinator';
 export { DefaultPluginLoader } from './plugin-loader';
 export { InMemoryBackend } from './memory-backend';
 export { QEKernelImpl, createKernel } from './kernel';

package/dist/kernel/interfaces.d.ts

@@ -126,12 +126,51 @@ export interface AgentCoordinator extends Disposable {
     /** Check if can spawn more agents */
     canSpawn(): boolean;
 }
+/**
+ * Context loading strategy for agent spawn.
+ * - 'full': Load all files (default, existing behavior)
+ * - 'lazy': Load files on-demand as agents request them
+ * - 'predictive': Use keyword matching to predict which files will be needed
+ */
+export type ContextLoadingStrategy = 'full' | 'lazy' | 'predictive';
+/**
+ * Configuration for progressive context loading (ADR-062 Action 5).
+ * Reduces token usage by ~40% by loading only predicted files at spawn.
+ */
+export interface ProgressiveContextConfig {
+    /** Loading strategy (default: 'full') */
+    strategy: ContextLoadingStrategy;
+    /** Maximum number of files to load at spawn (default: 10) */
+    maxInitialFiles: number;
+    /** Keyword similarity threshold for predictive loading (default: 0.7) */
+    predictionThreshold: number;
+    /** Whether to track file requests for accuracy measurement (default: true) */
+    trackFileRequests: boolean;
+}
+/**
+ * Record of a file request made by an agent (ADR-062 Action 5).
+ * Used to measure prediction accuracy and improve future predictions.
+ */
+export interface FileRequestRecord {
+    /** Path of the requested file */
+    filePath: string;
+    /** Timestamp when the file was requested */
+    requestedAt: number;
+    /** Whether this file was preloaded (predicted correctly) */
+    wasPreloaded: boolean;
+    /** ID of the agent that requested the file */
+    agentId: string;
+    /** Task description associated with this agent */
+    taskDescription: string;
+}
 export interface AgentSpawnConfig {
     name: string;
     domain: DomainName;
     type: string;
     capabilities: string[];
     config?: Record<string, unknown>;
+    /** ADR-062 Action 5: Progressive context loading configuration */
+    progressiveContext?: ProgressiveContextConfig;
 }
 export interface AgentFilter {
     domain?: DomainName;

package/dist/kernel/kernel.d.ts

@@ -4,6 +4,8 @@
  */
 import { DomainName } from '../shared/types';
 import { QEKernel, EventBus, AgentCoordinator, PluginLoader, MemoryBackend, KernelHealth, KernelConfig } from './interfaces';
+import { ToolCallSignatureTracker } from './anti-drift-middleware.js';
+import type { LoopDetectionResult } from './anti-drift-middleware.js';
 import '../domains/test-generation';
 import '../domains/coverage-analysis';
 import '../domains/security-compliance';
@@ -17,6 +19,7 @@ export declare class QEKernelImpl implements QEKernel {
     private _config;
     private _startTime;
     private _initialized;
+    private _loopTracker;
     constructor(config?: Partial<KernelConfig>);
     get eventBus(): EventBus;
     get coordinator(): AgentCoordinator;
@@ -50,6 +53,26 @@ export declare class QEKernelImpl implements QEKernel {
     getHealth(): KernelHealth;
     private determineOverallStatus;
     getConfig(): KernelConfig;
+    /**
+     * Check a tool call for loop detection (ADR-062).
+     *
+     * Delegates to {@link ToolCallSignatureTracker.trackCall} and publishes
+     * `loop.warning` or `loop.detected` events to the EventBus when the
+     * tracker returns `warn` or `steer` respectively.
+     *
+     * Feature-flagged: returns `allow` immediately when
+     * `process.env.AQE_LOOP_DETECTION_ENABLED === 'false'`.
+     *
+     * @param agentId  - The agent making the tool call
+     * @param toolName - Name of the tool being called
+     * @param args     - Arguments to the tool call
+     * @returns The loop detection result
+     */
+    checkToolCall(agentId: string, toolName: string, args: unknown): LoopDetectionResult;
+    /**
+     * Get the internal ToolCallSignatureTracker for metrics / testing.
+     */
+    get loopTracker(): ToolCallSignatureTracker;
 }
 export declare function createKernel(config?: Partial<KernelConfig>): QEKernel;
 //# sourceMappingURL=kernel.d.ts.map

package/dist/kernel/kernel.js

@@ -9,12 +9,15 @@ import { DefaultAgentCoordinator } from './agent-coordinator';
 import { DefaultPluginLoader } from './plugin-loader';
 import { InMemoryBackend } from './memory-backend';
 import { HybridMemoryBackend } from './hybrid-backend';
-import { SemanticAntiDriftMiddleware } from './anti-drift-middleware.js';
+import { SemanticAntiDriftMiddleware, ToolCallSignatureTracker } from './anti-drift-middleware.js';
+import { LOOP_EVENT_TYPES } from './event-bus.js';
 import { AGENT_CONSTANTS, MEMORY_CONSTANTS } from './constants.js';
 import { findProjectRoot } from './unified-memory.js';
 import { initializeUnifiedPersistence } from './unified-persistence.js';
 import * as path from 'path';
 import * as fs from 'fs';
+import { PluginLifecycleManager } from '../plugins/lifecycle';
+import { PluginCache } from '../plugins/cache';
 // Import domain plugin factories
 import { createTestGenerationPlugin } from '../domains/test-generation/plugin';
 import { createTestExecutionPlugin } from '../domains/test-execution/plugin';
@@ -70,6 +73,8 @@ export class QEKernelImpl {
     _config;
     _startTime;
     _initialized = false;
+    // ADR-062: Loop detection tracker
+    _loopTracker;
     constructor(config = {}) {
         this._config = { ...DEFAULT_CONFIG, ...config };
         this._startTime = new Date();
@@ -80,6 +85,8 @@ export class QEKernelImpl {
         this._eventBus = new InMemoryEventBus();
         this._coordinator = new DefaultAgentCoordinator(this._config.maxConcurrentAgents);
         this._plugins = new DefaultPluginLoader(this._eventBus, this._memory, this._config.lazyLoading);
+        // ADR-062: Instantiate loop detection tracker alongside anti-drift middleware
+        this._loopTracker = new ToolCallSignatureTracker();
     }
     get eventBus() {
         return this._eventBus;
@@ -149,10 +156,75 @@ export class QEKernelImpl {
             agentId: 'qe-kernel',
         });
         this._eventBus.registerMiddleware(antiDriftMiddleware);
+        // IMP-09: Discover and register external plugins from cache
+        try {
+            const pluginCacheDir = path.join(dataDir, 'plugins');
+            const pluginCache = new PluginCache({ cacheDir: pluginCacheDir });
+            const pluginLifecycle = new PluginLifecycleManager({ cache: pluginCache });
+            const resolution = pluginLifecycle.resolveLoadOrder();
+            for (const resolved of resolution.ordered) {
+                const manifest = resolved.manifest;
+                const cachedPlugin = pluginCache.get(manifest.name, manifest.version);
+                if (!cachedPlugin)
+                    continue;
+                const entryPointPath = path.join(cachedPlugin.path, manifest.entryPoint);
+                // Register a factory for each domain the plugin provides
+                for (const domain of manifest.domains) {
+                    const domainName = domain;
+                    if (DOMAIN_FACTORIES[domainName])
+                        continue; // don't override built-in domains
+                    const loader = this._plugins;
+                    loader.registerFactory(domainName, async (eventBus, memory) => {
+                        // Dynamically import the plugin entry point at load time
+                        const pluginModule = await import(entryPointPath);
+                        const createPlugin = pluginModule.default ?? pluginModule.createPlugin;
+                        if (typeof createPlugin !== 'function') {
+                            throw new Error(`Plugin "${manifest.name}" entry point must export a default function or "createPlugin" function`);
+                        }
+                        return createPlugin(eventBus, memory, this._coordinator);
+                    });
+                }
+            }
+        }
+        catch {
+            // External plugin loading is best-effort — don't block kernel startup
+        }
         // Load plugins based on configuration
         if (!this._config.lazyLoading) {
             await this._plugins.loadAll();
         }
+        // ADR-067: Wire agent memory branching when RVF PatternStore is enabled
+        // Uses shared adapter singleton to avoid duplicate file handles (M4 fix)
+        try {
+            const { isAgentMemoryBranchingEnabled, isRVFPatternStoreEnabled } = await import('../integrations/ruvector/feature-flags.js');
+            if (isAgentMemoryBranchingEnabled() && isRVFPatternStoreEnabled()) {
+                const { getSharedRvfAdapter } = await import('../integrations/ruvector/shared-rvf-adapter.js');
+                const { AgentMemoryBranch } = await import('../coordination/agent-memory-branch.js');
+                const rvfAdapter = getSharedRvfAdapter(dataDir, 384);
+                if (rvfAdapter) {
+                    const branch = new AgentMemoryBranch(rvfAdapter, {
+                        branchDir: path.join(dataDir, 'branches'),
+                    });
+                    this._coordinator.setMemoryBranch(branch);
+                }
+            }
+        }
+        catch {
+            // Agent memory branching is best-effort — don't block kernel startup
+        }
+        // ADR-072 Phase 3: Initialize RVF migration coordinator
+        try {
+            const { getRvfMigrationStage } = await import('../integrations/ruvector/feature-flags.js');
+            const stage = getRvfMigrationStage();
+            if (stage >= 2) {
+                const { RvfMigrationCoordinator } = await import('../persistence/rvf-migration-coordinator.js');
+                const coordinator = RvfMigrationCoordinator.getInstance({ stage });
+                await coordinator.initialize();
+            }
+        }
+        catch {
+            // Migration coordinator is best-effort — don't block kernel startup
+        }
         this._initialized = true;
     }
     async dispose() {
@@ -298,6 +370,74 @@ export class QEKernelImpl {
     getConfig() {
         return { ...this._config };
     }
+    // ==========================================================================
+    // ADR-062: Loop Detection
+    // ==========================================================================
+    /**
+     * Check a tool call for loop detection (ADR-062).
+     *
+     * Delegates to {@link ToolCallSignatureTracker.trackCall} and publishes
+     * `loop.warning` or `loop.detected` events to the EventBus when the
+     * tracker returns `warn` or `steer` respectively.
+     *
+     * Feature-flagged: returns `allow` immediately when
+     * `process.env.AQE_LOOP_DETECTION_ENABLED === 'false'`.
+     *
+     * @param agentId  - The agent making the tool call
+     * @param toolName - Name of the tool being called
+     * @param args     - Arguments to the tool call
+     * @returns The loop detection result
+     */
+    checkToolCall(agentId, toolName, args) {
+        // Feature flag gate — tracker checks internally too, but we skip event
+        // publishing entirely when disabled to avoid unnecessary async work.
+        if (process.env.AQE_LOOP_DETECTION_ENABLED === 'false') {
+            return this._loopTracker.trackCall(agentId, toolName, args);
+        }
+        const result = this._loopTracker.trackCall(agentId, toolName, args);
+        if (result.action === 'warn') {
+            // Fire-and-forget: publish warning event
+            const warningEvent = {
+                id: `loop-warn-${agentId}-${Date.now()}`,
+                type: LOOP_EVENT_TYPES.LOOP_WARNING,
+                timestamp: new Date(),
+                source: 'coordination',
+                correlationId: agentId,
+                payload: {
+                    agentId,
+                    toolName,
+                    callCount: result.callCount,
+                    signature: result.signature,
+                },
+            };
+            void this._eventBus.publish(warningEvent);
+        }
+        else if (result.action === 'steer') {
+            // Fire-and-forget: publish loop-detected event
+            const detectedEvent = {
+                id: `loop-detected-${agentId}-${Date.now()}`,
+                type: LOOP_EVENT_TYPES.LOOP_DETECTED,
+                timestamp: new Date(),
+                source: 'coordination',
+                correlationId: agentId,
+                payload: {
+                    agentId,
+                    toolName,
+                    callCount: result.callCount,
+                    signature: result.signature,
+                    steeringMessage: result.steeringMessage,
+                },
+            };
+            void this._eventBus.publish(detectedEvent);
+        }
+        return result;
+    }
+    /**
+     * Get the internal ToolCallSignatureTracker for metrics / testing.
+     */
+    get loopTracker() {
+        return this._loopTracker;
+    }
 }
 // Factory function
 export function createKernel(config) {

package/dist/kernel/memory-backend.js

@@ -56,7 +56,9 @@ export class InMemoryBackend {
         return value !== undefined;
     }
     async search(pattern, limit = MEMORY_CONSTANTS.DEFAULT_SEARCH_LIMIT) {
-        const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+        // Escape regex-special chars first, then convert glob wildcards to regex
+        const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        const regex = new RegExp(escaped.replace(/\*/g, '.*'));
         const results = [];
         for (const key of this.store.keys()) {
             if (regex.test(key)) {

package/dist/kernel/unified-memory.d.ts

@@ -23,7 +23,7 @@
  */
 import { type Database as DatabaseType, type Statement } from 'better-sqlite3';
 export { validateTableName, ALLOWED_TABLE_NAMES } from '../shared/sql-safety.js';
-export { BinaryHeap, InMemoryHNSWIndex, RuvectorFlatIndex } from './unified-memory-hnsw.js';
+export { BinaryHeap, UnifiedHnswIndex, createHnswIndex } from './unified-memory-hnsw.js';
 import { type CRDTStore, type CRDTStoreState, type CRDTStoreDelta } from '../memory/crdt/index.js';
 /**
  * Clear the cached project root. Useful for testing or when the

package/dist/kernel/unified-memory.js

@@ -34,8 +34,11 @@ const logger = LoggerFactory.create('unified-memory');
 export { validateTableName, ALLOWED_TABLE_NAMES } from '../shared/sql-safety.js';
 import { validateTableName } from '../shared/sql-safety.js';
 // Re-export extracted modules for backward compatibility
-export { BinaryHeap, InMemoryHNSWIndex, RuvectorFlatIndex } from './unified-memory-hnsw.js';
-import { RuvectorFlatIndex } from './unified-memory-hnsw.js';
+export { BinaryHeap, UnifiedHnswIndex, createHnswIndex } from './unified-memory-hnsw.js';
+// ADR-071 Phase 2C: InMemoryHNSWIndex and RuvectorFlatIndex are decommissioned
+// from production code. Import them directly from unified-memory-hnsw.js for
+// parity tests or benchmarks only.
+import { UnifiedHnswIndex } from './unified-memory-hnsw.js';
 // Import schemas
 import { SCHEMA_VERSION, SCHEMA_VERSION_TABLE, KV_STORE_SCHEMA, VECTORS_SCHEMA, RL_QVALUES_SCHEMA, GOAP_SCHEMA, DREAM_SCHEMA, QE_PATTERNS_SCHEMA, MINCUT_SCHEMA, SONA_PATTERNS_SCHEMA, FEEDBACK_SCHEMA, HYPERGRAPH_SCHEMA, STATS_TABLES, } from './unified-memory-schemas.js';
 // CRDT imports for distributed state synchronization
@@ -171,7 +174,8 @@ export class UnifiedMemoryManager {
     vectorsLoaded = false;
     initPromise = null;
     preparedStatements = new Map();
-    vectorIndex = new RuvectorFlatIndex();
+    // ADR-071 Phase 2C: Always use UnifiedHnswIndex (old implementations decommissioned)
+    vectorIndex = new UnifiedHnswIndex('qe-memory');
     // CRDT store for distributed state synchronization
     crdtStore = null;
     constructor(config) {

package/dist/learning/aqe-learning-engine.d.ts

@@ -281,6 +281,71 @@ export declare class AQELearningEngine {
      */
     dispose(): Promise<void>;
 }
+/**
+ * Configuration for the meta-learning cycle.
+ */
+export interface MetaLearningConfig {
+    /** Whether meta-learning is enabled */
+    enabled: boolean;
+    /** Interval between snapshots in milliseconds (default: 300 000 = 5 min) */
+    snapshotIntervalMs: number;
+    /** Minimum number of snapshots required before analysis runs (default: 5) */
+    minSnapshotsForAnalysis: number;
+    /** Confidence threshold for auto-applying suggestions (default: 0.8) */
+    autoApplyThreshold: number;
+}
+/**
+ * Default meta-learning configuration.
+ */
+export declare const DEFAULT_META_LEARNING_CONFIG: MetaLearningConfig;
+/**
+ * An actionable insight produced by the meta-learning cycle.
+ */
+export interface MetaInsight {
+    /** Unique identifier */
+    id: string;
+    /** Category of the detected issue */
+    type: 'token-waste' | 'quality-plateau' | 'learning-stall' | 'performance-regression';
+    /** Human-readable explanation */
+    description: string;
+    /** Confidence in this insight (0-1) */
+    confidence: number;
+    /** Recommended remediation action */
+    suggestedAction: string;
+    /** Epoch-ms when the insight was detected */
+    detectedAt: number;
+}
+/**
+ * Meta-Learning Engine — closed-loop meta-optimization (ADR-062).
+ *
+ * Analyses a time-series of `UnifiedMetricsSnapshot`s to detect
+ * token-waste, quality plateaus, learning stalls, and performance
+ * regressions.  Guarded by the `AQE_META_LEARNING_ENABLED` env var
+ * (opt-in, default `false`).
+ */
+export declare class MetaLearningEngine {
+    private readonly config;
+    constructor(config?: Partial<MetaLearningConfig>);
+    /**
+     * Run a single meta-learning analysis cycle.
+     *
+     * Trend detection strategy: compare the first half of snapshots to the
+     * second half using simple averages.  This keeps the implementation
+     * lightweight and predictable.
+     *
+     * @param snapshots - Ordered (oldest → newest) unified metric snapshots
+     * @returns Detected meta-insights (may be empty)
+     */
+    runMetaLearningCycle(snapshots: import('./metrics-tracker.js').UnifiedMetricsSnapshot[]): MetaInsight[];
+    /**
+     * Determine whether an insight should be auto-applied.
+     *
+     * @param insight - The insight to evaluate
+     * @param config  - Meta-learning config with the auto-apply threshold
+     * @returns `true` if the insight's confidence meets or exceeds the threshold
+     */
+    shouldAutoApply(insight: MetaInsight, config?: MetaLearningConfig): boolean;
+}
 /**
  * Create AQE Learning Engine
  *