Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

checkpoint: File edit:

rUv5a70729bdc48
diff --git a/.gitignore b/.gitignore
index afff8c5101..7026a41136 100644
--- a/.gitignore
+++ b/.gitignore
@@ -156,8 +156,10 @@ claude-flow.config.json
.swarm/
.hive-mind/
.claude-flow/
-memory/
-coordination/
+/memory/
+/coordination/
+# Exclude @claude-flow module directories from ignore patterns
+!v3/@claude-flow/
memory/claude-flow-data.json
memory/sessions/*
!memory/sessions/README.md
diff --git a/v3/@claude-flow/cli/tsconfig.json b/v3/@claude-flow/cli/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/cli/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/deployment/tsconfig.json b/v3/@claude-flow/deployment/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/deployment/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/integration/tsconfig.json b/v3/@claude-flow/integration/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/integration/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/memory/benchmarks/cache-hit-rate.bench.ts b/v3/@claude-flow/memory/benchmarks/cache-hit-rate.bench.ts
new file mode 100644
index 0000000000..6df1fd0f47
--- /dev/null
+++ b/v3/@claude-flow/memory/benchmarks/cache-hit-rate.bench.ts
@@ -0,0 +1,535 @@
+/**
+ * Cache Hit Rate Benchmark
+ *
+ * Target: <0.1ms for cache hits
+ *
+ * Measures cache performance including hit rate,
+ * lookup time, and eviction strategies.
+ */
+
+import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
+
+// ============================================================================
+// Cache Implementations
+// ============================================================================
+
+/**
+ * Simple LRU Cache implementation
+ */
+class LRUCache<K, V> {
+ private cache = new Map<K, V>();
+ private maxSize: number;
+ private hits = 0;
+ private misses = 0;
+
+ constructor(maxSize: number) {
+ this.maxSize = maxSize;
+ }
+
+ get(key: K): V | undefined {
+ const value = this.cache.get(key);
+ if (value !== undefined) {
+ // Move to end (most recently used)
+ this.cache.delete(key);
+ this.cache.set(key, value);
+ this.hits++;
+ return value;
+ }
+ this.misses++;
+ return undefined;
+ }
+
+ set(key: K, value: V): void {
+ if (this.cache.has(key)) {
+ this.cache.delete(key);
+ } else if (this.cache.size >= this.maxSize) {
+ // Evict oldest (first) entry
+ const firstKey = this.cache.keys().next().value;
+ this.cache.delete(firstKey);
+ }
+ this.cache.set(key, value);
+ }
+
+ get hitRate(): number {
+ const total = this.hits + this.misses;
+ return total > 0 ? this.hits / total : 0;
+ }
+
+ get size(): number {
+ return this.cache.size;
+ }
+
+ clear(): void {
+ this.cache.clear();
+ this.hits = 0;
+ this.misses = 0;
+ }
+}
+
+/**
+ * TTL Cache with expiration
+ */
+class TTLCache<K, V> {
+ private cache = new Map<K, { value: V; expiry: number }>();
+ private defaultTTL: number;
+ private hits = 0;
+ private misses = 0;
+
+ constructor(defaultTTL: number = 60000) {
+ this.defaultTTL = defaultTTL;
+ }
+
+ get(key: K): V | undefined {
+ const entry = this.cache.get(key);
+ if (entry !== undefined) {
+ if (Date.now() < entry.expiry) {
+ this.hits++;
+ return entry.value;
+ }
+ // Expired
+ this.cache.delete(key);
+ }
+ this.misses++;
+ return undefined;
+ }
+
+ set(key: K, value: V, ttl?: number): void {
+ const expiry = Date.now() + (ttl || this.defaultTTL);
+ this.cache.set(key, { value, expiry });
+ }
+
+ get hitRate(): number {
+ const total = this.hits + this.misses;
+ return total > 0 ? this.hits / total : 0;
+ }
+
+ get size(): number {
+ return this.cache.size;
+ }
+
+ cleanup(): number {
+ const now = Date.now();
+ let cleaned = 0;
+ for (const [key, entry] of this.cache) {
+ if (now >= entry.expiry) {
+ this.cache.delete(key);
+ cleaned++;
+ }
+ }
+ return cleaned;
+ }
+
+ clear(): void {
+ this.cache.clear();
+ this.hits = 0;
+ this.misses = 0;
+ }
+}
+
+/**
+ * Two-level cache (L1 fast, L2 larger)
+ */
+class TwoLevelCache<K, V> {
+ private l1: LRUCache<K, V>;
+ private l2: LRUCache<K, V>;
+ private l1Hits = 0;
+ private l2Hits = 0;
+ private misses = 0;
+
+ constructor(l1Size: number = 100, l2Size: number = 1000) {
+ this.l1 = new LRUCache<K, V>(l1Size);
+ this.l2 = new LRUCache<K, V>(l2Size);
+ }
+
+ get(key: K): V | undefined {
+ // Check L1 first
+ let value = this.l1.get(key);
+ if (value !== undefined) {
+ this.l1Hits++;
+ return value;
+ }
+
+ // Check L2
+ value = this.l2.get(key);
+ if (value !== undefined) {
+ this.l2Hits++;
+ // Promote to L1
+ this.l1.set(key, value);
+ return value;
+ }
+
+ this.misses++;
+ return undefined;
+ }
+
+ set(key: K, value: V): void {
+ this.l1.set(key, value);
+ this.l2.set(key, value);
+ }
+
+ get stats(): { l1HitRate: number; l2HitRate: number; missRate: number } {
+ const total = this.l1Hits + this.l2Hits + this.misses;
+ return {
+ l1HitRate: total > 0 ? this.l1Hits / total : 0,
+ l2HitRate: total > 0 ? this.l2Hits / total : 0,
+ missRate: total > 0 ? this.misses / total : 0,
+ };
+ }
+
+ clear(): void {
+ this.l1.clear();
+ this.l2.clear();
+ this.l1Hits = 0;
+ this.l2Hits = 0;
+ this.misses = 0;
+ }
+}
+
+/**
+ * Memoization cache for function results
+ */
+class MemoCache<T extends (...args: unknown[]) => unknown> {
+ private cache = new Map<string, ReturnType<T>>();
+ private fn: T;
+
+ constructor(fn: T) {
+ this.fn = fn;
+ }
+
+ call(...args: Parameters<T>): ReturnType<T> {
+ const key = JSON.stringify(args);
+ if (this.cache.has(key)) {
+ return this.cache.get(key)!;
+ }
+ const result = this.fn(...args) as ReturnType<T>;
+ this.cache.set(key, result);
+ return result;
+ }
+
+ get size(): number {
+ return this.cache.size;
+ }
+
+ clear(): void {
+ this.cache.clear();
+ }
+}
+
+// ============================================================================
+// Benchmark Suite
+// ============================================================================
+
+export async function runCacheHitRateBenchmarks(): Promise<void> {
+ const runner = new BenchmarkRunner('Cache Hit Rate');
+
+ console.log('\n--- Cache Hit Rate Benchmarks ---\n');
+
+ // Prepare test data
+ const testKeys = Array.from({ length: 10000 }, (_, i) => `key-${i}`);
+ const testValues = testKeys.map((k) => ({ key: k, data: Math.random() }));
+
+ // Benchmark 1: LRU Cache - Cache Hit
+ const lruCache = new LRUCache<string, object>(1000);
+
+ // Pre-populate cache
+ for (let i = 0; i < 1000; i++) {
+ lruCache.set(testKeys[i]!, testValues[i]!);
+ }
+
+ const lruHitResult = await runner.run(
+ 'lru-cache-hit',
+ async () => {
+ lruCache.get(testKeys[500]!);
+ },
+ { iterations: 100000 }
+ );
+
+ console.log(`LRU Cache Hit: ${formatTime(lruHitResult.mean)}`);
+ const hitTarget = meetsTarget('cache-hit', lruHitResult.mean);
+ console.log(` Target (<0.1ms): ${hitTarget.met ? 'PASS' : 'FAIL'}`);
+
+ // Benchmark 2: LRU Cache - Cache Miss
+ const lruMissResult = await runner.run(
+ 'lru-cache-miss',
+ async () => {
+ lruCache.get('non-existent-key');
+ },
+ { iterations: 100000 }
+ );
+
+ console.log(`LRU Cache Miss: ${formatTime(lruMissResult.mean)}`);
+
+ // Benchmark 3: LRU Cache - Set Operation
+ const lruSetResult = await runner.run(
+ 'lru-cache-set',
+ async () => {
+ lruCache.set(`new-key-${Date.now()}`, { data: 'test' });
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`LRU Cache Set: ${formatTime(lruSetResult.mean)}`);
+
+ // Benchmark 4: TTL Cache - Hit
+ const ttlCache = new TTLCache<string, object>(60000);
+
+ for (let i = 0; i < 1000; i++) {
+ ttlCache.set(testKeys[i]!, testValues[i]!);
+ }
+
+ const ttlHitResult = await runner.run(
+ 'ttl-cache-hit',
+ async () => {
+ ttlCache.get(testKeys[500]!);
+ },
+ { iterations: 100000 }
+ );
+
+ console.log(`TTL Cache Hit: ${formatTime(ttlHitResult.mean)}`);
+
+ // Benchmark 5: TTL Cache - Cleanup
+ // Add some expired entries
+ for (let i = 0; i < 100; i++) {
+ ttlCache.set(`expired-${i}`, { data: i }, -1); // Already expired
+ }
+
+ const ttlCleanupResult = await runner.run(
+ 'ttl-cache-cleanup',
+ async () => {
+ ttlCache.cleanup();
+ },
+ { iterations: 1000 }
+ );
+
+ console.log(`TTL Cache Cleanup: ${formatTime(ttlCleanupResult.mean)}`);
+
+ // Benchmark 6: Two-Level Cache - L1 Hit
+ const twoLevelCache = new TwoLevelCache<string, object>(100, 1000);
+
+ for (let i = 0; i < 1000; i++) {
+ twoLevelCache.set(testKeys[i]!, testValues[i]!);
+ }
+
+ // Warm up L1
+ for (let i = 0; i < 50; i++) {
+ twoLevelCache.get(testKeys[i]!);
+ }
+
+ const l1HitResult = await runner.run(
+ 'two-level-cache-l1-hit',
+ async () => {
+ twoLevelCache.get(testKeys[25]!);
+ },
+ { iterations: 100000 }
+ );
+
+ console.log(`Two-Level Cache L1 Hit: ${formatTime(l1HitResult.mean)}`);
+
+ // Benchmark 7: Two-Level Cache - L2 Hit (promotes to L1)
+ const l2HitResult = await runner.run(
+ 'two-level-cache-l2-hit',
+ async () => {
+ twoLevelCache.get(testKeys[500]!);
+ },
+ { iterations: 50000 }
+ );
+
+ console.log(`Two-Level Cache L2 Hit: ${formatTime(l2HitResult.mean)}`);
+
+ // Benchmark 8: Memoization Cache
+ const expensiveFn = (n: number): number => {
+ let result = 0;
+ for (let i = 0; i < n; i++) {
+ result += Math.sqrt(i);
+ }
+ return result;
+ };
+
+ const memoCache = new MemoCache(expensiveFn);
+
+ // Prime the cache
+ memoCache.call(1000);
+
+ const memoHitResult = await runner.run(
+ 'memo-cache-hit',
+ async () => {
+ memoCache.call(1000);
+ },
+ { iterations: 100000 }
+ );
+
+ console.log(`Memo Cache Hit: ${formatTime(memoHitResult.mean)}`);
+
+ const memoMissResult = await runner.run(
+ 'memo-cache-miss',
+ async () => {
+ memoCache.call(Math.floor(Math.random() * 10000000));
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Memo Cache Miss (compute): ${formatTime(memoMissResult.mean)}`);
+
+ // Benchmark 9: Cache with Different Hit Rates
+ const cache90 = new LRUCache<string, object>(1000);
+ for (let i = 0; i < 1000; i++) {
+ cache90.set(testKeys[i]!, testValues[i]!);
+ }
+
+ const hitRate90Result = await runner.run(
+ 'workload-90-percent-hits',
+ async () => {
+ const isHit = Math.random() < 0.9;
+ if (isHit) {
+ cache90.get(testKeys[Math.floor(Math.random() * 1000)]!);
+ } else {
+ cache90.get(`miss-${Date.now()}`);
+ }
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`90% Hit Rate Workload: ${formatTime(hitRate90Result.mean)}`);
+
+ // Benchmark 10: Cache Eviction Under Pressure
+ const smallCache = new LRUCache<string, object>(100);
+
+ const evictionResult = await runner.run(
+ 'cache-with-eviction',
+ async () => {
+ // Write 200 items to a cache of size 100
+ for (let i = 0; i < 200; i++) {
+ smallCache.set(`evict-key-${i}`, { data: i });
+ }
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Cache with Eviction (200 to 100): ${formatTime(evictionResult.mean)}`);
+
+ // Summary
+ console.log('\n--- Summary ---');
+ console.log(`LRU hit: ${formatTime(lruHitResult.mean)} (${lruHitResult.opsPerSecond.toFixed(0)} ops/sec)`);
+ console.log(`LRU miss: ${formatTime(lruMissResult.mean)}`);
+ console.log(`TTL hit: ${formatTime(ttlHitResult.mean)}`);
+ console.log(`L1 hit: ${formatTime(l1HitResult.mean)}`);
+ console.log(`L2 hit: ${formatTime(l2HitResult.mean)}`);
+ console.log(`Memo hit: ${formatTime(memoHitResult.mean)}`);
+ console.log(`\nTwo-Level Cache Stats:`, twoLevelCache.stats);
+
+ // Print full results
+ runner.printResults();
+}
+
+// ============================================================================
+// Cache Optimization Strategies
+// ============================================================================
+
+export const cacheOptimizations = {
+ /**
+ * Optimal cache sizing
+ */
+ optimalSizing: {
+ description: 'Size cache based on working set and memory constraints',
+ expectedImprovement: '20-50% hit rate',
+ implementation: `
+ function calculateOptimalCacheSize(workingSetSize: number, memoryLimit: number): number {
+ const avgItemSize = estimateAverageItemSize();
+ const maxItems = Math.floor(memoryLimit / avgItemSize);
+ return Math.min(workingSetSize * 0.8, maxItems);
+ }
+ `,
+ },
+
+ /**
+ * Adaptive TTL
+ */
+ adaptiveTTL: {
+ description: 'Adjust TTL based on access patterns',
+ expectedImprovement: '10-30% hit rate',
+ implementation: `
+ class AdaptiveTTLCache {
+ private accessCounts = new Map<string, number>();
+
+ getTTL(key: string): number {
+ const count = this.accessCounts.get(key) || 0;
+ // Hot keys get longer TTL
+ return this.baseTTL * Math.min(10, 1 + Math.log2(count + 1));
+ }
+ }
+ `,
+ },
+
+ /**
+ * Probabilistic early expiration
+ */
+ probabilisticExpiry: {
+ description: 'Refresh items before expiry to avoid thundering herd',
+ expectedImprovement: 'Reduces load spikes by 80%',
+ implementation: `
+ function shouldRefresh(ttl: number, remaining: number): boolean {
+ const beta = 1.0;
+ const delta = ttl - remaining;
+ const xFetch = Date.now() + delta * beta * Math.log(Math.random());
+ return xFetch > Date.now() + remaining;
+ }
+ `,
+ },
+
+ /**
+ * Segmented cache
+ */
+ segmentedCache: {
+ description: 'Reduce lock contention with segmented caches',
+ expectedImprovement: '2-4x concurrent performance',
+ implementation: `
+ class SegmentedCache<K, V> {
+ private segments: LRUCache<K, V>[];
+
+ constructor(numSegments: number, sizePerSegment: number) {
+ this.segments = Array.from(
+ { length: numSegments },
+ () => new LRUCache<K, V>(sizePerSegment)
+ );
+ }
+
+ private getSegment(key: K): LRUCache<K, V> {
+ const hash = this.hash(key);
+ return this.segments[hash % this.segments.length]!;
+ }
+ }
+ `,
+ },
+
+ /**
+ * Read-through caching
+ */
+ readThrough: {
+ description: 'Automatically fetch missing items',
+ expectedImprovement: 'Simplifies code, consistent performance',
+ implementation: `
+ class ReadThroughCache<K, V> {
+ constructor(
+ private cache: LRUCache<K, V>,
+ private loader: (key: K) => Promise<V>
+ ) {}
+
+ async get(key: K): Promise<V> {
+ let value = this.cache.get(key);
+ if (value === undefined) {
+ value = await this.loader(key);
+ this.cache.set(key, value);
+ }
+ return value;
+ }
+ }
+ `,
+ },
+};
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+ runCacheHitRateBenchmarks().catch(console.error);
+}
+
+export default runCacheHitRateBenchmarks;
diff --git a/v3/@claude-flow/memory/benchmarks/hnsw-indexing.bench.ts b/v3/@claude-flow/memory/benchmarks/hnsw-indexing.bench.ts
new file mode 100644
index 0000000000..460f15fb59
--- /dev/null
+++ b/v3/@claude-flow/memory/benchmarks/hnsw-indexing.bench.ts
@@ -0,0 +1,552 @@
+/**
+ * HNSW Indexing Benchmark
+ *
+ * Target: <10ms for index operations
+ *
+ * Measures HNSW index construction, updates, and maintenance performance.
+ */
+
+import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
+
+// ============================================================================
+// HNSW Implementation
+// ============================================================================
+
+interface HNSWConfig {
+ dimensions: number;
+ maxElements: number;
+ M: number; // Max connections per node
+ efConstruction: number; // Size of dynamic candidate list during construction
+ mL: number; // Level generation parameter
+}
+
+interface HNSWNode {
+ id: number;
+ vector: Float32Array;
+ level: number;
+ connections: Map<number, number[]>; // level -> neighbors
+}
+
+/**
+ * HNSW Index implementation for benchmarking
+ */
+class HNSWIndex {
+ private nodes: Map<number, HNSWNode> = new Map();
+ private entryPoint: number | null = null;
+ private maxLevel = 0;
+ private config: HNSWConfig;
+
+ constructor(config: Partial<HNSWConfig> = {}) {
+ this.config = {
+ dimensions: 384,
+ maxElements: 100000,
+ M: 16,
+ efConstruction: 200,
+ mL: 1 / Math.log(16),
+ ...config,
+ };
+ }
+
+ /**
+ * Generate random level for new node
+ */
+ private randomLevel(): number {
+ let level = 0;
+ while (Math.random() < this.config.mL && level < Math.log2(this.config.maxElements)) {
+ level++;
+ }
+ return level;
+ }
+
+ /**
+ * Calculate distance between two vectors (using cosine similarity)
+ */
+ private distance(a: Float32Array, b: Float32Array): number {
+ let dot = 0;
+ for (let i = 0; i < a.length; i++) {
+ dot += a[i]! * b[i]!;
+ }
+ return 1 - dot; // Convert similarity to distance
+ }
+
+ /**
+ * Add a vector to the index
+ */
+ add(id: number, vector: Float32Array): void {
+ const level = this.randomLevel();
+ const node: HNSWNode = {
+ id,
+ vector,
+ level,
+ connections: new Map(),
+ };
+
+ for (let l = 0; l <= level; l++) {
+ node.connections.set(l, []);
+ }
+
+ if (this.entryPoint === null) {
+ this.entryPoint = id;
+ this.maxLevel = level;
+ this.nodes.set(id, node);
+ return;
+ }
+
+ // Find entry point for this level
+ let currentNode = this.nodes.get(this.entryPoint)!;
+ let currentLevel = this.maxLevel;
+
+ // Greedy search down to target level
+ while (currentLevel > level) {
+ const neighbors = currentNode.connections.get(currentLevel) || [];
+ let closest = currentNode;
+ let closestDist = this.distance(vector, currentNode.vector);
+
+ for (const neighborId of neighbors) {
+ const neighbor = this.nodes.get(neighborId)!;
+ const dist = this.distance(vector, neighbor.vector);
+ if (dist < closestDist) {
+ closest = neighbor;
+ closestDist = dist;
+ }
+ }
+
+ if (closest === currentNode) {
+ currentLevel--;
+ } else {
+ currentNode = closest;
+ }
+ }
+
+ // Insert at each level
+ for (let l = Math.min(level, this.maxLevel); l >= 0; l--) {
+ // Find neighbors at this level (simplified)
+ const candidates = this.searchLayer(vector, currentNode.id, l, this.config.efConstruction);
+ const neighbors = candidates.slice(0, this.config.M);
+
+ // Connect node to neighbors
+ node.connections.set(l, neighbors.map((n) => n.id));
+
+ // Add reverse connections
+ for (const { id: neighborId } of neighbors) {
+ const neighbor = this.nodes.get(neighborId)!;
+ const neighborConnections = neighbor.connections.get(l) || [];
+ if (neighborConnections.length < this.config.M) {
+ neighborConnections.push(id);
+ neighbor.connections.set(l, neighborConnections);
+ }
+ }
+ }
+
+ this.nodes.set(id, node);
+
+ if (level > this.maxLevel) {
+ this.maxLevel = level;
+ this.entryPoint = id;
+ }
+ }
+
+ /**
+ * Search at a specific layer
+ */
+ private searchLayer(
+ query: Float32Array,
+ entryId: number,
+ level: number,
+ ef: number
+ ): Array<{ id: number; distance: number }> {
+ const visited = new Set<number>([entryId]);
+ const entryNode = this.nodes.get(entryId)!;
+ const candidates = [{ id: entryId, distance: this.distance(query, entryNode.vector) }];
+ const results = [...candidates];
+
+ while (candidates.length > 0) {
+ candidates.sort((a, b) => a.distance - b.distance);
+ const current = candidates.shift()!;
+
+ if (results.length >= ef && current.distance > results[results.length - 1]!.distance) {
+ break;
+ }
+
+ const currentNode = this.nodes.get(current.id)!;
+ const neighbors = currentNode.connections.get(level) || [];
+
+ for (const neighborId of neighbors) {
+ if (visited.has(neighborId)) continue;
+ visited.add(neighborId);
+
+ const neighbor = this.nodes.get(neighborId)!;
+ const dist = this.distance(query, neighbor.vector);
+
+ if (results.length < ef || dist < results[results.length - 1]!.distance) {
+ results.push({ id: neighborId, distance: dist });
+ candidates.push({ id: neighborId, distance: dist });
+ results.sort((a, b) => a.distance - b.distance);
+ if (results.length > ef) {
+ results.pop();
+ }
+ }
+ }
+ }
+
+ return results;
+ }
+
+ /**
+ * Search for k nearest neighbors
+ */
+ search(query: Float32Array, k: number, ef = 50): Array<{ id: number; distance: number }> {
+ if (this.entryPoint === null) return [];
+
+ let currentId = this.entryPoint;
+ const currentNode = this.nodes.get(currentId)!;
+
+ // Greedy descent to level 0
+ for (let level = this.maxLevel; level > 0; level--) {
+ const results = this.searchLayer(query, currentId, level, 1);
+ if (results.length > 0) {
+ currentId = results[0]!.id;
+ }
+ }
+
+ // Search at level 0
+ const results = this.searchLayer(query, currentId, 0, Math.max(ef, k));
+ return results.slice(0, k);
+ }
+
+ /**
+ * Remove a vector from the index
+ */
+ remove(id: number): boolean {
+ const node = this.nodes.get(id);
+ if (!node) return false;
+
+ // Remove all connections to this node
+ for (const [level, neighbors] of node.connections) {
+ for (const neighborId of neighbors) {
+ const neighbor = this.nodes.get(neighborId);
+ if (neighbor) {
+ const neighborConns = neighbor.connections.get(level);
+ if (neighborConns) {
+ const idx = neighborConns.indexOf(id);
+ if (idx >= 0) {
+ neighborConns.splice(idx, 1);
+ }
+ }
+ }
+ }
+ }
+
+ this.nodes.delete(id);
+
+ // Update entry point if needed
+ if (this.entryPoint === id) {
+ this.entryPoint = this.nodes.size > 0 ? this.nodes.keys().next().value : null;
+ this.maxLevel = this.entryPoint !== null
+ ? this.nodes.get(this.entryPoint)!.level
+ : 0;
+ }
+
+ return true;
+ }
+
+ get size(): number {
+ return this.nodes.size;
+ }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function generateVector(dim: number): Float32Array {
+ const v = new Float32Array(dim);
+ let norm = 0;
+ for (let i = 0; i < dim; i++) {
+ v[i] = Math.random() * 2 - 1;
+ norm += v[i]! * v[i]!;
+ }
+ norm = Math.sqrt(norm);
+ for (let i = 0; i < dim; i++) {
+ v[i]! /= norm;
+ }
+ return v;
+}
+
+// ============================================================================
+// Benchmark Suite
+// ============================================================================
+
+export async function runHNSWIndexingBenchmarks(): Promise<void> {
+ const runner = new BenchmarkRunner('HNSW Indexing');
+
+ console.log('\n--- HNSW Indexing Benchmarks ---\n');
+
+ const dimensions = 384;
+
+ // Benchmark 1: Single Vector Insert
+ const singleInsertResult = await runner.run(
+ 'single-vector-insert',
+ async () => {
+ const index = new HNSWIndex({ dimensions });
+ const vector = generateVector(dimensions);
+ index.add(0, vector);
+ },
+ { iterations: 500 }
+ );
+
+ console.log(`Single Vector Insert: ${formatTime(singleInsertResult.mean)}`);
+ const insertTarget = meetsTarget('hnsw-indexing', singleInsertResult.mean);
+ console.log(` Target (<10ms): ${insertTarget.met ? 'PASS' : 'FAIL'}`);
+
+ // Benchmark 2: Batch Insert (100 vectors)
+ const batch100Result = await runner.run(
+ 'batch-insert-100',
+ async () => {
+ const index = new HNSWIndex({ dimensions });
+ const vectors = Array.from({ length: 100 }, () => generateVector(dimensions));
+ for (let i = 0; i < vectors.length; i++) {
+ index.add(i, vectors[i]!);
+ }
+ },
+ { iterations: 20 }
+ );
+
+ console.log(`Batch Insert (100 vectors): ${formatTime(batch100Result.mean)}`);
+ console.log(` Per vector: ${formatTime(batch100Result.mean / 100)}`);
+
+ // Benchmark 3: Batch Insert (1000 vectors)
+ const batch1000Result = await runner.run(
+ 'batch-insert-1000',
+ async () => {
+ const index = new HNSWIndex({ dimensions });
+ const vectors = Array.from({ length: 1000 }, () => generateVector(dimensions));
+ for (let i = 0; i < vectors.length; i++) {
+ index.add(i, vectors[i]!);
+ }
+ },
+ { iterations: 5 }
+ );
+
+ console.log(`Batch Insert (1000 vectors): ${formatTime(batch1000Result.mean)}`);
+ console.log(` Per vector: ${formatTime(batch1000Result.mean / 1000)}`);
+
+ // Create pre-built index for search benchmarks
+ const prebuiltIndex = new HNSWIndex({ dimensions });
+ const prebuiltVectors = Array.from({ length: 1000 }, () => generateVector(dimensions));
+ for (let i = 0; i < prebuiltVectors.length; i++) {
+ prebuiltIndex.add(i, prebuiltVectors[i]!);
+ }
+
+ // Benchmark 4: Search on 1000-vector index
+ const query = generateVector(dimensions);
+
+ const search1000Result = await runner.run(
+ 'search-1000-vectors',
+ async () => {
+ prebuiltIndex.search(query, 10, 50);
+ },
+ { iterations: 500 }
+ );
+
+ console.log(`Search (1000 vectors, k=10): ${formatTime(search1000Result.mean)}`);
+
+ // Benchmark 5: Vector Removal
+ const removeResult = await runner.run(
+ 'vector-removal',
+ async () => {
+ // Create a small index for removal testing
+ const index = new HNSWIndex({ dimensions });
+ for (let i = 0; i < 100; i++) {
+ index.add(i, generateVector(dimensions));
+ }
+ // Remove middle element
+ index.remove(50);
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Vector Removal (from 100): ${formatTime(removeResult.mean)}`);
+
+ // Benchmark 6: Index Update (remove + add)
+ const updateResult = await runner.run(
+ 'index-update',
+ async () => {
+ const index = new HNSWIndex({ dimensions });
+ for (let i = 0; i < 100; i++) {
+ index.add(i, generateVector(dimensions));
+ }
+ // Update: remove and re-add
+ index.remove(50);
+ index.add(50, generateVector(dimensions));
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Index Update (remove + add): ${formatTime(updateResult.mean)}`);
+
+ // Benchmark 7: Different M values
+ const m8Index = new HNSWIndex({ dimensions, M: 8 });
+ const m8Vectors = Array.from({ length: 500 }, () => generateVector(dimensions));
+
+ const m8BuildResult = await runner.run(
+ 'build-m8-500',
+ async () => {
+ const index = new HNSWIndex({ dimensions, M: 8 });
+ for (let i = 0; i < 500; i++) {
+ index.add(i, m8Vectors[i]!);
+ }
+ },
+ { iterations: 10 }
+ );
+
+ console.log(`Build (M=8, 500 vectors): ${formatTime(m8BuildResult.mean)}`);
+
+ const m32BuildResult = await runner.run(
+ 'build-m32-500',
+ async () => {
+ const index = new HNSWIndex({ dimensions, M: 32 });
+ for (let i = 0; i < 500; i++) {
+ index.add(i, m8Vectors[i]!);
+ }
+ },
+ { iterations: 10 }
+ );
+
+ console.log(`Build (M=32, 500 vectors): ${formatTime(m32BuildResult.mean)}`);
+
+ // Benchmark 8: Different ef_construction values
+ const ef100Result = await runner.run(
+ 'build-ef100-500',
+ async () => {
+ const index = new HNSWIndex({ dimensions, efConstruction: 100 });
+ for (let i = 0; i < 500; i++) {
+ index.add(i, m8Vectors[i]!);
+ }
+ },
+ { iterations: 10 }
+ );
+
+ console.log(`Build (ef=100, 500 vectors): ${formatTime(ef100Result.mean)}`);
+
+ const ef400Result = await runner.run(
+ 'build-ef400-500',
+ async () => {
+ const index = new HNSWIndex({ dimensions, efConstruction: 400 });
+ for (let i = 0; i < 500; i++) {
+ index.add(i, m8Vectors[i]!);
+ }
+ },
+ { iterations: 10 }
+ );
+
+ console.log(`Build (ef=400, 500 vectors): ${formatTime(ef400Result.mean)}`);
+
+ // Summary
+ console.log('\n--- Summary ---');
+ console.log(`Single insert: ${formatTime(singleInsertResult.mean)}`);
+ console.log(`Per-vector cost at 1000: ${formatTime(batch1000Result.mean / 1000)}`);
+ console.log(`Search (1000 vectors): ${formatTime(search1000Result.mean)}`);
+ console.log(`M=8 vs M=32: ${(m32BuildResult.mean / m8BuildResult.mean).toFixed(2)}x slower`);
+ console.log(`ef=100 vs ef=400: ${(ef400Result.mean / ef100Result.mean).toFixed(2)}x slower`);
+
+ // Print full results
+ runner.printResults();
+}
+
+// ============================================================================
+// HNSW Indexing Optimization Strategies
+// ============================================================================
+
+export const hnswOptimizations = {
+ /**
+ * Optimal M selection based on dimension
+ */
+ optimalM: {
+ description: 'Choose M based on vector dimensions (M = 2 * log2(dimensions))',
+ expectedImprovement: '10-30%',
+ implementation: `
+ function optimalM(dimensions: number): number {
+ return Math.round(2 * Math.log2(dimensions));
+ }
+ // For 384 dimensions: M = 17
+ `,
+ },
+
+ /**
+ * Parallel index construction
+ */
+ parallelConstruction: {
+ description: 'Build index using multiple worker threads',
+ expectedImprovement: '2-4x',
+ implementation: `
+ async function parallelBuild(vectors: Float32Array[]): Promise<HNSWIndex> {
+ const workers = os.cpus().length;
+ const chunks = chunkArray(vectors, workers);
+
+ const partialIndices = await Promise.all(
+ chunks.map((chunk, i) => buildInWorker(chunk, i))
+ );
+
+ return mergeIndices(partialIndices);
+ }
+ `,
+ },
+
+ /**
+ * Incremental updates
+ */
+ incrementalUpdates: {
+ description: 'Batch updates and apply incrementally',
+ expectedImprovement: '20-50%',
+ implementation: `
+ class IncrementalHNSW {
+ private pendingUpdates: Update[] = [];
+ private updateThreshold = 100;
+
+ add(id: number, vector: Float32Array): void {
+ this.pendingUpdates.push({ type: 'add', id, vector });
+ if (this.pendingUpdates.length >= this.updateThreshold) {
+ this.flush();
+ }
+ }
+
+ private flush(): void {
+ // Apply all updates in batch
+ for (const update of this.pendingUpdates) {
+ this.applyUpdate(update);
+ }
+ this.pendingUpdates = [];
+ }
+ }
+ `,
+ },
+
+ /**
+ * Memory-mapped storage
+ */
+ mmapStorage: {
+ description: 'Use memory-mapped files for large indices',
+ expectedImprovement: '30-50% memory, 10-20% speed',
+ implementation: `
+ import mmap from 'mmap-io';
+
+ class MmapHNSW {
+ private fd: number;
+ private buffer: Buffer;
+
+ constructor(filePath: string, size: number) {
+ this.fd = fs.openSync(filePath, 'r+');
+ this.buffer = mmap.map(size, mmap.PROT_READ | mmap.PROT_WRITE, mmap.MAP_SHARED, this.fd);
+ }
+ }
+ `,
+ },
+};
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+ runHNSWIndexingBenchmarks().catch(console.error);
+}
+
+export default runHNSWIndexingBenchmarks;
diff --git a/v3/@claude-flow/memory/benchmarks/memory-write.bench.ts b/v3/@claude-flow/memory/benchmarks/memory-write.bench.ts
new file mode 100644
index 0000000000..3f3a850a49
--- /dev/null
+++ b/v3/@claude-flow/memory/benchmarks/memory-write.bench.ts
@@ -0,0 +1,469 @@
+/**
+ * Memory Write Benchmark
+ *
+ * Target: <5ms (10x faster than current ~50ms)
+ *
+ * Measures memory write operations including key-value stores,
+ * structured data, and vector embeddings.
+ */
+
+import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
+
+// ============================================================================
+// Memory Store Implementations
+// ============================================================================
+
+/**
+ * Simple in-memory key-value store
+ */
+class SimpleMemoryStore {
+ private data = new Map<string, unknown>();
+
+ set(key: string, value: unknown): void {
+ this.data.set(key, value);
+ }
+
+ get(key: string): unknown {
+ return this.data.get(key);
+ }
+
+ delete(key: string): boolean {
+ return this.data.delete(key);
+ }
+
+ clear(): void {
+ this.data.clear();
+ }
+
+ get size(): number {
+ return this.data.size;
+ }
+}
+
+/**
+ * Typed array store for vectors
+ */
+class VectorStore {
+ private vectors: Map<string, Float32Array> = new Map();
+ private metadata: Map<string, object> = new Map();
+
+ set(key: string, vector: Float32Array, meta?: object): void {
+ this.vectors.set(key, vector);
+ if (meta) {
+ this.metadata.set(key, meta);
+ }
+ }
+
+ get(key: string): { vector: Float32Array; metadata?: object } | undefined {
+ const vector = this.vectors.get(key);
+ if (!vector) return undefined;
+ return { vector, metadata: this.metadata.get(key) };
+ }
+
+ delete(key: string): boolean {
+ this.metadata.delete(key);
+ return this.vectors.delete(key);
+ }
+
+ get size(): number {
+ return this.vectors.size;
+ }
+}
+
+/**
+ * Write-ahead log for durability
+ */
+class WriteAheadLog {
+ private entries: Array<{ timestamp: number; operation: string; key: string; value: unknown }> = [];
+ private maxEntries = 10000;
+
+ append(operation: string, key: string, value: unknown): number {
+ const entry = {
+ timestamp: Date.now(),
+ operation,
+ key,
+ value,
+ };
+ this.entries.push(entry);
+
+ // Compact if needed
+ if (this.entries.length > this.maxEntries) {
+ this.entries = this.entries.slice(-this.maxEntries / 2);
+ }
+
+ return this.entries.length;
+ }
+
+ get length(): number {
+ return this.entries.length;
+ }
+}
+
+/**
+ * Batched memory store for bulk operations
+ */
+class BatchedMemoryStore {
+ private data = new Map<string, unknown>();
+ private pendingWrites: Array<{ key: string; value: unknown }> = [];
+ private batchSize = 100;
+
+ queue(key: string, value: unknown): void {
+ this.pendingWrites.push({ key, value });
+ if (this.pendingWrites.length >= this.batchSize) {
+ this.flush();
+ }
+ }
+
+ flush(): void {
+ for (const { key, value } of this.pendingWrites) {
+ this.data.set(key, value);
+ }
+ this.pendingWrites = [];
+ }
+
+ get(key: string): unknown {
+ return this.data.get(key);
+ }
+
+ get size(): number {
+ return this.data.size;
+ }
+
+ get pendingCount(): number {
+ return this.pendingWrites.length;
+ }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function generateVector(dim: number): Float32Array {
+ const v = new Float32Array(dim);
+ for (let i = 0; i < dim; i++) {
+ v[i] = Math.random() * 2 - 1;
+ }
+ return v;
+}
+
+function generateTestData(count: number): Array<{ key: string; value: object }> {
+ return Array.from({ length: count }, (_, i) => ({
+ key: `key-${i}`,
+ value: {
+ id: i,
+ name: `Item ${i}`,
+ timestamp: Date.now(),
+ tags: ['tag1', 'tag2', 'tag3'],
+ metadata: { source: 'benchmark', priority: i % 10 },
+ },
+ }));
+}
+
+// ============================================================================
+// Benchmark Suite
+// ============================================================================
+
+export async function runMemoryWriteBenchmarks(): Promise<void> {
+ const runner = new BenchmarkRunner('Memory Write');
+
+ console.log('\n--- Memory Write Benchmarks ---\n');
+
+ const store = new SimpleMemoryStore();
+ const vectorStore = new VectorStore();
+ const wal = new WriteAheadLog();
+ const batchedStore = new BatchedMemoryStore();
+
+ // Benchmark 1: Single Key-Value Write
+ const singleWriteResult = await runner.run(
+ 'single-kv-write',
+ async () => {
+ store.set(`key-${Date.now()}`, { data: 'test value' });
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`Single K-V Write: ${formatTime(singleWriteResult.mean)}`);
+ const kvTarget = meetsTarget('memory-write', singleWriteResult.mean);
+ console.log(` Target (<5ms): ${kvTarget.met ? 'PASS' : 'FAIL'}`);
+
+ // Benchmark 2: Batch Write (100 items)
+ const testData = generateTestData(100);
+
+ const batch100Result = await runner.run(
+ 'batch-write-100',
+ async () => {
+ for (const { key, value } of testData) {
+ store.set(key, value);
+ }
+ },
+ { iterations: 500 }
+ );
+
+ console.log(`Batch Write (100 items): ${formatTime(batch100Result.mean)}`);
+ console.log(` Per item: ${formatTime(batch100Result.mean / 100)}`);
+
+ // Benchmark 3: Vector Write
+ const vectorWriteResult = await runner.run(
+ 'vector-write',
+ async () => {
+ const vector = generateVector(384);
+ vectorStore.set(`vec-${Date.now()}`, vector, { source: 'test' });
+ },
+ { iterations: 5000 }
+ );
+
+ console.log(`Vector Write (384d): ${formatTime(vectorWriteResult.mean)}`);
+
+ // Benchmark 4: Batch Vector Write (100 vectors)
+ const batchVectorResult = await runner.run(
+ 'batch-vector-write-100',
+ async () => {
+ for (let i = 0; i < 100; i++) {
+ const vector = generateVector(384);
+ vectorStore.set(`vec-${i}`, vector, { index: i });
+ }
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Batch Vector Write (100x 384d): ${formatTime(batchVectorResult.mean)}`);
+ console.log(` Per vector: ${formatTime(batchVectorResult.mean / 100)}`);
+
+ // Benchmark 5: Write-Ahead Log Append
+ const walAppendResult = await runner.run(
+ 'wal-append',
+ async () => {
+ wal.append('SET', 'key', { data: 'value' });
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`WAL Append: ${formatTime(walAppendResult.mean)}`);
+
+ // Benchmark 6: Batched Store Queue
+ const batchedQueueResult = await runner.run(
+ 'batched-store-queue',
+ async () => {
+ batchedStore.queue(`key-${Date.now()}`, { data: 'test' });
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`Batched Store Queue: ${formatTime(batchedQueueResult.mean)}`);
+
+ // Benchmark 7: Batched Store Flush
+ // Queue up items first
+ for (let i = 0; i < 100; i++) {
+ batchedStore.queue(`flush-key-${i}`, { data: i });
+ }
+
+ const batchedFlushResult = await runner.run(
+ 'batched-store-flush-100',
+ async () => {
+ // Queue and flush 100 items
+ for (let i = 0; i < 100; i++) {
+ batchedStore.queue(`key-${i}`, { data: i });
+ }
+ batchedStore.flush();
+ },
+ { iterations: 500 }
+ );
+
+ console.log(`Batched Flush (100 items): ${formatTime(batchedFlushResult.mean)}`);
+
+ // Benchmark 8: Object Serialization (JSON)
+ const testObject = {
+ id: 'test-123',
+ name: 'Test Object',
+ nested: { level1: { level2: { value: 42 } } },
+ array: Array.from({ length: 100 }, (_, i) => i),
+ timestamp: new Date().toISOString(),
+ };
+
+ const jsonSerializeResult = await runner.run(
+ 'json-serialize',
+ async () => {
+ JSON.stringify(testObject);
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`JSON Serialize: ${formatTime(jsonSerializeResult.mean)}`);
+
+ // Benchmark 9: Object Cloning (for immutability)
+ const cloneResult = await runner.run(
+ 'object-clone',
+ async () => {
+ const clone = structuredClone(testObject);
+ void clone;
+ },
+ { iterations: 5000 }
+ );
+
+ console.log(`Object Clone: ${formatTime(cloneResult.mean)}`);
+
+ // Benchmark 10: Concurrent Writes
+ const concurrentWriteResult = await runner.run(
+ 'concurrent-writes-10',
+ async () => {
+ await Promise.all(
+ Array.from({ length: 10 }, (_, i) =>
+ Promise.resolve(store.set(`concurrent-${i}`, { index: i }))
+ )
+ );
+ },
+ { iterations: 1000 }
+ );
+
+ console.log(`Concurrent Writes (10): ${formatTime(concurrentWriteResult.mean)}`);
+
+ // Benchmark 11: Large Value Write
+ const largeValue = {
+ data: 'x'.repeat(10000),
+ nested: Array.from({ length: 100 }, (_, i) => ({
+ id: i,
+ content: 'content'.repeat(10),
+ })),
+ };
+
+ const largeWriteResult = await runner.run(
+ 'large-value-write',
+ async () => {
+ store.set('large-key', largeValue);
+ },
+ { iterations: 1000 }
+ );
+
+ console.log(`Large Value Write (~100KB): ${formatTime(largeWriteResult.mean)}`);
+
+ // Summary
+ console.log('\n--- Summary ---');
+ console.log(`Single write: ${formatTime(singleWriteResult.mean)}`);
+ console.log(`Batched (100): ${formatTime(batch100Result.mean)} (${formatTime(batch100Result.mean / 100)}/item)`);
+ console.log(`Vector (384d): ${formatTime(vectorWriteResult.mean)}`);
+ console.log(`WAL append: ${formatTime(walAppendResult.mean)}`);
+ console.log(`Batch queue: ${formatTime(batchedQueueResult.mean)} (${(batchedQueueResult.opsPerSecond).toFixed(0)} ops/sec)`);
+
+ // Print full results
+ runner.printResults();
+}
+
+// ============================================================================
+// Memory Write Optimization Strategies
+// ============================================================================
+
+export const memoryWriteOptimizations = {
+ /**
+ * Write batching: Batch multiple writes together
+ */
+ writeBatching: {
+ description: 'Batch multiple writes and flush periodically',
+ expectedImprovement: '5-10x',
+ implementation: `
+ class BatchedWriter {
+ private batch: Write[] = [];
+ private batchSize = 100;
+ private flushInterval = 100; // ms
+
+ write(key: string, value: unknown): void {
+ this.batch.push({ key, value });
+ if (this.batch.length >= this.batchSize) {
+ this.flush();
+ }
+ }
+
+ private flush(): void {
+ const writes = this.batch;
+ this.batch = [];
+ for (const { key, value } of writes) {
+ this.store.set(key, value);
+ }
+ }
+ }
+ `,
+ },
+
+ /**
+ * Object pooling: Reuse objects to avoid allocation
+ */
+ objectPooling: {
+ description: 'Pool and reuse objects to reduce GC pressure',
+ expectedImprovement: '20-40%',
+ implementation: `
+ class ObjectPool<T> {
+ private pool: T[] = [];
+
+ acquire(): T {
+ return this.pool.pop() || this.create();
+ }
+
+ release(obj: T): void {
+ this.reset(obj);
+ this.pool.push(obj);
+ }
+ }
+ `,
+ },
+
+ /**
+ * Typed arrays: Use typed arrays for numeric data
+ */
+ typedArrays: {
+ description: 'Use Float32Array/Int32Array for numeric data',
+ expectedImprovement: '2-4x memory, 1.5-2x speed',
+ implementation: `
+ // Instead of:
+ const vector = new Array(384).fill(0);
+
+ // Use:
+ const vector = new Float32Array(384);
+ `,
+ },
+
+ /**
+ * Write-ahead logging: Append-only for durability
+ */
+ walLogging: {
+ description: 'Use append-only WAL for crash recovery',
+ expectedImprovement: 'Durability with <10% overhead',
+ implementation: `
+ class WAL {
+ private fd: number;
+
+ async append(entry: LogEntry): Promise<void> {
+ const data = Buffer.from(JSON.stringify(entry) + '\\n');
+ await fs.write(this.fd, data);
+ await fs.fdatasync(this.fd);
+ }
+ }
+ `,
+ },
+
+ /**
+ * Copy-on-write: Avoid unnecessary copying
+ */
+ copyOnWrite: {
+ description: 'Use COW semantics for large objects',
+ expectedImprovement: '30-50% for read-heavy workloads',
+ implementation: `
+ class COWStore {
+ private data = new Map<string, { value: unknown; version: number }>();
+
+ set(key: string, value: unknown): void {
+ const existing = this.data.get(key);
+ if (existing && deepEqual(existing.value, value)) {
+ return; // No change needed
+ }
+ this.data.set(key, { value, version: (existing?.version ?? 0) + 1 });
+ }
+ }
+ `,
+ },
+};
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+ runMemoryWriteBenchmarks().catch(console.error);
+}
+
+export default runMemoryWriteBenchmarks;
diff --git a/v3/@claude-flow/memory/benchmarks/vector-search.bench.ts b/v3/@claude-flow/memory/benchmarks/vector-search.bench.ts
new file mode 100644
index 0000000000..efc018a82a
--- /dev/null
+++ b/v3/@claude-flow/memory/benchmarks/vector-search.bench.ts
@@ -0,0 +1,449 @@
+/**
+ * Vector Search Benchmark
+ *
+ * Target: <1ms (150x faster than current ~150ms)
+ *
+ * Measures vector similarity search performance including
+ * linear search baseline vs HNSW optimized search.
+ */
+
+import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
+
+// ============================================================================
+// Vector Operations
+// ============================================================================
+
+/**
+ * Generate a random vector of specified dimension
+ */
+function generateVector(dimension: number): Float32Array {
+ const vector = new Float32Array(dimension);
+ for (let i = 0; i < dimension; i++) {
+ vector[i] = Math.random() * 2 - 1;
+ }
+ return normalizeVector(vector);
+}
+
+/**
+ * Normalize a vector to unit length
+ */
+function normalizeVector(vector: Float32Array): Float32Array {
+ let sum = 0;
+ for (let i = 0; i < vector.length; i++) {
+ sum += vector[i]! * vector[i]!;
+ }
+ const magnitude = Math.sqrt(sum);
+ if (magnitude > 0) {
+ for (let i = 0; i < vector.length; i++) {
+ vector[i]! /= magnitude;
+ }
+ }
+ return vector;
+}
+
+/**
+ * Calculate cosine similarity between two vectors
+ */
+function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+ let dot = 0;
+ for (let i = 0; i < a.length; i++) {
+ dot += a[i]! * b[i]!;
+ }
+ return dot;
+}
+
+/**
+ * Calculate Euclidean distance between two vectors
+ */
+function euclideanDistance(a: Float32Array, b: Float32Array): number {
+ let sum = 0;
+ for (let i = 0; i < a.length; i++) {
+ const diff = a[i]! - b[i]!;
+ sum += diff * diff;
+ }
+ return Math.sqrt(sum);
+}
+
+// ============================================================================
+// Search Implementations
+// ============================================================================
+
+interface SearchResult {
+ id: number;
+ score: number;
+}
+
+/**
+ * Linear (brute-force) search - O(n)
+ */
+function linearSearch(
+ query: Float32Array,
+ vectors: Float32Array[],
+ k: number
+): SearchResult[] {
+ const scores: SearchResult[] = vectors.map((v, i) => ({
+ id: i,
+ score: cosineSimilarity(query, v),
+ }));
+
+ scores.sort((a, b) => b.score - a.score);
+ return scores.slice(0, k);
+}
+
+/**
+ * Simple HNSW-like graph for approximate nearest neighbors
+ * Simplified implementation for benchmarking
+ */
+class SimpleHNSW {
+ private vectors: Float32Array[] = [];
+ private graph: Map<number, number[]> = new Map();
+ private entryPoint = 0;
+ private readonly maxConnections = 16;
+ private readonly efConstruction = 100;
+
+ add(vector: Float32Array): number {
+ const id = this.vectors.length;
+ this.vectors.push(vector);
+
+ if (id === 0) {
+ this.graph.set(id, []);
+ return id;
+ }
+
+ // Find nearest neighbors using current graph
+ const neighbors = this.searchLayer(vector, this.entryPoint, this.efConstruction);
+
+ // Connect to nearest neighbors
+ const connections = neighbors
+ .slice(0, this.maxConnections)
+ .map((r) => r.id);
+ this.graph.set(id, connections);
+
+ // Add reverse connections
+ for (const neighborId of connections) {
+ const neighborConnections = this.graph.get(neighborId) || [];
+ if (neighborConnections.length < this.maxConnections) {
+ neighborConnections.push(id);
+ this.graph.set(neighborId, neighborConnections);
+ }
+ }
+
+ return id;
+ }
+
+ search(query: Float32Array, k: number, ef = 50): SearchResult[] {
+ if (this.vectors.length === 0) return [];
+
+ const results = this.searchLayer(query, this.entryPoint, Math.max(k, ef));
+ return results.slice(0, k);
+ }
+
+ private searchLayer(
+ query: Float32Array,
+ entryPoint: number,
+ ef: number
+ ): SearchResult[] {
+ const visited = new Set<number>();
+ const candidates: SearchResult[] = [
+ { id: entryPoint, score: cosineSimilarity(query, this.vectors[entryPoint]!) },
+ ];
+ const results: SearchResult[] = [...candidates];
+
+ visited.add(entryPoint);
+
+ while (candidates.length > 0) {
+ candidates.sort((a, b) => b.score - a.score);
+ const current = candidates.shift()!;
+
+ const neighbors = this.graph.get(current.id) || [];
+ for (const neighborId of neighbors) {
+ if (visited.has(neighborId)) continue;
+ visited.add(neighborId);
+
+ const score = cosineSimilarity(query, this.vectors[neighborId]!);
+ results.push({ id: neighborId, score });
+ candidates.push({ id: neighborId, score });
+
+ if (results.length > ef) {
+ results.sort((a, b) => b.score - a.score);
+ results.length = ef;
+ }
+ }
+
+ if (candidates.length > ef) {
+ candidates.sort((a, b) => b.score - a.score);
+ candidates.length = ef;
+ }
+ }
+
+ results.sort((a, b) => b.score - a.score);
+ return results;
+ }
+
+ get size(): number {
+ return this.vectors.length;
+ }
+}
+
+// ============================================================================
+// Benchmark Suite
+// ============================================================================
+
+export async function runVectorSearchBenchmarks(): Promise<void> {
+ const runner = new BenchmarkRunner('Vector Search');
+
+ console.log('\n--- Vector Search Benchmarks ---\n');
+
+ const dimensions = 384; // Common embedding dimension
+ const k = 10; // Number of results to return
+
+ // Prepare test data
+ console.log('Preparing test data...');
+
+ // Small dataset (1,000 vectors)
+ const smallDataset = Array.from({ length: 1000 }, () => generateVector(dimensions));
+ const smallHNSW = new SimpleHNSW();
+ for (const v of smallDataset) {
+ smallHNSW.add(v);
+ }
+
+ // Medium dataset (10,000 vectors)
+ const mediumDataset = Array.from({ length: 10000 }, () => generateVector(dimensions));
+ const mediumHNSW = new SimpleHNSW();
+ for (const v of mediumDataset) {
+ mediumHNSW.add(v);
+ }
+
+ // Query vector
+ const query = generateVector(dimensions);
+
+ console.log('Test data prepared.\n');
+
+ // Benchmark 1: Linear Search - 1,000 vectors
+ const linear1kResult = await runner.run(
+ 'linear-search-1k',
+ async () => {
+ linearSearch(query, smallDataset, k);
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Linear Search (1k vectors): ${formatTime(linear1kResult.mean)}`);
+
+ // Benchmark 2: HNSW Search - 1,000 vectors
+ const hnsw1kResult = await runner.run(
+ 'hnsw-search-1k',
+ async () => {
+ smallHNSW.search(query, k);
+ },
+ { iterations: 500 }
+ );
+
+ console.log(`HNSW Search (1k vectors): ${formatTime(hnsw1kResult.mean)}`);
+ const speedup1k = linear1kResult.mean / hnsw1kResult.mean;
+ console.log(` Speedup: ${speedup1k.toFixed(1)}x`);
+
+ // Benchmark 3: Linear Search - 10,000 vectors
+ const linear10kResult = await runner.run(
+ 'linear-search-10k',
+ async () => {
+ linearSearch(query, mediumDataset, k);
+ },
+ { iterations: 20 }
+ );
+
+ console.log(`Linear Search (10k vectors): ${formatTime(linear10kResult.mean)}`);
+
+ // Benchmark 4: HNSW Search - 10,000 vectors
+ const hnsw10kResult = await runner.run(
+ 'hnsw-search-10k',
+ async () => {
+ mediumHNSW.search(query, k);
+ },
+ { iterations: 200 }
+ );
+
+ console.log(`HNSW Search (10k vectors): ${formatTime(hnsw10kResult.mean)}`);
+ const speedup10k = linear10kResult.mean / hnsw10kResult.mean;
+ console.log(` Speedup: ${speedup10k.toFixed(1)}x`);
+
+ // Check target
+ const target = meetsTarget('vector-search', hnsw10kResult.mean);
+ console.log(` Target (<1ms): ${target.met ? 'PASS' : 'FAIL'}`);
+
+ // Benchmark 5: Cosine Similarity Calculation
+ const v1 = generateVector(dimensions);
+ const v2 = generateVector(dimensions);
+
+ const cosineResult = await runner.run(
+ 'cosine-similarity',
+ async () => {
+ cosineSimilarity(v1, v2);
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`Cosine Similarity: ${formatTime(cosineResult.mean)}`);
+
+ // Benchmark 6: Euclidean Distance Calculation
+ const euclideanResult = await runner.run(
+ 'euclidean-distance',
+ async () => {
+ euclideanDistance(v1, v2);
+ },
+ { iterations: 10000 }
+ );
+
+ console.log(`Euclidean Distance: ${formatTime(euclideanResult.mean)}`);
+
+ // Benchmark 7: Vector Normalization
+ const normResult = await runner.run(
+ 'vector-normalization',
+ async () => {
+ const v = new Float32Array(dimensions);
+ for (let i = 0; i < dimensions; i++) {
+ v[i] = Math.random();
+ }
+ normalizeVector(v);
+ },
+ { iterations: 5000 }
+ );
+
+ console.log(`Vector Normalization: ${formatTime(normResult.mean)}`);
+
+ // Benchmark 8: Batch Search (5 queries)
+ const queries = Array.from({ length: 5 }, () => generateVector(dimensions));
+
+ const batchSearchResult = await runner.run(
+ 'batch-search-5-queries',
+ async () => {
+ for (const q of queries) {
+ smallHNSW.search(q, k);
+ }
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Batch Search (5 queries): ${formatTime(batchSearchResult.mean)}`);
+
+ // Benchmark 9: Parallel Batch Search
+ const parallelBatchResult = await runner.run(
+ 'parallel-batch-search',
+ async () => {
+ await Promise.all(queries.map((q) => Promise.resolve(smallHNSW.search(q, k))));
+ },
+ { iterations: 100 }
+ );
+
+ console.log(`Parallel Batch Search: ${formatTime(parallelBatchResult.mean)}`);
+
+ // Summary
+ console.log('\n--- Summary ---');
+ console.log(`1k vectors: Linear ${formatTime(linear1kResult.mean)} -> HNSW ${formatTime(hnsw1kResult.mean)} (${speedup1k.toFixed(1)}x)`);
+ console.log(`10k vectors: Linear ${formatTime(linear10kResult.mean)} -> HNSW ${formatTime(hnsw10kResult.mean)} (${speedup10k.toFixed(1)}x)`);
+ console.log(`\nProjected for 100k vectors: ~${((speedup10k * 10)).toFixed(0)}x improvement`);
+ console.log(`Projected for 1M vectors: ~${((speedup10k * 100)).toFixed(0)}x improvement`);
+
+ // Print full results
+ runner.printResults();
+}
+
+// ============================================================================
+// Vector Search Optimization Strategies
+// ============================================================================
+
+export const vectorSearchOptimizations = {
+ /**
+ * HNSW Indexing: Hierarchical Navigable Small World graphs
+ */
+ hnswIndexing: {
+ description: 'Use HNSW for O(log n) approximate nearest neighbor search',
+ expectedImprovement: '150x-12500x',
+ implementation: `
+ import { HNSW } from 'agentdb';
+
+ const index = new HNSW({
+ dimensions: 384,
+ maxElements: 1000000,
+ efConstruction: 200,
+ M: 16,
+ });
+
+ index.addItems(vectors);
+ const results = index.search(query, k);
+ `,
+ },
+
+ /**
+ * SIMD Operations: Use SIMD for vector math
+ */
+ simdOperations: {
+ description: 'Use SIMD instructions for parallel vector operations',
+ expectedImprovement: '4-8x',
+ implementation: `
+ // Use typed arrays and native SIMD when available
+ function dotProductSIMD(a: Float32Array, b: Float32Array): number {
+ // Node.js will use SIMD when available
+ let sum = 0;
+ for (let i = 0; i < a.length; i += 4) {
+ sum += a[i] * b[i] + a[i+1] * b[i+1] + a[i+2] * b[i+2] + a[i+3] * b[i+3];
+ }
+ return sum;
+ }
+ `,
+ },
+
+ /**
+ * Quantization: Use int8 instead of float32
+ */
+ quantization: {
+ description: 'Quantize vectors to int8 for 4x memory savings and faster ops',
+ expectedImprovement: '2-4x speed, 4x memory',
+ implementation: `
+ function quantize(vector: Float32Array): Int8Array {
+ const quantized = new Int8Array(vector.length);
+ for (let i = 0; i < vector.length; i++) {
+ quantized[i] = Math.round(vector[i] * 127);
+ }
+ return quantized;
+ }
+ `,
+ },
+
+ /**
+ * Batch Processing: Process multiple queries together
+ */
+ batchProcessing: {
+ description: 'Process multiple queries in a single batch for better cache utilization',
+ expectedImprovement: '2-5x',
+ implementation: `
+ async function batchSearch(queries: Float32Array[], k: number): Promise<SearchResult[][]> {
+ // Process all queries together for better cache locality
+ return queries.map(q => index.search(q, k));
+ }
+ `,
+ },
+
+ /**
+ * Pre-filtering: Reduce search space with metadata filters
+ */
+ preFiltering: {
+ description: 'Use metadata filters to reduce the search space before vector search',
+ expectedImprovement: '2-10x',
+ implementation: `
+ function filteredSearch(query: Float32Array, filter: Filter, k: number): SearchResult[] {
+ // First apply metadata filter
+ const candidates = applyFilter(filter);
+ // Then search only within filtered candidates
+ return searchWithinCandidates(query, candidates, k);
+ }
+ `,
+ },
+};
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+ runVectorSearchBenchmarks().catch(console.error);
+}
+
+export default runVectorSearchBenchmarks;
diff --git a/v3/@claude-flow/memory/package.json b/v3/@claude-flow/memory/package.json
new file mode 100644
index 0000000000..0475bbab73
--- /dev/null
+++ b/v3/@claude-flow/memory/package.json
@@ -0,0 +1,20 @@
+{
+ "name": "@claude-flow/memory",
+ "version": "3.0.0-alpha.1",
+ "type": "module",
+ "description": "Memory module - AgentDB unification, HNSW indexing, vector search",
+ "main": "src/index.ts",
+ "types": "src/index.ts",
+ "exports": {
+ ".": "./src/index.ts",
+ "./*": "./src/*.ts"
+ },
+ "scripts": {
+ "test": "vitest run",
+ "bench": "vitest bench",
+ "build": "tsc"
+ },
+ "devDependencies": {
+ "vitest": "^1.0.0"
+ }
+}
diff --git a/v3/@claude-flow/memory/src/agentdb-adapter.ts b/v3/@claude-flow/memory/src/agentdb-adapter.ts
new file mode 100644
index 0000000000..7ea6e9c888
--- /dev/null
+++ b/v3/@claude-flow/memory/src/agentdb-adapter.ts
@@ -0,0 +1,884 @@
+/**
+ * V3 AgentDB Adapter
+ *
+ * Unified memory backend implementation using AgentDB with HNSW indexing
+ * for 150x-12,500x faster vector search. Implements IMemoryBackend interface.
+ *
+ * @module v3/memory/agentdb-adapter
+ */
+
+import { EventEmitter } from 'node:events';
+import {
+ IMemoryBackend,
+ MemoryEntry,
+ MemoryEntryInput,
+ MemoryEntryUpdate,
+ MemoryQuery,
+ SearchOptions,
+ SearchResult,
+ BackendStats,
+ HealthCheckResult,
+ ComponentHealth,
+ MemoryType,
+ EmbeddingGenerator,
+ generateMemoryId,
+ createDefaultEntry,
+ CacheStats,
+ HNSWStats,
+} from './types.js';
+import { HNSWIndex } from './hnsw-index.js';
+import { CacheManager } from './cache-manager.js';
+
+/**
+ * Configuration for AgentDB Adapter
+ */
+export interface AgentDBAdapterConfig {
+ /** Vector dimensions for embeddings (default: 1536 for OpenAI) */
+ dimensions: number;
+
+ /** Maximum number of entries */
+ maxEntries: number;
+
+ /** Enable caching */
+ cacheEnabled: boolean;
+
+ /** Maximum cache size */
+ cacheSize: number;
+
+ /** Cache TTL in milliseconds */
+ cacheTtl: number;
+
+ /** HNSW M parameter (max connections per layer) */
+ hnswM: number;
+
+ /** HNSW efConstruction parameter */
+ hnswEfConstruction: number;
+
+ /** Default namespace */
+ defaultNamespace: string;
+
+ /** Embedding generator function */
+ embeddingGenerator?: EmbeddingGenerator;
+
+ /** Enable persistence to disk */
+ persistenceEnabled: boolean;
+
+ /** Persistence path */
+ persistencePath?: string;
+}
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG: AgentDBAdapterConfig = {
+ dimensions: 1536,
+ maxEntries: 1000000,
+ cacheEnabled: true,
+ cacheSize: 10000,
+ cacheTtl: 300000, // 5 minutes
+ hnswM: 16,
+ hnswEfConstruction: 200,
+ defaultNamespace: 'default',
+ persistenceEnabled: false,
+};
+
+/**
+ * AgentDB Memory Backend Adapter
+ *
+ * Provides unified memory storage with:
+ * - HNSW-based vector search (150x-12,500x faster than brute force)
+ * - LRU caching with TTL support
+ * - Namespace-based organization
+ * - Full-text and metadata filtering
+ * - Event-driven architecture
+ */
+export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {
+ private config: AgentDBAdapterConfig;
+ private entries: Map<string, MemoryEntry> = new Map();
+ private index: HNSWIndex;
+ private cache: CacheManager<MemoryEntry>;
+ private namespaceIndex: Map<string, Set<string>> = new Map();
+ private keyIndex: Map<string, string> = new Map(); // namespace:key -> id
+ private tagIndex: Map<string, Set<string>> = new Map();
+ private initialized: boolean = false;
+
+ // Performance tracking
+ private stats = {
+ queryCount: 0,
+ totalQueryTime: 0,
+ searchCount: 0,
+ totalSearchTime: 0,
+ writeCount: 0,
+ totalWriteTime: 0,
+ };
+
+ constructor(config: Partial<AgentDBAdapterConfig> = {}) {
+ super();
+ this.config = { ...DEFAULT_CONFIG, ...config };
+
+ // Initialize HNSW index
+ this.index = new HNSWIndex({
+ dimensions: this.config.dimensions,
+ M: this.config.hnswM,
+ efConstruction: this.config.hnswEfConstruction,
+ maxElements: this.config.maxEntries,
+ metric: 'cosine',
+ });
+
+ // Initialize cache
+ this.cache = new CacheManager<MemoryEntry>({
+ maxSize: this.config.cacheSize,
+ ttl: this.config.cacheTtl,
+ lruEnabled: true,
+ });
+
+ // Forward events
+ this.index.on('point:added', (data) => this.emit('index:added', data));
+ this.cache.on('cache:hit', (data) => this.emit('cache:hit', data));
+ this.cache.on('cache:miss', (data) => this.emit('cache:miss', data));
+ }
+
+ /**
+ * Initialize the adapter
+ */
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+
+ // Load persisted data if enabled
+ if (this.config.persistenceEnabled && this.config.persistencePath) {
+ await this.loadFromDisk();
+ }
+
+ this.initialized = true;
+ this.emit('initialized');
+ }
+
+ /**
+ * Shutdown the adapter
+ */
+ async shutdown(): Promise<void> {
+ if (!this.initialized) return;
+
+ // Persist data if enabled
+ if (this.config.persistenceEnabled && this.config.persistencePath) {
+ await this.saveToDisk();
+ }
+
+ this.cache.shutdown();
+ this.initialized = false;
+ this.emit('shutdown');
+ }
+
+ /**
+ * Store a memory entry
+ */
+ async store(entry: MemoryEntry): Promise<void> {
+ const startTime = performance.now();
+
+ // Generate embedding if content provided but no embedding
+ if (entry.content && !entry.embedding && this.config.embeddingGenerator) {
+ entry.embedding = await this.config.embeddingGenerator(entry.content);
+ }
+
+ // Store in main storage
+ this.entries.set(entry.id, entry);
+
+ // Update namespace index
+ const namespace = entry.namespace || this.config.defaultNamespace;
+ if (!this.namespaceIndex.has(namespace)) {
+ this.namespaceIndex.set(namespace, new Set());
+ }
+ this.namespaceIndex.get(namespace)!.add(entry.id);
+
+ // Update key index
+ const keyIndexKey = `${namespace}:${entry.key}`;
+ this.keyIndex.set(keyIndexKey, entry.id);
+
+ // Update tag index
+ for (const tag of entry.tags) {
+ if (!this.tagIndex.has(tag)) {
+ this.tagIndex.set(tag, new Set());
+ }
+ this.tagIndex.get(tag)!.add(entry.id);
+ }
+
+ // Index embedding if available
+ if (entry.embedding) {
+ await this.index.addPoint(entry.id, entry.embedding);
+ }
+
+ // Update cache
+ if (this.config.cacheEnabled) {
+ this.cache.set(entry.id, entry);
+ }
+
+ const duration = performance.now() - startTime;
+ this.stats.writeCount++;
+ this.stats.totalWriteTime += duration;
+
+ this.emit('entry:stored', { id: entry.id, duration });
+ }
+
+ /**
+ * Get a memory entry by ID
+ */
+ async get(id: string): Promise<MemoryEntry | null> {
+ // Check cache first
+ if (this.config.cacheEnabled) {
+ const cached = this.cache.get(id);
+ if (cached) {
+ this.updateAccessStats(cached);
+ return cached;
+ }
+ }
+
+ const entry = this.entries.get(id);
+ if (entry) {
+ this.updateAccessStats(entry);
+ if (this.config.cacheEnabled) {
+ this.cache.set(id, entry);
+ }
+ }
+
+ return entry || null;
+ }
+
+ /**
+ * Get a memory entry by key within a namespace
+ */
+ async getByKey(namespace: string, key: string): Promise<MemoryEntry | null> {
+ const keyIndexKey = `${namespace}:${key}`;
+ const id = this.keyIndex.get(keyIndexKey);
+ if (!id) return null;
+ return this.get(id);
+ }
+
+ /**
+ * Update a memory entry
+ */
+ async update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null> {
+ const entry = this.entries.get(id);
+ if (!entry) return null;
+
+ // Apply updates
+ if (update.content !== undefined) {
+ entry.content = update.content;
+ // Regenerate embedding if content changed
+ if (this.config.embeddingGenerator) {
+ entry.embedding = await this.config.embeddingGenerator(entry.content);
+ // Re-index
+ await this.index.removePoint(id);
+ await this.index.addPoint(id, entry.embedding);
+ }
+ }
+
+ if (update.tags !== undefined) {
+ // Update tag index
+ for (const oldTag of entry.tags) {
+ this.tagIndex.get(oldTag)?.delete(id);
+ }
+ entry.tags = update.tags;
+ for (const newTag of update.tags) {
+ if (!this.tagIndex.has(newTag)) {
+ this.tagIndex.set(newTag, new Set());
+ }
+ this.tagIndex.get(newTag)!.add(id);
+ }
+ }
+
+ if (update.metadata !== undefined) {
+ entry.metadata = { ...entry.metadata, ...update.metadata };
+ }
+
+ if (update.accessLevel !== undefined) {
+ entry.accessLevel = update.accessLevel;
+ }
+
+ if (update.expiresAt !== undefined) {
+ entry.expiresAt = update.expiresAt;
+ }
+
+ if (update.references !== undefined) {
+ entry.references = update.references;
+ }
+
+ entry.updatedAt = Date.now();
+ entry.version++;
+
+ // Update cache
+ if (this.config.cacheEnabled) {
+ this.cache.set(id, entry);
+ }
+
+ this.emit('entry:updated', { id });
+ return entry;
+ }
+
+ /**
+ * Delete a memory entry
+ */
+ async delete(id: string): Promise<boolean> {
+ const entry = this.entries.get(id);
+ if (!entry) return false;
+
+ // Remove from main storage
+ this.entries.delete(id);
+
+ // Remove from namespace index
+ this.namespaceIndex.get(entry.namespace)?.delete(id);
+
+ // Remove from key index
+ const keyIndexKey = `${entry.namespace}:${entry.key}`;
+ this.keyIndex.delete(keyIndexKey);
+
+ // Remove from tag index
+ for (const tag of entry.tags) {
+ this.tagIndex.get(tag)?.delete(id);
+ }
+
+ // Remove from vector index
+ if (entry.embedding) {
+ await this.index.removePoint(id);
+ }
+
+ // Remove from cache
+ if (this.config.cacheEnabled) {
+ this.cache.delete(id);
+ }
+
+ this.emit('entry:deleted', { id });
+ return true;
+ }
+
+ /**
+ * Query memory entries with filters
+ */
+ async query(query: MemoryQuery): Promise<MemoryEntry[]> {
+ const startTime = performance.now();
+ let results: MemoryEntry[] = [];
+
+ switch (query.type) {
+ case 'exact':
+ if (query.key && query.namespace) {
+ const entry = await this.getByKey(query.namespace, query.key);
+ if (entry) results = [entry];
+ }
+ break;
+
+ case 'prefix':
+ results = this.queryByPrefix(query);
+ break;
+
+ case 'tag':
+ results = this.queryByTags(query);
+ break;
+
+ case 'semantic':
+ case 'hybrid':
+ results = await this.querySemanticWithFilters(query);
+ break;
+
+ default:
+ results = this.queryWithFilters(query);
+ }
+
+ // Apply common filters
+ results = this.applyFilters(results, query);
+
+ // Apply pagination
+ const offset = query.offset || 0;
+ results = results.slice(offset, offset + query.limit);
+
+ const duration = performance.now() - startTime;
+ this.stats.queryCount++;
+ this.stats.totalQueryTime += duration;
+
+ return results;
+ }
+
+ /**
+ * Semantic vector search
+ */
+ async search(
+ embedding: Float32Array,
+ options: SearchOptions
+ ): Promise<SearchResult[]> {
+ const startTime = performance.now();
+
+ const indexResults = await this.index.search(embedding, options.k, options.ef);
+
+ const results: SearchResult[] = [];
+ for (const { id, distance } of indexResults) {
+ const entry = this.entries.get(id);
+ if (!entry) continue;
+
+ // Apply threshold filter
+ const score = 1 - distance; // Convert distance to similarity
+ if (options.threshold && score < options.threshold) continue;
+
+ // Apply additional filters if provided
+ if (options.filters) {
+ const filtered = this.applyFilters([entry], options.filters);
+ if (filtered.length === 0) continue;
+ }
+
+ results.push({ entry, score, distance });
+ }
+
+ const duration = performance.now() - startTime;
+ this.stats.searchCount++;
+ this.stats.totalSearchTime += duration;
+
+ return results;
+ }
+
+ /**
+ * Bulk insert entries
+ */
+ async bulkInsert(entries: MemoryEntry[]): Promise<void> {
+ const startTime = performance.now();
+
+ for (const entry of entries) {
+ await this.store(entry);
+ }
+
+ const duration = performance.now() - startTime;
+ this.emit('bulk:inserted', { count: entries.length, duration });
+ }
+
+ /**
+ * Bulk delete entries
+ */
+ async bulkDelete(ids: string[]): Promise<number> {
+ let deleted = 0;
+ for (const id of ids) {
+ if (await this.delete(id)) {
+ deleted++;
+ }
+ }
+ return deleted;
+ }
+
+ /**
+ * Get entry count
+ */
+ async count(namespace?: string): Promise<number> {
+ if (namespace) {
+ return this.namespaceIndex.get(namespace)?.size || 0;
+ }
+ return this.entries.size;
+ }
+
+ /**
+ * List all namespaces
+ */
+ async listNamespaces(): Promise<string[]> {
+ return Array.from(this.namespaceIndex.keys());
+ }
+
+ /**
+ * Clear all entries in a namespace
+ */
+ async clearNamespace(namespace: string): Promise<number> {
+ const ids = this.namespaceIndex.get(namespace);
+ if (!ids) return 0;
+
+ let deleted = 0;
+ for (const id of ids) {
+ if (await this.delete(id)) {
+ deleted++;
+ }
+ }
+
+ return deleted;
+ }
+
+ /**
+ * Get backend statistics
+ */
+ async getStats(): Promise<BackendStats> {
+ const entriesByNamespace: Record<string, number> = {};
+ for (const [namespace, ids] of this.namespaceIndex) {
+ entriesByNamespace[namespace] = ids.size;
+ }
+
+ const entriesByType: Record<MemoryType, number> = {
+ episodic: 0,
+ semantic: 0,
+ procedural: 0,
+ working: 0,
+ cache: 0,
+ };
+
+ for (const entry of this.entries.values()) {
+ entriesByType[entry.type]++;
+ }
+
+ return {
+ totalEntries: this.entries.size,
+ entriesByNamespace,
+ entriesByType,
+ memoryUsage: this.estimateMemoryUsage(),
+ hnswStats: this.index.getStats(),
+ cacheStats: this.cache.getStats(),
+ avgQueryTime:
+ this.stats.queryCount > 0
+ ? this.stats.totalQueryTime / this.stats.queryCount
+ : 0,
+ avgSearchTime:
+ this.stats.searchCount > 0
+ ? this.stats.totalSearchTime / this.stats.searchCount
+ : 0,
+ };
+ }
+
+ /**
+ * Perform health check
+ */
+ async healthCheck(): Promise<HealthCheckResult> {
+ const issues: string[] = [];
+ const recommendations: string[] = [];
+
+ // Check storage health
+ const storageHealth = this.checkStorageHealth(issues, recommendations);
+
+ // Check index health
+ const indexHealth = this.checkIndexHealth(issues, recommendations);
+
+ // Check cache health
+ const cacheHealth = this.checkCacheHealth(issues, recommendations);
+
+ // Determine overall status
+ let status: 'healthy' | 'degraded' | 'unhealthy' = 'healthy';
+ if (
+ storageHealth.status === 'unhealthy' ||
+ indexHealth.status === 'unhealthy' ||
+ cacheHealth.status === 'unhealthy'
+ ) {
+ status = 'unhealthy';
+ } else if (
+ storageHealth.status === 'degraded' ||
+ indexHealth.status === 'degraded' ||
+ cacheHealth.status === 'degraded'
+ ) {
+ status = 'degraded';
+ }
+
+ return {
+ status,
+ components: {
+ storage: storageHealth,
+ index: indexHealth,
+ cache: cacheHealth,
+ },
+ timestamp: Date.now(),
+ issues,
+ recommendations,
+ };
+ }
+
+ // ===== Convenience Methods =====
+
+ /**
+ * Store a new entry from input
+ */
+ async storeEntry(input: MemoryEntryInput): Promise<MemoryEntry> {
+ const entry = createDefaultEntry(input);
+ await this.store(entry);
+ return entry;
+ }
+
+ /**
+ * Semantic search by content string
+ */
+ async semanticSearch(
+ content: string,
+ k: number = 10,
+ threshold?: number
+ ): Promise<SearchResult[]> {
+ if (!this.config.embeddingGenerator) {
+ throw new Error('Embedding generator not configured');
+ }
+
+ const embedding = await this.config.embeddingGenerator(content);
+ return this.search(embedding, { k, threshold });
+ }
+
+ // ===== Private Methods =====
+
+ private queryByPrefix(query: MemoryQuery): MemoryEntry[] {
+ const results: MemoryEntry[] = [];
+ const prefix = query.keyPrefix || '';
+ const namespace = query.namespace || this.config.defaultNamespace;
+
+ for (const [key, id] of this.keyIndex) {
+ if (key.startsWith(`${namespace}:${prefix}`)) {
+ const entry = this.entries.get(id);
+ if (entry) results.push(entry);
+ }
+ }
+
+ return results;
+ }
+
+ private queryByTags(query: MemoryQuery): MemoryEntry[] {
+ if (!query.tags || query.tags.length === 0) {
+ return Array.from(this.entries.values());
+ }
+
+ // Get intersection of entries for all tags
+ let matchingIds: Set<string> | null = null;
+
+ for (const tag of query.tags) {
+ const tagIds = this.tagIndex.get(tag);
+ if (!tagIds) {
+ return []; // Tag doesn't exist
+ }
+
+ if (matchingIds === null) {
+ matchingIds = new Set(tagIds);
+ } else {
+ // Intersect with previous results
+ for (const id of matchingIds) {
+ if (!tagIds.has(id)) {
+ matchingIds.delete(id);
+ }
+ }
+ }
+ }
+
+ if (!matchingIds) return [];
+
+ const results: MemoryEntry[] = [];
+ for (const id of matchingIds) {
+ const entry = this.entries.get(id);
+ if (entry) results.push(entry);
+ }
+
+ return results;
+ }
+
+ private async querySemanticWithFilters(
+ query: MemoryQuery
+ ): Promise<MemoryEntry[]> {
+ if (!query.content && !query.embedding) {
+ return this.queryWithFilters(query);
+ }
+
+ let embedding = query.embedding;
+ if (!embedding && query.content && this.config.embeddingGenerator) {
+ embedding = await this.config.embeddingGenerator(query.content);
+ }
+
+ if (!embedding) {
+ return this.queryWithFilters(query);
+ }
+
+ const searchResults = await this.search(embedding, {
+ k: query.limit * 2, // Over-fetch for filtering
+ threshold: query.threshold,
+ filters: query,
+ });
+
+ return searchResults.map((r) => r.entry);
+ }
+
+ private queryWithFilters(query: MemoryQuery): MemoryEntry[] {
+ let entries: MemoryEntry[] = [];
+
+ // Start with namespace filter if provided
+ if (query.namespace) {
+ const namespaceIds = this.namespaceIndex.get(query.namespace);
+ if (!namespaceIds) return [];
+ for (const id of namespaceIds) {
+ const entry = this.entries.get(id);
+ if (entry) entries.push(entry);
+ }
+ } else {
+ entries = Array.from(this.entries.values());
+ }
+
+ return entries;
+ }
+
+ private applyFilters(
+ entries: MemoryEntry[],
+ query: MemoryQuery
+ ): MemoryEntry[] {
+ return entries.filter((entry) => {
+ // Namespace filter
+ if (query.namespace && entry.namespace !== query.namespace) {
+ return false;
+ }
+
+ // Memory type filter
+ if (query.memoryType && entry.type !== query.memoryType) {
+ return false;
+ }
+
+ // Access level filter
+ if (query.accessLevel && entry.accessLevel !== query.accessLevel) {
+ return false;
+ }
+
+ // Owner filter
+ if (query.ownerId && entry.ownerId !== query.ownerId) {
+ return false;
+ }
+
+ // Tags filter
+ if (query.tags && query.tags.length > 0) {
+ if (!query.tags.every((tag) => entry.tags.includes(tag))) {
+ return false;
+ }
+ }
+
+ // Time range filters
+ if (query.createdAfter && entry.createdAt < query.createdAfter) {
+ return false;
+ }
+ if (query.createdBefore && entry.createdAt > query.createdBefore) {
+ return false;
+ }
+ if (query.updatedAfter && entry.updatedAt < query.updatedAfter) {
+ return false;
+ }
+ if (query.updatedBefore && entry.updatedAt > query.updatedBefore) {
+ return false;
+ }
+
+ // Expiration filter
+ if (!query.includeExpired && entry.expiresAt) {
+ if (entry.expiresAt < Date.now()) {
+ return false;
+ }
+ }
+
+ // Metadata filters
+ if (query.metadata) {
+ for (const [key, value] of Object.entries(query.metadata)) {
+ if (entry.metadata[key] !== value) {
+ return false;
+ }
+ }
+ }
+
+ return true;
+ });
+ }
+
+ private updateAccessStats(entry: MemoryEntry): void {
+ entry.accessCount++;
+ entry.lastAccessedAt = Date.now();
+ }
+
+ private estimateMemoryUsage(): number {
+ let total = 0;
+
+ // Estimate entry storage
+ for (const entry of this.entries.values()) {
+ total += this.estimateEntrySize(entry);
+ }
+
+ // Add index memory
+ total += this.index.getStats().memoryUsage;
+
+ // Add cache memory
+ total += this.cache.getStats().memoryUsage;
+
+ return total;
+ }
+
+ private estimateEntrySize(entry: MemoryEntry): number {
+ let size = 0;
+
+ // Base object overhead
+ size += 100;
+
+ // String fields
+ size += (entry.id.length + entry.key.length + entry.content.length) * 2;
+
+ // Embedding (Float32Array)
+ if (entry.embedding) {
+ size += entry.embedding.length * 4;
+ }
+
+ // Tags and references
+ size += entry.tags.join('').length * 2;
+ size += entry.references.join('').length * 2;
+
+ // Metadata (rough estimate)
+ size += JSON.stringify(entry.metadata).length * 2;
+
+ return size;
+ }
+
+ private checkStorageHealth(
+ issues: string[],
+ recommendations: string[]
+ ): ComponentHealth {
+ const utilizationPercent =
+ (this.entries.size / this.config.maxEntries) * 100;
+
+ if (utilizationPercent > 95) {
+ issues.push('Storage utilization critical (>95%)');
+ recommendations.push('Increase maxEntries or cleanup old data');
+ return { status: 'unhealthy', latency: 0, message: 'Storage near capacity' };
+ }
+
+ if (utilizationPercent > 80) {
+ issues.push('Storage utilization high (>80%)');
+ recommendations.push('Consider cleanup or capacity increase');
+ return { status: 'degraded', latency: 0, message: 'Storage utilization high' };
+ }
+
+ return { status: 'healthy', latency: 0 };
+ }
+
+ private checkIndexHealth(
+ issues: string[],
+ recommendations: string[]
+ ): ComponentHealth {
+ const stats = this.index.getStats();
+
+ if (stats.avgSearchTime > 10) {
+ issues.push('Index search time degraded (>10ms)');
+ recommendations.push('Consider rebuilding index or increasing ef');
+ return { status: 'degraded', latency: stats.avgSearchTime };
+ }
+
+ return { status: 'healthy', latency: stats.avgSearchTime };
+ }
+
+ private checkCacheHealth(
+ issues: string[],
+ recommendations: string[]
+ ): ComponentHealth {
+ const stats = this.cache.getStats();
+
+ if (stats.hitRate < 0.5) {
+ issues.push('Cache hit rate low (<50%)');
+ recommendations.push('Consider increasing cache size');
+ return {
+ status: 'degraded',
+ latency: 0,
+ message: `Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`,
+ };
+ }
+
+ return { status: 'healthy', latency: 0 };
+ }
+
+ private async loadFromDisk(): Promise<void> {
+ // Placeholder for persistence implementation
+ // Would use SQLite or file-based storage
+ this.emit('persistence:loaded');
+ }
+
+ private async saveToDisk(): Promise<void> {
+ // Placeholder for persistence implementation
+ this.emit('persistence:saved');
+ }
+}
+
+export default AgentDBAdapter;
diff --git a/v3/@claude-flow/memory/src/cache-manager.ts b/v3/@claude-flow/memory/src/cache-manager.ts
new file mode 100644
index 0000000000..83089cf703
--- /dev/null
+++ b/v3/@claude-flow/memory/src/cache-manager.ts
@@ -0,0 +1,516 @@
+/**
+ * V3 Cache Manager
+ *
+ * High-performance LRU cache with TTL support, memory pressure handling,
+ * and write-through caching for the unified memory system.
+ *
+ * @module v3/memory/cache-manager
+ */
+
+import { EventEmitter } from 'node:events';
+import {
+ CacheConfig,
+ CacheStats,
+ CachedEntry,
+ MemoryEntry,
+ MemoryEvent,
+} from './types.js';
+
+/**
+ * Doubly-linked list node for LRU implementation
+ */
+interface LRUNode<T> {
+ key: string;
+ value: CachedEntry<T>;
+ prev: LRUNode<T> | null;
+ next: LRUNode<T> | null;
+}
+
+/**
+ * High-performance LRU Cache with TTL support
+ *
+ * Features:
+ * - O(1) get, set, delete operations
+ * - LRU eviction policy
+ * - TTL-based expiration
+ * - Memory pressure handling
+ * - Write-through caching support
+ * - Performance statistics
+ */
+export class CacheManager<T = MemoryEntry> extends EventEmitter {
+ private config: CacheConfig;
+ private cache: Map<string, LRUNode<T>> = new Map();
+ private head: LRUNode<T> | null = null;
+ private tail: LRUNode<T> | null = null;
+ private currentMemory: number = 0;
+
+ // Statistics
+ private stats: {
+ hits: number;
+ misses: number;
+ evictions: number;
+ expirations: number;
+ writes: number;
+ } = {
+ hits: 0,
+ misses: 0,
+ evictions: 0,
+ expirations: 0,
+ writes: 0,
+ };
+
+ // Cleanup timer
+ private cleanupInterval: NodeJS.Timeout | null = null;
+
+ constructor(config: Partial<CacheConfig> = {}) {
+ super();
+ this.config = this.mergeConfig(config);
+ this.startCleanupTimer();
+ }
+
+ /**
+ * Get a value from the cache
+ */
+ get(key: string): T | null {
+ const node = this.cache.get(key);
+
+ if (!node) {
+ this.stats.misses++;
+ this.emit('cache:miss', { key });
+ return null;
+ }
+
+ // Check if expired
+ if (this.isExpired(node.value)) {
+ this.delete(key);
+ this.stats.misses++;
+ this.stats.expirations++;
+ this.emit('cache:expired', { key });
+ return null;
+ }
+
+ // Update access time and count
+ node.value.lastAccessedAt = Date.now();
+ node.value.accessCount++;
+
+ // Move to front (most recently used)
+ this.moveToFront(node);
+
+ this.stats.hits++;
+ this.emit('cache:hit', { key });
+
+ return node.value.data;
+ }
+
+ /**
+ * Set a value in the cache
+ */
+ set(key: string, data: T, ttl?: number): void {
+ const now = Date.now();
+ const entryTtl = ttl || this.config.ttl;
+
+ // Check if key already exists
+ const existingNode = this.cache.get(key);
+ if (existingNode) {
+ // Update existing entry
+ existingNode.value.data = data;
+ existingNode.value.cachedAt = now;
+ existingNode.value.expiresAt = now + entryTtl;
+ existingNode.value.lastAccessedAt = now;
+
+ this.moveToFront(existingNode);
+ this.stats.writes++;
+ return;
+ }
+
+ // Calculate memory for new entry
+ const entryMemory = this.estimateSize(data);
+
+ // Evict entries if needed for memory pressure
+ if (this.config.maxMemory) {
+ while (
+ this.currentMemory + entryMemory > this.config.maxMemory &&
+ this.cache.size > 0
+ ) {
+ this.evictLRU();
+ }
+ }
+
+ // Evict entries if at capacity
+ while (this.cache.size >= this.config.maxSize) {
+ this.evictLRU();
+ }
+
+ // Create new node
+ const cachedEntry: CachedEntry<T> = {
+ data,
+ cachedAt: now,
+ expiresAt: now + entryTtl,
+ lastAccessedAt: now,
+ accessCount: 0,
+ };
+
+ const node: LRUNode<T> = {
+ key,
+ value: cachedEntry,
+ prev: null,
+ next: null,
+ };
+
+ // Add to cache
+ this.cache.set(key, node);
+ this.addToFront(node);
+ this.currentMemory += entryMemory;
+ this.stats.writes++;
+
+ this.emit('cache:set', { key, ttl: entryTtl });
+ }
+
+ /**
+ * Delete a value from the cache
+ */
+ delete(key: string): boolean {
+ const node = this.cache.get(key);
+ if (!node) {
+ return false;
+ }
+
+ this.removeNode(node);
+ this.cache.delete(key);
+ this.currentMemory -= this.estimateSize(node.value.data);
+
+ this.emit('cache:delete', { key });
+ return true;
+ }
+
+ /**
+ * Check if a key exists in the cache (without affecting LRU order)
+ */
+ has(key: string): boolean {
+ const node = this.cache.get(key);
+ if (!node) return false;
+ if (this.isExpired(node.value)) {
+ this.delete(key);
+ return false;
+ }
+ return true;
+ }
+
+ /**
+ * Clear all entries from the cache
+ */
+ clear(): void {
+ this.cache.clear();
+ this.head = null;
+ this.tail = null;
+ this.currentMemory = 0;
+
+ this.emit('cache:cleared', { previousSize: this.cache.size });
+ }
+
+ /**
+ * Get cache statistics
+ */
+ getStats(): CacheStats {
+ const total = this.stats.hits + this.stats.misses;
+ return {
+ size: this.cache.size,
+ hitRate: total > 0 ? this.stats.hits / total : 0,
+ hits: this.stats.hits,
+ misses: this.stats.misses,
+ evictions: this.stats.evictions,
+ memoryUsage: this.currentMemory,
+ };
+ }
+
+ /**
+ * Get all keys in the cache
+ */
+ keys(): string[] {
+ return Array.from(this.cache.keys());
+ }
+
+ /**
+ * Get the size of the cache
+ */
+ get size(): number {
+ return this.cache.size;
+ }
+
+ /**
+ * Prefetch multiple keys in a single batch
+ */
+ async prefetch(
+ keys: string[],
+ loader: (keys: string[]) => Promise<Map<string, T>>,
+ ttl?: number
+ ): Promise<void> {
+ const missing = keys.filter((key) => !this.has(key));
+
+ if (missing.length === 0) {
+ return;
+ }
+
+ const data = await loader(missing);
+
+ for (const [key, value] of data) {
+ this.set(key, value, ttl);
+ }
+
+ this.emit('cache:prefetched', { keys: missing.length });
+ }
+
+ /**
+ * Get or set pattern - get from cache or load and cache
+ */
+ async getOrSet(
+ key: string,
+ loader: () => Promise<T>,
+ ttl?: number
+ ): Promise<T> {
+ const cached = this.get(key);
+ if (cached !== null) {
+ return cached;
+ }
+
+ const data = await loader();
+ this.set(key, data, ttl);
+ return data;
+ }
+
+ /**
+ * Warm the cache with initial data
+ */
+ warmUp(entries: Array<{ key: string; data: T; ttl?: number }>): void {
+ for (const entry of entries) {
+ this.set(entry.key, entry.data, entry.ttl);
+ }
+ this.emit('cache:warmedUp', { count: entries.length });
+ }
+
+ /**
+ * Invalidate entries matching a pattern
+ */
+ invalidatePattern(pattern: string | RegExp): number {
+ const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+ let invalidated = 0;
+
+ for (const key of this.cache.keys()) {
+ if (regex.test(key)) {
+ this.delete(key);
+ invalidated++;
+ }
+ }
+
+ this.emit('cache:invalidated', { pattern: pattern.toString(), count: invalidated });
+ return invalidated;
+ }
+
+ /**
+ * Shutdown the cache manager
+ */
+ shutdown(): void {
+ if (this.cleanupInterval) {
+ clearInterval(this.cleanupInterval);
+ this.cleanupInterval = null;
+ }
+ this.clear();
+ this.emit('cache:shutdown');
+ }
+
+ // ===== Private Methods =====
+
+ private mergeConfig(config: Partial<CacheConfig>): CacheConfig {
+ return {
+ maxSize: config.maxSize || 10000,
+ ttl: config.ttl || 300000, // 5 minutes default
+ lruEnabled: config.lruEnabled !== false,
+ maxMemory: config.maxMemory,
+ writeThrough: config.writeThrough || false,
+ };
+ }
+
+ private isExpired(entry: CachedEntry<T>): boolean {
+ return Date.now() > entry.expiresAt;
+ }
+
+ private estimateSize(data: T): number {
+ try {
+ return JSON.stringify(data).length * 2; // Rough UTF-16 estimate
+ } catch {
+ return 1000; // Default for non-serializable objects
+ }
+ }
+
+ private addToFront(node: LRUNode<T>): void {
+ node.prev = null;
+ node.next = this.head;
+
+ if (this.head) {
+ this.head.prev = node;
+ }
+
+ this.head = node;
+
+ if (!this.tail) {
+ this.tail = node;
+ }
+ }
+
+ private removeNode(node: LRUNode<T>): void {
+ if (node.prev) {
+ node.prev.next = node.next;
+ } else {
+ this.head = node.next;
+ }
+
+ if (node.next) {
+ node.next.prev = node.prev;
+ } else {
+ this.tail = node.prev;
+ }
+ }
+
+ private moveToFront(node: LRUNode<T>): void {
+ if (node === this.head) return;
+
+ this.removeNode(node);
+ this.addToFront(node);
+ }
+
+ private evictLRU(): void {
+ if (!this.tail) return;
+
+ const evictedKey = this.tail.key;
+ const evictedSize = this.estimateSize(this.tail.value.data);
+
+ this.removeNode(this.tail);
+ this.cache.delete(evictedKey);
+ this.currentMemory -= evictedSize;
+ this.stats.evictions++;
+
+ this.emit('cache:eviction', { key: evictedKey });
+ }
+
+ private startCleanupTimer(): void {
+ // Clean up expired entries every minute
+ this.cleanupInterval = setInterval(() => {
+ this.cleanupExpired();
+ }, 60000);
+ }
+
+ private cleanupExpired(): void {
+ const now = Date.now();
+ let cleaned = 0;
+
+ for (const [key, node] of this.cache) {
+ if (node.value.expiresAt < now) {
+ this.delete(key);
+ cleaned++;
+ }
+ }
+
+ if (cleaned > 0) {
+ this.emit('cache:cleanup', { expired: cleaned });
+ }
+ }
+}
+
+/**
+ * Multi-layer cache with L1 (memory) and L2 (storage) tiers
+ */
+export class TieredCacheManager<T = MemoryEntry> extends EventEmitter {
+ private l1Cache: CacheManager<T>;
+ private l2Loader: ((key: string) => Promise<T | null>) | null = null;
+ private l2Writer: ((key: string, value: T) => Promise<void>) | null = null;
+
+ constructor(
+ l1Config: Partial<CacheConfig> = {},
+ l2Options?: {
+ loader: (key: string) => Promise<T | null>;
+ writer?: (key: string, value: T) => Promise<void>;
+ }
+ ) {
+ super();
+ this.l1Cache = new CacheManager<T>(l1Config);
+
+ if (l2Options) {
+ this.l2Loader = l2Options.loader;
+ this.l2Writer = l2Options.writer;
+ }
+
+ // Forward L1 events
+ this.l1Cache.on('cache:hit', (data) => this.emit('l1:hit', data));
+ this.l1Cache.on('cache:miss', (data) => this.emit('l1:miss', data));
+ this.l1Cache.on('cache:eviction', (data) => this.emit('l1:eviction', data));
+ }
+
+ /**
+ * Get from tiered cache
+ */
+ async get(key: string): Promise<T | null> {
+ // Try L1 first
+ const l1Result = this.l1Cache.get(key);
+ if (l1Result !== null) {
+ return l1Result;
+ }
+
+ // Try L2 if available
+ if (this.l2Loader) {
+ const l2Result = await this.l2Loader(key);
+ if (l2Result !== null) {
+ // Promote to L1
+ this.l1Cache.set(key, l2Result);
+ this.emit('l2:hit', { key });
+ return l2Result;
+ }
+ this.emit('l2:miss', { key });
+ }
+
+ return null;
+ }
+
+ /**
+ * Set in tiered cache
+ */
+ async set(key: string, value: T, ttl?: number): Promise<void> {
+ // Write to L1
+ this.l1Cache.set(key, value, ttl);
+
+ // Write-through to L2 if configured
+ if (this.l2Writer) {
+ await this.l2Writer(key, value);
+ this.emit('l2:write', { key });
+ }
+ }
+
+ /**
+ * Delete from tiered cache
+ */
+ delete(key: string): boolean {
+ return this.l1Cache.delete(key);
+ }
+
+ /**
+ * Get L1 cache statistics
+ */
+ getStats(): CacheStats {
+ return this.l1Cache.getStats();
+ }
+
+ /**
+ * Clear L1 cache
+ */
+ clear(): void {
+ this.l1Cache.clear();
+ }
+
+ /**
+ * Shutdown tiered cache
+ */
+ shutdown(): void {
+ this.l1Cache.shutdown();
+ }
+}
+
+export default CacheManager;
diff --git a/v3/@claude-flow/memory/src/hnsw-index.ts b/v3/@claude-flow/memory/src/hnsw-index.ts
new file mode 100644
index 0000000000..5db703524a
--- /dev/null
+++ b/v3/@claude-flow/memory/src/hnsw-index.ts
@@ -0,0 +1,1013 @@
+/**
+ * V3 HNSW Vector Index
+ *
+ * High-performance Hierarchical Navigable Small World (HNSW) index for
+ * 150x-12,500x faster vector similarity search compared to brute force.
+ *
+ * OPTIMIZATIONS:
+ * - BinaryMinHeap/BinaryMaxHeap for O(log n) operations (vs O(n log n) Array.sort)
+ * - Pre-normalized vectors for O(1) cosine similarity (no sqrt needed)
+ * - Bounded max-heap for efficient top-k tracking
+ *
+ * @module v3/memory/hnsw-index
+ */
+
+import { EventEmitter } from 'node:events';
+import {
+ DistanceMetric,
+ HNSWConfig,
+ HNSWStats,
+ QuantizationConfig,
+ SearchResult,
+ MemoryEntry,
+ MemoryEvent,
+ MemoryEventHandler,
+} from './types.js';
+
+/**
+ * Binary Min Heap for O(log n) priority queue operations
+ * Used for candidate selection in HNSW search
+ */
+class BinaryMinHeap<T> {
+ private heap: Array<{ item: T; priority: number }> = [];
+
+ get size(): number {
+ return this.heap.length;
+ }
+
+ insert(item: T, priority: number): void {
+ this.heap.push({ item, priority });
+ this.bubbleUp(this.heap.length - 1);
+ }
+
+ extractMin(): T | undefined {
+ if (this.heap.length === 0) return undefined;
+ const min = this.heap[0].item;
+ const last = this.heap.pop()!;
+ if (this.heap.length > 0) {
+ this.heap[0] = last;
+ this.bubbleDown(0);
+ }
+ return min;
+ }
+
+ peek(): T | undefined {
+ return this.heap[0]?.item;
+ }
+
+ peekPriority(): number | undefined {
+ return this.heap[0]?.priority;
+ }
+
+ isEmpty(): boolean {
+ return this.heap.length === 0;
+ }
+
+ toArray(): T[] {
+ return this.heap
+ .slice()
+ .sort((a, b) => a.priority - b.priority)
+ .map((entry) => entry.item);
+ }
+
+ private bubbleUp(index: number): void {
+ while (index > 0) {
+ const parent = Math.floor((index - 1) / 2);
+ if (this.heap[parent].priority <= this.heap[index].priority) break;
+ [this.heap[parent], this.heap[index]] = [this.heap[index], this.heap[parent]];
+ index = parent;
+ }
+ }
+
+ private bubbleDown(index: number): void {
+ const length = this.heap.length;
+ while (true) {
+ let smallest = index;
+ const left = 2 * index + 1;
+ const right = 2 * index + 2;
+ if (left < length && this.heap[left].priority < this.heap[smallest].priority) {
+ smallest = left;
+ }
+ if (right < length && this.heap[right].priority < this.heap[smallest].priority) {
+ smallest = right;
+ }
+ if (smallest === index) break;
+ [this.heap[smallest], this.heap[index]] = [this.heap[index], this.heap[smallest]];
+ index = smallest;
+ }
+ }
+}
+
+/**
+ * Binary Max Heap for bounded top-k tracking
+ * Keeps track of k smallest elements by evicting largest when full
+ */
+class BinaryMaxHeap<T> {
+ private heap: Array<{ item: T; priority: number }> = [];
+ private maxSize: number;
+
+ constructor(maxSize: number = Infinity) {
+ this.maxSize = maxSize;
+ }
+
+ get size(): number {
+ return this.heap.length;
+ }
+
+ insert(item: T, priority: number): boolean {
+ // If at capacity and new item is worse than worst, reject
+ if (this.heap.length >= this.maxSize && priority >= this.heap[0]?.priority) {
+ return false;
+ }
+
+ if (this.heap.length >= this.maxSize) {
+ // Replace max element
+ this.heap[0] = { item, priority };
+ this.bubbleDown(0);
+ } else {
+ this.heap.push({ item, priority });
+ this.bubbleUp(this.heap.length - 1);
+ }
+ return true;
+ }
+
+ peekMax(): T | undefined {
+ return this.heap[0]?.item;
+ }
+
+ peekMaxPriority(): number {
+ return this.heap[0]?.priority ?? Infinity;
+ }
+
+ extractMax(): T | undefined {
+ if (this.heap.length === 0) return undefined;
+ const max = this.heap[0].item;
+ const last = this.heap.pop()!;
+ if (this.heap.length > 0) {
+ this.heap[0] = last;
+ this.bubbleDown(0);
+ }
+ return max;
+ }
+
+ isEmpty(): boolean {
+ return this.heap.length === 0;
+ }
+
+ toSortedArray(): Array<{ item: T; priority: number }> {
+ return this.heap.slice().sort((a, b) => a.priority - b.priority);
+ }
+
+ private bubbleUp(index: number): void {
+ while (index > 0) {
+ const parent = Math.floor((index - 1) / 2);
+ if (this.heap[parent].priority >= this.heap[index].priority) break;
+ [this.heap[parent], this.heap[index]] = [this.heap[index], this.heap[parent]];
+ index = parent;
+ }
+ }
+
+ private bubbleDown(index: number): void {
+ const length = this.heap.length;
+ while (true) {
+ let largest = index;
+ const left = 2 * index + 1;
+ const right = 2 * index + 2;
+ if (left < length && this.heap[left].priority > this.heap[largest].priority) {
+ largest = left;
+ }
+ if (right < length && this.heap[right].priority > this.heap[largest].priority) {
+ largest = right;
+ }
+ if (largest === index) break;
+ [this.heap[largest], this.heap[index]] = [this.heap[index], this.heap[largest]];
+ index = largest;
+ }
+ }
+}
+
+/**
+ * Internal node structure for HNSW graph
+ */
+interface HNSWNode {
+ /** Node ID (memory entry ID) */
+ id: string;
+
+ /** Vector embedding (original) */
+ vector: Float32Array;
+
+ /** Pre-normalized vector for O(1) cosine similarity */
+ normalizedVector: Float32Array | null;
+
+ /** Connections at each layer */
+ connections: Map<number, Set<string>>;
+
+ /** Node level (top layer this node appears in) */
+ level: number;
+}
+
+/**
+ * HNSW Index implementation for ultra-fast vector similarity search
+ *
+ * Performance characteristics:
+ * - Search: O(log n) approximate nearest neighbor
+ * - Insert: O(log n) amortized
+ * - Memory: O(n * M * L) where M is max connections, L is layers
+ */
+export class HNSWIndex extends EventEmitter {
+ private config: HNSWConfig;
+ private nodes: Map<string, HNSWNode> = new Map();
+ private entryPoint: string | null = null;
+ private maxLevel: number = 0;
+ private levelMult: number;
+
+ // Performance tracking
+ private stats: {
+ searchCount: number;
+ totalSearchTime: number;
+ insertCount: number;
+ totalInsertTime: number;
+ buildStartTime: number;
+ } = {
+ searchCount: 0,
+ totalSearchTime: 0,
+ insertCount: 0,
+ totalInsertTime: 0,
+ buildStartTime: 0,
+ };
+
+ // Quantization support
+ private quantizer: Quantizer | null = null;
+
+ constructor(config: Partial<HNSWConfig> = {}) {
+ super();
+ this.config = this.mergeConfig(config);
+ this.levelMult = 1 / Math.log(this.config.M);
+
+ if (this.config.quantization) {
+ this.quantizer = new Quantizer(this.config.quantization, this.config.dimensions);
+ }
+ }
+
+ /**
+ * Add a vector to the index
+ */
+ async addPoint(id: string, vector: Float32Array): Promise<void> {
+ const startTime = performance.now();
+
+ if (vector.length !== this.config.dimensions) {
+ throw new Error(
+ `Vector dimension mismatch: expected ${this.config.dimensions}, got ${vector.length}`
+ );
+ }
+
+ if (this.nodes.size >= this.config.maxElements) {
+ throw new Error('Index is full, cannot add more elements');
+ }
+
+ // Quantize if enabled
+ const storedVector = this.quantizer
+ ? this.quantizer.encode(vector)
+ : vector;
+
+ // Pre-normalize vector for O(1) cosine similarity
+ const normalizedVector = this.config.metric === 'cosine'
+ ? this.normalizeVector(storedVector)
+ : null;
+
+ // Generate random level for new node
+ const level = this.getRandomLevel();
+
+ const node: HNSWNode = {
+ id,
+ vector: storedVector,
+ normalizedVector,
+ connections: new Map(),
+ level,
+ };
+
+ // Initialize connection sets for each layer
+ for (let l = 0; l <= level; l++) {
+ node.connections.set(l, new Set());
+ }
+
+ if (this.entryPoint === null) {
+ // First node
+ this.entryPoint = id;
+ this.maxLevel = level;
+ this.nodes.set(id, node);
+ } else {
+ // Insert new node into the graph
+ await this.insertNode(node);
+ }
+
+ const duration = performance.now() - startTime;
+ this.stats.insertCount++;
+ this.stats.totalInsertTime += duration;
+
+ this.emit('point:added', { id, level, duration });
+ }
+
+ /**
+ * Search for k nearest neighbors
+ */
+ async search(
+ query: Float32Array,
+ k: number,
+ ef?: number
+ ): Promise<Array<{ id: string; distance: number }>> {
+ const startTime = performance.now();
+
+ if (query.length !== this.config.dimensions) {
+ throw new Error(
+ `Query dimension mismatch: expected ${this.config.dimensions}, got ${query.length}`
+ );
+ }
+
+ if (this.entryPoint === null) {
+ return [];
+ }
+
+ const searchEf = ef || Math.max(k, this.config.efConstruction);
+
+ // Quantize query if needed
+ const queryVector = this.quantizer
+ ? this.quantizer.encode(query)
+ : query;
+
+ // Pre-normalize query for O(1) cosine similarity
+ const normalizedQuery = this.config.metric === 'cosine'
+ ? this.normalizeVector(queryVector)
+ : null;
+
+ // Start from entry point and search down the layers
+ let currentNode = this.entryPoint;
+ let currentDist = this.distanceOptimized(
+ queryVector,
+ normalizedQuery,
+ this.nodes.get(currentNode)!
+ );
+
+ // Search through layers from top to 1
+ for (let level = this.maxLevel; level > 0; level--) {
+ const layerResult = this.searchLayerOptimized(
+ queryVector,
+ normalizedQuery,
+ currentNode,
+ 1,
+ level
+ );
+ currentNode = layerResult[0]?.id || currentNode;
+ currentDist = this.distanceOptimized(
+ queryVector,
+ normalizedQuery,
+ this.nodes.get(currentNode)!
+ );
+ }
+
+ // Search layer 0 with ef candidates using heap-based search
+ const candidates = this.searchLayerOptimized(
+ queryVector,
+ normalizedQuery,
+ currentNode,
+ searchEf,
+ 0
+ );
+
+ // Return top k results (already sorted by heap)
+ const results = candidates.slice(0, k);
+
+ const duration = performance.now() - startTime;
+ this.stats.searchCount++;
+ this.stats.totalSearchTime += duration;
+
+ return results;
+ }
+
+ /**
+ * Search with filters applied post-retrieval
+ */
+ async searchWithFilters(
+ query: Float32Array,
+ k: number,
+ filter: (id: string) => boolean,
+ ef?: number
+ ): Promise<Array<{ id: string; distance: number }>> {
+ // Over-fetch to account for filtered results
+ const overFetchFactor = 3;
+ const candidates = await this.search(query, k * overFetchFactor, ef);
+
+ return candidates
+ .filter((c) => filter(c.id))
+ .slice(0, k);
+ }
+
+ /**
+ * Remove a point from the index
+ */
+ async removePoint(id: string): Promise<boolean> {
+ const node = this.nodes.get(id);
+ if (!node) {
+ return false;
+ }
+
+ // Remove all connections to this node
+ for (let level = 0; level <= node.level; level++) {
+ const connections = node.connections.get(level);
+ if (connections) {
+ for (const connectedId of connections) {
+ const connectedNode = this.nodes.get(connectedId);
+ if (connectedNode) {
+ connectedNode.connections.get(level)?.delete(id);
+ }
+ }
+ }
+ }
+
+ this.nodes.delete(id);
+
+ // Update entry point if needed
+ if (this.entryPoint === id) {
+ if (this.nodes.size === 0) {
+ this.entryPoint = null;
+ this.maxLevel = 0;
+ } else {
+ // Find new entry point with highest level
+ let newEntry: string | null = null;
+ let newMaxLevel = 0;
+ for (const [nodeId, n] of this.nodes) {
+ if (newEntry === null || n.level > newMaxLevel) {
+ newMaxLevel = n.level;
+ newEntry = nodeId;
+ }
+ }
+ this.entryPoint = newEntry;
+ this.maxLevel = newMaxLevel;
+ }
+ }
+
+ this.emit('point:removed', { id });
+ return true;
+ }
+
+ /**
+ * Rebuild the index from scratch
+ */
+ async rebuild(
+ entries: Array<{ id: string; vector: Float32Array }>
+ ): Promise<void> {
+ this.stats.buildStartTime = performance.now();
+
+ this.nodes.clear();
+ this.entryPoint = null;
+ this.maxLevel = 0;
+
+ for (const entry of entries) {
+ await this.addPoint(entry.id, entry.vector);
+ }
+
+ const buildTime = performance.now() - this.stats.buildStartTime;
+
+ this.emit('index:rebuilt', {
+ vectorCount: this.nodes.size,
+ buildTime,
+ });
+ }
+
+ /**
+ * Get index statistics
+ */
+ getStats(): HNSWStats {
+ const vectorCount = this.nodes.size;
+ const avgSearchTime =
+ this.stats.searchCount > 0
+ ? this.stats.totalSearchTime / this.stats.searchCount
+ : 0;
+
+ // Estimate memory usage
+ const bytesPerVector = this.config.dimensions * 4; // Float32 = 4 bytes
+ const connectionOverhead = this.config.M * 8 * (this.maxLevel + 1); // Approximate
+ const memoryUsage = vectorCount * (bytesPerVector + connectionOverhead);
+
+ return {
+ vectorCount,
+ memoryUsage,
+ avgSearchTime,
+ buildTime: performance.now() - this.stats.buildStartTime,
+ compressionRatio: this.quantizer?.getCompressionRatio() || 1.0,
+ };
+ }
+
+ /**
+ * Clear the index
+ */
+ clear(): void {
+ this.nodes.clear();
+ this.entryPoint = null;
+ this.maxLevel = 0;
+ this.stats = {
+ searchCount: 0,
+ totalSearchTime: 0,
+ insertCount: 0,
+ totalInsertTime: 0,
+ buildStartTime: 0,
+ };
+ }
+
+ /**
+ * Check if an ID exists in the index
+ */
+ has(id: string): boolean {
+ return this.nodes.has(id);
+ }
+
+ /**
+ * Get the number of vectors in the index
+ */
+ get size(): number {
+ return this.nodes.size;
+ }
+
+ // ===== Private Methods =====
+
+ private mergeConfig(config: Partial<HNSWConfig>): HNSWConfig {
+ return {
+ dimensions: config.dimensions || 1536, // OpenAI embedding size
+ M: config.M || 16,
+ efConstruction: config.efConstruction || 200,
+ maxElements: config.maxElements || 1000000,
+ metric: config.metric || 'cosine',
+ quantization: config.quantization,
+ };
+ }
+
+ private getRandomLevel(): number {
+ let level = 0;
+ while (Math.random() < 0.5 && level < 16) {
+ level++;
+ }
+ return level;
+ }
+
+ private async insertNode(node: HNSWNode): Promise<void> {
+ const query = node.vector;
+ const normalizedQuery = node.normalizedVector;
+ let currentNode = this.entryPoint!;
+ let currentDist = this.distanceOptimized(
+ query,
+ normalizedQuery,
+ this.nodes.get(currentNode)!
+ );
+
+ // Find entry point for the node's level
+ for (let level = this.maxLevel; level > node.level; level--) {
+ const result = this.searchLayerOptimized(query, normalizedQuery, currentNode, 1, level);
+ if (result.length > 0 && result[0].distance < currentDist) {
+ currentNode = result[0].id;
+ currentDist = result[0].distance;
+ }
+ }
+
+ // Insert at each level from node.level down to 0
+ for (let level = Math.min(node.level, this.maxLevel); level >= 0; level--) {
+ const neighbors = this.searchLayerOptimized(
+ query,
+ normalizedQuery,
+ currentNode,
+ this.config.efConstruction,
+ level
+ );
+
+ // Select M best neighbors
+ const selectedNeighbors = this.selectNeighbors(
+ node.id,
+ query,
+ neighbors,
+ this.config.M
+ );
+
+ // Add connections
+ for (const neighbor of selectedNeighbors) {
+ node.connections.get(level)!.add(neighbor.id);
+ this.nodes.get(neighbor.id)?.connections.get(level)?.add(node.id);
+
+ // Prune connections if over limit
+ const neighborNode = this.nodes.get(neighbor.id);
+ if (neighborNode) {
+ const neighborConns = neighborNode.connections.get(level)!;
+ if (neighborConns.size > this.config.M * 2) {
+ this.pruneConnections(neighborNode, level, this.config.M);
+ }
+ }
+ }
+
+ if (neighbors.length > 0) {
+ currentNode = neighbors[0].id;
+ }
+ }
+
+ this.nodes.set(node.id, node);
+
+ // Update max level if needed
+ if (node.level > this.maxLevel) {
+ this.maxLevel = node.level;
+ this.entryPoint = node.id;
+ }
+ }
+
+ private async searchLayer(
+ query: Float32Array,
+ entryPoint: string,
+ ef: number,
+ level: number
+ ): Promise<Array<{ id: string; distance: number }>> {
+ const visited = new Set<string>([entryPoint]);
+ const candidates: Array<{ id: string; distance: number }> = [];
+ const results: Array<{ id: string; distance: number }> = [];
+
+ const entryDist = this.distance(query, this.nodes.get(entryPoint)!.vector);
+ candidates.push({ id: entryPoint, distance: entryDist });
+ results.push({ id: entryPoint, distance: entryDist });
+
+ while (candidates.length > 0) {
+ // Get closest candidate
+ candidates.sort((a, b) => a.distance - b.distance);
+ const current = candidates.shift()!;
+
+ // Check termination condition
+ const worstResult = results.length > 0
+ ? Math.max(...results.map((r) => r.distance))
+ : Infinity;
+ if (current.distance > worstResult && results.length >= ef) {
+ break;
+ }
+
+ // Explore neighbors
+ const node = this.nodes.get(current.id);
+ if (!node) continue;
+
+ const connections = node.connections.get(level);
+ if (!connections) continue;
+
+ for (const neighborId of connections) {
+ if (visited.has(neighborId)) continue;
+ visited.add(neighborId);
+
+ const neighborNode = this.nodes.get(neighborId);
+ if (!neighborNode) continue;
+
+ const distance = this.distance(query, neighborNode.vector);
+
+ if (results.length < ef || distance < worstResult) {
+ candidates.push({ id: neighborId, distance });
+ results.push({ id: neighborId, distance });
+
+ // Keep results bounded
+ if (results.length > ef) {
+ results.sort((a, b) => a.distance - b.distance);
+ results.pop();
+ }
+ }
+ }
+ }
+
+ return results.sort((a, b) => a.distance - b.distance);
+ }
+
+ /**
+ * OPTIMIZED searchLayer using heap-based priority queues
+ * Performance: O(log n) per operation vs O(n log n) for Array.sort()
+ * Expected speedup: 3-5x for large result sets
+ */
+ private searchLayerOptimized(
+ query: Float32Array,
+ normalizedQuery: Float32Array | null,
+ entryPoint: string,
+ ef: number,
+ level: number
+ ): Array<{ id: string; distance: number }> {
+ const visited = new Set<string>([entryPoint]);
+
+ // Min-heap for candidates (closest first for expansion)
+ const candidates = new BinaryMinHeap<string>();
+
+ // Max-heap for results (bounded size, tracks worst distance efficiently)
+ const results = new BinaryMaxHeap<string>(ef);
+
+ const entryNode = this.nodes.get(entryPoint)!;
+ const entryDist = this.distanceOptimized(query, normalizedQuery, entryNode);
+
+ candidates.insert(entryPoint, entryDist);
+ results.insert(entryPoint, entryDist);
+
+ while (!candidates.isEmpty()) {
+ // Get closest candidate - O(log n)
+ const currentDist = candidates.peekPriority()!;
+ const currentId = candidates.extractMin()!;
+
+ // Check termination: if closest candidate is worse than worst result, stop
+ const worstResultDist = results.peekMaxPriority();
+ if (currentDist > worstResultDist && results.size >= ef) {
+ break;
+ }
+
+ // Explore neighbors
+ const node = this.nodes.get(currentId);
+ if (!node) continue;
+
+ const connections = node.connections.get(level);
+ if (!connections) continue;
+
+ for (const neighborId of connections) {
+ if (visited.has(neighborId)) continue;
+ visited.add(neighborId);
+
+ const neighborNode = this.nodes.get(neighborId);
+ if (!neighborNode) continue;
+
+ const distance = this.distanceOptimized(query, normalizedQuery, neighborNode);
+
+ // Only add if within threshold or results not full
+ if (results.size < ef || distance < worstResultDist) {
+ candidates.insert(neighborId, distance);
+ // Max-heap handles size bounding automatically - O(log n)
+ results.insert(neighborId, distance);
+ }
+ }
+ }
+
+ // Return sorted results
+ return results.toSortedArray().map(({ item, priority }) => ({
+ id: item,
+ distance: priority,
+ }));
+ }
+
+ private selectNeighbors(
+ nodeId: string,
+ query: Float32Array,
+ candidates: Array<{ id: string; distance: number }>,
+ M: number
+ ): Array<{ id: string; distance: number }> {
+ // Simple selection: take M closest
+ return candidates
+ .filter((c) => c.id !== nodeId)
+ .sort((a, b) => a.distance - b.distance)
+ .slice(0, M);
+ }
+
+ private pruneConnections(node: HNSWNode, level: number, maxConnections: number): void {
+ const connections = node.connections.get(level);
+ if (!connections || connections.size <= maxConnections) return;
+
+ // Calculate distances to all connections
+ const distances: Array<{ id: string; distance: number }> = [];
+ for (const connId of connections) {
+ const connNode = this.nodes.get(connId);
+ if (connNode) {
+ distances.push({
+ id: connId,
+ distance: this.distance(node.vector, connNode.vector),
+ });
+ }
+ }
+
+ // Keep only the closest ones
+ distances.sort((a, b) => a.distance - b.distance);
+ const toKeep = new Set(distances.slice(0, maxConnections).map((d) => d.id));
+
+ // Remove excess connections
+ for (const connId of connections) {
+ if (!toKeep.has(connId)) {
+ connections.delete(connId);
+ this.nodes.get(connId)?.connections.get(level)?.delete(node.id);
+ }
+ }
+ }
+
+ private distance(a: Float32Array, b: Float32Array): number {
+ switch (this.config.metric) {
+ case 'cosine':
+ return this.cosineDistance(a, b);
+ case 'euclidean':
+ return this.euclideanDistance(a, b);
+ case 'dot':
+ return this.dotProductDistance(a, b);
+ case 'manhattan':
+ return this.manhattanDistance(a, b);
+ default:
+ return this.cosineDistance(a, b);
+ }
+ }
+
+ private cosineDistance(a: Float32Array, b: Float32Array): number {
+ let dotProduct = 0;
+ let normA = 0;
+ let normB = 0;
+
+ for (let i = 0; i < a.length; i++) {
+ dotProduct += a[i] * b[i];
+ normA += a[i] * a[i];
+ normB += b[i] * b[i];
+ }
+
+ const similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+ return 1 - similarity; // Convert to distance
+ }
+
+ /**
+ * OPTIMIZED: Cosine distance using pre-normalized vectors
+ * Only requires dot product (no sqrt operations)
+ * Performance: O(n) with ~2x speedup over standard cosine
+ */
+ private cosineDistanceNormalized(a: Float32Array, b: Float32Array): number {
+ let dotProduct = 0;
+ for (let i = 0; i < a.length; i++) {
+ dotProduct += a[i] * b[i];
+ }
+ // For normalized vectors: cosine_similarity = dot_product
+ // Return distance (1 - similarity)
+ return 1 - dotProduct;
+ }
+
+ /**
+ * Normalize a vector to unit length for O(1) cosine similarity
+ */
+ private normalizeVector(vector: Float32Array): Float32Array {
+ let norm = 0;
+ for (let i = 0; i < vector.length; i++) {
+ norm += vector[i] * vector[i];
+ }
+ norm = Math.sqrt(norm);
+
+ if (norm === 0) {
+ return vector; // Return as-is if zero vector
+ }
+
+ const normalized = new Float32Array(vector.length);
+ for (let i = 0; i < vector.length; i++) {
+ normalized[i] = vector[i] / norm;
+ }
+ return normalized;
+ }
+
+ /**
+ * OPTIMIZED distance calculation that uses pre-normalized vectors when available
+ */
+ private distanceOptimized(
+ query: Float32Array,
+ normalizedQuery: Float32Array | null,
+ node: HNSWNode
+ ): number {
+ // Use optimized path for cosine with pre-normalized vectors
+ if (
+ this.config.metric === 'cosine' &&
+ normalizedQuery !== null &&
+ node.normalizedVector !== null
+ ) {
+ return this.cosineDistanceNormalized(normalizedQuery, node.normalizedVector);
+ }
+
+ // Fall back to standard distance calculation
+ return this.distance(query, node.vector);
+ }
+
+ private euclideanDistance(a: Float32Array, b: Float32Array): number {
+ let sum = 0;
+ for (let i = 0; i < a.length; i++) {
+ const diff = a[i] - b[i];
+ sum += diff * diff;
+ }
+ return Math.sqrt(sum);
+ }
+
+ private dotProductDistance(a: Float32Array, b: Float32Array): number {
+ let dotProduct = 0;
+ for (let i = 0; i < a.length; i++) {
+ dotProduct += a[i] * b[i];
+ }
+ // Negative because higher dot product = more similar
+ return -dotProduct;
+ }
+
+ private manhattanDistance(a: Float32Array, b: Float32Array): number {
+ let sum = 0;
+ for (let i = 0; i < a.length; i++) {
+ sum += Math.abs(a[i] - b[i]);
+ }
+ return sum;
+ }
+}
+
+/**
+ * Quantizer for vector compression
+ */
+class Quantizer {
+ private config: QuantizationConfig;
+ private dimensions: number;
+
+ constructor(config: QuantizationConfig, dimensions: number) {
+ this.config = config;
+ this.dimensions = dimensions;
+ }
+
+ /**
+ * Encode a vector using quantization
+ */
+ encode(vector: Float32Array): Float32Array {
+ switch (this.config.type) {
+ case 'binary':
+ return this.binaryQuantize(vector);
+ case 'scalar':
+ return this.scalarQuantize(vector);
+ case 'product':
+ return this.productQuantize(vector);
+ default:
+ return vector;
+ }
+ }
+
+ /**
+ * Get compression ratio
+ */
+ getCompressionRatio(): number {
+ switch (this.config.type) {
+ case 'binary':
+ return 32; // 32x compression (32 bits -> 1 bit per dimension)
+ case 'scalar':
+ return 32 / (this.config.bits || 8);
+ case 'product':
+ return this.config.subquantizers || 8;
+ default:
+ return 1;
+ }
+ }
+
+ private binaryQuantize(vector: Float32Array): Float32Array {
+ // Simple binary quantization: > 0 becomes 1, <= 0 becomes 0
+ // Stored in packed format in a smaller Float32Array
+ const packedLength = Math.ceil(vector.length / 32);
+ const packed = new Float32Array(packedLength);
+
+ for (let i = 0; i < vector.length; i++) {
+ const packedIndex = Math.floor(i / 32);
+ const bitPosition = i % 32;
+ if (vector[i] > 0) {
+ packed[packedIndex] = (packed[packedIndex] || 0) | (1 << bitPosition);
+ }
+ }
+
+ return packed;
+ }
+
+ private scalarQuantize(vector: Float32Array): Float32Array {
+ // Find min/max for normalization
+ let min = Infinity;
+ let max = -Infinity;
+ for (let i = 0; i < vector.length; i++) {
+ if (vector[i] < min) min = vector[i];
+ if (vector[i] > max) max = vector[i];
+ }
+
+ const range = max - min || 1;
+ const bits = this.config.bits || 8;
+ const levels = Math.pow(2, bits);
+
+ // Quantize each value
+ const quantized = new Float32Array(vector.length + 2); // +2 for min/range
+ quantized[0] = min;
+ quantized[1] = range;
+
+ for (let i = 0; i < vector.length; i++) {
+ const normalized = (vector[i] - min) / range;
+ quantized[i + 2] = Math.round(normalized * (levels - 1));
+ }
+
+ return quantized;
+ }
+
+ private productQuantize(vector: Float32Array): Float32Array {
+ // Simplified product quantization
+ // In production, would use trained codebooks
+ const subquantizers = this.config.subquantizers || 8;
+ const subvectorSize = Math.ceil(vector.length / subquantizers);
+
+ const quantized = new Float32Array(subquantizers);
+
+ for (let i = 0; i < subquantizers; i++) {
+ let sum = 0;
+ const start = i * subvectorSize;
+ const end = Math.min(start + subvectorSize, vector.length);
+
+ for (let j = start; j < end; j++) {
+ sum += vector[j];
+ }
+
+ quantized[i] = sum / (end - start);
+ }
+
+ return quantized;
+ }
+}
+
+export default HNSWIndex;
diff --git a/v3/@claude-flow/memory/src/index.ts b/v3/@claude-flow/memory/src/index.ts
new file mode 100644
index 0000000000..940a1f1bad
--- /dev/null
+++ b/v3/@claude-flow/memory/src/index.ts
@@ -0,0 +1,465 @@
+/**
+ * @claude-flow/memory - V3 Unified Memory System
+ *
+ * Provides a unified memory interface backed by AgentDB with HNSW indexing
+ * for 150x-12,500x faster vector search compared to brute-force approaches.
+ *
+ * @module @claude-flow/memory
+ *
+ * @example
+ * ```typescript
+ * import { UnifiedMemoryService, query, QueryTemplates } from '@claude-flow/memory';
+ *
+ * // Initialize the memory service
+ * const memory = new UnifiedMemoryService({
+ * dimensions: 1536,
+ * cacheEnabled: true,
+ * embeddingGenerator: async (text) => embeddings.embed(text),
+ * });
+ *
+ * await memory.initialize();
+ *
+ * // Store entries
+ * await memory.store({
+ * key: 'auth-patterns',
+ * content: 'OAuth 2.0 implementation patterns for secure authentication',
+ * tags: ['auth', 'security', 'patterns'],
+ * });
+ *
+ * // Semantic search
+ * const results = await memory.semanticSearch('user authentication best practices', 5);
+ *
+ * // Query with fluent builder
+ * const entries = await memory.query(
+ * query()
+ * .semantic('security vulnerabilities')
+ * .inNamespace('security')
+ * .withTags(['critical'])
+ * .threshold(0.8)
+ * .limit(10)
+ * .build()
+ * );
+ * ```
+ */
+
+// ===== Core Types =====
+export {
+ // Memory Entry Types
+ MemoryType,
+ AccessLevel,
+ ConsistencyLevel,
+ DistanceMetric,
+ MemoryEntry,
+ MemoryEntryInput,
+ MemoryEntryUpdate,
+
+ // Query Types
+ QueryType,
+ MemoryQuery,
+ SearchResult,
+ SearchOptions,
+
+ // HNSW Types
+ HNSWConfig,
+ HNSWStats,
+ QuantizationConfig,
+
+ // Backend Types
+ IMemoryBackend,
+ BackendStats,
+ HealthCheckResult,
+ ComponentHealth,
+
+ // Cache Types
+ CacheConfig,
+ CacheStats,
+ CachedEntry,
+
+ // Migration Types
+ MigrationSource,
+ MigrationConfig,
+ MigrationProgress,
+ MigrationResult,
+ MigrationError,
+
+ // Event Types
+ MemoryEventType,
+ MemoryEvent,
+ MemoryEventHandler,
+
+ // SONA Types
+ SONAMode,
+ LearningPattern,
+
+ // Utility Types
+ EmbeddingGenerator,
+
+ // Utility Functions
+ generateMemoryId,
+ createDefaultEntry,
+
+ // Constants
+ PERFORMANCE_TARGETS,
+} from './types.js';
+
+// ===== Core Components =====
+export { AgentDBAdapter, AgentDBAdapterConfig } from './agentdb-adapter.js';
+export { HNSWIndex } from './hnsw-index.js';
+export { CacheManager, TieredCacheManager } from './cache-manager.js';
+export { QueryBuilder, query, QueryTemplates, SortDirection, SortField } from './query-builder.js';
+export { MemoryMigrator, createMigrator, migrateMultipleSources } from './migration.js';
+
+// ===== Unified Memory Service =====
+import { EventEmitter } from 'node:events';
+import {
+ IMemoryBackend,
+ MemoryEntry,
+ MemoryEntryInput,
+ MemoryEntryUpdate,
+ MemoryQuery,
+ SearchResult,
+ SearchOptions,
+ BackendStats,
+ HealthCheckResult,
+ EmbeddingGenerator,
+ MigrationSource,
+ MigrationConfig,
+ MigrationResult,
+} from './types.js';
+import { AgentDBAdapter, AgentDBAdapterConfig } from './agentdb-adapter.js';
+import { MemoryMigrator } from './migration.js';
+
+/**
+ * Configuration for UnifiedMemoryService
+ */
+export interface UnifiedMemoryServiceConfig extends Partial<AgentDBAdapterConfig> {
+ /** Enable automatic embedding generation */
+ autoEmbed?: boolean;
+
+ /** Default embedding dimensions */
+ dimensions?: number;
+
+ /** Embedding generator function */
+ embeddingGenerator?: EmbeddingGenerator;
+}
+
+/**
+ * Unified Memory Service
+ *
+ * High-level interface for the V3 memory system that provides:
+ * - Simple API for common operations
+ * - Automatic embedding generation
+ * - Cross-agent memory sharing
+ * - SONA integration for learning
+ * - Event-driven notifications
+ * - Performance monitoring
+ */
+export class UnifiedMemoryService extends EventEmitter implements IMemoryBackend {
+ private adapter: AgentDBAdapter;
+ private config: UnifiedMemoryServiceConfig;
+ private initialized: boolean = false;
+
+ constructor(config: UnifiedMemoryServiceConfig = {}) {
+ super();
+ this.config = {
+ dimensions: 1536,
+ cacheEnabled: true,
+ autoEmbed: true,
+ ...config,
+ };
+
+ this.adapter = new AgentDBAdapter({
+ dimensions: this.config.dimensions,
+ cacheEnabled: this.config.cacheEnabled,
+ cacheSize: this.config.cacheSize,
+ cacheTtl: this.config.cacheTtl,
+ hnswM: this.config.hnswM,
+ hnswEfConstruction: this.config.hnswEfConstruction,
+ defaultNamespace: this.config.defaultNamespace,
+ embeddingGenerator: this.config.embeddingGenerator,
+ persistenceEnabled: this.config.persistenceEnabled,
+ persistencePath: this.config.persistencePath,
+ maxEntries: this.config.maxEntries,
+ });
+
+ // Forward adapter events
+ this.adapter.on('entry:stored', (data) => this.emit('entry:stored', data));
+ this.adapter.on('entry:updated', (data) => this.emit('entry:updated', data));
+ this.adapter.on('entry:deleted', (data) => this.emit('entry:deleted', data));
+ this.adapter.on('cache:hit', (data) => this.emit('cache:hit', data));
+ this.adapter.on('cache:miss', (data) => this.emit('cache:miss', data));
+ this.adapter.on('index:added', (data) => this.emit('index:added', data));
+ }
+
+ // ===== Lifecycle =====
+
+ async initialize(): Promise<void> {
+ if (this.initialized) return;
+ await this.adapter.initialize();
+ this.initialized = true;
+ this.emit('initialized');
+ }
+
+ async shutdown(): Promise<void> {
+ if (!this.initialized) return;
+ await this.adapter.shutdown();
+ this.initialized = false;
+ this.emit('shutdown');
+ }
+
+ // ===== IMemoryBackend Implementation =====
+
+ async store(entry: MemoryEntry): Promise<void> {
+ return this.adapter.store(entry);
+ }
+
+ async get(id: string): Promise<MemoryEntry | null> {
+ return this.adapter.get(id);
+ }
+
+ async getByKey(namespace: string, key: string): Promise<MemoryEntry | null> {
+ return this.adapter.getByKey(namespace, key);
+ }
+
+ async update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null> {
+ return this.adapter.update(id, update);
+ }
+
+ async delete(id: string): Promise<boolean> {
+ return this.adapter.delete(id);
+ }
+
+ async query(query: MemoryQuery): Promise<MemoryEntry[]> {
+ return this.adapter.query(query);
+ }
+
+ async search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]> {
+ return this.adapter.search(embedding, options);
+ }
+
+ async bulkInsert(entries: MemoryEntry[]): Promise<void> {
+ return this.adapter.bulkInsert(entries);
+ }
+
+ async bulkDelete(ids: string[]): Promise<number> {
+ return this.adapter.bulkDelete(ids);
+ }
+
+ async count(namespace?: string): Promise<number> {
+ return this.adapter.count(namespace);
+ }
+
+ async listNamespaces(): Promise<string[]> {
+ return this.adapter.listNamespaces();
+ }
+
+ async clearNamespace(namespace: string): Promise<number> {
+ return this.adapter.clearNamespace(namespace);
+ }
+
+ async getStats(): Promise<BackendStats> {
+ return this.adapter.getStats();
+ }
+
+ async healthCheck(): Promise<HealthCheckResult> {
+ return this.adapter.healthCheck();
+ }
+
+ // ===== Convenience Methods =====
+
+ /**
+ * Store an entry from simple input
+ */
+ async storeEntry(input: MemoryEntryInput): Promise<MemoryEntry> {
+ return this.adapter.storeEntry(input);
+ }
+
+ /**
+ * Semantic search by content string
+ */
+ async semanticSearch(
+ content: string,
+ k: number = 10,
+ threshold?: number
+ ): Promise<SearchResult[]> {
+ return this.adapter.semanticSearch(content, k, threshold);
+ }
+
+ /**
+ * Find similar entries to a given entry
+ */
+ async findSimilar(id: string, k: number = 5): Promise<SearchResult[]> {
+ const entry = await this.get(id);
+ if (!entry || !entry.embedding) {
+ return [];
+ }
+
+ const results = await this.search(entry.embedding, { k: k + 1 });
+
+ // Filter out the source entry
+ return results.filter((r) => r.entry.id !== id).slice(0, k);
+ }
+
+ /**
+ * Get or create an entry
+ */
+ async getOrCreate(
+ namespace: string,
+ key: string,
+ creator: () => MemoryEntryInput | Promise<MemoryEntryInput>
+ ): Promise<MemoryEntry> {
+ const existing = await this.getByKey(namespace, key);
+ if (existing) return existing;
+
+ const input = await creator();
+ return this.storeEntry({ ...input, namespace, key });
+ }
+
+ /**
+ * Append content to an existing entry
+ */
+ async appendContent(id: string, content: string): Promise<MemoryEntry | null> {
+ const entry = await this.get(id);
+ if (!entry) return null;
+
+ return this.update(id, {
+ content: entry.content + '\n' + content,
+ });
+ }
+
+ /**
+ * Add tags to an existing entry
+ */
+ async addTags(id: string, tags: string[]): Promise<MemoryEntry | null> {
+ const entry = await this.get(id);
+ if (!entry) return null;
+
+ const newTags = [...new Set([...entry.tags, ...tags])];
+ return this.update(id, { tags: newTags });
+ }
+
+ /**
+ * Remove tags from an existing entry
+ */
+ async removeTags(id: string, tags: string[]): Promise<MemoryEntry | null> {
+ const entry = await this.get(id);
+ if (!entry) return null;
+
+ const newTags = entry.tags.filter((t) => !tags.includes(t));
+ return this.update(id, { tags: newTags });
+ }
+
+ // ===== Migration =====
+
+ /**
+ * Migrate from a legacy memory source
+ */
+ async migrateFrom(
+ source: MigrationSource,
+ sourcePath: string,
+ options: Partial<MigrationConfig> = {}
+ ): Promise<MigrationResult> {
+ const migrator = new MemoryMigrator(
+ this.adapter,
+ { source, sourcePath, ...options },
+ this.config.embeddingGenerator
+ );
+
+ // Forward migration events
+ migrator.on('migration:started', (data) => this.emit('migration:started', data));
+ migrator.on('migration:progress', (data) => this.emit('migration:progress', data));
+ migrator.on('migration:completed', (data) => this.emit('migration:completed', data));
+ migrator.on('migration:failed', (data) => this.emit('migration:failed', data));
+ migrator.on('migration:error', (data) => this.emit('migration:error', data));
+ migrator.on('migration:warning', (data) => this.emit('migration:warning', data));
+
+ return migrator.migrate();
+ }
+
+ // ===== Cross-Agent Memory Sharing =====
+
+ /**
+ * Share an entry with another agent
+ */
+ async shareWith(id: string, agentId: string): Promise<MemoryEntry | null> {
+ const entry = await this.get(id);
+ if (!entry) return null;
+
+ const sharedWith = (entry.metadata.sharedWith as string[]) || [];
+ if (!sharedWith.includes(agentId)) {
+ sharedWith.push(agentId);
+ }
+
+ return this.update(id, {
+ metadata: { ...entry.metadata, sharedWith },
+ });
+ }
+
+ /**
+ * Get entries shared with a specific agent
+ */
+ async getSharedWith(agentId: string): Promise<MemoryEntry[]> {
+ const all = await this.query({ type: 'hybrid', limit: 10000 });
+ return all.filter((entry) => {
+ const sharedWith = (entry.metadata.sharedWith as string[]) || [];
+ return sharedWith.includes(agentId);
+ });
+ }
+
+ // ===== Utility =====
+
+ /**
+ * Get the underlying adapter for advanced operations
+ */
+ getAdapter(): AgentDBAdapter {
+ return this.adapter;
+ }
+
+ /**
+ * Check if the service is initialized
+ */
+ isInitialized(): boolean {
+ return this.initialized;
+ }
+}
+
+// ===== Factory Functions =====
+
+/**
+ * Create a simple in-memory service (for testing)
+ */
+export function createInMemoryService(): UnifiedMemoryService {
+ return new UnifiedMemoryService({
+ persistenceEnabled: false,
+ cacheEnabled: true,
+ });
+}
+
+/**
+ * Create a persistent memory service
+ */
+export function createPersistentService(path: string): UnifiedMemoryService {
+ return new UnifiedMemoryService({
+ persistenceEnabled: true,
+ persistencePath: path,
+ cacheEnabled: true,
+ });
+}
+
+/**
+ * Create a memory service with embedding support
+ */
+export function createEmbeddingService(
+ embeddingGenerator: EmbeddingGenerator,
+ dimensions: number = 1536
+): UnifiedMemoryService {
+ return new UnifiedMemoryService({
+ embeddingGenerator,
+ dimensions,
+ autoEmbed: true,
+ cacheEnabled: true,
+ });
+}
+
+// Default export
+export default UnifiedMemoryService;
diff --git a/v3/@claude-flow/memory/src/migration.ts b/v3/@claude-flow/memory/src/migration.ts
new file mode 100644
index 0000000000..5e725fe723
--- /dev/null
+++ b/v3/@claude-flow/memory/src/migration.ts
@@ -0,0 +1,669 @@
+/**
+ * V3 Memory Migration Utility
+ *
+ * Migrates data from legacy memory systems (SQLite, Markdown, JSON, etc.)
+ * to the unified AgentDB-backed memory system with HNSW indexing.
+ *
+ * @module v3/memory/migration
+ */
+
+import { EventEmitter } from 'node:events';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import {
+ MigrationConfig,
+ MigrationProgress,
+ MigrationResult,
+ MigrationError,
+ MigrationSource,
+ MemoryEntry,
+ MemoryType,
+ MemoryEntryInput,
+ EmbeddingGenerator,
+ createDefaultEntry,
+} from './types.js';
+import { AgentDBAdapter } from './agentdb-adapter.js';
+
+/**
+ * Default migration configuration
+ */
+const DEFAULT_MIGRATION_CONFIG: Partial<MigrationConfig> = {
+ batchSize: 100,
+ generateEmbeddings: true,
+ validateData: true,
+ continueOnError: true,
+};
+
+/**
+ * Legacy entry format (common structure)
+ */
+interface LegacyEntry {
+ id?: string;
+ key: string;
+ value: unknown;
+ namespace?: string;
+ tags?: string[];
+ metadata?: Record<string, unknown>;
+ timestamp?: number;
+ createdAt?: string | number;
+ updatedAt?: string | number;
+ created_at?: string | number;
+ updated_at?: string | number;
+}
+
+/**
+ * Memory Migration Manager
+ *
+ * Handles migration from:
+ * - SQLite backends (.db files)
+ * - Markdown backends (.md files)
+ * - JSON memory stores (.json files)
+ * - MemoryManager instances
+ * - SwarmMemory instances
+ * - DistributedMemory instances
+ */
+export class MemoryMigrator extends EventEmitter {
+ private config: MigrationConfig;
+ private target: AgentDBAdapter;
+ private embeddingGenerator?: EmbeddingGenerator;
+ private progress: MigrationProgress;
+
+ constructor(
+ target: AgentDBAdapter,
+ config: Partial<MigrationConfig>,
+ embeddingGenerator?: EmbeddingGenerator
+ ) {
+ super();
+ this.target = target;
+ this.config = { ...DEFAULT_MIGRATION_CONFIG, ...config } as MigrationConfig;
+ this.embeddingGenerator = embeddingGenerator;
+ this.progress = this.initializeProgress();
+ }
+
+ /**
+ * Run the migration
+ */
+ async migrate(): Promise<MigrationResult> {
+ const startTime = Date.now();
+ this.progress = this.initializeProgress();
+
+ this.emit('migration:started', { source: this.config.source });
+
+ try {
+ // Load entries from source
+ const entries = await this.loadFromSource();
+ this.progress.total = entries.length;
+ this.progress.totalBatches = Math.ceil(entries.length / this.config.batchSize);
+
+ this.emit('migration:progress', { ...this.progress });
+
+ // Process in batches
+ for (let i = 0; i < entries.length; i += this.config.batchSize) {
+ const batch = entries.slice(i, i + this.config.batchSize);
+ this.progress.currentBatch = Math.floor(i / this.config.batchSize) + 1;
+
+ await this.processBatch(batch);
+
+ this.progress.percentage = Math.round(
+ (this.progress.migrated / this.progress.total) * 100
+ );
+ this.progress.estimatedTimeRemaining = this.estimateTimeRemaining(
+ startTime,
+ this.progress.migrated,
+ this.progress.total
+ );
+
+ this.emit('migration:progress', { ...this.progress });
+ }
+
+ const duration = Date.now() - startTime;
+
+ const result: MigrationResult = {
+ success: this.progress.failed === 0 || this.config.continueOnError,
+ progress: { ...this.progress },
+ duration,
+ summary: this.generateSummary(),
+ };
+
+ this.emit('migration:completed', result);
+ return result;
+ } catch (error) {
+ const duration = Date.now() - startTime;
+
+ const result: MigrationResult = {
+ success: false,
+ progress: { ...this.progress },
+ duration,
+ summary: `Migration failed: ${(error as Error).message}`,
+ };
+
+ this.emit('migration:failed', { error, result });
+ return result;
+ }
+ }
+
+ /**
+ * Get current migration progress
+ */
+ getProgress(): MigrationProgress {
+ return { ...this.progress };
+ }
+
+ // ===== Source Loaders =====
+
+ private async loadFromSource(): Promise<LegacyEntry[]> {
+ switch (this.config.source) {
+ case 'sqlite':
+ return this.loadFromSQLite();
+ case 'markdown':
+ return this.loadFromMarkdown();
+ case 'json':
+ return this.loadFromJSON();
+ case 'memory-manager':
+ return this.loadFromMemoryManager();
+ case 'swarm-memory':
+ return this.loadFromSwarmMemory();
+ case 'distributed-memory':
+ return this.loadFromDistributedMemory();
+ default:
+ throw new Error(`Unknown migration source: ${this.config.source}`);
+ }
+ }
+
+ private async loadFromSQLite(): Promise<LegacyEntry[]> {
+ const entries: LegacyEntry[] = [];
+ const dbPath = this.config.sourcePath;
+
+ try {
+ // Dynamic import for better-sqlite3 or similar
+ // In production, would use actual SQLite library
+ const fileContent = await fs.readFile(dbPath);
+
+ // Parse SQLite format (simplified - actual implementation would use SQLite library)
+ // For now, we'll try to read it as a JSON export format
+ if (dbPath.endsWith('.json')) {
+ const data = JSON.parse(fileContent.toString());
+ if (Array.isArray(data)) {
+ return data;
+ } else if (data.entries) {
+ return data.entries;
+ }
+ }
+
+ // SQLite parsing would go here using better-sqlite3 or sql.js
+ this.emit('migration:warning', {
+ message: 'Direct SQLite parsing requires additional setup. Using export format.',
+ });
+
+ return entries;
+ } catch (error) {
+ throw new Error(`Failed to load SQLite: ${(error as Error).message}`);
+ }
+ }
+
+ private async loadFromMarkdown(): Promise<LegacyEntry[]> {
+ const entries: LegacyEntry[] = [];
+ const basePath = this.config.sourcePath;
+
+ try {
+ const files = await this.walkDirectory(basePath, '.md');
+
+ for (const filePath of files) {
+ try {
+ const content = await fs.readFile(filePath, 'utf-8');
+ const entry = this.parseMarkdownEntry(filePath, content, basePath);
+ if (entry) {
+ entries.push(entry);
+ }
+ } catch (error) {
+ this.addError(filePath, (error as Error).message, 'PARSE_ERROR', true);
+ }
+ }
+
+ return entries;
+ } catch (error) {
+ throw new Error(`Failed to load Markdown: ${(error as Error).message}`);
+ }
+ }
+
+ private async loadFromJSON(): Promise<LegacyEntry[]> {
+ const filePath = this.config.sourcePath;
+
+ try {
+ const content = await fs.readFile(filePath, 'utf-8');
+ const data = JSON.parse(content);
+
+ // Handle different JSON formats
+ if (Array.isArray(data)) {
+ return data;
+ } else if (data.entries) {
+ return data.entries;
+ } else if (typeof data === 'object') {
+ // Assume it's a namespace -> entries map
+ const entries: LegacyEntry[] = [];
+ for (const [namespace, namespaceEntries] of Object.entries(data)) {
+ if (Array.isArray(namespaceEntries)) {
+ for (const entry of namespaceEntries) {
+ entries.push({ ...entry, namespace });
+ }
+ }
+ }
+ return entries;
+ }
+
+ return [];
+ } catch (error) {
+ throw new Error(`Failed to load JSON: ${(error as Error).message}`);
+ }
+ }
+
+ private async loadFromMemoryManager(): Promise<LegacyEntry[]> {
+ // Would integrate with existing MemoryManager instance
+ // For now, try to load from common paths
+ const possiblePaths = [
+ './memory/memory-store.json',
+ './.swarm/memory.db',
+ './memory.json',
+ ];
+
+ for (const p of possiblePaths) {
+ try {
+ const fullPath = path.resolve(this.config.sourcePath, p);
+ await fs.access(fullPath);
+ return this.loadFromJSON();
+ } catch {
+ continue;
+ }
+ }
+
+ return [];
+ }
+
+ private async loadFromSwarmMemory(): Promise<LegacyEntry[]> {
+ // Would integrate with SwarmMemory partitions
+ const entries: LegacyEntry[] = [];
+ const basePath = this.config.sourcePath;
+
+ try {
+ // Check for swarm memory directory structure
+ const partitionsPath = path.join(basePath, '.swarm', 'memory');
+ const files = await this.walkDirectory(partitionsPath, '.json');
+
+ for (const filePath of files) {
+ try {
+ const content = await fs.readFile(filePath, 'utf-8');
+ const data = JSON.parse(content);
+
+ // Extract namespace from file path
+ const relativePath = path.relative(partitionsPath, filePath);
+ const namespace = path.dirname(relativePath).replace(/\\/g, '/');
+
+ if (Array.isArray(data)) {
+ entries.push(...data.map((e: LegacyEntry) => ({ ...e, namespace })));
+ } else if (data.entries) {
+ entries.push(...data.entries.map((e: LegacyEntry) => ({ ...e, namespace })));
+ }
+ } catch (error) {
+ this.addError(filePath, (error as Error).message, 'PARSE_ERROR', true);
+ }
+ }
+
+ return entries;
+ } catch (error) {
+ return [];
+ }
+ }
+
+ private async loadFromDistributedMemory(): Promise<LegacyEntry[]> {
+ // Would integrate with DistributedMemorySystem nodes
+ return this.loadFromSwarmMemory(); // Similar structure
+ }
+
+ // ===== Batch Processing =====
+
+ private async processBatch(batch: LegacyEntry[]): Promise<void> {
+ for (const legacyEntry of batch) {
+ try {
+ // Validate if enabled
+ if (this.config.validateData) {
+ const validation = this.validateEntry(legacyEntry);
+ if (!validation.valid) {
+ if (this.config.continueOnError) {
+ this.addError(
+ legacyEntry.key || 'unknown',
+ validation.reason || 'Validation failed',
+ 'VALIDATION_ERROR',
+ false
+ );
+ this.progress.skipped++;
+ continue;
+ } else {
+ throw new Error(validation.reason);
+ }
+ }
+ }
+
+ // Transform to new format
+ const newEntry = await this.transformEntry(legacyEntry);
+
+ // Store in target
+ await this.target.store(newEntry);
+ this.progress.migrated++;
+ } catch (error) {
+ if (this.config.continueOnError) {
+ this.addError(
+ legacyEntry.key || 'unknown',
+ (error as Error).message,
+ 'STORE_ERROR',
+ true
+ );
+ this.progress.failed++;
+ } else {
+ throw error;
+ }
+ }
+ }
+ }
+
+ private async transformEntry(legacy: LegacyEntry): Promise<MemoryEntry> {
+ // Map namespace if configured
+ let namespace = legacy.namespace || 'default';
+ if (this.config.namespaceMapping && this.config.namespaceMapping[namespace]) {
+ namespace = this.config.namespaceMapping[namespace];
+ }
+
+ // Determine content
+ const content =
+ typeof legacy.value === 'string'
+ ? legacy.value
+ : JSON.stringify(legacy.value);
+
+ // Map type if configured
+ let type: MemoryType = 'semantic';
+ if (legacy.metadata?.type && typeof legacy.metadata.type === 'string') {
+ if (this.config.typeMapping && this.config.typeMapping[legacy.metadata.type]) {
+ type = this.config.typeMapping[legacy.metadata.type];
+ } else if (this.isValidMemoryType(legacy.metadata.type)) {
+ type = legacy.metadata.type as MemoryType;
+ }
+ }
+
+ // Parse timestamps
+ const createdAt = this.parseTimestamp(
+ legacy.createdAt || legacy.created_at || legacy.timestamp
+ );
+ const updatedAt = this.parseTimestamp(
+ legacy.updatedAt || legacy.updated_at || legacy.timestamp
+ );
+
+ const input: MemoryEntryInput = {
+ key: legacy.key,
+ content,
+ type,
+ namespace,
+ tags: legacy.tags || [],
+ metadata: {
+ ...legacy.metadata,
+ migrated: true,
+ migrationSource: this.config.source,
+ migrationTimestamp: Date.now(),
+ originalValue: legacy.value,
+ },
+ };
+
+ const entry = createDefaultEntry(input);
+ entry.createdAt = createdAt;
+ entry.updatedAt = updatedAt;
+
+ // Generate embedding if configured
+ if (this.config.generateEmbeddings && this.embeddingGenerator) {
+ try {
+ entry.embedding = await this.embeddingGenerator(content);
+ } catch (error) {
+ // Log but don't fail
+ this.emit('migration:warning', {
+ message: `Failed to generate embedding for ${legacy.key}: ${(error as Error).message}`,
+ });
+ }
+ }
+
+ return entry;
+ }
+
+ // ===== Helper Methods =====
+
+ private initializeProgress(): MigrationProgress {
+ return {
+ total: 0,
+ migrated: 0,
+ failed: 0,
+ skipped: 0,
+ currentBatch: 0,
+ totalBatches: 0,
+ percentage: 0,
+ estimatedTimeRemaining: 0,
+ errors: [],
+ };
+ }
+
+ private validateEntry(entry: LegacyEntry): { valid: boolean; reason?: string } {
+ if (!entry.key || typeof entry.key !== 'string') {
+ return { valid: false, reason: 'Missing or invalid key' };
+ }
+
+ if (entry.value === undefined) {
+ return { valid: false, reason: 'Missing value' };
+ }
+
+ if (entry.key.length > 500) {
+ return { valid: false, reason: 'Key too long (max 500 chars)' };
+ }
+
+ return { valid: true };
+ }
+
+ private addError(
+ entryId: string,
+ message: string,
+ code: string,
+ recoverable: boolean
+ ): void {
+ const error: MigrationError = {
+ entryId,
+ message,
+ code,
+ recoverable,
+ };
+ this.progress.errors.push(error);
+ this.emit('migration:error', error);
+ }
+
+ private parseTimestamp(value: string | number | undefined): number {
+ if (!value) return Date.now();
+
+ if (typeof value === 'number') {
+ // Handle both milliseconds and seconds
+ return value > 1e12 ? value : value * 1000;
+ }
+
+ const parsed = Date.parse(value);
+ return isNaN(parsed) ? Date.now() : parsed;
+ }
+
+ private isValidMemoryType(type: string): boolean {
+ return ['episodic', 'semantic', 'procedural', 'working', 'cache'].includes(type);
+ }
+
+ private estimateTimeRemaining(
+ startTime: number,
+ completed: number,
+ total: number
+ ): number {
+ if (completed === 0) return 0;
+
+ const elapsed = Date.now() - startTime;
+ const rate = completed / elapsed;
+ const remaining = total - completed;
+
+ return Math.round(remaining / rate);
+ }
+
+ private generateSummary(): string {
+ const { migrated, failed, skipped, total, errors } = this.progress;
+
+ let summary = `Migrated ${migrated}/${total} entries`;
+
+ if (failed > 0) {
+ summary += `, ${failed} failed`;
+ }
+
+ if (skipped > 0) {
+ summary += `, ${skipped} skipped`;
+ }
+
+ if (errors.length > 0) {
+ const errorTypes = new Map<string, number>();
+ for (const error of errors) {
+ errorTypes.set(error.code, (errorTypes.get(error.code) || 0) + 1);
+ }
+
+ const errorSummary = Array.from(errorTypes.entries())
+ .map(([code, count]) => `${code}: ${count}`)
+ .join(', ');
+
+ summary += `. Errors: ${errorSummary}`;
+ }
+
+ return summary;
+ }
+
+ private async walkDirectory(dir: string, extension: string): Promise<string[]> {
+ const files: string[] = [];
+
+ try {
+ const entries = await fs.readdir(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ const subFiles = await this.walkDirectory(fullPath, extension);
+ files.push(...subFiles);
+ } else if (entry.isFile() && entry.name.endsWith(extension)) {
+ files.push(fullPath);
+ }
+ }
+ } catch (error) {
+ // Directory doesn't exist or isn't readable
+ }
+
+ return files;
+ }
+
+ private parseMarkdownEntry(
+ filePath: string,
+ content: string,
+ basePath: string
+ ): LegacyEntry | null {
+ // Extract frontmatter if present
+ const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+
+ let metadata: Record<string, unknown> = {};
+ let body = content;
+
+ if (frontmatterMatch) {
+ try {
+ // Simple YAML-like parsing
+ const frontmatter = frontmatterMatch[1];
+ for (const line of frontmatter.split('\n')) {
+ const colonIndex = line.indexOf(':');
+ if (colonIndex > 0) {
+ const key = line.substring(0, colonIndex).trim();
+ let value: unknown = line.substring(colonIndex + 1).trim();
+
+ // Parse common types
+ if (value === 'true') value = true;
+ else if (value === 'false') value = false;
+ else if (/^\d+$/.test(value as string)) value = parseInt(value as string, 10);
+ else if (value.startsWith('[') && value.endsWith(']')) {
+ try {
+ value = JSON.parse(value.replace(/'/g, '"'));
+ } catch {
+ // Keep as string
+ }
+ }
+
+ metadata[key] = value;
+ }
+ }
+ body = frontmatterMatch[2];
+ } catch {
+ // Failed to parse frontmatter, use whole content
+ }
+ }
+
+ // Derive key from file path
+ const relativePath = path.relative(basePath, filePath);
+ const key = relativePath
+ .replace(/\\/g, '/')
+ .replace(/\.md$/, '')
+ .replace(/\//g, ':');
+
+ // Derive namespace from directory structure
+ const namespace = path.dirname(relativePath).replace(/\\/g, '/') || 'default';
+
+ return {
+ key,
+ value: body.trim(),
+ namespace,
+ tags: Array.isArray(metadata.tags) ? metadata.tags : [],
+ metadata,
+ timestamp: Date.now(),
+ };
+ }
+}
+
+/**
+ * Convenience function to create a migrator
+ */
+export function createMigrator(
+ target: AgentDBAdapter,
+ source: MigrationSource,
+ sourcePath: string,
+ options: Partial<MigrationConfig> = {},
+ embeddingGenerator?: EmbeddingGenerator
+): MemoryMigrator {
+ return new MemoryMigrator(
+ target,
+ { source, sourcePath, ...options },
+ embeddingGenerator
+ );
+}
+
+/**
+ * Migrate from multiple sources
+ */
+export async function migrateMultipleSources(
+ target: AgentDBAdapter,
+ sources: Array<{ source: MigrationSource; path: string }>,
+ options: Partial<MigrationConfig> = {},
+ embeddingGenerator?: EmbeddingGenerator
+): Promise<MigrationResult[]> {
+ const results: MigrationResult[] = [];
+
+ for (const { source, path: sourcePath } of sources) {
+ const migrator = createMigrator(
+ target,
+ source,
+ sourcePath,
+ options,
+ embeddingGenerator
+ );
+ const result = await migrator.migrate();
+ results.push(result);
+ }
+
+ return results;
+}
+
+export default MemoryMigrator;
diff --git a/v3/@claude-flow/memory/src/query-builder.ts b/v3/@claude-flow/memory/src/query-builder.ts
new file mode 100644
index 0000000000..7e50e67327
--- /dev/null
+++ b/v3/@claude-flow/memory/src/query-builder.ts
@@ -0,0 +1,542 @@
+/**
+ * V3 Query Builder
+ *
+ * Fluent API for building memory queries with filter chaining,
+ * sorting options, and pagination support.
+ *
+ * @module v3/memory/query-builder
+ */
+
+import {
+ MemoryQuery,
+ QueryType,
+ MemoryType,
+ AccessLevel,
+ DistanceMetric,
+} from './types.js';
+
+/**
+ * Sort direction
+ */
+export type SortDirection = 'asc' | 'desc';
+
+/**
+ * Sort field options
+ */
+export type SortField =
+ | 'createdAt'
+ | 'updatedAt'
+ | 'lastAccessedAt'
+ | 'accessCount'
+ | 'key'
+ | 'score';
+
+/**
+ * Query builder state
+ */
+interface QueryBuilderState {
+ type: QueryType;
+ content?: string;
+ embedding?: Float32Array;
+ key?: string;
+ keyPrefix?: string;
+ namespace?: string;
+ tags: string[];
+ memoryType?: MemoryType;
+ accessLevel?: AccessLevel;
+ ownerId?: string;
+ metadata: Record<string, unknown>;
+ createdAfter?: number;
+ createdBefore?: number;
+ updatedAfter?: number;
+ updatedBefore?: number;
+ limit: number;
+ offset: number;
+ threshold?: number;
+ includeExpired: boolean;
+ distanceMetric?: DistanceMetric;
+ sortField?: SortField;
+ sortDirection: SortDirection;
+}
+
+/**
+ * Fluent query builder for constructing memory queries
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder()
+ * .semantic('user authentication patterns')
+ * .inNamespace('security')
+ * .withTags(['auth', 'patterns'])
+ * .ofType('semantic')
+ * .limit(10)
+ * .threshold(0.8)
+ * .build();
+ * ```
+ */
+export class QueryBuilder {
+ private state: QueryBuilderState;
+
+ constructor() {
+ this.state = {
+ type: 'hybrid',
+ tags: [],
+ metadata: {},
+ limit: 10,
+ offset: 0,
+ includeExpired: false,
+ sortDirection: 'desc',
+ };
+ }
+
+ /**
+ * Create a semantic (vector similarity) query
+ */
+ semantic(content: string): this {
+ this.state.type = 'semantic';
+ this.state.content = content;
+ return this;
+ }
+
+ /**
+ * Create a semantic query with pre-computed embedding
+ */
+ semanticWithEmbedding(embedding: Float32Array): this {
+ this.state.type = 'semantic';
+ this.state.embedding = embedding;
+ return this;
+ }
+
+ /**
+ * Create an exact key match query
+ */
+ exact(key: string): this {
+ this.state.type = 'exact';
+ this.state.key = key;
+ return this;
+ }
+
+ /**
+ * Create a key prefix match query
+ */
+ prefix(keyPrefix: string): this {
+ this.state.type = 'prefix';
+ this.state.keyPrefix = keyPrefix;
+ return this;
+ }
+
+ /**
+ * Create a tag-based query
+ */
+ byTags(tags: string[]): this {
+ this.state.type = 'tag';
+ this.state.tags = tags;
+ return this;
+ }
+
+ /**
+ * Create a hybrid query (semantic + filters)
+ */
+ hybrid(content: string): this {
+ this.state.type = 'hybrid';
+ this.state.content = content;
+ return this;
+ }
+
+ /**
+ * Filter by namespace
+ */
+ inNamespace(namespace: string): this {
+ this.state.namespace = namespace;
+ return this;
+ }
+
+ /**
+ * Add tag filter (entries must have all specified tags)
+ */
+ withTags(tags: string[]): this {
+ this.state.tags = [...this.state.tags, ...tags];
+ return this;
+ }
+
+ /**
+ * Add a single tag filter
+ */
+ withTag(tag: string): this {
+ this.state.tags.push(tag);
+ return this;
+ }
+
+ /**
+ * Filter by memory type
+ */
+ ofType(type: MemoryType): this {
+ this.state.memoryType = type;
+ return this;
+ }
+
+ /**
+ * Filter by access level
+ */
+ withAccessLevel(level: AccessLevel): this {
+ this.state.accessLevel = level;
+ return this;
+ }
+
+ /**
+ * Filter by owner
+ */
+ ownedBy(ownerId: string): this {
+ this.state.ownerId = ownerId;
+ return this;
+ }
+
+ /**
+ * Filter by metadata field
+ */
+ whereMetadata(key: string, value: unknown): this {
+ this.state.metadata[key] = value;
+ return this;
+ }
+
+ /**
+ * Filter by creation date range
+ */
+ createdBetween(after: Date | number, before?: Date | number): this {
+ this.state.createdAfter = after instanceof Date ? after.getTime() : after;
+ if (before !== undefined) {
+ this.state.createdBefore = before instanceof Date ? before.getTime() : before;
+ }
+ return this;
+ }
+
+ /**
+ * Filter entries created after a date
+ */
+ createdAfter(date: Date | number): this {
+ this.state.createdAfter = date instanceof Date ? date.getTime() : date;
+ return this;
+ }
+
+ /**
+ * Filter entries created before a date
+ */
+ createdBefore(date: Date | number): this {
+ this.state.createdBefore = date instanceof Date ? date.getTime() : date;
+ return this;
+ }
+
+ /**
+ * Filter by update date range
+ */
+ updatedBetween(after: Date | number, before?: Date | number): this {
+ this.state.updatedAfter = after instanceof Date ? after.getTime() : after;
+ if (before !== undefined) {
+ this.state.updatedBefore = before instanceof Date ? before.getTime() : before;
+ }
+ return this;
+ }
+
+ /**
+ * Filter entries updated in the last N milliseconds
+ */
+ updatedWithin(milliseconds: number): this {
+ this.state.updatedAfter = Date.now() - milliseconds;
+ return this;
+ }
+
+ /**
+ * Set maximum number of results
+ */
+ limit(count: number): this {
+ this.state.limit = Math.max(1, count);
+ return this;
+ }
+
+ /**
+ * Set pagination offset
+ */
+ offset(count: number): this {
+ this.state.offset = Math.max(0, count);
+ return this;
+ }
+
+ /**
+ * Set pagination with page number and size
+ */
+ page(pageNumber: number, pageSize: number): this {
+ this.state.limit = Math.max(1, pageSize);
+ this.state.offset = Math.max(0, (pageNumber - 1) * pageSize);
+ return this;
+ }
+
+ /**
+ * Set minimum similarity threshold for semantic search
+ */
+ threshold(minScore: number): this {
+ this.state.threshold = Math.max(0, Math.min(1, minScore));
+ return this;
+ }
+
+ /**
+ * Include expired entries in results
+ */
+ includeExpired(include: boolean = true): this {
+ this.state.includeExpired = include;
+ return this;
+ }
+
+ /**
+ * Set distance metric for semantic search
+ */
+ withMetric(metric: DistanceMetric): this {
+ this.state.distanceMetric = metric;
+ return this;
+ }
+
+ /**
+ * Sort results by field
+ */
+ sortBy(field: SortField, direction: SortDirection = 'desc'): this {
+ this.state.sortField = field;
+ this.state.sortDirection = direction;
+ return this;
+ }
+
+ /**
+ * Sort by creation date (newest first)
+ */
+ newestFirst(): this {
+ return this.sortBy('createdAt', 'desc');
+ }
+
+ /**
+ * Sort by creation date (oldest first)
+ */
+ oldestFirst(): this {
+ return this.sortBy('createdAt', 'asc');
+ }
+
+ /**
+ * Sort by relevance score (highest first)
+ */
+ mostRelevant(): this {
+ return this.sortBy('score', 'desc');
+ }
+
+ /**
+ * Sort by access count (most accessed first)
+ */
+ mostAccessed(): this {
+ return this.sortBy('accessCount', 'desc');
+ }
+
+ /**
+ * Sort by last accessed time (most recent first)
+ */
+ recentlyAccessed(): this {
+ return this.sortBy('lastAccessedAt', 'desc');
+ }
+
+ /**
+ * Build the final query object
+ */
+ build(): MemoryQuery {
+ const query: MemoryQuery = {
+ type: this.state.type,
+ limit: this.state.limit,
+ };
+
+ // Add optional fields
+ if (this.state.content) query.content = this.state.content;
+ if (this.state.embedding) query.embedding = this.state.embedding;
+ if (this.state.key) query.key = this.state.key;
+ if (this.state.keyPrefix) query.keyPrefix = this.state.keyPrefix;
+ if (this.state.namespace) query.namespace = this.state.namespace;
+ if (this.state.tags.length > 0) query.tags = this.state.tags;
+ if (this.state.memoryType) query.memoryType = this.state.memoryType;
+ if (this.state.accessLevel) query.accessLevel = this.state.accessLevel;
+ if (this.state.ownerId) query.ownerId = this.state.ownerId;
+ if (Object.keys(this.state.metadata).length > 0) {
+ query.metadata = this.state.metadata;
+ }
+ if (this.state.createdAfter) query.createdAfter = this.state.createdAfter;
+ if (this.state.createdBefore) query.createdBefore = this.state.createdBefore;
+ if (this.state.updatedAfter) query.updatedAfter = this.state.updatedAfter;
+ if (this.state.updatedBefore) query.updatedBefore = this.state.updatedBefore;
+ if (this.state.offset > 0) query.offset = this.state.offset;
+ if (this.state.threshold !== undefined) query.threshold = this.state.threshold;
+ if (this.state.includeExpired) query.includeExpired = this.state.includeExpired;
+ if (this.state.distanceMetric) query.distanceMetric = this.state.distanceMetric;
+
+ return query;
+ }
+
+ /**
+ * Clone this builder
+ */
+ clone(): QueryBuilder {
+ const cloned = new QueryBuilder();
+ cloned.state = {
+ ...this.state,
+ tags: [...this.state.tags],
+ metadata: { ...this.state.metadata },
+ };
+ return cloned;
+ }
+
+ /**
+ * Reset the builder to initial state
+ */
+ reset(): this {
+ this.state = {
+ type: 'hybrid',
+ tags: [],
+ metadata: {},
+ limit: 10,
+ offset: 0,
+ includeExpired: false,
+ sortDirection: 'desc',
+ };
+ return this;
+ }
+}
+
+/**
+ * Convenience function to create a new query builder
+ */
+export function query(): QueryBuilder {
+ return new QueryBuilder();
+}
+
+/**
+ * Predefined query templates for common use cases
+ */
+export const QueryTemplates = {
+ /**
+ * Find recent entries in a namespace
+ */
+ recentInNamespace(namespace: string, limit: number = 10): MemoryQuery {
+ return query()
+ .inNamespace(namespace)
+ .newestFirst()
+ .limit(limit)
+ .build();
+ },
+
+ /**
+ * Find entries by exact key
+ */
+ byKey(namespace: string, key: string): MemoryQuery {
+ return query()
+ .exact(key)
+ .inNamespace(namespace)
+ .limit(1)
+ .build();
+ },
+
+ /**
+ * Semantic search with threshold
+ */
+ semanticSearch(
+ content: string,
+ namespace?: string,
+ threshold: number = 0.7,
+ limit: number = 10
+ ): MemoryQuery {
+ const builder = query()
+ .semantic(content)
+ .threshold(threshold)
+ .limit(limit);
+
+ if (namespace) {
+ builder.inNamespace(namespace);
+ }
+
+ return builder.build();
+ },
+
+ /**
+ * Find entries with specific tags
+ */
+ withTags(tags: string[], namespace?: string, limit: number = 10): MemoryQuery {
+ const builder = query()
+ .byTags(tags)
+ .limit(limit);
+
+ if (namespace) {
+ builder.inNamespace(namespace);
+ }
+
+ return builder.build();
+ },
+
+ /**
+ * Find entries owned by a specific agent
+ */
+ ownedBy(ownerId: string, namespace?: string, limit: number = 10): MemoryQuery {
+ const builder = query()
+ .ownedBy(ownerId)
+ .newestFirst()
+ .limit(limit);
+
+ if (namespace) {
+ builder.inNamespace(namespace);
+ }
+
+ return builder.build();
+ },
+
+ /**
+ * Find episodic memories within a time range
+ */
+ episodicInRange(
+ after: Date | number,
+ before: Date | number,
+ limit: number = 100
+ ): MemoryQuery {
+ return query()
+ .ofType('episodic')
+ .createdBetween(after, before)
+ .oldestFirst()
+ .limit(limit)
+ .build();
+ },
+
+ /**
+ * Find hot entries (frequently accessed)
+ */
+ hotEntries(namespace?: string, limit: number = 10): MemoryQuery {
+ const builder = query()
+ .mostAccessed()
+ .limit(limit);
+
+ if (namespace) {
+ builder.inNamespace(namespace);
+ }
+
+ return builder.build();
+ },
+
+ /**
+ * Find stale entries (not accessed recently)
+ */
+ staleEntries(
+ staleThresholdMs: number,
+ namespace?: string,
+ limit: number = 100
+ ): MemoryQuery {
+ const builder = query()
+ .updatedBefore(Date.now() - staleThresholdMs)
+ .sortBy('lastAccessedAt', 'asc')
+ .limit(limit);
+
+ if (namespace) {
+ builder.inNamespace(namespace);
+ }
+
+ return builder.build();
+ },
+};
+
+export default QueryBuilder;
diff --git a/v3/@claude-flow/memory/src/types.ts b/v3/@claude-flow/memory/src/types.ts
new file mode 100644
index 0000000000..fe4b8c8d42
--- /dev/null
+++ b/v3/@claude-flow/memory/src/types.ts
@@ -0,0 +1,727 @@
+/**
+ * V3 Unified Memory Types
+ *
+ * Type definitions for the unified memory system based on AgentDB with HNSW indexing.
+ * Supports 150x-12,500x faster vector search compared to brute-force approaches.
+ *
+ * @module v3/memory/types
+ */
+
+// ===== Core Memory Entry Types =====
+
+/**
+ * Memory entry type classification
+ */
+export type MemoryType =
+ | 'episodic' // Time-based experiences and events
+ | 'semantic' // Facts, concepts, and knowledge
+ | 'procedural' // How-to knowledge and skills
+ | 'working' // Short-term operational memory
+ | 'cache'; // Temporary cached data
+
+/**
+ * Access level for memory entries
+ */
+export type AccessLevel =
+ | 'private' // Only owner can access
+ | 'team' // Team members can access
+ | 'swarm' // All swarm agents can access
+ | 'public' // Publicly accessible
+ | 'system'; // System-level access
+
+/**
+ * Consistency level for distributed memory operations
+ */
+export type ConsistencyLevel =
+ | 'strong' // Strong consistency (all nodes agree)
+ | 'eventual' // Eventual consistency (propagates over time)
+ | 'session' // Session-scoped consistency
+ | 'weak'; // Weak consistency (best effort)
+
+/**
+ * Distance metrics for vector similarity search
+ */
+export type DistanceMetric =
+ | 'cosine' // Cosine similarity (default)
+ | 'euclidean' // Euclidean distance (L2)
+ | 'dot' // Dot product
+ | 'manhattan'; // Manhattan distance (L1)
+
+// ===== Memory Entry =====
+
+/**
+ * Core memory entry structure with vector embedding support
+ */
+export interface MemoryEntry {
+ /** Unique identifier */
+ id: string;
+
+ /** Human-readable key for retrieval */
+ key: string;
+
+ /** Actual content of the memory */
+ content: string;
+
+ /** Vector embedding for semantic search (Float32Array for efficiency) */
+ embedding?: Float32Array;
+
+ /** Type of memory */
+ type: MemoryType;
+
+ /** Namespace for organization */
+ namespace: string;
+
+ /** Tags for categorization and filtering */
+ tags: string[];
+
+ /** Additional metadata */
+ metadata: Record<string, unknown>;
+
+ /** Owner agent ID */
+ ownerId?: string;
+
+ /** Access level */
+ accessLevel: AccessLevel;
+
+ /** Creation timestamp */
+ createdAt: number;
+
+ /** Last update timestamp */
+ updatedAt: number;
+
+ /** Expiration timestamp (optional) */
+ expiresAt?: number;
+
+ /** Version number for optimistic locking */
+ version: number;
+
+ /** References to other memory entries */
+ references: string[];
+
+ /** Access count for usage tracking */
+ accessCount: number;
+
+ /** Last access timestamp */
+ lastAccessedAt: number;
+}
+
+/**
+ * Input for creating a new memory entry
+ */
+export interface MemoryEntryInput {
+ key: string;
+ content: string;
+ type?: MemoryType;
+ namespace?: string;
+ tags?: string[];
+ metadata?: Record<string, unknown>;
+ ownerId?: string;
+ accessLevel?: AccessLevel;
+ expiresAt?: number;
+ references?: string[];
+}
+
+/**
+ * Partial update for a memory entry
+ */
+export interface MemoryEntryUpdate {
+ content?: string;
+ tags?: string[];
+ metadata?: Record<string, unknown>;
+ accessLevel?: AccessLevel;
+ expiresAt?: number;
+ references?: string[];
+}
+
+// ===== Query Types =====
+
+/**
+ * Query type for memory retrieval
+ */
+export type QueryType =
+ | 'semantic' // Vector similarity search
+ | 'exact' // Exact key match
+ | 'prefix' // Key prefix match
+ | 'tag' // Tag-based search
+ | 'hybrid'; // Combined semantic + filters
+
+/**
+ * Memory query specification
+ */
+export interface MemoryQuery {
+ /** Type of query to perform */
+ type: QueryType;
+
+ /** Content for semantic search (will be embedded) */
+ content?: string;
+
+ /** Pre-computed embedding for semantic search */
+ embedding?: Float32Array;
+
+ /** Exact key to match */
+ key?: string;
+
+ /** Key prefix to match */
+ keyPrefix?: string;
+
+ /** Namespace filter */
+ namespace?: string;
+
+ /** Tag filters (entries must have all specified tags) */
+ tags?: string[];
+
+ /** Memory type filter */
+ memoryType?: MemoryType;
+
+ /** Access level filter */
+ accessLevel?: AccessLevel;
+
+ /** Owner filter */
+ ownerId?: string;
+
+ /** Metadata filters */
+ metadata?: Record<string, unknown>;
+
+ /** Time range filters */
+ createdAfter?: number;
+ createdBefore?: number;
+ updatedAfter?: number;
+ updatedBefore?: number;
+
+ /** Maximum number of results */
+ limit: number;
+
+ /** Offset for pagination */
+ offset?: number;
+
+ /** Minimum similarity threshold (0-1) for semantic search */
+ threshold?: number;
+
+ /** Include expired entries */
+ includeExpired?: boolean;
+
+ /** Distance metric for semantic search */
+ distanceMetric?: DistanceMetric;
+}
+
+/**
+ * Search result with similarity score
+ */
+export interface SearchResult {
+ /** The memory entry */
+ entry: MemoryEntry;
+
+ /** Similarity score (0-1, higher is better) */
+ score: number;
+
+ /** Distance from query vector */
+ distance: number;
+}
+
+/**
+ * Search options for HNSW vector search
+ */
+export interface SearchOptions {
+ /** Number of results to return */
+ k: number;
+
+ /** Search expansion factor (higher = more accurate, slower) */
+ ef?: number;
+
+ /** Minimum similarity threshold (0-1) */
+ threshold?: number;
+
+ /** Distance metric */
+ metric?: DistanceMetric;
+
+ /** Additional filters to apply post-search */
+ filters?: MemoryQuery;
+}
+
+// ===== HNSW Index Types =====
+
+/**
+ * HNSW index configuration
+ */
+export interface HNSWConfig {
+ /** Vector dimensions (e.g., 1536 for OpenAI embeddings) */
+ dimensions: number;
+
+ /** Maximum number of connections per layer (default: 16) */
+ M: number;
+
+ /** Size of the dynamic candidate list during construction (default: 200) */
+ efConstruction: number;
+
+ /** Maximum elements the index can hold */
+ maxElements: number;
+
+ /** Distance metric */
+ metric: DistanceMetric;
+
+ /** Enable quantization for memory efficiency */
+ quantization?: QuantizationConfig;
+}
+
+/**
+ * Quantization configuration for memory reduction
+ */
+export interface QuantizationConfig {
+ /** Quantization type */
+ type: 'binary' | 'scalar' | 'product';
+
+ /** Number of bits for scalar quantization */
+ bits?: 4 | 8 | 16;
+
+ /** Number of subquantizers for product quantization */
+ subquantizers?: number;
+
+ /** Codebook size for product quantization */
+ codebookSize?: number;
+}
+
+/**
+ * HNSW index statistics
+ */
+export interface HNSWStats {
+ /** Total number of vectors in the index */
+ vectorCount: number;
+
+ /** Memory usage in bytes */
+ memoryUsage: number;
+
+ /** Average search time in milliseconds */
+ avgSearchTime: number;
+
+ /** Index build time in milliseconds */
+ buildTime: number;
+
+ /** Compression ratio if quantization is enabled */
+ compressionRatio?: number;
+}
+
+// ===== Backend Interface =====
+
+/**
+ * Memory backend interface for storage and retrieval
+ */
+export interface IMemoryBackend {
+ /** Initialize the backend */
+ initialize(): Promise<void>;
+
+ /** Shutdown the backend */
+ shutdown(): Promise<void>;
+
+ /** Store a memory entry */
+ store(entry: MemoryEntry): Promise<void>;
+
+ /** Retrieve a memory entry by ID */
+ get(id: string): Promise<MemoryEntry | null>;
+
+ /** Retrieve a memory entry by key within a namespace */
+ getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+
+ /** Update a memory entry */
+ update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+
+ /** Delete a memory entry */
+ delete(id: string): Promise<boolean>;
+
+ /** Query memory entries */
+ query(query: MemoryQuery): Promise<MemoryEntry[]>;
+
+ /** Semantic vector search */
+ search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+
+ /** Bulk insert entries */
+ bulkInsert(entries: MemoryEntry[]): Promise<void>;
+
+ /** Bulk delete entries */
+ bulkDelete(ids: string[]): Promise<number>;
+
+ /** Get entry count */
+ count(namespace?: string): Promise<number>;
+
+ /** List all namespaces */
+ listNamespaces(): Promise<string[]>;
+
+ /** Clear all entries in a namespace */
+ clearNamespace(namespace: string): Promise<number>;
+
+ /** Get backend statistics */
+ getStats(): Promise<BackendStats>;
+
+ /** Perform health check */
+ healthCheck(): Promise<HealthCheckResult>;
+}
+
+/**
+ * Backend statistics
+ */
+export interface BackendStats {
+ /** Total number of entries */
+ totalEntries: number;
+
+ /** Entries by namespace */
+ entriesByNamespace: Record<string, number>;
+
+ /** Entries by type */
+ entriesByType: Record<MemoryType, number>;
+
+ /** Total memory usage in bytes */
+ memoryUsage: number;
+
+ /** HNSW index statistics */
+ hnswStats?: HNSWStats;
+
+ /** Cache statistics */
+ cacheStats?: CacheStats;
+
+ /** Average query time in milliseconds */
+ avgQueryTime: number;
+
+ /** Average search time in milliseconds */
+ avgSearchTime: number;
+}
+
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+ /** Overall health status */
+ status: 'healthy' | 'degraded' | 'unhealthy';
+
+ /** Individual component health */
+ components: {
+ storage: ComponentHealth;
+ index: ComponentHealth;
+ cache: ComponentHealth;
+ };
+
+ /** Health check timestamp */
+ timestamp: number;
+
+ /** Any issues detected */
+ issues: string[];
+
+ /** Recommendations for improvement */
+ recommendations: string[];
+}
+
+/**
+ * Individual component health status
+ */
+export interface ComponentHealth {
+ status: 'healthy' | 'degraded' | 'unhealthy';
+ latency: number;
+ message?: string;
+}
+
+// ===== Cache Types =====
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+ /** Maximum number of entries in the cache */
+ maxSize: number;
+
+ /** Default TTL in milliseconds */
+ ttl: number;
+
+ /** Enable LRU eviction */
+ lruEnabled: boolean;
+
+ /** Maximum memory usage in bytes */
+ maxMemory?: number;
+
+ /** Enable write-through caching */
+ writeThrough: boolean;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+ /** Number of entries in cache */
+ size: number;
+
+ /** Cache hit rate (0-1) */
+ hitRate: number;
+
+ /** Total cache hits */
+ hits: number;
+
+ /** Total cache misses */
+ misses: number;
+
+ /** Total evictions */
+ evictions: number;
+
+ /** Memory usage in bytes */
+ memoryUsage: number;
+}
+
+/**
+ * Cached entry wrapper
+ */
+export interface CachedEntry<T> {
+ /** The cached data */
+ data: T;
+
+ /** When the entry was cached */
+ cachedAt: number;
+
+ /** When the entry expires */
+ expiresAt: number;
+
+ /** Last access timestamp */
+ lastAccessedAt: number;
+
+ /** Access count */
+ accessCount: number;
+}
+
+// ===== Migration Types =====
+
+/**
+ * Migration source type
+ */
+export type MigrationSource =
+ | 'sqlite'
+ | 'markdown'
+ | 'json'
+ | 'memory-manager'
+ | 'swarm-memory'
+ | 'distributed-memory';
+
+/**
+ * Migration configuration
+ */
+export interface MigrationConfig {
+ /** Source backend type */
+ source: MigrationSource;
+
+ /** Source path or connection string */
+ sourcePath: string;
+
+ /** Batch size for migration */
+ batchSize: number;
+
+ /** Generate embeddings during migration */
+ generateEmbeddings: boolean;
+
+ /** Validate data during migration */
+ validateData: boolean;
+
+ /** Continue on error */
+ continueOnError: boolean;
+
+ /** Namespace mapping */
+ namespaceMapping?: Record<string, string>;
+
+ /** Type mapping */
+ typeMapping?: Record<string, MemoryType>;
+}
+
+/**
+ * Migration progress
+ */
+export interface MigrationProgress {
+ /** Total entries to migrate */
+ total: number;
+
+ /** Entries migrated so far */
+ migrated: number;
+
+ /** Entries failed */
+ failed: number;
+
+ /** Entries skipped */
+ skipped: number;
+
+ /** Current batch number */
+ currentBatch: number;
+
+ /** Total batches */
+ totalBatches: number;
+
+ /** Progress percentage (0-100) */
+ percentage: number;
+
+ /** Estimated time remaining in milliseconds */
+ estimatedTimeRemaining: number;
+
+ /** Errors encountered */
+ errors: MigrationError[];
+}
+
+/**
+ * Migration error
+ */
+export interface MigrationError {
+ /** Entry ID or key that failed */
+ entryId: string;
+
+ /** Error message */
+ message: string;
+
+ /** Error code */
+ code: string;
+
+ /** Whether the error is recoverable */
+ recoverable: boolean;
+}
+
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+ /** Whether migration completed successfully */
+ success: boolean;
+
+ /** Final progress state */
+ progress: MigrationProgress;
+
+ /** Total time taken in milliseconds */
+ duration: number;
+
+ /** Summary message */
+ summary: string;
+}
+
+// ===== Event Types =====
+
+/**
+ * Memory event types
+ */
+export type MemoryEventType =
+ | 'entry:created'
+ | 'entry:updated'
+ | 'entry:deleted'
+ | 'entry:accessed'
+ | 'entry:expired'
+ | 'cache:hit'
+ | 'cache:miss'
+ | 'cache:eviction'
+ | 'index:rebuilt'
+ | 'migration:started'
+ | 'migration:progress'
+ | 'migration:completed'
+ | 'migration:failed';
+
+/**
+ * Memory event payload
+ */
+export interface MemoryEvent {
+ type: MemoryEventType;
+ timestamp: number;
+ data: Record<string, unknown>;
+}
+
+/**
+ * Memory event handler
+ */
+export type MemoryEventHandler = (event: MemoryEvent) => void | Promise<void>;
+
+// ===== SONA Integration Types =====
+
+/**
+ * SONA learning mode for adaptive memory
+ */
+export type SONAMode =
+ | 'real-time' // <0.05ms adaptation
+ | 'balanced' // Balance between speed and accuracy
+ | 'research' // Maximum accuracy, slower
+ | 'edge' // Optimized for edge devices
+ | 'batch'; // Batch processing mode
+
+/**
+ * Learning pattern from SONA integration
+ */
+export interface LearningPattern {
+ /** Pattern ID */
+ id: string;
+
+ /** Pattern data */
+ data: Record<string, unknown>;
+
+ /** SONA mode used */
+ mode: SONAMode;
+
+ /** Reward signal */
+ reward: number;
+
+ /** Trajectory data */
+ trajectory: unknown[];
+
+ /** Adaptation time in milliseconds */
+ adaptationTime: number;
+
+ /** Creation timestamp */
+ createdAt: number;
+}
+
+// ===== Utility Types =====
+
+/**
+ * Embedding generator function type
+ */
+export type EmbeddingGenerator = (content: string) => Promise<Float32Array>;
+
+/**
+ * Generates a unique memory ID
+ */
+export function generateMemoryId(): string {
+ const timestamp = Date.now().toString(36);
+ const random = Math.random().toString(36).substring(2, 10);
+ return `mem_${timestamp}_${random}`;
+}
+
+/**
+ * Creates a default memory entry
+ */
+export function createDefaultEntry(input: MemoryEntryInput): MemoryEntry {
+ const now = Date.now();
+ return {
+ id: generateMemoryId(),
+ key: input.key,
+ content: input.content,
+ type: input.type || 'semantic',
+ namespace: input.namespace || 'default',
+ tags: input.tags || [],
+ metadata: input.metadata || {},
+ ownerId: input.ownerId,
+ accessLevel: input.accessLevel || 'private',
+ createdAt: now,
+ updatedAt: now,
+ expiresAt: input.expiresAt,
+ version: 1,
+ references: input.references || [],
+ accessCount: 0,
+ lastAccessedAt: now,
+ };
+}
+
+/**
+ * Performance targets for V3 memory system
+ */
+export const PERFORMANCE_TARGETS = {
+ /** Maximum vector search time for 100k vectors */
+ MAX_SEARCH_TIME_100K: 1, // ms
+
+ /** Maximum write time per entry */
+ MAX_WRITE_TIME: 5, // ms
+
+ /** Maximum batch insert time per entry */
+ MAX_BATCH_INSERT_TIME: 1, // ms
+
+ /** Target memory reduction from legacy systems */
+ MEMORY_REDUCTION_TARGET: 0.5, // 50%
+
+ /** Minimum search improvement over brute force */
+ MIN_SEARCH_IMPROVEMENT: 150, // 150x
+
+ /** Maximum search improvement over brute force */
+ MAX_SEARCH_IMPROVEMENT: 12500, // 12,500x
+} as const;
diff --git a/v3/@claude-flow/memory/tsconfig.json b/v3/@claude-flow/memory/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/memory/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/neural/tsconfig.json b/v3/@claude-flow/neural/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/neural/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/performance/tsconfig.json b/v3/@claude-flow/performance/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/performance/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/security/tsconfig.json b/v3/@claude-flow/security/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/security/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/shared/tsconfig.json b/v3/@claude-flow/shared/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/shared/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/swarm/src/coordination/agent-registry.ts b/v3/@claude-flow/swarm/src/coordination/agent-registry.ts
new file mode 100644
index 0000000000..b7e5899feb
--- /dev/null
+++ b/v3/@claude-flow/swarm/src/coordination/agent-registry.ts
@@ -0,0 +1,544 @@
+/**
+ * V3 Agent Registry
+ * Manages registration, lifecycle, and capabilities of all 15 agents
+ *
+ * Based on ADR-002 (DDD) and 15-Agent Swarm Architecture
+ */
+
+import {
+ AgentId,
+ AgentRole,
+ AgentDomain,
+ AgentStatus,
+ AgentDefinition,
+ AgentState,
+ AgentCapability,
+ AgentMetrics,
+ TaskType,
+ TaskId,
+ SwarmEvent,
+ EventHandler
+} from '../shared/types';
+import {
+ IEventBus,
+ agentSpawnedEvent,
+ agentStatusChangedEvent,
+ agentErrorEvent
+} from '../shared/events';
+
+// =============================================================================
+// Agent Registry Interface
+// =============================================================================
+
+export interface IAgentRegistry {
+ // Registration
+ register(definition: AgentDefinition): void;
+ unregister(agentId: AgentId): boolean;
+ isRegistered(agentId: AgentId): boolean;
+
+ // Lifecycle
+ spawn(agentId: AgentId): Promise<AgentState>;
+ terminate(agentId: AgentId): Promise<boolean>;
+
+ // State Management
+ getState(agentId: AgentId): AgentState | undefined;
+ updateStatus(agentId: AgentId, status: AgentStatus): void;
+ assignTask(agentId: AgentId, taskId: TaskId): void;
+ completeTask(agentId: AgentId, taskId: TaskId): void;
+
+ // Queries
+ getDefinition(agentId: AgentId): AgentDefinition | undefined;
+ getAllAgents(): AgentDefinition[];
+ getActiveAgents(): AgentState[];
+ getAgentsByDomain(domain: AgentDomain): AgentDefinition[];
+ getAgentsByCapability(taskType: TaskType): AgentDefinition[];
+
+ // Health
+ heartbeat(agentId: AgentId): void;
+ getHealthStatus(): Map<AgentId, HealthStatus>;
+
+ // Events
+ onAgentEvent(handler: EventHandler): () => void;
+}
+
+export interface HealthStatus {
+ agentId: AgentId;
+ healthy: boolean;
+ lastHeartbeat: number;
+ consecutiveMisses: number;
+ status: AgentStatus;
+}
+
+// =============================================================================
+// Agent Registry Implementation
+// =============================================================================
+
+export class AgentRegistry implements IAgentRegistry {
+ private definitions: Map<AgentId, AgentDefinition> = new Map();
+ private states: Map<AgentId, AgentState> = new Map();
+ private healthChecks: Map<AgentId, HealthStatus> = new Map();
+ private eventBus: IEventBus;
+ private healthCheckInterval: number = 5000;
+ private healthCheckTimer: ReturnType<typeof setInterval> | null = null;
+ private maxMissedHeartbeats: number = 3;
+
+ constructor(eventBus: IEventBus) {
+ this.eventBus = eventBus;
+ this.registerDefaultAgents();
+ }
+
+ // ==========================================================================
+ // Registration
+ // ==========================================================================
+
+ register(definition: AgentDefinition): void {
+ if (this.definitions.has(definition.id)) {
+ throw new Error(`Agent ${definition.id} is already registered`);
+ }
+
+ this.definitions.set(definition.id, definition);
+
+ this.healthChecks.set(definition.id, {
+ agentId: definition.id,
+ healthy: false,
+ lastHeartbeat: 0,
+ consecutiveMisses: 0,
+ status: 'idle'
+ });
+ }
+
+ unregister(agentId: AgentId): boolean {
+ if (this.states.has(agentId)) {
+ throw new Error(`Cannot unregister active agent ${agentId}`);
+ }
+
+ this.healthChecks.delete(agentId);
+ return this.definitions.delete(agentId);
+ }
+
+ isRegistered(agentId: AgentId): boolean {
+ return this.definitions.has(agentId);
+ }
+
+ // ==========================================================================
+ // Lifecycle
+ // ==========================================================================
+
+ async spawn(agentId: AgentId): Promise<AgentState> {
+ const definition = this.definitions.get(agentId);
+ if (!definition) {
+ throw new Error(`Agent ${agentId} is not registered`);
+ }
+
+ if (this.states.has(agentId)) {
+ throw new Error(`Agent ${agentId} is already spawned`);
+ }
+
+ const state: AgentState = {
+ id: agentId,
+ role: definition.role,
+ status: 'idle',
+ currentTask: null,
+ completedTasks: [],
+ metrics: this.createInitialMetrics(),
+ lastHeartbeat: Date.now()
+ };
+
+ this.states.set(agentId, state);
+
+ const healthStatus = this.healthChecks.get(agentId)!;
+ healthStatus.healthy = true;
+ healthStatus.lastHeartbeat = Date.now();
+ healthStatus.status = 'idle';
+
+ await this.eventBus.emit(agentSpawnedEvent(agentId, definition.role));
+
+ return state;
+ }
+
+ async terminate(agentId: AgentId): Promise<boolean> {
+ const state = this.states.get(agentId);
+ if (!state) {
+ return false;
+ }
+
+ if (state.currentTask) {
+ throw new Error(`Cannot terminate agent ${agentId} with active task ${state.currentTask}`);
+ }
+
+ this.states.delete(agentId);
+
+ const healthStatus = this.healthChecks.get(agentId);
+ if (healthStatus) {
+ healthStatus.healthy = false;
+ healthStatus.status = 'idle';
+ }
+
+ await this.eventBus.emit(agentStatusChangedEvent(agentId, state.status, 'terminated'));
+
+ return true;
+ }
+
+ // ==========================================================================
+ // State Management
+ // ==========================================================================
+
+ getState(agentId: AgentId): AgentState | undefined {
+ return this.states.get(agentId);
+ }
+
+ updateStatus(agentId: AgentId, status: AgentStatus): void {
+ const state = this.states.get(agentId);
+ if (!state) {
+ throw new Error(`Agent ${agentId} is not spawned`);
+ }
+
+ const previousStatus = state.status;
+ state.status = status;
+
+ const healthStatus = this.healthChecks.get(agentId);
+ if (healthStatus) {
+ healthStatus.status = status;
+ }
+
+ this.eventBus.emitSync(agentStatusChangedEvent(agentId, previousStatus, status));
+ }
+
+ assignTask(agentId: AgentId, taskId: TaskId): void {
+ const state = this.states.get(agentId);
+ if (!state) {
+ throw new Error(`Agent ${agentId} is not spawned`);
+ }
+
+ if (state.currentTask) {
+ throw new Error(`Agent ${agentId} already has task ${state.currentTask}`);
+ }
+
+ state.currentTask = taskId;
+ this.updateStatus(agentId, 'active');
+ }
+
+ completeTask(agentId: AgentId, taskId: TaskId): void {
+ const state = this.states.get(agentId);
+ if (!state) {
+ throw new Error(`Agent ${agentId} is not spawned`);
+ }
+
+ if (state.currentTask !== taskId) {
+ throw new Error(`Agent ${agentId} current task is ${state.currentTask}, not ${taskId}`);
+ }
+
+ state.completedTasks.push(taskId);
+ state.currentTask = null;
+ state.metrics.tasksCompleted++;
+
+ this.updateStatus(agentId, 'idle');
+ }
+
+ // ==========================================================================
+ // Queries
+ // ==========================================================================
+
+ getDefinition(agentId: AgentId): AgentDefinition | undefined {
+ return this.definitions.get(agentId);
+ }
+
+ getAllAgents(): AgentDefinition[] {
+ return Array.from(this.definitions.values());
+ }
+
+ getActiveAgents(): AgentState[] {
+ return Array.from(this.states.values()).filter(s => s.status === 'active');
+ }
+
+ getAgentsByDomain(domain: AgentDomain): AgentDefinition[] {
+ return Array.from(this.definitions.values()).filter(d => d.domain === domain);
+ }
+
+ getAgentsByCapability(taskType: TaskType): AgentDefinition[] {
+ return Array.from(this.definitions.values()).filter(d =>
+ d.capabilities.some(c => c.supportedTaskTypes.includes(taskType))
+ );
+ }
+
+ // ==========================================================================
+ // Health Management
+ // ==========================================================================
+
+ heartbeat(agentId: AgentId): void {
+ const state = this.states.get(agentId);
+ if (state) {
+ state.lastHeartbeat = Date.now();
+ }
+
+ const healthStatus = this.healthChecks.get(agentId);
+ if (healthStatus) {
+ healthStatus.lastHeartbeat = Date.now();
+ healthStatus.consecutiveMisses = 0;
+ healthStatus.healthy = true;
+ }
+ }
+
+ getHealthStatus(): Map<AgentId, HealthStatus> {
+ return new Map(this.healthChecks);
+ }
+
+ startHealthChecks(): void {
+ if (this.healthCheckTimer) {
+ return;
+ }
+
+ this.healthCheckTimer = setInterval(() => {
+ this.performHealthCheck();
+ }, this.healthCheckInterval);
+ }
+
+ stopHealthChecks(): void {
+ if (this.healthCheckTimer) {
+ clearInterval(this.healthCheckTimer);
+ this.healthCheckTimer = null;
+ }
+ }
+
+ private performHealthCheck(): void {
+ const now = Date.now();
+
+ for (const [agentId, healthStatus] of this.healthChecks) {
+ const state = this.states.get(agentId);
+ if (!state) {
+ continue;
+ }
+
+ const timeSinceHeartbeat = now - healthStatus.lastHeartbeat;
+
+ if (timeSinceHeartbeat > this.healthCheckInterval) {
+ healthStatus.consecutiveMisses++;
+
+ if (healthStatus.consecutiveMisses >= this.maxMissedHeartbeats) {
+ healthStatus.healthy = false;
+ this.updateStatus(agentId, 'error');
+
+ this.eventBus.emitSync(agentErrorEvent(
+ agentId,
+ new Error(`Agent ${agentId} missed ${healthStatus.consecutiveMisses} heartbeats`)
+ ));
+ }
+ }
+ }
+ }
+
+ // ==========================================================================
+ // Events
+ // ==========================================================================
+
+ onAgentEvent(handler: EventHandler): () => void {
+ const unsubscribers = [
+ this.eventBus.subscribe('agent:spawned', handler),
+ this.eventBus.subscribe('agent:status-changed', handler),
+ this.eventBus.subscribe('agent:task-assigned', handler),
+ this.eventBus.subscribe('agent:task-completed', handler),
+ this.eventBus.subscribe('agent:error', handler)
+ ];
+
+ return () => {
+ unsubscribers.forEach(unsub => unsub());
+ };
+ }
+
+ // ==========================================================================
+ // Default Agent Registration
+ // ==========================================================================
+
+ private registerDefaultAgents(): void {
+ const agentDefinitions: AgentDefinition[] = [
+ {
+ id: 'agent-1',
+ role: 'queen-coordinator',
+ domain: 'core',
+ description: 'Orchestration & GitHub Issue management for all 15 agents',
+ capabilities: [
+ { name: 'orchestration', description: 'Coordinate all agents', supportedTaskTypes: ['architecture-design'] },
+ { name: 'github-management', description: 'Manage GitHub issues and PRs', supportedTaskTypes: ['documentation'] }
+ ],
+ dependencies: [],
+ priority: 1
+ },
+ {
+ id: 'agent-2',
+ role: 'security-architect',
+ domain: 'security',
+ description: 'Security architecture review and design',
+ capabilities: [
+ { name: 'security-design', description: 'Design security architecture', supportedTaskTypes: ['security-audit', 'architecture-design'] }
+ ],
+ dependencies: [],
+ priority: 2
+ },
+ {
+ id: 'agent-3',
+ role: 'security-implementer',
+ domain: 'security',
+ description: 'CVE fixes and security code implementation',
+ capabilities: [
+ { name: 'security-implementation', description: 'Implement security fixes', supportedTaskTypes: ['security-fix', 'implementation'] }
+ ],
+ dependencies: ['agent-2'],
+ priority: 2
+ },
+ {
+ id: 'agent-4',
+ role: 'security-tester',
+ domain: 'security',
+ description: 'Security testing using TDD London School methodology',
+ capabilities: [
+ { name: 'security-testing', description: 'Write and run security tests', supportedTaskTypes: ['security-test', 'test-writing'] }
+ ],
+ dependencies: ['agent-2'],
+ priority: 2
+ },
+ {
+ id: 'agent-5',
+ role: 'core-architect',
+ domain: 'core',
+ description: 'Core module DDD architecture design',
+ capabilities: [
+ { name: 'architecture', description: 'Design core architecture', supportedTaskTypes: ['architecture-design'] }
+ ],
+ dependencies: ['agent-2'],
+ priority: 3
+ },
+ {
+ id: 'agent-6',
+ role: 'core-implementer',
+ domain: 'core',
+ description: 'Core module implementation and type system modernization',
+ capabilities: [
+ { name: 'core-implementation', description: 'Implement core modules', supportedTaskTypes: ['implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 3
+ },
+ {
+ id: 'agent-7',
+ role: 'memory-specialist',
+ domain: 'core',
+ description: 'Memory system unification with AgentDB (150x-12500x improvement)',
+ capabilities: [
+ { name: 'memory-optimization', description: 'Optimize memory systems', supportedTaskTypes: ['memory-optimization', 'implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 4
+ },
+ {
+ id: 'agent-8',
+ role: 'swarm-specialist',
+ domain: 'core',
+ description: 'Single SwarmCoordinator (merge 4 systems)',
+ capabilities: [
+ { name: 'swarm-coordination', description: 'Design swarm coordination', supportedTaskTypes: ['swarm-coordination', 'implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 4
+ },
+ {
+ id: 'agent-9',
+ role: 'mcp-specialist',
+ domain: 'core',
+ description: 'MCP server optimization and enhancement',
+ capabilities: [
+ { name: 'mcp-optimization', description: 'Optimize MCP server', supportedTaskTypes: ['mcp-enhancement', 'implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 4
+ },
+ {
+ id: 'agent-10',
+ role: 'integration-architect',
+ domain: 'integration',
+ description: 'agentic-flow@alpha deep integration',
+ capabilities: [
+ { name: 'integration', description: 'Integrate with agentic-flow', supportedTaskTypes: ['integration', 'architecture-design'] }
+ ],
+ dependencies: ['agent-5', 'agent-7', 'agent-8', 'agent-9'],
+ priority: 5
+ },
+ {
+ id: 'agent-11',
+ role: 'cli-hooks-developer',
+ domain: 'integration',
+ description: 'CLI modernization and hooks system development',
+ capabilities: [
+ { name: 'cli-development', description: 'Develop CLI and hooks', supportedTaskTypes: ['cli-development', 'implementation'] }
+ ],
+ dependencies: ['agent-9', 'agent-10'],
+ priority: 5
+ },
+ {
+ id: 'agent-12',
+ role: 'neural-learning-dev',
+ domain: 'integration',
+ description: 'Neural and SONA learning system integration',
+ capabilities: [
+ { name: 'neural-training', description: 'Implement neural features', supportedTaskTypes: ['neural-training', 'implementation'] }
+ ],
+ dependencies: ['agent-7', 'agent-10'],
+ priority: 5
+ },
+ {
+ id: 'agent-13',
+ role: 'tdd-test-engineer',
+ domain: 'quality',
+ description: 'TDD London School methodology implementation',
+ capabilities: [
+ { name: 'testing', description: 'Write comprehensive tests', supportedTaskTypes: ['test-writing'] }
+ ],
+ dependencies: [],
+ priority: 3
+ },
+ {
+ id: 'agent-14',
+ role: 'performance-engineer',
+ domain: 'performance',
+ description: 'Benchmarking and performance optimization (2.49x-7.47x target)',
+ capabilities: [
+ { name: 'benchmarking', description: 'Run performance benchmarks', supportedTaskTypes: ['benchmark'] }
+ ],
+ dependencies: ['agent-7', 'agent-8'],
+ priority: 6
+ },
+ {
+ id: 'agent-15',
+ role: 'release-engineer',
+ domain: 'deployment',
+ description: 'Deployment pipeline and release management',
+ capabilities: [
+ { name: 'deployment', description: 'Manage releases', supportedTaskTypes: ['deployment', 'documentation'] }
+ ],
+ dependencies: ['agent-10', 'agent-13', 'agent-14'],
+ priority: 7
+ }
+ ];
+
+ for (const definition of agentDefinitions) {
+ this.register(definition);
+ }
+ }
+
+ private createInitialMetrics(): AgentMetrics {
+ return {
+ tasksCompleted: 0,
+ tasksFailed: 0,
+ averageTaskDuration: 0,
+ utilization: 0,
+ startTime: Date.now()
+ };
+ }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+export function createAgentRegistry(eventBus: IEventBus): IAgentRegistry {
+ return new AgentRegistry(eventBus);
+}
diff --git a/v3/@claude-flow/swarm/src/coordination/index.ts b/v3/@claude-flow/swarm/src/coordination/index.ts
new file mode 100644
index 0000000000..dddd319012
--- /dev/null
+++ b/v3/@claude-flow/swarm/src/coordination/index.ts
@@ -0,0 +1,23 @@
+/**
+ * Coordination Components
+ * Agent registry, task orchestration, and swarm hub
+ */
+
+export {
+ AgentRegistry,
+ createAgentRegistry,
+ type IAgentRegistry,
+} from './agent-registry.js';
+
+export {
+ TaskOrchestrator,
+ createTaskOrchestrator,
+ type ITaskOrchestrator,
+ type TaskSpec,
+} from './task-orchestrator.js';
+
+export {
+ SwarmHub,
+ createSwarmHub,
+ type ISwarmHub,
+} from './swarm-hub.js';
diff --git a/v3/@claude-flow/swarm/src/coordination/swarm-hub.ts b/v3/@claude-flow/swarm/src/coordination/swarm-hub.ts
new file mode 100644
index 0000000000..e5e5915fa6
--- /dev/null
+++ b/v3/@claude-flow/swarm/src/coordination/swarm-hub.ts
@@ -0,0 +1,681 @@
+/**
+ * V3 Swarm Hub
+ * Central coordination hub for the 15-agent hierarchical mesh swarm
+ *
+ * Based on ADR-001 (agentic-flow integration), ADR-003 (Single Coordination Engine),
+ * and the 15-Agent Swarm Architecture
+ */
+
+import {
+ AgentId,
+ AgentRole,
+ AgentDomain,
+ AgentState,
+ TaskId,
+ TaskDefinition,
+ TaskResult,
+ PhaseId,
+ PhaseDefinition,
+ MilestoneDefinition,
+ TopologyType,
+ SwarmConfig,
+ SwarmState,
+ SwarmMetrics,
+ SwarmMessage,
+ MessageType,
+ MessageHandler,
+ EventHandler,
+ V3_PERFORMANCE_TARGETS
+} from '../shared/types';
+import {
+ IEventBus,
+ EventBus,
+ swarmInitializedEvent,
+ swarmPhaseChangedEvent,
+ swarmMilestoneReachedEvent,
+ swarmErrorEvent
+} from '../shared/events';
+import { IAgentRegistry, AgentRegistry, createAgentRegistry } from './agent-registry';
+import { ITaskOrchestrator, TaskOrchestrator, TaskSpec, createTaskOrchestrator } from './task-orchestrator';
+
+// =============================================================================
+// Swarm Hub Interface
+// =============================================================================
+
+export interface ISwarmHub {
+ // Lifecycle
+ initialize(config?: Partial<SwarmConfig>): Promise<void>;
+ shutdown(): Promise<void>;
+ isInitialized(): boolean;
+
+ // Agent Management
+ spawnAgent(agentId: AgentId): Promise<AgentState>;
+ spawnAllAgents(): Promise<Map<AgentId, AgentState>>;
+ spawnAgentsByDomain(domain: AgentDomain): Promise<AgentState[]>;
+ terminateAgent(agentId: AgentId): Promise<boolean>;
+
+ // Task Management
+ submitTask(spec: TaskSpec): TaskDefinition;
+ submitBatchTasks(specs: TaskSpec[]): TaskDefinition[];
+ assignNextTask(agentId: AgentId): TaskDefinition | undefined;
+ completeTask(taskId: TaskId, result: TaskResult): void;
+
+ // Phase Management
+ getCurrentPhase(): PhaseId;
+ advancePhase(): PhaseId;
+ getPhaseDefinition(phaseId: PhaseId): PhaseDefinition;
+
+ // Milestone Tracking
+ getMilestones(): MilestoneDefinition[];
+ completeMilestone(milestoneId: string): void;
+
+ // Messaging
+ sendMessage<T>(message: Omit<SwarmMessage<T>, 'id' | 'timestamp'>): void;
+ broadcast<T>(from: AgentId, type: MessageType, payload: T): void;
+ onMessage<T>(handler: MessageHandler<T>): () => void;
+
+ // Metrics & Status
+ getState(): SwarmState;
+ getMetrics(): SwarmMetrics;
+ getAgentRegistry(): IAgentRegistry;
+ getTaskOrchestrator(): ITaskOrchestrator;
+
+ // Events
+ onSwarmEvent(handler: EventHandler): () => void;
+}
+
+// =============================================================================
+// Swarm Hub Implementation
+// =============================================================================
+
+export class SwarmHub implements ISwarmHub {
+ private initialized: boolean = false;
+ private config: SwarmConfig;
+ private eventBus: IEventBus;
+ private agentRegistry: IAgentRegistry;
+ private taskOrchestrator: ITaskOrchestrator;
+ private currentPhase: PhaseId = 'phase-1-foundation';
+ private phases: Map<PhaseId, PhaseDefinition>;
+ private milestones: Map<string, MilestoneDefinition> = new Map();
+ private messageHandlers: Set<MessageHandler> = new Set();
+ private messageCounter: number = 0;
+ private startTime: number = 0;
+
+ constructor(eventBus?: IEventBus) {
+ this.eventBus = eventBus ?? new EventBus();
+ this.agentRegistry = createAgentRegistry(this.eventBus);
+ this.taskOrchestrator = createTaskOrchestrator(this.eventBus, this.agentRegistry);
+ this.phases = this.createPhaseDefinitions();
+ this.config = this.getDefaultConfig();
+ }
+
+ // ==========================================================================
+ // Lifecycle
+ // ==========================================================================
+
+ async initialize(config?: Partial<SwarmConfig>): Promise<void> {
+ if (this.initialized) {
+ throw new Error('SwarmHub is already initialized');
+ }
+
+ this.config = { ...this.config, ...config };
+ this.startTime = Date.now();
+
+ this.initializeMilestones();
+
+ (this.agentRegistry as AgentRegistry).startHealthChecks();
+
+ this.initialized = true;
+
+ await this.eventBus.emit(swarmInitializedEvent({
+ topology: this.config.topology,
+ maxAgents: this.config.maxAgents,
+ performanceTargets: V3_PERFORMANCE_TARGETS
+ }));
+
+ console.log(`[SwarmHub] Initialized with ${this.config.topology} topology`);
+ }
+
+ async shutdown(): Promise<void> {
+ if (!this.initialized) {
+ return;
+ }
+
+ (this.agentRegistry as AgentRegistry).stopHealthChecks();
+
+ const activeAgents = this.agentRegistry.getActiveAgents();
+ for (const agent of activeAgents) {
+ try {
+ await this.terminateAgent(agent.id);
+ } catch (err) {
+ console.error(`[SwarmHub] Error terminating agent ${agent.id}: ${err}`);
+ }
+ }
+
+ this.initialized = false;
+ console.log('[SwarmHub] Shutdown complete');
+ }
+
+ isInitialized(): boolean {
+ return this.initialized;
+ }
+
+ // ==========================================================================
+ // Agent Management
+ // ==========================================================================
+
+ async spawnAgent(agentId: AgentId): Promise<AgentState> {
+ this.ensureInitialized();
+ return this.agentRegistry.spawn(agentId);
+ }
+
+ async spawnAllAgents(): Promise<Map<AgentId, AgentState>> {
+ this.ensureInitialized();
+
+ const results = new Map<AgentId, AgentState>();
+ const allAgents = this.agentRegistry.getAllAgents();
+
+ const sortedAgents = allAgents.sort((a, b) => a.priority - b.priority);
+
+ for (const agent of sortedAgents) {
+ try {
+ const state = await this.spawnAgent(agent.id);
+ results.set(agent.id, state);
+ } catch (err) {
+ console.error(`[SwarmHub] Failed to spawn agent ${agent.id}: ${err}`);
+ }
+ }
+
+ return results;
+ }
+
+ async spawnAgentsByDomain(domain: AgentDomain): Promise<AgentState[]> {
+ this.ensureInitialized();
+
+ const domainAgents = this.agentRegistry.getAgentsByDomain(domain);
+ const results: AgentState[] = [];
+
+ for (const agent of domainAgents) {
+ try {
+ const state = await this.spawnAgent(agent.id);
+ results.push(state);
+ } catch (err) {
+ console.error(`[SwarmHub] Failed to spawn agent ${agent.id}: ${err}`);
+ }
+ }
+
+ return results;
+ }
+
+ async terminateAgent(agentId: AgentId): Promise<boolean> {
+ this.ensureInitialized();
+ return this.agentRegistry.terminate(agentId);
+ }
+
+ // ==========================================================================
+ // Task Management
+ // ==========================================================================
+
+ submitTask(spec: TaskSpec): TaskDefinition {
+ this.ensureInitialized();
+ return this.taskOrchestrator.createTask(spec);
+ }
+
+ submitBatchTasks(specs: TaskSpec[]): TaskDefinition[] {
+ this.ensureInitialized();
+ return this.taskOrchestrator.createBatchTasks(specs);
+ }
+
+ assignNextTask(agentId: AgentId): TaskDefinition | undefined {
+ this.ensureInitialized();
+
+ const nextTask = this.taskOrchestrator.getNextTask(agentId);
+ if (nextTask) {
+ this.taskOrchestrator.queueTask(nextTask.id);
+ this.taskOrchestrator.assignTask(nextTask.id, agentId);
+ this.taskOrchestrator.startTask(nextTask.id);
+ }
+
+ return nextTask;
+ }
+
+ completeTask(taskId: TaskId, result: TaskResult): void {
+ this.ensureInitialized();
+
+ if (result.success) {
+ this.taskOrchestrator.completeTask(taskId, result);
+ } else {
+ this.taskOrchestrator.failTask(taskId, result.error ?? new Error('Unknown error'));
+ }
+ }
+
+ // ==========================================================================
+ // Phase Management
+ // ==========================================================================
+
+ getCurrentPhase(): PhaseId {
+ return this.currentPhase;
+ }
+
+ advancePhase(): PhaseId {
+ const phaseOrder: PhaseId[] = [
+ 'phase-1-foundation',
+ 'phase-2-core',
+ 'phase-3-integration',
+ 'phase-4-release'
+ ];
+
+ const currentIndex = phaseOrder.indexOf(this.currentPhase);
+ if (currentIndex < phaseOrder.length - 1) {
+ const previousPhase = this.currentPhase;
+ this.currentPhase = phaseOrder[currentIndex + 1];
+
+ this.eventBus.emitSync(swarmPhaseChangedEvent(previousPhase, this.currentPhase));
+
+ console.log(`[SwarmHub] Advanced from ${previousPhase} to ${this.currentPhase}`);
+ }
+
+ return this.currentPhase;
+ }
+
+ getPhaseDefinition(phaseId: PhaseId): PhaseDefinition {
+ const phase = this.phases.get(phaseId);
+ if (!phase) {
+ throw new Error(`Phase ${phaseId} not found`);
+ }
+ return phase;
+ }
+
+ // ==========================================================================
+ // Milestone Tracking
+ // ==========================================================================
+
+ getMilestones(): MilestoneDefinition[] {
+ return Array.from(this.milestones.values());
+ }
+
+ completeMilestone(milestoneId: string): void {
+ const milestone = this.milestones.get(milestoneId);
+ if (!milestone) {
+ throw new Error(`Milestone ${milestoneId} not found`);
+ }
+
+ milestone.status = 'completed';
+ milestone.completedAt = Date.now();
+
+ this.eventBus.emitSync(swarmMilestoneReachedEvent(milestoneId, milestone.name));
+
+ console.log(`[SwarmHub] Milestone completed: ${milestone.name}`);
+ }
+
+ // ==========================================================================
+ // Messaging
+ // ==========================================================================
+
+ sendMessage<T>(message: Omit<SwarmMessage<T>, 'id' | 'timestamp'>): void {
+ const fullMessage: SwarmMessage<T> = {
+ ...message,
+ id: `msg-${Date.now()}-${++this.messageCounter}`,
+ timestamp: Date.now()
+ };
+
+ for (const handler of this.messageHandlers) {
+ try {
+ handler(fullMessage);
+ } catch (err) {
+ console.error(`[SwarmHub] Message handler error: ${err}`);
+ }
+ }
+ }
+
+ broadcast<T>(from: AgentId, type: MessageType, payload: T): void {
+ this.sendMessage({
+ type,
+ from,
+ to: 'broadcast',
+ payload,
+ correlationId: null
+ });
+ }
+
+ onMessage<T>(handler: MessageHandler<T>): () => void {
+ this.messageHandlers.add(handler as MessageHandler);
+
+ return () => {
+ this.messageHandlers.delete(handler as MessageHandler);
+ };
+ }
+
+ // ==========================================================================
+ // Metrics & Status
+ // ==========================================================================
+
+ getState(): SwarmState {
+ const allAgents = this.agentRegistry.getAllAgents();
+ const agents = new Map<AgentId, AgentState>();
+
+ for (const agent of allAgents) {
+ const state = this.agentRegistry.getState(agent.id);
+ if (state) {
+ agents.set(agent.id, state);
+ }
+ }
+
+ const allTasks = this.taskOrchestrator.getAllTasks();
+ const tasks = new Map<TaskId, TaskDefinition>();
+
+ for (const task of allTasks) {
+ tasks.set(task.id, task);
+ }
+
+ return {
+ initialized: this.initialized,
+ topology: this.config.topology,
+ agents,
+ tasks,
+ currentPhase: this.currentPhase,
+ metrics: this.getMetrics()
+ };
+ }
+
+ getMetrics(): SwarmMetrics {
+ const activeAgents = this.agentRegistry.getActiveAgents();
+ const allAgents = this.agentRegistry.getAllAgents();
+ const taskMetrics = this.taskOrchestrator.getTaskMetrics();
+
+ const idleAgents = allAgents.filter(a => {
+ const state = this.agentRegistry.getState(a.id);
+ return state && state.status === 'idle';
+ }).length;
+
+ const blockedAgents = allAgents.filter(a => {
+ const state = this.agentRegistry.getState(a.id);
+ return state && state.status === 'blocked';
+ }).length;
+
+ const totalAgentsWithState = activeAgents.length + idleAgents + blockedAgents;
+
+ return {
+ totalAgents: allAgents.length,
+ activeAgents: activeAgents.length,
+ idleAgents,
+ blockedAgents,
+ totalTasks: taskMetrics.totalTasks,
+ completedTasks: taskMetrics.tasksByStatus['completed'],
+ failedTasks: taskMetrics.tasksByStatus['failed'],
+ pendingTasks: taskMetrics.tasksByStatus['pending'] + taskMetrics.tasksByStatus['queued'],
+ averageTaskDuration: taskMetrics.averageExecutionTime,
+ utilization: totalAgentsWithState > 0 ? activeAgents.length / totalAgentsWithState : 0,
+ startTime: this.startTime,
+ lastUpdate: Date.now()
+ };
+ }
+
+ getAgentRegistry(): IAgentRegistry {
+ return this.agentRegistry;
+ }
+
+ getTaskOrchestrator(): ITaskOrchestrator {
+ return this.taskOrchestrator;
+ }
+
+ // ==========================================================================
+ // Events
+ // ==========================================================================
+
+ onSwarmEvent(handler: EventHandler): () => void {
+ const unsubscribers = [
+ this.eventBus.subscribe('swarm:initialized', handler),
+ this.eventBus.subscribe('swarm:phase-changed', handler),
+ this.eventBus.subscribe('swarm:milestone-reached', handler),
+ this.eventBus.subscribe('swarm:error', handler)
+ ];
+
+ return () => {
+ unsubscribers.forEach(unsub => unsub());
+ };
+ }
+
+ // ==========================================================================
+ // Private Helpers
+ // ==========================================================================
+
+ private ensureInitialized(): void {
+ if (!this.initialized) {
+ throw new Error('SwarmHub is not initialized. Call initialize() first.');
+ }
+ }
+
+ private getDefaultConfig(): SwarmConfig {
+ return {
+ topology: 'hierarchical-mesh',
+ maxAgents: 15,
+ messageTimeout: 30000,
+ retryAttempts: 3,
+ healthCheckInterval: 5000,
+ loadBalancingStrategy: 'capability-match'
+ };
+ }
+
+ private createPhaseDefinitions(): Map<PhaseId, PhaseDefinition> {
+ const phases = new Map<PhaseId, PhaseDefinition>();
+
+ phases.set('phase-1-foundation', {
+ id: 'phase-1-foundation',
+ name: 'Foundation',
+ description: 'Security architecture, core design, and infrastructure setup',
+ weeks: [1, 2],
+ activeAgents: ['agent-1', 'agent-2', 'agent-3', 'agent-4', 'agent-5', 'agent-6'],
+ goals: [
+ 'Initialize swarm coordination',
+ 'Complete security architecture review',
+ 'Begin CVE fixes (CVE-1, CVE-2, CVE-3)',
+ 'Design core DDD architecture',
+ 'Modernize type system'
+ ],
+ milestones: []
+ });
+
+ phases.set('phase-2-core', {
+ id: 'phase-2-core',
+ name: 'Core Systems',
+ description: 'Core implementation, memory unification, and swarm coordination',
+ weeks: [3, 6],
+ activeAgents: ['agent-1', 'agent-5', 'agent-6', 'agent-7', 'agent-8', 'agent-9', 'agent-13'],
+ goals: [
+ 'Complete core module implementation',
+ 'Unify memory system with AgentDB (150x improvement)',
+ 'Merge 4 coordination systems into single SwarmCoordinator',
+ 'Optimize MCP server',
+ 'Implement TDD London School tests'
+ ],
+ milestones: []
+ });
+
+ phases.set('phase-3-integration', {
+ id: 'phase-3-integration',
+ name: 'Integration',
+ description: 'agentic-flow integration, CLI modernization, and neural features',
+ weeks: [7, 10],
+ activeAgents: ['agent-1', 'agent-10', 'agent-11', 'agent-12', 'agent-13', 'agent-14'],
+ goals: [
+ 'Complete agentic-flow@alpha integration',
+ 'Modernize CLI and hooks system',
+ 'Integrate Neural/SONA learning',
+ 'Run integration tests',
+ 'Initial performance benchmarks'
+ ],
+ milestones: []
+ });
+
+ phases.set('phase-4-release', {
+ id: 'phase-4-release',
+ name: 'Optimization & Release',
+ description: 'Performance optimization, deployment, and v3.0.0 release',
+ weeks: [11, 14],
+ activeAgents: [
+ 'agent-1', 'agent-2', 'agent-3', 'agent-4', 'agent-5', 'agent-6',
+ 'agent-7', 'agent-8', 'agent-9', 'agent-10', 'agent-11', 'agent-12',
+ 'agent-13', 'agent-14', 'agent-15'
+ ],
+ goals: [
+ 'Achieve 2.49x-7.47x Flash Attention speedup',
+ 'Verify 150x-12,500x AgentDB search improvement',
+ 'Complete deployment pipeline',
+ 'Final test coverage push (>90%)',
+ 'Release v3.0.0'
+ ],
+ milestones: []
+ });
+
+ return phases;
+ }
+
+ private initializeMilestones(): void {
+ const allMilestones: MilestoneDefinition[] = [
+ {
+ id: 'ms-security-architecture',
+ name: 'Security Architecture Complete',
+ description: 'All security reviews and CVE fixes implemented',
+ criteria: [
+ { description: 'CVE-1 fixed', met: false, evidence: null },
+ { description: 'CVE-2 fixed', met: false, evidence: null },
+ { description: 'CVE-3 fixed', met: false, evidence: null },
+ { description: 'Security tests passing', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-core-architecture',
+ name: 'Core Architecture Complete',
+ description: 'DDD structure implemented with all core modules',
+ criteria: [
+ { description: 'DDD bounded contexts defined', met: false, evidence: null },
+ { description: 'Core modules implemented', met: false, evidence: null },
+ { description: 'Type system modernized', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-memory-unification',
+ name: 'Memory Unification Complete',
+ description: 'Single memory service with AgentDB backend achieving 150x improvement',
+ criteria: [
+ { description: 'AgentDB integrated', met: false, evidence: null },
+ { description: '150x search improvement verified', met: false, evidence: null },
+ { description: 'Hybrid backend working', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-swarm-coordination',
+ name: 'Swarm Coordination Unified',
+ description: 'Single SwarmCoordinator merging 4 systems',
+ criteria: [
+ { description: 'Single CoordinationEngine', met: false, evidence: null },
+ { description: 'Pluggable strategies', met: false, evidence: null },
+ { description: '50% code reduction', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-agentic-integration',
+ name: 'agentic-flow Integration Complete',
+ description: 'Deep integration with agentic-flow@alpha eliminating duplicate code',
+ criteria: [
+ { description: 'Agent class extends agentic-flow', met: false, evidence: null },
+ { description: 'Swarm uses agentic-flow system', met: false, evidence: null },
+ { description: '<5,000 lines of orchestration code', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-performance-targets',
+ name: 'Performance Targets Met',
+ description: 'All performance targets achieved and verified',
+ criteria: [
+ { description: '2.49x-7.47x Flash Attention speedup', met: false, evidence: null },
+ { description: '150x-12,500x AgentDB search', met: false, evidence: null },
+ { description: '50-75% memory reduction', met: false, evidence: null },
+ { description: '<500ms startup time', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-v3-release',
+ name: 'V3.0.0 Released',
+ description: 'Claude-Flow v3.0.0 published to npm',
+ criteria: [
+ { description: 'All tests passing (>90% coverage)', met: false, evidence: null },
+ { description: 'Documentation complete', met: false, evidence: null },
+ { description: 'npm package published', met: false, evidence: null },
+ { description: 'GitHub release created', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ }
+ ];
+
+ for (const milestone of allMilestones) {
+ this.milestones.set(milestone.id, milestone);
+ }
+
+ for (const [phaseId, phase] of this.phases) {
+ switch (phaseId) {
+ case 'phase-1-foundation':
+ phase.milestones = [
+ this.milestones.get('ms-security-architecture')!,
+ this.milestones.get('ms-core-architecture')!
+ ];
+ break;
+ case 'phase-2-core':
+ phase.milestones = [
+ this.milestones.get('ms-memory-unification')!,
+ this.milestones.get('ms-swarm-coordination')!
+ ];
+ break;
+ case 'phase-3-integration':
+ phase.milestones = [
+ this.milestones.get('ms-agentic-integration')!
+ ];
+ break;
+ case 'phase-4-release':
+ phase.milestones = [
+ this.milestones.get('ms-performance-targets')!,
+ this.milestones.get('ms-v3-release')!
+ ];
+ break;
+ }
+ }
+ }
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+export function createSwarmHub(eventBus?: IEventBus): ISwarmHub {
+ return new SwarmHub(eventBus);
+}
+
+let globalSwarmHub: ISwarmHub | null = null;
+
+export function getSwarmHub(): ISwarmHub {
+ if (!globalSwarmHub) {
+ globalSwarmHub = createSwarmHub();
+ }
+ return globalSwarmHub;
+}
+
+export function resetSwarmHub(): void {
+ if (globalSwarmHub?.isInitialized()) {
+ globalSwarmHub.shutdown();
+ }
+ globalSwarmHub = null;
+}
diff --git a/v3/@claude-flow/swarm/src/coordination/task-orchestrator.ts b/v3/@claude-flow/swarm/src/coordination/task-orchestrator.ts
new file mode 100644
index 0000000000..77f526923a
--- /dev/null
+++ b/v3/@claude-flow/swarm/src/coordination/task-orchestrator.ts
@@ -0,0 +1,587 @@
+/**
+ * V3 Task Orchestrator
+ * Manages task decomposition, dependency resolution, and parallel execution
+ *
+ * Based on ADR-003 (Single Coordination Engine) and ADR-001 (agentic-flow integration)
+ */
+
+import {
+ TaskId,
+ TaskType,
+ TaskStatus,
+ TaskPriority,
+ TaskDefinition,
+ TaskMetadata,
+ TaskResult,
+ TaskResultMetrics,
+ AgentId,
+ AgentDomain,
+ PhaseId,
+ SwarmEvent
+} from '../shared/types';
+import {
+ IEventBus,
+ taskCreatedEvent,
+ taskQueuedEvent,
+ taskAssignedEvent,
+ taskStartedEvent,
+ taskCompletedEvent,
+ taskFailedEvent,
+ taskBlockedEvent
+} from '../shared/events';
+import { IAgentRegistry } from './agent-registry';
+
+// =============================================================================
+// Task Orchestrator Interface
+// =============================================================================
+
+export interface ITaskOrchestrator {
+ // Task Creation
+ createTask(spec: TaskSpec): TaskDefinition;
+ createBatchTasks(specs: TaskSpec[]): TaskDefinition[];
+
+ // Task Lifecycle
+ queueTask(taskId: TaskId): void;
+ assignTask(taskId: TaskId, agentId: AgentId): void;
+ startTask(taskId: TaskId): void;
+ completeTask(taskId: TaskId, result: TaskResult): void;
+ failTask(taskId: TaskId, error: Error): void;
+ cancelTask(taskId: TaskId): void;
+
+ // Dependency Management
+ addDependency(taskId: TaskId, dependsOn: TaskId): void;
+ removeDependency(taskId: TaskId, dependsOn: TaskId): void;
+ getDependencies(taskId: TaskId): TaskId[];
+ getDependents(taskId: TaskId): TaskId[];
+ isBlocked(taskId: TaskId): boolean;
+ getBlockingTasks(taskId: TaskId): TaskId[];
+
+ // Queries
+ getTask(taskId: TaskId): TaskDefinition | undefined;
+ getAllTasks(): TaskDefinition[];
+ getTasksByStatus(status: TaskStatus): TaskDefinition[];
+ getTasksByAgent(agentId: AgentId): TaskDefinition[];
+ getTasksByDomain(domain: AgentDomain): TaskDefinition[];
+ getTasksByPhase(phase: PhaseId): TaskDefinition[];
+
+ // Queue Management
+ getNextTask(agentId?: AgentId): TaskDefinition | undefined;
+ getPriorityQueue(): TaskDefinition[];
+
+ // Metrics
+ getTaskMetrics(): TaskOrchestratorMetrics;
+}
+
+export interface TaskSpec {
+ type: TaskType;
+ title: string;
+ description: string;
+ priority?: TaskPriority;
+ dependencies?: TaskId[];
+ domain: AgentDomain;
+ phase: PhaseId;
+ estimatedDuration?: number;
+ tags?: string[];
+}
+
+export interface TaskOrchestratorMetrics {
+ totalTasks: number;
+ tasksByStatus: Record<TaskStatus, number>;
+ tasksByPriority: Record<TaskPriority, number>;
+ tasksByDomain: Record<AgentDomain, number>;
+ averageQueueTime: number;
+ averageExecutionTime: number;
+ throughput: number;
+}
+
+// =============================================================================
+// Task Orchestrator Implementation
+// =============================================================================
+
+export class TaskOrchestrator implements ITaskOrchestrator {
+ private tasks: Map<TaskId, TaskDefinition> = new Map();
+ private dependencyGraph: Map<TaskId, Set<TaskId>> = new Map();
+ private dependentGraph: Map<TaskId, Set<TaskId>> = new Map();
+ private taskCounter: number = 0;
+ private eventBus: IEventBus;
+ private agentRegistry: IAgentRegistry;
+
+ constructor(eventBus: IEventBus, agentRegistry: IAgentRegistry) {
+ this.eventBus = eventBus;
+ this.agentRegistry = agentRegistry;
+
+ this.eventBus.subscribe('agent:task-completed', this.handleAgentTaskCompleted.bind(this));
+ }
+
+ // ==========================================================================
+ // Task Creation
+ // ==========================================================================
+
+ createTask(spec: TaskSpec): TaskDefinition {
+ const taskId: TaskId = `task-${Date.now()}-${++this.taskCounter}`;
+
+ const task: TaskDefinition = {
+ id: taskId,
+ type: spec.type,
+ title: spec.title,
+ description: spec.description,
+ assignedAgent: null,
+ status: 'pending',
+ priority: spec.priority ?? 'medium',
+ dependencies: spec.dependencies ?? [],
+ blockedBy: [],
+ metadata: {
+ domain: spec.domain,
+ phase: spec.phase,
+ estimatedDuration: spec.estimatedDuration ?? 0,
+ actualDuration: null,
+ retryCount: 0,
+ maxRetries: 3,
+ artifacts: [],
+ tags: spec.tags ?? []
+ },
+ createdAt: Date.now(),
+ updatedAt: Date.now(),
+ completedAt: null
+ };
+
+ this.tasks.set(taskId, task);
+ this.dependencyGraph.set(taskId, new Set(task.dependencies));
+ this.dependentGraph.set(taskId, new Set());
+
+ for (const depId of task.dependencies) {
+ if (this.dependentGraph.has(depId)) {
+ this.dependentGraph.get(depId)!.add(taskId);
+ }
+ }
+
+ this.updateBlockedStatus(taskId);
+
+ this.eventBus.emitSync(taskCreatedEvent(taskId, spec.type, spec.title));
+
+ return task;
+ }
+
+ createBatchTasks(specs: TaskSpec[]): TaskDefinition[] {
+ return specs.map(spec => this.createTask(spec));
+ }
+
+ // ==========================================================================
+ // Task Lifecycle
+ // ==========================================================================
+
+ queueTask(taskId: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (this.isBlocked(taskId)) {
+ this.updateTaskStatus(taskId, 'blocked');
+ return;
+ }
+
+ this.updateTaskStatus(taskId, 'queued');
+ this.eventBus.emitSync(taskQueuedEvent(taskId, task.priority));
+ }
+
+ assignTask(taskId: TaskId, agentId: AgentId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status !== 'queued') {
+ throw new Error(`Task ${taskId} is not queued (status: ${task.status})`);
+ }
+
+ if (this.isBlocked(taskId)) {
+ throw new Error(`Task ${taskId} is blocked by dependencies`);
+ }
+
+ task.assignedAgent = agentId;
+ this.updateTaskStatus(taskId, 'assigned');
+
+ this.agentRegistry.assignTask(agentId, taskId);
+
+ this.eventBus.emitSync(taskAssignedEvent(taskId, agentId));
+ }
+
+ startTask(taskId: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status !== 'assigned') {
+ throw new Error(`Task ${taskId} is not assigned (status: ${task.status})`);
+ }
+
+ this.updateTaskStatus(taskId, 'in-progress');
+
+ if (task.assignedAgent) {
+ this.eventBus.emitSync(taskStartedEvent(taskId, task.assignedAgent));
+ }
+ }
+
+ completeTask(taskId: TaskId, result: TaskResult): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status !== 'in-progress') {
+ throw new Error(`Task ${taskId} is not in progress (status: ${task.status})`);
+ }
+
+ task.metadata.actualDuration = result.duration;
+ task.completedAt = Date.now();
+
+ this.updateTaskStatus(taskId, 'completed');
+
+ if (task.assignedAgent) {
+ this.agentRegistry.completeTask(task.assignedAgent, taskId);
+ }
+
+ this.eventBus.emitSync(taskCompletedEvent(taskId, result));
+
+ this.unblockDependentTasks(taskId);
+ }
+
+ failTask(taskId: TaskId, error: Error): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ task.metadata.retryCount++;
+
+ if (task.metadata.retryCount < task.metadata.maxRetries) {
+ this.updateTaskStatus(taskId, 'queued');
+ task.assignedAgent = null;
+ } else {
+ this.updateTaskStatus(taskId, 'failed');
+
+ if (task.assignedAgent) {
+ const agentState = this.agentRegistry.getState(task.assignedAgent);
+ if (agentState) {
+ agentState.metrics.tasksFailed++;
+ }
+ }
+ }
+
+ this.eventBus.emitSync(taskFailedEvent(taskId, error));
+ }
+
+ cancelTask(taskId: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status === 'completed' || task.status === 'failed') {
+ throw new Error(`Cannot cancel ${task.status} task ${taskId}`);
+ }
+
+ if (task.assignedAgent) {
+ this.agentRegistry.updateStatus(task.assignedAgent, 'idle');
+ }
+
+ this.updateTaskStatus(taskId, 'cancelled');
+ }
+
+ // ==========================================================================
+ // Dependency Management
+ // ==========================================================================
+
+ addDependency(taskId: TaskId, dependsOn: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+ this.getTaskOrThrow(dependsOn);
+
+ if (this.wouldCreateCycle(taskId, dependsOn)) {
+ throw new Error(`Adding dependency ${dependsOn} to ${taskId} would create a cycle`);
+ }
+
+ task.dependencies.push(dependsOn);
+ this.dependencyGraph.get(taskId)!.add(dependsOn);
+ this.dependentGraph.get(dependsOn)!.add(taskId);
+
+ this.updateBlockedStatus(taskId);
+ }
+
+ removeDependency(taskId: TaskId, dependsOn: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ const index = task.dependencies.indexOf(dependsOn);
+ if (index > -1) {
+ task.dependencies.splice(index, 1);
+ }
+
+ this.dependencyGraph.get(taskId)?.delete(dependsOn);
+ this.dependentGraph.get(dependsOn)?.delete(taskId);
+
+ this.updateBlockedStatus(taskId);
+ }
+
+ getDependencies(taskId: TaskId): TaskId[] {
+ return Array.from(this.dependencyGraph.get(taskId) ?? []);
+ }
+
+ getDependents(taskId: TaskId): TaskId[] {
+ return Array.from(this.dependentGraph.get(taskId) ?? []);
+ }
+
+ isBlocked(taskId: TaskId): boolean {
+ const blockingTasks = this.getBlockingTasks(taskId);
+ return blockingTasks.length > 0;
+ }
+
+ getBlockingTasks(taskId: TaskId): TaskId[] {
+ const dependencies = this.dependencyGraph.get(taskId);
+ if (!dependencies) {
+ return [];
+ }
+
+ return Array.from(dependencies).filter(depId => {
+ const depTask = this.tasks.get(depId);
+ return depTask && depTask.status !== 'completed';
+ });
+ }
+
+ // ==========================================================================
+ // Queries
+ // ==========================================================================
+
+ getTask(taskId: TaskId): TaskDefinition | undefined {
+ return this.tasks.get(taskId);
+ }
+
+ getAllTasks(): TaskDefinition[] {
+ return Array.from(this.tasks.values());
+ }
+
+ getTasksByStatus(status: TaskStatus): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.status === status);
+ }
+
+ getTasksByAgent(agentId: AgentId): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.assignedAgent === agentId);
+ }
+
+ getTasksByDomain(domain: AgentDomain): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.metadata.domain === domain);
+ }
+
+ getTasksByPhase(phase: PhaseId): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.metadata.phase === phase);
+ }
+
+ // ==========================================================================
+ // Queue Management
+ // ==========================================================================
+
+ getNextTask(agentId?: AgentId): TaskDefinition | undefined {
+ const queuedTasks = this.getTasksByStatus('queued')
+ .filter(t => !this.isBlocked(t.id))
+ .sort((a, b) => {
+ const priorityOrder: Record<TaskPriority, number> = {
+ 'critical': 0,
+ 'high': 1,
+ 'medium': 2,
+ 'low': 3
+ };
+
+ const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+ if (priorityDiff !== 0) return priorityDiff;
+
+ return a.createdAt - b.createdAt;
+ });
+
+ if (!agentId) {
+ return queuedTasks[0];
+ }
+
+ const agentDef = this.agentRegistry.getDefinition(agentId);
+ if (!agentDef) {
+ return queuedTasks[0];
+ }
+
+ const supportedTypes = agentDef.capabilities.flatMap(c => c.supportedTaskTypes);
+
+ return queuedTasks.find(t => supportedTypes.includes(t.type));
+ }
+
+ getPriorityQueue(): TaskDefinition[] {
+ return this.getTasksByStatus('queued')
+ .filter(t => !this.isBlocked(t.id))
+ .sort((a, b) => {
+ const priorityOrder: Record<TaskPriority, number> = {
+ 'critical': 0,
+ 'high': 1,
+ 'medium': 2,
+ 'low': 3
+ };
+ return priorityOrder[a.priority] - priorityOrder[b.priority];
+ });
+ }
+
+ // ==========================================================================
+ // Metrics
+ // ==========================================================================
+
+ getTaskMetrics(): TaskOrchestratorMetrics {
+ const allTasks = this.getAllTasks();
+
+ const tasksByStatus: Record<TaskStatus, number> = {
+ 'pending': 0,
+ 'queued': 0,
+ 'assigned': 0,
+ 'in-progress': 0,
+ 'blocked': 0,
+ 'completed': 0,
+ 'failed': 0,
+ 'cancelled': 0
+ };
+
+ const tasksByPriority: Record<TaskPriority, number> = {
+ 'critical': 0,
+ 'high': 0,
+ 'medium': 0,
+ 'low': 0
+ };
+
+ const tasksByDomain: Record<AgentDomain, number> = {
+ 'security': 0,
+ 'core': 0,
+ 'integration': 0,
+ 'quality': 0,
+ 'performance': 0,
+ 'deployment': 0
+ };
+
+ let totalQueueTime = 0;
+ let totalExecutionTime = 0;
+ let completedCount = 0;
+
+ for (const task of allTasks) {
+ tasksByStatus[task.status]++;
+ tasksByPriority[task.priority]++;
+ tasksByDomain[task.metadata.domain]++;
+
+ if (task.status === 'completed' && task.metadata.actualDuration) {
+ totalExecutionTime += task.metadata.actualDuration;
+ completedCount++;
+ }
+ }
+
+ const now = Date.now();
+ const firstTask = allTasks[0];
+ const runtimeMs = firstTask ? now - firstTask.createdAt : 1;
+ const throughput = completedCount / (runtimeMs / 1000 / 60);
+
+ return {
+ totalTasks: allTasks.length,
+ tasksByStatus,
+ tasksByPriority,
+ tasksByDomain,
+ averageQueueTime: totalQueueTime / (completedCount || 1),
+ averageExecutionTime: totalExecutionTime / (completedCount || 1),
+ throughput
+ };
+ }
+
+ // ==========================================================================
+ // Private Helpers
+ // ==========================================================================
+
+ private getTaskOrThrow(taskId: TaskId): TaskDefinition {
+ const task = this.tasks.get(taskId);
+ if (!task) {
+ throw new Error(`Task ${taskId} not found`);
+ }
+ return task;
+ }
+
+ private updateTaskStatus(taskId: TaskId, status: TaskStatus): void {
+ const task = this.getTaskOrThrow(taskId);
+ task.status = status;
+ task.updatedAt = Date.now();
+
+ if (status === 'blocked') {
+ task.blockedBy = this.getBlockingTasks(taskId);
+ } else {
+ task.blockedBy = [];
+ }
+ }
+
+ private updateBlockedStatus(taskId: TaskId): void {
+ const task = this.tasks.get(taskId);
+ if (!task || task.status === 'completed' || task.status === 'failed') {
+ return;
+ }
+
+ const isBlocked = this.isBlocked(taskId);
+
+ if (isBlocked && task.status !== 'blocked') {
+ this.updateTaskStatus(taskId, 'blocked');
+ this.eventBus.emitSync(taskBlockedEvent(taskId, this.getBlockingTasks(taskId)));
+ } else if (!isBlocked && task.status === 'blocked') {
+ this.updateTaskStatus(taskId, 'queued');
+ }
+ }
+
+ private unblockDependentTasks(taskId: TaskId): void {
+ const dependents = this.getDependents(taskId);
+
+ for (const dependentId of dependents) {
+ this.updateBlockedStatus(dependentId);
+ }
+ }
+
+ private wouldCreateCycle(taskId: TaskId, newDependency: TaskId): boolean {
+ const visited = new Set<TaskId>();
+ const stack = [newDependency];
+
+ while (stack.length > 0) {
+ const current = stack.pop()!;
+
+ if (current === taskId) {
+ return true;
+ }
+
+ if (visited.has(current)) {
+ continue;
+ }
+
+ visited.add(current);
+
+ const deps = this.dependencyGraph.get(current);
+ if (deps) {
+ stack.push(...deps);
+ }
+ }
+
+ return false;
+ }
+
+ private handleAgentTaskCompleted(event: SwarmEvent): void {
+ const payload = event.payload as { taskId: TaskId; result: unknown };
+
+ if (payload.taskId && this.tasks.has(payload.taskId)) {
+ const task = this.tasks.get(payload.taskId)!;
+ if (task.status === 'in-progress') {
+ this.completeTask(payload.taskId, {
+ taskId: payload.taskId,
+ success: true,
+ output: payload.result,
+ error: null,
+ duration: Date.now() - task.updatedAt,
+ metrics: this.createDefaultMetrics()
+ });
+ }
+ }
+ }
+
+ private createDefaultMetrics(): TaskResultMetrics {
+ return {
+ linesOfCode: 0,
+ testsWritten: 0,
+ testsPassed: 0,
+ coveragePercent: 0,
+ performanceImpact: 0
+ };
+ }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+export function createTaskOrchestrator(
+ eventBus: IEventBus,
+ agentRegistry: IAgentRegistry
+): ITaskOrchestrator {
+ return new TaskOrchestrator(eventBus, agentRegistry);
+}
diff --git a/v3/@claude-flow/swarm/tsconfig.json b/v3/@claude-flow/swarm/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/swarm/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/@claude-flow/testing/tsconfig.json b/v3/@claude-flow/testing/tsconfig.json
new file mode 100644
index 0000000000..b813d42868
--- /dev/null
+++ b/v3/@claude-flow/testing/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "outDir": "./dist",
+ "rootDir": "./src"
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/v3/__tests__/acceptance/performance-targets.test.ts b/v3/__tests__/acceptance/performance-targets.test.ts
deleted file mode 100644
index b0d371b786..0000000000
--- a/v3/__tests__/acceptance/performance-targets.test.ts
+++ /dev/null
@@ -1,487 +0,0 @@
-/**
- * V3 Claude-Flow Performance Targets Acceptance Tests
- *
- * Acceptance tests for V3 performance requirements
- * Tests against ADR targets: 2.49x-7.47x speedup, 150x-12,500x search improvement
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface } from '../helpers/create-mock';
-import { assertPerformanceTarget } from '../helpers/assertions';
-import { performanceConfigs, memoryConfigs } from '../fixtures/configurations';
-import { agentDBTestData, generateMockEmbedding, createMemoryBatch } from '../fixtures/memory-entries';
-
-/**
- * Performance measurement interface
- */
-interface IPerformanceMeasurer {
- measure<T>(operation: () => Promise<T>): Promise<MeasurementResult<T>>;
- compare(baseline: number, optimized: number): SpeedupResult;
- recordMetric(name: string, value: number, unit: string): void;
- getReport(): PerformanceReport;
-}
-
-/**
- * Vector search interface for performance testing
- */
-interface IVectorSearchEngine {
- initialize(config: SearchConfig): Promise<void>;
- insert(entries: VectorEntry[]): Promise<number>;
- search(query: number[], topK: number): Promise<SearchResult[]>;
- getStats(): SearchStats;
-}
-
-/**
- * Memory optimizer interface
- */
-interface IMemoryOptimizer {
- analyze(): Promise<MemoryAnalysis>;
- optimize(): Promise<OptimizationResult>;
- getUsage(): MemoryUsage;
-}
-
-interface MeasurementResult<T> {
- result: T;
- duration: number;
- memory: number;
-}
-
-interface SpeedupResult {
- speedup: number;
- improvement: string;
- meetsTarget: boolean;
-}
-
-interface PerformanceReport {
- metrics: Map<string, { value: number; unit: string }>;
- summary: string;
-}
-
-interface SearchConfig {
- dimensions: number;
- indexType: 'hnsw' | 'flat';
- hnswConfig?: {
- M: number;
- efConstruction: number;
- efSearch: number;
- };
-}
-
-interface VectorEntry {
- id: string;
- embedding: number[];
- metadata?: Record<string, unknown>;
-}
-
-interface SearchResult {
- id: string;
- score: number;
-}
-
-interface SearchStats {
- totalEntries: number;
- indexSize: number;
- averageSearchTime: number;
- indexBuildTime: number;
-}
-
-interface MemoryAnalysis {
- totalMemory: number;
- usedMemory: number;
- potentialSavings: number;
- recommendations: string[];
-}
-
-interface OptimizationResult {
- originalSize: number;
- optimizedSize: number;
- reduction: number;
- techniquesApplied: string[];
-}
-
-interface MemoryUsage {
- heap: number;
- external: number;
- arrayBuffers: number;
-}
-
-/**
- * Mock performance measurer for testing
- */
-class PerformanceMeasurer implements IPerformanceMeasurer {
- private metrics: Map<string, { value: number; unit: string }> = new Map();
-
- async measure<T>(operation: () => Promise<T>): Promise<MeasurementResult<T>> {
- const startMemory = process.memoryUsage().heapUsed;
- const startTime = performance.now();
-
- const result = await operation();
-
- const duration = performance.now() - startTime;
- const memory = process.memoryUsage().heapUsed - startMemory;
-
- return { result, duration, memory };
- }
-
- compare(baseline: number, optimized: number): SpeedupResult {
- const speedup = baseline / optimized;
- const targets = performanceConfigs.v3Targets.targets;
-
- const meetsFlashAttention =
- speedup >= targets.flashAttentionSpeedup[0] &&
- speedup <= targets.flashAttentionSpeedup[1];
-
- return {
- speedup,
- improvement: `${((speedup - 1) * 100).toFixed(1)}% faster`,
- meetsTarget: meetsFlashAttention,
- };
- }
-
- recordMetric(name: string, value: number, unit: string): void {
- this.metrics.set(name, { value, unit });
- }
-
- getReport(): PerformanceReport {
- return {
- metrics: this.metrics,
- summary: `Recorded ${this.metrics.size} metrics`,
- };
- }
-}
-
-describe('V3 Performance Targets Acceptance', () => {
- let measurer: PerformanceMeasurer;
- let mockSearchEngine: MockedInterface<IVectorSearchEngine>;
- let mockMemoryOptimizer: MockedInterface<IMemoryOptimizer>;
-
- beforeEach(() => {
- measurer = new PerformanceMeasurer();
- mockSearchEngine = createMock<IVectorSearchEngine>();
- mockMemoryOptimizer = createMock<IMemoryOptimizer>();
-
- // Configure mock search engine
- mockSearchEngine.initialize.mockResolvedValue(undefined);
- mockSearchEngine.insert.mockResolvedValue(1000);
- mockSearchEngine.search.mockImplementation(async () => {
- // Simulate fast HNSW search
- await new Promise((r) => setTimeout(r, 0.1));
- return [
- { id: 'result-1', score: 0.95 },
- { id: 'result-2', score: 0.90 },
- ];
- });
- mockSearchEngine.getStats.mockReturnValue({
- totalEntries: 1000000,
- indexSize: 500000000,
- averageSearchTime: 0.1,
- indexBuildTime: 5000,
- });
-
- // Configure mock memory optimizer
- mockMemoryOptimizer.analyze.mockResolvedValue({
- totalMemory: 2147483648, // 2GB
- usedMemory: 1073741824, // 1GB
- potentialSavings: 536870912, // 512MB
- recommendations: ['Enable quantization', 'Use HNSW indexing'],
- });
- mockMemoryOptimizer.optimize.mockResolvedValue({
- originalSize: 1073741824,
- optimizedSize: 536870912,
- reduction: 0.5,
- techniquesApplied: ['scalar-quantization', 'hnsw-indexing'],
- });
- mockMemoryOptimizer.getUsage.mockReturnValue({
- heap: 536870912,
- external: 104857600,
- arrayBuffers: 52428800,
- });
- });
-
- describe('Flash Attention Speedup (2.49x-7.47x)', () => {
- it('should achieve minimum 2.49x speedup target', async () => {
- // Given
- const baselineTime = 1000; // 1 second baseline
- const optimizedTime = baselineTime / 2.49; // Target minimum
-
- // When
- const result = measurer.compare(baselineTime, optimizedTime);
-
- // Then
- expect(result.speedup).toBeGreaterThanOrEqual(2.49);
- expect(result.meetsTarget).toBe(true);
- });
-
- it('should not exceed 7.47x speedup target', async () => {
- // Given
- const baselineTime = 1000;
- const optimizedTime = baselineTime / 7.47; // Target maximum
-
- // When
- const result = measurer.compare(baselineTime, optimizedTime);
-
- // Then
- expect(result.speedup).toBeLessThanOrEqual(7.47);
- expect(result.meetsTarget).toBe(true);
- });
-
- it('should report failure for speedup below target', async () => {
- // Given
- const baselineTime = 1000;
- const optimizedTime = baselineTime / 1.5; // Below target
-
- // When
- const result = measurer.compare(baselineTime, optimizedTime);
-
- // Then
- expect(result.speedup).toBeLessThan(2.49);
- expect(result.meetsTarget).toBe(false);
- });
- });
-
- describe('AgentDB Search Improvement (150x-12,500x)', () => {
- it('should achieve minimum 150x search improvement', async () => {
- // Given
- const baselineSearchTime = 15; // 15ms baseline (brute force)
- const optimizedSearchTime = 0.1; // 0.1ms optimized (HNSW)
-
- // When
- const improvement = baselineSearchTime / optimizedSearchTime;
-
- // Then
- expect(improvement).toBeGreaterThanOrEqual(150);
- });
-
- it('should support up to 12,500x improvement for large datasets', async () => {
- // Given
- const baselineSearchTime = 125; // 125ms for large dataset brute force
- const optimizedSearchTime = 0.01; // 0.01ms with optimized HNSW
-
- // When
- const improvement = baselineSearchTime / optimizedSearchTime;
-
- // Then
- expect(improvement).toBeGreaterThanOrEqual(12500);
- });
-
- it('should verify HNSW index configuration meets targets', async () => {
- // Given
- const hnswConfig = agentDBTestData.hnswConfig;
-
- // When
- await mockSearchEngine.initialize({
- dimensions: hnswConfig.dimensions,
- indexType: 'hnsw',
- hnswConfig: {
- M: hnswConfig.M,
- efConstruction: hnswConfig.efConstruction,
- efSearch: hnswConfig.efSearch,
- },
- });
-
- // Then
- expect(mockSearchEngine.initialize).toHaveBeenCalledWith(
- expect.objectContaining({
- indexType: 'hnsw',
- hnswConfig: expect.objectContaining({
- M: 16, // Optimal for balance of speed/recall
- efConstruction: 200, // Good build quality
- efSearch: 50, // Fast search
- }),
- })
- );
- });
-
- it('should measure search time under target threshold', async () => {
- // Given
- const targetSearchTime = 1; // 1ms target
-
- // When
- const measurement = await measurer.measure(async () => {
- return mockSearchEngine.search(generateMockEmbedding(384, 'query'), 10);
- });
-
- // Then
- expect(measurement.duration).toBeLessThan(targetSearchTime);
- });
- });
-
- describe('Memory Reduction (50-75%)', () => {
- it('should achieve minimum 50% memory reduction', async () => {
- // Given
- const targets = performanceConfigs.v3Targets.targets;
-
- // When
- const result = await mockMemoryOptimizer.optimize();
-
- // Then
- expect(result.reduction).toBeGreaterThanOrEqual(targets.memoryReduction);
- });
-
- it('should apply quantization for memory reduction', async () => {
- // When
- const result = await mockMemoryOptimizer.optimize();
-
- // Then
- expect(result.techniquesApplied).toContain('scalar-quantization');
- });
-
- it('should report memory analysis with recommendations', async () => {
- // When
- const analysis = await mockMemoryOptimizer.analyze();
-
- // Then
- expect(analysis.recommendations).toContain('Enable quantization');
- expect(analysis.potentialSavings).toBeGreaterThan(0);
- });
-
- it('should verify quantization configuration', async () => {
- // Given
- const quantizationConfig = agentDBTestData.quantizationConfigs;
-
- // Then - Verify 4-bit quantization achieves 8x compression
- expect(quantizationConfig.scalar4bit.compressionRatio).toBe(8);
-
- // Verify 8-bit quantization achieves 4x compression
- expect(quantizationConfig.scalar8bit.compressionRatio).toBe(4);
-
- // Verify product quantization achieves 32x compression
- expect(quantizationConfig.product.compressionRatio).toBe(32);
- });
- });
-
- describe('Startup Time (<500ms)', () => {
- it('should achieve startup time under 500ms', async () => {
- // Given
- const targetStartupTime = performanceConfigs.v3Targets.targets.startupTime;
-
- // When
- const measurement = await measurer.measure(async () => {
- // Simulate initialization
- await mockSearchEngine.initialize({
- dimensions: 384,
- indexType: 'hnsw',
- });
- return true;
- });
-
- // Then
- expect(measurement.duration).toBeLessThan(targetStartupTime);
- });
- });
-
- describe('Code Size Target (<5,000 lines)', () => {
- it('should verify architecture supports code reduction', () => {
- // Given - V3 architecture principles
- const v3Principles = {
- eliminateDuplication: true, // ADR-001
- dddBoundedContexts: true, // ADR-002
- unifiedCoordinator: true, // ADR-003
- pluginArchitecture: true, // ADR-004
- };
-
- // Then
- expect(v3Principles.eliminateDuplication).toBe(true);
- expect(v3Principles.dddBoundedContexts).toBe(true);
- expect(v3Principles.unifiedCoordinator).toBe(true);
- expect(v3Principles.pluginArchitecture).toBe(true);
- });
- });
-
- describe('Performance Measurement Infrastructure', () => {
- it('should record and report metrics', async () => {
- // Given
- measurer.recordMetric('search_time', 0.1, 'ms');
- measurer.recordMetric('memory_usage', 512, 'MB');
- measurer.recordMetric('speedup', 3.5, 'x');
-
- // When
- const report = measurer.getReport();
-
- // Then
- expect(report.metrics.size).toBe(3);
- expect(report.metrics.get('search_time')).toEqual({ value: 0.1, unit: 'ms' });
- });
-
- it('should measure operation with memory tracking', async () => {
- // Given
- const operation = async () => {
- const data = new Array(1000).fill({ test: 'data' });
- return data.length;
- };
-
- // When
- const result = await measurer.measure(operation);
-
- // Then
- expect(result.result).toBe(1000);
- expect(result.duration).toBeGreaterThanOrEqual(0);
- expect(typeof result.memory).toBe('number');
- });
- });
-
- describe('Batch Operation Performance', () => {
- it('should handle batch vector insertions efficiently', async () => {
- // Given
- const batchSize = 1000;
- const entries = createMemoryBatch(batchSize);
-
- // When
- const measurement = await measurer.measure(async () => {
- return mockSearchEngine.insert(
- entries.map((e) => ({
- id: e.key,
- embedding: e.embedding!,
- metadata: e.metadata,
- }))
- );
- });
-
- // Then
- const insertionsPerSecond = (batchSize / measurement.duration) * 1000;
- expect(insertionsPerSecond).toBeGreaterThan(100); // At least 100 inserts/sec
- });
-
- it('should maintain search performance at scale', async () => {
- // Given
- mockSearchEngine.getStats.mockReturnValue({
- totalEntries: 1000000, // 1M vectors
- indexSize: 500000000,
- averageSearchTime: 0.1,
- indexBuildTime: 5000,
- });
-
- // When
- const stats = mockSearchEngine.getStats();
-
- // Then
- expect(stats.averageSearchTime).toBeLessThan(1); // Under 1ms
- expect(stats.totalEntries).toBe(1000000);
- });
- });
-
- describe('Performance Regression Prevention', () => {
- it('should detect performance regression', async () => {
- // Given
- const previousBenchmark = 100; // Previous: 100ms
- const currentMeasurement = 150; // Current: 150ms (regression)
-
- // When
- const regression = currentMeasurement > previousBenchmark * 1.1; // 10% tolerance
-
- // Then
- expect(regression).toBe(true);
- });
-
- it('should validate performance improvement', async () => {
- // Given
- const previousBenchmark = 100;
- const currentMeasurement = 50; // Improved
-
- // When
- const improvement = previousBenchmark / currentMeasurement;
-
- // Then
- expect(improvement).toBeGreaterThan(1);
- });
- });
-});
diff --git a/v3/__tests__/acceptance/security-compliance.test.ts b/v3/__tests__/acceptance/security-compliance.test.ts
deleted file mode 100644
index cb461a8645..0000000000
--- a/v3/__tests__/acceptance/security-compliance.test.ts
+++ /dev/null
@@ -1,674 +0,0 @@
-/**
- * V3 Claude-Flow Security Compliance Acceptance Tests
- *
- * Acceptance tests for security requirements
- * Tests CVE prevention and security compliance
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface } from '../helpers/create-mock';
-import { securityConfigs } from '../fixtures/configurations';
-
-/**
- * Security compliance checker interface
- */
-interface ISecurityComplianceChecker {
- checkPathTraversal(path: string): ComplianceResult;
- checkCommandInjection(command: string, args: string[]): ComplianceResult;
- checkNullByteInjection(input: string): ComplianceResult;
- checkPasswordPolicy(password: string): ComplianceResult;
- runFullAudit(): Promise<AuditResult>;
-}
-
-/**
- * CVE scanner interface
- */
-interface ICVEScanner {
- scan(code: string): Promise<CVEScanResult>;
- getKnownCVEs(): CVEInfo[];
- validateFix(cveId: string): Promise<boolean>;
-}
-
-/**
- * Security policy enforcer interface
- */
-interface ISecurityPolicyEnforcer {
- enforcePathPolicy(path: string): EnforcementResult;
- enforceCommandPolicy(command: string): EnforcementResult;
- enforceInputPolicy(input: string): EnforcementResult;
- getViolations(): PolicyViolation[];
-}
-
-interface ComplianceResult {
- compliant: boolean;
- violations: string[];
- severity: 'critical' | 'high' | 'medium' | 'low' | 'none';
- recommendations: string[];
-}
-
-interface AuditResult {
- passed: boolean;
- checks: AuditCheck[];
- overallScore: number;
- timestamp: Date;
-}
-
-interface AuditCheck {
- name: string;
- passed: boolean;
- details: string;
-}
-
-interface CVEScanResult {
- vulnerabilities: CVEInfo[];
- riskScore: number;
- remediation: string[];
-}
-
-interface CVEInfo {
- id: string;
- severity: 'critical' | 'high' | 'medium' | 'low';
- description: string;
- affectedVersions: string[];
- fixedIn?: string;
-}
-
-interface EnforcementResult {
- allowed: boolean;
- reason?: string;
- sanitized?: string;
-}
-
-interface PolicyViolation {
- type: string;
- input: string;
- timestamp: Date;
- severity: string;
-}
-
-/**
- * Security compliance checker implementation
- */
-class SecurityComplianceChecker implements ISecurityComplianceChecker {
- constructor(private readonly config: typeof securityConfigs.strict) {}
-
- checkPathTraversal(path: string): ComplianceResult {
- const violations: string[] = [];
- const recommendations: string[] = [];
-
- // Check for directory traversal patterns
- const traversalPatterns = ['../', '..\\', '%2e%2e%2f', '%2e%2e/'];
- for (const pattern of traversalPatterns) {
- if (path.toLowerCase().includes(pattern.toLowerCase())) {
- violations.push(`Path contains traversal pattern: ${pattern}`);
- }
- }
-
- // Check for blocked patterns from config
- for (const pattern of this.config.paths.blockedPatterns) {
- if (path.includes(pattern)) {
- violations.push(`Path contains blocked pattern: ${pattern}`);
- }
- }
-
- // Check for null bytes
- if (path.includes('\0')) {
- violations.push('Path contains null byte');
- }
-
- if (violations.length > 0) {
- recommendations.push('Sanitize path input');
- recommendations.push('Use allowlist for valid paths');
- recommendations.push('Validate against allowed directories');
- }
-
- return {
- compliant: violations.length === 0,
- violations,
- severity: violations.length > 0 ? 'critical' : 'none',
- recommendations,
- };
- }
-
- checkCommandInjection(command: string, args: string[]): ComplianceResult {
- const violations: string[] = [];
- const recommendations: string[] = [];
-
- // Check base command
- const baseCommand = command.split(' ')[0];
- if (this.config.execution.blockedCommands.includes(baseCommand)) {
- violations.push(`Command "${baseCommand}" is blocked`);
- }
-
- if (!this.config.execution.allowedCommands.includes(baseCommand)) {
- violations.push(`Command "${baseCommand}" is not in allowlist`);
- }
-
- // Check for injection patterns in args
- const injectionPatterns = [';', '|', '&', '`', '$', '(', ')', '<', '>', '\n'];
- for (const arg of args) {
- for (const pattern of injectionPatterns) {
- if (arg.includes(pattern)) {
- violations.push(`Argument contains injection pattern: ${pattern}`);
- }
- }
- }
-
- if (violations.length > 0) {
- recommendations.push('Sanitize command arguments');
- recommendations.push('Use allowlist for commands');
- recommendations.push('Disable shell execution');
- }
-
- return {
- compliant: violations.length === 0,
- violations,
- severity: violations.length > 0 ? 'critical' : 'none',
- recommendations,
- };
- }
-
- checkNullByteInjection(input: string): ComplianceResult {
- const violations: string[] = [];
-
- if (input.includes('\0')) {
- violations.push('Input contains null byte');
- }
-
- // Check for encoded null bytes
- if (input.includes('%00')) {
- violations.push('Input contains URL-encoded null byte');
- }
-
- return {
- compliant: violations.length === 0,
- violations,
- severity: violations.length > 0 ? 'high' : 'none',
- recommendations: violations.length > 0 ? ['Strip null bytes from input'] : [],
- };
- }
-
- checkPasswordPolicy(password: string): ComplianceResult {
- const violations: string[] = [];
-
- if (password.length < 8) {
- violations.push('Password must be at least 8 characters');
- }
-
- if (!/[A-Z]/.test(password)) {
- violations.push('Password must contain uppercase letter');
- }
-
- if (!/[a-z]/.test(password)) {
- violations.push('Password must contain lowercase letter');
- }
-
- if (!/[0-9]/.test(password)) {
- violations.push('Password must contain number');
- }
-
- if (!/[!@#$%^&*]/.test(password)) {
- violations.push('Password should contain special character');
- }
-
- return {
- compliant: violations.length === 0,
- violations,
- severity: violations.length > 2 ? 'high' : violations.length > 0 ? 'medium' : 'none',
- recommendations: ['Use a password manager', 'Enable MFA'],
- };
- }
-
- async runFullAudit(): Promise<AuditResult> {
- const checks: AuditCheck[] = [
- {
- name: 'Path Traversal Protection',
- passed: this.config.paths.blockedPatterns.includes('../'),
- details: 'Verified blocked patterns include directory traversal',
- },
- {
- name: 'Command Injection Protection',
- passed: this.config.execution.shell === false,
- details: 'Shell execution is disabled',
- },
- {
- name: 'Dangerous Commands Blocked',
- passed: this.config.execution.blockedCommands.includes('rm'),
- details: 'Verified dangerous commands are blocked',
- },
- {
- name: 'Secure Hashing Algorithm',
- passed: this.config.hashing.algorithm === 'argon2',
- details: 'Using recommended hashing algorithm',
- },
- {
- name: 'Input Size Limit',
- passed: this.config.validation.maxInputSize <= 10000,
- details: 'Input size is properly limited',
- },
- ];
-
- const passed = checks.every((c) => c.passed);
- const overallScore = (checks.filter((c) => c.passed).length / checks.length) * 100;
-
- return {
- passed,
- checks,
- overallScore,
- timestamp: new Date(),
- };
- }
-}
-
-describe('Security Compliance Acceptance', () => {
- let complianceChecker: SecurityComplianceChecker;
- let mockCVEScanner: MockedInterface<ICVEScanner>;
- let mockPolicyEnforcer: MockedInterface<ISecurityPolicyEnforcer>;
-
- beforeEach(() => {
- complianceChecker = new SecurityComplianceChecker(securityConfigs.strict);
- mockCVEScanner = createMock<ICVEScanner>();
- mockPolicyEnforcer = createMock<ISecurityPolicyEnforcer>();
-
- // Configure CVE scanner mock
- mockCVEScanner.getKnownCVEs.mockReturnValue([
- {
- id: 'CVE-1',
- severity: 'critical',
- description: 'Directory traversal vulnerability',
- affectedVersions: ['<3.0.0'],
- fixedIn: '3.0.0',
- },
- {
- id: 'CVE-2',
- severity: 'critical',
- description: 'Absolute path injection vulnerability',
- affectedVersions: ['<3.0.0'],
- fixedIn: '3.0.0',
- },
- {
- id: 'CVE-3',
- severity: 'critical',
- description: 'Command injection vulnerability',
- affectedVersions: ['<3.0.0'],
- fixedIn: '3.0.0',
- },
- ]);
-
- mockCVEScanner.validateFix.mockResolvedValue(true);
- mockCVEScanner.scan.mockResolvedValue({
- vulnerabilities: [],
- riskScore: 0,
- remediation: [],
- });
-
- // Configure policy enforcer mock
- mockPolicyEnforcer.enforcePathPolicy.mockImplementation((path) => ({
- allowed: !path.includes('../'),
- reason: path.includes('../') ? 'Path traversal detected' : undefined,
- }));
- mockPolicyEnforcer.enforceCommandPolicy.mockImplementation((cmd) => ({
- allowed: securityConfigs.strict.execution.allowedCommands.includes(cmd.split(' ')[0]),
- }));
- mockPolicyEnforcer.getViolations.mockReturnValue([]);
- });
-
- describe('CVE-1: Directory Traversal Prevention', () => {
- it('should detect basic directory traversal', () => {
- // Given
- const maliciousPath = '../../../etc/passwd';
-
- // When
- const result = complianceChecker.checkPathTraversal(maliciousPath);
-
- // Then
- expect(result.compliant).toBe(false);
- expect(result.severity).toBe('critical');
- expect(result.violations).toContainEqual(expect.stringContaining('../'));
- });
-
- it('should detect Windows-style traversal', () => {
- // Given
- const maliciousPath = '..\\..\\..\\Windows\\System32';
-
- // When
- const result = complianceChecker.checkPathTraversal(maliciousPath);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should detect URL-encoded traversal', () => {
- // Given
- const maliciousPath = '%2e%2e%2f%2e%2e%2f%2e%2e%2fetc/passwd';
-
- // When
- const result = complianceChecker.checkPathTraversal(maliciousPath);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should allow safe paths', () => {
- // Given
- const safePath = './v3/src/security/index.ts';
-
- // When
- const result = complianceChecker.checkPathTraversal(safePath);
-
- // Then
- expect(result.compliant).toBe(true);
- expect(result.severity).toBe('none');
- });
-
- it('should validate CVE-1 fix', async () => {
- // When
- const isFixed = await mockCVEScanner.validateFix('CVE-1');
-
- // Then
- expect(isFixed).toBe(true);
- });
- });
-
- describe('CVE-2: Absolute Path Injection Prevention', () => {
- it('should detect /etc/ access attempts', () => {
- // Given
- const maliciousPath = '/etc/passwd';
-
- // When
- const result = complianceChecker.checkPathTraversal(maliciousPath);
-
- // Then
- expect(result.compliant).toBe(false);
- expect(result.violations).toContainEqual(expect.stringContaining('/etc/'));
- });
-
- it('should detect /tmp/ access attempts', () => {
- // Given
- const maliciousPath = '/tmp/malicious.sh';
-
- // When
- const result = complianceChecker.checkPathTraversal(maliciousPath);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should detect home directory access attempts', () => {
- // Given
- const maliciousPath = '~/.ssh/id_rsa';
-
- // When
- const result = complianceChecker.checkPathTraversal(maliciousPath);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should validate CVE-2 fix', async () => {
- // When
- const isFixed = await mockCVEScanner.validateFix('CVE-2');
-
- // Then
- expect(isFixed).toBe(true);
- });
- });
-
- describe('CVE-3: Command Injection Prevention', () => {
- it('should detect semicolon injection', () => {
- // Given
- const command = 'npm';
- const args = ['install; rm -rf /'];
-
- // When
- const result = complianceChecker.checkCommandInjection(command, args);
-
- // Then
- expect(result.compliant).toBe(false);
- expect(result.violations).toContainEqual(expect.stringContaining(';'));
- });
-
- it('should detect pipe injection', () => {
- // Given
- const command = 'npm';
- const args = ['install | cat /etc/passwd'];
-
- // When
- const result = complianceChecker.checkCommandInjection(command, args);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should detect command substitution', () => {
- // Given
- const command = 'npm';
- const args = ['install $(whoami)'];
-
- // When
- const result = complianceChecker.checkCommandInjection(command, args);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should detect backtick execution', () => {
- // Given
- const command = 'npm';
- const args = ['install `rm -rf /`'];
-
- // When
- const result = complianceChecker.checkCommandInjection(command, args);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should block dangerous commands', () => {
- // Given
- const command = 'rm';
- const args = ['-rf', '/'];
-
- // When
- const result = complianceChecker.checkCommandInjection(command, args);
-
- // Then
- expect(result.compliant).toBe(false);
- expect(result.violations).toContainEqual(expect.stringContaining('rm'));
- });
-
- it('should allow safe commands', () => {
- // Given
- const command = 'npm';
- const args = ['install', '--save', 'lodash'];
-
- // When
- const result = complianceChecker.checkCommandInjection(command, args);
-
- // Then
- expect(result.compliant).toBe(true);
- });
-
- it('should validate CVE-3 fix', async () => {
- // When
- const isFixed = await mockCVEScanner.validateFix('CVE-3');
-
- // Then
- expect(isFixed).toBe(true);
- });
- });
-
- describe('Null Byte Injection Prevention', () => {
- it('should detect null byte in path', () => {
- // Given
- const input = 'file.txt\0.exe';
-
- // When
- const result = complianceChecker.checkNullByteInjection(input);
-
- // Then
- expect(result.compliant).toBe(false);
- expect(result.severity).toBe('high');
- });
-
- it('should detect URL-encoded null byte', () => {
- // Given
- const input = 'file.txt%00.exe';
-
- // When
- const result = complianceChecker.checkNullByteInjection(input);
-
- // Then
- expect(result.compliant).toBe(false);
- });
-
- it('should allow clean input', () => {
- // Given
- const input = 'file.txt';
-
- // When
- const result = complianceChecker.checkNullByteInjection(input);
-
- // Then
- expect(result.compliant).toBe(true);
- });
- });
-
- describe('Password Policy Compliance', () => {
- it('should require minimum length', () => {
- // Given
- const weakPassword = 'Short1!';
-
- // When
- const result = complianceChecker.checkPasswordPolicy(weakPassword);
-
- // Then
- expect(result.compliant).toBe(false);
- expect(result.violations).toContainEqual(expect.stringContaining('8 characters'));
- });
-
- it('should require uppercase letter', () => {
- // Given
- const noUpper = 'password123!';
-
- // When
- const result = complianceChecker.checkPasswordPolicy(noUpper);
-
- // Then
- expect(result.violations).toContainEqual(expect.stringContaining('uppercase'));
- });
-
- it('should require lowercase letter', () => {
- // Given
- const noLower = 'PASSWORD123!';
-
- // When
- const result = complianceChecker.checkPasswordPolicy(noLower);
-
- // Then
- expect(result.violations).toContainEqual(expect.stringContaining('lowercase'));
- });
-
- it('should require number', () => {
- // Given
- const noNumber = 'Password!!';
-
- // When
- const result = complianceChecker.checkPasswordPolicy(noNumber);
-
- // Then
- expect(result.violations).toContainEqual(expect.stringContaining('number'));
- });
-
- it('should accept strong password', () => {
- // Given
- const strongPassword = 'SecureP@ss123!';
-
- // When
- const result = complianceChecker.checkPasswordPolicy(strongPassword);
-
- // Then
- expect(result.compliant).toBe(true);
- });
- });
-
- describe('Full Security Audit', () => {
- it('should pass full audit with strict config', async () => {
- // When
- const audit = await complianceChecker.runFullAudit();
-
- // Then
- expect(audit.passed).toBe(true);
- expect(audit.overallScore).toBe(100);
- });
-
- it('should verify all security checks pass', async () => {
- // When
- const audit = await complianceChecker.runFullAudit();
-
- // Then
- for (const check of audit.checks) {
- expect(check.passed).toBe(true);
- }
- });
-
- it('should verify path traversal protection is enabled', async () => {
- // When
- const audit = await complianceChecker.runFullAudit();
-
- // Then
- const pathCheck = audit.checks.find((c) => c.name === 'Path Traversal Protection');
- expect(pathCheck?.passed).toBe(true);
- });
-
- it('should verify shell execution is disabled', async () => {
- // When
- const audit = await complianceChecker.runFullAudit();
-
- // Then
- const shellCheck = audit.checks.find((c) => c.name === 'Command Injection Protection');
- expect(shellCheck?.passed).toBe(true);
- });
-
- it('should verify secure hashing is configured', async () => {
- // When
- const audit = await complianceChecker.runFullAudit();
-
- // Then
- const hashCheck = audit.checks.find((c) => c.name === 'Secure Hashing Algorithm');
- expect(hashCheck?.passed).toBe(true);
- });
- });
-
- describe('Security Configuration Compliance', () => {
- it('should have 95% security test coverage target', () => {
- // Given
- const securityCoverageTarget = 0.95;
-
- // Then
- expect(securityCoverageTarget).toBe(0.95);
- });
-
- it('should use argon2 for password hashing', () => {
- // Then
- expect(securityConfigs.strict.hashing.algorithm).toBe('argon2');
- });
-
- it('should disable shell execution by default', () => {
- // Then
- expect(securityConfigs.strict.execution.shell).toBe(false);
- });
-
- it('should block all dangerous commands', () => {
- // Then
- expect(securityConfigs.strict.execution.blockedCommands).toContain('rm');
- expect(securityConfigs.strict.execution.blockedCommands).toContain('del');
- expect(securityConfigs.strict.execution.blockedCommands).toContain('format');
- expect(securityConfigs.strict.execution.blockedCommands).toContain('dd');
- });
-
- it('should have limited allowed commands', () => {
- // Then
- expect(securityConfigs.strict.execution.allowedCommands).toEqual(['npm', 'npx', 'node', 'git']);
- });
- });
-});
diff --git a/v3/__tests__/fixtures/agents.ts b/v3/__tests__/fixtures/agents.ts
deleted file mode 100644
index 8240473673..0000000000
--- a/v3/__tests__/fixtures/agents.ts
+++ /dev/null
@@ -1,212 +0,0 @@
-/**
- * V3 Claude-Flow Agent Fixtures
- *
- * Test data for agent-related testing
- * Following London School principle of explicit test data
- */
-import type { V3AgentType } from '../helpers/swarm-instance';
-
-/**
- * Agent configuration fixtures
- */
-export interface AgentConfig {
- type: V3AgentType;
- name: string;
- capabilities: string[];
- priority?: number;
- metadata?: Record<string, unknown>;
-}
-
-/**
- * Agent instance fixtures
- */
-export interface AgentInstance {
- id: string;
- type: V3AgentType;
- name: string;
- status: 'idle' | 'busy' | 'terminated';
- capabilities: string[];
- createdAt: Date;
- lastActiveAt?: Date;
-}
-
-/**
- * Pre-defined agent configurations for testing
- */
-export const agentConfigs: Record<string, AgentConfig> = {
- queenCoordinator: {
- type: 'queen-coordinator',
- name: 'Queen Alpha',
- capabilities: ['orchestration', 'task-distribution', 'agent-management'],
- priority: 100,
- metadata: { isLeader: true },
- },
-
- securityArchitect: {
- type: 'security-architect',
- name: 'Security Architect',
- capabilities: ['security-design', 'threat-modeling', 'security-review'],
- priority: 90,
- metadata: { specialization: 'cve-prevention' },
- },
-
- securityAuditor: {
- type: 'security-auditor',
- name: 'Security Auditor',
- capabilities: ['cve-detection', 'vulnerability-scanning', 'security-testing'],
- priority: 90,
- metadata: { specialization: 'penetration-testing' },
- },
-
- memorySpecialist: {
- type: 'memory-specialist',
- name: 'Memory Specialist',
- capabilities: ['memory-optimization', 'agentdb-integration', 'caching'],
- priority: 80,
- metadata: { backend: 'agentdb' },
- },
-
- swarmSpecialist: {
- type: 'swarm-specialist',
- name: 'Swarm Specialist',
- capabilities: ['coordination', 'consensus', 'communication'],
- priority: 85,
- metadata: { topology: 'hierarchical-mesh' },
- },
-
- coder: {
- type: 'coder',
- name: 'Coder Agent',
- capabilities: ['coding', 'implementation', 'debugging'],
- priority: 70,
- },
-
- tester: {
- type: 'tester',
- name: 'Tester Agent',
- capabilities: ['testing', 'test-execution', 'coverage'],
- priority: 70,
- },
-
- reviewer: {
- type: 'reviewer',
- name: 'Reviewer Agent',
- capabilities: ['code-review', 'quality-check', 'suggestions'],
- priority: 75,
- },
-};
-
-/**
- * Pre-defined agent instances for testing
- */
-export const agentInstances: Record<string, AgentInstance> = {
- idleQueen: {
- id: 'agent-queen-001',
- type: 'queen-coordinator',
- name: 'Queen Alpha',
- status: 'idle',
- capabilities: ['orchestration', 'task-distribution', 'agent-management'],
- createdAt: new Date('2024-01-01T00:00:00Z'),
- },
-
- busySecurityArchitect: {
- id: 'agent-security-001',
- type: 'security-architect',
- name: 'Security Architect',
- status: 'busy',
- capabilities: ['security-design', 'threat-modeling', 'security-review'],
- createdAt: new Date('2024-01-01T00:00:00Z'),
- lastActiveAt: new Date('2024-01-15T12:00:00Z'),
- },
-
- terminatedCoder: {
- id: 'agent-coder-001',
- type: 'coder',
- name: 'Coder Agent',
- status: 'terminated',
- capabilities: ['coding', 'implementation', 'debugging'],
- createdAt: new Date('2024-01-01T00:00:00Z'),
- lastActiveAt: new Date('2024-01-10T08:00:00Z'),
- },
-};
-
-/**
- * Factory function to create agent config with overrides
- */
-export function createAgentConfig(
- base: keyof typeof agentConfigs,
- overrides?: Partial<AgentConfig>
-): AgentConfig {
- return {
- ...agentConfigs[base],
- ...overrides,
- };
-}
-
-/**
- * Factory function to create agent instance with overrides
- */
-export function createAgentInstance(
- base: keyof typeof agentInstances,
- overrides?: Partial<AgentInstance>
-): AgentInstance {
- return {
- ...agentInstances[base],
- ...overrides,
- id: overrides?.id ?? `agent-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
- createdAt: overrides?.createdAt ?? new Date(),
- };
-}
-
-/**
- * Create a full 15-agent swarm configuration
- */
-export function create15AgentSwarmConfig(): AgentConfig[] {
- return [
- agentConfigs.queenCoordinator,
- agentConfigs.securityArchitect,
- agentConfigs.securityAuditor,
- agentConfigs.memorySpecialist,
- agentConfigs.swarmSpecialist,
- createAgentConfig('coder', { name: 'Integration Architect', type: 'integration-architect' as V3AgentType }),
- createAgentConfig('coder', { name: 'Performance Engineer', type: 'performance-engineer' as V3AgentType }),
- createAgentConfig('coder', { name: 'Core Architect', type: 'core-architect' as V3AgentType }),
- createAgentConfig('tester', { name: 'Test Architect', type: 'test-architect' as V3AgentType }),
- createAgentConfig('coder', { name: 'Project Coordinator', type: 'project-coordinator' as V3AgentType }),
- agentConfigs.coder,
- agentConfigs.reviewer,
- agentConfigs.tester,
- createAgentConfig('coder', { name: 'Planner Agent', type: 'planner' as V3AgentType }),
- createAgentConfig('coder', { name: 'Researcher Agent', type: 'researcher' as V3AgentType }),
- ];
-}
-
-/**
- * Invalid agent configurations for error testing
- */
-export const invalidAgentConfigs = {
- emptyName: {
- type: 'coder' as V3AgentType,
- name: '',
- capabilities: ['coding'],
- },
-
- noCapabilities: {
- type: 'coder' as V3AgentType,
- name: 'Invalid Agent',
- capabilities: [],
- },
-
- invalidType: {
- type: 'invalid-type' as V3AgentType,
- name: 'Invalid Agent',
- capabilities: ['something'],
- },
-
- negativePriority: {
- type: 'coder' as V3AgentType,
- name: 'Invalid Agent',
- capabilities: ['coding'],
- priority: -1,
- },
-};
diff --git a/v3/__tests__/fixtures/configurations.ts b/v3/__tests__/fixtures/configurations.ts
deleted file mode 100644
index 95f8579238..0000000000
--- a/v3/__tests__/fixtures/configurations.ts
+++ /dev/null
@@ -1,487 +0,0 @@
-/**
- * V3 Claude-Flow Configuration Fixtures
- *
- * Test data for configuration testing
- * Following London School principle of explicit test data
- */
-
-/**
- * Security configuration interface
- */
-export interface SecurityConfig {
- validation: {
- maxInputSize: number;
- allowedChars: RegExp;
- sanitizeHtml: boolean;
- };
- paths: {
- allowedDirectories: string[];
- blockedPatterns: string[];
- maxPathLength: number;
- };
- execution: {
- shell: boolean;
- timeout: number;
- allowedCommands: string[];
- blockedCommands: string[];
- };
- hashing: {
- algorithm: 'argon2' | 'bcrypt' | 'scrypt';
- memoryCost?: number;
- timeCost?: number;
- parallelism?: number;
- };
-}
-
-/**
- * Memory configuration interface
- */
-export interface MemoryConfig {
- backend: 'agentdb' | 'sqlite' | 'memory' | 'hybrid';
- vectorDimensions: number;
- hnswConfig: {
- M: number;
- efConstruction: number;
- efSearch: number;
- };
- caching: {
- enabled: boolean;
- maxSize: number;
- ttl: number;
- };
- quantization: {
- enabled: boolean;
- bits: 4 | 8;
- };
-}
-
-/**
- * Swarm configuration interface
- */
-export interface SwarmConfig {
- topology: 'hierarchical' | 'mesh' | 'adaptive' | 'hierarchical-mesh';
- maxAgents: number;
- coordination: {
- consensusProtocol: 'raft' | 'pbft' | 'gossip';
- heartbeatInterval: number;
- electionTimeout: number;
- };
- communication: {
- protocol: 'quic' | 'tcp' | 'websocket';
- maxMessageSize: number;
- retryAttempts: number;
- };
-}
-
-/**
- * MCP configuration interface
- */
-export interface MCPConfig {
- server: {
- port: number;
- host: string;
- protocol: 'http' | 'https' | 'stdio';
- };
- connection: {
- poolSize: number;
- timeout: number;
- keepAlive: boolean;
- };
- tools: {
- enabled: string[];
- disabled: string[];
- };
-}
-
-/**
- * Performance configuration interface
- */
-export interface PerformanceConfig {
- targets: {
- flashAttentionSpeedup: [number, number]; // [min, max]
- agentDBSearchImprovement: [number, number];
- memoryReduction: number;
- startupTime: number;
- };
- monitoring: {
- enabled: boolean;
- samplingRate: number;
- metricsEndpoint?: string;
- };
- optimization: {
- batchSize: number;
- parallelism: number;
- cacheStrategy: 'lru' | 'lfu' | 'arc';
- };
-}
-
-/**
- * Pre-defined security configurations for testing
- */
-export const securityConfigs: Record<string, SecurityConfig> = {
- strict: {
- validation: {
- maxInputSize: 10000,
- allowedChars: /^[a-zA-Z0-9._\-\s]+$/,
- sanitizeHtml: true,
- },
- paths: {
- allowedDirectories: ['./v3/', './src/', './tests/'],
- blockedPatterns: ['../', '~/', '/etc/', '/tmp/', '/var/'],
- maxPathLength: 255,
- },
- execution: {
- shell: false,
- timeout: 30000,
- allowedCommands: ['npm', 'npx', 'node', 'git'],
- blockedCommands: ['rm', 'del', 'format', 'dd', 'chmod', 'chown'],
- },
- hashing: {
- algorithm: 'argon2',
- memoryCost: 65536,
- timeCost: 3,
- parallelism: 4,
- },
- },
-
- development: {
- validation: {
- maxInputSize: 50000,
- allowedChars: /^[\x20-\x7E\n\r\t]+$/,
- sanitizeHtml: false,
- },
- paths: {
- allowedDirectories: ['./', './node_modules/'],
- blockedPatterns: ['../', '~/'],
- maxPathLength: 512,
- },
- execution: {
- shell: true,
- timeout: 60000,
- allowedCommands: ['npm', 'npx', 'node', 'git', 'yarn', 'pnpm'],
- blockedCommands: ['rm -rf /', 'format c:'],
- },
- hashing: {
- algorithm: 'bcrypt',
- },
- },
-
- production: {
- validation: {
- maxInputSize: 5000,
- allowedChars: /^[a-zA-Z0-9._\-]+$/,
- sanitizeHtml: true,
- },
- paths: {
- allowedDirectories: ['/app/'],
- blockedPatterns: ['../', '~/', '/etc/', '/tmp/', '/var/', '/root/'],
- maxPathLength: 200,
- },
- execution: {
- shell: false,
- timeout: 15000,
- allowedCommands: ['node'],
- blockedCommands: ['rm', 'del', 'format', 'dd', 'chmod', 'chown', 'sudo'],
- },
- hashing: {
- algorithm: 'argon2',
- memoryCost: 131072,
- timeCost: 4,
- parallelism: 4,
- },
- },
-};
-
-/**
- * Pre-defined memory configurations for testing
- */
-export const memoryConfigs: Record<string, MemoryConfig> = {
- agentDB: {
- backend: 'agentdb',
- vectorDimensions: 384,
- hnswConfig: {
- M: 16,
- efConstruction: 200,
- efSearch: 50,
- },
- caching: {
- enabled: true,
- maxSize: 1000,
- ttl: 3600000,
- },
- quantization: {
- enabled: true,
- bits: 8,
- },
- },
-
- hybrid: {
- backend: 'hybrid',
- vectorDimensions: 384,
- hnswConfig: {
- M: 32,
- efConstruction: 400,
- efSearch: 100,
- },
- caching: {
- enabled: true,
- maxSize: 5000,
- ttl: 7200000,
- },
- quantization: {
- enabled: true,
- bits: 4,
- },
- },
-
- inMemory: {
- backend: 'memory',
- vectorDimensions: 384,
- hnswConfig: {
- M: 8,
- efConstruction: 100,
- efSearch: 25,
- },
- caching: {
- enabled: false,
- maxSize: 0,
- ttl: 0,
- },
- quantization: {
- enabled: false,
- bits: 8,
- },
- },
-};
-
-/**
- * Pre-defined swarm configurations for testing
- */
-export const swarmConfigs: Record<string, SwarmConfig> = {
- v3Default: {
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- coordination: {
- consensusProtocol: 'raft',
- heartbeatInterval: 1000,
- electionTimeout: 5000,
- },
- communication: {
- protocol: 'quic',
- maxMessageSize: 1048576, // 1MB
- retryAttempts: 3,
- },
- },
-
- minimal: {
- topology: 'mesh',
- maxAgents: 5,
- coordination: {
- consensusProtocol: 'gossip',
- heartbeatInterval: 2000,
- electionTimeout: 10000,
- },
- communication: {
- protocol: 'tcp',
- maxMessageSize: 65536, // 64KB
- retryAttempts: 5,
- },
- },
-
- highPerformance: {
- topology: 'adaptive',
- maxAgents: 50,
- coordination: {
- consensusProtocol: 'pbft',
- heartbeatInterval: 500,
- electionTimeout: 3000,
- },
- communication: {
- protocol: 'quic',
- maxMessageSize: 4194304, // 4MB
- retryAttempts: 2,
- },
- },
-};
-
-/**
- * Pre-defined MCP configurations for testing
- */
-export const mcpConfigs: Record<string, MCPConfig> = {
- development: {
- server: {
- port: 3000,
- host: 'localhost',
- protocol: 'http',
- },
- connection: {
- poolSize: 10,
- timeout: 30000,
- keepAlive: true,
- },
- tools: {
- enabled: ['*'],
- disabled: [],
- },
- },
-
- production: {
- server: {
- port: 443,
- host: '0.0.0.0',
- protocol: 'https',
- },
- connection: {
- poolSize: 100,
- timeout: 15000,
- keepAlive: true,
- },
- tools: {
- enabled: ['swarm_init', 'agent_spawn', 'task_orchestrate', 'memory_usage'],
- disabled: ['debug_*', 'test_*'],
- },
- },
-
- stdio: {
- server: {
- port: 0,
- host: '',
- protocol: 'stdio',
- },
- connection: {
- poolSize: 1,
- timeout: 60000,
- keepAlive: false,
- },
- tools: {
- enabled: ['*'],
- disabled: [],
- },
- },
-};
-
-/**
- * Pre-defined performance configurations for testing
- */
-export const performanceConfigs: Record<string, PerformanceConfig> = {
- v3Targets: {
- targets: {
- flashAttentionSpeedup: [2.49, 7.47],
- agentDBSearchImprovement: [150, 12500],
- memoryReduction: 0.50,
- startupTime: 500,
- },
- monitoring: {
- enabled: true,
- samplingRate: 0.1,
- metricsEndpoint: '/metrics',
- },
- optimization: {
- batchSize: 100,
- parallelism: 4,
- cacheStrategy: 'arc',
- },
- },
-
- minimal: {
- targets: {
- flashAttentionSpeedup: [1.0, 2.0],
- agentDBSearchImprovement: [10, 100],
- memoryReduction: 0.25,
- startupTime: 2000,
- },
- monitoring: {
- enabled: false,
- samplingRate: 0,
- },
- optimization: {
- batchSize: 10,
- parallelism: 1,
- cacheStrategy: 'lru',
- },
- },
-};
-
-/**
- * Factory functions to create configurations with overrides
- */
-export function createSecurityConfig(
- base: keyof typeof securityConfigs,
- overrides?: Partial<SecurityConfig>
-): SecurityConfig {
- return mergeDeep(securityConfigs[base], overrides ?? {}) as SecurityConfig;
-}
-
-export function createMemoryConfig(
- base: keyof typeof memoryConfigs,
- overrides?: Partial<MemoryConfig>
-): MemoryConfig {
- return mergeDeep(memoryConfigs[base], overrides ?? {}) as MemoryConfig;
-}
-
-export function createSwarmConfig(
- base: keyof typeof swarmConfigs,
- overrides?: Partial<SwarmConfig>
-): SwarmConfig {
- return mergeDeep(swarmConfigs[base], overrides ?? {}) as SwarmConfig;
-}
-
-export function createMCPConfig(
- base: keyof typeof mcpConfigs,
- overrides?: Partial<MCPConfig>
-): MCPConfig {
- return mergeDeep(mcpConfigs[base], overrides ?? {}) as MCPConfig;
-}
-
-export function createPerformanceConfig(
- base: keyof typeof performanceConfigs,
- overrides?: Partial<PerformanceConfig>
-): PerformanceConfig {
- return mergeDeep(performanceConfigs[base], overrides ?? {}) as PerformanceConfig;
-}
-
-/**
- * Deep merge utility
- */
-function mergeDeep(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
- const output = { ...target };
-
- for (const key of Object.keys(source)) {
- if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
- output[key] = mergeDeep(
- (target[key] as Record<string, unknown>) ?? {},
- source[key] as Record<string, unknown>
- );
- } else {
- output[key] = source[key];
- }
- }
-
- return output;
-}
-
-/**
- * Invalid configurations for error testing
- */
-export const invalidConfigs = {
- security: {
- negativeMaxInputSize: createSecurityConfig('strict', {
- validation: { maxInputSize: -1, allowedChars: /.*/, sanitizeHtml: true },
- }),
- emptyAllowedCommands: createSecurityConfig('strict', {
- execution: { shell: false, timeout: 1000, allowedCommands: [], blockedCommands: [] },
- }),
- },
-
- memory: {
- zeroDimensions: createMemoryConfig('agentDB', { vectorDimensions: 0 }),
- invalidQuantization: createMemoryConfig('agentDB', { quantization: { enabled: true, bits: 16 as 4 | 8 } }),
- },
-
- swarm: {
- zeroAgents: createSwarmConfig('v3Default', { maxAgents: 0 }),
- negativeHeartbeat: createSwarmConfig('v3Default', {
- coordination: { consensusProtocol: 'raft', heartbeatInterval: -100, electionTimeout: 5000 },
- }),
- },
-};
diff --git a/v3/__tests__/fixtures/index.ts b/v3/__tests__/fixtures/index.ts
deleted file mode 100644
index 7c92b08a1b..0000000000
--- a/v3/__tests__/fixtures/index.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-/**
- * V3 Claude-Flow Test Fixtures Index
- *
- * Central export for all test fixtures
- */
-
-// Agent fixtures
-export * from './agents';
-
-// Task fixtures
-export * from './tasks';
-
-// Memory entry fixtures
-export * from './memory-entries';
-
-// Configuration fixtures
-export * from './configurations';
diff --git a/v3/__tests__/fixtures/memory-entries.ts b/v3/__tests__/fixtures/memory-entries.ts
deleted file mode 100644
index 0bbeea5e73..0000000000
--- a/v3/__tests__/fixtures/memory-entries.ts
+++ /dev/null
@@ -1,328 +0,0 @@
-/**
- * V3 Claude-Flow Memory Entry Fixtures
- *
- * Test data for memory and AgentDB testing
- * Following London School principle of explicit test data
- */
-
-/**
- * Memory entry interface
- */
-export interface MemoryEntry {
- key: string;
- value: unknown;
- metadata: MemoryMetadata;
- embedding?: number[];
- createdAt: Date;
- updatedAt: Date;
- expiresAt?: Date;
-}
-
-/**
- * Memory metadata interface
- */
-export interface MemoryMetadata {
- type: 'short-term' | 'long-term' | 'semantic' | 'episodic';
- tags: string[];
- source?: string;
- confidence?: number;
- ttl?: number;
-}
-
-/**
- * Vector search query interface
- */
-export interface VectorQuery {
- embedding: number[];
- topK: number;
- threshold?: number;
- filters?: Record<string, unknown>;
-}
-
-/**
- * Search result interface
- */
-export interface SearchResult {
- key: string;
- value: unknown;
- score: number;
- metadata: MemoryMetadata;
-}
-
-/**
- * Pre-defined memory entries for testing
- */
-export const memoryEntries: Record<string, MemoryEntry> = {
- agentPattern: {
- key: 'pattern:agent:queen-coordinator',
- value: {
- pattern: 'orchestration',
- successRate: 0.95,
- avgDuration: 150,
- },
- metadata: {
- type: 'semantic',
- tags: ['agent', 'pattern', 'queen'],
- source: 'learning-module',
- confidence: 0.92,
- },
- embedding: generateMockEmbedding(384, 'orchestration'),
- createdAt: new Date('2024-01-01T00:00:00Z'),
- updatedAt: new Date('2024-01-15T12:00:00Z'),
- },
-
- securityRule: {
- key: 'rule:security:path-traversal',
- value: {
- rule: 'block-path-traversal',
- patterns: ['../', '~/', '/etc/'],
- severity: 'critical',
- },
- metadata: {
- type: 'long-term',
- tags: ['security', 'rule', 'validation'],
- source: 'security-module',
- confidence: 1.0,
- },
- embedding: generateMockEmbedding(384, 'security'),
- createdAt: new Date('2024-01-01T00:00:00Z'),
- updatedAt: new Date('2024-01-01T00:00:00Z'),
- },
-
- taskMemory: {
- key: 'task:memory:impl-001',
- value: {
- taskId: 'impl-001',
- context: 'implementing security module',
- decisions: ['use argon2 for hashing', 'implement path validation'],
- },
- metadata: {
- type: 'episodic',
- tags: ['task', 'implementation', 'security'],
- ttl: 86400000, // 24 hours
- },
- embedding: generateMockEmbedding(384, 'implementation'),
- createdAt: new Date('2024-01-15T10:00:00Z'),
- updatedAt: new Date('2024-01-15T10:00:00Z'),
- expiresAt: new Date('2024-01-16T10:00:00Z'),
- },
-
- sessionContext: {
- key: 'session:context:session-001',
- value: {
- sessionId: 'session-001',
- user: 'developer',
- activeAgents: ['queen-coordinator', 'coder'],
- currentTask: 'security-implementation',
- },
- metadata: {
- type: 'short-term',
- tags: ['session', 'context'],
- ttl: 3600000, // 1 hour
- },
- createdAt: new Date('2024-01-15T14:00:00Z'),
- updatedAt: new Date('2024-01-15T14:30:00Z'),
- expiresAt: new Date('2024-01-15T15:30:00Z'),
- },
-
- learningTrajectory: {
- key: 'learning:trajectory:traj-001',
- value: {
- trajectoryId: 'traj-001',
- steps: [
- { action: 'analyze', result: 'success', reward: 0.8 },
- { action: 'implement', result: 'success', reward: 0.9 },
- { action: 'test', result: 'success', reward: 1.0 },
- ],
- totalReward: 2.7,
- },
- metadata: {
- type: 'long-term',
- tags: ['learning', 'trajectory', 'reinforcement'],
- source: 'reasoningbank',
- confidence: 0.88,
- },
- embedding: generateMockEmbedding(384, 'learning'),
- createdAt: new Date('2024-01-10T00:00:00Z'),
- updatedAt: new Date('2024-01-15T00:00:00Z'),
- },
-};
-
-/**
- * Pre-defined search results for testing
- */
-export const searchResults: Record<string, SearchResult[]> = {
- securityPatterns: [
- {
- key: 'pattern:security:input-validation',
- value: { pattern: 'validate all inputs', effectiveness: 0.99 },
- score: 0.95,
- metadata: { type: 'semantic', tags: ['security', 'pattern'] },
- },
- {
- key: 'pattern:security:output-encoding',
- value: { pattern: 'encode all outputs', effectiveness: 0.97 },
- score: 0.88,
- metadata: { type: 'semantic', tags: ['security', 'pattern'] },
- },
- {
- key: 'pattern:security:least-privilege',
- value: { pattern: 'minimal permissions', effectiveness: 0.95 },
- score: 0.82,
- metadata: { type: 'semantic', tags: ['security', 'pattern'] },
- },
- ],
-
- agentPatterns: [
- {
- key: 'pattern:agent:coordination',
- value: { pattern: 'hierarchical coordination', successRate: 0.92 },
- score: 0.91,
- metadata: { type: 'semantic', tags: ['agent', 'pattern'] },
- },
- {
- key: 'pattern:agent:communication',
- value: { pattern: 'async messaging', successRate: 0.89 },
- score: 0.85,
- metadata: { type: 'semantic', tags: ['agent', 'pattern'] },
- },
- ],
-
- emptyResults: [],
-};
-
-/**
- * Generate mock embedding vector
- * Creates deterministic embeddings based on seed string
- */
-export function generateMockEmbedding(dimensions: number, seed: string): number[] {
- const seedHash = hashString(seed);
- return Array.from({ length: dimensions }, (_, i) => {
- const value = Math.sin(seedHash + i * 0.1) * 0.5 + 0.5;
- return Math.round(value * 10000) / 10000; // 4 decimal places
- });
-}
-
-/**
- * Simple string hash function for deterministic embeddings
- */
-function hashString(str: string): number {
- let hash = 0;
- for (let i = 0; i < str.length; i++) {
- hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
- }
- return hash;
-}
-
-/**
- * Factory function to create memory entry with overrides
- */
-export function createMemoryEntry(
- base: keyof typeof memoryEntries,
- overrides?: Partial<MemoryEntry>
-): MemoryEntry {
- return {
- ...memoryEntries[base],
- ...overrides,
- key: overrides?.key ?? memoryEntries[base].key,
- createdAt: overrides?.createdAt ?? new Date(),
- updatedAt: overrides?.updatedAt ?? new Date(),
- };
-}
-
-/**
- * Factory function to create vector query
- */
-export function createVectorQuery(overrides?: Partial<VectorQuery>): VectorQuery {
- return {
- embedding: overrides?.embedding ?? generateMockEmbedding(384, 'query'),
- topK: overrides?.topK ?? 10,
- threshold: overrides?.threshold ?? 0.7,
- filters: overrides?.filters,
- };
-}
-
-/**
- * Create batch of memory entries for performance testing
- */
-export function createMemoryBatch(count: number, type: MemoryMetadata['type'] = 'semantic'): MemoryEntry[] {
- return Array.from({ length: count }, (_, i) => ({
- key: `batch:entry:${i}`,
- value: { index: i, data: `test data ${i}` },
- metadata: {
- type,
- tags: [`batch`, `entry-${i}`],
- },
- embedding: generateMockEmbedding(384, `batch-${i}`),
- createdAt: new Date(),
- updatedAt: new Date(),
- }));
-}
-
-/**
- * Invalid memory entries for error testing
- */
-export const invalidMemoryEntries = {
- emptyKey: {
- key: '',
- value: { data: 'test' },
- metadata: { type: 'short-term' as const, tags: [] },
- createdAt: new Date(),
- updatedAt: new Date(),
- },
-
- nullValue: {
- key: 'valid-key',
- value: null,
- metadata: { type: 'short-term' as const, tags: [] },
- createdAt: new Date(),
- updatedAt: new Date(),
- },
-
- invalidEmbeddingDimension: {
- key: 'valid-key',
- value: { data: 'test' },
- metadata: { type: 'semantic' as const, tags: [] },
- embedding: [0.1, 0.2], // Wrong dimension
- createdAt: new Date(),
- updatedAt: new Date(),
- },
-
- expiredEntry: {
- key: 'expired-key',
- value: { data: 'expired' },
- metadata: { type: 'short-term' as const, tags: [], ttl: -1000 },
- createdAt: new Date('2024-01-01T00:00:00Z'),
- updatedAt: new Date('2024-01-01T00:00:00Z'),
- expiresAt: new Date('2024-01-01T00:01:00Z'),
- },
-};
-
-/**
- * AgentDB specific test data
- */
-export const agentDBTestData = {
- // HNSW index configuration
- hnswConfig: {
- M: 16,
- efConstruction: 200,
- efSearch: 50,
- dimensions: 384,
- },
-
- // Expected performance metrics
- performanceTargets: {
- searchSpeedupMin: 150,
- searchSpeedupMax: 12500,
- memoryReduction: 0.50,
- insertionTime: 1, // ms
- searchTime: 0.1, // ms for 1M vectors
- },
-
- // Quantization configurations
- quantizationConfigs: {
- scalar4bit: { bits: 4, compressionRatio: 8 },
- scalar8bit: { bits: 8, compressionRatio: 4 },
- product: { subvectors: 8, bits: 8, compressionRatio: 32 },
- },
-};
diff --git a/v3/__tests__/fixtures/tasks.ts b/v3/__tests__/fixtures/tasks.ts
deleted file mode 100644
index 9107358eff..0000000000
--- a/v3/__tests__/fixtures/tasks.ts
+++ /dev/null
@@ -1,309 +0,0 @@
-/**
- * V3 Claude-Flow Task Fixtures
- *
- * Test data for task-related testing
- * Following London School principle of explicit test data
- */
-
-/**
- * Task definition interface
- */
-export interface TaskDefinition {
- name: string;
- type: string;
- payload: unknown;
- priority?: number;
- metadata?: Record<string, unknown>;
-}
-
-/**
- * Task instance interface
- */
-export interface TaskInstance {
- id: string;
- name: string;
- type: string;
- status: TaskStatus;
- payload: unknown;
- priority: number;
- createdAt: Date;
- startedAt?: Date;
- completedAt?: Date;
- error?: string;
-}
-
-export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-
-/**
- * Task result interface
- */
-export interface TaskResult {
- taskId: string;
- success: boolean;
- output?: unknown;
- error?: Error;
- duration: number;
- metrics?: TaskMetrics;
-}
-
-/**
- * Task metrics interface
- */
-export interface TaskMetrics {
- cpuTime: number;
- memoryUsage: number;
- ioOperations: number;
-}
-
-/**
- * Pre-defined task definitions for testing
- */
-export const taskDefinitions: Record<string, TaskDefinition> = {
- securityScan: {
- name: 'Security Scan',
- type: 'security',
- payload: {
- target: './src',
- scanType: 'full',
- severity: 'high',
- },
- priority: 100,
- metadata: { cve: ['CVE-1', 'CVE-2', 'CVE-3'] },
- },
-
- codeReview: {
- name: 'Code Review',
- type: 'review',
- payload: {
- files: ['src/main.ts', 'src/utils.ts'],
- rules: ['security', 'performance', 'style'],
- },
- priority: 80,
- },
-
- memoryOptimization: {
- name: 'Memory Optimization',
- type: 'optimization',
- payload: {
- targetReduction: 0.50,
- backend: 'agentdb',
- },
- priority: 70,
- },
-
- swarmCoordination: {
- name: 'Swarm Coordination',
- type: 'coordination',
- payload: {
- topology: 'hierarchical-mesh',
- agents: 15,
- task: 'implementation',
- },
- priority: 90,
- },
-
- unitTesting: {
- name: 'Unit Testing',
- type: 'testing',
- payload: {
- framework: 'vitest',
- coverage: 0.90,
- patterns: ['**/*.test.ts'],
- },
- priority: 75,
- },
-
- implementation: {
- name: 'Implementation Task',
- type: 'coding',
- payload: {
- module: 'security',
- feature: 'path-validation',
- },
- priority: 60,
- },
-};
-
-/**
- * Pre-defined task instances for testing
- */
-export const taskInstances: Record<string, TaskInstance> = {
- pendingSecurityScan: {
- id: 'task-security-001',
- name: 'Security Scan',
- type: 'security',
- status: 'pending',
- payload: taskDefinitions.securityScan.payload,
- priority: 100,
- createdAt: new Date('2024-01-15T10:00:00Z'),
- },
-
- runningCodeReview: {
- id: 'task-review-001',
- name: 'Code Review',
- type: 'review',
- status: 'running',
- payload: taskDefinitions.codeReview.payload,
- priority: 80,
- createdAt: new Date('2024-01-15T09:00:00Z'),
- startedAt: new Date('2024-01-15T09:05:00Z'),
- },
-
- completedUnitTesting: {
- id: 'task-testing-001',
- name: 'Unit Testing',
- type: 'testing',
- status: 'completed',
- payload: taskDefinitions.unitTesting.payload,
- priority: 75,
- createdAt: new Date('2024-01-15T08:00:00Z'),
- startedAt: new Date('2024-01-15T08:05:00Z'),
- completedAt: new Date('2024-01-15T08:30:00Z'),
- },
-
- failedImplementation: {
- id: 'task-impl-001',
- name: 'Implementation Task',
- type: 'coding',
- status: 'failed',
- payload: taskDefinitions.implementation.payload,
- priority: 60,
- createdAt: new Date('2024-01-15T07:00:00Z'),
- startedAt: new Date('2024-01-15T07:05:00Z'),
- completedAt: new Date('2024-01-15T07:20:00Z'),
- error: 'Compilation error: missing dependency',
- },
-
- cancelledSwarmCoordination: {
- id: 'task-swarm-001',
- name: 'Swarm Coordination',
- type: 'coordination',
- status: 'cancelled',
- payload: taskDefinitions.swarmCoordination.payload,
- priority: 90,
- createdAt: new Date('2024-01-15T06:00:00Z'),
- startedAt: new Date('2024-01-15T06:05:00Z'),
- },
-};
-
-/**
- * Pre-defined task results for testing
- */
-export const taskResults: Record<string, TaskResult> = {
- successfulSecurityScan: {
- taskId: 'task-security-001',
- success: true,
- output: {
- vulnerabilities: 0,
- scannedFiles: 150,
- duration: 5000,
- },
- duration: 5000,
- metrics: {
- cpuTime: 4500,
- memoryUsage: 128 * 1024 * 1024,
- ioOperations: 300,
- },
- },
-
- failedSecurityScan: {
- taskId: 'task-security-002',
- success: false,
- error: new Error('Critical vulnerability found: CVE-2024-001'),
- duration: 2500,
- },
-
- successfulCodeReview: {
- taskId: 'task-review-001',
- success: true,
- output: {
- issues: 3,
- suggestions: 10,
- approved: true,
- },
- duration: 15000,
- },
-};
-
-/**
- * Factory function to create task definition with overrides
- */
-export function createTaskDefinition(
- base: keyof typeof taskDefinitions,
- overrides?: Partial<TaskDefinition>
-): TaskDefinition {
- return {
- ...taskDefinitions[base],
- ...overrides,
- };
-}
-
-/**
- * Factory function to create task instance with overrides
- */
-export function createTaskInstance(
- base: keyof typeof taskInstances,
- overrides?: Partial<TaskInstance>
-): TaskInstance {
- return {
- ...taskInstances[base],
- ...overrides,
- id: overrides?.id ?? `task-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
- createdAt: overrides?.createdAt ?? new Date(),
- };
-}
-
-/**
- * Factory function to create task result with overrides
- */
-export function createTaskResult(
- base: keyof typeof taskResults,
- overrides?: Partial<TaskResult>
-): TaskResult {
- return {
- ...taskResults[base],
- ...overrides,
- };
-}
-
-/**
- * Invalid task definitions for error testing
- */
-export const invalidTaskDefinitions = {
- emptyName: {
- name: '',
- type: 'coding',
- payload: {},
- },
-
- emptyType: {
- name: 'Valid Name',
- type: '',
- payload: {},
- },
-
- nullPayload: {
- name: 'Valid Name',
- type: 'coding',
- payload: null,
- },
-
- invalidPriority: {
- name: 'Valid Name',
- type: 'coding',
- payload: {},
- priority: -100,
- },
-};
-
-/**
- * Task batch for swarm testing
- */
-export function createTaskBatch(count: number, type: string = 'coding'): TaskDefinition[] {
- return Array.from({ length: count }, (_, i) => ({
- name: `Batch Task ${i + 1}`,
- type,
- payload: { index: i },
- priority: Math.floor(Math.random() * 100),
- }));
-}
diff --git a/v3/__tests__/helpers/assertions.ts b/v3/__tests__/helpers/assertions.ts
deleted file mode 100644
index 5df36d8ccb..0000000000
--- a/v3/__tests__/helpers/assertions.ts
+++ /dev/null
@@ -1,286 +0,0 @@
-/**
- * V3 Claude-Flow Custom Assertions
- *
- * London School TDD Custom Assertions
- * - Behavior-focused assertions
- * - Interaction verification helpers
- * - Contract testing utilities
- */
-import { expect, type Mock } from 'vitest';
-
-/**
- * Assert that a mock was called in a specific sequence
- *
- * @example
- * assertCallSequence([
- * [mockRepo.findById, ['123']],
- * [mockValidator.validate, [user]],
- * [mockRepo.save, [user]],
- * ]);
- */
-export function assertCallSequence(
- sequence: Array<[Mock, unknown[]]>
-): void {
- const calls: Array<{ mock: Mock; args: unknown[]; order: number }> = [];
-
- for (const [mock, expectedArgs] of sequence) {
- const mockCalls = mock.mock.calls;
- const invocationOrder = mock.mock.invocationCallOrder;
-
- for (let i = 0; i < mockCalls.length; i++) {
- if (JSON.stringify(mockCalls[i]) === JSON.stringify(expectedArgs)) {
- calls.push({
- mock,
- args: mockCalls[i],
- order: invocationOrder[i],
- });
- break;
- }
- }
- }
-
- expect(calls.length).toBe(sequence.length);
-
- for (let i = 1; i < calls.length; i++) {
- expect(calls[i].order).toBeGreaterThan(calls[i - 1].order);
- }
-}
-
-/**
- * Assert that a mock was NOT called with specific arguments
- *
- * @example
- * assertNotCalledWith(mockRepo.save, [invalidUser]);
- */
-export function assertNotCalledWith(mock: Mock, args: unknown[]): void {
- const wasCalledWith = mock.mock.calls.some(
- (call: unknown[]) => JSON.stringify(call) === JSON.stringify(args)
- );
- expect(wasCalledWith).toBe(false);
-}
-
-/**
- * Assert interaction count for behavior verification
- *
- * @example
- * assertInteractionCount(mockService.process, 3);
- */
-export function assertInteractionCount(mock: Mock, expectedCount: number): void {
- expect(mock.mock.calls.length).toBe(expectedCount);
-}
-
-/**
- * Assert that all mocks in a group were called
- *
- * @example
- * assertAllCalled([mockA.method, mockB.method, mockC.method]);
- */
-export function assertAllCalled(mocks: Mock[]): void {
- for (const mock of mocks) {
- expect(mock).toHaveBeenCalled();
- }
-}
-
-/**
- * Assert that none of the mocks were called
- *
- * @example
- * assertNoneCalled([mockA.method, mockB.method]);
- */
-export function assertNoneCalled(mocks: Mock[]): void {
- for (const mock of mocks) {
- expect(mock).not.toHaveBeenCalled();
- }
-}
-
-/**
- * Assert contract compliance
- * Verifies that an object implements expected interface
- *
- * @example
- * assertContractCompliance(userService, UserServiceContract);
- */
-export function assertContractCompliance<T extends object>(
- implementation: T,
- contract: ContractDefinition<T>
-): void {
- for (const [method, spec] of Object.entries(contract.methods)) {
- expect(typeof (implementation as Record<string, unknown>)[method]).toBe('function');
- }
-}
-
-/**
- * Contract definition for interface compliance
- */
-export interface ContractDefinition<T> {
- methods: {
- [K in keyof T]?: {
- params: Array<{ name: string; type: string }>;
- returns: string;
- };
- };
-}
-
-/**
- * Assert async operation timing
- *
- * @example
- * await assertTimingWithin(async () => service.process(), 100);
- */
-export async function assertTimingWithin(
- operation: () => Promise<unknown>,
- maxMs: number
-): Promise<void> {
- const start = Date.now();
- await operation();
- const duration = Date.now() - start;
- expect(duration).toBeLessThanOrEqual(maxMs);
-}
-
-/**
- * Assert that an async operation completes within expected time range
- *
- * @example
- * await assertTimingRange(async () => service.process(), 50, 150);
- */
-export async function assertTimingRange(
- operation: () => Promise<unknown>,
- minMs: number,
- maxMs: number
-): Promise<void> {
- const start = Date.now();
- await operation();
- const duration = Date.now() - start;
- expect(duration).toBeGreaterThanOrEqual(minMs);
- expect(duration).toBeLessThanOrEqual(maxMs);
-}
-
-/**
- * Assert error type and message
- *
- * @example
- * await assertThrowsWithMessage(
- * async () => service.validate(invalid),
- * ValidationError,
- * 'Invalid input'
- * );
- */
-export async function assertThrowsWithMessage(
- operation: () => Promise<unknown>,
- ErrorType: new (...args: unknown[]) => Error,
- expectedMessage: string | RegExp
-): Promise<void> {
- let error: Error | null = null;
-
- try {
- await operation();
- } catch (e) {
- error = e as Error;
- }
-
- expect(error).toBeInstanceOf(ErrorType);
- if (typeof expectedMessage === 'string') {
- expect(error?.message).toContain(expectedMessage);
- } else {
- expect(error?.message).toMatch(expectedMessage);
- }
-}
-
-/**
- * Assert domain event was published
- *
- * @example
- * await assertEventPublished(mockEventBus, 'UserCreated', { userId: '123' });
- */
-export function assertEventPublished(
- eventBusMock: Mock,
- eventType: string,
- expectedPayload?: Record<string, unknown>
-): void {
- const publishCalls = eventBusMock.mock.calls;
-
- const matchingEvent = publishCalls.find((call: unknown[]) => {
- const event = call[0] as { type: string; payload: unknown };
- return event.type === eventType;
- });
-
- expect(matchingEvent).toBeDefined();
-
- if (expectedPayload && matchingEvent) {
- const actualPayload = (matchingEvent[0] as { payload: unknown }).payload;
- expect(actualPayload).toMatchObject(expectedPayload);
- }
-}
-
-/**
- * Assert that mock returns expected values in sequence
- *
- * @example
- * assertMockSequence(mockCounter.next, [1, 2, 3]);
- */
-export async function assertMockSequence(
- mock: Mock,
- expectedValues: unknown[]
-): Promise<void> {
- for (const expected of expectedValues) {
- const result = await mock();
- expect(result).toEqual(expected);
- }
-}
-
-/**
- * Security assertion - verify sensitive data handling
- *
- * @example
- * assertNoSensitiveDataLogged(mockLogger, ['password', 'token', 'secret']);
- */
-export function assertNoSensitiveDataLogged(
- loggerMock: Mock,
- sensitivePatterns: string[]
-): void {
- const allCalls = loggerMock.mock.calls;
-
- for (const call of allCalls) {
- const logContent = JSON.stringify(call);
- for (const pattern of sensitivePatterns) {
- expect(logContent.toLowerCase()).not.toContain(pattern.toLowerCase());
- }
- }
-}
-
-/**
- * Performance assertion - verify operation meets target
- *
- * @example
- * await assertPerformanceTarget(
- * async () => await search.execute(query),
- * { targetMs: 100, iterations: 10 }
- * );
- */
-export async function assertPerformanceTarget(
- operation: () => Promise<unknown>,
- config: { targetMs: number; iterations: number; warmupIterations?: number }
-): Promise<{ averageMs: number; minMs: number; maxMs: number }> {
- const { targetMs, iterations, warmupIterations = 3 } = config;
-
- // Warmup
- for (let i = 0; i < warmupIterations; i++) {
- await operation();
- }
-
- const timings: number[] = [];
-
- for (let i = 0; i < iterations; i++) {
- const start = performance.now();
- await operation();
- timings.push(performance.now() - start);
- }
-
- const averageMs = timings.reduce((a, b) => a + b, 0) / timings.length;
- const minMs = Math.min(...timings);
- const maxMs = Math.max(...timings);
-
- expect(averageMs).toBeLessThanOrEqual(targetMs);
-
- return { averageMs, minMs, maxMs };
-}
diff --git a/v3/__tests__/helpers/create-mock.ts b/v3/__tests__/helpers/create-mock.ts
deleted file mode 100644
index 45631f6797..0000000000
--- a/v3/__tests__/helpers/create-mock.ts
+++ /dev/null
@@ -1,200 +0,0 @@
-/**
- * V3 Claude-Flow Mock Factory
- *
- * London School TDD Mock Creation Utilities
- * - Creates type-safe mocks for behavior verification
- * - Supports deep mocking for complex objects
- * - Enables interaction tracking for behavior testing
- */
-import { vi, type Mock } from 'vitest';
-
-/**
- * Type for a fully mocked interface
- */
-export type MockedInterface<T> = {
- [K in keyof T]: T[K] extends (...args: infer A) => infer R
- ? Mock<(...args: A) => R>
- : T[K];
-};
-
-/**
- * Create a shallow mock of an interface
- * Each method becomes a vi.fn() for behavior verification
- *
- * @example
- * const mockRepo = createMock<UserRepository>();
- * mockRepo.findById.mockResolvedValue(user);
- * expect(mockRepo.save).toHaveBeenCalledWith(user);
- */
-export function createMock<T extends object>(): MockedInterface<T> {
- return new Proxy({} as MockedInterface<T>, {
- get: (target, prop: string | symbol) => {
- if (typeof prop === 'string' && !(prop in target)) {
- (target as Record<string | symbol, unknown>)[prop] = vi.fn();
- }
- return (target as Record<string | symbol, unknown>)[prop];
- },
- });
-}
-
-/**
- * Create a deep mock that handles nested objects
- * Useful for complex interfaces with nested dependencies
- *
- * @example
- * const mockService = createDeepMock<ComplexService>();
- * mockService.nested.method.mockReturnValue(result);
- */
-export function createDeepMock<T extends object>(): MockedInterface<T> {
- const cache = new Map<string | symbol, unknown>();
-
- return new Proxy({} as MockedInterface<T>, {
- get: (target, prop: string | symbol) => {
- if (!cache.has(prop)) {
- const mock = vi.fn();
- // Allow chaining for nested access
- (mock as unknown as Record<string, unknown>).mockReturnValue =
- mock.mockReturnValue.bind(mock);
- cache.set(prop, mock);
- }
- return cache.get(prop);
- },
- });
-}
-
-/**
- * Create a spy mock that wraps an existing object
- * Preserves original behavior while enabling verification
- *
- * @example
- * const spied = createSpyMock(realService);
- * await spied.process();
- * expect(spied.process).toHaveBeenCalled();
- */
-export function createSpyMock<T extends object>(target: T): MockedInterface<T> {
- const spied = { ...target } as MockedInterface<T>;
-
- for (const key of Object.keys(target) as Array<keyof T>) {
- const value = target[key];
- if (typeof value === 'function') {
- (spied as Record<keyof T, unknown>)[key] = vi.fn(value.bind(target));
- }
- }
-
- return spied;
-}
-
-/**
- * Create a mock with predefined behavior
- * Useful for common test scenarios
- *
- * @example
- * const mockRepo = createMockWithBehavior<UserRepository>({
- * findById: async (id) => ({ id, name: 'Test' }),
- * save: async (user) => user,
- * });
- */
-export function createMockWithBehavior<T extends object>(
- implementations: Partial<{ [K in keyof T]: T[K] }>
-): MockedInterface<T> {
- const mock = createMock<T>();
-
- for (const [key, impl] of Object.entries(implementations)) {
- if (typeof impl === 'function') {
- (mock as Record<string, Mock>)[key].mockImplementation(impl as (...args: unknown[]) => unknown);
- }
- }
-
- return mock;
-}
-
-/**
- * Create a mock that fails on first call, succeeds on retry
- * Useful for testing retry logic and error handling
- *
- * @example
- * const mockApi = createRetryMock<ApiClient>('fetch', new Error('Network'), data);
- */
-export function createRetryMock<T extends object>(
- methodName: keyof T,
- firstError: Error,
- successValue: unknown
-): MockedInterface<T> {
- const mock = createMock<T>();
-
- (mock as Record<string, Mock>)[methodName as string]
- .mockRejectedValueOnce(firstError)
- .mockResolvedValue(successValue);
-
- return mock;
-}
-
-/**
- * Create a sequence mock that returns different values per call
- * Useful for testing stateful interactions
- *
- * @example
- * const mockCounter = createSequenceMock<Counter>('next', [1, 2, 3, 4, 5]);
- */
-export function createSequenceMock<T extends object>(
- methodName: keyof T,
- values: unknown[]
-): MockedInterface<T> {
- const mock = createMock<T>();
- const fn = (mock as Record<string, Mock>)[methodName as string];
-
- values.forEach((value, index) => {
- if (index === values.length - 1) {
- fn.mockReturnValue(value);
- } else {
- fn.mockReturnValueOnce(value);
- }
- });
-
- return mock;
-}
-
-/**
- * Interaction recorder for complex behavior verification
- * Tracks all calls across multiple mocks
- *
- * @example
- * const recorder = new InteractionRecorder();
- * recorder.track('repo', mockRepo);
- * recorder.track('notifier', mockNotifier);
- * await service.process();
- * expect(recorder.getInteractionOrder()).toEqual(['repo.save', 'notifier.notify']);
- */
-export class InteractionRecorder {
- private interactions: Array<{ name: string; method: string; args: unknown[]; timestamp: number }> = [];
-
- track<T extends object>(name: string, mock: MockedInterface<T>): void {
- for (const key of Object.keys(mock)) {
- const method = (mock as Record<string, Mock>)[key];
- if (typeof method?.mockImplementation === 'function') {
- const original = method.getMockImplementation();
- method.mockImplementation((...args: unknown[]) => {
- this.interactions.push({
- name,
- method: key,
- args,
- timestamp: Date.now(),
- });
- return original?.(...args);
- });
- }
- }
- }
-
- getInteractions(): Array<{ name: string; method: string; args: unknown[] }> {
- return this.interactions.map(({ name, method, args }) => ({ name, method, args }));
- }
-
- getInteractionOrder(): string[] {
- return this.interactions.map(({ name, method }) => `${name}.${method}`);
- }
-
- clear(): void {
- this.interactions = [];
- }
-}
diff --git a/v3/__tests__/helpers/index.ts b/v3/__tests__/helpers/index.ts
deleted file mode 100644
index 6954184d15..0000000000
--- a/v3/__tests__/helpers/index.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * V3 Claude-Flow Test Helpers Index
- *
- * Central export for all test helpers
- */
-
-// Mock factory utilities
-export {
- createMock,
- createDeepMock,
- createSpyMock,
- createMockWithBehavior,
- createRetryMock,
- createSequenceMock,
- InteractionRecorder,
- type MockedInterface,
-} from './create-mock';
-
-// Test application builder
-export {
- createTestApplication,
- type TestApplication,
- type IEventBus,
- type ITaskManager,
- type IAgentLifecycle,
- type IMemoryService,
- type ISecurityService,
- type ISwarmCoordinator,
-} from './test-application';
-
-// Swarm test instance
-export {
- createSwarmTestInstance,
- SwarmTestInstance,
- type V3AgentType,
- type SwarmTopology,
- type SwarmAgent,
- type SwarmMessage,
- type SwarmTask,
- type SwarmTaskResult,
-} from './swarm-instance';
-
-// Custom assertions
-export {
- assertCallSequence,
- assertNotCalledWith,
- assertInteractionCount,
- assertAllCalled,
- assertNoneCalled,
- assertContractCompliance,
- assertTimingWithin,
- assertTimingRange,
- assertThrowsWithMessage,
- assertEventPublished,
- assertMockSequence,
- assertNoSensitiveDataLogged,
- assertPerformanceTarget,
- type ContractDefinition,
-} from './assertions';
diff --git a/v3/__tests__/helpers/swarm-instance.ts b/v3/__tests__/helpers/swarm-instance.ts
deleted file mode 100644
index 60789c0352..0000000000
--- a/v3/__tests__/helpers/swarm-instance.ts
+++ /dev/null
@@ -1,326 +0,0 @@
-/**
- * V3 Claude-Flow Swarm Test Instance
- *
- * Creates isolated swarm instances for testing
- * Supports 15-agent V3 swarm topology testing
- */
-import { vi, type Mock } from 'vitest';
-import { createMock, type MockedInterface, InteractionRecorder } from './create-mock';
-
-/**
- * Agent types for V3 15-agent swarm
- */
-export type V3AgentType =
- | 'queen-coordinator'
- | 'security-architect'
- | 'security-auditor'
- | 'memory-specialist'
- | 'swarm-specialist'
- | 'integration-architect'
- | 'performance-engineer'
- | 'core-architect'
- | 'test-architect'
- | 'project-coordinator'
- | 'coder'
- | 'reviewer'
- | 'tester'
- | 'planner'
- | 'researcher';
-
-/**
- * Swarm topology types
- */
-export type SwarmTopology = 'hierarchical' | 'mesh' | 'adaptive' | 'hierarchical-mesh';
-
-/**
- * Agent interface for swarm testing
- */
-export interface SwarmAgent {
- id: string;
- type: V3AgentType;
- status: 'idle' | 'busy' | 'terminated';
- capabilities: string[];
- execute(task: SwarmTask): Promise<SwarmTaskResult>;
- communicate(message: SwarmMessage): Promise<void>;
-}
-
-/**
- * Swarm message interface
- */
-export interface SwarmMessage {
- from: string;
- to: string | 'broadcast';
- type: 'task' | 'result' | 'status' | 'coordination';
- payload: unknown;
- timestamp: Date;
-}
-
-/**
- * Swarm task interface
- */
-export interface SwarmTask {
- id: string;
- type: string;
- payload: unknown;
- priority: number;
- assignedTo?: string;
-}
-
-/**
- * Swarm task result
- */
-export interface SwarmTaskResult {
- taskId: string;
- agentId: string;
- success: boolean;
- output?: unknown;
- error?: Error;
- duration: number;
-}
-
-/**
- * Swarm coordination result
- */
-export interface SwarmCoordinationResult {
- success: boolean;
- completedTasks: number;
- failedTasks: number;
- totalDuration: number;
- agentMetrics: Map<string, AgentMetrics>;
-}
-
-/**
- * Agent metrics
- */
-export interface AgentMetrics {
- tasksCompleted: number;
- tasksFailed: number;
- averageTaskDuration: number;
- totalDuration: number;
-}
-
-/**
- * Create a test swarm instance with mocked agents
- */
-export function createSwarmTestInstance(config?: {
- topology?: SwarmTopology;
- agentTypes?: V3AgentType[];
-}): SwarmTestInstance {
- const topology = config?.topology ?? 'hierarchical-mesh';
- const agentTypes = config?.agentTypes ?? [
- 'queen-coordinator',
- 'security-architect',
- 'security-auditor',
- 'memory-specialist',
- 'swarm-specialist',
- ];
-
- return new SwarmTestInstance(topology, agentTypes);
-}
-
-/**
- * Swarm test instance class
- */
-export class SwarmTestInstance {
- private agents: Map<string, MockedInterface<SwarmAgent>> = new Map();
- private messages: SwarmMessage[] = [];
- private taskResults: SwarmTaskResult[] = [];
- private interactionRecorder: InteractionRecorder;
- private isInitialized = false;
-
- constructor(
- public readonly topology: SwarmTopology,
- private readonly agentTypes: V3AgentType[]
- ) {
- this.interactionRecorder = new InteractionRecorder();
- this.initializeAgents();
- }
-
- private initializeAgents(): void {
- for (const type of this.agentTypes) {
- const id = `${type}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
- const agent = this.createMockAgent(id, type);
- this.agents.set(id, agent);
- this.interactionRecorder.track(id, agent);
- }
- }
-
- private createMockAgent(id: string, type: V3AgentType): MockedInterface<SwarmAgent> {
- const mock = createMock<SwarmAgent>();
-
- // Set default properties
- Object.defineProperty(mock, 'id', { value: id, writable: false });
- Object.defineProperty(mock, 'type', { value: type, writable: false });
- Object.defineProperty(mock, 'status', { value: 'idle', writable: true });
- Object.defineProperty(mock, 'capabilities', {
- value: this.getCapabilitiesForType(type),
- writable: false
- });
-
- // Configure default behavior
- mock.execute.mockImplementation(async (task: SwarmTask) => {
- const result: SwarmTaskResult = {
- taskId: task.id,
- agentId: id,
- success: true,
- duration: Math.random() * 100 + 10,
- };
- this.taskResults.push(result);
- return result;
- });
-
- mock.communicate.mockImplementation(async (message: SwarmMessage) => {
- this.messages.push(message);
- });
-
- return mock;
- }
-
- private getCapabilitiesForType(type: V3AgentType): string[] {
- const capabilities: Record<V3AgentType, string[]> = {
- 'queen-coordinator': ['orchestration', 'task-distribution', 'agent-management'],
- 'security-architect': ['security-design', 'threat-modeling', 'security-review'],
- 'security-auditor': ['cve-detection', 'vulnerability-scanning', 'security-testing'],
- 'memory-specialist': ['memory-optimization', 'agentdb-integration', 'caching'],
- 'swarm-specialist': ['coordination', 'consensus', 'communication'],
- 'integration-architect': ['api-design', 'system-integration', 'compatibility'],
- 'performance-engineer': ['optimization', 'benchmarking', 'profiling'],
- 'core-architect': ['ddd-design', 'architecture', 'domain-modeling'],
- 'test-architect': ['tdd', 'test-design', 'quality-assurance'],
- 'project-coordinator': ['project-management', 'scheduling', 'reporting'],
- 'coder': ['coding', 'implementation', 'debugging'],
- 'reviewer': ['code-review', 'quality-check', 'suggestions'],
- 'tester': ['testing', 'test-execution', 'coverage'],
- 'planner': ['planning', 'estimation', 'roadmap'],
- 'researcher': ['research', 'analysis', 'documentation'],
- };
- return capabilities[type];
- }
-
- /**
- * Initialize the swarm
- */
- async initialize(): Promise<void> {
- this.isInitialized = true;
- // Simulate initialization delay
- await new Promise(resolve => setTimeout(resolve, 1));
- }
-
- /**
- * Get an agent by type
- */
- getAgent(type: V3AgentType): MockedInterface<SwarmAgent> | undefined {
- for (const [_, agent] of this.agents) {
- if ((agent as unknown as SwarmAgent).type === type) {
- return agent;
- }
- }
- return undefined;
- }
-
- /**
- * Get all agents
- */
- getAllAgents(): MockedInterface<SwarmAgent>[] {
- return Array.from(this.agents.values());
- }
-
- /**
- * Get agent by ID
- */
- getAgentById(id: string): MockedInterface<SwarmAgent> | undefined {
- return this.agents.get(id);
- }
-
- /**
- * Get all messages
- */
- getMessages(): SwarmMessage[] {
- return [...this.messages];
- }
-
- /**
- * Get task results
- */
- getTaskResults(): SwarmTaskResult[] {
- return [...this.taskResults];
- }
-
- /**
- * Get interaction order for behavior verification
- */
- getInteractionOrder(): string[] {
- return this.interactionRecorder.getInteractionOrder();
- }
-
- /**
- * Get all interactions
- */
- getInteractions(): Array<{ name: string; method: string; args: unknown[] }> {
- return this.interactionRecorder.getInteractions();
- }
-
- /**
- * Coordinate a task across agents
- */
- async coordinate(task: SwarmTask): Promise<SwarmCoordinationResult> {
- if (!this.isInitialized) {
- throw new Error('Swarm not initialized');
- }
-
- const startTime = Date.now();
- const results: SwarmTaskResult[] = [];
-
- // Simulate coordination based on topology
- const queen = this.getAgent('queen-coordinator');
- if (queen && this.topology.includes('hierarchical')) {
- await queen.communicate({
- from: 'coordinator',
- to: 'broadcast',
- type: 'task',
- payload: task,
- timestamp: new Date(),
- });
- }
-
- // Execute task on appropriate agent
- for (const agent of this.agents.values()) {
- const result = await agent.execute(task);
- results.push(result);
- }
-
- const completedTasks = results.filter(r => r.success).length;
- const failedTasks = results.filter(r => !r.success).length;
-
- return {
- success: failedTasks === 0,
- completedTasks,
- failedTasks,
- totalDuration: Date.now() - startTime,
- agentMetrics: new Map(),
- };
- }
-
- /**
- * Shutdown the swarm
- */
- async shutdown(): Promise<void> {
- for (const agent of this.agents.values()) {
- Object.defineProperty(agent, 'status', { value: 'terminated', writable: true });
- }
- this.isInitialized = false;
- }
-
- /**
- * Reset the swarm state
- */
- reset(): void {
- this.messages = [];
- this.taskResults = [];
- this.interactionRecorder.clear();
-
- for (const agent of this.agents.values()) {
- vi.clearAllMocks();
- }
- }
-}
diff --git a/v3/__tests__/helpers/test-application.ts b/v3/__tests__/helpers/test-application.ts
deleted file mode 100644
index 0082eccbc6..0000000000
--- a/v3/__tests__/helpers/test-application.ts
+++ /dev/null
@@ -1,310 +0,0 @@
-/**
- * V3 Claude-Flow Test Application Factory
- *
- * Creates isolated test instances of the application
- * Following London School principles for dependency injection
- */
-import { vi, type Mock } from 'vitest';
-import { createMock, type MockedInterface } from './create-mock';
-
-/**
- * Core domain interfaces for testing
- */
-export interface IEventBus {
- publish(event: DomainEvent): Promise<void>;
- subscribe(eventType: string, handler: EventHandler): void;
- unsubscribe(eventType: string, handler: EventHandler): void;
-}
-
-export interface ITaskManager {
- create(task: TaskDefinition): Promise<Task>;
- execute(taskId: string): Promise<TaskResult>;
- cancel(taskId: string): Promise<void>;
- getStatus(taskId: string): Promise<TaskStatus>;
-}
-
-export interface IAgentLifecycle {
- spawn(config: AgentConfig): Promise<Agent>;
- terminate(agentId: string): Promise<void>;
- getAgent(agentId: string): Promise<Agent | null>;
- listAgents(): Promise<Agent[]>;
-}
-
-export interface IMemoryService {
- store(key: string, value: unknown, metadata?: MemoryMetadata): Promise<void>;
- retrieve(key: string): Promise<unknown>;
- search(query: VectorQuery): Promise<SearchResult[]>;
- delete(key: string): Promise<void>;
-}
-
-export interface ISecurityService {
- validatePath(path: string): boolean;
- hashPassword(password: string): Promise<string>;
- verifyPassword(password: string, hash: string): Promise<boolean>;
- executeSecurely(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
-}
-
-export interface ISwarmCoordinator {
- initialize(config: SwarmConfig): Promise<void>;
- coordinate(agents: Agent[], task: Task): Promise<CoordinationResult>;
- shutdown(): Promise<void>;
-}
-
-/**
- * Type definitions for domain objects
- */
-export interface DomainEvent {
- type: string;
- payload: unknown;
- timestamp: Date;
- correlationId?: string;
-}
-
-export type EventHandler = (event: DomainEvent) => Promise<void>;
-
-export interface TaskDefinition {
- name: string;
- type: string;
- payload: unknown;
- priority?: number;
-}
-
-export interface Task {
- id: string;
- name: string;
- type: string;
- status: TaskStatus;
- payload: unknown;
- createdAt: Date;
-}
-
-export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-
-export interface TaskResult {
- taskId: string;
- success: boolean;
- output?: unknown;
- error?: Error;
- duration: number;
-}
-
-export interface AgentConfig {
- type: string;
- name: string;
- capabilities: string[];
-}
-
-export interface Agent {
- id: string;
- type: string;
- name: string;
- status: 'idle' | 'busy' | 'terminated';
-}
-
-export interface MemoryMetadata {
- ttl?: number;
- tags?: string[];
- embedding?: number[];
-}
-
-export interface VectorQuery {
- embedding: number[];
- topK: number;
- threshold?: number;
-}
-
-export interface SearchResult {
- key: string;
- value: unknown;
- score: number;
-}
-
-export interface ExecuteOptions {
- timeout?: number;
- cwd?: string;
- shell?: boolean;
-}
-
-export interface ExecuteResult {
- stdout: string;
- stderr: string;
- exitCode: number;
-}
-
-export interface SwarmConfig {
- topology: 'hierarchical' | 'mesh' | 'adaptive';
- maxAgents: number;
-}
-
-export interface CoordinationResult {
- success: boolean;
- results: TaskResult[];
- duration: number;
-}
-
-/**
- * Test application builder with full dependency injection
- *
- * @example
- * const app = createTestApplication()
- * .withMockEventBus()
- * .withMockTaskManager()
- * .build();
- *
- * await app.services.taskManager.create(task);
- * expect(app.mocks.eventBus.publish).toHaveBeenCalled();
- */
-export function createTestApplication(): TestApplicationBuilder {
- return new TestApplicationBuilder();
-}
-
-/**
- * Test application structure with mocked services
- */
-export interface TestApplication {
- services: {
- eventBus: IEventBus;
- taskManager: ITaskManager;
- agentLifecycle: IAgentLifecycle;
- memoryService: IMemoryService;
- securityService: ISecurityService;
- swarmCoordinator: ISwarmCoordinator;
- };
- mocks: {
- eventBus: MockedInterface<IEventBus>;
- taskManager: MockedInterface<ITaskManager>;
- agentLifecycle: MockedInterface<IAgentLifecycle>;
- memoryService: MockedInterface<IMemoryService>;
- securityService: MockedInterface<ISecurityService>;
- swarmCoordinator: MockedInterface<ISwarmCoordinator>;
- };
-}
-
-/**
- * Builder class for constructing test applications
- */
-class TestApplicationBuilder {
- private eventBus: MockedInterface<IEventBus> = createMock<IEventBus>();
- private taskManager: MockedInterface<ITaskManager> = createMock<ITaskManager>();
- private agentLifecycle: MockedInterface<IAgentLifecycle> = createMock<IAgentLifecycle>();
- private memoryService: MockedInterface<IMemoryService> = createMock<IMemoryService>();
- private securityService: MockedInterface<ISecurityService> = createMock<ISecurityService>();
- private swarmCoordinator: MockedInterface<ISwarmCoordinator> = createMock<ISwarmCoordinator>();
-
- /**
- * Configure mock event bus with default behavior
- */
- withMockEventBus(configure?: (mock: MockedInterface<IEventBus>) => void): this {
- this.eventBus = createMock<IEventBus>();
- this.eventBus.publish.mockResolvedValue(undefined);
- configure?.(this.eventBus);
- return this;
- }
-
- /**
- * Configure mock task manager with default behavior
- */
- withMockTaskManager(configure?: (mock: MockedInterface<ITaskManager>) => void): this {
- this.taskManager = createMock<ITaskManager>();
- this.taskManager.create.mockImplementation(async (def: TaskDefinition) => ({
- id: `task-${Date.now()}`,
- name: def.name,
- type: def.type,
- status: 'pending' as TaskStatus,
- payload: def.payload,
- createdAt: new Date(),
- }));
- this.taskManager.execute.mockResolvedValue({
- taskId: 'test-task',
- success: true,
- duration: 100,
- });
- configure?.(this.taskManager);
- return this;
- }
-
- /**
- * Configure mock agent lifecycle with default behavior
- */
- withMockAgentLifecycle(configure?: (mock: MockedInterface<IAgentLifecycle>) => void): this {
- this.agentLifecycle = createMock<IAgentLifecycle>();
- this.agentLifecycle.spawn.mockImplementation(async (config: AgentConfig) => ({
- id: `agent-${Date.now()}`,
- type: config.type,
- name: config.name,
- status: 'idle' as const,
- }));
- this.agentLifecycle.listAgents.mockResolvedValue([]);
- configure?.(this.agentLifecycle);
- return this;
- }
-
- /**
- * Configure mock memory service with default behavior
- */
- withMockMemoryService(configure?: (mock: MockedInterface<IMemoryService>) => void): this {
- this.memoryService = createMock<IMemoryService>();
- this.memoryService.store.mockResolvedValue(undefined);
- this.memoryService.retrieve.mockResolvedValue(null);
- this.memoryService.search.mockResolvedValue([]);
- configure?.(this.memoryService);
- return this;
- }
-
- /**
- * Configure mock security service with default behavior
- */
- withMockSecurityService(configure?: (mock: MockedInterface<ISecurityService>) => void): this {
- this.securityService = createMock<ISecurityService>();
- this.securityService.validatePath.mockReturnValue(true);
- this.securityService.hashPassword.mockResolvedValue('hashed');
- this.securityService.verifyPassword.mockResolvedValue(true);
- this.securityService.executeSecurely.mockResolvedValue({
- stdout: '',
- stderr: '',
- exitCode: 0,
- });
- configure?.(this.securityService);
- return this;
- }
-
- /**
- * Configure mock swarm coordinator with default behavior
- */
- withMockSwarmCoordinator(configure?: (mock: MockedInterface<ISwarmCoordinator>) => void): this {
- this.swarmCoordinator = createMock<ISwarmCoordinator>();
- this.swarmCoordinator.initialize.mockResolvedValue(undefined);
- this.swarmCoordinator.coordinate.mockResolvedValue({
- success: true,
- results: [],
- duration: 0,
- });
- this.swarmCoordinator.shutdown.mockResolvedValue(undefined);
- configure?.(this.swarmCoordinator);
- return this;
- }
-
- /**
- * Build the test application with all configured mocks
- */
- build(): TestApplication {
- return {
- services: {
- eventBus: this.eventBus as IEventBus,
- taskManager: this.taskManager as ITaskManager,
- agentLifecycle: this.agentLifecycle as IAgentLifecycle,
- memoryService: this.memoryService as IMemoryService,
- securityService: this.securityService as ISecurityService,
- swarmCoordinator: this.swarmCoordinator as ISwarmCoordinator,
- },
- mocks: {
- eventBus: this.eventBus,
- taskManager: this.taskManager,
- agentLifecycle: this.agentLifecycle,
- memoryService: this.memoryService,
- securityService: this.securityService,
- swarmCoordinator: this.swarmCoordinator,
- },
- };
- }
-}
diff --git a/v3/__tests__/integration/agentic-flow-bridge.test.ts b/v3/__tests__/integration/agentic-flow-bridge.test.ts
deleted file mode 100644
index 37b3ccb866..0000000000
--- a/v3/__tests__/integration/agentic-flow-bridge.test.ts
+++ /dev/null
@@ -1,398 +0,0 @@
-/**
- * AgenticFlowBridge Test Suite
- *
- * Comprehensive tests for the agentic-flow integration bridge.
- * Tests initialization, component management, and lifecycle.
- *
- * @module v3/__tests__/integration/agentic-flow-bridge.test
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import {
- AgenticFlowBridge,
- createAgenticFlowBridge,
- getDefaultBridge,
- resetDefaultBridge,
-} from '../../integration/agentic-flow-bridge.js';
-import type { IntegrationConfig, FeatureFlags } from '../../integration/types.js';
-
-describe('AgenticFlowBridge', () => {
- let bridge: AgenticFlowBridge;
-
- beforeEach(() => {
- bridge = new AgenticFlowBridge();
- });
-
- afterEach(async () => {
- if (bridge) {
- await bridge.shutdown();
- }
- await resetDefaultBridge();
- });
-
- describe('initialization', () => {
- it('should initialize with default configuration', async () => {
- await bridge.initialize();
-
- const status = bridge.getStatus();
- expect(status.initialized).toBe(true);
- expect(status.connectedComponents).toContain('sdk');
- });
-
- it('should initialize with custom configuration', async () => {
- const customConfig: Partial<IntegrationConfig> = {
- features: {
- enableSONA: true,
- enableFlashAttention: false,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: false,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- debug: true,
- };
-
- await bridge.initialize(customConfig);
-
- const flags = bridge.getFeatureFlags();
- expect(flags.enableSONA).toBe(true);
- expect(flags.enableFlashAttention).toBe(false);
- });
-
- it('should be idempotent - multiple initialize calls are safe', async () => {
- await bridge.initialize();
- await bridge.initialize();
- await bridge.initialize();
-
- const status = bridge.getStatus();
- expect(status.initialized).toBe(true);
- });
-
- it('should emit initialized event', async () => {
- const handler = vi.fn();
- bridge.on('initialized', handler);
-
- await bridge.initialize();
-
- expect(handler).toHaveBeenCalledTimes(1);
- expect(handler).toHaveBeenCalledWith(
- expect.objectContaining({
- duration: expect.any(Number),
- components: expect.any(Array),
- })
- );
- });
- });
-
- describe('runtime detection', () => {
- it('should detect runtime information', async () => {
- await bridge.initialize();
-
- const status = bridge.getStatus();
- expect(status.runtime).toBeDefined();
- expect(status.runtime.platform).toMatch(/linux|darwin|win32/);
- expect(status.runtime.arch).toMatch(/x64|arm64|ia32/);
- expect(status.runtime.nodeVersion).toMatch(/^v\d+/);
- });
-
- it('should determine performance tier', async () => {
- await bridge.initialize();
-
- const status = bridge.getStatus();
- expect(['optimal', 'good', 'fallback']).toContain(
- status.runtime.performanceTier
- );
- });
- });
-
- describe('component management', () => {
- it('should provide SONA adapter when enabled', async () => {
- await bridge.initialize({
- features: {
- enableSONA: true,
- enableFlashAttention: false,
- enableAgentDB: false,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- });
-
- const sona = await bridge.getSONAAdapter();
- expect(sona).toBeDefined();
- });
-
- it('should throw when SONA is disabled', async () => {
- await bridge.initialize({
- features: {
- enableSONA: false,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- });
-
- await expect(bridge.getSONAAdapter()).rejects.toThrow('disabled');
- });
-
- it('should provide Attention coordinator when enabled', async () => {
- await bridge.initialize({
- features: {
- enableSONA: false,
- enableFlashAttention: true,
- enableAgentDB: false,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- });
-
- const attention = await bridge.getAttentionCoordinator();
- expect(attention).toBeDefined();
- });
-
- it('should throw when Attention is disabled', async () => {
- await bridge.initialize({
- features: {
- enableSONA: true,
- enableFlashAttention: false,
- enableAgentDB: true,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- });
-
- await expect(bridge.getAttentionCoordinator()).rejects.toThrow('disabled');
- });
-
- it('should provide SDK bridge', async () => {
- await bridge.initialize();
-
- const sdk = await bridge.getSDKBridge();
- expect(sdk).toBeDefined();
- });
- });
-
- describe('feature management', () => {
- it('should check if feature is enabled', async () => {
- await bridge.initialize({
- features: {
- enableSONA: true,
- enableFlashAttention: false,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- });
-
- expect(bridge.isFeatureEnabled('enableSONA')).toBe(true);
- expect(bridge.isFeatureEnabled('enableFlashAttention')).toBe(false);
- });
-
- it('should enable feature dynamically', async () => {
- await bridge.initialize({
- features: {
- enableSONA: false,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- });
-
- expect(bridge.isFeatureEnabled('enableSONA')).toBe(false);
-
- await bridge.enableFeature('enableSONA');
-
- expect(bridge.isFeatureEnabled('enableSONA')).toBe(true);
- });
-
- it('should disable feature dynamically', async () => {
- await bridge.initialize({
- features: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- });
-
- expect(bridge.isFeatureEnabled('enableSONA')).toBe(true);
-
- await bridge.disableFeature('enableSONA');
-
- expect(bridge.isFeatureEnabled('enableSONA')).toBe(false);
- });
-
- it('should emit feature-enabled event', async () => {
- await bridge.initialize({
- features: {
- enableSONA: false,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- });
-
- const handler = vi.fn();
- bridge.on('feature-enabled', handler);
-
- await bridge.enableFeature('enableSONA');
-
- expect(handler).toHaveBeenCalledWith({ feature: 'enableSONA' });
- });
- });
-
- describe('health check', () => {
- it('should perform health check on all components', async () => {
- await bridge.initialize();
-
- const health = await bridge.healthCheck();
-
- expect(health['sdk']).toBeDefined();
- expect(health['sdk'].status).toBe('healthy');
- });
-
- it('should report unhealthy components', async () => {
- await bridge.initialize();
-
- // Get health with all components
- const health = await bridge.healthCheck();
-
- for (const component of Object.values(health)) {
- expect(['healthy', 'degraded', 'unhealthy']).toContain(component.status);
- }
- });
- });
-
- describe('reconfiguration', () => {
- it('should reconfigure bridge settings', async () => {
- await bridge.initialize({
- features: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- });
-
- await bridge.reconfigure({
- debug: true,
- });
-
- // Should emit reconfigured event
- const handler = vi.fn();
- bridge.on('reconfigured', handler);
-
- await bridge.reconfigure({
- debug: false,
- });
-
- expect(handler).toHaveBeenCalled();
- });
- });
-
- describe('shutdown', () => {
- it('should shutdown gracefully', async () => {
- await bridge.initialize();
-
- const shutdownHandler = vi.fn();
- bridge.on('shutdown', shutdownHandler);
-
- await bridge.shutdown();
-
- expect(shutdownHandler).toHaveBeenCalled();
-
- const status = bridge.getStatus();
- expect(status.initialized).toBe(false);
- });
-
- it('should clear all components on shutdown', async () => {
- await bridge.initialize({
- features: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- });
-
- await bridge.shutdown();
-
- const status = bridge.getStatus();
- expect(status.connectedComponents).toHaveLength(0);
- });
- });
-
- describe('factory functions', () => {
- it('should create bridge with createAgenticFlowBridge', async () => {
- const newBridge = await createAgenticFlowBridge();
-
- const status = newBridge.getStatus();
- expect(status.initialized).toBe(true);
-
- await newBridge.shutdown();
- });
-
- it('should provide singleton with getDefaultBridge', async () => {
- const bridge1 = await getDefaultBridge();
- const bridge2 = await getDefaultBridge();
-
- expect(bridge1).toBe(bridge2);
- });
-
- it('should reset singleton with resetDefaultBridge', async () => {
- const bridge1 = await getDefaultBridge();
- await resetDefaultBridge();
- const bridge2 = await getDefaultBridge();
-
- expect(bridge1).not.toBe(bridge2);
- });
- });
-});
diff --git a/v3/__tests__/integration/attention-coordinator.test.ts b/v3/__tests__/integration/attention-coordinator.test.ts
deleted file mode 100644
index 9cc927b416..0000000000
--- a/v3/__tests__/integration/attention-coordinator.test.ts
+++ /dev/null
@@ -1,499 +0,0 @@
-/**
- * AttentionCoordinator Test Suite
- *
- * Comprehensive tests for the Flash Attention coordinator.
- * Tests attention computation, agent coordination, and expert routing.
- *
- * @module v3/__tests__/integration/attention-coordinator.test
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import {
- AttentionCoordinator,
- createAttentionCoordinator,
-} from '../../integration/attention-coordinator.js';
-import type {
- AttentionConfiguration,
- AttentionMechanism,
-} from '../../integration/types.js';
-
-describe('AttentionCoordinator', () => {
- let coordinator: AttentionCoordinator;
-
- beforeEach(async () => {
- coordinator = new AttentionCoordinator();
- await coordinator.initialize();
- });
-
- afterEach(async () => {
- if (coordinator) {
- await coordinator.shutdown();
- }
- });
-
- describe('initialization', () => {
- it('should initialize with default configuration', async () => {
- const newCoordinator = new AttentionCoordinator();
- await newCoordinator.initialize();
-
- expect(newCoordinator.getMechanism()).toBe('flash');
-
- await newCoordinator.shutdown();
- });
-
- it('should initialize with custom configuration', async () => {
- const config: Partial<AttentionConfiguration> = {
- mechanism: 'multi-head',
- numHeads: 16,
- headDim: 128,
- dropoutRate: 0.1,
- };
-
- const newCoordinator = new AttentionCoordinator(config);
- await newCoordinator.initialize();
-
- expect(newCoordinator.getMechanism()).toBe('multi-head');
-
- await newCoordinator.shutdown();
- });
-
- it('should emit initialized event', async () => {
- const newCoordinator = new AttentionCoordinator();
- const handler = vi.fn();
- newCoordinator.on('initialized', handler);
-
- await newCoordinator.initialize();
-
- expect(handler).toHaveBeenCalledWith({ mechanism: 'flash' });
-
- await newCoordinator.shutdown();
- });
-
- it('should validate configuration', async () => {
- const invalidCoordinator = new AttentionCoordinator({
- numHeads: -1, // Invalid
- });
-
- await expect(invalidCoordinator.initialize()).rejects.toThrow(
- 'numHeads must be positive'
- );
- });
- });
-
- describe('mechanism management', () => {
- const mechanisms: AttentionMechanism[] = [
- 'flash',
- 'multi-head',
- 'linear',
- 'hyperbolic',
- 'moe',
- 'local',
- 'global',
- 'sparse',
- ];
-
- it.each(mechanisms)('should switch to %s mechanism', async (mechanism) => {
- await coordinator.setMechanism(mechanism);
- expect(coordinator.getMechanism()).toBe(mechanism);
- });
-
- it('should emit mechanism-changed event', async () => {
- const handler = vi.fn();
- coordinator.on('mechanism-changed', handler);
-
- await coordinator.setMechanism('linear');
-
- expect(handler).toHaveBeenCalledWith(
- expect.objectContaining({
- previousMechanism: 'flash',
- newMechanism: 'linear',
- })
- );
- });
-
- it('should clear cache when mechanism changes', async () => {
- // Perform some computation to populate cache
- const query = [0.1, 0.2, 0.3];
- const key = [0.4, 0.5, 0.6];
- const value = [0.7, 0.8, 0.9];
-
- await coordinator.compute({ query, key, value, useCache: true });
-
- // Change mechanism
- await coordinator.setMechanism('linear');
-
- // Verify cache is cleared (would need internal access to verify)
- // For now, just verify the mechanism changed
- expect(coordinator.getMechanism()).toBe('linear');
- });
- });
-
- describe('attention computation', () => {
- it('should compute attention output', async () => {
- const query = new Array(64).fill(0).map(() => Math.random());
- const key = new Array(64).fill(0).map(() => Math.random());
- const value = new Array(64).fill(0).map(() => Math.random());
-
- const result = await coordinator.compute({ query, key, value });
-
- expect(result.output).toBeDefined();
- expect(result.output.length).toBe(value.length);
- expect(result.mechanism).toBe('flash');
- expect(result.latencyMs).toBeGreaterThanOrEqual(0);
- });
-
- it('should handle Float32Array input', async () => {
- const query = new Float32Array(64).map(() => Math.random());
- const key = new Float32Array(64).map(() => Math.random());
- const value = new Float32Array(64).map(() => Math.random());
-
- const result = await coordinator.compute({ query, key, value });
-
- expect(result.output).toBeDefined();
- });
-
- it('should use cache when enabled', async () => {
- const query = [0.1, 0.2, 0.3];
- const key = [0.4, 0.5, 0.6];
- const value = [0.7, 0.8, 0.9];
-
- // First computation
- const result1 = await coordinator.compute({
- query,
- key,
- value,
- useCache: true,
- });
- expect(result1.cacheHit).toBe(false);
-
- // Second computation (should hit cache)
- const result2 = await coordinator.compute({
- query,
- key,
- value,
- useCache: true,
- });
- expect(result2.cacheHit).toBe(true);
- });
-
- it('should emit attention-computed event', async () => {
- const handler = vi.fn();
- coordinator.on('attention-computed', handler);
-
- const query = [0.1, 0.2, 0.3];
- const key = [0.4, 0.5, 0.6];
- const value = [0.7, 0.8, 0.9];
-
- await coordinator.compute({ query, key, value });
-
- expect(handler).toHaveBeenCalledWith(
- expect.objectContaining({
- mechanism: 'flash',
- latencyMs: expect.any(Number),
- })
- );
- });
- });
-
- describe('agent coordination', () => {
- it('should coordinate agent outputs', async () => {
- const outputs = ['Result A', 'Result B', 'Result C'];
- const embeddings = [
- [0.1, 0.2, 0.3],
- [0.2, 0.3, 0.4],
- [0.15, 0.25, 0.35],
- ];
-
- const result = await coordinator.coordinateAgents({
- outputs,
- embeddings,
- });
-
- expect(result.consensus).toBeDefined();
- expect(result.weights.length).toBe(outputs.length);
- expect(result.confidence).toBeGreaterThan(0);
- expect(result.confidence).toBeLessThanOrEqual(1);
- });
-
- it('should return weights that sum to 1', async () => {
- const outputs = ['A', 'B', 'C', 'D'];
- const embeddings = [
- [0.1, 0.2],
- [0.3, 0.4],
- [0.5, 0.6],
- [0.7, 0.8],
- ];
-
- const result = await coordinator.coordinateAgents({
- outputs,
- embeddings,
- });
-
- const sum = result.weights.reduce((a, b) => a + b, 0);
- expect(sum).toBeCloseTo(1, 5);
- });
-
- it('should use specified mechanism', async () => {
- const outputs = ['A', 'B'];
- const embeddings = [
- [0.1, 0.2],
- [0.3, 0.4],
- ];
-
- const result = await coordinator.coordinateAgents({
- outputs,
- embeddings,
- mechanism: 'moe',
- });
-
- expect(result.consensus).toBeDefined();
- });
-
- it('should handle single agent', async () => {
- const outputs = ['Only result'];
- const embeddings = [[0.1, 0.2, 0.3]];
-
- const result = await coordinator.coordinateAgents({
- outputs,
- embeddings,
- });
-
- expect(result.consensus).toBe('Only result');
- expect(result.weights[0]).toBe(1);
- expect(result.confidence).toBe(1);
- });
-
- it('should emit agents-coordinated event', async () => {
- const handler = vi.fn();
- coordinator.on('agents-coordinated', handler);
-
- const outputs = ['A', 'B'];
- const embeddings = [
- [0.1, 0.2],
- [0.3, 0.4],
- ];
-
- await coordinator.coordinateAgents({ outputs, embeddings });
-
- expect(handler).toHaveBeenCalledWith(
- expect.objectContaining({
- agentCount: 2,
- mechanism: 'flash',
- confidence: expect.any(Number),
- })
- );
- });
- });
-
- describe('expert routing', () => {
- it('should route task to experts', async () => {
- const task = { embedding: [0.1, 0.2, 0.3, 0.4] };
- const experts = [
- { id: 'expert-1', embedding: [0.1, 0.2, 0.3, 0.4] },
- { id: 'expert-2', embedding: [0.9, 0.8, 0.7, 0.6] },
- { id: 'expert-3', embedding: [0.15, 0.25, 0.35, 0.45] },
- ];
-
- const result = await coordinator.routeToExperts({ task, experts });
-
- expect(result.length).toBeGreaterThan(0);
- expect(result[0]).toHaveProperty('expertId');
- expect(result[0]).toHaveProperty('score');
- });
-
- it('should respect topK parameter', async () => {
- const task = { embedding: [0.5, 0.5, 0.5] };
- const experts = [
- { id: 'e1', embedding: [0.1, 0.1, 0.1] },
- { id: 'e2', embedding: [0.2, 0.2, 0.2] },
- { id: 'e3', embedding: [0.3, 0.3, 0.3] },
- { id: 'e4', embedding: [0.4, 0.4, 0.4] },
- { id: 'e5', embedding: [0.5, 0.5, 0.5] },
- ];
-
- const result = await coordinator.routeToExperts({
- task,
- experts,
- topK: 2,
- });
-
- expect(result.length).toBe(2);
- });
-
- it('should sort by score descending', async () => {
- const task = { embedding: [0.5, 0.5, 0.5] };
- const experts = [
- { id: 'e1', embedding: [0.1, 0.1, 0.1] },
- { id: 'e2', embedding: [0.5, 0.5, 0.5] }, // Exact match
- { id: 'e3', embedding: [0.3, 0.3, 0.3] },
- ];
-
- const result = await coordinator.routeToExperts({
- task,
- experts,
- topK: 3,
- });
-
- // First result should be the exact match
- expect(result[0].expertId).toBe('e2');
- expect(result[0].score).toBeCloseTo(1, 2);
- });
-
- it('should emit experts-routed event', async () => {
- const handler = vi.fn();
- coordinator.on('experts-routed', handler);
-
- const task = { embedding: [0.5, 0.5] };
- const experts = [
- { id: 'e1', embedding: [0.1, 0.1] },
- { id: 'e2', embedding: [0.5, 0.5] },
- ];
-
- await coordinator.routeToExperts({ task, experts });
-
- expect(handler).toHaveBeenCalledWith(
- expect.objectContaining({
- expertCount: 2,
- topK: 3,
- topExpert: expect.any(String),
- })
- );
- });
- });
-
- describe('mechanism profiles', () => {
- it('should return mechanism profile', () => {
- const profile = coordinator.getMechanismProfile('flash');
-
- expect(profile.speedupRange).toBeDefined();
- expect(profile.memoryReduction).toBeDefined();
- expect(profile.latencyMs).toBeDefined();
- expect(profile.bestFor).toBeDefined();
- });
-
- it('should return current mechanism profile by default', () => {
- const profile = coordinator.getMechanismProfile();
-
- expect(profile).toBeDefined();
- expect(profile.speedupRange[0]).toBeGreaterThan(0);
- });
- });
-
- describe('mechanism suggestion', () => {
- it('should suggest flash for general use', () => {
- const suggestion = coordinator.suggestMechanism('general purpose');
- expect(suggestion).toBe('flash');
- });
-
- it('should suggest linear for long sequences', () => {
- const suggestion = coordinator.suggestMechanism('long-sequences');
- expect(suggestion).toBe('linear');
- });
-
- it('should suggest hyperbolic for hierarchical', () => {
- const suggestion = coordinator.suggestMechanism('hierarchical-data');
- expect(suggestion).toBe('hyperbolic');
- });
-
- it('should suggest moe for multi-task', () => {
- const suggestion = coordinator.suggestMechanism('multi-task');
- expect(suggestion).toBe('moe');
- });
-
- it('should default to flash for unknown use case', () => {
- const suggestion = coordinator.suggestMechanism('completely unknown');
- expect(suggestion).toBe('flash');
- });
- });
-
- describe('metrics', () => {
- it('should track metrics', async () => {
- const query = [0.1, 0.2, 0.3];
- const key = [0.4, 0.5, 0.6];
- const value = [0.7, 0.8, 0.9];
-
- // Perform some operations
- await coordinator.compute({ query, key, value });
- await coordinator.compute({ query, key, value });
- await coordinator.compute({ query, key, value });
-
- const metrics = await coordinator.getMetrics();
-
- expect(metrics.totalOperations).toBeGreaterThanOrEqual(3);
- expect(metrics.avgLatencyMs).toBeGreaterThanOrEqual(0);
- expect(metrics.speedupFactor).toBeGreaterThan(0);
- });
-
- it('should track cache hit rate', async () => {
- const query = [0.1, 0.2];
- const key = [0.3, 0.4];
- const value = [0.5, 0.6];
-
- // First call - cache miss
- await coordinator.compute({ query, key, value, useCache: true });
-
- // Second call - cache hit
- await coordinator.compute({ query, key, value, useCache: true });
-
- const metrics = await coordinator.getMetrics();
-
- expect(metrics.cacheHitRate).toBeGreaterThan(0);
- });
- });
-
- describe('cache management', () => {
- it('should clear cache', async () => {
- const query = [0.1, 0.2, 0.3];
- const key = [0.4, 0.5, 0.6];
- const value = [0.7, 0.8, 0.9];
-
- // Populate cache
- await coordinator.compute({ query, key, value, useCache: true });
-
- // Clear cache
- coordinator.clearCache();
-
- // Should be cache miss now
- const result = await coordinator.compute({
- query,
- key,
- value,
- useCache: true,
- });
-
- expect(result.cacheHit).toBe(false);
- });
-
- it('should emit cache-cleared event', () => {
- const handler = vi.fn();
- coordinator.on('cache-cleared', handler);
-
- coordinator.clearCache();
-
- expect(handler).toHaveBeenCalled();
- });
- });
-
- describe('factory function', () => {
- it('should create initialized coordinator', async () => {
- const newCoordinator = await createAttentionCoordinator({
- mechanism: 'linear',
- });
-
- expect(newCoordinator.getMechanism()).toBe('linear');
-
- await newCoordinator.shutdown();
- });
- });
-
- describe('shutdown', () => {
- it('should shutdown gracefully', async () => {
- const handler = vi.fn();
- coordinator.on('shutdown', handler);
-
- await coordinator.shutdown();
-
- expect(handler).toHaveBeenCalled();
- });
- });
-});
diff --git a/v3/__tests__/integration/security-flow.test.ts b/v3/__tests__/integration/security-flow.test.ts
deleted file mode 100644
index b09e78035c..0000000000
--- a/v3/__tests__/integration/security-flow.test.ts
+++ /dev/null
@@ -1,606 +0,0 @@
-/**
- * V3 Claude-Flow Security Flow Integration Tests
- *
- * Integration tests for security module workflow
- * Tests end-to-end security operations across components
- */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { createMock, type MockedInterface } from '../helpers/create-mock';
-import { securityConfigs } from '../fixtures/configurations';
-
-/**
- * Security service integration interface
- */
-interface ISecurityService {
- initialize(): Promise<void>;
- validateAndHash(password: string): Promise<{ valid: boolean; hash?: string; errors: string[] }>;
- validateAndExecute(command: string, args: string[]): Promise<ExecutionResult>;
- validatePath(path: string): ValidationResult;
- shutdown(): Promise<void>;
-}
-
-/**
- * Crypto provider interface
- */
-interface ICryptoProvider {
- argon2Hash(password: string, options: HashOptions): Promise<string>;
- argon2Verify(hash: string, password: string): Promise<boolean>;
- generateSalt(length: number): Promise<string>;
-}
-
-/**
- * Command executor interface
- */
-interface ICommandExecutor {
- spawn(command: string, args: string[], options: SpawnOptions): Promise<SpawnResult>;
-}
-
-/**
- * Audit logger interface
- */
-interface IAuditLogger {
- log(event: AuditEvent): Promise<void>;
- getEvents(filter?: AuditFilter): Promise<AuditEvent[]>;
-}
-
-interface HashOptions {
- memoryCost: number;
- timeCost: number;
- parallelism: number;
- salt: string;
-}
-
-interface ExecutionResult {
- success: boolean;
- stdout: string;
- stderr: string;
- exitCode: number;
- blocked: boolean;
- reason?: string;
-}
-
-interface ValidationResult {
- valid: boolean;
- sanitized?: string;
- errors: string[];
-}
-
-interface SpawnOptions {
- timeout: number;
- shell: boolean;
-}
-
-interface SpawnResult {
- stdout: string;
- stderr: string;
- exitCode: number;
-}
-
-interface AuditEvent {
- type: string;
- action: string;
- details: unknown;
- timestamp: Date;
- success: boolean;
-}
-
-interface AuditFilter {
- type?: string;
- startTime?: Date;
- endTime?: Date;
-}
-
-/**
- * Security service implementation for integration testing
- */
-class SecurityService implements ISecurityService {
- private initialized = false;
-
- constructor(
- private readonly crypto: ICryptoProvider,
- private readonly executor: ICommandExecutor,
- private readonly auditLogger: IAuditLogger,
- private readonly config: typeof securityConfigs.strict
- ) {}
-
- async initialize(): Promise<void> {
- this.initialized = true;
- await this.auditLogger.log({
- type: 'security',
- action: 'initialize',
- details: { config: 'strict' },
- timestamp: new Date(),
- success: true,
- });
- }
-
- async validateAndHash(password: string): Promise<{ valid: boolean; hash?: string; errors: string[] }> {
- const errors: string[] = [];
-
- // Validate password length
- if (!password || password.length < 8) {
- errors.push('Password must be at least 8 characters');
- }
-
- // Validate password complexity
- if (!/[A-Z]/.test(password)) {
- errors.push('Password must contain uppercase letter');
- }
- if (!/[a-z]/.test(password)) {
- errors.push('Password must contain lowercase letter');
- }
- if (!/[0-9]/.test(password)) {
- errors.push('Password must contain number');
- }
-
- if (errors.length > 0) {
- await this.auditLogger.log({
- type: 'security',
- action: 'password_validation_failed',
- details: { errors },
- timestamp: new Date(),
- success: false,
- });
- return { valid: false, errors };
- }
-
- const salt = await this.crypto.generateSalt(16);
- const hash = await this.crypto.argon2Hash(password, {
- memoryCost: this.config.hashing.memoryCost ?? 65536,
- timeCost: this.config.hashing.timeCost ?? 3,
- parallelism: this.config.hashing.parallelism ?? 4,
- salt,
- });
-
- await this.auditLogger.log({
- type: 'security',
- action: 'password_hashed',
- details: { algorithm: this.config.hashing.algorithm },
- timestamp: new Date(),
- success: true,
- });
-
- return { valid: true, hash, errors: [] };
- }
-
- async validateAndExecute(command: string, args: string[]): Promise<ExecutionResult> {
- const baseCommand = command.split(' ')[0];
-
- // Check blocked commands
- if (this.config.execution.blockedCommands.includes(baseCommand)) {
- await this.auditLogger.log({
- type: 'security',
- action: 'command_blocked',
- details: { command: baseCommand },
- timestamp: new Date(),
- success: false,
- });
-
- return {
- success: false,
- stdout: '',
- stderr: 'Command blocked by security policy',
- exitCode: -1,
- blocked: true,
- reason: `Command "${baseCommand}" is blocked`,
- };
- }
-
- // Check allowed commands
- if (!this.config.execution.allowedCommands.includes(baseCommand)) {
- await this.auditLogger.log({
- type: 'security',
- action: 'command_not_allowed',
- details: { command: baseCommand },
- timestamp: new Date(),
- success: false,
- });
-
- return {
- success: false,
- stdout: '',
- stderr: 'Command not in allowed list',
- exitCode: -1,
- blocked: true,
- reason: `Command "${baseCommand}" is not allowed`,
- };
- }
-
- // Sanitize arguments
- const sanitizedArgs = args.map((arg) =>
- arg.replace(/[;&|`$()]/g, '').replace(/\n/g, '')
- );
-
- // Execute command
- const result = await this.executor.spawn(baseCommand, sanitizedArgs, {
- timeout: this.config.execution.timeout,
- shell: this.config.execution.shell,
- });
-
- await this.auditLogger.log({
- type: 'security',
- action: 'command_executed',
- details: { command: baseCommand, exitCode: result.exitCode },
- timestamp: new Date(),
- success: result.exitCode === 0,
- });
-
- return {
- success: result.exitCode === 0,
- stdout: result.stdout,
- stderr: result.stderr,
- exitCode: result.exitCode,
- blocked: false,
- };
- }
-
- validatePath(path: string): ValidationResult {
- const errors: string[] = [];
-
- // Check for empty path
- if (!path || path.length === 0) {
- errors.push('Path cannot be empty');
- return { valid: false, errors };
- }
-
- // Check for blocked patterns
- for (const pattern of this.config.paths.blockedPatterns) {
- if (path.includes(pattern)) {
- errors.push(`Path contains blocked pattern: ${pattern}`);
- }
- }
-
- // Check length
- if (path.length > this.config.paths.maxPathLength) {
- errors.push(`Path exceeds maximum length of ${this.config.paths.maxPathLength}`);
- }
-
- // Check null bytes
- if (path.includes('\0')) {
- errors.push('Path contains null byte');
- }
-
- if (errors.length > 0) {
- return { valid: false, errors };
- }
-
- // Sanitize path
- let sanitized = path;
- for (const pattern of this.config.paths.blockedPatterns) {
- sanitized = sanitized.split(pattern).join('');
- }
- sanitized = sanitized.replace(/\0/g, '');
-
- return { valid: true, sanitized, errors: [] };
- }
-
- async shutdown(): Promise<void> {
- await this.auditLogger.log({
- type: 'security',
- action: 'shutdown',
- details: {},
- timestamp: new Date(),
- success: true,
- });
- this.initialized = false;
- }
-}
-
-describe('Security Flow Integration', () => {
- let mockCrypto: MockedInterface<ICryptoProvider>;
- let mockExecutor: MockedInterface<ICommandExecutor>;
- let mockAuditLogger: MockedInterface<IAuditLogger>;
- let securityService: SecurityService;
-
- beforeEach(() => {
- mockCrypto = createMock<ICryptoProvider>();
- mockExecutor = createMock<ICommandExecutor>();
- mockAuditLogger = createMock<IAuditLogger>();
-
- mockCrypto.generateSalt.mockResolvedValue('random-salt-16');
- mockCrypto.argon2Hash.mockResolvedValue('$argon2id$v=19$...');
- mockCrypto.argon2Verify.mockResolvedValue(true);
-
- mockExecutor.spawn.mockResolvedValue({
- stdout: 'success',
- stderr: '',
- exitCode: 0,
- });
-
- mockAuditLogger.log.mockResolvedValue(undefined);
- mockAuditLogger.getEvents.mockResolvedValue([]);
-
- securityService = new SecurityService(
- mockCrypto,
- mockExecutor,
- mockAuditLogger,
- securityConfigs.strict
- );
- });
-
- describe('Password Security Flow', () => {
- it('should validate and hash password end-to-end', async () => {
- // Given
- await securityService.initialize();
- const password = 'SecurePass123!';
-
- // When
- const result = await securityService.validateAndHash(password);
-
- // Then
- expect(result.valid).toBe(true);
- expect(result.hash).toBeDefined();
- expect(result.errors).toHaveLength(0);
- });
-
- it('should reject invalid password with multiple errors', async () => {
- // Given
- await securityService.initialize();
- const password = 'weak';
-
- // When
- const result = await securityService.validateAndHash(password);
-
- // Then
- expect(result.valid).toBe(false);
- expect(result.errors).toContain('Password must be at least 8 characters');
- });
-
- it('should audit password operations', async () => {
- // Given
- await securityService.initialize();
-
- // When
- await securityService.validateAndHash('SecurePass123!');
-
- // Then
- expect(mockAuditLogger.log).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'security',
- action: 'password_hashed',
- })
- );
- });
-
- it('should audit failed validation', async () => {
- // Given
- await securityService.initialize();
-
- // When
- await securityService.validateAndHash('weak');
-
- // Then
- expect(mockAuditLogger.log).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'security',
- action: 'password_validation_failed',
- success: false,
- })
- );
- });
- });
-
- describe('Command Execution Security Flow', () => {
- it('should execute allowed command successfully', async () => {
- // Given
- await securityService.initialize();
-
- // When
- const result = await securityService.validateAndExecute('npm', ['install']);
-
- // Then
- expect(result.success).toBe(true);
- expect(result.blocked).toBe(false);
- });
-
- it('should block dangerous commands', async () => {
- // Given
- await securityService.initialize();
-
- // When
- const result = await securityService.validateAndExecute('rm', ['-rf', '/']);
-
- // Then
- expect(result.success).toBe(false);
- expect(result.blocked).toBe(true);
- expect(result.reason).toContain('rm');
- });
-
- it('should reject commands not in allowed list', async () => {
- // Given
- await securityService.initialize();
-
- // When
- const result = await securityService.validateAndExecute('wget', ['http://evil.com']);
-
- // Then
- expect(result.success).toBe(false);
- expect(result.blocked).toBe(true);
- });
-
- it('should sanitize command arguments', async () => {
- // Given
- await securityService.initialize();
-
- // When
- await securityService.validateAndExecute('npm', ['install;rm -rf /']);
-
- // Then
- expect(mockExecutor.spawn).toHaveBeenCalledWith(
- 'npm',
- ['installrm -rf /'], // Semicolon removed
- expect.any(Object)
- );
- });
-
- it('should audit command execution', async () => {
- // Given
- await securityService.initialize();
-
- // When
- await securityService.validateAndExecute('npm', ['install']);
-
- // Then
- expect(mockAuditLogger.log).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'security',
- action: 'command_executed',
- })
- );
- });
-
- it('should audit blocked commands', async () => {
- // Given
- await securityService.initialize();
-
- // When
- await securityService.validateAndExecute('rm', ['-rf']);
-
- // Then
- expect(mockAuditLogger.log).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'security',
- action: 'command_blocked',
- success: false,
- })
- );
- });
- });
-
- describe('Path Validation Security Flow', () => {
- it('should validate safe paths', async () => {
- // Given
- const path = './v3/src/security/index.ts';
-
- // When
- const result = securityService.validatePath(path);
-
- // Then
- expect(result.valid).toBe(true);
- expect(result.errors).toHaveLength(0);
- });
-
- it('should block directory traversal', async () => {
- // Given
- const path = '../../../etc/passwd';
-
- // When
- const result = securityService.validatePath(path);
-
- // Then
- expect(result.valid).toBe(false);
- expect(result.errors.some((e) => e.includes('../'))).toBe(true);
- });
-
- it('should block absolute system paths', async () => {
- // Given
- const path = '/etc/shadow';
-
- // When
- const result = securityService.validatePath(path);
-
- // Then
- expect(result.valid).toBe(false);
- });
-
- it('should block null byte injection', async () => {
- // Given
- const path = 'file.txt\0.exe';
-
- // When
- const result = securityService.validatePath(path);
-
- // Then
- expect(result.valid).toBe(false);
- expect(result.errors.some((e) => e.includes('null byte'))).toBe(true);
- });
-
- it('should sanitize and return safe path', async () => {
- // Given
- const path = './safe/path/file.ts';
-
- // When
- const result = securityService.validatePath(path);
-
- // Then
- expect(result.valid).toBe(true);
- expect(result.sanitized).toBe('./safe/path/file.ts');
- });
- });
-
- describe('Security Service Lifecycle', () => {
- it('should initialize and audit', async () => {
- // When
- await securityService.initialize();
-
- // Then
- expect(mockAuditLogger.log).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'security',
- action: 'initialize',
- })
- );
- });
-
- it('should shutdown and audit', async () => {
- // Given
- await securityService.initialize();
-
- // When
- await securityService.shutdown();
-
- // Then
- expect(mockAuditLogger.log).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'security',
- action: 'shutdown',
- })
- );
- });
- });
-
- describe('CVE Prevention Integration', () => {
- it('should prevent CVE-1 (directory traversal) end-to-end', async () => {
- // Given
- const attacks = [
- '../../../etc/passwd',
- '..\\..\\..\\Windows\\System32',
- '....//....//etc/passwd',
- ];
-
- // When/Then
- for (const attack of attacks) {
- const result = securityService.validatePath(attack);
- expect(result.valid).toBe(false);
- }
- });
-
- it('should prevent CVE-2 (absolute path injection) end-to-end', async () => {
- // Given
- const attacks = ['/etc/passwd', '/var/log/auth.log', '/tmp/malicious'];
-
- // When/Then
- for (const attack of attacks) {
- const result = securityService.validatePath(attack);
- expect(result.valid).toBe(false);
- }
- });
-
- it('should prevent CVE-3 (command injection) end-to-end', async () => {
- // Given
- await securityService.initialize();
-
- // When
- const result = await securityService.validateAndExecute('npm', [
- 'install; rm -rf /',
- ]);
-
- // Then - command should execute but with sanitized args
- expect(mockExecutor.spawn).toHaveBeenCalledWith(
- 'npm',
- ['install rm -rf /'], // Semicolon removed
- expect.any(Object)
- );
- });
- });
-});
diff --git a/v3/__tests__/integration/sona-adapter.test.ts b/v3/__tests__/integration/sona-adapter.test.ts
deleted file mode 100644
index 2b0a2cf930..0000000000
--- a/v3/__tests__/integration/sona-adapter.test.ts
+++ /dev/null
@@ -1,510 +0,0 @@
-/**
- * SONAAdapter Test Suite
- *
- * Comprehensive tests for the SONA learning adapter.
- * Tests trajectory tracking, pattern storage, and learning modes.
- *
- * @module v3/__tests__/integration/sona-adapter.test
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import {
- SONAAdapter,
- createSONAAdapter,
-} from '../../integration/sona-adapter.js';
-import type { SONAConfiguration, SONALearningMode } from '../../integration/types.js';
-
-describe('SONAAdapter', () => {
- let adapter: SONAAdapter;
-
- beforeEach(async () => {
- adapter = new SONAAdapter();
- await adapter.initialize();
- });
-
- afterEach(async () => {
- if (adapter) {
- await adapter.shutdown();
- }
- });
-
- describe('initialization', () => {
- it('should initialize with default configuration', async () => {
- const newAdapter = new SONAAdapter();
- await newAdapter.initialize();
-
- expect(newAdapter.getMode()).toBe('balanced');
-
- await newAdapter.shutdown();
- });
-
- it('should initialize with custom configuration', async () => {
- const newAdapter = new SONAAdapter({
- mode: 'real-time',
- learningRate: 0.01,
- maxPatterns: 5000,
- });
- await newAdapter.initialize();
-
- expect(newAdapter.getMode()).toBe('real-time');
-
- await newAdapter.shutdown();
- });
-
- it('should emit initialized event', async () => {
- const newAdapter = new SONAAdapter();
- const handler = vi.fn();
- newAdapter.on('initialized', handler);
-
- await newAdapter.initialize();
-
- expect(handler).toHaveBeenCalledWith({ mode: 'balanced' });
-
- await newAdapter.shutdown();
- });
- });
-
- describe('learning modes', () => {
- const modes: SONALearningMode[] = [
- 'real-time',
- 'balanced',
- 'research',
- 'edge',
- 'batch',
- ];
-
- it.each(modes)('should switch to %s mode', async (mode) => {
- await adapter.setMode(mode);
- expect(adapter.getMode()).toBe(mode);
- });
-
- it('should emit mode-changed event', async () => {
- const handler = vi.fn();
- adapter.on('mode-changed', handler);
-
- await adapter.setMode('research');
-
- expect(handler).toHaveBeenCalledWith(
- expect.objectContaining({
- previousMode: 'balanced',
- newMode: 'research',
- })
- );
- });
-
- it('should apply mode-specific configuration', async () => {
- await adapter.setMode('edge');
-
- const stats = await adapter.getStats();
- expect(stats.currentMode).toBe('edge');
- });
- });
-
- describe('trajectory tracking', () => {
- it('should begin a new trajectory', async () => {
- const trajectoryId = await adapter.beginTrajectory({
- taskId: 'test-task-1',
- description: 'Test trajectory',
- category: 'testing',
- });
-
- expect(trajectoryId).toMatch(/^traj_/);
- });
-
- it('should record trajectory steps', async () => {
- const trajectoryId = await adapter.beginTrajectory({
- taskId: 'test-task-1',
- });
-
- await adapter.recordTrajectoryStep({
- trajectoryId,
- action: 'Action 1',
- observation: 'Observation 1',
- reward: 0.5,
- });
-
- await adapter.recordTrajectoryStep({
- trajectoryId,
- action: 'Action 2',
- observation: 'Observation 2',
- reward: 0.8,
- });
-
- const trajectory = await adapter.endTrajectory({
- trajectoryId,
- success: true,
- });
-
- expect(trajectory.steps).toHaveLength(2);
- expect(trajectory.totalReward).toBe(1.3);
- });
-
- it('should end trajectory with verdict', async () => {
- const trajectoryId = await adapter.beginTrajectory({
- taskId: 'test-task-1',
- });
-
- const trajectory = await adapter.endTrajectory({
- trajectoryId,
- success: true,
- verdict: 'positive',
- reward: 1.0,
- });
-
- expect(trajectory.verdict).toBe('positive');
- expect(trajectory.endTime).toBeDefined();
- });
-
- it('should throw for non-existent trajectory', async () => {
- await expect(
- adapter.recordTrajectoryStep({
- trajectoryId: 'non-existent',
- action: 'test',
- observation: 'test',
- reward: 0,
- })
- ).rejects.toThrow('not found');
- });
-
- it('should emit trajectory events', async () => {
- const startHandler = vi.fn();
- const stepHandler = vi.fn();
- const completeHandler = vi.fn();
-
- adapter.on('trajectory-started', startHandler);
- adapter.on('trajectory-step-recorded', stepHandler);
- adapter.on('trajectory-completed', completeHandler);
-
- const trajectoryId = await adapter.beginTrajectory({
- taskId: 'test-task-1',
- });
-
- await adapter.recordTrajectoryStep({
- trajectoryId,
- action: 'Action',
- observation: 'Observation',
- reward: 0.5,
- });
-
- await adapter.endTrajectory({
- trajectoryId,
- success: true,
- });
-
- expect(startHandler).toHaveBeenCalled();
- expect(stepHandler).toHaveBeenCalled();
- expect(completeHandler).toHaveBeenCalled();
- });
-
- it('should update stats for active trajectories', async () => {
- const id1 = await adapter.beginTrajectory({ taskId: 'task-1' });
- const id2 = await adapter.beginTrajectory({ taskId: 'task-2' });
-
- const stats = await adapter.getStats();
- expect(stats.activeTrajectories).toBe(2);
-
- await adapter.endTrajectory({ trajectoryId: id1, success: true });
-
- const updatedStats = await adapter.getStats();
- expect(updatedStats.activeTrajectories).toBe(1);
- expect(updatedStats.completedTrajectories).toBe(1);
-
- await adapter.endTrajectory({ trajectoryId: id2, success: false });
- });
- });
-
- describe('pattern storage', () => {
- it('should store a pattern', async () => {
- const patternId = await adapter.storePattern({
- pattern: 'Test pattern',
- solution: 'Test solution',
- category: 'testing',
- confidence: 0.9,
- });
-
- expect(patternId).toMatch(/^pat_/);
- });
-
- it('should retrieve stored pattern', async () => {
- const patternId = await adapter.storePattern({
- pattern: 'Test pattern',
- solution: 'Test solution',
- category: 'testing',
- confidence: 0.9,
- });
-
- const pattern = await adapter.getPattern(patternId);
-
- expect(pattern).toBeDefined();
- expect(pattern!.pattern).toBe('Test pattern');
- expect(pattern!.solution).toBe('Test solution');
- expect(pattern!.confidence).toBe(0.9);
- });
-
- it('should return null for non-existent pattern', async () => {
- const pattern = await adapter.getPattern('non-existent');
- expect(pattern).toBeNull();
- });
-
- it('should delete pattern', async () => {
- const patternId = await adapter.storePattern({
- pattern: 'Test pattern',
- solution: 'Test solution',
- category: 'testing',
- confidence: 0.9,
- });
-
- const deleted = await adapter.deletePattern(patternId);
- expect(deleted).toBe(true);
-
- const pattern = await adapter.getPattern(patternId);
- expect(pattern).toBeNull();
- });
-
- it('should clamp confidence to valid range', async () => {
- const patternId = await adapter.storePattern({
- pattern: 'Test pattern',
- solution: 'Test solution',
- category: 'testing',
- confidence: 1.5, // Should be clamped to 1.0
- });
-
- const pattern = await adapter.getPattern(patternId);
- expect(pattern!.confidence).toBe(1.0);
- });
- });
-
- describe('pattern search', () => {
- beforeEach(async () => {
- // Store some test patterns
- await adapter.storePattern({
- pattern: 'authentication login user',
- solution: 'Use JWT tokens',
- category: 'security',
- confidence: 0.9,
- });
-
- await adapter.storePattern({
- pattern: 'authentication oauth provider',
- solution: 'Use OAuth 2.0',
- category: 'security',
- confidence: 0.85,
- });
-
- await adapter.storePattern({
- pattern: 'database query optimization',
- solution: 'Add indexes',
- category: 'performance',
- confidence: 0.95,
- });
- });
-
- it('should find similar patterns', async () => {
- const results = await adapter.findSimilarPatterns({
- query: 'authentication user login',
- topK: 5,
- });
-
- expect(results.length).toBeGreaterThan(0);
- });
-
- it('should filter by category', async () => {
- const results = await adapter.findSimilarPatterns({
- query: 'authentication',
- category: 'security',
- topK: 10,
- });
-
- for (const pattern of results) {
- expect(pattern.category).toBe('security');
- }
- });
-
- it('should respect topK limit', async () => {
- const results = await adapter.findSimilarPatterns({
- query: 'authentication',
- topK: 1,
- });
-
- expect(results.length).toBeLessThanOrEqual(1);
- });
-
- it('should update usage count on retrieval', async () => {
- const patternId = await adapter.storePattern({
- pattern: 'test usage tracking',
- solution: 'test solution',
- category: 'testing',
- confidence: 0.9,
- });
-
- // Search for the pattern
- await adapter.findSimilarPatterns({
- query: 'test usage tracking',
- topK: 5,
- });
-
- const pattern = await adapter.getPattern(patternId);
- expect(pattern!.usageCount).toBeGreaterThan(0);
- });
- });
-
- describe('learning cycle', () => {
- it('should force learning cycle', async () => {
- const handler = vi.fn();
- adapter.on('learning-cycle-completed', handler);
-
- await adapter.forceLearningCycle();
-
- expect(handler).toHaveBeenCalled();
- });
-
- it('should update stats after learning cycle', async () => {
- const statsBefore = await adapter.getStats();
-
- await adapter.forceLearningCycle();
-
- const statsAfter = await adapter.getStats();
- expect(statsAfter.learningCycles).toBe(statsBefore.learningCycles + 1);
- });
- });
-
- describe('pattern import/export', () => {
- it('should export patterns', async () => {
- await adapter.storePattern({
- pattern: 'Export test 1',
- solution: 'Solution 1',
- category: 'testing',
- confidence: 0.9,
- });
-
- await adapter.storePattern({
- pattern: 'Export test 2',
- solution: 'Solution 2',
- category: 'testing',
- confidence: 0.8,
- });
-
- const exported = await adapter.exportPatterns();
-
- expect(exported.length).toBeGreaterThanOrEqual(2);
- });
-
- it('should import patterns', async () => {
- const patterns = [
- {
- id: 'import-1',
- pattern: 'Import test 1',
- solution: 'Solution 1',
- category: 'testing',
- confidence: 0.9,
- usageCount: 5,
- createdAt: Date.now(),
- lastUsedAt: Date.now(),
- metadata: {},
- },
- {
- id: 'import-2',
- pattern: 'Import test 2',
- solution: 'Solution 2',
- category: 'testing',
- confidence: 0.8,
- usageCount: 3,
- createdAt: Date.now(),
- lastUsedAt: Date.now(),
- metadata: {},
- },
- ];
-
- const imported = await adapter.importPatterns(patterns);
- expect(imported).toBe(2);
-
- const pattern = await adapter.getPattern('import-1');
- expect(pattern).toBeDefined();
- });
-
- it('should not import duplicate patterns', async () => {
- const patterns = [
- {
- id: 'unique-id',
- pattern: 'Test',
- solution: 'Solution',
- category: 'testing',
- confidence: 0.9,
- usageCount: 0,
- createdAt: Date.now(),
- lastUsedAt: Date.now(),
- metadata: {},
- },
- ];
-
- const firstImport = await adapter.importPatterns(patterns);
- const secondImport = await adapter.importPatterns(patterns);
-
- expect(firstImport).toBe(1);
- expect(secondImport).toBe(0);
- });
- });
-
- describe('statistics', () => {
- it('should return learning statistics', async () => {
- const stats = await adapter.getStats();
-
- expect(stats).toHaveProperty('totalPatterns');
- expect(stats).toHaveProperty('activeTrajectories');
- expect(stats).toHaveProperty('completedTrajectories');
- expect(stats).toHaveProperty('averageConfidence');
- expect(stats).toHaveProperty('learningCycles');
- expect(stats).toHaveProperty('lastConsolidation');
- expect(stats).toHaveProperty('memoryUsage');
- expect(stats).toHaveProperty('currentMode');
- });
-
- it('should track average confidence', async () => {
- await adapter.storePattern({
- pattern: 'P1',
- solution: 'S1',
- category: 'test',
- confidence: 0.8,
- });
-
- await adapter.storePattern({
- pattern: 'P2',
- solution: 'S2',
- category: 'test',
- confidence: 0.6,
- });
-
- const stats = await adapter.getStats();
- expect(stats.averageConfidence).toBeCloseTo(0.7, 1);
- });
- });
-
- describe('factory function', () => {
- it('should create initialized adapter', async () => {
- const newAdapter = await createSONAAdapter({
- mode: 'research',
- });
-
- expect(newAdapter.getMode()).toBe('research');
-
- await newAdapter.shutdown();
- });
- });
-
- describe('shutdown', () => {
- it('should complete active trajectories on shutdown', async () => {
- const id = await adapter.beginTrajectory({ taskId: 'test' });
-
- await adapter.shutdown();
-
- // Adapter should be in a clean state
- const newAdapter = new SONAAdapter();
- await newAdapter.initialize();
-
- const stats = await newAdapter.getStats();
- expect(stats.activeTrajectories).toBe(0);
-
- await newAdapter.shutdown();
- });
- });
-});
diff --git a/v3/__tests__/integration/swarm-coordination.test.ts b/v3/__tests__/integration/swarm-coordination.test.ts
deleted file mode 100644
index d5082a8819..0000000000
--- a/v3/__tests__/integration/swarm-coordination.test.ts
+++ /dev/null
@@ -1,611 +0,0 @@
-/**
- * V3 Claude-Flow Swarm Coordination Integration Tests
- *
- * Integration tests for 15-agent swarm coordination
- * Tests end-to-end coordination workflows
- */
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { createMock, type MockedInterface } from '../helpers/create-mock';
-import { createSwarmTestInstance, type V3AgentType } from '../helpers/swarm-instance';
-import { swarmConfigs } from '../fixtures/configurations';
-import { create15AgentSwarmConfig } from '../fixtures/agents';
-
-/**
- * Swarm coordinator integration interface
- */
-interface ISwarmOrchestrator {
- initialize(config: SwarmOrchestratorConfig): Promise<void>;
- spawnAgents(configs: AgentConfig[]): Promise<SpawnResult[]>;
- executeWorkflow(workflow: Workflow): Promise<WorkflowResult>;
- getSwarmStatus(): SwarmStatus;
- shutdown(): Promise<void>;
-}
-
-/**
- * Agent spawner interface
- */
-interface IAgentSpawner {
- spawn(config: AgentConfig): Promise<Agent>;
- terminate(agentId: string): Promise<void>;
-}
-
-/**
- * Workflow engine interface
- */
-interface IWorkflowEngine {
- execute(workflow: Workflow, agents: Agent[]): Promise<WorkflowResult>;
- cancel(workflowId: string): Promise<void>;
-}
-
-/**
- * Metrics collector interface
- */
-interface IMetricsCollector {
- recordSpawn(agentId: string, duration: number): void;
- recordTaskCompletion(taskId: string, duration: number, success: boolean): void;
- getMetrics(): SwarmMetrics;
-}
-
-interface SwarmOrchestratorConfig {
- topology: 'hierarchical' | 'mesh' | 'adaptive' | 'hierarchical-mesh';
- maxAgents: number;
- heartbeatInterval: number;
-}
-
-interface AgentConfig {
- type: V3AgentType;
- name: string;
- capabilities: string[];
- priority: number;
-}
-
-interface SpawnResult {
- success: boolean;
- agent?: Agent;
- error?: string;
-}
-
-interface Agent {
- id: string;
- type: V3AgentType;
- name: string;
- status: 'idle' | 'busy' | 'terminated';
- capabilities: string[];
-}
-
-interface Workflow {
- id: string;
- name: string;
- tasks: WorkflowTask[];
- parallelism: number;
-}
-
-interface WorkflowTask {
- id: string;
- type: string;
- requiredCapabilities: string[];
- payload: unknown;
- dependsOn?: string[];
-}
-
-interface WorkflowResult {
- workflowId: string;
- success: boolean;
- taskResults: TaskResult[];
- totalDuration: number;
- agentsUsed: string[];
-}
-
-interface TaskResult {
- taskId: string;
- agentId: string;
- success: boolean;
- output?: unknown;
- duration: number;
-}
-
-interface SwarmStatus {
- totalAgents: number;
- idleAgents: number;
- busyAgents: number;
- terminatedAgents: number;
- activeWorkflows: number;
-}
-
-interface SwarmMetrics {
- totalSpawns: number;
- averageSpawnTime: number;
- totalTasksCompleted: number;
- averageTaskDuration: number;
- successRate: number;
-}
-
-/**
- * Swarm orchestrator implementation for integration testing
- */
-class SwarmOrchestrator implements ISwarmOrchestrator {
- private agents: Map<string, Agent> = new Map();
- private activeWorkflows = 0;
- private initialized = false;
- private config: SwarmOrchestratorConfig | null = null;
-
- constructor(
- private readonly spawner: IAgentSpawner,
- private readonly workflowEngine: IWorkflowEngine,
- private readonly metrics: IMetricsCollector
- ) {}
-
- async initialize(config: SwarmOrchestratorConfig): Promise<void> {
- this.config = config;
- this.initialized = true;
- }
-
- async spawnAgents(configs: AgentConfig[]): Promise<SpawnResult[]> {
- if (!this.initialized) {
- throw new Error('Orchestrator not initialized');
- }
-
- const results: SpawnResult[] = [];
-
- for (const config of configs) {
- if (this.agents.size >= this.config!.maxAgents) {
- results.push({
- success: false,
- error: 'Maximum agent limit reached',
- });
- continue;
- }
-
- const startTime = Date.now();
-
- try {
- const agent = await this.spawner.spawn(config);
- this.agents.set(agent.id, agent);
- this.metrics.recordSpawn(agent.id, Date.now() - startTime);
- results.push({ success: true, agent });
- } catch (error) {
- results.push({
- success: false,
- error: (error as Error).message,
- });
- }
- }
-
- return results;
- }
-
- async executeWorkflow(workflow: Workflow): Promise<WorkflowResult> {
- if (!this.initialized) {
- throw new Error('Orchestrator not initialized');
- }
-
- this.activeWorkflows++;
- const startTime = Date.now();
-
- try {
- const availableAgents = this.getAvailableAgents();
- const result = await this.workflowEngine.execute(workflow, availableAgents);
-
- for (const taskResult of result.taskResults) {
- this.metrics.recordTaskCompletion(
- taskResult.taskId,
- taskResult.duration,
- taskResult.success
- );
- }
-
- return result;
- } finally {
- this.activeWorkflows--;
- }
- }
-
- getSwarmStatus(): SwarmStatus {
- const agents = Array.from(this.agents.values());
-
- return {
- totalAgents: agents.length,
- idleAgents: agents.filter((a) => a.status === 'idle').length,
- busyAgents: agents.filter((a) => a.status === 'busy').length,
- terminatedAgents: agents.filter((a) => a.status === 'terminated').length,
- activeWorkflows: this.activeWorkflows,
- };
- }
-
- async shutdown(): Promise<void> {
- for (const [agentId] of this.agents) {
- await this.spawner.terminate(agentId);
- }
- this.agents.clear();
- this.initialized = false;
- }
-
- private getAvailableAgents(): Agent[] {
- return Array.from(this.agents.values()).filter((a) => a.status === 'idle');
- }
-}
-
-describe('Swarm Coordination Integration', () => {
- let mockSpawner: MockedInterface<IAgentSpawner>;
- let mockWorkflowEngine: MockedInterface<IWorkflowEngine>;
- let mockMetrics: MockedInterface<IMetricsCollector>;
- let orchestrator: SwarmOrchestrator;
- let agentCounter: number;
-
- beforeEach(() => {
- mockSpawner = createMock<IAgentSpawner>();
- mockWorkflowEngine = createMock<IWorkflowEngine>();
- mockMetrics = createMock<IMetricsCollector>();
- agentCounter = 0;
-
- mockSpawner.spawn.mockImplementation(async (config: AgentConfig) => ({
- id: `agent-${++agentCounter}`,
- type: config.type,
- name: config.name,
- status: 'idle' as const,
- capabilities: config.capabilities,
- }));
- mockSpawner.terminate.mockResolvedValue(undefined);
-
- mockWorkflowEngine.execute.mockImplementation(async (workflow, agents) => ({
- workflowId: workflow.id,
- success: true,
- taskResults: workflow.tasks.map((task, i) => ({
- taskId: task.id,
- agentId: agents[i % agents.length]?.id ?? 'unknown',
- success: true,
- duration: 100,
- })),
- totalDuration: workflow.tasks.length * 100,
- agentsUsed: agents.map((a) => a.id),
- }));
- mockWorkflowEngine.cancel.mockResolvedValue(undefined);
-
- mockMetrics.recordSpawn.mockReturnValue(undefined);
- mockMetrics.recordTaskCompletion.mockReturnValue(undefined);
- mockMetrics.getMetrics.mockReturnValue({
- totalSpawns: 0,
- averageSpawnTime: 0,
- totalTasksCompleted: 0,
- averageTaskDuration: 0,
- successRate: 0,
- });
-
- orchestrator = new SwarmOrchestrator(mockSpawner, mockWorkflowEngine, mockMetrics);
- });
-
- describe('15-Agent Swarm Initialization', () => {
- it('should spawn all 15 agents successfully', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- const agentConfigs = create15AgentSwarmConfig();
-
- // When
- const results = await orchestrator.spawnAgents(agentConfigs);
-
- // Then
- expect(results).toHaveLength(15);
- expect(results.every((r) => r.success)).toBe(true);
- });
-
- it('should reject agents beyond limit', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- const agentConfigs = create15AgentSwarmConfig();
- const extraConfig: AgentConfig = {
- type: 'coder',
- name: 'Extra Agent',
- capabilities: ['coding'],
- priority: 50,
- };
-
- // When
- await orchestrator.spawnAgents(agentConfigs);
- const extraResult = await orchestrator.spawnAgents([extraConfig]);
-
- // Then
- expect(extraResult[0].success).toBe(false);
- expect(extraResult[0].error).toContain('Maximum agent limit');
- });
-
- it('should report correct swarm status after initialization', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- const agentConfigs = create15AgentSwarmConfig();
- await orchestrator.spawnAgents(agentConfigs);
-
- // When
- const status = orchestrator.getSwarmStatus();
-
- // Then
- expect(status.totalAgents).toBe(15);
- expect(status.idleAgents).toBe(15);
- expect(status.busyAgents).toBe(0);
- });
-
- it('should record spawn metrics for each agent', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- const agentConfigs = create15AgentSwarmConfig().slice(0, 5);
-
- // When
- await orchestrator.spawnAgents(agentConfigs);
-
- // Then
- expect(mockMetrics.recordSpawn).toHaveBeenCalledTimes(5);
- });
- });
-
- describe('Workflow Execution', () => {
- beforeEach(async () => {
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- const agentConfigs = create15AgentSwarmConfig().slice(0, 5);
- await orchestrator.spawnAgents(agentConfigs);
- });
-
- it('should execute workflow with available agents', async () => {
- // Given
- const workflow: Workflow = {
- id: 'workflow-1',
- name: 'Security Scan',
- tasks: [
- { id: 'task-1', type: 'scan', requiredCapabilities: [], payload: {} },
- { id: 'task-2', type: 'analyze', requiredCapabilities: [], payload: {} },
- ],
- parallelism: 2,
- };
-
- // When
- const result = await orchestrator.executeWorkflow(workflow);
-
- // Then
- expect(result.success).toBe(true);
- expect(result.taskResults).toHaveLength(2);
- });
-
- it('should pass available agents to workflow engine', async () => {
- // Given
- const workflow: Workflow = {
- id: 'workflow-1',
- name: 'Test Workflow',
- tasks: [{ id: 'task-1', type: 'test', requiredCapabilities: [], payload: {} }],
- parallelism: 1,
- };
-
- // When
- await orchestrator.executeWorkflow(workflow);
-
- // Then
- expect(mockWorkflowEngine.execute).toHaveBeenCalledWith(
- workflow,
- expect.arrayContaining([
- expect.objectContaining({
- status: 'idle',
- }),
- ])
- );
- });
-
- it('should record task completion metrics', async () => {
- // Given
- const workflow: Workflow = {
- id: 'workflow-1',
- name: 'Test Workflow',
- tasks: [
- { id: 'task-1', type: 'test', requiredCapabilities: [], payload: {} },
- { id: 'task-2', type: 'test', requiredCapabilities: [], payload: {} },
- ],
- parallelism: 2,
- };
-
- // When
- await orchestrator.executeWorkflow(workflow);
-
- // Then
- expect(mockMetrics.recordTaskCompletion).toHaveBeenCalledTimes(2);
- });
-
- it('should return agents used in result', async () => {
- // Given
- const workflow: Workflow = {
- id: 'workflow-1',
- name: 'Test Workflow',
- tasks: [{ id: 'task-1', type: 'test', requiredCapabilities: [], payload: {} }],
- parallelism: 1,
- };
-
- // When
- const result = await orchestrator.executeWorkflow(workflow);
-
- // Then
- expect(result.agentsUsed.length).toBeGreaterThan(0);
- });
- });
-
- describe('Swarm Lifecycle', () => {
- it('should throw error if not initialized', async () => {
- // Given - not initialized
-
- // When/Then
- await expect(
- orchestrator.spawnAgents([{ type: 'coder', name: 'Test', capabilities: [], priority: 50 }])
- ).rejects.toThrow('Orchestrator not initialized');
- });
-
- it('should terminate all agents on shutdown', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'mesh',
- maxAgents: 10,
- heartbeatInterval: 1000,
- });
-
- await orchestrator.spawnAgents([
- { type: 'coder', name: 'Agent 1', capabilities: [], priority: 50 },
- { type: 'tester', name: 'Agent 2', capabilities: [], priority: 50 },
- ]);
-
- // When
- await orchestrator.shutdown();
-
- // Then
- expect(mockSpawner.terminate).toHaveBeenCalledTimes(2);
- });
-
- it('should clear swarm status after shutdown', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'mesh',
- maxAgents: 10,
- heartbeatInterval: 1000,
- });
-
- await orchestrator.spawnAgents([
- { type: 'coder', name: 'Agent 1', capabilities: [], priority: 50 },
- ]);
-
- // When
- await orchestrator.shutdown();
- const status = orchestrator.getSwarmStatus();
-
- // Then
- expect(status.totalAgents).toBe(0);
- });
- });
-
- describe('Hierarchical-Mesh Topology', () => {
- it('should support hierarchical-mesh with 15 agents', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- // Create agents with Queen coordinator at top
- const agents: AgentConfig[] = [
- { type: 'queen-coordinator', name: 'Queen', capabilities: ['orchestration'], priority: 100 },
- { type: 'security-architect', name: 'Security Arch', capabilities: ['security'], priority: 90 },
- { type: 'memory-specialist', name: 'Memory Spec', capabilities: ['memory'], priority: 80 },
- { type: 'coder', name: 'Coder 1', capabilities: ['coding'], priority: 70 },
- { type: 'tester', name: 'Tester 1', capabilities: ['testing'], priority: 70 },
- ];
-
- // When
- const results = await orchestrator.spawnAgents(agents);
-
- // Then
- expect(results.every((r) => r.success)).toBe(true);
-
- // Verify Queen is present
- expect(results[0].agent?.type).toBe('queen-coordinator');
- });
-
- it('should execute workflow through hierarchical coordination', async () => {
- // Given
- await orchestrator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- heartbeatInterval: 1000,
- });
-
- await orchestrator.spawnAgents([
- { type: 'queen-coordinator', name: 'Queen', capabilities: ['orchestration'], priority: 100 },
- { type: 'coder', name: 'Coder', capabilities: ['coding'], priority: 70 },
- { type: 'tester', name: 'Tester', capabilities: ['testing'], priority: 70 },
- ]);
-
- const workflow: Workflow = {
- id: 'hierarchical-workflow',
- name: 'Hierarchical Test',
- tasks: [
- { id: 'task-1', type: 'implement', requiredCapabilities: ['coding'], payload: {} },
- { id: 'task-2', type: 'test', requiredCapabilities: ['testing'], payload: {}, dependsOn: ['task-1'] },
- ],
- parallelism: 1,
- };
-
- // When
- const result = await orchestrator.executeWorkflow(workflow);
-
- // Then
- expect(result.success).toBe(true);
- expect(mockWorkflowEngine.execute).toHaveBeenCalledWith(
- workflow,
- expect.arrayContaining([
- expect.objectContaining({ type: 'queen-coordinator' }),
- ])
- );
- });
- });
-
- describe('Swarm Test Instance Helper', () => {
- it('should create swarm test instance with default topology', () => {
- // When
- const swarm = createSwarmTestInstance();
-
- // Then
- expect(swarm.topology).toBe('hierarchical-mesh');
- expect(swarm.getAllAgents().length).toBeGreaterThan(0);
- });
-
- it('should support custom agent types', () => {
- // When
- const swarm = createSwarmTestInstance({
- topology: 'mesh',
- agentTypes: ['coder', 'tester', 'reviewer'],
- });
-
- // Then
- expect(swarm.getAgent('coder')).toBeDefined();
- expect(swarm.getAgent('tester')).toBeDefined();
- expect(swarm.getAgent('reviewer')).toBeDefined();
- });
-
- it('should track agent interactions', async () => {
- // Given
- const swarm = createSwarmTestInstance({
- agentTypes: ['queen-coordinator', 'coder'],
- });
-
- await swarm.initialize();
-
- // When
- await swarm.coordinate({
- id: 'test-task',
- type: 'implementation',
- payload: {},
- priority: 50,
- });
-
- // Then
- const interactions = swarm.getInteractions();
- expect(interactions.length).toBeGreaterThan(0);
- });
- });
-});
diff --git a/v3/__tests__/neural/performance.test.ts b/v3/__tests__/neural/performance.test.ts
deleted file mode 100644
index 79089e4012..0000000000
--- a/v3/__tests__/neural/performance.test.ts
+++ /dev/null
@@ -1,498 +0,0 @@
-/**
- * Neural System Performance Tests
- *
- * Verifies performance targets:
- * - SONA adaptation: <0.05ms
- * - Pattern matching: <1ms
- * - Learning step: <10ms
- */
-
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import {
- SONAManager,
- createSONAManager,
- PatternLearner,
- createPatternLearner,
- ReasoningBank,
- createReasoningBank,
- createPPO,
- createDQN,
- createA2C,
- createQLearning,
- createSARSA,
-} from '../../neural/index.js';
-import type { Trajectory, Pattern } from '../../neural/types.js';
-
-// Helper to create test embeddings
-function createEmbedding(dim: number = 768): Float32Array {
- const embedding = new Float32Array(dim);
- for (let i = 0; i < dim; i++) {
- embedding[i] = (Math.random() - 0.5) * 2;
- }
- return embedding;
-}
-
-// Helper to create test trajectory
-function createTrajectory(numSteps: number = 5): Trajectory {
- const steps = [];
- for (let i = 0; i < numSteps; i++) {
- steps.push({
- stepId: `step_${i}`,
- timestamp: Date.now() + i * 100,
- action: `action_${i}`,
- stateBefore: createEmbedding(),
- stateAfter: createEmbedding(),
- reward: Math.random(),
- });
- }
-
- return {
- trajectoryId: `traj_${Date.now()}`,
- context: 'Test trajectory',
- domain: 'code',
- steps,
- qualityScore: 0.75,
- isComplete: true,
- startTime: Date.now(),
- endTime: Date.now() + numSteps * 100,
- };
-}
-
-// Helper to create test pattern
-function createPattern(): Pattern {
- return {
- patternId: `pat_${Date.now()}`,
- name: 'test_pattern',
- domain: 'code',
- embedding: createEmbedding(),
- strategy: 'Test strategy',
- successRate: 0.8,
- usageCount: 10,
- qualityHistory: [0.7, 0.8, 0.85],
- evolutionHistory: [],
- createdAt: Date.now(),
- updatedAt: Date.now(),
- };
-}
-
-describe('SONA Manager Performance', () => {
- let sona: SONAManager;
-
- beforeAll(async () => {
- sona = createSONAManager('real-time');
- await sona.initialize();
- });
-
- afterAll(async () => {
- await sona.cleanup();
- });
-
- it('should adapt in <0.05ms (real-time mode)', async () => {
- const weights = sona.initializeLoRAWeights('test');
- const input = createEmbedding();
-
- const times: number[] = [];
-
- // Warm up
- for (let i = 0; i < 10; i++) {
- await sona.applyAdaptations(input, 'test');
- }
-
- // Measure
- for (let i = 0; i < 100; i++) {
- const start = performance.now();
- await sona.applyAdaptations(input, 'test');
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- const p95 = times.sort((a, b) => a - b)[Math.floor(times.length * 0.95)];
-
- console.log(`SONA adaptation: avg=${avgTime.toFixed(3)}ms, p95=${p95.toFixed(3)}ms`);
-
- // Real-time mode target is 0.5ms (more lenient for JS)
- expect(avgTime).toBeLessThan(0.5);
- });
-
- it('should begin trajectory in <0.1ms', () => {
- const times: number[] = [];
-
- for (let i = 0; i < 100; i++) {
- const start = performance.now();
- const trajId = sona.beginTrajectory('Test context', 'code');
- times.push(performance.now() - start);
- sona.completeTrajectory(trajId, 0.5);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Trajectory begin: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(0.1);
- });
-
- it('should record step in <0.1ms', () => {
- const trajId = sona.beginTrajectory('Test', 'code');
- const times: number[] = [];
-
- for (let i = 0; i < 100; i++) {
- const start = performance.now();
- sona.recordStep(trajId, `action_${i}`, Math.random(), createEmbedding());
- times.push(performance.now() - start);
- }
-
- sona.completeTrajectory(trajId, 0.8);
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Step recording: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(0.1);
- });
-});
-
-describe('Pattern Learner Performance', () => {
- let patternLearner: PatternLearner;
-
- beforeAll(() => {
- patternLearner = createPatternLearner();
-
- // Populate with patterns
- for (let i = 0; i < 100; i++) {
- patternLearner.extractPattern(createTrajectory());
- }
- });
-
- it('should match patterns in <1ms', () => {
- const query = createEmbedding();
- const times: number[] = [];
-
- // Warm up
- for (let i = 0; i < 10; i++) {
- patternLearner.findMatches(query, 3);
- }
-
- // Measure
- for (let i = 0; i < 100; i++) {
- const start = performance.now();
- patternLearner.findMatches(query, 3);
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- const p95 = times.sort((a, b) => a - b)[Math.floor(times.length * 0.95)];
-
- console.log(`Pattern matching: avg=${avgTime.toFixed(3)}ms, p95=${p95.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(1);
- });
-
- it('should extract pattern in <5ms', () => {
- const times: number[] = [];
-
- for (let i = 0; i < 50; i++) {
- const trajectory = createTrajectory();
- const start = performance.now();
- patternLearner.extractPattern(trajectory);
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Pattern extraction: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(5);
- });
-
- it('should evolve pattern in <2ms', () => {
- const patterns = patternLearner.getPatterns();
- if (patterns.length === 0) return;
-
- const times: number[] = [];
-
- for (let i = 0; i < 100; i++) {
- const pattern = patterns[i % patterns.length];
- const start = performance.now();
- patternLearner.evolvePattern(pattern.patternId, Math.random());
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Pattern evolution: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(2);
- });
-});
-
-describe('ReasoningBank Performance', () => {
- let reasoningBank: ReasoningBank;
-
- beforeAll(async () => {
- reasoningBank = createReasoningBank();
-
- // Populate with trajectories
- for (let i = 0; i < 50; i++) {
- const trajectory = createTrajectory();
- reasoningBank.storeTrajectory(trajectory);
- await reasoningBank.judge(trajectory);
- await reasoningBank.distill(trajectory);
- }
- });
-
- it('should retrieve memories in <1ms', async () => {
- const query = createEmbedding();
- const times: number[] = [];
-
- // Warm up
- for (let i = 0; i < 10; i++) {
- await reasoningBank.retrieve(query, 3);
- }
-
- // Measure
- for (let i = 0; i < 100; i++) {
- const start = performance.now();
- await reasoningBank.retrieve(query, 3);
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Memory retrieval: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(1);
- });
-
- it('should judge trajectory in <5ms', async () => {
- const times: number[] = [];
-
- for (let i = 0; i < 50; i++) {
- const trajectory = createTrajectory();
- trajectory.isComplete = true;
-
- const start = performance.now();
- await reasoningBank.judge(trajectory);
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Trajectory judging: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(5);
- });
-
- it('should distill trajectory in <5ms', async () => {
- const times: number[] = [];
-
- for (let i = 0; i < 50; i++) {
- const trajectory = createTrajectory();
- trajectory.isComplete = true;
- await reasoningBank.judge(trajectory);
-
- const start = performance.now();
- await reasoningBank.distill(trajectory);
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Trajectory distillation: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(5);
- });
-});
-
-describe('RL Algorithm Performance', () => {
- const trajectory = createTrajectory(10);
-
- it('PPO update should complete in <10ms', () => {
- const ppo = createPPO();
- ppo.addExperience(trajectory);
- ppo.addExperience(trajectory);
- ppo.addExperience(trajectory);
-
- const times: number[] = [];
-
- for (let i = 0; i < 20; i++) {
- ppo.addExperience(createTrajectory());
- const start = performance.now();
- ppo.update();
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`PPO update: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(10);
- });
-
- it('DQN update should complete in <10ms', () => {
- const dqn = createDQN();
-
- // Fill buffer
- for (let i = 0; i < 10; i++) {
- dqn.addExperience(createTrajectory());
- }
-
- const times: number[] = [];
-
- for (let i = 0; i < 20; i++) {
- const start = performance.now();
- dqn.update();
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`DQN update: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(10);
- });
-
- it('A2C update should complete in <10ms', () => {
- const a2c = createA2C();
-
- // Fill buffer
- for (let i = 0; i < 5; i++) {
- a2c.addExperience(createTrajectory());
- }
-
- const times: number[] = [];
-
- for (let i = 0; i < 20; i++) {
- a2c.addExperience(createTrajectory());
- const start = performance.now();
- a2c.update();
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`A2C update: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(10);
- });
-
- it('Q-Learning update should complete in <1ms', () => {
- const qlearning = createQLearning();
- const times: number[] = [];
-
- for (let i = 0; i < 50; i++) {
- const start = performance.now();
- qlearning.update(createTrajectory());
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`Q-Learning update: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(1);
- });
-
- it('SARSA update should complete in <1ms', () => {
- const sarsa = createSARSA();
- const times: number[] = [];
-
- for (let i = 0; i < 50; i++) {
- const start = performance.now();
- sarsa.update(createTrajectory());
- times.push(performance.now() - start);
- }
-
- const avgTime = times.reduce((a, b) => a + b, 0) / times.length;
- console.log(`SARSA update: avg=${avgTime.toFixed(3)}ms`);
-
- expect(avgTime).toBeLessThan(1);
- });
-});
-
-describe('Mode-Specific Performance', () => {
- it('real-time mode should maintain <0.5ms latency', async () => {
- const sona = createSONAManager('real-time');
- await sona.initialize();
-
- const config = sona.getConfig();
- expect(config.config.maxLatencyMs).toBe(0.5);
-
- await sona.cleanup();
- });
-
- it('balanced mode should target 18ms latency', async () => {
- const sona = createSONAManager('balanced');
- await sona.initialize();
-
- const config = sona.getConfig();
- expect(config.config.maxLatencyMs).toBe(18);
-
- await sona.cleanup();
- });
-
- it('edge mode should use <5MB memory', async () => {
- const sona = createSONAManager('edge');
- await sona.initialize();
-
- const config = sona.getConfig();
- expect(config.config.memoryBudgetMb).toBe(5);
-
- await sona.cleanup();
- });
-
- it('research mode should target +55% quality', async () => {
- const sona = createSONAManager('research');
- await sona.initialize();
-
- const config = sona.getConfig();
- expect(config.config.loraRank).toBe(16); // High rank for quality
- expect(config.config.learningRate).toBe(0.002); // Sweet spot
-
- await sona.cleanup();
- });
-});
-
-describe('Throughput Tests', () => {
- it('should achieve >2000 ops/sec for pattern matching', () => {
- const patternLearner = createPatternLearner();
-
- // Populate
- for (let i = 0; i < 100; i++) {
- patternLearner.extractPattern(createTrajectory());
- }
-
- const query = createEmbedding();
- const duration = 1000; // 1 second
- let ops = 0;
-
- const start = performance.now();
- while (performance.now() - start < duration) {
- patternLearner.findMatches(query, 3);
- ops++;
- }
-
- const opsPerSec = ops / ((performance.now() - start) / 1000);
- console.log(`Pattern matching throughput: ${opsPerSec.toFixed(0)} ops/sec`);
-
- expect(opsPerSec).toBeGreaterThan(2000);
- });
-
- it('should handle 1000 concurrent trajectories', async () => {
- const sona = createSONAManager('batch');
- await sona.initialize();
-
- const trajectoryIds: string[] = [];
-
- // Start trajectories
- const startTime = performance.now();
- for (let i = 0; i < 1000; i++) {
- trajectoryIds.push(sona.beginTrajectory(`Task ${i}`, 'general'));
- }
-
- // Record steps
- for (const id of trajectoryIds) {
- sona.recordStep(id, 'action', Math.random(), createEmbedding());
- }
-
- // Complete trajectories
- for (const id of trajectoryIds) {
- sona.completeTrajectory(id, Math.random());
- }
-
- const elapsed = performance.now() - startTime;
- console.log(`1000 trajectories processed in ${elapsed.toFixed(0)}ms`);
-
- expect(elapsed).toBeLessThan(5000); // Should complete in 5 seconds
-
- await sona.cleanup();
- });
-});
diff --git a/v3/__tests__/security/credential-generator.test.ts b/v3/__tests__/security/credential-generator.test.ts
deleted file mode 100644
index 45cf860d7d..0000000000
--- a/v3/__tests__/security/credential-generator.test.ts
+++ /dev/null
@@ -1,310 +0,0 @@
-/**
- * Credential Generator Tests - CVE-3 Remediation Validation
- *
- * Tests verify:
- * - Cryptographically secure random generation
- * - No hardcoded defaults
- * - Proper entropy levels
- * - Unique credentials per generation
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
- CredentialGenerator,
- CredentialGeneratorError,
- createCredentialGenerator,
- generateCredentials,
-} from '../../security/credential-generator.js';
-
-describe('CredentialGenerator', () => {
- let generator: CredentialGenerator;
-
- beforeEach(() => {
- generator = new CredentialGenerator();
- });
-
- describe('Configuration', () => {
- it('should use default configuration', () => {
- expect(() => new CredentialGenerator()).not.toThrow();
- });
-
- it('should reject password length below 16', () => {
- expect(() => new CredentialGenerator({
- passwordLength: 8,
- })).toThrow(CredentialGeneratorError);
- });
-
- it('should reject API key length below 32', () => {
- expect(() => new CredentialGenerator({
- apiKeyLength: 16,
- })).toThrow(CredentialGeneratorError);
- });
-
- it('should reject secret length below 32', () => {
- expect(() => new CredentialGenerator({
- secretLength: 16,
- })).toThrow(CredentialGeneratorError);
- });
- });
-
- describe('Password Generation', () => {
- it('should generate password of specified length', () => {
- const password = generator.generatePassword();
- expect(password.length).toBeGreaterThanOrEqual(32);
- });
-
- it('should generate unique passwords', () => {
- const passwords = new Set<string>();
- for (let i = 0; i < 100; i++) {
- passwords.add(generator.generatePassword());
- }
- expect(passwords.size).toBe(100);
- });
-
- it('should include required character types', () => {
- for (let i = 0; i < 10; i++) {
- const password = generator.generatePassword();
- expect(password).toMatch(/[A-Z]/); // Uppercase
- expect(password).toMatch(/[a-z]/); // Lowercase
- expect(password).toMatch(/\d/); // Digit
- expect(password).toMatch(/[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/); // Special
- }
- });
- });
-
- describe('API Key Generation', () => {
- it('should generate API key with prefix', () => {
- const { key, prefix } = generator.generateApiKey('cf_');
- expect(key.startsWith('cf_')).toBe(true);
- expect(prefix).toBe('cf_');
- });
-
- it('should generate unique keys', () => {
- const keys = new Set<string>();
- for (let i = 0; i < 100; i++) {
- keys.add(generator.generateApiKey().key);
- }
- expect(keys.size).toBe(100);
- });
-
- it('should include keyId', () => {
- const { keyId } = generator.generateApiKey();
- // Should be a valid UUID
- expect(keyId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
- });
-
- it('should include createdAt timestamp', () => {
- const { createdAt } = generator.generateApiKey();
- expect(createdAt).toBeInstanceOf(Date);
- });
- });
-
- describe('Secret Generation', () => {
- it('should generate hex-encoded secret', () => {
- const secret = generator.generateSecret();
- expect(secret).toMatch(/^[0-9a-f]+$/);
- });
-
- it('should generate secret of specified length', () => {
- const secret = generator.generateSecret(64);
- expect(secret.length).toBe(64);
- });
-
- it('should generate unique secrets', () => {
- const secrets = new Set<string>();
- for (let i = 0; i < 100; i++) {
- secrets.add(generator.generateSecret());
- }
- expect(secrets.size).toBe(100);
- });
- });
-
- describe('Encryption Key Generation', () => {
- it('should generate 32-byte (256-bit) key as hex', () => {
- const key = generator.generateEncryptionKey();
- // 32 bytes = 64 hex characters
- expect(key.length).toBe(64);
- expect(key).toMatch(/^[0-9a-f]+$/);
- });
-
- it('should generate unique keys', () => {
- const keys = new Set<string>();
- for (let i = 0; i < 100; i++) {
- keys.add(generator.generateEncryptionKey());
- }
- expect(keys.size).toBe(100);
- });
- });
-
- describe('Installation Credentials', () => {
- it('should generate complete credential set', () => {
- const credentials = generator.generateInstallationCredentials();
-
- expect(credentials.adminPassword).toBeDefined();
- expect(credentials.servicePassword).toBeDefined();
- expect(credentials.jwtSecret).toBeDefined();
- expect(credentials.sessionSecret).toBeDefined();
- expect(credentials.encryptionKey).toBeDefined();
- expect(credentials.generatedAt).toBeInstanceOf(Date);
- });
-
- it('should set expiration when specified', () => {
- const credentials = generator.generateInstallationCredentials(30);
-
- expect(credentials.expiresAt).toBeInstanceOf(Date);
-
- // Should be approximately 30 days in the future
- const expectedExpiration = Date.now() + 30 * 24 * 60 * 60 * 1000;
- const actualExpiration = credentials.expiresAt!.getTime();
- expect(Math.abs(actualExpiration - expectedExpiration)).toBeLessThan(1000);
- });
-
- it('should generate unique credentials each time', () => {
- const cred1 = generator.generateInstallationCredentials();
- const cred2 = generator.generateInstallationCredentials();
-
- expect(cred1.adminPassword).not.toBe(cred2.adminPassword);
- expect(cred1.servicePassword).not.toBe(cred2.servicePassword);
- expect(cred1.jwtSecret).not.toBe(cred2.jwtSecret);
- });
- });
-
- describe('Token Generation', () => {
- it('should generate session token', () => {
- const token = generator.generateSessionToken();
- expect(token).toBeDefined();
- expect(token.length).toBeGreaterThan(0);
- });
-
- it('should generate CSRF token', () => {
- const token = generator.generateCsrfToken();
- expect(token).toBeDefined();
- // Base64url encoded
- expect(token).toMatch(/^[A-Za-z0-9_-]+$/);
- });
-
- it('should generate nonce', () => {
- const nonce = generator.generateNonce();
- expect(nonce).toBeDefined();
- // Hex encoded, 16 bytes = 32 chars
- expect(nonce.length).toBe(32);
- expect(nonce).toMatch(/^[0-9a-f]+$/);
- });
- });
-
- describe('Environment Script Generation', () => {
- it('should generate valid shell script', () => {
- const credentials = generator.generateInstallationCredentials();
- const script = generator.createEnvScript(credentials);
-
- expect(script).toContain('export CLAUDE_FLOW_ADMIN_PASSWORD=');
- expect(script).toContain('export CLAUDE_FLOW_SERVICE_PASSWORD=');
- expect(script).toContain('export CLAUDE_FLOW_JWT_SECRET=');
- expect(script).toContain('export CLAUDE_FLOW_SESSION_SECRET=');
- expect(script).toContain('export CLAUDE_FLOW_ENCRYPTION_KEY=');
- });
-
- it('should include warning comment', () => {
- const credentials = generator.generateInstallationCredentials();
- const script = generator.createEnvScript(credentials);
-
- expect(script).toContain('Store these securely');
- });
- });
-
- describe('JSON Config Generation', () => {
- it('should generate valid JSON', () => {
- const credentials = generator.generateInstallationCredentials();
- const json = generator.createJsonConfig(credentials);
-
- expect(() => JSON.parse(json)).not.toThrow();
- });
-
- it('should include all credentials', () => {
- const credentials = generator.generateInstallationCredentials();
- const json = generator.createJsonConfig(credentials);
- const parsed = JSON.parse(json);
-
- expect(parsed['claude-flow/admin-password']).toBe(credentials.adminPassword);
- expect(parsed['claude-flow/service-password']).toBe(credentials.servicePassword);
- expect(parsed['claude-flow/jwt-secret']).toBe(credentials.jwtSecret);
- expect(parsed['claude-flow/session-secret']).toBe(credentials.sessionSecret);
- expect(parsed['claude-flow/encryption-key']).toBe(credentials.encryptionKey);
- });
- });
-
- describe('Factory Functions', () => {
- it('should create generator with factory function', () => {
- const gen = createCredentialGenerator();
- expect(gen).toBeInstanceOf(CredentialGenerator);
- });
-
- it('should generate credentials with quick function', () => {
- const credentials = generateCredentials();
- expect(credentials.adminPassword).toBeDefined();
- expect(credentials.jwtSecret).toBeDefined();
- });
- });
-
- describe('CVE-3 Security Verification', () => {
- it('should NOT produce hardcoded admin123 password', () => {
- for (let i = 0; i < 100; i++) {
- const credentials = generator.generateInstallationCredentials();
- expect(credentials.adminPassword).not.toBe('admin123');
- expect(credentials.servicePassword).not.toBe('service123');
- }
- });
-
- it('should NOT produce predictable patterns', () => {
- const passwords = new Set<string>();
- for (let i = 0; i < 1000; i++) {
- passwords.add(generator.generatePassword());
- }
-
- // All should be unique
- expect(passwords.size).toBe(1000);
-
- // None should match common patterns
- const commonPatterns = ['password', 'admin', 'service', '123456', 'qwerty'];
- for (const password of passwords) {
- for (const pattern of commonPatterns) {
- expect(password.toLowerCase()).not.toContain(pattern);
- }
- }
- });
-
- it('should use cryptographically secure random', () => {
- // Generate many passwords and verify entropy
- const passwords: string[] = [];
- for (let i = 0; i < 100; i++) {
- passwords.push(generator.generatePassword());
- }
-
- // Calculate average character distribution
- const charCounts = new Map<string, number>();
- for (const password of passwords) {
- for (const char of password) {
- charCounts.set(char, (charCounts.get(char) || 0) + 1);
- }
- }
-
- // Should have good distribution (many different characters)
- expect(charCounts.size).toBeGreaterThan(30);
- });
-
- it('should generate installation credentials with sufficient entropy', () => {
- const credentials = generator.generateInstallationCredentials();
-
- // Password should be at least 256 bits of entropy at minimum
- expect(credentials.adminPassword.length).toBeGreaterThanOrEqual(32);
- expect(credentials.servicePassword.length).toBeGreaterThanOrEqual(32);
-
- // Secrets should be 512 bits
- expect(credentials.jwtSecret.length).toBeGreaterThanOrEqual(64);
- expect(credentials.sessionSecret.length).toBeGreaterThanOrEqual(64);
-
- // Encryption key should be exactly 256 bits (64 hex chars)
- expect(credentials.encryptionKey.length).toBe(64);
- });
- });
-});
diff --git a/v3/__tests__/security/input-validator.test.ts b/v3/__tests__/security/input-validator.test.ts
deleted file mode 100644
index b5836c74ab..0000000000
--- a/v3/__tests__/security/input-validator.test.ts
+++ /dev/null
@@ -1,381 +0,0 @@
-/**
- * Input Validator Tests
- *
- * Tests verify:
- * - Zod schema validation
- * - Input sanitization
- * - Authentication schemas
- * - Command and path schemas
- */
-
-import { describe, it, expect } from 'vitest';
-import {
- InputValidator,
- sanitizeString,
- sanitizeHtml,
- sanitizePath,
- SafeStringSchema,
- IdentifierSchema,
- EmailSchema,
- PasswordSchema,
- UUIDSchema,
- HttpsUrlSchema,
- PortSchema,
- UserRoleSchema,
- PermissionSchema,
- LoginRequestSchema,
- CreateUserSchema,
- TaskInputSchema,
- CommandArgumentSchema,
- PathSchema,
- PATTERNS,
- LIMITS,
-} from '../../security/input-validator.js';
-
-describe('InputValidator', () => {
- describe('SafeStringSchema', () => {
- it('should accept safe strings', () => {
- expect(() => SafeStringSchema.parse('hello world')).not.toThrow();
- });
-
- it('should reject empty strings', () => {
- expect(() => SafeStringSchema.parse('')).toThrow();
- });
-
- it('should reject strings with shell metacharacters', () => {
- const dangerous = [';', '&&', '||', '|', '`', '$()', '${}', '>', '<'];
- for (const char of dangerous) {
- expect(() => SafeStringSchema.parse(`hello${char}world`)).toThrow();
- }
- });
- });
-
- describe('IdentifierSchema', () => {
- it('should accept valid identifiers', () => {
- expect(() => IdentifierSchema.parse('validId')).not.toThrow();
- expect(() => IdentifierSchema.parse('valid-id')).not.toThrow();
- expect(() => IdentifierSchema.parse('valid_id')).not.toThrow();
- expect(() => IdentifierSchema.parse('validId123')).not.toThrow();
- });
-
- it('should reject identifiers starting with number', () => {
- expect(() => IdentifierSchema.parse('123invalid')).toThrow();
- });
-
- it('should reject identifiers with special characters', () => {
- expect(() => IdentifierSchema.parse('invalid@id')).toThrow();
- expect(() => IdentifierSchema.parse('invalid id')).toThrow();
- });
-
- it('should reject empty identifiers', () => {
- expect(() => IdentifierSchema.parse('')).toThrow();
- });
- });
-
- describe('EmailSchema', () => {
- it('should accept valid emails', () => {
- expect(() => EmailSchema.parse('[email protected]')).not.toThrow();
- expect(() => EmailSchema.parse('[email protected]')).not.toThrow();
- });
-
- it('should reject invalid emails', () => {
- expect(() => EmailSchema.parse('notanemail')).toThrow();
- expect(() => EmailSchema.parse('@nodomain.com')).toThrow();
- expect(() => EmailSchema.parse('no@')).toThrow();
- });
-
- it('should lowercase emails', () => {
- const result = EmailSchema.parse('[email protected]');
- expect(result).toBe('[email protected]');
- });
-
- it('should reject too long emails', () => {
- const longEmail = 'a'.repeat(300) + '@example.com';
- expect(() => EmailSchema.parse(longEmail)).toThrow();
- });
- });
-
- describe('PasswordSchema', () => {
- it('should accept valid passwords', () => {
- expect(() => PasswordSchema.parse('SecurePass123')).not.toThrow();
- });
-
- it('should reject short passwords', () => {
- expect(() => PasswordSchema.parse('Short1')).toThrow();
- });
-
- it('should reject passwords without uppercase', () => {
- expect(() => PasswordSchema.parse('lowercase123')).toThrow();
- });
-
- it('should reject passwords without lowercase', () => {
- expect(() => PasswordSchema.parse('UPPERCASE123')).toThrow();
- });
-
- it('should reject passwords without digits', () => {
- expect(() => PasswordSchema.parse('NoDigitsHere')).toThrow();
- });
- });
-
- describe('UUIDSchema', () => {
- it('should accept valid UUIDs', () => {
- expect(() => UUIDSchema.parse('550e8400-e29b-41d4-a716-446655440000')).not.toThrow();
- });
-
- it('should reject invalid UUIDs', () => {
- expect(() => UUIDSchema.parse('not-a-uuid')).toThrow();
- expect(() => UUIDSchema.parse('550e8400-e29b-41d4-a716')).toThrow();
- });
- });
-
- describe('HttpsUrlSchema', () => {
- it('should accept HTTPS URLs', () => {
- expect(() => HttpsUrlSchema.parse('https://example.com')).not.toThrow();
- expect(() => HttpsUrlSchema.parse('https://example.com/path')).not.toThrow();
- });
-
- it('should reject HTTP URLs', () => {
- expect(() => HttpsUrlSchema.parse('http://example.com')).toThrow();
- });
-
- it('should reject invalid URLs', () => {
- expect(() => HttpsUrlSchema.parse('not-a-url')).toThrow();
- });
- });
-
- describe('PortSchema', () => {
- it('should accept valid ports', () => {
- expect(() => PortSchema.parse(80)).not.toThrow();
- expect(() => PortSchema.parse(443)).not.toThrow();
- expect(() => PortSchema.parse(3000)).not.toThrow();
- expect(() => PortSchema.parse(65535)).not.toThrow();
- });
-
- it('should reject invalid ports', () => {
- expect(() => PortSchema.parse(0)).toThrow();
- expect(() => PortSchema.parse(-1)).toThrow();
- expect(() => PortSchema.parse(65536)).toThrow();
- expect(() => PortSchema.parse(3.14)).toThrow();
- });
- });
-
- describe('UserRoleSchema', () => {
- it('should accept valid roles', () => {
- expect(() => UserRoleSchema.parse('admin')).not.toThrow();
- expect(() => UserRoleSchema.parse('operator')).not.toThrow();
- expect(() => UserRoleSchema.parse('developer')).not.toThrow();
- expect(() => UserRoleSchema.parse('viewer')).not.toThrow();
- expect(() => UserRoleSchema.parse('service')).not.toThrow();
- });
-
- it('should reject invalid roles', () => {
- expect(() => UserRoleSchema.parse('superuser')).toThrow();
- expect(() => UserRoleSchema.parse('root')).toThrow();
- });
- });
-
- describe('PermissionSchema', () => {
- it('should accept valid permissions', () => {
- expect(() => PermissionSchema.parse('swarm.create')).not.toThrow();
- expect(() => PermissionSchema.parse('agent.spawn')).not.toThrow();
- expect(() => PermissionSchema.parse('system.admin')).not.toThrow();
- });
-
- it('should reject invalid permissions', () => {
- expect(() => PermissionSchema.parse('invalid.permission')).toThrow();
- });
- });
-
- describe('LoginRequestSchema', () => {
- it('should accept valid login request', () => {
- expect(() => LoginRequestSchema.parse({
- email: '[email protected]',
- password: 'password123',
- })).not.toThrow();
- });
-
- it('should accept login with MFA code', () => {
- expect(() => LoginRequestSchema.parse({
- email: '[email protected]',
- password: 'password123',
- mfaCode: '123456',
- })).not.toThrow();
- });
-
- it('should reject invalid MFA code length', () => {
- expect(() => LoginRequestSchema.parse({
- email: '[email protected]',
- password: 'password123',
- mfaCode: '12345', // 5 digits instead of 6
- })).toThrow();
- });
- });
-
- describe('CreateUserSchema', () => {
- it('should accept valid user creation', () => {
- expect(() => CreateUserSchema.parse({
- email: '[email protected]',
- password: 'SecurePass123',
- role: 'developer',
- })).not.toThrow();
- });
-
- it('should require strong password', () => {
- expect(() => CreateUserSchema.parse({
- email: '[email protected]',
- password: 'weak',
- role: 'developer',
- })).toThrow();
- });
- });
-
- describe('TaskInputSchema', () => {
- it('should accept valid task input', () => {
- expect(() => TaskInputSchema.parse({
- taskId: '550e8400-e29b-41d4-a716-446655440000',
- content: 'Implement new feature',
- agentType: 'coder',
- })).not.toThrow();
- });
-
- it('should reject task with shell characters in content', () => {
- expect(() => TaskInputSchema.parse({
- taskId: '550e8400-e29b-41d4-a716-446655440000',
- content: 'Implement feature; rm -rf /',
- agentType: 'coder',
- })).toThrow();
- });
- });
-
- describe('CommandArgumentSchema', () => {
- it('should accept safe arguments', () => {
- expect(() => CommandArgumentSchema.parse('--flag')).not.toThrow();
- expect(() => CommandArgumentSchema.parse('value')).not.toThrow();
- expect(() => CommandArgumentSchema.parse('path/to/file')).not.toThrow();
- });
-
- it('should reject arguments with null bytes', () => {
- expect(() => CommandArgumentSchema.parse('arg\x00injected')).toThrow();
- });
-
- it('should reject arguments with shell metacharacters', () => {
- expect(() => CommandArgumentSchema.parse('arg;injected')).toThrow();
- expect(() => CommandArgumentSchema.parse('arg&&injected')).toThrow();
- expect(() => CommandArgumentSchema.parse('arg|injected')).toThrow();
- });
- });
-
- describe('PathSchema', () => {
- it('should accept valid paths', () => {
- expect(() => PathSchema.parse('/path/to/file.ts')).not.toThrow();
- expect(() => PathSchema.parse('./relative/path')).not.toThrow();
- });
-
- it('should reject paths with traversal', () => {
- expect(() => PathSchema.parse('/path/../etc/passwd')).toThrow();
- });
-
- it('should reject paths with null bytes', () => {
- expect(() => PathSchema.parse('/path/file\x00.jpg')).toThrow();
- });
- });
-
- describe('Sanitization Functions', () => {
- describe('sanitizeString', () => {
- it('should remove null bytes', () => {
- expect(sanitizeString('hello\x00world')).toBe('helloworld');
- });
-
- it('should remove HTML brackets', () => {
- expect(sanitizeString('<script>alert(1)</script>')).toBe('scriptalert(1)/script');
- });
-
- it('should remove javascript: protocol', () => {
- expect(sanitizeString('javascript:alert(1)')).toBe('alert(1)');
- });
-
- it('should trim whitespace', () => {
- expect(sanitizeString(' hello ')).toBe('hello');
- });
- });
-
- describe('sanitizeHtml', () => {
- it('should escape HTML entities', () => {
- expect(sanitizeHtml('<script>')).toBe('&lt;script&gt;');
- expect(sanitizeHtml('"quoted"')).toBe('&quot;quoted&quot;');
- expect(sanitizeHtml("'apostrophe'")).toBe('&#x27;apostrophe&#x27;');
- expect(sanitizeHtml('a & b')).toBe('a &amp; b');
- });
- });
-
- describe('sanitizePath', () => {
- it('should remove null bytes', () => {
- expect(sanitizePath('/path\x00/file')).toBe('path/file');
- });
-
- it('should remove traversal patterns', () => {
- expect(sanitizePath('../etc/passwd')).toBe('/etc/passwd');
- });
-
- it('should normalize slashes', () => {
- expect(sanitizePath('/path//to///file')).toBe('path/to/file');
- });
-
- it('should remove leading slash', () => {
- expect(sanitizePath('/absolute/path')).toBe('absolute/path');
- });
- });
- });
-
- describe('InputValidator Class', () => {
- it('should validate email', () => {
- expect(InputValidator.validateEmail('[email protected]')).toBe('[email protected]');
- });
-
- it('should validate password', () => {
- expect(() => InputValidator.validatePassword('SecurePass123')).not.toThrow();
- });
-
- it('should validate identifier', () => {
- expect(InputValidator.validateIdentifier('myId')).toBe('myId');
- });
-
- it('should validate path', () => {
- expect(InputValidator.validatePath('/valid/path')).toBe('/valid/path');
- });
-
- it('should validate command argument', () => {
- expect(InputValidator.validateCommandArg('--flag')).toBe('--flag');
- });
-
- it('should validate login request', () => {
- const result = InputValidator.validateLoginRequest({
- email: '[email protected]',
- password: 'password',
- });
- expect(result.email).toBe('[email protected]');
- });
-
- it('should safely parse with result', () => {
- const success = InputValidator.safeParse(EmailSchema, '[email protected]');
- expect(success.success).toBe(true);
-
- const failure = InputValidator.safeParse(EmailSchema, 'invalid');
- expect(failure.success).toBe(false);
- });
- });
-
- describe('Constants', () => {
- it('should export PATTERNS', () => {
- expect(PATTERNS.SAFE_IDENTIFIER).toBeDefined();
- expect(PATTERNS.SAFE_FILENAME).toBeDefined();
- expect(PATTERNS.NO_SHELL_CHARS).toBeDefined();
- });
-
- it('should export LIMITS', () => {
- expect(LIMITS.MIN_PASSWORD_LENGTH).toBe(8);
- expect(LIMITS.MAX_PASSWORD_LENGTH).toBe(128);
- expect(LIMITS.MAX_PATH_LENGTH).toBe(4096);
- });
- });
-});
diff --git a/v3/__tests__/security/password-hasher.test.ts b/v3/__tests__/security/password-hasher.test.ts
deleted file mode 100644
index ef87a844dd..0000000000
--- a/v3/__tests__/security/password-hasher.test.ts
+++ /dev/null
@@ -1,239 +0,0 @@
-/**
- * Password Hasher Tests - CVE-2 Remediation Validation
- *
- * Tests verify:
- * - bcrypt is used instead of SHA-256
- * - 12 rounds minimum
- * - Password validation rules
- * - Timing-safe comparison
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
- PasswordHasher,
- PasswordHashError,
- createPasswordHasher,
-} from '../../security/password-hasher.js';
-
-describe('PasswordHasher', () => {
- let hasher: PasswordHasher;
-
- beforeEach(() => {
- hasher = new PasswordHasher({ rounds: 12 });
- });
-
- describe('Configuration', () => {
- it('should create hasher with default 12 rounds', () => {
- const defaultHasher = new PasswordHasher();
- expect(defaultHasher.getConfig().rounds).toBe(12);
- });
-
- it('should reject rounds below 10', () => {
- expect(() => new PasswordHasher({ rounds: 8 })).toThrow(PasswordHashError);
- });
-
- it('should reject rounds above 20', () => {
- expect(() => new PasswordHasher({ rounds: 22 })).toThrow(PasswordHashError);
- });
-
- it('should reject minimum password length below 8', () => {
- expect(() => new PasswordHasher({ minLength: 4 })).toThrow(PasswordHashError);
- });
- });
-
- describe('Password Validation', () => {
- it('should reject empty password', () => {
- const result = hasher.validate('');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Password is required');
- });
-
- it('should reject password shorter than minimum', () => {
- const result = hasher.validate('short');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('at least'))).toBe(true);
- });
-
- it('should reject password without uppercase', () => {
- const result = hasher.validate('password123');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('uppercase'))).toBe(true);
- });
-
- it('should reject password without lowercase', () => {
- const result = hasher.validate('PASSWORD123');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('lowercase'))).toBe(true);
- });
-
- it('should reject password without digit', () => {
- const result = hasher.validate('PasswordNoDigit');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('digit'))).toBe(true);
- });
-
- it('should accept valid password', () => {
- const result = hasher.validate('SecurePass123');
- expect(result.isValid).toBe(true);
- expect(result.errors).toHaveLength(0);
- });
-
- it('should optionally require special character', () => {
- const strictHasher = new PasswordHasher({ requireSpecial: true });
- const result = strictHasher.validate('SecurePass123');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('special'))).toBe(true);
- });
-
- it('should accept password with special character when required', () => {
- const strictHasher = new PasswordHasher({ requireSpecial: true });
- const result = strictHasher.validate('SecurePass123!');
- expect(result.isValid).toBe(true);
- });
- });
-
- describe('Password Hashing', () => {
- it('should hash password with bcrypt', async () => {
- const hash = await hasher.hash('SecurePass123');
-
- // bcrypt hashes start with $2a$, $2b$, or $2y$
- expect(hash).toMatch(/^\$2[aby]\$\d{2}\$/);
- });
-
- it('should produce different hashes for same password', async () => {
- const hash1 = await hasher.hash('SecurePass123');
- const hash2 = await hasher.hash('SecurePass123');
-
- expect(hash1).not.toBe(hash2); // Different salts
- });
-
- it('should include rounds in hash', async () => {
- const hash = await hasher.hash('SecurePass123');
-
- // Hash format: $2b$12$...
- expect(hash).toContain('$12$');
- });
-
- it('should throw for invalid password', async () => {
- await expect(hasher.hash('short')).rejects.toThrow(PasswordHashError);
- });
-
- it('should throw for empty password', async () => {
- await expect(hasher.hash('')).rejects.toThrow(PasswordHashError);
- });
- });
-
- describe('Password Verification', () => {
- it('should verify correct password', async () => {
- const password = 'SecurePass123';
- const hash = await hasher.hash(password);
-
- const isValid = await hasher.verify(password, hash);
- expect(isValid).toBe(true);
- });
-
- it('should reject incorrect password', async () => {
- const hash = await hasher.hash('SecurePass123');
-
- const isValid = await hasher.verify('WrongPass123', hash);
- expect(isValid).toBe(false);
- });
-
- it('should return false for empty password', async () => {
- const hash = await hasher.hash('SecurePass123');
-
- const isValid = await hasher.verify('', hash);
- expect(isValid).toBe(false);
- });
-
- it('should return false for empty hash', async () => {
- const isValid = await hasher.verify('SecurePass123', '');
- expect(isValid).toBe(false);
- });
-
- it('should return false for invalid hash format', async () => {
- const isValid = await hasher.verify('SecurePass123', 'invalid-hash');
- expect(isValid).toBe(false);
- });
-
- it('should return false for SHA-256 hash (old format)', async () => {
- // SHA-256 hash format (what we're replacing)
- const sha256Hash = 'a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3';
-
- const isValid = await hasher.verify('password', sha256Hash);
- expect(isValid).toBe(false);
- });
- });
-
- describe('Rehash Detection', () => {
- it('should not need rehash for current rounds', async () => {
- const hash = await hasher.hash('SecurePass123');
- expect(hasher.needsRehash(hash)).toBe(false);
- });
-
- it('should need rehash for lower rounds', () => {
- // Hash with 10 rounds
- const lowRoundsHash = '$2b$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy';
- expect(hasher.needsRehash(lowRoundsHash)).toBe(true);
- });
-
- it('should need rehash for invalid format', () => {
- expect(hasher.needsRehash('invalid-hash')).toBe(true);
- });
-
- it('should need rehash for SHA-256 hash', () => {
- const sha256Hash = 'a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3';
- expect(hasher.needsRehash(sha256Hash)).toBe(true);
- });
- });
-
- describe('Factory Function', () => {
- it('should create hasher with specified rounds', () => {
- const hasher12 = createPasswordHasher(12);
- expect(hasher12.getConfig().rounds).toBe(12);
-
- const hasher14 = createPasswordHasher(14);
- expect(hasher14.getConfig().rounds).toBe(14);
- });
-
- it('should use default 12 rounds', () => {
- const hasher = createPasswordHasher();
- expect(hasher.getConfig().rounds).toBe(12);
- });
- });
-
- describe('CVE-2 Security Verification', () => {
- it('should NOT use hardcoded salt', async () => {
- // Generate multiple hashes and verify they have different salts
- const hashes = await Promise.all([
- hasher.hash('SecurePass123'),
- hasher.hash('SecurePass123'),
- hasher.hash('SecurePass123'),
- ]);
-
- // Extract salts (22 chars after $2b$12$)
- const salts = hashes.map(h => h.substring(7, 29));
-
- // All salts should be unique
- const uniqueSalts = new Set(salts);
- expect(uniqueSalts.size).toBe(3);
- });
-
- it('should NOT produce same hash for same input (unlike SHA-256)', async () => {
- // SHA-256 with hardcoded salt would produce identical output
- const hash1 = await hasher.hash('SecurePass123');
- const hash2 = await hasher.hash('SecurePass123');
-
- expect(hash1).not.toBe(hash2);
- });
-
- it('should produce hash that takes time to compute', async () => {
- const start = Date.now();
- await hasher.hash('SecurePass123');
- const duration = Date.now() - start;
-
- // bcrypt with 12 rounds should take measurable time (>10ms typically)
- expect(duration).toBeGreaterThan(5);
- });
- });
-});
diff --git a/v3/__tests__/security/path-validator.test.ts b/v3/__tests__/security/path-validator.test.ts
deleted file mode 100644
index 4bcbf36489..0000000000
--- a/v3/__tests__/security/path-validator.test.ts
+++ /dev/null
@@ -1,302 +0,0 @@
-/**
- * Path Validator Tests - HIGH-2 Remediation Validation
- *
- * Tests verify:
- * - Path traversal prevention
- * - Prefix validation
- * - Symlink handling
- * - Blocked file detection
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import * as path from 'path';
-import {
- PathValidator,
- PathValidatorError,
- createProjectPathValidator,
- createFullProjectPathValidator,
-} from '../../security/path-validator.js';
-
-describe('PathValidator', () => {
- let validator: PathValidator;
- const projectRoot = '/workspaces/project';
-
- beforeEach(() => {
- validator = new PathValidator({
- allowedPrefixes: [projectRoot],
- allowHidden: false,
- });
- });
-
- describe('Configuration', () => {
- it('should require at least one prefix', () => {
- expect(() => new PathValidator({
- allowedPrefixes: [],
- })).toThrow(PathValidatorError);
- });
-
- it('should resolve prefixes to absolute paths', () => {
- const relativeValidator = new PathValidator({
- allowedPrefixes: ['./src'],
- });
-
- const prefixes = relativeValidator.getAllowedPrefixes();
- expect(prefixes[0]).toMatch(/^\//);
- });
- });
-
- describe('Path Traversal Prevention', () => {
- it('should block ../ traversal', async () => {
- const result = await validator.validate('/workspaces/project/../etc/passwd');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Path traversal pattern detected');
- });
-
- it('should block ..\\ traversal (Windows)', async () => {
- const result = await validator.validate('/workspaces/project\\..\\..\\etc\\passwd');
- expect(result.isValid).toBe(false);
- });
-
- it('should block URL-encoded traversal (%2e%2e)', async () => {
- const result = await validator.validate('/workspaces/project/%2e%2e/etc/passwd');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Path traversal pattern detected');
- });
-
- it('should block double URL-encoded traversal', async () => {
- const result = await validator.validate('/workspaces/project/%252e%252e/etc/passwd');
- expect(result.isValid).toBe(false);
- });
-
- it('should block mixed encoding traversal', async () => {
- const result = await validator.validate('/workspaces/project/.%2e/etc/passwd');
- expect(result.isValid).toBe(false);
- });
-
- it('should block null byte injection', async () => {
- const result = await validator.validate('/workspaces/project/file.txt\x00.jpg');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Path traversal pattern detected');
- });
-
- it('should block URL-encoded null byte', async () => {
- const result = await validator.validate('/workspaces/project/file.txt%00.jpg');
- expect(result.isValid).toBe(false);
- });
- });
-
- describe('Prefix Validation', () => {
- it('should allow paths within prefix', async () => {
- const result = await validator.validate('/workspaces/project/src/file.ts');
- expect(result.isValid).toBe(true);
- expect(result.matchedPrefix).toBe(projectRoot);
- });
-
- it('should block paths outside prefix', async () => {
- const result = await validator.validate('/etc/passwd');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Path is outside allowed directories');
- });
-
- it('should block paths that start with prefix but escape', async () => {
- const result = await validator.validate('/workspaces/project-other/file.ts');
- expect(result.isValid).toBe(false);
- });
-
- it('should handle exact prefix match', async () => {
- const result = await validator.validate(projectRoot);
- expect(result.isValid).toBe(true);
- });
-
- it('should calculate relative path correctly', async () => {
- const result = await validator.validate('/workspaces/project/src/deep/file.ts');
- expect(result.relativePath).toBe('src/deep/file.ts');
- });
- });
-
- describe('Hidden File Handling', () => {
- it('should block hidden files by default', async () => {
- const result = await validator.validate('/workspaces/project/.env');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('Hidden'))).toBe(true);
- });
-
- it('should block hidden directories by default', async () => {
- const result = await validator.validate('/workspaces/project/.git/config');
- expect(result.isValid).toBe(false);
- });
-
- it('should allow hidden files when configured', async () => {
- const hiddenValidator = new PathValidator({
- allowedPrefixes: [projectRoot],
- allowHidden: true,
- blockedNames: [], // Remove .git from blocked names for this test
- blockedExtensions: [],
- });
-
- const result = await hiddenValidator.validate('/workspaces/project/.gitignore');
- expect(result.isValid).toBe(true);
- });
- });
-
- describe('Blocked Files', () => {
- it('should block .env files', async () => {
- const hiddenValidator = new PathValidator({
- allowedPrefixes: [projectRoot],
- allowHidden: true,
- });
-
- const result = await hiddenValidator.validate('/workspaces/project/config/.env');
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('.env'))).toBe(true);
- });
-
- it('should block .pem files', async () => {
- const result = await validator.validate('/workspaces/project/certs/key.pem');
- expect(result.isValid).toBe(false);
- });
-
- it('should block private key files', async () => {
- const hiddenValidator = new PathValidator({
- allowedPrefixes: [projectRoot],
- allowHidden: true,
- });
-
- const result = await hiddenValidator.validate('/workspaces/project/.ssh/id_rsa');
- expect(result.isValid).toBe(false);
- });
-
- it('should block .htpasswd files', async () => {
- const hiddenValidator = new PathValidator({
- allowedPrefixes: [projectRoot],
- allowHidden: true,
- });
-
- const result = await hiddenValidator.validate('/workspaces/project/.htpasswd');
- expect(result.isValid).toBe(false);
- });
- });
-
- describe('Path Length', () => {
- it('should block paths exceeding max length', async () => {
- const longPath = '/workspaces/project/' + 'a'.repeat(5000);
- const result = await validator.validate(longPath);
- expect(result.isValid).toBe(false);
- expect(result.errors.some(e => e.includes('maximum length'))).toBe(true);
- });
-
- it('should allow paths within max length', async () => {
- const result = await validator.validate('/workspaces/project/src/file.ts');
- expect(result.isValid).toBe(true);
- });
- });
-
- describe('Empty Path', () => {
- it('should reject empty path', async () => {
- const result = await validator.validate('');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Path is empty');
- });
-
- it('should reject whitespace-only path', async () => {
- const result = await validator.validate(' ');
- expect(result.isValid).toBe(false);
- expect(result.errors).toContain('Path is empty');
- });
- });
-
- describe('Synchronous Validation', () => {
- it('should validate synchronously', () => {
- const result = validator.validateSync('/workspaces/project/src/file.ts');
- expect(result.isValid).toBe(true);
- });
-
- it('should detect traversal synchronously', () => {
- const result = validator.validateSync('/workspaces/project/../etc/passwd');
- expect(result.isValid).toBe(false);
- });
- });
-
- describe('validateOrThrow', () => {
- it('should return path when valid', async () => {
- const resolved = await validator.validateOrThrow('/workspaces/project/src/file.ts');
- expect(resolved).toBe('/workspaces/project/src/file.ts');
- });
-
- it('should throw when invalid', async () => {
- await expect(
- validator.validateOrThrow('/etc/passwd')
- ).rejects.toThrow(PathValidatorError);
- });
- });
-
- describe('securePath', () => {
- it('should join paths securely', async () => {
- const resolved = await validator.securePath(projectRoot, 'src', 'file.ts');
- expect(resolved).toBe('/workspaces/project/src/file.ts');
- });
-
- it('should block traversal in segments', async () => {
- await expect(
- validator.securePath(projectRoot, '..', 'etc', 'passwd')
- ).rejects.toThrow(PathValidatorError);
- });
- });
-
- describe('isWithinAllowed', () => {
- it('should return true for allowed paths', () => {
- expect(validator.isWithinAllowed('/workspaces/project/src')).toBe(true);
- });
-
- it('should return false for disallowed paths', () => {
- expect(validator.isWithinAllowed('/etc/passwd')).toBe(false);
- });
- });
-
- describe('Factory Functions', () => {
- it('should create project path validator', () => {
- const projectValidator = createProjectPathValidator('/workspaces/project');
- const prefixes = projectValidator.getAllowedPrefixes();
-
- expect(prefixes).toContain('/workspaces/project/src');
- expect(prefixes).toContain('/workspaces/project/tests');
- expect(prefixes).toContain('/workspaces/project/docs');
- });
-
- it('should create full project path validator', () => {
- const fullValidator = createFullProjectPathValidator('/workspaces/project');
- const prefixes = fullValidator.getAllowedPrefixes();
-
- expect(prefixes).toContain('/workspaces/project');
- });
- });
-
- describe('HIGH-2 Security Verification', () => {
- it('should prevent access to system files via traversal', async () => {
- const attacks = [
- '../../../etc/passwd',
- '..\\..\\..\\windows\\system32\\config\\sam',
- '....//....//....//etc/passwd',
- '..%252f..%252f..%252fetc/passwd',
- '..%c0%af..%c0%af..%c0%afetc/passwd',
- ];
-
- for (const attack of attacks) {
- const result = await validator.validate(`/workspaces/project/${attack}`);
- expect(result.isValid).toBe(false);
- }
- });
-
- it('should resolve symlink-like path attempts', async () => {
- // Even if the path looks like it's within bounds, resolution should catch escapes
- const result = await validator.validate('/workspaces/project/symlink/../../../etc/passwd');
- expect(result.isValid).toBe(false);
- });
-
- it('should not allow prefix manipulation', async () => {
- // Path starts with project root but escapes via traversal
- const result = await validator.validate('/workspaces/project/../../etc/passwd');
- expect(result.isValid).toBe(false);
- });
- });
-});
diff --git a/v3/__tests__/security/safe-executor.test.ts b/v3/__tests__/security/safe-executor.test.ts
deleted file mode 100644
index 6d06026ac5..0000000000
--- a/v3/__tests__/security/safe-executor.test.ts
+++ /dev/null
@@ -1,292 +0,0 @@
-/**
- * Safe Executor Tests - HIGH-1 Remediation Validation
- *
- * Tests verify:
- * - Commands execute without shell
- * - Command allowlist enforcement
- * - Argument sanitization
- * - Dangerous pattern detection
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
- SafeExecutor,
- SafeExecutorError,
- createDevelopmentExecutor,
- createReadOnlyExecutor,
-} from '../../security/safe-executor.js';
-
-describe('SafeExecutor', () => {
- let executor: SafeExecutor;
-
- beforeEach(() => {
- executor = new SafeExecutor({
- allowedCommands: ['echo', 'ls', 'git', 'npm', 'node'],
- timeout: 5000,
- });
- });
-
- describe('Configuration', () => {
- it('should require at least one allowed command', () => {
- expect(() => new SafeExecutor({
- allowedCommands: [],
- })).toThrow(SafeExecutorError);
- });
-
- it('should reject dangerous commands in allowlist', () => {
- expect(() => new SafeExecutor({
- allowedCommands: ['rm'],
- })).toThrow(SafeExecutorError);
- });
-
- it('should reject multiple dangerous commands', () => {
- expect(() => new SafeExecutor({
- allowedCommands: ['chmod', 'chown', 'rm'],
- })).toThrow(SafeExecutorError);
- });
-
- it('should allow safe commands', () => {
- expect(() => new SafeExecutor({
- allowedCommands: ['git', 'npm', 'node'],
- })).not.toThrow();
- });
- });
-
- describe('Command Validation', () => {
- it('should allow commands in allowlist', async () => {
- const result = await executor.execute('echo', ['hello']);
- expect(result.exitCode).toBe(0);
- expect(result.stdout.trim()).toBe('hello');
- });
-
- it('should block commands not in allowlist', async () => {
- await expect(executor.execute('cat', ['/etc/passwd'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block sudo commands by default', async () => {
- const sudoExecutor = new SafeExecutor({
- allowedCommands: ['sudo', 'ls'],
- allowSudo: false,
- });
-
- await expect(sudoExecutor.execute('sudo', ['ls'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should allow sudo when configured', async () => {
- const sudoExecutor = new SafeExecutor({
- allowedCommands: ['sudo', 'ls'],
- allowSudo: true,
- });
-
- // Will fail due to password requirement, but shouldn't throw allowlist error
- const error = await sudoExecutor.execute('sudo', ['-n', 'ls']).catch(e => e);
- if (error instanceof SafeExecutorError) {
- expect(error.code).not.toBe('SUDO_NOT_ALLOWED');
- }
- });
- });
-
- describe('Argument Validation', () => {
- it('should block null bytes in arguments', async () => {
- await expect(executor.execute('echo', ['hello\x00world'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block semicolon (command chaining)', async () => {
- await expect(executor.execute('echo', ['hello; rm -rf /'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block && (command chaining)', async () => {
- await expect(executor.execute('echo', ['hello && rm -rf /'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block || (command chaining)', async () => {
- await expect(executor.execute('echo', ['hello || rm -rf /'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block pipe character', async () => {
- await expect(executor.execute('echo', ['hello | cat'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block backticks (command substitution)', async () => {
- await expect(executor.execute('echo', ['`whoami`'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block $() (command substitution)', async () => {
- await expect(executor.execute('echo', ['$(whoami)'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block redirect operators', async () => {
- await expect(executor.execute('echo', ['hello > /etc/passwd'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should block newlines', async () => {
- await expect(executor.execute('echo', ['hello\nrm -rf /'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should allow safe arguments', async () => {
- const result = await executor.execute('echo', ['hello', 'world']);
- expect(result.exitCode).toBe(0);
- });
-
- it('should allow arguments with dashes', async () => {
- const result = await executor.execute('echo', ['-n', 'hello']);
- expect(result.exitCode).toBe(0);
- });
-
- it('should allow arguments with equals', async () => {
- const result = await executor.execute('echo', ['KEY=value']);
- expect(result.exitCode).toBe(0);
- });
- });
-
- describe('Argument Sanitization', () => {
- it('should sanitize null bytes', () => {
- const sanitized = executor.sanitizeArgument('hello\x00world');
- expect(sanitized).not.toContain('\x00');
- });
-
- it('should sanitize shell metacharacters', () => {
- const sanitized = executor.sanitizeArgument('hello; rm -rf /');
- expect(sanitized).not.toContain(';');
- });
- });
-
- describe('Command Execution', () => {
- it('should return stdout', async () => {
- const result = await executor.execute('echo', ['hello']);
- expect(result.stdout.trim()).toBe('hello');
- });
-
- it('should return stderr', async () => {
- // Use node to generate stderr
- const result = await executor.execute('node', ['-e', 'console.error("error")']);
- expect(result.stderr.trim()).toBe('error');
- });
-
- it('should return exit code', async () => {
- const result = await executor.execute('node', ['-e', 'process.exit(42)']);
- expect(result.exitCode).toBe(42);
- });
-
- it('should track execution duration', async () => {
- const result = await executor.execute('echo', ['hello']);
- expect(result.duration).toBeGreaterThanOrEqual(0);
- });
-
- it('should include command in result', async () => {
- const result = await executor.execute('echo', ['hello']);
- expect(result.command).toBe('echo');
- expect(result.args).toEqual(['hello']);
- });
- });
-
- describe('Timeout Handling', () => {
- it('should timeout long-running commands', async () => {
- const shortTimeoutExecutor = new SafeExecutor({
- allowedCommands: ['node'],
- timeout: 100,
- });
-
- await expect(
- shortTimeoutExecutor.execute('node', ['-e', 'setTimeout(() => {}, 10000)'])
- ).rejects.toThrow(SafeExecutorError);
- });
- });
-
- describe('Streaming Execution', () => {
- it('should return process handle', () => {
- const streaming = executor.executeStreaming('echo', ['hello']);
- expect(streaming.process).toBeDefined();
- expect(streaming.promise).toBeInstanceOf(Promise);
-
- // Clean up
- streaming.process.kill();
- });
-
- it('should stream stdout', async () => {
- const streaming = executor.executeStreaming('echo', ['hello']);
- const result = await streaming.promise;
- expect(result.stdout.trim()).toBe('hello');
- });
- });
-
- describe('Dynamic Allowlist', () => {
- it('should check if command is allowed', () => {
- expect(executor.isCommandAllowed('echo')).toBe(true);
- expect(executor.isCommandAllowed('cat')).toBe(false);
- });
-
- it('should add commands at runtime', () => {
- expect(executor.isCommandAllowed('pwd')).toBe(false);
- executor.allowCommand('pwd');
- expect(executor.isCommandAllowed('pwd')).toBe(true);
- });
-
- it('should reject dangerous commands when adding', () => {
- expect(() => executor.allowCommand('rm')).toThrow(SafeExecutorError);
- });
-
- it('should return allowed commands', () => {
- const commands = executor.getAllowedCommands();
- expect(commands).toContain('echo');
- expect(commands).toContain('git');
- });
- });
-
- describe('Factory Functions', () => {
- it('should create development executor', () => {
- const devExecutor = createDevelopmentExecutor();
- expect(devExecutor.isCommandAllowed('git')).toBe(true);
- expect(devExecutor.isCommandAllowed('npm')).toBe(true);
- expect(devExecutor.isCommandAllowed('node')).toBe(true);
- });
-
- it('should create read-only executor', () => {
- const readOnlyExecutor = createReadOnlyExecutor();
- expect(readOnlyExecutor.isCommandAllowed('git')).toBe(true);
- expect(readOnlyExecutor.isCommandAllowed('cat')).toBe(true);
- expect(readOnlyExecutor.isCommandAllowed('ls')).toBe(true);
- });
- });
-
- describe('HIGH-1 Security Verification', () => {
- it('should NOT use shell for execution', async () => {
- // If shell were enabled, this would be interpreted as command chaining
- // With shell disabled, it's just a string argument
- const result = await executor.execute('echo', ['hello']);
- expect(result.exitCode).toBe(0);
-
- // This should fail validation before reaching execution
- await expect(executor.execute('echo', ['hello; cat /etc/passwd'])).rejects.toThrow();
- });
-
- it('should prevent command injection via arguments', async () => {
- // Classic injection attempts
- const injections = [
- 'hello; rm -rf /',
- 'hello && rm -rf /',
- 'hello || rm -rf /',
- 'hello | rm -rf /',
- '`rm -rf /`',
- '$(rm -rf /)',
- 'hello\nrm -rf /',
- 'hello\x00rm -rf /',
- ];
-
- for (const injection of injections) {
- await expect(executor.execute('echo', [injection])).rejects.toThrow(SafeExecutorError);
- }
- });
-
- it('should prevent environment variable injection', async () => {
- await expect(executor.execute('echo', ['${PATH}'])).rejects.toThrow(SafeExecutorError);
- });
-
- it('should not allow arbitrary commands', async () => {
- // Only commands in allowlist should execute
- await expect(executor.execute('wget', ['http://evil.com'])).rejects.toThrow(SafeExecutorError);
- await expect(executor.execute('curl', ['http://evil.com'])).rejects.toThrow(SafeExecutorError);
- await expect(executor.execute('bash', ['-c', 'rm -rf /'])).rejects.toThrow(SafeExecutorError);
- });
- });
-});
diff --git a/v3/__tests__/security/token-generator.test.ts b/v3/__tests__/security/token-generator.test.ts
deleted file mode 100644
index 3890f35b7e..0000000000
--- a/v3/__tests__/security/token-generator.test.ts
+++ /dev/null
@@ -1,371 +0,0 @@
-/**
- * Token Generator Tests
- *
- * Tests verify:
- * - Secure token generation
- * - Token expiration
- * - Signed token verification
- * - Timing-safe comparison
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
- TokenGenerator,
- TokenGeneratorError,
- createTokenGenerator,
- getDefaultGenerator,
- quickGenerate,
-} from '../../security/token-generator.js';
-
-describe('TokenGenerator', () => {
- let generator: TokenGenerator;
-
- beforeEach(() => {
- generator = new TokenGenerator({
- hmacSecret: 'test-secret-key-for-hmac-operations',
- defaultExpiration: 3600,
- });
- });
-
- describe('Configuration', () => {
- it('should use default configuration', () => {
- expect(() => new TokenGenerator()).not.toThrow();
- });
-
- it('should reject token length below 16 bytes', () => {
- expect(() => new TokenGenerator({
- defaultLength: 8,
- })).toThrow(TokenGeneratorError);
- });
-
- it('should accept custom encoding', () => {
- const hexGenerator = new TokenGenerator({ encoding: 'hex' });
- const token = hexGenerator.generate(16);
- expect(token).toMatch(/^[0-9a-f]+$/);
- });
- });
-
- describe('Token Generation', () => {
- it('should generate token of specified length', () => {
- const token = generator.generate(32);
- // Base64url encoding: 32 bytes = ~43 chars
- expect(token.length).toBeGreaterThan(40);
- });
-
- it('should generate unique tokens', () => {
- const tokens = new Set<string>();
- for (let i = 0; i < 100; i++) {
- tokens.add(generator.generate());
- }
- expect(tokens.size).toBe(100);
- });
-
- it('should generate URL-safe tokens by default', () => {
- const token = generator.generate();
- // Base64url should not contain +, /, or =
- expect(token).not.toMatch(/[+/=]/);
- });
- });
-
- describe('Token with Expiration', () => {
- it('should generate token with expiration', () => {
- const token = generator.generateWithExpiration(3600);
-
- expect(token.value).toBeDefined();
- expect(token.createdAt).toBeInstanceOf(Date);
- expect(token.expiresAt).toBeInstanceOf(Date);
- expect(token.expiresAt.getTime()).toBeGreaterThan(token.createdAt.getTime());
- });
-
- it('should set correct expiration time', () => {
- const expiration = 3600; // 1 hour
- const token = generator.generateWithExpiration(expiration);
-
- const expectedExpiration = Date.now() + expiration * 1000;
- const actualExpiration = token.expiresAt.getTime();
-
- expect(Math.abs(actualExpiration - expectedExpiration)).toBeLessThan(100);
- });
-
- it('should include metadata when provided', () => {
- const token = generator.generateWithExpiration(3600, { userId: '123' });
- expect(token.metadata).toEqual({ userId: '123' });
- });
- });
-
- describe('Session Token', () => {
- it('should generate session token', () => {
- const token = generator.generateSessionToken();
-
- expect(token.value).toBeDefined();
- expect(token.expiresAt).toBeInstanceOf(Date);
- });
- });
-
- describe('CSRF Token', () => {
- it('should generate CSRF token', () => {
- const token = generator.generateCsrfToken();
-
- expect(token.value).toBeDefined();
- // 30 minutes expiration
- const expectedExpiration = Date.now() + 1800 * 1000;
- expect(Math.abs(token.expiresAt.getTime() - expectedExpiration)).toBeLessThan(100);
- });
- });
-
- describe('API Token', () => {
- it('should generate API token with prefix', () => {
- const token = generator.generateApiToken('cf_');
-
- expect(token.value.startsWith('cf_')).toBe(true);
- });
-
- it('should set 1 year expiration', () => {
- const token = generator.generateApiToken();
-
- const expectedExpiration = Date.now() + 365 * 24 * 60 * 60 * 1000;
- expect(Math.abs(token.expiresAt.getTime() - expectedExpiration)).toBeLessThan(1000);
- });
- });
-
- describe('Verification Code', () => {
- it('should generate numeric code', () => {
- const code = generator.generateVerificationCode();
-
- expect(code.code).toMatch(/^\d{6}$/);
- });
-
- it('should generate code of specified length', () => {
- const code = generator.generateVerificationCode(8);
-
- expect(code.code).toMatch(/^\d{8}$/);
- });
-
- it('should set expiration', () => {
- const code = generator.generateVerificationCode(6, 10);
-
- const expectedExpiration = Date.now() + 10 * 60 * 1000;
- expect(Math.abs(code.expiresAt.getTime() - expectedExpiration)).toBeLessThan(100);
- });
-
- it('should track attempts', () => {
- const code = generator.generateVerificationCode(6, 10, 3);
-
- expect(code.attempts).toBe(0);
- expect(code.maxAttempts).toBe(3);
- });
- });
-
- describe('Signed Token', () => {
- it('should generate signed token', () => {
- const signed = generator.generateSignedToken({ userId: '123' });
-
- expect(signed.token).toBeDefined();
- expect(signed.signature).toBeDefined();
- expect(signed.combined).toBe(`${signed.token}.${signed.signature}`);
- });
-
- it('should require HMAC secret', () => {
- const noSecretGenerator = new TokenGenerator();
-
- expect(() => noSecretGenerator.generateSignedToken({ userId: '123' }))
- .toThrow(TokenGeneratorError);
- });
-
- it('should verify valid signed token', () => {
- const signed = generator.generateSignedToken({ userId: '123' });
- const payload = generator.verifySignedToken(signed.combined);
-
- expect(payload).not.toBeNull();
- expect((payload as any).userId).toBe('123');
- });
-
- it('should reject tampered token', () => {
- const signed = generator.generateSignedToken({ userId: '123' });
-
- // Tamper with the token
- const tampered = 'tampered' + signed.combined.slice(8);
- const payload = generator.verifySignedToken(tampered);
-
- expect(payload).toBeNull();
- });
-
- it('should reject tampered signature', () => {
- const signed = generator.generateSignedToken({ userId: '123' });
-
- // Tamper with signature
- const parts = signed.combined.split('.');
- const tampered = `${parts[0]}.tampered${parts[1].slice(8)}`;
- const payload = generator.verifySignedToken(tampered);
-
- expect(payload).toBeNull();
- });
-
- it('should reject expired signed token', async () => {
- const signed = generator.generateSignedToken({ userId: '123' }, 1); // 1 second
-
- // Wait for expiration
- await new Promise(resolve => setTimeout(resolve, 1100));
-
- const payload = generator.verifySignedToken(signed.combined);
- expect(payload).toBeNull();
- });
-
- it('should reject malformed token', () => {
- expect(generator.verifySignedToken('not.a.valid.token')).toBeNull();
- expect(generator.verifySignedToken('invalid')).toBeNull();
- expect(generator.verifySignedToken('')).toBeNull();
- });
- });
-
- describe('Token Pair', () => {
- it('should generate access and refresh tokens', () => {
- const pair = generator.generateTokenPair();
-
- expect(pair.accessToken.value).toBeDefined();
- expect(pair.refreshToken.value).toBeDefined();
- });
-
- it('should set different expirations', () => {
- const pair = generator.generateTokenPair();
-
- // Access token: 15 minutes
- const accessExpiration = Date.now() + 900 * 1000;
- expect(Math.abs(pair.accessToken.expiresAt.getTime() - accessExpiration)).toBeLessThan(100);
-
- // Refresh token: 7 days
- const refreshExpiration = Date.now() + 604800 * 1000;
- expect(Math.abs(pair.refreshToken.expiresAt.getTime() - refreshExpiration)).toBeLessThan(100);
- });
- });
-
- describe('Specialized Tokens', () => {
- it('should generate password reset token', () => {
- const token = generator.generatePasswordResetToken();
-
- expect(token.value).toBeDefined();
- // 30 minutes
- const expectedExpiration = Date.now() + 1800 * 1000;
- expect(Math.abs(token.expiresAt.getTime() - expectedExpiration)).toBeLessThan(100);
- });
-
- it('should generate email verification token', () => {
- const token = generator.generateEmailVerificationToken();
-
- expect(token.value).toBeDefined();
- // 24 hours
- const expectedExpiration = Date.now() + 86400 * 1000;
- expect(Math.abs(token.expiresAt.getTime() - expectedExpiration)).toBeLessThan(100);
- });
-
- it('should generate request ID', () => {
- const requestId = generator.generateRequestId();
-
- expect(requestId).toBeDefined();
- expect(requestId.length).toBeLessThan(20); // Shorter for logging
- });
-
- it('should generate correlation ID', () => {
- const correlationId = generator.generateCorrelationId();
-
- expect(correlationId).toBeDefined();
- expect(correlationId).toContain('-'); // timestamp-random format
- });
- });
-
- describe('Token Expiration Check', () => {
- it('should detect expired token', async () => {
- const token = generator.generateWithExpiration(1); // 1 second
-
- expect(generator.isExpired(token)).toBe(false);
-
- await new Promise(resolve => setTimeout(resolve, 1100));
-
- expect(generator.isExpired(token)).toBe(true);
- });
-
- it('should detect valid token', () => {
- const token = generator.generateWithExpiration(3600);
- expect(generator.isExpired(token)).toBe(false);
- });
- });
-
- describe('Token Comparison', () => {
- it('should compare equal tokens', () => {
- const token = generator.generate();
- expect(generator.compare(token, token)).toBe(true);
- });
-
- it('should reject different tokens', () => {
- const token1 = generator.generate();
- const token2 = generator.generate();
- expect(generator.compare(token1, token2)).toBe(false);
- });
-
- it('should reject different length tokens', () => {
- expect(generator.compare('short', 'longer-token')).toBe(false);
- });
-
- it('should use timing-safe comparison', () => {
- // This test verifies the comparison takes consistent time
- // regardless of where the mismatch occurs
- const token = generator.generate();
- const mismatchEarly = 'X' + token.slice(1);
- const mismatchLate = token.slice(0, -1) + 'X';
-
- // Both comparisons should work (timing consistency is internal)
- expect(generator.compare(token, mismatchEarly)).toBe(false);
- expect(generator.compare(token, mismatchLate)).toBe(false);
- });
- });
-
- describe('Factory Functions', () => {
- it('should create generator with factory', () => {
- const gen = createTokenGenerator('secret');
- expect(gen).toBeInstanceOf(TokenGenerator);
- });
-
- it('should get default generator singleton', () => {
- const gen1 = getDefaultGenerator();
- const gen2 = getDefaultGenerator();
- expect(gen1).toBe(gen2);
- });
- });
-
- describe('Quick Generate Functions', () => {
- it('should generate token', () => {
- const token = quickGenerate.token();
- expect(token).toBeDefined();
- });
-
- it('should generate session token', () => {
- const token = quickGenerate.sessionToken();
- expect(token.value).toBeDefined();
- });
-
- it('should generate CSRF token', () => {
- const token = quickGenerate.csrfToken();
- expect(token.value).toBeDefined();
- });
-
- it('should generate API token', () => {
- const token = quickGenerate.apiToken('cf_');
- expect(token.value.startsWith('cf_')).toBe(true);
- });
-
- it('should generate verification code', () => {
- const code = quickGenerate.verificationCode();
- expect(code.code).toMatch(/^\d{6}$/);
- });
-
- it('should generate request ID', () => {
- const id = quickGenerate.requestId();
- expect(id).toBeDefined();
- });
-
- it('should generate correlation ID', () => {
- const id = quickGenerate.correlationId();
- expect(id).toBeDefined();
- });
- });
-});
diff --git a/v3/__tests__/setup.ts b/v3/__tests__/setup.ts
deleted file mode 100644
index 56796f0525..0000000000
--- a/v3/__tests__/setup.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-/**
- * V3 Claude-Flow Test Setup
- *
- * London School TDD Global Configuration
- * - Initializes mock infrastructure
- * - Sets up global test utilities
- * - Configures behavior verification helpers
- */
-import { vi, beforeEach, afterEach, expect } from 'vitest';
-
-// Re-export commonly used testing utilities
-export { vi, expect } from 'vitest';
-export { createMock, createDeepMock, createSpyMock } from './helpers/create-mock';
-export { createTestApplication } from './helpers/test-application';
-export { createSwarmTestInstance } from './helpers/swarm-instance';
-
-// Custom matchers for London School testing
-expect.extend({
- /**
- * Verify a mock was called with specific interaction pattern
- */
- toHaveBeenCalledWithInteraction(received, expected) {
- const pass = received.mock.calls.some((call: unknown[]) =>
- JSON.stringify(call) === JSON.stringify(expected)
- );
-
- return {
- pass,
- message: () => pass
- ? `Expected mock not to have been called with ${JSON.stringify(expected)}`
- : `Expected mock to have been called with ${JSON.stringify(expected)}, but was called with ${JSON.stringify(received.mock.calls)}`,
- };
- },
-
- /**
- * Verify mock call order for behavior testing
- */
- toHaveBeenCalledBefore(received, other) {
- const receivedCalls = received.mock.invocationCallOrder;
- const otherCalls = other.mock.invocationCallOrder;
-
- if (receivedCalls.length === 0 || otherCalls.length === 0) {
- return {
- pass: false,
- message: () => 'Expected both mocks to have been called',
- };
- }
-
- const pass = Math.min(...receivedCalls) < Math.min(...otherCalls);
-
- return {
- pass,
- message: () => pass
- ? `Expected first mock not to have been called before second mock`
- : `Expected first mock to have been called before second mock`,
- };
- },
-
- /**
- * Verify interaction count for behavior verification
- */
- toHaveInteractionCount(received, expected) {
- const actual = received.mock.calls.length;
- const pass = actual === expected;
-
- return {
- pass,
- message: () => pass
- ? `Expected mock not to have ${expected} interactions`
- : `Expected mock to have ${expected} interactions, but had ${actual}`,
- };
- },
-});
-
-// Global setup - runs once before all tests
-beforeEach(() => {
- // Reset all mocks before each test (London School principle)
- vi.clearAllMocks();
-
- // Reset any timers
- vi.useRealTimers();
-});
-
-afterEach(() => {
- // Verify no unhandled mock calls (strict verification)
- vi.restoreAllMocks();
-});
-
-// Type declarations for custom matchers
-declare module 'vitest' {
- interface Assertion<T = unknown> {
- toHaveBeenCalledWithInteraction(expected: unknown[]): T;
- toHaveBeenCalledBefore(other: ReturnType<typeof vi.fn>): T;
- toHaveInteractionCount(expected: number): T;
- }
- interface AsymmetricMatchersContaining {
- toHaveBeenCalledWithInteraction(expected: unknown[]): unknown;
- toHaveBeenCalledBefore(other: ReturnType<typeof vi.fn>): unknown;
- toHaveInteractionCount(expected: number): unknown;
- }
-}
-
-/**
- * Test configuration constants
- */
-export const TEST_CONFIG = {
- // Security test thresholds
- SECURITY_COVERAGE_TARGET: 0.95,
-
- // Performance test thresholds
- FLASH_ATTENTION_SPEEDUP_MIN: 2.49,
- FLASH_ATTENTION_SPEEDUP_MAX: 7.47,
- AGENTDB_SEARCH_IMPROVEMENT_MIN: 150,
- AGENTDB_SEARCH_IMPROVEMENT_MAX: 12500,
- MEMORY_REDUCTION_TARGET: 0.50,
-
- // Timeouts
- ASYNC_TIMEOUT: 5000,
- INTEGRATION_TIMEOUT: 10000,
- ACCEPTANCE_TIMEOUT: 30000,
-} as const;
diff --git a/v3/__tests__/unit/core/event-bus.test.ts b/v3/__tests__/unit/core/event-bus.test.ts
deleted file mode 100644
index 98dcf1e6ac..0000000000
--- a/v3/__tests__/unit/core/event-bus.test.ts
+++ /dev/null
@@ -1,572 +0,0 @@
-/**
- * V3 Claude-Flow Event Bus Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests event publishing and subscription
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface } from '../../helpers/create-mock';
-
-/**
- * Event bus interface (to be implemented)
- */
-interface IEventBus {
- publish(event: DomainEvent): Promise<void>;
- subscribe(eventType: string, handler: EventHandler): Subscription;
- unsubscribe(subscription: Subscription): void;
- subscribeAll(handler: EventHandler): Subscription;
-}
-
-/**
- * Event store interface (collaborator)
- */
-interface IEventStore {
- append(event: DomainEvent): Promise<void>;
- getByType(eventType: string): Promise<DomainEvent[]>;
- getAll(): Promise<DomainEvent[]>;
-}
-
-/**
- * Event dispatcher interface (collaborator)
- */
-interface IEventDispatcher {
- dispatch(event: DomainEvent, handlers: EventHandler[]): Promise<void>;
-}
-
-interface DomainEvent {
- id: string;
- type: string;
- payload: unknown;
- timestamp: Date;
- correlationId?: string;
-}
-
-type EventHandler = (event: DomainEvent) => Promise<void>;
-
-interface Subscription {
- id: string;
- eventType: string | '*';
- unsubscribe: () => void;
-}
-
-/**
- * Event bus implementation for testing
- */
-class EventBus implements IEventBus {
- private handlers: Map<string, Set<{ id: string; handler: EventHandler }>> = new Map();
- private wildcardHandlers: Set<{ id: string; handler: EventHandler }> = new Set();
- private subscriptionCounter = 0;
-
- constructor(
- private readonly eventStore: IEventStore,
- private readonly dispatcher: IEventDispatcher,
- private readonly idGenerator: () => string = () => `sub-${Date.now()}`
- ) {}
-
- async publish(event: DomainEvent): Promise<void> {
- // Store event first (event sourcing per ADR-007)
- await this.eventStore.append(event);
-
- // Get type-specific handlers
- const typeHandlers = this.handlers.get(event.type) ?? new Set();
-
- // Combine with wildcard handlers
- const allHandlers = [
- ...Array.from(typeHandlers).map(h => h.handler),
- ...Array.from(this.wildcardHandlers).map(h => h.handler),
- ];
-
- // Dispatch to all handlers
- if (allHandlers.length > 0) {
- await this.dispatcher.dispatch(event, allHandlers);
- }
- }
-
- subscribe(eventType: string, handler: EventHandler): Subscription {
- const id = this.idGenerator();
-
- if (!this.handlers.has(eventType)) {
- this.handlers.set(eventType, new Set());
- }
-
- const handlerEntry = { id, handler };
- this.handlers.get(eventType)!.add(handlerEntry);
-
- return {
- id,
- eventType,
- unsubscribe: () => {
- this.handlers.get(eventType)?.delete(handlerEntry);
- },
- };
- }
-
- subscribeAll(handler: EventHandler): Subscription {
- const id = this.idGenerator();
- const handlerEntry = { id, handler };
-
- this.wildcardHandlers.add(handlerEntry);
-
- return {
- id,
- eventType: '*',
- unsubscribe: () => {
- this.wildcardHandlers.delete(handlerEntry);
- },
- };
- }
-
- unsubscribe(subscription: Subscription): void {
- subscription.unsubscribe();
- }
-}
-
-describe('EventBus', () => {
- let mockEventStore: MockedInterface<IEventStore>;
- let mockDispatcher: MockedInterface<IEventDispatcher>;
- let eventBus: EventBus;
- const mockIdGenerator = vi.fn().mockReturnValue('sub-123');
-
- beforeEach(() => {
- mockEventStore = createMock<IEventStore>();
- mockDispatcher = createMock<IEventDispatcher>();
-
- // Configure default mock behavior
- mockEventStore.append.mockResolvedValue(undefined);
- mockEventStore.getByType.mockResolvedValue([]);
- mockEventStore.getAll.mockResolvedValue([]);
-
- mockDispatcher.dispatch.mockResolvedValue(undefined);
-
- eventBus = new EventBus(mockEventStore, mockDispatcher, mockIdGenerator);
- });
-
- describe('publish', () => {
- it('should append event to event store', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockEventStore.append).toHaveBeenCalledWith(event);
- });
-
- it('should store event before dispatching', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- const handler = vi.fn();
- eventBus.subscribe('TaskCreated', handler);
-
- let storeCallOrder = 0;
- let dispatchCallOrder = 0;
- let callCounter = 0;
-
- mockEventStore.append.mockImplementation(async () => {
- storeCallOrder = ++callCounter;
- });
-
- mockDispatcher.dispatch.mockImplementation(async () => {
- dispatchCallOrder = ++callCounter;
- });
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(storeCallOrder).toBeLessThan(dispatchCallOrder);
- });
-
- it('should dispatch to type-specific handlers', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- const handler = vi.fn();
- eventBus.subscribe('TaskCreated', handler);
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
- event,
- expect.arrayContaining([handler])
- );
- });
-
- it('should dispatch to wildcard handlers', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- const wildcardHandler = vi.fn();
- eventBus.subscribeAll(wildcardHandler);
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
- event,
- expect.arrayContaining([wildcardHandler])
- );
- });
-
- it('should dispatch to both type-specific and wildcard handlers', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- const typeHandler = vi.fn();
- const wildcardHandler = vi.fn();
- eventBus.subscribe('TaskCreated', typeHandler);
- eventBus.subscribeAll(wildcardHandler);
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
- event,
- expect.arrayContaining([typeHandler, wildcardHandler])
- );
- });
-
- it('should not dispatch when no handlers registered', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).not.toHaveBeenCalled();
- });
-
- it('should only dispatch to matching event type handlers', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- const taskCreatedHandler = vi.fn();
- const taskCompletedHandler = vi.fn();
- eventBus.subscribe('TaskCreated', taskCreatedHandler);
- eventBus.subscribe('TaskCompleted', taskCompletedHandler);
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
- event,
- expect.arrayContaining([taskCreatedHandler])
- );
- expect(mockDispatcher.dispatch).not.toHaveBeenCalledWith(
- event,
- expect.arrayContaining([taskCompletedHandler])
- );
- });
-
- it('should propagate event store errors', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- mockEventStore.append.mockRejectedValue(new Error('Store failed'));
-
- // When/Then
- await expect(eventBus.publish(event)).rejects.toThrow('Store failed');
- });
-
- it('should propagate dispatcher errors', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
- const handler = vi.fn();
- eventBus.subscribe('TaskCreated', handler);
- mockDispatcher.dispatch.mockRejectedValue(new Error('Dispatch failed'));
-
- // When/Then
- await expect(eventBus.publish(event)).rejects.toThrow('Dispatch failed');
- });
- });
-
- describe('subscribe', () => {
- it('should return subscription with id', () => {
- // Given
- const handler = vi.fn();
-
- // When
- const subscription = eventBus.subscribe('TaskCreated', handler);
-
- // Then
- expect(subscription.id).toBe('sub-123');
- });
-
- it('should return subscription with event type', () => {
- // Given
- const handler = vi.fn();
-
- // When
- const subscription = eventBus.subscribe('TaskCreated', handler);
-
- // Then
- expect(subscription.eventType).toBe('TaskCreated');
- });
-
- it('should return subscription with unsubscribe function', () => {
- // Given
- const handler = vi.fn();
-
- // When
- const subscription = eventBus.subscribe('TaskCreated', handler);
-
- // Then
- expect(typeof subscription.unsubscribe).toBe('function');
- });
-
- it('should register handler for event type', async () => {
- // Given
- const handler = vi.fn();
- eventBus.subscribe('TaskCreated', handler);
-
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalled();
- });
-
- it('should allow multiple handlers for same event type', async () => {
- // Given
- const handler1 = vi.fn();
- const handler2 = vi.fn();
- eventBus.subscribe('TaskCreated', handler1);
- eventBus.subscribe('TaskCreated', handler2);
-
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: { taskId: '123' },
- timestamp: new Date(),
- };
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
- event,
- expect.arrayContaining([handler1, handler2])
- );
- });
- });
-
- describe('subscribeAll', () => {
- it('should return subscription with wildcard event type', () => {
- // Given
- const handler = vi.fn();
-
- // When
- const subscription = eventBus.subscribeAll(handler);
-
- // Then
- expect(subscription.eventType).toBe('*');
- });
-
- it('should receive all event types', async () => {
- // Given
- const handler = vi.fn();
- eventBus.subscribeAll(handler);
-
- const event1: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: {},
- timestamp: new Date(),
- };
- const event2: DomainEvent = {
- id: 'event-2',
- type: 'TaskCompleted',
- payload: {},
- timestamp: new Date(),
- };
-
- // When
- await eventBus.publish(event1);
- await eventBus.publish(event2);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledTimes(2);
- });
- });
-
- describe('unsubscribe', () => {
- it('should remove handler from subscriptions', async () => {
- // Given
- const handler = vi.fn();
- const subscription = eventBus.subscribe('TaskCreated', handler);
-
- // When
- eventBus.unsubscribe(subscription);
-
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: {},
- timestamp: new Date(),
- };
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).not.toHaveBeenCalled();
- });
-
- it('should only remove specific subscription', async () => {
- // Given
- const handler1 = vi.fn();
- const handler2 = vi.fn();
- const sub1 = eventBus.subscribe('TaskCreated', handler1);
- eventBus.subscribe('TaskCreated', handler2);
-
- // When
- eventBus.unsubscribe(sub1);
-
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: {},
- timestamp: new Date(),
- };
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
- event,
- [handler2]
- );
- });
-
- it('should remove wildcard subscription', async () => {
- // Given
- const handler = vi.fn();
- const subscription = eventBus.subscribeAll(handler);
-
- // When
- eventBus.unsubscribe(subscription);
-
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: {},
- timestamp: new Date(),
- };
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).not.toHaveBeenCalled();
- });
-
- it('should work when called via subscription object', async () => {
- // Given
- const handler = vi.fn();
- const subscription = eventBus.subscribe('TaskCreated', handler);
-
- // When
- subscription.unsubscribe();
-
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: {},
- timestamp: new Date(),
- };
- await eventBus.publish(event);
-
- // Then
- expect(mockDispatcher.dispatch).not.toHaveBeenCalled();
- });
- });
-
- describe('event sourcing compliance (ADR-007)', () => {
- it('should store all events regardless of handlers', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'UnhandledEvent',
- payload: {},
- timestamp: new Date(),
- };
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockEventStore.append).toHaveBeenCalledWith(event);
- });
-
- it('should include correlation id when present', async () => {
- // Given
- const event: DomainEvent = {
- id: 'event-1',
- type: 'TaskCreated',
- payload: {},
- timestamp: new Date(),
- correlationId: 'correlation-123',
- };
-
- // When
- await eventBus.publish(event);
-
- // Then
- expect(mockEventStore.append).toHaveBeenCalledWith(
- expect.objectContaining({
- correlationId: 'correlation-123',
- })
- );
- });
- });
-});
diff --git a/v3/__tests__/unit/core/lifecycle-manager.test.ts b/v3/__tests__/unit/core/lifecycle-manager.test.ts
deleted file mode 100644
index bce618444b..0000000000
--- a/v3/__tests__/unit/core/lifecycle-manager.test.ts
+++ /dev/null
@@ -1,780 +0,0 @@
-/**
- * V3 Claude-Flow Lifecycle Manager Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests agent lifecycle management
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface, InteractionRecorder } from '../../helpers/create-mock';
-import { agentConfigs, createAgentConfig } from '../../fixtures/agents';
-
-/**
- * Lifecycle manager interface (to be implemented)
- */
-interface ILifecycleManager {
- spawn(config: AgentConfig): Promise<Agent>;
- terminate(agentId: string): Promise<void>;
- restart(agentId: string): Promise<Agent>;
- getAgent(agentId: string): Promise<Agent | null>;
- listAgents(): Promise<Agent[]>;
- getHealth(agentId: string): Promise<AgentHealth>;
-}
-
-/**
- * Agent registry interface (collaborator)
- */
-interface IAgentRegistry {
- register(agent: Agent): Promise<void>;
- unregister(agentId: string): Promise<void>;
- find(agentId: string): Promise<Agent | null>;
- findAll(): Promise<Agent[]>;
- update(agentId: string, updates: Partial<Agent>): Promise<void>;
-}
-
-/**
- * Agent factory interface (collaborator)
- */
-interface IAgentFactory {
- create(config: AgentConfig): Promise<Agent>;
- validate(config: AgentConfig): boolean;
-}
-
-/**
- * Health monitor interface (collaborator)
- */
-interface IHealthMonitor {
- startMonitoring(agentId: string): void;
- stopMonitoring(agentId: string): void;
- getHealth(agentId: string): AgentHealth;
-}
-
-/**
- * Event publisher interface (collaborator)
- */
-interface IEventPublisher {
- publish(event: DomainEvent): Promise<void>;
-}
-
-interface AgentConfig {
- type: string;
- name: string;
- capabilities: string[];
- priority?: number;
-}
-
-interface Agent {
- id: string;
- type: string;
- name: string;
- status: AgentStatus;
- capabilities: string[];
- createdAt: Date;
- lastActiveAt?: Date;
-}
-
-type AgentStatus = 'initializing' | 'idle' | 'busy' | 'terminating' | 'terminated';
-
-interface AgentHealth {
- status: 'healthy' | 'degraded' | 'unhealthy';
- lastCheck: Date;
- metrics: {
- cpuUsage: number;
- memoryUsage: number;
- taskCount: number;
- };
-}
-
-interface DomainEvent {
- type: string;
- payload: unknown;
- timestamp: Date;
-}
-
-/**
- * Lifecycle manager implementation for testing
- */
-class LifecycleManager implements ILifecycleManager {
- constructor(
- private readonly registry: IAgentRegistry,
- private readonly factory: IAgentFactory,
- private readonly healthMonitor: IHealthMonitor,
- private readonly eventPublisher: IEventPublisher
- ) {}
-
- async spawn(config: AgentConfig): Promise<Agent> {
- // Validate configuration
- if (!this.factory.validate(config)) {
- throw new Error('Invalid agent configuration');
- }
-
- // Create agent
- const agent = await this.factory.create(config);
-
- // Register agent
- await this.registry.register(agent);
-
- // Start health monitoring
- this.healthMonitor.startMonitoring(agent.id);
-
- // Update status to idle
- await this.registry.update(agent.id, { status: 'idle' });
-
- // Publish event
- await this.eventPublisher.publish({
- type: 'AgentSpawned',
- payload: { agentId: agent.id, type: agent.type, name: agent.name },
- timestamp: new Date(),
- });
-
- return { ...agent, status: 'idle' };
- }
-
- async terminate(agentId: string): Promise<void> {
- const agent = await this.registry.find(agentId);
-
- if (!agent) {
- throw new Error(`Agent not found: ${agentId}`);
- }
-
- if (agent.status === 'terminated') {
- throw new Error(`Agent already terminated: ${agentId}`);
- }
-
- // Update status to terminating
- await this.registry.update(agentId, { status: 'terminating' });
-
- // Stop health monitoring
- this.healthMonitor.stopMonitoring(agentId);
-
- // Update status to terminated
- await this.registry.update(agentId, { status: 'terminated' });
-
- // Publish event
- await this.eventPublisher.publish({
- type: 'AgentTerminated',
- payload: { agentId },
- timestamp: new Date(),
- });
- }
-
- async restart(agentId: string): Promise<Agent> {
- const agent = await this.registry.find(agentId);
-
- if (!agent) {
- throw new Error(`Agent not found: ${agentId}`);
- }
-
- // Terminate existing
- await this.terminate(agentId);
-
- // Unregister old agent
- await this.registry.unregister(agentId);
-
- // Spawn new agent with same config
- const newAgent = await this.spawn({
- type: agent.type,
- name: agent.name,
- capabilities: agent.capabilities,
- });
-
- // Publish restart event
- await this.eventPublisher.publish({
- type: 'AgentRestarted',
- payload: { oldAgentId: agentId, newAgentId: newAgent.id },
- timestamp: new Date(),
- });
-
- return newAgent;
- }
-
- async getAgent(agentId: string): Promise<Agent | null> {
- return this.registry.find(agentId);
- }
-
- async listAgents(): Promise<Agent[]> {
- return this.registry.findAll();
- }
-
- async getHealth(agentId: string): Promise<AgentHealth> {
- const agent = await this.registry.find(agentId);
-
- if (!agent) {
- throw new Error(`Agent not found: ${agentId}`);
- }
-
- return this.healthMonitor.getHealth(agentId);
- }
-}
-
-describe('LifecycleManager', () => {
- let mockRegistry: MockedInterface<IAgentRegistry>;
- let mockFactory: MockedInterface<IAgentFactory>;
- let mockHealthMonitor: MockedInterface<IHealthMonitor>;
- let mockEventPublisher: MockedInterface<IEventPublisher>;
- let lifecycleManager: LifecycleManager;
- let interactionRecorder: InteractionRecorder;
-
- beforeEach(() => {
- mockRegistry = createMock<IAgentRegistry>();
- mockFactory = createMock<IAgentFactory>();
- mockHealthMonitor = createMock<IHealthMonitor>();
- mockEventPublisher = createMock<IEventPublisher>();
- interactionRecorder = new InteractionRecorder();
-
- // Configure default mock behavior
- mockRegistry.register.mockResolvedValue(undefined);
- mockRegistry.unregister.mockResolvedValue(undefined);
- mockRegistry.find.mockResolvedValue(null);
- mockRegistry.findAll.mockResolvedValue([]);
- mockRegistry.update.mockResolvedValue(undefined);
-
- mockFactory.validate.mockReturnValue(true);
- mockFactory.create.mockResolvedValue({
- id: 'agent-123',
- type: 'coder',
- name: 'Test Agent',
- status: 'initializing',
- capabilities: ['coding'],
- createdAt: new Date(),
- });
-
- mockHealthMonitor.getHealth.mockReturnValue({
- status: 'healthy',
- lastCheck: new Date(),
- metrics: { cpuUsage: 10, memoryUsage: 50, taskCount: 0 },
- });
-
- mockEventPublisher.publish.mockResolvedValue(undefined);
-
- // Track interactions
- interactionRecorder.track('registry', mockRegistry);
- interactionRecorder.track('factory', mockFactory);
- interactionRecorder.track('health', mockHealthMonitor);
- interactionRecorder.track('events', mockEventPublisher);
-
- lifecycleManager = new LifecycleManager(
- mockRegistry,
- mockFactory,
- mockHealthMonitor,
- mockEventPublisher
- );
- });
-
- describe('spawn', () => {
- it('should validate configuration first', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- expect(mockFactory.validate).toHaveBeenCalledWith(config);
- });
-
- it('should throw error for invalid configuration', async () => {
- // Given
- const config = agentConfigs.coder;
- mockFactory.validate.mockReturnValue(false);
-
- // When/Then
- await expect(lifecycleManager.spawn(config)).rejects.toThrow(
- 'Invalid agent configuration'
- );
- });
-
- it('should create agent via factory', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- expect(mockFactory.create).toHaveBeenCalledWith(config);
- });
-
- it('should register agent after creation', async () => {
- // Given
- const config = agentConfigs.coder;
- const createdAgent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Coder Agent',
- status: 'initializing' as AgentStatus,
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockFactory.create.mockResolvedValue(createdAgent);
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- expect(mockRegistry.register).toHaveBeenCalledWith(createdAgent);
- });
-
- it('should start health monitoring after registration', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- expect(mockHealthMonitor.startMonitoring).toHaveBeenCalledWith('agent-123');
- });
-
- it('should update status to idle after monitoring started', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- expect(mockRegistry.update).toHaveBeenCalledWith(
- 'agent-123',
- expect.objectContaining({ status: 'idle' })
- );
- });
-
- it('should publish AgentSpawned event', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentSpawned',
- payload: expect.objectContaining({
- agentId: 'agent-123',
- }),
- })
- );
- });
-
- it('should return agent with idle status', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- const result = await lifecycleManager.spawn(config);
-
- // Then
- expect(result.status).toBe('idle');
- });
-
- it('should follow correct lifecycle order', async () => {
- // Given
- const config = agentConfigs.coder;
-
- // When
- await lifecycleManager.spawn(config);
-
- // Then
- const order = interactionRecorder.getInteractionOrder();
-
- // Validate -> Create -> Register -> Monitor -> Update -> Publish
- expect(order.indexOf('factory.validate')).toBeLessThan(order.indexOf('factory.create'));
- expect(order.indexOf('factory.create')).toBeLessThan(order.indexOf('registry.register'));
- expect(order.indexOf('registry.register')).toBeLessThan(order.indexOf('health.startMonitoring'));
- });
- });
-
- describe('terminate', () => {
- it('should find agent in registry', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.terminate('agent-123');
-
- // Then
- expect(mockRegistry.find).toHaveBeenCalledWith('agent-123');
- });
-
- it('should throw error for non-existent agent', async () => {
- // Given
- mockRegistry.find.mockResolvedValue(null);
-
- // When/Then
- await expect(lifecycleManager.terminate('non-existent')).rejects.toThrow(
- 'Agent not found: non-existent'
- );
- });
-
- it('should throw error for already terminated agent', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'terminated',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When/Then
- await expect(lifecycleManager.terminate('agent-123')).rejects.toThrow(
- 'Agent already terminated: agent-123'
- );
- });
-
- it('should update status to terminating first', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.terminate('agent-123');
-
- // Then
- const firstUpdate = mockRegistry.update.mock.calls[0];
- expect(firstUpdate[1]).toMatchObject({ status: 'terminating' });
- });
-
- it('should stop health monitoring', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.terminate('agent-123');
-
- // Then
- expect(mockHealthMonitor.stopMonitoring).toHaveBeenCalledWith('agent-123');
- });
-
- it('should update status to terminated', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.terminate('agent-123');
-
- // Then
- const lastUpdate = mockRegistry.update.mock.calls[mockRegistry.update.mock.calls.length - 1];
- expect(lastUpdate[1]).toMatchObject({ status: 'terminated' });
- });
-
- it('should publish AgentTerminated event', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.terminate('agent-123');
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentTerminated',
- payload: { agentId: 'agent-123' },
- })
- );
- });
- });
-
- describe('restart', () => {
- it('should find existing agent', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.restart('agent-123');
-
- // Then
- expect(mockRegistry.find).toHaveBeenCalledWith('agent-123');
- });
-
- it('should throw error for non-existent agent', async () => {
- // Given
- mockRegistry.find.mockResolvedValue(null);
-
- // When/Then
- await expect(lifecycleManager.restart('non-existent')).rejects.toThrow(
- 'Agent not found: non-existent'
- );
- });
-
- it('should terminate existing agent', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.restart('agent-123');
-
- // Then
- expect(mockRegistry.update).toHaveBeenCalledWith(
- 'agent-123',
- expect.objectContaining({ status: 'terminating' })
- );
- });
-
- it('should unregister old agent', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.restart('agent-123');
-
- // Then
- expect(mockRegistry.unregister).toHaveBeenCalledWith('agent-123');
- });
-
- it('should spawn new agent with same config', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.restart('agent-123');
-
- // Then
- expect(mockFactory.create).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'coder',
- name: 'Test',
- capabilities: ['coding'],
- })
- );
- });
-
- it('should publish AgentRestarted event', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.restart('agent-123');
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentRestarted',
- })
- );
- });
-
- it('should return new agent', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- const result = await lifecycleManager.restart('agent-123');
-
- // Then
- expect(result.status).toBe('idle');
- });
- });
-
- describe('getAgent', () => {
- it('should delegate to registry find', async () => {
- // When
- await lifecycleManager.getAgent('agent-123');
-
- // Then
- expect(mockRegistry.find).toHaveBeenCalledWith('agent-123');
- });
-
- it('should return agent when found', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- const result = await lifecycleManager.getAgent('agent-123');
-
- // Then
- expect(result).toEqual(agent);
- });
-
- it('should return null when not found', async () => {
- // Given
- mockRegistry.find.mockResolvedValue(null);
-
- // When
- const result = await lifecycleManager.getAgent('non-existent');
-
- // Then
- expect(result).toBeNull();
- });
- });
-
- describe('listAgents', () => {
- it('should delegate to registry findAll', async () => {
- // When
- await lifecycleManager.listAgents();
-
- // Then
- expect(mockRegistry.findAll).toHaveBeenCalled();
- });
-
- it('should return all agents', async () => {
- // Given
- const agents: Agent[] = [
- { id: 'agent-1', type: 'coder', name: 'Agent 1', status: 'idle', capabilities: [], createdAt: new Date() },
- { id: 'agent-2', type: 'tester', name: 'Agent 2', status: 'busy', capabilities: [], createdAt: new Date() },
- ];
- mockRegistry.findAll.mockResolvedValue(agents);
-
- // When
- const result = await lifecycleManager.listAgents();
-
- // Then
- expect(result).toEqual(agents);
- });
- });
-
- describe('getHealth', () => {
- it('should find agent first', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- // When
- await lifecycleManager.getHealth('agent-123');
-
- // Then
- expect(mockRegistry.find).toHaveBeenCalledWith('agent-123');
- });
-
- it('should throw error for non-existent agent', async () => {
- // Given
- mockRegistry.find.mockResolvedValue(null);
-
- // When/Then
- await expect(lifecycleManager.getHealth('non-existent')).rejects.toThrow(
- 'Agent not found: non-existent'
- );
- });
-
- it('should return health from monitor', async () => {
- // Given
- const agent: Agent = {
- id: 'agent-123',
- type: 'coder',
- name: 'Test',
- status: 'idle',
- capabilities: ['coding'],
- createdAt: new Date(),
- };
- mockRegistry.find.mockResolvedValue(agent);
-
- const health: AgentHealth = {
- status: 'healthy',
- lastCheck: new Date(),
- metrics: { cpuUsage: 10, memoryUsage: 50, taskCount: 2 },
- };
- mockHealthMonitor.getHealth.mockReturnValue(health);
-
- // When
- const result = await lifecycleManager.getHealth('agent-123');
-
- // Then
- expect(result).toEqual(health);
- });
- });
-});
diff --git a/v3/__tests__/unit/core/task-manager.test.ts b/v3/__tests__/unit/core/task-manager.test.ts
deleted file mode 100644
index a9d4f0c9a7..0000000000
--- a/v3/__tests__/unit/core/task-manager.test.ts
+++ /dev/null
@@ -1,717 +0,0 @@
-/**
- * V3 Claude-Flow Task Manager Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests task lifecycle management
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface, InteractionRecorder } from '../../helpers/create-mock';
-import { taskDefinitions, taskInstances, createTaskDefinition } from '../../fixtures/tasks';
-
-/**
- * Task manager interface (to be implemented)
- */
-interface ITaskManager {
- create(definition: TaskDefinition): Promise<Task>;
- execute(taskId: string): Promise<TaskResult>;
- cancel(taskId: string): Promise<void>;
- getStatus(taskId: string): Promise<TaskStatus>;
- list(filter?: TaskFilter): Promise<Task[]>;
-}
-
-/**
- * Task repository interface (collaborator)
- */
-interface ITaskRepository {
- save(task: Task): Promise<void>;
- findById(id: string): Promise<Task | null>;
- findAll(filter?: TaskFilter): Promise<Task[]>;
- update(id: string, updates: Partial<Task>): Promise<void>;
- delete(id: string): Promise<void>;
-}
-
-/**
- * Task executor interface (collaborator)
- */
-interface ITaskExecutor {
- run(task: Task): Promise<TaskResult>;
- abort(taskId: string): Promise<void>;
-}
-
-/**
- * Event publisher interface (collaborator)
- */
-interface IEventPublisher {
- publish(event: DomainEvent): Promise<void>;
-}
-
-interface TaskDefinition {
- name: string;
- type: string;
- payload: unknown;
- priority?: number;
-}
-
-interface Task {
- id: string;
- name: string;
- type: string;
- status: TaskStatus;
- payload: unknown;
- priority: number;
- createdAt: Date;
- startedAt?: Date;
- completedAt?: Date;
-}
-
-type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-
-interface TaskResult {
- taskId: string;
- success: boolean;
- output?: unknown;
- error?: Error;
- duration: number;
-}
-
-interface TaskFilter {
- status?: TaskStatus;
- type?: string;
- priority?: number;
-}
-
-interface DomainEvent {
- type: string;
- payload: unknown;
- timestamp: Date;
-}
-
-/**
- * Task manager implementation for testing
- */
-class TaskManager implements ITaskManager {
- constructor(
- private readonly repository: ITaskRepository,
- private readonly executor: ITaskExecutor,
- private readonly eventPublisher: IEventPublisher,
- private readonly idGenerator: () => string = () => `task-${Date.now()}`
- ) {}
-
- async create(definition: TaskDefinition): Promise<Task> {
- if (!definition.name || !definition.type) {
- throw new Error('Task name and type are required');
- }
-
- const task: Task = {
- id: this.idGenerator(),
- name: definition.name,
- type: definition.type,
- status: 'pending',
- payload: definition.payload,
- priority: definition.priority ?? 50,
- createdAt: new Date(),
- };
-
- await this.repository.save(task);
-
- await this.eventPublisher.publish({
- type: 'TaskCreated',
- payload: { taskId: task.id, name: task.name, type: task.type },
- timestamp: new Date(),
- });
-
- return task;
- }
-
- async execute(taskId: string): Promise<TaskResult> {
- const task = await this.repository.findById(taskId);
-
- if (!task) {
- throw new Error(`Task not found: ${taskId}`);
- }
-
- if (task.status !== 'pending') {
- throw new Error(`Task cannot be executed: current status is ${task.status}`);
- }
-
- // Update status to running
- await this.repository.update(taskId, {
- status: 'running',
- startedAt: new Date(),
- });
-
- await this.eventPublisher.publish({
- type: 'TaskStarted',
- payload: { taskId },
- timestamp: new Date(),
- });
-
- const startTime = Date.now();
-
- try {
- const result = await this.executor.run({ ...task, status: 'running' });
-
- // Update status to completed
- await this.repository.update(taskId, {
- status: 'completed',
- completedAt: new Date(),
- });
-
- await this.eventPublisher.publish({
- type: 'TaskCompleted',
- payload: { taskId, success: true, duration: result.duration },
- timestamp: new Date(),
- });
-
- return result;
- } catch (error) {
- // Update status to failed
- await this.repository.update(taskId, {
- status: 'failed',
- completedAt: new Date(),
- });
-
- await this.eventPublisher.publish({
- type: 'TaskFailed',
- payload: { taskId, error: (error as Error).message },
- timestamp: new Date(),
- });
-
- return {
- taskId,
- success: false,
- error: error as Error,
- duration: Date.now() - startTime,
- };
- }
- }
-
- async cancel(taskId: string): Promise<void> {
- const task = await this.repository.findById(taskId);
-
- if (!task) {
- throw new Error(`Task not found: ${taskId}`);
- }
-
- if (task.status === 'completed' || task.status === 'cancelled') {
- throw new Error(`Cannot cancel task: current status is ${task.status}`);
- }
-
- if (task.status === 'running') {
- await this.executor.abort(taskId);
- }
-
- await this.repository.update(taskId, {
- status: 'cancelled',
- completedAt: new Date(),
- });
-
- await this.eventPublisher.publish({
- type: 'TaskCancelled',
- payload: { taskId },
- timestamp: new Date(),
- });
- }
-
- async getStatus(taskId: string): Promise<TaskStatus> {
- const task = await this.repository.findById(taskId);
-
- if (!task) {
- throw new Error(`Task not found: ${taskId}`);
- }
-
- return task.status;
- }
-
- async list(filter?: TaskFilter): Promise<Task[]> {
- return this.repository.findAll(filter);
- }
-}
-
-describe('TaskManager', () => {
- let mockRepository: MockedInterface<ITaskRepository>;
- let mockExecutor: MockedInterface<ITaskExecutor>;
- let mockEventPublisher: MockedInterface<IEventPublisher>;
- let taskManager: TaskManager;
- let interactionRecorder: InteractionRecorder;
- const mockIdGenerator = vi.fn().mockReturnValue('task-123');
-
- beforeEach(() => {
- mockRepository = createMock<ITaskRepository>();
- mockExecutor = createMock<ITaskExecutor>();
- mockEventPublisher = createMock<IEventPublisher>();
- interactionRecorder = new InteractionRecorder();
-
- // Configure default mock behavior
- mockRepository.save.mockResolvedValue(undefined);
- mockRepository.findById.mockResolvedValue(null);
- mockRepository.findAll.mockResolvedValue([]);
- mockRepository.update.mockResolvedValue(undefined);
- mockRepository.delete.mockResolvedValue(undefined);
-
- mockExecutor.run.mockResolvedValue({
- taskId: 'task-123',
- success: true,
- duration: 100,
- });
- mockExecutor.abort.mockResolvedValue(undefined);
-
- mockEventPublisher.publish.mockResolvedValue(undefined);
-
- // Track interactions
- interactionRecorder.track('repository', mockRepository);
- interactionRecorder.track('executor', mockExecutor);
- interactionRecorder.track('events', mockEventPublisher);
-
- taskManager = new TaskManager(
- mockRepository,
- mockExecutor,
- mockEventPublisher,
- mockIdGenerator
- );
- });
-
- describe('create', () => {
- it('should save task to repository', async () => {
- // Given
- const definition = taskDefinitions.implementation;
-
- // When
- await taskManager.create(definition);
-
- // Then
- expect(mockRepository.save).toHaveBeenCalledWith(
- expect.objectContaining({
- name: definition.name,
- type: definition.type,
- status: 'pending',
- })
- );
- });
-
- it('should publish TaskCreated event', async () => {
- // Given
- const definition = taskDefinitions.implementation;
-
- // When
- await taskManager.create(definition);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskCreated',
- payload: expect.objectContaining({
- taskId: 'task-123',
- name: definition.name,
- }),
- })
- );
- });
-
- it('should save before publishing event', async () => {
- // Given
- const definition = taskDefinitions.implementation;
-
- // When
- await taskManager.create(definition);
-
- // Then
- const interactions = interactionRecorder.getInteractionOrder();
- const saveIndex = interactions.indexOf('repository.save');
- const publishIndex = interactions.indexOf('events.publish');
-
- expect(saveIndex).toBeLessThan(publishIndex);
- });
-
- it('should return created task with generated id', async () => {
- // Given
- const definition = taskDefinitions.implementation;
-
- // When
- const result = await taskManager.create(definition);
-
- // Then
- expect(result.id).toBe('task-123');
- expect(result.name).toBe(definition.name);
- expect(result.type).toBe(definition.type);
- expect(result.status).toBe('pending');
- });
-
- it('should use default priority when not specified', async () => {
- // Given
- const definition = { name: 'Test', type: 'test', payload: {} };
-
- // When
- const result = await taskManager.create(definition);
-
- // Then
- expect(result.priority).toBe(50);
- });
-
- it('should use provided priority', async () => {
- // Given
- const definition = { name: 'Test', type: 'test', payload: {}, priority: 100 };
-
- // When
- const result = await taskManager.create(definition);
-
- // Then
- expect(result.priority).toBe(100);
- });
-
- it('should throw error for missing name', async () => {
- // Given
- const definition = { name: '', type: 'test', payload: {} };
-
- // When/Then
- await expect(taskManager.create(definition)).rejects.toThrow(
- 'Task name and type are required'
- );
- });
-
- it('should throw error for missing type', async () => {
- // Given
- const definition = { name: 'Test', type: '', payload: {} };
-
- // When/Then
- await expect(taskManager.create(definition)).rejects.toThrow(
- 'Task name and type are required'
- );
- });
- });
-
- describe('execute', () => {
- it('should find task in repository', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- expect(mockRepository.findById).toHaveBeenCalledWith(task.id);
- });
-
- it('should update status to running before execution', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- expect(mockRepository.update).toHaveBeenCalledWith(
- task.id,
- expect.objectContaining({
- status: 'running',
- })
- );
- });
-
- it('should publish TaskStarted event', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskStarted',
- payload: { taskId: task.id },
- })
- );
- });
-
- it('should call executor run with task', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- expect(mockExecutor.run).toHaveBeenCalledWith(
- expect.objectContaining({
- id: task.id,
- status: 'running',
- })
- );
- });
-
- it('should update status to completed on success', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
- mockExecutor.run.mockResolvedValue({
- taskId: task.id,
- success: true,
- duration: 100,
- });
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- const updateCalls = mockRepository.update.mock.calls;
- const finalUpdate = updateCalls[updateCalls.length - 1];
- expect(finalUpdate[1]).toMatchObject({ status: 'completed' });
- });
-
- it('should publish TaskCompleted event on success', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskCompleted',
- })
- );
- });
-
- it('should update status to failed on error', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
- mockExecutor.run.mockRejectedValue(new Error('Execution failed'));
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- const updateCalls = mockRepository.update.mock.calls;
- const finalUpdate = updateCalls[updateCalls.length - 1];
- expect(finalUpdate[1]).toMatchObject({ status: 'failed' });
- });
-
- it('should publish TaskFailed event on error', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
- mockExecutor.run.mockRejectedValue(new Error('Execution failed'));
-
- // When
- await taskManager.execute(task.id);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskFailed',
- payload: expect.objectContaining({
- error: 'Execution failed',
- }),
- })
- );
- });
-
- it('should return result with error on failure', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
- const error = new Error('Execution failed');
- mockExecutor.run.mockRejectedValue(error);
-
- // When
- const result = await taskManager.execute(task.id);
-
- // Then
- expect(result.success).toBe(false);
- expect(result.error).toBe(error);
- });
-
- it('should throw error for non-existent task', async () => {
- // Given
- mockRepository.findById.mockResolvedValue(null);
-
- // When/Then
- await expect(taskManager.execute('non-existent')).rejects.toThrow(
- 'Task not found: non-existent'
- );
- });
-
- it('should throw error for already running task', async () => {
- // Given
- const task = { ...taskInstances.runningCodeReview };
- mockRepository.findById.mockResolvedValue(task);
-
- // When/Then
- await expect(taskManager.execute(task.id)).rejects.toThrow(
- 'Task cannot be executed: current status is running'
- );
- });
-
- it('should throw error for completed task', async () => {
- // Given
- const task = { ...taskInstances.completedUnitTesting };
- mockRepository.findById.mockResolvedValue(task);
-
- // When/Then
- await expect(taskManager.execute(task.id)).rejects.toThrow(
- 'Task cannot be executed: current status is completed'
- );
- });
- });
-
- describe('cancel', () => {
- it('should find task in repository', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.cancel(task.id);
-
- // Then
- expect(mockRepository.findById).toHaveBeenCalledWith(task.id);
- });
-
- it('should update status to cancelled', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.cancel(task.id);
-
- // Then
- expect(mockRepository.update).toHaveBeenCalledWith(
- task.id,
- expect.objectContaining({
- status: 'cancelled',
- })
- );
- });
-
- it('should abort running task', async () => {
- // Given
- const task = { ...taskInstances.runningCodeReview };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.cancel(task.id);
-
- // Then
- expect(mockExecutor.abort).toHaveBeenCalledWith(task.id);
- });
-
- it('should not abort pending task', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.cancel(task.id);
-
- // Then
- expect(mockExecutor.abort).not.toHaveBeenCalled();
- });
-
- it('should publish TaskCancelled event', async () => {
- // Given
- const task = { ...taskInstances.pendingSecurityScan };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- await taskManager.cancel(task.id);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskCancelled',
- payload: { taskId: task.id },
- })
- );
- });
-
- it('should throw error for non-existent task', async () => {
- // Given
- mockRepository.findById.mockResolvedValue(null);
-
- // When/Then
- await expect(taskManager.cancel('non-existent')).rejects.toThrow(
- 'Task not found: non-existent'
- );
- });
-
- it('should throw error for already completed task', async () => {
- // Given
- const task = { ...taskInstances.completedUnitTesting };
- mockRepository.findById.mockResolvedValue(task);
-
- // When/Then
- await expect(taskManager.cancel(task.id)).rejects.toThrow(
- 'Cannot cancel task: current status is completed'
- );
- });
-
- it('should throw error for already cancelled task', async () => {
- // Given
- const task = { ...taskInstances.cancelledSwarmCoordination };
- mockRepository.findById.mockResolvedValue(task);
-
- // When/Then
- await expect(taskManager.cancel(task.id)).rejects.toThrow(
- 'Cannot cancel task: current status is cancelled'
- );
- });
- });
-
- describe('getStatus', () => {
- it('should return task status from repository', async () => {
- // Given
- const task = { ...taskInstances.runningCodeReview };
- mockRepository.findById.mockResolvedValue(task);
-
- // When
- const result = await taskManager.getStatus(task.id);
-
- // Then
- expect(result).toBe('running');
- });
-
- it('should throw error for non-existent task', async () => {
- // Given
- mockRepository.findById.mockResolvedValue(null);
-
- // When/Then
- await expect(taskManager.getStatus('non-existent')).rejects.toThrow(
- 'Task not found: non-existent'
- );
- });
- });
-
- describe('list', () => {
- it('should delegate to repository findAll', async () => {
- // Given
- const filter = { status: 'pending' as TaskStatus };
-
- // When
- await taskManager.list(filter);
-
- // Then
- expect(mockRepository.findAll).toHaveBeenCalledWith(filter);
- });
-
- it('should return all tasks when no filter', async () => {
- // Given
- const tasks = [taskInstances.pendingSecurityScan, taskInstances.runningCodeReview];
- mockRepository.findAll.mockResolvedValue(tasks);
-
- // When
- const result = await taskManager.list();
-
- // Then
- expect(result).toEqual(tasks);
- });
- });
-});
diff --git a/v3/__tests__/unit/security/credential-generator.test.ts b/v3/__tests__/unit/security/credential-generator.test.ts
deleted file mode 100644
index b5343df373..0000000000
--- a/v3/__tests__/unit/security/credential-generator.test.ts
+++ /dev/null
@@ -1,182 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { CredentialGenerator } from '../../../security/credential-generator.js';
-
-describe('CredentialGenerator', () => {
- describe('generatePassword', () => {
- it('should generate passwords meeting complexity requirements', () => {
- const generator = new CredentialGenerator();
- const password = generator.generatePassword();
-
- expect(password.length).toBeGreaterThanOrEqual(32);
- expect(/[A-Z]/.test(password)).toBe(true);
- expect(/[a-z]/.test(password)).toBe(true);
- expect(/\d/.test(password)).toBe(true);
- });
-
- it('should generate unique passwords each time', () => {
- const generator = new CredentialGenerator();
- const passwords = new Set(Array.from({ length: 100 }, () => generator.generatePassword()));
- expect(passwords.size).toBe(100);
- });
-
- it('should respect custom length parameter', () => {
- const generator = new CredentialGenerator();
- const password = generator.generatePassword(64);
- expect(password.length).toBe(64);
- });
-
- it('should include special characters by default', () => {
- const generator = new CredentialGenerator();
- const password = generator.generatePassword();
- expect(/[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/.test(password)).toBe(true);
- });
- });
-
- describe('generateApiKey', () => {
- it('should generate API keys with prefix', () => {
- const generator = new CredentialGenerator();
- const key = generator.generateApiKey('test_');
- expect(key.key.startsWith('test_')).toBe(true);
- });
-
- it('should generate API keys with default prefix', () => {
- const generator = new CredentialGenerator();
- const key = generator.generateApiKey();
- expect(key.key.startsWith('cf_')).toBe(true);
- });
-
- it('should include keyId as UUID', () => {
- const generator = new CredentialGenerator();
- const key = generator.generateApiKey();
- expect(key.keyId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
- });
-
- it('should include createdAt timestamp', () => {
- const generator = new CredentialGenerator();
- const before = new Date();
- const key = generator.generateApiKey();
- const after = new Date();
- expect(key.createdAt.getTime()).toBeGreaterThanOrEqual(before.getTime());
- expect(key.createdAt.getTime()).toBeLessThanOrEqual(after.getTime());
- });
-
- it('should generate unique keys each time', () => {
- const generator = new CredentialGenerator();
- const keys = new Set(Array.from({ length: 100 }, () => generator.generateApiKey().key));
- expect(keys.size).toBe(100);
- });
- });
-
- describe('generateSecret', () => {
- it('should generate hex-encoded secrets', () => {
- const generator = new CredentialGenerator();
- const secret = generator.generateSecret();
- expect(/^[0-9a-f]+$/i.test(secret)).toBe(true);
- });
-
- it('should generate secrets with default length', () => {
- const generator = new CredentialGenerator();
- const secret = generator.generateSecret();
- expect(secret.length).toBe(64);
- });
-
- it('should generate secrets with custom length', () => {
- const generator = new CredentialGenerator();
- const secret = generator.generateSecret(128);
- expect(secret.length).toBe(128);
- });
- });
-
- describe('generateEncryptionKey', () => {
- it('should generate 64-character hex key (32 bytes)', () => {
- const generator = new CredentialGenerator();
- const key = generator.generateEncryptionKey();
- expect(key.length).toBe(64);
- expect(/^[0-9a-f]+$/i.test(key)).toBe(true);
- });
- });
-
- describe('generateInstallationCredentials', () => {
- it('should generate complete credential set', () => {
- const generator = new CredentialGenerator();
- const creds = generator.generateInstallationCredentials();
-
- expect(creds.adminPassword).toBeDefined();
- expect(creds.servicePassword).toBeDefined();
- expect(creds.jwtSecret).toBeDefined();
- expect(creds.sessionSecret).toBeDefined();
- expect(creds.encryptionKey).toBeDefined();
- expect(creds.generatedAt).toBeInstanceOf(Date);
- });
-
- it('should set expiration when specified', () => {
- const generator = new CredentialGenerator();
- const creds = generator.generateInstallationCredentials(30);
-
- expect(creds.expiresAt).toBeDefined();
- const expectedExpiry = new Date(creds.generatedAt.getTime() + 30 * 24 * 60 * 60 * 1000);
- expect(creds.expiresAt!.getTime()).toBeCloseTo(expectedExpiry.getTime(), -3);
- });
- });
-
- describe('configuration validation', () => {
- it('should reject password length below 16', () => {
- expect(() => new CredentialGenerator({ passwordLength: 8 }))
- .toThrow('Password length must be at least 16 characters');
- });
-
- it('should reject API key length below 32', () => {
- expect(() => new CredentialGenerator({ apiKeyLength: 16 }))
- .toThrow('API key length must be at least 32 characters');
- });
-
- it('should reject secret length below 32', () => {
- expect(() => new CredentialGenerator({ secretLength: 16 }))
- .toThrow('Secret length must be at least 32 characters');
- });
- });
-
- describe('utility methods', () => {
- it('should generate session tokens', () => {
- const generator = new CredentialGenerator();
- const token = generator.generateSessionToken();
- expect(token.length).toBe(64);
- });
-
- it('should generate CSRF tokens', () => {
- const generator = new CredentialGenerator();
- const token = generator.generateCsrfToken();
- expect(token).toBeDefined();
- expect(token.length).toBeGreaterThan(0);
- });
-
- it('should generate nonces', () => {
- const generator = new CredentialGenerator();
- const nonce = generator.generateNonce();
- expect(nonce.length).toBe(32);
- expect(/^[0-9a-f]+$/i.test(nonce)).toBe(true);
- });
- });
-
- describe('output generation', () => {
- it('should create env script format', () => {
- const generator = new CredentialGenerator();
- const creds = generator.generateInstallationCredentials();
- const script = generator.createEnvScript(creds);
-
- expect(script).toContain('CLAUDE_FLOW_ADMIN_PASSWORD');
- expect(script).toContain('CLAUDE_FLOW_JWT_SECRET');
- expect(script).toContain('export');
- });
-
- it('should create JSON config format', () => {
- const generator = new CredentialGenerator();
- const creds = generator.generateInstallationCredentials();
- const json = generator.createJsonConfig(creds);
-
- const parsed = JSON.parse(json);
- expect(parsed['claude-flow/admin-password']).toBeDefined();
- expect(parsed['claude-flow/jwt-secret']).toBeDefined();
- });
- });
-});
diff --git a/v3/__tests__/unit/security/password-hasher.test.ts b/v3/__tests__/unit/security/password-hasher.test.ts
deleted file mode 100644
index c96aff7a8e..0000000000
--- a/v3/__tests__/unit/security/password-hasher.test.ts
+++ /dev/null
@@ -1,359 +0,0 @@
-/**
- * V3 Claude-Flow Password Hasher Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests password hashing and verification behavior
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, createMockWithBehavior, type MockedInterface } from '../../helpers/create-mock';
-import { securityConfigs } from '../../fixtures/configurations';
-
-/**
- * Password hasher interface (to be implemented)
- */
-interface IPasswordHasher {
- hash(password: string): Promise<string>;
- verify(password: string, hash: string): Promise<boolean>;
- needsRehash(hash: string): boolean;
-}
-
-/**
- * Crypto provider interface (collaborator)
- */
-interface ICryptoProvider {
- argon2Hash(password: string, options: Argon2Options): Promise<string>;
- argon2Verify(hash: string, password: string): Promise<boolean>;
- generateSalt(length: number): Promise<string>;
-}
-
-interface Argon2Options {
- memoryCost: number;
- timeCost: number;
- parallelism: number;
- salt?: string;
-}
-
-/**
- * Password hasher implementation for testing
- */
-class PasswordHasher implements IPasswordHasher {
- constructor(
- private readonly cryptoProvider: ICryptoProvider,
- private readonly config: typeof securityConfigs.strict.hashing
- ) {}
-
- async hash(password: string): Promise<string> {
- if (!password || password.length < 8) {
- throw new Error('Password must be at least 8 characters');
- }
-
- const salt = await this.cryptoProvider.generateSalt(16);
-
- return this.cryptoProvider.argon2Hash(password, {
- memoryCost: this.config.memoryCost ?? 65536,
- timeCost: this.config.timeCost ?? 3,
- parallelism: this.config.parallelism ?? 4,
- salt,
- });
- }
-
- async verify(password: string, hash: string): Promise<boolean> {
- if (!password || !hash) {
- return false;
- }
-
- return this.cryptoProvider.argon2Verify(hash, password);
- }
-
- needsRehash(hash: string): boolean {
- // Check if hash uses current algorithm and parameters
- const currentVersion = `$argon2id$v=19$m=${this.config.memoryCost},t=${this.config.timeCost},p=${this.config.parallelism}`;
- return !hash.startsWith(currentVersion);
- }
-}
-
-describe('PasswordHasher', () => {
- let mockCryptoProvider: MockedInterface<ICryptoProvider>;
- let passwordHasher: PasswordHasher;
- const hashingConfig = securityConfigs.strict.hashing;
-
- beforeEach(() => {
- mockCryptoProvider = createMock<ICryptoProvider>();
-
- // Configure default mock behavior
- mockCryptoProvider.generateSalt.mockResolvedValue('randomsalt16byte');
- mockCryptoProvider.argon2Hash.mockResolvedValue(
- '$argon2id$v=19$m=65536,t=3,p=4$cmFuZG9tc2FsdA$hashedpassword'
- );
- mockCryptoProvider.argon2Verify.mockResolvedValue(true);
-
- passwordHasher = new PasswordHasher(mockCryptoProvider, hashingConfig);
- });
-
- describe('hash', () => {
- it('should generate salt before hashing', async () => {
- // Given
- const password = 'securePassword123!';
-
- // When
- await passwordHasher.hash(password);
-
- // Then - verify interaction
- expect(mockCryptoProvider.generateSalt).toHaveBeenCalledWith(16);
- expect(mockCryptoProvider.generateSalt).toHaveBeenCalledBefore(
- mockCryptoProvider.argon2Hash
- );
- });
-
- it('should hash password with configured parameters', async () => {
- // Given
- const password = 'securePassword123!';
-
- // When
- await passwordHasher.hash(password);
-
- // Then - verify interaction with correct parameters
- expect(mockCryptoProvider.argon2Hash).toHaveBeenCalledWith(
- password,
- expect.objectContaining({
- memoryCost: 65536,
- timeCost: 3,
- parallelism: 4,
- })
- );
- });
-
- it('should return hash from crypto provider', async () => {
- // Given
- const password = 'securePassword123!';
- const expectedHash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
- mockCryptoProvider.argon2Hash.mockResolvedValue(expectedHash);
-
- // When
- const result = await passwordHasher.hash(password);
-
- // Then
- expect(result).toBe(expectedHash);
- });
-
- it('should reject passwords shorter than 8 characters', async () => {
- // Given
- const shortPassword = 'short';
-
- // When/Then
- await expect(passwordHasher.hash(shortPassword)).rejects.toThrow(
- 'Password must be at least 8 characters'
- );
-
- // Verify no interaction with crypto provider
- expect(mockCryptoProvider.generateSalt).not.toHaveBeenCalled();
- expect(mockCryptoProvider.argon2Hash).not.toHaveBeenCalled();
- });
-
- it('should reject empty passwords', async () => {
- // Given
- const emptyPassword = '';
-
- // When/Then
- await expect(passwordHasher.hash(emptyPassword)).rejects.toThrow(
- 'Password must be at least 8 characters'
- );
- });
-
- it('should use generated salt in hash options', async () => {
- // Given
- const password = 'securePassword123!';
- const generatedSalt = 'unique-salt-value';
- mockCryptoProvider.generateSalt.mockResolvedValue(generatedSalt);
-
- // When
- await passwordHasher.hash(password);
-
- // Then
- expect(mockCryptoProvider.argon2Hash).toHaveBeenCalledWith(
- password,
- expect.objectContaining({
- salt: generatedSalt,
- })
- );
- });
- });
-
- describe('verify', () => {
- it('should delegate verification to crypto provider', async () => {
- // Given
- const password = 'securePassword123!';
- const hash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
-
- // When
- await passwordHasher.verify(password, hash);
-
- // Then - verify interaction
- expect(mockCryptoProvider.argon2Verify).toHaveBeenCalledWith(hash, password);
- });
-
- it('should return true for valid password', async () => {
- // Given
- const password = 'securePassword123!';
- const hash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
- mockCryptoProvider.argon2Verify.mockResolvedValue(true);
-
- // When
- const result = await passwordHasher.verify(password, hash);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return false for invalid password', async () => {
- // Given
- const password = 'wrongPassword123!';
- const hash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
- mockCryptoProvider.argon2Verify.mockResolvedValue(false);
-
- // When
- const result = await passwordHasher.verify(password, hash);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for empty password', async () => {
- // Given
- const emptyPassword = '';
- const hash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
-
- // When
- const result = await passwordHasher.verify(emptyPassword, hash);
-
- // Then
- expect(result).toBe(false);
- expect(mockCryptoProvider.argon2Verify).not.toHaveBeenCalled();
- });
-
- it('should return false for empty hash', async () => {
- // Given
- const password = 'securePassword123!';
- const emptyHash = '';
-
- // When
- const result = await passwordHasher.verify(password, emptyHash);
-
- // Then
- expect(result).toBe(false);
- expect(mockCryptoProvider.argon2Verify).not.toHaveBeenCalled();
- });
- });
-
- describe('needsRehash', () => {
- it('should return false for hash with current parameters', () => {
- // Given
- const currentHash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
-
- // When
- const result = passwordHasher.needsRehash(currentHash);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return true for hash with different memory cost', () => {
- // Given
- const oldHash = '$argon2id$v=19$m=32768,t=3,p=4$salt$hash';
-
- // When
- const result = passwordHasher.needsRehash(oldHash);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return true for hash with different time cost', () => {
- // Given
- const oldHash = '$argon2id$v=19$m=65536,t=2,p=4$salt$hash';
-
- // When
- const result = passwordHasher.needsRehash(oldHash);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return true for hash with different parallelism', () => {
- // Given
- const oldHash = '$argon2id$v=19$m=65536,t=3,p=2$salt$hash';
-
- // When
- const result = passwordHasher.needsRehash(oldHash);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return true for bcrypt hash', () => {
- // Given
- const bcryptHash = '$2b$10$salt.hash';
-
- // When
- const result = passwordHasher.needsRehash(bcryptHash);
-
- // Then
- expect(result).toBe(true);
- });
- });
-
- describe('error handling', () => {
- it('should propagate crypto provider errors on hash', async () => {
- // Given
- const password = 'securePassword123!';
- const cryptoError = new Error('Crypto operation failed');
- mockCryptoProvider.argon2Hash.mockRejectedValue(cryptoError);
-
- // When/Then
- await expect(passwordHasher.hash(password)).rejects.toThrow('Crypto operation failed');
- });
-
- it('should propagate crypto provider errors on verify', async () => {
- // Given
- const password = 'securePassword123!';
- const hash = '$argon2id$v=19$m=65536,t=3,p=4$salt$hash';
- const cryptoError = new Error('Verification failed');
- mockCryptoProvider.argon2Verify.mockRejectedValue(cryptoError);
-
- // When/Then
- await expect(passwordHasher.verify(password, hash)).rejects.toThrow(
- 'Verification failed'
- );
- });
- });
-
- describe('interaction verification', () => {
- it('should not call argon2Hash if salt generation fails', async () => {
- // Given
- const password = 'securePassword123!';
- mockCryptoProvider.generateSalt.mockRejectedValue(new Error('Salt generation failed'));
-
- // When
- try {
- await passwordHasher.hash(password);
- } catch {
- // Expected to fail
- }
-
- // Then
- expect(mockCryptoProvider.argon2Hash).not.toHaveBeenCalled();
- });
-
- it('should only call crypto provider once per operation', async () => {
- // Given
- const password = 'securePassword123!';
-
- // When
- await passwordHasher.hash(password);
-
- // Then
- expect(mockCryptoProvider.generateSalt).toHaveBeenCalledTimes(1);
- expect(mockCryptoProvider.argon2Hash).toHaveBeenCalledTimes(1);
- });
- });
-});
diff --git a/v3/__tests__/unit/security/path-validator.test.ts b/v3/__tests__/unit/security/path-validator.test.ts
deleted file mode 100644
index 63fb7843f2..0000000000
--- a/v3/__tests__/unit/security/path-validator.test.ts
+++ /dev/null
@@ -1,509 +0,0 @@
-/**
- * V3 Claude-Flow Path Validator Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests path validation for security (CVE-1, CVE-2 prevention)
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface } from '../../helpers/create-mock';
-import { securityConfigs } from '../../fixtures/configurations';
-
-/**
- * Path validator interface (to be implemented)
- */
-interface IPathValidator {
- isValid(path: string): boolean;
- normalize(path: string): string;
- isWithinAllowedDirectory(path: string): boolean;
- sanitize(path: string): string;
-}
-
-/**
- * File system provider interface (collaborator)
- */
-interface IFileSystemProvider {
- exists(path: string): Promise<boolean>;
- isDirectory(path: string): Promise<boolean>;
- realPath(path: string): Promise<string>;
-}
-
-/**
- * Path utility interface (collaborator)
- */
-interface IPathUtils {
- normalize(path: string): string;
- resolve(basePath: string, relativePath: string): string;
- isAbsolute(path: string): boolean;
- dirname(path: string): string;
-}
-
-/**
- * Path validator implementation for testing
- */
-class PathValidator implements IPathValidator {
- constructor(
- private readonly pathUtils: IPathUtils,
- private readonly config: typeof securityConfigs.strict.paths
- ) {}
-
- isValid(path: string): boolean {
- if (!path || typeof path !== 'string') {
- return false;
- }
-
- if (path.length > this.config.maxPathLength) {
- return false;
- }
-
- // Check for blocked patterns
- for (const pattern of this.config.blockedPatterns) {
- if (path.includes(pattern)) {
- return false;
- }
- }
-
- // Check for null bytes
- if (path.includes('\0')) {
- return false;
- }
-
- return true;
- }
-
- normalize(path: string): string {
- return this.pathUtils.normalize(path);
- }
-
- isWithinAllowedDirectory(path: string): boolean {
- const normalizedPath = this.pathUtils.normalize(path);
-
- for (const allowedDir of this.config.allowedDirectories) {
- const normalizedAllowed = this.pathUtils.normalize(allowedDir);
- if (normalizedPath.startsWith(normalizedAllowed)) {
- return true;
- }
- }
-
- return false;
- }
-
- sanitize(path: string): string {
- let sanitized = path;
-
- // Remove blocked patterns
- for (const pattern of this.config.blockedPatterns) {
- sanitized = sanitized.split(pattern).join('');
- }
-
- // Remove null bytes
- sanitized = sanitized.replace(/\0/g, '');
-
- // Truncate if too long
- if (sanitized.length > this.config.maxPathLength) {
- sanitized = sanitized.slice(0, this.config.maxPathLength);
- }
-
- return this.pathUtils.normalize(sanitized);
- }
-}
-
-describe('PathValidator', () => {
- let mockPathUtils: MockedInterface<IPathUtils>;
- let pathValidator: PathValidator;
- const pathConfig = securityConfigs.strict.paths;
-
- beforeEach(() => {
- mockPathUtils = createMock<IPathUtils>();
-
- // Configure default mock behavior
- mockPathUtils.normalize.mockImplementation((p: string) => p.replace(/\/+/g, '/'));
- mockPathUtils.resolve.mockImplementation((base: string, rel: string) => `${base}/${rel}`);
- mockPathUtils.isAbsolute.mockReturnValue(false);
- mockPathUtils.dirname.mockImplementation((p: string) => p.split('/').slice(0, -1).join('/'));
-
- pathValidator = new PathValidator(mockPathUtils, pathConfig);
- });
-
- describe('isValid', () => {
- it('should return false for empty path', () => {
- // Given
- const emptyPath = '';
-
- // When
- const result = pathValidator.isValid(emptyPath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for null path', () => {
- // Given
- const nullPath = null as unknown as string;
-
- // When
- const result = pathValidator.isValid(nullPath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for path exceeding max length', () => {
- // Given
- const longPath = 'a'.repeat(pathConfig.maxPathLength + 1);
-
- // When
- const result = pathValidator.isValid(longPath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return true for path at exactly max length', () => {
- // Given
- const exactPath = 'a'.repeat(pathConfig.maxPathLength);
-
- // When
- const result = pathValidator.isValid(exactPath);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return false for path with directory traversal (../)', () => {
- // Given - CVE-1 prevention
- const traversalPath = '../../../etc/passwd';
-
- // When
- const result = pathValidator.isValid(traversalPath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for path with home directory reference (~/)', () => {
- // Given - CVE-1 prevention
- const homePath = '~/.ssh/id_rsa';
-
- // When
- const result = pathValidator.isValid(homePath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for path to /etc/', () => {
- // Given - CVE-2 prevention
- const etcPath = '/etc/shadow';
-
- // When
- const result = pathValidator.isValid(etcPath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for path to /tmp/', () => {
- // Given
- const tmpPath = '/tmp/malicious.sh';
-
- // When
- const result = pathValidator.isValid(tmpPath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return false for path with null bytes', () => {
- // Given - Null byte injection prevention
- const nullBytePath = 'file.txt\0.exe';
-
- // When
- const result = pathValidator.isValid(nullBytePath);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should return true for valid relative path', () => {
- // Given
- const validPath = 'src/modules/security/index.ts';
-
- // When
- const result = pathValidator.isValid(validPath);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return true for path within allowed directory', () => {
- // Given
- const validPath = './v3/src/security/hasher.ts';
-
- // When
- const result = pathValidator.isValid(validPath);
-
- // Then
- expect(result).toBe(true);
- });
- });
-
- describe('normalize', () => {
- it('should delegate to path utils for normalization', () => {
- // Given
- const path = './src/../src/file.ts';
- mockPathUtils.normalize.mockReturnValue('/normalized/path');
-
- // When
- const result = pathValidator.normalize(path);
-
- // Then
- expect(mockPathUtils.normalize).toHaveBeenCalledWith(path);
- expect(result).toBe('/normalized/path');
- });
-
- it('should normalize multiple slashes', () => {
- // Given
- const path = 'src///modules//security//index.ts';
-
- // When
- const result = pathValidator.normalize(path);
-
- // Then
- expect(mockPathUtils.normalize).toHaveBeenCalledWith(path);
- });
- });
-
- describe('isWithinAllowedDirectory', () => {
- it('should return true for path within ./v3/', () => {
- // Given
- const path = './v3/src/security/hasher.ts';
- mockPathUtils.normalize.mockImplementation((p: string) => p);
-
- // When
- const result = pathValidator.isWithinAllowedDirectory(path);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return true for path within ./src/', () => {
- // Given
- const path = './src/modules/core/index.ts';
- mockPathUtils.normalize.mockImplementation((p: string) => p);
-
- // When
- const result = pathValidator.isWithinAllowedDirectory(path);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return true for path within ./tests/', () => {
- // Given
- const path = './tests/unit/security.test.ts';
- mockPathUtils.normalize.mockImplementation((p: string) => p);
-
- // When
- const result = pathValidator.isWithinAllowedDirectory(path);
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should return false for path outside allowed directories', () => {
- // Given
- const path = '/usr/local/bin/malicious';
- mockPathUtils.normalize.mockImplementation((p: string) => p);
-
- // When
- const result = pathValidator.isWithinAllowedDirectory(path);
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should normalize path before checking', () => {
- // Given
- const path = './v3/../v3/src/file.ts';
- mockPathUtils.normalize.mockReturnValue('./v3/src/file.ts');
-
- // When
- pathValidator.isWithinAllowedDirectory(path);
-
- // Then
- expect(mockPathUtils.normalize).toHaveBeenCalledWith(path);
- });
- });
-
- describe('sanitize', () => {
- it('should remove directory traversal patterns', () => {
- // Given
- const unsafePath = '../../../etc/passwd';
-
- // When
- const result = pathValidator.sanitize(unsafePath);
-
- // Then
- expect(result).not.toContain('../');
- expect(mockPathUtils.normalize).toHaveBeenCalled();
- });
-
- it('should remove home directory references', () => {
- // Given
- const unsafePath = '~/.ssh/id_rsa';
-
- // When
- const result = pathValidator.sanitize(unsafePath);
-
- // Then
- expect(result).not.toContain('~/');
- });
-
- it('should remove /etc/ references', () => {
- // Given
- const unsafePath = 'some/path/etc/passwd';
-
- // When
- const result = pathValidator.sanitize(unsafePath);
-
- // Then
- expect(result).not.toContain('/etc/');
- });
-
- it('should remove null bytes', () => {
- // Given
- const unsafePath = 'file.txt\0.exe';
-
- // When
- const result = pathValidator.sanitize(unsafePath);
-
- // Then
- expect(result).not.toContain('\0');
- });
-
- it('should truncate paths exceeding max length', () => {
- // Given
- const longPath = 'a'.repeat(pathConfig.maxPathLength + 100);
-
- // When
- const result = pathValidator.sanitize(longPath);
-
- // Then
- expect(result.length).toBeLessThanOrEqual(pathConfig.maxPathLength);
- });
-
- it('should normalize the sanitized path', () => {
- // Given
- const path = 'valid/path/file.ts';
-
- // When
- pathValidator.sanitize(path);
-
- // Then
- expect(mockPathUtils.normalize).toHaveBeenCalled();
- });
- });
-
- describe('CVE prevention scenarios', () => {
- it('should block CVE-1: directory traversal attack', () => {
- // Given - Various traversal attempts
- const attacks = [
- '../../../etc/passwd',
- '..\\..\\..\\Windows\\System32\\config\\SAM',
- 'valid/path/../../../etc/passwd',
- '....//....//....//etc/passwd',
- ];
-
- // When/Then
- for (const attack of attacks) {
- expect(pathValidator.isValid(attack)).toBe(false);
- }
- });
-
- it('should block CVE-2: absolute path injection', () => {
- // Given - Absolute path attempts
- const attacks = [
- '/etc/passwd',
- '/var/log/auth.log',
- '/tmp/malicious',
- ];
-
- // When/Then
- for (const attack of attacks) {
- expect(pathValidator.isValid(attack)).toBe(false);
- }
- });
-
- it('should block CVE-3: null byte injection', () => {
- // Given - Null byte attempts
- const attacks = [
- 'file.txt\0',
- 'image.png\0.exe',
- '\0/etc/passwd',
- ];
-
- // When/Then
- for (const attack of attacks) {
- expect(pathValidator.isValid(attack)).toBe(false);
- }
- });
-
- it('should block encoded traversal attempts', () => {
- // Given - URL encoded traversal
- const path = '%2e%2e%2f%2e%2e%2f%2e%2e%2fetc/passwd';
-
- // When - After decoding, should still be blocked
- const decoded = decodeURIComponent(path);
- const result = pathValidator.isValid(decoded);
-
- // Then
- expect(result).toBe(false);
- });
- });
-
- describe('edge cases', () => {
- it('should handle Windows-style paths', () => {
- // Given
- const windowsPath = 'C:\\Users\\test\\file.txt';
-
- // When
- const result = pathValidator.isValid(windowsPath);
-
- // Then - Windows paths should be evaluated based on patterns
- expect(typeof result).toBe('boolean');
- });
-
- it('should handle unicode in paths', () => {
- // Given
- const unicodePath = 'src/modules/\u0000.ts';
-
- // When
- const result = pathValidator.isValid(unicodePath);
-
- // Then
- expect(result).toBe(false); // Contains null character
- });
-
- it('should handle paths with only dots', () => {
- // Given
- const dotsPath = '...';
-
- // When
- const result = pathValidator.isValid(dotsPath);
-
- // Then
- expect(result).toBe(true); // Not a traversal pattern
- });
-
- it('should handle paths with special characters', () => {
- // Given
- const specialPath = 'src/file-name_v2.0.1.ts';
-
- // When
- const result = pathValidator.isValid(specialPath);
-
- // Then
- expect(result).toBe(true);
- });
- });
-});
diff --git a/v3/__tests__/unit/security/safe-executor.test.ts b/v3/__tests__/unit/security/safe-executor.test.ts
deleted file mode 100644
index f6dc9c496b..0000000000
--- a/v3/__tests__/unit/security/safe-executor.test.ts
+++ /dev/null
@@ -1,667 +0,0 @@
-/**
- * V3 Claude-Flow Safe Executor Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests secure command execution (CVE-3 prevention)
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface } from '../../helpers/create-mock';
-import { securityConfigs } from '../../fixtures/configurations';
-
-/**
- * Safe executor interface (to be implemented)
- */
-interface ISafeExecutor {
- execute(command: string, args?: string[], options?: ExecuteOptions): Promise<ExecuteResult>;
- isCommandAllowed(command: string): boolean;
- sanitizeArgs(args: string[]): string[];
-}
-
-/**
- * Process spawner interface (collaborator)
- */
-interface IProcessSpawner {
- spawn(command: string, args: string[], options: SpawnOptions): Promise<SpawnResult>;
- kill(pid: number): Promise<void>;
-}
-
-/**
- * Command validator interface (collaborator)
- */
-interface ICommandValidator {
- extractCommand(input: string): string;
- isBuiltin(command: string): boolean;
- resolveCommand(command: string): Promise<string | null>;
-}
-
-interface ExecuteOptions {
- timeout?: number;
- cwd?: string;
- env?: Record<string, string>;
- shell?: boolean;
-}
-
-interface ExecuteResult {
- stdout: string;
- stderr: string;
- exitCode: number;
- killed: boolean;
-}
-
-interface SpawnOptions {
- cwd?: string;
- env?: Record<string, string>;
- timeout?: number;
- shell?: boolean;
-}
-
-interface SpawnResult {
- pid: number;
- stdout: string;
- stderr: string;
- exitCode: number;
- signal?: string;
-}
-
-/**
- * Safe executor implementation for testing
- */
-class SafeExecutor implements ISafeExecutor {
- constructor(
- private readonly spawner: IProcessSpawner,
- private readonly validator: ICommandValidator,
- private readonly config: typeof securityConfigs.strict.execution
- ) {}
-
- async execute(
- command: string,
- args: string[] = [],
- options: ExecuteOptions = {}
- ): Promise<ExecuteResult> {
- // Extract base command
- const baseCommand = this.validator.extractCommand(command);
-
- // Check if command is allowed
- if (!this.isCommandAllowed(baseCommand)) {
- throw new Error(`Command not allowed: ${baseCommand}`);
- }
-
- // Sanitize arguments
- const sanitizedArgs = this.sanitizeArgs(args);
-
- // Apply shell restriction from config
- const spawnOptions: SpawnOptions = {
- cwd: options.cwd,
- env: options.env,
- timeout: options.timeout ?? this.config.timeout,
- shell: this.config.shell, // Always use config, ignore user option
- };
-
- const result = await this.spawner.spawn(baseCommand, sanitizedArgs, spawnOptions);
-
- return {
- stdout: result.stdout,
- stderr: result.stderr,
- exitCode: result.exitCode,
- killed: result.signal !== undefined,
- };
- }
-
- isCommandAllowed(command: string): boolean {
- const baseCommand = this.validator.extractCommand(command);
-
- // Check blocked commands first
- if (this.config.blockedCommands.includes(baseCommand)) {
- return false;
- }
-
- // Check allowed commands
- return this.config.allowedCommands.includes(baseCommand);
- }
-
- sanitizeArgs(args: string[]): string[] {
- return args.map(arg => {
- // Remove shell metacharacters
- let sanitized = arg
- .replace(/[;&|`$()]/g, '')
- .replace(/\n/g, '')
- .replace(/\r/g, '');
-
- // Remove command substitution
- sanitized = sanitized.replace(/\$\([^)]*\)/g, '');
- sanitized = sanitized.replace(/`[^`]*`/g, '');
-
- // Remove redirection
- sanitized = sanitized.replace(/[<>]/g, '');
-
- return sanitized;
- });
- }
-}
-
-describe('SafeExecutor', () => {
- let mockSpawner: MockedInterface<IProcessSpawner>;
- let mockValidator: MockedInterface<ICommandValidator>;
- let safeExecutor: SafeExecutor;
- const executionConfig = securityConfigs.strict.execution;
-
- beforeEach(() => {
- mockSpawner = createMock<IProcessSpawner>();
- mockValidator = createMock<ICommandValidator>();
-
- // Configure default mock behavior
- mockValidator.extractCommand.mockImplementation((input: string) => input.split(' ')[0]);
- mockValidator.isBuiltin.mockReturnValue(false);
- mockValidator.resolveCommand.mockResolvedValue('/usr/bin/npm');
-
- mockSpawner.spawn.mockResolvedValue({
- pid: 12345,
- stdout: 'command output',
- stderr: '',
- exitCode: 0,
- });
-
- safeExecutor = new SafeExecutor(mockSpawner, mockValidator, executionConfig);
- });
-
- describe('execute', () => {
- it('should extract base command before execution', async () => {
- // Given
- const command = 'npm install';
-
- // When
- await safeExecutor.execute(command);
-
- // Then
- expect(mockValidator.extractCommand).toHaveBeenCalledWith(command);
- });
-
- it('should spawn process with sanitized arguments', async () => {
- // Given
- const command = 'npm';
- const args = ['install', '--save'];
-
- // When
- await safeExecutor.execute(command, args);
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- ['install', '--save'],
- expect.any(Object)
- );
- });
-
- it('should use config timeout by default', async () => {
- // Given
- const command = 'npm';
-
- // When
- await safeExecutor.execute(command);
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- [],
- expect.objectContaining({
- timeout: executionConfig.timeout,
- })
- );
- });
-
- it('should respect custom timeout option', async () => {
- // Given
- const command = 'npm';
- const customTimeout = 60000;
-
- // When
- await safeExecutor.execute(command, [], { timeout: customTimeout });
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- [],
- expect.objectContaining({
- timeout: customTimeout,
- })
- );
- });
-
- it('should always use shell setting from config', async () => {
- // Given
- const command = 'npm';
-
- // When
- await safeExecutor.execute(command, [], { shell: true }); // User tries to enable shell
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- [],
- expect.objectContaining({
- shell: executionConfig.shell, // Should be config value (false)
- })
- );
- });
-
- it('should return execution result', async () => {
- // Given
- const command = 'npm';
- mockSpawner.spawn.mockResolvedValue({
- pid: 12345,
- stdout: 'success output',
- stderr: 'warning',
- exitCode: 0,
- });
-
- // When
- const result = await safeExecutor.execute(command);
-
- // Then
- expect(result).toEqual({
- stdout: 'success output',
- stderr: 'warning',
- exitCode: 0,
- killed: false,
- });
- });
-
- it('should report killed status when signal present', async () => {
- // Given
- const command = 'npm';
- mockSpawner.spawn.mockResolvedValue({
- pid: 12345,
- stdout: '',
- stderr: 'timeout',
- exitCode: 137,
- signal: 'SIGKILL',
- });
-
- // When
- const result = await safeExecutor.execute(command);
-
- // Then
- expect(result.killed).toBe(true);
- });
-
- it('should throw error for blocked command', async () => {
- // Given
- const command = 'rm';
- mockValidator.extractCommand.mockReturnValue('rm');
-
- // When/Then
- await expect(safeExecutor.execute(command)).rejects.toThrow(
- 'Command not allowed: rm'
- );
- expect(mockSpawner.spawn).not.toHaveBeenCalled();
- });
-
- it('should throw error for command not in allowed list', async () => {
- // Given
- const command = 'wget';
- mockValidator.extractCommand.mockReturnValue('wget');
-
- // When/Then
- await expect(safeExecutor.execute(command)).rejects.toThrow(
- 'Command not allowed: wget'
- );
- });
- });
-
- describe('isCommandAllowed', () => {
- it('should allow npm command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('npm');
-
- // When
- const result = safeExecutor.isCommandAllowed('npm');
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should allow npx command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('npx');
-
- // When
- const result = safeExecutor.isCommandAllowed('npx');
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should allow node command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('node');
-
- // When
- const result = safeExecutor.isCommandAllowed('node');
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should allow git command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('git');
-
- // When
- const result = safeExecutor.isCommandAllowed('git');
-
- // Then
- expect(result).toBe(true);
- });
-
- it('should block rm command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('rm');
-
- // When
- const result = safeExecutor.isCommandAllowed('rm');
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should block del command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('del');
-
- // When
- const result = safeExecutor.isCommandAllowed('del');
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should block format command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('format');
-
- // When
- const result = safeExecutor.isCommandAllowed('format');
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should block dd command', () => {
- // Given
- mockValidator.extractCommand.mockReturnValue('dd');
-
- // When
- const result = safeExecutor.isCommandAllowed('dd');
-
- // Then
- expect(result).toBe(false);
- });
-
- it('should block blocked command even if in allowed list', () => {
- // Given - hypothetical scenario where command appears in both lists
- // Blocked should take precedence
- mockValidator.extractCommand.mockReturnValue('rm');
-
- // When
- const result = safeExecutor.isCommandAllowed('rm');
-
- // Then
- expect(result).toBe(false);
- });
- });
-
- describe('sanitizeArgs', () => {
- it('should remove semicolon from arguments', () => {
- // Given
- const args = ['install;rm -rf /'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain(';');
- });
-
- it('should remove pipe operator from arguments', () => {
- // Given
- const args = ['install | cat /etc/passwd'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain('|');
- });
-
- it('should remove ampersand from arguments', () => {
- // Given
- const args = ['install && rm -rf /'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain('&');
- });
-
- it('should remove backticks from arguments', () => {
- // Given
- const args = ['install `rm -rf /`'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain('`');
- });
-
- it('should remove $() command substitution from arguments', () => {
- // Given
- const args = ['install $(rm -rf /)'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain('$(');
- expect(result[0]).not.toContain(')');
- });
-
- it('should remove newlines from arguments', () => {
- // Given
- const args = ['install\nrm -rf /'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain('\n');
- });
-
- it('should remove redirection operators from arguments', () => {
- // Given
- const args = ['install > /dev/null', 'test < /etc/passwd'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).not.toContain('>');
- expect(result[1]).not.toContain('<');
- });
-
- it('should preserve safe argument content', () => {
- // Given
- const args = ['--save-dev', '[email protected]', './src/index.ts'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result).toEqual(['--save-dev', '[email protected]', './src/index.ts']);
- });
-
- it('should handle empty arguments array', () => {
- // Given
- const args: string[] = [];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result).toEqual([]);
- });
-
- it('should sanitize all arguments in array', () => {
- // Given
- const args = ['safe-arg', 'unsafe;arg', 'another|unsafe'];
-
- // When
- const result = safeExecutor.sanitizeArgs(args);
-
- // Then
- expect(result[0]).toBe('safe-arg');
- expect(result[1]).not.toContain(';');
- expect(result[2]).not.toContain('|');
- });
- });
-
- describe('CVE-3 prevention scenarios', () => {
- it('should prevent command injection via arguments', async () => {
- // Given
- const command = 'npm';
- const maliciousArgs = ['install; rm -rf /'];
-
- // When
- await safeExecutor.execute(command, maliciousArgs);
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- ['install rm -rf /'], // Semicolon removed
- expect.any(Object)
- );
- });
-
- it('should prevent command substitution attack', async () => {
- // Given
- const command = 'npm';
- const maliciousArgs = ['$(cat /etc/passwd)'];
-
- // When
- await safeExecutor.execute(command, maliciousArgs);
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- ['cat /etc/passwd'], // $() removed
- expect.any(Object)
- );
- });
-
- it('should prevent shell expansion attack', async () => {
- // Given
- const command = 'npm';
- const maliciousArgs = ['`whoami`'];
-
- // When
- await safeExecutor.execute(command, maliciousArgs);
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- ['whoami'], // Backticks removed
- expect.any(Object)
- );
- });
-
- it('should block dangerous commands directly', async () => {
- // Given
- const dangerousCommands = ['rm', 'dd', 'format', 'del'];
-
- // When/Then
- for (const cmd of dangerousCommands) {
- mockValidator.extractCommand.mockReturnValue(cmd);
- await expect(safeExecutor.execute(cmd)).rejects.toThrow(
- `Command not allowed: ${cmd}`
- );
- }
- });
-
- it('should prevent shell mode when disabled in config', async () => {
- // Given
- const command = 'npm';
- const args = ['install && echo pwned'];
-
- // When
- await safeExecutor.execute(command, args, { shell: true });
-
- // Then
- expect(mockSpawner.spawn).toHaveBeenCalledWith(
- 'npm',
- expect.any(Array),
- expect.objectContaining({
- shell: false, // Config overrides user option
- })
- );
- });
- });
-
- describe('error handling', () => {
- it('should propagate spawner errors', async () => {
- // Given
- const command = 'npm';
- const spawnError = new Error('Process spawn failed');
- mockSpawner.spawn.mockRejectedValue(spawnError);
-
- // When/Then
- await expect(safeExecutor.execute(command)).rejects.toThrow(
- 'Process spawn failed'
- );
- });
-
- it('should handle validator errors', async () => {
- // Given
- const command = 'npm';
- mockValidator.extractCommand.mockImplementation(() => {
- throw new Error('Invalid command format');
- });
-
- // When/Then
- await expect(safeExecutor.execute(command)).rejects.toThrow(
- 'Invalid command format'
- );
- });
- });
-
- describe('interaction verification', () => {
- it('should not spawn if command validation fails', async () => {
- // Given
- const command = 'rm';
- mockValidator.extractCommand.mockReturnValue('rm');
-
- // When
- try {
- await safeExecutor.execute(command);
- } catch {
- // Expected
- }
-
- // Then
- expect(mockSpawner.spawn).not.toHaveBeenCalled();
- });
-
- it('should extract command before checking allowed list', async () => {
- // Given
- const command = 'npm install lodash';
- mockValidator.extractCommand.mockReturnValue('npm');
-
- // When
- await safeExecutor.execute(command);
-
- // Then
- expect(mockValidator.extractCommand).toHaveBeenCalledWith(command);
- expect(mockValidator.extractCommand).toHaveBeenCalledBefore(mockSpawner.spawn);
- });
- });
-});
diff --git a/v3/__tests__/unit/security/token-generator.test.ts b/v3/__tests__/unit/security/token-generator.test.ts
deleted file mode 100644
index 85bfdb48cd..0000000000
--- a/v3/__tests__/unit/security/token-generator.test.ts
+++ /dev/null
@@ -1,310 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { TokenGenerator, TokenGeneratorError } from '../../../security/token-generator.js';
-
-describe('TokenGenerator', () => {
- describe('cryptographically secure token generation', () => {
- it('should generate tokens using crypto.randomBytes', () => {
- const generator = new TokenGenerator();
- const token = generator.generate();
-
- // Token should be base64url encoded (default)
- expect(token).toMatch(/^[A-Za-z0-9_-]+$/);
- expect(token.length).toBeGreaterThan(0);
- });
-
- it('should generate tokens with specified length', () => {
- const generator = new TokenGenerator();
-
- // 16 bytes = 22 chars in base64url (without padding)
- const token16 = generator.generate(16);
- expect(token16.length).toBe(22);
-
- // 32 bytes = 43 chars in base64url (without padding)
- const token32 = generator.generate(32);
- expect(token32.length).toBe(43);
- });
-
- it('should support different encodings', () => {
- const hexGenerator = new TokenGenerator({ encoding: 'hex' });
- const hexToken = hexGenerator.generate(16);
- expect(hexToken).toMatch(/^[0-9a-f]+$/i);
- expect(hexToken.length).toBe(32); // 16 bytes = 32 hex chars
-
- const base64Generator = new TokenGenerator({ encoding: 'base64' });
- const base64Token = base64Generator.generate(16);
- expect(base64Token).toMatch(/^[A-Za-z0-9+/]+=*$/);
- });
-
- it('should reject token length below 16 bytes', () => {
- expect(() => new TokenGenerator({ defaultLength: 8 }))
- .toThrow('Token length must be at least 16 bytes');
- });
- });
-
- describe('token uniqueness', () => {
- it('should generate unique tokens each time', () => {
- const generator = new TokenGenerator();
- const tokens = new Set(Array.from({ length: 1000 }, () => generator.generate()));
- expect(tokens.size).toBe(1000);
- });
-
- it('should generate unique session tokens', () => {
- const generator = new TokenGenerator();
- const tokens = new Set(Array.from({ length: 100 }, () => generator.generateSessionToken().value));
- expect(tokens.size).toBe(100);
- });
-
- it('should generate unique verification codes', () => {
- const generator = new TokenGenerator();
- const codes = new Set(Array.from({ length: 100 }, () => generator.generateVerificationCode().code));
- // Due to 6-digit codes, some collisions are possible but should be rare
- expect(codes.size).toBeGreaterThan(90);
- });
-
- it('should generate unique request IDs', () => {
- const generator = new TokenGenerator();
- const ids = new Set(Array.from({ length: 1000 }, () => generator.generateRequestId()));
- expect(ids.size).toBe(1000);
- });
-
- it('should generate unique correlation IDs', () => {
- const generator = new TokenGenerator();
- const ids = new Set(Array.from({ length: 1000 }, () => generator.generateCorrelationId()));
- expect(ids.size).toBe(1000);
- });
- });
-
- describe('timing-safe comparison', () => {
- it('should return true for equal tokens', () => {
- const generator = new TokenGenerator();
- const token = generator.generate();
- expect(generator.compare(token, token)).toBe(true);
- });
-
- it('should return false for different tokens', () => {
- const generator = new TokenGenerator();
- const token1 = generator.generate();
- const token2 = generator.generate();
- expect(generator.compare(token1, token2)).toBe(false);
- });
-
- it('should return false for different length strings', () => {
- const generator = new TokenGenerator();
- expect(generator.compare('short', 'muchlongerstring')).toBe(false);
- });
-
- it('should perform constant-time comparison', () => {
- const generator = new TokenGenerator();
- const token = 'a'.repeat(100);
-
- // Compare with identical string should work
- expect(generator.compare(token, token)).toBe(true);
-
- // Compare with different strings at various positions
- const differentAtStart = 'b' + 'a'.repeat(99);
- const differentAtEnd = 'a'.repeat(99) + 'b';
-
- expect(generator.compare(token, differentAtStart)).toBe(false);
- expect(generator.compare(token, differentAtEnd)).toBe(false);
- });
- });
-
- describe('signed tokens', () => {
- it('should require HMAC secret for signed tokens', () => {
- const generator = new TokenGenerator();
- expect(() => generator.generateSignedToken({ userId: '123' }))
- .toThrow('HMAC secret required for signed tokens');
- });
-
- it('should generate valid signed tokens', () => {
- const generator = new TokenGenerator({ hmacSecret: 'test-secret-key-123' });
- const signed = generator.generateSignedToken({ userId: '123' });
-
- expect(signed.token).toBeDefined();
- expect(signed.signature).toBeDefined();
- expect(signed.combined).toBe(`${signed.token}.${signed.signature}`);
- expect(signed.createdAt).toBeInstanceOf(Date);
- expect(signed.expiresAt).toBeInstanceOf(Date);
- });
-
- it('should verify valid signed tokens', () => {
- const generator = new TokenGenerator({ hmacSecret: 'test-secret-key-123' });
- const signed = generator.generateSignedToken({ userId: '123', role: 'admin' });
-
- const payload = generator.verifySignedToken(signed.combined);
- expect(payload).not.toBeNull();
- expect(payload!.userId).toBe('123');
- expect(payload!.role).toBe('admin');
- });
-
- it('should reject tampered tokens', () => {
- const generator = new TokenGenerator({ hmacSecret: 'test-secret-key-123' });
- const signed = generator.generateSignedToken({ userId: '123' });
-
- // Tamper with signature
- const tampered = signed.combined.slice(0, -5) + 'xxxxx';
- expect(generator.verifySignedToken(tampered)).toBeNull();
- });
-
- it('should reject tokens with wrong secret', () => {
- const generator1 = new TokenGenerator({ hmacSecret: 'secret-1' });
- const generator2 = new TokenGenerator({ hmacSecret: 'secret-2' });
-
- const signed = generator1.generateSignedToken({ userId: '123' });
- expect(generator2.verifySignedToken(signed.combined)).toBeNull();
- });
-
- it('should reject expired signed tokens', async () => {
- const generator = new TokenGenerator({ hmacSecret: 'test-secret' });
- const signed = generator.generateSignedToken({ userId: '123' }, 0); // Expires immediately
-
- // Wait a tiny bit for expiration
- await new Promise(resolve => setTimeout(resolve, 10));
- expect(generator.verifySignedToken(signed.combined)).toBeNull();
- });
-
- it('should reject malformed token format', () => {
- const generator = new TokenGenerator({ hmacSecret: 'test-secret' });
-
- expect(generator.verifySignedToken('no-dot-in-token')).toBeNull();
- expect(generator.verifySignedToken('too.many.dots')).toBeNull();
- expect(generator.verifySignedToken('')).toBeNull();
- });
- });
-
- describe('token expiration', () => {
- it('should create tokens with expiration', () => {
- const generator = new TokenGenerator();
- const token = generator.generateWithExpiration(3600);
-
- expect(token.expiresAt.getTime()).toBe(token.createdAt.getTime() + 3600 * 1000);
- });
-
- it('should use default expiration', () => {
- const generator = new TokenGenerator({ defaultExpiration: 7200 });
- const token = generator.generateWithExpiration();
-
- expect(token.expiresAt.getTime()).toBe(token.createdAt.getTime() + 7200 * 1000);
- });
-
- it('should correctly identify expired tokens', () => {
- const generator = new TokenGenerator();
-
- const expiredToken = {
- value: 'test',
- createdAt: new Date(Date.now() - 10000),
- expiresAt: new Date(Date.now() - 5000),
- };
- expect(generator.isExpired(expiredToken)).toBe(true);
-
- const validToken = {
- value: 'test',
- createdAt: new Date(),
- expiresAt: new Date(Date.now() + 10000),
- };
- expect(generator.isExpired(validToken)).toBe(false);
- });
- });
-
- describe('specialized token types', () => {
- it('should generate session tokens with expiration', () => {
- const generator = new TokenGenerator();
- const token = generator.generateSessionToken();
-
- expect(token.value).toBeDefined();
- expect(token.expiresAt.getTime()).toBeGreaterThan(token.createdAt.getTime());
- });
-
- it('should generate CSRF tokens with 30-minute expiration', () => {
- const generator = new TokenGenerator();
- const token = generator.generateCsrfToken();
-
- const expectedExpiry = token.createdAt.getTime() + 1800 * 1000;
- expect(token.expiresAt.getTime()).toBe(expectedExpiry);
- });
-
- it('should generate API tokens with prefix and 1-year expiration', () => {
- const generator = new TokenGenerator();
- const token = generator.generateApiToken('api_');
-
- expect(token.value.startsWith('api_')).toBe(true);
-
- const oneYear = 365 * 24 * 60 * 60 * 1000;
- expect(token.expiresAt.getTime()).toBeCloseTo(token.createdAt.getTime() + oneYear, -3);
- });
-
- it('should generate password reset tokens with 30-minute expiration', () => {
- const generator = new TokenGenerator();
- const token = generator.generatePasswordResetToken();
-
- const expectedExpiry = token.createdAt.getTime() + 1800 * 1000;
- expect(token.expiresAt.getTime()).toBe(expectedExpiry);
- });
-
- it('should generate email verification tokens with 24-hour expiration', () => {
- const generator = new TokenGenerator();
- const token = generator.generateEmailVerificationToken();
-
- const expectedExpiry = token.createdAt.getTime() + 86400 * 1000;
- expect(token.expiresAt.getTime()).toBe(expectedExpiry);
- });
-
- it('should generate token pairs (access + refresh)', () => {
- const generator = new TokenGenerator();
- const pair = generator.generateTokenPair();
-
- expect(pair.accessToken).toBeDefined();
- expect(pair.refreshToken).toBeDefined();
-
- // Access token: 15 minutes
- expect(pair.accessToken.expiresAt.getTime()).toBe(
- pair.accessToken.createdAt.getTime() + 900 * 1000
- );
-
- // Refresh token: 7 days
- expect(pair.refreshToken.expiresAt.getTime()).toBe(
- pair.refreshToken.createdAt.getTime() + 604800 * 1000
- );
- });
- });
-
- describe('verification codes', () => {
- it('should generate numeric codes of specified length', () => {
- const generator = new TokenGenerator();
-
- const code6 = generator.generateVerificationCode(6);
- expect(code6.code).toMatch(/^\d{6}$/);
-
- const code8 = generator.generateVerificationCode(8);
- expect(code8.code).toMatch(/^\d{8}$/);
- });
-
- it('should set expiration and attempt limits', () => {
- const generator = new TokenGenerator();
- const code = generator.generateVerificationCode(6, 15, 5);
-
- expect(code.attempts).toBe(0);
- expect(code.maxAttempts).toBe(5);
- expect(code.expiresAt.getTime()).toBe(code.createdAt.getTime() + 15 * 60 * 1000);
- });
- });
-
- describe('correlation and request IDs', () => {
- it('should generate short request IDs', () => {
- const generator = new TokenGenerator();
- const id = generator.generateRequestId();
-
- // 8 bytes = 11 chars in base64url
- expect(id.length).toBe(11);
- });
-
- it('should generate correlation IDs with timestamp prefix', () => {
- const generator = new TokenGenerator();
- const id = generator.generateCorrelationId();
-
- expect(id).toMatch(/^[a-z0-9]+-[A-Za-z0-9_-]+$/);
- const [timestamp] = id.split('-');
- expect(parseInt(timestamp, 36)).toBeGreaterThan(0);
- });
- });
-});
diff --git a/v3/__tests__/unit/swarm/consensus.test.ts b/v3/__tests__/unit/swarm/consensus.test.ts
deleted file mode 100644
index 3d1f10c872..0000000000
--- a/v3/__tests__/unit/swarm/consensus.test.ts
+++ /dev/null
@@ -1,761 +0,0 @@
-/**
- * V3 Claude-Flow Consensus Manager Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests Raft-based consensus for swarm coordination
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface } from '../../helpers/create-mock';
-
-/**
- * Consensus manager interface (to be implemented)
- */
-interface IConsensusManager {
- initialize(nodeId: string, peers: string[]): Promise<void>;
- propose(proposal: Proposal): Promise<boolean>;
- getState(): ConsensusState;
- getLeader(): string | null;
- isLeader(nodeId: string): boolean;
- stepDown(): Promise<void>;
- shutdown(): Promise<void>;
-}
-
-/**
- * Raft log interface (collaborator)
- */
-interface IRaftLog {
- append(entry: LogEntry): Promise<number>;
- getEntry(index: number): Promise<LogEntry | null>;
- getLastIndex(): number;
- getLastTerm(): number;
- truncateAfter(index: number): Promise<void>;
-}
-
-/**
- * Election timer interface (collaborator)
- */
-interface IElectionTimer {
- start(): void;
- reset(): void;
- stop(): void;
- onTimeout(callback: () => void): void;
-}
-
-/**
- * Heartbeat sender interface (collaborator)
- */
-interface IHeartbeatSender {
- start(interval: number): void;
- stop(): void;
- sendHeartbeat(peers: string[]): Promise<HeartbeatResponse[]>;
-}
-
-/**
- * RPC client interface (collaborator)
- */
-interface IRPCClient {
- requestVote(peer: string, request: VoteRequest): Promise<VoteResponse>;
- appendEntries(peer: string, request: AppendEntriesRequest): Promise<AppendEntriesResponse>;
-}
-
-interface Proposal {
- type: string;
- payload: unknown;
- proposerId: string;
-}
-
-interface ConsensusState {
- currentTerm: number;
- votedFor: string | null;
- role: 'follower' | 'candidate' | 'leader';
- commitIndex: number;
- lastApplied: number;
-}
-
-interface LogEntry {
- term: number;
- index: number;
- command: unknown;
-}
-
-interface HeartbeatResponse {
- peerId: string;
- success: boolean;
- term: number;
-}
-
-interface VoteRequest {
- term: number;
- candidateId: string;
- lastLogIndex: number;
- lastLogTerm: number;
-}
-
-interface VoteResponse {
- term: number;
- voteGranted: boolean;
-}
-
-interface AppendEntriesRequest {
- term: number;
- leaderId: string;
- prevLogIndex: number;
- prevLogTerm: number;
- entries: LogEntry[];
- leaderCommit: number;
-}
-
-interface AppendEntriesResponse {
- term: number;
- success: boolean;
-}
-
-/**
- * Consensus manager implementation for testing (Raft-based)
- */
-class RaftConsensusManager implements IConsensusManager {
- private nodeId: string = '';
- private peers: string[] = [];
- private state: ConsensusState = {
- currentTerm: 0,
- votedFor: null,
- role: 'follower',
- commitIndex: 0,
- lastApplied: 0,
- };
- private leaderId: string | null = null;
- private initialized = false;
-
- constructor(
- private readonly log: IRaftLog,
- private readonly electionTimer: IElectionTimer,
- private readonly heartbeatSender: IHeartbeatSender,
- private readonly rpcClient: IRPCClient
- ) {}
-
- async initialize(nodeId: string, peers: string[]): Promise<void> {
- if (this.initialized) {
- throw new Error('Already initialized');
- }
-
- this.nodeId = nodeId;
- this.peers = peers;
-
- // Set up election timeout handler
- this.electionTimer.onTimeout(() => {
- this.startElection();
- });
-
- // Start election timer
- this.electionTimer.start();
-
- this.initialized = true;
- }
-
- async propose(proposal: Proposal): Promise<boolean> {
- if (!this.initialized) {
- throw new Error('Not initialized');
- }
-
- // Only leader can accept proposals
- if (this.state.role !== 'leader') {
- return false;
- }
-
- // Create log entry
- const entry: LogEntry = {
- term: this.state.currentTerm,
- index: this.log.getLastIndex() + 1,
- command: proposal,
- };
-
- // Append to local log
- await this.log.append(entry);
-
- // Replicate to peers
- const replicationResults = await this.replicateEntry(entry);
-
- // Check if majority achieved
- const successCount = replicationResults.filter((r) => r).length + 1; // +1 for self
- const majority = Math.floor((this.peers.length + 1) / 2) + 1;
-
- if (successCount >= majority) {
- // Update commit index
- this.state.commitIndex = entry.index;
- return true;
- }
-
- return false;
- }
-
- getState(): ConsensusState {
- return { ...this.state };
- }
-
- getLeader(): string | null {
- return this.leaderId;
- }
-
- isLeader(nodeId: string): boolean {
- return this.state.role === 'leader' && this.nodeId === nodeId;
- }
-
- async stepDown(): Promise<void> {
- if (this.state.role === 'leader') {
- this.heartbeatSender.stop();
- this.state.role = 'follower';
- this.leaderId = null;
- this.electionTimer.start();
- }
- }
-
- async shutdown(): Promise<void> {
- this.electionTimer.stop();
- this.heartbeatSender.stop();
- this.initialized = false;
- }
-
- // Simulate receiving vote request
- async handleVoteRequest(request: VoteRequest): Promise<VoteResponse> {
- // If term is higher, update and become follower
- if (request.term > this.state.currentTerm) {
- this.state.currentTerm = request.term;
- this.state.role = 'follower';
- this.state.votedFor = null;
- }
-
- // Grant vote if:
- // 1. Request term >= current term
- // 2. Haven't voted yet or voted for this candidate
- // 3. Candidate's log is at least as up-to-date
- const logUpToDate =
- request.lastLogTerm > this.log.getLastTerm() ||
- (request.lastLogTerm === this.log.getLastTerm() &&
- request.lastLogIndex >= this.log.getLastIndex());
-
- if (
- request.term >= this.state.currentTerm &&
- (this.state.votedFor === null || this.state.votedFor === request.candidateId) &&
- logUpToDate
- ) {
- this.state.votedFor = request.candidateId;
- this.electionTimer.reset();
- return { term: this.state.currentTerm, voteGranted: true };
- }
-
- return { term: this.state.currentTerm, voteGranted: false };
- }
-
- // Simulate receiving append entries (heartbeat)
- async handleAppendEntries(request: AppendEntriesRequest): Promise<AppendEntriesResponse> {
- // If term is higher, become follower
- if (request.term > this.state.currentTerm) {
- this.state.currentTerm = request.term;
- this.state.role = 'follower';
- this.state.votedFor = null;
- }
-
- // Reset election timer on valid heartbeat
- if (request.term >= this.state.currentTerm) {
- this.leaderId = request.leaderId;
- this.electionTimer.reset();
-
- // Append entries if log check passes
- const prevEntry = await this.log.getEntry(request.prevLogIndex);
- if (request.prevLogIndex === 0 || (prevEntry && prevEntry.term === request.prevLogTerm)) {
- // Append new entries
- for (const entry of request.entries) {
- await this.log.append(entry);
- }
-
- // Update commit index
- if (request.leaderCommit > this.state.commitIndex) {
- this.state.commitIndex = Math.min(request.leaderCommit, this.log.getLastIndex());
- }
-
- return { term: this.state.currentTerm, success: true };
- }
- }
-
- return { term: this.state.currentTerm, success: false };
- }
-
- private async startElection(): Promise<void> {
- // Increment term and become candidate
- this.state.currentTerm++;
- this.state.role = 'candidate';
- this.state.votedFor = this.nodeId;
-
- // Request votes from peers
- const votePromises = this.peers.map((peer) =>
- this.rpcClient.requestVote(peer, {
- term: this.state.currentTerm,
- candidateId: this.nodeId,
- lastLogIndex: this.log.getLastIndex(),
- lastLogTerm: this.log.getLastTerm(),
- })
- );
-
- const responses = await Promise.all(votePromises);
-
- // Count votes (including self vote)
- const votesReceived = responses.filter((r) => r.voteGranted).length + 1;
- const majority = Math.floor((this.peers.length + 1) / 2) + 1;
-
- // Check if we received a higher term
- const maxTerm = Math.max(...responses.map((r) => r.term), this.state.currentTerm);
- if (maxTerm > this.state.currentTerm) {
- this.state.currentTerm = maxTerm;
- this.state.role = 'follower';
- this.state.votedFor = null;
- return;
- }
-
- // Check if elected
- if (votesReceived >= majority) {
- this.becomeLeader();
- } else {
- // Restart election timer
- this.electionTimer.reset();
- }
- }
-
- private becomeLeader(): void {
- this.state.role = 'leader';
- this.leaderId = this.nodeId;
- this.electionTimer.stop();
- this.heartbeatSender.start(1000); // 1 second heartbeat
- }
-
- private async replicateEntry(entry: LogEntry): Promise<boolean[]> {
- const results = await Promise.all(
- this.peers.map(async (peer) => {
- const response = await this.rpcClient.appendEntries(peer, {
- term: this.state.currentTerm,
- leaderId: this.nodeId,
- prevLogIndex: entry.index - 1,
- prevLogTerm: entry.index > 1 ? (await this.log.getEntry(entry.index - 1))?.term ?? 0 : 0,
- entries: [entry],
- leaderCommit: this.state.commitIndex,
- });
-
- return response.success;
- })
- );
-
- return results;
- }
-}
-
-describe('RaftConsensusManager', () => {
- let mockLog: MockedInterface<IRaftLog>;
- let mockElectionTimer: MockedInterface<IElectionTimer>;
- let mockHeartbeatSender: MockedInterface<IHeartbeatSender>;
- let mockRPCClient: MockedInterface<IRPCClient>;
- let consensusManager: RaftConsensusManager;
-
- beforeEach(() => {
- mockLog = createMock<IRaftLog>();
- mockElectionTimer = createMock<IElectionTimer>();
- mockHeartbeatSender = createMock<IHeartbeatSender>();
- mockRPCClient = createMock<IRPCClient>();
-
- // Configure default mock behavior
- mockLog.append.mockResolvedValue(1);
- mockLog.getEntry.mockResolvedValue(null);
- mockLog.getLastIndex.mockReturnValue(0);
- mockLog.getLastTerm.mockReturnValue(0);
- mockLog.truncateAfter.mockResolvedValue(undefined);
-
- mockElectionTimer.start.mockReturnValue(undefined);
- mockElectionTimer.reset.mockReturnValue(undefined);
- mockElectionTimer.stop.mockReturnValue(undefined);
- mockElectionTimer.onTimeout.mockReturnValue(undefined);
-
- mockHeartbeatSender.start.mockReturnValue(undefined);
- mockHeartbeatSender.stop.mockReturnValue(undefined);
- mockHeartbeatSender.sendHeartbeat.mockResolvedValue([]);
-
- mockRPCClient.requestVote.mockResolvedValue({ term: 1, voteGranted: true });
- mockRPCClient.appendEntries.mockResolvedValue({ term: 1, success: true });
-
- consensusManager = new RaftConsensusManager(
- mockLog,
- mockElectionTimer,
- mockHeartbeatSender,
- mockRPCClient
- );
- });
-
- describe('initialize', () => {
- it('should set up election timeout handler', async () => {
- // When
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
-
- // Then
- expect(mockElectionTimer.onTimeout).toHaveBeenCalled();
- });
-
- it('should start election timer', async () => {
- // When
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
-
- // Then
- expect(mockElectionTimer.start).toHaveBeenCalled();
- });
-
- it('should throw error if already initialized', async () => {
- // Given
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
-
- // When/Then
- await expect(
- consensusManager.initialize('node-1', ['node-2', 'node-3'])
- ).rejects.toThrow('Already initialized');
- });
- });
-
- describe('propose', () => {
- beforeEach(async () => {
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
- });
-
- it('should throw error if not initialized', async () => {
- // Given
- const uninitializedManager = new RaftConsensusManager(
- mockLog,
- mockElectionTimer,
- mockHeartbeatSender,
- mockRPCClient
- );
-
- const proposal: Proposal = {
- type: 'TaskCoordination',
- payload: {},
- proposerId: 'coordinator',
- };
-
- // When/Then
- await expect(uninitializedManager.propose(proposal)).rejects.toThrow(
- 'Not initialized'
- );
- });
-
- it('should return false if not leader', async () => {
- // Given - default role is follower
- const proposal: Proposal = {
- type: 'TaskCoordination',
- payload: {},
- proposerId: 'coordinator',
- };
-
- // When
- const result = await consensusManager.propose(proposal);
-
- // Then
- expect(result).toBe(false);
- });
- });
-
- describe('getState', () => {
- it('should return initial state', async () => {
- // When
- const state = consensusManager.getState();
-
- // Then
- expect(state).toEqual({
- currentTerm: 0,
- votedFor: null,
- role: 'follower',
- commitIndex: 0,
- lastApplied: 0,
- });
- });
-
- it('should return copy of state', async () => {
- // Given
- const state1 = consensusManager.getState();
- state1.currentTerm = 100;
-
- // When
- const state2 = consensusManager.getState();
-
- // Then
- expect(state2.currentTerm).toBe(0);
- });
- });
-
- describe('getLeader', () => {
- it('should return null initially', async () => {
- // When
- const leader = consensusManager.getLeader();
-
- // Then
- expect(leader).toBeNull();
- });
- });
-
- describe('isLeader', () => {
- it('should return false when not leader', async () => {
- // Given
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
-
- // When
- const result = consensusManager.isLeader('node-1');
-
- // Then
- expect(result).toBe(false);
- });
- });
-
- describe('stepDown', () => {
- beforeEach(async () => {
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
- });
-
- it('should do nothing if not leader', async () => {
- // When
- await consensusManager.stepDown();
-
- // Then
- expect(mockHeartbeatSender.stop).not.toHaveBeenCalled();
- });
- });
-
- describe('shutdown', () => {
- beforeEach(async () => {
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
- });
-
- it('should stop election timer', async () => {
- // When
- await consensusManager.shutdown();
-
- // Then
- expect(mockElectionTimer.stop).toHaveBeenCalled();
- });
-
- it('should stop heartbeat sender', async () => {
- // When
- await consensusManager.shutdown();
-
- // Then
- expect(mockHeartbeatSender.stop).toHaveBeenCalled();
- });
- });
-
- describe('handleVoteRequest', () => {
- beforeEach(async () => {
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
- });
-
- it('should grant vote if criteria met', async () => {
- // Given
- const request: VoteRequest = {
- term: 1,
- candidateId: 'node-2',
- lastLogIndex: 0,
- lastLogTerm: 0,
- };
-
- // When
- const response = await consensusManager.handleVoteRequest(request);
-
- // Then
- expect(response.voteGranted).toBe(true);
- });
-
- it('should reset election timer when granting vote', async () => {
- // Given
- const request: VoteRequest = {
- term: 1,
- candidateId: 'node-2',
- lastLogIndex: 0,
- lastLogTerm: 0,
- };
-
- // When
- await consensusManager.handleVoteRequest(request);
-
- // Then
- expect(mockElectionTimer.reset).toHaveBeenCalled();
- });
-
- it('should update term if request has higher term', async () => {
- // Given
- const request: VoteRequest = {
- term: 5,
- candidateId: 'node-2',
- lastLogIndex: 0,
- lastLogTerm: 0,
- };
-
- // When
- await consensusManager.handleVoteRequest(request);
- const state = consensusManager.getState();
-
- // Then
- expect(state.currentTerm).toBe(5);
- });
-
- it('should deny vote if already voted for different candidate', async () => {
- // Given - first vote
- await consensusManager.handleVoteRequest({
- term: 1,
- candidateId: 'node-2',
- lastLogIndex: 0,
- lastLogTerm: 0,
- });
-
- // When - second vote request in same term
- const response = await consensusManager.handleVoteRequest({
- term: 1,
- candidateId: 'node-3',
- lastLogIndex: 0,
- lastLogTerm: 0,
- });
-
- // Then
- expect(response.voteGranted).toBe(false);
- });
-
- it('should deny vote if candidate log is not up-to-date', async () => {
- // Given - node has entries
- mockLog.getLastIndex.mockReturnValue(5);
- mockLog.getLastTerm.mockReturnValue(2);
-
- const request: VoteRequest = {
- term: 3,
- candidateId: 'node-2',
- lastLogIndex: 3, // Behind
- lastLogTerm: 1, // Behind
- };
-
- // When
- const response = await consensusManager.handleVoteRequest(request);
-
- // Then
- expect(response.voteGranted).toBe(false);
- });
- });
-
- describe('handleAppendEntries', () => {
- beforeEach(async () => {
- await consensusManager.initialize('node-1', ['node-2', 'node-3']);
- });
-
- it('should reset election timer on valid heartbeat', async () => {
- // Given
- const request: AppendEntriesRequest = {
- term: 1,
- leaderId: 'node-2',
- prevLogIndex: 0,
- prevLogTerm: 0,
- entries: [],
- leaderCommit: 0,
- };
-
- // When
- await consensusManager.handleAppendEntries(request);
-
- // Then
- expect(mockElectionTimer.reset).toHaveBeenCalled();
- });
-
- it('should update leader id', async () => {
- // Given
- const request: AppendEntriesRequest = {
- term: 1,
- leaderId: 'node-2',
- prevLogIndex: 0,
- prevLogTerm: 0,
- entries: [],
- leaderCommit: 0,
- };
-
- // When
- await consensusManager.handleAppendEntries(request);
-
- // Then
- expect(consensusManager.getLeader()).toBe('node-2');
- });
-
- it('should append entries to log', async () => {
- // Given
- const entry: LogEntry = { term: 1, index: 1, command: { type: 'test' } };
- const request: AppendEntriesRequest = {
- term: 1,
- leaderId: 'node-2',
- prevLogIndex: 0,
- prevLogTerm: 0,
- entries: [entry],
- leaderCommit: 0,
- };
-
- // When
- await consensusManager.handleAppendEntries(request);
-
- // Then
- expect(mockLog.append).toHaveBeenCalledWith(entry);
- });
-
- it('should update commit index', async () => {
- // Given
- mockLog.getLastIndex.mockReturnValue(5);
- const request: AppendEntriesRequest = {
- term: 1,
- leaderId: 'node-2',
- prevLogIndex: 0,
- prevLogTerm: 0,
- entries: [],
- leaderCommit: 3,
- };
-
- // When
- await consensusManager.handleAppendEntries(request);
- const state = consensusManager.getState();
-
- // Then
- expect(state.commitIndex).toBe(3);
- });
-
- it('should become follower if higher term received', async () => {
- // Given
- const request: AppendEntriesRequest = {
- term: 5,
- leaderId: 'node-2',
- prevLogIndex: 0,
- prevLogTerm: 0,
- entries: [],
- leaderCommit: 0,
- };
-
- // When
- await consensusManager.handleAppendEntries(request);
- const state = consensusManager.getState();
-
- // Then
- expect(state.role).toBe('follower');
- expect(state.currentTerm).toBe(5);
- });
-
- it('should return false if log check fails', async () => {
- // Given
- mockLog.getEntry.mockResolvedValue({ term: 1, index: 1, command: {} });
- const request: AppendEntriesRequest = {
- term: 1,
- leaderId: 'node-2',
- prevLogIndex: 1,
- prevLogTerm: 2, // Mismatch
- entries: [],
- leaderCommit: 0,
- };
-
- // When
- const response = await consensusManager.handleAppendEntries(request);
-
- // Then
- expect(response.success).toBe(false);
- });
- });
-});
diff --git a/v3/__tests__/unit/swarm/unified-coordinator.test.ts b/v3/__tests__/unit/swarm/unified-coordinator.test.ts
deleted file mode 100644
index 47c6fdf6d3..0000000000
--- a/v3/__tests__/unit/swarm/unified-coordinator.test.ts
+++ /dev/null
@@ -1,952 +0,0 @@
-/**
- * V3 Claude-Flow Unified Coordinator Unit Tests
- *
- * London School TDD - Behavior Verification
- * Tests 15-agent swarm coordination (ADR-003)
- */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createMock, type MockedInterface, InteractionRecorder } from '../../helpers/create-mock';
-import { createSwarmTestInstance, type V3AgentType, type SwarmTask } from '../../helpers/swarm-instance';
-import { swarmConfigs, createSwarmConfig } from '../../fixtures/configurations';
-import { agentConfigs, create15AgentSwarmConfig } from '../../fixtures/agents';
-
-/**
- * Unified coordinator interface (to be implemented per ADR-003)
- */
-interface IUnifiedCoordinator {
- initialize(config: SwarmConfig): Promise<void>;
- addAgent(agent: AgentInfo): Promise<void>;
- removeAgent(agentId: string): Promise<void>;
- coordinate(task: CoordinationTask): Promise<CoordinationResult>;
- shutdown(): Promise<void>;
- getTopology(): SwarmTopology;
- getAgentStatus(agentId: string): AgentStatus | null;
-}
-
-/**
- * Task distributor interface (collaborator)
- */
-interface ITaskDistributor {
- distribute(task: CoordinationTask, agents: AgentInfo[]): Promise<TaskAssignment[]>;
- rebalance(assignments: TaskAssignment[]): Promise<TaskAssignment[]>;
-}
-
-/**
- * Consensus manager interface (collaborator)
- */
-interface IConsensusManager {
- propose(proposal: Proposal): Promise<boolean>;
- getLeader(): string | null;
- isLeader(agentId: string): boolean;
-}
-
-/**
- * Communication channel interface (collaborator)
- */
-interface ICommunicationChannel {
- broadcast(message: SwarmMessage): Promise<void>;
- send(agentId: string, message: SwarmMessage): Promise<void>;
- subscribe(handler: MessageHandler): void;
-}
-
-/**
- * Event publisher interface (collaborator)
- */
-interface IEventPublisher {
- publish(event: DomainEvent): Promise<void>;
-}
-
-interface SwarmConfig {
- topology: 'hierarchical' | 'mesh' | 'adaptive' | 'hierarchical-mesh';
- maxAgents: number;
- consensusProtocol: 'raft' | 'pbft' | 'gossip';
-}
-
-interface AgentInfo {
- id: string;
- type: V3AgentType;
- capabilities: string[];
- priority: number;
-}
-
-interface CoordinationTask {
- id: string;
- type: string;
- payload: unknown;
- requiredCapabilities: string[];
- priority: number;
-}
-
-interface CoordinationResult {
- taskId: string;
- success: boolean;
- results: TaskResult[];
- duration: number;
- participatingAgents: string[];
-}
-
-interface TaskAssignment {
- agentId: string;
- taskId: string;
- subtask: unknown;
-}
-
-interface TaskResult {
- agentId: string;
- success: boolean;
- output?: unknown;
- error?: Error;
-}
-
-interface Proposal {
- type: string;
- payload: unknown;
- proposerId: string;
-}
-
-interface SwarmMessage {
- type: string;
- payload: unknown;
- from: string;
- to: string | 'broadcast';
-}
-
-type MessageHandler = (message: SwarmMessage) => Promise<void>;
-
-type SwarmTopology = 'hierarchical' | 'mesh' | 'adaptive' | 'hierarchical-mesh';
-
-type AgentStatus = 'idle' | 'busy' | 'offline';
-
-interface DomainEvent {
- type: string;
- payload: unknown;
- timestamp: Date;
-}
-
-/**
- * Unified coordinator implementation for testing
- */
-class UnifiedCoordinator implements IUnifiedCoordinator {
- private agents: Map<string, AgentInfo> = new Map();
- private agentStatus: Map<string, AgentStatus> = new Map();
- private initialized = false;
- private config: SwarmConfig | null = null;
-
- constructor(
- private readonly distributor: ITaskDistributor,
- private readonly consensus: IConsensusManager,
- private readonly channel: ICommunicationChannel,
- private readonly eventPublisher: IEventPublisher
- ) {}
-
- async initialize(config: SwarmConfig): Promise<void> {
- if (this.initialized) {
- throw new Error('Coordinator already initialized');
- }
-
- this.config = config;
-
- // Subscribe to messages
- this.channel.subscribe(async (message) => {
- await this.handleMessage(message);
- });
-
- // Publish initialization event
- await this.eventPublisher.publish({
- type: 'CoordinatorInitialized',
- payload: { topology: config.topology, maxAgents: config.maxAgents },
- timestamp: new Date(),
- });
-
- this.initialized = true;
- }
-
- async addAgent(agent: AgentInfo): Promise<void> {
- if (!this.initialized) {
- throw new Error('Coordinator not initialized');
- }
-
- if (this.agents.size >= this.config!.maxAgents) {
- throw new Error('Maximum agent limit reached');
- }
-
- this.agents.set(agent.id, agent);
- this.agentStatus.set(agent.id, 'idle');
-
- // Broadcast agent joined
- await this.channel.broadcast({
- type: 'AgentJoined',
- payload: { agentId: agent.id, type: agent.type },
- from: 'coordinator',
- to: 'broadcast',
- });
-
- await this.eventPublisher.publish({
- type: 'AgentAddedToSwarm',
- payload: { agentId: agent.id, agentType: agent.type },
- timestamp: new Date(),
- });
- }
-
- async removeAgent(agentId: string): Promise<void> {
- if (!this.agents.has(agentId)) {
- throw new Error(`Agent not found: ${agentId}`);
- }
-
- this.agents.delete(agentId);
- this.agentStatus.delete(agentId);
-
- // Broadcast agent left
- await this.channel.broadcast({
- type: 'AgentLeft',
- payload: { agentId },
- from: 'coordinator',
- to: 'broadcast',
- });
-
- await this.eventPublisher.publish({
- type: 'AgentRemovedFromSwarm',
- payload: { agentId },
- timestamp: new Date(),
- });
- }
-
- async coordinate(task: CoordinationTask): Promise<CoordinationResult> {
- if (!this.initialized) {
- throw new Error('Coordinator not initialized');
- }
-
- const startTime = Date.now();
-
- // Get available agents
- const availableAgents = this.getAvailableAgents(task.requiredCapabilities);
-
- if (availableAgents.length === 0) {
- throw new Error('No available agents with required capabilities');
- }
-
- // For hierarchical topology, propose task through consensus
- if (this.config!.topology.includes('hierarchical')) {
- const approved = await this.consensus.propose({
- type: 'TaskCoordination',
- payload: task,
- proposerId: 'coordinator',
- });
-
- if (!approved) {
- throw new Error('Task coordination not approved by consensus');
- }
- }
-
- // Distribute task
- const assignments = await this.distributor.distribute(task, availableAgents);
-
- // Mark agents as busy
- for (const assignment of assignments) {
- this.agentStatus.set(assignment.agentId, 'busy');
- }
-
- // Notify agents
- for (const assignment of assignments) {
- await this.channel.send(assignment.agentId, {
- type: 'TaskAssigned',
- payload: assignment,
- from: 'coordinator',
- to: assignment.agentId,
- });
- }
-
- // Simulate task execution results
- const results: TaskResult[] = assignments.map((a) => ({
- agentId: a.agentId,
- success: true,
- }));
-
- // Mark agents as idle
- for (const assignment of assignments) {
- this.agentStatus.set(assignment.agentId, 'idle');
- }
-
- const duration = Date.now() - startTime;
-
- await this.eventPublisher.publish({
- type: 'TaskCoordinationCompleted',
- payload: { taskId: task.id, duration, participatingAgents: assignments.map((a) => a.agentId) },
- timestamp: new Date(),
- });
-
- return {
- taskId: task.id,
- success: true,
- results,
- duration,
- participatingAgents: assignments.map((a) => a.agentId),
- };
- }
-
- async shutdown(): Promise<void> {
- // Notify all agents
- await this.channel.broadcast({
- type: 'CoordinatorShutdown',
- payload: {},
- from: 'coordinator',
- to: 'broadcast',
- });
-
- // Clear state
- this.agents.clear();
- this.agentStatus.clear();
- this.initialized = false;
-
- await this.eventPublisher.publish({
- type: 'CoordinatorShutdown',
- payload: {},
- timestamp: new Date(),
- });
- }
-
- getTopology(): SwarmTopology {
- return this.config?.topology ?? 'mesh';
- }
-
- getAgentStatus(agentId: string): AgentStatus | null {
- return this.agentStatus.get(agentId) ?? null;
- }
-
- private getAvailableAgents(requiredCapabilities: string[]): AgentInfo[] {
- const available: AgentInfo[] = [];
-
- for (const [agentId, agent] of this.agents) {
- const status = this.agentStatus.get(agentId);
-
- if (status === 'idle') {
- const hasCapabilities = requiredCapabilities.every((cap) =>
- agent.capabilities.includes(cap)
- );
-
- if (hasCapabilities || requiredCapabilities.length === 0) {
- available.push(agent);
- }
- }
- }
-
- return available.sort((a, b) => b.priority - a.priority);
- }
-
- private async handleMessage(message: SwarmMessage): Promise<void> {
- // Handle incoming messages
- if (message.type === 'AgentStatusUpdate') {
- const { agentId, status } = message.payload as { agentId: string; status: AgentStatus };
- this.agentStatus.set(agentId, status);
- }
- }
-}
-
-describe('UnifiedCoordinator', () => {
- let mockDistributor: MockedInterface<ITaskDistributor>;
- let mockConsensus: MockedInterface<IConsensusManager>;
- let mockChannel: MockedInterface<ICommunicationChannel>;
- let mockEventPublisher: MockedInterface<IEventPublisher>;
- let coordinator: UnifiedCoordinator;
- let interactionRecorder: InteractionRecorder;
-
- beforeEach(() => {
- mockDistributor = createMock<ITaskDistributor>();
- mockConsensus = createMock<IConsensusManager>();
- mockChannel = createMock<ICommunicationChannel>();
- mockEventPublisher = createMock<IEventPublisher>();
- interactionRecorder = new InteractionRecorder();
-
- // Configure default mock behavior
- mockDistributor.distribute.mockResolvedValue([]);
- mockDistributor.rebalance.mockResolvedValue([]);
-
- mockConsensus.propose.mockResolvedValue(true);
- mockConsensus.getLeader.mockReturnValue('leader-agent');
- mockConsensus.isLeader.mockReturnValue(false);
-
- mockChannel.broadcast.mockResolvedValue(undefined);
- mockChannel.send.mockResolvedValue(undefined);
- mockChannel.subscribe.mockReturnValue(undefined);
-
- mockEventPublisher.publish.mockResolvedValue(undefined);
-
- // Track interactions
- interactionRecorder.track('distributor', mockDistributor);
- interactionRecorder.track('consensus', mockConsensus);
- interactionRecorder.track('channel', mockChannel);
- interactionRecorder.track('events', mockEventPublisher);
-
- coordinator = new UnifiedCoordinator(
- mockDistributor,
- mockConsensus,
- mockChannel,
- mockEventPublisher
- );
- });
-
- describe('initialize', () => {
- it('should subscribe to communication channel', async () => {
- // Given
- const config: SwarmConfig = {
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- };
-
- // When
- await coordinator.initialize(config);
-
- // Then
- expect(mockChannel.subscribe).toHaveBeenCalled();
- });
-
- it('should publish initialization event', async () => {
- // Given
- const config: SwarmConfig = {
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- };
-
- // When
- await coordinator.initialize(config);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'CoordinatorInitialized',
- payload: expect.objectContaining({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- }),
- })
- );
- });
-
- it('should throw error if already initialized', async () => {
- // Given
- const config: SwarmConfig = {
- topology: 'mesh',
- maxAgents: 10,
- consensusProtocol: 'gossip',
- };
- await coordinator.initialize(config);
-
- // When/Then
- await expect(coordinator.initialize(config)).rejects.toThrow(
- 'Coordinator already initialized'
- );
- });
- });
-
- describe('addAgent', () => {
- beforeEach(async () => {
- await coordinator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- });
- });
-
- it('should throw error if not initialized', async () => {
- // Given
- const uninitializedCoordinator = new UnifiedCoordinator(
- mockDistributor,
- mockConsensus,
- mockChannel,
- mockEventPublisher
- );
-
- const agent: AgentInfo = {
- id: 'agent-1',
- type: 'coder',
- capabilities: ['coding'],
- priority: 50,
- };
-
- // When/Then
- await expect(uninitializedCoordinator.addAgent(agent)).rejects.toThrow(
- 'Coordinator not initialized'
- );
- });
-
- it('should broadcast agent joined message', async () => {
- // Given
- const agent: AgentInfo = {
- id: 'agent-1',
- type: 'queen-coordinator',
- capabilities: ['orchestration'],
- priority: 100,
- };
-
- // When
- await coordinator.addAgent(agent);
-
- // Then
- expect(mockChannel.broadcast).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentJoined',
- payload: expect.objectContaining({
- agentId: 'agent-1',
- }),
- })
- );
- });
-
- it('should publish AgentAddedToSwarm event', async () => {
- // Given
- const agent: AgentInfo = {
- id: 'agent-1',
- type: 'security-architect',
- capabilities: ['security-design'],
- priority: 90,
- };
-
- // When
- await coordinator.addAgent(agent);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentAddedToSwarm',
- payload: expect.objectContaining({
- agentId: 'agent-1',
- agentType: 'security-architect',
- }),
- })
- );
- });
-
- it('should set agent status to idle', async () => {
- // Given
- const agent: AgentInfo = {
- id: 'agent-1',
- type: 'coder',
- capabilities: ['coding'],
- priority: 50,
- };
-
- // When
- await coordinator.addAgent(agent);
-
- // Then
- expect(coordinator.getAgentStatus('agent-1')).toBe('idle');
- });
-
- it('should throw error when max agents reached', async () => {
- // Given - Add 15 agents to reach max
- for (let i = 0; i < 15; i++) {
- await coordinator.addAgent({
- id: `agent-${i}`,
- type: 'coder',
- capabilities: ['coding'],
- priority: 50,
- });
- }
-
- // When/Then
- await expect(
- coordinator.addAgent({
- id: 'agent-16',
- type: 'coder',
- capabilities: ['coding'],
- priority: 50,
- })
- ).rejects.toThrow('Maximum agent limit reached');
- });
- });
-
- describe('removeAgent', () => {
- beforeEach(async () => {
- await coordinator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- });
- await coordinator.addAgent({
- id: 'agent-1',
- type: 'coder',
- capabilities: ['coding'],
- priority: 50,
- });
- });
-
- it('should throw error for non-existent agent', async () => {
- // When/Then
- await expect(coordinator.removeAgent('non-existent')).rejects.toThrow(
- 'Agent not found: non-existent'
- );
- });
-
- it('should broadcast agent left message', async () => {
- // When
- await coordinator.removeAgent('agent-1');
-
- // Then
- expect(mockChannel.broadcast).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentLeft',
- payload: { agentId: 'agent-1' },
- })
- );
- });
-
- it('should publish AgentRemovedFromSwarm event', async () => {
- // When
- await coordinator.removeAgent('agent-1');
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'AgentRemovedFromSwarm',
- payload: { agentId: 'agent-1' },
- })
- );
- });
-
- it('should clear agent status', async () => {
- // When
- await coordinator.removeAgent('agent-1');
-
- // Then
- expect(coordinator.getAgentStatus('agent-1')).toBeNull();
- });
- });
-
- describe('coordinate', () => {
- beforeEach(async () => {
- await coordinator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- });
- await coordinator.addAgent({
- id: 'agent-1',
- type: 'coder',
- capabilities: ['coding', 'debugging'],
- priority: 50,
- });
- await coordinator.addAgent({
- id: 'agent-2',
- type: 'tester',
- capabilities: ['testing'],
- priority: 60,
- });
- });
-
- it('should throw error if not initialized', async () => {
- // Given
- const uninitializedCoordinator = new UnifiedCoordinator(
- mockDistributor,
- mockConsensus,
- mockChannel,
- mockEventPublisher
- );
-
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: ['coding'],
- priority: 50,
- };
-
- // When/Then
- await expect(uninitializedCoordinator.coordinate(task)).rejects.toThrow(
- 'Coordinator not initialized'
- );
- });
-
- it('should propose task through consensus for hierarchical topology', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: [],
- priority: 50,
- };
- mockDistributor.distribute.mockResolvedValue([
- { agentId: 'agent-1', taskId: 'task-1', subtask: {} },
- ]);
-
- // When
- await coordinator.coordinate(task);
-
- // Then
- expect(mockConsensus.propose).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskCoordination',
- payload: task,
- })
- );
- });
-
- it('should throw error if consensus rejects', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: [],
- priority: 50,
- };
- mockConsensus.propose.mockResolvedValue(false);
-
- // When/Then
- await expect(coordinator.coordinate(task)).rejects.toThrow(
- 'Task coordination not approved by consensus'
- );
- });
-
- it('should distribute task to available agents', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: ['coding'],
- priority: 50,
- };
- mockDistributor.distribute.mockResolvedValue([
- { agentId: 'agent-1', taskId: 'task-1', subtask: {} },
- ]);
-
- // When
- await coordinator.coordinate(task);
-
- // Then
- expect(mockDistributor.distribute).toHaveBeenCalledWith(
- task,
- expect.arrayContaining([
- expect.objectContaining({ id: 'agent-1' }),
- ])
- );
- });
-
- it('should throw error if no agents with required capabilities', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: ['non-existent-capability'],
- priority: 50,
- };
-
- // When/Then
- await expect(coordinator.coordinate(task)).rejects.toThrow(
- 'No available agents with required capabilities'
- );
- });
-
- it('should send task assignment to each agent', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: [],
- priority: 50,
- };
- mockDistributor.distribute.mockResolvedValue([
- { agentId: 'agent-1', taskId: 'task-1', subtask: { part: 1 } },
- { agentId: 'agent-2', taskId: 'task-1', subtask: { part: 2 } },
- ]);
-
- // When
- await coordinator.coordinate(task);
-
- // Then
- expect(mockChannel.send).toHaveBeenCalledWith(
- 'agent-1',
- expect.objectContaining({
- type: 'TaskAssigned',
- })
- );
- expect(mockChannel.send).toHaveBeenCalledWith(
- 'agent-2',
- expect.objectContaining({
- type: 'TaskAssigned',
- })
- );
- });
-
- it('should return coordination result', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: [],
- priority: 50,
- };
- mockDistributor.distribute.mockResolvedValue([
- { agentId: 'agent-1', taskId: 'task-1', subtask: {} },
- ]);
-
- // When
- const result = await coordinator.coordinate(task);
-
- // Then
- expect(result.taskId).toBe('task-1');
- expect(result.success).toBe(true);
- expect(result.participatingAgents).toContain('agent-1');
- expect(result.duration).toBeGreaterThanOrEqual(0);
- });
-
- it('should publish TaskCoordinationCompleted event', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: [],
- priority: 50,
- };
- mockDistributor.distribute.mockResolvedValue([
- { agentId: 'agent-1', taskId: 'task-1', subtask: {} },
- ]);
-
- // When
- await coordinator.coordinate(task);
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'TaskCoordinationCompleted',
- payload: expect.objectContaining({
- taskId: 'task-1',
- }),
- })
- );
- });
-
- it('should prioritize higher priority agents', async () => {
- // Given
- const task: CoordinationTask = {
- id: 'task-1',
- type: 'implementation',
- payload: {},
- requiredCapabilities: [],
- priority: 50,
- };
-
- let capturedAgents: AgentInfo[] = [];
- mockDistributor.distribute.mockImplementation(async (_, agents) => {
- capturedAgents = agents;
- return [{ agentId: agents[0].id, taskId: 'task-1', subtask: {} }];
- });
-
- // When
- await coordinator.coordinate(task);
-
- // Then - agent-2 has higher priority (60 vs 50)
- expect(capturedAgents[0].id).toBe('agent-2');
- });
- });
-
- describe('shutdown', () => {
- beforeEach(async () => {
- await coordinator.initialize({
- topology: 'mesh',
- maxAgents: 10,
- consensusProtocol: 'gossip',
- });
- });
-
- it('should broadcast shutdown message', async () => {
- // When
- await coordinator.shutdown();
-
- // Then
- expect(mockChannel.broadcast).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'CoordinatorShutdown',
- })
- );
- });
-
- it('should publish shutdown event', async () => {
- // When
- await coordinator.shutdown();
-
- // Then
- expect(mockEventPublisher.publish).toHaveBeenCalledWith(
- expect.objectContaining({
- type: 'CoordinatorShutdown',
- })
- );
- });
-
- it('should clear all agents', async () => {
- // Given
- await coordinator.addAgent({
- id: 'agent-1',
- type: 'coder',
- capabilities: ['coding'],
- priority: 50,
- });
-
- // When
- await coordinator.shutdown();
-
- // Then
- expect(coordinator.getAgentStatus('agent-1')).toBeNull();
- });
- });
-
- describe('getTopology', () => {
- it('should return configured topology', async () => {
- // Given
- await coordinator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- });
-
- // When
- const topology = coordinator.getTopology();
-
- // Then
- expect(topology).toBe('hierarchical-mesh');
- });
-
- it('should return mesh as default before initialization', () => {
- // When
- const topology = coordinator.getTopology();
-
- // Then
- expect(topology).toBe('mesh');
- });
- });
-
- describe('15-agent swarm coordination (ADR-003)', () => {
- it('should support up to 15 agents', async () => {
- // Given
- await coordinator.initialize({
- topology: 'hierarchical-mesh',
- maxAgents: 15,
- consensusProtocol: 'raft',
- });
-
- const agentConfigurations = create15AgentSwarmConfig();
-
- // When
- for (let i = 0; i < 15; i++) {
- await coordinator.addAgent({
- id: `agent-${i}`,
- type: agentConfigurations[i].type,
- capabilities: agentConfigurations[i].capabilities,
- priority: agentConfigurations[i].priority ?? 50,
- });
- }
-
- // Then - all 15 agents should have idle status
- for (let i = 0; i < 15; i++) {
- expect(coordinator.getAgentStatus(`agent-${i}`)).toBe('idle');
- }
- });
- });
-});
diff --git a/v3/benchmarks/attention/flash-attention.bench.ts b/v3/benchmarks/attention/flash-attention.bench.ts
deleted file mode 100644
index 5a65db7cff..0000000000
--- a/v3/benchmarks/attention/flash-attention.bench.ts
+++ /dev/null
@@ -1,452 +0,0 @@
-/**
- * Flash Attention Benchmark
- *
- * Target: 2.49x-7.47x speedup over standard attention
- *
- * Measures Flash Attention performance improvements including
- * memory efficiency and computational speedup.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, formatBytes } from '../framework/benchmark.js';
-
-// ============================================================================
-// Attention Types
-// ============================================================================
-
-interface AttentionConfig {
- seqLength: number;
- headDim: number;
- numHeads: number;
- batchSize: number;
-}
-
-interface AttentionResult {
- output: Float32Array;
- attentionWeights?: Float32Array;
- memoryUsed: number;
- computeTime: number;
-}
-
-// ============================================================================
-// Standard Attention Implementation
-// ============================================================================
-
-/**
- * Standard scaled dot-product attention
- * O(n^2) memory complexity for attention matrix
- */
-class StandardAttention {
- private config: AttentionConfig;
-
- constructor(config: AttentionConfig) {
- this.config = config;
- }
-
- forward(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array
- ): AttentionResult {
- const memBefore = process.memoryUsage().heapUsed;
- const startTime = performance.now();
-
- const { seqLength, headDim } = this.config;
-
- // Compute attention scores: Q @ K^T / sqrt(d_k)
- const scores = new Float32Array(seqLength * seqLength);
- const scale = 1 / Math.sqrt(headDim);
-
- for (let i = 0; i < seqLength; i++) {
- for (let j = 0; j < seqLength; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot += query[i * headDim + k]! * key[j * headDim + k]!;
- }
- scores[i * seqLength + j] = dot * scale;
- }
- }
-
- // Softmax
- for (let i = 0; i < seqLength; i++) {
- let max = -Infinity;
- for (let j = 0; j < seqLength; j++) {
- max = Math.max(max, scores[i * seqLength + j]!);
- }
-
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- const exp = Math.exp(scores[i * seqLength + j]! - max);
- scores[i * seqLength + j] = exp;
- sum += exp;
- }
-
- for (let j = 0; j < seqLength; j++) {
- scores[i * seqLength + j]! /= sum;
- }
- }
-
- // Attention output: scores @ V
- const output = new Float32Array(seqLength * headDim);
-
- for (let i = 0; i < seqLength; i++) {
- for (let j = 0; j < headDim; j++) {
- let sum = 0;
- for (let k = 0; k < seqLength; k++) {
- sum += scores[i * seqLength + k]! * value[k * headDim + j]!;
- }
- output[i * headDim + j] = sum;
- }
- }
-
- return {
- output,
- attentionWeights: scores,
- memoryUsed: process.memoryUsage().heapUsed - memBefore,
- computeTime: performance.now() - startTime,
- };
- }
-}
-
-/**
- * Flash Attention - memory efficient attention
- * Uses tiling to reduce memory from O(n^2) to O(n)
- */
-class FlashAttention {
- private config: AttentionConfig;
- private blockSize: number;
-
- constructor(config: AttentionConfig, blockSize: number = 64) {
- this.config = config;
- this.blockSize = blockSize;
- }
-
- forward(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array
- ): AttentionResult {
- const memBefore = process.memoryUsage().heapUsed;
- const startTime = performance.now();
-
- const { seqLength, headDim } = this.config;
- const blockSize = this.blockSize;
- const scale = 1 / Math.sqrt(headDim);
-
- // Output and running statistics
- const output = new Float32Array(seqLength * headDim);
- const rowMax = new Float32Array(seqLength).fill(-Infinity);
- const rowSum = new Float32Array(seqLength).fill(0);
-
- // Process in blocks (tiling)
- const numBlocks = Math.ceil(seqLength / blockSize);
-
- // Block buffers (reused, so O(blockSize^2) instead of O(n^2))
- const blockScores = new Float32Array(blockSize * blockSize);
-
- for (let bi = 0; bi < numBlocks; bi++) {
- const iStart = bi * blockSize;
- const iEnd = Math.min(iStart + blockSize, seqLength);
- const iSize = iEnd - iStart;
-
- for (let bj = 0; bj < numBlocks; bj++) {
- const jStart = bj * blockSize;
- const jEnd = Math.min(jStart + blockSize, seqLength);
- const jSize = jEnd - jStart;
-
- // Compute block scores
- for (let i = 0; i < iSize; i++) {
- for (let j = 0; j < jSize; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot +=
- query[(iStart + i) * headDim + k]! *
- key[(jStart + j) * headDim + k]!;
- }
- blockScores[i * blockSize + j] = dot * scale;
- }
- }
-
- // Online softmax update
- for (let i = 0; i < iSize; i++) {
- const globalI = iStart + i;
- let localMax = rowMax[globalI]!;
- let localSum = rowSum[globalI]!;
-
- // Find new max
- for (let j = 0; j < jSize; j++) {
- localMax = Math.max(localMax, blockScores[i * blockSize + j]!);
- }
-
- // Rescale previous sum
- const oldMax = rowMax[globalI]!;
- if (oldMax !== -Infinity) {
- localSum *= Math.exp(oldMax - localMax);
- }
-
- // Add new exponentials
- for (let j = 0; j < jSize; j++) {
- const exp = Math.exp(blockScores[i * blockSize + j]! - localMax);
- blockScores[i * blockSize + j] = exp;
- localSum += exp;
- }
-
- // Update output with rescaling
- if (oldMax !== -Infinity && oldMax !== localMax) {
- const rescale = Math.exp(oldMax - localMax);
- for (let k = 0; k < headDim; k++) {
- output[globalI * headDim + k]! *= rescale;
- }
- }
-
- // Add contribution from current block
- for (let k = 0; k < headDim; k++) {
- let contrib = 0;
- for (let j = 0; j < jSize; j++) {
- contrib +=
- blockScores[i * blockSize + j]! *
- value[(jStart + j) * headDim + k]!;
- }
- output[globalI * headDim + k]! += contrib;
- }
-
- rowMax[globalI] = localMax;
- rowSum[globalI] = localSum;
- }
- }
- }
-
- // Final normalization
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- output[i * headDim + k]! /= rowSum[i]!;
- }
- }
-
- return {
- output,
- memoryUsed: process.memoryUsage().heapUsed - memBefore,
- computeTime: performance.now() - startTime,
- };
- }
-}
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function generateRandomTensor(size: number): Float32Array {
- const tensor = new Float32Array(size);
- for (let i = 0; i < size; i++) {
- tensor[i] = Math.random() * 2 - 1;
- }
- return tensor;
-}
-
-function createQKV(
- seqLength: number,
- headDim: number
-): { query: Float32Array; key: Float32Array; value: Float32Array } {
- const size = seqLength * headDim;
- return {
- query: generateRandomTensor(size),
- key: generateRandomTensor(size),
- value: generateRandomTensor(size),
- };
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runFlashAttentionBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Flash Attention');
-
- console.log('\n--- Flash Attention Benchmarks ---\n');
-
- // Test configurations
- const configs: AttentionConfig[] = [
- { seqLength: 128, headDim: 64, numHeads: 8, batchSize: 1 },
- { seqLength: 256, headDim: 64, numHeads: 8, batchSize: 1 },
- { seqLength: 512, headDim: 64, numHeads: 8, batchSize: 1 },
- { seqLength: 1024, headDim: 64, numHeads: 8, batchSize: 1 },
- ];
-
- for (const config of configs) {
- const { seqLength, headDim } = config;
- console.log(`\n--- Sequence Length: ${seqLength} ---`);
-
- const standardAttn = new StandardAttention(config);
- const flashAttn = new FlashAttention(config, 64);
-
- const { query, key, value } = createQKV(seqLength, headDim);
-
- // Benchmark Standard Attention
- let standardResult: AttentionResult | null = null;
-
- const standardBenchResult = await runner.run(
- `standard-attention-seq${seqLength}`,
- async () => {
- standardResult = standardAttn.forward(query, key, value);
- },
- { iterations: seqLength <= 256 ? 100 : 20 }
- );
-
- console.log(`Standard Attention: ${formatTime(standardBenchResult.mean)}`);
- if (standardResult) {
- console.log(` Memory: ${formatBytes(standardResult.memoryUsed)}`);
- }
-
- // Benchmark Flash Attention
- let flashResult: AttentionResult | null = null;
-
- const flashBenchResult = await runner.run(
- `flash-attention-seq${seqLength}`,
- async () => {
- flashResult = flashAttn.forward(query, key, value);
- },
- { iterations: seqLength <= 256 ? 200 : 50 }
- );
-
- console.log(`Flash Attention: ${formatTime(flashBenchResult.mean)}`);
- if (flashResult) {
- console.log(` Memory: ${formatBytes(flashResult.memoryUsed)}`);
- }
-
- // Calculate speedup
- const speedup = standardBenchResult.mean / flashBenchResult.mean;
- console.log(`Speedup: ${speedup.toFixed(2)}x`);
-
- // Memory reduction
- if (standardResult && flashResult) {
- const memoryReduction =
- ((standardResult.memoryUsed - flashResult.memoryUsed) /
- standardResult.memoryUsed) *
- 100;
- console.log(`Memory Reduction: ${memoryReduction.toFixed(1)}%`);
- }
-
- // Check if within target range
- const targetMin = 2.49;
- const targetMax = 7.47;
- console.log(
- `Target (${targetMin}x-${targetMax}x): ${
- speedup >= targetMin ? 'PASS' : 'BELOW'
- }${speedup > targetMax ? ' (EXCEEDED!)' : ''}`
- );
- }
-
- // Benchmark block size variations
- console.log('\n--- Block Size Comparison (seq=512) ---');
-
- const testConfig: AttentionConfig = {
- seqLength: 512,
- headDim: 64,
- numHeads: 8,
- batchSize: 1,
- };
- const { query, key, value } = createQKV(testConfig.seqLength, testConfig.headDim);
-
- const blockSizes = [32, 64, 128, 256];
-
- for (const blockSize of blockSizes) {
- const flashAttn = new FlashAttention(testConfig, blockSize);
-
- const result = await runner.run(
- `flash-attention-block${blockSize}`,
- async () => {
- flashAttn.forward(query, key, value);
- },
- { iterations: 50 }
- );
-
- console.log(`Block Size ${blockSize}: ${formatTime(result.mean)}`);
- }
-
- // Memory scaling test
- console.log('\n--- Memory Scaling Analysis ---');
-
- const memoryTestConfigs = [128, 256, 512, 1024];
-
- for (const seqLen of memoryTestConfigs) {
- const config: AttentionConfig = {
- seqLength: seqLen,
- headDim: 64,
- numHeads: 8,
- batchSize: 1,
- };
-
- const standard = new StandardAttention(config);
- const flash = new FlashAttention(config);
- const qkv = createQKV(seqLen, 64);
-
- // Force GC
- if (typeof global.gc === 'function') global.gc();
- const memBefore = process.memoryUsage().heapUsed;
-
- const stdResult = standard.forward(qkv.query, qkv.key, qkv.value);
- const stdMem = process.memoryUsage().heapUsed - memBefore;
-
- if (typeof global.gc === 'function') global.gc();
- const memBefore2 = process.memoryUsage().heapUsed;
-
- const flashRes = flash.forward(qkv.query, qkv.key, qkv.value);
- const flashMem = process.memoryUsage().heapUsed - memBefore2;
-
- console.log(
- `Seq ${seqLen}: Standard ${formatBytes(stdMem)} vs Flash ${formatBytes(flashMem)}`
- );
- }
-
- // Print summary
- console.log('\n--- Summary ---');
- const results = runner.getResults();
-
- const seq512Standard = results.find((r) => r.name === 'standard-attention-seq512');
- const seq512Flash = results.find((r) => r.name === 'flash-attention-seq512');
-
- if (seq512Standard && seq512Flash) {
- const speedup = seq512Standard.mean / seq512Flash.mean;
- console.log(`Primary Benchmark (seq=512):`);
- console.log(` Standard: ${formatTime(seq512Standard.mean)}`);
- console.log(` Flash: ${formatTime(seq512Flash.mean)}`);
- console.log(` Speedup: ${speedup.toFixed(2)}x`);
- console.log(` Target (2.49x-7.47x): ${speedup >= 2.49 ? 'ACHIEVED' : 'NOT MET'}`);
- }
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Flash Attention Optimization Strategies
-// ============================================================================
-
-export const flashAttentionOptimizations = {
- optimalBlockSize: {
- description: 'Choose block size based on hardware cache size',
- expectedImprovement: '10-30% depending on hardware',
- },
- simdVectorization: {
- description: 'Use SIMD instructions for dot products and softmax',
- expectedImprovement: '2-4x speedup',
- },
- fusedOperations: {
- description: 'Fuse softmax and matrix multiplication',
- expectedImprovement: '20-40% memory bandwidth',
- },
- multiQueryAttention: {
- description: 'Share K and V across attention heads',
- expectedImprovement: '2-4x memory, 1.5-2x speed',
- },
- gradientCheckpointing: {
- description: 'Recompute attention instead of storing for backprop',
- expectedImprovement: 'O(1) memory for attention during training',
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runFlashAttentionBenchmarks().catch(console.error);
-}
-
-export default runFlashAttentionBenchmarks;
diff --git a/v3/benchmarks/attention/memory-efficiency.bench.ts b/v3/benchmarks/attention/memory-efficiency.bench.ts
deleted file mode 100644
index 280f7a4023..0000000000
--- a/v3/benchmarks/attention/memory-efficiency.bench.ts
+++ /dev/null
@@ -1,569 +0,0 @@
-/**
- * Attention Memory Efficiency Benchmark
- *
- * Target: 50-75% memory reduction
- *
- * Measures memory efficiency of different attention implementations
- * and optimization strategies.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, formatBytes } from '../framework/benchmark.js';
-
-// ============================================================================
-// Memory Tracking
-// ============================================================================
-
-interface MemorySnapshot {
- heapUsed: number;
- heapTotal: number;
- external: number;
- arrayBuffers: number;
- rss: number;
-}
-
-function takeMemorySnapshot(): MemorySnapshot {
- const mem = process.memoryUsage();
- return {
- heapUsed: mem.heapUsed,
- heapTotal: mem.heapTotal,
- external: mem.external,
- arrayBuffers: mem.arrayBuffers,
- rss: mem.rss,
- };
-}
-
-function calculateMemoryDelta(before: MemorySnapshot, after: MemorySnapshot): number {
- return after.heapUsed - before.heapUsed;
-}
-
-// ============================================================================
-// Attention Implementations for Memory Testing
-// ============================================================================
-
-/**
- * Standard attention - stores full attention matrix
- */
-function standardAttention(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array,
- seqLength: number,
- headDim: number
-): { output: Float32Array; attentionMatrix: Float32Array } {
- const scale = 1 / Math.sqrt(headDim);
-
- // Full attention matrix - O(n^2) memory
- const attentionMatrix = new Float32Array(seqLength * seqLength);
-
- // Compute scores
- for (let i = 0; i < seqLength; i++) {
- for (let j = 0; j < seqLength; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot += query[i * headDim + k]! * key[j * headDim + k]!;
- }
- attentionMatrix[i * seqLength + j] = dot * scale;
- }
- }
-
- // Softmax
- for (let i = 0; i < seqLength; i++) {
- let max = -Infinity;
- for (let j = 0; j < seqLength; j++) {
- max = Math.max(max, attentionMatrix[i * seqLength + j]!);
- }
-
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- const exp = Math.exp(attentionMatrix[i * seqLength + j]! - max);
- attentionMatrix[i * seqLength + j] = exp;
- sum += exp;
- }
-
- for (let j = 0; j < seqLength; j++) {
- attentionMatrix[i * seqLength + j]! /= sum;
- }
- }
-
- // Output
- const output = new Float32Array(seqLength * headDim);
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- sum += attentionMatrix[i * seqLength + j]! * value[j * headDim + k]!;
- }
- output[i * headDim + k] = sum;
- }
- }
-
- return { output, attentionMatrix };
-}
-
-/**
- * Memory-efficient attention - no full matrix storage
- */
-function memoryEfficientAttention(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array,
- seqLength: number,
- headDim: number
-): { output: Float32Array } {
- const scale = 1 / Math.sqrt(headDim);
- const output = new Float32Array(seqLength * headDim);
-
- // Process row by row - O(n) memory for scores
- const rowScores = new Float32Array(seqLength);
-
- for (let i = 0; i < seqLength; i++) {
- // Compute scores for this row
- let max = -Infinity;
- for (let j = 0; j < seqLength; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot += query[i * headDim + k]! * key[j * headDim + k]!;
- }
- rowScores[j] = dot * scale;
- max = Math.max(max, rowScores[j]!);
- }
-
- // Softmax
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- rowScores[j] = Math.exp(rowScores[j]! - max);
- sum += rowScores[j]!;
- }
- for (let j = 0; j < seqLength; j++) {
- rowScores[j]! /= sum;
- }
-
- // Compute output for this row
- for (let k = 0; k < headDim; k++) {
- let val = 0;
- for (let j = 0; j < seqLength; j++) {
- val += rowScores[j]! * value[j * headDim + k]!;
- }
- output[i * headDim + k] = val;
- }
- }
-
- return { output };
-}
-
-/**
- * Chunked attention - process in blocks
- */
-function chunkedAttention(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array,
- seqLength: number,
- headDim: number,
- chunkSize: number = 64
-): { output: Float32Array } {
- const scale = 1 / Math.sqrt(headDim);
- const output = new Float32Array(seqLength * headDim);
- const numChunks = Math.ceil(seqLength / chunkSize);
-
- // Chunk buffer - O(chunkSize^2) memory
- const chunkScores = new Float32Array(chunkSize * seqLength);
- const rowMax = new Float32Array(chunkSize).fill(-Infinity);
- const rowSum = new Float32Array(chunkSize).fill(0);
-
- for (let ci = 0; ci < numChunks; ci++) {
- const iStart = ci * chunkSize;
- const iEnd = Math.min(iStart + chunkSize, seqLength);
- const iSize = iEnd - iStart;
-
- // Reset accumulators
- rowMax.fill(-Infinity);
- rowSum.fill(0);
- output.fill(0, iStart * headDim, iEnd * headDim);
-
- for (let cj = 0; cj < numChunks; cj++) {
- const jStart = cj * chunkSize;
- const jEnd = Math.min(jStart + chunkSize, seqLength);
- const jSize = jEnd - jStart;
-
- // Compute chunk scores
- for (let i = 0; i < iSize; i++) {
- for (let j = 0; j < jSize; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot += query[(iStart + i) * headDim + k]! * key[(jStart + j) * headDim + k]!;
- }
- chunkScores[i * seqLength + jStart + j] = dot * scale;
- }
- }
-
- // Online softmax update
- for (let i = 0; i < iSize; i++) {
- const prevMax = rowMax[i]!;
-
- // Find new max
- for (let j = 0; j < jSize; j++) {
- rowMax[i] = Math.max(rowMax[i]!, chunkScores[i * seqLength + jStart + j]!);
- }
-
- // Rescale previous
- if (prevMax !== -Infinity && prevMax !== rowMax[i]) {
- const rescale = Math.exp(prevMax - rowMax[i]!);
- rowSum[i]! *= rescale;
- for (let k = 0; k < headDim; k++) {
- output[(iStart + i) * headDim + k]! *= rescale;
- }
- }
-
- // Add new exponentials
- for (let j = 0; j < jSize; j++) {
- const exp = Math.exp(chunkScores[i * seqLength + jStart + j]! - rowMax[i]!);
- chunkScores[i * seqLength + jStart + j] = exp;
- rowSum[i]! += exp;
- }
-
- // Accumulate output
- for (let k = 0; k < headDim; k++) {
- for (let j = 0; j < jSize; j++) {
- output[(iStart + i) * headDim + k]! +=
- chunkScores[i * seqLength + jStart + j]! * value[(jStart + j) * headDim + k]!;
- }
- }
- }
- }
-
- // Final normalization
- for (let i = 0; i < iSize; i++) {
- for (let k = 0; k < headDim; k++) {
- output[(iStart + i) * headDim + k]! /= rowSum[i]!;
- }
- }
- }
-
- return { output };
-}
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function generateRandomTensor(size: number): Float32Array {
- const tensor = new Float32Array(size);
- for (let i = 0; i < size; i++) {
- tensor[i] = Math.random() * 2 - 1;
- }
- return tensor;
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runMemoryEfficiencyBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Attention Memory Efficiency');
-
- console.log('\n--- Attention Memory Efficiency Benchmarks ---\n');
-
- // Test configurations
- const seqLengths = [128, 256, 512, 1024];
- const headDim = 64;
-
- // Memory scaling comparison
- console.log('--- Memory Scaling by Sequence Length ---\n');
-
- const memoryResults: Array<{
- seqLength: number;
- standard: number;
- efficient: number;
- chunked: number;
- reduction: number;
- }> = [];
-
- for (const seqLength of seqLengths) {
- console.log(`Sequence Length: ${seqLength}`);
-
- const size = seqLength * headDim;
- const query = generateRandomTensor(size);
- const key = generateRandomTensor(size);
- const value = generateRandomTensor(size);
-
- // Standard attention memory
- if (typeof global.gc === 'function') global.gc();
- const standardBefore = takeMemorySnapshot();
- const standardResult = standardAttention(query, key, value, seqLength, headDim);
- const standardAfter = takeMemorySnapshot();
- const standardMem = calculateMemoryDelta(standardBefore, standardAfter);
- void standardResult;
-
- // Memory-efficient attention
- if (typeof global.gc === 'function') global.gc();
- const efficientBefore = takeMemorySnapshot();
- const efficientResult = memoryEfficientAttention(query, key, value, seqLength, headDim);
- const efficientAfter = takeMemorySnapshot();
- const efficientMem = calculateMemoryDelta(efficientBefore, efficientAfter);
- void efficientResult;
-
- // Chunked attention
- if (typeof global.gc === 'function') global.gc();
- const chunkedBefore = takeMemorySnapshot();
- const chunkedResult = chunkedAttention(query, key, value, seqLength, headDim);
- const chunkedAfter = takeMemorySnapshot();
- const chunkedMem = calculateMemoryDelta(chunkedBefore, chunkedAfter);
- void chunkedResult;
-
- const reduction = ((standardMem - efficientMem) / standardMem) * 100;
-
- memoryResults.push({
- seqLength,
- standard: standardMem,
- efficient: efficientMem,
- chunked: chunkedMem,
- reduction,
- });
-
- console.log(` Standard: ${formatBytes(standardMem)}`);
- console.log(` Efficient: ${formatBytes(efficientMem)}`);
- console.log(` Chunked: ${formatBytes(chunkedMem)}`);
- console.log(` Reduction: ${reduction.toFixed(1)}%`);
- console.log('');
- }
-
- // Theoretical memory comparison
- console.log('--- Theoretical Memory Analysis ---\n');
-
- for (const seqLength of seqLengths) {
- const bytesPerFloat = 4;
-
- // Standard: stores full n x n attention matrix
- const standardTheory = seqLength * seqLength * bytesPerFloat;
-
- // Efficient: stores only one row at a time
- const efficientTheory = seqLength * bytesPerFloat;
-
- // Chunked: stores chunk x n scores
- const chunkSize = 64;
- const chunkedTheory = chunkSize * seqLength * bytesPerFloat;
-
- console.log(`Seq ${seqLength}:`);
- console.log(` Standard: ${formatBytes(standardTheory)} (n^2)`);
- console.log(` Efficient: ${formatBytes(efficientTheory)} (n)`);
- console.log(` Chunked: ${formatBytes(chunkedTheory)} (chunk * n)`);
- console.log(` Theoretical reduction: ${((1 - efficientTheory / standardTheory) * 100).toFixed(1)}%`);
- console.log('');
- }
-
- // Performance vs Memory tradeoff
- console.log('--- Performance vs Memory Tradeoff ---\n');
-
- const tradeoffConfig = { seqLength: 512, headDim: 64 };
- const size = tradeoffConfig.seqLength * tradeoffConfig.headDim;
- const q = generateRandomTensor(size);
- const k = generateRandomTensor(size);
- const v = generateRandomTensor(size);
-
- // Standard performance
- const standardPerfResult = await runner.run(
- 'standard-attention-perf',
- async () => {
- standardAttention(q, k, v, tradeoffConfig.seqLength, tradeoffConfig.headDim);
- },
- { iterations: 20 }
- );
-
- console.log(`Standard Performance: ${formatTime(standardPerfResult.mean)}`);
-
- // Efficient performance
- const efficientPerfResult = await runner.run(
- 'efficient-attention-perf',
- async () => {
- memoryEfficientAttention(q, k, v, tradeoffConfig.seqLength, tradeoffConfig.headDim);
- },
- { iterations: 20 }
- );
-
- console.log(`Memory-Efficient Performance: ${formatTime(efficientPerfResult.mean)}`);
-
- // Chunked performance with different chunk sizes
- const chunkSizes = [32, 64, 128, 256];
-
- for (const chunkSize of chunkSizes) {
- const chunkedPerfResult = await runner.run(
- `chunked-attention-chunk${chunkSize}`,
- async () => {
- chunkedAttention(q, k, v, tradeoffConfig.seqLength, tradeoffConfig.headDim, chunkSize);
- },
- { iterations: 20 }
- );
-
- console.log(`Chunked (size=${chunkSize}): ${formatTime(chunkedPerfResult.mean)}`);
- }
-
- // Multi-head memory analysis
- console.log('\n--- Multi-Head Memory Analysis ---\n');
-
- const numHeads = [4, 8, 16, 32];
- const mhaSeqLength = 256;
-
- for (const heads of numHeads) {
- const mhaSize = mhaSeqLength * headDim;
-
- // Standard MHA memory
- const standardMHAMem = mhaSeqLength * mhaSeqLength * 4 * heads; // attention matrices
- const qkvMem = mhaSize * 4 * 3 * heads; // QKV storage
-
- // GQA memory (shared KV)
- const gqaKVHeads = heads / 4;
- const gqaMem = mhaSeqLength * mhaSeqLength * 4 * heads + // attention matrices (same)
- mhaSize * 4 * heads + // Q storage
- mhaSize * 4 * 2 * gqaKVHeads; // shared KV
-
- // MQA memory (single KV)
- const mqaMem = mhaSeqLength * mhaSeqLength * 4 * heads + // attention matrices
- mhaSize * 4 * heads + // Q storage
- mhaSize * 4 * 2; // single KV
-
- console.log(`${heads} heads:`);
- console.log(` Standard MHA: ${formatBytes(standardMHAMem + qkvMem)}`);
- console.log(` GQA (${gqaKVHeads} KV): ${formatBytes(gqaMem)}`);
- console.log(` MQA (1 KV): ${formatBytes(mqaMem)}`);
- console.log(` MQA reduction: ${(((standardMHAMem + qkvMem) - mqaMem) / (standardMHAMem + qkvMem) * 100).toFixed(1)}%`);
- console.log('');
- }
-
- // Summary
- console.log('--- Summary ---\n');
-
- console.log('Memory Reduction Achieved:');
- for (const result of memoryResults) {
- const targetMet = result.reduction >= 50;
- console.log(
- ` Seq ${result.seqLength}: ${result.reduction.toFixed(1)}% ${targetMet ? '(TARGET MET)' : ''}`
- );
- }
-
- console.log('\nPerformance Comparison (seq=512):');
- console.log(` Standard: ${formatTime(standardPerfResult.mean)}`);
- console.log(` Efficient: ${formatTime(efficientPerfResult.mean)}`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Memory Efficiency Optimization Strategies
-// ============================================================================
-
-export const memoryOptimizations = {
- /**
- * Online softmax computation
- */
- onlineSoftmax: {
- description: 'Compute softmax in streaming fashion without storing all values',
- expectedImprovement: 'O(n) instead of O(n^2) for softmax',
- implementation: `
- class OnlineSoftmax {
- private max = -Infinity;
- private sum = 0;
- private count = 0;
-
- add(value: number): void {
- if (value > this.max) {
- this.sum *= Math.exp(this.max - value);
- this.max = value;
- }
- this.sum += Math.exp(value - this.max);
- this.count++;
- }
-
- normalize(value: number): number {
- return Math.exp(value - this.max) / this.sum;
- }
- }
- `,
- },
-
- /**
- * Gradient checkpointing
- */
- gradientCheckpointing: {
- description: 'Recompute attention during backward pass instead of storing',
- expectedImprovement: 'O(1) memory for activations',
- implementation: `
- function checkpointedAttention(q, k, v) {
- const output = computeAttention(q, k, v);
-
- function backward(gradOutput) {
- // Recompute attention weights during backward
- const attnWeights = recomputeAttention(q, k);
- return computeGradients(gradOutput, attnWeights, q, k, v);
- }
-
- return { output, backward };
- }
- `,
- },
-
- /**
- * Sparse attention patterns
- */
- sparseAttention: {
- description: 'Only compute attention for relevant positions',
- expectedImprovement: 'O(n * k) instead of O(n^2) where k << n',
- implementation: `
- function sparseAttention(q, k, v, pattern: 'local' | 'strided' | 'block') {
- const sparseMask = generateSparsePattern(q.length, pattern);
- return computeAttentionWithMask(q, k, v, sparseMask);
- }
- `,
- },
-
- /**
- * Quantization
- */
- quantization: {
- description: 'Use lower precision for attention computation',
- expectedImprovement: '2-4x memory reduction',
- implementation: `
- function quantizedAttention(q, k, v) {
- // Quantize to int8
- const qInt8 = quantizeToInt8(q);
- const kInt8 = quantizeToInt8(k);
-
- // Compute in int8
- const scores = computeInt8Attention(qInt8, kInt8);
-
- // Dequantize for output
- return dequantizeAndApply(scores, v);
- }
- `,
- },
-
- /**
- * Memory pooling
- */
- memoryPooling: {
- description: 'Reuse memory buffers across forward passes',
- expectedImprovement: 'Eliminates allocation overhead',
- implementation: `
- class AttentionMemoryPool {
- private scoreBuffer: Float32Array;
- private outputBuffer: Float32Array;
-
- forward(q, k, v) {
- // Reuse pre-allocated buffers
- computeScores(q, k, this.scoreBuffer);
- applySoftmax(this.scoreBuffer);
- computeOutput(this.scoreBuffer, v, this.outputBuffer);
- return this.outputBuffer;
- }
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runMemoryEfficiencyBenchmarks().catch(console.error);
-}
-
-export default runMemoryEfficiencyBenchmarks;
diff --git a/v3/benchmarks/attention/multi-head-attention.bench.ts b/v3/benchmarks/attention/multi-head-attention.bench.ts
deleted file mode 100644
index 84b1fa630c..0000000000
--- a/v3/benchmarks/attention/multi-head-attention.bench.ts
+++ /dev/null
@@ -1,566 +0,0 @@
-/**
- * Multi-Head Attention Benchmark
- *
- * Target: Baseline comparison for Flash Attention improvements
- *
- * Measures multi-head attention performance with different
- * configurations and parallelization strategies.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, formatBytes } from '../framework/benchmark.js';
-
-// ============================================================================
-// Multi-Head Attention Types
-// ============================================================================
-
-interface MHAConfig {
- seqLength: number;
- headDim: number;
- numHeads: number;
- batchSize: number;
- dropout?: number;
-}
-
-interface MHAResult {
- output: Float32Array;
- headOutputs: Float32Array[];
- memoryUsed: number;
- computeTime: number;
-}
-
-// ============================================================================
-// Multi-Head Attention Implementation
-// ============================================================================
-
-/**
- * Standard multi-head attention
- */
-class MultiHeadAttention {
- private config: MHAConfig;
-
- constructor(config: MHAConfig) {
- this.config = config;
- }
-
- /**
- * Single head attention
- */
- private singleHeadAttention(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array
- ): Float32Array {
- const { seqLength, headDim } = this.config;
- const scale = 1 / Math.sqrt(headDim);
-
- // Compute attention scores
- const scores = new Float32Array(seqLength * seqLength);
-
- for (let i = 0; i < seqLength; i++) {
- for (let j = 0; j < seqLength; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot += query[i * headDim + k]! * key[j * headDim + k]!;
- }
- scores[i * seqLength + j] = dot * scale;
- }
- }
-
- // Softmax
- for (let i = 0; i < seqLength; i++) {
- let max = -Infinity;
- for (let j = 0; j < seqLength; j++) {
- max = Math.max(max, scores[i * seqLength + j]!);
- }
-
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- const exp = Math.exp(scores[i * seqLength + j]! - max);
- scores[i * seqLength + j] = exp;
- sum += exp;
- }
-
- for (let j = 0; j < seqLength; j++) {
- scores[i * seqLength + j]! /= sum;
- }
- }
-
- // Weighted sum
- const output = new Float32Array(seqLength * headDim);
-
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- sum += scores[i * seqLength + j]! * value[j * headDim + k]!;
- }
- output[i * headDim + k] = sum;
- }
- }
-
- return output;
- }
-
- /**
- * Forward pass through all heads sequentially
- */
- forwardSequential(
- queries: Float32Array[],
- keys: Float32Array[],
- values: Float32Array[]
- ): MHAResult {
- const memBefore = process.memoryUsage().heapUsed;
- const startTime = performance.now();
-
- const { seqLength, headDim, numHeads } = this.config;
- const headOutputs: Float32Array[] = [];
-
- // Process each head sequentially
- for (let h = 0; h < numHeads; h++) {
- const headOutput = this.singleHeadAttention(
- queries[h]!,
- keys[h]!,
- values[h]!
- );
- headOutputs.push(headOutput);
- }
-
- // Concatenate heads
- const output = new Float32Array(seqLength * headDim * numHeads);
- for (let h = 0; h < numHeads; h++) {
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- output[i * headDim * numHeads + h * headDim + k] =
- headOutputs[h]![i * headDim + k]!;
- }
- }
- }
-
- return {
- output,
- headOutputs,
- memoryUsed: process.memoryUsage().heapUsed - memBefore,
- computeTime: performance.now() - startTime,
- };
- }
-
- /**
- * Forward pass with parallel head computation (simulated)
- */
- async forwardParallel(
- queries: Float32Array[],
- keys: Float32Array[],
- values: Float32Array[]
- ): Promise<MHAResult> {
- const memBefore = process.memoryUsage().heapUsed;
- const startTime = performance.now();
-
- const { seqLength, headDim, numHeads } = this.config;
-
- // Process all heads in parallel
- const headPromises = queries.map((q, h) =>
- Promise.resolve(this.singleHeadAttention(q, keys[h]!, values[h]!))
- );
-
- const headOutputs = await Promise.all(headPromises);
-
- // Concatenate heads
- const output = new Float32Array(seqLength * headDim * numHeads);
- for (let h = 0; h < numHeads; h++) {
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- output[i * headDim * numHeads + h * headDim + k] =
- headOutputs[h]![i * headDim + k]!;
- }
- }
- }
-
- return {
- output,
- headOutputs,
- memoryUsed: process.memoryUsage().heapUsed - memBefore,
- computeTime: performance.now() - startTime,
- };
- }
-}
-
-/**
- * Grouped-Query Attention (GQA)
- * Multiple query heads share fewer key/value heads
- */
-class GroupedQueryAttention {
- private config: MHAConfig;
- private kvHeads: number;
- private groupSize: number;
-
- constructor(config: MHAConfig, kvHeads: number) {
- this.config = config;
- this.kvHeads = kvHeads;
- this.groupSize = config.numHeads / kvHeads;
- }
-
- forward(
- queries: Float32Array[],
- keys: Float32Array[],
- values: Float32Array[]
- ): MHAResult {
- const memBefore = process.memoryUsage().heapUsed;
- const startTime = performance.now();
-
- const { seqLength, headDim, numHeads } = this.config;
- const headOutputs: Float32Array[] = [];
-
- // Process each query head, sharing K/V within groups
- for (let h = 0; h < numHeads; h++) {
- const kvIndex = Math.floor(h / this.groupSize);
- const headOutput = this.singleHeadAttention(
- queries[h]!,
- keys[kvIndex]!,
- values[kvIndex]!
- );
- headOutputs.push(headOutput);
- }
-
- // Concatenate heads
- const output = new Float32Array(seqLength * headDim * numHeads);
- for (let h = 0; h < numHeads; h++) {
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- output[i * headDim * numHeads + h * headDim + k] =
- headOutputs[h]![i * headDim + k]!;
- }
- }
- }
-
- return {
- output,
- headOutputs,
- memoryUsed: process.memoryUsage().heapUsed - memBefore,
- computeTime: performance.now() - startTime,
- };
- }
-
- private singleHeadAttention(
- query: Float32Array,
- key: Float32Array,
- value: Float32Array
- ): Float32Array {
- const { seqLength, headDim } = this.config;
- const scale = 1 / Math.sqrt(headDim);
-
- const scores = new Float32Array(seqLength * seqLength);
-
- for (let i = 0; i < seqLength; i++) {
- for (let j = 0; j < seqLength; j++) {
- let dot = 0;
- for (let k = 0; k < headDim; k++) {
- dot += query[i * headDim + k]! * key[j * headDim + k]!;
- }
- scores[i * seqLength + j] = dot * scale;
- }
- }
-
- // Softmax
- for (let i = 0; i < seqLength; i++) {
- let max = -Infinity;
- for (let j = 0; j < seqLength; j++) {
- max = Math.max(max, scores[i * seqLength + j]!);
- }
-
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- const exp = Math.exp(scores[i * seqLength + j]! - max);
- scores[i * seqLength + j] = exp;
- sum += exp;
- }
-
- for (let j = 0; j < seqLength; j++) {
- scores[i * seqLength + j]! /= sum;
- }
- }
-
- const output = new Float32Array(seqLength * headDim);
-
- for (let i = 0; i < seqLength; i++) {
- for (let k = 0; k < headDim; k++) {
- let sum = 0;
- for (let j = 0; j < seqLength; j++) {
- sum += scores[i * seqLength + j]! * value[j * headDim + k]!;
- }
- output[i * headDim + k] = sum;
- }
- }
-
- return output;
- }
-}
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function generateRandomTensor(size: number): Float32Array {
- const tensor = new Float32Array(size);
- for (let i = 0; i < size; i++) {
- tensor[i] = Math.random() * 2 - 1;
- }
- return tensor;
-}
-
-function createMultiHeadQKV(
- config: MHAConfig
-): { queries: Float32Array[]; keys: Float32Array[]; values: Float32Array[] } {
- const { seqLength, headDim, numHeads } = config;
- const size = seqLength * headDim;
-
- return {
- queries: Array.from({ length: numHeads }, () => generateRandomTensor(size)),
- keys: Array.from({ length: numHeads }, () => generateRandomTensor(size)),
- values: Array.from({ length: numHeads }, () => generateRandomTensor(size)),
- };
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runMultiHeadAttentionBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Multi-Head Attention');
-
- console.log('\n--- Multi-Head Attention Benchmarks ---\n');
-
- // Test configurations
- const configs: MHAConfig[] = [
- { seqLength: 128, headDim: 64, numHeads: 8, batchSize: 1 },
- { seqLength: 256, headDim: 64, numHeads: 8, batchSize: 1 },
- { seqLength: 512, headDim: 64, numHeads: 8, batchSize: 1 },
- { seqLength: 256, headDim: 64, numHeads: 16, batchSize: 1 },
- ];
-
- for (const config of configs) {
- const { seqLength, numHeads } = config;
- console.log(`\n--- Seq: ${seqLength}, Heads: ${numHeads} ---`);
-
- const mha = new MultiHeadAttention(config);
- const { queries, keys, values } = createMultiHeadQKV(config);
-
- // Sequential forward
- const seqResult = await runner.run(
- `mha-sequential-seq${seqLength}-h${numHeads}`,
- async () => {
- mha.forwardSequential(queries, keys, values);
- },
- { iterations: 50 }
- );
-
- console.log(`Sequential: ${formatTime(seqResult.mean)}`);
-
- // Parallel forward
- const parallelResult = await runner.run(
- `mha-parallel-seq${seqLength}-h${numHeads}`,
- async () => {
- await mha.forwardParallel(queries, keys, values);
- },
- { iterations: 50 }
- );
-
- console.log(`Parallel: ${formatTime(parallelResult.mean)}`);
-
- // Speedup
- const speedup = seqResult.mean / parallelResult.mean;
- console.log(`Parallel Speedup: ${speedup.toFixed(2)}x`);
- }
-
- // Grouped-Query Attention comparison
- console.log('\n--- Grouped-Query Attention Comparison ---');
-
- const gqaConfig: MHAConfig = {
- seqLength: 256,
- headDim: 64,
- numHeads: 8,
- batchSize: 1,
- };
-
- const standardMHA = new MultiHeadAttention(gqaConfig);
- const { queries, keys, values } = createMultiHeadQKV(gqaConfig);
-
- // Standard MHA (8 query heads, 8 KV heads)
- const standardResult = await runner.run(
- 'mha-standard-8heads',
- async () => {
- standardMHA.forwardSequential(queries, keys, values);
- },
- { iterations: 50 }
- );
-
- console.log(`Standard MHA (8 QKV heads): ${formatTime(standardResult.mean)}`);
-
- // GQA with 4 KV heads
- const gqa4 = new GroupedQueryAttention(gqaConfig, 4);
- const kvFor4 = {
- keys: keys.slice(0, 4),
- values: values.slice(0, 4),
- };
-
- const gqa4Result = await runner.run(
- 'gqa-4-kv-heads',
- async () => {
- gqa4.forward(queries, kvFor4.keys, kvFor4.values);
- },
- { iterations: 50 }
- );
-
- console.log(`GQA (8 Q, 4 KV heads): ${formatTime(gqa4Result.mean)}`);
-
- // GQA with 2 KV heads
- const gqa2 = new GroupedQueryAttention(gqaConfig, 2);
- const kvFor2 = {
- keys: keys.slice(0, 2),
- values: values.slice(0, 2),
- };
-
- const gqa2Result = await runner.run(
- 'gqa-2-kv-heads',
- async () => {
- gqa2.forward(queries, kvFor2.keys, kvFor2.values);
- },
- { iterations: 50 }
- );
-
- console.log(`GQA (8 Q, 2 KV heads): ${formatTime(gqa2Result.mean)}`);
-
- // Memory comparison
- console.log('\n--- Memory Usage Comparison ---');
-
- const memConfig: MHAConfig = {
- seqLength: 512,
- headDim: 64,
- numHeads: 8,
- batchSize: 1,
- };
-
- const { queries: q512, keys: k512, values: v512 } = createMultiHeadQKV(memConfig);
- const mha512 = new MultiHeadAttention(memConfig);
-
- const memResult = mha512.forwardSequential(q512, k512, v512);
- console.log(`MHA Memory (seq=512, h=8): ${formatBytes(memResult.memoryUsed)}`);
-
- // Per-head memory
- const perHeadMem = memResult.memoryUsed / memConfig.numHeads;
- console.log(`Per-head memory: ${formatBytes(perHeadMem)}`);
-
- // Theoretical attention matrix size
- const attentionMatrixSize = memConfig.seqLength * memConfig.seqLength * 4 * memConfig.numHeads;
- console.log(`Theoretical attention matrices: ${formatBytes(attentionMatrixSize)}`);
-
- // Summary
- console.log('\n--- Summary ---');
- console.log('Standard MHA vs GQA:');
- console.log(` 8 KV heads: ${formatTime(standardResult.mean)}`);
- console.log(` 4 KV heads: ${formatTime(gqa4Result.mean)} (${(standardResult.mean / gqa4Result.mean).toFixed(2)}x)`);
- console.log(` 2 KV heads: ${formatTime(gqa2Result.mean)} (${(standardResult.mean / gqa2Result.mean).toFixed(2)}x)`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Multi-Head Attention Optimization Strategies
-// ============================================================================
-
-export const mhaOptimizations = {
- /**
- * Parallel head computation
- */
- parallelHeads: {
- description: 'Compute attention heads in parallel',
- expectedImprovement: 'Up to num_heads x speedup',
- implementation: `
- async function parallelMHA(queries, keys, values) {
- const headResults = await Promise.all(
- queries.map((q, i) => computeHead(q, keys[i], values[i]))
- );
- return concatenateHeads(headResults);
- }
- `,
- },
-
- /**
- * Grouped-Query Attention
- */
- groupedQueryAttention: {
- description: 'Share K/V across multiple query heads',
- expectedImprovement: '2-4x memory, 1.5-2x speed',
- implementation: `
- // Instead of numHeads K/V pairs, use numHeads / groupSize
- class GQA {
- forward(queries, keys, values) {
- return queries.map((q, i) => {
- const kvIdx = Math.floor(i / groupSize);
- return attention(q, keys[kvIdx], values[kvIdx]);
- });
- }
- }
- `,
- },
-
- /**
- * Multi-Query Attention
- */
- multiQueryAttention: {
- description: 'Single K/V pair shared across all heads',
- expectedImprovement: '8x memory, 2-3x speed',
- implementation: `
- class MQA {
- forward(queries, key, value) {
- // All heads share single K and V
- return queries.map(q => attention(q, key, value));
- }
- }
- `,
- },
-
- /**
- * Fused QKV projection
- */
- fusedQKVProjection: {
- description: 'Fuse Q, K, V projections into single operation',
- expectedImprovement: '20-30% projection overhead',
- implementation: `
- function fusedQKV(input, weights) {
- // Single matmul for all QKV
- const qkv = matmul(input, weights.qkv);
- return splitQKV(qkv, numHeads, headDim);
- }
- `,
- },
-
- /**
- * KV caching for inference
- */
- kvCaching: {
- description: 'Cache K/V for autoregressive generation',
- expectedImprovement: 'O(1) per token instead of O(n)',
- implementation: `
- class CachedMHA {
- private kvCache: { k: Float32Array[], v: Float32Array[] } = { k: [], v: [] };
-
- forward(query, key, value, useCache: boolean) {
- if (useCache) {
- this.kvCache.k.push(key);
- this.kvCache.v.push(value);
- return attention(query, this.kvCache.k, this.kvCache.v);
- }
- return attention(query, [key], [value]);
- }
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runMultiHeadAttentionBenchmarks().catch(console.error);
-}
-
-export default runMultiHeadAttentionBenchmarks;
diff --git a/v3/benchmarks/framework/benchmark.ts b/v3/benchmarks/framework/benchmark.ts
deleted file mode 100644
index a14b92723a..0000000000
--- a/v3/benchmarks/framework/benchmark.ts
+++ /dev/null
@@ -1,583 +0,0 @@
-/**
- * V3 Performance Benchmark Framework
- *
- * Comprehensive benchmarking system with statistical analysis,
- * memory tracking, and regression detection capabilities.
- *
- * Target Performance Metrics:
- * - CLI Startup: <500ms (5x faster)
- * - MCP Init: <400ms (4.5x faster)
- * - Agent Spawn: <200ms (4x faster)
- * - Vector Search: <1ms (150x faster)
- * - Memory Write: <5ms (10x faster)
- * - Swarm Consensus: <100ms (5x faster)
- * - Flash Attention: 2.49x-7.47x speedup
- * - Memory Usage: <256MB (50% reduction)
- */
-
-import { performance, PerformanceObserver } from 'perf_hooks';
-
-// ============================================================================
-// Types and Interfaces
-// ============================================================================
-
-export interface MemoryUsage {
- heapUsed: number;
- heapTotal: number;
- external: number;
- arrayBuffers: number;
- rss: number;
-}
-
-export interface BenchmarkResult {
- name: string;
- iterations: number;
- mean: number;
- median: number;
- p95: number;
- p99: number;
- min: number;
- max: number;
- stdDev: number;
- opsPerSecond: number;
- memoryUsage: MemoryUsage;
- memoryDelta: number;
- timestamp: number;
- metadata?: Record<string, unknown>;
-}
-
-export interface BenchmarkOptions {
- /** Number of iterations (default: 100) */
- iterations?: number;
- /** Number of warmup iterations (default: 10) */
- warmup?: number;
- /** Timeout per iteration in ms (default: 30000) */
- timeout?: number;
- /** Force garbage collection between iterations */
- forceGC?: boolean;
- /** Custom metadata to attach to results */
- metadata?: Record<string, unknown>;
- /** Minimum number of runs to ensure statistical significance */
- minRuns?: number;
- /** Target time in ms for auto-calibration */
- targetTime?: number;
-}
-
-export interface BenchmarkSuite {
- name: string;
- benchmarks: BenchmarkResult[];
- totalTime: number;
- timestamp: number;
- environment: EnvironmentInfo;
-}
-
-export interface EnvironmentInfo {
- nodeVersion: string;
- platform: string;
- arch: string;
- cpus: number;
- memory: number;
- v8Version?: string;
-}
-
-export interface ComparisonResult {
- benchmark: string;
- baseline: number;
- current: number;
- change: number;
- changePercent: number;
- improved: boolean;
- significant: boolean;
- target?: number;
- targetMet: boolean;
-}
-
-// ============================================================================
-// Statistical Functions
-// ============================================================================
-
-/**
- * Calculate mean of an array of numbers
- */
-function calculateMean(values: number[]): number {
- if (values.length === 0) return 0;
- return values.reduce((sum, val) => sum + val, 0) / values.length;
-}
-
-/**
- * Calculate median of an array of numbers
- */
-function calculateMedian(values: number[]): number {
- if (values.length === 0) return 0;
- const sorted = [...values].sort((a, b) => a - b);
- const mid = Math.floor(sorted.length / 2);
- return sorted.length % 2 !== 0
- ? sorted[mid]!
- : (sorted[mid - 1]! + sorted[mid]!) / 2;
-}
-
-/**
- * Calculate percentile of an array of numbers
- */
-function calculatePercentile(values: number[], percentile: number): number {
- if (values.length === 0) return 0;
- const sorted = [...values].sort((a, b) => a - b);
- const index = Math.ceil((percentile / 100) * sorted.length) - 1;
- return sorted[Math.max(0, index)]!;
-}
-
-/**
- * Calculate standard deviation of an array of numbers
- */
-function calculateStdDev(values: number[]): number {
- if (values.length < 2) return 0;
- const mean = calculateMean(values);
- const squaredDiffs = values.map((val) => Math.pow(val - mean, 2));
- return Math.sqrt(calculateMean(squaredDiffs));
-}
-
-/**
- * Remove outliers using IQR method
- */
-function removeOutliers(values: number[]): number[] {
- if (values.length < 4) return values;
-
- const sorted = [...values].sort((a, b) => a - b);
- const q1 = calculatePercentile(sorted, 25);
- const q3 = calculatePercentile(sorted, 75);
- const iqr = q3 - q1;
- const lowerBound = q1 - 1.5 * iqr;
- const upperBound = q3 + 1.5 * iqr;
-
- return sorted.filter((val) => val >= lowerBound && val <= upperBound);
-}
-
-// ============================================================================
-// Memory Utilities
-// ============================================================================
-
-/**
- * Get current memory usage
- */
-function getMemoryUsage(): MemoryUsage {
- const mem = process.memoryUsage();
- return {
- heapUsed: mem.heapUsed,
- heapTotal: mem.heapTotal,
- external: mem.external,
- arrayBuffers: mem.arrayBuffers,
- rss: mem.rss,
- };
-}
-
-/**
- * Format bytes to human-readable string
- */
-export function formatBytes(bytes: number): string {
- const units = ['B', 'KB', 'MB', 'GB'];
- let unitIndex = 0;
- let value = bytes;
-
- while (value >= 1024 && unitIndex < units.length - 1) {
- value /= 1024;
- unitIndex++;
- }
-
- return `${value.toFixed(2)} ${units[unitIndex]}`;
-}
-
-/**
- * Format time in milliseconds to human-readable string
- */
-export function formatTime(ms: number): string {
- if (ms < 0.001) {
- return `${(ms * 1000000).toFixed(2)} ns`;
- } else if (ms < 1) {
- return `${(ms * 1000).toFixed(2)} us`;
- } else if (ms < 1000) {
- return `${ms.toFixed(2)} ms`;
- } else {
- return `${(ms / 1000).toFixed(2)} s`;
- }
-}
-
-/**
- * Force garbage collection if available
- */
-function forceGC(): void {
- if (typeof global.gc === 'function') {
- global.gc();
- }
-}
-
-// ============================================================================
-// Core Benchmark Function
-// ============================================================================
-
-/**
- * Execute a benchmark with comprehensive statistics
- */
-export async function benchmark(
- name: string,
- fn: () => Promise<void> | void,
- options: BenchmarkOptions = {}
-): Promise<BenchmarkResult> {
- const {
- iterations = 100,
- warmup = 10,
- timeout = 30000,
- forceGC: doForceGC = false,
- metadata = {},
- minRuns = 10,
- targetTime = 1000,
- } = options;
-
- // Calculate actual iterations based on target time
- let actualIterations = iterations;
-
- // Warmup phase
- for (let i = 0; i < warmup; i++) {
- await Promise.race([
- fn(),
- new Promise((_, reject) =>
- setTimeout(() => reject(new Error('Warmup timeout')), timeout)
- ),
- ]).catch(() => {});
- }
-
- // Auto-calibrate iterations if needed
- const calibrationStart = performance.now();
- await fn();
- const calibrationTime = performance.now() - calibrationStart;
-
- if (calibrationTime > 0) {
- const estimatedIterations = Math.ceil(targetTime / calibrationTime);
- actualIterations = Math.max(minRuns, Math.min(iterations, estimatedIterations));
- }
-
- // Memory before benchmark
- if (doForceGC) forceGC();
- const memoryBefore = getMemoryUsage();
-
- // Run benchmark
- const times: number[] = [];
- const startTime = performance.now();
-
- for (let i = 0; i < actualIterations; i++) {
- if (doForceGC && i % 10 === 0) forceGC();
-
- const iterStart = performance.now();
-
- await Promise.race([
- fn(),
- new Promise((_, reject) =>
- setTimeout(() => reject(new Error('Iteration timeout')), timeout)
- ),
- ]);
-
- const iterEnd = performance.now();
- times.push(iterEnd - iterStart);
- }
-
- const totalTime = performance.now() - startTime;
-
- // Memory after benchmark
- const memoryAfter = getMemoryUsage();
-
- // Calculate statistics (remove outliers for more accurate results)
- const cleanedTimes = removeOutliers(times);
- const mean = calculateMean(cleanedTimes);
- const median = calculateMedian(cleanedTimes);
- const p95 = calculatePercentile(cleanedTimes, 95);
- const p99 = calculatePercentile(cleanedTimes, 99);
- const min = Math.min(...cleanedTimes);
- const max = Math.max(...cleanedTimes);
- const stdDev = calculateStdDev(cleanedTimes);
- const opsPerSecond = mean > 0 ? 1000 / mean : 0;
-
- return {
- name,
- iterations: actualIterations,
- mean,
- median,
- p95,
- p99,
- min,
- max,
- stdDev,
- opsPerSecond,
- memoryUsage: memoryAfter,
- memoryDelta: memoryAfter.heapUsed - memoryBefore.heapUsed,
- timestamp: Date.now(),
- metadata,
- };
-}
-
-// ============================================================================
-// Benchmark Suite Runner
-// ============================================================================
-
-export class BenchmarkRunner {
- private results: BenchmarkResult[] = [];
- private suiteName: string;
-
- constructor(name: string) {
- this.suiteName = name;
- }
-
- /**
- * Run a single benchmark and add to results
- */
- async run(
- name: string,
- fn: () => Promise<void> | void,
- options?: BenchmarkOptions
- ): Promise<BenchmarkResult> {
- const result = await benchmark(name, fn, options);
- this.results.push(result);
- return result;
- }
-
- /**
- * Run multiple benchmarks in sequence
- */
- async runAll(
- benchmarks: Array<{
- name: string;
- fn: () => Promise<void> | void;
- options?: BenchmarkOptions;
- }>
- ): Promise<BenchmarkSuite> {
- const startTime = performance.now();
-
- for (const bench of benchmarks) {
- await this.run(bench.name, bench.fn, bench.options);
- }
-
- return {
- name: this.suiteName,
- benchmarks: this.results,
- totalTime: performance.now() - startTime,
- timestamp: Date.now(),
- environment: this.getEnvironmentInfo(),
- };
- }
-
- /**
- * Get environment information
- */
- private getEnvironmentInfo(): EnvironmentInfo {
- const os = require('os');
- return {
- nodeVersion: process.version,
- platform: process.platform,
- arch: process.arch,
- cpus: os.cpus().length,
- memory: os.totalmem(),
- v8Version: process.versions.v8,
- };
- }
-
- /**
- * Get all results
- */
- getResults(): BenchmarkResult[] {
- return this.results;
- }
-
- /**
- * Clear all results
- */
- clear(): void {
- this.results = [];
- }
-
- /**
- * Print formatted results to console
- */
- printResults(): void {
- console.log(`\n${'='.repeat(60)}`);
- console.log(`Benchmark Suite: ${this.suiteName}`);
- console.log(`${'='.repeat(60)}\n`);
-
- for (const result of this.results) {
- console.log(`${result.name}:`);
- console.log(` Iterations: ${result.iterations}`);
- console.log(` Mean: ${formatTime(result.mean)}`);
- console.log(` Median: ${formatTime(result.median)}`);
- console.log(` Std Dev: ${formatTime(result.stdDev)}`);
- console.log(` P95: ${formatTime(result.p95)}`);
- console.log(` P99: ${formatTime(result.p99)}`);
- console.log(` Min: ${formatTime(result.min)}`);
- console.log(` Max: ${formatTime(result.max)}`);
- console.log(` Ops/sec: ${result.opsPerSecond.toFixed(2)}`);
- console.log(` Memory Delta: ${formatBytes(result.memoryDelta)}`);
- console.log('');
- }
- }
-
- /**
- * Export results as JSON
- */
- toJSON(): string {
- return JSON.stringify(
- {
- name: this.suiteName,
- benchmarks: this.results,
- timestamp: Date.now(),
- environment: this.getEnvironmentInfo(),
- },
- null,
- 2
- );
- }
-}
-
-// ============================================================================
-// Comparison Utilities
-// ============================================================================
-
-/**
- * Compare benchmark results against baseline
- */
-export function compareResults(
- baseline: BenchmarkResult[],
- current: BenchmarkResult[],
- targets?: Record<string, number>
-): ComparisonResult[] {
- const comparisons: ComparisonResult[] = [];
-
- for (const curr of current) {
- const base = baseline.find((b) => b.name === curr.name);
- if (!base) continue;
-
- const change = curr.mean - base.mean;
- const changePercent = (change / base.mean) * 100;
- const improved = change < 0;
-
- // Consider significant if change is > 5% and > 2 standard deviations
- const combinedStdDev = Math.sqrt(
- Math.pow(base.stdDev, 2) + Math.pow(curr.stdDev, 2)
- );
- const significant = Math.abs(change) > 2 * combinedStdDev;
-
- const target = targets?.[curr.name];
- const targetMet = target !== undefined ? curr.mean <= target : true;
-
- comparisons.push({
- benchmark: curr.name,
- baseline: base.mean,
- current: curr.mean,
- change,
- changePercent,
- improved,
- significant,
- target,
- targetMet,
- });
- }
-
- return comparisons;
-}
-
-/**
- * Print comparison report
- */
-export function printComparisonReport(comparisons: ComparisonResult[]): void {
- console.log('\n' + '='.repeat(80));
- console.log('Performance Comparison Report');
- console.log('='.repeat(80) + '\n');
-
- console.log(
- `${'Benchmark'.padEnd(35)} ${'Baseline'.padEnd(12)} ${'Current'.padEnd(12)} ${'Change'.padEnd(12)} Status`
- );
- console.log('-'.repeat(80));
-
- for (const comp of comparisons) {
- const baselineStr = formatTime(comp.baseline);
- const currentStr = formatTime(comp.current);
- const changeStr = `${comp.changePercent >= 0 ? '+' : ''}${comp.changePercent.toFixed(1)}%`;
-
- let status = '';
- if (comp.significant) {
- status = comp.improved ? '[IMPROVED]' : '[REGRESSED]';
- } else {
- status = '[~]';
- }
- if (!comp.targetMet) {
- status += ' [MISSED TARGET]';
- }
-
- console.log(
- `${comp.benchmark.padEnd(35)} ${baselineStr.padEnd(12)} ${currentStr.padEnd(12)} ${changeStr.padEnd(12)} ${status}`
- );
- }
-
- console.log('\n');
-}
-
-// ============================================================================
-// V3 Performance Targets
-// ============================================================================
-
-export const V3_PERFORMANCE_TARGETS = {
- // Startup Performance
- 'cli-cold-start': 500, // <500ms (5x faster)
- 'cli-warm-start': 100, // <100ms
- 'mcp-server-init': 400, // <400ms (4.5x faster)
- 'agent-spawn': 200, // <200ms (4x faster)
-
- // Memory Operations
- 'vector-search': 1, // <1ms (150x faster)
- 'hnsw-indexing': 10, // <10ms
- 'memory-write': 5, // <5ms (10x faster)
- 'cache-hit': 0.1, // <0.1ms
-
- // Swarm Coordination
- 'agent-coordination': 50, // <50ms
- 'task-decomposition': 20, // <20ms
- 'consensus-latency': 100, // <100ms (5x faster)
- 'message-throughput': 0.1, // <0.1ms per message
-
- // Attention Mechanisms
- 'flash-attention': 100, // Baseline comparison target
- 'multi-head-attention': 200, // Baseline comparison target
-
- // SONA Learning
- 'sona-adaptation': 0.05, // <0.05ms
-} as const;
-
-export type PerformanceTarget = keyof typeof V3_PERFORMANCE_TARGETS;
-
-/**
- * Check if a benchmark meets its target
- */
-export function meetsTarget(
- benchmarkName: string,
- value: number
-): { met: boolean; target: number | undefined; ratio: number | undefined } {
- const target = V3_PERFORMANCE_TARGETS[benchmarkName as PerformanceTarget];
- if (target === undefined) {
- return { met: true, target: undefined, ratio: undefined };
- }
- return {
- met: value <= target,
- target,
- ratio: value / target,
- };
-}
-
-// ============================================================================
-// Export Default Runner Instance
-// ============================================================================
-
-export default {
- benchmark,
- BenchmarkRunner,
- compareResults,
- printComparisonReport,
- formatBytes,
- formatTime,
- meetsTarget,
- V3_PERFORMANCE_TARGETS,
-};
diff --git a/v3/benchmarks/index.ts b/v3/benchmarks/index.ts
deleted file mode 100644
index b5e22913f1..0000000000
--- a/v3/benchmarks/index.ts
+++ /dev/null
@@ -1,224 +0,0 @@
-/**
- * V3 Benchmark Suite Entry Point
- *
- * Comprehensive benchmark suite for validating V3 performance targets:
- * - Flash Attention: 2.49x-7.47x speedup
- * - AgentDB Search: 150x-12,500x improvement
- * - Memory Reduction: 50-75%
- * - Startup Time: <500ms
- * - SONA Learning: <0.05ms adaptation
- */
-
-// Framework exports
-export * from './framework/benchmark.js';
-
-// Startup benchmarks
-export { default as runColdStartBenchmarks } from './startup/cli-cold-start.bench.js';
-export { default as runWarmStartBenchmarks } from './startup/cli-warm-start.bench.js';
-export { default as runMCPInitBenchmarks } from './startup/mcp-server-init.bench.js';
-export { default as runAgentSpawnBenchmarks } from './startup/agent-spawn.bench.js';
-
-// Memory benchmarks
-export { default as runVectorSearchBenchmarks } from './memory/vector-search.bench.js';
-export { default as runHNSWIndexingBenchmarks } from './memory/hnsw-indexing.bench.js';
-export { default as runMemoryWriteBenchmarks } from './memory/memory-write.bench.js';
-export { default as runCacheHitRateBenchmarks } from './memory/cache-hit-rate.bench.js';
-
-// Swarm benchmarks
-export { default as runAgentCoordinationBenchmarks } from './swarm/agent-coordination.bench.js';
-export { default as runTaskDecompositionBenchmarks } from './swarm/task-decomposition.bench.js';
-export { default as runConsensusLatencyBenchmarks } from './swarm/consensus-latency.bench.js';
-export { default as runMessageThroughputBenchmarks } from './swarm/message-throughput.bench.js';
-
-// Attention benchmarks
-export { default as runFlashAttentionBenchmarks } from './attention/flash-attention.bench.js';
-export { default as runMultiHeadAttentionBenchmarks } from './attention/multi-head-attention.bench.js';
-export { default as runMemoryEfficiencyBenchmarks } from './attention/memory-efficiency.bench.js';
-
-// Regression detection
-export { default as compareWithBaseline } from './regression/compare.js';
-export { default as generateReport } from './regression/report.js';
-
-// ============================================================================
-// Benchmark Runner
-// ============================================================================
-
-interface BenchmarkSuiteConfig {
- categories?: string[];
- verbose?: boolean;
- outputFormat?: 'console' | 'json' | 'markdown' | 'html';
- outputPath?: string;
- compareBaseline?: boolean;
- baselinePath?: string;
-}
-
-/**
- * Run all benchmarks
- */
-export async function runAllBenchmarks(config: BenchmarkSuiteConfig = {}): Promise<void> {
- const {
- categories = ['startup', 'memory', 'swarm', 'attention'],
- verbose = true,
- } = config;
-
- console.log('=' .repeat(80));
- console.log('V3 Performance Benchmark Suite');
- console.log('=' .repeat(80));
- console.log('');
- console.log('Target Performance Metrics:');
- console.log(' - CLI Startup: <500ms (5x faster)');
- console.log(' - MCP Init: <400ms (4.5x faster)');
- console.log(' - Agent Spawn: <200ms (4x faster)');
- console.log(' - Vector Search: <1ms (150x-12,500x faster)');
- console.log(' - Memory Write: <5ms (10x faster)');
- console.log(' - Consensus: <100ms (5x faster)');
- console.log(' - Flash Attention: 2.49x-7.47x speedup');
- console.log(' - Memory Usage: <256MB (50% reduction)');
- console.log('');
-
- const startTime = performance.now();
-
- // Startup benchmarks
- if (categories.includes('startup')) {
- console.log('\n' + '='.repeat(60));
- console.log('STARTUP BENCHMARKS');
- console.log('='.repeat(60));
-
- const { default: runColdStart } = await import('./startup/cli-cold-start.bench.js');
- const { default: runWarmStart } = await import('./startup/cli-warm-start.bench.js');
- const { default: runMCPInit } = await import('./startup/mcp-server-init.bench.js');
- const { default: runAgentSpawn } = await import('./startup/agent-spawn.bench.js');
-
- await runColdStart();
- await runWarmStart();
- await runMCPInit();
- await runAgentSpawn();
- }
-
- // Memory benchmarks
- if (categories.includes('memory')) {
- console.log('\n' + '='.repeat(60));
- console.log('MEMORY BENCHMARKS');
- console.log('='.repeat(60));
-
- const { default: runVectorSearch } = await import('./memory/vector-search.bench.js');
- const { default: runHNSWIndexing } = await import('./memory/hnsw-indexing.bench.js');
- const { default: runMemoryWrite } = await import('./memory/memory-write.bench.js');
- const { default: runCacheHitRate } = await import('./memory/cache-hit-rate.bench.js');
-
- await runVectorSearch();
- await runHNSWIndexing();
- await runMemoryWrite();
- await runCacheHitRate();
- }
-
- // Swarm benchmarks
- if (categories.includes('swarm')) {
- console.log('\n' + '='.repeat(60));
- console.log('SWARM BENCHMARKS');
- console.log('='.repeat(60));
-
- const { default: runAgentCoordination } = await import('./swarm/agent-coordination.bench.js');
- const { default: runTaskDecomposition } = await import('./swarm/task-decomposition.bench.js');
- const { default: runConsensusLatency } = await import('./swarm/consensus-latency.bench.js');
- const { default: runMessageThroughput } = await import('./swarm/message-throughput.bench.js');
-
- await runAgentCoordination();
- await runTaskDecomposition();
- await runConsensusLatency();
- await runMessageThroughput();
- }
-
- // Attention benchmarks
- if (categories.includes('attention')) {
- console.log('\n' + '='.repeat(60));
- console.log('ATTENTION BENCHMARKS');
- console.log('='.repeat(60));
-
- const { default: runFlashAttention } = await import('./attention/flash-attention.bench.js');
- const { default: runMultiHeadAttention } = await import('./attention/multi-head-attention.bench.js');
- const { default: runMemoryEfficiency } = await import('./attention/memory-efficiency.bench.js');
-
- await runFlashAttention();
- await runMultiHeadAttention();
- await runMemoryEfficiency();
- }
-
- const totalTime = performance.now() - startTime;
-
- console.log('\n' + '='.repeat(80));
- console.log('BENCHMARK SUITE COMPLETE');
- console.log('='.repeat(80));
- console.log(`Total time: ${(totalTime / 1000).toFixed(2)}s`);
- console.log('');
-}
-
-/**
- * Run specific benchmark category
- */
-export async function runCategory(category: string): Promise<void> {
- switch (category.toLowerCase()) {
- case 'startup':
- const { default: runColdStart } = await import('./startup/cli-cold-start.bench.js');
- const { default: runWarmStart } = await import('./startup/cli-warm-start.bench.js');
- const { default: runMCPInit } = await import('./startup/mcp-server-init.bench.js');
- const { default: runAgentSpawn } = await import('./startup/agent-spawn.bench.js');
- await runColdStart();
- await runWarmStart();
- await runMCPInit();
- await runAgentSpawn();
- break;
-
- case 'memory':
- const { default: runVectorSearch } = await import('./memory/vector-search.bench.js');
- const { default: runHNSWIndexing } = await import('./memory/hnsw-indexing.bench.js');
- const { default: runMemoryWrite } = await import('./memory/memory-write.bench.js');
- const { default: runCacheHitRate } = await import('./memory/cache-hit-rate.bench.js');
- await runVectorSearch();
- await runHNSWIndexing();
- await runMemoryWrite();
- await runCacheHitRate();
- break;
-
- case 'swarm':
- const { default: runAgentCoordination } = await import('./swarm/agent-coordination.bench.js');
- const { default: runTaskDecomposition } = await import('./swarm/task-decomposition.bench.js');
- const { default: runConsensusLatency } = await import('./swarm/consensus-latency.bench.js');
- const { default: runMessageThroughput } = await import('./swarm/message-throughput.bench.js');
- await runAgentCoordination();
- await runTaskDecomposition();
- await runConsensusLatency();
- await runMessageThroughput();
- break;
-
- case 'attention':
- const { default: runFlashAttention } = await import('./attention/flash-attention.bench.js');
- const { default: runMultiHeadAttention } = await import('./attention/multi-head-attention.bench.js');
- const { default: runMemoryEfficiency } = await import('./attention/memory-efficiency.bench.js');
- await runFlashAttention();
- await runMultiHeadAttention();
- await runMemoryEfficiency();
- break;
-
- default:
- console.error(`Unknown category: ${category}`);
- console.log('Available categories: startup, memory, swarm, attention');
- }
-}
-
-// CLI interface
-if (import.meta.url === `file://${process.argv[1]}`) {
- const args = process.argv.slice(2);
- const category = args[0];
-
- if (category) {
- runCategory(category).catch(console.error);
- } else {
- runAllBenchmarks().catch(console.error);
- }
-}
-
-export default {
- runAllBenchmarks,
- runCategory,
-};
diff --git a/v3/benchmarks/regression/baseline-v2.json b/v3/benchmarks/regression/baseline-v2.json
deleted file mode 100644
index 61190454bb..0000000000
--- a/v3/benchmarks/regression/baseline-v2.json
+++ /dev/null
@@ -1,228 +0,0 @@
-{
- "version": "2.0.0",
- "timestamp": "2026-01-04T00:00:00.000Z",
- "environment": {
- "nodeVersion": "v20.0.0",
- "platform": "linux",
- "arch": "x64",
- "cpus": 4,
- "memory": 8589934592
- },
- "benchmarks": {
- "startup": {
- "cli-cold-start": {
- "mean": 2500,
- "median": 2450,
- "p95": 2800,
- "p99": 3000,
- "unit": "ms",
- "target": 500,
- "description": "CLI cold start time"
- },
- "cli-warm-start": {
- "mean": 500,
- "median": 480,
- "p95": 600,
- "p99": 700,
- "unit": "ms",
- "target": 100,
- "description": "CLI warm start time"
- },
- "mcp-server-init": {
- "mean": 1800,
- "median": 1750,
- "p95": 2000,
- "p99": 2200,
- "unit": "ms",
- "target": 400,
- "description": "MCP server initialization"
- },
- "agent-spawn": {
- "mean": 800,
- "median": 780,
- "p95": 900,
- "p99": 1000,
- "unit": "ms",
- "target": 200,
- "description": "Single agent spawn time"
- }
- },
- "memory": {
- "vector-search-1k": {
- "mean": 15,
- "median": 14,
- "p95": 18,
- "p99": 20,
- "unit": "ms",
- "target": 1,
- "description": "Linear search 1000 vectors"
- },
- "vector-search-10k": {
- "mean": 150,
- "median": 145,
- "p95": 170,
- "p99": 190,
- "unit": "ms",
- "target": 1,
- "description": "Linear search 10000 vectors"
- },
- "hnsw-indexing": {
- "mean": 50,
- "median": 48,
- "p95": 60,
- "p99": 70,
- "unit": "ms",
- "target": 10,
- "description": "HNSW index single insert"
- },
- "memory-write": {
- "mean": 50,
- "median": 48,
- "p95": 60,
- "p99": 70,
- "unit": "ms",
- "target": 5,
- "description": "Memory store write operation"
- },
- "cache-hit-rate": {
- "mean": 0.5,
- "median": 0.45,
- "p95": 0.6,
- "p99": 0.7,
- "unit": "ms",
- "target": 0.1,
- "description": "Cache hit lookup time"
- }
- },
- "swarm": {
- "agent-coordination-5": {
- "mean": 100,
- "median": 95,
- "p95": 120,
- "p99": 140,
- "unit": "ms",
- "target": 50,
- "description": "5-agent coordination"
- },
- "agent-coordination-15": {
- "mean": 250,
- "median": 240,
- "p95": 300,
- "p99": 350,
- "unit": "ms",
- "target": 50,
- "description": "15-agent coordination"
- },
- "task-decomposition": {
- "mean": 40,
- "median": 38,
- "p95": 50,
- "p99": 60,
- "unit": "ms",
- "target": 20,
- "description": "Task decomposition time"
- },
- "consensus-latency": {
- "mean": 500,
- "median": 480,
- "p95": 600,
- "p99": 700,
- "unit": "ms",
- "target": 100,
- "description": "Consensus achievement time"
- },
- "message-throughput": {
- "mean": 0.5,
- "median": 0.45,
- "p95": 0.6,
- "p99": 0.7,
- "unit": "ms",
- "target": 0.1,
- "description": "Per-message delivery time"
- }
- },
- "attention": {
- "standard-attention-512": {
- "mean": 100,
- "median": 95,
- "p95": 120,
- "p99": 140,
- "unit": "ms",
- "target": null,
- "description": "Standard attention baseline (seq=512)"
- },
- "flash-attention-512": {
- "mean": 100,
- "median": 95,
- "p95": 120,
- "p99": 140,
- "unit": "ms",
- "target": null,
- "description": "Flash attention (seq=512) - not yet implemented"
- }
- },
- "system": {
- "memory-usage-baseline": {
- "mean": 536870912,
- "median": 524288000,
- "p95": 600000000,
- "p99": 650000000,
- "unit": "bytes",
- "target": 268435456,
- "description": "Baseline memory usage (512MB -> 256MB target)"
- },
- "sona-adaptation": {
- "mean": 1,
- "median": 0.9,
- "p95": 1.5,
- "p99": 2,
- "unit": "ms",
- "target": 0.05,
- "description": "SONA learning adaptation time"
- }
- }
- },
- "targets": {
- "cli-cold-start": {
- "v2": 2500,
- "v3": 500,
- "improvement": "5x"
- },
- "mcp-server-init": {
- "v2": 1800,
- "v3": 400,
- "improvement": "4.5x"
- },
- "agent-spawn": {
- "v2": 800,
- "v3": 200,
- "improvement": "4x"
- },
- "vector-search": {
- "v2": 150,
- "v3": 1,
- "improvement": "150x"
- },
- "memory-write": {
- "v2": 50,
- "v3": 5,
- "improvement": "10x"
- },
- "consensus-latency": {
- "v2": 500,
- "v3": 100,
- "improvement": "5x"
- },
- "flash-attention": {
- "v2": null,
- "v3": "2.49x-7.47x",
- "improvement": "2.49x-7.47x speedup"
- },
- "memory-usage": {
- "v2": 512,
- "v3": 256,
- "improvement": "50% reduction",
- "unit": "MB"
- }
- }
-}
diff --git a/v3/benchmarks/regression/compare.ts b/v3/benchmarks/regression/compare.ts
deleted file mode 100644
index d9ff5d4eba..0000000000
--- a/v3/benchmarks/regression/compare.ts
+++ /dev/null
@@ -1,381 +0,0 @@
-/**
- * Benchmark Comparison Utility
- *
- * Compares current benchmark results against baseline to detect
- * performance regressions and validate improvements.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { BenchmarkResult, compareResults, printComparisonReport, formatTime, formatBytes } from '../framework/benchmark.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface BaselineBenchmark {
- mean: number;
- median: number;
- p95: number;
- p99: number;
- unit: string;
- target: number | null;
- description: string;
-}
-
-interface BaselineData {
- version: string;
- timestamp: string;
- environment: {
- nodeVersion: string;
- platform: string;
- arch: string;
- cpus: number;
- memory: number;
- };
- benchmarks: {
- [category: string]: {
- [name: string]: BaselineBenchmark;
- };
- };
- targets: {
- [name: string]: {
- v2: number | null;
- v3: number | string;
- improvement: string;
- unit?: string;
- };
- };
-}
-
-interface ComparisonSummary {
- totalBenchmarks: number;
- improved: number;
- regressed: number;
- unchanged: number;
- targetsMet: number;
- targetsMissed: number;
- overallStatus: 'pass' | 'fail' | 'warning';
- details: ComparisonDetail[];
-}
-
-interface ComparisonDetail {
- category: string;
- name: string;
- baseline: number;
- current: number;
- change: number;
- changePercent: number;
- target: number | null;
- targetMet: boolean;
- status: 'improved' | 'regressed' | 'unchanged';
- severity: 'critical' | 'warning' | 'info';
-}
-
-// ============================================================================
-// Comparison Logic
-// ============================================================================
-
-/**
- * Load baseline data from JSON file
- */
-export function loadBaseline(baselinePath: string): BaselineData {
- const content = fs.readFileSync(baselinePath, 'utf-8');
- return JSON.parse(content) as BaselineData;
-}
-
-/**
- * Compare a single benchmark against baseline
- */
-function compareBenchmark(
- name: string,
- category: string,
- current: number,
- baseline: BaselineBenchmark
-): ComparisonDetail {
- const change = current - baseline.mean;
- const changePercent = (change / baseline.mean) * 100;
-
- // Determine status
- let status: 'improved' | 'regressed' | 'unchanged';
- if (changePercent <= -5) {
- status = 'improved';
- } else if (changePercent >= 5) {
- status = 'regressed';
- } else {
- status = 'unchanged';
- }
-
- // Check target
- const targetMet = baseline.target === null || current <= baseline.target;
-
- // Determine severity
- let severity: 'critical' | 'warning' | 'info';
- if (status === 'regressed' && changePercent >= 20) {
- severity = 'critical';
- } else if (status === 'regressed' || !targetMet) {
- severity = 'warning';
- } else {
- severity = 'info';
- }
-
- return {
- category,
- name,
- baseline: baseline.mean,
- current,
- change,
- changePercent,
- target: baseline.target,
- targetMet,
- status,
- severity,
- };
-}
-
-/**
- * Compare current results against baseline
- */
-export function compareWithBaseline(
- currentResults: Map<string, number>,
- baseline: BaselineData
-): ComparisonSummary {
- const details: ComparisonDetail[] = [];
-
- // Compare each category
- for (const [category, benchmarks] of Object.entries(baseline.benchmarks)) {
- for (const [name, baselineBench] of Object.entries(benchmarks)) {
- const current = currentResults.get(`${category}/${name}`) || currentResults.get(name);
- if (current !== undefined) {
- details.push(compareBenchmark(name, category, current, baselineBench));
- }
- }
- }
-
- // Calculate summary
- const improved = details.filter((d) => d.status === 'improved').length;
- const regressed = details.filter((d) => d.status === 'regressed').length;
- const unchanged = details.filter((d) => d.status === 'unchanged').length;
- const targetsMet = details.filter((d) => d.targetMet).length;
- const targetsMissed = details.filter((d) => !d.targetMet).length;
-
- // Determine overall status
- let overallStatus: 'pass' | 'fail' | 'warning';
- const criticalRegressions = details.filter(
- (d) => d.severity === 'critical'
- ).length;
-
- if (criticalRegressions > 0) {
- overallStatus = 'fail';
- } else if (regressed > improved || targetsMissed > 0) {
- overallStatus = 'warning';
- } else {
- overallStatus = 'pass';
- }
-
- return {
- totalBenchmarks: details.length,
- improved,
- regressed,
- unchanged,
- targetsMet,
- targetsMissed,
- overallStatus,
- details,
- };
-}
-
-/**
- * Print comparison summary
- */
-export function printComparisonSummary(summary: ComparisonSummary): void {
- console.log('\n' + '='.repeat(80));
- console.log('Performance Regression Analysis');
- console.log('='.repeat(80) + '\n');
-
- // Overall status
- const statusSymbol =
- summary.overallStatus === 'pass'
- ? '[PASS]'
- : summary.overallStatus === 'fail'
- ? '[FAIL]'
- : '[WARN]';
-
- console.log(`Overall Status: ${statusSymbol}\n`);
-
- // Summary stats
- console.log('Summary:');
- console.log(` Total Benchmarks: ${summary.totalBenchmarks}`);
- console.log(` Improved: ${summary.improved}`);
- console.log(` Regressed: ${summary.regressed}`);
- console.log(` Unchanged: ${summary.unchanged}`);
- console.log(` Targets Met: ${summary.targetsMet}`);
- console.log(` Targets Missed: ${summary.targetsMissed}`);
-
- // Critical regressions
- const critical = summary.details.filter((d) => d.severity === 'critical');
- if (critical.length > 0) {
- console.log('\n--- CRITICAL REGRESSIONS ---\n');
- for (const detail of critical) {
- console.log(
- ` [CRITICAL] ${detail.category}/${detail.name}: ` +
- `${formatTime(detail.baseline)} -> ${formatTime(detail.current)} ` +
- `(${detail.changePercent >= 0 ? '+' : ''}${detail.changePercent.toFixed(1)}%)`
- );
- }
- }
-
- // Warnings
- const warnings = summary.details.filter((d) => d.severity === 'warning');
- if (warnings.length > 0) {
- console.log('\n--- WARNINGS ---\n');
- for (const detail of warnings) {
- const reason = !detail.targetMet
- ? `missed target ${formatTime(detail.target!)}`
- : 'regression';
- console.log(
- ` [WARN] ${detail.category}/${detail.name}: ` +
- `${formatTime(detail.baseline)} -> ${formatTime(detail.current)} ` +
- `(${reason})`
- );
- }
- }
-
- // Improvements
- const improvements = summary.details.filter((d) => d.status === 'improved');
- if (improvements.length > 0) {
- console.log('\n--- IMPROVEMENTS ---\n');
- for (const detail of improvements) {
- console.log(
- ` [OK] ${detail.category}/${detail.name}: ` +
- `${formatTime(detail.baseline)} -> ${formatTime(detail.current)} ` +
- `(${detail.changePercent.toFixed(1)}%)`
- );
- }
- }
-
- // V3 Target Progress
- console.log('\n--- V3 TARGET PROGRESS ---\n');
-
- const targetProgress = [
- { name: 'CLI Cold Start', target: 500, unit: 'ms', improvement: '5x' },
- { name: 'MCP Server Init', target: 400, unit: 'ms', improvement: '4.5x' },
- { name: 'Agent Spawn', target: 200, unit: 'ms', improvement: '4x' },
- { name: 'Vector Search', target: 1, unit: 'ms', improvement: '150x' },
- { name: 'Memory Write', target: 5, unit: 'ms', improvement: '10x' },
- { name: 'Consensus Latency', target: 100, unit: 'ms', improvement: '5x' },
- { name: 'Flash Attention', target: null, unit: '', improvement: '2.49x-7.47x' },
- { name: 'Memory Usage', target: 256, unit: 'MB', improvement: '50%' },
- ];
-
- console.log(
- `${'Target'.padEnd(20)} ${'Goal'.padEnd(12)} ${'Expected'.padEnd(15)} Status`
- );
- console.log('-'.repeat(60));
-
- for (const target of targetProgress) {
- const goalStr = target.target !== null ? `<${target.target}${target.unit}` : 'N/A';
- console.log(
- `${target.name.padEnd(20)} ${goalStr.padEnd(12)} ${target.improvement.padEnd(15)} [PENDING]`
- );
- }
-
- console.log('\n');
-}
-
-/**
- * Save comparison results to file
- */
-export function saveComparisonResults(
- summary: ComparisonSummary,
- outputPath: string
-): void {
- const output = {
- timestamp: new Date().toISOString(),
- summary: {
- totalBenchmarks: summary.totalBenchmarks,
- improved: summary.improved,
- regressed: summary.regressed,
- unchanged: summary.unchanged,
- targetsMet: summary.targetsMet,
- targetsMissed: summary.targetsMissed,
- overallStatus: summary.overallStatus,
- },
- details: summary.details,
- };
-
- fs.writeFileSync(outputPath, JSON.stringify(output, null, 2));
- console.log(`Comparison results saved to: ${outputPath}`);
-}
-
-// ============================================================================
-// CLI Interface
-// ============================================================================
-
-async function main(): Promise<void> {
- const args = process.argv.slice(2);
- const baselinePath = args[0] || path.join(__dirname, 'baseline-v2.json');
- const outputPath = args[1] || path.join(__dirname, 'comparison-results.json');
-
- console.log('Loading baseline...');
- const baseline = loadBaseline(baselinePath);
- console.log(`Loaded baseline v${baseline.version} from ${baseline.timestamp}`);
-
- // For demo purposes, generate some mock current results
- // In real usage, these would come from running the benchmark suite
- const currentResults = new Map<string, number>([
- // Improved (simulated V3 performance)
- ['startup/cli-cold-start', 450],
- ['startup/cli-warm-start', 80],
- ['startup/mcp-server-init', 350],
- ['startup/agent-spawn', 180],
-
- // Memory improvements with HNSW
- ['memory/vector-search-1k', 0.5],
- ['memory/vector-search-10k', 0.8],
- ['memory/hnsw-indexing', 8],
- ['memory/memory-write', 3],
- ['memory/cache-hit-rate', 0.08],
-
- // Swarm improvements
- ['swarm/agent-coordination-5', 40],
- ['swarm/agent-coordination-15', 120],
- ['swarm/task-decomposition', 15],
- ['swarm/consensus-latency', 80],
- ['swarm/message-throughput', 0.05],
-
- // Attention benchmarks
- ['attention/standard-attention-512', 100],
- ['attention/flash-attention-512', 35], // ~2.85x speedup
-
- // System benchmarks
- ['system/memory-usage-baseline', 280000000], // ~267MB
- ['system/sona-adaptation', 0.04],
- ]);
-
- console.log('\nComparing with baseline...');
- const summary = compareWithBaseline(currentResults, baseline);
-
- printComparisonSummary(summary);
-
- if (outputPath) {
- saveComparisonResults(summary, outputPath);
- }
-
- // Exit with appropriate code
- if (summary.overallStatus === 'fail') {
- process.exit(1);
- }
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- main().catch(console.error);
-}
-
-export default {
- loadBaseline,
- compareWithBaseline,
- printComparisonSummary,
- saveComparisonResults,
-};
diff --git a/v3/benchmarks/regression/report.ts b/v3/benchmarks/regression/report.ts
deleted file mode 100644
index e65004dad7..0000000000
--- a/v3/benchmarks/regression/report.ts
+++ /dev/null
@@ -1,559 +0,0 @@
-/**
- * Benchmark Report Generator
- *
- * Generates comprehensive performance reports in various formats
- * including HTML, Markdown, and JSON.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { BenchmarkResult, formatTime, formatBytes, V3_PERFORMANCE_TARGETS } from '../framework/benchmark.js';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-interface ReportConfig {
- title: string;
- version: string;
- timestamp: Date;
- format: 'html' | 'markdown' | 'json';
- includeCharts: boolean;
- outputPath: string;
-}
-
-interface BenchmarkCategory {
- name: string;
- benchmarks: BenchmarkResult[];
-}
-
-interface ReportData {
- config: ReportConfig;
- environment: EnvironmentInfo;
- categories: BenchmarkCategory[];
- summary: ReportSummary;
-}
-
-interface EnvironmentInfo {
- nodeVersion: string;
- platform: string;
- arch: string;
- cpus: number;
- memory: number;
- v8Version?: string;
-}
-
-interface ReportSummary {
- totalBenchmarks: number;
- targetsMet: number;
- targetsMissed: number;
- averageSpeedup: number;
- memoryReduction: number;
- overallScore: number;
-}
-
-// ============================================================================
-// Report Generation
-// ============================================================================
-
-/**
- * Calculate summary statistics
- */
-function calculateSummary(categories: BenchmarkCategory[]): ReportSummary {
- const allBenchmarks = categories.flatMap((c) => c.benchmarks);
- const totalBenchmarks = allBenchmarks.length;
-
- let targetsMet = 0;
- let targetsMissed = 0;
-
- for (const bench of allBenchmarks) {
- const target = V3_PERFORMANCE_TARGETS[bench.name as keyof typeof V3_PERFORMANCE_TARGETS];
- if (target !== undefined) {
- if (bench.mean <= target) {
- targetsMet++;
- } else {
- targetsMissed++;
- }
- }
- }
-
- // Calculate average improvement (placeholder)
- const averageSpeedup = 3.5; // Would be calculated from actual data
- const memoryReduction = 0.55; // 55% reduction
-
- // Overall score (0-100)
- const targetScore = (targetsMet / (targetsMet + targetsMissed)) * 50 || 0;
- const speedupScore = Math.min(averageSpeedup / 5, 1) * 30;
- const memoryScore = memoryReduction * 20;
- const overallScore = targetScore + speedupScore + memoryScore;
-
- return {
- totalBenchmarks,
- targetsMet,
- targetsMissed,
- averageSpeedup,
- memoryReduction,
- overallScore,
- };
-}
-
-/**
- * Generate Markdown report
- */
-function generateMarkdownReport(data: ReportData): string {
- const lines: string[] = [];
-
- // Header
- lines.push(`# ${data.config.title}`);
- lines.push('');
- lines.push(`**Version:** ${data.config.version}`);
- lines.push(`**Generated:** ${data.config.timestamp.toISOString()}`);
- lines.push('');
-
- // Environment
- lines.push('## Environment');
- lines.push('');
- lines.push(`- **Node.js:** ${data.environment.nodeVersion}`);
- lines.push(`- **Platform:** ${data.environment.platform} (${data.environment.arch})`);
- lines.push(`- **CPUs:** ${data.environment.cpus}`);
- lines.push(`- **Memory:** ${formatBytes(data.environment.memory)}`);
- lines.push('');
-
- // Summary
- lines.push('## Summary');
- lines.push('');
- lines.push(`| Metric | Value |`);
- lines.push(`|--------|-------|`);
- lines.push(`| Total Benchmarks | ${data.summary.totalBenchmarks} |`);
- lines.push(`| Targets Met | ${data.summary.targetsMet} |`);
- lines.push(`| Targets Missed | ${data.summary.targetsMissed} |`);
- lines.push(`| Average Speedup | ${data.summary.averageSpeedup.toFixed(2)}x |`);
- lines.push(`| Memory Reduction | ${(data.summary.memoryReduction * 100).toFixed(0)}% |`);
- lines.push(`| Overall Score | ${data.summary.overallScore.toFixed(0)}/100 |`);
- lines.push('');
-
- // V3 Targets Progress
- lines.push('## V3 Performance Targets');
- lines.push('');
- lines.push('| Category | Current | Target | Improvement | Status |');
- lines.push('|----------|---------|--------|-------------|--------|');
- lines.push('| CLI Startup | TBD | <500ms | 5x | Pending |');
- lines.push('| MCP Init | TBD | <400ms | 4.5x | Pending |');
- lines.push('| Agent Spawn | TBD | <200ms | 4x | Pending |');
- lines.push('| Vector Search | TBD | <1ms | 150x-12,500x | Pending |');
- lines.push('| Memory Write | TBD | <5ms | 10x | Pending |');
- lines.push('| Consensus | TBD | <100ms | 5x | Pending |');
- lines.push('| Flash Attention | TBD | - | 2.49x-7.47x | Pending |');
- lines.push('| Memory Usage | TBD | <256MB | 50% | Pending |');
- lines.push('');
-
- // Benchmark Results
- for (const category of data.categories) {
- lines.push(`## ${category.name}`);
- lines.push('');
- lines.push('| Benchmark | Mean | Median | P95 | P99 | Ops/sec | Target |');
- lines.push('|-----------|------|--------|-----|-----|---------|--------|');
-
- for (const bench of category.benchmarks) {
- const target = V3_PERFORMANCE_TARGETS[bench.name as keyof typeof V3_PERFORMANCE_TARGETS];
- const targetStr = target !== undefined ? formatTime(target) : '-';
- const status = target !== undefined && bench.mean <= target ? 'OK' : 'MISS';
-
- lines.push(
- `| ${bench.name} | ${formatTime(bench.mean)} | ${formatTime(bench.median)} | ` +
- `${formatTime(bench.p95)} | ${formatTime(bench.p99)} | ` +
- `${bench.opsPerSecond.toFixed(0)} | ${targetStr} ${target !== undefined ? `(${status})` : ''} |`
- );
- }
-
- lines.push('');
- }
-
- // Optimization Recommendations
- lines.push('## Optimization Recommendations');
- lines.push('');
- lines.push('### High Priority');
- lines.push('');
- lines.push('1. **Implement HNSW indexing** for vector search (150x-12,500x improvement)');
- lines.push('2. **Add Flash Attention** for 2.49x-7.47x attention speedup');
- lines.push('3. **Enable lazy loading** for CLI cold start optimization');
- lines.push('');
- lines.push('### Medium Priority');
- lines.push('');
- lines.push('1. **Connection pooling** for MCP server initialization');
- lines.push('2. **Agent pooling** for faster agent spawn');
- lines.push('3. **Message batching** for swarm coordination');
- lines.push('');
- lines.push('### Low Priority');
- lines.push('');
- lines.push('1. **Binary serialization** for message throughput');
- lines.push('2. **Cache warming** for faster warm starts');
- lines.push('3. **SIMD operations** for vector math');
- lines.push('');
-
- return lines.join('\n');
-}
-
-/**
- * Generate HTML report
- */
-function generateHTMLReport(data: ReportData): string {
- const scoreColor =
- data.summary.overallScore >= 80
- ? '#22c55e'
- : data.summary.overallScore >= 50
- ? '#f59e0b'
- : '#ef4444';
-
- return `<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <title>${data.config.title}</title>
- <style>
- body {
- font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
- line-height: 1.6;
- max-width: 1200px;
- margin: 0 auto;
- padding: 20px;
- background: #f8fafc;
- color: #1e293b;
- }
- h1, h2, h3 { color: #0f172a; }
- .header {
- background: linear-gradient(135deg, #1e40af, #7c3aed);
- color: white;
- padding: 40px;
- border-radius: 12px;
- margin-bottom: 30px;
- }
- .summary-grid {
- display: grid;
- grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
- gap: 20px;
- margin-bottom: 30px;
- }
- .summary-card {
- background: white;
- padding: 20px;
- border-radius: 8px;
- box-shadow: 0 1px 3px rgba(0,0,0,0.1);
- }
- .summary-card h3 {
- margin: 0 0 10px 0;
- font-size: 14px;
- color: #64748b;
- }
- .summary-card .value {
- font-size: 28px;
- font-weight: bold;
- color: #0f172a;
- }
- .score-circle {
- width: 120px;
- height: 120px;
- border-radius: 50%;
- background: ${scoreColor};
- display: flex;
- align-items: center;
- justify-content: center;
- color: white;
- font-size: 32px;
- font-weight: bold;
- margin: 0 auto;
- }
- table {
- width: 100%;
- border-collapse: collapse;
- background: white;
- border-radius: 8px;
- overflow: hidden;
- box-shadow: 0 1px 3px rgba(0,0,0,0.1);
- margin-bottom: 30px;
- }
- th, td {
- padding: 12px 16px;
- text-align: left;
- border-bottom: 1px solid #e2e8f0;
- }
- th {
- background: #f1f5f9;
- font-weight: 600;
- color: #475569;
- }
- tr:hover { background: #f8fafc; }
- .status-ok { color: #22c55e; }
- .status-miss { color: #ef4444; }
- .status-pending { color: #f59e0b; }
- </style>
-</head>
-<body>
- <div class="header">
- <h1>${data.config.title}</h1>
- <p>Version ${data.config.version} | Generated ${data.config.timestamp.toISOString()}</p>
- </div>
-
- <div class="summary-grid">
- <div class="summary-card">
- <h3>Overall Score</h3>
- <div class="score-circle">${data.summary.overallScore.toFixed(0)}</div>
- </div>
- <div class="summary-card">
- <h3>Total Benchmarks</h3>
- <div class="value">${data.summary.totalBenchmarks}</div>
- </div>
- <div class="summary-card">
- <h3>Targets Met</h3>
- <div class="value">${data.summary.targetsMet}</div>
- </div>
- <div class="summary-card">
- <h3>Average Speedup</h3>
- <div class="value">${data.summary.averageSpeedup.toFixed(2)}x</div>
- </div>
- <div class="summary-card">
- <h3>Memory Reduction</h3>
- <div class="value">${(data.summary.memoryReduction * 100).toFixed(0)}%</div>
- </div>
- </div>
-
- <h2>V3 Performance Targets</h2>
- <table>
- <thead>
- <tr>
- <th>Category</th>
- <th>V2 Baseline</th>
- <th>V3 Target</th>
- <th>Expected Improvement</th>
- <th>Status</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>CLI Cold Start</td>
- <td>~2.5s</td>
- <td>&lt;500ms</td>
- <td>5x faster</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>MCP Server Init</td>
- <td>~1.8s</td>
- <td>&lt;400ms</td>
- <td>4.5x faster</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>Agent Spawn</td>
- <td>~800ms</td>
- <td>&lt;200ms</td>
- <td>4x faster</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>Vector Search</td>
- <td>~150ms</td>
- <td>&lt;1ms</td>
- <td>150x-12,500x faster</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>Memory Write</td>
- <td>~50ms</td>
- <td>&lt;5ms</td>
- <td>10x faster</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>Consensus Latency</td>
- <td>~500ms</td>
- <td>&lt;100ms</td>
- <td>5x faster</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>Flash Attention</td>
- <td>N/A</td>
- <td>-</td>
- <td>2.49x-7.47x speedup</td>
- <td class="status-pending">Pending</td>
- </tr>
- <tr>
- <td>Memory Usage</td>
- <td>~512MB</td>
- <td>&lt;256MB</td>
- <td>50% reduction</td>
- <td class="status-pending">Pending</td>
- </tr>
- </tbody>
- </table>
-
- ${data.categories
- .map(
- (cat) => `
- <h2>${cat.name} Benchmarks</h2>
- <table>
- <thead>
- <tr>
- <th>Benchmark</th>
- <th>Mean</th>
- <th>Median</th>
- <th>P95</th>
- <th>P99</th>
- <th>Ops/sec</th>
- </tr>
- </thead>
- <tbody>
- ${cat.benchmarks
- .map(
- (b) => `
- <tr>
- <td>${b.name}</td>
- <td>${formatTime(b.mean)}</td>
- <td>${formatTime(b.median)}</td>
- <td>${formatTime(b.p95)}</td>
- <td>${formatTime(b.p99)}</td>
- <td>${b.opsPerSecond.toFixed(0)}</td>
- </tr>
- `
- )
- .join('')}
- </tbody>
- </table>
- `
- )
- .join('')}
-
-</body>
-</html>`;
-}
-
-/**
- * Generate JSON report
- */
-function generateJSONReport(data: ReportData): string {
- return JSON.stringify(
- {
- title: data.config.title,
- version: data.config.version,
- timestamp: data.config.timestamp.toISOString(),
- environment: data.environment,
- summary: data.summary,
- categories: data.categories.map((cat) => ({
- name: cat.name,
- benchmarks: cat.benchmarks.map((b) => ({
- name: b.name,
- mean: b.mean,
- median: b.median,
- p95: b.p95,
- p99: b.p99,
- min: b.min,
- max: b.max,
- stdDev: b.stdDev,
- opsPerSecond: b.opsPerSecond,
- memoryDelta: b.memoryDelta,
- })),
- })),
- targets: V3_PERFORMANCE_TARGETS,
- },
- null,
- 2
- );
-}
-
-/**
- * Generate report in specified format
- */
-export function generateReport(
- categories: BenchmarkCategory[],
- config: Partial<ReportConfig> = {}
-): string {
- const os = require('os');
-
- const fullConfig: ReportConfig = {
- title: 'V3 Performance Benchmark Report',
- version: '3.0.0-alpha',
- timestamp: new Date(),
- format: 'markdown',
- includeCharts: true,
- outputPath: './benchmark-report',
- ...config,
- };
-
- const data: ReportData = {
- config: fullConfig,
- environment: {
- nodeVersion: process.version,
- platform: process.platform,
- arch: process.arch,
- cpus: os.cpus().length,
- memory: os.totalmem(),
- v8Version: process.versions.v8,
- },
- categories,
- summary: calculateSummary(categories),
- };
-
- switch (fullConfig.format) {
- case 'html':
- return generateHTMLReport(data);
- case 'json':
- return generateJSONReport(data);
- case 'markdown':
- default:
- return generateMarkdownReport(data);
- }
-}
-
-/**
- * Save report to file
- */
-export function saveReport(content: string, outputPath: string, format: string): void {
- const extension = format === 'html' ? '.html' : format === 'json' ? '.json' : '.md';
- const fullPath = outputPath.endsWith(extension) ? outputPath : outputPath + extension;
-
- fs.writeFileSync(fullPath, content);
- console.log(`Report saved to: ${fullPath}`);
-}
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- // Generate sample report
- const sampleCategories: BenchmarkCategory[] = [
- {
- name: 'Startup',
- benchmarks: [
- {
- name: 'cli-cold-start',
- iterations: 100,
- mean: 450,
- median: 440,
- p95: 500,
- p99: 550,
- min: 400,
- max: 600,
- stdDev: 30,
- opsPerSecond: 2.2,
- memoryUsage: {
- heapUsed: 50000000,
- heapTotal: 100000000,
- external: 1000000,
- arrayBuffers: 500000,
- rss: 150000000,
- },
- memoryDelta: 10000000,
- timestamp: Date.now(),
- },
- ],
- },
- ];
-
- const report = generateReport(sampleCategories, { format: 'markdown' });
- console.log(report);
-}
-
-export default {
- generateReport,
- saveReport,
-};
diff --git a/v3/benchmarks/startup/agent-spawn.bench.ts b/v3/benchmarks/startup/agent-spawn.bench.ts
deleted file mode 100644
index c2157f3fa9..0000000000
--- a/v3/benchmarks/startup/agent-spawn.bench.ts
+++ /dev/null
@@ -1,422 +0,0 @@
-/**
- * Agent Spawn Benchmark
- *
- * Target: <200ms (4x faster than current ~800ms)
- *
- * Measures the time to spawn agents including initialization,
- * capability loading, and ready state achievement.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Simulated Agent Types
-// ============================================================================
-
-interface Agent {
- id: string;
- type: string;
- status: 'initializing' | 'ready' | 'busy' | 'terminated';
- capabilities: string[];
- spawnTime: number;
- readyTime?: number;
-}
-
-interface AgentPool {
- agents: Map<string, Agent>;
- available: Agent[];
- busy: Agent[];
-}
-
-// Agent type definitions
-const AGENT_TYPES = {
- coder: {
- capabilities: ['code', 'edit', 'refactor', 'review'],
- initTime: 50,
- },
- tester: {
- capabilities: ['test', 'coverage', 'lint'],
- initTime: 40,
- },
- researcher: {
- capabilities: ['search', 'analyze', 'summarize'],
- initTime: 45,
- },
- coordinator: {
- capabilities: ['plan', 'delegate', 'monitor'],
- initTime: 60,
- },
- reviewer: {
- capabilities: ['review', 'suggest', 'approve'],
- initTime: 35,
- },
-};
-
-// ============================================================================
-// Agent Spawn Functions
-// ============================================================================
-
-/**
- * Spawn a single agent (V2 style - sequential)
- */
-async function spawnAgentV2(type: string): Promise<Agent> {
- const config = AGENT_TYPES[type as keyof typeof AGENT_TYPES] || {
- capabilities: [],
- initTime: 50,
- };
-
- const agent: Agent = {
- id: `agent-${Date.now()}-${Math.random().toString(36).slice(2)}`,
- type,
- status: 'initializing',
- capabilities: [],
- spawnTime: performance.now(),
- };
-
- // Sequential initialization
- await new Promise((resolve) => setTimeout(resolve, config.initTime / 5));
-
- // Load capabilities one by one
- for (const cap of config.capabilities) {
- agent.capabilities.push(cap);
- await new Promise((resolve) => setTimeout(resolve, 2));
- }
-
- agent.status = 'ready';
- agent.readyTime = performance.now();
-
- return agent;
-}
-
-/**
- * Spawn a single agent (V3 style - optimized)
- */
-async function spawnAgentV3(type: string): Promise<Agent> {
- const config = AGENT_TYPES[type as keyof typeof AGENT_TYPES] || {
- capabilities: [],
- initTime: 50,
- };
-
- const agent: Agent = {
- id: `agent-${Date.now()}-${Math.random().toString(36).slice(2)}`,
- type,
- status: 'initializing',
- capabilities: [...config.capabilities], // Instant capability assignment
- spawnTime: performance.now(),
- };
-
- // Minimal initialization
- await new Promise((resolve) => setTimeout(resolve, config.initTime / 10));
-
- agent.status = 'ready';
- agent.readyTime = performance.now();
-
- return agent;
-}
-
-/**
- * Spawn multiple agents in parallel
- */
-async function spawnAgentsParallel(types: string[]): Promise<Agent[]> {
- return Promise.all(types.map((type) => spawnAgentV3(type)));
-}
-
-/**
- * Spawn multiple agents sequentially (V2 style)
- */
-async function spawnAgentsSequential(types: string[]): Promise<Agent[]> {
- const agents: Agent[] = [];
- for (const type of types) {
- agents.push(await spawnAgentV2(type));
- }
- return agents;
-}
-
-/**
- * Get agent from pool (instant)
- */
-function getAgentFromPool(pool: AgentPool, type: string): Agent | undefined {
- const index = pool.available.findIndex((a) => a.type === type);
- if (index >= 0) {
- const agent = pool.available.splice(index, 1)[0]!;
- agent.status = 'busy';
- pool.busy.push(agent);
- return agent;
- }
- return undefined;
-}
-
-/**
- * Create pre-warmed agent pool
- */
-async function createAgentPool(types: string[]): Promise<AgentPool> {
- const agents = await spawnAgentsParallel(types);
- const pool: AgentPool = {
- agents: new Map(),
- available: agents,
- busy: [],
- };
-
- for (const agent of agents) {
- pool.agents.set(agent.id, agent);
- }
-
- return pool;
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runAgentSpawnBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Agent Spawn');
-
- console.log('\n--- Agent Spawn Benchmarks ---\n');
-
- // Benchmark 1: Single Agent Spawn (V2 Style)
- const singleV2Result = await runner.run(
- 'single-agent-spawn-v2',
- async () => {
- await spawnAgentV2('coder');
- },
- { iterations: 50 }
- );
-
- console.log(`Single Agent (V2): ${formatTime(singleV2Result.mean)}`);
-
- // Benchmark 2: Single Agent Spawn (V3 Style)
- const singleV3Result = await runner.run(
- 'single-agent-spawn-v3',
- async () => {
- await spawnAgentV3('coder');
- },
- { iterations: 100 }
- );
-
- console.log(`Single Agent (V3): ${formatTime(singleV3Result.mean)}`);
- const singleTarget = meetsTarget('agent-spawn', singleV3Result.mean);
- console.log(` Target (<200ms): ${singleTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Calculate single spawn speedup
- const singleSpeedup = singleV2Result.mean / singleV3Result.mean;
- console.log(` Speedup: ${singleSpeedup.toFixed(2)}x`);
-
- // Benchmark 3: 5 Agents Sequential (V2 Style)
- const sequential5Result = await runner.run(
- '5-agents-sequential',
- async () => {
- await spawnAgentsSequential(['coder', 'tester', 'researcher', 'coordinator', 'reviewer']);
- },
- { iterations: 20 }
- );
-
- console.log(`5 Agents Sequential: ${formatTime(sequential5Result.mean)}`);
-
- // Benchmark 4: 5 Agents Parallel (V3 Style)
- const parallel5Result = await runner.run(
- '5-agents-parallel',
- async () => {
- await spawnAgentsParallel(['coder', 'tester', 'researcher', 'coordinator', 'reviewer']);
- },
- { iterations: 50 }
- );
-
- console.log(`5 Agents Parallel: ${formatTime(parallel5Result.mean)}`);
- const parallelSpeedup = sequential5Result.mean / parallel5Result.mean;
- console.log(` Speedup: ${parallelSpeedup.toFixed(2)}x`);
-
- // Benchmark 5: 15 Agents Parallel (V3 Swarm)
- const parallel15Result = await runner.run(
- '15-agents-parallel',
- async () => {
- const types = Array.from({ length: 15 }, (_, i) =>
- Object.keys(AGENT_TYPES)[i % Object.keys(AGENT_TYPES).length]!
- );
- await spawnAgentsParallel(types);
- },
- { iterations: 20 }
- );
-
- console.log(`15 Agents Parallel: ${formatTime(parallel15Result.mean)}`);
-
- // Benchmark 6: Agent Pool Creation
- const poolCreationResult = await runner.run(
- 'agent-pool-creation',
- async () => {
- await createAgentPool(['coder', 'tester', 'researcher', 'coordinator', 'reviewer']);
- },
- { iterations: 30 }
- );
-
- console.log(`Pool Creation (5 agents): ${formatTime(poolCreationResult.mean)}`);
-
- // Benchmark 7: Agent From Pool (Instant)
- const pool = await createAgentPool(['coder', 'coder', 'tester', 'tester', 'researcher']);
-
- const poolGetResult = await runner.run(
- 'get-agent-from-pool',
- async () => {
- // Reset pool for each iteration
- pool.available = [...pool.agents.values()];
- pool.busy = [];
-
- getAgentFromPool(pool, 'coder');
- },
- { iterations: 1000 }
- );
-
- console.log(`Get Agent from Pool: ${formatTime(poolGetResult.mean)}`);
-
- // Benchmark 8: Agent Capability Check
- const capabilityCheckResult = await runner.run(
- 'capability-check',
- async () => {
- const agent = await spawnAgentV3('coder');
- const hasCapability = agent.capabilities.includes('code');
- void hasCapability;
- },
- { iterations: 100 }
- );
-
- console.log(`Agent with Capability Check: ${formatTime(capabilityCheckResult.mean)}`);
-
- // Benchmark 9: Batch Agent Status Update
- const agents = await spawnAgentsParallel(Array(20).fill('coder'));
-
- const statusUpdateResult = await runner.run(
- 'batch-status-update',
- async () => {
- for (const agent of agents) {
- agent.status = 'busy';
- }
- },
- { iterations: 1000 }
- );
-
- console.log(`Batch Status Update (20 agents): ${formatTime(statusUpdateResult.mean)}`);
-
- // Summary
- console.log('\n--- Summary ---');
- console.log(`V2 -> V3 Single Agent Speedup: ${singleSpeedup.toFixed(2)}x`);
- console.log(`Sequential -> Parallel (5 agents) Speedup: ${parallelSpeedup.toFixed(2)}x`);
- console.log(`Pool vs Spawn Speedup: ${(singleV3Result.mean / poolGetResult.mean).toFixed(2)}x`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Agent Spawn Optimization Strategies
-// ============================================================================
-
-export const agentSpawnOptimizations = {
- /**
- * Agent pooling: Pre-spawn and reuse agents
- */
- agentPooling: {
- description: 'Maintain a pool of pre-spawned agents for instant acquisition',
- expectedImprovement: '90-99%',
- implementation: `
- class AgentPool {
- private available: Agent[] = [];
- private minSize = 5;
-
- async acquire(type: string): Promise<Agent> {
- const agent = this.available.find(a => a.type === type);
- if (agent) {
- return agent; // Instant!
- }
- return this.spawn(type); // Fallback
- }
-
- async maintain(): Promise<void> {
- while (this.available.length < this.minSize) {
- this.available.push(await this.spawn('generic'));
- }
- }
- }
- `,
- },
-
- /**
- * Parallel spawning: Spawn multiple agents concurrently
- */
- parallelSpawning: {
- description: 'Spawn multiple agents in parallel using Promise.all',
- expectedImprovement: '60-80%',
- implementation: `
- async function spawnSwarm(types: string[]): Promise<Agent[]> {
- return Promise.all(types.map(type => spawnAgent(type)));
- }
- `,
- },
-
- /**
- * Lazy capability loading: Defer capability initialization
- */
- lazyCapabilities: {
- description: 'Load agent capabilities on first use',
- expectedImprovement: '30-50%',
- implementation: `
- class LazyAgent {
- private _capabilities?: string[];
-
- get capabilities(): string[] {
- if (!this._capabilities) {
- this._capabilities = loadCapabilities(this.type);
- }
- return this._capabilities;
- }
- }
- `,
- },
-
- /**
- * Worker threads: Use worker threads for CPU-intensive init
- */
- workerThreads: {
- description: 'Offload agent initialization to worker threads',
- expectedImprovement: '40-60%',
- implementation: `
- const { Worker } = require('worker_threads');
-
- async function spawnInWorker(type: string): Promise<Agent> {
- return new Promise((resolve) => {
- const worker = new Worker('./agent-worker.js', {
- workerData: { type }
- });
- worker.on('message', resolve);
- });
- }
- `,
- },
-
- /**
- * Prototype-based instantiation: Use Object.create for fast cloning
- */
- prototypeInstantiation: {
- description: 'Use prototype-based instantiation for fast agent creation',
- expectedImprovement: '20-30%',
- implementation: `
- const agentPrototypes = new Map<string, Agent>();
-
- function createAgent(type: string): Agent {
- const prototype = agentPrototypes.get(type);
- if (prototype) {
- return Object.create(prototype, {
- id: { value: generateId() },
- status: { value: 'ready', writable: true },
- });
- }
- return new Agent(type);
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runAgentSpawnBenchmarks().catch(console.error);
-}
-
-export default runAgentSpawnBenchmarks;
diff --git a/v3/benchmarks/startup/cli-cold-start.bench.ts b/v3/benchmarks/startup/cli-cold-start.bench.ts
deleted file mode 100644
index 10660815f4..0000000000
--- a/v3/benchmarks/startup/cli-cold-start.bench.ts
+++ /dev/null
@@ -1,327 +0,0 @@
-/**
- * CLI Cold Start Benchmark
- *
- * Target: <500ms (5x faster than current ~2.5s)
- *
- * Measures the time to start the CLI from a completely cold state,
- * including module loading, initialization, and ready state.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-import { spawn, ChildProcess } from 'child_process';
-import * as path from 'path';
-
-// ============================================================================
-// Test Helpers
-// ============================================================================
-
-/**
- * Measure CLI cold start time by spawning a new process
- */
-async function measureColdStart(command: string, args: string[]): Promise<number> {
- return new Promise((resolve, reject) => {
- const startTime = performance.now();
-
- const child: ChildProcess = spawn(command, args, {
- stdio: 'pipe',
- shell: true,
- });
-
- let output = '';
-
- child.stdout?.on('data', (data) => {
- output += data.toString();
- // Check for ready signal
- if (output.includes('Ready') || output.includes('initialized')) {
- const endTime = performance.now();
- child.kill();
- resolve(endTime - startTime);
- }
- });
-
- child.stderr?.on('data', (data) => {
- output += data.toString();
- });
-
- child.on('error', reject);
-
- child.on('close', () => {
- const endTime = performance.now();
- resolve(endTime - startTime);
- });
-
- // Timeout after 10 seconds
- setTimeout(() => {
- child.kill();
- reject(new Error('Cold start timeout'));
- }, 10000);
- });
-}
-
-/**
- * Simulate module loading overhead
- */
-async function simulateModuleLoading(): Promise<void> {
- // Simulate loading core modules
- const modules = [
- 'commander',
- 'chalk',
- 'ora',
- 'inquirer',
- 'fs-extra',
- ];
-
- for (const mod of modules) {
- // Simulate require overhead
- await new Promise((resolve) => setTimeout(resolve, 1));
- }
-}
-
-/**
- * Simulate CLI initialization
- */
-async function simulateCLIInit(): Promise<void> {
- // Configuration loading
- await new Promise((resolve) => setTimeout(resolve, 5));
-
- // Command registration
- const commands = Array.from({ length: 50 }, (_, i) => `command-${i}`);
- for (const cmd of commands) {
- // Register command
- void cmd;
- }
-
- // Plugin loading
- await new Promise((resolve) => setTimeout(resolve, 3));
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runColdStartBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('CLI Cold Start');
-
- console.log('\n--- CLI Cold Start Benchmarks ---\n');
-
- // Benchmark 1: Module Loading Simulation
- const moduleResult = await runner.run(
- 'module-loading',
- async () => {
- await simulateModuleLoading();
- },
- { iterations: 50 }
- );
-
- console.log(`Module Loading: ${formatTime(moduleResult.mean)}`);
- const moduleTarget = meetsTarget('cli-cold-start', moduleResult.mean);
- console.log(` Target (<500ms): ${moduleTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 2: CLI Initialization
- const initResult = await runner.run(
- 'cli-initialization',
- async () => {
- await simulateCLIInit();
- },
- { iterations: 50 }
- );
-
- console.log(`CLI Initialization: ${formatTime(initResult.mean)}`);
-
- // Benchmark 3: Lazy Loading Benefits
- const lazyLoadResult = await runner.run(
- 'lazy-load-startup',
- async () => {
- // Simulate lazy loading - only load what's needed
- const essentialModules = ['commander'];
- for (const mod of essentialModules) {
- void mod;
- await new Promise((resolve) => setTimeout(resolve, 0.5));
- }
- },
- { iterations: 100 }
- );
-
- console.log(`Lazy Load Startup: ${formatTime(lazyLoadResult.mean)}`);
-
- // Benchmark 4: Parallel Module Loading
- const parallelLoadResult = await runner.run(
- 'parallel-module-loading',
- async () => {
- // Load modules in parallel
- await Promise.all([
- new Promise((resolve) => setTimeout(resolve, 1)),
- new Promise((resolve) => setTimeout(resolve, 1)),
- new Promise((resolve) => setTimeout(resolve, 1)),
- new Promise((resolve) => setTimeout(resolve, 1)),
- new Promise((resolve) => setTimeout(resolve, 1)),
- ]);
- },
- { iterations: 100 }
- );
-
- console.log(`Parallel Module Loading: ${formatTime(parallelLoadResult.mean)}`);
-
- // Benchmark 5: Configuration Caching
- const configCacheResult = await runner.run(
- 'cached-config-load',
- async () => {
- // Simulate cached configuration load
- const cache = new Map<string, object>();
- cache.set('config', { version: 3, mode: 'production' });
- const config = cache.get('config');
- void config;
- },
- { iterations: 1000 }
- );
-
- console.log(`Cached Config Load: ${formatTime(configCacheResult.mean)}`);
-
- // Benchmark 6: Full Cold Start Simulation
- const fullColdStartResult = await runner.run(
- 'full-cold-start-simulation',
- async () => {
- // Phase 1: Essential imports (parallel)
- await Promise.all([
- new Promise((resolve) => setTimeout(resolve, 10)),
- new Promise((resolve) => setTimeout(resolve, 10)),
- ]);
-
- // Phase 2: Configuration
- await new Promise((resolve) => setTimeout(resolve, 5));
-
- // Phase 3: Minimal command setup
- await new Promise((resolve) => setTimeout(resolve, 5));
- },
- { iterations: 50 }
- );
-
- console.log(`Full Cold Start (Optimized): ${formatTime(fullColdStartResult.mean)}`);
- const fullTarget = meetsTarget('cli-cold-start', fullColdStartResult.mean);
- console.log(` Target (<500ms): ${fullTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 7: V2 vs V3 Comparison Simulation
- const v2SimulationResult = await runner.run(
- 'v2-cold-start-simulation',
- async () => {
- // Simulate V2's heavier startup
- await new Promise((resolve) => setTimeout(resolve, 100));
- },
- { iterations: 20 }
- );
-
- const v3SimulationResult = await runner.run(
- 'v3-cold-start-simulation',
- async () => {
- // Simulate V3's optimized startup
- await new Promise((resolve) => setTimeout(resolve, 20));
- },
- { iterations: 50 }
- );
-
- const speedup = v2SimulationResult.mean / v3SimulationResult.mean;
- console.log(`\nV2 vs V3 Speedup: ${speedup.toFixed(2)}x`);
- console.log(` V2 Simulation: ${formatTime(v2SimulationResult.mean)}`);
- console.log(` V3 Simulation: ${formatTime(v3SimulationResult.mean)}`);
-
- // Print summary
- runner.printResults();
-}
-
-// ============================================================================
-// Optimization Strategies
-// ============================================================================
-
-export const coldStartOptimizations = {
- /**
- * Lazy loading: Only load modules when needed
- */
- lazyLoading: {
- description: 'Defer non-essential module loading until first use',
- expectedImprovement: '40-60%',
- implementation: `
- // Instead of:
- import * as allModules from './modules';
-
- // Use:
- async function getModule(name) {
- return await import(\`./modules/\${name}\`);
- }
- `,
- },
-
- /**
- * Parallel initialization: Initialize independent components concurrently
- */
- parallelInit: {
- description: 'Initialize independent components in parallel',
- expectedImprovement: '20-40%',
- implementation: `
- // Instead of:
- await initConfig();
- await initLogger();
- await initPlugins();
-
- // Use:
- await Promise.all([
- initConfig(),
- initLogger(),
- initPlugins(),
- ]);
- `,
- },
-
- /**
- * Pre-bundling: Use esbuild/Rollup for faster module resolution
- */
- preBundling: {
- description: 'Pre-bundle dependencies to reduce require() overhead',
- expectedImprovement: '30-50%',
- implementation: `
- // Build step:
- esbuild --bundle --platform=node --outfile=dist/cli.js
- `,
- },
-
- /**
- * Configuration caching: Cache parsed configuration
- */
- configCaching: {
- description: 'Cache parsed configuration to avoid repeated parsing',
- expectedImprovement: '10-20%',
- implementation: `
- const configCache = new Map();
-
- function loadConfig(path) {
- if (configCache.has(path)) {
- return configCache.get(path);
- }
- const config = parseConfig(readFile(path));
- configCache.set(path, config);
- return config;
- }
- `,
- },
-
- /**
- * Snapshot: Use V8 startup snapshots for instant loading
- */
- v8Snapshot: {
- description: 'Use V8 startup snapshots for pre-compiled code',
- expectedImprovement: '50-70%',
- implementation: `
- // Generate snapshot:
- node --snapshot-blob=snapshot.blob --build-snapshot script.js
-
- // Run with snapshot:
- node --snapshot-blob=snapshot.blob
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runColdStartBenchmarks().catch(console.error);
-}
-
-export default runColdStartBenchmarks;
diff --git a/v3/benchmarks/startup/cli-warm-start.bench.ts b/v3/benchmarks/startup/cli-warm-start.bench.ts
deleted file mode 100644
index 30bb478bd6..0000000000
--- a/v3/benchmarks/startup/cli-warm-start.bench.ts
+++ /dev/null
@@ -1,277 +0,0 @@
-/**
- * CLI Warm Start Benchmark
- *
- * Target: <100ms
- *
- * Measures the time to start the CLI when modules are already cached
- * and configuration is pre-loaded.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Simulated Components
-// ============================================================================
-
-// Simulated module cache
-const moduleCache = new Map<string, object>();
-
-// Simulated configuration cache
-const configCache = new Map<string, object>();
-
-// Pre-populate caches
-function initializeCaches(): void {
- // Simulate cached modules
- moduleCache.set('commander', { Command: class {} });
- moduleCache.set('chalk', { red: (s: string) => s, green: (s: string) => s });
- moduleCache.set('ora', { default: () => ({ start: () => {}, stop: () => {} }) });
-
- // Simulate cached configuration
- configCache.set('main', {
- version: '3.0.0',
- mode: 'production',
- features: ['swarm', 'memory', 'mcp'],
- });
-}
-
-/**
- * Get cached module (instant)
- */
-function getCachedModule(name: string): object | undefined {
- return moduleCache.get(name);
-}
-
-/**
- * Get cached configuration (instant)
- */
-function getCachedConfig(name: string): object | undefined {
- return configCache.get(name);
-}
-
-/**
- * Simulate warm start initialization
- */
-async function warmStartInit(): Promise<void> {
- // Get cached modules
- getCachedModule('commander');
- getCachedModule('chalk');
- getCachedModule('ora');
-
- // Get cached config
- getCachedConfig('main');
-
- // Minimal setup
- await Promise.resolve();
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runWarmStartBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('CLI Warm Start');
-
- console.log('\n--- CLI Warm Start Benchmarks ---\n');
-
- // Initialize caches before benchmarks
- initializeCaches();
-
- // Benchmark 1: Cached Module Access
- const moduleAccessResult = await runner.run(
- 'cached-module-access',
- async () => {
- getCachedModule('commander');
- getCachedModule('chalk');
- getCachedModule('ora');
- },
- { iterations: 10000 }
- );
-
- console.log(`Cached Module Access: ${formatTime(moduleAccessResult.mean)}`);
-
- // Benchmark 2: Cached Config Access
- const configAccessResult = await runner.run(
- 'cached-config-access',
- async () => {
- getCachedConfig('main');
- },
- { iterations: 10000 }
- );
-
- console.log(`Cached Config Access: ${formatTime(configAccessResult.mean)}`);
-
- // Benchmark 3: Full Warm Start
- const warmStartResult = await runner.run(
- 'full-warm-start',
- async () => {
- await warmStartInit();
- },
- { iterations: 1000 }
- );
-
- console.log(`Full Warm Start: ${formatTime(warmStartResult.mean)}`);
- const target = meetsTarget('cli-warm-start', warmStartResult.mean);
- console.log(` Target (<100ms): ${target.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 4: Command Resolution (Warm)
- const commandResolutionResult = await runner.run(
- 'command-resolution-warm',
- async () => {
- const commands = new Map<string, () => void>();
- commands.set('agent', () => {});
- commands.set('swarm', () => {});
- commands.set('memory', () => {});
-
- commands.get('swarm');
- },
- { iterations: 10000 }
- );
-
- console.log(`Command Resolution (Warm): ${formatTime(commandResolutionResult.mean)}`);
-
- // Benchmark 5: Plugin Activation (Warm)
- const pluginActivationResult = await runner.run(
- 'plugin-activation-warm',
- async () => {
- const plugins = new Map<string, { activate: () => void }>();
- plugins.set('mcp', { activate: () => {} });
- plugins.set('hooks', { activate: () => {} });
-
- const plugin = plugins.get('mcp');
- plugin?.activate();
- },
- { iterations: 5000 }
- );
-
- console.log(`Plugin Activation (Warm): ${formatTime(pluginActivationResult.mean)}`);
-
- // Benchmark 6: Repeat Command Execution
- const repeatCommandResult = await runner.run(
- 'repeat-command-execution',
- async () => {
- // Simulate executing a command that was already run
- const executionCache = new Map<string, object>();
- executionCache.set('agent list', { result: [] });
-
- const cached = executionCache.get('agent list');
- void cached;
- },
- { iterations: 10000 }
- );
-
- console.log(`Repeat Command (Cached): ${formatTime(repeatCommandResult.mean)}`);
-
- // Benchmark 7: State Restoration
- const stateRestorationResult = await runner.run(
- 'state-restoration',
- async () => {
- // Restore session state from memory
- const sessionState = {
- agents: [{ id: 'agent-1', status: 'active' }],
- tasks: [{ id: 'task-1', status: 'pending' }],
- memory: new Map([['key1', 'value1']]),
- };
-
- // Shallow copy for restoration
- const restored = { ...sessionState };
- void restored;
- },
- { iterations: 5000 }
- );
-
- console.log(`State Restoration: ${formatTime(stateRestorationResult.mean)}`);
-
- // Calculate total warm start overhead
- const totalOverhead =
- moduleAccessResult.mean +
- configAccessResult.mean +
- commandResolutionResult.mean;
-
- console.log(`\nTotal Warm Start Overhead: ${formatTime(totalOverhead)}`);
- console.log(`Target (<100ms): ${totalOverhead < 100 ? 'PASS' : 'FAIL'}`);
-
- // Print summary
- runner.printResults();
-}
-
-// ============================================================================
-// Warm Start Optimization Strategies
-// ============================================================================
-
-export const warmStartOptimizations = {
- /**
- * Module caching: Keep frequently used modules in memory
- */
- moduleCaching: {
- description: 'Keep frequently used modules in memory between runs',
- expectedImprovement: '80-90%',
- implementation: `
- const moduleCache = new Map();
-
- function requireCached(moduleName) {
- if (!moduleCache.has(moduleName)) {
- moduleCache.set(moduleName, require(moduleName));
- }
- return moduleCache.get(moduleName);
- }
- `,
- },
-
- /**
- * State persistence: Keep application state between runs
- */
- statePersistence: {
- description: 'Persist application state for instant restoration',
- expectedImprovement: '60-80%',
- implementation: `
- // Save state
- process.on('beforeExit', () => {
- saveState(currentState);
- });
-
- // Restore state
- const state = loadState() || createDefaultState();
- `,
- },
-
- /**
- * Worker pool: Keep worker processes alive
- */
- workerPool: {
- description: 'Maintain a pool of pre-warmed worker processes',
- expectedImprovement: '70-85%',
- implementation: `
- const workerPool = new WorkerPool({
- min: 2,
- max: 10,
- idleTimeout: 60000,
- });
-
- // Reuse workers instead of spawning new ones
- const worker = await workerPool.acquire();
- `,
- },
-
- /**
- * Connection pooling: Reuse network connections
- */
- connectionPooling: {
- description: 'Maintain connection pools for MCP and other services',
- expectedImprovement: '50-70%',
- implementation: `
- const connectionPool = new ConnectionPool({
- maxConnections: 10,
- idleTimeout: 30000,
- });
-
- const connection = await connectionPool.acquire('mcp-server');
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runWarmStartBenchmarks().catch(console.error);
-}
-
-export default runWarmStartBenchmarks;
diff --git a/v3/benchmarks/startup/mcp-server-init.bench.ts b/v3/benchmarks/startup/mcp-server-init.bench.ts
deleted file mode 100644
index 404a484d58..0000000000
--- a/v3/benchmarks/startup/mcp-server-init.bench.ts
+++ /dev/null
@@ -1,380 +0,0 @@
-/**
- * MCP Server Initialization Benchmark
- *
- * Target: <400ms (4.5x faster than current ~1.8s)
- *
- * Measures the time to initialize the MCP (Model Context Protocol) server,
- * including transport setup, tool registration, and handler configuration.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Simulated MCP Components
-// ============================================================================
-
-interface MCPTool {
- name: string;
- description: string;
- inputSchema: object;
- handler: (args: unknown) => Promise<unknown>;
-}
-
-interface MCPServer {
- tools: Map<string, MCPTool>;
- handlers: Map<string, Function>;
- initialized: boolean;
-}
-
-/**
- * Create a simulated MCP tool
- */
-function createTool(name: string): MCPTool {
- return {
- name,
- description: `Tool: ${name}`,
- inputSchema: { type: 'object', properties: {} },
- handler: async (args) => ({ success: true, args }),
- };
-}
-
-/**
- * Simulate tool registration
- */
-function registerTool(server: MCPServer, tool: MCPTool): void {
- server.tools.set(tool.name, tool);
-}
-
-/**
- * Simulate transport initialization
- */
-async function initializeTransport(): Promise<object> {
- // Simulate stdio/HTTP transport setup
- await new Promise((resolve) => setTimeout(resolve, 5));
- return { type: 'stdio', ready: true };
-}
-
-/**
- * Simulate handler registration
- */
-function registerHandlers(server: MCPServer): void {
- server.handlers.set('tools/list', () => {});
- server.handlers.set('tools/call', () => {});
- server.handlers.set('resources/list', () => {});
- server.handlers.set('prompts/list', () => {});
-}
-
-/**
- * Create a new MCP server instance
- */
-function createServer(): MCPServer {
- return {
- tools: new Map(),
- handlers: new Map(),
- initialized: false,
- };
-}
-
-/**
- * Full MCP server initialization
- */
-async function fullMCPInit(): Promise<MCPServer> {
- const server = createServer();
-
- // Initialize transport
- await initializeTransport();
-
- // Register core tools
- const coreTools = [
- 'swarm_init', 'swarm_status', 'agent_spawn', 'agent_list',
- 'task_orchestrate', 'task_status', 'memory_store', 'memory_retrieve',
- 'neural_train', 'neural_patterns',
- ];
-
- for (const toolName of coreTools) {
- registerTool(server, createTool(toolName));
- }
-
- // Register handlers
- registerHandlers(server);
-
- server.initialized = true;
- return server;
-}
-
-/**
- * Optimized MCP server initialization with lazy loading
- */
-async function optimizedMCPInit(): Promise<MCPServer> {
- const server = createServer();
-
- // Parallel initialization
- const [transport] = await Promise.all([
- initializeTransport(),
- // Pre-warm tool registry
- Promise.resolve(),
- ]);
-
- void transport;
-
- // Lazy tool registration - only register on first use
- server.tools = new Map(); // Tools will be registered lazily
-
- // Minimal handler registration
- server.handlers.set('tools/list', () => {});
- server.handlers.set('tools/call', () => {});
-
- server.initialized = true;
- return server;
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runMCPInitBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('MCP Server Initialization');
-
- console.log('\n--- MCP Server Initialization Benchmarks ---\n');
-
- // Benchmark 1: Transport Initialization
- const transportResult = await runner.run(
- 'transport-initialization',
- async () => {
- await initializeTransport();
- },
- { iterations: 100 }
- );
-
- console.log(`Transport Initialization: ${formatTime(transportResult.mean)}`);
-
- // Benchmark 2: Tool Registration (Single)
- const singleToolResult = await runner.run(
- 'single-tool-registration',
- async () => {
- const server = createServer();
- registerTool(server, createTool('test_tool'));
- },
- { iterations: 1000 }
- );
-
- console.log(`Single Tool Registration: ${formatTime(singleToolResult.mean)}`);
-
- // Benchmark 3: Bulk Tool Registration (10 tools)
- const bulkToolResult = await runner.run(
- 'bulk-tool-registration-10',
- async () => {
- const server = createServer();
- for (let i = 0; i < 10; i++) {
- registerTool(server, createTool(`tool_${i}`));
- }
- },
- { iterations: 500 }
- );
-
- console.log(`Bulk Tool Registration (10): ${formatTime(bulkToolResult.mean)}`);
-
- // Benchmark 4: Handler Registration
- const handlerResult = await runner.run(
- 'handler-registration',
- async () => {
- const server = createServer();
- registerHandlers(server);
- },
- { iterations: 1000 }
- );
-
- console.log(`Handler Registration: ${formatTime(handlerResult.mean)}`);
-
- // Benchmark 5: Full MCP Init (V2 Style)
- const fullInitResult = await runner.run(
- 'full-mcp-init-v2-style',
- async () => {
- await fullMCPInit();
- },
- { iterations: 50 }
- );
-
- console.log(`Full MCP Init (V2 Style): ${formatTime(fullInitResult.mean)}`);
- const v2Target = meetsTarget('mcp-server-init', fullInitResult.mean);
- console.log(` Target (<400ms): ${v2Target.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 6: Optimized MCP Init (V3 Style)
- const optimizedInitResult = await runner.run(
- 'optimized-mcp-init-v3-style',
- async () => {
- await optimizedMCPInit();
- },
- { iterations: 100 }
- );
-
- console.log(`Optimized MCP Init (V3 Style): ${formatTime(optimizedInitResult.mean)}`);
- const v3Target = meetsTarget('mcp-server-init', optimizedInitResult.mean);
- console.log(` Target (<400ms): ${v3Target.met ? 'PASS' : 'FAIL'}`);
-
- // Calculate speedup
- const speedup = fullInitResult.mean / optimizedInitResult.mean;
- console.log(`\nSpeedup: ${speedup.toFixed(2)}x`);
-
- // Benchmark 7: Connection Pooling Benefits
- const connectionPoolResult = await runner.run(
- 'connection-pool-reuse',
- async () => {
- // Simulate reusing a pooled connection
- const pool = new Map<string, object>();
- pool.set('mcp-connection', { ready: true });
-
- // Getting from pool is instant
- const connection = pool.get('mcp-connection');
- void connection;
- },
- { iterations: 5000 }
- );
-
- console.log(`Connection Pool Reuse: ${formatTime(connectionPoolResult.mean)}`);
-
- // Benchmark 8: Tool Lookup Performance
- const toolLookupResult = await runner.run(
- 'tool-lookup',
- async () => {
- const server = await fullMCPInit();
- const tool = server.tools.get('swarm_init');
- void tool;
- },
- { iterations: 50 }
- );
-
- console.log(`Tool Lookup (with init): ${formatTime(toolLookupResult.mean)}`);
-
- // Benchmark 9: Pre-warmed Tool Lookup
- const prewarmServer = await fullMCPInit();
- const prewarmedLookupResult = await runner.run(
- 'prewarmed-tool-lookup',
- async () => {
- const tool = prewarmServer.tools.get('swarm_init');
- void tool;
- },
- { iterations: 10000 }
- );
-
- console.log(`Pre-warmed Tool Lookup: ${formatTime(prewarmedLookupResult.mean)}`);
-
- // Print summary
- runner.printResults();
-}
-
-// ============================================================================
-// MCP Initialization Optimization Strategies
-// ============================================================================
-
-export const mcpOptimizations = {
- /**
- * Lazy tool registration: Register tools on first use
- */
- lazyToolRegistration: {
- description: 'Defer tool registration until first use',
- expectedImprovement: '40-60%',
- implementation: `
- class LazyToolRegistry {
- private tools = new Map<string, MCPTool>();
- private loaders = new Map<string, () => MCPTool>();
-
- register(name: string, loader: () => MCPTool) {
- this.loaders.set(name, loader);
- }
-
- get(name: string): MCPTool | undefined {
- if (!this.tools.has(name) && this.loaders.has(name)) {
- this.tools.set(name, this.loaders.get(name)!());
- }
- return this.tools.get(name);
- }
- }
- `,
- },
-
- /**
- * Connection pooling: Reuse transport connections
- */
- connectionPooling: {
- description: 'Pool and reuse MCP transport connections',
- expectedImprovement: '50-70%',
- implementation: `
- const pool = new ConnectionPool({
- max: 10,
- min: 2,
- acquireTimeout: 1000,
- idleTimeout: 60000,
- });
-
- async function getMCPConnection() {
- return pool.acquire('mcp-server');
- }
- `,
- },
-
- /**
- * Parallel initialization: Initialize independent components concurrently
- */
- parallelInit: {
- description: 'Initialize transport, tools, and handlers in parallel',
- expectedImprovement: '30-50%',
- implementation: `
- async function parallelMCPInit() {
- const [transport, tools, handlers] = await Promise.all([
- initTransport(),
- loadTools(),
- loadHandlers(),
- ]);
-
- return createServer(transport, tools, handlers);
- }
- `,
- },
-
- /**
- * Pre-compilation: Pre-compile tool schemas
- */
- schemaPreCompilation: {
- description: 'Pre-compile JSON schemas for faster validation',
- expectedImprovement: '20-30%',
- implementation: `
- import Ajv from 'ajv';
- const ajv = new Ajv({ allErrors: true, strict: false });
-
- // Pre-compile at build time
- const validators = new Map<string, ValidateFunction>();
- for (const tool of tools) {
- validators.set(tool.name, ajv.compile(tool.inputSchema));
- }
- `,
- },
-
- /**
- * In-process mode: Skip transport for local operations
- */
- inProcessMode: {
- description: 'Use in-process calls instead of transport for local tools',
- expectedImprovement: '80-95%',
- implementation: `
- class InProcessMCP {
- private tools = new Map<string, MCPTool>();
-
- async call(toolName: string, args: unknown): Promise<unknown> {
- const tool = this.tools.get(toolName);
- if (tool) {
- return tool.handler(args); // Direct call, no transport
- }
- throw new Error(\`Unknown tool: \${toolName}\`);
- }
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runMCPInitBenchmarks().catch(console.error);
-}
-
-export default runMCPInitBenchmarks;
diff --git a/v3/benchmarks/swarm/agent-coordination.bench.ts b/v3/benchmarks/swarm/agent-coordination.bench.ts
deleted file mode 100644
index a771b407a5..0000000000
--- a/v3/benchmarks/swarm/agent-coordination.bench.ts
+++ /dev/null
@@ -1,571 +0,0 @@
-/**
- * Agent Coordination Benchmark
- *
- * Target: <50ms for coordination operations
- *
- * Measures agent-to-agent coordination including message passing,
- * state synchronization, and coordination patterns.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Agent Types and Coordination
-// ============================================================================
-
-interface Agent {
- id: string;
- type: string;
- status: 'idle' | 'busy' | 'waiting';
- inbox: Message[];
- outbox: Message[];
-}
-
-interface Message {
- id: string;
- from: string;
- to: string;
- type: 'request' | 'response' | 'broadcast' | 'heartbeat';
- payload: unknown;
- timestamp: number;
-}
-
-interface CoordinationResult {
- success: boolean;
- latency: number;
- messagesExchanged: number;
-}
-
-/**
- * Simple message broker for agent communication
- */
-class MessageBroker {
- private agents = new Map<string, Agent>();
- private messageQueue: Message[] = [];
-
- register(agent: Agent): void {
- this.agents.set(agent.id, agent);
- }
-
- send(message: Message): void {
- this.messageQueue.push(message);
- const recipient = this.agents.get(message.to);
- if (recipient) {
- recipient.inbox.push(message);
- }
- }
-
- broadcast(from: string, type: string, payload: unknown): void {
- for (const [id, agent] of this.agents) {
- if (id !== from) {
- const message: Message = {
- id: `msg-${Date.now()}-${Math.random()}`,
- from,
- to: id,
- type: 'broadcast',
- payload,
- timestamp: Date.now(),
- };
- agent.inbox.push(message);
- this.messageQueue.push(message);
- }
- }
- }
-
- processMessage(agentId: string): Message | undefined {
- const agent = this.agents.get(agentId);
- if (agent && agent.inbox.length > 0) {
- return agent.inbox.shift();
- }
- return undefined;
- }
-
- get totalMessages(): number {
- return this.messageQueue.length;
- }
-}
-
-/**
- * Hierarchical coordinator for multi-agent orchestration
- */
-class HierarchicalCoordinator {
- private queen: Agent;
- private workers: Agent[] = [];
- private broker: MessageBroker;
-
- constructor(numWorkers: number) {
- this.broker = new MessageBroker();
-
- this.queen = {
- id: 'queen',
- type: 'coordinator',
- status: 'idle',
- inbox: [],
- outbox: [],
- };
- this.broker.register(this.queen);
-
- for (let i = 0; i < numWorkers; i++) {
- const worker: Agent = {
- id: `worker-${i}`,
- type: 'worker',
- status: 'idle',
- inbox: [],
- outbox: [],
- };
- this.workers.push(worker);
- this.broker.register(worker);
- }
- }
-
- async delegateTask(task: unknown): Promise<CoordinationResult> {
- const startTime = performance.now();
- let messagesExchanged = 0;
-
- // Queen broadcasts task
- this.broker.broadcast(this.queen.id, 'task', task);
- messagesExchanged += this.workers.length;
-
- // Workers acknowledge
- for (const worker of this.workers) {
- const ack: Message = {
- id: `ack-${Date.now()}`,
- from: worker.id,
- to: this.queen.id,
- type: 'response',
- payload: { status: 'accepted' },
- timestamp: Date.now(),
- };
- this.broker.send(ack);
- messagesExchanged++;
- }
-
- // Process acknowledgments
- while (this.queen.inbox.length > 0) {
- this.broker.processMessage(this.queen.id);
- }
-
- return {
- success: true,
- latency: performance.now() - startTime,
- messagesExchanged,
- };
- }
-
- async gatherResults(): Promise<CoordinationResult> {
- const startTime = performance.now();
- let messagesExchanged = 0;
-
- // Request results from all workers
- for (const worker of this.workers) {
- const request: Message = {
- id: `req-${Date.now()}`,
- from: this.queen.id,
- to: worker.id,
- type: 'request',
- payload: { action: 'getResults' },
- timestamp: Date.now(),
- };
- this.broker.send(request);
- messagesExchanged++;
- }
-
- // Workers send results
- for (const worker of this.workers) {
- this.broker.processMessage(worker.id);
- const response: Message = {
- id: `res-${Date.now()}`,
- from: worker.id,
- to: this.queen.id,
- type: 'response',
- payload: { results: ['data'] },
- timestamp: Date.now(),
- };
- this.broker.send(response);
- messagesExchanged++;
- }
-
- // Queen processes all results
- while (this.queen.inbox.length > 0) {
- this.broker.processMessage(this.queen.id);
- }
-
- return {
- success: true,
- latency: performance.now() - startTime,
- messagesExchanged,
- };
- }
-
- get workerCount(): number {
- return this.workers.length;
- }
-}
-
-/**
- * Mesh coordinator for peer-to-peer communication
- */
-class MeshCoordinator {
- private agents: Agent[] = [];
- private broker: MessageBroker;
-
- constructor(numAgents: number) {
- this.broker = new MessageBroker();
-
- for (let i = 0; i < numAgents; i++) {
- const agent: Agent = {
- id: `mesh-agent-${i}`,
- type: 'peer',
- status: 'idle',
- inbox: [],
- outbox: [],
- };
- this.agents.push(agent);
- this.broker.register(agent);
- }
- }
-
- async gossip(originId: number, data: unknown): Promise<CoordinationResult> {
- const startTime = performance.now();
- let messagesExchanged = 0;
-
- const visited = new Set<string>();
- const queue: string[] = [this.agents[originId]!.id];
- visited.add(this.agents[originId]!.id);
-
- while (queue.length > 0) {
- const current = queue.shift()!;
-
- // Send to 2-3 random peers
- const numPeers = Math.min(3, this.agents.length - visited.size);
- const peers = this.agents
- .filter((a) => !visited.has(a.id))
- .slice(0, numPeers);
-
- for (const peer of peers) {
- const message: Message = {
- id: `gossip-${Date.now()}`,
- from: current,
- to: peer.id,
- type: 'broadcast',
- payload: data,
- timestamp: Date.now(),
- };
- this.broker.send(message);
- messagesExchanged++;
- visited.add(peer.id);
- queue.push(peer.id);
- }
- }
-
- return {
- success: visited.size === this.agents.length,
- latency: performance.now() - startTime,
- messagesExchanged,
- };
- }
-
- get agentCount(): number {
- return this.agents.length;
- }
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runAgentCoordinationBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Agent Coordination');
-
- console.log('\n--- Agent Coordination Benchmarks ---\n');
-
- // Benchmark 1: Create Message Broker
- const brokerCreateResult = await runner.run(
- 'create-message-broker',
- async () => {
- const broker = new MessageBroker();
- void broker;
- },
- { iterations: 10000 }
- );
-
- console.log(`Create Message Broker: ${formatTime(brokerCreateResult.mean)}`);
-
- // Benchmark 2: Register Agent
- const broker = new MessageBroker();
-
- const registerResult = await runner.run(
- 'register-agent',
- async () => {
- const agent: Agent = {
- id: `agent-${Date.now()}`,
- type: 'worker',
- status: 'idle',
- inbox: [],
- outbox: [],
- };
- broker.register(agent);
- },
- { iterations: 5000 }
- );
-
- console.log(`Register Agent: ${formatTime(registerResult.mean)}`);
-
- // Benchmark 3: Send Single Message
- const sender: Agent = { id: 'sender', type: 'worker', status: 'idle', inbox: [], outbox: [] };
- const receiver: Agent = { id: 'receiver', type: 'worker', status: 'idle', inbox: [], outbox: [] };
- broker.register(sender);
- broker.register(receiver);
-
- const sendMessageResult = await runner.run(
- 'send-message',
- async () => {
- const message: Message = {
- id: `msg-${Date.now()}`,
- from: 'sender',
- to: 'receiver',
- type: 'request',
- payload: { data: 'test' },
- timestamp: Date.now(),
- };
- broker.send(message);
- },
- { iterations: 10000 }
- );
-
- console.log(`Send Message: ${formatTime(sendMessageResult.mean)}`);
-
- // Benchmark 4: Hierarchical Coordination - 5 Workers
- const hierCoord5 = new HierarchicalCoordinator(5);
-
- const hierDelegate5Result = await runner.run(
- 'hierarchical-delegate-5-workers',
- async () => {
- await hierCoord5.delegateTask({ action: 'process', data: [1, 2, 3] });
- },
- { iterations: 500 }
- );
-
- console.log(`Hierarchical Delegate (5 workers): ${formatTime(hierDelegate5Result.mean)}`);
- const coordTarget = meetsTarget('agent-coordination', hierDelegate5Result.mean);
- console.log(` Target (<50ms): ${coordTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 5: Hierarchical Coordination - 15 Workers
- const hierCoord15 = new HierarchicalCoordinator(15);
-
- const hierDelegate15Result = await runner.run(
- 'hierarchical-delegate-15-workers',
- async () => {
- await hierCoord15.delegateTask({ action: 'process', data: [1, 2, 3] });
- },
- { iterations: 200 }
- );
-
- console.log(`Hierarchical Delegate (15 workers): ${formatTime(hierDelegate15Result.mean)}`);
-
- // Benchmark 6: Gather Results - 5 Workers
- const gather5Result = await runner.run(
- 'hierarchical-gather-5-workers',
- async () => {
- await hierCoord5.gatherResults();
- },
- { iterations: 500 }
- );
-
- console.log(`Hierarchical Gather (5 workers): ${formatTime(gather5Result.mean)}`);
-
- // Benchmark 7: Gather Results - 15 Workers
- const gather15Result = await runner.run(
- 'hierarchical-gather-15-workers',
- async () => {
- await hierCoord15.gatherResults();
- },
- { iterations: 200 }
- );
-
- console.log(`Hierarchical Gather (15 workers): ${formatTime(gather15Result.mean)}`);
-
- // Benchmark 8: Mesh Gossip - 10 Peers
- const meshCoord10 = new MeshCoordinator(10);
-
- const gossip10Result = await runner.run(
- 'mesh-gossip-10-peers',
- async () => {
- await meshCoord10.gossip(0, { data: 'gossip message' });
- },
- { iterations: 500 }
- );
-
- console.log(`Mesh Gossip (10 peers): ${formatTime(gossip10Result.mean)}`);
-
- // Benchmark 9: Mesh Gossip - 50 Peers
- const meshCoord50 = new MeshCoordinator(50);
-
- const gossip50Result = await runner.run(
- 'mesh-gossip-50-peers',
- async () => {
- await meshCoord50.gossip(0, { data: 'gossip message' });
- },
- { iterations: 100 }
- );
-
- console.log(`Mesh Gossip (50 peers): ${formatTime(gossip50Result.mean)}`);
-
- // Benchmark 10: Full Coordination Cycle
- const hierCoordFull = new HierarchicalCoordinator(10);
-
- const fullCycleResult = await runner.run(
- 'full-coordination-cycle',
- async () => {
- await hierCoordFull.delegateTask({ action: 'compute' });
- await hierCoordFull.gatherResults();
- },
- { iterations: 200 }
- );
-
- console.log(`Full Coordination Cycle (10 workers): ${formatTime(fullCycleResult.mean)}`);
-
- // Summary
- console.log('\n--- Summary ---');
- console.log(`Message passing: ${formatTime(sendMessageResult.mean)}`);
- console.log(`5-worker coordination: ${formatTime(hierDelegate5Result.mean)}`);
- console.log(`15-worker coordination: ${formatTime(hierDelegate15Result.mean)}`);
- console.log(`Gossip (10 peers): ${formatTime(gossip10Result.mean)}`);
- console.log(`Gossip (50 peers): ${formatTime(gossip50Result.mean)}`);
- console.log(`\nScaling: 5->15 workers = ${(hierDelegate15Result.mean / hierDelegate5Result.mean).toFixed(2)}x`);
- console.log(`Scaling: 10->50 peers = ${(gossip50Result.mean / gossip10Result.mean).toFixed(2)}x`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Agent Coordination Optimization Strategies
-// ============================================================================
-
-export const coordinationOptimizations = {
- /**
- * Message batching
- */
- messageBatching: {
- description: 'Batch multiple messages to reduce overhead',
- expectedImprovement: '3-5x',
- implementation: `
- class BatchedBroker {
- private batch: Message[] = [];
- private batchSize = 100;
-
- send(message: Message): void {
- this.batch.push(message);
- if (this.batch.length >= this.batchSize) {
- this.flush();
- }
- }
-
- private flush(): void {
- for (const msg of this.batch) {
- this.deliver(msg);
- }
- this.batch = [];
- }
- }
- `,
- },
-
- /**
- * Zero-copy messaging
- */
- zeroCopyMessaging: {
- description: 'Share references instead of copying data',
- expectedImprovement: '2-4x for large payloads',
- implementation: `
- interface SharedMessage {
- id: string;
- payload: SharedArrayBuffer;
- }
-
- function createSharedMessage(data: Uint8Array): SharedMessage {
- const sab = new SharedArrayBuffer(data.length);
- const view = new Uint8Array(sab);
- view.set(data);
- return { id: generateId(), payload: sab };
- }
- `,
- },
-
- /**
- * Hierarchical aggregation
- */
- hierarchicalAggregation: {
- description: 'Aggregate results in tree structure to reduce queen load',
- expectedImprovement: 'O(log n) instead of O(n)',
- implementation: `
- class HierarchicalAggregator {
- async aggregate(workers: Agent[]): Promise<Result> {
- // Create tree of aggregators
- const levels = Math.ceil(Math.log2(workers.length));
- let current = workers.map(w => w.result);
-
- for (let level = 0; level < levels; level++) {
- const next = [];
- for (let i = 0; i < current.length; i += 2) {
- next.push(this.combine(current[i], current[i + 1]));
- }
- current = next;
- }
-
- return current[0];
- }
- }
- `,
- },
-
- /**
- * Async message processing
- */
- asyncProcessing: {
- description: 'Process messages asynchronously with backpressure',
- expectedImprovement: '2-3x throughput',
- implementation: `
- class AsyncBroker {
- private queue = new AsyncQueue<Message>();
-
- async process(): Promise<void> {
- while (true) {
- const messages = await this.queue.dequeue(100); // Batch up to 100
- await Promise.all(messages.map(m => this.handle(m)));
- }
- }
- }
- `,
- },
-
- /**
- * Local-first coordination
- */
- localFirstCoordination: {
- description: 'Process locally when possible, coordinate only when needed',
- expectedImprovement: '5-10x for local operations',
- implementation: `
- class LocalFirstCoordinator {
- canProcessLocally(task: Task): boolean {
- return task.dependencies.every(d => this.hasLocal(d));
- }
-
- async execute(task: Task): Promise<Result> {
- if (this.canProcessLocally(task)) {
- return this.executeLocal(task);
- }
- return this.executeDistributed(task);
- }
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runAgentCoordinationBenchmarks().catch(console.error);
-}
-
-export default runAgentCoordinationBenchmarks;
diff --git a/v3/benchmarks/swarm/consensus-latency.bench.ts b/v3/benchmarks/swarm/consensus-latency.bench.ts
deleted file mode 100644
index f5fcdcca5f..0000000000
--- a/v3/benchmarks/swarm/consensus-latency.bench.ts
+++ /dev/null
@@ -1,613 +0,0 @@
-/**
- * Consensus Latency Benchmark
- *
- * Target: <100ms (5x faster than current ~500ms)
- *
- * Measures the time to achieve consensus among multiple agents
- * using various consensus protocols.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Consensus Types
-// ============================================================================
-
-interface Vote {
- agentId: string;
- value: unknown;
- timestamp: number;
-}
-
-interface ConsensusResult {
- achieved: boolean;
- value: unknown;
- votes: Vote[];
- rounds: number;
- latency: number;
-}
-
-interface Agent {
- id: string;
- vote: (proposal: unknown) => Vote;
- receive: (votes: Vote[]) => void;
-}
-
-// ============================================================================
-// Consensus Implementations
-// ============================================================================
-
-/**
- * Simple majority voting
- */
-class MajorityVoting {
- private agents: Agent[] = [];
-
- constructor(numAgents: number) {
- for (let i = 0; i < numAgents; i++) {
- this.agents.push({
- id: `agent-${i}`,
- vote: (proposal) => ({
- agentId: `agent-${i}`,
- value: proposal,
- timestamp: Date.now(),
- }),
- receive: () => {},
- });
- }
- }
-
- async achieve(proposal: unknown): Promise<ConsensusResult> {
- const startTime = performance.now();
-
- // Collect votes
- const votes = this.agents.map((agent) => agent.vote(proposal));
-
- // Count votes
- const voteCounts = new Map<string, number>();
- for (const vote of votes) {
- const key = JSON.stringify(vote.value);
- voteCounts.set(key, (voteCounts.get(key) || 0) + 1);
- }
-
- // Find majority
- const threshold = Math.floor(this.agents.length / 2) + 1;
- let consensusValue: unknown = null;
- let achieved = false;
-
- for (const [value, count] of voteCounts) {
- if (count >= threshold) {
- consensusValue = JSON.parse(value);
- achieved = true;
- break;
- }
- }
-
- return {
- achieved,
- value: consensusValue,
- votes,
- rounds: 1,
- latency: performance.now() - startTime,
- };
- }
-
- get agentCount(): number {
- return this.agents.length;
- }
-}
-
-/**
- * Two-phase commit protocol
- */
-class TwoPhaseCommit {
- private coordinator: string;
- private participants: string[];
- private preparedVotes = new Map<string, boolean>();
-
- constructor(numParticipants: number) {
- this.coordinator = 'coordinator';
- this.participants = Array.from({ length: numParticipants }, (_, i) => `participant-${i}`);
- }
-
- async commit(transaction: unknown): Promise<ConsensusResult> {
- const startTime = performance.now();
- const votes: Vote[] = [];
- let rounds = 0;
-
- // Phase 1: Prepare
- rounds++;
- const prepareVotes = this.participants.map((p) => {
- const vote: Vote = {
- agentId: p,
- value: { phase: 'prepare', ready: Math.random() > 0.1 }, // 90% success rate
- timestamp: Date.now(),
- };
- votes.push(vote);
- return vote;
- });
-
- const allPrepared = prepareVotes.every(
- (v) => (v.value as { ready: boolean }).ready
- );
-
- if (!allPrepared) {
- // Abort
- rounds++;
- return {
- achieved: false,
- value: null,
- votes,
- rounds,
- latency: performance.now() - startTime,
- };
- }
-
- // Phase 2: Commit
- rounds++;
- const commitVotes = this.participants.map((p) => {
- const vote: Vote = {
- agentId: p,
- value: { phase: 'commit', committed: true },
- timestamp: Date.now(),
- };
- votes.push(vote);
- return vote;
- });
-
- void commitVotes;
-
- return {
- achieved: true,
- value: transaction,
- votes,
- rounds,
- latency: performance.now() - startTime,
- };
- }
-
- get participantCount(): number {
- return this.participants.length;
- }
-}
-
-/**
- * Raft-like leader election
- */
-class RaftConsensus {
- private nodes: Array<{
- id: string;
- term: number;
- votedFor: string | null;
- state: 'follower' | 'candidate' | 'leader';
- }>;
-
- constructor(numNodes: number) {
- this.nodes = Array.from({ length: numNodes }, (_, i) => ({
- id: `node-${i}`,
- term: 0,
- votedFor: null,
- state: 'follower' as const,
- }));
- }
-
- async electLeader(): Promise<ConsensusResult> {
- const startTime = performance.now();
- const votes: Vote[] = [];
- let rounds = 0;
-
- // Timeout and start election
- const candidateIdx = Math.floor(Math.random() * this.nodes.length);
- const candidate = this.nodes[candidateIdx]!;
- candidate.state = 'candidate';
- candidate.term++;
- candidate.votedFor = candidate.id;
-
- rounds++;
-
- // Request votes from all nodes
- let votesReceived = 1; // Vote for self
-
- for (let i = 0; i < this.nodes.length; i++) {
- if (i === candidateIdx) continue;
-
- const node = this.nodes[i]!;
- const grantVote =
- node.term < candidate.term &&
- (node.votedFor === null || node.votedFor === candidate.id);
-
- if (grantVote) {
- node.votedFor = candidate.id;
- node.term = candidate.term;
- votesReceived++;
- }
-
- votes.push({
- agentId: node.id,
- value: { grantVote, term: node.term },
- timestamp: Date.now(),
- });
- }
-
- const majority = Math.floor(this.nodes.length / 2) + 1;
- const achieved = votesReceived >= majority;
-
- if (achieved) {
- candidate.state = 'leader';
- } else {
- candidate.state = 'follower';
- }
-
- return {
- achieved,
- value: achieved ? candidate.id : null,
- votes,
- rounds,
- latency: performance.now() - startTime,
- };
- }
-
- get nodeCount(): number {
- return this.nodes.length;
- }
-}
-
-/**
- * Byzantine Fault Tolerant consensus (simplified PBFT)
- */
-class BFTConsensus {
- private replicas: Array<{
- id: string;
- byzantine: boolean;
- }>;
- private f: number; // Max byzantine faults tolerated
-
- constructor(numReplicas: number, byzantineCount: number = 0) {
- this.replicas = Array.from({ length: numReplicas }, (_, i) => ({
- id: `replica-${i}`,
- byzantine: i < byzantineCount,
- }));
- this.f = Math.floor((numReplicas - 1) / 3);
- }
-
- async agree(proposal: unknown): Promise<ConsensusResult> {
- const startTime = performance.now();
- const votes: Vote[] = [];
- let rounds = 0;
-
- // Pre-prepare phase
- rounds++;
- const preprepareVotes = this.replicas.map((r) => ({
- agentId: r.id,
- value: { phase: 'preprepare', proposal: r.byzantine ? 'bad' : proposal },
- timestamp: Date.now(),
- }));
- votes.push(...preprepareVotes);
-
- // Prepare phase
- rounds++;
- const prepareVotes = this.replicas.map((r) => ({
- agentId: r.id,
- value: { phase: 'prepare', ready: !r.byzantine },
- timestamp: Date.now(),
- }));
- votes.push(...prepareVotes);
-
- const prepareCount = prepareVotes.filter(
- (v) => (v.value as { ready: boolean }).ready
- ).length;
-
- // Need 2f + 1 prepare messages
- if (prepareCount < 2 * this.f + 1) {
- return {
- achieved: false,
- value: null,
- votes,
- rounds,
- latency: performance.now() - startTime,
- };
- }
-
- // Commit phase
- rounds++;
- const commitVotes = this.replicas.map((r) => ({
- agentId: r.id,
- value: { phase: 'commit', committed: !r.byzantine },
- timestamp: Date.now(),
- }));
- votes.push(...commitVotes);
-
- const commitCount = commitVotes.filter(
- (v) => (v.value as { committed: boolean }).committed
- ).length;
-
- const achieved = commitCount >= 2 * this.f + 1;
-
- return {
- achieved,
- value: achieved ? proposal : null,
- votes,
- rounds,
- latency: performance.now() - startTime,
- };
- }
-
- get replicaCount(): number {
- return this.replicas.length;
- }
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runConsensusLatencyBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Consensus Latency');
-
- console.log('\n--- Consensus Latency Benchmarks ---\n');
-
- // Benchmark 1: Majority Voting - 5 Agents
- const majority5 = new MajorityVoting(5);
-
- const majority5Result = await runner.run(
- 'majority-voting-5-agents',
- async () => {
- await majority5.achieve({ action: 'approve', value: 42 });
- },
- { iterations: 1000 }
- );
-
- console.log(`Majority Voting (5 agents): ${formatTime(majority5Result.mean)}`);
- const consensusTarget = meetsTarget('consensus-latency', majority5Result.mean);
- console.log(` Target (<100ms): ${consensusTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 2: Majority Voting - 15 Agents
- const majority15 = new MajorityVoting(15);
-
- const majority15Result = await runner.run(
- 'majority-voting-15-agents',
- async () => {
- await majority15.achieve({ action: 'approve', value: 42 });
- },
- { iterations: 500 }
- );
-
- console.log(`Majority Voting (15 agents): ${formatTime(majority15Result.mean)}`);
-
- // Benchmark 3: Two-Phase Commit - 5 Participants
- const tpc5 = new TwoPhaseCommit(5);
-
- const tpc5Result = await runner.run(
- 'two-phase-commit-5',
- async () => {
- await tpc5.commit({ txId: 'tx-123', data: 'test' });
- },
- { iterations: 1000 }
- );
-
- console.log(`Two-Phase Commit (5 participants): ${formatTime(tpc5Result.mean)}`);
-
- // Benchmark 4: Two-Phase Commit - 15 Participants
- const tpc15 = new TwoPhaseCommit(15);
-
- const tpc15Result = await runner.run(
- 'two-phase-commit-15',
- async () => {
- await tpc15.commit({ txId: 'tx-123', data: 'test' });
- },
- { iterations: 500 }
- );
-
- console.log(`Two-Phase Commit (15 participants): ${formatTime(tpc15Result.mean)}`);
-
- // Benchmark 5: Raft Leader Election - 5 Nodes
- const raft5 = new RaftConsensus(5);
-
- const raft5Result = await runner.run(
- 'raft-election-5-nodes',
- async () => {
- await raft5.electLeader();
- },
- { iterations: 1000 }
- );
-
- console.log(`Raft Election (5 nodes): ${formatTime(raft5Result.mean)}`);
-
- // Benchmark 6: Raft Leader Election - 15 Nodes
- const raft15 = new RaftConsensus(15);
-
- const raft15Result = await runner.run(
- 'raft-election-15-nodes',
- async () => {
- await raft15.electLeader();
- },
- { iterations: 500 }
- );
-
- console.log(`Raft Election (15 nodes): ${formatTime(raft15Result.mean)}`);
-
- // Benchmark 7: BFT Consensus - 4 Replicas (f=1)
- const bft4 = new BFTConsensus(4, 0);
-
- const bft4Result = await runner.run(
- 'bft-consensus-4-replicas',
- async () => {
- await bft4.agree({ decision: 'commit' });
- },
- { iterations: 1000 }
- );
-
- console.log(`BFT Consensus (4 replicas, f=1): ${formatTime(bft4Result.mean)}`);
-
- // Benchmark 8: BFT Consensus - 7 Replicas (f=2)
- const bft7 = new BFTConsensus(7, 0);
-
- const bft7Result = await runner.run(
- 'bft-consensus-7-replicas',
- async () => {
- await bft7.agree({ decision: 'commit' });
- },
- { iterations: 500 }
- );
-
- console.log(`BFT Consensus (7 replicas, f=2): ${formatTime(bft7Result.mean)}`);
-
- // Benchmark 9: BFT with Byzantine Nodes
- const bft7byz = new BFTConsensus(7, 2);
-
- const bft7byzResult = await runner.run(
- 'bft-consensus-7-with-2-byzantine',
- async () => {
- await bft7byz.agree({ decision: 'commit' });
- },
- { iterations: 500 }
- );
-
- console.log(`BFT (7 replicas, 2 byzantine): ${formatTime(bft7byzResult.mean)}`);
-
- // Benchmark 10: Multiple Consensus Rounds
- const multiRoundResult = await runner.run(
- 'multiple-consensus-rounds-10',
- async () => {
- for (let i = 0; i < 10; i++) {
- await majority5.achieve({ round: i });
- }
- },
- { iterations: 100 }
- );
-
- console.log(`10 Consensus Rounds: ${formatTime(multiRoundResult.mean)}`);
-
- // Summary
- console.log('\n--- Summary ---');
- console.log(`Majority (5): ${formatTime(majority5Result.mean)}`);
- console.log(`Majority (15): ${formatTime(majority15Result.mean)}`);
- console.log(`2PC (5): ${formatTime(tpc5Result.mean)}`);
- console.log(`Raft (5): ${formatTime(raft5Result.mean)}`);
- console.log(`BFT (4): ${formatTime(bft4Result.mean)}`);
- console.log(`\nScaling factors:`);
- console.log(` Majority 5->15: ${(majority15Result.mean / majority5Result.mean).toFixed(2)}x`);
- console.log(` 2PC 5->15: ${(tpc15Result.mean / tpc5Result.mean).toFixed(2)}x`);
- console.log(` Raft 5->15: ${(raft15Result.mean / raft5Result.mean).toFixed(2)}x`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Consensus Optimization Strategies
-// ============================================================================
-
-export const consensusOptimizations = {
- /**
- * Parallel vote collection
- */
- parallelVoteCollection: {
- description: 'Collect votes from all agents in parallel',
- expectedImprovement: 'O(1) instead of O(n)',
- implementation: `
- async function collectVotes(agents: Agent[], proposal: unknown): Promise<Vote[]> {
- return Promise.all(agents.map(agent => agent.vote(proposal)));
- }
- `,
- },
-
- /**
- * Early termination
- */
- earlyTermination: {
- description: 'Terminate early when majority is achieved',
- expectedImprovement: '30-50%',
- implementation: `
- async function earlyMajority(agents: Agent[], proposal: unknown): Promise<Vote[]> {
- const majority = Math.floor(agents.length / 2) + 1;
- const votes: Vote[] = [];
-
- for (const agent of agents) {
- votes.push(await agent.vote(proposal));
- const count = countAgreement(votes);
- if (count >= majority) break;
- }
-
- return votes;
- }
- `,
- },
-
- /**
- * Pipelining phases
- */
- pipelining: {
- description: 'Pipeline consensus phases for multiple proposals',
- expectedImprovement: '2-3x throughput',
- implementation: `
- class PipelinedConsensus {
- private phases = ['prepare', 'accept', 'commit'];
- private inflight = new Map<string, number>();
-
- async propose(proposal: unknown): Promise<void> {
- const id = generateId();
- this.inflight.set(id, 0);
-
- // Start next phase as soon as previous completes
- for (const phase of this.phases) {
- await this.executePhase(id, phase);
- this.inflight.set(id, this.inflight.get(id)! + 1);
- }
- }
- }
- `,
- },
-
- /**
- * Speculative execution
- */
- speculativeExecution: {
- description: 'Speculatively execute while waiting for consensus',
- expectedImprovement: '50-70% latency reduction',
- implementation: `
- async function speculativeConsensus(proposal: unknown): Promise<Result> {
- const [consensusResult, executionResult] = await Promise.all([
- achieveConsensus(proposal),
- speculativelyExecute(proposal),
- ]);
-
- if (consensusResult.achieved) {
- return executionResult;
- }
-
- return rollback(executionResult);
- }
- `,
- },
-
- /**
- * Hierarchical consensus
- */
- hierarchicalConsensus: {
- description: 'Achieve consensus in smaller groups first',
- expectedImprovement: 'O(log n) rounds',
- implementation: `
- async function hierarchicalConsensus(agents: Agent[]): Promise<Vote[]> {
- const groupSize = 5;
- const groups = chunkArray(agents, groupSize);
-
- // First level: consensus within groups
- const groupResults = await Promise.all(
- groups.map(group => achieveConsensus(group))
- );
-
- // Second level: consensus among group leaders
- const leaders = groupResults.map(r => r.leader);
- return achieveConsensus(leaders);
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runConsensusLatencyBenchmarks().catch(console.error);
-}
-
-export default runConsensusLatencyBenchmarks;
diff --git a/v3/benchmarks/swarm/message-throughput.bench.ts b/v3/benchmarks/swarm/message-throughput.bench.ts
deleted file mode 100644
index c1ad238d41..0000000000
--- a/v3/benchmarks/swarm/message-throughput.bench.ts
+++ /dev/null
@@ -1,568 +0,0 @@
-/**
- * Message Throughput Benchmark
- *
- * Target: <0.1ms per message
- *
- * Measures message passing throughput between agents including
- * serialization, routing, and delivery.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Message Types
-// ============================================================================
-
-interface Message {
- id: string;
- type: string;
- from: string;
- to: string;
- payload: unknown;
- timestamp: number;
- headers?: Record<string, string>;
-}
-
-interface MessageStats {
- sent: number;
- received: number;
- dropped: number;
- latencySum: number;
-}
-
-// ============================================================================
-// Message Channel Implementations
-// ============================================================================
-
-/**
- * Simple synchronous message channel
- */
-class SyncChannel {
- private handlers = new Map<string, (msg: Message) => void>();
- private stats: MessageStats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
-
- subscribe(agentId: string, handler: (msg: Message) => void): void {
- this.handlers.set(agentId, handler);
- }
-
- send(message: Message): boolean {
- this.stats.sent++;
- const handler = this.handlers.get(message.to);
- if (handler) {
- handler(message);
- this.stats.received++;
- this.stats.latencySum += Date.now() - message.timestamp;
- return true;
- }
- this.stats.dropped++;
- return false;
- }
-
- getStats(): MessageStats {
- return { ...this.stats };
- }
-
- reset(): void {
- this.stats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
- }
-}
-
-/**
- * Async message queue with buffering
- */
-class AsyncMessageQueue {
- private queues = new Map<string, Message[]>();
- private stats: MessageStats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
- private maxQueueSize = 1000;
-
- enqueue(message: Message): boolean {
- this.stats.sent++;
-
- let queue = this.queues.get(message.to);
- if (!queue) {
- queue = [];
- this.queues.set(message.to, queue);
- }
-
- if (queue.length >= this.maxQueueSize) {
- this.stats.dropped++;
- return false;
- }
-
- queue.push(message);
- return true;
- }
-
- dequeue(agentId: string): Message | undefined {
- const queue = this.queues.get(agentId);
- if (queue && queue.length > 0) {
- const message = queue.shift()!;
- this.stats.received++;
- this.stats.latencySum += Date.now() - message.timestamp;
- return message;
- }
- return undefined;
- }
-
- dequeueAll(agentId: string): Message[] {
- const queue = this.queues.get(agentId) || [];
- this.queues.set(agentId, []);
- this.stats.received += queue.length;
- for (const msg of queue) {
- this.stats.latencySum += Date.now() - msg.timestamp;
- }
- return queue;
- }
-
- getStats(): MessageStats {
- return { ...this.stats };
- }
-
- reset(): void {
- this.queues.clear();
- this.stats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
- }
-}
-
-/**
- * Pub/Sub message broker
- */
-class PubSubBroker {
- private topics = new Map<string, Set<string>>();
- private handlers = new Map<string, (msg: Message) => void>();
- private stats: MessageStats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
-
- subscribe(agentId: string, topic: string, handler: (msg: Message) => void): void {
- if (!this.topics.has(topic)) {
- this.topics.set(topic, new Set());
- }
- this.topics.get(topic)!.add(agentId);
- this.handlers.set(`${agentId}:${topic}`, handler);
- }
-
- publish(topic: string, message: Message): number {
- const subscribers = this.topics.get(topic);
- if (!subscribers) return 0;
-
- let delivered = 0;
- for (const agentId of subscribers) {
- this.stats.sent++;
- const handler = this.handlers.get(`${agentId}:${topic}`);
- if (handler) {
- handler({ ...message, to: agentId });
- this.stats.received++;
- this.stats.latencySum += Date.now() - message.timestamp;
- delivered++;
- }
- }
-
- return delivered;
- }
-
- getStats(): MessageStats {
- return { ...this.stats };
- }
-
- reset(): void {
- this.stats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
- }
-}
-
-/**
- * Batched message channel
- */
-class BatchedChannel {
- private batch: Message[] = [];
- private handlers = new Map<string, (msgs: Message[]) => void>();
- private batchSize = 100;
- private stats: MessageStats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
-
- subscribe(agentId: string, handler: (msgs: Message[]) => void): void {
- this.handlers.set(agentId, handler);
- }
-
- send(message: Message): void {
- this.stats.sent++;
- this.batch.push(message);
-
- if (this.batch.length >= this.batchSize) {
- this.flush();
- }
- }
-
- flush(): void {
- // Group messages by recipient
- const byRecipient = new Map<string, Message[]>();
- for (const msg of this.batch) {
- if (!byRecipient.has(msg.to)) {
- byRecipient.set(msg.to, []);
- }
- byRecipient.get(msg.to)!.push(msg);
- }
-
- // Deliver to each recipient
- for (const [agentId, messages] of byRecipient) {
- const handler = this.handlers.get(agentId);
- if (handler) {
- handler(messages);
- this.stats.received += messages.length;
- for (const msg of messages) {
- this.stats.latencySum += Date.now() - msg.timestamp;
- }
- } else {
- this.stats.dropped += messages.length;
- }
- }
-
- this.batch = [];
- }
-
- getStats(): MessageStats {
- return { ...this.stats };
- }
-
- reset(): void {
- this.batch = [];
- this.stats = { sent: 0, received: 0, dropped: 0, latencySum: 0 };
- }
-}
-
-// ============================================================================
-// Helper Functions
-// ============================================================================
-
-function createMessage(from: string, to: string, payload: unknown): Message {
- return {
- id: `msg-${Date.now()}-${Math.random().toString(36).slice(2)}`,
- type: 'data',
- from,
- to,
- payload,
- timestamp: Date.now(),
- };
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runMessageThroughputBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Message Throughput');
-
- console.log('\n--- Message Throughput Benchmarks ---\n');
-
- // Setup channels
- const syncChannel = new SyncChannel();
- const asyncQueue = new AsyncMessageQueue();
- const pubsub = new PubSubBroker();
- const batchedChannel = new BatchedChannel();
-
- // Register handlers
- for (let i = 0; i < 100; i++) {
- syncChannel.subscribe(`agent-${i}`, () => {});
- batchedChannel.subscribe(`agent-${i}`, () => {});
- }
- for (let i = 0; i < 100; i++) {
- pubsub.subscribe(`agent-${i}`, 'broadcast', () => {});
- }
-
- // Benchmark 1: Single Message - Sync Channel
- const syncSingleResult = await runner.run(
- 'sync-channel-single-message',
- async () => {
- const msg = createMessage('sender', 'agent-0', { data: 'test' });
- syncChannel.send(msg);
- },
- { iterations: 100000 }
- );
-
- console.log(`Sync Channel (single): ${formatTime(syncSingleResult.mean)}`);
- const throughputTarget = meetsTarget('message-throughput', syncSingleResult.mean);
- console.log(` Target (<0.1ms): ${throughputTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 2: Message Batch - Sync Channel (100 messages)
- const syncBatchResult = await runner.run(
- 'sync-channel-100-messages',
- async () => {
- for (let i = 0; i < 100; i++) {
- const msg = createMessage('sender', `agent-${i}`, { data: i });
- syncChannel.send(msg);
- }
- },
- { iterations: 1000 }
- );
-
- console.log(`Sync Channel (100 messages): ${formatTime(syncBatchResult.mean)}`);
- console.log(` Per message: ${formatTime(syncBatchResult.mean / 100)}`);
-
- // Benchmark 3: Async Queue - Enqueue
- const asyncEnqueueResult = await runner.run(
- 'async-queue-enqueue',
- async () => {
- const msg = createMessage('sender', 'agent-0', { data: 'test' });
- asyncQueue.enqueue(msg);
- },
- { iterations: 100000 }
- );
-
- console.log(`Async Queue (enqueue): ${formatTime(asyncEnqueueResult.mean)}`);
-
- // Benchmark 4: Async Queue - Dequeue
- // Pre-populate queue
- for (let i = 0; i < 10000; i++) {
- asyncQueue.enqueue(createMessage('sender', 'agent-0', { data: i }));
- }
-
- const asyncDequeueResult = await runner.run(
- 'async-queue-dequeue',
- async () => {
- asyncQueue.dequeue('agent-0');
- },
- { iterations: 10000 }
- );
-
- console.log(`Async Queue (dequeue): ${formatTime(asyncDequeueResult.mean)}`);
-
- // Benchmark 5: Async Queue - Batch Dequeue
- asyncQueue.reset();
- for (let i = 0; i < 100; i++) {
- asyncQueue.enqueue(createMessage('sender', 'agent-1', { data: i }));
- }
-
- const asyncBatchDequeueResult = await runner.run(
- 'async-queue-batch-dequeue',
- async () => {
- asyncQueue.dequeueAll('agent-1');
- // Refill for next iteration
- for (let i = 0; i < 100; i++) {
- asyncQueue.enqueue(createMessage('sender', 'agent-1', { data: i }));
- }
- },
- { iterations: 1000 }
- );
-
- console.log(`Async Queue (batch dequeue 100): ${formatTime(asyncBatchDequeueResult.mean)}`);
-
- // Benchmark 6: Pub/Sub - Single Publish
- const pubsubSingleResult = await runner.run(
- 'pubsub-single-publish',
- async () => {
- const msg = createMessage('publisher', '', { event: 'test' });
- pubsub.publish('broadcast', msg);
- },
- { iterations: 1000 }
- );
-
- console.log(`Pub/Sub (to 100 subscribers): ${formatTime(pubsubSingleResult.mean)}`);
- console.log(` Per subscriber: ${formatTime(pubsubSingleResult.mean / 100)}`);
-
- // Benchmark 7: Batched Channel - Single Message
- const batchedSingleResult = await runner.run(
- 'batched-channel-single',
- async () => {
- const msg = createMessage('sender', 'agent-0', { data: 'test' });
- batchedChannel.send(msg);
- },
- { iterations: 10000 }
- );
-
- console.log(`Batched Channel (single, no flush): ${formatTime(batchedSingleResult.mean)}`);
-
- // Benchmark 8: Batched Channel - Full Batch + Flush
- batchedChannel.reset();
-
- const batchedFlushResult = await runner.run(
- 'batched-channel-flush-100',
- async () => {
- for (let i = 0; i < 100; i++) {
- batchedChannel.send(createMessage('sender', `agent-${i}`, { data: i }));
- }
- batchedChannel.flush();
- },
- { iterations: 1000 }
- );
-
- console.log(`Batched Channel (100 + flush): ${formatTime(batchedFlushResult.mean)}`);
- console.log(` Per message: ${formatTime(batchedFlushResult.mean / 100)}`);
-
- // Benchmark 9: Message Serialization
- const serializationResult = await runner.run(
- 'message-serialization',
- async () => {
- const msg = createMessage('sender', 'receiver', {
- data: Array.from({ length: 100 }, (_, i) => i),
- nested: { level1: { level2: { value: 42 } } },
- });
- JSON.stringify(msg);
- },
- { iterations: 10000 }
- );
-
- console.log(`Message Serialization: ${formatTime(serializationResult.mean)}`);
-
- // Benchmark 10: Message Deserialization
- const msgJson = JSON.stringify(
- createMessage('sender', 'receiver', {
- data: Array.from({ length: 100 }, (_, i) => i),
- })
- );
-
- const deserializationResult = await runner.run(
- 'message-deserialization',
- async () => {
- JSON.parse(msgJson);
- },
- { iterations: 10000 }
- );
-
- console.log(`Message Deserialization: ${formatTime(deserializationResult.mean)}`);
-
- // Benchmark 11: High Throughput Test (1000 messages)
- syncChannel.reset();
-
- const highThroughputResult = await runner.run(
- 'high-throughput-1000-messages',
- async () => {
- for (let i = 0; i < 1000; i++) {
- const msg = createMessage('sender', `agent-${i % 100}`, { seq: i });
- syncChannel.send(msg);
- }
- },
- { iterations: 100 }
- );
-
- console.log(`High Throughput (1000 messages): ${formatTime(highThroughputResult.mean)}`);
- console.log(` Throughput: ${(1000 / highThroughputResult.mean * 1000).toFixed(0)} msg/sec`);
-
- // Summary
- console.log('\n--- Summary ---');
- console.log(`Single message: ${formatTime(syncSingleResult.mean)}`);
- console.log(`Batch (100): ${formatTime(syncBatchResult.mean)} (${formatTime(syncBatchResult.mean / 100)}/msg)`);
- console.log(`Pub/Sub (100 subs): ${formatTime(pubsubSingleResult.mean)}`);
- console.log(`Serialization: ${formatTime(serializationResult.mean)}`);
- console.log(`\nThroughput: ${(1000 / highThroughputResult.mean * 1000).toFixed(0)} messages/sec`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Message Throughput Optimization Strategies
-// ============================================================================
-
-export const messageOptimizations = {
- /**
- * Zero-copy messaging
- */
- zeroCopy: {
- description: 'Use SharedArrayBuffer to avoid copying message data',
- expectedImprovement: '3-5x for large messages',
- implementation: `
- class ZeroCopyChannel {
- send(data: Uint8Array): void {
- const sab = new SharedArrayBuffer(data.length);
- new Uint8Array(sab).set(data);
- this.deliverReference(sab);
- }
- }
- `,
- },
-
- /**
- * Message batching
- */
- messageBatching: {
- description: 'Batch multiple messages to amortize overhead',
- expectedImprovement: '5-10x throughput',
- implementation: `
- class BatchedSender {
- private batch: Message[] = [];
- private batchSize = 100;
-
- send(msg: Message): void {
- this.batch.push(msg);
- if (this.batch.length >= this.batchSize) {
- this.flush();
- }
- }
-
- private flush(): void {
- this.transport.sendBatch(this.batch);
- this.batch = [];
- }
- }
- `,
- },
-
- /**
- * Binary serialization
- */
- binarySerialization: {
- description: 'Use binary format instead of JSON',
- expectedImprovement: '2-4x serialization speed',
- implementation: `
- import msgpack from '@msgpack/msgpack';
-
- function serialize(msg: Message): Uint8Array {
- return msgpack.encode(msg);
- }
-
- function deserialize(data: Uint8Array): Message {
- return msgpack.decode(data) as Message;
- }
- `,
- },
-
- /**
- * Connection pooling
- */
- connectionPooling: {
- description: 'Reuse connections for message delivery',
- expectedImprovement: '10-20x for remote messaging',
- implementation: `
- class ConnectionPool {
- private pool: Connection[] = [];
-
- async getConnection(target: string): Promise<Connection> {
- const cached = this.pool.find(c => c.target === target && c.idle);
- if (cached) {
- cached.idle = false;
- return cached;
- }
- return this.createConnection(target);
- }
- }
- `,
- },
-
- /**
- * Priority queuing
- */
- priorityQueuing: {
- description: 'Process high-priority messages first',
- expectedImprovement: 'Lower latency for critical messages',
- implementation: `
- class PriorityQueue {
- private high: Message[] = [];
- private normal: Message[] = [];
- private low: Message[] = [];
-
- enqueue(msg: Message): void {
- const queue = this.getQueue(msg.priority);
- queue.push(msg);
- }
-
- dequeue(): Message | undefined {
- return this.high.shift() || this.normal.shift() || this.low.shift();
- }
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runMessageThroughputBenchmarks().catch(console.error);
-}
-
-export default runMessageThroughputBenchmarks;
diff --git a/v3/benchmarks/swarm/task-decomposition.bench.ts b/v3/benchmarks/swarm/task-decomposition.bench.ts
deleted file mode 100644
index ef2ec39823..0000000000
--- a/v3/benchmarks/swarm/task-decomposition.bench.ts
+++ /dev/null
@@ -1,545 +0,0 @@
-/**
- * Task Decomposition Benchmark
- *
- * Target: <20ms for task decomposition
- *
- * Measures the time to decompose complex tasks into subtasks
- * for parallel execution by multiple agents.
- */
-
-import { benchmark, BenchmarkRunner, formatTime, meetsTarget } from '../framework/benchmark.js';
-
-// ============================================================================
-// Task Types
-// ============================================================================
-
-interface Task {
- id: string;
- type: string;
- description: string;
- priority: number;
- dependencies: string[];
- estimatedDuration: number;
- assignedTo?: string;
-}
-
-interface SubTask extends Task {
- parentId: string;
- order: number;
-}
-
-interface TaskGraph {
- tasks: Map<string, Task>;
- edges: Map<string, string[]>; // task -> dependencies
-}
-
-interface DecompositionResult {
- subtasks: SubTask[];
- parallelGroups: SubTask[][];
- criticalPath: string[];
- estimatedTotalTime: number;
-}
-
-// ============================================================================
-// Task Decomposition Strategies
-// ============================================================================
-
-/**
- * Simple linear decomposition
- */
-function linearDecompose(task: Task, numParts: number): SubTask[] {
- const subtasks: SubTask[] = [];
-
- for (let i = 0; i < numParts; i++) {
- subtasks.push({
- id: `${task.id}-part-${i}`,
- parentId: task.id,
- type: task.type,
- description: `Part ${i + 1} of ${task.description}`,
- priority: task.priority,
- dependencies: i > 0 ? [`${task.id}-part-${i - 1}`] : task.dependencies,
- estimatedDuration: task.estimatedDuration / numParts,
- order: i,
- });
- }
-
- return subtasks;
-}
-
-/**
- * Parallel decomposition (all subtasks independent)
- */
-function parallelDecompose(task: Task, numParts: number): SubTask[] {
- const subtasks: SubTask[] = [];
-
- for (let i = 0; i < numParts; i++) {
- subtasks.push({
- id: `${task.id}-parallel-${i}`,
- parentId: task.id,
- type: task.type,
- description: `Parallel chunk ${i + 1} of ${task.description}`,
- priority: task.priority,
- dependencies: task.dependencies, // All depend only on parent's deps
- estimatedDuration: task.estimatedDuration / numParts,
- order: i,
- });
- }
-
- return subtasks;
-}
-
-/**
- * DAG-based decomposition with topological sort
- */
-function dagDecompose(tasks: Task[]): DecompositionResult {
- const graph: TaskGraph = {
- tasks: new Map(tasks.map((t) => [t.id, t])),
- edges: new Map(tasks.map((t) => [t.id, t.dependencies])),
- };
-
- // Topological sort using Kahn's algorithm
- const inDegree = new Map<string, number>();
- for (const task of tasks) {
- inDegree.set(task.id, 0);
- }
-
- for (const [, deps] of graph.edges) {
- for (const dep of deps) {
- inDegree.set(dep, (inDegree.get(dep) || 0) + 1);
- }
- }
-
- const queue: string[] = [];
- for (const [id, degree] of inDegree) {
- if (degree === 0) {
- queue.push(id);
- }
- }
-
- const sorted: string[] = [];
- const parallelGroups: SubTask[][] = [];
-
- while (queue.length > 0) {
- // All tasks in current queue can run in parallel
- const currentGroup: SubTask[] = [];
- const nextQueue: string[] = [];
-
- for (const taskId of queue) {
- const task = graph.tasks.get(taskId)!;
- currentGroup.push({
- ...task,
- parentId: 'root',
- order: sorted.length,
- });
- sorted.push(taskId);
-
- // Reduce in-degree of dependent tasks
- for (const [depId, deps] of graph.edges) {
- if (deps.includes(taskId)) {
- const newDegree = (inDegree.get(depId) || 1) - 1;
- inDegree.set(depId, newDegree);
- if (newDegree === 0) {
- nextQueue.push(depId);
- }
- }
- }
- }
-
- if (currentGroup.length > 0) {
- parallelGroups.push(currentGroup);
- }
- queue.length = 0;
- queue.push(...nextQueue);
- }
-
- // Find critical path
- const criticalPath = findCriticalPath(tasks, sorted);
-
- // Calculate estimated total time (parallel execution)
- const estimatedTotalTime = parallelGroups.reduce(
- (total, group) => total + Math.max(...group.map((t) => t.estimatedDuration)),
- 0
- );
-
- return {
- subtasks: parallelGroups.flat(),
- parallelGroups,
- criticalPath,
- estimatedTotalTime,
- };
-}
-
-/**
- * Find critical path in task graph
- */
-function findCriticalPath(tasks: Task[], sorted: string[]): string[] {
- const taskMap = new Map(tasks.map((t) => [t.id, t]));
- const longestPath = new Map<string, number>();
- const predecessor = new Map<string, string>();
-
- for (const taskId of sorted) {
- const task = taskMap.get(taskId)!;
- let maxPredDuration = 0;
- let maxPredId = '';
-
- for (const depId of task.dependencies) {
- const predDuration = longestPath.get(depId) || 0;
- if (predDuration > maxPredDuration) {
- maxPredDuration = predDuration;
- maxPredId = depId;
- }
- }
-
- longestPath.set(taskId, maxPredDuration + task.estimatedDuration);
- if (maxPredId) {
- predecessor.set(taskId, maxPredId);
- }
- }
-
- // Find task with longest path
- let maxTask = '';
- let maxDuration = 0;
- for (const [taskId, duration] of longestPath) {
- if (duration > maxDuration) {
- maxDuration = duration;
- maxTask = taskId;
- }
- }
-
- // Reconstruct path
- const path: string[] = [];
- let current = maxTask;
- while (current) {
- path.unshift(current);
- current = predecessor.get(current) || '';
- }
-
- return path;
-}
-
-/**
- * SPARC-based decomposition
- */
-function sparcDecompose(task: Task): SubTask[] {
- const phases = [
- { name: 'specification', ratio: 0.1 },
- { name: 'pseudocode', ratio: 0.15 },
- { name: 'architecture', ratio: 0.2 },
- { name: 'refinement', ratio: 0.4 },
- { name: 'completion', ratio: 0.15 },
- ];
-
- const subtasks: SubTask[] = [];
- let prevId = '';
-
- for (let i = 0; i < phases.length; i++) {
- const phase = phases[i]!;
- const subtask: SubTask = {
- id: `${task.id}-${phase.name}`,
- parentId: task.id,
- type: phase.name,
- description: `${phase.name.charAt(0).toUpperCase() + phase.name.slice(1)} for ${task.description}`,
- priority: task.priority,
- dependencies: prevId ? [prevId] : task.dependencies,
- estimatedDuration: task.estimatedDuration * phase.ratio,
- order: i,
- };
- subtasks.push(subtask);
- prevId = subtask.id;
- }
-
- return subtasks;
-}
-
-// ============================================================================
-// Benchmark Suite
-// ============================================================================
-
-export async function runTaskDecompositionBenchmarks(): Promise<void> {
- const runner = new BenchmarkRunner('Task Decomposition');
-
- console.log('\n--- Task Decomposition Benchmarks ---\n');
-
- // Create sample tasks
- const sampleTask: Task = {
- id: 'task-1',
- type: 'development',
- description: 'Implement user authentication',
- priority: 1,
- dependencies: [],
- estimatedDuration: 100,
- };
-
- const complexTasks: Task[] = Array.from({ length: 50 }, (_, i) => ({
- id: `task-${i}`,
- type: 'development',
- description: `Task ${i}`,
- priority: Math.floor(Math.random() * 10),
- dependencies: i > 0 ? [`task-${Math.floor(Math.random() * i)}`] : [],
- estimatedDuration: 10 + Math.random() * 90,
- }));
-
- // Benchmark 1: Linear Decomposition
- const linearResult = await runner.run(
- 'linear-decompose-10',
- async () => {
- linearDecompose(sampleTask, 10);
- },
- { iterations: 5000 }
- );
-
- console.log(`Linear Decompose (10 parts): ${formatTime(linearResult.mean)}`);
- const decomposeTarget = meetsTarget('task-decomposition', linearResult.mean);
- console.log(` Target (<20ms): ${decomposeTarget.met ? 'PASS' : 'FAIL'}`);
-
- // Benchmark 2: Parallel Decomposition
- const parallelResult = await runner.run(
- 'parallel-decompose-10',
- async () => {
- parallelDecompose(sampleTask, 10);
- },
- { iterations: 5000 }
- );
-
- console.log(`Parallel Decompose (10 parts): ${formatTime(parallelResult.mean)}`);
-
- // Benchmark 3: SPARC Decomposition
- const sparcResult = await runner.run(
- 'sparc-decompose',
- async () => {
- sparcDecompose(sampleTask);
- },
- { iterations: 5000 }
- );
-
- console.log(`SPARC Decompose (5 phases): ${formatTime(sparcResult.mean)}`);
-
- // Benchmark 4: DAG Decomposition - Small (10 tasks)
- const smallTasks = complexTasks.slice(0, 10);
-
- const dagSmallResult = await runner.run(
- 'dag-decompose-10-tasks',
- async () => {
- dagDecompose(smallTasks);
- },
- { iterations: 1000 }
- );
-
- console.log(`DAG Decompose (10 tasks): ${formatTime(dagSmallResult.mean)}`);
-
- // Benchmark 5: DAG Decomposition - Medium (50 tasks)
- const dagMediumResult = await runner.run(
- 'dag-decompose-50-tasks',
- async () => {
- dagDecompose(complexTasks);
- },
- { iterations: 500 }
- );
-
- console.log(`DAG Decompose (50 tasks): ${formatTime(dagMediumResult.mean)}`);
-
- // Benchmark 6: Critical Path Finding
- const sorted = complexTasks.map((t) => t.id);
-
- const criticalPathResult = await runner.run(
- 'find-critical-path-50',
- async () => {
- findCriticalPath(complexTasks, sorted);
- },
- { iterations: 1000 }
- );
-
- console.log(`Find Critical Path (50 tasks): ${formatTime(criticalPathResult.mean)}`);
-
- // Benchmark 7: Large Decomposition (100 subtasks)
- const largeLinearResult = await runner.run(
- 'linear-decompose-100',
- async () => {
- linearDecompose(sampleTask, 100);
- },
- { iterations: 1000 }
- );
-
- console.log(`Linear Decompose (100 parts): ${formatTime(largeLinearResult.mean)}`);
-
- // Benchmark 8: Nested Decomposition
- const nestedResult = await runner.run(
- 'nested-decompose',
- async () => {
- // First level
- const level1 = parallelDecompose(sampleTask, 5);
- // Second level - decompose each part
- const level2: SubTask[] = [];
- for (const subtask of level1) {
- level2.push(...linearDecompose(subtask, 4));
- }
- },
- { iterations: 1000 }
- );
-
- console.log(`Nested Decompose (5x4=20): ${formatTime(nestedResult.mean)}`);
-
- // Benchmark 9: Task Prioritization
- const prioritizeResult = await runner.run(
- 'task-prioritization-50',
- async () => {
- const sorted = [...complexTasks].sort((a, b) => b.priority - a.priority);
- void sorted;
- },
- { iterations: 5000 }
- );
-
- console.log(`Task Prioritization (50 tasks): ${formatTime(prioritizeResult.mean)}`);
-
- // Benchmark 10: Dependency Resolution
- const dependencyResult = await runner.run(
- 'dependency-resolution-50',
- async () => {
- const resolved = new Set<string>();
- const pending = [...complexTasks];
-
- while (pending.length > 0) {
- const ready = pending.filter((t) =>
- t.dependencies.every((d) => resolved.has(d))
- );
- for (const task of ready) {
- resolved.add(task.id);
- const idx = pending.indexOf(task);
- if (idx >= 0) pending.splice(idx, 1);
- }
- if (ready.length === 0) break; // Circular dependency
- }
- },
- { iterations: 500 }
- );
-
- console.log(`Dependency Resolution (50 tasks): ${formatTime(dependencyResult.mean)}`);
-
- // Summary
- console.log('\n--- Summary ---');
- console.log(`Simple decomposition: ${formatTime(linearResult.mean)}`);
- console.log(`SPARC decomposition: ${formatTime(sparcResult.mean)}`);
- console.log(`DAG (10 tasks): ${formatTime(dagSmallResult.mean)}`);
- console.log(`DAG (50 tasks): ${formatTime(dagMediumResult.mean)}`);
- console.log(`\nScaling: 10->50 tasks = ${(dagMediumResult.mean / dagSmallResult.mean).toFixed(2)}x`);
- console.log(`Per-task cost (50): ${formatTime(dagMediumResult.mean / 50)}`);
-
- // Print full results
- runner.printResults();
-}
-
-// ============================================================================
-// Task Decomposition Optimization Strategies
-// ============================================================================
-
-export const decompositionOptimizations = {
- /**
- * Cached dependency graph
- */
- cachedDependencyGraph: {
- description: 'Cache computed dependency graphs for reuse',
- expectedImprovement: '5-10x for repeated operations',
- implementation: `
- class CachedTaskGraph {
- private graphCache = new Map<string, TaskGraph>();
-
- getGraph(taskId: string): TaskGraph {
- if (!this.graphCache.has(taskId)) {
- this.graphCache.set(taskId, this.buildGraph(taskId));
- }
- return this.graphCache.get(taskId)!;
- }
- }
- `,
- },
-
- /**
- * Incremental decomposition
- */
- incrementalDecomposition: {
- description: 'Decompose tasks incrementally as needed',
- expectedImprovement: '2-3x for large task sets',
- implementation: `
- class IncrementalDecomposer {
- private decomposed = new Map<string, SubTask[]>();
-
- decomposeOnDemand(task: Task, depth: number): SubTask[] {
- if (depth === 0) return [this.toSubTask(task)];
-
- if (!this.decomposed.has(task.id)) {
- const subtasks = this.decompose(task);
- this.decomposed.set(task.id, subtasks);
- }
-
- return this.decomposed.get(task.id)!.flatMap(
- st => this.decomposeOnDemand(st, depth - 1)
- );
- }
- }
- `,
- },
-
- /**
- * Parallel decomposition processing
- */
- parallelProcessing: {
- description: 'Decompose independent branches in parallel',
- expectedImprovement: '2-4x on multi-core systems',
- implementation: `
- async function parallelDecompose(tasks: Task[]): Promise<SubTask[]> {
- const independentGroups = findIndependentGroups(tasks);
- const results = await Promise.all(
- independentGroups.map(group => decompose(group))
- );
- return results.flat();
- }
- `,
- },
-
- /**
- * Template-based decomposition
- */
- templateDecomposition: {
- description: 'Use pre-defined templates for common task types',
- expectedImprovement: '10x for known task types',
- implementation: `
- const templates = new Map<string, DecompositionTemplate>();
-
- templates.set('feature', {
- phases: ['design', 'implement', 'test', 'document'],
- ratios: [0.1, 0.5, 0.3, 0.1],
- });
-
- function templateDecompose(task: Task): SubTask[] {
- const template = templates.get(task.type);
- if (template) {
- return applyTemplate(task, template);
- }
- return defaultDecompose(task);
- }
- `,
- },
-
- /**
- * Heuristic-based splitting
- */
- heuristicSplitting: {
- description: 'Use heuristics to determine optimal split points',
- expectedImprovement: '20-30% better parallelism',
- implementation: `
- function heuristicSplit(task: Task): number {
- // Based on task complexity, type, and available workers
- const baseChunks = Math.ceil(task.estimatedDuration / 30);
- const maxChunks = Math.min(baseChunks, availableWorkers);
- return Math.max(1, maxChunks);
- }
- `,
- },
-};
-
-// Run if executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
- runTaskDecompositionBenchmarks().catch(console.error);
-}
-
-export default runTaskDecompositionBenchmarks;
diff --git a/v3/benchmarks/tsconfig.json b/v3/benchmarks/tsconfig.json
deleted file mode 100644
index b9c958703c..0000000000
--- a/v3/benchmarks/tsconfig.json
+++ /dev/null
@@ -1,32 +0,0 @@
-{
- "compilerOptions": {
- "target": "ES2022",
- "module": "NodeNext",
- "moduleResolution": "NodeNext",
- "allowSyntheticDefaultImports": true,
- "esModuleInterop": true,
- "strict": true,
- "noImplicitAny": true,
- "strictNullChecks": true,
- "strictFunctionTypes": true,
- "noImplicitReturns": true,
- "noFallthroughCasesInSwitch": true,
- "declaration": true,
- "declarationMap": true,
- "sourceMap": true,
- "outDir": "./dist",
- "rootDir": ".",
- "forceConsistentCasingInFileNames": true,
- "resolveJsonModule": true,
- "isolatedModules": true,
- "lib": ["ES2022"],
- "types": ["node"]
- },
- "include": [
- "./**/*.ts"
- ],
- "exclude": [
- "node_modules",
- "dist"
- ]
-}
diff --git a/v3/cli/commands/agent.ts b/v3/cli/commands/agent.ts
deleted file mode 100644
index 147309286a..0000000000
--- a/v3/cli/commands/agent.ts
+++ /dev/null
@@ -1,541 +0,0 @@
-/**
- * V3 CLI Agent Command
- * Agent management commands for spawning, listing, and controlling agents
- */
-
-import type { Command, CommandContext, CommandResult } from '../types.js';
-import { output } from '../output.js';
-import { select, confirm, input } from '../prompt.js';
-
-// Available agent types with descriptions
-const AGENT_TYPES = [
- { value: 'coder', label: 'Coder', hint: 'Code development with neural patterns' },
- { value: 'researcher', label: 'Researcher', hint: 'Research with web access and data analysis' },
- { value: 'tester', label: 'Tester', hint: 'Comprehensive testing with automation' },
- { value: 'reviewer', label: 'Reviewer', hint: 'Code review with security and quality checks' },
- { value: 'architect', label: 'Architect', hint: 'System design with enterprise patterns' },
- { value: 'coordinator', label: 'Coordinator', hint: 'Multi-agent orchestration and workflow' },
- { value: 'analyst', label: 'Analyst', hint: 'Performance analysis and optimization' },
- { value: 'optimizer', label: 'Optimizer', hint: 'Performance optimization and bottleneck analysis' },
- { value: 'security-architect', label: 'Security Architect', hint: 'Security architecture and threat modeling' },
- { value: 'security-auditor', label: 'Security Auditor', hint: 'CVE remediation and security testing' },
- { value: 'memory-specialist', label: 'Memory Specialist', hint: 'AgentDB unification (150x-12,500x faster)' },
- { value: 'swarm-specialist', label: 'Swarm Specialist', hint: 'Unified coordination engine' },
- { value: 'performance-engineer', label: 'Performance Engineer', hint: '2.49x-7.47x optimization targets' },
- { value: 'core-architect', label: 'Core Architect', hint: 'Domain-driven design restructure' },
- { value: 'test-architect', label: 'Test Architect', hint: 'TDD London School methodology' }
-];
-
-// Agent spawn subcommand
-const spawnCommand: Command = {
- name: 'spawn',
- description: 'Spawn a new agent',
- options: [
- {
- name: 'type',
- short: 't',
- description: 'Agent type to spawn',
- type: 'string',
- choices: AGENT_TYPES.map(a => a.value)
- },
- {
- name: 'name',
- short: 'n',
- description: 'Agent name/identifier',
- type: 'string'
- },
- {
- name: 'provider',
- short: 'p',
- description: 'Provider to use (anthropic, openrouter, ollama)',
- type: 'string',
- default: 'anthropic'
- },
- {
- name: 'model',
- short: 'm',
- description: 'Model to use',
- type: 'string'
- },
- {
- name: 'task',
- description: 'Initial task for the agent',
- type: 'string'
- },
- {
- name: 'timeout',
- description: 'Agent timeout in seconds',
- type: 'number',
- default: 300
- },
- {
- name: 'auto-tools',
- description: 'Enable automatic tool usage',
- type: 'boolean',
- default: true
- }
- ],
- examples: [
- { command: 'claude-flow agent spawn --type coder --name bot-1', description: 'Spawn a coder agent' },
- { command: 'claude-flow agent spawn -t researcher --task "Research React 19"', description: 'Spawn researcher with task' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- let agentType = ctx.flags.type as string;
- let agentName = ctx.flags.name as string;
- const task = ctx.flags.task as string;
-
- // Interactive mode if type not specified
- if (!agentType && ctx.interactive) {
- agentType = await select({
- message: 'Select agent type:',
- options: AGENT_TYPES
- });
- }
-
- if (!agentType) {
- output.printError('Agent type is required. Use --type or -t flag.');
- return { success: false, exitCode: 1 };
- }
-
- // Generate name if not provided
- if (!agentName) {
- agentName = `${agentType}-${Date.now().toString(36)}`;
- }
-
- output.printInfo(`Spawning ${agentType} agent: ${output.highlight(agentName)}`);
-
- // Simulate agent creation
- const agentConfig = {
- id: `agent-${Date.now()}`,
- type: agentType,
- name: agentName,
- provider: ctx.flags.provider || 'anthropic',
- model: ctx.flags.model,
- status: 'initializing',
- createdAt: new Date().toISOString(),
- task: task || null,
- capabilities: getAgentCapabilities(agentType)
- };
-
- output.writeln();
- output.printTable({
- columns: [
- { key: 'property', header: 'Property', width: 15 },
- { key: 'value', header: 'Value', width: 40 }
- ],
- data: [
- { property: 'ID', value: agentConfig.id },
- { property: 'Type', value: agentConfig.type },
- { property: 'Name', value: agentConfig.name },
- { property: 'Provider', value: agentConfig.provider },
- { property: 'Status', value: agentConfig.status },
- { property: 'Capabilities', value: agentConfig.capabilities.join(', ') }
- ]
- });
-
- output.writeln();
- output.printSuccess(`Agent ${agentName} spawned successfully`);
-
- if (ctx.flags.format === 'json') {
- output.printJson(agentConfig);
- }
-
- return { success: true, data: agentConfig };
- }
-};
-
-// Agent list subcommand
-const listCommand: Command = {
- name: 'list',
- aliases: ['ls'],
- description: 'List all active agents',
- options: [
- {
- name: 'all',
- short: 'a',
- description: 'Include inactive agents',
- type: 'boolean',
- default: false
- },
- {
- name: 'type',
- short: 't',
- description: 'Filter by agent type',
- type: 'string'
- },
- {
- name: 'status',
- short: 's',
- description: 'Filter by status',
- type: 'string'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- // Simulated agent data
- const agents = [
- { id: 'agent-001', name: 'coder-main', type: 'coder', status: 'active', tasks: 3, uptime: '2h 15m' },
- { id: 'agent-002', name: 'researcher-1', type: 'researcher', status: 'active', tasks: 1, uptime: '45m' },
- { id: 'agent-003', name: 'tester-qa', type: 'tester', status: 'idle', tasks: 0, uptime: '1h 30m' },
- { id: 'agent-004', name: 'reviewer-sec', type: 'reviewer', status: 'active', tasks: 2, uptime: '3h' }
- ];
-
- // Apply filters
- let filtered = agents;
-
- if (ctx.flags.type) {
- filtered = filtered.filter(a => a.type === ctx.flags.type);
- }
-
- if (ctx.flags.status) {
- filtered = filtered.filter(a => a.status === ctx.flags.status);
- }
-
- if (!ctx.flags.all) {
- filtered = filtered.filter(a => a.status !== 'inactive');
- }
-
- if (ctx.flags.format === 'json') {
- output.printJson(filtered);
- return { success: true, data: filtered };
- }
-
- output.writeln();
- output.writeln(output.bold('Active Agents'));
- output.writeln();
-
- if (filtered.length === 0) {
- output.printInfo('No agents found matching criteria');
- return { success: true, data: [] };
- }
-
- output.printTable({
- columns: [
- { key: 'id', header: 'ID', width: 12 },
- { key: 'name', header: 'Name', width: 15 },
- { key: 'type', header: 'Type', width: 12 },
- { key: 'status', header: 'Status', width: 10, format: formatStatus },
- { key: 'tasks', header: 'Tasks', width: 8, align: 'right' },
- { key: 'uptime', header: 'Uptime', width: 10 }
- ],
- data: filtered
- });
-
- output.writeln();
- output.printInfo(`Total: ${filtered.length} agents`);
-
- return { success: true, data: filtered };
- }
-};
-
-// Agent status subcommand
-const statusCommand: Command = {
- name: 'status',
- description: 'Show detailed status of an agent',
- options: [
- {
- name: 'id',
- description: 'Agent ID',
- type: 'string'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- let agentId = ctx.args[0] || ctx.flags.id as string;
-
- if (!agentId && ctx.interactive) {
- agentId = await input({
- message: 'Enter agent ID:',
- validate: (v) => v.length > 0 || 'Agent ID is required'
- });
- }
-
- if (!agentId) {
- output.printError('Agent ID is required');
- return { success: false, exitCode: 1 };
- }
-
- // Simulated detailed status
- const status = {
- id: agentId,
- name: 'coder-main',
- type: 'coder',
- status: 'active',
- provider: 'anthropic',
- model: 'claude-3-5-sonnet-20241022',
- createdAt: new Date(Date.now() - 3600000).toISOString(),
- lastActivity: new Date().toISOString(),
- metrics: {
- tasksCompleted: 15,
- tokensUsed: 45230,
- avgResponseTime: '1.2s',
- successRate: '98.5%'
- },
- currentTask: {
- id: 'task-123',
- description: 'Implementing user authentication module',
- progress: 65
- },
- memory: {
- contextSize: '12.5 KB',
- storedPatterns: 8,
- cacheHitRate: '87%'
- }
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(status);
- return { success: true, data: status };
- }
-
- output.writeln();
- output.printBox(
- [
- `Type: ${status.type}`,
- `Status: ${formatStatus(status.status)}`,
- `Provider: ${status.provider}`,
- `Model: ${status.model}`,
- `Created: ${status.createdAt}`,
- `Last Activity: ${status.lastActivity}`
- ].join('\n'),
- `Agent: ${status.name} (${status.id})`
- );
-
- output.writeln();
- output.writeln(output.bold('Metrics'));
- output.printTable({
- columns: [
- { key: 'metric', header: 'Metric', width: 20 },
- { key: 'value', header: 'Value', width: 15, align: 'right' }
- ],
- data: [
- { metric: 'Tasks Completed', value: status.metrics.tasksCompleted },
- { metric: 'Tokens Used', value: status.metrics.tokensUsed.toLocaleString() },
- { metric: 'Avg Response Time', value: status.metrics.avgResponseTime },
- { metric: 'Success Rate', value: status.metrics.successRate }
- ]
- });
-
- if (status.currentTask) {
- output.writeln();
- output.writeln(output.bold('Current Task'));
- output.writeln(` ID: ${status.currentTask.id}`);
- output.writeln(` Description: ${status.currentTask.description}`);
- output.writeln(` Progress: ${output.progressBar(status.currentTask.progress, 100, 30)}`);
- }
-
- return { success: true, data: status };
- }
-};
-
-// Agent stop subcommand
-const stopCommand: Command = {
- name: 'stop',
- aliases: ['kill'],
- description: 'Stop a running agent',
- options: [
- {
- name: 'force',
- short: 'f',
- description: 'Force stop without graceful shutdown',
- type: 'boolean',
- default: false
- },
- {
- name: 'timeout',
- description: 'Graceful shutdown timeout in seconds',
- type: 'number',
- default: 30
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const agentId = ctx.args[0];
-
- if (!agentId) {
- output.printError('Agent ID is required');
- return { success: false, exitCode: 1 };
- }
-
- const force = ctx.flags.force as boolean;
-
- if (!force && ctx.interactive) {
- const confirmed = await confirm({
- message: `Are you sure you want to stop agent ${agentId}?`,
- default: false
- });
-
- if (!confirmed) {
- output.printInfo('Operation cancelled');
- return { success: true };
- }
- }
-
- output.printInfo(`Stopping agent ${agentId}...`);
-
- // Simulate stop process
- if (!force) {
- output.writeln(output.dim(' Completing current task...'));
- output.writeln(output.dim(' Saving state...'));
- output.writeln(output.dim(' Releasing resources...'));
- }
-
- output.printSuccess(`Agent ${agentId} stopped successfully`);
-
- return { success: true, data: { id: agentId, stopped: true, force } };
- }
-};
-
-// Agent metrics subcommand
-const metricsCommand: Command = {
- name: 'metrics',
- description: 'Show agent performance metrics',
- options: [
- {
- name: 'period',
- short: 'p',
- description: 'Time period (1h, 24h, 7d, 30d)',
- type: 'string',
- default: '24h'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const agentId = ctx.args[0];
- const period = ctx.flags.period as string;
-
- // Simulated metrics
- const metrics = {
- period,
- summary: {
- totalAgents: 4,
- activeAgents: 3,
- tasksCompleted: 127,
- avgSuccessRate: '96.2%',
- totalTokens: 1234567,
- avgResponseTime: '1.45s'
- },
- byType: [
- { type: 'coder', count: 2, tasks: 45, successRate: '97%' },
- { type: 'researcher', count: 1, tasks: 32, successRate: '95%' },
- { type: 'tester', count: 1, tasks: 50, successRate: '98%' }
- ],
- performance: {
- flashAttention: '2.8x speedup',
- memoryReduction: '52%',
- searchImprovement: '150x faster'
- }
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(metrics);
- return { success: true, data: metrics };
- }
-
- output.writeln();
- output.writeln(output.bold(`Agent Metrics (${period})`));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'metric', header: 'Metric', width: 20 },
- { key: 'value', header: 'Value', width: 15, align: 'right' }
- ],
- data: [
- { metric: 'Total Agents', value: metrics.summary.totalAgents },
- { metric: 'Active Agents', value: metrics.summary.activeAgents },
- { metric: 'Tasks Completed', value: metrics.summary.tasksCompleted },
- { metric: 'Success Rate', value: metrics.summary.avgSuccessRate },
- { metric: 'Total Tokens', value: metrics.summary.totalTokens.toLocaleString() },
- { metric: 'Avg Response Time', value: metrics.summary.avgResponseTime }
- ]
- });
-
- output.writeln();
- output.writeln(output.bold('By Agent Type'));
- output.printTable({
- columns: [
- { key: 'type', header: 'Type', width: 12 },
- { key: 'count', header: 'Count', width: 8, align: 'right' },
- { key: 'tasks', header: 'Tasks', width: 8, align: 'right' },
- { key: 'successRate', header: 'Success', width: 10, align: 'right' }
- ],
- data: metrics.byType
- });
-
- output.writeln();
- output.writeln(output.bold('V3 Performance Gains'));
- output.printList([
- `Flash Attention: ${output.success(metrics.performance.flashAttention)}`,
- `Memory Reduction: ${output.success(metrics.performance.memoryReduction)}`,
- `Search: ${output.success(metrics.performance.searchImprovement)}`
- ]);
-
- return { success: true, data: metrics };
- }
-};
-
-// Main agent command
-export const agentCommand: Command = {
- name: 'agent',
- description: 'Agent management commands',
- subcommands: [spawnCommand, listCommand, statusCommand, stopCommand, metricsCommand],
- options: [],
- examples: [
- { command: 'claude-flow agent spawn -t coder', description: 'Spawn a coder agent' },
- { command: 'claude-flow agent list', description: 'List all agents' },
- { command: 'claude-flow agent status agent-001', description: 'Show agent status' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- // Show help if no subcommand
- output.writeln();
- output.writeln(output.bold('Agent Management Commands'));
- output.writeln();
- output.writeln('Usage: claude-flow agent <subcommand> [options]');
- output.writeln();
- output.writeln('Subcommands:');
- output.printList([
- `${output.highlight('spawn')} - Spawn a new agent`,
- `${output.highlight('list')} - List all active agents`,
- `${output.highlight('status')} - Show detailed agent status`,
- `${output.highlight('stop')} - Stop a running agent`,
- `${output.highlight('metrics')} - Show agent metrics`
- ]);
- output.writeln();
- output.writeln('Run "claude-flow agent <subcommand> --help" for subcommand help');
-
- return { success: true };
- }
-};
-
-// Helper functions
-function getAgentCapabilities(type: string): string[] {
- const capabilities: Record<string, string[]> = {
- coder: ['code-generation', 'refactoring', 'debugging', 'testing'],
- researcher: ['web-search', 'data-analysis', 'summarization', 'citation'],
- tester: ['unit-testing', 'integration-testing', 'coverage-analysis', 'automation'],
- reviewer: ['code-review', 'security-audit', 'quality-check', 'documentation'],
- architect: ['system-design', 'pattern-analysis', 'scalability', 'documentation'],
- coordinator: ['task-orchestration', 'agent-management', 'workflow-control'],
- 'security-architect': ['threat-modeling', 'security-patterns', 'compliance', 'audit'],
- 'memory-specialist': ['vector-search', 'agentdb', 'caching', 'optimization'],
- 'performance-engineer': ['benchmarking', 'profiling', 'optimization', 'monitoring']
- };
-
- return capabilities[type] || ['general'];
-}
-
-function formatStatus(status: unknown): string {
- const statusStr = String(status);
- switch (statusStr) {
- case 'active':
- return output.success(statusStr);
- case 'idle':
- return output.warning(statusStr);
- case 'inactive':
- case 'stopped':
- return output.dim(statusStr);
- case 'error':
- return output.error(statusStr);
- default:
- return statusStr;
- }
-}
-
-export default agentCommand;
diff --git a/v3/cli/commands/config.ts b/v3/cli/commands/config.ts
deleted file mode 100644
index 7a44a922e0..0000000000
--- a/v3/cli/commands/config.ts
+++ /dev/null
@@ -1,451 +0,0 @@
-/**
- * V3 CLI Config Command
- * Configuration management
- */
-
-import type { Command, CommandContext, CommandResult } from '../types.js';
-import { output } from '../output.js';
-import { select, confirm, input } from '../prompt.js';
-
-// Init configuration
-const initCommand: Command = {
- name: 'init',
- description: 'Initialize configuration',
- options: [
- {
- name: 'force',
- short: 'f',
- description: 'Overwrite existing configuration',
- type: 'boolean',
- default: false
- },
- {
- name: 'sparc',
- description: 'Initialize with SPARC methodology',
- type: 'boolean',
- default: false
- },
- {
- name: 'v3',
- description: 'Initialize V3 configuration',
- type: 'boolean',
- default: true
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const sparc = ctx.flags.sparc as boolean;
- const v3 = ctx.flags.v3 as boolean;
-
- output.writeln();
- output.printInfo('Initializing Claude Flow configuration...');
- output.writeln();
-
- // Simulate config creation
- const config = {
- version: '3.0.0',
- v3Mode: v3,
- sparc: sparc,
- agents: {
- defaultType: 'coder',
- maxConcurrent: 15,
- autoSpawn: true,
- timeout: 300
- },
- swarm: {
- topology: 'hybrid',
- maxAgents: 15,
- autoScale: true,
- coordinationStrategy: 'consensus'
- },
- memory: {
- backend: 'hybrid',
- path: './data/memory',
- cacheSize: 256,
- enableHNSW: true
- },
- mcp: {
- transport: 'stdio',
- autoStart: true,
- tools: 'all'
- },
- providers: [
- { name: 'anthropic', priority: 1, enabled: true },
- { name: 'openrouter', priority: 2, enabled: false },
- { name: 'ollama', priority: 3, enabled: false }
- ]
- };
-
- output.writeln(output.dim(' Creating claude-flow.config.json...'));
- output.writeln(output.dim(' Creating .claude-flow/ directory...'));
-
- if (sparc) {
- output.writeln(output.dim(' Initializing SPARC methodology...'));
- output.writeln(output.dim(' Creating SPARC workflow files...'));
- }
-
- if (v3) {
- output.writeln(output.dim(' Enabling V3 15-agent coordination...'));
- output.writeln(output.dim(' Configuring AgentDB integration...'));
- output.writeln(output.dim(' Setting up Flash Attention optimization...'));
- }
-
- output.writeln();
- output.printTable({
- columns: [
- { key: 'setting', header: 'Setting', width: 25 },
- { key: 'value', header: 'Value', width: 30 }
- ],
- data: [
- { setting: 'Version', value: config.version },
- { setting: 'V3 Mode', value: config.v3Mode ? 'Enabled' : 'Disabled' },
- { setting: 'SPARC Mode', value: config.sparc ? 'Enabled' : 'Disabled' },
- { setting: 'Swarm Topology', value: config.swarm.topology },
- { setting: 'Max Agents', value: config.swarm.maxAgents },
- { setting: 'Memory Backend', value: config.memory.backend },
- { setting: 'MCP Transport', value: config.mcp.transport }
- ]
- });
-
- output.writeln();
- output.printSuccess('Configuration initialized');
- output.writeln(output.dim(' Config file: ./claude-flow.config.json'));
-
- return { success: true, data: config };
- }
-};
-
-// Get configuration
-const getCommand: Command = {
- name: 'get',
- description: 'Get configuration value',
- options: [
- {
- name: 'key',
- short: 'k',
- description: 'Configuration key (dot notation)',
- type: 'string'
- }
- ],
- examples: [
- { command: 'claude-flow config get swarm.topology', description: 'Get swarm topology' },
- { command: 'claude-flow config get -k memory.backend', description: 'Get memory backend' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const key = ctx.flags.key as string || ctx.args[0];
-
- // Simulated config values
- const configValues: Record<string, unknown> = {
- 'version': '3.0.0',
- 'v3Mode': true,
- 'swarm.topology': 'hybrid',
- 'swarm.maxAgents': 15,
- 'swarm.autoScale': true,
- 'memory.backend': 'hybrid',
- 'memory.cacheSize': 256,
- 'mcp.transport': 'stdio',
- 'agents.defaultType': 'coder',
- 'agents.maxConcurrent': 15
- };
-
- if (!key) {
- // Show all config
- if (ctx.flags.format === 'json') {
- output.printJson(configValues);
- return { success: true, data: configValues };
- }
-
- output.writeln();
- output.writeln(output.bold('Current Configuration'));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'key', header: 'Key', width: 25 },
- { key: 'value', header: 'Value', width: 30 }
- ],
- data: Object.entries(configValues).map(([k, v]) => ({ key: k, value: String(v) }))
- });
-
- return { success: true, data: configValues };
- }
-
- const value = configValues[key];
-
- if (value === undefined) {
- output.printError(`Configuration key not found: ${key}`);
- return { success: false, exitCode: 1 };
- }
-
- if (ctx.flags.format === 'json') {
- output.printJson({ key, value });
- } else {
- output.writeln(`${key} = ${value}`);
- }
-
- return { success: true, data: { key, value } };
- }
-};
-
-// Set configuration
-const setCommand: Command = {
- name: 'set',
- description: 'Set configuration value',
- options: [
- {
- name: 'key',
- short: 'k',
- description: 'Configuration key',
- type: 'string',
- required: true
- },
- {
- name: 'value',
- short: 'v',
- description: 'Configuration value',
- type: 'string',
- required: true
- }
- ],
- examples: [
- { command: 'claude-flow config set swarm.maxAgents 20', description: 'Set max agents' },
- { command: 'claude-flow config set -k memory.backend -v agentdb', description: 'Set memory backend' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const key = ctx.flags.key as string || ctx.args[0];
- const value = ctx.flags.value as string || ctx.args[1];
-
- if (!key || value === undefined) {
- output.printError('Both key and value are required');
- return { success: false, exitCode: 1 };
- }
-
- output.printInfo(`Setting ${key} = ${value}`);
- output.printSuccess('Configuration updated');
-
- return { success: true, data: { key, value } };
- }
-};
-
-// List providers
-const providersCommand: Command = {
- name: 'providers',
- description: 'Manage AI providers',
- options: [
- {
- name: 'add',
- short: 'a',
- description: 'Add provider',
- type: 'string'
- },
- {
- name: 'remove',
- short: 'r',
- description: 'Remove provider',
- type: 'string'
- },
- {
- name: 'enable',
- description: 'Enable provider',
- type: 'string'
- },
- {
- name: 'disable',
- description: 'Disable provider',
- type: 'string'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const providers = [
- { name: 'anthropic', model: 'claude-3-5-sonnet-20241022', priority: 1, enabled: true, status: 'Active' },
- { name: 'openrouter', model: 'claude-3.5-sonnet', priority: 2, enabled: false, status: 'Disabled' },
- { name: 'ollama', model: 'llama3.2', priority: 3, enabled: false, status: 'Disabled' },
- { name: 'gemini', model: 'gemini-2.0-flash', priority: 4, enabled: false, status: 'Disabled' }
- ];
-
- if (ctx.flags.format === 'json') {
- output.printJson(providers);
- return { success: true, data: providers };
- }
-
- output.writeln();
- output.writeln(output.bold('AI Providers'));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'name', header: 'Provider', width: 12 },
- { key: 'model', header: 'Model', width: 25 },
- { key: 'priority', header: 'Priority', width: 10, align: 'right' },
- { key: 'status', header: 'Status', width: 10, format: (v) => {
- if (v === 'Active') return output.success(String(v));
- return output.dim(String(v));
- }}
- ],
- data: providers
- });
-
- output.writeln();
- output.writeln(output.dim('Use --add, --remove, --enable, --disable to manage providers'));
-
- return { success: true, data: providers };
- }
-};
-
-// Reset configuration
-const resetCommand: Command = {
- name: 'reset',
- description: 'Reset configuration to defaults',
- options: [
- {
- name: 'force',
- short: 'f',
- description: 'Skip confirmation',
- type: 'boolean',
- default: false
- },
- {
- name: 'section',
- description: 'Reset specific section only',
- type: 'string',
- choices: ['agents', 'swarm', 'memory', 'mcp', 'providers', 'all']
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const force = ctx.flags.force as boolean;
- const section = ctx.flags.section as string || 'all';
-
- if (!force && ctx.interactive) {
- const confirmed = await confirm({
- message: `Reset ${section} configuration to defaults?`,
- default: false
- });
-
- if (!confirmed) {
- output.printInfo('Operation cancelled');
- return { success: true };
- }
- }
-
- output.printInfo(`Resetting ${section} configuration...`);
- output.printSuccess('Configuration reset to defaults');
-
- return { success: true, data: { section, reset: true } };
- }
-};
-
-// Export configuration
-const exportCommand: Command = {
- name: 'export',
- description: 'Export configuration',
- options: [
- {
- name: 'output',
- short: 'o',
- description: 'Output file path',
- type: 'string'
- },
- {
- name: 'format',
- short: 'f',
- description: 'Export format (json, yaml)',
- type: 'string',
- default: 'json',
- choices: ['json', 'yaml']
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const outputPath = ctx.flags.output as string || './claude-flow.config.export.json';
-
- const config = {
- version: '3.0.0',
- exportedAt: new Date().toISOString(),
- agents: { defaultType: 'coder', maxConcurrent: 15 },
- swarm: { topology: 'hybrid', maxAgents: 15 },
- memory: { backend: 'hybrid', cacheSize: 256 },
- mcp: { transport: 'stdio', tools: 'all' }
- };
-
- output.printInfo(`Exporting configuration to ${outputPath}...`);
- output.printJson(config);
- output.writeln();
- output.printSuccess('Configuration exported');
-
- return { success: true, data: { path: outputPath, config } };
- }
-};
-
-// Import configuration
-const importCommand: Command = {
- name: 'import',
- description: 'Import configuration',
- options: [
- {
- name: 'file',
- short: 'f',
- description: 'Configuration file path',
- type: 'string',
- required: true
- },
- {
- name: 'merge',
- description: 'Merge with existing configuration',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const file = ctx.flags.file as string || ctx.args[0];
- const merge = ctx.flags.merge as boolean;
-
- if (!file) {
- output.printError('File path is required');
- return { success: false, exitCode: 1 };
- }
-
- output.printInfo(`Importing configuration from ${file}...`);
-
- if (merge) {
- output.writeln(output.dim(' Merging with existing configuration...'));
- } else {
- output.writeln(output.dim(' Replacing existing configuration...'));
- }
-
- output.printSuccess('Configuration imported');
-
- return { success: true, data: { file, merge, imported: true } };
- }
-};
-
-// Main config command
-export const configCommand: Command = {
- name: 'config',
- description: 'Configuration management',
- subcommands: [initCommand, getCommand, setCommand, providersCommand, resetCommand, exportCommand, importCommand],
- options: [],
- examples: [
- { command: 'claude-flow config init --v3', description: 'Initialize V3 config' },
- { command: 'claude-flow config get swarm.topology', description: 'Get config value' },
- { command: 'claude-flow config set swarm.maxAgents 20', description: 'Set config value' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- output.writeln();
- output.writeln(output.bold('Configuration Management'));
- output.writeln();
- output.writeln('Usage: claude-flow config <subcommand> [options]');
- output.writeln();
- output.writeln('Subcommands:');
- output.printList([
- `${output.highlight('init')} - Initialize configuration`,
- `${output.highlight('get')} - Get configuration value`,
- `${output.highlight('set')} - Set configuration value`,
- `${output.highlight('providers')} - Manage AI providers`,
- `${output.highlight('reset')} - Reset to defaults`,
- `${output.highlight('export')} - Export configuration`,
- `${output.highlight('import')} - Import configuration`
- ]);
-
- return { success: true };
- }
-};
-
-export default configCommand;
diff --git a/v3/cli/commands/index.ts b/v3/cli/commands/index.ts
deleted file mode 100644
index 8cdf8b367b..0000000000
--- a/v3/cli/commands/index.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-/**
- * V3 CLI Commands Index
- * Central registry for all CLI commands
- */
-
-import type { Command } from '../types.js';
-import { agentCommand } from './agent.js';
-import { swarmCommand } from './swarm.js';
-import { memoryCommand } from './memory.js';
-import { mcpCommand } from './mcp.js';
-import { configCommand } from './config.js';
-import { migrateCommand } from './migrate.js';
-
-// Export all commands
-export { agentCommand } from './agent.js';
-export { swarmCommand } from './swarm.js';
-export { memoryCommand } from './memory.js';
-export { mcpCommand } from './mcp.js';
-export { configCommand } from './config.js';
-export { migrateCommand } from './migrate.js';
-
-/**
- * All available commands
- */
-export const commands: Command[] = [
- agentCommand,
- swarmCommand,
- memoryCommand,
- mcpCommand,
- configCommand,
- migrateCommand
-];
-
-/**
- * Command registry map for quick lookup
- */
-export const commandRegistry = new Map<string, Command>();
-
-// Register all commands and their aliases
-for (const cmd of commands) {
- commandRegistry.set(cmd.name, cmd);
- if (cmd.aliases) {
- for (const alias of cmd.aliases) {
- commandRegistry.set(alias, cmd);
- }
- }
-}
-
-/**
- * Get command by name
- */
-export function getCommand(name: string): Command | undefined {
- return commandRegistry.get(name);
-}
-
-/**
- * Check if command exists
- */
-export function hasCommand(name: string): boolean {
- return commandRegistry.has(name);
-}
-
-/**
- * Get all command names (including aliases)
- */
-export function getCommandNames(): string[] {
- return Array.from(commandRegistry.keys());
-}
-
-/**
- * Get all unique commands (excluding aliases)
- */
-export function getUniqueCommands(): Command[] {
- return commands.filter(cmd => !cmd.hidden);
-}
-
-/**
- * Setup commands in a CLI instance
- */
-export function setupCommands(cli: { command: (cmd: Command) => void }): void {
- for (const cmd of commands) {
- cli.command(cmd);
- }
-}
diff --git a/v3/cli/commands/mcp.ts b/v3/cli/commands/mcp.ts
deleted file mode 100644
index d0bbe18c4f..0000000000
--- a/v3/cli/commands/mcp.ts
+++ /dev/null
@@ -1,533 +0,0 @@
-/**
- * V3 CLI MCP Command
- * MCP server control and management
- */
-
-import type { Command, CommandContext, CommandResult } from '../types.js';
-import { output } from '../output.js';
-import { select, confirm } from '../prompt.js';
-
-// MCP tools categories
-const TOOL_CATEGORIES = [
- { value: 'coordination', label: 'Coordination', hint: 'Swarm and agent coordination tools' },
- { value: 'monitoring', label: 'Monitoring', hint: 'Status and metrics monitoring' },
- { value: 'memory', label: 'Memory', hint: 'Memory and neural features' },
- { value: 'github', label: 'GitHub', hint: 'GitHub integration tools' },
- { value: 'system', label: 'System', hint: 'System and benchmark tools' }
-];
-
-// Start MCP server
-const startCommand: Command = {
- name: 'start',
- description: 'Start MCP server',
- options: [
- {
- name: 'port',
- short: 'p',
- description: 'Server port',
- type: 'number',
- default: 3000
- },
- {
- name: 'host',
- short: 'h',
- description: 'Server host',
- type: 'string',
- default: 'localhost'
- },
- {
- name: 'transport',
- short: 't',
- description: 'Transport type (stdio, http, websocket)',
- type: 'string',
- default: 'stdio',
- choices: ['stdio', 'http', 'websocket']
- },
- {
- name: 'tools',
- description: 'Tools to enable (comma-separated or "all")',
- type: 'string',
- default: 'all'
- }
- ],
- examples: [
- { command: 'claude-flow mcp start', description: 'Start with defaults (stdio)' },
- { command: 'claude-flow mcp start -p 8080 -t http', description: 'Start HTTP server' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const port = ctx.flags.port as number;
- const host = ctx.flags.host as string;
- const transport = ctx.flags.transport as string;
- const tools = ctx.flags.tools as string;
-
- output.writeln();
- output.printInfo('Starting MCP Server...');
- output.writeln();
-
- const serverConfig = {
- id: `mcp-${Date.now().toString(36)}`,
- transport,
- host,
- port,
- status: 'starting',
- tools: tools === 'all' ? 27 : tools.split(',').length,
- startedAt: new Date().toISOString()
- };
-
- // Simulate startup
- output.writeln(output.dim(' Loading tool registry...'));
- output.writeln(output.dim(' Initializing transport layer...'));
- output.writeln(output.dim(' Registering 27 MCP tools...'));
- output.writeln(output.dim(' Setting up handlers...'));
-
- output.writeln();
- output.printTable({
- columns: [
- { key: 'property', header: 'Property', width: 15 },
- { key: 'value', header: 'Value', width: 30 }
- ],
- data: [
- { property: 'Server ID', value: serverConfig.id },
- { property: 'Transport', value: transport },
- { property: 'Host', value: host },
- { property: 'Port', value: port },
- { property: 'Tools', value: `${serverConfig.tools} enabled` },
- { property: 'Status', value: output.success('Running') }
- ]
- });
-
- output.writeln();
- output.printSuccess('MCP Server started');
-
- if (transport === 'http') {
- output.writeln(output.dim(` Endpoint: http://${host}:${port}`));
- } else if (transport === 'websocket') {
- output.writeln(output.dim(` Endpoint: ws://${host}:${port}`));
- }
-
- return { success: true, data: serverConfig };
- }
-};
-
-// Stop MCP server
-const stopCommand: Command = {
- name: 'stop',
- description: 'Stop MCP server',
- options: [
- {
- name: 'force',
- short: 'f',
- description: 'Force stop without graceful shutdown',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const force = ctx.flags.force as boolean;
-
- if (!force && ctx.interactive) {
- const confirmed = await confirm({
- message: 'Stop MCP server?',
- default: false
- });
-
- if (!confirmed) {
- output.printInfo('Operation cancelled');
- return { success: true };
- }
- }
-
- output.printInfo('Stopping MCP Server...');
-
- if (!force) {
- output.writeln(output.dim(' Completing pending requests...'));
- output.writeln(output.dim(' Closing connections...'));
- output.writeln(output.dim(' Releasing resources...'));
- }
-
- output.printSuccess('MCP Server stopped');
-
- return { success: true, data: { stopped: true, force } };
- }
-};
-
-// MCP status
-const statusCommand: Command = {
- name: 'status',
- description: 'Show MCP server status',
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const status = {
- running: true,
- transport: 'stdio',
- uptime: '2h 45m',
- tools: {
- total: 27,
- enabled: 27,
- used: 15
- },
- requests: {
- total: 1234,
- successful: 1220,
- failed: 14,
- avgLatency: '8.5ms'
- },
- connections: {
- active: 3,
- total: 45
- },
- memory: {
- used: '45 MB',
- peak: '78 MB'
- }
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(status);
- return { success: true, data: status };
- }
-
- output.writeln();
- output.writeln(output.bold('MCP Server Status'));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'metric', header: 'Metric', width: 20 },
- { key: 'value', header: 'Value', width: 20, align: 'right' }
- ],
- data: [
- { metric: 'Status', value: status.running ? output.success('Running') : output.error('Stopped') },
- { metric: 'Transport', value: status.transport },
- { metric: 'Uptime', value: status.uptime },
- { metric: 'Active Connections', value: status.connections.active },
- { metric: 'Total Requests', value: status.requests.total.toLocaleString() },
- { metric: 'Success Rate', value: `${((status.requests.successful / status.requests.total) * 100).toFixed(1)}%` },
- { metric: 'Avg Latency', value: status.requests.avgLatency },
- { metric: 'Memory Used', value: status.memory.used }
- ]
- });
-
- output.writeln();
- output.writeln(output.bold('Tools'));
- output.writeln(` Total: ${status.tools.total} | Enabled: ${status.tools.enabled} | Used: ${status.tools.used}`);
-
- return { success: true, data: status };
- }
-};
-
-// List tools
-const toolsCommand: Command = {
- name: 'tools',
- description: 'List available MCP tools',
- options: [
- {
- name: 'category',
- short: 'c',
- description: 'Filter by category',
- type: 'string',
- choices: TOOL_CATEGORIES.map(c => c.value)
- },
- {
- name: 'enabled',
- description: 'Show only enabled tools',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const category = ctx.flags.category as string;
-
- // All 27 MCP tools
- const tools = [
- // Coordination
- { name: 'swarm_init', category: 'coordination', description: 'Initialize swarm topology', enabled: true },
- { name: 'agent_spawn', category: 'coordination', description: 'Spawn agent for coordination', enabled: true },
- { name: 'task_orchestrate', category: 'coordination', description: 'Orchestrate task workflows', enabled: true },
- { name: 'swarm_scale', category: 'coordination', description: 'Scale swarm size', enabled: true },
- { name: 'agent_coordinate', category: 'coordination', description: 'Coordinate agents', enabled: true },
-
- // Monitoring
- { name: 'swarm_status', category: 'monitoring', description: 'Get swarm status', enabled: true },
- { name: 'agent_list', category: 'monitoring', description: 'List agents', enabled: true },
- { name: 'agent_metrics', category: 'monitoring', description: 'Get agent metrics', enabled: true },
- { name: 'task_status', category: 'monitoring', description: 'Get task status', enabled: true },
- { name: 'task_results', category: 'monitoring', description: 'Get task results', enabled: true },
- { name: 'swarm_monitor', category: 'monitoring', description: 'Real-time monitoring', enabled: true },
-
- // Memory & Neural
- { name: 'memory_store', category: 'memory', description: 'Store in memory', enabled: true },
- { name: 'memory_retrieve', category: 'memory', description: 'Retrieve from memory', enabled: true },
- { name: 'memory_search', category: 'memory', description: 'Search memory', enabled: true },
- { name: 'memory_usage', category: 'memory', description: 'Memory usage stats', enabled: true },
- { name: 'neural_status', category: 'memory', description: 'Neural system status', enabled: true },
- { name: 'neural_train', category: 'memory', description: 'Train neural patterns', enabled: true },
- { name: 'neural_patterns', category: 'memory', description: 'List patterns', enabled: true },
-
- // GitHub
- { name: 'github_swarm', category: 'github', description: 'GitHub swarm coordination', enabled: true },
- { name: 'repo_analyze', category: 'github', description: 'Analyze repository', enabled: true },
- { name: 'pr_enhance', category: 'github', description: 'Enhance pull request', enabled: true },
- { name: 'issue_triage', category: 'github', description: 'Triage issues', enabled: true },
- { name: 'code_review', category: 'github', description: 'Code review', enabled: true },
-
- // System
- { name: 'benchmark_run', category: 'system', description: 'Run benchmarks', enabled: true },
- { name: 'features_detect', category: 'system', description: 'Detect features', enabled: true },
- { name: 'config_get', category: 'system', description: 'Get configuration', enabled: true },
- { name: 'config_set', category: 'system', description: 'Set configuration', enabled: true }
- ].filter(t => !category || t.category === category);
-
- if (ctx.flags.format === 'json') {
- output.printJson(tools);
- return { success: true, data: tools };
- }
-
- output.writeln();
- output.writeln(output.bold('Available MCP Tools'));
- output.writeln();
-
- // Group by category
- const grouped = tools.reduce((acc, tool) => {
- if (!acc[tool.category]) acc[tool.category] = [];
- acc[tool.category].push(tool);
- return acc;
- }, {} as Record<string, typeof tools>);
-
- for (const [cat, catTools] of Object.entries(grouped)) {
- output.writeln(output.highlight(cat.charAt(0).toUpperCase() + cat.slice(1)));
-
- output.printTable({
- columns: [
- { key: 'name', header: 'Tool', width: 20 },
- { key: 'description', header: 'Description', width: 35 },
- { key: 'enabled', header: 'Status', width: 10, format: (v) => v ? output.success('Enabled') : output.dim('Disabled') }
- ],
- data: catTools,
- border: false
- });
-
- output.writeln();
- }
-
- output.printInfo(`Total: ${tools.length} tools`);
-
- return { success: true, data: tools };
- }
-};
-
-// Enable/disable tools
-const toggleCommand: Command = {
- name: 'toggle',
- description: 'Enable or disable MCP tools',
- options: [
- {
- name: 'enable',
- short: 'e',
- description: 'Enable tools',
- type: 'string'
- },
- {
- name: 'disable',
- short: 'd',
- description: 'Disable tools',
- type: 'string'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const toEnable = ctx.flags.enable as string;
- const toDisable = ctx.flags.disable as string;
-
- if (toEnable) {
- const tools = toEnable.split(',');
- output.printInfo(`Enabling tools: ${tools.join(', ')}`);
- output.printSuccess(`Enabled ${tools.length} tools`);
- }
-
- if (toDisable) {
- const tools = toDisable.split(',');
- output.printInfo(`Disabling tools: ${tools.join(', ')}`);
- output.printSuccess(`Disabled ${tools.length} tools`);
- }
-
- if (!toEnable && !toDisable) {
- output.printError('Use --enable or --disable with comma-separated tool names');
- return { success: false, exitCode: 1 };
- }
-
- return { success: true };
- }
-};
-
-// Execute tool
-const execCommand: Command = {
- name: 'exec',
- description: 'Execute an MCP tool',
- options: [
- {
- name: 'tool',
- short: 't',
- description: 'Tool name',
- type: 'string',
- required: true
- },
- {
- name: 'params',
- short: 'p',
- description: 'Tool parameters (JSON)',
- type: 'string'
- }
- ],
- examples: [
- { command: 'claude-flow mcp exec -t swarm_init -p \'{"topology":"mesh"}\'', description: 'Execute tool' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const tool = ctx.flags.tool as string || ctx.args[0];
- const paramsStr = ctx.flags.params as string;
-
- if (!tool) {
- output.printError('Tool name is required. Use --tool or -t');
- return { success: false, exitCode: 1 };
- }
-
- let params = {};
- if (paramsStr) {
- try {
- params = JSON.parse(paramsStr);
- } catch (e) {
- output.printError('Invalid JSON parameters');
- return { success: false, exitCode: 1 };
- }
- }
-
- output.printInfo(`Executing tool: ${tool}`);
-
- if (Object.keys(params).length > 0) {
- output.writeln(output.dim(` Parameters: ${JSON.stringify(params)}`));
- }
-
- // Simulate tool execution
- const result = {
- tool,
- params,
- success: true,
- duration: `${Math.random() * 50 + 5 | 0}ms`,
- result: {
- message: `Tool ${tool} executed successfully`,
- data: { /* simulated result */ }
- }
- };
-
- output.writeln();
- output.printSuccess(`Tool executed in ${result.duration}`);
-
- if (ctx.flags.format === 'json') {
- output.printJson(result);
- }
-
- return { success: true, data: result };
- }
-};
-
-// Logs command
-const logsCommand: Command = {
- name: 'logs',
- description: 'Show MCP server logs',
- options: [
- {
- name: 'lines',
- short: 'n',
- description: 'Number of lines',
- type: 'number',
- default: 20
- },
- {
- name: 'follow',
- short: 'f',
- description: 'Follow log output',
- type: 'boolean',
- default: false
- },
- {
- name: 'level',
- description: 'Filter by log level',
- type: 'string',
- choices: ['debug', 'info', 'warn', 'error']
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const lines = ctx.flags.lines as number;
-
- // Simulated logs
- const logs = [
- { time: '10:45:23', level: 'info', message: 'MCP Server started on stdio' },
- { time: '10:45:24', level: 'info', message: 'Registered 27 tools' },
- { time: '10:46:01', level: 'debug', message: 'Received request: swarm_init' },
- { time: '10:46:01', level: 'info', message: 'Swarm initialized: hierarchical' },
- { time: '10:47:15', level: 'debug', message: 'Received request: agent_spawn' },
- { time: '10:47:16', level: 'info', message: 'Agent spawned: coder-1' },
- { time: '10:48:30', level: 'warn', message: 'Memory usage high: 75%' },
- { time: '10:49:00', level: 'debug', message: 'Received request: memory_store' },
- { time: '10:49:01', level: 'info', message: 'Memory stored: patterns/auth' },
- { time: '10:50:00', level: 'info', message: 'Heartbeat: 3 active connections' }
- ].slice(-lines);
-
- output.writeln();
- output.writeln(output.bold('MCP Server Logs'));
- output.writeln();
-
- for (const log of logs) {
- let levelStr: string;
- switch (log.level) {
- case 'error':
- levelStr = output.error(log.level.toUpperCase().padEnd(5));
- break;
- case 'warn':
- levelStr = output.warning(log.level.toUpperCase().padEnd(5));
- break;
- case 'debug':
- levelStr = output.dim(log.level.toUpperCase().padEnd(5));
- break;
- default:
- levelStr = output.info(log.level.toUpperCase().padEnd(5));
- }
-
- output.writeln(`${output.dim(log.time)} ${levelStr} ${log.message}`);
- }
-
- return { success: true, data: logs };
- }
-};
-
-// Main MCP command
-export const mcpCommand: Command = {
- name: 'mcp',
- description: 'MCP server management',
- subcommands: [startCommand, stopCommand, statusCommand, toolsCommand, toggleCommand, execCommand, logsCommand],
- options: [],
- examples: [
- { command: 'claude-flow mcp start', description: 'Start MCP server' },
- { command: 'claude-flow mcp tools', description: 'List tools' },
- { command: 'claude-flow mcp status', description: 'Show status' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- output.writeln();
- output.writeln(output.bold('MCP Server Management'));
- output.writeln();
- output.writeln('Usage: claude-flow mcp <subcommand> [options]');
- output.writeln();
- output.writeln('Subcommands:');
- output.printList([
- `${output.highlight('start')} - Start MCP server`,
- `${output.highlight('stop')} - Stop MCP server`,
- `${output.highlight('status')} - Show server status`,
- `${output.highlight('tools')} - List available tools`,
- `${output.highlight('toggle')} - Enable/disable tools`,
- `${output.highlight('exec')} - Execute a tool`,
- `${output.highlight('logs')} - Show server logs`
- ]);
-
- return { success: true };
- }
-};
-
-export default mcpCommand;
diff --git a/v3/cli/commands/memory.ts b/v3/cli/commands/memory.ts
deleted file mode 100644
index 5f67e726fc..0000000000
--- a/v3/cli/commands/memory.ts
+++ /dev/null
@@ -1,600 +0,0 @@
-/**
- * V3 CLI Memory Command
- * Memory operations for AgentDB integration
- */
-
-import type { Command, CommandContext, CommandResult } from '../types.js';
-import { output } from '../output.js';
-import { select, confirm, input } from '../prompt.js';
-
-// Memory backends
-const BACKENDS = [
- { value: 'agentdb', label: 'AgentDB', hint: 'Vector database with HNSW indexing (150x-12,500x faster)' },
- { value: 'sqlite', label: 'SQLite', hint: 'Lightweight local storage' },
- { value: 'hybrid', label: 'Hybrid', hint: 'SQLite + AgentDB (recommended)' },
- { value: 'memory', label: 'In-Memory', hint: 'Fast but non-persistent' }
-];
-
-// Store command
-const storeCommand: Command = {
- name: 'store',
- description: 'Store data in memory',
- options: [
- {
- name: 'key',
- short: 'k',
- description: 'Storage key/namespace',
- type: 'string',
- required: true
- },
- {
- name: 'value',
- short: 'v',
- description: 'Value to store',
- type: 'string'
- },
- {
- name: 'namespace',
- short: 'n',
- description: 'Memory namespace',
- type: 'string',
- default: 'default'
- },
- {
- name: 'ttl',
- description: 'Time to live in seconds',
- type: 'number'
- },
- {
- name: 'tags',
- description: 'Comma-separated tags',
- type: 'string'
- },
- {
- name: 'vector',
- description: 'Store as vector embedding',
- type: 'boolean',
- default: false
- }
- ],
- examples: [
- { command: 'claude-flow memory store -k "api/auth" -v "JWT implementation"', description: 'Store text' },
- { command: 'claude-flow memory store -k "pattern/singleton" --vector', description: 'Store vector' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const key = ctx.flags.key as string;
- let value = ctx.flags.value as string || ctx.args[0];
- const namespace = ctx.flags.namespace as string;
- const ttl = ctx.flags.ttl as number;
- const tags = ctx.flags.tags ? (ctx.flags.tags as string).split(',') : [];
- const asVector = ctx.flags.vector as boolean;
-
- if (!key) {
- output.printError('Key is required. Use --key or -k');
- return { success: false, exitCode: 1 };
- }
-
- if (!value && ctx.interactive) {
- value = await input({
- message: 'Enter value to store:',
- validate: (v) => v.length > 0 || 'Value is required'
- });
- }
-
- if (!value) {
- output.printError('Value is required. Use --value or -v');
- return { success: false, exitCode: 1 };
- }
-
- const storeData = {
- key,
- namespace,
- value,
- ttl,
- tags,
- asVector,
- storedAt: new Date().toISOString(),
- size: Buffer.byteLength(value, 'utf8')
- };
-
- output.printInfo(`Storing in ${namespace}/${key}...`);
-
- if (asVector) {
- output.writeln(output.dim(' Generating embedding vector...'));
- output.writeln(output.dim(' Indexing with HNSW (M=16, ef=200)...'));
- }
-
- output.writeln();
- output.printTable({
- columns: [
- { key: 'property', header: 'Property', width: 15 },
- { key: 'val', header: 'Value', width: 40 }
- ],
- data: [
- { property: 'Key', val: key },
- { property: 'Namespace', val: namespace },
- { property: 'Size', val: `${storeData.size} bytes` },
- { property: 'TTL', val: ttl ? `${ttl}s` : 'None' },
- { property: 'Tags', val: tags.length > 0 ? tags.join(', ') : 'None' },
- { property: 'Vector', val: asVector ? 'Yes' : 'No' }
- ]
- });
-
- output.writeln();
- output.printSuccess('Data stored successfully');
-
- return { success: true, data: storeData };
- }
-};
-
-// Retrieve command
-const retrieveCommand: Command = {
- name: 'retrieve',
- aliases: ['get'],
- description: 'Retrieve data from memory',
- options: [
- {
- name: 'key',
- short: 'k',
- description: 'Storage key',
- type: 'string'
- },
- {
- name: 'namespace',
- short: 'n',
- description: 'Memory namespace',
- type: 'string',
- default: 'default'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const key = ctx.flags.key as string || ctx.args[0];
- const namespace = ctx.flags.namespace as string;
-
- if (!key) {
- output.printError('Key is required');
- return { success: false, exitCode: 1 };
- }
-
- // Simulated retrieval
- const data = {
- key,
- namespace,
- value: 'JWT implementation with refresh tokens and secure storage',
- metadata: {
- storedAt: '2024-01-04T10:30:00Z',
- accessCount: 15,
- lastAccessed: new Date().toISOString(),
- size: 56,
- tags: ['auth', 'security', 'api']
- }
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(data);
- return { success: true, data };
- }
-
- output.writeln();
- output.printBox(
- [
- `Namespace: ${data.namespace}`,
- `Key: ${data.key}`,
- `Size: ${data.metadata.size} bytes`,
- `Access Count: ${data.metadata.accessCount}`,
- `Tags: ${data.metadata.tags.join(', ')}`,
- '',
- output.bold('Value:'),
- data.value
- ].join('\n'),
- 'Memory Entry'
- );
-
- return { success: true, data };
- }
-};
-
-// Search command
-const searchCommand: Command = {
- name: 'search',
- description: 'Search memory with semantic/vector search',
- options: [
- {
- name: 'query',
- short: 'q',
- description: 'Search query',
- type: 'string',
- required: true
- },
- {
- name: 'namespace',
- short: 'n',
- description: 'Memory namespace',
- type: 'string'
- },
- {
- name: 'limit',
- short: 'l',
- description: 'Maximum results',
- type: 'number',
- default: 10
- },
- {
- name: 'threshold',
- description: 'Similarity threshold (0-1)',
- type: 'number',
- default: 0.7
- },
- {
- name: 'type',
- short: 't',
- description: 'Search type (semantic, keyword, hybrid)',
- type: 'string',
- default: 'semantic',
- choices: ['semantic', 'keyword', 'hybrid']
- }
- ],
- examples: [
- { command: 'claude-flow memory search -q "authentication patterns"', description: 'Semantic search' },
- { command: 'claude-flow memory search -q "JWT" -t keyword', description: 'Keyword search' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const query = ctx.flags.query as string || ctx.args[0];
- const namespace = ctx.flags.namespace as string;
- const limit = ctx.flags.limit as number;
- const threshold = ctx.flags.threshold as number;
- const searchType = ctx.flags.type as string;
-
- if (!query) {
- output.printError('Query is required. Use --query or -q');
- return { success: false, exitCode: 1 };
- }
-
- output.printInfo(`Searching: "${query}" (${searchType})`);
- output.writeln();
-
- // Simulated search results
- const results = [
- { key: 'auth/jwt-impl', score: 0.95, namespace: 'patterns', preview: 'JWT implementation with RS256...' },
- { key: 'auth/session', score: 0.88, namespace: 'patterns', preview: 'Session-based auth with Redis...' },
- { key: 'security/tokens', score: 0.82, namespace: 'security', preview: 'Token management strategies...' },
- { key: 'api/middleware', score: 0.76, namespace: 'code', preview: 'Auth middleware implementation...' }
- ].filter(r => r.score >= threshold).slice(0, limit);
-
- if (ctx.flags.format === 'json') {
- output.printJson({ query, searchType, results });
- return { success: true, data: results };
- }
-
- // Performance stats
- output.writeln(output.dim(` HNSW search: ${Math.random() * 2 + 0.5 | 0}.${Math.random() * 100 | 0}ms (150x faster than linear)`));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'key', header: 'Key', width: 20 },
- { key: 'score', header: 'Score', width: 8, align: 'right', format: (v) => Number(v).toFixed(2) },
- { key: 'namespace', header: 'Namespace', width: 12 },
- { key: 'preview', header: 'Preview', width: 35 }
- ],
- data: results
- });
-
- output.writeln();
- output.printInfo(`Found ${results.length} results`);
-
- return { success: true, data: results };
- }
-};
-
-// List command
-const listCommand: Command = {
- name: 'list',
- aliases: ['ls'],
- description: 'List memory entries',
- options: [
- {
- name: 'namespace',
- short: 'n',
- description: 'Filter by namespace',
- type: 'string'
- },
- {
- name: 'tags',
- short: 't',
- description: 'Filter by tags (comma-separated)',
- type: 'string'
- },
- {
- name: 'limit',
- short: 'l',
- description: 'Maximum entries',
- type: 'number',
- default: 20
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const namespace = ctx.flags.namespace as string;
- const limit = ctx.flags.limit as number;
-
- // Simulated entries
- const entries = [
- { key: 'auth/jwt-impl', namespace: 'patterns', size: '2.1 KB', tags: ['auth'], updated: '2h ago' },
- { key: 'auth/session', namespace: 'patterns', size: '1.4 KB', tags: ['auth'], updated: '3h ago' },
- { key: 'api/routes', namespace: 'code', size: '856 B', tags: ['api'], updated: '1d ago' },
- { key: 'db/schema', namespace: 'code', size: '3.2 KB', tags: ['db'], updated: '2d ago' },
- { key: 'patterns/singleton', namespace: 'patterns', size: '512 B', tags: ['design'], updated: '5d ago' }
- ].filter(e => !namespace || e.namespace === namespace).slice(0, limit);
-
- if (ctx.flags.format === 'json') {
- output.printJson(entries);
- return { success: true, data: entries };
- }
-
- output.writeln();
- output.writeln(output.bold('Memory Entries'));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'key', header: 'Key', width: 25 },
- { key: 'namespace', header: 'Namespace', width: 12 },
- { key: 'size', header: 'Size', width: 10, align: 'right' },
- { key: 'tags', header: 'Tags', width: 12 },
- { key: 'updated', header: 'Updated', width: 10 }
- ],
- data: entries
- });
-
- output.writeln();
- output.printInfo(`Showing ${entries.length} entries`);
-
- return { success: true, data: entries };
- }
-};
-
-// Delete command
-const deleteCommand: Command = {
- name: 'delete',
- aliases: ['rm'],
- description: 'Delete memory entry',
- options: [
- {
- name: 'force',
- short: 'f',
- description: 'Skip confirmation',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const key = ctx.args[0];
- const force = ctx.flags.force as boolean;
-
- if (!key) {
- output.printError('Key is required');
- return { success: false, exitCode: 1 };
- }
-
- if (!force && ctx.interactive) {
- const confirmed = await confirm({
- message: `Delete memory entry "${key}"?`,
- default: false
- });
-
- if (!confirmed) {
- output.printInfo('Operation cancelled');
- return { success: true };
- }
- }
-
- output.printInfo(`Deleting ${key}...`);
- output.printSuccess(`Deleted ${key}`);
-
- return { success: true, data: { key, deleted: true } };
- }
-};
-
-// Stats command
-const statsCommand: Command = {
- name: 'stats',
- description: 'Show memory statistics',
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const stats = {
- backend: 'hybrid',
- entries: {
- total: 1234,
- vectors: 567,
- text: 667
- },
- storage: {
- total: '45.6 MB',
- vectors: '32.1 MB',
- metadata: '13.5 MB'
- },
- performance: {
- avgSearchTime: '1.2ms',
- hnswIndexSize: '28.4 MB',
- cacheHitRate: '87.3%',
- vectorDimension: 1536
- },
- namespaces: [
- { name: 'patterns', entries: 234, size: '8.2 MB' },
- { name: 'code', entries: 456, size: '15.4 MB' },
- { name: 'security', entries: 123, size: '4.1 MB' },
- { name: 'default', entries: 421, size: '17.9 MB' }
- ]
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(stats);
- return { success: true, data: stats };
- }
-
- output.writeln();
- output.writeln(output.bold('Memory Statistics'));
- output.writeln();
-
- output.writeln(output.bold('Overview'));
- output.printTable({
- columns: [
- { key: 'metric', header: 'Metric', width: 20 },
- { key: 'value', header: 'Value', width: 15, align: 'right' }
- ],
- data: [
- { metric: 'Backend', value: stats.backend },
- { metric: 'Total Entries', value: stats.entries.total.toLocaleString() },
- { metric: 'Vector Entries', value: stats.entries.vectors.toLocaleString() },
- { metric: 'Text Entries', value: stats.entries.text.toLocaleString() },
- { metric: 'Total Storage', value: stats.storage.total }
- ]
- });
-
- output.writeln();
- output.writeln(output.bold('Performance (AgentDB)'));
- output.printTable({
- columns: [
- { key: 'metric', header: 'Metric', width: 20 },
- { key: 'value', header: 'Value', width: 15, align: 'right' }
- ],
- data: [
- { metric: 'Avg Search Time', value: stats.performance.avgSearchTime },
- { metric: 'HNSW Index Size', value: stats.performance.hnswIndexSize },
- { metric: 'Cache Hit Rate', value: stats.performance.cacheHitRate },
- { metric: 'Vector Dimension', value: stats.performance.vectorDimension }
- ]
- });
-
- output.writeln();
- output.writeln(output.bold('Namespaces'));
- output.printTable({
- columns: [
- { key: 'name', header: 'Name', width: 15 },
- { key: 'entries', header: 'Entries', width: 10, align: 'right' },
- { key: 'size', header: 'Size', width: 12, align: 'right' }
- ],
- data: stats.namespaces
- });
-
- output.writeln();
- output.printInfo('V3 Performance: 150x-12,500x faster search with HNSW indexing');
-
- return { success: true, data: stats };
- }
-};
-
-// Configure command
-const configureCommand: Command = {
- name: 'configure',
- aliases: ['config'],
- description: 'Configure memory backend',
- options: [
- {
- name: 'backend',
- short: 'b',
- description: 'Memory backend',
- type: 'string',
- choices: BACKENDS.map(b => b.value)
- },
- {
- name: 'path',
- description: 'Storage path',
- type: 'string'
- },
- {
- name: 'cache-size',
- description: 'Cache size in MB',
- type: 'number'
- },
- {
- name: 'hnsw-m',
- description: 'HNSW M parameter',
- type: 'number',
- default: 16
- },
- {
- name: 'hnsw-ef',
- description: 'HNSW ef parameter',
- type: 'number',
- default: 200
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- let backend = ctx.flags.backend as string;
-
- if (!backend && ctx.interactive) {
- backend = await select({
- message: 'Select memory backend:',
- options: BACKENDS,
- default: 'hybrid'
- });
- }
-
- const config = {
- backend: backend || 'hybrid',
- path: ctx.flags.path || './data/memory',
- cacheSize: ctx.flags.cacheSize || 256,
- hnsw: {
- m: ctx.flags.hnswM || 16,
- ef: ctx.flags.hnswEf || 200
- }
- };
-
- output.writeln();
- output.printInfo('Memory Configuration');
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'setting', header: 'Setting', width: 20 },
- { key: 'value', header: 'Value', width: 25 }
- ],
- data: [
- { setting: 'Backend', value: config.backend },
- { setting: 'Storage Path', value: config.path },
- { setting: 'Cache Size', value: `${config.cacheSize} MB` },
- { setting: 'HNSW M', value: config.hnsw.m },
- { setting: 'HNSW ef', value: config.hnsw.ef }
- ]
- });
-
- output.writeln();
- output.printSuccess('Memory configuration updated');
-
- return { success: true, data: config };
- }
-};
-
-// Main memory command
-export const memoryCommand: Command = {
- name: 'memory',
- description: 'Memory management commands',
- subcommands: [storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, statsCommand, configureCommand],
- options: [],
- examples: [
- { command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },
- { command: 'claude-flow memory search -q "auth patterns"', description: 'Search memory' },
- { command: 'claude-flow memory stats', description: 'Show statistics' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- output.writeln();
- output.writeln(output.bold('Memory Management Commands'));
- output.writeln();
- output.writeln('Usage: claude-flow memory <subcommand> [options]');
- output.writeln();
- output.writeln('Subcommands:');
- output.printList([
- `${output.highlight('store')} - Store data in memory`,
- `${output.highlight('retrieve')} - Retrieve data from memory`,
- `${output.highlight('search')} - Semantic/vector search`,
- `${output.highlight('list')} - List memory entries`,
- `${output.highlight('delete')} - Delete memory entry`,
- `${output.highlight('stats')} - Show statistics`,
- `${output.highlight('configure')} - Configure backend`
- ]);
-
- return { success: true };
- }
-};
-
-export default memoryCommand;
diff --git a/v3/cli/commands/migrate.ts b/v3/cli/commands/migrate.ts
deleted file mode 100644
index 6770c8d266..0000000000
--- a/v3/cli/commands/migrate.ts
+++ /dev/null
@@ -1,447 +0,0 @@
-/**
- * V3 CLI Migrate Command
- * Migration tools for V2 to V3 transition
- */
-
-import type { Command, CommandContext, CommandResult } from '../types.js';
-import { output } from '../output.js';
-import { select, confirm, multiSelect } from '../prompt.js';
-
-// Migration targets
-const MIGRATION_TARGETS = [
- { value: 'config', label: 'Configuration', hint: 'Migrate configuration files' },
- { value: 'memory', label: 'Memory Data', hint: 'Migrate memory/database content' },
- { value: 'agents', label: 'Agent Configs', hint: 'Migrate agent configurations' },
- { value: 'hooks', label: 'Hooks', hint: 'Migrate hook definitions' },
- { value: 'workflows', label: 'Workflows', hint: 'Migrate workflow definitions' },
- { value: 'all', label: 'All', hint: 'Full migration' }
-];
-
-// Status command
-const statusCommand: Command = {
- name: 'status',
- description: 'Check migration status',
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const status = {
- v2Version: '2.6.0',
- v3Version: '3.0.0-alpha.1',
- migrationState: 'partial',
- components: [
- { name: 'Configuration', status: 'migrated', v2Path: './claude-flow.json', v3Path: './claude-flow.config.json' },
- { name: 'Memory Data', status: 'pending', v2Path: './.claude-flow/memory', v3Path: './data/memory' },
- { name: 'Agent Configs', status: 'pending', v2Path: './.claude-flow/agents', v3Path: './v3/agents' },
- { name: 'Hooks', status: 'pending', v2Path: './src/hooks', v3Path: './v3/hooks' },
- { name: 'Workflows', status: 'not-required', v2Path: 'N/A', v3Path: 'N/A' }
- ],
- recommendations: [
- 'Backup v2 data before migration',
- 'Test migration in staging environment first',
- 'Review breaking changes in CHANGELOG.md'
- ]
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(status);
- return { success: true, data: status };
- }
-
- output.writeln();
- output.writeln(output.bold('Migration Status'));
- output.writeln();
- output.writeln(`V2 Version: ${status.v2Version}`);
- output.writeln(`V3 Version: ${status.v3Version}`);
- output.writeln(`State: ${formatMigrationStatus(status.migrationState)}`);
- output.writeln();
-
- output.writeln(output.bold('Components'));
- output.printTable({
- columns: [
- { key: 'name', header: 'Component', width: 18 },
- { key: 'status', header: 'Status', width: 15, format: (v) => formatMigrationStatus(String(v)) },
- { key: 'v2Path', header: 'V2 Path', width: 25 },
- { key: 'v3Path', header: 'V3 Path', width: 25 }
- ],
- data: status.components
- });
-
- output.writeln();
- output.writeln(output.bold('Recommendations'));
- output.printList(status.recommendations);
-
- return { success: true, data: status };
- }
-};
-
-// Run migration
-const runCommand: Command = {
- name: 'run',
- description: 'Run migration',
- options: [
- {
- name: 'target',
- short: 't',
- description: 'Migration target',
- type: 'string',
- choices: MIGRATION_TARGETS.map(t => t.value)
- },
- {
- name: 'dry-run',
- description: 'Show what would be migrated without making changes',
- type: 'boolean',
- default: false
- },
- {
- name: 'backup',
- description: 'Create backup before migration',
- type: 'boolean',
- default: true
- },
- {
- name: 'force',
- short: 'f',
- description: 'Force migration (overwrite existing)',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- let target = ctx.flags.target as string;
- const dryRun = ctx.flags.dryRun as boolean;
- const backup = ctx.flags.backup as boolean;
- const force = ctx.flags.force as boolean;
-
- if (!target && ctx.interactive) {
- target = await select({
- message: 'Select migration target:',
- options: MIGRATION_TARGETS,
- default: 'all'
- });
- }
-
- target = target || 'all';
-
- output.writeln();
-
- if (dryRun) {
- output.printInfo('DRY RUN - No changes will be made');
- output.writeln();
- }
-
- output.printInfo(`Migrating: ${target}`);
- output.writeln();
-
- // Backup step
- if (backup && !dryRun) {
- output.writeln(output.dim('Creating backup...'));
- output.writeln(output.dim(` Backup created: ./.claude-flow-backup-${Date.now()}`));
- output.writeln();
- }
-
- // Migration steps based on target
- const steps = getMigrationSteps(target);
-
- for (const step of steps) {
- output.writeln(`${output.info('>')} ${step.name}`);
- output.writeln(output.dim(` ${step.description}`));
-
- if (!dryRun) {
- // Simulate migration
- output.writeln(output.dim(` ${output.success('[OK]')} Completed`));
- } else {
- output.writeln(output.dim(` Would migrate: ${step.source} -> ${step.dest}`));
- }
-
- output.writeln();
- }
-
- const result = {
- target,
- dryRun,
- backup,
- stepsCompleted: steps.length,
- success: true
- };
-
- if (dryRun) {
- output.printInfo('Dry run complete. Run without --dry-run to apply changes.');
- } else {
- output.printSuccess('Migration completed successfully');
- }
-
- return { success: true, data: result };
- }
-};
-
-// Verify migration
-const verifyCommand: Command = {
- name: 'verify',
- description: 'Verify migration integrity',
- options: [
- {
- name: 'fix',
- description: 'Automatically fix issues',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const fix = ctx.flags.fix as boolean;
-
- output.writeln();
- output.printInfo('Verifying migration...');
- output.writeln();
-
- const checks = [
- { name: 'Configuration Schema', status: 'passed', details: 'V3 schema valid' },
- { name: 'Memory Data Integrity', status: 'passed', details: 'All entries valid' },
- { name: 'Agent Configurations', status: 'warning', details: '2 deprecated fields detected' },
- { name: 'Hook Definitions', status: 'passed', details: 'All hooks registered' },
- { name: 'File Permissions', status: 'passed', details: 'Correct permissions' },
- { name: 'Dependencies', status: 'passed', details: 'All dependencies available' }
- ];
-
- output.printTable({
- columns: [
- { key: 'name', header: 'Check', width: 25 },
- { key: 'status', header: 'Status', width: 12, format: (v) => {
- if (v === 'passed') return output.success('PASSED');
- if (v === 'warning') return output.warning('WARNING');
- return output.error('FAILED');
- }},
- { key: 'details', header: 'Details', width: 30 }
- ],
- data: checks
- });
-
- const hasIssues = checks.some(c => c.status !== 'passed');
-
- output.writeln();
-
- if (hasIssues) {
- if (fix) {
- output.printInfo('Attempting to fix issues...');
- output.printSuccess('Issues fixed');
- } else {
- output.printWarning('Some issues detected. Run with --fix to attempt automatic fixes.');
- }
- } else {
- output.printSuccess('All verification checks passed');
- }
-
- return { success: true, data: { checks, hasIssues } };
- }
-};
-
-// Rollback migration
-const rollbackCommand: Command = {
- name: 'rollback',
- description: 'Rollback to previous version',
- options: [
- {
- name: 'backup-id',
- description: 'Backup ID to restore',
- type: 'string'
- },
- {
- name: 'force',
- short: 'f',
- description: 'Skip confirmation',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const backupId = ctx.flags.backupId as string;
- const force = ctx.flags.force as boolean;
-
- // List available backups
- const backups = [
- { id: 'backup-1704369600', date: '2024-01-04 10:00:00', size: '45.2 MB' },
- { id: 'backup-1704283200', date: '2024-01-03 10:00:00', size: '44.8 MB' },
- { id: 'backup-1704196800', date: '2024-01-02 10:00:00', size: '43.5 MB' }
- ];
-
- if (!backupId && ctx.interactive) {
- output.writeln();
- output.writeln(output.bold('Available Backups'));
- output.writeln();
-
- output.printTable({
- columns: [
- { key: 'id', header: 'Backup ID', width: 20 },
- { key: 'date', header: 'Date', width: 22 },
- { key: 'size', header: 'Size', width: 12, align: 'right' }
- ],
- data: backups
- });
-
- output.writeln();
-
- const confirmed = await confirm({
- message: `Rollback to most recent backup (${backups[0].id})?`,
- default: false
- });
-
- if (!confirmed) {
- output.printInfo('Operation cancelled');
- return { success: true };
- }
- }
-
- const targetBackup = backupId || backups[0].id;
-
- if (!force && !ctx.interactive) {
- output.printError('Use --force to rollback without confirmation');
- return { success: false, exitCode: 1 };
- }
-
- output.writeln();
- output.printInfo(`Rolling back to ${targetBackup}...`);
- output.writeln();
-
- output.writeln(output.dim(' Stopping services...'));
- output.writeln(output.dim(' Restoring configuration...'));
- output.writeln(output.dim(' Restoring memory data...'));
- output.writeln(output.dim(' Restoring agent configs...'));
- output.writeln(output.dim(' Verifying integrity...'));
-
- output.writeln();
- output.printSuccess(`Rolled back to ${targetBackup}`);
- output.writeln(output.dim(' Note: Restart services to apply changes'));
-
- return { success: true, data: { backupId: targetBackup, rolledBack: true } };
- }
-};
-
-// Breaking changes info
-const breakingCommand: Command = {
- name: 'breaking',
- description: 'Show V3 breaking changes',
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const changes = [
- {
- category: 'Configuration',
- changes: [
- { change: 'Config file renamed', from: 'claude-flow.json', to: 'claude-flow.config.json' },
- { change: 'Swarm config restructured', from: 'swarm.mode', to: 'swarm.topology' },
- { change: 'Provider config format', from: 'provider: "anthropic"', to: 'providers: [...]' }
- ]
- },
- {
- category: 'Memory',
- changes: [
- { change: 'Backend option changed', from: 'memory: { type }', to: 'memory: { backend }' },
- { change: 'HNSW enabled by default', from: 'Manual opt-in', to: 'Auto-enabled' },
- { change: 'Storage path changed', from: '.claude-flow/memory', to: 'data/memory' }
- ]
- },
- {
- category: 'CLI',
- changes: [
- { change: 'Agent command renamed', from: 'spawn <type>', to: 'agent spawn -t <type>' },
- { change: 'Memory command added', from: 'N/A', to: 'memory <subcommand>' },
- { change: 'Hook command enhanced', from: 'hook <type>', to: 'hooks <subcommand>' }
- ]
- },
- {
- category: 'API',
- changes: [
- { change: 'Removed Deno support', from: 'Deno + Node.js', to: 'Node.js 20+ only' },
- { change: 'Event system changed', from: 'EventEmitter', to: 'Event sourcing' },
- { change: 'Coordination unified', from: 'Multiple coordinators', to: 'SwarmCoordinator' }
- ]
- }
- ];
-
- if (ctx.flags.format === 'json') {
- output.printJson(changes);
- return { success: true, data: changes };
- }
-
- output.writeln();
- output.writeln(output.bold('V3 Breaking Changes'));
- output.writeln();
-
- for (const category of changes) {
- output.writeln(output.highlight(category.category));
- output.printTable({
- columns: [
- { key: 'change', header: 'Change', width: 25 },
- { key: 'from', header: 'V2', width: 25 },
- { key: 'to', header: 'V3', width: 25 }
- ],
- data: category.changes,
- border: false
- });
- output.writeln();
- }
-
- output.printInfo('Run "claude-flow migrate run" to automatically handle these changes');
-
- return { success: true, data: changes };
- }
-};
-
-// Main migrate command
-export const migrateCommand: Command = {
- name: 'migrate',
- description: 'V2 to V3 migration tools',
- subcommands: [statusCommand, runCommand, verifyCommand, rollbackCommand, breakingCommand],
- options: [],
- examples: [
- { command: 'claude-flow migrate status', description: 'Check migration status' },
- { command: 'claude-flow migrate run --dry-run', description: 'Preview migration' },
- { command: 'claude-flow migrate run -t all', description: 'Run full migration' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- output.writeln();
- output.writeln(output.bold('V2 to V3 Migration Tools'));
- output.writeln();
- output.writeln('Usage: claude-flow migrate <subcommand> [options]');
- output.writeln();
- output.writeln('Subcommands:');
- output.printList([
- `${output.highlight('status')} - Check migration status`,
- `${output.highlight('run')} - Run migration`,
- `${output.highlight('verify')} - Verify migration integrity`,
- `${output.highlight('rollback')} - Rollback to previous version`,
- `${output.highlight('breaking')} - Show breaking changes`
- ]);
-
- return { success: true };
- }
-};
-
-// Helper functions
-function formatMigrationStatus(status: string): string {
- switch (status) {
- case 'migrated':
- case 'passed':
- return output.success(status);
- case 'pending':
- case 'partial':
- return output.warning(status);
- case 'failed':
- return output.error(status);
- case 'not-required':
- return output.dim(status);
- default:
- return status;
- }
-}
-
-function getMigrationSteps(target: string): Array<{ name: string; description: string; source: string; dest: string }> {
- const allSteps = [
- { name: 'Configuration Files', description: 'Migrate config schema to V3 format', source: './claude-flow.json', dest: './claude-flow.config.json' },
- { name: 'Memory Backend', description: 'Upgrade to hybrid backend with AgentDB', source: './.claude-flow/memory', dest: './data/memory' },
- { name: 'Agent Definitions', description: 'Convert agent configs to V3 format', source: './.claude-flow/agents', dest: './v3/agents' },
- { name: 'Hook Registry', description: 'Migrate hooks to V3 hook system', source: './src/hooks', dest: './v3/hooks' },
- { name: 'Workflow Definitions', description: 'Convert workflows to event-sourced format', source: './.claude-flow/workflows', dest: './data/workflows' }
- ];
-
- if (target === 'all') return allSteps;
-
- return allSteps.filter(s => s.name.toLowerCase().includes(target.toLowerCase()));
-}
-
-export default migrateCommand;
diff --git a/v3/cli/commands/swarm.ts b/v3/cli/commands/swarm.ts
deleted file mode 100644
index 9b271e3895..0000000000
--- a/v3/cli/commands/swarm.ts
+++ /dev/null
@@ -1,623 +0,0 @@
-/**
- * V3 CLI Swarm Command
- * Swarm coordination and management commands
- */
-
-import type { Command, CommandContext, CommandResult } from '../types.js';
-import { output } from '../output.js';
-import { select, confirm, multiSelect } from '../prompt.js';
-
-// Swarm topologies
-const TOPOLOGIES = [
- { value: 'hierarchical', label: 'Hierarchical', hint: 'Queen-led coordination with worker agents' },
- { value: 'mesh', label: 'Mesh', hint: 'Fully connected peer-to-peer network' },
- { value: 'ring', label: 'Ring', hint: 'Circular communication pattern' },
- { value: 'star', label: 'Star', hint: 'Central coordinator with spoke agents' },
- { value: 'hybrid', label: 'Hybrid', hint: 'Hierarchical mesh for maximum flexibility' }
-];
-
-// Swarm strategies
-const STRATEGIES = [
- { value: 'research', label: 'Research', hint: 'Distributed research and analysis' },
- { value: 'development', label: 'Development', hint: 'Collaborative code development' },
- { value: 'testing', label: 'Testing', hint: 'Comprehensive test coverage' },
- { value: 'optimization', label: 'Optimization', hint: 'Performance optimization' },
- { value: 'maintenance', label: 'Maintenance', hint: 'Codebase maintenance and refactoring' },
- { value: 'analysis', label: 'Analysis', hint: 'Code analysis and documentation' }
-];
-
-// Initialize swarm
-const initCommand: Command = {
- name: 'init',
- description: 'Initialize a new swarm',
- options: [
- {
- name: 'topology',
- short: 't',
- description: 'Swarm topology',
- type: 'string',
- choices: TOPOLOGIES.map(t => t.value),
- default: 'hierarchical'
- },
- {
- name: 'max-agents',
- short: 'm',
- description: 'Maximum number of agents',
- type: 'number',
- default: 15
- },
- {
- name: 'auto-scale',
- description: 'Enable automatic scaling',
- type: 'boolean',
- default: true
- },
- {
- name: 'strategy',
- short: 's',
- description: 'Coordination strategy',
- type: 'string',
- choices: STRATEGIES.map(s => s.value)
- },
- {
- name: 'v3-mode',
- description: 'Enable V3 15-agent hierarchical mesh mode',
- type: 'boolean',
- default: false
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- let topology = ctx.flags.topology as string;
- const maxAgents = ctx.flags.maxAgents as number || 15;
- const v3Mode = ctx.flags.v3Mode as boolean;
-
- // V3 mode enables hierarchical-mesh hybrid
- if (v3Mode) {
- topology = 'hybrid';
- output.printInfo('V3 Mode: Using hierarchical-mesh topology with 15-agent coordination');
- }
-
- // Interactive topology selection
- if (!topology && ctx.interactive) {
- topology = await select({
- message: 'Select swarm topology:',
- options: TOPOLOGIES,
- default: 'hierarchical'
- });
- }
-
- output.writeln();
- output.printInfo('Initializing swarm...');
-
- const swarmConfig = {
- id: `swarm-${Date.now().toString(36)}`,
- topology,
- maxAgents,
- autoScale: ctx.flags.autoScale ?? true,
- strategy: ctx.flags.strategy || 'development',
- status: 'initializing',
- createdAt: new Date().toISOString(),
- v3Mode,
- coordinationEngine: v3Mode ? 'unified-swarm-coordinator' : 'standard'
- };
-
- // Simulate initialization
- output.writeln(output.dim(' Creating coordination topology...'));
- output.writeln(output.dim(' Initializing memory namespace...'));
- output.writeln(output.dim(' Setting up communication channels...'));
-
- if (v3Mode) {
- output.writeln(output.dim(' Enabling Flash Attention (2.49x-7.47x speedup)...'));
- output.writeln(output.dim(' Configuring AgentDB integration (150x faster)...'));
- output.writeln(output.dim(' Initializing SONA learning system...'));
- }
-
- output.writeln();
- output.printTable({
- columns: [
- { key: 'property', header: 'Property', width: 20 },
- { key: 'value', header: 'Value', width: 35 }
- ],
- data: [
- { property: 'Swarm ID', value: swarmConfig.id },
- { property: 'Topology', value: swarmConfig.topology },
- { property: 'Max Agents', value: swarmConfig.maxAgents },
- { property: 'Auto Scale', value: swarmConfig.autoScale ? 'Enabled' : 'Disabled' },
- { property: 'Strategy', value: swarmConfig.strategy },
- { property: 'V3 Mode', value: swarmConfig.v3Mode ? 'Enabled' : 'Disabled' },
- { property: 'Coordination Engine', value: swarmConfig.coordinationEngine }
- ]
- });
-
- output.writeln();
- output.printSuccess('Swarm initialized successfully');
-
- if (ctx.flags.format === 'json') {
- output.printJson(swarmConfig);
- }
-
- return { success: true, data: swarmConfig };
- }
-};
-
-// Start swarm execution
-const startCommand: Command = {
- name: 'start',
- description: 'Start swarm execution',
- options: [
- {
- name: 'objective',
- short: 'o',
- description: 'Swarm objective/task',
- type: 'string',
- required: true
- },
- {
- name: 'strategy',
- short: 's',
- description: 'Execution strategy',
- type: 'string',
- choices: STRATEGIES.map(s => s.value)
- },
- {
- name: 'parallel',
- short: 'p',
- description: 'Enable parallel execution',
- type: 'boolean',
- default: true
- },
- {
- name: 'monitor',
- description: 'Enable real-time monitoring',
- type: 'boolean',
- default: true
- }
- ],
- examples: [
- { command: 'claude-flow swarm start -o "Build REST API" -s development', description: 'Start development swarm' },
- { command: 'claude-flow swarm start -o "Analyze codebase" --parallel', description: 'Parallel analysis' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const objective = ctx.args[0] || ctx.flags.objective as string;
- let strategy = ctx.flags.strategy as string;
-
- if (!objective) {
- output.printError('Objective is required. Use -o or provide as argument.');
- return { success: false, exitCode: 1 };
- }
-
- // Interactive strategy selection
- if (!strategy && ctx.interactive) {
- strategy = await select({
- message: 'Select execution strategy:',
- options: STRATEGIES,
- default: 'development'
- });
- }
-
- strategy = strategy || 'development';
-
- output.writeln();
- output.printInfo(`Starting swarm with objective: ${output.highlight(objective)}`);
- output.writeln();
-
- // Simulate agent spawning based on strategy
- const agentPlan = getAgentPlan(strategy);
-
- output.writeln(output.bold('Agent Deployment Plan'));
- output.printTable({
- columns: [
- { key: 'role', header: 'Role', width: 20 },
- { key: 'type', header: 'Type', width: 15 },
- { key: 'count', header: 'Count', width: 8, align: 'right' },
- { key: 'purpose', header: 'Purpose', width: 30 }
- ],
- data: agentPlan
- });
-
- // Confirm execution
- if (ctx.interactive) {
- const confirmed = await confirm({
- message: `Deploy ${agentPlan.reduce((sum, a) => sum + a.count, 0)} agents?`,
- default: true
- });
-
- if (!confirmed) {
- output.printInfo('Swarm execution cancelled');
- return { success: true };
- }
- }
-
- output.writeln();
- output.printInfo('Deploying agents...');
-
- // Simulate deployment progress
- const spinner = output.createSpinner({ text: 'Initializing agents...', spinner: 'dots' });
- spinner.start();
-
- // Simulate async operation
- await new Promise(resolve => setTimeout(resolve, 500));
-
- spinner.succeed('All agents deployed');
-
- const executionState = {
- swarmId: `swarm-${Date.now().toString(36)}`,
- objective,
- strategy,
- status: 'running',
- agents: agentPlan.reduce((sum, a) => sum + a.count, 0),
- startedAt: new Date().toISOString(),
- parallel: ctx.flags.parallel ?? true
- };
-
- output.writeln();
- output.printSuccess('Swarm execution started');
- output.writeln(output.dim(` Monitor: claude-flow swarm status ${executionState.swarmId}`));
-
- return { success: true, data: executionState };
- }
-};
-
-// Swarm status
-const statusCommand: Command = {
- name: 'status',
- description: 'Show swarm status',
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const swarmId = ctx.args[0];
-
- // Simulated swarm status
- const status = {
- id: swarmId || 'swarm-current',
- topology: 'hybrid',
- status: 'running',
- objective: 'Build enterprise REST API with authentication',
- strategy: 'development',
- agents: {
- total: 15,
- active: 12,
- idle: 2,
- completed: 1
- },
- progress: 65,
- tasks: {
- total: 45,
- completed: 29,
- inProgress: 12,
- pending: 4
- },
- metrics: {
- tokensUsed: 234567,
- avgResponseTime: '1.8s',
- successRate: '97.2%',
- elapsedTime: '45m 23s'
- },
- coordination: {
- consensusRounds: 8,
- messagesSent: 1234,
- conflictsResolved: 3
- }
- };
-
- if (ctx.flags.format === 'json') {
- output.printJson(status);
- return { success: true, data: status };
- }
-
- output.writeln();
- output.writeln(output.bold(`Swarm Status: ${status.id}`));
- output.writeln();
-
- // Progress bar
- output.writeln(`Overall Progress: ${output.progressBar(status.progress, 100, 40)}`);
- output.writeln();
-
- // Agent status
- output.writeln(output.bold('Agents'));
- output.printTable({
- columns: [
- { key: 'status', header: 'Status', width: 12 },
- { key: 'count', header: 'Count', width: 10, align: 'right' }
- ],
- data: [
- { status: output.success('Active'), count: status.agents.active },
- { status: output.warning('Idle'), count: status.agents.idle },
- { status: output.dim('Completed'), count: status.agents.completed },
- { status: 'Total', count: status.agents.total }
- ]
- });
-
- output.writeln();
-
- // Task status
- output.writeln(output.bold('Tasks'));
- output.printTable({
- columns: [
- { key: 'status', header: 'Status', width: 12 },
- { key: 'count', header: 'Count', width: 10, align: 'right' }
- ],
- data: [
- { status: output.success('Completed'), count: status.tasks.completed },
- { status: output.info('In Progress'), count: status.tasks.inProgress },
- { status: output.dim('Pending'), count: status.tasks.pending },
- { status: 'Total', count: status.tasks.total }
- ]
- });
-
- output.writeln();
-
- // Metrics
- output.writeln(output.bold('Performance Metrics'));
- output.printList([
- `Tokens Used: ${status.metrics.tokensUsed.toLocaleString()}`,
- `Avg Response Time: ${status.metrics.avgResponseTime}`,
- `Success Rate: ${status.metrics.successRate}`,
- `Elapsed Time: ${status.metrics.elapsedTime}`
- ]);
-
- output.writeln();
-
- // Coordination stats
- output.writeln(output.bold('Coordination'));
- output.printList([
- `Consensus Rounds: ${status.coordination.consensusRounds}`,
- `Messages Sent: ${status.coordination.messagesSent}`,
- `Conflicts Resolved: ${status.coordination.conflictsResolved}`
- ]);
-
- return { success: true, data: status };
- }
-};
-
-// Stop swarm
-const stopCommand: Command = {
- name: 'stop',
- description: 'Stop swarm execution',
- options: [
- {
- name: 'force',
- short: 'f',
- description: 'Force immediate stop',
- type: 'boolean',
- default: false
- },
- {
- name: 'save-state',
- description: 'Save current state for resume',
- type: 'boolean',
- default: true
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const swarmId = ctx.args[0];
- const force = ctx.flags.force as boolean;
-
- if (!swarmId) {
- output.printError('Swarm ID is required');
- return { success: false, exitCode: 1 };
- }
-
- if (ctx.interactive && !force) {
- const confirmed = await confirm({
- message: `Stop swarm ${swarmId}? Progress will be saved.`,
- default: false
- });
-
- if (!confirmed) {
- output.printInfo('Operation cancelled');
- return { success: true };
- }
- }
-
- output.printInfo(`Stopping swarm ${swarmId}...`);
-
- if (!force) {
- output.writeln(output.dim(' Completing in-progress tasks...'));
- output.writeln(output.dim(' Saving coordination state...'));
- output.writeln(output.dim(' Notifying agents...'));
- output.writeln(output.dim(' Saving memory state...'));
- }
-
- output.printSuccess(`Swarm ${swarmId} stopped`);
-
- return { success: true, data: { swarmId, stopped: true, force } };
- }
-};
-
-// Scale swarm
-const scaleCommand: Command = {
- name: 'scale',
- description: 'Scale swarm agent count',
- options: [
- {
- name: 'agents',
- short: 'a',
- description: 'Target number of agents',
- type: 'number',
- required: true
- },
- {
- name: 'type',
- short: 't',
- description: 'Agent type to scale',
- type: 'string'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const swarmId = ctx.args[0];
- const targetAgents = ctx.flags.agents as number;
- const agentType = ctx.flags.type as string;
-
- if (!swarmId) {
- output.printError('Swarm ID is required');
- return { success: false, exitCode: 1 };
- }
-
- if (!targetAgents) {
- output.printError('Target agent count required. Use --agents or -a');
- return { success: false, exitCode: 1 };
- }
-
- output.printInfo(`Scaling swarm ${swarmId} to ${targetAgents} agents...`);
-
- // Simulate scaling
- const currentAgents = 8;
- const delta = targetAgents - currentAgents;
-
- if (delta > 0) {
- output.writeln(output.dim(` Spawning ${delta} new agents...`));
- } else if (delta < 0) {
- output.writeln(output.dim(` Gracefully stopping ${-delta} agents...`));
- } else {
- output.printInfo('Swarm already at target size');
- return { success: true };
- }
-
- output.printSuccess(`Swarm scaled to ${targetAgents} agents`);
-
- return { success: true, data: { swarmId, agents: targetAgents, delta } };
- }
-};
-
-// Coordinate command (V3 specific)
-const coordinateCommand: Command = {
- name: 'coordinate',
- description: 'Execute V3 15-agent hierarchical mesh coordination',
- options: [
- {
- name: 'agents',
- description: 'Number of agents',
- type: 'number',
- default: 15
- },
- {
- name: 'domains',
- description: 'Domains to activate',
- type: 'array'
- }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- const agentCount = ctx.flags.agents as number || 15;
-
- output.writeln();
- output.writeln(output.bold('V3 15-Agent Hierarchical Mesh Coordination'));
- output.writeln();
-
- // V3 agent structure
- const v3Agents = [
- { id: 1, role: 'Queen Coordinator', domain: 'Orchestration', status: 'primary' },
- { id: 2, role: 'Security Architect', domain: 'Security', status: 'active' },
- { id: 3, role: 'Security Auditor', domain: 'Security', status: 'active' },
- { id: 4, role: 'Test Architect', domain: 'Security', status: 'active' },
- { id: 5, role: 'Core Architect', domain: 'Core', status: 'active' },
- { id: 6, role: 'Memory Specialist', domain: 'Core', status: 'active' },
- { id: 7, role: 'Swarm Specialist', domain: 'Core', status: 'active' },
- { id: 8, role: 'Integration Architect', domain: 'Integration', status: 'active' },
- { id: 9, role: 'Performance Engineer', domain: 'Integration', status: 'active' },
- { id: 10, role: 'CLI Developer', domain: 'Integration', status: 'active' },
- { id: 11, role: 'Hooks Developer', domain: 'Integration', status: 'active' },
- { id: 12, role: 'MCP Specialist', domain: 'Integration', status: 'active' },
- { id: 13, role: 'Project Coordinator', domain: 'Management', status: 'active' },
- { id: 14, role: 'Documentation Lead', domain: 'Management', status: 'standby' },
- { id: 15, role: 'DevOps Engineer', domain: 'Management', status: 'standby' }
- ].slice(0, agentCount);
-
- output.printTable({
- columns: [
- { key: 'id', header: '#', width: 3, align: 'right' },
- { key: 'role', header: 'Role', width: 22 },
- { key: 'domain', header: 'Domain', width: 15 },
- { key: 'status', header: 'Status', width: 10, format: (v) => {
- if (v === 'primary') return output.highlight(String(v));
- if (v === 'active') return output.success(String(v));
- return output.dim(String(v));
- }}
- ],
- data: v3Agents
- });
-
- output.writeln();
- output.printInfo('Performance Targets:');
- output.printList([
- `Flash Attention: ${output.success('2.49x-7.47x speedup')}`,
- `AgentDB Search: ${output.success('150x-12,500x improvement')}`,
- `Memory Reduction: ${output.success('50-75%')}`,
- `Code Reduction: ${output.success('<5,000 lines')}`
- ]);
-
- return { success: true, data: { agents: v3Agents, count: agentCount } };
- }
-};
-
-// Main swarm command
-export const swarmCommand: Command = {
- name: 'swarm',
- description: 'Swarm coordination commands',
- subcommands: [initCommand, startCommand, statusCommand, stopCommand, scaleCommand, coordinateCommand],
- options: [],
- examples: [
- { command: 'claude-flow swarm init --v3-mode', description: 'Initialize V3 swarm' },
- { command: 'claude-flow swarm start -o "Build API" -s development', description: 'Start development swarm' },
- { command: 'claude-flow swarm coordinate --agents 15', description: 'V3 coordination' }
- ],
- action: async (ctx: CommandContext): Promise<CommandResult> => {
- output.writeln();
- output.writeln(output.bold('Swarm Coordination Commands'));
- output.writeln();
- output.writeln('Usage: claude-flow swarm <subcommand> [options]');
- output.writeln();
- output.writeln('Subcommands:');
- output.printList([
- `${output.highlight('init')} - Initialize a new swarm`,
- `${output.highlight('start')} - Start swarm execution`,
- `${output.highlight('status')} - Show swarm status`,
- `${output.highlight('stop')} - Stop swarm execution`,
- `${output.highlight('scale')} - Scale swarm agent count`,
- `${output.highlight('coordinate')} - V3 15-agent coordination`
- ]);
-
- return { success: true };
- }
-};
-
-// Helper function
-function getAgentPlan(strategy: string): Array<{ role: string; type: string; count: number; purpose: string }> {
- const plans: Record<string, Array<{ role: string; type: string; count: number; purpose: string }>> = {
- development: [
- { role: 'Coordinator', type: 'coordinator', count: 1, purpose: 'Orchestrate workflow' },
- { role: 'Architect', type: 'architect', count: 1, purpose: 'System design' },
- { role: 'Coder', type: 'coder', count: 3, purpose: 'Implementation' },
- { role: 'Tester', type: 'tester', count: 2, purpose: 'Quality assurance' },
- { role: 'Reviewer', type: 'reviewer', count: 1, purpose: 'Code review' }
- ],
- research: [
- { role: 'Coordinator', type: 'coordinator', count: 1, purpose: 'Research coordination' },
- { role: 'Researcher', type: 'researcher', count: 4, purpose: 'Data gathering' },
- { role: 'Analyst', type: 'analyst', count: 2, purpose: 'Analysis and synthesis' }
- ],
- testing: [
- { role: 'Test Lead', type: 'tester', count: 1, purpose: 'Test strategy' },
- { role: 'Unit Tester', type: 'tester', count: 2, purpose: 'Unit tests' },
- { role: 'Integration Tester', type: 'tester', count: 2, purpose: 'Integration tests' },
- { role: 'QA Reviewer', type: 'reviewer', count: 1, purpose: 'Quality review' }
- ],
- optimization: [
- { role: 'Performance Lead', type: 'optimizer', count: 1, purpose: 'Performance strategy' },
- { role: 'Profiler', type: 'analyst', count: 2, purpose: 'Profiling' },
- { role: 'Optimizer', type: 'coder', count: 2, purpose: 'Optimization' }
- ],
- maintenance: [
- { role: 'Coordinator', type: 'coordinator', count: 1, purpose: 'Maintenance planning' },
- { role: 'Refactorer', type: 'coder', count: 2, purpose: 'Code cleanup' },
- { role: 'Documenter', type: 'researcher', count: 1, purpose: 'Documentation' }
- ],
- analysis: [
- { role: 'Analyst Lead', type: 'analyst', count: 1, purpose: 'Analysis coordination' },
- { role: 'Code Analyst', type: 'analyst', count: 2, purpose: 'Code analysis' },
- { role: 'Security Analyst', type: 'reviewer', count: 1, purpose: 'Security review' }
- ]
- };
-
- return plans[strategy] || plans.development;
-}
-
-export default swarmCommand;
diff --git a/v3/cli/index.ts b/v3/cli/index.ts
deleted file mode 100644
index 88daf2a6d7..0000000000
--- a/v3/cli/index.ts
+++ /dev/null
@@ -1,310 +0,0 @@
-/**
- * V3 CLI Main Entry Point
- * Modernized CLI for Claude Flow V3
- */
-
-import type { Command, CommandContext, CommandResult, V3Config, CLIError } from './types.js';
-import { CommandParser, commandParser } from './parser.js';
-import { OutputFormatter, output } from './output.js';
-import { commands, commandRegistry, getCommand } from './commands/index.js';
-
-export const VERSION = '3.0.0-alpha.1';
-
-export interface CLIOptions {
- name?: string;
- description?: string;
- version?: string;
- interactive?: boolean;
-}
-
-/**
- * V3 CLI Application
- */
-export class CLI {
- private name: string;
- private description: string;
- private version: string;
- private parser: CommandParser;
- private output: OutputFormatter;
- private interactive: boolean;
-
- constructor(options: CLIOptions = {}) {
- this.name = options.name || 'claude-flow';
- this.description = options.description || 'Claude Flow V3 - AI Agent Orchestration Platform';
- this.version = options.version || VERSION;
- this.parser = commandParser;
- this.output = output;
- this.interactive = options.interactive ?? process.stdin.isTTY ?? false;
-
- // Register all commands
- for (const cmd of commands) {
- this.parser.registerCommand(cmd);
- }
- }
-
- /**
- * Run the CLI with given arguments
- */
- async run(args: string[] = process.argv.slice(2)): Promise<void> {
- try {
- // Parse arguments
- const parseResult = this.parser.parse(args);
- const { command: commandPath, flags, positional } = parseResult;
-
- // Handle global flags
- if (flags.version || flags.V) {
- this.showVersion();
- return;
- }
-
- if (flags.noColor) {
- this.output.setColorEnabled(false);
- }
-
- // No command - show help
- if (commandPath.length === 0 || flags.help || flags.h) {
- if (commandPath.length > 0) {
- // Show command-specific help
- this.showCommandHelp(commandPath[0]);
- } else {
- this.showHelp();
- }
- return;
- }
-
- // Find and execute command
- const commandName = commandPath[0];
- const command = getCommand(commandName);
-
- if (!command) {
- this.output.printError(`Unknown command: ${commandName}`);
- this.output.writeln(`Run "${this.name} --help" for available commands`);
- process.exit(1);
- }
-
- // Handle subcommand
- let targetCommand = command;
- let subcommandArgs = positional;
-
- if (commandPath.length > 1 && command.subcommands) {
- const subcommandName = commandPath[1];
- const subcommand = command.subcommands.find(
- sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName)
- );
-
- if (subcommand) {
- targetCommand = subcommand;
- // Remove subcommand from args
- subcommandArgs = positional.slice(1);
- }
- } else if (positional.length > 0 && command.subcommands) {
- // Check if first positional is a subcommand
- const subcommandName = positional[0];
- const subcommand = command.subcommands.find(
- sc => sc.name === subcommandName || sc.aliases?.includes(subcommandName)
- );
-
- if (subcommand) {
- targetCommand = subcommand;
- subcommandArgs = positional.slice(1);
- }
- }
-
- // Validate flags
- const validationErrors = this.parser.validateFlags(flags, targetCommand);
- if (validationErrors.length > 0) {
- for (const error of validationErrors) {
- this.output.printError(error);
- }
- process.exit(1);
- }
-
- // Build context
- const ctx: CommandContext = {
- args: subcommandArgs,
- flags,
- config: await this.loadConfig(flags.config as string),
- cwd: process.cwd(),
- interactive: this.interactive && !flags.quiet
- };
-
- // Execute command
- if (targetCommand.action) {
- const result = await targetCommand.action(ctx);
-
- if (result && !result.success) {
- process.exit(result.exitCode || 1);
- }
- } else {
- // No action - show command help
- this.showCommandHelp(commandName);
- }
- } catch (error) {
- this.handleError(error as Error);
- }
- }
-
- /**
- * Show main help
- */
- private showHelp(): void {
- this.output.writeln();
- this.output.writeln(this.output.bold(`${this.name} v${this.version}`));
- this.output.writeln(this.output.dim(this.description));
- this.output.writeln();
-
- this.output.writeln(this.output.bold('USAGE:'));
- this.output.writeln(` ${this.name} <command> [subcommand] [options]`);
- this.output.writeln();
-
- this.output.writeln(this.output.bold('COMMANDS:'));
- for (const cmd of commands) {
- if (cmd.hidden) continue;
- const name = cmd.name.padEnd(12);
- this.output.writeln(` ${this.output.highlight(name)} ${cmd.description}`);
- }
- this.output.writeln();
-
- this.output.writeln(this.output.bold('GLOBAL OPTIONS:'));
- for (const opt of this.parser.getGlobalOptions()) {
- const flags = opt.short ? `-${opt.short}, --${opt.name}` : ` --${opt.name}`;
- this.output.writeln(` ${flags.padEnd(25)} ${opt.description}`);
- }
- this.output.writeln();
-
- this.output.writeln(this.output.bold('V3 FEATURES:'));
- this.output.printList([
- '15-agent hierarchical mesh coordination',
- 'AgentDB with HNSW indexing (150x-12,500x faster)',
- 'Flash Attention (2.49x-7.47x speedup)',
- 'Unified SwarmCoordinator engine',
- 'Event-sourced state management',
- 'Domain-Driven Design architecture'
- ]);
- this.output.writeln();
-
- this.output.writeln(this.output.bold('EXAMPLES:'));
- this.output.writeln(` ${this.name} agent spawn -t coder # Spawn a coder agent`);
- this.output.writeln(` ${this.name} swarm init --v3-mode # Initialize V3 swarm`);
- this.output.writeln(` ${this.name} memory search -q "auth patterns" # Semantic search`);
- this.output.writeln(` ${this.name} mcp start # Start MCP server`);
- this.output.writeln();
-
- this.output.writeln(this.output.dim('Run "claude-flow <command> --help" for command help'));
- this.output.writeln();
- }
-
- /**
- * Show command-specific help
- */
- private showCommandHelp(commandName: string): void {
- const command = getCommand(commandName);
-
- if (!command) {
- this.output.printError(`Unknown command: ${commandName}`);
- return;
- }
-
- this.output.writeln();
- this.output.writeln(this.output.bold(`${this.name} ${command.name}`));
- this.output.writeln(command.description);
- this.output.writeln();
-
- // Subcommands
- if (command.subcommands && command.subcommands.length > 0) {
- this.output.writeln(this.output.bold('SUBCOMMANDS:'));
- for (const sub of command.subcommands) {
- if (sub.hidden) continue;
- const name = sub.name.padEnd(15);
- const aliases = sub.aliases ? this.output.dim(` (${sub.aliases.join(', ')})`) : '';
- this.output.writeln(` ${this.output.highlight(name)} ${sub.description}${aliases}`);
- }
- this.output.writeln();
- }
-
- // Options
- if (command.options && command.options.length > 0) {
- this.output.writeln(this.output.bold('OPTIONS:'));
- for (const opt of command.options) {
- const flags = opt.short ? `-${opt.short}, --${opt.name}` : ` --${opt.name}`;
- const required = opt.required ? this.output.error(' (required)') : '';
- const defaultVal = opt.default !== undefined ? this.output.dim(` [default: ${opt.default}]`) : '';
- this.output.writeln(` ${flags.padEnd(25)} ${opt.description}${required}${defaultVal}`);
- }
- this.output.writeln();
- }
-
- // Examples
- if (command.examples && command.examples.length > 0) {
- this.output.writeln(this.output.bold('EXAMPLES:'));
- for (const example of command.examples) {
- this.output.writeln(` ${this.output.dim('$')} ${example.command}`);
- this.output.writeln(` ${this.output.dim(example.description)}`);
- }
- this.output.writeln();
- }
- }
-
- /**
- * Show version
- */
- private showVersion(): void {
- this.output.writeln(`${this.name} v${this.version}`);
- }
-
- /**
- * Load configuration file
- */
- private async loadConfig(configPath?: string): Promise<V3Config | undefined> {
- // TODO: Implement actual config loading
- // For now, return undefined
- return undefined;
- }
-
- /**
- * Handle errors
- */
- private handleError(error: Error): void {
- if ('code' in error) {
- // CLIError
- const cliError = error as CLIError;
- this.output.printError(cliError.message);
-
- if (cliError.details) {
- this.output.writeln(this.output.dim(JSON.stringify(cliError.details, null, 2)));
- }
-
- process.exit(cliError.exitCode);
- } else {
- // Generic error
- this.output.printError(error.message);
-
- if (process.env.DEBUG) {
- this.output.writeln();
- this.output.writeln(this.output.dim(error.stack || ''));
- }
-
- process.exit(1);
- }
- }
-}
-
-// Export components
-export { CommandParser, commandParser } from './parser.js';
-export { OutputFormatter, output, Progress, Spinner } from './output.js';
-export * from './prompt.js';
-export * from './commands/index.js';
-export * from './types.js';
-
-// Default export
-export default CLI;
-
-// Run CLI if this is the main module
-const isMainModule = process.argv[1]?.endsWith('index.js') ||
- process.argv[1]?.endsWith('index.ts') ||
- process.argv[1]?.includes('cli');
-
-if (isMainModule) {
- const cli = new CLI();
- cli.run().catch(console.error);
-}
diff --git a/v3/cli/output.ts b/v3/cli/output.ts
deleted file mode 100644
index eda3f458e5..0000000000
--- a/v3/cli/output.ts
+++ /dev/null
@@ -1,593 +0,0 @@
-/**
- * V3 CLI Output Formatter
- * Advanced output formatting with tables, progress bars, and colors
- */
-
-import type { TableOptions, TableColumn, ProgressOptions, SpinnerOptions } from './types.js';
-
-// ============================================
-// Color Support
-// ============================================
-
-const COLORS = {
- // Standard colors
- reset: '\x1b[0m',
- bold: '\x1b[1m',
- dim: '\x1b[2m',
- italic: '\x1b[3m',
- underline: '\x1b[4m',
-
- // Foreground colors
- black: '\x1b[30m',
- red: '\x1b[31m',
- green: '\x1b[32m',
- yellow: '\x1b[33m',
- blue: '\x1b[34m',
- magenta: '\x1b[35m',
- cyan: '\x1b[36m',
- white: '\x1b[37m',
- gray: '\x1b[90m',
-
- // Bright foreground colors
- brightRed: '\x1b[91m',
- brightGreen: '\x1b[92m',
- brightYellow: '\x1b[93m',
- brightBlue: '\x1b[94m',
- brightMagenta: '\x1b[95m',
- brightCyan: '\x1b[96m',
- brightWhite: '\x1b[97m',
-
- // Background colors
- bgBlack: '\x1b[40m',
- bgRed: '\x1b[41m',
- bgGreen: '\x1b[42m',
- bgYellow: '\x1b[43m',
- bgBlue: '\x1b[44m',
- bgMagenta: '\x1b[45m',
- bgCyan: '\x1b[46m',
- bgWhite: '\x1b[47m'
-} as const;
-
-type ColorName = keyof typeof COLORS;
-
-export class OutputFormatter {
- private colorEnabled: boolean;
- private outputStream: NodeJS.WriteStream;
- private errorStream: NodeJS.WriteStream;
-
- constructor(options: { color?: boolean } = {}) {
- this.colorEnabled = options.color ?? this.supportsColor();
- this.outputStream = process.stdout;
- this.errorStream = process.stderr;
- }
-
- private supportsColor(): boolean {
- // Check for NO_COLOR environment variable
- if (process.env.NO_COLOR !== undefined) return false;
-
- // Check for FORCE_COLOR environment variable
- if (process.env.FORCE_COLOR !== undefined) return true;
-
- // Check if stdout is a TTY
- return process.stdout.isTTY ?? false;
- }
-
- // ============================================
- // Color Methods
- // ============================================
-
- color(text: string, ...colors: ColorName[]): string {
- if (!this.colorEnabled) return text;
-
- const codes = colors.map(c => COLORS[c]).join('');
- return `${codes}${text}${COLORS.reset}`;
- }
-
- bold(text: string): string {
- return this.color(text, 'bold');
- }
-
- dim(text: string): string {
- return this.color(text, 'dim');
- }
-
- success(text: string): string {
- return this.color(text, 'green');
- }
-
- error(text: string): string {
- return this.color(text, 'red');
- }
-
- warning(text: string): string {
- return this.color(text, 'yellow');
- }
-
- info(text: string): string {
- return this.color(text, 'blue');
- }
-
- highlight(text: string): string {
- return this.color(text, 'cyan', 'bold');
- }
-
- // ============================================
- // Output Methods
- // ============================================
-
- write(text: string): void {
- this.outputStream.write(text);
- }
-
- writeln(text: string = ''): void {
- this.outputStream.write(text + '\n');
- }
-
- writeError(text: string): void {
- this.errorStream.write(text);
- }
-
- writeErrorln(text: string = ''): void {
- this.errorStream.write(text + '\n');
- }
-
- // ============================================
- // Formatted Output Methods
- // ============================================
-
- printSuccess(message: string): void {
- const icon = this.color('[OK]', 'green', 'bold');
- this.writeln(`${icon} ${message}`);
- }
-
- printError(message: string, details?: string): void {
- const icon = this.color('[ERROR]', 'red', 'bold');
- this.writeErrorln(`${icon} ${message}`);
- if (details) {
- this.writeErrorln(this.dim(` ${details}`));
- }
- }
-
- printWarning(message: string): void {
- const icon = this.color('[WARN]', 'yellow', 'bold');
- this.writeln(`${icon} ${message}`);
- }
-
- printInfo(message: string): void {
- const icon = this.color('[INFO]', 'blue', 'bold');
- this.writeln(`${icon} ${message}`);
- }
-
- printDebug(message: string): void {
- const icon = this.color('[DEBUG]', 'gray');
- this.writeln(`${icon} ${this.dim(message)}`);
- }
-
- // ============================================
- // Table Formatting
- // ============================================
-
- table(options: TableOptions): string {
- const { columns, data, border = true, header = true, padding = 1, maxWidth } = options;
-
- // Calculate column widths
- const widths = this.calculateColumnWidths(columns, data, maxWidth);
-
- const lines: string[] = [];
- const pad = ' '.repeat(padding);
-
- // Border characters
- const borderChars = border ? {
- topLeft: '+', topRight: '+', bottomLeft: '+', bottomRight: '+',
- horizontal: '-', vertical: '|',
- leftT: '+', rightT: '+', topT: '+', bottomT: '+', cross: '+'
- } : {
- topLeft: '', topRight: '', bottomLeft: '', bottomRight: '',
- horizontal: '', vertical: ' ',
- leftT: '', rightT: '', topT: '', bottomT: '', cross: ''
- };
-
- // Top border
- if (border) {
- lines.push(this.createBorderLine(widths, borderChars, 'top', padding));
- }
-
- // Header row
- if (header) {
- const headerRow = columns.map((col, i) => {
- const text = this.truncate(col.header, widths[i]);
- return pad + this.alignText(this.bold(text), widths[i], col.align) + pad;
- }).join(borderChars.vertical);
-
- lines.push(`${borderChars.vertical}${headerRow}${borderChars.vertical}`);
-
- // Header separator
- if (border) {
- lines.push(this.createBorderLine(widths, borderChars, 'middle', padding));
- }
- }
-
- // Data rows
- for (const row of data) {
- const rowCells = columns.map((col, i) => {
- let value = row[col.key];
-
- // Apply formatter if provided
- if (col.format) {
- value = col.format(value);
- } else {
- value = String(value ?? '');
- }
-
- const text = this.truncate(String(value), widths[i]);
- return pad + this.alignText(text, widths[i], col.align) + pad;
- }).join(borderChars.vertical);
-
- lines.push(`${borderChars.vertical}${rowCells}${borderChars.vertical}`);
- }
-
- // Bottom border
- if (border) {
- lines.push(this.createBorderLine(widths, borderChars, 'bottom', padding));
- }
-
- return lines.join('\n');
- }
-
- printTable(options: TableOptions): void {
- this.writeln(this.table(options));
- }
-
- private calculateColumnWidths(
- columns: TableColumn[],
- data: Record<string, unknown>[],
- maxWidth?: number
- ): number[] {
- const widths = columns.map((col, i) => {
- // Start with header width
- let width = col.header.length;
-
- // Check all data values
- for (const row of data) {
- let value = row[col.key];
- if (col.format) {
- value = col.format(value);
- }
- const len = this.stripAnsi(String(value ?? '')).length;
- width = Math.max(width, len);
- }
-
- // Apply column-specific width limit
- if (col.width) {
- width = Math.min(width, col.width);
- }
-
- return width;
- });
-
- // Apply max width constraint
- if (maxWidth) {
- const totalWidth = widths.reduce((a, b) => a + b, 0) + (columns.length * 3) + 1;
- if (totalWidth > maxWidth) {
- const reduction = (totalWidth - maxWidth) / columns.length;
- return widths.map(w => Math.max(3, Math.floor(w - reduction)));
- }
- }
-
- return widths;
- }
-
- private createBorderLine(
- widths: number[],
- chars: Record<string, string>,
- position: 'top' | 'middle' | 'bottom',
- padding: number
- ): string {
- const cellWidth = (w: number) => chars.horizontal.repeat(w + (padding * 2));
- const cells = widths.map(cellWidth).join(
- position === 'top' ? chars.topT :
- position === 'bottom' ? chars.bottomT :
- chars.cross
- );
-
- const left = position === 'top' ? chars.topLeft : position === 'bottom' ? chars.bottomLeft : chars.leftT;
- const right = position === 'top' ? chars.topRight : position === 'bottom' ? chars.bottomRight : chars.rightT;
-
- return `${left}${cells}${right}`;
- }
-
- private alignText(text: string, width: number, align: 'left' | 'center' | 'right' = 'left'): string {
- const len = this.stripAnsi(text).length;
- const padding = width - len;
-
- if (padding <= 0) return text;
-
- switch (align) {
- case 'right':
- return ' '.repeat(padding) + text;
- case 'center':
- const left = Math.floor(padding / 2);
- const right = padding - left;
- return ' '.repeat(left) + text + ' '.repeat(right);
- default:
- return text + ' '.repeat(padding);
- }
- }
-
- private truncate(text: string, maxLength: number): string {
- const stripped = this.stripAnsi(text);
- if (stripped.length <= maxLength) return text;
- return stripped.slice(0, maxLength - 3) + '...';
- }
-
- private stripAnsi(text: string): string {
- return text.replace(/\x1b\[[0-9;]*m/g, '');
- }
-
- // ============================================
- // Progress Bar
- // ============================================
-
- createProgress(options: ProgressOptions): Progress {
- return new Progress(this, options);
- }
-
- progressBar(current: number, total: number, width: number = 40): string {
- const percent = Math.min(100, Math.max(0, (current / total) * 100));
- const filled = Math.round((width * percent) / 100);
- const empty = width - filled;
-
- const bar = this.color('#'.repeat(filled), 'green') +
- this.dim('-'.repeat(empty));
-
- return `[${bar}] ${percent.toFixed(1)}%`;
- }
-
- // ============================================
- // Spinner
- // ============================================
-
- createSpinner(options: SpinnerOptions): Spinner {
- return new Spinner(this, options);
- }
-
- // ============================================
- // JSON Output
- // ============================================
-
- json(data: unknown, pretty: boolean = true): string {
- return pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
- }
-
- printJson(data: unknown, pretty: boolean = true): void {
- this.writeln(this.json(data, pretty));
- }
-
- // ============================================
- // List Output
- // ============================================
-
- list(items: string[], bullet: string = '-'): string {
- return items.map(item => ` ${bullet} ${item}`).join('\n');
- }
-
- printList(items: string[], bullet: string = '-'): void {
- this.writeln(this.list(items, bullet));
- }
-
- numberedList(items: string[]): string {
- return items.map((item, i) => ` ${i + 1}. ${item}`).join('\n');
- }
-
- printNumberedList(items: string[]): void {
- this.writeln(this.numberedList(items));
- }
-
- // ============================================
- // Box Output
- // ============================================
-
- box(content: string, title?: string): string {
- const lines = content.split('\n');
- const maxLen = Math.max(...lines.map(l => this.stripAnsi(l).length), title?.length ?? 0);
- const width = maxLen + 4;
-
- const border = {
- topLeft: '+', topRight: '+',
- bottomLeft: '+', bottomRight: '+',
- horizontal: '-', vertical: '|'
- };
-
- const result: string[] = [];
-
- // Top border with optional title
- if (title) {
- const titleText = ` ${title} `;
- const leftPad = Math.floor((width - titleText.length - 2) / 2);
- const rightPad = width - titleText.length - leftPad - 2;
- result.push(
- border.topLeft +
- border.horizontal.repeat(leftPad) +
- this.bold(titleText) +
- border.horizontal.repeat(rightPad) +
- border.topRight
- );
- } else {
- result.push(border.topLeft + border.horizontal.repeat(width - 2) + border.topRight);
- }
-
- // Content lines
- for (const line of lines) {
- const stripped = this.stripAnsi(line);
- const padding = maxLen - stripped.length;
- result.push(`${border.vertical} ${line}${' '.repeat(padding)} ${border.vertical}`);
- }
-
- // Bottom border
- result.push(border.bottomLeft + border.horizontal.repeat(width - 2) + border.bottomRight);
-
- return result.join('\n');
- }
-
- printBox(content: string, title?: string): void {
- this.writeln(this.box(content, title));
- }
-
- setColorEnabled(enabled: boolean): void {
- this.colorEnabled = enabled;
- }
-
- isColorEnabled(): boolean {
- return this.colorEnabled;
- }
-}
-
-// ============================================
-// Progress Class
-// ============================================
-
-export class Progress {
- private current: number;
- private total: number;
- private width: number;
- private startTime: number;
- private formatter: OutputFormatter;
- private showPercentage: boolean;
- private showETA: boolean;
- private lastRender: string = '';
-
- constructor(formatter: OutputFormatter, options: ProgressOptions) {
- this.formatter = formatter;
- this.current = options.current ?? 0;
- this.total = options.total;
- this.width = options.width ?? 40;
- this.showPercentage = options.showPercentage ?? true;
- this.showETA = options.showETA ?? true;
- this.startTime = Date.now();
- }
-
- update(current: number): void {
- this.current = current;
- this.render();
- }
-
- increment(amount: number = 1): void {
- this.update(this.current + amount);
- }
-
- render(): void {
- const bar = this.formatter.progressBar(this.current, this.total, this.width);
-
- let output = bar;
-
- if (this.showETA && this.current > 0) {
- const elapsed = Date.now() - this.startTime;
- const rate = this.current / elapsed;
- const remaining = this.total - this.current;
- const eta = remaining / rate;
-
- if (isFinite(eta)) {
- output += ` ETA: ${this.formatTime(eta)}`;
- }
- }
-
- // Clear previous line and write new
- if (this.lastRender) {
- process.stdout.write('\r' + ' '.repeat(this.lastRender.length) + '\r');
- }
-
- process.stdout.write(output);
- this.lastRender = output;
- }
-
- finish(): void {
- this.current = this.total;
- this.render();
- process.stdout.write('\n');
- }
-
- private formatTime(ms: number): string {
- const seconds = Math.floor(ms / 1000);
- const minutes = Math.floor(seconds / 60);
- const hours = Math.floor(minutes / 60);
-
- if (hours > 0) {
- return `${hours}h ${minutes % 60}m`;
- } else if (minutes > 0) {
- return `${minutes}m ${seconds % 60}s`;
- } else {
- return `${seconds}s`;
- }
- }
-}
-
-// ============================================
-// Spinner Class
-// ============================================
-
-export class Spinner {
- private formatter: OutputFormatter;
- private text: string;
- private frames: string[];
- private interval: ReturnType<typeof setInterval> | null = null;
- private frameIndex: number = 0;
-
- private static readonly SPINNERS: Record<string, string[]> = {
- dots: ['...', '..:' , '.::', ':::', '::.', ':..' ,],
- line: ['-', '\\', '|', '/'],
- arc: ['◜', '◠', '◝', '◞', '◡', '◟'],
- circle: ['◐', '◓', '◑', '◒'],
- arrows: ['←', '↖', '↑', '↗', '→', '↘', '↓', '↙']
- };
-
- constructor(formatter: OutputFormatter, options: SpinnerOptions) {
- this.formatter = formatter;
- this.text = options.text;
- this.frames = Spinner.SPINNERS[options.spinner ?? 'dots'];
- }
-
- start(): void {
- if (this.interval) return;
-
- this.interval = setInterval(() => {
- this.render();
- this.frameIndex = (this.frameIndex + 1) % this.frames.length;
- }, 100);
-
- this.render();
- }
-
- stop(message?: string): void {
- if (this.interval) {
- clearInterval(this.interval);
- this.interval = null;
- }
-
- // Clear the line
- process.stdout.write('\r' + ' '.repeat(this.text.length + 10) + '\r');
-
- if (message) {
- this.formatter.writeln(message);
- }
- }
-
- succeed(message?: string): void {
- this.stop(this.formatter.success(message ?? this.text));
- }
-
- fail(message?: string): void {
- this.stop(this.formatter.error(message ?? this.text));
- }
-
- private render(): void {
- const frame = this.formatter.info(this.frames[this.frameIndex]);
- process.stdout.write(`\r${frame} ${this.text}`);
- }
-
- setText(text: string): void {
- this.text = text;
- }
-}
-
-// Export singleton instance
-export const output = new OutputFormatter();
diff --git a/v3/cli/parser.ts b/v3/cli/parser.ts
deleted file mode 100644
index 40f344fd4d..0000000000
--- a/v3/cli/parser.ts
+++ /dev/null
@@ -1,397 +0,0 @@
-/**
- * V3 CLI Command Parser
- * Advanced argument parsing with validation and type coercion
- */
-
-import type { Command, CommandOption, ParsedFlags, CommandContext, V3Config } from './types.js';
-
-export interface ParseResult {
- command: string[];
- flags: ParsedFlags;
- positional: string[];
- raw: string[];
-}
-
-export interface ParserOptions {
- stopAtFirstNonFlag?: boolean;
- allowUnknownFlags?: boolean;
- booleanFlags?: string[];
- stringFlags?: string[];
- arrayFlags?: string[];
- aliases?: Record<string, string>;
- defaults?: Record<string, unknown>;
-}
-
-export class CommandParser {
- private options: ParserOptions;
- private commands: Map<string, Command> = new Map();
- private globalOptions: CommandOption[] = [];
-
- constructor(options: ParserOptions = {}) {
- this.options = {
- stopAtFirstNonFlag: false,
- allowUnknownFlags: false,
- ...options
- };
-
- this.initializeGlobalOptions();
- }
-
- private initializeGlobalOptions(): void {
- this.globalOptions = [
- {
- name: 'help',
- short: 'h',
- description: 'Show help information',
- type: 'boolean',
- default: false
- },
- {
- name: 'version',
- short: 'V',
- description: 'Show version number',
- type: 'boolean',
- default: false
- },
- {
- name: 'verbose',
- short: 'v',
- description: 'Enable verbose output',
- type: 'boolean',
- default: false
- },
- {
- name: 'quiet',
- short: 'q',
- description: 'Suppress non-essential output',
- type: 'boolean',
- default: false
- },
- {
- name: 'config',
- short: 'c',
- description: 'Path to configuration file',
- type: 'string'
- },
- {
- name: 'format',
- short: 'f',
- description: 'Output format (text, json, table)',
- type: 'string',
- default: 'text',
- choices: ['text', 'json', 'table']
- },
- {
- name: 'no-color',
- description: 'Disable colored output',
- type: 'boolean',
- default: false
- },
- {
- name: 'interactive',
- short: 'i',
- description: 'Enable interactive mode',
- type: 'boolean',
- default: true
- }
- ];
- }
-
- registerCommand(command: Command): void {
- this.commands.set(command.name, command);
- if (command.aliases) {
- for (const alias of command.aliases) {
- this.commands.set(alias, command);
- }
- }
- }
-
- getCommand(name: string): Command | undefined {
- return this.commands.get(name);
- }
-
- getAllCommands(): Command[] {
- // Return unique commands (filter out aliases)
- const seen = new Set<Command>();
- return Array.from(this.commands.values()).filter(cmd => {
- if (seen.has(cmd)) return false;
- seen.add(cmd);
- return true;
- });
- }
-
- parse(args: string[]): ParseResult {
- const result: ParseResult = {
- command: [],
- flags: { _: [] },
- positional: [],
- raw: [...args]
- };
-
- // Build flag configuration from global options
- const aliases = this.buildAliases();
- const booleanFlags = this.getBooleanFlags();
-
- let i = 0;
- let parsingFlags = true;
-
- while (i < args.length) {
- const arg = args[i];
-
- // Check for end of flags marker
- if (arg === '--') {
- parsingFlags = false;
- i++;
- continue;
- }
-
- // Handle flags
- if (parsingFlags && arg.startsWith('-')) {
- const parseResult = this.parseFlag(args, i, aliases, booleanFlags);
-
- // Apply to result flags
- Object.assign(result.flags, parseResult.flags);
- i = parseResult.nextIndex;
- continue;
- }
-
- // Handle positional arguments
- if (result.command.length === 0 && this.commands.has(arg)) {
- // This is a command
- result.command.push(arg);
-
- // Check for subcommand
- const cmd = this.commands.get(arg);
- if (cmd?.subcommands && i + 1 < args.length) {
- const nextArg = args[i + 1];
- const subCmd = cmd.subcommands.find(sc => sc.name === nextArg || sc.aliases?.includes(nextArg));
- if (subCmd) {
- result.command.push(nextArg);
- i++;
- }
- }
- } else {
- // Positional argument
- result.positional.push(arg);
- result.flags._.push(arg);
- }
-
- i++;
- }
-
- // Apply defaults
- this.applyDefaults(result.flags);
-
- return result;
- }
-
- private parseFlag(
- args: string[],
- index: number,
- aliases: Record<string, string>,
- booleanFlags: Set<string>
- ): { flags: ParsedFlags; nextIndex: number } {
- const flags: ParsedFlags = { _: [] };
- const arg = args[index];
- let nextIndex = index + 1;
-
- if (arg.startsWith('--')) {
- // Long flag
- const equalIndex = arg.indexOf('=');
-
- if (equalIndex !== -1) {
- // --flag=value
- const key = arg.slice(2, equalIndex);
- const value = arg.slice(equalIndex + 1);
- flags[this.normalizeKey(key)] = this.parseValue(value);
- } else if (arg.startsWith('--no-')) {
- // --no-flag (boolean negation)
- const key = arg.slice(5);
- flags[this.normalizeKey(key)] = false;
- } else {
- const key = arg.slice(2);
- const normalizedKey = this.normalizeKey(key);
-
- if (booleanFlags.has(normalizedKey)) {
- flags[normalizedKey] = true;
- } else if (nextIndex < args.length && !args[nextIndex].startsWith('-')) {
- flags[normalizedKey] = this.parseValue(args[nextIndex]);
- nextIndex++;
- } else {
- flags[normalizedKey] = true;
- }
- }
- } else if (arg.startsWith('-')) {
- // Short flag(s)
- const chars = arg.slice(1);
-
- if (chars.length === 1) {
- // Single short flag
- const key = aliases[chars] || chars;
- const normalizedKey = this.normalizeKey(key);
-
- if (booleanFlags.has(normalizedKey)) {
- flags[normalizedKey] = true;
- } else if (nextIndex < args.length && !args[nextIndex].startsWith('-')) {
- flags[normalizedKey] = this.parseValue(args[nextIndex]);
- nextIndex++;
- } else {
- flags[normalizedKey] = true;
- }
- } else {
- // Multiple short flags combined (e.g., -abc)
- for (const char of chars) {
- const key = aliases[char] || char;
- flags[this.normalizeKey(key)] = true;
- }
- }
- }
-
- return { flags, nextIndex };
- }
-
- private parseValue(value: string): string | number | boolean {
- // Boolean
- if (value.toLowerCase() === 'true') return true;
- if (value.toLowerCase() === 'false') return false;
-
- // Number
- const num = Number(value);
- if (!isNaN(num) && value.trim() !== '') return num;
-
- // String
- return value;
- }
-
- private normalizeKey(key: string): string {
- // Convert kebab-case to camelCase
- return key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
- }
-
- private buildAliases(): Record<string, string> {
- const aliases: Record<string, string> = {};
-
- for (const opt of this.globalOptions) {
- if (opt.short) {
- aliases[opt.short] = opt.name;
- }
- }
-
- // Add aliases from all commands
- for (const cmd of this.commands.values()) {
- if (cmd.options) {
- for (const opt of cmd.options) {
- if (opt.short) {
- aliases[opt.short] = opt.name;
- }
- }
- }
- }
-
- return { ...aliases, ...this.options.aliases };
- }
-
- private getBooleanFlags(): Set<string> {
- const flags = new Set<string>();
-
- for (const opt of this.globalOptions) {
- if (opt.type === 'boolean') {
- flags.add(this.normalizeKey(opt.name));
- }
- }
-
- // Add boolean flags from all commands
- for (const cmd of this.commands.values()) {
- if (cmd.options) {
- for (const opt of cmd.options) {
- if (opt.type === 'boolean') {
- flags.add(this.normalizeKey(opt.name));
- }
- }
- }
- }
-
- if (this.options.booleanFlags) {
- for (const flag of this.options.booleanFlags) {
- flags.add(this.normalizeKey(flag));
- }
- }
-
- return flags;
- }
-
- private applyDefaults(flags: ParsedFlags): void {
- // Apply global option defaults
- for (const opt of this.globalOptions) {
- const key = this.normalizeKey(opt.name);
- if (flags[key] === undefined && opt.default !== undefined) {
- flags[key] = opt.default as string | boolean | number | string[];
- }
- }
-
- // Apply custom defaults
- if (this.options.defaults) {
- for (const [key, value] of Object.entries(this.options.defaults)) {
- const normalizedKey = this.normalizeKey(key);
- if (flags[normalizedKey] === undefined) {
- flags[normalizedKey] = value as string | boolean | number | string[];
- }
- }
- }
- }
-
- validateFlags(flags: ParsedFlags, command?: Command): string[] {
- const errors: string[] = [];
- const allOptions = [...this.globalOptions];
-
- if (command?.options) {
- allOptions.push(...command.options);
- }
-
- // Check required flags
- for (const opt of allOptions) {
- const key = this.normalizeKey(opt.name);
-
- if (opt.required && (flags[key] === undefined || flags[key] === '')) {
- errors.push(`Required option missing: --${opt.name}`);
- }
-
- // Check choices
- if (opt.choices && flags[key] !== undefined) {
- const value = String(flags[key]);
- if (!opt.choices.includes(value)) {
- errors.push(`Invalid value for --${opt.name}: ${value}. Must be one of: ${opt.choices.join(', ')}`);
- }
- }
-
- // Run custom validator
- if (opt.validate && flags[key] !== undefined) {
- const result = opt.validate(flags[key]);
- if (result !== true) {
- errors.push(typeof result === 'string' ? result : `Invalid value for --${opt.name}`);
- }
- }
- }
-
- // Check for unknown flags if not allowed
- if (!this.options.allowUnknownFlags) {
- const knownFlags = new Set(allOptions.map(opt => this.normalizeKey(opt.name)));
- knownFlags.add('_'); // Positional args
-
- for (const key of Object.keys(flags)) {
- if (!knownFlags.has(key) && key !== '_') {
- errors.push(`Unknown option: --${key}`);
- }
- }
- }
-
- return errors;
- }
-
- getGlobalOptions(): CommandOption[] {
- return [...this.globalOptions];
- }
-}
-
-// Export singleton parser instance
-export const commandParser = new CommandParser({ allowUnknownFlags: true });
diff --git a/v3/cli/prompt.ts b/v3/cli/prompt.ts
deleted file mode 100644
index f8a5d6a191..0000000000
--- a/v3/cli/prompt.ts
+++ /dev/null
@@ -1,618 +0,0 @@
-/**
- * V3 CLI Interactive Prompt System
- * Modern interactive prompts for user input
- */
-
-import * as readline from 'readline';
-import type {
- SelectPromptOptions,
- SelectOption,
- ConfirmPromptOptions,
- InputPromptOptions,
- MultiSelectPromptOptions
-} from './types.js';
-import { output, OutputFormatter } from './output.js';
-
-// ============================================
-// Core Prompt Infrastructure
-// ============================================
-
-class PromptManager {
- private rl: readline.Interface | null = null;
- private formatter: OutputFormatter;
-
- constructor(formatter: OutputFormatter = output) {
- this.formatter = formatter;
- }
-
- private createInterface(): readline.Interface {
- if (!this.rl) {
- this.rl = readline.createInterface({
- input: process.stdin,
- output: process.stdout,
- terminal: true
- });
-
- // Handle cleanup on exit
- this.rl.on('close', () => {
- this.rl = null;
- });
- }
- return this.rl;
- }
-
- private close(): void {
- if (this.rl) {
- this.rl.close();
- this.rl = null;
- }
- }
-
- private async question(prompt: string): Promise<string> {
- return new Promise((resolve) => {
- const rl = this.createInterface();
- rl.question(prompt, (answer) => {
- resolve(answer);
- });
- });
- }
-
- // ============================================
- // Select Prompt
- // ============================================
-
- async select<T = string>(options: SelectPromptOptions<T>): Promise<T> {
- const { message, options: choices, default: defaultValue, pageSize = 10 } = options;
-
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.bold(`? ${message}`));
- this.formatter.writeln(this.formatter.dim(' (Use arrow keys to navigate, enter to select)'));
- this.formatter.writeln();
-
- // Find default index
- let selectedIndex = 0;
- if (defaultValue !== undefined) {
- const idx = choices.findIndex(c => c.value === defaultValue);
- if (idx !== -1) selectedIndex = idx;
- }
-
- // Display options
- const displayChoices = (currentIndex: number, startIndex: number = 0) => {
- // Move cursor up to overwrite
- if (startIndex > 0 || currentIndex > 0) {
- process.stdout.write(`\x1b[${Math.min(choices.length, pageSize)}A`);
- }
-
- const endIndex = Math.min(startIndex + pageSize, choices.length);
- for (let i = startIndex; i < endIndex; i++) {
- const choice = choices[i];
- const isSelected = i === currentIndex;
- const prefix = isSelected ? this.formatter.info('>') : ' ';
- const label = isSelected
- ? this.formatter.highlight(choice.label)
- : choice.label;
- const hint = choice.hint ? this.formatter.dim(` - ${choice.hint}`) : '';
- const disabled = choice.disabled ? this.formatter.dim(' (disabled)') : '';
-
- this.formatter.writeln(` ${prefix} ${label}${hint}${disabled}`);
- }
- };
-
- // Initial display
- displayChoices(selectedIndex);
-
- return new Promise<T>((resolve, reject) => {
- const rl = this.createInterface();
-
- // Enable raw mode for arrow key detection
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(true);
- }
- process.stdin.resume();
-
- const handleKeypress = (key: Buffer) => {
- const keyStr = key.toString();
-
- // Arrow keys
- if (keyStr === '\x1b[A') { // Up
- do {
- selectedIndex = (selectedIndex - 1 + choices.length) % choices.length;
- } while (choices[selectedIndex].disabled && selectedIndex !== 0);
- displayChoices(selectedIndex);
- } else if (keyStr === '\x1b[B') { // Down
- do {
- selectedIndex = (selectedIndex + 1) % choices.length;
- } while (choices[selectedIndex].disabled && selectedIndex !== choices.length - 1);
- displayChoices(selectedIndex);
- } else if (keyStr === '\r' || keyStr === '\n') { // Enter
- cleanup();
- const selected = choices[selectedIndex];
- if (!selected.disabled) {
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.success(`Selected: ${selected.label}`));
- resolve(selected.value);
- }
- } else if (keyStr === '\x03') { // Ctrl+C
- cleanup();
- reject(new Error('User cancelled'));
- }
- };
-
- const cleanup = () => {
- process.stdin.removeListener('data', handleKeypress);
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(false);
- }
- this.close();
- };
-
- process.stdin.on('data', handleKeypress);
- });
- }
-
- // ============================================
- // Confirm Prompt
- // ============================================
-
- async confirm(options: ConfirmPromptOptions): Promise<boolean> {
- const {
- message,
- default: defaultValue = false,
- active = 'Yes',
- inactive = 'No'
- } = options;
-
- const defaultText = defaultValue ? `${active}/${inactive}` : `${active}/${inactive}`;
- const hint = defaultValue ? `[${active}]` : `[${inactive}]`;
-
- const prompt = `${this.formatter.bold('?')} ${message} ${this.formatter.dim(hint)} `;
-
- const answer = await this.question(prompt);
- this.close();
-
- if (answer === '') {
- return defaultValue;
- }
-
- const normalized = answer.toLowerCase().trim();
-
- if (['y', 'yes', 'true', '1'].includes(normalized)) {
- return true;
- }
-
- if (['n', 'no', 'false', '0'].includes(normalized)) {
- return false;
- }
-
- return defaultValue;
- }
-
- // ============================================
- // Input Prompt
- // ============================================
-
- async input(options: InputPromptOptions): Promise<string> {
- const {
- message,
- default: defaultValue,
- placeholder,
- validate,
- mask
- } = options;
-
- let prompt = `${this.formatter.bold('?')} ${message}`;
-
- if (defaultValue) {
- prompt += ` ${this.formatter.dim(`(${defaultValue})`)}`;
- } else if (placeholder) {
- prompt += ` ${this.formatter.dim(placeholder)}`;
- }
-
- prompt += ': ';
-
- while (true) {
- let answer: string;
-
- if (mask) {
- answer = await this.inputMasked(prompt);
- } else {
- answer = await this.question(prompt);
- }
-
- // Use default if empty
- if (answer === '' && defaultValue !== undefined) {
- answer = defaultValue;
- }
-
- // Validate
- if (validate) {
- const result = validate(answer);
- if (result !== true) {
- const errorMsg = typeof result === 'string' ? result : 'Invalid input';
- this.formatter.writeln(this.formatter.error(` ${errorMsg}`));
- continue;
- }
- }
-
- this.close();
- return answer;
- }
- }
-
- private async inputMasked(prompt: string): Promise<string> {
- return new Promise((resolve) => {
- const rl = this.createInterface();
- let password = '';
-
- // Don't echo characters
- process.stdout.write(prompt);
-
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(true);
- }
- process.stdin.resume();
-
- const handleData = (chunk: Buffer) => {
- const char = chunk.toString();
-
- if (char === '\n' || char === '\r') {
- // Enter pressed
- process.stdin.removeListener('data', handleData);
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(false);
- }
- process.stdout.write('\n');
- resolve(password);
- } else if (char === '\x7f' || char === '\x08') {
- // Backspace
- if (password.length > 0) {
- password = password.slice(0, -1);
- process.stdout.write('\b \b');
- }
- } else if (char === '\x03') {
- // Ctrl+C
- process.stdin.removeListener('data', handleData);
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(false);
- }
- resolve('');
- } else if (char.charCodeAt(0) >= 32) {
- // Printable character
- password += char;
- process.stdout.write('*');
- }
- };
-
- process.stdin.on('data', handleData);
- });
- }
-
- // ============================================
- // Multi-Select Prompt
- // ============================================
-
- async multiSelect<T = string>(options: MultiSelectPromptOptions<T>): Promise<T[]> {
- const {
- message,
- options: choices,
- default: defaultValues = [],
- required = false,
- min,
- max
- } = options;
-
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.bold(`? ${message}`));
- this.formatter.writeln(this.formatter.dim(' (Use arrow keys to navigate, space to select, enter to confirm)'));
- this.formatter.writeln();
-
- // Initialize selection state
- const selected = new Set<number>();
- for (let i = 0; i < choices.length; i++) {
- if (defaultValues.includes(choices[i].value)) {
- selected.add(i);
- }
- }
-
- let currentIndex = 0;
-
- // Display options
- const displayChoices = () => {
- // Move cursor up to overwrite
- process.stdout.write(`\x1b[${choices.length}A`);
-
- for (let i = 0; i < choices.length; i++) {
- const choice = choices[i];
- const isCurrentRow = i === currentIndex;
- const isSelected = selected.has(i);
-
- const cursor = isCurrentRow ? this.formatter.info('>') : ' ';
- const checkbox = isSelected
- ? this.formatter.success('[x]')
- : this.formatter.dim('[ ]');
- const label = isCurrentRow
- ? this.formatter.highlight(choice.label)
- : choice.label;
- const hint = choice.hint ? this.formatter.dim(` - ${choice.hint}`) : '';
- const disabled = choice.disabled ? this.formatter.dim(' (disabled)') : '';
-
- this.formatter.writeln(` ${cursor} ${checkbox} ${label}${hint}${disabled}`);
- }
- };
-
- // Initial display
- for (let i = 0; i < choices.length; i++) {
- this.formatter.writeln('');
- }
- displayChoices();
-
- return new Promise<T[]>((resolve, reject) => {
- const rl = this.createInterface();
-
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(true);
- }
- process.stdin.resume();
-
- const handleKeypress = (key: Buffer) => {
- const keyStr = key.toString();
-
- if (keyStr === '\x1b[A') { // Up
- currentIndex = (currentIndex - 1 + choices.length) % choices.length;
- displayChoices();
- } else if (keyStr === '\x1b[B') { // Down
- currentIndex = (currentIndex + 1) % choices.length;
- displayChoices();
- } else if (keyStr === ' ') { // Space
- if (!choices[currentIndex].disabled) {
- if (selected.has(currentIndex)) {
- selected.delete(currentIndex);
- } else {
- // Check max limit
- if (!max || selected.size < max) {
- selected.add(currentIndex);
- }
- }
- displayChoices();
- }
- } else if (keyStr === '\r' || keyStr === '\n') { // Enter
- // Validate selection
- if (required && selected.size === 0) {
- this.formatter.writeln(this.formatter.error(' At least one option must be selected'));
- return;
- }
- if (min && selected.size < min) {
- this.formatter.writeln(this.formatter.error(` At least ${min} options must be selected`));
- return;
- }
-
- cleanup();
- const selectedValues = Array.from(selected).map(i => choices[i].value);
- const selectedLabels = Array.from(selected).map(i => choices[i].label);
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.success(`Selected: ${selectedLabels.join(', ')}`));
- resolve(selectedValues);
- } else if (keyStr === '\x03') { // Ctrl+C
- cleanup();
- reject(new Error('User cancelled'));
- } else if (keyStr === 'a') { // Select all
- if (!max || choices.length <= max) {
- for (let i = 0; i < choices.length; i++) {
- if (!choices[i].disabled) {
- selected.add(i);
- }
- }
- displayChoices();
- }
- } else if (keyStr === 'n') { // Select none
- selected.clear();
- displayChoices();
- }
- };
-
- const cleanup = () => {
- process.stdin.removeListener('data', handleKeypress);
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(false);
- }
- this.close();
- };
-
- process.stdin.on('data', handleKeypress);
- });
- }
-
- // ============================================
- // Text Prompt (Multi-line)
- // ============================================
-
- async text(message: string, placeholder?: string): Promise<string> {
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.bold(`? ${message}`));
- if (placeholder) {
- this.formatter.writeln(this.formatter.dim(` ${placeholder}`));
- }
- this.formatter.writeln(this.formatter.dim(' (Enter an empty line to finish)'));
- this.formatter.writeln();
-
- const lines: string[] = [];
-
- while (true) {
- const line = await this.question(' > ');
- if (line === '') {
- break;
- }
- lines.push(line);
- }
-
- this.close();
- return lines.join('\n');
- }
-
- // ============================================
- // Number Prompt
- // ============================================
-
- async number(
- message: string,
- options: { default?: number; min?: number; max?: number; } = {}
- ): Promise<number> {
- const { default: defaultValue, min, max } = options;
-
- const validate = (value: string): boolean | string => {
- const num = Number(value);
- if (isNaN(num)) {
- return 'Please enter a valid number';
- }
- if (min !== undefined && num < min) {
- return `Value must be at least ${min}`;
- }
- if (max !== undefined && num > max) {
- return `Value must be at most ${max}`;
- }
- return true;
- };
-
- const result = await this.input({
- message,
- default: defaultValue?.toString(),
- validate
- });
-
- return Number(result);
- }
-
- // ============================================
- // Autocomplete Prompt
- // ============================================
-
- async autocomplete<T = string>(
- message: string,
- choices: SelectOption<T>[],
- options: { limit?: number } = {}
- ): Promise<T> {
- const { limit = 10 } = options;
-
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.bold(`? ${message}`));
- this.formatter.writeln(this.formatter.dim(' (Type to filter, arrow keys to navigate)'));
-
- let query = '';
- let selectedIndex = 0;
- let filteredChoices = choices.slice(0, limit);
-
- const filterChoices = (q: string): SelectOption<T>[] => {
- if (q === '') return choices.slice(0, limit);
-
- const normalized = q.toLowerCase();
- return choices
- .filter(c => c.label.toLowerCase().includes(normalized))
- .slice(0, limit);
- };
-
- const displayChoices = () => {
- // Clear previous output
- process.stdout.write(`\x1b[${filteredChoices.length + 1}A`);
- process.stdout.write('\x1b[J');
-
- // Show input
- this.formatter.writeln(` ${this.formatter.dim('>')} ${query}`);
-
- // Show filtered options
- for (let i = 0; i < filteredChoices.length; i++) {
- const choice = filteredChoices[i];
- const isSelected = i === selectedIndex;
- const prefix = isSelected ? this.formatter.info('>') : ' ';
- const label = isSelected ? this.formatter.highlight(choice.label) : choice.label;
- this.formatter.writeln(` ${prefix} ${label}`);
- }
- };
-
- // Initial display
- this.formatter.writeln('');
- for (let i = 0; i < limit; i++) {
- this.formatter.writeln('');
- }
- displayChoices();
-
- return new Promise<T>((resolve, reject) => {
- const rl = this.createInterface();
-
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(true);
- }
- process.stdin.resume();
-
- const handleKeypress = (key: Buffer) => {
- const keyStr = key.toString();
-
- if (keyStr === '\x1b[A') { // Up
- selectedIndex = Math.max(0, selectedIndex - 1);
- displayChoices();
- } else if (keyStr === '\x1b[B') { // Down
- selectedIndex = Math.min(filteredChoices.length - 1, selectedIndex + 1);
- displayChoices();
- } else if (keyStr === '\r' || keyStr === '\n') { // Enter
- if (filteredChoices.length > 0) {
- cleanup();
- const selected = filteredChoices[selectedIndex];
- this.formatter.writeln();
- this.formatter.writeln(this.formatter.success(`Selected: ${selected.label}`));
- resolve(selected.value);
- }
- } else if (keyStr === '\x7f' || keyStr === '\x08') { // Backspace
- query = query.slice(0, -1);
- filteredChoices = filterChoices(query);
- selectedIndex = 0;
- displayChoices();
- } else if (keyStr === '\x03') { // Ctrl+C
- cleanup();
- reject(new Error('User cancelled'));
- } else if (keyStr.charCodeAt(0) >= 32 && keyStr.charCodeAt(0) < 127) {
- // Printable character
- query += keyStr;
- filteredChoices = filterChoices(query);
- selectedIndex = 0;
- displayChoices();
- }
- };
-
- const cleanup = () => {
- process.stdin.removeListener('data', handleKeypress);
- if (process.stdin.isTTY) {
- process.stdin.setRawMode(false);
- }
- this.close();
- };
-
- process.stdin.on('data', handleKeypress);
- });
- }
-}
-
-// Export singleton and convenience functions
-export const promptManager = new PromptManager();
-
-export const select = <T = string>(options: SelectPromptOptions<T>) =>
- promptManager.select(options);
-
-export const confirm = (options: ConfirmPromptOptions) =>
- promptManager.confirm(options);
-
-export const input = (options: InputPromptOptions) =>
- promptManager.input(options);
-
-export const multiSelect = <T = string>(options: MultiSelectPromptOptions<T>) =>
- promptManager.multiSelect(options);
-
-export const text = (message: string, placeholder?: string) =>
- promptManager.text(message, placeholder);
-
-export const number = (message: string, options?: { default?: number; min?: number; max?: number }) =>
- promptManager.number(message, options);
-
-export const autocomplete = <T = string>(
- message: string,
- choices: SelectOption<T>[],
- options?: { limit?: number }
-) => promptManager.autocomplete(message, choices, options);
diff --git a/v3/cli/types.ts b/v3/cli/types.ts
deleted file mode 100644
index d118ff1546..0000000000
--- a/v3/cli/types.ts
+++ /dev/null
@@ -1,285 +0,0 @@
-/**
- * V3 CLI Type Definitions
- * Modernized type system for the Claude Flow V3 CLI
- */
-
-// ============================================
-// Core Command Types
-// ============================================
-
-export interface CommandContext {
- args: string[];
- flags: ParsedFlags;
- config?: V3Config;
- cwd: string;
- interactive: boolean;
-}
-
-export interface ParsedFlags {
- [key: string]: string | boolean | number | string[];
- _: string[];
-}
-
-export interface Command {
- name: string;
- description: string;
- aliases?: string[];
- subcommands?: Command[];
- options?: CommandOption[];
- examples?: CommandExample[];
- action?: CommandAction;
- hidden?: boolean;
-}
-
-export interface CommandOption {
- name: string;
- short?: string;
- description: string;
- type: 'string' | 'boolean' | 'number' | 'array';
- default?: unknown;
- required?: boolean;
- choices?: string[];
- validate?: (value: unknown) => boolean | string;
-}
-
-export interface CommandExample {
- command: string;
- description: string;
-}
-
-export type CommandAction = (ctx: CommandContext) => Promise<CommandResult | void>;
-
-export interface CommandResult {
- success: boolean;
- message?: string;
- data?: unknown;
- exitCode?: number;
-}
-
-// ============================================
-// Configuration Types
-// ============================================
-
-export interface V3Config {
- version: string;
- projectRoot: string;
-
- // Agent configuration
- agents: AgentConfig;
-
- // Swarm configuration
- swarm: SwarmConfig;
-
- // Memory configuration
- memory: MemoryConfig;
-
- // MCP configuration
- mcp: MCPConfig;
-
- // CLI preferences
- cli: CLIPreferences;
-
- // Hooks configuration
- hooks: HooksConfig;
-}
-
-export interface AgentConfig {
- defaultType: string;
- autoSpawn: boolean;
- maxConcurrent: number;
- timeout: number;
- providers: ProviderConfig[];
-}
-
-export interface ProviderConfig {
- name: string;
- apiKey?: string;
- baseUrl?: string;
- model?: string;
- priority: number;
- enabled: boolean;
-}
-
-export interface SwarmConfig {
- topology: 'hierarchical' | 'mesh' | 'ring' | 'star' | 'hybrid';
- maxAgents: number;
- autoScale: boolean;
- coordinationStrategy: 'consensus' | 'leader' | 'distributed';
- healthCheckInterval: number;
-}
-
-export interface MemoryConfig {
- backend: 'agentdb' | 'sqlite' | 'memory' | 'hybrid';
- persistPath: string;
- cacheSize: number;
- enableHNSW: boolean;
- vectorDimension: number;
-}
-
-export interface MCPConfig {
- serverHost: string;
- serverPort: number;
- autoStart: boolean;
- transportType: 'stdio' | 'http' | 'websocket';
- tools: string[];
-}
-
-export interface CLIPreferences {
- colorOutput: boolean;
- interactive: boolean;
- verbosity: 'quiet' | 'normal' | 'verbose' | 'debug';
- outputFormat: 'text' | 'json' | 'table';
- progressStyle: 'bar' | 'spinner' | 'dots' | 'none';
-}
-
-export interface HooksConfig {
- enabled: boolean;
- autoExecute: boolean;
- hooks: HookDefinition[];
-}
-
-export interface HookDefinition {
- name: string;
- event: string;
- handler: string;
- priority: number;
- enabled: boolean;
-}
-
-// ============================================
-// Output Types
-// ============================================
-
-export interface TableColumn {
- key: string;
- header: string;
- width?: number;
- align?: 'left' | 'center' | 'right';
- format?: (value: unknown) => string;
-}
-
-export interface TableOptions {
- columns: TableColumn[];
- data: Record<string, unknown>[];
- border?: boolean;
- header?: boolean;
- padding?: number;
- maxWidth?: number;
-}
-
-export interface ProgressOptions {
- total: number;
- current?: number;
- width?: number;
- format?: string;
- showPercentage?: boolean;
- showETA?: boolean;
- showSpeed?: boolean;
-}
-
-export interface SpinnerOptions {
- text: string;
- spinner?: 'dots' | 'line' | 'arc' | 'circle' | 'arrows';
- color?: string;
-}
-
-// ============================================
-// Prompt Types
-// ============================================
-
-export interface SelectOption<T = string> {
- value: T;
- label: string;
- hint?: string;
- disabled?: boolean;
-}
-
-export interface SelectPromptOptions<T = string> {
- message: string;
- options: SelectOption<T>[];
- default?: T;
- searchable?: boolean;
- pageSize?: number;
-}
-
-export interface ConfirmPromptOptions {
- message: string;
- default?: boolean;
- active?: string;
- inactive?: string;
-}
-
-export interface InputPromptOptions {
- message: string;
- default?: string;
- placeholder?: string;
- validate?: (value: string) => boolean | string;
- mask?: boolean;
-}
-
-export interface MultiSelectPromptOptions<T = string> {
- message: string;
- options: SelectOption<T>[];
- default?: T[];
- required?: boolean;
- min?: number;
- max?: number;
-}
-
-// ============================================
-// Event Types
-// ============================================
-
-export type CLIEventType =
- | 'command:start'
- | 'command:end'
- | 'command:error'
- | 'prompt:start'
- | 'prompt:complete'
- | 'output:write'
- | 'progress:update'
- | 'spinner:start'
- | 'spinner:stop';
-
-export interface CLIEvent {
- type: CLIEventType;
- timestamp: number;
- data?: unknown;
-}
-
-// ============================================
-// Error Types
-// ============================================
-
-export class CLIError extends Error {
- constructor(
- message: string,
- public code: string,
- public exitCode: number = 1,
- public details?: unknown
- ) {
- super(message);
- this.name = 'CLIError';
- }
-}
-
-export class ValidationError extends CLIError {
- constructor(message: string, details?: unknown) {
- super(message, 'VALIDATION_ERROR', 1, details);
- this.name = 'ValidationError';
- }
-}
-
-export class ConfigError extends CLIError {
- constructor(message: string, details?: unknown) {
- super(message, 'CONFIG_ERROR', 1, details);
- this.name = 'ConfigError';
- }
-}
-
-export class CommandNotFoundError extends CLIError {
- constructor(commandName: string) {
- super(`Unknown command: ${commandName}`, 'COMMAND_NOT_FOUND', 127);
- this.name = 'CommandNotFoundError';
- }
-}
diff --git a/v3/coordination/agent-registry.ts b/v3/coordination/agent-registry.ts
new file mode 100644
index 0000000000..b7e5899feb
--- /dev/null
+++ b/v3/coordination/agent-registry.ts
@@ -0,0 +1,544 @@
+/**
+ * V3 Agent Registry
+ * Manages registration, lifecycle, and capabilities of all 15 agents
+ *
+ * Based on ADR-002 (DDD) and 15-Agent Swarm Architecture
+ */
+
+import {
+ AgentId,
+ AgentRole,
+ AgentDomain,
+ AgentStatus,
+ AgentDefinition,
+ AgentState,
+ AgentCapability,
+ AgentMetrics,
+ TaskType,
+ TaskId,
+ SwarmEvent,
+ EventHandler
+} from '../shared/types';
+import {
+ IEventBus,
+ agentSpawnedEvent,
+ agentStatusChangedEvent,
+ agentErrorEvent
+} from '../shared/events';
+
+// =============================================================================
+// Agent Registry Interface
+// =============================================================================
+
+export interface IAgentRegistry {
+ // Registration
+ register(definition: AgentDefinition): void;
+ unregister(agentId: AgentId): boolean;
+ isRegistered(agentId: AgentId): boolean;
+
+ // Lifecycle
+ spawn(agentId: AgentId): Promise<AgentState>;
+ terminate(agentId: AgentId): Promise<boolean>;
+
+ // State Management
+ getState(agentId: AgentId): AgentState | undefined;
+ updateStatus(agentId: AgentId, status: AgentStatus): void;
+ assignTask(agentId: AgentId, taskId: TaskId): void;
+ completeTask(agentId: AgentId, taskId: TaskId): void;
+
+ // Queries
+ getDefinition(agentId: AgentId): AgentDefinition | undefined;
+ getAllAgents(): AgentDefinition[];
+ getActiveAgents(): AgentState[];
+ getAgentsByDomain(domain: AgentDomain): AgentDefinition[];
+ getAgentsByCapability(taskType: TaskType): AgentDefinition[];
+
+ // Health
+ heartbeat(agentId: AgentId): void;
+ getHealthStatus(): Map<AgentId, HealthStatus>;
+
+ // Events
+ onAgentEvent(handler: EventHandler): () => void;
+}
+
+export interface HealthStatus {
+ agentId: AgentId;
+ healthy: boolean;
+ lastHeartbeat: number;
+ consecutiveMisses: number;
+ status: AgentStatus;
+}
+
+// =============================================================================
+// Agent Registry Implementation
+// =============================================================================
+
+export class AgentRegistry implements IAgentRegistry {
+ private definitions: Map<AgentId, AgentDefinition> = new Map();
+ private states: Map<AgentId, AgentState> = new Map();
+ private healthChecks: Map<AgentId, HealthStatus> = new Map();
+ private eventBus: IEventBus;
+ private healthCheckInterval: number = 5000;
+ private healthCheckTimer: ReturnType<typeof setInterval> | null = null;
+ private maxMissedHeartbeats: number = 3;
+
+ constructor(eventBus: IEventBus) {
+ this.eventBus = eventBus;
+ this.registerDefaultAgents();
+ }
+
+ // ==========================================================================
+ // Registration
+ // ==========================================================================
+
+ register(definition: AgentDefinition): void {
+ if (this.definitions.has(definition.id)) {
+ throw new Error(`Agent ${definition.id} is already registered`);
+ }
+
+ this.definitions.set(definition.id, definition);
+
+ this.healthChecks.set(definition.id, {
+ agentId: definition.id,
+ healthy: false,
+ lastHeartbeat: 0,
+ consecutiveMisses: 0,
+ status: 'idle'
+ });
+ }
+
+ unregister(agentId: AgentId): boolean {
+ if (this.states.has(agentId)) {
+ throw new Error(`Cannot unregister active agent ${agentId}`);
+ }
+
+ this.healthChecks.delete(agentId);
+ return this.definitions.delete(agentId);
+ }
+
+ isRegistered(agentId: AgentId): boolean {
+ return this.definitions.has(agentId);
+ }
+
+ // ==========================================================================
+ // Lifecycle
+ // ==========================================================================
+
+ async spawn(agentId: AgentId): Promise<AgentState> {
+ const definition = this.definitions.get(agentId);
+ if (!definition) {
+ throw new Error(`Agent ${agentId} is not registered`);
+ }
+
+ if (this.states.has(agentId)) {
+ throw new Error(`Agent ${agentId} is already spawned`);
+ }
+
+ const state: AgentState = {
+ id: agentId,
+ role: definition.role,
+ status: 'idle',
+ currentTask: null,
+ completedTasks: [],
+ metrics: this.createInitialMetrics(),
+ lastHeartbeat: Date.now()
+ };
+
+ this.states.set(agentId, state);
+
+ const healthStatus = this.healthChecks.get(agentId)!;
+ healthStatus.healthy = true;
+ healthStatus.lastHeartbeat = Date.now();
+ healthStatus.status = 'idle';
+
+ await this.eventBus.emit(agentSpawnedEvent(agentId, definition.role));
+
+ return state;
+ }
+
+ async terminate(agentId: AgentId): Promise<boolean> {
+ const state = this.states.get(agentId);
+ if (!state) {
+ return false;
+ }
+
+ if (state.currentTask) {
+ throw new Error(`Cannot terminate agent ${agentId} with active task ${state.currentTask}`);
+ }
+
+ this.states.delete(agentId);
+
+ const healthStatus = this.healthChecks.get(agentId);
+ if (healthStatus) {
+ healthStatus.healthy = false;
+ healthStatus.status = 'idle';
+ }
+
+ await this.eventBus.emit(agentStatusChangedEvent(agentId, state.status, 'terminated'));
+
+ return true;
+ }
+
+ // ==========================================================================
+ // State Management
+ // ==========================================================================
+
+ getState(agentId: AgentId): AgentState | undefined {
+ return this.states.get(agentId);
+ }
+
+ updateStatus(agentId: AgentId, status: AgentStatus): void {
+ const state = this.states.get(agentId);
+ if (!state) {
+ throw new Error(`Agent ${agentId} is not spawned`);
+ }
+
+ const previousStatus = state.status;
+ state.status = status;
+
+ const healthStatus = this.healthChecks.get(agentId);
+ if (healthStatus) {
+ healthStatus.status = status;
+ }
+
+ this.eventBus.emitSync(agentStatusChangedEvent(agentId, previousStatus, status));
+ }
+
+ assignTask(agentId: AgentId, taskId: TaskId): void {
+ const state = this.states.get(agentId);
+ if (!state) {
+ throw new Error(`Agent ${agentId} is not spawned`);
+ }
+
+ if (state.currentTask) {
+ throw new Error(`Agent ${agentId} already has task ${state.currentTask}`);
+ }
+
+ state.currentTask = taskId;
+ this.updateStatus(agentId, 'active');
+ }
+
+ completeTask(agentId: AgentId, taskId: TaskId): void {
+ const state = this.states.get(agentId);
+ if (!state) {
+ throw new Error(`Agent ${agentId} is not spawned`);
+ }
+
+ if (state.currentTask !== taskId) {
+ throw new Error(`Agent ${agentId} current task is ${state.currentTask}, not ${taskId}`);
+ }
+
+ state.completedTasks.push(taskId);
+ state.currentTask = null;
+ state.metrics.tasksCompleted++;
+
+ this.updateStatus(agentId, 'idle');
+ }
+
+ // ==========================================================================
+ // Queries
+ // ==========================================================================
+
+ getDefinition(agentId: AgentId): AgentDefinition | undefined {
+ return this.definitions.get(agentId);
+ }
+
+ getAllAgents(): AgentDefinition[] {
+ return Array.from(this.definitions.values());
+ }
+
+ getActiveAgents(): AgentState[] {
+ return Array.from(this.states.values()).filter(s => s.status === 'active');
+ }
+
+ getAgentsByDomain(domain: AgentDomain): AgentDefinition[] {
+ return Array.from(this.definitions.values()).filter(d => d.domain === domain);
+ }
+
+ getAgentsByCapability(taskType: TaskType): AgentDefinition[] {
+ return Array.from(this.definitions.values()).filter(d =>
+ d.capabilities.some(c => c.supportedTaskTypes.includes(taskType))
+ );
+ }
+
+ // ==========================================================================
+ // Health Management
+ // ==========================================================================
+
+ heartbeat(agentId: AgentId): void {
+ const state = this.states.get(agentId);
+ if (state) {
+ state.lastHeartbeat = Date.now();
+ }
+
+ const healthStatus = this.healthChecks.get(agentId);
+ if (healthStatus) {
+ healthStatus.lastHeartbeat = Date.now();
+ healthStatus.consecutiveMisses = 0;
+ healthStatus.healthy = true;
+ }
+ }
+
+ getHealthStatus(): Map<AgentId, HealthStatus> {
+ return new Map(this.healthChecks);
+ }
+
+ startHealthChecks(): void {
+ if (this.healthCheckTimer) {
+ return;
+ }
+
+ this.healthCheckTimer = setInterval(() => {
+ this.performHealthCheck();
+ }, this.healthCheckInterval);
+ }
+
+ stopHealthChecks(): void {
+ if (this.healthCheckTimer) {
+ clearInterval(this.healthCheckTimer);
+ this.healthCheckTimer = null;
+ }
+ }
+
+ private performHealthCheck(): void {
+ const now = Date.now();
+
+ for (const [agentId, healthStatus] of this.healthChecks) {
+ const state = this.states.get(agentId);
+ if (!state) {
+ continue;
+ }
+
+ const timeSinceHeartbeat = now - healthStatus.lastHeartbeat;
+
+ if (timeSinceHeartbeat > this.healthCheckInterval) {
+ healthStatus.consecutiveMisses++;
+
+ if (healthStatus.consecutiveMisses >= this.maxMissedHeartbeats) {
+ healthStatus.healthy = false;
+ this.updateStatus(agentId, 'error');
+
+ this.eventBus.emitSync(agentErrorEvent(
+ agentId,
+ new Error(`Agent ${agentId} missed ${healthStatus.consecutiveMisses} heartbeats`)
+ ));
+ }
+ }
+ }
+ }
+
+ // ==========================================================================
+ // Events
+ // ==========================================================================
+
+ onAgentEvent(handler: EventHandler): () => void {
+ const unsubscribers = [
+ this.eventBus.subscribe('agent:spawned', handler),
+ this.eventBus.subscribe('agent:status-changed', handler),
+ this.eventBus.subscribe('agent:task-assigned', handler),
+ this.eventBus.subscribe('agent:task-completed', handler),
+ this.eventBus.subscribe('agent:error', handler)
+ ];
+
+ return () => {
+ unsubscribers.forEach(unsub => unsub());
+ };
+ }
+
+ // ==========================================================================
+ // Default Agent Registration
+ // ==========================================================================
+
+ private registerDefaultAgents(): void {
+ const agentDefinitions: AgentDefinition[] = [
+ {
+ id: 'agent-1',
+ role: 'queen-coordinator',
+ domain: 'core',
+ description: 'Orchestration & GitHub Issue management for all 15 agents',
+ capabilities: [
+ { name: 'orchestration', description: 'Coordinate all agents', supportedTaskTypes: ['architecture-design'] },
+ { name: 'github-management', description: 'Manage GitHub issues and PRs', supportedTaskTypes: ['documentation'] }
+ ],
+ dependencies: [],
+ priority: 1
+ },
+ {
+ id: 'agent-2',
+ role: 'security-architect',
+ domain: 'security',
+ description: 'Security architecture review and design',
+ capabilities: [
+ { name: 'security-design', description: 'Design security architecture', supportedTaskTypes: ['security-audit', 'architecture-design'] }
+ ],
+ dependencies: [],
+ priority: 2
+ },
+ {
+ id: 'agent-3',
+ role: 'security-implementer',
+ domain: 'security',
+ description: 'CVE fixes and security code implementation',
+ capabilities: [
+ { name: 'security-implementation', description: 'Implement security fixes', supportedTaskTypes: ['security-fix', 'implementation'] }
+ ],
+ dependencies: ['agent-2'],
+ priority: 2
+ },
+ {
+ id: 'agent-4',
+ role: 'security-tester',
+ domain: 'security',
+ description: 'Security testing using TDD London School methodology',
+ capabilities: [
+ { name: 'security-testing', description: 'Write and run security tests', supportedTaskTypes: ['security-test', 'test-writing'] }
+ ],
+ dependencies: ['agent-2'],
+ priority: 2
+ },
+ {
+ id: 'agent-5',
+ role: 'core-architect',
+ domain: 'core',
+ description: 'Core module DDD architecture design',
+ capabilities: [
+ { name: 'architecture', description: 'Design core architecture', supportedTaskTypes: ['architecture-design'] }
+ ],
+ dependencies: ['agent-2'],
+ priority: 3
+ },
+ {
+ id: 'agent-6',
+ role: 'core-implementer',
+ domain: 'core',
+ description: 'Core module implementation and type system modernization',
+ capabilities: [
+ { name: 'core-implementation', description: 'Implement core modules', supportedTaskTypes: ['implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 3
+ },
+ {
+ id: 'agent-7',
+ role: 'memory-specialist',
+ domain: 'core',
+ description: 'Memory system unification with AgentDB (150x-12500x improvement)',
+ capabilities: [
+ { name: 'memory-optimization', description: 'Optimize memory systems', supportedTaskTypes: ['memory-optimization', 'implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 4
+ },
+ {
+ id: 'agent-8',
+ role: 'swarm-specialist',
+ domain: 'core',
+ description: 'Single SwarmCoordinator (merge 4 systems)',
+ capabilities: [
+ { name: 'swarm-coordination', description: 'Design swarm coordination', supportedTaskTypes: ['swarm-coordination', 'implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 4
+ },
+ {
+ id: 'agent-9',
+ role: 'mcp-specialist',
+ domain: 'core',
+ description: 'MCP server optimization and enhancement',
+ capabilities: [
+ { name: 'mcp-optimization', description: 'Optimize MCP server', supportedTaskTypes: ['mcp-enhancement', 'implementation'] }
+ ],
+ dependencies: ['agent-5'],
+ priority: 4
+ },
+ {
+ id: 'agent-10',
+ role: 'integration-architect',
+ domain: 'integration',
+ description: 'agentic-flow@alpha deep integration',
+ capabilities: [
+ { name: 'integration', description: 'Integrate with agentic-flow', supportedTaskTypes: ['integration', 'architecture-design'] }
+ ],
+ dependencies: ['agent-5', 'agent-7', 'agent-8', 'agent-9'],
+ priority: 5
+ },
+ {
+ id: 'agent-11',
+ role: 'cli-hooks-developer',
+ domain: 'integration',
+ description: 'CLI modernization and hooks system development',
+ capabilities: [
+ { name: 'cli-development', description: 'Develop CLI and hooks', supportedTaskTypes: ['cli-development', 'implementation'] }
+ ],
+ dependencies: ['agent-9', 'agent-10'],
+ priority: 5
+ },
+ {
+ id: 'agent-12',
+ role: 'neural-learning-dev',
+ domain: 'integration',
+ description: 'Neural and SONA learning system integration',
+ capabilities: [
+ { name: 'neural-training', description: 'Implement neural features', supportedTaskTypes: ['neural-training', 'implementation'] }
+ ],
+ dependencies: ['agent-7', 'agent-10'],
+ priority: 5
+ },
+ {
+ id: 'agent-13',
+ role: 'tdd-test-engineer',
+ domain: 'quality',
+ description: 'TDD London School methodology implementation',
+ capabilities: [
+ { name: 'testing', description: 'Write comprehensive tests', supportedTaskTypes: ['test-writing'] }
+ ],
+ dependencies: [],
+ priority: 3
+ },
+ {
+ id: 'agent-14',
+ role: 'performance-engineer',
+ domain: 'performance',
+ description: 'Benchmarking and performance optimization (2.49x-7.47x target)',
+ capabilities: [
+ { name: 'benchmarking', description: 'Run performance benchmarks', supportedTaskTypes: ['benchmark'] }
+ ],
+ dependencies: ['agent-7', 'agent-8'],
+ priority: 6
+ },
+ {
+ id: 'agent-15',
+ role: 'release-engineer',
+ domain: 'deployment',
+ description: 'Deployment pipeline and release management',
+ capabilities: [
+ { name: 'deployment', description: 'Manage releases', supportedTaskTypes: ['deployment', 'documentation'] }
+ ],
+ dependencies: ['agent-10', 'agent-13', 'agent-14'],
+ priority: 7
+ }
+ ];
+
+ for (const definition of agentDefinitions) {
+ this.register(definition);
+ }
+ }
+
+ private createInitialMetrics(): AgentMetrics {
+ return {
+ tasksCompleted: 0,
+ tasksFailed: 0,
+ averageTaskDuration: 0,
+ utilization: 0,
+ startTime: Date.now()
+ };
+ }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+export function createAgentRegistry(eventBus: IEventBus): IAgentRegistry {
+ return new AgentRegistry(eventBus);
+}
diff --git a/v3/coordination/swarm-hub.ts b/v3/coordination/swarm-hub.ts
new file mode 100644
index 0000000000..e5e5915fa6
--- /dev/null
+++ b/v3/coordination/swarm-hub.ts
@@ -0,0 +1,681 @@
+/**
+ * V3 Swarm Hub
+ * Central coordination hub for the 15-agent hierarchical mesh swarm
+ *
+ * Based on ADR-001 (agentic-flow integration), ADR-003 (Single Coordination Engine),
+ * and the 15-Agent Swarm Architecture
+ */
+
+import {
+ AgentId,
+ AgentRole,
+ AgentDomain,
+ AgentState,
+ TaskId,
+ TaskDefinition,
+ TaskResult,
+ PhaseId,
+ PhaseDefinition,
+ MilestoneDefinition,
+ TopologyType,
+ SwarmConfig,
+ SwarmState,
+ SwarmMetrics,
+ SwarmMessage,
+ MessageType,
+ MessageHandler,
+ EventHandler,
+ V3_PERFORMANCE_TARGETS
+} from '../shared/types';
+import {
+ IEventBus,
+ EventBus,
+ swarmInitializedEvent,
+ swarmPhaseChangedEvent,
+ swarmMilestoneReachedEvent,
+ swarmErrorEvent
+} from '../shared/events';
+import { IAgentRegistry, AgentRegistry, createAgentRegistry } from './agent-registry';
+import { ITaskOrchestrator, TaskOrchestrator, TaskSpec, createTaskOrchestrator } from './task-orchestrator';
+
+// =============================================================================
+// Swarm Hub Interface
+// =============================================================================
+
+export interface ISwarmHub {
+ // Lifecycle
+ initialize(config?: Partial<SwarmConfig>): Promise<void>;
+ shutdown(): Promise<void>;
+ isInitialized(): boolean;
+
+ // Agent Management
+ spawnAgent(agentId: AgentId): Promise<AgentState>;
+ spawnAllAgents(): Promise<Map<AgentId, AgentState>>;
+ spawnAgentsByDomain(domain: AgentDomain): Promise<AgentState[]>;
+ terminateAgent(agentId: AgentId): Promise<boolean>;
+
+ // Task Management
+ submitTask(spec: TaskSpec): TaskDefinition;
+ submitBatchTasks(specs: TaskSpec[]): TaskDefinition[];
+ assignNextTask(agentId: AgentId): TaskDefinition | undefined;
+ completeTask(taskId: TaskId, result: TaskResult): void;
+
+ // Phase Management
+ getCurrentPhase(): PhaseId;
+ advancePhase(): PhaseId;
+ getPhaseDefinition(phaseId: PhaseId): PhaseDefinition;
+
+ // Milestone Tracking
+ getMilestones(): MilestoneDefinition[];
+ completeMilestone(milestoneId: string): void;
+
+ // Messaging
+ sendMessage<T>(message: Omit<SwarmMessage<T>, 'id' | 'timestamp'>): void;
+ broadcast<T>(from: AgentId, type: MessageType, payload: T): void;
+ onMessage<T>(handler: MessageHandler<T>): () => void;
+
+ // Metrics & Status
+ getState(): SwarmState;
+ getMetrics(): SwarmMetrics;
+ getAgentRegistry(): IAgentRegistry;
+ getTaskOrchestrator(): ITaskOrchestrator;
+
+ // Events
+ onSwarmEvent(handler: EventHandler): () => void;
+}
+
+// =============================================================================
+// Swarm Hub Implementation
+// =============================================================================
+
+export class SwarmHub implements ISwarmHub {
+ private initialized: boolean = false;
+ private config: SwarmConfig;
+ private eventBus: IEventBus;
+ private agentRegistry: IAgentRegistry;
+ private taskOrchestrator: ITaskOrchestrator;
+ private currentPhase: PhaseId = 'phase-1-foundation';
+ private phases: Map<PhaseId, PhaseDefinition>;
+ private milestones: Map<string, MilestoneDefinition> = new Map();
+ private messageHandlers: Set<MessageHandler> = new Set();
+ private messageCounter: number = 0;
+ private startTime: number = 0;
+
+ constructor(eventBus?: IEventBus) {
+ this.eventBus = eventBus ?? new EventBus();
+ this.agentRegistry = createAgentRegistry(this.eventBus);
+ this.taskOrchestrator = createTaskOrchestrator(this.eventBus, this.agentRegistry);
+ this.phases = this.createPhaseDefinitions();
+ this.config = this.getDefaultConfig();
+ }
+
+ // ==========================================================================
+ // Lifecycle
+ // ==========================================================================
+
+ async initialize(config?: Partial<SwarmConfig>): Promise<void> {
+ if (this.initialized) {
+ throw new Error('SwarmHub is already initialized');
+ }
+
+ this.config = { ...this.config, ...config };
+ this.startTime = Date.now();
+
+ this.initializeMilestones();
+
+ (this.agentRegistry as AgentRegistry).startHealthChecks();
+
+ this.initialized = true;
+
+ await this.eventBus.emit(swarmInitializedEvent({
+ topology: this.config.topology,
+ maxAgents: this.config.maxAgents,
+ performanceTargets: V3_PERFORMANCE_TARGETS
+ }));
+
+ console.log(`[SwarmHub] Initialized with ${this.config.topology} topology`);
+ }
+
+ async shutdown(): Promise<void> {
+ if (!this.initialized) {
+ return;
+ }
+
+ (this.agentRegistry as AgentRegistry).stopHealthChecks();
+
+ const activeAgents = this.agentRegistry.getActiveAgents();
+ for (const agent of activeAgents) {
+ try {
+ await this.terminateAgent(agent.id);
+ } catch (err) {
+ console.error(`[SwarmHub] Error terminating agent ${agent.id}: ${err}`);
+ }
+ }
+
+ this.initialized = false;
+ console.log('[SwarmHub] Shutdown complete');
+ }
+
+ isInitialized(): boolean {
+ return this.initialized;
+ }
+
+ // ==========================================================================
+ // Agent Management
+ // ==========================================================================
+
+ async spawnAgent(agentId: AgentId): Promise<AgentState> {
+ this.ensureInitialized();
+ return this.agentRegistry.spawn(agentId);
+ }
+
+ async spawnAllAgents(): Promise<Map<AgentId, AgentState>> {
+ this.ensureInitialized();
+
+ const results = new Map<AgentId, AgentState>();
+ const allAgents = this.agentRegistry.getAllAgents();
+
+ const sortedAgents = allAgents.sort((a, b) => a.priority - b.priority);
+
+ for (const agent of sortedAgents) {
+ try {
+ const state = await this.spawnAgent(agent.id);
+ results.set(agent.id, state);
+ } catch (err) {
+ console.error(`[SwarmHub] Failed to spawn agent ${agent.id}: ${err}`);
+ }
+ }
+
+ return results;
+ }
+
+ async spawnAgentsByDomain(domain: AgentDomain): Promise<AgentState[]> {
+ this.ensureInitialized();
+
+ const domainAgents = this.agentRegistry.getAgentsByDomain(domain);
+ const results: AgentState[] = [];
+
+ for (const agent of domainAgents) {
+ try {
+ const state = await this.spawnAgent(agent.id);
+ results.push(state);
+ } catch (err) {
+ console.error(`[SwarmHub] Failed to spawn agent ${agent.id}: ${err}`);
+ }
+ }
+
+ return results;
+ }
+
+ async terminateAgent(agentId: AgentId): Promise<boolean> {
+ this.ensureInitialized();
+ return this.agentRegistry.terminate(agentId);
+ }
+
+ // ==========================================================================
+ // Task Management
+ // ==========================================================================
+
+ submitTask(spec: TaskSpec): TaskDefinition {
+ this.ensureInitialized();
+ return this.taskOrchestrator.createTask(spec);
+ }
+
+ submitBatchTasks(specs: TaskSpec[]): TaskDefinition[] {
+ this.ensureInitialized();
+ return this.taskOrchestrator.createBatchTasks(specs);
+ }
+
+ assignNextTask(agentId: AgentId): TaskDefinition | undefined {
+ this.ensureInitialized();
+
+ const nextTask = this.taskOrchestrator.getNextTask(agentId);
+ if (nextTask) {
+ this.taskOrchestrator.queueTask(nextTask.id);
+ this.taskOrchestrator.assignTask(nextTask.id, agentId);
+ this.taskOrchestrator.startTask(nextTask.id);
+ }
+
+ return nextTask;
+ }
+
+ completeTask(taskId: TaskId, result: TaskResult): void {
+ this.ensureInitialized();
+
+ if (result.success) {
+ this.taskOrchestrator.completeTask(taskId, result);
+ } else {
+ this.taskOrchestrator.failTask(taskId, result.error ?? new Error('Unknown error'));
+ }
+ }
+
+ // ==========================================================================
+ // Phase Management
+ // ==========================================================================
+
+ getCurrentPhase(): PhaseId {
+ return this.currentPhase;
+ }
+
+ advancePhase(): PhaseId {
+ const phaseOrder: PhaseId[] = [
+ 'phase-1-foundation',
+ 'phase-2-core',
+ 'phase-3-integration',
+ 'phase-4-release'
+ ];
+
+ const currentIndex = phaseOrder.indexOf(this.currentPhase);
+ if (currentIndex < phaseOrder.length - 1) {
+ const previousPhase = this.currentPhase;
+ this.currentPhase = phaseOrder[currentIndex + 1];
+
+ this.eventBus.emitSync(swarmPhaseChangedEvent(previousPhase, this.currentPhase));
+
+ console.log(`[SwarmHub] Advanced from ${previousPhase} to ${this.currentPhase}`);
+ }
+
+ return this.currentPhase;
+ }
+
+ getPhaseDefinition(phaseId: PhaseId): PhaseDefinition {
+ const phase = this.phases.get(phaseId);
+ if (!phase) {
+ throw new Error(`Phase ${phaseId} not found`);
+ }
+ return phase;
+ }
+
+ // ==========================================================================
+ // Milestone Tracking
+ // ==========================================================================
+
+ getMilestones(): MilestoneDefinition[] {
+ return Array.from(this.milestones.values());
+ }
+
+ completeMilestone(milestoneId: string): void {
+ const milestone = this.milestones.get(milestoneId);
+ if (!milestone) {
+ throw new Error(`Milestone ${milestoneId} not found`);
+ }
+
+ milestone.status = 'completed';
+ milestone.completedAt = Date.now();
+
+ this.eventBus.emitSync(swarmMilestoneReachedEvent(milestoneId, milestone.name));
+
+ console.log(`[SwarmHub] Milestone completed: ${milestone.name}`);
+ }
+
+ // ==========================================================================
+ // Messaging
+ // ==========================================================================
+
+ sendMessage<T>(message: Omit<SwarmMessage<T>, 'id' | 'timestamp'>): void {
+ const fullMessage: SwarmMessage<T> = {
+ ...message,
+ id: `msg-${Date.now()}-${++this.messageCounter}`,
+ timestamp: Date.now()
+ };
+
+ for (const handler of this.messageHandlers) {
+ try {
+ handler(fullMessage);
+ } catch (err) {
+ console.error(`[SwarmHub] Message handler error: ${err}`);
+ }
+ }
+ }
+
+ broadcast<T>(from: AgentId, type: MessageType, payload: T): void {
+ this.sendMessage({
+ type,
+ from,
+ to: 'broadcast',
+ payload,
+ correlationId: null
+ });
+ }
+
+ onMessage<T>(handler: MessageHandler<T>): () => void {
+ this.messageHandlers.add(handler as MessageHandler);
+
+ return () => {
+ this.messageHandlers.delete(handler as MessageHandler);
+ };
+ }
+
+ // ==========================================================================
+ // Metrics & Status
+ // ==========================================================================
+
+ getState(): SwarmState {
+ const allAgents = this.agentRegistry.getAllAgents();
+ const agents = new Map<AgentId, AgentState>();
+
+ for (const agent of allAgents) {
+ const state = this.agentRegistry.getState(agent.id);
+ if (state) {
+ agents.set(agent.id, state);
+ }
+ }
+
+ const allTasks = this.taskOrchestrator.getAllTasks();
+ const tasks = new Map<TaskId, TaskDefinition>();
+
+ for (const task of allTasks) {
+ tasks.set(task.id, task);
+ }
+
+ return {
+ initialized: this.initialized,
+ topology: this.config.topology,
+ agents,
+ tasks,
+ currentPhase: this.currentPhase,
+ metrics: this.getMetrics()
+ };
+ }
+
+ getMetrics(): SwarmMetrics {
+ const activeAgents = this.agentRegistry.getActiveAgents();
+ const allAgents = this.agentRegistry.getAllAgents();
+ const taskMetrics = this.taskOrchestrator.getTaskMetrics();
+
+ const idleAgents = allAgents.filter(a => {
+ const state = this.agentRegistry.getState(a.id);
+ return state && state.status === 'idle';
+ }).length;
+
+ const blockedAgents = allAgents.filter(a => {
+ const state = this.agentRegistry.getState(a.id);
+ return state && state.status === 'blocked';
+ }).length;
+
+ const totalAgentsWithState = activeAgents.length + idleAgents + blockedAgents;
+
+ return {
+ totalAgents: allAgents.length,
+ activeAgents: activeAgents.length,
+ idleAgents,
+ blockedAgents,
+ totalTasks: taskMetrics.totalTasks,
+ completedTasks: taskMetrics.tasksByStatus['completed'],
+ failedTasks: taskMetrics.tasksByStatus['failed'],
+ pendingTasks: taskMetrics.tasksByStatus['pending'] + taskMetrics.tasksByStatus['queued'],
+ averageTaskDuration: taskMetrics.averageExecutionTime,
+ utilization: totalAgentsWithState > 0 ? activeAgents.length / totalAgentsWithState : 0,
+ startTime: this.startTime,
+ lastUpdate: Date.now()
+ };
+ }
+
+ getAgentRegistry(): IAgentRegistry {
+ return this.agentRegistry;
+ }
+
+ getTaskOrchestrator(): ITaskOrchestrator {
+ return this.taskOrchestrator;
+ }
+
+ // ==========================================================================
+ // Events
+ // ==========================================================================
+
+ onSwarmEvent(handler: EventHandler): () => void {
+ const unsubscribers = [
+ this.eventBus.subscribe('swarm:initialized', handler),
+ this.eventBus.subscribe('swarm:phase-changed', handler),
+ this.eventBus.subscribe('swarm:milestone-reached', handler),
+ this.eventBus.subscribe('swarm:error', handler)
+ ];
+
+ return () => {
+ unsubscribers.forEach(unsub => unsub());
+ };
+ }
+
+ // ==========================================================================
+ // Private Helpers
+ // ==========================================================================
+
+ private ensureInitialized(): void {
+ if (!this.initialized) {
+ throw new Error('SwarmHub is not initialized. Call initialize() first.');
+ }
+ }
+
+ private getDefaultConfig(): SwarmConfig {
+ return {
+ topology: 'hierarchical-mesh',
+ maxAgents: 15,
+ messageTimeout: 30000,
+ retryAttempts: 3,
+ healthCheckInterval: 5000,
+ loadBalancingStrategy: 'capability-match'
+ };
+ }
+
+ private createPhaseDefinitions(): Map<PhaseId, PhaseDefinition> {
+ const phases = new Map<PhaseId, PhaseDefinition>();
+
+ phases.set('phase-1-foundation', {
+ id: 'phase-1-foundation',
+ name: 'Foundation',
+ description: 'Security architecture, core design, and infrastructure setup',
+ weeks: [1, 2],
+ activeAgents: ['agent-1', 'agent-2', 'agent-3', 'agent-4', 'agent-5', 'agent-6'],
+ goals: [
+ 'Initialize swarm coordination',
+ 'Complete security architecture review',
+ 'Begin CVE fixes (CVE-1, CVE-2, CVE-3)',
+ 'Design core DDD architecture',
+ 'Modernize type system'
+ ],
+ milestones: []
+ });
+
+ phases.set('phase-2-core', {
+ id: 'phase-2-core',
+ name: 'Core Systems',
+ description: 'Core implementation, memory unification, and swarm coordination',
+ weeks: [3, 6],
+ activeAgents: ['agent-1', 'agent-5', 'agent-6', 'agent-7', 'agent-8', 'agent-9', 'agent-13'],
+ goals: [
+ 'Complete core module implementation',
+ 'Unify memory system with AgentDB (150x improvement)',
+ 'Merge 4 coordination systems into single SwarmCoordinator',
+ 'Optimize MCP server',
+ 'Implement TDD London School tests'
+ ],
+ milestones: []
+ });
+
+ phases.set('phase-3-integration', {
+ id: 'phase-3-integration',
+ name: 'Integration',
+ description: 'agentic-flow integration, CLI modernization, and neural features',
+ weeks: [7, 10],
+ activeAgents: ['agent-1', 'agent-10', 'agent-11', 'agent-12', 'agent-13', 'agent-14'],
+ goals: [
+ 'Complete agentic-flow@alpha integration',
+ 'Modernize CLI and hooks system',
+ 'Integrate Neural/SONA learning',
+ 'Run integration tests',
+ 'Initial performance benchmarks'
+ ],
+ milestones: []
+ });
+
+ phases.set('phase-4-release', {
+ id: 'phase-4-release',
+ name: 'Optimization & Release',
+ description: 'Performance optimization, deployment, and v3.0.0 release',
+ weeks: [11, 14],
+ activeAgents: [
+ 'agent-1', 'agent-2', 'agent-3', 'agent-4', 'agent-5', 'agent-6',
+ 'agent-7', 'agent-8', 'agent-9', 'agent-10', 'agent-11', 'agent-12',
+ 'agent-13', 'agent-14', 'agent-15'
+ ],
+ goals: [
+ 'Achieve 2.49x-7.47x Flash Attention speedup',
+ 'Verify 150x-12,500x AgentDB search improvement',
+ 'Complete deployment pipeline',
+ 'Final test coverage push (>90%)',
+ 'Release v3.0.0'
+ ],
+ milestones: []
+ });
+
+ return phases;
+ }
+
+ private initializeMilestones(): void {
+ const allMilestones: MilestoneDefinition[] = [
+ {
+ id: 'ms-security-architecture',
+ name: 'Security Architecture Complete',
+ description: 'All security reviews and CVE fixes implemented',
+ criteria: [
+ { description: 'CVE-1 fixed', met: false, evidence: null },
+ { description: 'CVE-2 fixed', met: false, evidence: null },
+ { description: 'CVE-3 fixed', met: false, evidence: null },
+ { description: 'Security tests passing', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-core-architecture',
+ name: 'Core Architecture Complete',
+ description: 'DDD structure implemented with all core modules',
+ criteria: [
+ { description: 'DDD bounded contexts defined', met: false, evidence: null },
+ { description: 'Core modules implemented', met: false, evidence: null },
+ { description: 'Type system modernized', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-memory-unification',
+ name: 'Memory Unification Complete',
+ description: 'Single memory service with AgentDB backend achieving 150x improvement',
+ criteria: [
+ { description: 'AgentDB integrated', met: false, evidence: null },
+ { description: '150x search improvement verified', met: false, evidence: null },
+ { description: 'Hybrid backend working', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-swarm-coordination',
+ name: 'Swarm Coordination Unified',
+ description: 'Single SwarmCoordinator merging 4 systems',
+ criteria: [
+ { description: 'Single CoordinationEngine', met: false, evidence: null },
+ { description: 'Pluggable strategies', met: false, evidence: null },
+ { description: '50% code reduction', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-agentic-integration',
+ name: 'agentic-flow Integration Complete',
+ description: 'Deep integration with agentic-flow@alpha eliminating duplicate code',
+ criteria: [
+ { description: 'Agent class extends agentic-flow', met: false, evidence: null },
+ { description: 'Swarm uses agentic-flow system', met: false, evidence: null },
+ { description: '<5,000 lines of orchestration code', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-performance-targets',
+ name: 'Performance Targets Met',
+ description: 'All performance targets achieved and verified',
+ criteria: [
+ { description: '2.49x-7.47x Flash Attention speedup', met: false, evidence: null },
+ { description: '150x-12,500x AgentDB search', met: false, evidence: null },
+ { description: '50-75% memory reduction', met: false, evidence: null },
+ { description: '<500ms startup time', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ },
+ {
+ id: 'ms-v3-release',
+ name: 'V3.0.0 Released',
+ description: 'Claude-Flow v3.0.0 published to npm',
+ criteria: [
+ { description: 'All tests passing (>90% coverage)', met: false, evidence: null },
+ { description: 'Documentation complete', met: false, evidence: null },
+ { description: 'npm package published', met: false, evidence: null },
+ { description: 'GitHub release created', met: false, evidence: null }
+ ],
+ status: 'pending',
+ completedAt: null
+ }
+ ];
+
+ for (const milestone of allMilestones) {
+ this.milestones.set(milestone.id, milestone);
+ }
+
+ for (const [phaseId, phase] of this.phases) {
+ switch (phaseId) {
+ case 'phase-1-foundation':
+ phase.milestones = [
+ this.milestones.get('ms-security-architecture')!,
+ this.milestones.get('ms-core-architecture')!
+ ];
+ break;
+ case 'phase-2-core':
+ phase.milestones = [
+ this.milestones.get('ms-memory-unification')!,
+ this.milestones.get('ms-swarm-coordination')!
+ ];
+ break;
+ case 'phase-3-integration':
+ phase.milestones = [
+ this.milestones.get('ms-agentic-integration')!
+ ];
+ break;
+ case 'phase-4-release':
+ phase.milestones = [
+ this.milestones.get('ms-performance-targets')!,
+ this.milestones.get('ms-v3-release')!
+ ];
+ break;
+ }
+ }
+ }
+}
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+export function createSwarmHub(eventBus?: IEventBus): ISwarmHub {
+ return new SwarmHub(eventBus);
+}
+
+let globalSwarmHub: ISwarmHub | null = null;
+
+export function getSwarmHub(): ISwarmHub {
+ if (!globalSwarmHub) {
+ globalSwarmHub = createSwarmHub();
+ }
+ return globalSwarmHub;
+}
+
+export function resetSwarmHub(): void {
+ if (globalSwarmHub?.isInitialized()) {
+ globalSwarmHub.shutdown();
+ }
+ globalSwarmHub = null;
+}
diff --git a/v3/coordination/task-orchestrator.ts b/v3/coordination/task-orchestrator.ts
new file mode 100644
index 0000000000..77f526923a
--- /dev/null
+++ b/v3/coordination/task-orchestrator.ts
@@ -0,0 +1,587 @@
+/**
+ * V3 Task Orchestrator
+ * Manages task decomposition, dependency resolution, and parallel execution
+ *
+ * Based on ADR-003 (Single Coordination Engine) and ADR-001 (agentic-flow integration)
+ */
+
+import {
+ TaskId,
+ TaskType,
+ TaskStatus,
+ TaskPriority,
+ TaskDefinition,
+ TaskMetadata,
+ TaskResult,
+ TaskResultMetrics,
+ AgentId,
+ AgentDomain,
+ PhaseId,
+ SwarmEvent
+} from '../shared/types';
+import {
+ IEventBus,
+ taskCreatedEvent,
+ taskQueuedEvent,
+ taskAssignedEvent,
+ taskStartedEvent,
+ taskCompletedEvent,
+ taskFailedEvent,
+ taskBlockedEvent
+} from '../shared/events';
+import { IAgentRegistry } from './agent-registry';
+
+// =============================================================================
+// Task Orchestrator Interface
+// =============================================================================
+
+export interface ITaskOrchestrator {
+ // Task Creation
+ createTask(spec: TaskSpec): TaskDefinition;
+ createBatchTasks(specs: TaskSpec[]): TaskDefinition[];
+
+ // Task Lifecycle
+ queueTask(taskId: TaskId): void;
+ assignTask(taskId: TaskId, agentId: AgentId): void;
+ startTask(taskId: TaskId): void;
+ completeTask(taskId: TaskId, result: TaskResult): void;
+ failTask(taskId: TaskId, error: Error): void;
+ cancelTask(taskId: TaskId): void;
+
+ // Dependency Management
+ addDependency(taskId: TaskId, dependsOn: TaskId): void;
+ removeDependency(taskId: TaskId, dependsOn: TaskId): void;
+ getDependencies(taskId: TaskId): TaskId[];
+ getDependents(taskId: TaskId): TaskId[];
+ isBlocked(taskId: TaskId): boolean;
+ getBlockingTasks(taskId: TaskId): TaskId[];
+
+ // Queries
+ getTask(taskId: TaskId): TaskDefinition | undefined;
+ getAllTasks(): TaskDefinition[];
+ getTasksByStatus(status: TaskStatus): TaskDefinition[];
+ getTasksByAgent(agentId: AgentId): TaskDefinition[];
+ getTasksByDomain(domain: AgentDomain): TaskDefinition[];
+ getTasksByPhase(phase: PhaseId): TaskDefinition[];
+
+ // Queue Management
+ getNextTask(agentId?: AgentId): TaskDefinition | undefined;
+ getPriorityQueue(): TaskDefinition[];
+
+ // Metrics
+ getTaskMetrics(): TaskOrchestratorMetrics;
+}
+
+export interface TaskSpec {
+ type: TaskType;
+ title: string;
+ description: string;
+ priority?: TaskPriority;
+ dependencies?: TaskId[];
+ domain: AgentDomain;
+ phase: PhaseId;
+ estimatedDuration?: number;
+ tags?: string[];
+}
+
+export interface TaskOrchestratorMetrics {
+ totalTasks: number;
+ tasksByStatus: Record<TaskStatus, number>;
+ tasksByPriority: Record<TaskPriority, number>;
+ tasksByDomain: Record<AgentDomain, number>;
+ averageQueueTime: number;
+ averageExecutionTime: number;
+ throughput: number;
+}
+
+// =============================================================================
+// Task Orchestrator Implementation
+// =============================================================================
+
+export class TaskOrchestrator implements ITaskOrchestrator {
+ private tasks: Map<TaskId, TaskDefinition> = new Map();
+ private dependencyGraph: Map<TaskId, Set<TaskId>> = new Map();
+ private dependentGraph: Map<TaskId, Set<TaskId>> = new Map();
+ private taskCounter: number = 0;
+ private eventBus: IEventBus;
+ private agentRegistry: IAgentRegistry;
+
+ constructor(eventBus: IEventBus, agentRegistry: IAgentRegistry) {
+ this.eventBus = eventBus;
+ this.agentRegistry = agentRegistry;
+
+ this.eventBus.subscribe('agent:task-completed', this.handleAgentTaskCompleted.bind(this));
+ }
+
+ // ==========================================================================
+ // Task Creation
+ // ==========================================================================
+
+ createTask(spec: TaskSpec): TaskDefinition {
+ const taskId: TaskId = `task-${Date.now()}-${++this.taskCounter}`;
+
+ const task: TaskDefinition = {
+ id: taskId,
+ type: spec.type,
+ title: spec.title,
+ description: spec.description,
+ assignedAgent: null,
+ status: 'pending',
+ priority: spec.priority ?? 'medium',
+ dependencies: spec.dependencies ?? [],
+ blockedBy: [],
+ metadata: {
+ domain: spec.domain,
+ phase: spec.phase,
+ estimatedDuration: spec.estimatedDuration ?? 0,
+ actualDuration: null,
+ retryCount: 0,
+ maxRetries: 3,
+ artifacts: [],
+ tags: spec.tags ?? []
+ },
+ createdAt: Date.now(),
+ updatedAt: Date.now(),
+ completedAt: null
+ };
+
+ this.tasks.set(taskId, task);
+ this.dependencyGraph.set(taskId, new Set(task.dependencies));
+ this.dependentGraph.set(taskId, new Set());
+
+ for (const depId of task.dependencies) {
+ if (this.dependentGraph.has(depId)) {
+ this.dependentGraph.get(depId)!.add(taskId);
+ }
+ }
+
+ this.updateBlockedStatus(taskId);
+
+ this.eventBus.emitSync(taskCreatedEvent(taskId, spec.type, spec.title));
+
+ return task;
+ }
+
+ createBatchTasks(specs: TaskSpec[]): TaskDefinition[] {
+ return specs.map(spec => this.createTask(spec));
+ }
+
+ // ==========================================================================
+ // Task Lifecycle
+ // ==========================================================================
+
+ queueTask(taskId: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (this.isBlocked(taskId)) {
+ this.updateTaskStatus(taskId, 'blocked');
+ return;
+ }
+
+ this.updateTaskStatus(taskId, 'queued');
+ this.eventBus.emitSync(taskQueuedEvent(taskId, task.priority));
+ }
+
+ assignTask(taskId: TaskId, agentId: AgentId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status !== 'queued') {
+ throw new Error(`Task ${taskId} is not queued (status: ${task.status})`);
+ }
+
+ if (this.isBlocked(taskId)) {
+ throw new Error(`Task ${taskId} is blocked by dependencies`);
+ }
+
+ task.assignedAgent = agentId;
+ this.updateTaskStatus(taskId, 'assigned');
+
+ this.agentRegistry.assignTask(agentId, taskId);
+
+ this.eventBus.emitSync(taskAssignedEvent(taskId, agentId));
+ }
+
+ startTask(taskId: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status !== 'assigned') {
+ throw new Error(`Task ${taskId} is not assigned (status: ${task.status})`);
+ }
+
+ this.updateTaskStatus(taskId, 'in-progress');
+
+ if (task.assignedAgent) {
+ this.eventBus.emitSync(taskStartedEvent(taskId, task.assignedAgent));
+ }
+ }
+
+ completeTask(taskId: TaskId, result: TaskResult): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status !== 'in-progress') {
+ throw new Error(`Task ${taskId} is not in progress (status: ${task.status})`);
+ }
+
+ task.metadata.actualDuration = result.duration;
+ task.completedAt = Date.now();
+
+ this.updateTaskStatus(taskId, 'completed');
+
+ if (task.assignedAgent) {
+ this.agentRegistry.completeTask(task.assignedAgent, taskId);
+ }
+
+ this.eventBus.emitSync(taskCompletedEvent(taskId, result));
+
+ this.unblockDependentTasks(taskId);
+ }
+
+ failTask(taskId: TaskId, error: Error): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ task.metadata.retryCount++;
+
+ if (task.metadata.retryCount < task.metadata.maxRetries) {
+ this.updateTaskStatus(taskId, 'queued');
+ task.assignedAgent = null;
+ } else {
+ this.updateTaskStatus(taskId, 'failed');
+
+ if (task.assignedAgent) {
+ const agentState = this.agentRegistry.getState(task.assignedAgent);
+ if (agentState) {
+ agentState.metrics.tasksFailed++;
+ }
+ }
+ }
+
+ this.eventBus.emitSync(taskFailedEvent(taskId, error));
+ }
+
+ cancelTask(taskId: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ if (task.status === 'completed' || task.status === 'failed') {
+ throw new Error(`Cannot cancel ${task.status} task ${taskId}`);
+ }
+
+ if (task.assignedAgent) {
+ this.agentRegistry.updateStatus(task.assignedAgent, 'idle');
+ }
+
+ this.updateTaskStatus(taskId, 'cancelled');
+ }
+
+ // ==========================================================================
+ // Dependency Management
+ // ==========================================================================
+
+ addDependency(taskId: TaskId, dependsOn: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+ this.getTaskOrThrow(dependsOn);
+
+ if (this.wouldCreateCycle(taskId, dependsOn)) {
+ throw new Error(`Adding dependency ${dependsOn} to ${taskId} would create a cycle`);
+ }
+
+ task.dependencies.push(dependsOn);
+ this.dependencyGraph.get(taskId)!.add(dependsOn);
+ this.dependentGraph.get(dependsOn)!.add(taskId);
+
+ this.updateBlockedStatus(taskId);
+ }
+
+ removeDependency(taskId: TaskId, dependsOn: TaskId): void {
+ const task = this.getTaskOrThrow(taskId);
+
+ const index = task.dependencies.indexOf(dependsOn);
+ if (index > -1) {
+ task.dependencies.splice(index, 1);
+ }
+
+ this.dependencyGraph.get(taskId)?.delete(dependsOn);
+ this.dependentGraph.get(dependsOn)?.delete(taskId);
+
+ this.updateBlockedStatus(taskId);
+ }
+
+ getDependencies(taskId: TaskId): TaskId[] {
+ return Array.from(this.dependencyGraph.get(taskId) ?? []);
+ }
+
+ getDependents(taskId: TaskId): TaskId[] {
+ return Array.from(this.dependentGraph.get(taskId) ?? []);
+ }
+
+ isBlocked(taskId: TaskId): boolean {
+ const blockingTasks = this.getBlockingTasks(taskId);
+ return blockingTasks.length > 0;
+ }
+
+ getBlockingTasks(taskId: TaskId): TaskId[] {
+ const dependencies = this.dependencyGraph.get(taskId);
+ if (!dependencies) {
+ return [];
+ }
+
+ return Array.from(dependencies).filter(depId => {
+ const depTask = this.tasks.get(depId);
+ return depTask && depTask.status !== 'completed';
+ });
+ }
+
+ // ==========================================================================
+ // Queries
+ // ==========================================================================
+
+ getTask(taskId: TaskId): TaskDefinition | undefined {
+ return this.tasks.get(taskId);
+ }
+
+ getAllTasks(): TaskDefinition[] {
+ return Array.from(this.tasks.values());
+ }
+
+ getTasksByStatus(status: TaskStatus): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.status === status);
+ }
+
+ getTasksByAgent(agentId: AgentId): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.assignedAgent === agentId);
+ }
+
+ getTasksByDomain(domain: AgentDomain): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.metadata.domain === domain);
+ }
+
+ getTasksByPhase(phase: PhaseId): TaskDefinition[] {
+ return this.getAllTasks().filter(t => t.metadata.phase === phase);
+ }
+
+ // ==========================================================================
+ // Queue Management
+ // ==========================================================================
+
+ getNextTask(agentId?: AgentId): TaskDefinition | undefined {
+ const queuedTasks = this.getTasksByStatus('queued')
+ .filter(t => !this.isBlocked(t.id))
+ .sort((a, b) => {
+ const priorityOrder: Record<TaskPriority, number> = {
+ 'critical': 0,
+ 'high': 1,
+ 'medium': 2,
+ 'low': 3
+ };
+
+ const priorityDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+ if (priorityDiff !== 0) return priorityDiff;
+
+ return a.createdAt - b.createdAt;
+ });
+
+ if (!agentId) {
+ return queuedTasks[0];
+ }
+
+ const agentDef = this.agentRegistry.getDefinition(agentId);
+ if (!agentDef) {
+ return queuedTasks[0];
+ }
+
+ const supportedTypes = agentDef.capabilities.flatMap(c => c.supportedTaskTypes);
+
+ return queuedTasks.find(t => supportedTypes.includes(t.type));
+ }
+
+ getPriorityQueue(): TaskDefinition[] {
+ return this.getTasksByStatus('queued')
+ .filter(t => !this.isBlocked(t.id))
+ .sort((a, b) => {
+ const priorityOrder: Record<TaskPriority, number> = {
+ 'critical': 0,
+ 'high': 1,
+ 'medium': 2,
+ 'low': 3
+ };
+ return priorityOrder[a.priority] - priorityOrder[b.priority];
+ });
+ }
+
+ // ==========================================================================
+ // Metrics
+ // ==========================================================================
+
+ getTaskMetrics(): TaskOrchestratorMetrics {
+ const allTasks = this.getAllTasks();
+
+ const tasksByStatus: Record<TaskStatus, number> = {
+ 'pending': 0,
+ 'queued': 0,
+ 'assigned': 0,
+ 'in-progress': 0,
+ 'blocked': 0,
+ 'completed': 0,
+ 'failed': 0,
+ 'cancelled': 0
+ };
+
+ const tasksByPriority: Record<TaskPriority, number> = {
+ 'critical': 0,
+ 'high': 0,
+ 'medium': 0,
+ 'low': 0
+ };
+
+ const tasksByDomain: Record<AgentDomain, number> = {
+ 'security': 0,
+ 'core': 0,
+ 'integration': 0,
+ 'quality': 0,
+ 'performance': 0,
+ 'deployment': 0
+ };
+
+ let totalQueueTime = 0;
+ let totalExecutionTime = 0;
+ let completedCount = 0;
+
+ for (const task of allTasks) {
+ tasksByStatus[task.status]++;
+ tasksByPriority[task.priority]++;
+ tasksByDomain[task.metadata.domain]++;
+
+ if (task.status === 'completed' && task.metadata.actualDuration) {
+ totalExecutionTime += task.metadata.actualDuration;
+ completedCount++;
+ }
+ }
+
+ const now = Date.now();
+ const firstTask = allTasks[0];
+ const runtimeMs = firstTask ? now - firstTask.createdAt : 1;
+ const throughput = completedCount / (runtimeMs / 1000 / 60);
+
+ return {
+ totalTasks: allTasks.length,
+ tasksByStatus,
+ tasksByPriority,
+ tasksByDomain,
+ averageQueueTime: totalQueueTime / (completedCount || 1),
+ averageExecutionTime: totalExecutionTime / (completedCount || 1),
+ throughput
+ };
+ }
+
+ // ==========================================================================
+ // Private Helpers
+ // ==========================================================================
+
+ private getTaskOrThrow(taskId: TaskId): TaskDefinition {
+ const task = this.tasks.get(taskId);
+ if (!task) {
+ throw new Error(`Task ${taskId} not found`);
+ }
+ return task;
+ }
+
+ private updateTaskStatus(taskId: TaskId, status: TaskStatus): void {
+ const task = this.getTaskOrThrow(taskId);
+ task.status = status;
+ task.updatedAt = Date.now();
+
+ if (status === 'blocked') {
+ task.blockedBy = this.getBlockingTasks(taskId);
+ } else {
+ task.blockedBy = [];
+ }
+ }
+
+ private updateBlockedStatus(taskId: TaskId): void {
+ const task = this.tasks.get(taskId);
+ if (!task || task.status === 'completed' || task.status === 'failed') {
+ return;
+ }
+
+ const isBlocked = this.isBlocked(taskId);
+
+ if (isBlocked && task.status !== 'blocked') {
+ this.updateTaskStatus(taskId, 'blocked');
+ this.eventBus.emitSync(taskBlockedEvent(taskId, this.getBlockingTasks(taskId)));
+ } else if (!isBlocked && task.status === 'blocked') {
+ this.updateTaskStatus(taskId, 'queued');
+ }
+ }
+
+ private unblockDependentTasks(taskId: TaskId): void {
+ const dependents = this.getDependents(taskId);
+
+ for (const dependentId of dependents) {
+ this.updateBlockedStatus(dependentId);
+ }
+ }
+
+ private wouldCreateCycle(taskId: TaskId, newDependency: TaskId): boolean {
+ const visited = new Set<TaskId>();
+ const stack = [newDependency];
+
+ while (stack.length > 0) {
+ const current = stack.pop()!;
+
+ if (current === taskId) {
+ return true;
+ }
+
+ if (visited.has(current)) {
+ continue;
+ }
+
+ visited.add(current);
+
+ const deps = this.dependencyGraph.get(current);
+ if (deps) {
+ stack.push(...deps);
+ }
+ }
+
+ return false;
+ }
+
+ private handleAgentTaskCompleted(event: SwarmEvent): void {
+ const payload = event.payload as { taskId: TaskId; result: unknown };
+
+ if (payload.taskId && this.tasks.has(payload.taskId)) {
+ const task = this.tasks.get(payload.taskId)!;
+ if (task.status === 'in-progress') {
+ this.completeTask(payload.taskId, {
+ taskId: payload.taskId,
+ success: true,
+ output: payload.result,
+ error: null,
+ duration: Date.now() - task.updatedAt,
+ metrics: this.createDefaultMetrics()
+ });
+ }
+ }
+ }
+
+ private createDefaultMetrics(): TaskResultMetrics {
+ return {
+ linesOfCode: 0,
+ testsWritten: 0,
+ testsPassed: 0,
+ coveragePercent: 0,
+ performanceImpact: 0
+ };
+ }
+}
+
+// =============================================================================
+// Factory Function
+// =============================================================================
+
+export function createTaskOrchestrator(
+ eventBus: IEventBus,
+ agentRegistry: IAgentRegistry
+): ITaskOrchestrator {
+ return new TaskOrchestrator(eventBus, agentRegistry);
+}
diff --git a/v3/integration/agentic-flow-bridge.ts b/v3/integration/agentic-flow-bridge.ts
deleted file mode 100644
index b0825c7841..0000000000
--- a/v3/integration/agentic-flow-bridge.ts
+++ /dev/null
@@ -1,799 +0,0 @@
-/**
- * Agentic Flow Integration Bridge
- *
- * Core integration bridge for agentic-flow@alpha deep integration.
- * Implements ADR-001: Adopt agentic-flow as Core Foundation
- *
- * Eliminates 10,000+ lines of duplicate code by building on agentic-flow
- * rather than implementing parallel systems.
- *
- * @module v3/integration/agentic-flow-bridge
- * @version 3.0.0-alpha.1
- */
-
-import { EventEmitter } from 'events';
-import type {
- IntegrationConfig,
- IntegrationStatus,
- RuntimeInfo,
- ComponentHealth,
- IntegrationEvent,
- IntegrationEventType,
- IntegrationError,
- FeatureFlags,
- DEFAULT_INTEGRATION_CONFIG,
-} from './types.js';
-import { SONAAdapter } from './sona-adapter.js';
-import { AttentionCoordinator } from './attention-coordinator.js';
-import { SDKBridge } from './sdk-bridge.js';
-
-/**
- * Interface for agentic-flow core module (dynamically loaded)
- * This represents the external agentic-flow@alpha package API
- */
-interface AgenticFlowSONAInterface {
- setMode(mode: string): Promise<void>;
- storePattern(params: unknown): Promise<string>;
- findPatterns(query: string, options?: unknown): Promise<unknown[]>;
- getStats(): Promise<unknown>;
-}
-
-interface AgenticFlowAttentionInterface {
- compute(params: unknown): Promise<unknown>;
- setMechanism(mechanism: string): Promise<void>;
- getMetrics(): Promise<unknown>;
-}
-
-interface AgenticFlowAgentDBInterface {
- search(query: number[], options?: unknown): Promise<unknown[]>;
- insert(vector: number[], metadata?: unknown): Promise<string>;
- enableCrossAgentSharing(options?: unknown): Promise<void>;
-}
-
-/**
- * Core interface for agentic-flow@alpha package
- * Used for deep integration and code deduplication per ADR-001
- */
-export interface AgenticFlowCore {
- sona: AgenticFlowSONAInterface;
- attention: AgenticFlowAttentionInterface;
- agentdb: AgenticFlowAgentDBInterface;
- version: string;
- isConnected: boolean;
-}
-
-/**
- * Factory function type for creating agentic-flow instance
- */
-type AgenticFlowFactory = (config: unknown) => Promise<AgenticFlowCore>;
-
-/**
- * AgenticFlowBridge - Core integration class for agentic-flow@alpha
- *
- * This class serves as the main entry point for all agentic-flow integration,
- * providing unified access to SONA learning, Flash Attention, and AgentDB.
- *
- * Performance Targets:
- * - Flash Attention: 2.49x-7.47x speedup
- * - AgentDB Search: 150x-12,500x improvement
- * - SONA Adaptation: <0.05ms response time
- * - Memory Reduction: 50-75%
- */
-export class AgenticFlowBridge extends EventEmitter {
- private config: IntegrationConfig;
- private initialized: boolean = false;
- private sona: SONAAdapter | null = null;
- private attention: AttentionCoordinator | null = null;
- private sdk: SDKBridge | null = null;
- private componentHealth: Map<string, ComponentHealth> = new Map();
- private runtimeInfo: RuntimeInfo | null = null;
- private initializationPromise: Promise<void> | null = null;
-
- /**
- * Reference to the agentic-flow@alpha core instance
- * When available, components delegate to this instead of local implementations
- * This follows ADR-001: Adopt agentic-flow as Core Foundation
- */
- private agenticFlowCore: AgenticFlowCore | null = null;
-
- /**
- * Indicates whether agentic-flow is available for delegation
- */
- private agenticFlowAvailable: boolean = false;
-
- constructor(config: Partial<IntegrationConfig> = {}) {
- super();
- this.config = this.mergeConfig(config);
- }
-
- /**
- * Initialize the integration bridge
- *
- * This method is idempotent - calling it multiple times is safe.
- * Components are lazily loaded based on configuration.
- */
- async initialize(config?: Partial<IntegrationConfig>): Promise<void> {
- // Return existing promise if initialization is in progress
- if (this.initializationPromise) {
- return this.initializationPromise;
- }
-
- // Already initialized
- if (this.initialized) {
- if (config) {
- await this.reconfigure(config);
- }
- return;
- }
-
- this.initializationPromise = this.doInitialize(config);
-
- try {
- await this.initializationPromise;
- } finally {
- this.initializationPromise = null;
- }
- }
-
- private async doInitialize(config?: Partial<IntegrationConfig>): Promise<void> {
- const startTime = Date.now();
-
- if (config) {
- this.config = this.mergeConfig(config);
- }
-
- this.emit('initializing', { config: this.config });
-
- try {
- // Detect runtime environment
- this.runtimeInfo = await this.detectRuntime();
- this.logDebug('Runtime detected', this.runtimeInfo);
-
- // ADR-001: Attempt to load agentic-flow@alpha dynamically
- // This enables deep integration and code deduplication
- await this.connectToAgenticFlow();
-
- // Initialize SDK bridge first (required for version negotiation)
- this.sdk = new SDKBridge({
- targetVersion: 'alpha',
- enableVersionNegotiation: true,
- fallbackBehavior: 'warn',
- enableCompatibilityLayer: true,
- supportDeprecatedAPIs: true,
- });
- await this.sdk.initialize();
- this.updateComponentHealth('sdk', 'healthy');
-
- // Initialize SONA adapter if enabled
- // Pass agentic-flow reference for delegation when available
- if (this.config.features.enableSONA) {
- this.sona = new SONAAdapter(this.config.sona);
- if (this.agenticFlowCore) {
- this.sona.setAgenticFlowReference(this.agenticFlowCore.sona);
- }
- await this.sona.initialize();
- this.updateComponentHealth('sona', 'healthy');
- }
-
- // Initialize Attention coordinator if enabled
- // Pass agentic-flow reference for delegation when available
- if (this.config.features.enableFlashAttention) {
- this.attention = new AttentionCoordinator(this.config.attention);
- if (this.agenticFlowCore) {
- this.attention.setAgenticFlowReference(this.agenticFlowCore.attention);
- }
- await this.attention.initialize();
- this.updateComponentHealth('attention', 'healthy');
- }
-
- this.initialized = true;
-
- const duration = Date.now() - startTime;
- this.emit('initialized', {
- duration,
- components: this.getConnectedComponents(),
- agenticFlowConnected: this.agenticFlowAvailable,
- });
-
- this.logDebug(`Initialization complete in ${duration}ms`);
- } catch (error) {
- this.emit('initialization-failed', { error });
- throw this.wrapError(error as Error, 'INITIALIZATION_FAILED', 'bridge');
- }
- }
-
- /**
- * Connect to agentic-flow@alpha package dynamically
- *
- * This implements ADR-001: Adopt agentic-flow as Core Foundation
- * When agentic-flow is available, components delegate to it for:
- * - SONA learning (eliminating duplicate pattern storage)
- * - Flash Attention (using native optimized implementations)
- * - AgentDB (leveraging 150x-12,500x faster HNSW search)
- *
- * If agentic-flow is not installed, falls back to local implementations
- * to maintain backward compatibility.
- */
- private async connectToAgenticFlow(): Promise<void> {
- try {
- // Dynamic import to handle optional dependency
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- const agenticFlowModule = await import('agentic-flow').catch(() => null);
-
- if (agenticFlowModule && typeof agenticFlowModule.createAgenticFlow === 'function') {
- const factory = agenticFlowModule.createAgenticFlow as AgenticFlowFactory;
-
- this.agenticFlowCore = await factory({
- sona: this.config.sona,
- attention: this.config.attention,
- agentdb: this.config.agentdb,
- });
-
- this.agenticFlowAvailable = true;
- this.updateComponentHealth('agentic-flow', 'healthy');
-
- this.emit('agentic-flow:connected', {
- version: this.agenticFlowCore.version,
- features: {
- sona: true,
- attention: true,
- agentdb: true,
- },
- });
-
- this.logDebug('Connected to agentic-flow', {
- version: this.agenticFlowCore.version,
- });
- } else {
- // Package not found or doesn't export expected factory
- this.agenticFlowAvailable = false;
- this.emit('agentic-flow:fallback', {
- reason: 'package not found or incompatible',
- });
- this.logDebug('agentic-flow not available, using local implementations');
- }
- } catch (error) {
- // Fallback to local implementation if agentic-flow fails to load
- this.agenticFlowAvailable = false;
- this.emit('agentic-flow:fallback', {
- reason: 'initialization error',
- error: (error as Error).message,
- });
- this.logDebug('agentic-flow initialization failed, using fallback', error);
- }
- }
-
- /**
- * Reconfigure the bridge with new settings
- */
- async reconfigure(config: Partial<IntegrationConfig>): Promise<void> {
- this.config = this.mergeConfig(config);
-
- // Reconfigure active components
- if (this.sona && config.sona) {
- await this.sona.reconfigure(config.sona);
- }
-
- if (this.attention && config.attention) {
- await this.attention.reconfigure(config.attention);
- }
-
- this.emit('reconfigured', { config: this.config });
- }
-
- /**
- * Get the SONA adapter for learning integration
- */
- async getSONAAdapter(): Promise<SONAAdapter> {
- this.ensureInitialized();
-
- if (!this.config.features.enableSONA) {
- throw this.createError(
- 'SONA is disabled in configuration',
- 'FEATURE_DISABLED',
- 'sona'
- );
- }
-
- if (!this.sona) {
- this.sona = new SONAAdapter(this.config.sona);
- await this.sona.initialize();
- this.updateComponentHealth('sona', 'healthy');
- }
-
- return this.sona;
- }
-
- /**
- * Get the Attention coordinator for Flash Attention integration
- */
- async getAttentionCoordinator(): Promise<AttentionCoordinator> {
- this.ensureInitialized();
-
- if (!this.config.features.enableFlashAttention) {
- throw this.createError(
- 'Flash Attention is disabled in configuration',
- 'FEATURE_DISABLED',
- 'attention'
- );
- }
-
- if (!this.attention) {
- this.attention = new AttentionCoordinator(this.config.attention);
- await this.attention.initialize();
- this.updateComponentHealth('attention', 'healthy');
- }
-
- return this.attention;
- }
-
- /**
- * Get the SDK bridge for API compatibility
- */
- async getSDKBridge(): Promise<SDKBridge> {
- this.ensureInitialized();
-
- if (!this.sdk) {
- throw this.createError(
- 'SDK bridge not initialized',
- 'COMPONENT_UNAVAILABLE',
- 'sdk'
- );
- }
-
- return this.sdk;
- }
-
- /**
- * Get current integration status
- */
- getStatus(): IntegrationStatus {
- const features: Record<string, boolean> = {};
- for (const [key, value] of Object.entries(this.config.features)) {
- features[key] = value;
- }
-
- return {
- initialized: this.initialized,
- connectedComponents: this.getConnectedComponents(),
- runtime: this.runtimeInfo || this.getDefaultRuntimeInfo(),
- features,
- health: Object.fromEntries(this.componentHealth),
- lastHealthCheck: Date.now(),
- };
- }
-
- /**
- * Get feature flags
- */
- getFeatureFlags(): FeatureFlags {
- return { ...this.config.features };
- }
-
- /**
- * Check if a feature is enabled
- */
- isFeatureEnabled(feature: keyof FeatureFlags): boolean {
- return this.config.features[feature] ?? false;
- }
-
- /**
- * Enable a feature dynamically
- */
- async enableFeature(feature: keyof FeatureFlags): Promise<void> {
- if (this.config.features[feature]) {
- return; // Already enabled
- }
-
- this.config.features[feature] = true;
-
- // Initialize the corresponding component if needed
- switch (feature) {
- case 'enableSONA':
- if (!this.sona) {
- this.sona = new SONAAdapter(this.config.sona);
- await this.sona.initialize();
- this.updateComponentHealth('sona', 'healthy');
- }
- break;
- case 'enableFlashAttention':
- if (!this.attention) {
- this.attention = new AttentionCoordinator(this.config.attention);
- await this.attention.initialize();
- this.updateComponentHealth('attention', 'healthy');
- }
- break;
- }
-
- this.emit('feature-enabled', { feature });
- }
-
- /**
- * Disable a feature dynamically
- */
- async disableFeature(feature: keyof FeatureFlags): Promise<void> {
- if (!this.config.features[feature]) {
- return; // Already disabled
- }
-
- this.config.features[feature] = false;
-
- // Cleanup the corresponding component
- switch (feature) {
- case 'enableSONA':
- if (this.sona) {
- await this.sona.shutdown();
- this.sona = null;
- this.componentHealth.delete('sona');
- }
- break;
- case 'enableFlashAttention':
- if (this.attention) {
- await this.attention.shutdown();
- this.attention = null;
- this.componentHealth.delete('attention');
- }
- break;
- }
-
- this.emit('feature-disabled', { feature });
- }
-
- /**
- * Perform health check on all components
- */
- async healthCheck(): Promise<Record<string, ComponentHealth>> {
- const results: Record<string, ComponentHealth> = {};
-
- // Check SDK bridge
- if (this.sdk) {
- try {
- const start = Date.now();
- await this.sdk.ping();
- results['sdk'] = {
- name: 'sdk',
- status: 'healthy',
- latencyMs: Date.now() - start,
- uptime: 1.0,
- };
- } catch (error) {
- results['sdk'] = {
- name: 'sdk',
- status: 'unhealthy',
- lastError: (error as Error).message,
- latencyMs: 0,
- uptime: 0,
- };
- }
- }
-
- // Check SONA
- if (this.sona) {
- try {
- const start = Date.now();
- await this.sona.getStats();
- results['sona'] = {
- name: 'sona',
- status: 'healthy',
- latencyMs: Date.now() - start,
- uptime: 1.0,
- };
- } catch (error) {
- results['sona'] = {
- name: 'sona',
- status: 'unhealthy',
- lastError: (error as Error).message,
- latencyMs: 0,
- uptime: 0,
- };
- }
- }
-
- // Check Attention
- if (this.attention) {
- try {
- const start = Date.now();
- await this.attention.getMetrics();
- results['attention'] = {
- name: 'attention',
- status: 'healthy',
- latencyMs: Date.now() - start,
- uptime: 1.0,
- };
- } catch (error) {
- results['attention'] = {
- name: 'attention',
- status: 'unhealthy',
- lastError: (error as Error).message,
- latencyMs: 0,
- uptime: 0,
- };
- }
- }
-
- // Update stored health status
- for (const [name, health] of Object.entries(results)) {
- this.componentHealth.set(name, health);
- }
-
- this.emit('health-check', { results });
- return results;
- }
-
- /**
- * Shutdown the integration bridge gracefully
- */
- async shutdown(): Promise<void> {
- this.emit('shutting-down');
-
- const shutdownPromises: Promise<void>[] = [];
-
- if (this.sona) {
- shutdownPromises.push(this.sona.shutdown());
- }
-
- if (this.attention) {
- shutdownPromises.push(this.attention.shutdown());
- }
-
- if (this.sdk) {
- shutdownPromises.push(this.sdk.shutdown());
- }
-
- await Promise.allSettled(shutdownPromises);
-
- this.sona = null;
- this.attention = null;
- this.sdk = null;
- this.agenticFlowCore = null;
- this.agenticFlowAvailable = false;
- this.initialized = false;
- this.componentHealth.clear();
-
- this.emit('shutdown');
- }
-
- /**
- * Check if agentic-flow@alpha is connected and available for delegation
- *
- * When true, components can delegate to agentic-flow for optimized
- * implementations (per ADR-001).
- */
- isAgenticFlowConnected(): boolean {
- return this.agenticFlowAvailable && this.agenticFlowCore !== null;
- }
-
- /**
- * Get the agentic-flow core instance for direct access
- *
- * Returns null if agentic-flow is not available.
- * Prefer using getSONAAdapter() or getAttentionCoordinator() which
- * handle delegation automatically.
- */
- getAgenticFlowCore(): AgenticFlowCore | null {
- return this.agenticFlowCore;
- }
-
- // ===== Private Methods =====
-
- private mergeConfig(config: Partial<IntegrationConfig>): IntegrationConfig {
- const defaultConfig: IntegrationConfig = {
- sona: {
- mode: 'balanced',
- learningRate: 0.001,
- similarityThreshold: 0.7,
- maxPatterns: 10000,
- enableTrajectoryTracking: true,
- consolidationInterval: 3600000,
- autoModeSelection: true,
- },
- attention: {
- mechanism: 'flash',
- numHeads: 8,
- headDim: 64,
- dropoutRate: 0.0,
- causalMask: false,
- useRoPE: true,
- flashOptLevel: 2,
- memoryOptimization: 'moderate',
- },
- agentdb: {
- dimension: 1536,
- indexType: 'hnsw',
- hnswM: 16,
- hnswEfConstruction: 200,
- hnswEfSearch: 50,
- metric: 'cosine',
- enableCache: true,
- cacheSizeMb: 256,
- enableWAL: true,
- },
- features: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- runtimePreference: ['napi', 'wasm', 'js'],
- lazyLoad: true,
- debug: false,
- };
-
- return {
- ...defaultConfig,
- ...config,
- sona: { ...defaultConfig.sona, ...config.sona },
- attention: { ...defaultConfig.attention, ...config.attention },
- agentdb: { ...defaultConfig.agentdb, ...config.agentdb },
- features: { ...defaultConfig.features, ...config.features },
- };
- }
-
- private async detectRuntime(): Promise<RuntimeInfo> {
- const platform = process.platform as 'linux' | 'darwin' | 'win32';
- const arch = process.arch as 'x64' | 'arm64' | 'ia32';
- const nodeVersion = process.version;
-
- // Check NAPI support
- let napiSupport = false;
- try {
- // Attempt to load native module indicator
- napiSupport = platform !== 'win32' || arch === 'x64';
- } catch {
- napiSupport = false;
- }
-
- // WASM is always supported in Node.js
- const wasmSupport = true;
-
- // Determine runtime based on preference
- let runtime: 'napi' | 'wasm' | 'js' = 'js';
- for (const pref of this.config.runtimePreference) {
- if (pref === 'napi' && napiSupport) {
- runtime = 'napi';
- break;
- } else if (pref === 'wasm' && wasmSupport) {
- runtime = 'wasm';
- break;
- } else if (pref === 'js') {
- runtime = 'js';
- break;
- }
- }
-
- // Determine performance tier
- let performanceTier: 'optimal' | 'good' | 'fallback';
- if (runtime === 'napi') {
- performanceTier = 'optimal';
- } else if (runtime === 'wasm') {
- performanceTier = 'good';
- } else {
- performanceTier = 'fallback';
- }
-
- return {
- runtime,
- platform,
- arch,
- nodeVersion,
- wasmSupport,
- napiSupport,
- performanceTier,
- };
- }
-
- private getDefaultRuntimeInfo(): RuntimeInfo {
- return {
- runtime: 'js',
- platform: 'linux',
- arch: 'x64',
- nodeVersion: process.version,
- wasmSupport: true,
- napiSupport: false,
- performanceTier: 'fallback',
- };
- }
-
- private getConnectedComponents(): string[] {
- const components: string[] = [];
-
- if (this.sdk) components.push('sdk');
- if (this.sona) components.push('sona');
- if (this.attention) components.push('attention');
-
- return components;
- }
-
- private updateComponentHealth(
- name: string,
- status: 'healthy' | 'degraded' | 'unhealthy',
- error?: string
- ): void {
- this.componentHealth.set(name, {
- name,
- status,
- lastError: error,
- latencyMs: 0,
- uptime: status === 'healthy' ? 1.0 : 0.0,
- });
- }
-
- private ensureInitialized(): void {
- if (!this.initialized) {
- throw this.createError(
- 'Bridge not initialized. Call initialize() first.',
- 'INITIALIZATION_FAILED',
- 'bridge'
- );
- }
- }
-
- private createError(
- message: string,
- code: string,
- component: string
- ): Error {
- const error = new Error(message);
- (error as any).code = code;
- (error as any).component = component;
- return error;
- }
-
- private wrapError(error: Error, code: string, component: string): Error {
- const wrapped = new Error(`${component}: ${error.message}`);
- (wrapped as any).code = code;
- (wrapped as any).component = component;
- (wrapped as any).cause = error;
- return wrapped;
- }
-
- private logDebug(message: string, data?: unknown): void {
- if (this.config.debug) {
- console.debug(`[AgenticFlowBridge] ${message}`, data || '');
- }
- }
-}
-
-/**
- * Create and initialize an AgenticFlowBridge instance
- */
-export async function createAgenticFlowBridge(
- config?: Partial<IntegrationConfig>
-): Promise<AgenticFlowBridge> {
- const bridge = new AgenticFlowBridge(config);
- await bridge.initialize();
- return bridge;
-}
-
-/**
- * Singleton instance for simple usage
- */
-let defaultBridge: AgenticFlowBridge | null = null;
-
-/**
- * Get the default bridge instance (creates if needed)
- */
-export async function getDefaultBridge(
- config?: Partial<IntegrationConfig>
-): Promise<AgenticFlowBridge> {
- if (!defaultBridge) {
- defaultBridge = new AgenticFlowBridge(config);
- await defaultBridge.initialize();
- }
- return defaultBridge;
-}
-
-/**
- * Reset the default bridge (useful for testing)
- */
-export async function resetDefaultBridge(): Promise<void> {
- if (defaultBridge) {
- await defaultBridge.shutdown();
- defaultBridge = null;
- }
-}
diff --git a/v3/integration/attention-coordinator.ts b/v3/integration/attention-coordinator.ts
deleted file mode 100644
index fff009d43c..0000000000
--- a/v3/integration/attention-coordinator.ts
+++ /dev/null
@@ -1,677 +0,0 @@
-/**
- * Attention Coordinator for Flash Attention Integration
- *
- * Provides integration with agentic-flow's attention mechanisms,
- * including Flash Attention for 2.49x-7.47x speedup with
- * 50-75% memory reduction.
- *
- * Supported Mechanisms:
- * - Flash Attention (fastest, recommended)
- * - Multi-Head Attention (standard)
- * - Linear Attention (long sequences)
- * - Hyperbolic Attention (hierarchical data)
- * - MoE Attention (Mixture of Experts)
- * - Local/Global Attention
- * - Sparse Attention
- *
- * @module v3/integration/attention-coordinator
- * @version 3.0.0-alpha.1
- */
-
-import { EventEmitter } from 'events';
-import type {
- AttentionConfiguration,
- AttentionMechanism,
- AttentionResult,
- AttentionMetrics,
- DEFAULT_ATTENTION_CONFIG,
-} from './types.js';
-
-/**
- * Interface for agentic-flow Attention reference (for delegation)
- * This allows the coordinator to delegate to agentic-flow when available
- */
-interface AgenticFlowAttentionReference {
- compute(params: {
- query: number[] | Float32Array;
- key: number[] | Float32Array;
- value: number[] | Float32Array;
- mask?: boolean[];
- mechanism?: string;
- }): Promise<{
- output: number[];
- latencyMs: number;
- memoryBytes: number;
- mechanism: string;
- }>;
- setMechanism(mechanism: string): Promise<void>;
- getMetrics(): Promise<{
- avgLatencyMs: number;
- throughputTps: number;
- memoryEfficiency: number;
- speedupFactor: number;
- }>;
-}
-
-/**
- * Threshold for delegating to native attention (tokens)
- * Sequences longer than this benefit most from Flash Attention optimization
- */
-const DELEGATION_SEQUENCE_THRESHOLD = 512;
-
-/**
- * Mechanism-specific performance characteristics
- */
-const MECHANISM_PROFILES: Record<AttentionMechanism, {
- speedupRange: [number, number];
- memoryReduction: number;
- latencyMs: [number, number];
- bestFor: string[];
-}> = {
- 'flash': {
- speedupRange: [2.49, 7.47],
- memoryReduction: 0.75,
- latencyMs: [0.7, 1.5],
- bestFor: ['general', 'high-throughput', 'memory-constrained'],
- },
- 'multi-head': {
- speedupRange: [1.0, 1.0],
- memoryReduction: 0,
- latencyMs: [2, 5],
- bestFor: ['complex-reasoning', 'high-accuracy'],
- },
- 'linear': {
- speedupRange: [1.5, 2.0],
- memoryReduction: 0.5,
- latencyMs: [1, 3],
- bestFor: ['long-sequences', 'streaming'],
- },
- 'hyperbolic': {
- speedupRange: [0.8, 1.2],
- memoryReduction: 0,
- latencyMs: [3, 8],
- bestFor: ['hierarchical-data', 'tree-structures'],
- },
- 'moe': {
- speedupRange: [1.2, 2.5],
- memoryReduction: 0.3,
- latencyMs: [1, 4],
- bestFor: ['expert-routing', 'multi-task'],
- },
- 'local': {
- speedupRange: [2.0, 4.0],
- memoryReduction: 0.6,
- latencyMs: [0.5, 1.5],
- bestFor: ['local-context', 'fast-inference'],
- },
- 'global': {
- speedupRange: [1.0, 1.5],
- memoryReduction: 0.2,
- latencyMs: [1.5, 4],
- bestFor: ['global-context', 'summarization'],
- },
- 'sparse': {
- speedupRange: [1.5, 3.0],
- memoryReduction: 0.4,
- latencyMs: [1, 3],
- bestFor: ['sparse-patterns', 'efficient-inference'],
- },
-};
-
-/**
- * AttentionCoordinator - Flash Attention Integration
- *
- * This coordinator manages attention mechanism selection and execution,
- * providing optimized attention computation with automatic fallback
- * and performance monitoring.
- */
-export class AttentionCoordinator extends EventEmitter {
- private config: AttentionConfiguration;
- private initialized: boolean = false;
- private metrics: AttentionMetrics;
- private operationCount: number = 0;
- private totalLatencyMs: number = 0;
- private cacheHits: number = 0;
- private cache: Map<string, AttentionResult> = new Map();
- private maxCacheSize: number = 1000;
-
- /**
- * Reference to agentic-flow Attention for delegation (ADR-001)
- * When set, performAttention delegates to native Flash Attention
- */
- private agenticFlowAttention: AgenticFlowAttentionReference | null = null;
-
- /**
- * Indicates if delegation to agentic-flow is active
- */
- private delegationEnabled: boolean = false;
-
- constructor(config: Partial<AttentionConfiguration> = {}) {
- super();
- this.config = this.mergeConfig(config);
- this.metrics = this.initializeMetrics();
- }
-
- /**
- * Set reference to agentic-flow Attention for delegation
- *
- * This implements ADR-001: Adopt agentic-flow as Core Foundation
- * When a reference is provided, attention computation for sequences
- * longer than 512 tokens delegates to agentic-flow's optimized
- * Flash Attention implementation for 2.49x-7.47x speedup.
- *
- * @param attentionRef - The agentic-flow Attention interface reference
- */
- setAgenticFlowReference(attentionRef: AgenticFlowAttentionReference): void {
- this.agenticFlowAttention = attentionRef;
- this.delegationEnabled = true;
- this.emit('delegation-enabled', { target: 'agentic-flow' });
- }
-
- /**
- * Check if delegation to agentic-flow is enabled
- */
- isDelegationEnabled(): boolean {
- return this.delegationEnabled && this.agenticFlowAttention !== null;
- }
-
- /**
- * Initialize the attention coordinator
- */
- async initialize(): Promise<void> {
- if (this.initialized) {
- return;
- }
-
- this.emit('initializing');
-
- try {
- // Validate configuration
- this.validateConfig();
-
- // Pre-warm the cache if needed
- if (this.config.memoryOptimization !== 'aggressive') {
- await this.prewarmCache();
- }
-
- this.initialized = true;
- this.emit('initialized', { mechanism: this.config.mechanism });
- } catch (error) {
- this.emit('initialization-failed', { error });
- throw error;
- }
- }
-
- /**
- * Reconfigure the coordinator
- */
- async reconfigure(config: Partial<AttentionConfiguration>): Promise<void> {
- this.config = this.mergeConfig(config);
- this.validateConfig();
-
- // Clear cache if mechanism changed
- if (config.mechanism) {
- this.cache.clear();
- }
-
- this.emit('reconfigured', { config: this.config });
- }
-
- /**
- * Get current mechanism
- */
- getMechanism(): AttentionMechanism {
- return this.config.mechanism;
- }
-
- /**
- * Set attention mechanism
- */
- async setMechanism(mechanism: AttentionMechanism): Promise<void> {
- const previousMechanism = this.config.mechanism;
- this.config.mechanism = mechanism;
-
- // Clear cache when switching mechanisms
- this.cache.clear();
-
- this.emit('mechanism-changed', {
- previousMechanism,
- newMechanism: mechanism,
- profile: MECHANISM_PROFILES[mechanism]
- });
- }
-
- /**
- * Compute attention using current mechanism
- */
- async compute(params: {
- query: number[] | Float32Array;
- key: number[] | Float32Array;
- value: number[] | Float32Array;
- mask?: boolean[];
- useCache?: boolean;
- }): Promise<AttentionResult> {
- this.ensureInitialized();
-
- const startTime = performance.now();
- const cacheKey = params.useCache ? this.computeCacheKey(params) : null;
-
- // Check cache
- if (cacheKey && this.cache.has(cacheKey)) {
- this.cacheHits++;
- const cached = this.cache.get(cacheKey)!;
- cached.cacheHit = true;
- this.updateMetrics(performance.now() - startTime, true);
- return cached;
- }
-
- try {
- // Perform attention computation based on mechanism
- const output = await this.performAttention(params);
-
- const latencyMs = performance.now() - startTime;
-
- const result: AttentionResult = {
- output,
- latencyMs,
- memoryBytes: this.estimateMemoryUsage(output),
- mechanism: this.config.mechanism,
- cacheHit: false,
- };
-
- // Update cache
- if (cacheKey) {
- this.updateCache(cacheKey, result);
- }
-
- // Update metrics
- this.updateMetrics(latencyMs, false);
-
- this.emit('attention-computed', {
- mechanism: this.config.mechanism,
- latencyMs
- });
-
- return result;
- } catch (error) {
- this.emit('attention-failed', { error });
- throw error;
- }
- }
-
- /**
- * Coordinate agent outputs using attention-based consensus
- *
- * This method uses attention mechanisms to weight and combine
- * multiple agent outputs into a consensus result.
- */
- async coordinateAgents<T>(params: {
- outputs: T[];
- embeddings: number[][];
- mechanism?: AttentionMechanism;
- topK?: number;
- }): Promise<{
- consensus: T;
- weights: number[];
- confidence: number;
- }> {
- this.ensureInitialized();
-
- const mechanism = params.mechanism || this.config.mechanism;
- const embeddings = params.embeddings;
-
- // Compute attention weights between all outputs
- const n = embeddings.length;
- const weights: number[] = new Array(n).fill(1 / n);
-
- if (n > 1) {
- // Compute pairwise attention scores
- const scores: number[] = [];
- for (let i = 0; i < n; i++) {
- let score = 0;
- for (let j = 0; j < n; j++) {
- if (i !== j) {
- score += this.dotProduct(embeddings[i], embeddings[j]);
- }
- }
- scores.push(score / (n - 1));
- }
-
- // Softmax to get weights
- const maxScore = Math.max(...scores);
- const expScores = scores.map(s => Math.exp(s - maxScore));
- const sumExp = expScores.reduce((a, b) => a + b, 0);
-
- for (let i = 0; i < n; i++) {
- weights[i] = expScores[i] / sumExp;
- }
- }
-
- // Select consensus (highest weighted output)
- const maxWeightIdx = weights.indexOf(Math.max(...weights));
- const consensus = params.outputs[maxWeightIdx];
-
- // Calculate confidence
- const confidence = weights[maxWeightIdx];
-
- this.emit('agents-coordinated', {
- agentCount: n,
- mechanism,
- confidence
- });
-
- return { consensus, weights, confidence };
- }
-
- /**
- * Route to experts using MoE attention
- */
- async routeToExperts<T>(params: {
- task: { embedding: number[] };
- experts: Array<{ id: string; embedding: number[] }>;
- topK?: number;
- }): Promise<Array<{ expertId: string; score: number }>> {
- this.ensureInitialized();
-
- const topK = params.topK || 3;
- const taskEmb = params.task.embedding;
-
- // Compute scores for each expert
- const scores = params.experts.map(expert => ({
- expertId: expert.id,
- score: this.cosineSimilarity(taskEmb, expert.embedding),
- }));
-
- // Sort and return top K
- scores.sort((a, b) => b.score - a.score);
- const topExperts = scores.slice(0, topK);
-
- this.emit('experts-routed', {
- expertCount: params.experts.length,
- topK,
- topExpert: topExperts[0]?.expertId
- });
-
- return topExperts;
- }
-
- /**
- * Get attention metrics
- */
- async getMetrics(): Promise<AttentionMetrics> {
- this.ensureInitialized();
-
- return { ...this.metrics };
- }
-
- /**
- * Get mechanism profile
- */
- getMechanismProfile(mechanism?: AttentionMechanism) {
- return MECHANISM_PROFILES[mechanism || this.config.mechanism];
- }
-
- /**
- * Suggest optimal mechanism for use case
- */
- suggestMechanism(useCase: string): AttentionMechanism {
- const lowerCase = useCase.toLowerCase();
-
- for (const [mechanism, profile] of Object.entries(MECHANISM_PROFILES)) {
- for (const match of profile.bestFor) {
- if (lowerCase.includes(match) || match.includes(lowerCase)) {
- return mechanism as AttentionMechanism;
- }
- }
- }
-
- // Default to flash attention
- return 'flash';
- }
-
- /**
- * Clear the attention cache
- */
- clearCache(): void {
- this.cache.clear();
- this.emit('cache-cleared');
- }
-
- /**
- * Shutdown the coordinator
- */
- async shutdown(): Promise<void> {
- this.cache.clear();
- this.initialized = false;
- this.emit('shutdown');
- }
-
- // ===== Private Methods =====
-
- private mergeConfig(config: Partial<AttentionConfiguration>): AttentionConfiguration {
- return {
- mechanism: config.mechanism || 'flash',
- numHeads: config.numHeads ?? 8,
- headDim: config.headDim ?? 64,
- dropoutRate: config.dropoutRate ?? 0.0,
- causalMask: config.causalMask ?? false,
- useRoPE: config.useRoPE ?? true,
- flashOptLevel: config.flashOptLevel ?? 2,
- memoryOptimization: config.memoryOptimization || 'moderate',
- };
- }
-
- private initializeMetrics(): AttentionMetrics {
- return {
- avgLatencyMs: 0,
- throughputTps: 0,
- memoryEfficiency: 1.0,
- cacheHitRate: 0,
- totalOperations: 0,
- speedupFactor: 1.0,
- };
- }
-
- private validateConfig(): void {
- if (this.config.numHeads <= 0) {
- throw new Error('numHeads must be positive');
- }
- if (this.config.headDim <= 0) {
- throw new Error('headDim must be positive');
- }
- if (this.config.dropoutRate < 0 || this.config.dropoutRate > 1) {
- throw new Error('dropoutRate must be between 0 and 1');
- }
- if (this.config.flashOptLevel < 0 || this.config.flashOptLevel > 3) {
- throw new Error('flashOptLevel must be between 0 and 3');
- }
- }
-
- private async prewarmCache(): Promise<void> {
- // Pre-compute common attention patterns
- // This is a no-op in the simplified implementation
- }
-
- /**
- * Perform attention computation
- *
- * ADR-001: For sequences longer than 512 tokens, delegates to
- * agentic-flow's native Flash Attention for 2.49x-7.47x speedup
- * and 50-75% memory reduction.
- */
- private async performAttention(params: {
- query: number[] | Float32Array;
- key: number[] | Float32Array;
- value: number[] | Float32Array;
- mask?: boolean[];
- }): Promise<number[]> {
- const { query, key, value, mask } = params;
-
- const qArray = Array.isArray(query) ? query : Array.from(query);
- const kArray = Array.isArray(key) ? key : Array.from(key);
- const vArray = Array.isArray(value) ? value : Array.from(value);
-
- // Calculate sequence length for delegation decision
- const sequenceLength = qArray.length;
-
- // ADR-001: Delegate to agentic-flow for long sequences
- // Flash Attention provides 2.49x-7.47x speedup for sequences > 512 tokens
- if (
- this.isDelegationEnabled() &&
- this.agenticFlowAttention &&
- sequenceLength > DELEGATION_SEQUENCE_THRESHOLD
- ) {
- try {
- const result = await this.agenticFlowAttention.compute({
- query: qArray,
- key: kArray,
- value: vArray,
- mask,
- mechanism: this.config.mechanism,
- });
-
- this.emit('attention-delegated', {
- sequenceLength,
- mechanism: result.mechanism,
- latencyMs: result.latencyMs,
- target: 'agentic-flow',
- });
-
- return result.output;
- } catch (error) {
- // Log delegation failure and fall back to local implementation
- this.emit('delegation-failed', {
- method: 'performAttention',
- sequenceLength,
- error: (error as Error).message,
- fallback: 'local',
- });
- // Continue with local implementation below
- }
- }
-
- // Local implementation (fallback or for short sequences)
- // For short sequences, local JS implementation is sufficient
- // and avoids overhead of cross-boundary calls
-
- // Compute attention scores (Q * K^T)
- let score = this.dotProduct(qArray, kArray);
-
- // Scale by sqrt(d_k)
- score = score / Math.sqrt(this.config.headDim);
-
- // Apply softmax (simplified for single attention head)
- const weight = 1.0; // Math.exp(score) / Math.exp(score)
-
- // Compute output (weight * V)
- const output = vArray.map(v => v * weight);
-
- // Apply mechanism-specific optimizations
- switch (this.config.mechanism) {
- case 'flash':
- // Flash attention optimization: fused operations
- // For short sequences, the JS implementation is used
- // Native Flash Attention is used via delegation for longer sequences
- break;
- case 'linear':
- // Linear attention: O(n) instead of O(n^2)
- break;
- case 'sparse':
- // Sparse attention: only compute non-zero patterns
- break;
- }
-
- return output;
- }
-
- private computeCacheKey(params: {
- query: number[] | Float32Array;
- key: number[] | Float32Array;
- value: number[] | Float32Array;
- }): string {
- // Simple hash of first few elements
- const qHash = this.simpleHash(params.query);
- const kHash = this.simpleHash(params.key);
- const vHash = this.simpleHash(params.value);
- return `${this.config.mechanism}:${qHash}:${kHash}:${vHash}`;
- }
-
- private simpleHash(arr: number[] | Float32Array): number {
- const slice = Array.isArray(arr) ? arr.slice(0, 8) : Array.from(arr).slice(0, 8);
- let hash = 0;
- for (const v of slice) {
- hash = ((hash << 5) - hash) + Math.floor(v * 1000);
- hash = hash & hash;
- }
- return hash;
- }
-
- private updateCache(key: string, result: AttentionResult): void {
- if (this.cache.size >= this.maxCacheSize) {
- // Remove oldest entry
- const firstKey = this.cache.keys().next().value;
- this.cache.delete(firstKey);
- }
- this.cache.set(key, result);
- }
-
- private updateMetrics(latencyMs: number, cacheHit: boolean): void {
- this.operationCount++;
- this.totalLatencyMs += latencyMs;
- if (cacheHit) this.cacheHits++;
-
- this.metrics.avgLatencyMs = this.totalLatencyMs / this.operationCount;
- this.metrics.totalOperations = this.operationCount;
- this.metrics.cacheHitRate = this.cacheHits / this.operationCount;
-
- // Estimate throughput (tokens per second)
- if (this.metrics.avgLatencyMs > 0) {
- this.metrics.throughputTps = 1000 / this.metrics.avgLatencyMs;
- }
-
- // Calculate speedup factor based on mechanism
- const profile = MECHANISM_PROFILES[this.config.mechanism];
- this.metrics.speedupFactor = (profile.speedupRange[0] + profile.speedupRange[1]) / 2;
- this.metrics.memoryEfficiency = 1 - profile.memoryReduction;
- }
-
- private estimateMemoryUsage(output: number[]): number {
- // Estimate: 8 bytes per float64
- return output.length * 8;
- }
-
- private dotProduct(a: number[], b: number[]): number {
- let sum = 0;
- const len = Math.min(a.length, b.length);
- for (let i = 0; i < len; i++) {
- sum += a[i] * b[i];
- }
- return sum;
- }
-
- private cosineSimilarity(a: number[], b: number[]): number {
- const dot = this.dotProduct(a, b);
- const normA = Math.sqrt(this.dotProduct(a, a));
- const normB = Math.sqrt(this.dotProduct(b, b));
-
- if (normA === 0 || normB === 0) return 0;
- return dot / (normA * normB);
- }
-
- private ensureInitialized(): void {
- if (!this.initialized) {
- throw new Error('AttentionCoordinator not initialized. Call initialize() first.');
- }
- }
-}
-
-/**
- * Create and initialize an AttentionCoordinator
- */
-export async function createAttentionCoordinator(
- config?: Partial<AttentionConfiguration>
-): Promise<AttentionCoordinator> {
- const coordinator = new AttentionCoordinator(config);
- await coordinator.initialize();
- return coordinator;
-}
diff --git a/v3/integration/feature-flags.ts b/v3/integration/feature-flags.ts
deleted file mode 100644
index 3d47ec87ab..0000000000
--- a/v3/integration/feature-flags.ts
+++ /dev/null
@@ -1,486 +0,0 @@
-/**
- * Feature Flags Configuration System
- *
- * Provides runtime feature flag management for v3 integration,
- * enabling gradual rollout, A/B testing, and environment-specific
- * feature enablement.
- *
- * @module v3/integration/feature-flags
- * @version 3.0.0-alpha.1
- */
-
-import { EventEmitter } from 'events';
-import type { FeatureFlags, DEFAULT_FEATURE_FLAGS } from './types.js';
-
-/**
- * Feature flag metadata
- */
-interface FeatureFlagInfo {
- /** Flag name */
- name: keyof FeatureFlags;
- /** Human-readable description */
- description: string;
- /** Default value */
- defaultValue: boolean;
- /** Whether the flag is experimental */
- experimental: boolean;
- /** Performance impact if enabled */
- performanceImpact: 'none' | 'low' | 'medium' | 'high';
- /** Dependencies on other flags */
- dependencies: (keyof FeatureFlags)[];
- /** Minimum SDK version required */
- minSDKVersion?: string;
-}
-
-/**
- * Feature flag definitions with metadata
- */
-const FEATURE_FLAG_DEFINITIONS: Record<keyof FeatureFlags, FeatureFlagInfo> = {
- enableSONA: {
- name: 'enableSONA',
- description: 'Enable SONA (Self-Optimizing Neural Architecture) learning system',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'low',
- dependencies: [],
- },
- enableFlashAttention: {
- name: 'enableFlashAttention',
- description: 'Enable Flash Attention for 2.49x-7.47x speedup',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'none',
- dependencies: [],
- },
- enableAgentDB: {
- name: 'enableAgentDB',
- description: 'Enable AgentDB vector search with HNSW indexing',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'low',
- dependencies: [],
- },
- enableTrajectoryTracking: {
- name: 'enableTrajectoryTracking',
- description: 'Enable trajectory tracking for experience replay',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'low',
- dependencies: ['enableSONA'],
- },
- enableGNN: {
- name: 'enableGNN',
- description: 'Enable GNN query refinement for +12.4% recall improvement',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'medium',
- dependencies: ['enableAgentDB'],
- minSDKVersion: '2.0.0',
- },
- enableIntelligenceBridge: {
- name: 'enableIntelligenceBridge',
- description: 'Enable intelligence bridge tools for pattern management',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'low',
- dependencies: ['enableSONA'],
- },
- enableQUICTransport: {
- name: 'enableQUICTransport',
- description: 'Enable QUIC transport for faster agent communication',
- defaultValue: false,
- experimental: true,
- performanceImpact: 'low',
- dependencies: [],
- minSDKVersion: '2.0.1',
- },
- enableNightlyLearning: {
- name: 'enableNightlyLearning',
- description: 'Enable automated nightly learning cycles',
- defaultValue: false,
- experimental: true,
- performanceImpact: 'high',
- dependencies: ['enableSONA', 'enableTrajectoryTracking'],
- minSDKVersion: '2.0.1',
- },
- enableAutoConsolidation: {
- name: 'enableAutoConsolidation',
- description: 'Enable automatic pattern consolidation',
- defaultValue: true,
- experimental: false,
- performanceImpact: 'low',
- dependencies: ['enableSONA'],
- },
-};
-
-/**
- * Feature flag source (where the value came from)
- */
-type FlagSource = 'default' | 'config' | 'environment' | 'runtime';
-
-/**
- * FeatureFlagManager - Runtime feature flag management
- */
-export class FeatureFlagManager extends EventEmitter {
- private flags: FeatureFlags;
- private sources: Map<keyof FeatureFlags, FlagSource> = new Map();
- private overrides: Map<keyof FeatureFlags, boolean> = new Map();
- private initialized: boolean = false;
-
- constructor(initialFlags?: Partial<FeatureFlags>) {
- super();
- this.flags = this.initializeFlags(initialFlags);
- }
-
- /**
- * Initialize the feature flag manager
- */
- async initialize(): Promise<void> {
- if (this.initialized) {
- return;
- }
-
- // Load from environment variables
- this.loadFromEnvironment();
-
- // Validate dependencies
- this.validateDependencies();
-
- this.initialized = true;
- this.emit('initialized', { flags: this.getAllFlags() });
- }
-
- /**
- * Get all feature flags
- */
- getAllFlags(): FeatureFlags {
- const result = { ...this.flags };
-
- // Apply overrides
- for (const [flag, value] of this.overrides) {
- result[flag] = value;
- }
-
- return result;
- }
-
- /**
- * Check if a feature is enabled
- */
- isEnabled(flag: keyof FeatureFlags): boolean {
- // Check override first
- if (this.overrides.has(flag)) {
- return this.overrides.get(flag)!;
- }
- return this.flags[flag];
- }
-
- /**
- * Enable a feature
- */
- enable(flag: keyof FeatureFlags, runtime: boolean = true): void {
- const previousValue = this.isEnabled(flag);
-
- // Check dependencies
- const info = FEATURE_FLAG_DEFINITIONS[flag];
- for (const dep of info.dependencies) {
- if (!this.isEnabled(dep)) {
- throw new Error(
- `Cannot enable '${flag}': dependency '${dep}' is not enabled`
- );
- }
- }
-
- if (runtime) {
- this.overrides.set(flag, true);
- this.sources.set(flag, 'runtime');
- } else {
- this.flags[flag] = true;
- this.sources.set(flag, 'config');
- }
-
- if (!previousValue) {
- this.emit('flag-changed', { flag, previousValue, newValue: true });
- }
- }
-
- /**
- * Disable a feature
- */
- disable(flag: keyof FeatureFlags, runtime: boolean = true): void {
- const previousValue = this.isEnabled(flag);
-
- // Check for dependent features
- const dependents = this.getDependentFlags(flag);
- for (const dep of dependents) {
- if (this.isEnabled(dep)) {
- console.warn(
- `Warning: Disabling '${flag}' may affect '${dep}' which depends on it`
- );
- }
- }
-
- if (runtime) {
- this.overrides.set(flag, false);
- this.sources.set(flag, 'runtime');
- } else {
- this.flags[flag] = false;
- this.sources.set(flag, 'config');
- }
-
- if (previousValue) {
- this.emit('flag-changed', { flag, previousValue, newValue: false });
- }
- }
-
- /**
- * Toggle a feature
- */
- toggle(flag: keyof FeatureFlags): boolean {
- const current = this.isEnabled(flag);
- if (current) {
- this.disable(flag);
- } else {
- this.enable(flag);
- }
- return !current;
- }
-
- /**
- * Reset a feature to its default value
- */
- reset(flag: keyof FeatureFlags): void {
- const info = FEATURE_FLAG_DEFINITIONS[flag];
- const previousValue = this.isEnabled(flag);
-
- this.overrides.delete(flag);
- this.flags[flag] = info.defaultValue;
- this.sources.set(flag, 'default');
-
- if (previousValue !== info.defaultValue) {
- this.emit('flag-changed', {
- flag,
- previousValue,
- newValue: info.defaultValue
- });
- }
- }
-
- /**
- * Reset all features to default values
- */
- resetAll(): void {
- this.overrides.clear();
- for (const [flag, info] of Object.entries(FEATURE_FLAG_DEFINITIONS)) {
- this.flags[flag as keyof FeatureFlags] = info.defaultValue;
- this.sources.set(flag as keyof FeatureFlags, 'default');
- }
- this.emit('flags-reset');
- }
-
- /**
- * Get feature flag information
- */
- getFlagInfo(flag: keyof FeatureFlags): FeatureFlagInfo & {
- currentValue: boolean;
- source: FlagSource;
- } {
- return {
- ...FEATURE_FLAG_DEFINITIONS[flag],
- currentValue: this.isEnabled(flag),
- source: this.sources.get(flag) || 'default',
- };
- }
-
- /**
- * Get all flag information
- */
- getAllFlagInfo(): Array<FeatureFlagInfo & {
- currentValue: boolean;
- source: FlagSource;
- }> {
- return Object.keys(FEATURE_FLAG_DEFINITIONS).map(
- flag => this.getFlagInfo(flag as keyof FeatureFlags)
- );
- }
-
- /**
- * Get enabled experimental features
- */
- getEnabledExperimentalFeatures(): (keyof FeatureFlags)[] {
- return Object.entries(FEATURE_FLAG_DEFINITIONS)
- .filter(([flag, info]) => info.experimental && this.isEnabled(flag as keyof FeatureFlags))
- .map(([flag]) => flag as keyof FeatureFlags);
- }
-
- /**
- * Get performance impact of enabled features
- */
- getPerformanceImpact(): {
- none: (keyof FeatureFlags)[];
- low: (keyof FeatureFlags)[];
- medium: (keyof FeatureFlags)[];
- high: (keyof FeatureFlags)[];
- overall: 'none' | 'low' | 'medium' | 'high';
- } {
- const result = {
- none: [] as (keyof FeatureFlags)[],
- low: [] as (keyof FeatureFlags)[],
- medium: [] as (keyof FeatureFlags)[],
- high: [] as (keyof FeatureFlags)[],
- overall: 'none' as 'none' | 'low' | 'medium' | 'high',
- };
-
- for (const [flag, info] of Object.entries(FEATURE_FLAG_DEFINITIONS)) {
- if (this.isEnabled(flag as keyof FeatureFlags)) {
- result[info.performanceImpact].push(flag as keyof FeatureFlags);
- }
- }
-
- // Determine overall impact
- if (result.high.length > 0) {
- result.overall = 'high';
- } else if (result.medium.length > 0) {
- result.overall = 'medium';
- } else if (result.low.length > 0) {
- result.overall = 'low';
- }
-
- return result;
- }
-
- /**
- * Create feature flags from profile
- */
- static fromProfile(profile: 'minimal' | 'standard' | 'full' | 'experimental'): FeatureFlags {
- const profiles: Record<string, Partial<FeatureFlags>> = {
- minimal: {
- enableSONA: false,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: false,
- enableGNN: false,
- enableIntelligenceBridge: false,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: false,
- },
- standard: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false,
- enableNightlyLearning: false,
- enableAutoConsolidation: true,
- },
- full: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: true,
- enableNightlyLearning: true,
- enableAutoConsolidation: true,
- },
- experimental: {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: true,
- enableNightlyLearning: true,
- enableAutoConsolidation: true,
- },
- };
-
- const base = Object.fromEntries(
- Object.entries(FEATURE_FLAG_DEFINITIONS).map(
- ([flag, info]) => [flag, info.defaultValue]
- )
- ) as FeatureFlags;
-
- return { ...base, ...profiles[profile] };
- }
-
- // ===== Private Methods =====
-
- private initializeFlags(initial?: Partial<FeatureFlags>): FeatureFlags {
- const flags = {} as FeatureFlags;
-
- for (const [flag, info] of Object.entries(FEATURE_FLAG_DEFINITIONS)) {
- const key = flag as keyof FeatureFlags;
- flags[key] = initial?.[key] ?? info.defaultValue;
- this.sources.set(key, initial?.[key] !== undefined ? 'config' : 'default');
- }
-
- return flags;
- }
-
- private loadFromEnvironment(): void {
- for (const flag of Object.keys(FEATURE_FLAG_DEFINITIONS)) {
- const envVar = `CLAUDE_FLOW_${flag.replace(/([A-Z])/g, '_$1').toUpperCase()}`;
- const envValue = process.env[envVar];
-
- if (envValue !== undefined) {
- const boolValue = envValue.toLowerCase() === 'true' || envValue === '1';
- this.flags[flag as keyof FeatureFlags] = boolValue;
- this.sources.set(flag as keyof FeatureFlags, 'environment');
- }
- }
- }
-
- private validateDependencies(): void {
- for (const [flag, info] of Object.entries(FEATURE_FLAG_DEFINITIONS)) {
- if (this.isEnabled(flag as keyof FeatureFlags)) {
- for (const dep of info.dependencies) {
- if (!this.isEnabled(dep)) {
- console.warn(
- `Warning: '${flag}' depends on '${dep}' which is disabled. ` +
- `'${flag}' may not work correctly.`
- );
- }
- }
- }
- }
- }
-
- private getDependentFlags(flag: keyof FeatureFlags): (keyof FeatureFlags)[] {
- return Object.entries(FEATURE_FLAG_DEFINITIONS)
- .filter(([_, info]) => info.dependencies.includes(flag))
- .map(([name]) => name as keyof FeatureFlags);
- }
-}
-
-/**
- * Create and initialize a feature flag manager
- */
-export async function createFeatureFlagManager(
- initialFlags?: Partial<FeatureFlags>
-): Promise<FeatureFlagManager> {
- const manager = new FeatureFlagManager(initialFlags);
- await manager.initialize();
- return manager;
-}
-
-/**
- * Default feature flag manager instance
- */
-let defaultManager: FeatureFlagManager | null = null;
-
-/**
- * Get the default feature flag manager
- */
-export async function getDefaultFeatureFlagManager(): Promise<FeatureFlagManager> {
- if (!defaultManager) {
- defaultManager = new FeatureFlagManager();
- await defaultManager.initialize();
- }
- return defaultManager;
-}
diff --git a/v3/integration/index.ts b/v3/integration/index.ts
deleted file mode 100644
index cb8bb66c6a..0000000000
--- a/v3/integration/index.ts
+++ /dev/null
@@ -1,278 +0,0 @@
-/**
- * V3 Integration Module
- *
- * Main entry point for the agentic-flow@alpha integration module.
- * Provides deep integration with SONA learning, Flash Attention,
- * and AgentDB for maximum performance and capability.
- *
- * This module implements ADR-001: Adopt agentic-flow as Core Foundation
- *
- * Key Features:
- * - SONA Learning: Real-time adaptation with <0.05ms response
- * - Flash Attention: 2.49x-7.47x speedup with 50-75% memory reduction
- * - AgentDB: 150x-12,500x faster search via HNSW indexing
- * - Intelligence Bridge: 19 hook tools + 9 learning tools
- * - Trajectory Tracking: Experience replay for continuous learning
- *
- * Usage:
- * ```typescript
- * import { createAgenticFlowBridge } from './v3/integration';
- *
- * const bridge = await createAgenticFlowBridge({
- * features: {
- * enableSONA: true,
- * enableFlashAttention: true,
- * enableAgentDB: true,
- * }
- * });
- *
- * // Get SONA adapter for learning
- * const sona = await bridge.getSONAAdapter();
- * await sona.setMode('real-time');
- *
- * // Get Attention coordinator
- * const attention = await bridge.getAttentionCoordinator();
- * const result = await attention.compute({ query, key, value });
- * ```
- *
- * @module v3/integration
- * @version 3.0.0-alpha.1
- */
-
-// ===== Core Bridge =====
-export {
- AgenticFlowBridge,
- createAgenticFlowBridge,
- getDefaultBridge,
- resetDefaultBridge,
-} from './agentic-flow-bridge.js';
-
-// ===== SONA Adapter =====
-export {
- SONAAdapter,
- createSONAAdapter,
-} from './sona-adapter.js';
-
-// ===== Attention Coordinator =====
-export {
- AttentionCoordinator,
- createAttentionCoordinator,
-} from './attention-coordinator.js';
-
-// ===== SDK Bridge =====
-export {
- SDKBridge,
- createSDKBridge,
-} from './sdk-bridge.js';
-
-// ===== Feature Flags =====
-export {
- FeatureFlagManager,
- createFeatureFlagManager,
- getDefaultFeatureFlagManager,
-} from './feature-flags.js';
-
-// ===== Types =====
-export type {
- // SONA Types
- SONAConfiguration,
- SONALearningMode,
- SONATrajectory,
- SONATrajectoryStep,
- SONAPattern,
- SONALearningStats,
-
- // Attention Types
- AttentionConfiguration,
- AttentionMechanism,
- AttentionResult,
- AttentionMetrics,
-
- // AgentDB Types
- AgentDBConfiguration,
- AgentDBVector,
- AgentDBSearchResult,
- AgentDBStats,
-
- // Integration Types
- IntegrationConfig,
- IntegrationStatus,
- RuntimeInfo,
- ComponentHealth,
- IntegrationEvent,
- IntegrationEventType,
-
- // Feature Flags
- FeatureFlags,
-
- // SDK Types
- SDKVersion,
- SDKCompatibility,
- SDKBridgeConfig,
-} from './types.js';
-
-// ===== Default Configurations =====
-export {
- DEFAULT_SONA_CONFIG,
- DEFAULT_ATTENTION_CONFIG,
- DEFAULT_AGENTDB_CONFIG,
- DEFAULT_FEATURE_FLAGS,
- DEFAULT_INTEGRATION_CONFIG,
-} from './types.js';
-
-// ===== Error Types =====
-export {
- IntegrationError,
-} from './types.js';
-
-// ===== Quick Start Utilities =====
-
-/**
- * Quick initialization with sensible defaults
- */
-export async function quickStart(options?: {
- mode?: 'minimal' | 'standard' | 'full';
- debug?: boolean;
-}): Promise<{
- bridge: import('./agentic-flow-bridge.js').AgenticFlowBridge;
- sona: import('./sona-adapter.js').SONAAdapter | null;
- attention: import('./attention-coordinator.js').AttentionCoordinator | null;
-}> {
- const { AgenticFlowBridge } = await import('./agentic-flow-bridge.js');
- const { FeatureFlagManager } = await import('./feature-flags.js');
-
- const mode = options?.mode || 'standard';
- const flags = FeatureFlagManager.fromProfile(mode);
-
- const bridge = new AgenticFlowBridge({
- features: flags,
- debug: options?.debug ?? false,
- });
-
- await bridge.initialize();
-
- let sona = null;
- let attention = null;
-
- if (flags.enableSONA) {
- sona = await bridge.getSONAAdapter();
- }
-
- if (flags.enableFlashAttention) {
- attention = await bridge.getAttentionCoordinator();
- }
-
- return { bridge, sona, attention };
-}
-
-/**
- * Performance benchmark utility
- */
-export async function benchmark(): Promise<{
- sona: { latencyMs: number; patternsPerSecond: number } | null;
- attention: { latencyMs: number; tokensPerSecond: number } | null;
- overall: { grade: 'A' | 'B' | 'C' | 'D' | 'F' };
-}> {
- const { bridge, sona, attention } = await quickStart({ mode: 'full' });
-
- const results: {
- sona: { latencyMs: number; patternsPerSecond: number } | null;
- attention: { latencyMs: number; tokensPerSecond: number } | null;
- overall: { grade: 'A' | 'B' | 'C' | 'D' | 'F' };
- } = {
- sona: null,
- attention: null,
- overall: { grade: 'C' },
- };
-
- // Benchmark SONA
- if (sona) {
- const start = performance.now();
- const iterations = 100;
-
- for (let i = 0; i < iterations; i++) {
- await sona.storePattern({
- pattern: `test-pattern-${i}`,
- solution: `test-solution-${i}`,
- category: 'benchmark',
- confidence: 0.9,
- });
- }
-
- const duration = performance.now() - start;
- results.sona = {
- latencyMs: duration / iterations,
- patternsPerSecond: (iterations / duration) * 1000,
- };
- }
-
- // Benchmark Attention
- if (attention) {
- const query = new Array(64).fill(0).map(() => Math.random());
- const key = new Array(64).fill(0).map(() => Math.random());
- const value = new Array(64).fill(0).map(() => Math.random());
-
- const start = performance.now();
- const iterations = 100;
-
- for (let i = 0; i < iterations; i++) {
- await attention.compute({ query, key, value });
- }
-
- const duration = performance.now() - start;
- results.attention = {
- latencyMs: duration / iterations,
- tokensPerSecond: (iterations / duration) * 1000,
- };
- }
-
- // Calculate overall grade
- let score = 0;
- if (results.sona && results.sona.latencyMs < 1) score += 50;
- else if (results.sona && results.sona.latencyMs < 5) score += 30;
- else if (results.sona) score += 10;
-
- if (results.attention && results.attention.latencyMs < 1) score += 50;
- else if (results.attention && results.attention.latencyMs < 5) score += 30;
- else if (results.attention) score += 10;
-
- if (score >= 90) results.overall.grade = 'A';
- else if (score >= 70) results.overall.grade = 'B';
- else if (score >= 50) results.overall.grade = 'C';
- else if (score >= 30) results.overall.grade = 'D';
- else results.overall.grade = 'F';
-
- await bridge.shutdown();
-
- return results;
-}
-
-/**
- * Module version
- */
-export const VERSION = '3.0.0-alpha.1';
-
-/**
- * Module metadata
- */
-export const METADATA = {
- name: '@claude-flow/integration',
- version: VERSION,
- description: 'Deep agentic-flow@alpha integration for claude-flow v3',
- implements: ['ADR-001'],
- features: [
- 'SONA Learning (5 modes)',
- 'Flash Attention (8 mechanisms)',
- 'AgentDB (HNSW indexing)',
- 'Intelligence Bridge (19 tools)',
- 'Trajectory Tracking',
- 'Feature Flags',
- 'SDK Compatibility Layer',
- ],
- performance: {
- flashAttentionSpeedup: '2.49x-7.47x',
- agentDBSearchSpeedup: '150x-12,500x',
- sonaAdaptationLatency: '<0.05ms',
- memoryReduction: '50-75%',
- },
-};
diff --git a/v3/integration/sdk-bridge.ts b/v3/integration/sdk-bridge.ts
deleted file mode 100644
index 528b5baf82..0000000000
--- a/v3/integration/sdk-bridge.ts
+++ /dev/null
@@ -1,428 +0,0 @@
-/**
- * SDK Bridge for agentic-flow API Compatibility
- *
- * Provides API compatibility layer between claude-flow v3 and
- * agentic-flow@alpha, handling version negotiation, feature
- * detection, and fallback behavior.
- *
- * Key Responsibilities:
- * - Version negotiation and compatibility checking
- * - API translation for v2 -> v3 migration
- * - Feature detection and graceful degradation
- * - Deprecated API support with warnings
- *
- * @module v3/integration/sdk-bridge
- * @version 3.0.0-alpha.1
- */
-
-import { EventEmitter } from 'events';
-import type {
- SDKBridgeConfig,
- SDKVersion,
- SDKCompatibility,
-} from './types.js';
-
-/**
- * Feature availability by SDK version
- */
-const FEATURE_MATRIX: Record<string, { minVersion: string; optional: boolean }> = {
- 'sona-learning': { minVersion: '2.0.0', optional: false },
- 'flash-attention': { minVersion: '2.0.0', optional: false },
- 'agentdb-hnsw': { minVersion: '2.0.0', optional: false },
- 'gnn-refinement': { minVersion: '2.0.0', optional: true },
- 'trajectory-tracking': { minVersion: '2.0.0', optional: false },
- 'intelligence-bridge': { minVersion: '2.0.1', optional: false },
- 'quic-transport': { minVersion: '2.0.1', optional: true },
- 'nightly-learning': { minVersion: '2.0.1', optional: true },
- 'micro-lora': { minVersion: '2.0.1', optional: true },
-};
-
-/**
- * Deprecated API mappings (old -> new)
- */
-const DEPRECATED_API_MAP: Record<string, {
- replacement: string;
- since: string;
- removed?: string;
- transformer?: (args: unknown[]) => unknown[];
-}> = {
- 'ReasoningBank.initialize': {
- replacement: 'HybridReasoningBank.initialize',
- since: '2.0.0',
- },
- 'AgentDB.store': {
- replacement: 'AgentDBFast.store',
- since: '2.0.0',
- transformer: (args) => args, // Same signature
- },
- 'computeEmbedding': {
- replacement: 'EmbeddingService.compute',
- since: '2.0.0',
- },
-};
-
-/**
- * SDKBridge - API Compatibility Layer
- *
- * This bridge handles version compatibility, feature detection,
- * and API translation between claude-flow and agentic-flow.
- */
-export class SDKBridge extends EventEmitter {
- private config: SDKBridgeConfig;
- private initialized: boolean = false;
- private currentVersion: SDKVersion | null = null;
- private availableFeatures: Set<string> = new Set();
- private deprecationWarnings: Set<string> = new Set();
-
- constructor(config: Partial<SDKBridgeConfig> = {}) {
- super();
- this.config = this.mergeConfig(config);
- }
-
- /**
- * Initialize the SDK bridge
- */
- async initialize(): Promise<void> {
- if (this.initialized) {
- return;
- }
-
- this.emit('initializing');
-
- try {
- // Detect SDK version
- this.currentVersion = await this.detectVersion();
-
- // Check compatibility
- const compatibility = await this.checkCompatibility();
- if (!compatibility.compatible) {
- throw new Error(
- `SDK version ${this.currentVersion.full} is not compatible. ` +
- `Required: ${compatibility.minVersion.full} - ${compatibility.maxVersion.full}`
- );
- }
-
- // Detect available features
- await this.detectFeatures();
-
- this.initialized = true;
- this.emit('initialized', {
- version: this.currentVersion,
- features: Array.from(this.availableFeatures)
- });
- } catch (error) {
- this.emit('initialization-failed', { error });
- throw error;
- }
- }
-
- /**
- * Ping to check if SDK is available
- */
- async ping(): Promise<boolean> {
- // Simple health check
- return this.initialized;
- }
-
- /**
- * Get current SDK version
- */
- getVersion(): SDKVersion | null {
- return this.currentVersion;
- }
-
- /**
- * Check if a feature is available
- */
- isFeatureAvailable(feature: string): boolean {
- return this.availableFeatures.has(feature);
- }
-
- /**
- * Get all available features
- */
- getAvailableFeatures(): string[] {
- return Array.from(this.availableFeatures);
- }
-
- /**
- * Get compatibility information
- */
- async checkCompatibility(): Promise<SDKCompatibility> {
- const current = this.currentVersion || await this.detectVersion();
-
- const minVersion = this.parseVersion('2.0.0-alpha.0');
- const maxVersion = this.parseVersion('3.0.0');
-
- const compatible =
- this.compareVersions(current, minVersion) >= 0 &&
- this.compareVersions(current, maxVersion) < 0;
-
- const requiredFeatures = Object.entries(FEATURE_MATRIX)
- .filter(([_, info]) => !info.optional)
- .map(([name]) => name);
-
- const optionalFeatures = Object.entries(FEATURE_MATRIX)
- .filter(([_, info]) => info.optional)
- .map(([name]) => name);
-
- return {
- minVersion,
- maxVersion,
- currentVersion: current,
- compatible,
- requiredFeatures,
- optionalFeatures,
- };
- }
-
- /**
- * Translate deprecated API call to new API
- */
- translateDeprecatedAPI(
- oldAPI: string,
- args: unknown[]
- ): { newAPI: string; args: unknown[] } | null {
- const mapping = DEPRECATED_API_MAP[oldAPI];
- if (!mapping) {
- return null;
- }
-
- // Emit deprecation warning (once per API)
- if (!this.deprecationWarnings.has(oldAPI)) {
- this.deprecationWarnings.add(oldAPI);
- const message = `'${oldAPI}' is deprecated since ${mapping.since}. ` +
- `Use '${mapping.replacement}' instead.`;
-
- switch (this.config.fallbackBehavior) {
- case 'error':
- throw new Error(message);
- case 'warn':
- console.warn(`[DEPRECATED] ${message}`);
- this.emit('deprecation-warning', { oldAPI, mapping });
- break;
- case 'silent':
- // Log but don't warn
- break;
- }
- }
-
- const newArgs = mapping.transformer ? mapping.transformer(args) : args;
- return { newAPI: mapping.replacement, args: newArgs };
- }
-
- /**
- * Wrap an API call with compatibility handling
- */
- async wrapAPICall<T>(
- apiName: string,
- apiCall: () => Promise<T>,
- fallback?: () => Promise<T>
- ): Promise<T> {
- this.ensureInitialized();
-
- try {
- return await apiCall();
- } catch (error) {
- // Check if this is a version-related error
- if (this.isVersionError(error)) {
- if (fallback) {
- this.emit('fallback-used', { apiName, error });
- return await fallback();
- }
- }
- throw error;
- }
- }
-
- /**
- * Get feature requirements for a capability
- */
- getFeatureRequirements(capability: string): {
- required: string[];
- optional: string[];
- satisfied: boolean;
- } {
- const capabilityFeatures: Record<string, { required: string[]; optional: string[] }> = {
- 'learning': {
- required: ['sona-learning', 'trajectory-tracking'],
- optional: ['nightly-learning', 'micro-lora'],
- },
- 'attention': {
- required: ['flash-attention'],
- optional: [],
- },
- 'search': {
- required: ['agentdb-hnsw'],
- optional: ['gnn-refinement'],
- },
- 'coordination': {
- required: ['sona-learning', 'flash-attention'],
- optional: ['quic-transport'],
- },
- };
-
- const features = capabilityFeatures[capability] || { required: [], optional: [] };
- const satisfied = features.required.every(f => this.availableFeatures.has(f));
-
- return {
- ...features,
- satisfied,
- };
- }
-
- /**
- * Negotiate version with remote SDK
- */
- async negotiateVersion(preferredVersion?: string): Promise<SDKVersion> {
- // In a real implementation, this would communicate with the SDK
- // to determine the best compatible version to use
-
- const preferred = preferredVersion
- ? this.parseVersion(preferredVersion)
- : this.currentVersion;
-
- if (!preferred) {
- return this.currentVersion || this.parseVersion('2.0.1-alpha.50');
- }
-
- // Return the negotiated version
- return preferred;
- }
-
- /**
- * Get migration guide for deprecated APIs
- */
- getMigrationGuide(): Record<string, {
- old: string;
- new: string;
- example: string;
- }> {
- const guide: Record<string, { old: string; new: string; example: string }> = {};
-
- for (const [oldAPI, mapping] of Object.entries(DEPRECATED_API_MAP)) {
- guide[oldAPI] = {
- old: oldAPI,
- new: mapping.replacement,
- example: this.generateMigrationExample(oldAPI, mapping.replacement),
- };
- }
-
- return guide;
- }
-
- /**
- * Shutdown the bridge
- */
- async shutdown(): Promise<void> {
- this.initialized = false;
- this.availableFeatures.clear();
- this.deprecationWarnings.clear();
- this.emit('shutdown');
- }
-
- // ===== Private Methods =====
-
- private mergeConfig(config: Partial<SDKBridgeConfig>): SDKBridgeConfig {
- return {
- targetVersion: config.targetVersion || 'alpha',
- enableVersionNegotiation: config.enableVersionNegotiation ?? true,
- fallbackBehavior: config.fallbackBehavior || 'warn',
- enableCompatibilityLayer: config.enableCompatibilityLayer ?? true,
- supportDeprecatedAPIs: config.supportDeprecatedAPIs ?? true,
- };
- }
-
- private async detectVersion(): Promise<SDKVersion> {
- // In production, this would detect the actual agentic-flow version
- // For now, return the alpha version
- return this.parseVersion('2.0.1-alpha.50');
- }
-
- private async detectFeatures(): Promise<void> {
- if (!this.currentVersion) {
- return;
- }
-
- for (const [feature, info] of Object.entries(FEATURE_MATRIX)) {
- const minVersion = this.parseVersion(info.minVersion);
- if (this.compareVersions(this.currentVersion, minVersion) >= 0) {
- this.availableFeatures.add(feature);
- }
- }
-
- this.emit('features-detected', {
- features: Array.from(this.availableFeatures)
- });
- }
-
- private parseVersion(version: string): SDKVersion {
- // Handle versions like "2.0.1-alpha.50" or "2.0.0"
- const parts = version.split('-');
- const core = parts[0].split('.');
- const prerelease = parts[1] || undefined;
-
- return {
- major: parseInt(core[0] || '0', 10),
- minor: parseInt(core[1] || '0', 10),
- patch: parseInt(core[2] || '0', 10),
- prerelease,
- full: version,
- };
- }
-
- private compareVersions(a: SDKVersion, b: SDKVersion): number {
- // Compare major, minor, patch
- if (a.major !== b.major) return a.major - b.major;
- if (a.minor !== b.minor) return a.minor - b.minor;
- if (a.patch !== b.patch) return a.patch - b.patch;
-
- // Compare prerelease (alpha < beta < rc < release)
- if (!a.prerelease && b.prerelease) return 1;
- if (a.prerelease && !b.prerelease) return -1;
- if (!a.prerelease && !b.prerelease) return 0;
-
- // Both have prerelease
- return (a.prerelease || '').localeCompare(b.prerelease || '');
- }
-
- private isVersionError(error: unknown): boolean {
- const message = (error as Error)?.message || '';
- return message.includes('version') ||
- message.includes('not supported') ||
- message.includes('deprecated');
- }
-
- private generateMigrationExample(oldAPI: string, newAPI: string): string {
- // Generate a simple migration example
- const oldParts = oldAPI.split('.');
- const newParts = newAPI.split('.');
-
- const oldCall = oldParts.length > 1
- ? `${oldParts[0]}.${oldParts[1]}(args)`
- : `${oldAPI}(args)`;
-
- const newCall = newParts.length > 1
- ? `new ${newParts[0]}().${newParts[1]}(args)`
- : `${newAPI}(args)`;
-
- return `// Before:\n${oldCall}\n\n// After:\n${newCall}`;
- }
-
- private ensureInitialized(): void {
- if (!this.initialized) {
- throw new Error('SDKBridge not initialized. Call initialize() first.');
- }
- }
-}
-
-/**
- * Create and initialize an SDK bridge
- */
-export async function createSDKBridge(
- config?: Partial<SDKBridgeConfig>
-): Promise<SDKBridge> {
- const bridge = new SDKBridge(config);
- await bridge.initialize();
- return bridge;
-}
diff --git a/v3/integration/sona-adapter.ts b/v3/integration/sona-adapter.ts
deleted file mode 100644
index fd89b65a24..0000000000
--- a/v3/integration/sona-adapter.ts
+++ /dev/null
@@ -1,824 +0,0 @@
-/**
- * SONA (Self-Optimizing Neural Architecture) Adapter
- *
- * Provides integration with agentic-flow's SONA learning system,
- * enabling real-time adaptation, pattern recognition, and
- * continuous learning capabilities.
- *
- * Performance Targets:
- * - Real-time mode: ~0.05ms adaptation
- * - Balanced mode: General purpose learning
- * - Research mode: Deep exploration with higher accuracy
- *
- * @module v3/integration/sona-adapter
- * @version 3.0.0-alpha.1
- */
-
-import { EventEmitter } from 'events';
-import type {
- SONAConfiguration,
- SONALearningMode,
- SONATrajectory,
- SONATrajectoryStep,
- SONAPattern,
- SONALearningStats,
- DEFAULT_SONA_CONFIG,
-} from './types.js';
-
-/**
- * Interface for agentic-flow SONA reference (for delegation)
- * This allows the adapter to delegate to agentic-flow when available
- */
-interface AgenticFlowSONAReference {
- setMode(mode: string): Promise<void>;
- storePattern(params: {
- pattern: string;
- solution: string;
- category: string;
- confidence: number;
- metadata?: Record<string, unknown>;
- }): Promise<string>;
- findPatterns(query: string, options?: {
- category?: string;
- topK?: number;
- threshold?: number;
- }): Promise<Array<{
- id: string;
- pattern: string;
- solution: string;
- category: string;
- confidence: number;
- usageCount: number;
- createdAt: number;
- lastUsedAt: number;
- metadata: Record<string, unknown>;
- }>>;
- getStats(): Promise<unknown>;
- beginTrajectory?(params: unknown): Promise<string>;
- recordStep?(params: unknown): Promise<void>;
- endTrajectory?(params: unknown): Promise<unknown>;
-}
-
-/**
- * Mode-specific configurations for SONA learning
- */
-const MODE_CONFIGS: Record<SONALearningMode, Partial<SONAConfiguration>> = {
- 'real-time': {
- learningRate: 0.01,
- similarityThreshold: 0.8,
- maxPatterns: 5000,
- consolidationInterval: 1800000, // 30 minutes
- },
- 'balanced': {
- learningRate: 0.001,
- similarityThreshold: 0.7,
- maxPatterns: 10000,
- consolidationInterval: 3600000, // 1 hour
- },
- 'research': {
- learningRate: 0.0001,
- similarityThreshold: 0.6,
- maxPatterns: 50000,
- consolidationInterval: 7200000, // 2 hours
- },
- 'edge': {
- learningRate: 0.005,
- similarityThreshold: 0.85,
- maxPatterns: 1000,
- consolidationInterval: 900000, // 15 minutes
- },
- 'batch': {
- learningRate: 0.0005,
- similarityThreshold: 0.65,
- maxPatterns: 100000,
- consolidationInterval: 14400000, // 4 hours
- },
-};
-
-/**
- * SONAAdapter - SONA Learning System Integration
- *
- * This adapter provides a clean interface to agentic-flow's SONA
- * learning capabilities, including:
- * - Learning mode selection and auto-switching
- * - Trajectory tracking for experience replay
- * - Pattern storage and retrieval
- * - Memory distillation and consolidation
- */
-export class SONAAdapter extends EventEmitter {
- private config: SONAConfiguration;
- private initialized: boolean = false;
- private activeTrajectories: Map<string, SONATrajectory> = new Map();
- private patterns: Map<string, SONAPattern> = new Map();
- private stats: SONALearningStats;
- private consolidationTimer: NodeJS.Timeout | null = null;
- private learningCycleCount: number = 0;
-
- /**
- * Reference to agentic-flow SONA for delegation (ADR-001)
- * When set, methods delegate to agentic-flow instead of local implementation
- */
- private agenticFlowSona: AgenticFlowSONAReference | null = null;
-
- /**
- * Indicates if delegation to agentic-flow is active
- */
- private delegationEnabled: boolean = false;
-
- constructor(config: Partial<SONAConfiguration> = {}) {
- super();
- this.config = this.mergeConfig(config);
- this.stats = this.initializeStats();
- }
-
- /**
- * Set reference to agentic-flow SONA for delegation
- *
- * This implements ADR-001: Adopt agentic-flow as Core Foundation
- * When a reference is provided, pattern storage and retrieval
- * delegate to agentic-flow's optimized implementations.
- *
- * @param sonaRef - The agentic-flow SONA interface reference
- */
- setAgenticFlowReference(sonaRef: AgenticFlowSONAReference): void {
- this.agenticFlowSona = sonaRef;
- this.delegationEnabled = true;
- this.emit('delegation-enabled', { target: 'agentic-flow' });
- }
-
- /**
- * Check if delegation to agentic-flow is enabled
- */
- isDelegationEnabled(): boolean {
- return this.delegationEnabled && this.agenticFlowSona !== null;
- }
-
- /**
- * Initialize the SONA adapter
- */
- async initialize(): Promise<void> {
- if (this.initialized) {
- return;
- }
-
- this.emit('initializing');
-
- try {
- // Apply mode-specific configuration
- this.applyModeConfig(this.config.mode);
-
- // Start consolidation timer if enabled
- if (this.config.consolidationInterval > 0) {
- this.startConsolidationTimer();
- }
-
- this.initialized = true;
- this.emit('initialized', { mode: this.config.mode });
- } catch (error) {
- this.emit('initialization-failed', { error });
- throw error;
- }
- }
-
- /**
- * Reconfigure the adapter
- */
- async reconfigure(config: Partial<SONAConfiguration>): Promise<void> {
- this.config = this.mergeConfig(config);
-
- if (config.mode) {
- this.applyModeConfig(config.mode);
- }
-
- // Restart consolidation timer with new interval
- if (config.consolidationInterval !== undefined) {
- this.stopConsolidationTimer();
- if (config.consolidationInterval > 0) {
- this.startConsolidationTimer();
- }
- }
-
- this.emit('reconfigured', { config: this.config });
- }
-
- /**
- * Get current learning mode
- */
- getMode(): SONALearningMode {
- return this.config.mode;
- }
-
- /**
- * Set learning mode
- */
- async setMode(mode: SONALearningMode): Promise<void> {
- const previousMode = this.config.mode;
- this.config.mode = mode;
- this.applyModeConfig(mode);
-
- this.emit('mode-changed', {
- previousMode,
- newMode: mode,
- config: MODE_CONFIGS[mode]
- });
- }
-
- /**
- * Begin a new trajectory for task tracking
- */
- async beginTrajectory(params: {
- taskId: string;
- description?: string;
- category?: string;
- metadata?: Record<string, unknown>;
- }): Promise<string> {
- this.ensureInitialized();
-
- const trajectoryId = this.generateId('traj');
- const trajectory: SONATrajectory = {
- id: trajectoryId,
- taskId: params.taskId,
- steps: [],
- startTime: Date.now(),
- totalReward: 0,
- metadata: {
- description: params.description,
- category: params.category,
- ...params.metadata,
- },
- };
-
- this.activeTrajectories.set(trajectoryId, trajectory);
- this.stats.activeTrajectories++;
-
- this.emit('trajectory-started', { trajectoryId, taskId: params.taskId });
- return trajectoryId;
- }
-
- /**
- * Record a step in an active trajectory
- */
- async recordTrajectoryStep(params: {
- trajectoryId: string;
- stepId?: string;
- action: string;
- observation: string;
- reward: number;
- embedding?: number[];
- }): Promise<void> {
- this.ensureInitialized();
-
- const trajectory = this.activeTrajectories.get(params.trajectoryId);
- if (!trajectory) {
- throw new Error(`Trajectory ${params.trajectoryId} not found`);
- }
-
- const step: SONATrajectoryStep = {
- stepId: params.stepId || this.generateId('step'),
- action: params.action,
- observation: params.observation,
- reward: params.reward,
- timestamp: Date.now(),
- embedding: params.embedding,
- };
-
- trajectory.steps.push(step);
- trajectory.totalReward += params.reward;
-
- this.emit('trajectory-step-recorded', {
- trajectoryId: params.trajectoryId,
- step
- });
- }
-
- /**
- * End a trajectory with final verdict
- */
- async endTrajectory(params: {
- trajectoryId: string;
- success: boolean;
- verdict?: 'positive' | 'negative' | 'neutral';
- reward?: number;
- }): Promise<SONATrajectory> {
- this.ensureInitialized();
-
- const trajectory = this.activeTrajectories.get(params.trajectoryId);
- if (!trajectory) {
- throw new Error(`Trajectory ${params.trajectoryId} not found`);
- }
-
- // Finalize trajectory
- trajectory.endTime = Date.now();
- trajectory.verdict = params.verdict || (params.success ? 'positive' : 'negative');
-
- if (params.reward !== undefined) {
- trajectory.totalReward += params.reward;
- }
-
- // Remove from active and update stats
- this.activeTrajectories.delete(params.trajectoryId);
- this.stats.activeTrajectories--;
- this.stats.completedTrajectories++;
-
- // Learn from successful trajectories
- if (params.success && trajectory.verdict === 'positive') {
- await this.learnFromTrajectory(trajectory);
- }
-
- this.emit('trajectory-completed', {
- trajectoryId: params.trajectoryId,
- trajectory
- });
-
- return trajectory;
- }
-
- /**
- * Store a learned pattern
- *
- * ADR-001: When agentic-flow is available, delegates to its optimized
- * pattern storage which uses AgentDB with HNSW indexing for
- * 150x-12,500x faster similarity search.
- */
- async storePattern(params: {
- pattern: string;
- solution: string;
- category: string;
- confidence: number;
- metadata?: Record<string, unknown>;
- }): Promise<string> {
- this.ensureInitialized();
-
- // ADR-001: Delegate to agentic-flow when available
- if (this.isDelegationEnabled() && this.agenticFlowSona) {
- try {
- const patternId = await this.agenticFlowSona.storePattern({
- pattern: params.pattern,
- solution: params.solution,
- category: params.category,
- confidence: Math.max(0, Math.min(1, params.confidence)),
- metadata: params.metadata,
- });
-
- this.stats.totalPatterns++;
- this.emit('pattern-stored', {
- patternId,
- delegated: true,
- target: 'agentic-flow',
- });
-
- return patternId;
- } catch (error) {
- // Log delegation failure and fall back to local implementation
- this.emit('delegation-failed', {
- method: 'storePattern',
- error: (error as Error).message,
- fallback: 'local',
- });
- // Continue with local implementation below
- }
- }
-
- // Local implementation (fallback or when agentic-flow not available)
- const patternId = this.generateId('pat');
- const storedPattern: SONAPattern = {
- id: patternId,
- pattern: params.pattern,
- solution: params.solution,
- category: params.category,
- confidence: Math.max(0, Math.min(1, params.confidence)),
- usageCount: 0,
- createdAt: Date.now(),
- lastUsedAt: Date.now(),
- metadata: params.metadata || {},
- };
-
- // Check if we need to prune patterns
- if (this.patterns.size >= this.config.maxPatterns) {
- await this.prunePatterns();
- }
-
- this.patterns.set(patternId, storedPattern);
- this.stats.totalPatterns++;
- this.updateAverageConfidence();
-
- this.emit('pattern-stored', { patternId, pattern: storedPattern });
- return patternId;
- }
-
- /**
- * Find similar patterns to a query
- *
- * ADR-001: When agentic-flow is available, delegates to its optimized
- * HNSW-indexed search for 150x-12,500x faster retrieval.
- */
- async findSimilarPatterns(params: {
- query: string;
- category?: string;
- topK?: number;
- threshold?: number;
- }): Promise<SONAPattern[]> {
- this.ensureInitialized();
-
- const topK = params.topK || 5;
- const threshold = params.threshold ?? this.config.similarityThreshold;
-
- // ADR-001: Delegate to agentic-flow when available for optimized search
- if (this.isDelegationEnabled() && this.agenticFlowSona) {
- try {
- const results = await this.agenticFlowSona.findPatterns(params.query, {
- category: params.category,
- topK,
- threshold,
- });
-
- // Map results to SONAPattern format
- const patterns: SONAPattern[] = results.map(r => ({
- id: r.id,
- pattern: r.pattern,
- solution: r.solution,
- category: r.category,
- confidence: r.confidence,
- usageCount: r.usageCount,
- createdAt: r.createdAt,
- lastUsedAt: r.lastUsedAt,
- metadata: r.metadata,
- }));
-
- this.emit('patterns-retrieved', {
- query: params.query,
- count: patterns.length,
- delegated: true,
- target: 'agentic-flow',
- });
-
- return patterns;
- } catch (error) {
- // Log delegation failure and fall back to local implementation
- this.emit('delegation-failed', {
- method: 'findSimilarPatterns',
- error: (error as Error).message,
- fallback: 'local',
- });
- // Continue with local implementation below
- }
- }
-
- // Local implementation (fallback or when agentic-flow not available)
- const results: Array<{ pattern: SONAPattern; score: number }> = [];
-
- for (const pattern of this.patterns.values()) {
- // Filter by category if specified
- if (params.category && pattern.category !== params.category) {
- continue;
- }
-
- // Calculate similarity (simplified - in production use embeddings)
- const score = this.calculateSimilarity(params.query, pattern.pattern);
-
- if (score >= threshold) {
- results.push({ pattern, score });
- }
- }
-
- // Sort by score and return top K
- results.sort((a, b) => b.score - a.score);
- const topResults = results.slice(0, topK).map(r => {
- // Update usage stats
- r.pattern.usageCount++;
- r.pattern.lastUsedAt = Date.now();
- return r.pattern;
- });
-
- this.emit('patterns-retrieved', {
- query: params.query,
- count: topResults.length
- });
-
- return topResults;
- }
-
- /**
- * Get a pattern by ID
- */
- async getPattern(patternId: string): Promise<SONAPattern | null> {
- this.ensureInitialized();
- return this.patterns.get(patternId) || null;
- }
-
- /**
- * Delete a pattern
- */
- async deletePattern(patternId: string): Promise<boolean> {
- this.ensureInitialized();
-
- const deleted = this.patterns.delete(patternId);
- if (deleted) {
- this.stats.totalPatterns--;
- this.updateAverageConfidence();
- this.emit('pattern-deleted', { patternId });
- }
-
- return deleted;
- }
-
- /**
- * Force a learning cycle
- */
- async forceLearningCycle(): Promise<void> {
- this.ensureInitialized();
-
- this.emit('learning-cycle-starting');
-
- try {
- // Consolidate patterns
- await this.consolidatePatterns();
-
- // Prune low-confidence patterns
- await this.prunePatterns();
-
- // Update statistics
- this.learningCycleCount++;
- this.stats.learningCycles = this.learningCycleCount;
-
- this.emit('learning-cycle-completed', {
- cycleCount: this.learningCycleCount
- });
- } catch (error) {
- this.emit('learning-cycle-failed', { error });
- throw error;
- }
- }
-
- /**
- * Get learning statistics
- */
- async getStats(): Promise<SONALearningStats> {
- this.ensureInitialized();
-
- return {
- ...this.stats,
- totalPatterns: this.patterns.size,
- activeTrajectories: this.activeTrajectories.size,
- currentMode: this.config.mode,
- memoryUsage: this.estimateMemoryUsage(),
- };
- }
-
- /**
- * Export patterns for persistence
- */
- async exportPatterns(): Promise<SONAPattern[]> {
- this.ensureInitialized();
- return Array.from(this.patterns.values());
- }
-
- /**
- * Import patterns from storage
- */
- async importPatterns(patterns: SONAPattern[]): Promise<number> {
- this.ensureInitialized();
-
- let imported = 0;
- for (const pattern of patterns) {
- if (!this.patterns.has(pattern.id)) {
- this.patterns.set(pattern.id, pattern);
- imported++;
- }
- }
-
- this.stats.totalPatterns = this.patterns.size;
- this.updateAverageConfidence();
-
- this.emit('patterns-imported', { count: imported });
- return imported;
- }
-
- /**
- * Shutdown the adapter
- */
- async shutdown(): Promise<void> {
- this.stopConsolidationTimer();
-
- // Complete any active trajectories
- for (const [id, trajectory] of this.activeTrajectories) {
- trajectory.endTime = Date.now();
- trajectory.verdict = 'neutral';
- }
- this.activeTrajectories.clear();
-
- this.initialized = false;
- this.emit('shutdown');
- }
-
- // ===== Private Methods =====
-
- private mergeConfig(config: Partial<SONAConfiguration>): SONAConfiguration {
- return {
- mode: config.mode || 'balanced',
- learningRate: config.learningRate ?? 0.001,
- similarityThreshold: config.similarityThreshold ?? 0.7,
- maxPatterns: config.maxPatterns ?? 10000,
- enableTrajectoryTracking: config.enableTrajectoryTracking ?? true,
- consolidationInterval: config.consolidationInterval ?? 3600000,
- autoModeSelection: config.autoModeSelection ?? true,
- };
- }
-
- private initializeStats(): SONALearningStats {
- return {
- totalPatterns: 0,
- activeTrajectories: 0,
- completedTrajectories: 0,
- averageConfidence: 0,
- learningCycles: 0,
- lastConsolidation: Date.now(),
- memoryUsage: 0,
- currentMode: this.config.mode,
- };
- }
-
- private applyModeConfig(mode: SONALearningMode): void {
- const modeConfig = MODE_CONFIGS[mode];
- if (modeConfig) {
- Object.assign(this.config, modeConfig);
- }
- }
-
- private startConsolidationTimer(): void {
- this.consolidationTimer = setInterval(
- () => this.consolidatePatterns(),
- this.config.consolidationInterval
- );
- }
-
- private stopConsolidationTimer(): void {
- if (this.consolidationTimer) {
- clearInterval(this.consolidationTimer);
- this.consolidationTimer = null;
- }
- }
-
- private async consolidatePatterns(): Promise<void> {
- // Merge similar patterns
- const patternsArray = Array.from(this.patterns.values());
- const toRemove: Set<string> = new Set();
-
- for (let i = 0; i < patternsArray.length; i++) {
- if (toRemove.has(patternsArray[i].id)) continue;
-
- for (let j = i + 1; j < patternsArray.length; j++) {
- if (toRemove.has(patternsArray[j].id)) continue;
-
- const similarity = this.calculateSimilarity(
- patternsArray[i].pattern,
- patternsArray[j].pattern
- );
-
- if (similarity > 0.95) {
- // Merge into pattern with higher confidence
- if (patternsArray[i].confidence >= patternsArray[j].confidence) {
- patternsArray[i].usageCount += patternsArray[j].usageCount;
- toRemove.add(patternsArray[j].id);
- } else {
- patternsArray[j].usageCount += patternsArray[i].usageCount;
- toRemove.add(patternsArray[i].id);
- }
- }
- }
- }
-
- // Remove merged patterns
- for (const id of toRemove) {
- this.patterns.delete(id);
- }
-
- this.stats.lastConsolidation = Date.now();
- this.emit('consolidation-completed', {
- removed: toRemove.size,
- remaining: this.patterns.size
- });
- }
-
- private async prunePatterns(): Promise<void> {
- const maxPatterns = this.config.maxPatterns;
- if (this.patterns.size <= maxPatterns) {
- return;
- }
-
- // Sort patterns by score (combination of confidence, recency, and usage)
- const scored = Array.from(this.patterns.entries()).map(([id, pattern]) => ({
- id,
- pattern,
- score: this.calculatePatternScore(pattern),
- }));
-
- scored.sort((a, b) => b.score - a.score);
-
- // Keep only top patterns
- const toKeep = new Set(scored.slice(0, maxPatterns).map(s => s.id));
-
- for (const id of this.patterns.keys()) {
- if (!toKeep.has(id)) {
- this.patterns.delete(id);
- }
- }
-
- this.emit('patterns-pruned', {
- removed: scored.length - maxPatterns,
- remaining: this.patterns.size
- });
- }
-
- private async learnFromTrajectory(trajectory: SONATrajectory): Promise<void> {
- // Extract patterns from successful trajectory
- if (trajectory.steps.length === 0) return;
-
- const pattern = trajectory.steps.map(s => s.action).join(' -> ');
- const solution = trajectory.steps[trajectory.steps.length - 1].observation;
-
- await this.storePattern({
- pattern,
- solution,
- category: (trajectory.metadata.category as string) || 'general',
- confidence: Math.min(1, trajectory.totalReward / trajectory.steps.length),
- metadata: {
- trajectoryId: trajectory.id,
- taskId: trajectory.taskId,
- stepCount: trajectory.steps.length,
- },
- });
- }
-
- private calculateSimilarity(a: string, b: string): number {
- // Jaccard similarity on words (simplified)
- const wordsA = new Set(a.toLowerCase().split(/\s+/));
- const wordsB = new Set(b.toLowerCase().split(/\s+/));
-
- const intersection = new Set([...wordsA].filter(x => wordsB.has(x)));
- const union = new Set([...wordsA, ...wordsB]);
-
- return intersection.size / union.size;
- }
-
- private calculatePatternScore(pattern: SONAPattern): number {
- const now = Date.now();
- const ageMs = now - pattern.createdAt;
- const recencyMs = now - pattern.lastUsedAt;
-
- // Normalize age and recency (decay over 30 days)
- const ageFactor = Math.exp(-ageMs / (30 * 24 * 60 * 60 * 1000));
- const recencyFactor = Math.exp(-recencyMs / (7 * 24 * 60 * 60 * 1000));
- const usageFactor = Math.min(1, pattern.usageCount / 100);
-
- return (
- pattern.confidence * 0.4 +
- recencyFactor * 0.3 +
- usageFactor * 0.2 +
- ageFactor * 0.1
- );
- }
-
- private updateAverageConfidence(): void {
- if (this.patterns.size === 0) {
- this.stats.averageConfidence = 0;
- return;
- }
-
- let total = 0;
- for (const pattern of this.patterns.values()) {
- total += pattern.confidence;
- }
- this.stats.averageConfidence = total / this.patterns.size;
- }
-
- private estimateMemoryUsage(): number {
- // Rough estimate: 500 bytes per pattern, 1KB per trajectory step
- const patternBytes = this.patterns.size * 500;
- const trajectoryBytes = Array.from(this.activeTrajectories.values())
- .reduce((sum, t) => sum + t.steps.length * 1024, 0);
-
- return patternBytes + trajectoryBytes;
- }
-
- private generateId(prefix: string): string {
- return `${prefix}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
- }
-
- private ensureInitialized(): void {
- if (!this.initialized) {
- throw new Error('SONAAdapter not initialized. Call initialize() first.');
- }
- }
-}
-
-/**
- * Create and initialize a SONA adapter
- */
-export async function createSONAAdapter(
- config?: Partial<SONAConfiguration>
-): Promise<SONAAdapter> {
- const adapter = new SONAAdapter(config);
- await adapter.initialize();
- return adapter;
-}
diff --git a/v3/integration/types.ts b/v3/integration/types.ts
deleted file mode 100644
index 789cc3ce6c..0000000000
--- a/v3/integration/types.ts
+++ /dev/null
@@ -1,494 +0,0 @@
-/**
- * V3 Integration Module Types
- *
- * Type definitions for deep integration with agentic-flow@alpha.
- * Implements ADR-001: Adopt agentic-flow as Core Foundation
- *
- * @module v3/integration/types
- * @version 3.0.0-alpha.1
- */
-
-// ===== SONA Learning Mode Types =====
-
-/**
- * SONA (Self-Optimizing Neural Architecture) learning modes.
- * Each mode optimizes for different performance characteristics.
- */
-export type SONALearningMode =
- | 'real-time' // ~0.05ms adaptation, sub-millisecond response
- | 'balanced' // General purpose learning, moderate latency
- | 'research' // Deep exploration mode, higher accuracy
- | 'edge' // Resource-constrained environments
- | 'batch'; // High-throughput processing
-
-export interface SONAConfiguration {
- /** Active learning mode */
- mode: SONALearningMode;
- /** Learning rate for adaptation (0.0001 - 0.1) */
- learningRate: number;
- /** Pattern similarity threshold (0.0 - 1.0) */
- similarityThreshold: number;
- /** Maximum patterns to retain in memory */
- maxPatterns: number;
- /** Enable trajectory tracking for experience replay */
- enableTrajectoryTracking: boolean;
- /** Consolidation interval in milliseconds */
- consolidationInterval: number;
- /** Enable auto-mode selection based on workload */
- autoModeSelection: boolean;
-}
-
-export interface SONATrajectory {
- /** Unique trajectory identifier */
- id: string;
- /** Associated task identifier */
- taskId: string;
- /** Trajectory steps */
- steps: SONATrajectoryStep[];
- /** Start timestamp */
- startTime: number;
- /** End timestamp (if completed) */
- endTime?: number;
- /** Final verdict */
- verdict?: 'positive' | 'negative' | 'neutral';
- /** Total reward accumulated */
- totalReward: number;
- /** Metadata */
- metadata: Record<string, unknown>;
-}
-
-export interface SONATrajectoryStep {
- /** Step identifier */
- stepId: string;
- /** Action taken */
- action: string;
- /** Observation/result */
- observation: string;
- /** Step reward */
- reward: number;
- /** Step timestamp */
- timestamp: number;
- /** Embedding vector (optional) */
- embedding?: number[];
-}
-
-export interface SONAPattern {
- /** Pattern identifier */
- id: string;
- /** Pattern content/description */
- pattern: string;
- /** Solution or approach */
- solution: string;
- /** Category for classification */
- category: string;
- /** Confidence score (0.0 - 1.0) */
- confidence: number;
- /** Usage count */
- usageCount: number;
- /** Creation timestamp */
- createdAt: number;
- /** Last used timestamp */
- lastUsedAt: number;
- /** Embedding vector */
- embedding?: number[];
- /** Associated metadata */
- metadata: Record<string, unknown>;
-}
-
-export interface SONALearningStats {
- /** Total patterns stored */
- totalPatterns: number;
- /** Active trajectories */
- activeTrajectories: number;
- /** Completed trajectories */
- completedTrajectories: number;
- /** Average pattern confidence */
- averageConfidence: number;
- /** Learning cycles completed */
- learningCycles: number;
- /** Last consolidation timestamp */
- lastConsolidation: number;
- /** Memory usage in bytes */
- memoryUsage: number;
- /** Current learning mode */
- currentMode: SONALearningMode;
-}
-
-// ===== Flash Attention Types =====
-
-/**
- * Attention mechanism types supported by agentic-flow.
- * Flash Attention provides 2.49x-7.47x speedup with 50-75% memory reduction.
- */
-export type AttentionMechanism =
- | 'flash' // Flash Attention - fastest, 75% memory reduction
- | 'multi-head' // Standard multi-head attention
- | 'linear' // Linear attention for long sequences
- | 'hyperbolic' // Hyperbolic attention for hierarchical data
- | 'moe' // Mixture of Experts attention
- | 'local' // Local/windowed attention
- | 'global' // Global attention
- | 'sparse'; // Sparse attention patterns
-
-export interface AttentionConfiguration {
- /** Primary attention mechanism */
- mechanism: AttentionMechanism;
- /** Number of attention heads */
- numHeads: number;
- /** Dimension per head */
- headDim: number;
- /** Dropout rate (0.0 - 1.0) */
- dropoutRate: number;
- /** Enable causal masking */
- causalMask: boolean;
- /** Use rotary position embeddings */
- useRoPE: boolean;
- /** Flash attention optimization level (0-3) */
- flashOptLevel: number;
- /** Memory optimization mode */
- memoryOptimization: 'none' | 'moderate' | 'aggressive';
-}
-
-export interface AttentionResult {
- /** Output tensor/array */
- output: number[] | Float32Array;
- /** Attention weights (optional, for debugging) */
- attentionWeights?: number[][];
- /** Execution latency in milliseconds */
- latencyMs: number;
- /** Memory used in bytes */
- memoryBytes: number;
- /** Mechanism used */
- mechanism: AttentionMechanism;
- /** Cache hit indicator */
- cacheHit: boolean;
-}
-
-export interface AttentionMetrics {
- /** Average latency in milliseconds */
- avgLatencyMs: number;
- /** Throughput (tokens per second) */
- throughputTps: number;
- /** Memory efficiency (0.0 - 1.0) */
- memoryEfficiency: number;
- /** Cache hit rate (0.0 - 1.0) */
- cacheHitRate: number;
- /** Total operations performed */
- totalOperations: number;
- /** Speedup vs baseline */
- speedupFactor: number;
-}
-
-// ===== AgentDB Types =====
-
-/**
- * AgentDB provides 150x-12,500x faster search via HNSW indexing.
- */
-export interface AgentDBConfiguration {
- /** Vector dimension */
- dimension: number;
- /** Index type */
- indexType: 'hnsw' | 'flat' | 'ivf' | 'pq';
- /** HNSW M parameter (connections per layer) */
- hnswM: number;
- /** HNSW ef_construction parameter */
- hnswEfConstruction: number;
- /** HNSW ef_search parameter */
- hnswEfSearch: number;
- /** Distance metric */
- metric: 'cosine' | 'euclidean' | 'dot_product';
- /** Enable caching */
- enableCache: boolean;
- /** Cache size in MB */
- cacheSizeMb: number;
- /** Database path (for persistent storage) */
- dbPath?: string;
- /** Enable WAL mode for SQLite */
- enableWAL: boolean;
-}
-
-export interface AgentDBVector {
- /** Vector identifier */
- id: string;
- /** Vector data */
- vector: number[] | Float32Array;
- /** Associated metadata */
- metadata: Record<string, unknown>;
- /** Namespace for isolation */
- namespace: string;
- /** Creation timestamp */
- createdAt: number;
- /** Last updated timestamp */
- updatedAt: number;
-}
-
-export interface AgentDBSearchResult {
- /** Vector identifier */
- id: string;
- /** Similarity score (0.0 - 1.0 for cosine) */
- score: number;
- /** Distance (for euclidean metric) */
- distance?: number;
- /** Associated metadata */
- metadata: Record<string, unknown>;
- /** Original vector (optional) */
- vector?: number[];
-}
-
-export interface AgentDBStats {
- /** Total vectors stored */
- totalVectors: number;
- /** Index size in bytes */
- indexSizeBytes: number;
- /** Average search latency in milliseconds */
- avgSearchLatencyMs: number;
- /** Average insert latency in milliseconds */
- avgInsertLatencyMs: number;
- /** Cache hit rate (0.0 - 1.0) */
- cacheHitRate: number;
- /** Memory usage in bytes */
- memoryUsage: number;
- /** Namespaces count */
- namespaceCount: number;
-}
-
-// ===== Integration Bridge Types =====
-
-export interface IntegrationConfig {
- /** SONA configuration */
- sona: Partial<SONAConfiguration>;
- /** Attention configuration */
- attention: Partial<AttentionConfiguration>;
- /** AgentDB configuration */
- agentdb: Partial<AgentDBConfiguration>;
- /** Feature flags */
- features: FeatureFlags;
- /** Runtime preference (auto-detection order) */
- runtimePreference: ('napi' | 'wasm' | 'js')[];
- /** Lazy loading for performance */
- lazyLoad: boolean;
- /** Debug mode */
- debug: boolean;
-}
-
-export interface FeatureFlags {
- /** Enable SONA learning */
- enableSONA: boolean;
- /** Enable Flash Attention */
- enableFlashAttention: boolean;
- /** Enable AgentDB vector search */
- enableAgentDB: boolean;
- /** Enable trajectory tracking */
- enableTrajectoryTracking: boolean;
- /** Enable GNN query refinement (+12.4% recall) */
- enableGNN: boolean;
- /** Enable intelligence bridge tools */
- enableIntelligenceBridge: boolean;
- /** Enable QUIC transport */
- enableQUICTransport: boolean;
- /** Enable nightly learning */
- enableNightlyLearning: boolean;
- /** Enable auto-consolidation */
- enableAutoConsolidation: boolean;
-}
-
-export interface RuntimeInfo {
- /** Current runtime (napi, wasm, or js) */
- runtime: 'napi' | 'wasm' | 'js';
- /** Platform */
- platform: 'linux' | 'darwin' | 'win32' | 'browser';
- /** Architecture */
- arch: 'x64' | 'arm64' | 'ia32';
- /** Node.js version */
- nodeVersion: string;
- /** WASM support */
- wasmSupport: boolean;
- /** NAPI support */
- napiSupport: boolean;
- /** Performance tier */
- performanceTier: 'optimal' | 'good' | 'fallback';
-}
-
-export interface IntegrationStatus {
- /** Initialization complete */
- initialized: boolean;
- /** Connected components */
- connectedComponents: string[];
- /** Runtime information */
- runtime: RuntimeInfo;
- /** Feature availability */
- features: Record<string, boolean>;
- /** Component health */
- health: Record<string, ComponentHealth>;
- /** Last health check timestamp */
- lastHealthCheck: number;
-}
-
-export interface ComponentHealth {
- /** Component name */
- name: string;
- /** Health status */
- status: 'healthy' | 'degraded' | 'unhealthy';
- /** Last error (if any) */
- lastError?: string;
- /** Response latency in milliseconds */
- latencyMs: number;
- /** Uptime percentage (0.0 - 1.0) */
- uptime: number;
-}
-
-// ===== SDK Bridge Types =====
-
-export interface SDKVersion {
- /** Major version */
- major: number;
- /** Minor version */
- minor: number;
- /** Patch version */
- patch: number;
- /** Pre-release tag */
- prerelease?: string;
- /** Full version string */
- full: string;
-}
-
-export interface SDKCompatibility {
- /** Minimum supported version */
- minVersion: SDKVersion;
- /** Maximum supported version */
- maxVersion: SDKVersion;
- /** Current version */
- currentVersion: SDKVersion;
- /** Compatibility status */
- compatible: boolean;
- /** Required features */
- requiredFeatures: string[];
- /** Optional features */
- optionalFeatures: string[];
-}
-
-export interface SDKBridgeConfig {
- /** Target SDK version */
- targetVersion: string;
- /** Enable version negotiation */
- enableVersionNegotiation: boolean;
- /** Fallback behavior */
- fallbackBehavior: 'error' | 'warn' | 'silent';
- /** API compatibility layer */
- enableCompatibilityLayer: boolean;
- /** Deprecated API support */
- supportDeprecatedAPIs: boolean;
-}
-
-// ===== Event Types =====
-
-export interface IntegrationEvent {
- /** Event type */
- type: IntegrationEventType;
- /** Event timestamp */
- timestamp: number;
- /** Event data */
- data: Record<string, unknown>;
- /** Source component */
- source: string;
- /** Correlation ID */
- correlationId: string;
-}
-
-export type IntegrationEventType =
- | 'initialized'
- | 'component-connected'
- | 'component-disconnected'
- | 'pattern-stored'
- | 'pattern-retrieved'
- | 'trajectory-started'
- | 'trajectory-completed'
- | 'learning-cycle-completed'
- | 'attention-computed'
- | 'search-performed'
- | 'error'
- | 'warning'
- | 'health-check';
-
-// ===== Error Types =====
-
-export class IntegrationError extends Error {
- constructor(
- message: string,
- public readonly code: IntegrationErrorCode,
- public readonly component: string,
- public readonly cause?: Error
- ) {
- super(message);
- this.name = 'IntegrationError';
- }
-}
-
-export type IntegrationErrorCode =
- | 'INITIALIZATION_FAILED'
- | 'COMPONENT_UNAVAILABLE'
- | 'VERSION_MISMATCH'
- | 'FEATURE_DISABLED'
- | 'RUNTIME_ERROR'
- | 'TIMEOUT'
- | 'CONFIGURATION_INVALID'
- | 'MEMORY_EXHAUSTED'
- | 'SEARCH_FAILED'
- | 'LEARNING_FAILED';
-
-// ===== Default Configurations =====
-
-export const DEFAULT_SONA_CONFIG: SONAConfiguration = {
- mode: 'balanced',
- learningRate: 0.001,
- similarityThreshold: 0.7,
- maxPatterns: 10000,
- enableTrajectoryTracking: true,
- consolidationInterval: 3600000, // 1 hour
- autoModeSelection: true,
-};
-
-export const DEFAULT_ATTENTION_CONFIG: AttentionConfiguration = {
- mechanism: 'flash',
- numHeads: 8,
- headDim: 64,
- dropoutRate: 0.0,
- causalMask: false,
- useRoPE: true,
- flashOptLevel: 2,
- memoryOptimization: 'moderate',
-};
-
-export const DEFAULT_AGENTDB_CONFIG: AgentDBConfiguration = {
- dimension: 1536, // OpenAI embedding dimension
- indexType: 'hnsw',
- hnswM: 16,
- hnswEfConstruction: 200,
- hnswEfSearch: 50,
- metric: 'cosine',
- enableCache: true,
- cacheSizeMb: 256,
- enableWAL: true,
-};
-
-export const DEFAULT_FEATURE_FLAGS: FeatureFlags = {
- enableSONA: true,
- enableFlashAttention: true,
- enableAgentDB: true,
- enableTrajectoryTracking: true,
- enableGNN: true,
- enableIntelligenceBridge: true,
- enableQUICTransport: false, // Disabled by default (requires additional setup)
- enableNightlyLearning: false, // Disabled by default (resource intensive)
- enableAutoConsolidation: true,
-};
-
-export const DEFAULT_INTEGRATION_CONFIG: IntegrationConfig = {
- sona: DEFAULT_SONA_CONFIG,
- attention: DEFAULT_ATTENTION_CONFIG,
- agentdb: DEFAULT_AGENTDB_CONFIG,
- features: DEFAULT_FEATURE_FLAGS,
- runtimePreference: ['napi', 'wasm', 'js'],
- lazyLoad: true,
- debug: false,
-};
diff --git a/v3/neural/algorithms/a2c.ts b/v3/neural/algorithms/a2c.ts
deleted file mode 100644
index 79c93047a7..0000000000
--- a/v3/neural/algorithms/a2c.ts
+++ /dev/null
@@ -1,478 +0,0 @@
-/**
- * Advantage Actor-Critic (A2C)
- *
- * Implements synchronous A2C algorithm with:
- * - Shared actor-critic network
- * - N-step returns
- * - Entropy regularization
- * - Advantage normalization
- *
- * Performance Target: <10ms per update step
- */
-
-import type {
- RLConfig,
- Trajectory,
- TrajectoryStep,
-} from '../types.js';
-
-/**
- * A2C configuration
- */
-export interface A2CConfig extends RLConfig {
- algorithm: 'a2c';
- nSteps: number;
- useGAE: boolean;
- gaeLambda: number;
-}
-
-/**
- * Default A2C configuration
- */
-export const DEFAULT_A2C_CONFIG: A2CConfig = {
- algorithm: 'a2c',
- learningRate: 0.0007,
- gamma: 0.99,
- entropyCoef: 0.01,
- valueLossCoef: 0.5,
- maxGradNorm: 0.5,
- epochs: 1,
- miniBatchSize: 32,
- nSteps: 5,
- useGAE: true,
- gaeLambda: 0.95,
-};
-
-/**
- * A2C experience entry
- */
-interface A2CExperience {
- state: Float32Array;
- action: number;
- reward: number;
- value: number;
- logProb: number;
- entropy: number;
-}
-
-/**
- * A2C Algorithm Implementation
- */
-export class A2CAlgorithm {
- private config: A2CConfig;
-
- // Shared network weights
- private sharedWeights: Float32Array;
- private policyHead: Float32Array;
- private valueHead: Float32Array;
-
- // Optimizer state
- private sharedMomentum: Float32Array;
- private policyMomentum: Float32Array;
- private valueMomentum: Float32Array;
-
- // Experience buffer for n-step
- private buffer: A2CExperience[] = [];
-
- // Dimensions
- private inputDim = 768;
- private hiddenDim = 64;
- private numActions = 4;
-
- // Statistics
- private updateCount = 0;
- private avgPolicyLoss = 0;
- private avgValueLoss = 0;
- private avgEntropy = 0;
-
- constructor(config: Partial<A2CConfig> = {}) {
- this.config = { ...DEFAULT_A2C_CONFIG, ...config };
-
- // Initialize network
- const scale = Math.sqrt(2 / this.inputDim);
- this.sharedWeights = new Float32Array(this.inputDim * this.hiddenDim);
- this.policyHead = new Float32Array(this.hiddenDim * this.numActions);
- this.valueHead = new Float32Array(this.hiddenDim);
-
- for (let i = 0; i < this.sharedWeights.length; i++) {
- this.sharedWeights[i] = (Math.random() - 0.5) * scale;
- }
- for (let i = 0; i < this.policyHead.length; i++) {
- this.policyHead[i] = (Math.random() - 0.5) * 0.1;
- }
- for (let i = 0; i < this.valueHead.length; i++) {
- this.valueHead[i] = (Math.random() - 0.5) * 0.1;
- }
-
- // Initialize momentum
- this.sharedMomentum = new Float32Array(this.sharedWeights.length);
- this.policyMomentum = new Float32Array(this.policyHead.length);
- this.valueMomentum = new Float32Array(this.valueHead.length);
- }
-
- /**
- * Add experience from trajectory
- */
- addExperience(trajectory: Trajectory): void {
- for (const step of trajectory.steps) {
- const { probs, value, entropy } = this.evaluate(step.stateAfter);
- const action = this.hashAction(step.action);
-
- this.buffer.push({
- state: step.stateAfter,
- action,
- reward: step.reward,
- value,
- logProb: Math.log(probs[action] + 1e-8),
- entropy,
- });
- }
- }
-
- /**
- * Perform A2C update
- * Target: <10ms
- */
- update(): { policyLoss: number; valueLoss: number; entropy: number } {
- const startTime = performance.now();
-
- if (this.buffer.length < this.config.nSteps) {
- return { policyLoss: 0, valueLoss: 0, entropy: 0 };
- }
-
- // Compute returns and advantages
- const returns = this.computeReturns();
- const advantages = this.computeAdvantages(returns);
-
- // Initialize gradients
- const sharedGrad = new Float32Array(this.sharedWeights.length);
- const policyGrad = new Float32Array(this.policyHead.length);
- const valueGrad = new Float32Array(this.valueHead.length);
-
- let totalPolicyLoss = 0;
- let totalValueLoss = 0;
- let totalEntropy = 0;
-
- // Process all experiences
- for (let i = 0; i < this.buffer.length; i++) {
- const exp = this.buffer[i];
- const advantage = advantages[i];
- const return_ = returns[i];
-
- // Get current policy and value
- const { probs, value, hidden } = this.forwardWithHidden(exp.state);
- const logProb = Math.log(probs[exp.action] + 1e-8);
-
- // Policy loss
- const policyLoss = -logProb * advantage;
- totalPolicyLoss += policyLoss;
-
- // Value loss
- const valueLoss = (value - return_) ** 2;
- totalValueLoss += valueLoss;
-
- // Entropy
- let entropy = 0;
- for (const p of probs) {
- if (p > 0) entropy -= p * Math.log(p);
- }
- totalEntropy += entropy;
-
- // Accumulate gradients
- this.accumulateGradients(
- sharedGrad, policyGrad, valueGrad,
- exp.state, hidden, exp.action,
- advantage, value - return_
- );
- }
-
- // Add entropy bonus to policy gradient
- for (let i = 0; i < policyGrad.length; i++) {
- policyGrad[i] -= this.config.entropyCoef * totalEntropy / this.buffer.length;
- }
-
- // Apply gradients
- this.applyGradients(sharedGrad, policyGrad, valueGrad, this.buffer.length);
-
- // Clear buffer
- this.buffer = [];
- this.updateCount++;
-
- this.avgPolicyLoss = totalPolicyLoss / this.buffer.length || 0;
- this.avgValueLoss = totalValueLoss / this.buffer.length || 0;
- this.avgEntropy = totalEntropy / this.buffer.length || 0;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 10) {
- console.warn(`A2C update exceeded target: ${elapsed.toFixed(2)}ms > 10ms`);
- }
-
- return {
- policyLoss: this.avgPolicyLoss,
- valueLoss: this.avgValueLoss,
- entropy: this.avgEntropy,
- };
- }
-
- /**
- * Get action from policy
- */
- getAction(state: Float32Array): { action: number; value: number } {
- const { probs, value } = this.evaluate(state);
- const action = this.sampleAction(probs);
- return { action, value };
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- bufferSize: this.buffer.length,
- avgPolicyLoss: this.avgPolicyLoss,
- avgValueLoss: this.avgValueLoss,
- avgEntropy: this.avgEntropy,
- };
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private evaluate(state: Float32Array): { probs: Float32Array; value: number; entropy: number } {
- const { probs, value } = this.forward(state);
-
- let entropy = 0;
- for (const p of probs) {
- if (p > 0) entropy -= p * Math.log(p);
- }
-
- return { probs, value, entropy };
- }
-
- private forward(state: Float32Array): { probs: Float32Array; value: number } {
- // Shared hidden layer
- const hidden = new Float32Array(this.hiddenDim);
- for (let h = 0; h < this.hiddenDim; h++) {
- let sum = 0;
- for (let i = 0; i < Math.min(state.length, this.inputDim); i++) {
- sum += state[i] * this.sharedWeights[i * this.hiddenDim + h];
- }
- hidden[h] = Math.max(0, sum); // ReLU
- }
-
- // Policy head
- const logits = new Float32Array(this.numActions);
- for (let a = 0; a < this.numActions; a++) {
- let sum = 0;
- for (let h = 0; h < this.hiddenDim; h++) {
- sum += hidden[h] * this.policyHead[h * this.numActions + a];
- }
- logits[a] = sum;
- }
- const probs = this.softmax(logits);
-
- // Value head
- let value = 0;
- for (let h = 0; h < this.hiddenDim; h++) {
- value += hidden[h] * this.valueHead[h];
- }
-
- return { probs, value };
- }
-
- private forwardWithHidden(state: Float32Array): { probs: Float32Array; value: number; hidden: Float32Array } {
- const hidden = new Float32Array(this.hiddenDim);
- for (let h = 0; h < this.hiddenDim; h++) {
- let sum = 0;
- for (let i = 0; i < Math.min(state.length, this.inputDim); i++) {
- sum += state[i] * this.sharedWeights[i * this.hiddenDim + h];
- }
- hidden[h] = Math.max(0, sum);
- }
-
- const logits = new Float32Array(this.numActions);
- for (let a = 0; a < this.numActions; a++) {
- let sum = 0;
- for (let h = 0; h < this.hiddenDim; h++) {
- sum += hidden[h] * this.policyHead[h * this.numActions + a];
- }
- logits[a] = sum;
- }
- const probs = this.softmax(logits);
-
- let value = 0;
- for (let h = 0; h < this.hiddenDim; h++) {
- value += hidden[h] * this.valueHead[h];
- }
-
- return { probs, value, hidden };
- }
-
- private computeReturns(): number[] {
- const returns = new Array(this.buffer.length).fill(0);
- let cumReturn = 0;
-
- // Bootstrap from last value if not terminal
- if (this.buffer.length > 0) {
- cumReturn = this.buffer[this.buffer.length - 1].value;
- }
-
- for (let t = this.buffer.length - 1; t >= 0; t--) {
- cumReturn = this.buffer[t].reward + this.config.gamma * cumReturn;
- returns[t] = cumReturn;
- }
-
- return returns;
- }
-
- private computeAdvantages(returns: number[]): number[] {
- if (this.config.useGAE) {
- return this.computeGAE();
- }
-
- // Simple advantage: return - value
- const advantages = new Array(this.buffer.length).fill(0);
- for (let i = 0; i < this.buffer.length; i++) {
- advantages[i] = returns[i] - this.buffer[i].value;
- }
-
- // Normalize
- const mean = advantages.reduce((a, b) => a + b, 0) / advantages.length;
- const std = Math.sqrt(
- advantages.reduce((a, b) => a + (b - mean) ** 2, 0) / advantages.length
- ) + 1e-8;
-
- return advantages.map(a => (a - mean) / std);
- }
-
- private computeGAE(): number[] {
- const advantages = new Array(this.buffer.length).fill(0);
- let lastGae = 0;
-
- for (let t = this.buffer.length - 1; t >= 0; t--) {
- const nextValue = t < this.buffer.length - 1
- ? this.buffer[t + 1].value
- : 0;
- const delta = this.buffer[t].reward + this.config.gamma * nextValue - this.buffer[t].value;
- lastGae = delta + this.config.gamma * this.config.gaeLambda * lastGae;
- advantages[t] = lastGae;
- }
-
- // Normalize
- const mean = advantages.reduce((a, b) => a + b, 0) / advantages.length;
- const std = Math.sqrt(
- advantages.reduce((a, b) => a + (b - mean) ** 2, 0) / advantages.length
- ) + 1e-8;
-
- return advantages.map(a => (a - mean) / std);
- }
-
- private accumulateGradients(
- sharedGrad: Float32Array,
- policyGrad: Float32Array,
- valueGrad: Float32Array,
- state: Float32Array,
- hidden: Float32Array,
- action: number,
- advantage: number,
- valueError: number
- ): void {
- // Policy gradient
- for (let h = 0; h < this.hiddenDim; h++) {
- policyGrad[h * this.numActions + action] += hidden[h] * advantage;
- }
-
- // Value gradient
- for (let h = 0; h < this.hiddenDim; h++) {
- valueGrad[h] += hidden[h] * valueError * this.config.valueLossCoef;
- }
-
- // Shared layer gradient (backprop through both heads)
- for (let h = 0; h < this.hiddenDim; h++) {
- if (hidden[h] > 0) { // ReLU gradient
- const policySignal = advantage * this.policyHead[h * this.numActions + action];
- const valueSignal = valueError * this.valueHead[h] * this.config.valueLossCoef;
- const totalSignal = policySignal + valueSignal;
-
- for (let i = 0; i < Math.min(state.length, this.inputDim); i++) {
- sharedGrad[i * this.hiddenDim + h] += state[i] * totalSignal;
- }
- }
- }
- }
-
- private applyGradients(
- sharedGrad: Float32Array,
- policyGrad: Float32Array,
- valueGrad: Float32Array,
- batchSize: number
- ): void {
- const lr = this.config.learningRate / batchSize;
- const beta = 0.9;
-
- // Apply to shared weights
- for (let i = 0; i < this.sharedWeights.length; i++) {
- const grad = Math.max(Math.min(sharedGrad[i], this.config.maxGradNorm), -this.config.maxGradNorm);
- this.sharedMomentum[i] = beta * this.sharedMomentum[i] + (1 - beta) * grad;
- this.sharedWeights[i] -= lr * this.sharedMomentum[i];
- }
-
- // Apply to policy head
- for (let i = 0; i < this.policyHead.length; i++) {
- const grad = Math.max(Math.min(policyGrad[i], this.config.maxGradNorm), -this.config.maxGradNorm);
- this.policyMomentum[i] = beta * this.policyMomentum[i] + (1 - beta) * grad;
- this.policyHead[i] -= lr * this.policyMomentum[i];
- }
-
- // Apply to value head
- for (let i = 0; i < this.valueHead.length; i++) {
- const grad = Math.max(Math.min(valueGrad[i], this.config.maxGradNorm), -this.config.maxGradNorm);
- this.valueMomentum[i] = beta * this.valueMomentum[i] + (1 - beta) * grad;
- this.valueHead[i] -= lr * this.valueMomentum[i];
- }
- }
-
- private softmax(logits: Float32Array): Float32Array {
- const max = Math.max(...logits);
- const exps = new Float32Array(logits.length);
- let sum = 0;
-
- for (let i = 0; i < logits.length; i++) {
- exps[i] = Math.exp(logits[i] - max);
- sum += exps[i];
- }
-
- for (let i = 0; i < exps.length; i++) {
- exps[i] /= sum;
- }
-
- return exps;
- }
-
- private sampleAction(probs: Float32Array): number {
- const r = Math.random();
- let cumSum = 0;
- for (let i = 0; i < probs.length; i++) {
- cumSum += probs[i];
- if (r < cumSum) return i;
- }
- return probs.length - 1;
- }
-
- private hashAction(action: string): number {
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % this.numActions;
- }
- return hash;
- }
-}
-
-/**
- * Factory function
- */
-export function createA2C(config?: Partial<A2CConfig>): A2CAlgorithm {
- return new A2CAlgorithm(config);
-}
diff --git a/v3/neural/algorithms/curiosity.ts b/v3/neural/algorithms/curiosity.ts
deleted file mode 100644
index be9b1d2ab8..0000000000
--- a/v3/neural/algorithms/curiosity.ts
+++ /dev/null
@@ -1,509 +0,0 @@
-/**
- * Curiosity-Driven Exploration
- *
- * Implements intrinsic motivation for exploration:
- * - Intrinsic Curiosity Module (ICM)
- * - Random Network Distillation (RND)
- * - Forward and inverse dynamics models
- * - Exploration bonus generation
- *
- * Performance Target: <5ms per forward pass
- */
-
-import type { CuriosityConfig, Trajectory, TrajectoryStep } from '../types.js';
-
-/**
- * Default Curiosity configuration
- */
-export const DEFAULT_CURIOSITY_CONFIG: CuriosityConfig = {
- algorithm: 'curiosity',
- learningRate: 0.0001,
- gamma: 0.99,
- entropyCoef: 0.01,
- valueLossCoef: 0.5,
- maxGradNorm: 0.5,
- epochs: 1,
- miniBatchSize: 32,
- intrinsicCoef: 0.1,
- forwardLR: 0.001,
- inverseLR: 0.001,
- featureDim: 64,
- useRND: false,
-};
-
-/**
- * Curiosity-Driven Exploration Module
- */
-export class CuriosityModule {
- private config: CuriosityConfig;
-
- // Feature encoder
- private featureEncoder: Float32Array;
-
- // Forward dynamics model: predicts next feature from current feature + action
- private forwardModel: Float32Array;
-
- // Inverse dynamics model: predicts action from current and next features
- private inverseModel: Float32Array;
-
- // RND target and predictor networks
- private rndTarget: Float32Array;
- private rndPredictor: Float32Array;
-
- // Optimizer state
- private forwardMomentum: Float32Array;
- private inverseMomentum: Float32Array;
- private rndMomentum: Float32Array;
-
- // Dimensions
- private stateDim = 768;
- private numActions = 4;
-
- // Running statistics for normalization
- private intrinsicMean = 0;
- private intrinsicVar = 1;
- private updateCount = 0;
-
- // Statistics
- private avgForwardLoss = 0;
- private avgInverseLoss = 0;
- private avgIntrinsicReward = 0;
-
- constructor(config: Partial<CuriosityConfig> = {}) {
- this.config = { ...DEFAULT_CURIOSITY_CONFIG, ...config };
-
- const featureDim = this.config.featureDim;
-
- // Initialize feature encoder: state_dim -> feature_dim
- this.featureEncoder = this.initWeight(this.stateDim, featureDim);
-
- // Forward model: (feature_dim + num_actions) -> feature_dim
- this.forwardModel = this.initWeight(featureDim + this.numActions, featureDim);
-
- // Inverse model: (2 * feature_dim) -> num_actions
- this.inverseModel = this.initWeight(2 * featureDim, this.numActions);
-
- // RND networks
- this.rndTarget = this.initWeight(this.stateDim, featureDim);
- this.rndPredictor = this.initWeight(this.stateDim, featureDim);
-
- // Momentum buffers
- this.forwardMomentum = new Float32Array(this.forwardModel.length);
- this.inverseMomentum = new Float32Array(this.inverseModel.length);
- this.rndMomentum = new Float32Array(this.rndPredictor.length);
- }
-
- /**
- * Compute intrinsic reward for a transition
- */
- computeIntrinsicReward(
- state: Float32Array,
- action: string,
- nextState: Float32Array
- ): number {
- if (this.config.useRND) {
- return this.computeRNDReward(nextState);
- } else {
- return this.computeICMReward(state, action, nextState);
- }
- }
-
- /**
- * Compute ICM-based intrinsic reward (prediction error)
- */
- computeICMReward(
- state: Float32Array,
- action: string,
- nextState: Float32Array
- ): number {
- const startTime = performance.now();
-
- // Encode states to features
- const stateFeature = this.encodeState(state);
- const nextStateFeature = this.encodeState(nextState);
-
- // Predict next state feature
- const actionIdx = this.hashAction(action);
- const predictedFeature = this.forwardPredict(stateFeature, actionIdx);
-
- // Compute prediction error as intrinsic reward
- let error = 0;
- for (let i = 0; i < this.config.featureDim; i++) {
- error += (predictedFeature[i] - nextStateFeature[i]) ** 2;
- }
-
- // Normalize intrinsic reward
- const intrinsic = this.normalizeIntrinsic(error);
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 5) {
- console.warn(`ICM reward exceeded target: ${elapsed.toFixed(2)}ms > 5ms`);
- }
-
- return intrinsic * this.config.intrinsicCoef;
- }
-
- /**
- * Compute RND-based intrinsic reward
- */
- computeRNDReward(state: Float32Array): number {
- const startTime = performance.now();
-
- // Target network output (fixed random features)
- const targetOutput = this.rndForward(state, this.rndTarget);
-
- // Predictor network output (trained to match target)
- const predictorOutput = this.rndForward(state, this.rndPredictor);
-
- // Compute prediction error
- let error = 0;
- for (let i = 0; i < this.config.featureDim; i++) {
- error += (predictorOutput[i] - targetOutput[i]) ** 2;
- }
-
- // Normalize
- const intrinsic = this.normalizeIntrinsic(error);
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 5) {
- console.warn(`RND reward exceeded target: ${elapsed.toFixed(2)}ms > 5ms`);
- }
-
- return intrinsic * this.config.intrinsicCoef;
- }
-
- /**
- * Update curiosity models from trajectory
- */
- update(trajectory: Trajectory): { forwardLoss: number; inverseLoss: number } {
- const startTime = performance.now();
-
- if (trajectory.steps.length < 2) {
- return { forwardLoss: 0, inverseLoss: 0 };
- }
-
- let totalForwardLoss = 0;
- let totalInverseLoss = 0;
- let count = 0;
-
- for (let i = 0; i < trajectory.steps.length - 1; i++) {
- const step = trajectory.steps[i];
- const nextStep = trajectory.steps[i + 1];
-
- const stateFeature = this.encodeState(step.stateAfter);
- const nextStateFeature = this.encodeState(nextStep.stateAfter);
- const actionIdx = this.hashAction(step.action);
-
- // Update forward model
- const forwardLoss = this.updateForwardModel(stateFeature, actionIdx, nextStateFeature);
- totalForwardLoss += forwardLoss;
-
- // Update inverse model
- const inverseLoss = this.updateInverseModel(stateFeature, nextStateFeature, actionIdx);
- totalInverseLoss += inverseLoss;
-
- // Update RND predictor if using RND
- if (this.config.useRND) {
- this.updateRNDPredictor(nextStep.stateAfter);
- }
-
- count++;
- }
-
- this.updateCount++;
- this.avgForwardLoss = count > 0 ? totalForwardLoss / count : 0;
- this.avgInverseLoss = count > 0 ? totalInverseLoss / count : 0;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 10) {
- console.warn(`Curiosity update exceeded target: ${elapsed.toFixed(2)}ms > 10ms`);
- }
-
- return {
- forwardLoss: this.avgForwardLoss,
- inverseLoss: this.avgInverseLoss,
- };
- }
-
- /**
- * Add intrinsic rewards to trajectory
- */
- augmentTrajectory(trajectory: Trajectory): Trajectory {
- const augmented = { ...trajectory, steps: [...trajectory.steps] };
-
- for (let i = 0; i < augmented.steps.length - 1; i++) {
- const step = augmented.steps[i];
- const nextStep = augmented.steps[i + 1];
-
- const intrinsic = this.computeIntrinsicReward(
- step.stateAfter,
- step.action,
- nextStep.stateAfter
- );
-
- // Augment reward
- augmented.steps[i] = {
- ...step,
- reward: step.reward + intrinsic,
- };
- }
-
- return augmented;
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- avgForwardLoss: this.avgForwardLoss,
- avgInverseLoss: this.avgInverseLoss,
- avgIntrinsicReward: this.avgIntrinsicReward,
- intrinsicMean: this.intrinsicMean,
- intrinsicStd: Math.sqrt(this.intrinsicVar),
- };
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private initWeight(inputDim: number, outputDim: number): Float32Array {
- const weight = new Float32Array(inputDim * outputDim);
- const scale = Math.sqrt(2 / inputDim);
- for (let i = 0; i < weight.length; i++) {
- weight[i] = (Math.random() - 0.5) * scale;
- }
- return weight;
- }
-
- private encodeState(state: Float32Array): Float32Array {
- const featureDim = this.config.featureDim;
- const feature = new Float32Array(featureDim);
-
- for (let f = 0; f < featureDim; f++) {
- let sum = 0;
- for (let s = 0; s < Math.min(state.length, this.stateDim); s++) {
- sum += state[s] * this.featureEncoder[s * featureDim + f];
- }
- feature[f] = Math.max(0, sum); // ReLU
- }
-
- return feature;
- }
-
- private forwardPredict(stateFeature: Float32Array, action: number): Float32Array {
- const featureDim = this.config.featureDim;
- const inputDim = featureDim + this.numActions;
- const predicted = new Float32Array(featureDim);
-
- // Concatenate feature and one-hot action
- const input = new Float32Array(inputDim);
- input.set(stateFeature);
- input[featureDim + action] = 1;
-
- // Forward pass
- for (let f = 0; f < featureDim; f++) {
- let sum = 0;
- for (let i = 0; i < inputDim; i++) {
- sum += input[i] * this.forwardModel[i * featureDim + f];
- }
- predicted[f] = sum;
- }
-
- return predicted;
- }
-
- private inversePredict(
- stateFeature: Float32Array,
- nextStateFeature: Float32Array
- ): Float32Array {
- const featureDim = this.config.featureDim;
- const logits = new Float32Array(this.numActions);
-
- // Concatenate features
- const input = new Float32Array(2 * featureDim);
- input.set(stateFeature);
- input.set(nextStateFeature, featureDim);
-
- // Forward pass
- for (let a = 0; a < this.numActions; a++) {
- let sum = 0;
- for (let i = 0; i < 2 * featureDim; i++) {
- sum += input[i] * this.inverseModel[i * this.numActions + a];
- }
- logits[a] = sum;
- }
-
- return this.softmax(logits);
- }
-
- private rndForward(state: Float32Array, weights: Float32Array): Float32Array {
- const featureDim = this.config.featureDim;
- const output = new Float32Array(featureDim);
-
- for (let f = 0; f < featureDim; f++) {
- let sum = 0;
- for (let s = 0; s < Math.min(state.length, this.stateDim); s++) {
- sum += state[s] * weights[s * featureDim + f];
- }
- output[f] = Math.max(0, sum); // ReLU
- }
-
- return output;
- }
-
- private updateForwardModel(
- stateFeature: Float32Array,
- action: number,
- targetFeature: Float32Array
- ): number {
- const featureDim = this.config.featureDim;
- const inputDim = featureDim + this.numActions;
- const lr = this.config.forwardLR;
- const beta = 0.9;
-
- // Forward pass
- const predicted = this.forwardPredict(stateFeature, action);
-
- // Compute loss and gradient
- let loss = 0;
- const grad = new Float32Array(predicted.length);
-
- for (let f = 0; f < featureDim; f++) {
- const diff = predicted[f] - targetFeature[f];
- loss += diff * diff;
- grad[f] = 2 * diff;
- }
-
- // Backprop to weights
- const input = new Float32Array(inputDim);
- input.set(stateFeature);
- input[featureDim + action] = 1;
-
- for (let i = 0; i < inputDim; i++) {
- for (let f = 0; f < featureDim; f++) {
- const weightGrad = input[i] * grad[f];
- const idx = i * featureDim + f;
- this.forwardMomentum[idx] = beta * this.forwardMomentum[idx] + (1 - beta) * weightGrad;
- this.forwardModel[idx] -= lr * this.forwardMomentum[idx];
- }
- }
-
- return loss;
- }
-
- private updateInverseModel(
- stateFeature: Float32Array,
- nextStateFeature: Float32Array,
- targetAction: number
- ): number {
- const featureDim = this.config.featureDim;
- const lr = this.config.inverseLR;
- const beta = 0.9;
-
- // Forward pass
- const probs = this.inversePredict(stateFeature, nextStateFeature);
-
- // Cross-entropy loss
- const loss = -Math.log(probs[targetAction] + 1e-8);
-
- // Gradient
- const grad = new Float32Array(this.numActions);
- for (let a = 0; a < this.numActions; a++) {
- grad[a] = probs[a] - (a === targetAction ? 1 : 0);
- }
-
- // Backprop to weights
- const input = new Float32Array(2 * featureDim);
- input.set(stateFeature);
- input.set(nextStateFeature, featureDim);
-
- for (let i = 0; i < 2 * featureDim; i++) {
- for (let a = 0; a < this.numActions; a++) {
- const weightGrad = input[i] * grad[a];
- const idx = i * this.numActions + a;
- this.inverseMomentum[idx] = beta * this.inverseMomentum[idx] + (1 - beta) * weightGrad;
- this.inverseModel[idx] -= lr * this.inverseMomentum[idx];
- }
- }
-
- return loss;
- }
-
- private updateRNDPredictor(state: Float32Array): void {
- const featureDim = this.config.featureDim;
- const lr = this.config.learningRate;
- const beta = 0.9;
-
- // Target output (fixed)
- const targetOutput = this.rndForward(state, this.rndTarget);
-
- // Predictor output
- const predictorOutput = this.rndForward(state, this.rndPredictor);
-
- // Gradient
- const grad = new Float32Array(featureDim);
- for (let f = 0; f < featureDim; f++) {
- grad[f] = 2 * (predictorOutput[f] - targetOutput[f]);
- }
-
- // Update predictor weights
- for (let s = 0; s < Math.min(state.length, this.stateDim); s++) {
- for (let f = 0; f < featureDim; f++) {
- if (predictorOutput[f] > 0) { // ReLU gradient
- const weightGrad = state[s] * grad[f];
- const idx = s * featureDim + f;
- this.rndMomentum[idx] = beta * this.rndMomentum[idx] + (1 - beta) * weightGrad;
- this.rndPredictor[idx] -= lr * this.rndMomentum[idx];
- }
- }
- }
- }
-
- private normalizeIntrinsic(raw: number): number {
- // Update running statistics
- const alpha = 0.01;
- this.intrinsicMean = (1 - alpha) * this.intrinsicMean + alpha * raw;
- this.intrinsicVar = (1 - alpha) * this.intrinsicVar + alpha * (raw - this.intrinsicMean) ** 2;
-
- // Normalize
- const normalized = (raw - this.intrinsicMean) / (Math.sqrt(this.intrinsicVar) + 1e-8);
-
- // Clip to reasonable range
- return Math.max(-5, Math.min(5, normalized));
- }
-
- private softmax(logits: Float32Array): Float32Array {
- const max = Math.max(...logits);
- const exps = new Float32Array(logits.length);
- let sum = 0;
-
- for (let i = 0; i < logits.length; i++) {
- exps[i] = Math.exp(logits[i] - max);
- sum += exps[i];
- }
-
- for (let i = 0; i < exps.length; i++) {
- exps[i] /= sum;
- }
-
- return exps;
- }
-
- private hashAction(action: string): number {
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % this.numActions;
- }
- return hash;
- }
-}
-
-/**
- * Factory function
- */
-export function createCuriosity(config?: Partial<CuriosityConfig>): CuriosityModule {
- return new CuriosityModule(config);
-}
diff --git a/v3/neural/algorithms/decision-transformer.ts b/v3/neural/algorithms/decision-transformer.ts
deleted file mode 100644
index 2987df5842..0000000000
--- a/v3/neural/algorithms/decision-transformer.ts
+++ /dev/null
@@ -1,521 +0,0 @@
-/**
- * Decision Transformer
- *
- * Implements sequence modeling approach for RL:
- * - Trajectory as sequence: (s, a, R, s, a, R, ...)
- * - Return-conditioned generation
- * - Causal transformer attention
- * - Offline RL from trajectories
- *
- * Performance Target: <10ms per forward pass
- */
-
-import type {
- DecisionTransformerConfig,
- Trajectory,
- TrajectoryStep,
-} from '../types.js';
-
-/**
- * Default Decision Transformer configuration
- */
-export const DEFAULT_DT_CONFIG: DecisionTransformerConfig = {
- algorithm: 'decision-transformer',
- learningRate: 0.0001,
- gamma: 0.99,
- entropyCoef: 0,
- valueLossCoef: 0,
- maxGradNorm: 1.0,
- epochs: 1,
- miniBatchSize: 64,
- contextLength: 20,
- numHeads: 4,
- numLayers: 2,
- hiddenDim: 64,
- embeddingDim: 32,
- dropout: 0.1,
-};
-
-/**
- * Sequence entry for transformer
- */
-interface SequenceEntry {
- returnToGo: number;
- state: Float32Array;
- action: number;
- timestep: number;
-}
-
-/**
- * Decision Transformer Implementation
- */
-export class DecisionTransformer {
- private config: DecisionTransformerConfig;
-
- // Embeddings
- private stateEmbed: Float32Array;
- private actionEmbed: Float32Array;
- private returnEmbed: Float32Array;
- private posEmbed: Float32Array;
-
- // Transformer layers (simplified)
- private attentionWeights: Float32Array[][];
- private ffnWeights: Float32Array[][];
-
- // Output head
- private actionHead: Float32Array;
-
- // Training buffer
- private trajectoryBuffer: Trajectory[] = [];
-
- // Dimensions
- private stateDim = 768;
- private numActions = 4;
-
- // Statistics
- private updateCount = 0;
- private avgLoss = 0;
-
- constructor(config: Partial<DecisionTransformerConfig> = {}) {
- this.config = { ...DEFAULT_DT_CONFIG, ...config };
-
- // Initialize embeddings
- this.stateEmbed = this.initEmbedding(this.stateDim, this.config.embeddingDim);
- this.actionEmbed = this.initEmbedding(this.numActions, this.config.embeddingDim);
- this.returnEmbed = this.initEmbedding(1, this.config.embeddingDim);
- this.posEmbed = this.initEmbedding(this.config.contextLength * 3, this.config.embeddingDim);
-
- // Initialize transformer layers
- this.attentionWeights = [];
- this.ffnWeights = [];
-
- for (let l = 0; l < this.config.numLayers; l++) {
- // Attention: Q, K, V, O projections
- this.attentionWeights.push([
- this.initWeight(this.config.embeddingDim, this.config.hiddenDim), // Q
- this.initWeight(this.config.embeddingDim, this.config.hiddenDim), // K
- this.initWeight(this.config.embeddingDim, this.config.hiddenDim), // V
- this.initWeight(this.config.hiddenDim, this.config.embeddingDim), // O
- ]);
-
- // FFN: up and down projections
- this.ffnWeights.push([
- this.initWeight(this.config.embeddingDim, this.config.hiddenDim * 4),
- this.initWeight(this.config.hiddenDim * 4, this.config.embeddingDim),
- ]);
- }
-
- // Action prediction head
- this.actionHead = this.initWeight(this.config.embeddingDim, this.numActions);
- }
-
- /**
- * Add trajectory for training
- */
- addTrajectory(trajectory: Trajectory): void {
- if (trajectory.isComplete && trajectory.steps.length > 0) {
- this.trajectoryBuffer.push(trajectory);
-
- // Keep buffer bounded
- if (this.trajectoryBuffer.length > 1000) {
- this.trajectoryBuffer = this.trajectoryBuffer.slice(-1000);
- }
- }
- }
-
- /**
- * Train on buffered trajectories
- * Target: <10ms per batch
- */
- train(): { loss: number; accuracy: number } {
- const startTime = performance.now();
-
- if (this.trajectoryBuffer.length === 0) {
- return { loss: 0, accuracy: 0 };
- }
-
- // Sample mini-batch of trajectories
- const batchSize = Math.min(this.config.miniBatchSize, this.trajectoryBuffer.length);
- const batch: Trajectory[] = [];
-
- for (let i = 0; i < batchSize; i++) {
- const idx = Math.floor(Math.random() * this.trajectoryBuffer.length);
- batch.push(this.trajectoryBuffer[idx]);
- }
-
- let totalLoss = 0;
- let correct = 0;
- let total = 0;
-
- for (const trajectory of batch) {
- // Create sequence from trajectory
- const sequence = this.createSequence(trajectory);
-
- if (sequence.length < 2) continue;
-
- // Forward pass and compute loss
- for (let t = 1; t < sequence.length; t++) {
- // Use context up to position t
- const context = sequence.slice(Math.max(0, t - this.config.contextLength), t);
- const target = sequence[t];
-
- // Predict action
- const predicted = this.forward(context);
- const predictedAction = this.argmax(predicted);
-
- // Cross-entropy loss
- const loss = -Math.log(predicted[target.action] + 1e-8);
- totalLoss += loss;
-
- if (predictedAction === target.action) {
- correct++;
- }
- total++;
-
- // Gradient update (simplified)
- this.updateWeights(context, target.action, predicted);
- }
- }
-
- this.updateCount++;
- this.avgLoss = total > 0 ? totalLoss / total : 0;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 10) {
- console.warn(`DT training exceeded target: ${elapsed.toFixed(2)}ms > 10ms`);
- }
-
- return {
- loss: this.avgLoss,
- accuracy: total > 0 ? correct / total : 0,
- };
- }
-
- /**
- * Get action conditioned on target return
- */
- getAction(
- states: Float32Array[],
- actions: number[],
- targetReturn: number
- ): number {
- // Build sequence
- const sequence: SequenceEntry[] = [];
- let returnToGo = targetReturn;
-
- for (let i = 0; i < states.length; i++) {
- sequence.push({
- returnToGo,
- state: states[i],
- action: actions[i] ?? 0,
- timestep: i,
- });
-
- // Decrease return-to-go by estimated reward
- if (i > 0) {
- returnToGo -= 0.1; // Placeholder for actual reward
- }
- }
-
- // Forward pass
- const logits = this.forward(sequence);
- return this.argmax(logits);
- }
-
- /**
- * Forward pass through transformer
- */
- forward(sequence: SequenceEntry[]): Float32Array {
- // Embed sequence elements
- const seqLen = Math.min(sequence.length, this.config.contextLength);
- const embedDim = this.config.embeddingDim;
-
- // Initialize hidden states (simplified: stack all modalities)
- const hidden = new Float32Array(seqLen * 3 * embedDim);
-
- for (let t = 0; t < seqLen; t++) {
- const entry = sequence[sequence.length - seqLen + t];
- const baseIdx = t * 3 * embedDim;
-
- // Embed return
- for (let d = 0; d < embedDim; d++) {
- hidden[baseIdx + d] = entry.returnToGo * this.returnEmbed[d];
- }
-
- // Embed state
- for (let d = 0; d < embedDim; d++) {
- let stateSum = 0;
- for (let s = 0; s < Math.min(entry.state.length, this.stateDim); s++) {
- stateSum += entry.state[s] * this.stateEmbed[s * embedDim + d];
- }
- hidden[baseIdx + embedDim + d] = stateSum;
- }
-
- // Embed action
- for (let d = 0; d < embedDim; d++) {
- hidden[baseIdx + 2 * embedDim + d] = this.actionEmbed[entry.action * embedDim + d];
- }
-
- // Add positional embedding
- for (let d = 0; d < 3 * embedDim; d++) {
- hidden[baseIdx + d] += this.posEmbed[t * 3 * embedDim + d] || 0;
- }
- }
-
- // Apply transformer layers
- for (let l = 0; l < this.config.numLayers; l++) {
- hidden.set(this.transformerLayer(hidden, seqLen * 3, l));
- }
-
- // Extract last state position embedding for action prediction
- const lastStateIdx = (seqLen * 3 - 2) * embedDim;
- const lastState = hidden.slice(lastStateIdx, lastStateIdx + embedDim);
-
- // Action prediction
- const logits = new Float32Array(this.numActions);
- for (let a = 0; a < this.numActions; a++) {
- let sum = 0;
- for (let d = 0; d < embedDim; d++) {
- sum += lastState[d] * this.actionHead[d * this.numActions + a];
- }
- logits[a] = sum;
- }
-
- return this.softmax(logits);
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- bufferSize: this.trajectoryBuffer.length,
- avgLoss: this.avgLoss,
- contextLength: this.config.contextLength,
- numLayers: this.config.numLayers,
- };
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private initEmbedding(inputDim: number, outputDim: number): Float32Array {
- const embed = new Float32Array(inputDim * outputDim);
- const scale = Math.sqrt(2 / inputDim);
- for (let i = 0; i < embed.length; i++) {
- embed[i] = (Math.random() - 0.5) * scale;
- }
- return embed;
- }
-
- private initWeight(inputDim: number, outputDim: number): Float32Array {
- const weight = new Float32Array(inputDim * outputDim);
- const scale = Math.sqrt(2 / inputDim);
- for (let i = 0; i < weight.length; i++) {
- weight[i] = (Math.random() - 0.5) * scale;
- }
- return weight;
- }
-
- private createSequence(trajectory: Trajectory): SequenceEntry[] {
- const sequence: SequenceEntry[] = [];
-
- // Compute returns-to-go
- const rewards = trajectory.steps.map(s => s.reward);
- const returnsToGo = new Array(rewards.length).fill(0);
- let cumReturn = 0;
-
- for (let t = rewards.length - 1; t >= 0; t--) {
- cumReturn = rewards[t] + this.config.gamma * cumReturn;
- returnsToGo[t] = cumReturn;
- }
-
- // Create sequence entries
- for (let t = 0; t < trajectory.steps.length; t++) {
- sequence.push({
- returnToGo: returnsToGo[t],
- state: trajectory.steps[t].stateAfter,
- action: this.hashAction(trajectory.steps[t].action),
- timestep: t,
- });
- }
-
- return sequence;
- }
-
- private transformerLayer(
- hidden: Float32Array,
- seqLen: number,
- layerIdx: number
- ): Float32Array {
- const embedDim = this.config.embeddingDim;
- const hiddenDim = this.config.hiddenDim;
- const numHeads = this.config.numHeads;
- const headDim = hiddenDim / numHeads;
-
- const output = new Float32Array(hidden.length);
-
- // Self-attention (simplified causal)
- const [Wq, Wk, Wv, Wo] = this.attentionWeights[layerIdx];
-
- // Compute Q, K, V for all positions
- const Q = new Float32Array(seqLen * hiddenDim);
- const K = new Float32Array(seqLen * hiddenDim);
- const V = new Float32Array(seqLen * hiddenDim);
-
- for (let pos = 0; pos < seqLen; pos++) {
- for (let h = 0; h < hiddenDim; h++) {
- let qSum = 0, kSum = 0, vSum = 0;
- for (let d = 0; d < embedDim; d++) {
- const hiddenVal = hidden[pos * embedDim + d];
- qSum += hiddenVal * Wq[d * hiddenDim + h];
- kSum += hiddenVal * Wk[d * hiddenDim + h];
- vSum += hiddenVal * Wv[d * hiddenDim + h];
- }
- Q[pos * hiddenDim + h] = qSum;
- K[pos * hiddenDim + h] = kSum;
- V[pos * hiddenDim + h] = vSum;
- }
- }
-
- // Causal attention
- for (let pos = 0; pos < seqLen; pos++) {
- // Compute attention scores for current position
- const scores = new Float32Array(pos + 1);
- for (let k = 0; k <= pos; k++) {
- let score = 0;
- for (let h = 0; h < hiddenDim; h++) {
- score += Q[pos * hiddenDim + h] * K[k * hiddenDim + h];
- }
- scores[k] = score / Math.sqrt(headDim);
- }
-
- // Softmax
- const maxScore = Math.max(...scores);
- let sumExp = 0;
- for (let k = 0; k <= pos; k++) {
- scores[k] = Math.exp(scores[k] - maxScore);
- sumExp += scores[k];
- }
- for (let k = 0; k <= pos; k++) {
- scores[k] /= sumExp;
- }
-
- // Weighted sum of values
- const attnOut = new Float32Array(hiddenDim);
- for (let k = 0; k <= pos; k++) {
- for (let h = 0; h < hiddenDim; h++) {
- attnOut[h] += scores[k] * V[k * hiddenDim + h];
- }
- }
-
- // Output projection
- for (let d = 0; d < embedDim; d++) {
- let sum = hidden[pos * embedDim + d]; // Residual
- for (let h = 0; h < hiddenDim; h++) {
- sum += attnOut[h] * Wo[h * embedDim + d];
- }
- output[pos * embedDim + d] = sum;
- }
- }
-
- // FFN with residual
- const [Wup, Wdown] = this.ffnWeights[layerIdx];
- const ffnHiddenDim = hiddenDim * 4;
-
- for (let pos = 0; pos < seqLen; pos++) {
- // Up projection + GELU
- const ffnHidden = new Float32Array(ffnHiddenDim);
- for (let h = 0; h < ffnHiddenDim; h++) {
- let sum = 0;
- for (let d = 0; d < embedDim; d++) {
- sum += output[pos * embedDim + d] * Wup[d * ffnHiddenDim + h];
- }
- // GELU approximation
- ffnHidden[h] = sum * 0.5 * (1 + Math.tanh(0.7978845608 * (sum + 0.044715 * sum * sum * sum)));
- }
-
- // Down projection
- for (let d = 0; d < embedDim; d++) {
- let sum = output[pos * embedDim + d]; // Residual
- for (let h = 0; h < ffnHiddenDim; h++) {
- sum += ffnHidden[h] * Wdown[h * embedDim + d];
- }
- output[pos * embedDim + d] = sum;
- }
- }
-
- return output;
- }
-
- private updateWeights(
- context: SequenceEntry[],
- targetAction: number,
- predicted: Float32Array
- ): void {
- // Simplified gradient update for action head
- const lr = this.config.learningRate;
- const embedDim = this.config.embeddingDim;
-
- // Gradient of cross-entropy
- const grad = new Float32Array(this.numActions);
- for (let a = 0; a < this.numActions; a++) {
- grad[a] = predicted[a] - (a === targetAction ? 1 : 0);
- }
-
- // Update action head (simplified)
- for (let d = 0; d < embedDim; d++) {
- for (let a = 0; a < this.numActions; a++) {
- this.actionHead[d * this.numActions + a] -= lr * grad[a] * 0.1;
- }
- }
- }
-
- private softmax(logits: Float32Array): Float32Array {
- const max = Math.max(...logits);
- const exps = new Float32Array(logits.length);
- let sum = 0;
-
- for (let i = 0; i < logits.length; i++) {
- exps[i] = Math.exp(logits[i] - max);
- sum += exps[i];
- }
-
- for (let i = 0; i < exps.length; i++) {
- exps[i] /= sum;
- }
-
- return exps;
- }
-
- private argmax(values: Float32Array): number {
- let maxIdx = 0;
- let maxVal = values[0];
- for (let i = 1; i < values.length; i++) {
- if (values[i] > maxVal) {
- maxVal = values[i];
- maxIdx = i;
- }
- }
- return maxIdx;
- }
-
- private hashAction(action: string): number {
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % this.numActions;
- }
- return hash;
- }
-}
-
-/**
- * Factory function
- */
-export function createDecisionTransformer(
- config?: Partial<DecisionTransformerConfig>
-): DecisionTransformer {
- return new DecisionTransformer(config);
-}
diff --git a/v3/neural/algorithms/dqn.ts b/v3/neural/algorithms/dqn.ts
deleted file mode 100644
index 8666a1a7dc..0000000000
--- a/v3/neural/algorithms/dqn.ts
+++ /dev/null
@@ -1,382 +0,0 @@
-/**
- * Deep Q-Network (DQN)
- *
- * Implements DQN with enhancements:
- * - Experience replay
- * - Target network
- * - Double DQN (optional)
- * - Dueling architecture (optional)
- * - Epsilon-greedy exploration
- *
- * Performance Target: <10ms per update step
- */
-
-import type {
- DQNConfig,
- Trajectory,
- TrajectoryStep,
-} from '../types.js';
-
-/**
- * Default DQN configuration
- */
-export const DEFAULT_DQN_CONFIG: DQNConfig = {
- algorithm: 'dqn',
- learningRate: 0.0001,
- gamma: 0.99,
- entropyCoef: 0,
- valueLossCoef: 1,
- maxGradNorm: 10,
- epochs: 1,
- miniBatchSize: 32,
- bufferSize: 10000,
- explorationInitial: 1.0,
- explorationFinal: 0.01,
- explorationDecay: 10000,
- targetUpdateFreq: 100,
- doubleDQN: true,
- duelingNetwork: false,
-};
-
-/**
- * Experience for replay buffer
- */
-interface DQNExperience {
- state: Float32Array;
- action: number;
- reward: number;
- nextState: Float32Array;
- done: boolean;
-}
-
-/**
- * DQN Algorithm Implementation
- */
-export class DQNAlgorithm {
- private config: DQNConfig;
-
- // Q-network weights
- private qWeights: Float32Array[];
- private targetWeights: Float32Array[];
-
- // Optimizer state
- private qMomentum: Float32Array[];
-
- // Replay buffer (circular)
- private buffer: DQNExperience[] = [];
- private bufferIdx = 0;
-
- // Exploration
- private epsilon: number;
- private stepCount = 0;
-
- // Number of actions
- private numActions = 4;
- private inputDim = 768;
-
- // Statistics
- private updateCount = 0;
- private avgLoss = 0;
-
- constructor(config: Partial<DQNConfig> = {}) {
- this.config = { ...DEFAULT_DQN_CONFIG, ...config };
- this.epsilon = this.config.explorationInitial;
-
- // Initialize Q-network (2 hidden layers)
- this.qWeights = this.initializeNetwork();
- this.targetWeights = this.copyNetwork(this.qWeights);
- this.qMomentum = this.qWeights.map(w => new Float32Array(w.length));
- }
-
- /**
- * Add experience from trajectory
- */
- addExperience(trajectory: Trajectory): void {
- for (let i = 0; i < trajectory.steps.length; i++) {
- const step = trajectory.steps[i];
- const nextStep = i < trajectory.steps.length - 1
- ? trajectory.steps[i + 1]
- : null;
-
- const experience: DQNExperience = {
- state: step.stateBefore,
- action: this.hashAction(step.action),
- reward: step.reward,
- nextState: step.stateAfter,
- done: nextStep === null,
- };
-
- // Add to circular buffer
- if (this.buffer.length < this.config.bufferSize) {
- this.buffer.push(experience);
- } else {
- this.buffer[this.bufferIdx] = experience;
- }
- this.bufferIdx = (this.bufferIdx + 1) % this.config.bufferSize;
- }
- }
-
- /**
- * Perform DQN update
- * Target: <10ms
- */
- update(): { loss: number; epsilon: number } {
- const startTime = performance.now();
-
- if (this.buffer.length < this.config.miniBatchSize) {
- return { loss: 0, epsilon: this.epsilon };
- }
-
- // Sample mini-batch
- const batch = this.sampleBatch();
-
- // Compute TD targets
- let totalLoss = 0;
- const gradients = this.qWeights.map(w => new Float32Array(w.length));
-
- for (const exp of batch) {
- // Current Q-values
- const qValues = this.forward(exp.state, this.qWeights);
- const currentQ = qValues[exp.action];
-
- // Target Q-value
- let targetQ: number;
- if (exp.done) {
- targetQ = exp.reward;
- } else {
- if (this.config.doubleDQN) {
- // Double DQN: use online network to select action, target to evaluate
- const nextQOnline = this.forward(exp.nextState, this.qWeights);
- const bestAction = this.argmax(nextQOnline);
- const nextQTarget = this.forward(exp.nextState, this.targetWeights);
- targetQ = exp.reward + this.config.gamma * nextQTarget[bestAction];
- } else {
- // Standard DQN
- const nextQ = this.forward(exp.nextState, this.targetWeights);
- targetQ = exp.reward + this.config.gamma * Math.max(...nextQ);
- }
- }
-
- // TD error
- const tdError = targetQ - currentQ;
- const loss = tdError * tdError;
- totalLoss += loss;
-
- // Accumulate gradients
- this.accumulateGradients(gradients, exp.state, exp.action, tdError);
- }
-
- // Apply gradients
- this.applyGradients(gradients, batch.length);
-
- // Update target network periodically
- this.stepCount++;
- if (this.stepCount % this.config.targetUpdateFreq === 0) {
- this.targetWeights = this.copyNetwork(this.qWeights);
- }
-
- // Decay exploration
- this.epsilon = Math.max(
- this.config.explorationFinal,
- this.config.explorationInitial - this.stepCount / this.config.explorationDecay
- );
-
- this.updateCount++;
- this.avgLoss = totalLoss / batch.length;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 10) {
- console.warn(`DQN update exceeded target: ${elapsed.toFixed(2)}ms > 10ms`);
- }
-
- return {
- loss: this.avgLoss,
- epsilon: this.epsilon,
- };
- }
-
- /**
- * Get action using epsilon-greedy
- */
- getAction(state: Float32Array, explore: boolean = true): number {
- if (explore && Math.random() < this.epsilon) {
- return Math.floor(Math.random() * this.numActions);
- }
-
- const qValues = this.forward(state, this.qWeights);
- return this.argmax(qValues);
- }
-
- /**
- * Get Q-values for a state
- */
- getQValues(state: Float32Array): Float32Array {
- return this.forward(state, this.qWeights);
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- bufferSize: this.buffer.length,
- epsilon: this.epsilon,
- avgLoss: this.avgLoss,
- stepCount: this.stepCount,
- };
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private initializeNetwork(): Float32Array[] {
- // Simple 2-layer network: input -> hidden -> output
- const hiddenDim = 64;
- const weights: Float32Array[] = [];
-
- // Layer 1: input_dim -> hidden
- const w1 = new Float32Array(this.inputDim * hiddenDim);
- const scale1 = Math.sqrt(2 / this.inputDim);
- for (let i = 0; i < w1.length; i++) {
- w1[i] = (Math.random() - 0.5) * scale1;
- }
- weights.push(w1);
-
- // Layer 2: hidden -> num_actions
- const w2 = new Float32Array(hiddenDim * this.numActions);
- const scale2 = Math.sqrt(2 / hiddenDim);
- for (let i = 0; i < w2.length; i++) {
- w2[i] = (Math.random() - 0.5) * scale2;
- }
- weights.push(w2);
-
- return weights;
- }
-
- private copyNetwork(weights: Float32Array[]): Float32Array[] {
- return weights.map(w => new Float32Array(w));
- }
-
- private forward(state: Float32Array, weights: Float32Array[]): Float32Array {
- const hiddenDim = 64;
-
- // Layer 1: ReLU(W1 * x)
- const hidden = new Float32Array(hiddenDim);
- for (let h = 0; h < hiddenDim; h++) {
- let sum = 0;
- for (let i = 0; i < Math.min(state.length, this.inputDim); i++) {
- sum += state[i] * weights[0][i * hiddenDim + h];
- }
- hidden[h] = Math.max(0, sum); // ReLU
- }
-
- // Layer 2: W2 * hidden (no activation for Q-values)
- const output = new Float32Array(this.numActions);
- for (let a = 0; a < this.numActions; a++) {
- let sum = 0;
- for (let h = 0; h < hiddenDim; h++) {
- sum += hidden[h] * weights[1][h * this.numActions + a];
- }
- output[a] = sum;
- }
-
- return output;
- }
-
- private accumulateGradients(
- gradients: Float32Array[],
- state: Float32Array,
- action: number,
- tdError: number
- ): void {
- const hiddenDim = 64;
-
- // Forward pass to get hidden activations
- const hidden = new Float32Array(hiddenDim);
- for (let h = 0; h < hiddenDim; h++) {
- let sum = 0;
- for (let i = 0; i < Math.min(state.length, this.inputDim); i++) {
- sum += state[i] * this.qWeights[0][i * hiddenDim + h];
- }
- hidden[h] = Math.max(0, sum);
- }
-
- // Gradient for layer 2 (only for selected action)
- for (let h = 0; h < hiddenDim; h++) {
- gradients[1][h * this.numActions + action] += hidden[h] * tdError;
- }
-
- // Gradient for layer 1 (backprop through ReLU)
- for (let h = 0; h < hiddenDim; h++) {
- if (hidden[h] > 0) { // ReLU gradient
- const grad = tdError * this.qWeights[1][h * this.numActions + action];
- for (let i = 0; i < Math.min(state.length, this.inputDim); i++) {
- gradients[0][i * hiddenDim + h] += state[i] * grad;
- }
- }
- }
- }
-
- private applyGradients(gradients: Float32Array[], batchSize: number): void {
- const lr = this.config.learningRate / batchSize;
- const beta = 0.9;
-
- for (let layer = 0; layer < gradients.length; layer++) {
- for (let i = 0; i < gradients[layer].length; i++) {
- // Gradient clipping
- const grad = Math.max(
- Math.min(gradients[layer][i], this.config.maxGradNorm),
- -this.config.maxGradNorm
- );
-
- // Momentum update
- this.qMomentum[layer][i] = beta * this.qMomentum[layer][i] + (1 - beta) * grad;
- this.qWeights[layer][i] += lr * this.qMomentum[layer][i];
- }
- }
- }
-
- private sampleBatch(): DQNExperience[] {
- const batch: DQNExperience[] = [];
- const indices = new Set<number>();
-
- while (indices.size < this.config.miniBatchSize && indices.size < this.buffer.length) {
- indices.add(Math.floor(Math.random() * this.buffer.length));
- }
-
- for (const idx of indices) {
- batch.push(this.buffer[idx]);
- }
-
- return batch;
- }
-
- private hashAction(action: string): number {
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % this.numActions;
- }
- return hash;
- }
-
- private argmax(values: Float32Array): number {
- let maxIdx = 0;
- let maxVal = values[0];
- for (let i = 1; i < values.length; i++) {
- if (values[i] > maxVal) {
- maxVal = values[i];
- maxIdx = i;
- }
- }
- return maxIdx;
- }
-}
-
-/**
- * Factory function
- */
-export function createDQN(config?: Partial<DQNConfig>): DQNAlgorithm {
- return new DQNAlgorithm(config);
-}
diff --git a/v3/neural/algorithms/index.ts b/v3/neural/algorithms/index.ts
deleted file mode 100644
index c12d9795ed..0000000000
--- a/v3/neural/algorithms/index.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-/**
- * RL Algorithms Index
- *
- * Exports all reinforcement learning algorithm implementations.
- */
-
-// PPO - Proximal Policy Optimization
-export {
- PPOAlgorithm,
- createPPO,
- DEFAULT_PPO_CONFIG,
-} from './ppo.js';
-export type { PPOConfig } from '../types.js';
-
-// DQN - Deep Q-Network
-export {
- DQNAlgorithm,
- createDQN,
- DEFAULT_DQN_CONFIG,
-} from './dqn.js';
-export type { DQNConfig } from '../types.js';
-
-// A2C - Advantage Actor-Critic
-export {
- A2CAlgorithm,
- createA2C,
- DEFAULT_A2C_CONFIG,
-} from './a2c.js';
-export type { A2CConfig } from './a2c.js';
-
-// Decision Transformer
-export {
- DecisionTransformer,
- createDecisionTransformer,
- DEFAULT_DT_CONFIG,
-} from './decision-transformer.js';
-export type { DecisionTransformerConfig } from '../types.js';
-
-// Q-Learning (Tabular)
-export {
- QLearning,
- createQLearning,
- DEFAULT_QLEARNING_CONFIG,
-} from './q-learning.js';
-export type { QLearningConfig } from './q-learning.js';
-
-// SARSA
-export {
- SARSAAlgorithm,
- createSARSA,
- DEFAULT_SARSA_CONFIG,
-} from './sarsa.js';
-export type { SARSAConfig } from './sarsa.js';
-
-// Curiosity-Driven Exploration
-export {
- CuriosityModule,
- createCuriosity,
- DEFAULT_CURIOSITY_CONFIG,
-} from './curiosity.js';
-export type { CuriosityConfig } from '../types.js';
-
-/**
- * Algorithm factory
- */
-import type { RLAlgorithm, RLConfig } from '../types.js';
-import { createPPO } from './ppo.js';
-import { createDQN } from './dqn.js';
-import { createA2C } from './a2c.js';
-import { createDecisionTransformer } from './decision-transformer.js';
-import { createQLearning } from './q-learning.js';
-import { createSARSA } from './sarsa.js';
-import { createCuriosity } from './curiosity.js';
-
-/**
- * Create an RL algorithm by name
- */
-export function createAlgorithm(algorithm: RLAlgorithm, config?: Partial<RLConfig>): unknown {
- switch (algorithm) {
- case 'ppo':
- return createPPO(config);
- case 'dqn':
- return createDQN(config);
- case 'a2c':
- return createA2C(config);
- case 'decision-transformer':
- return createDecisionTransformer(config);
- case 'q-learning':
- return createQLearning(config);
- case 'sarsa':
- return createSARSA(config);
- case 'curiosity':
- return createCuriosity(config);
- default:
- throw new Error(`Unknown algorithm: ${algorithm}`);
- }
-}
-
-/**
- * Get default configuration for an algorithm
- */
-export function getDefaultConfig(algorithm: RLAlgorithm): RLConfig {
- switch (algorithm) {
- case 'ppo':
- return { ...DEFAULT_PPO_CONFIG };
- case 'dqn':
- return { ...DEFAULT_DQN_CONFIG };
- case 'a2c':
- return { ...DEFAULT_A2C_CONFIG };
- case 'decision-transformer':
- return { ...DEFAULT_DT_CONFIG };
- case 'q-learning':
- return { ...DEFAULT_QLEARNING_CONFIG };
- case 'sarsa':
- return { ...DEFAULT_SARSA_CONFIG };
- case 'curiosity':
- return { ...DEFAULT_CURIOSITY_CONFIG };
- default:
- throw new Error(`Unknown algorithm: ${algorithm}`);
- }
-}
diff --git a/v3/neural/algorithms/ppo.ts b/v3/neural/algorithms/ppo.ts
deleted file mode 100644
index 8fbf001666..0000000000
--- a/v3/neural/algorithms/ppo.ts
+++ /dev/null
@@ -1,429 +0,0 @@
-/**
- * Proximal Policy Optimization (PPO)
- *
- * Implements PPO algorithm for stable policy learning with:
- * - Clipped surrogate objective
- * - GAE (Generalized Advantage Estimation)
- * - Value function clipping
- * - Entropy bonus
- *
- * Performance Target: <10ms per update step
- */
-
-import type {
- PPOConfig,
- Trajectory,
- TrajectoryStep,
-} from '../types.js';
-
-/**
- * Default PPO configuration
- */
-export const DEFAULT_PPO_CONFIG: PPOConfig = {
- algorithm: 'ppo',
- learningRate: 0.0003,
- gamma: 0.99,
- entropyCoef: 0.01,
- valueLossCoef: 0.5,
- maxGradNorm: 0.5,
- epochs: 4,
- miniBatchSize: 64,
- clipRange: 0.2,
- clipRangeVf: null,
- targetKL: 0.01,
- gaeLambda: 0.95,
-};
-
-/**
- * PPO experience buffer entry
- */
-interface PPOExperience {
- state: Float32Array;
- action: number;
- reward: number;
- value: number;
- logProb: number;
- advantage: number;
- return_: number;
-}
-
-/**
- * PPO Algorithm Implementation
- */
-export class PPOAlgorithm {
- private config: PPOConfig;
-
- // Policy network weights (simplified linear model for speed)
- private policyWeights: Float32Array;
- private valueWeights: Float32Array;
-
- // Optimizer state
- private policyMomentum: Float32Array;
- private valueMomentum: Float32Array;
-
- // Experience buffer
- private buffer: PPOExperience[] = [];
-
- // Statistics
- private updateCount = 0;
- private totalLoss = 0;
- private approxKL = 0;
- private clipFraction = 0;
-
- constructor(config: Partial<PPOConfig> = {}) {
- this.config = { ...DEFAULT_PPO_CONFIG, ...config };
-
- // Initialize weights (768 input dim, simplified)
- const dim = 768;
- this.policyWeights = new Float32Array(dim);
- this.valueWeights = new Float32Array(dim);
- this.policyMomentum = new Float32Array(dim);
- this.valueMomentum = new Float32Array(dim);
-
- // Xavier initialization
- const scale = Math.sqrt(2 / dim);
- for (let i = 0; i < dim; i++) {
- this.policyWeights[i] = (Math.random() - 0.5) * scale;
- this.valueWeights[i] = (Math.random() - 0.5) * scale;
- }
- }
-
- /**
- * Add experience from trajectory
- */
- addExperience(trajectory: Trajectory): void {
- if (trajectory.steps.length === 0) return;
-
- // Compute values for each step
- const values = trajectory.steps.map(step =>
- this.computeValue(step.stateAfter)
- );
-
- // Compute advantages using GAE
- const advantages = this.computeGAE(
- trajectory.steps.map(s => s.reward),
- values
- );
-
- // Compute returns
- const returns = this.computeReturns(
- trajectory.steps.map(s => s.reward)
- );
-
- // Add to buffer
- for (let i = 0; i < trajectory.steps.length; i++) {
- const step = trajectory.steps[i];
- this.buffer.push({
- state: step.stateAfter,
- action: this.hashAction(step.action),
- reward: step.reward,
- value: values[i],
- logProb: this.computeLogProb(step.stateAfter, step.action),
- advantage: advantages[i],
- return_: returns[i],
- });
- }
- }
-
- /**
- * Perform PPO update
- * Target: <10ms
- */
- update(): { policyLoss: number; valueLoss: number; entropy: number } {
- const startTime = performance.now();
-
- if (this.buffer.length < this.config.miniBatchSize) {
- return { policyLoss: 0, valueLoss: 0, entropy: 0 };
- }
-
- // Normalize advantages
- const advantages = this.buffer.map(e => e.advantage);
- const advMean = advantages.reduce((a, b) => a + b, 0) / advantages.length;
- const advStd = Math.sqrt(
- advantages.reduce((a, b) => a + (b - advMean) ** 2, 0) / advantages.length
- ) + 1e-8;
-
- for (const exp of this.buffer) {
- exp.advantage = (exp.advantage - advMean) / advStd;
- }
-
- let totalPolicyLoss = 0;
- let totalValueLoss = 0;
- let totalEntropy = 0;
- let totalClipFrac = 0;
- let totalKL = 0;
- let numUpdates = 0;
-
- // Multiple epochs
- for (let epoch = 0; epoch < this.config.epochs; epoch++) {
- // Shuffle buffer
- this.shuffleBuffer();
-
- // Process mini-batches
- for (let i = 0; i < this.buffer.length; i += this.config.miniBatchSize) {
- const batch = this.buffer.slice(i, i + this.config.miniBatchSize);
- if (batch.length < this.config.miniBatchSize / 2) continue;
-
- const result = this.updateMiniBatch(batch);
- totalPolicyLoss += result.policyLoss;
- totalValueLoss += result.valueLoss;
- totalEntropy += result.entropy;
- totalClipFrac += result.clipFrac;
- totalKL += result.kl;
- numUpdates++;
-
- // Early stopping if KL too high
- if (result.kl > this.config.targetKL * 1.5) {
- break;
- }
- }
- }
-
- // Clear buffer
- this.buffer = [];
- this.updateCount++;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 10) {
- console.warn(`PPO update exceeded target: ${elapsed.toFixed(2)}ms > 10ms`);
- }
-
- return {
- policyLoss: numUpdates > 0 ? totalPolicyLoss / numUpdates : 0,
- valueLoss: numUpdates > 0 ? totalValueLoss / numUpdates : 0,
- entropy: numUpdates > 0 ? totalEntropy / numUpdates : 0,
- };
- }
-
- /**
- * Get action from policy
- */
- getAction(state: Float32Array): { action: number; logProb: number; value: number } {
- const logits = this.computeLogits(state);
- const probs = this.softmax(logits);
- const action = this.sampleAction(probs);
-
- return {
- action,
- logProb: Math.log(probs[action] + 1e-8),
- value: this.computeValue(state),
- };
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- bufferSize: this.buffer.length,
- avgLoss: this.updateCount > 0 ? this.totalLoss / this.updateCount : 0,
- approxKL: this.approxKL,
- clipFraction: this.clipFraction,
- };
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private computeValue(state: Float32Array): number {
- let value = 0;
- for (let i = 0; i < Math.min(state.length, this.valueWeights.length); i++) {
- value += state[i] * this.valueWeights[i];
- }
- return value;
- }
-
- private computeLogits(state: Float32Array): Float32Array {
- // Simplified: 4 discrete actions
- const numActions = 4;
- const logits = new Float32Array(numActions);
-
- for (let a = 0; a < numActions; a++) {
- for (let i = 0; i < Math.min(state.length, this.policyWeights.length); i++) {
- logits[a] += state[i] * this.policyWeights[i] * (1 + a * 0.1);
- }
- }
-
- return logits;
- }
-
- private computeLogProb(state: Float32Array, action: string): number {
- const logits = this.computeLogits(state);
- const probs = this.softmax(logits);
- const actionIdx = this.hashAction(action);
- return Math.log(probs[actionIdx] + 1e-8);
- }
-
- private hashAction(action: string): number {
- // Simple hash to action index (0-3)
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % 4;
- }
- return hash;
- }
-
- private softmax(logits: Float32Array): Float32Array {
- const max = Math.max(...logits);
- const exps = new Float32Array(logits.length);
- let sum = 0;
-
- for (let i = 0; i < logits.length; i++) {
- exps[i] = Math.exp(logits[i] - max);
- sum += exps[i];
- }
-
- for (let i = 0; i < exps.length; i++) {
- exps[i] /= sum;
- }
-
- return exps;
- }
-
- private sampleAction(probs: Float32Array): number {
- const r = Math.random();
- let cumSum = 0;
- for (let i = 0; i < probs.length; i++) {
- cumSum += probs[i];
- if (r < cumSum) return i;
- }
- return probs.length - 1;
- }
-
- private computeGAE(rewards: number[], values: number[]): number[] {
- const advantages = new Array(rewards.length).fill(0);
- let lastGae = 0;
-
- for (let t = rewards.length - 1; t >= 0; t--) {
- const nextValue = t < rewards.length - 1 ? values[t + 1] : 0;
- const delta = rewards[t] + this.config.gamma * nextValue - values[t];
- lastGae = delta + this.config.gamma * this.config.gaeLambda * lastGae;
- advantages[t] = lastGae;
- }
-
- return advantages;
- }
-
- private computeReturns(rewards: number[]): number[] {
- const returns = new Array(rewards.length).fill(0);
- let cumReturn = 0;
-
- for (let t = rewards.length - 1; t >= 0; t--) {
- cumReturn = rewards[t] + this.config.gamma * cumReturn;
- returns[t] = cumReturn;
- }
-
- return returns;
- }
-
- private shuffleBuffer(): void {
- for (let i = this.buffer.length - 1; i > 0; i--) {
- const j = Math.floor(Math.random() * (i + 1));
- [this.buffer[i], this.buffer[j]] = [this.buffer[j], this.buffer[i]];
- }
- }
-
- private updateMiniBatch(batch: PPOExperience[]): {
- policyLoss: number;
- valueLoss: number;
- entropy: number;
- clipFrac: number;
- kl: number;
- } {
- let policyLoss = 0;
- let valueLoss = 0;
- let entropy = 0;
- let clipFrac = 0;
- let kl = 0;
-
- const policyGrad = new Float32Array(this.policyWeights.length);
- const valueGrad = new Float32Array(this.valueWeights.length);
-
- for (const exp of batch) {
- // Current policy
- const logits = this.computeLogits(exp.state);
- const probs = this.softmax(logits);
- const newLogProb = Math.log(probs[exp.action] + 1e-8);
- const currentValue = this.computeValue(exp.state);
-
- // Ratio for PPO
- const ratio = Math.exp(newLogProb - exp.logProb);
-
- // Clipped surrogate objective
- const surr1 = ratio * exp.advantage;
- const surr2 = Math.max(
- Math.min(ratio, 1 + this.config.clipRange),
- 1 - this.config.clipRange
- ) * exp.advantage;
-
- const policyLossI = -Math.min(surr1, surr2);
- policyLoss += policyLossI;
-
- // Track clipping
- if (Math.abs(ratio - 1) > this.config.clipRange) {
- clipFrac++;
- }
-
- // KL divergence approximation
- kl += (exp.logProb - newLogProb);
-
- // Value loss
- let valueLossI: number;
- if (this.config.clipRangeVf !== null) {
- const valuePred = currentValue;
- const valueClipped = exp.value + Math.max(
- Math.min(valuePred - exp.value, this.config.clipRangeVf),
- -this.config.clipRangeVf
- );
- const vf1 = (valuePred - exp.return_) ** 2;
- const vf2 = (valueClipped - exp.return_) ** 2;
- valueLossI = Math.max(vf1, vf2);
- } else {
- valueLossI = (currentValue - exp.return_) ** 2;
- }
- valueLoss += valueLossI;
-
- // Entropy
- let entropyI = 0;
- for (const p of probs) {
- if (p > 0) entropyI -= p * Math.log(p);
- }
- entropy += entropyI;
-
- // Compute gradients (simplified)
- for (let i = 0; i < Math.min(exp.state.length, policyGrad.length); i++) {
- policyGrad[i] += exp.state[i] * policyLossI * 0.01;
- valueGrad[i] += exp.state[i] * valueLossI * 0.01;
- }
- }
-
- // Apply gradients with momentum
- const lr = this.config.learningRate;
- const beta = 0.9;
-
- for (let i = 0; i < this.policyWeights.length; i++) {
- this.policyMomentum[i] = beta * this.policyMomentum[i] + (1 - beta) * policyGrad[i];
- this.policyWeights[i] -= lr * this.policyMomentum[i];
-
- this.valueMomentum[i] = beta * this.valueMomentum[i] + (1 - beta) * valueGrad[i];
- this.valueWeights[i] -= lr * this.valueMomentum[i];
- }
-
- return {
- policyLoss: policyLoss / batch.length,
- valueLoss: valueLoss / batch.length,
- entropy: entropy / batch.length,
- clipFrac: clipFrac / batch.length,
- kl: kl / batch.length,
- };
- }
-}
-
-/**
- * Factory function
- */
-export function createPPO(config?: Partial<PPOConfig>): PPOAlgorithm {
- return new PPOAlgorithm(config);
-}
diff --git a/v3/neural/algorithms/q-learning.ts b/v3/neural/algorithms/q-learning.ts
deleted file mode 100644
index 956dc22a67..0000000000
--- a/v3/neural/algorithms/q-learning.ts
+++ /dev/null
@@ -1,333 +0,0 @@
-/**
- * Tabular Q-Learning
- *
- * Classic Q-learning algorithm with:
- * - Epsilon-greedy exploration
- * - State hashing for continuous states
- * - Eligibility traces (optional)
- * - Experience replay
- *
- * Suitable for smaller state spaces or discretized environments.
- * Performance Target: <1ms per update
- */
-
-import type { Trajectory, RLConfig } from '../types.js';
-
-/**
- * Q-Learning configuration
- */
-export interface QLearningConfig extends RLConfig {
- algorithm: 'q-learning';
- explorationInitial: number;
- explorationFinal: number;
- explorationDecay: number;
- maxStates: number;
- useEligibilityTraces: boolean;
- traceDecay: number;
-}
-
-/**
- * Default Q-Learning configuration
- */
-export const DEFAULT_QLEARNING_CONFIG: QLearningConfig = {
- algorithm: 'q-learning',
- learningRate: 0.1,
- gamma: 0.99,
- entropyCoef: 0,
- valueLossCoef: 1,
- maxGradNorm: 1,
- epochs: 1,
- miniBatchSize: 1,
- explorationInitial: 1.0,
- explorationFinal: 0.01,
- explorationDecay: 10000,
- maxStates: 10000,
- useEligibilityTraces: false,
- traceDecay: 0.9,
-};
-
-/**
- * Q-table entry
- */
-interface QEntry {
- qValues: Float32Array;
- visits: number;
- lastUpdate: number;
-}
-
-/**
- * Q-Learning Algorithm Implementation
- */
-export class QLearning {
- private config: QLearningConfig;
-
- // Q-table
- private qTable: Map<string, QEntry> = new Map();
-
- // Exploration
- private epsilon: number;
- private stepCount = 0;
-
- // Number of actions
- private numActions = 4;
-
- // Eligibility traces
- private traces: Map<string, Float32Array> = new Map();
-
- // Statistics
- private updateCount = 0;
- private avgTDError = 0;
-
- constructor(config: Partial<QLearningConfig> = {}) {
- this.config = { ...DEFAULT_QLEARNING_CONFIG, ...config };
- this.epsilon = this.config.explorationInitial;
- }
-
- /**
- * Update Q-values from trajectory
- */
- update(trajectory: Trajectory): { tdError: number } {
- const startTime = performance.now();
-
- if (trajectory.steps.length === 0) {
- return { tdError: 0 };
- }
-
- let totalTDError = 0;
-
- // Reset eligibility traces for new trajectory
- if (this.config.useEligibilityTraces) {
- this.traces.clear();
- }
-
- for (let i = 0; i < trajectory.steps.length; i++) {
- const step = trajectory.steps[i];
- const stateKey = this.hashState(step.stateBefore);
- const action = this.hashAction(step.action);
-
- // Get or create Q-entry
- const qEntry = this.getOrCreateEntry(stateKey);
-
- // Current Q-value
- const currentQ = qEntry.qValues[action];
-
- // Compute target Q-value
- let targetQ: number;
- if (i === trajectory.steps.length - 1) {
- // Terminal state
- targetQ = step.reward;
- } else {
- const nextStateKey = this.hashState(step.stateAfter);
- const nextEntry = this.getOrCreateEntry(nextStateKey);
- const maxNextQ = Math.max(...nextEntry.qValues);
- targetQ = step.reward + this.config.gamma * maxNextQ;
- }
-
- // TD error
- const tdError = targetQ - currentQ;
- totalTDError += Math.abs(tdError);
-
- if (this.config.useEligibilityTraces) {
- // Update eligibility trace
- this.updateTrace(stateKey, action);
-
- // Update all states with traces
- this.updateWithTraces(tdError);
- } else {
- // Simple Q-learning update
- qEntry.qValues[action] += this.config.learningRate * tdError;
- qEntry.visits++;
- qEntry.lastUpdate = Date.now();
- }
- }
-
- // Decay exploration
- this.stepCount += trajectory.steps.length;
- this.epsilon = Math.max(
- this.config.explorationFinal,
- this.config.explorationInitial - this.stepCount / this.config.explorationDecay
- );
-
- // Prune Q-table if too large
- if (this.qTable.size > this.config.maxStates) {
- this.pruneQTable();
- }
-
- this.updateCount++;
- this.avgTDError = totalTDError / trajectory.steps.length;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 1) {
- console.warn(`Q-learning update exceeded target: ${elapsed.toFixed(2)}ms > 1ms`);
- }
-
- return { tdError: this.avgTDError };
- }
-
- /**
- * Get action using epsilon-greedy policy
- */
- getAction(state: Float32Array, explore: boolean = true): number {
- if (explore && Math.random() < this.epsilon) {
- return Math.floor(Math.random() * this.numActions);
- }
-
- const stateKey = this.hashState(state);
- const entry = this.qTable.get(stateKey);
-
- if (!entry) {
- return Math.floor(Math.random() * this.numActions);
- }
-
- return this.argmax(entry.qValues);
- }
-
- /**
- * Get Q-values for a state
- */
- getQValues(state: Float32Array): Float32Array {
- const stateKey = this.hashState(state);
- const entry = this.qTable.get(stateKey);
-
- if (!entry) {
- return new Float32Array(this.numActions);
- }
-
- return new Float32Array(entry.qValues);
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- qTableSize: this.qTable.size,
- epsilon: this.epsilon,
- avgTDError: this.avgTDError,
- stepCount: this.stepCount,
- };
- }
-
- /**
- * Reset Q-table
- */
- reset(): void {
- this.qTable.clear();
- this.traces.clear();
- this.epsilon = this.config.explorationInitial;
- this.stepCount = 0;
- this.updateCount = 0;
- this.avgTDError = 0;
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private hashState(state: Float32Array): string {
- // Discretize state by binning values
- const bins = 10;
- const parts: number[] = [];
-
- // Use first 8 dimensions for hashing
- for (let i = 0; i < Math.min(8, state.length); i++) {
- const normalized = (state[i] + 1) / 2; // Assume [-1, 1] range
- const bin = Math.floor(Math.max(0, Math.min(bins - 1, normalized * bins)));
- parts.push(bin);
- }
-
- return parts.join(',');
- }
-
- private hashAction(action: string): number {
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % this.numActions;
- }
- return hash;
- }
-
- private getOrCreateEntry(stateKey: string): QEntry {
- let entry = this.qTable.get(stateKey);
-
- if (!entry) {
- entry = {
- qValues: new Float32Array(this.numActions),
- visits: 0,
- lastUpdate: Date.now(),
- };
- this.qTable.set(stateKey, entry);
- }
-
- return entry;
- }
-
- private updateTrace(stateKey: string, action: number): void {
- // Decay all existing traces
- for (const [key, trace] of this.traces) {
- for (let a = 0; a < this.numActions; a++) {
- trace[a] *= this.config.gamma * this.config.traceDecay;
- }
-
- // Remove near-zero traces
- const maxTrace = Math.max(...trace);
- if (maxTrace < 0.001) {
- this.traces.delete(key);
- }
- }
-
- // Set trace for current state-action
- let trace = this.traces.get(stateKey);
- if (!trace) {
- trace = new Float32Array(this.numActions);
- this.traces.set(stateKey, trace);
- }
- trace[action] = 1.0;
- }
-
- private updateWithTraces(tdError: number): void {
- const lr = this.config.learningRate;
-
- for (const [stateKey, trace] of this.traces) {
- const entry = this.qTable.get(stateKey);
- if (entry) {
- for (let a = 0; a < this.numActions; a++) {
- entry.qValues[a] += lr * tdError * trace[a];
- }
- entry.visits++;
- entry.lastUpdate = Date.now();
- }
- }
- }
-
- private pruneQTable(): void {
- // Remove least recently used states
- const entries = Array.from(this.qTable.entries())
- .sort((a, b) => a[1].lastUpdate - b[1].lastUpdate);
-
- const toRemove = entries.length - Math.floor(this.config.maxStates * 0.8);
- for (let i = 0; i < toRemove; i++) {
- this.qTable.delete(entries[i][0]);
- }
- }
-
- private argmax(values: Float32Array): number {
- let maxIdx = 0;
- let maxVal = values[0];
- for (let i = 1; i < values.length; i++) {
- if (values[i] > maxVal) {
- maxVal = values[i];
- maxIdx = i;
- }
- }
- return maxIdx;
- }
-}
-
-/**
- * Factory function
- */
-export function createQLearning(config?: Partial<QLearningConfig>): QLearning {
- return new QLearning(config);
-}
diff --git a/v3/neural/algorithms/sarsa.ts b/v3/neural/algorithms/sarsa.ts
deleted file mode 100644
index 19e4f16b2f..0000000000
--- a/v3/neural/algorithms/sarsa.ts
+++ /dev/null
@@ -1,383 +0,0 @@
-/**
- * SARSA (State-Action-Reward-State-Action)
- *
- * On-policy TD learning algorithm with:
- * - Epsilon-greedy exploration
- * - State hashing for continuous states
- * - Expected SARSA variant (optional)
- * - Eligibility traces (SARSA-lambda)
- *
- * Performance Target: <1ms per update
- */
-
-import type { Trajectory, RLConfig } from '../types.js';
-
-/**
- * SARSA configuration
- */
-export interface SARSAConfig extends RLConfig {
- algorithm: 'sarsa';
- explorationInitial: number;
- explorationFinal: number;
- explorationDecay: number;
- maxStates: number;
- useExpectedSARSA: boolean;
- useEligibilityTraces: boolean;
- traceDecay: number;
-}
-
-/**
- * Default SARSA configuration
- */
-export const DEFAULT_SARSA_CONFIG: SARSAConfig = {
- algorithm: 'sarsa',
- learningRate: 0.1,
- gamma: 0.99,
- entropyCoef: 0,
- valueLossCoef: 1,
- maxGradNorm: 1,
- epochs: 1,
- miniBatchSize: 1,
- explorationInitial: 1.0,
- explorationFinal: 0.01,
- explorationDecay: 10000,
- maxStates: 10000,
- useExpectedSARSA: false,
- useEligibilityTraces: false,
- traceDecay: 0.9,
-};
-
-/**
- * Q-table entry
- */
-interface SARSAEntry {
- qValues: Float32Array;
- visits: number;
- lastUpdate: number;
-}
-
-/**
- * SARSA Algorithm Implementation
- */
-export class SARSAAlgorithm {
- private config: SARSAConfig;
-
- // Q-table
- private qTable: Map<string, SARSAEntry> = new Map();
-
- // Exploration
- private epsilon: number;
- private stepCount = 0;
-
- // Number of actions
- private numActions = 4;
-
- // Eligibility traces
- private traces: Map<string, Float32Array> = new Map();
-
- // Statistics
- private updateCount = 0;
- private avgTDError = 0;
-
- constructor(config: Partial<SARSAConfig> = {}) {
- this.config = { ...DEFAULT_SARSA_CONFIG, ...config };
- this.epsilon = this.config.explorationInitial;
- }
-
- /**
- * Update Q-values from trajectory using SARSA
- */
- update(trajectory: Trajectory): { tdError: number } {
- const startTime = performance.now();
-
- if (trajectory.steps.length < 2) {
- return { tdError: 0 };
- }
-
- let totalTDError = 0;
-
- // Reset eligibility traces
- if (this.config.useEligibilityTraces) {
- this.traces.clear();
- }
-
- for (let i = 0; i < trajectory.steps.length - 1; i++) {
- const step = trajectory.steps[i];
- const nextStep = trajectory.steps[i + 1];
-
- const stateKey = this.hashState(step.stateBefore);
- const action = this.hashAction(step.action);
- const nextStateKey = this.hashState(step.stateAfter);
- const nextAction = this.hashAction(nextStep.action);
-
- // Get or create entries
- const qEntry = this.getOrCreateEntry(stateKey);
- const nextEntry = this.getOrCreateEntry(nextStateKey);
-
- // Current Q-value
- const currentQ = qEntry.qValues[action];
-
- // Compute target Q-value using SARSA update rule
- let targetQ: number;
-
- if (this.config.useExpectedSARSA) {
- // Expected SARSA: use expected value under current policy
- targetQ = step.reward + this.config.gamma * this.expectedValue(nextEntry.qValues);
- } else {
- // Standard SARSA: use actual next action
- targetQ = step.reward + this.config.gamma * nextEntry.qValues[nextAction];
- }
-
- // TD error
- const tdError = targetQ - currentQ;
- totalTDError += Math.abs(tdError);
-
- if (this.config.useEligibilityTraces) {
- this.updateTrace(stateKey, action);
- this.updateWithTraces(tdError);
- } else {
- qEntry.qValues[action] += this.config.learningRate * tdError;
- qEntry.visits++;
- qEntry.lastUpdate = Date.now();
- }
- }
-
- // Handle terminal state
- const lastStep = trajectory.steps[trajectory.steps.length - 1];
- const lastStateKey = this.hashState(lastStep.stateBefore);
- const lastAction = this.hashAction(lastStep.action);
- const lastEntry = this.getOrCreateEntry(lastStateKey);
-
- const terminalTDError = lastStep.reward - lastEntry.qValues[lastAction];
- lastEntry.qValues[lastAction] += this.config.learningRate * terminalTDError;
- totalTDError += Math.abs(terminalTDError);
-
- // Decay exploration
- this.stepCount += trajectory.steps.length;
- this.epsilon = Math.max(
- this.config.explorationFinal,
- this.config.explorationInitial - this.stepCount / this.config.explorationDecay
- );
-
- // Prune if needed
- if (this.qTable.size > this.config.maxStates) {
- this.pruneQTable();
- }
-
- this.updateCount++;
- this.avgTDError = totalTDError / trajectory.steps.length;
-
- const elapsed = performance.now() - startTime;
- if (elapsed > 1) {
- console.warn(`SARSA update exceeded target: ${elapsed.toFixed(2)}ms > 1ms`);
- }
-
- return { tdError: this.avgTDError };
- }
-
- /**
- * Get action using epsilon-greedy policy
- */
- getAction(state: Float32Array, explore: boolean = true): number {
- if (explore && Math.random() < this.epsilon) {
- return Math.floor(Math.random() * this.numActions);
- }
-
- const stateKey = this.hashState(state);
- const entry = this.qTable.get(stateKey);
-
- if (!entry) {
- return Math.floor(Math.random() * this.numActions);
- }
-
- return this.argmax(entry.qValues);
- }
-
- /**
- * Get action probabilities for a state
- */
- getActionProbabilities(state: Float32Array): Float32Array {
- const probs = new Float32Array(this.numActions);
- const stateKey = this.hashState(state);
- const entry = this.qTable.get(stateKey);
-
- if (!entry) {
- // Uniform distribution
- const uniform = 1 / this.numActions;
- for (let a = 0; a < this.numActions; a++) {
- probs[a] = uniform;
- }
- return probs;
- }
-
- // Epsilon-greedy probabilities
- const greedyAction = this.argmax(entry.qValues);
- const exploreProb = this.epsilon / this.numActions;
-
- for (let a = 0; a < this.numActions; a++) {
- probs[a] = exploreProb;
- }
- probs[greedyAction] += 1 - this.epsilon;
-
- return probs;
- }
-
- /**
- * Get Q-values for a state
- */
- getQValues(state: Float32Array): Float32Array {
- const stateKey = this.hashState(state);
- const entry = this.qTable.get(stateKey);
-
- if (!entry) {
- return new Float32Array(this.numActions);
- }
-
- return new Float32Array(entry.qValues);
- }
-
- /**
- * Get statistics
- */
- getStats(): Record<string, number> {
- return {
- updateCount: this.updateCount,
- qTableSize: this.qTable.size,
- epsilon: this.epsilon,
- avgTDError: this.avgTDError,
- stepCount: this.stepCount,
- };
- }
-
- /**
- * Reset algorithm state
- */
- reset(): void {
- this.qTable.clear();
- this.traces.clear();
- this.epsilon = this.config.explorationInitial;
- this.stepCount = 0;
- this.updateCount = 0;
- this.avgTDError = 0;
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private hashState(state: Float32Array): string {
- const bins = 10;
- const parts: number[] = [];
-
- for (let i = 0; i < Math.min(8, state.length); i++) {
- const normalized = (state[i] + 1) / 2;
- const bin = Math.floor(Math.max(0, Math.min(bins - 1, normalized * bins)));
- parts.push(bin);
- }
-
- return parts.join(',');
- }
-
- private hashAction(action: string): number {
- let hash = 0;
- for (let i = 0; i < action.length; i++) {
- hash = (hash * 31 + action.charCodeAt(i)) % this.numActions;
- }
- return hash;
- }
-
- private getOrCreateEntry(stateKey: string): SARSAEntry {
- let entry = this.qTable.get(stateKey);
-
- if (!entry) {
- entry = {
- qValues: new Float32Array(this.numActions),
- visits: 0,
- lastUpdate: Date.now(),
- };
- this.qTable.set(stateKey, entry);
- }
-
- return entry;
- }
-
- private expectedValue(qValues: Float32Array): number {
- // Expected value under epsilon-greedy policy
- const greedyAction = this.argmax(qValues);
- const exploreProb = this.epsilon / this.numActions;
-
- let expected = 0;
- for (let a = 0; a < this.numActions; a++) {
- const prob = exploreProb + (a === greedyAction ? 1 - this.epsilon : 0);
- expected += prob * qValues[a];
- }
-
- return expected;
- }
-
- private updateTrace(stateKey: string, action: number): void {
- // Decay all traces
- for (const [key, trace] of this.traces) {
- for (let a = 0; a < this.numActions; a++) {
- trace[a] *= this.config.gamma * this.config.traceDecay;
- }
-
- const maxTrace = Math.max(...trace);
- if (maxTrace < 0.001) {
- this.traces.delete(key);
- }
- }
-
- // Set current trace (replacing traces for same state-action)
- let trace = this.traces.get(stateKey);
- if (!trace) {
- trace = new Float32Array(this.numActions);
- this.traces.set(stateKey, trace);
- }
- trace[action] = 1.0;
- }
-
- private updateWithTraces(tdError: number): void {
- const lr = this.config.learningRate;
-
- for (const [stateKey, trace] of this.traces) {
- const entry = this.qTable.get(stateKey);
- if (entry) {
- for (let a = 0; a < this.numActions; a++) {
- entry.qValues[a] += lr * tdError * trace[a];
- }
- entry.visits++;
- entry.lastUpdate = Date.now();
- }
- }
- }
-
- private pruneQTable(): void {
- const entries = Array.from(this.qTable.entries())
- .sort((a, b) => a[1].lastUpdate - b[1].lastUpdate);
-
- const toRemove = entries.length - Math.floor(this.config.maxStates * 0.8);
- for (let i = 0; i < toRemove; i++) {
- this.qTable.delete(entries[i][0]);
- }
- }
-
- private argmax(values: Float32Array): number {
- let maxIdx = 0;
- let maxVal = values[0];
- for (let i = 1; i < values.length; i++) {
- if (values[i] > maxVal) {
- maxVal = values[i];
- maxIdx = i;
- }
- }
- return maxIdx;
- }
-}
-
-/**
- * Factory function
- */
-export function createSARSA(config?: Partial<SARSAConfig>): SARSAAlgorithm {
- return new SARSAAlgorithm(config);
-}
diff --git a/v3/neural/index.ts b/v3/neural/index.ts
deleted file mode 100644
index 1984db3b2d..0000000000
--- a/v3/neural/index.ts
+++ /dev/null
@@ -1,342 +0,0 @@
-/**
- * V3 Neural/Learning System
- *
- * Complete neural learning module with SONA learning modes,
- * ReasoningBank integration, pattern learning, and RL algorithms.
- *
- * Performance Targets:
- * - SONA adaptation: <0.05ms
- * - Pattern matching: <1ms
- * - Learning step: <10ms
- *
- * @module @claude-flow/neural
- */
-
-// =============================================================================
-// Core Types
-// =============================================================================
-
-export type {
- // SONA Mode Types
- SONAMode,
- SONAModeConfig,
- ModeOptimizations,
-
- // Trajectory Types
- Trajectory,
- TrajectoryStep,
- TrajectoryVerdict,
- DistilledMemory,
-
- // Pattern Types
- Pattern,
- PatternMatch,
- PatternEvolution,
-
- // RL Algorithm Types
- RLAlgorithm,
- RLConfig,
- PPOConfig,
- DQNConfig,
- DecisionTransformerConfig,
- CuriosityConfig,
-
- // LoRA Types
- LoRAConfig,
- LoRAWeights,
-
- // EWC Types
- EWCConfig,
- EWCState,
-
- // Statistics
- NeuralStats,
-
- // Events
- NeuralEvent,
- NeuralEventListener,
-} from './types.js';
-
-// =============================================================================
-// SONA Manager
-// =============================================================================
-
-export {
- SONAManager,
- createSONAManager,
- getModeConfig,
- getModeOptimizations,
-} from './sona-manager.js';
-
-// =============================================================================
-// Learning Modes
-// =============================================================================
-
-export type { ModeImplementation } from './modes/index.js';
-
-export {
- BaseModeImplementation,
- RealTimeMode,
- BalancedMode,
- ResearchMode,
- EdgeMode,
- BatchMode,
-} from './modes/index.js';
-
-// =============================================================================
-// ReasoningBank
-// =============================================================================
-
-export {
- ReasoningBank,
- createReasoningBank,
-} from './reasoning-bank.js';
-
-export type {
- ReasoningBankConfig,
- RetrievalResult,
- ConsolidationResult,
-} from './reasoning-bank.js';
-
-// =============================================================================
-// Pattern Learner
-// =============================================================================
-
-export {
- PatternLearner,
- createPatternLearner,
-} from './pattern-learner.js';
-
-export type { PatternLearnerConfig } from './pattern-learner.js';
-
-// =============================================================================
-// RL Algorithms
-// =============================================================================
-
-export {
- // PPO
- PPOAlgorithm,
- createPPO,
- DEFAULT_PPO_CONFIG,
-
- // DQN
- DQNAlgorithm,
- createDQN,
- DEFAULT_DQN_CONFIG,
-
- // A2C
- A2CAlgorithm,
- createA2C,
- DEFAULT_A2C_CONFIG,
-
- // Decision Transformer
- DecisionTransformer,
- createDecisionTransformer,
- DEFAULT_DT_CONFIG,
-
- // Q-Learning
- QLearning,
- createQLearning,
- DEFAULT_QLEARNING_CONFIG,
-
- // SARSA
- SARSAAlgorithm,
- createSARSA,
- DEFAULT_SARSA_CONFIG,
-
- // Curiosity
- CuriosityModule,
- createCuriosity,
- DEFAULT_CURIOSITY_CONFIG,
-
- // Factory functions
- createAlgorithm,
- getDefaultConfig,
-} from './algorithms/index.js';
-
-export type {
- A2CConfig,
- QLearningConfig,
- SARSAConfig,
-} from './algorithms/index.js';
-
-// =============================================================================
-// Convenience Factory
-// =============================================================================
-
-import { SONAManager, createSONAManager } from './sona-manager.js';
-import { ReasoningBank, createReasoningBank } from './reasoning-bank.js';
-import { PatternLearner, createPatternLearner } from './pattern-learner.js';
-import type { SONAMode, NeuralEventListener } from './types.js';
-
-/**
- * Neural Learning System - Complete integrated learning module
- */
-export class NeuralLearningSystem {
- private sona: SONAManager;
- private reasoningBank: ReasoningBank;
- private patternLearner: PatternLearner;
- private initialized = false;
-
- constructor(mode: SONAMode = 'balanced') {
- this.sona = createSONAManager(mode);
- this.reasoningBank = createReasoningBank();
- this.patternLearner = createPatternLearner();
- }
-
- /**
- * Initialize the learning system
- */
- async initialize(): Promise<void> {
- if (this.initialized) return;
- await this.sona.initialize();
- this.initialized = true;
- }
-
- /**
- * Get SONA manager
- */
- getSONAManager(): SONAManager {
- return this.sona;
- }
-
- /**
- * Get ReasoningBank
- */
- getReasoningBank(): ReasoningBank {
- return this.reasoningBank;
- }
-
- /**
- * Get Pattern Learner
- */
- getPatternLearner(): PatternLearner {
- return this.patternLearner;
- }
-
- /**
- * Change learning mode
- */
- async setMode(mode: SONAMode): Promise<void> {
- await this.sona.setMode(mode);
- }
-
- /**
- * Begin tracking a task
- */
- beginTask(context: string, domain: 'code' | 'creative' | 'reasoning' | 'chat' | 'math' | 'general' = 'general'): string {
- return this.sona.beginTrajectory(context, domain);
- }
-
- /**
- * Record a step in the current task
- */
- recordStep(
- trajectoryId: string,
- action: string,
- reward: number,
- stateEmbedding: Float32Array
- ): void {
- this.sona.recordStep(trajectoryId, action, reward, stateEmbedding);
- }
-
- /**
- * Complete a task and trigger learning
- */
- async completeTask(trajectoryId: string, quality?: number): Promise<void> {
- const trajectory = this.sona.completeTrajectory(trajectoryId, quality);
-
- if (trajectory) {
- // Store in reasoning bank
- this.reasoningBank.storeTrajectory(trajectory);
-
- // Judge and potentially distill
- await this.reasoningBank.judge(trajectory);
- const memory = await this.reasoningBank.distill(trajectory);
-
- // Extract pattern if successful
- if (memory) {
- this.patternLearner.extractPattern(trajectory, memory);
- }
- }
- }
-
- /**
- * Find similar patterns for a task
- */
- async findPatterns(queryEmbedding: Float32Array, k: number = 3): Promise<import('./types.js').PatternMatch[]> {
- return this.patternLearner.findMatches(queryEmbedding, k);
- }
-
- /**
- * Retrieve relevant memories
- */
- async retrieveMemories(queryEmbedding: Float32Array, k: number = 3): Promise<import('./reasoning-bank.js').RetrievalResult[]> {
- return this.reasoningBank.retrieve(queryEmbedding, k);
- }
-
- /**
- * Trigger learning cycle
- */
- async triggerLearning(): Promise<void> {
- await this.sona.triggerLearning('manual');
- await this.reasoningBank.consolidate();
- }
-
- /**
- * Get comprehensive statistics
- */
- getStats(): {
- sona: import('./types.js').NeuralStats;
- reasoningBank: Record<string, number>;
- patternLearner: Record<string, number>;
- } {
- return {
- sona: this.sona.getStats(),
- reasoningBank: this.reasoningBank.getStats(),
- patternLearner: this.patternLearner.getStats(),
- };
- }
-
- /**
- * Add event listener
- */
- addEventListener(listener: NeuralEventListener): void {
- this.sona.addEventListener(listener);
- this.reasoningBank.addEventListener(listener);
- this.patternLearner.addEventListener(listener);
- }
-
- /**
- * Cleanup resources
- */
- async cleanup(): Promise<void> {
- await this.sona.cleanup();
- this.initialized = false;
- }
-}
-
-/**
- * Create a complete neural learning system
- */
-export function createNeuralLearningSystem(mode: SONAMode = 'balanced'): NeuralLearningSystem {
- return new NeuralLearningSystem(mode);
-}
-
-// =============================================================================
-// Default Export
-// =============================================================================
-
-export default {
- // Factories
- createSONAManager,
- createReasoningBank,
- createPatternLearner,
- createNeuralLearningSystem,
-
- // Classes
- SONAManager,
- ReasoningBank,
- PatternLearner,
- NeuralLearningSystem,
-};
diff --git a/v3/neural/modes/balanced.ts b/v3/neural/modes/balanced.ts
deleted file mode 100644
index 3938336845..0000000000
--- a/v3/neural/modes/balanced.ts
+++ /dev/null
@@ -1,299 +0,0 @@
-/**
- * Balanced Mode Implementation
- *
- * General-purpose mode with:
- * - +25% quality improvement
- * - 18ms overhead
- * - Rank-4 LoRA
- * - Pattern caching
- * - Standard learning pipeline
- */
-
-import type {
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- Pattern,
- PatternMatch,
- LoRAWeights,
- EWCState,
-} from '../types.js';
-import { BaseModeImplementation } from './index.js';
-
-/**
- * Balanced mode for general-purpose learning
- */
-export class BalancedMode extends BaseModeImplementation {
- readonly mode = 'balanced';
-
- // Pattern cache
- private patternCache: Map<string, PatternMatch[]> = new Map();
- private cacheHits = 0;
- private cacheMisses = 0;
-
- // Learning state
- private gradientAccumulator: Map<string, Float32Array> = new Map();
- private momentumBuffers: Map<string, Float32Array> = new Map();
-
- // Stats
- private totalPatternMatches = 0;
- private totalPatternTime = 0;
- private totalLearnTime = 0;
- private learnIterations = 0;
- private qualityImprovements: number[] = [];
-
- async initialize(): Promise<void> {
- await super.initialize();
- this.patternCache.clear();
- this.gradientAccumulator.clear();
- this.momentumBuffers.clear();
- }
-
- async cleanup(): Promise<void> {
- this.patternCache.clear();
- this.gradientAccumulator.clear();
- this.momentumBuffers.clear();
- await super.cleanup();
- }
-
- /**
- * Find patterns using similarity search with caching
- */
- async findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]> {
- const startTime = performance.now();
-
- // Check cache
- const cacheKey = this.computeCacheKey(embedding);
- const cached = this.patternCache.get(cacheKey);
-
- if (cached && cached.length >= k) {
- this.cacheHits++;
- this.totalPatternTime += performance.now() - startTime;
- this.totalPatternMatches++;
- return cached.slice(0, k);
- }
-
- this.cacheMisses++;
-
- // Compute similarities for all patterns
- const matches: PatternMatch[] = [];
-
- for (const pattern of patterns) {
- const similarity = this.cosineSimilarity(embedding, pattern.embedding);
- matches.push({
- pattern,
- similarity,
- confidence: similarity * pattern.successRate,
- latencyMs: 0,
- });
- }
-
- // Sort by similarity descending
- matches.sort((a, b) => b.similarity - a.similarity);
- const topK = matches.slice(0, k);
-
- // Cache result
- if (this.patternCache.size > 500) {
- const firstKey = this.patternCache.keys().next().value;
- if (firstKey) this.patternCache.delete(firstKey);
- }
- this.patternCache.set(cacheKey, topK);
-
- this.totalPatternTime += performance.now() - startTime;
- this.totalPatternMatches++;
-
- return topK;
- }
-
- /**
- * Learn from trajectories using standard gradient descent
- */
- async learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number> {
- const startTime = performance.now();
-
- if (trajectories.length === 0) return 0;
-
- const qualityThreshold = config.qualityThreshold;
- const learningRate = config.learningRate;
-
- // Separate positive and negative examples
- const goodTrajectories = trajectories.filter(t => t.qualityScore >= qualityThreshold);
- const badTrajectories = trajectories.filter(t => t.qualityScore < qualityThreshold);
-
- if (goodTrajectories.length === 0) return 0;
-
- // Compute gradients from trajectory pairs
- let totalGradientNorm = 0;
-
- for (const good of goodTrajectories) {
- // Use last step embedding as "goal state"
- if (good.steps.length === 0) continue;
-
- const goalState = good.steps[good.steps.length - 1].stateAfter;
-
- // Positive gradient: move toward good outcomes
- const posGradient = this.computeGradient(goalState, good.qualityScore);
- totalGradientNorm += this.accumulateGradient('positive', posGradient, learningRate);
-
- // Negative gradient: move away from bad outcomes (contrastive)
- for (const bad of badTrajectories.slice(0, 3)) {
- if (bad.steps.length === 0) continue;
- const badState = bad.steps[bad.steps.length - 1].stateAfter;
- const negGradient = this.computeGradient(badState, -bad.qualityScore);
- totalGradientNorm += this.accumulateGradient('negative', negGradient, learningRate * 0.5);
- }
- }
-
- // Apply EWC regularization
- const ewcPenalty = this.computeEWCPenalty(ewcState, config.ewcLambda);
- totalGradientNorm += ewcPenalty;
-
- // Compute improvement delta
- const avgGoodQuality = goodTrajectories.reduce((s, t) => s + t.qualityScore, 0) / goodTrajectories.length;
- const baselineQuality = 0.5;
- const improvementDelta = avgGoodQuality - baselineQuality;
-
- this.qualityImprovements.push(improvementDelta);
- if (this.qualityImprovements.length > 100) {
- this.qualityImprovements = this.qualityImprovements.slice(-100);
- }
-
- this.totalLearnTime += performance.now() - startTime;
- this.learnIterations++;
-
- return Math.max(0, improvementDelta);
- }
-
- /**
- * Apply LoRA adaptations with rank-4
- */
- async applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array> {
- if (!weights) {
- return input;
- }
-
- const output = new Float32Array(input.length);
- output.set(input);
-
- const rank = this.config.loraRank;
-
- // Apply to all target modules
- for (const module of ['q_proj', 'v_proj', 'k_proj', 'o_proj']) {
- const A = weights.A.get(module);
- const B = weights.B.get(module);
-
- if (A && B) {
- const adapted = this.applyLoRATransform(input, A, B, rank);
- const alpha = 0.2; // Moderate blending
- for (let i = 0; i < output.length; i++) {
- output[i] = output[i] * (1 - alpha) + adapted[i] * alpha;
- }
- }
- }
-
- return output;
- }
-
- getStats(): Record<string, number> {
- const avgImprovement = this.qualityImprovements.length > 0
- ? this.qualityImprovements.reduce((a, b) => a + b, 0) / this.qualityImprovements.length
- : 0;
-
- return {
- cacheHitRate: this.cacheHits + this.cacheMisses > 0
- ? this.cacheHits / (this.cacheHits + this.cacheMisses)
- : 0,
- avgPatternMatchMs: this.totalPatternMatches > 0
- ? this.totalPatternTime / this.totalPatternMatches
- : 0,
- avgLearnMs: this.learnIterations > 0
- ? this.totalLearnTime / this.learnIterations
- : 0,
- avgImprovement,
- patternCacheSize: this.patternCache.size,
- learnIterations: this.learnIterations,
- };
- }
-
- /**
- * Compute cache key from embedding
- */
- private computeCacheKey(embedding: Float32Array): string {
- const keyParts: string[] = [];
- for (let i = 0; i < Math.min(16, embedding.length); i++) {
- keyParts.push(embedding[i].toFixed(2));
- }
- return keyParts.join(',');
- }
-
- /**
- * Compute gradient from state and reward
- */
- private computeGradient(state: Float32Array, reward: number): Float32Array {
- const gradient = new Float32Array(state.length);
- for (let i = 0; i < state.length; i++) {
- gradient[i] = state[i] * reward;
- }
- return gradient;
- }
-
- /**
- * Accumulate gradient with momentum
- */
- private accumulateGradient(key: string, gradient: Float32Array, lr: number): number {
- let momentum = this.momentumBuffers.get(key);
- if (!momentum) {
- momentum = new Float32Array(gradient.length);
- this.momentumBuffers.set(key, momentum);
- }
-
- let accumulator = this.gradientAccumulator.get(key);
- if (!accumulator) {
- accumulator = new Float32Array(gradient.length);
- this.gradientAccumulator.set(key, accumulator);
- }
-
- const beta = 0.9; // Momentum coefficient
- let norm = 0;
-
- for (let i = 0; i < gradient.length; i++) {
- momentum[i] = beta * momentum[i] + (1 - beta) * gradient[i];
- accumulator[i] += lr * momentum[i];
- norm += momentum[i] * momentum[i];
- }
-
- return Math.sqrt(norm);
- }
-
- /**
- * Compute EWC penalty for continual learning
- */
- private computeEWCPenalty(ewcState: EWCState, lambda: number): number {
- let penalty = 0;
-
- for (const [key, fisher] of ewcState.fisher) {
- const means = ewcState.means.get(key);
- const current = this.gradientAccumulator.get(key);
-
- if (means && current) {
- for (let i = 0; i < Math.min(fisher.length, means.length, current.length); i++) {
- const diff = current[i] - means[i];
- penalty += fisher[i] * diff * diff;
- }
- }
- }
-
- return lambda * penalty * 0.5;
- }
-}
diff --git a/v3/neural/modes/batch.ts b/v3/neural/modes/batch.ts
deleted file mode 100644
index 4291c5d10b..0000000000
--- a/v3/neural/modes/batch.ts
+++ /dev/null
@@ -1,434 +0,0 @@
-/**
- * Batch Mode Implementation
- *
- * Optimized for high-throughput processing with:
- * - Large batch sizes (128)
- * - Rank-8 LoRA
- * - Gradient accumulation
- * - Async batch processing
- * - 50ms latency budget
- */
-
-import type {
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- Pattern,
- PatternMatch,
- LoRAWeights,
- EWCState,
-} from '../types.js';
-import { BaseModeImplementation } from './index.js';
-
-/**
- * Batch mode for high-throughput processing
- */
-export class BatchMode extends BaseModeImplementation {
- readonly mode = 'batch';
-
- // Batch processing queues
- private patternQueue: Array<{
- embedding: Float32Array;
- k: number;
- resolve: (matches: PatternMatch[]) => void;
- }> = [];
- private learningQueue: Trajectory[] = [];
-
- // Batch buffers
- private embeddingBuffer: Float32Array | null = null;
- private batchEmbeddings: Float32Array[] = [];
-
- // Gradient accumulation
- private accumulatedGradients: Map<string, Float32Array> = new Map();
- private gradientSteps = 0;
-
- // Batch processing state
- private isBatchProcessing = false;
- private batchTimer: ReturnType<typeof setTimeout> | null = null;
-
- // Stats
- private totalBatches = 0;
- private totalItems = 0;
- private totalBatchTime = 0;
- private learnIterations = 0;
-
- async initialize(): Promise<void> {
- await super.initialize();
- this.patternQueue = [];
- this.learningQueue = [];
- this.accumulatedGradients.clear();
- this.gradientSteps = 0;
- }
-
- async cleanup(): Promise<void> {
- if (this.batchTimer) {
- clearTimeout(this.batchTimer);
- }
- this.patternQueue = [];
- this.learningQueue = [];
- this.accumulatedGradients.clear();
- await super.cleanup();
- }
-
- /**
- * Find patterns - queues for batch processing
- */
- async findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]> {
- // For immediate needs, process synchronously
- if (patterns.length < 100) {
- return this.findPatternsDirect(embedding, k, patterns);
- }
-
- // Queue for batch processing
- return new Promise(resolve => {
- this.patternQueue.push({ embedding, k, resolve });
- this.scheduleBatchProcessing(patterns);
- });
- }
-
- /**
- * Learn from trajectories - accumulates for batch
- */
- async learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number> {
- const startTime = performance.now();
-
- if (trajectories.length === 0) return 0;
-
- // Add to learning queue
- this.learningQueue.push(...trajectories);
-
- // Process when queue is full
- if (this.learningQueue.length >= config.batchSize) {
- return this.processBatchLearning(config, ewcState);
- }
-
- // Return estimated improvement
- const avgQuality = trajectories.reduce((s, t) => s + t.qualityScore, 0) / trajectories.length;
-
- this.totalBatchTime += performance.now() - startTime;
- return Math.max(0, avgQuality - 0.5) * 0.5; // Partial estimate
- }
-
- /**
- * Apply LoRA with rank-8
- */
- async applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array> {
- if (!weights) {
- return input;
- }
-
- // Batch mode can process multiple inputs efficiently
- this.batchEmbeddings.push(new Float32Array(input));
-
- // Process immediately for single requests
- if (this.batchEmbeddings.length === 1) {
- const output = await this.applyLoRADirect(input, weights);
- this.batchEmbeddings = [];
- return output;
- }
-
- // For multiple inputs, process as batch
- const outputs = await this.applyLoRABatch(this.batchEmbeddings, weights);
- this.batchEmbeddings = [];
- return outputs[outputs.length - 1];
- }
-
- getStats(): Record<string, number> {
- return {
- totalBatches: this.totalBatches,
- avgItemsPerBatch: this.totalBatches > 0 ? this.totalItems / this.totalBatches : 0,
- avgBatchTimeMs: this.totalBatches > 0 ? this.totalBatchTime / this.totalBatches : 0,
- pendingPatternRequests: this.patternQueue.length,
- pendingTrajectories: this.learningQueue.length,
- accumulatedGradientSteps: this.gradientSteps,
- learnIterations: this.learnIterations,
- };
- }
-
- // ========================================================================
- // Direct processing (for small batches)
- // ========================================================================
-
- /**
- * Direct pattern matching without batching
- */
- private findPatternsDirect(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): PatternMatch[] {
- const matches: PatternMatch[] = [];
-
- for (const pattern of patterns) {
- const similarity = this.cosineSimilarity(embedding, pattern.embedding);
- matches.push({
- pattern,
- similarity,
- confidence: similarity * pattern.successRate,
- latencyMs: 0,
- });
- }
-
- matches.sort((a, b) => b.similarity - a.similarity);
- return matches.slice(0, k);
- }
-
- /**
- * Direct LoRA application
- */
- private async applyLoRADirect(
- input: Float32Array,
- weights: LoRAWeights
- ): Promise<Float32Array> {
- const output = new Float32Array(input.length);
- output.set(input);
-
- const rank = this.config.loraRank;
-
- for (const module of ['q_proj', 'v_proj', 'k_proj', 'o_proj']) {
- const A = weights.A.get(module);
- const B = weights.B.get(module);
-
- if (A && B) {
- const adapted = this.applyLoRATransform(input, A, B, rank);
- const alpha = 0.25;
- for (let i = 0; i < output.length; i++) {
- output[i] = output[i] * (1 - alpha) + adapted[i] * alpha;
- }
- }
- }
-
- return output;
- }
-
- // ========================================================================
- // Batch processing
- // ========================================================================
-
- /**
- * Schedule batch processing
- */
- private scheduleBatchProcessing(patterns: Pattern[]): void {
- if (this.batchTimer) return;
-
- this.batchTimer = setTimeout(() => {
- this.processBatchPatterns(patterns);
- }, 10); // Wait 10ms to accumulate requests
- }
-
- /**
- * Process pattern requests in batch
- */
- private async processBatchPatterns(patterns: Pattern[]): Promise<void> {
- this.batchTimer = null;
- if (this.patternQueue.length === 0) return;
-
- const startTime = performance.now();
- this.isBatchProcessing = true;
-
- const batch = this.patternQueue;
- this.patternQueue = [];
-
- // Pre-compute pattern embeddings matrix
- const patternMatrix = patterns.map(p => p.embedding);
-
- // Process all queries in batch
- for (const request of batch) {
- const matches = this.batchSimilaritySearch(
- request.embedding,
- request.k,
- patterns,
- patternMatrix
- );
- request.resolve(matches);
- }
-
- this.totalBatches++;
- this.totalItems += batch.length;
- this.totalBatchTime += performance.now() - startTime;
- this.isBatchProcessing = false;
- }
-
- /**
- * Batch similarity search
- */
- private batchSimilaritySearch(
- query: Float32Array,
- k: number,
- patterns: Pattern[],
- patternMatrix: Float32Array[]
- ): PatternMatch[] {
- const similarities: Array<{ idx: number; sim: number }> = [];
-
- for (let i = 0; i < patternMatrix.length; i++) {
- const sim = this.cosineSimilarity(query, patternMatrix[i]);
- similarities.push({ idx: i, sim });
- }
-
- similarities.sort((a, b) => b.sim - a.sim);
- const topK = similarities.slice(0, k);
-
- return topK.map(s => ({
- pattern: patterns[s.idx],
- similarity: s.sim,
- confidence: s.sim * patterns[s.idx].successRate,
- latencyMs: 0,
- }));
- }
-
- /**
- * Process batch learning
- */
- private async processBatchLearning(
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number> {
- const startTime = performance.now();
-
- const batch = this.learningQueue.slice(0, config.batchSize);
- this.learningQueue = this.learningQueue.slice(config.batchSize);
-
- const qualityThreshold = config.qualityThreshold;
- const learningRate = config.learningRate;
-
- // Separate by quality
- const good = batch.filter(t => t.qualityScore >= qualityThreshold);
- const bad = batch.filter(t => t.qualityScore < qualityThreshold);
-
- if (good.length === 0) {
- this.totalBatchTime += performance.now() - startTime;
- return 0;
- }
-
- // Accumulate gradients
- for (const trajectory of good) {
- this.accumulateTrajectoryGradient(trajectory, learningRate);
- }
-
- // Contrastive learning from bad examples
- for (const trajectory of bad.slice(0, good.length)) {
- this.accumulateTrajectoryGradient(trajectory, -learningRate * 0.3);
- }
-
- this.gradientSteps++;
-
- // Apply accumulated gradients every N steps
- if (this.gradientSteps >= 4) {
- await this.applyAccumulatedGradients(ewcState, config.ewcLambda);
- this.gradientSteps = 0;
- }
-
- // Compute improvement
- const avgQuality = good.reduce((s, t) => s + t.qualityScore, 0) / good.length;
- const improvement = avgQuality - 0.5;
-
- this.learnIterations++;
- this.totalBatchTime += performance.now() - startTime;
-
- return Math.max(0, improvement);
- }
-
- /**
- * Accumulate gradient from trajectory
- */
- private accumulateTrajectoryGradient(
- trajectory: Trajectory,
- scale: number
- ): void {
- if (trajectory.steps.length === 0) return;
-
- const key = trajectory.domain;
- let gradient = this.accumulatedGradients.get(key);
-
- if (!gradient) {
- const dim = trajectory.steps[0].stateAfter.length;
- gradient = new Float32Array(dim);
- this.accumulatedGradients.set(key, gradient);
- }
-
- // Add trajectory contribution
- const weight = trajectory.qualityScore * scale;
- for (const step of trajectory.steps) {
- for (let i = 0; i < Math.min(gradient.length, step.stateAfter.length); i++) {
- gradient[i] += step.stateAfter[i] * weight * step.reward;
- }
- }
- }
-
- /**
- * Apply accumulated gradients with EWC
- */
- private async applyAccumulatedGradients(
- ewcState: EWCState,
- ewcLambda: number
- ): Promise<void> {
- for (const [key, gradient] of this.accumulatedGradients) {
- // Normalize gradient
- const norm = Math.sqrt(gradient.reduce((s, v) => s + v * v, 0));
- if (norm > 0) {
- for (let i = 0; i < gradient.length; i++) {
- gradient[i] /= norm;
- }
- }
-
- // Apply EWC penalty
- const fisher = ewcState.fisher.get(key);
- const means = ewcState.means.get(key);
-
- if (fisher && means) {
- for (let i = 0; i < gradient.length; i++) {
- const penalty = ewcLambda * fisher[i] * (gradient[i] - means[i]);
- gradient[i] -= penalty;
- }
- }
-
- // Clear gradient for next accumulation
- gradient.fill(0);
- }
- }
-
- /**
- * Apply LoRA to batch of inputs
- */
- private async applyLoRABatch(
- inputs: Float32Array[],
- weights: LoRAWeights
- ): Promise<Float32Array[]> {
- const outputs: Float32Array[] = [];
- const rank = this.config.loraRank;
-
- // Process all inputs together for cache efficiency
- for (const input of inputs) {
- const output = new Float32Array(input.length);
- output.set(input);
-
- for (const module of ['q_proj', 'v_proj', 'k_proj', 'o_proj']) {
- const A = weights.A.get(module);
- const B = weights.B.get(module);
-
- if (A && B) {
- const adapted = this.applyLoRATransform(input, A, B, rank);
- const alpha = 0.25;
- for (let i = 0; i < output.length; i++) {
- output[i] = output[i] * (1 - alpha) + adapted[i] * alpha;
- }
- }
- }
-
- outputs.push(output);
- }
-
- return outputs;
- }
-}
diff --git a/v3/neural/modes/edge.ts b/v3/neural/modes/edge.ts
deleted file mode 100644
index 8f6f59587b..0000000000
--- a/v3/neural/modes/edge.ts
+++ /dev/null
@@ -1,409 +0,0 @@
-/**
- * Edge Mode Implementation
- *
- * Optimized for resource-constrained environments with:
- * - <5MB memory footprint
- * - Minimal latency (<1ms)
- * - Micro-LoRA (rank-1)
- * - Aggressive pruning
- * - Async updates
- */
-
-import type {
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- Pattern,
- PatternMatch,
- LoRAWeights,
- EWCState,
-} from '../types.js';
-import { BaseModeImplementation } from './index.js';
-
-/**
- * Edge mode for resource-constrained devices
- */
-export class EdgeMode extends BaseModeImplementation {
- readonly mode = 'edge';
-
- // Minimal pattern storage (compressed)
- private compressedPatterns: Map<string, CompressedPattern> = new Map();
-
- // Quantized LoRA weights (int8)
- private quantizedWeights: Map<string, Int8Array> = new Map();
- private quantizationScale: number = 1.0;
-
- // Pending async updates
- private pendingUpdates: Array<() => Promise<void>> = [];
- private updateTimer: ReturnType<typeof setTimeout> | null = null;
-
- // Stats
- private totalOps = 0;
- private totalTime = 0;
-
- async initialize(): Promise<void> {
- await super.initialize();
- this.compressedPatterns.clear();
- this.quantizedWeights.clear();
- this.pendingUpdates = [];
- }
-
- async cleanup(): Promise<void> {
- if (this.updateTimer) {
- clearTimeout(this.updateTimer);
- }
- this.compressedPatterns.clear();
- this.quantizedWeights.clear();
- this.pendingUpdates = [];
- await super.cleanup();
- }
-
- /**
- * Find patterns using compressed embeddings
- */
- async findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]> {
- const startTime = performance.now();
-
- // Compress input embedding for comparison
- const compressedInput = this.compressEmbedding(embedding);
-
- // Fast similarity on compressed representations
- const matches: Array<{ pattern: Pattern; score: number }> = [];
-
- for (const pattern of patterns) {
- let compressed = this.compressedPatterns.get(pattern.patternId);
- if (!compressed) {
- compressed = this.createCompressedPattern(pattern);
- this.compressedPatterns.set(pattern.patternId, compressed);
- }
-
- // Use compressed similarity (faster but less accurate)
- const score = this.compressedSimilarity(compressedInput, compressed.embedding);
- matches.push({ pattern, score });
- }
-
- // Quick partial sort
- matches.sort((a, b) => b.score - a.score);
- const topK = matches.slice(0, k);
-
- this.totalOps++;
- this.totalTime += performance.now() - startTime;
-
- return topK.map(m => ({
- pattern: m.pattern,
- similarity: m.score,
- confidence: m.score * m.pattern.successRate,
- latencyMs: 0,
- }));
- }
-
- /**
- * Lightweight learning with async updates
- */
- async learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number> {
- const startTime = performance.now();
-
- if (trajectories.length === 0) return 0;
-
- // Edge mode: only learn from high-quality trajectories
- const threshold = config.qualityThreshold;
- const good = trajectories.filter(t => t.qualityScore >= threshold);
-
- if (good.length === 0) return 0;
-
- const avgQuality = good.reduce((s, t) => s + t.qualityScore, 0) / good.length;
-
- // Queue async update for later processing
- this.queueAsyncUpdate(async () => {
- await this.performLightweightUpdate(good, config.learningRate);
- });
-
- this.totalOps++;
- this.totalTime += performance.now() - startTime;
-
- return Math.max(0, avgQuality - 0.5);
- }
-
- /**
- * Apply quantized LoRA
- */
- async applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array> {
- if (!weights) {
- return input;
- }
-
- const output = new Float32Array(input.length);
- output.set(input);
-
- // Quantize weights if not already done
- for (const module of ['q_proj', 'v_proj']) {
- const A = weights.A.get(module);
- const B = weights.B.get(module);
-
- if (A && B) {
- const qA = this.getOrQuantize(`A_${module}`, A);
- const qB = this.getOrQuantize(`B_${module}`, B);
-
- // Apply quantized LoRA
- const adapted = this.applyQuantizedLoRA(input, qA, qB);
- const alpha = 0.05; // Very small blending for edge
- for (let i = 0; i < output.length; i++) {
- output[i] = output[i] * (1 - alpha) + adapted[i] * alpha;
- }
- }
- }
-
- return output;
- }
-
- getStats(): Record<string, number> {
- return {
- avgLatencyMs: this.totalOps > 0 ? this.totalTime / this.totalOps : 0,
- compressedPatterns: this.compressedPatterns.size,
- quantizedWeights: this.quantizedWeights.size,
- pendingUpdates: this.pendingUpdates.length,
- memoryEstimateMb: this.estimateMemoryUsage(),
- };
- }
-
- // ========================================================================
- // Compression utilities
- // ========================================================================
-
- /**
- * Compress embedding to 8-bit representation
- */
- private compressEmbedding(embedding: Float32Array): Int8Array {
- const compressed = new Int8Array(embedding.length);
- const max = Math.max(...embedding.map(Math.abs));
- const scale = max > 0 ? 127 / max : 1;
-
- for (let i = 0; i < embedding.length; i++) {
- compressed[i] = Math.round(embedding[i] * scale);
- }
-
- return compressed;
- }
-
- /**
- * Create compressed pattern representation
- */
- private createCompressedPattern(pattern: Pattern): CompressedPattern {
- return {
- id: pattern.patternId,
- embedding: this.compressEmbedding(pattern.embedding),
- successRate: Math.round(pattern.successRate * 255),
- usageCount: Math.min(pattern.usageCount, 255),
- };
- }
-
- /**
- * Fast similarity on compressed embeddings
- */
- private compressedSimilarity(a: Int8Array, b: Int8Array): number {
- if (a.length !== b.length) return 0;
-
- let dot = 0;
- let normA = 0;
- let normB = 0;
-
- // Process in chunks of 8 for better cache utilization
- const len = a.length;
- for (let i = 0; i < len; i++) {
- dot += a[i] * b[i];
- normA += a[i] * a[i];
- normB += b[i] * b[i];
- }
-
- const denom = Math.sqrt(normA * normB);
- return denom > 0 ? dot / denom : 0;
- }
-
- /**
- * Get or create quantized weights
- */
- private getOrQuantize(key: string, weights: Float32Array): Int8Array {
- let quantized = this.quantizedWeights.get(key);
- if (!quantized) {
- quantized = this.quantizeWeights(weights);
- this.quantizedWeights.set(key, quantized);
- }
- return quantized;
- }
-
- /**
- * Quantize float weights to int8
- */
- private quantizeWeights(weights: Float32Array): Int8Array {
- const max = Math.max(...weights.map(Math.abs));
- this.quantizationScale = max > 0 ? 127 / max : 1;
-
- const quantized = new Int8Array(weights.length);
- for (let i = 0; i < weights.length; i++) {
- quantized[i] = Math.round(weights[i] * this.quantizationScale);
- }
-
- return quantized;
- }
-
- /**
- * Apply LoRA with quantized weights
- */
- private applyQuantizedLoRA(
- input: Float32Array,
- qA: Int8Array,
- qB: Int8Array
- ): Float32Array {
- const dim = input.length;
- const rank = 1; // Edge mode uses rank-1
-
- const output = new Float32Array(dim);
- const dequantScale = 1 / this.quantizationScale;
-
- // A * input -> intermediate (scalar for rank-1)
- let intermediate = 0;
- for (let d = 0; d < dim; d++) {
- intermediate += (qA[d] * dequantScale) * input[d];
- }
-
- // B * intermediate -> output
- for (let d = 0; d < dim; d++) {
- output[d] = (qB[d] * dequantScale) * intermediate;
- }
-
- return output;
- }
-
- // ========================================================================
- // Async updates
- // ========================================================================
-
- /**
- * Queue an async update
- */
- private queueAsyncUpdate(update: () => Promise<void>): void {
- this.pendingUpdates.push(update);
-
- // Schedule processing if not already scheduled
- if (!this.updateTimer) {
- this.updateTimer = setTimeout(() => {
- this.processAsyncUpdates();
- }, 100); // Process updates every 100ms
- }
- }
-
- /**
- * Process pending async updates
- */
- private async processAsyncUpdates(): Promise<void> {
- this.updateTimer = null;
-
- const updates = this.pendingUpdates;
- this.pendingUpdates = [];
-
- // Process up to 5 updates at a time
- for (const update of updates.slice(0, 5)) {
- try {
- await update();
- } catch (error) {
- console.error('Edge mode async update failed:', error);
- }
- }
-
- // Re-queue remaining updates
- if (updates.length > 5) {
- this.pendingUpdates = updates.slice(5);
- this.updateTimer = setTimeout(() => {
- this.processAsyncUpdates();
- }, 100);
- }
- }
-
- /**
- * Perform lightweight parameter update
- */
- private async performLightweightUpdate(
- trajectories: Trajectory[],
- learningRate: number
- ): Promise<void> {
- // Simple exponential moving average update
- const alpha = learningRate;
-
- for (const trajectory of trajectories) {
- if (trajectory.steps.length === 0) continue;
-
- // Update compressed patterns based on trajectory success
- const lastStep = trajectory.steps[trajectory.steps.length - 1];
- const pattern = this.findSimilarCompressedPattern(lastStep.stateAfter);
-
- if (pattern) {
- // Update success rate with EMA
- const newRate = alpha * trajectory.qualityScore + (1 - alpha) * (pattern.successRate / 255);
- pattern.successRate = Math.round(newRate * 255);
- pattern.usageCount = Math.min(255, pattern.usageCount + 1);
- }
- }
- }
-
- /**
- * Find most similar compressed pattern
- */
- private findSimilarCompressedPattern(embedding: Float32Array): CompressedPattern | null {
- const compressed = this.compressEmbedding(embedding);
- let best: CompressedPattern | null = null;
- let bestSim = -1;
-
- for (const pattern of this.compressedPatterns.values()) {
- const sim = this.compressedSimilarity(compressed, pattern.embedding);
- if (sim > bestSim) {
- bestSim = sim;
- best = pattern;
- }
- }
-
- return best;
- }
-
- /**
- * Estimate memory usage in MB
- */
- private estimateMemoryUsage(): number {
- let bytes = 0;
-
- // Compressed patterns
- for (const pattern of this.compressedPatterns.values()) {
- bytes += pattern.embedding.byteLength + 8; // embedding + overhead
- }
-
- // Quantized weights
- for (const weights of this.quantizedWeights.values()) {
- bytes += weights.byteLength;
- }
-
- // Pending updates (minimal)
- bytes += this.pendingUpdates.length * 100;
-
- return bytes / (1024 * 1024);
- }
-}
-
-/**
- * Compressed pattern representation
- */
-interface CompressedPattern {
- id: string;
- embedding: Int8Array;
- successRate: number; // 0-255
- usageCount: number; // 0-255
-}
diff --git a/v3/neural/modes/index.ts b/v3/neural/modes/index.ts
deleted file mode 100644
index 73df6ada00..0000000000
--- a/v3/neural/modes/index.ts
+++ /dev/null
@@ -1,170 +0,0 @@
-/**
- * SONA Learning Modes Index
- *
- * Exports all learning mode implementations and the common interface.
- */
-
-import type {
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- Pattern,
- PatternMatch,
- LoRAWeights,
- EWCState,
-} from '../types.js';
-
-/**
- * Common interface for all mode implementations
- */
-export interface ModeImplementation {
- /** Mode identifier */
- readonly mode: string;
-
- /** Initialize the mode */
- initialize(): Promise<void>;
-
- /** Cleanup resources */
- cleanup(): Promise<void>;
-
- /** Find similar patterns (k-nearest) */
- findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]>;
-
- /** Perform a learning step */
- learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number>;
-
- /** Apply LoRA adaptations */
- applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array>;
-
- /** Get mode-specific stats */
- getStats(): Record<string, number>;
-}
-
-/**
- * Base class for mode implementations
- */
-export abstract class BaseModeImplementation implements ModeImplementation {
- abstract readonly mode: string;
-
- protected config: SONAModeConfig;
- protected optimizations: ModeOptimizations;
- protected isInitialized = false;
-
- constructor(config: SONAModeConfig, optimizations: ModeOptimizations) {
- this.config = config;
- this.optimizations = optimizations;
- }
-
- async initialize(): Promise<void> {
- this.isInitialized = true;
- }
-
- async cleanup(): Promise<void> {
- this.isInitialized = false;
- }
-
- /**
- * Compute cosine similarity between two vectors (SIMD-optimized)
- */
- protected cosineSimilarity(a: Float32Array, b: Float32Array): number {
- if (a.length !== b.length) return 0;
-
- let dotProduct = 0;
- let normA = 0;
- let normB = 0;
-
- // Process 4 elements at a time for SIMD-like behavior
- const len = a.length;
- const simdLen = len - (len % 4);
-
- for (let i = 0; i < simdLen; i += 4) {
- dotProduct += a[i] * b[i] + a[i+1] * b[i+1] + a[i+2] * b[i+2] + a[i+3] * b[i+3];
- normA += a[i] * a[i] + a[i+1] * a[i+1] + a[i+2] * a[i+2] + a[i+3] * a[i+3];
- normB += b[i] * b[i] + b[i+1] * b[i+1] + b[i+2] * b[i+2] + b[i+3] * b[i+3];
- }
-
- // Handle remaining elements
- for (let i = simdLen; i < len; i++) {
- dotProduct += a[i] * b[i];
- normA += a[i] * a[i];
- normB += b[i] * b[i];
- }
-
- const denom = Math.sqrt(normA) * Math.sqrt(normB);
- return denom > 0 ? dotProduct / denom : 0;
- }
-
- /**
- * Apply LoRA: output = input + BA * input (simplified)
- */
- protected applyLoRATransform(
- input: Float32Array,
- A: Float32Array,
- B: Float32Array,
- rank: number
- ): Float32Array {
- const dim = input.length;
- const output = new Float32Array(dim);
-
- // Copy input to output
- output.set(input);
-
- // Compute A * input -> intermediate (rank dimensions)
- const intermediate = new Float32Array(rank);
- for (let r = 0; r < rank; r++) {
- let sum = 0;
- for (let d = 0; d < dim; d++) {
- sum += A[d * rank + r] * input[d];
- }
- intermediate[r] = sum;
- }
-
- // Compute B * intermediate -> delta (dim dimensions)
- for (let d = 0; d < dim; d++) {
- let sum = 0;
- for (let r = 0; r < rank; r++) {
- sum += B[r * dim + d] * intermediate[r];
- }
- output[d] += sum;
- }
-
- return output;
- }
-
- abstract findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]>;
-
- abstract learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number>;
-
- abstract applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array>;
-
- abstract getStats(): Record<string, number>;
-}
-
-// Export mode implementations
-export { RealTimeMode } from './real-time.js';
-export { BalancedMode } from './balanced.js';
-export { ResearchMode } from './research.js';
-export { EdgeMode } from './edge.js';
-export { BatchMode } from './batch.js';
diff --git a/v3/neural/modes/real-time.ts b/v3/neural/modes/real-time.ts
deleted file mode 100644
index d41cdc22ed..0000000000
--- a/v3/neural/modes/real-time.ts
+++ /dev/null
@@ -1,257 +0,0 @@
-/**
- * Real-Time Mode Implementation
- *
- * Optimized for sub-millisecond adaptation with:
- * - 2200 ops/sec target
- * - <0.5ms latency
- * - Micro-LoRA (rank-2)
- * - SIMD vectorization
- * - Aggressive caching
- */
-
-import type {
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- Pattern,
- PatternMatch,
- LoRAWeights,
- EWCState,
-} from '../types.js';
-import { BaseModeImplementation } from './index.js';
-
-/**
- * Real-Time mode for sub-millisecond adaptation
- */
-export class RealTimeMode extends BaseModeImplementation {
- readonly mode = 'real-time';
-
- // Pattern cache for fast lookups
- private patternCache: Map<string, PatternMatch[]> = new Map();
- private cacheHits = 0;
- private cacheMisses = 0;
-
- // Pre-computed pattern embeddings for fast similarity
- private patternEmbeddings: Float32Array[] = [];
- private patternIds: string[] = [];
-
- // Stats
- private totalPatternMatches = 0;
- private totalPatternTime = 0;
- private totalLearnTime = 0;
- private learnIterations = 0;
-
- async initialize(): Promise<void> {
- await super.initialize();
- this.patternCache.clear();
- this.patternEmbeddings = [];
- this.patternIds = [];
- }
-
- async cleanup(): Promise<void> {
- this.patternCache.clear();
- this.patternEmbeddings = [];
- this.patternIds = [];
- await super.cleanup();
- }
-
- /**
- * Find patterns using cached similarity search
- * Target: <1ms for k=3
- */
- async findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]> {
- const startTime = performance.now();
-
- // Check cache first (hash first 8 floats for cache key)
- const cacheKey = this.computeCacheKey(embedding);
- const cached = this.patternCache.get(cacheKey);
-
- if (cached && cached.length >= k) {
- this.cacheHits++;
- this.totalPatternTime += performance.now() - startTime;
- this.totalPatternMatches++;
- return cached.slice(0, k);
- }
-
- this.cacheMisses++;
-
- // Update pattern embeddings if patterns changed
- if (patterns.length !== this.patternIds.length) {
- this.updatePatternIndex(patterns);
- }
-
- // Fast similarity search using pre-computed embeddings
- const similarities: Array<{ index: number; similarity: number }> = [];
-
- for (let i = 0; i < this.patternEmbeddings.length; i++) {
- const similarity = this.cosineSimilarity(embedding, this.patternEmbeddings[i]);
- similarities.push({ index: i, similarity });
- }
-
- // Partial sort to get top-k (faster than full sort)
- const topK = this.partialSort(similarities, k);
-
- const matches: PatternMatch[] = topK.map(item => ({
- pattern: patterns[item.index],
- similarity: item.similarity,
- confidence: item.similarity * patterns[item.index].successRate,
- latencyMs: 0, // Will be set by caller
- }));
-
- // Cache the result
- if (this.patternCache.size > 1000) {
- // LRU eviction: remove oldest entries
- const firstKey = this.patternCache.keys().next().value;
- if (firstKey) this.patternCache.delete(firstKey);
- }
- this.patternCache.set(cacheKey, matches);
-
- this.totalPatternTime += performance.now() - startTime;
- this.totalPatternMatches++;
-
- return matches;
- }
-
- /**
- * Fast learning using Micro-LoRA updates
- * Target: <10ms per batch
- */
- async learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number> {
- const startTime = performance.now();
-
- if (trajectories.length === 0) return 0;
-
- // Real-time mode uses simplified learning for speed
- // Only process high-quality trajectories
- const qualityThreshold = config.qualityThreshold;
- const goodTrajectories = trajectories.filter(t => t.qualityScore >= qualityThreshold);
-
- if (goodTrajectories.length === 0) return 0;
-
- // Compute average quality improvement
- const avgQuality = goodTrajectories.reduce((sum, t) => sum + t.qualityScore, 0) / goodTrajectories.length;
-
- // Simplified gradient update (for real-time, we skip full backprop)
- // Just update EWC means to track what works
- const improvementDelta = avgQuality - 0.5; // Relative to baseline of 0.5
-
- this.totalLearnTime += performance.now() - startTime;
- this.learnIterations++;
-
- return Math.max(0, improvementDelta);
- }
-
- /**
- * Apply LoRA with minimal overhead
- * Target: <0.05ms
- */
- async applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array> {
- if (!weights) {
- // No adaptation, return input as-is
- return input;
- }
-
- // Micro-LoRA: only apply to key modules
- const output = new Float32Array(input.length);
- output.set(input);
-
- // Apply rank-2 adaptation (minimal overhead)
- const rank = this.config.loraRank;
-
- for (const module of ['q_proj', 'v_proj']) {
- const A = weights.A.get(module);
- const B = weights.B.get(module);
-
- if (A && B) {
- const adapted = this.applyLoRATransform(input, A, B, rank);
- // Blend with small alpha for stability
- const alpha = 0.1;
- for (let i = 0; i < output.length; i++) {
- output[i] = output[i] * (1 - alpha) + adapted[i] * alpha;
- }
- }
- }
-
- return output;
- }
-
- getStats(): Record<string, number> {
- return {
- cacheHitRate: this.cacheHits + this.cacheMisses > 0
- ? this.cacheHits / (this.cacheHits + this.cacheMisses)
- : 0,
- avgPatternMatchMs: this.totalPatternMatches > 0
- ? this.totalPatternTime / this.totalPatternMatches
- : 0,
- avgLearnMs: this.learnIterations > 0
- ? this.totalLearnTime / this.learnIterations
- : 0,
- patternCacheSize: this.patternCache.size,
- indexedPatterns: this.patternEmbeddings.length,
- };
- }
-
- /**
- * Compute cache key from embedding
- */
- private computeCacheKey(embedding: Float32Array): string {
- // Use first 8 floats for cache key (fast hash)
- const keyParts: string[] = [];
- for (let i = 0; i < Math.min(8, embedding.length); i++) {
- keyParts.push(embedding[i].toFixed(3));
- }
- return keyParts.join(',');
- }
-
- /**
- * Update pattern index for fast similarity search
- */
- private updatePatternIndex(patterns: Pattern[]): void {
- this.patternEmbeddings = patterns.map(p => p.embedding);
- this.patternIds = patterns.map(p => p.patternId);
- this.patternCache.clear();
- }
-
- /**
- * Partial sort to get top-k elements (faster than full sort)
- */
- private partialSort(
- items: Array<{ index: number; similarity: number }>,
- k: number
- ): Array<{ index: number; similarity: number }> {
- if (items.length <= k) {
- return items.sort((a, b) => b.similarity - a.similarity);
- }
-
- // Use a simple selection algorithm for small k
- const result: Array<{ index: number; similarity: number }> = [];
-
- for (let i = 0; i < k; i++) {
- let maxIdx = 0;
- let maxVal = -Infinity;
-
- for (let j = 0; j < items.length; j++) {
- if (items[j].similarity > maxVal) {
- maxVal = items[j].similarity;
- maxIdx = j;
- }
- }
-
- result.push(items[maxIdx]);
- items[maxIdx] = { index: -1, similarity: -Infinity };
- }
-
- return result;
- }
-}
diff --git a/v3/neural/modes/research.ts b/v3/neural/modes/research.ts
deleted file mode 100644
index 528f5f9e71..0000000000
--- a/v3/neural/modes/research.ts
+++ /dev/null
@@ -1,486 +0,0 @@
-/**
- * Research Mode Implementation
- *
- * Optimized for maximum quality with:
- * - +55% quality improvement target
- * - Learning rate 0.002 (sweet spot)
- * - Rank-16 LoRA
- * - Gradient checkpointing
- * - Full learning pipeline
- */
-
-import type {
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- Pattern,
- PatternMatch,
- LoRAWeights,
- EWCState,
-} from '../types.js';
-import { BaseModeImplementation } from './index.js';
-
-/**
- * Research mode for maximum quality learning
- */
-export class ResearchMode extends BaseModeImplementation {
- readonly mode = 'research';
-
- // Extended pattern storage
- private patternIndex: Map<string, number> = new Map();
- private clusterCentroids: Float32Array[] = [];
-
- // Learning state with checkpointing
- private gradientHistory: Array<Map<string, Float32Array>> = [];
- private checkpoints: Array<{ iteration: number; state: Map<string, Float32Array> }> = [];
-
- // Adam optimizer state
- private adamM: Map<string, Float32Array> = new Map();
- private adamV: Map<string, Float32Array> = new Map();
- private adamStep = 0;
-
- // Stats
- private totalPatternMatches = 0;
- private totalPatternTime = 0;
- private totalLearnTime = 0;
- private learnIterations = 0;
- private qualityHistory: number[] = [];
- private explorationRewards: number[] = [];
-
- async initialize(): Promise<void> {
- await super.initialize();
- this.patternIndex.clear();
- this.clusterCentroids = [];
- this.gradientHistory = [];
- this.checkpoints = [];
- this.adamM.clear();
- this.adamV.clear();
- this.adamStep = 0;
- }
-
- async cleanup(): Promise<void> {
- this.patternIndex.clear();
- this.clusterCentroids = [];
- this.gradientHistory = [];
- this.checkpoints = [];
- this.adamM.clear();
- this.adamV.clear();
- await super.cleanup();
- }
-
- /**
- * Find patterns using cluster-based search
- */
- async findPatterns(
- embedding: Float32Array,
- k: number,
- patterns: Pattern[]
- ): Promise<PatternMatch[]> {
- const startTime = performance.now();
-
- // Update clusters if needed
- if (this.clusterCentroids.length !== this.config.patternClusters) {
- await this.rebuildClusters(patterns);
- }
-
- // Find nearest cluster
- let bestCluster = 0;
- let bestSim = -1;
- for (let c = 0; c < this.clusterCentroids.length; c++) {
- const sim = this.cosineSimilarity(embedding, this.clusterCentroids[c]);
- if (sim > bestSim) {
- bestSim = sim;
- bestCluster = c;
- }
- }
-
- // Search within cluster + nearby clusters
- const clustersToSearch = this.getNearestClusters(embedding, 3);
- const candidates: PatternMatch[] = [];
-
- for (const pattern of patterns) {
- const patternCluster = this.patternIndex.get(pattern.patternId);
- if (patternCluster !== undefined && clustersToSearch.includes(patternCluster)) {
- const similarity = this.cosineSimilarity(embedding, pattern.embedding);
- candidates.push({
- pattern,
- similarity,
- confidence: this.computeConfidence(pattern, similarity),
- latencyMs: 0,
- });
- }
- }
-
- // If not enough candidates, search all patterns
- if (candidates.length < k) {
- for (const pattern of patterns) {
- if (!candidates.find(c => c.pattern.patternId === pattern.patternId)) {
- const similarity = this.cosineSimilarity(embedding, pattern.embedding);
- candidates.push({
- pattern,
- similarity,
- confidence: this.computeConfidence(pattern, similarity),
- latencyMs: 0,
- });
- }
- }
- }
-
- // Sort and return top-k
- candidates.sort((a, b) => b.similarity - a.similarity);
-
- this.totalPatternTime += performance.now() - startTime;
- this.totalPatternMatches++;
-
- return candidates.slice(0, k);
- }
-
- /**
- * Learn using full Adam optimizer with gradient checkpointing
- */
- async learn(
- trajectories: Trajectory[],
- config: SONAModeConfig,
- ewcState: EWCState
- ): Promise<number> {
- const startTime = performance.now();
-
- if (trajectories.length === 0) return 0;
-
- // Research mode uses low threshold to learn from all data
- const learningRate = config.learningRate; // 0.002 sweet spot
- const batchSize = config.batchSize;
-
- // Sort trajectories by quality
- const sortedTrajectories = [...trajectories].sort((a, b) => b.qualityScore - a.qualityScore);
-
- // Create checkpoint before learning
- if (this.learnIterations % 10 === 0) {
- this.createCheckpoint();
- }
-
- let totalLoss = 0;
- let batchCount = 0;
-
- // Process in mini-batches
- for (let i = 0; i < sortedTrajectories.length; i += batchSize) {
- const batch = sortedTrajectories.slice(i, i + batchSize);
- const batchLoss = await this.processBatch(batch, learningRate, ewcState, config.ewcLambda);
- totalLoss += batchLoss;
- batchCount++;
- }
-
- // Track quality
- const avgQuality = sortedTrajectories.reduce((s, t) => s + t.qualityScore, 0) / sortedTrajectories.length;
- this.qualityHistory.push(avgQuality);
- if (this.qualityHistory.length > 1000) {
- this.qualityHistory = this.qualityHistory.slice(-1000);
- }
-
- // Compute improvement
- const recentAvg = this.qualityHistory.slice(-10).reduce((a, b) => a + b, 0) / Math.min(10, this.qualityHistory.length);
- const oldAvg = this.qualityHistory.slice(0, Math.max(1, this.qualityHistory.length - 10)).reduce((a, b) => a + b, 0) / Math.max(1, this.qualityHistory.length - 10);
- const improvementDelta = recentAvg - oldAvg;
-
- this.totalLearnTime += performance.now() - startTime;
- this.learnIterations++;
-
- return Math.max(0, improvementDelta * 2); // Scale for research mode
- }
-
- /**
- * Apply LoRA with rank-16 for maximum expressivity
- */
- async applyLoRA(
- input: Float32Array,
- weights?: LoRAWeights
- ): Promise<Float32Array> {
- if (!weights) {
- return input;
- }
-
- const output = new Float32Array(input.length);
- output.set(input);
-
- const rank = this.config.loraRank; // 16 for research mode
-
- // Apply to all modules with higher blending
- for (const module of ['q_proj', 'v_proj', 'k_proj', 'o_proj']) {
- const A = weights.A.get(module);
- const B = weights.B.get(module);
-
- if (A && B) {
- const adapted = this.applyLoRATransform(input, A, B, rank);
- const alpha = 0.3; // Higher blending for research
- for (let i = 0; i < output.length; i++) {
- output[i] = output[i] * (1 - alpha) + adapted[i] * alpha;
- }
- }
- }
-
- return output;
- }
-
- getStats(): Record<string, number> {
- const avgQuality = this.qualityHistory.length > 0
- ? this.qualityHistory.reduce((a, b) => a + b, 0) / this.qualityHistory.length
- : 0;
-
- const recentQuality = this.qualityHistory.slice(-10).reduce((a, b) => a + b, 0) / Math.min(10, this.qualityHistory.length) || 0;
-
- return {
- avgPatternMatchMs: this.totalPatternMatches > 0
- ? this.totalPatternTime / this.totalPatternMatches
- : 0,
- avgLearnMs: this.learnIterations > 0
- ? this.totalLearnTime / this.learnIterations
- : 0,
- avgQuality,
- recentQuality,
- qualityImprovement: recentQuality - avgQuality,
- clusterCount: this.clusterCentroids.length,
- checkpointCount: this.checkpoints.length,
- adamStep: this.adamStep,
- learnIterations: this.learnIterations,
- };
- }
-
- /**
- * Rebuild cluster centroids using k-means
- */
- private async rebuildClusters(patterns: Pattern[]): Promise<void> {
- if (patterns.length === 0) return;
-
- const k = Math.min(this.config.patternClusters, patterns.length);
- const dim = patterns[0].embedding.length;
-
- // Initialize centroids randomly
- this.clusterCentroids = [];
- const indices = new Set<number>();
- while (indices.size < k) {
- indices.add(Math.floor(Math.random() * patterns.length));
- }
- for (const idx of indices) {
- this.clusterCentroids.push(new Float32Array(patterns[idx].embedding));
- }
-
- // Run k-means iterations
- for (let iter = 0; iter < 10; iter++) {
- // Assign patterns to clusters
- const clusterAssignments: number[][] = Array.from({ length: k }, () => []);
-
- for (let p = 0; p < patterns.length; p++) {
- let bestCluster = 0;
- let bestSim = -1;
- for (let c = 0; c < k; c++) {
- const sim = this.cosineSimilarity(patterns[p].embedding, this.clusterCentroids[c]);
- if (sim > bestSim) {
- bestSim = sim;
- bestCluster = c;
- }
- }
- clusterAssignments[bestCluster].push(p);
- this.patternIndex.set(patterns[p].patternId, bestCluster);
- }
-
- // Update centroids
- for (let c = 0; c < k; c++) {
- if (clusterAssignments[c].length > 0) {
- const newCentroid = new Float32Array(dim);
- for (const p of clusterAssignments[c]) {
- for (let d = 0; d < dim; d++) {
- newCentroid[d] += patterns[p].embedding[d];
- }
- }
- for (let d = 0; d < dim; d++) {
- newCentroid[d] /= clusterAssignments[c].length;
- }
- this.clusterCentroids[c] = newCentroid;
- }
- }
- }
- }
-
- /**
- * Get nearest clusters to embedding
- */
- private getNearestClusters(embedding: Float32Array, n: number): number[] {
- const similarities: Array<{ cluster: number; sim: number }> = [];
- for (let c = 0; c < this.clusterCentroids.length; c++) {
- similarities.push({ cluster: c, sim: this.cosineSimilarity(embedding, this.clusterCentroids[c]) });
- }
- similarities.sort((a, b) => b.sim - a.sim);
- return similarities.slice(0, n).map(s => s.cluster);
- }
-
- /**
- * Compute confidence for pattern match
- */
- private computeConfidence(pattern: Pattern, similarity: number): number {
- // Combine similarity with pattern history
- const historyWeight = Math.min(pattern.usageCount / 10, 1);
- return similarity * (1 - historyWeight * 0.3) + pattern.successRate * historyWeight * 0.3;
- }
-
- /**
- * Create learning checkpoint
- */
- private createCheckpoint(): void {
- const state = new Map<string, Float32Array>();
- for (const [key, value] of this.adamM) {
- state.set(`m_${key}`, new Float32Array(value));
- }
- for (const [key, value] of this.adamV) {
- state.set(`v_${key}`, new Float32Array(value));
- }
-
- this.checkpoints.push({ iteration: this.learnIterations, state });
-
- // Keep only last 10 checkpoints
- if (this.checkpoints.length > 10) {
- this.checkpoints = this.checkpoints.slice(-10);
- }
- }
-
- /**
- * Process a mini-batch with Adam optimizer
- */
- private async processBatch(
- batch: Trajectory[],
- learningRate: number,
- ewcState: EWCState,
- ewcLambda: number
- ): Promise<number> {
- const beta1 = 0.9;
- const beta2 = 0.999;
- const epsilon = 1e-8;
-
- this.adamStep++;
-
- let totalLoss = 0;
-
- for (const trajectory of batch) {
- if (trajectory.steps.length === 0) continue;
-
- // Compute gradient from trajectory
- const gradient = this.computeTrajectoryGradient(trajectory);
-
- for (const [key, grad] of gradient) {
- // Get or initialize Adam state
- let m = this.adamM.get(key);
- let v = this.adamV.get(key);
-
- if (!m) {
- m = new Float32Array(grad.length);
- this.adamM.set(key, m);
- }
- if (!v) {
- v = new Float32Array(grad.length);
- this.adamV.set(key, v);
- }
-
- // Update biased first moment estimate
- for (let i = 0; i < grad.length; i++) {
- m[i] = beta1 * m[i] + (1 - beta1) * grad[i];
- }
-
- // Update biased second moment estimate
- for (let i = 0; i < grad.length; i++) {
- v[i] = beta2 * v[i] + (1 - beta2) * grad[i] * grad[i];
- }
-
- // Bias correction
- const mHat = new Float32Array(grad.length);
- const vHat = new Float32Array(grad.length);
- for (let i = 0; i < grad.length; i++) {
- mHat[i] = m[i] / (1 - Math.pow(beta1, this.adamStep));
- vHat[i] = v[i] / (1 - Math.pow(beta2, this.adamStep));
- }
-
- // Compute loss contribution
- for (let i = 0; i < grad.length; i++) {
- totalLoss += grad[i] * grad[i];
- }
- }
- }
-
- // Add EWC penalty
- const ewcPenalty = this.computeEWCLoss(ewcState, ewcLambda);
- totalLoss += ewcPenalty;
-
- return totalLoss / batch.length;
- }
-
- /**
- * Compute gradient from trajectory
- */
- private computeTrajectoryGradient(trajectory: Trajectory): Map<string, Float32Array> {
- const gradient = new Map<string, Float32Array>();
-
- if (trajectory.steps.length < 2) return gradient;
-
- // Use advantage estimation
- const rewards = trajectory.steps.map(s => s.reward);
- const advantages = this.computeAdvantages(rewards);
-
- for (let i = 0; i < trajectory.steps.length; i++) {
- const step = trajectory.steps[i];
- const advantage = advantages[i];
-
- // Policy gradient: grad = advantage * grad_log_pi
- const stateGrad = new Float32Array(step.stateAfter.length);
- for (let j = 0; j < stateGrad.length; j++) {
- stateGrad[j] = step.stateAfter[j] * advantage;
- }
-
- gradient.set(`step_${i}`, stateGrad);
- }
-
- return gradient;
- }
-
- /**
- * Compute advantages using GAE
- */
- private computeAdvantages(rewards: number[]): number[] {
- const gamma = 0.99;
- const lambda = 0.95;
-
- const advantages = new Array(rewards.length).fill(0);
- let lastGae = 0;
-
- for (let t = rewards.length - 1; t >= 0; t--) {
- const nextValue = t < rewards.length - 1 ? rewards[t + 1] : 0;
- const delta = rewards[t] + gamma * nextValue - rewards[t];
- lastGae = delta + gamma * lambda * lastGae;
- advantages[t] = lastGae;
- }
-
- // Normalize advantages
- const mean = advantages.reduce((a, b) => a + b, 0) / advantages.length;
- const std = Math.sqrt(advantages.reduce((a, b) => a + (b - mean) ** 2, 0) / advantages.length) + 1e-8;
-
- return advantages.map(a => (a - mean) / std);
- }
-
- /**
- * Compute EWC loss for continual learning
- */
- private computeEWCLoss(ewcState: EWCState, lambda: number): number {
- let loss = 0;
-
- for (const [key, fisher] of ewcState.fisher) {
- const means = ewcState.means.get(key);
- const current = this.adamM.get(key);
-
- if (means && current) {
- for (let i = 0; i < Math.min(fisher.length, means.length, current.length); i++) {
- const diff = current[i] - means[i];
- loss += fisher[i] * diff * diff;
- }
- }
- }
-
- return lambda * loss * 0.5;
- }
-}
diff --git a/v3/neural/pattern-learner.ts b/v3/neural/pattern-learner.ts
deleted file mode 100644
index 0c563c22be..0000000000
--- a/v3/neural/pattern-learner.ts
+++ /dev/null
@@ -1,757 +0,0 @@
-/**
- * Pattern Learner
- *
- * Implements pattern extraction, matching, and evolution for
- * continuous learning from agent experiences.
- *
- * Performance Targets:
- * - Pattern matching: <1ms
- * - Pattern extraction: <5ms
- * - Evolution step: <2ms
- */
-
-import type {
- Pattern,
- PatternMatch,
- PatternEvolution,
- Trajectory,
- DistilledMemory,
- NeuralEvent,
- NeuralEventListener,
-} from './types.js';
-
-/**
- * Configuration for Pattern Learner
- */
-export interface PatternLearnerConfig {
- /** Maximum number of patterns to store */
- maxPatterns: number;
-
- /** Similarity threshold for matching */
- matchThreshold: number;
-
- /** Minimum usages before pattern is stable */
- minUsagesForStable: number;
-
- /** Quality threshold for pattern inclusion */
- qualityThreshold: number;
-
- /** Enable pattern clustering */
- enableClustering: boolean;
-
- /** Number of clusters (if clustering enabled) */
- numClusters: number;
-
- /** Evolution learning rate */
- evolutionLearningRate: number;
-}
-
-/**
- * Default Pattern Learner configuration
- */
-const DEFAULT_CONFIG: PatternLearnerConfig = {
- maxPatterns: 1000,
- matchThreshold: 0.7,
- minUsagesForStable: 5,
- qualityThreshold: 0.5,
- enableClustering: true,
- numClusters: 50,
- evolutionLearningRate: 0.1,
-};
-
-/**
- * Cluster representation for fast pattern lookup
- */
-interface PatternCluster {
- clusterId: number;
- centroid: Float32Array;
- patternIds: Set<string>;
-}
-
-/**
- * Pattern Learner - Manages pattern extraction, matching, and evolution
- */
-export class PatternLearner {
- private config: PatternLearnerConfig;
- private patterns: Map<string, Pattern> = new Map();
- private clusters: PatternCluster[] = [];
- private patternToCluster: Map<string, number> = new Map();
-
- // Performance tracking
- private matchCount = 0;
- private totalMatchTime = 0;
- private extractionCount = 0;
- private totalExtractionTime = 0;
- private evolutionCount = 0;
- private totalEvolutionTime = 0;
-
- // Event listeners
- private eventListeners: Set<NeuralEventListener> = new Set();
-
- constructor(config: Partial<PatternLearnerConfig> = {}) {
- this.config = { ...DEFAULT_CONFIG, ...config };
- }
-
- // ==========================================================================
- // Pattern Matching
- // ==========================================================================
-
- /**
- * Find matching patterns for a query embedding
- * Target: <1ms
- */
- findMatches(queryEmbedding: Float32Array, k: number = 3): PatternMatch[] {
- const startTime = performance.now();
-
- if (this.patterns.size === 0) {
- return [];
- }
-
- let candidates: Pattern[];
-
- // Use clustering for faster search if enabled and clusters exist
- if (this.config.enableClustering && this.clusters.length > 0) {
- candidates = this.getCandidatesFromClusters(queryEmbedding);
- } else {
- candidates = Array.from(this.patterns.values());
- }
-
- // Compute similarities
- const matches: PatternMatch[] = [];
-
- for (const pattern of candidates) {
- const similarity = this.cosineSimilarity(queryEmbedding, pattern.embedding);
-
- if (similarity >= this.config.matchThreshold) {
- matches.push({
- pattern,
- similarity,
- confidence: this.computeMatchConfidence(pattern, similarity),
- latencyMs: 0,
- });
- }
- }
-
- // Sort by similarity
- matches.sort((a, b) => b.similarity - a.similarity);
- const result = matches.slice(0, k);
-
- // Track performance
- const elapsed = performance.now() - startTime;
- this.matchCount++;
- this.totalMatchTime += elapsed;
-
- // Warn if over target
- if (elapsed > 1) {
- console.warn(`Pattern matching exceeded target: ${elapsed.toFixed(2)}ms > 1ms`);
- }
-
- return result;
- }
-
- /**
- * Find best single match
- */
- findBestMatch(queryEmbedding: Float32Array): PatternMatch | null {
- const matches = this.findMatches(queryEmbedding, 1);
- return matches.length > 0 ? matches[0] : null;
- }
-
- // ==========================================================================
- // Pattern Extraction
- // ==========================================================================
-
- /**
- * Extract a pattern from a trajectory
- * Target: <5ms
- */
- extractPattern(trajectory: Trajectory, memory?: DistilledMemory): Pattern | null {
- const startTime = performance.now();
-
- // Validate trajectory
- if (!trajectory.isComplete || trajectory.qualityScore < this.config.qualityThreshold) {
- return null;
- }
-
- // Check for duplicates
- const embedding = this.computePatternEmbedding(trajectory);
- const existing = this.findSimilarPattern(embedding, 0.95);
-
- if (existing) {
- // Update existing pattern instead
- this.updatePatternFromTrajectory(existing, trajectory);
- return existing;
- }
-
- // Create new pattern
- const pattern: Pattern = {
- patternId: `pat_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
- name: this.generatePatternName(trajectory),
- domain: trajectory.domain,
- embedding,
- strategy: this.extractStrategy(trajectory),
- successRate: trajectory.qualityScore,
- usageCount: 1,
- qualityHistory: [trajectory.qualityScore],
- evolutionHistory: [],
- createdAt: Date.now(),
- updatedAt: Date.now(),
- };
-
- // Store pattern
- this.patterns.set(pattern.patternId, pattern);
-
- // Update clusters if enabled
- if (this.config.enableClustering) {
- this.assignToCluster(pattern);
- }
-
- // Prune if over capacity
- if (this.patterns.size > this.config.maxPatterns) {
- this.prunePatterns();
- }
-
- // Track performance
- const elapsed = performance.now() - startTime;
- this.extractionCount++;
- this.totalExtractionTime += elapsed;
-
- return pattern;
- }
-
- /**
- * Extract patterns from multiple trajectories in batch
- */
- extractPatternsBatch(trajectories: Trajectory[]): Pattern[] {
- const patterns: Pattern[] = [];
-
- for (const trajectory of trajectories) {
- const pattern = this.extractPattern(trajectory);
- if (pattern) {
- patterns.push(pattern);
- }
- }
-
- // Rebuild clusters after batch extraction
- if (this.config.enableClustering && patterns.length > 10) {
- this.rebuildClusters();
- }
-
- return patterns;
- }
-
- // ==========================================================================
- // Pattern Evolution
- // ==========================================================================
-
- /**
- * Evolve a pattern based on new experience
- * Target: <2ms
- */
- evolvePattern(patternId: string, quality: number, context?: string): void {
- const startTime = performance.now();
-
- const pattern = this.patterns.get(patternId);
- if (!pattern) return;
-
- const previousQuality = pattern.successRate;
- const lr = this.config.evolutionLearningRate;
-
- // Update quality history
- pattern.qualityHistory.push(quality);
- if (pattern.qualityHistory.length > 100) {
- pattern.qualityHistory = pattern.qualityHistory.slice(-100);
- }
-
- // Exponential moving average for success rate
- pattern.successRate = pattern.successRate * (1 - lr) + quality * lr;
- pattern.usageCount++;
- pattern.updatedAt = Date.now();
-
- // Record evolution
- const evolutionType = this.determineEvolutionType(previousQuality, pattern.successRate);
- pattern.evolutionHistory.push({
- timestamp: Date.now(),
- type: evolutionType,
- previousQuality,
- newQuality: pattern.successRate,
- description: context || 'Updated from new experience',
- });
-
- // Keep evolution history bounded
- if (pattern.evolutionHistory.length > 50) {
- pattern.evolutionHistory = pattern.evolutionHistory.slice(-50);
- }
-
- // Emit event
- this.emitEvent({
- type: 'pattern_evolved',
- patternId,
- evolutionType,
- });
-
- // Track performance
- const elapsed = performance.now() - startTime;
- this.evolutionCount++;
- this.totalEvolutionTime += elapsed;
- }
-
- /**
- * Merge two similar patterns
- */
- mergePatterns(patternId1: string, patternId2: string): Pattern | null {
- const p1 = this.patterns.get(patternId1);
- const p2 = this.patterns.get(patternId2);
-
- if (!p1 || !p2) return null;
-
- // Keep the higher quality pattern as base
- const [keep, remove] = p1.successRate >= p2.successRate ? [p1, p2] : [p2, p1];
-
- // Merge embeddings (weighted average)
- const totalUsage = keep.usageCount + remove.usageCount;
- const w1 = keep.usageCount / totalUsage;
- const w2 = remove.usageCount / totalUsage;
-
- for (let i = 0; i < keep.embedding.length; i++) {
- keep.embedding[i] = keep.embedding[i] * w1 + remove.embedding[i] * w2;
- }
-
- // Merge statistics
- keep.usageCount += remove.usageCount;
- keep.qualityHistory.push(...remove.qualityHistory);
- keep.successRate = keep.qualityHistory.reduce((a, b) => a + b, 0) / keep.qualityHistory.length;
-
- // Record merge
- keep.evolutionHistory.push({
- timestamp: Date.now(),
- type: 'merge',
- previousQuality: p1.successRate,
- newQuality: keep.successRate,
- description: `Merged with pattern ${remove.patternId}`,
- });
-
- // Remove the merged pattern
- this.patterns.delete(remove.patternId);
- this.patternToCluster.delete(remove.patternId);
-
- return keep;
- }
-
- /**
- * Split a pattern into more specific sub-patterns
- */
- splitPattern(patternId: string, numSplits: number = 2): Pattern[] {
- const pattern = this.patterns.get(patternId);
- if (!pattern || numSplits < 2) return [];
-
- const splits: Pattern[] = [];
-
- for (let i = 0; i < numSplits; i++) {
- // Create variation of embedding with noise
- const newEmbedding = new Float32Array(pattern.embedding.length);
- for (let j = 0; j < newEmbedding.length; j++) {
- const noise = (Math.random() - 0.5) * 0.1;
- newEmbedding[j] = pattern.embedding[j] + noise;
- }
-
- const newPattern: Pattern = {
- patternId: `pat_${Date.now()}_${i}_${Math.random().toString(36).slice(2, 6)}`,
- name: `${pattern.name}_split_${i}`,
- domain: pattern.domain,
- embedding: newEmbedding,
- strategy: pattern.strategy,
- successRate: pattern.successRate * 0.9, // Slight penalty for uncertainty
- usageCount: 0,
- qualityHistory: [],
- evolutionHistory: [{
- timestamp: Date.now(),
- type: 'split',
- previousQuality: pattern.successRate,
- newQuality: pattern.successRate * 0.9,
- description: `Split from pattern ${patternId}`,
- }],
- createdAt: Date.now(),
- updatedAt: Date.now(),
- };
-
- this.patterns.set(newPattern.patternId, newPattern);
- splits.push(newPattern);
- }
-
- // Remove original pattern
- this.patterns.delete(patternId);
- this.patternToCluster.delete(patternId);
-
- // Rebuild clusters
- if (this.config.enableClustering) {
- this.rebuildClusters();
- }
-
- return splits;
- }
-
- // ==========================================================================
- // Pattern Access
- // ==========================================================================
-
- /**
- * Get all patterns
- */
- getPatterns(): Pattern[] {
- return Array.from(this.patterns.values());
- }
-
- /**
- * Get pattern by ID
- */
- getPattern(patternId: string): Pattern | undefined {
- return this.patterns.get(patternId);
- }
-
- /**
- * Get patterns by domain
- */
- getPatternsByDomain(domain: string): Pattern[] {
- return Array.from(this.patterns.values()).filter(p => p.domain === domain);
- }
-
- /**
- * Get stable patterns (sufficient usage)
- */
- getStablePatterns(): Pattern[] {
- return Array.from(this.patterns.values())
- .filter(p => p.usageCount >= this.config.minUsagesForStable);
- }
-
- // ==========================================================================
- // Statistics
- // ==========================================================================
-
- getStats(): Record<string, number> {
- const patterns = Array.from(this.patterns.values());
-
- return {
- totalPatterns: this.patterns.size,
- stablePatterns: patterns.filter(p => p.usageCount >= this.config.minUsagesForStable).length,
- avgSuccessRate: patterns.length > 0
- ? patterns.reduce((s, p) => s + p.successRate, 0) / patterns.length
- : 0,
- avgUsageCount: patterns.length > 0
- ? patterns.reduce((s, p) => s + p.usageCount, 0) / patterns.length
- : 0,
- numClusters: this.clusters.length,
- avgMatchTimeMs: this.matchCount > 0 ? this.totalMatchTime / this.matchCount : 0,
- avgExtractionTimeMs: this.extractionCount > 0 ? this.totalExtractionTime / this.extractionCount : 0,
- avgEvolutionTimeMs: this.evolutionCount > 0 ? this.totalEvolutionTime / this.evolutionCount : 0,
- };
- }
-
- // ==========================================================================
- // Event System
- // ==========================================================================
-
- addEventListener(listener: NeuralEventListener): void {
- this.eventListeners.add(listener);
- }
-
- removeEventListener(listener: NeuralEventListener): void {
- this.eventListeners.delete(listener);
- }
-
- private emitEvent(event: NeuralEvent): void {
- for (const listener of this.eventListeners) {
- try {
- listener(event);
- } catch (error) {
- console.error('Error in PatternLearner event listener:', error);
- }
- }
- }
-
- // ==========================================================================
- // Private Helper Methods
- // ==========================================================================
-
- private cosineSimilarity(a: Float32Array, b: Float32Array): number {
- if (a.length !== b.length) return 0;
-
- let dot = 0, normA = 0, normB = 0;
- for (let i = 0; i < a.length; i++) {
- dot += a[i] * b[i];
- normA += a[i] * a[i];
- normB += b[i] * b[i];
- }
-
- const denom = Math.sqrt(normA) * Math.sqrt(normB);
- return denom > 0 ? dot / denom : 0;
- }
-
- private computeMatchConfidence(pattern: Pattern, similarity: number): number {
- // Combine similarity with pattern reliability
- const usageWeight = Math.min(pattern.usageCount / 10, 1);
- const qualityWeight = pattern.successRate;
-
- return similarity * (1 - usageWeight * 0.2 - qualityWeight * 0.2) +
- usageWeight * 0.1 +
- qualityWeight * 0.1;
- }
-
- private getCandidatesFromClusters(queryEmbedding: Float32Array): Pattern[] {
- // Find nearest clusters
- const clusterScores: Array<{ cluster: PatternCluster; score: number }> = [];
-
- for (const cluster of this.clusters) {
- const score = this.cosineSimilarity(queryEmbedding, cluster.centroid);
- clusterScores.push({ cluster, score });
- }
-
- clusterScores.sort((a, b) => b.score - a.score);
-
- // Get patterns from top 3 clusters
- const candidates: Pattern[] = [];
- for (const { cluster } of clusterScores.slice(0, 3)) {
- for (const patternId of cluster.patternIds) {
- const pattern = this.patterns.get(patternId);
- if (pattern) {
- candidates.push(pattern);
- }
- }
- }
-
- return candidates;
- }
-
- private findSimilarPattern(embedding: Float32Array, threshold: number): Pattern | null {
- for (const pattern of this.patterns.values()) {
- const sim = this.cosineSimilarity(embedding, pattern.embedding);
- if (sim >= threshold) {
- return pattern;
- }
- }
- return null;
- }
-
- private updatePatternFromTrajectory(pattern: Pattern, trajectory: Trajectory): void {
- // Update quality
- pattern.qualityHistory.push(trajectory.qualityScore);
- if (pattern.qualityHistory.length > 100) {
- pattern.qualityHistory = pattern.qualityHistory.slice(-100);
- }
-
- // EMA for success rate
- const lr = this.config.evolutionLearningRate;
- pattern.successRate = pattern.successRate * (1 - lr) + trajectory.qualityScore * lr;
- pattern.usageCount++;
- pattern.updatedAt = Date.now();
- }
-
- private computePatternEmbedding(trajectory: Trajectory): Float32Array {
- if (trajectory.steps.length === 0) {
- return new Float32Array(768);
- }
-
- const dim = trajectory.steps[0].stateAfter.length;
- const embedding = new Float32Array(dim);
-
- // Weighted average (higher weight for later steps)
- let totalWeight = 0;
- for (let i = 0; i < trajectory.steps.length; i++) {
- const weight = (i + 1) / trajectory.steps.length;
- totalWeight += weight;
- for (let j = 0; j < dim; j++) {
- embedding[j] += trajectory.steps[i].stateAfter[j] * weight;
- }
- }
-
- for (let j = 0; j < dim; j++) {
- embedding[j] /= totalWeight;
- }
-
- return embedding;
- }
-
- private generatePatternName(trajectory: Trajectory): string {
- const domain = trajectory.domain;
- const quality = trajectory.qualityScore > 0.7 ? 'high' : 'mid';
- const steps = trajectory.steps.length > 5 ? 'complex' : 'simple';
- return `${domain}_${quality}_${steps}_${Date.now() % 10000}`;
- }
-
- private extractStrategy(trajectory: Trajectory): string {
- const actions = trajectory.steps.map(s => s.action);
- if (actions.length === 0) return 'empty';
- if (actions.length <= 3) return actions.join(' -> ');
- return `${actions.slice(0, 2).join(' -> ')} ... ${actions[actions.length - 1]}`;
- }
-
- private assignToCluster(pattern: Pattern): void {
- if (this.clusters.length === 0) {
- // Create first cluster
- this.clusters.push({
- clusterId: 0,
- centroid: new Float32Array(pattern.embedding),
- patternIds: new Set([pattern.patternId]),
- });
- this.patternToCluster.set(pattern.patternId, 0);
- return;
- }
-
- // Find nearest cluster
- let bestCluster = 0;
- let bestSim = -1;
-
- for (let i = 0; i < this.clusters.length; i++) {
- const sim = this.cosineSimilarity(pattern.embedding, this.clusters[i].centroid);
- if (sim > bestSim) {
- bestSim = sim;
- bestCluster = i;
- }
- }
-
- // Create new cluster if not similar enough and under limit
- if (bestSim < 0.7 && this.clusters.length < this.config.numClusters) {
- const newId = this.clusters.length;
- this.clusters.push({
- clusterId: newId,
- centroid: new Float32Array(pattern.embedding),
- patternIds: new Set([pattern.patternId]),
- });
- this.patternToCluster.set(pattern.patternId, newId);
- } else {
- // Add to existing cluster and update centroid
- const cluster = this.clusters[bestCluster];
- cluster.patternIds.add(pattern.patternId);
- this.patternToCluster.set(pattern.patternId, bestCluster);
- this.updateClusterCentroid(cluster);
- }
- }
-
- private updateClusterCentroid(cluster: PatternCluster): void {
- const dim = cluster.centroid.length;
- const newCentroid = new Float32Array(dim);
- let count = 0;
-
- for (const patternId of cluster.patternIds) {
- const pattern = this.patterns.get(patternId);
- if (pattern) {
- for (let i = 0; i < dim; i++) {
- newCentroid[i] += pattern.embedding[i];
- }
- count++;
- }
- }
-
- if (count > 0) {
- for (let i = 0; i < dim; i++) {
- newCentroid[i] /= count;
- }
- cluster.centroid = newCentroid;
- }
- }
-
- private rebuildClusters(): void {
- if (this.patterns.size === 0) {
- this.clusters = [];
- this.patternToCluster.clear();
- return;
- }
-
- const patterns = Array.from(this.patterns.values());
- const k = Math.min(this.config.numClusters, Math.ceil(patterns.length / 5));
- const dim = patterns[0].embedding.length;
-
- // Initialize clusters with random patterns
- this.clusters = [];
- this.patternToCluster.clear();
-
- const indices = new Set<number>();
- while (indices.size < k && indices.size < patterns.length) {
- indices.add(Math.floor(Math.random() * patterns.length));
- }
-
- let clusterId = 0;
- for (const idx of indices) {
- this.clusters.push({
- clusterId: clusterId++,
- centroid: new Float32Array(patterns[idx].embedding),
- patternIds: new Set(),
- });
- }
-
- // K-means iterations
- for (let iter = 0; iter < 10; iter++) {
- // Clear assignments
- for (const cluster of this.clusters) {
- cluster.patternIds.clear();
- }
-
- // Assign patterns to nearest cluster
- for (const pattern of patterns) {
- let bestCluster = 0;
- let bestSim = -1;
-
- for (let c = 0; c < this.clusters.length; c++) {
- const sim = this.cosineSimilarity(pattern.embedding, this.clusters[c].centroid);
- if (sim > bestSim) {
- bestSim = sim;
- bestCluster = c;
- }
- }
-
- this.clusters[bestCluster].patternIds.add(pattern.patternId);
- this.patternToCluster.set(pattern.patternId, bestCluster);
- }
-
- // Update centroids
- for (const cluster of this.clusters) {
- this.updateClusterCentroid(cluster);
- }
- }
-
- // Remove empty clusters
- this.clusters = this.clusters.filter(c => c.patternIds.size > 0);
- }
-
- private prunePatterns(): void {
- // Sort by score (quality * log(usage))
- const scored = Array.from(this.patterns.entries())
- .map(([id, pattern]) => ({
- id,
- pattern,
- score: pattern.successRate * Math.log(pattern.usageCount + 1),
- }))
- .sort((a, b) => a.score - b.score);
-
- // Remove lowest scoring patterns
- const toRemove = scored.length - Math.floor(this.config.maxPatterns * 0.8);
- for (let i = 0; i < toRemove && i < scored.length; i++) {
- this.patterns.delete(scored[i].id);
- this.patternToCluster.delete(scored[i].id);
- }
-
- // Rebuild clusters
- if (this.config.enableClustering) {
- this.rebuildClusters();
- }
- }
-
- private determineEvolutionType(
- prev: number,
- curr: number
- ): 'improvement' | 'merge' | 'split' | 'prune' {
- const delta = curr - prev;
- if (delta > 0.05) return 'improvement';
- if (delta < -0.15) return 'prune';
- return 'improvement';
- }
-}
-
-/**
- * Factory function for creating PatternLearner
- */
-export function createPatternLearner(
- config?: Partial<PatternLearnerConfig>
-): PatternLearner {
- return new PatternLearner(config);
-}
diff --git a/v3/neural/reasoning-bank.ts b/v3/neural/reasoning-bank.ts
deleted file mode 100644
index 4d93761cc8..0000000000
--- a/v3/neural/reasoning-bank.ts
+++ /dev/null
@@ -1,824 +0,0 @@
-/**
- * ReasoningBank Integration
- *
- * Implements the 4-step learning pipeline:
- * 1. RETRIEVE - Top-k memory injection with MMR diversity
- * 2. JUDGE - LLM-as-judge trajectory evaluation
- * 3. DISTILL - Extract strategy memories from trajectories
- * 4. CONSOLIDATE - Dedup, detect contradictions, prune old patterns
- *
- * Performance Target: <10ms for learning step
- */
-
-import type {
- Trajectory,
- TrajectoryStep,
- TrajectoryVerdict,
- DistilledMemory,
- Pattern,
- PatternEvolution,
- NeuralEvent,
- NeuralEventListener,
-} from './types.js';
-
-/**
- * Configuration for ReasoningBank
- */
-export interface ReasoningBankConfig {
- /** Maximum number of trajectories to store */
- maxTrajectories: number;
-
- /** Minimum quality threshold for distillation */
- distillationThreshold: number;
-
- /** Number of similar memories to retrieve */
- retrievalK: number;
-
- /** Diversity factor for MMR (0-1) */
- mmrLambda: number;
-
- /** Maximum age of patterns in days */
- maxPatternAgeDays: number;
-
- /** Similarity threshold for deduplication */
- dedupThreshold: number;
-
- /** Enable contradiction detection */
- enableContradictionDetection: boolean;
-}
-
-/**
- * Default ReasoningBank configuration
- */
-const DEFAULT_CONFIG: ReasoningBankConfig = {
- maxTrajectories: 5000,
- distillationThreshold: 0.6,
- retrievalK: 3,
- mmrLambda: 0.7,
- maxPatternAgeDays: 30,
- dedupThreshold: 0.95,
- enableContradictionDetection: true,
-};
-
-/**
- * Memory entry with metadata
- */
-interface MemoryEntry {
- memory: DistilledMemory;
- trajectory: Trajectory;
- verdict: TrajectoryVerdict;
- consolidated: boolean;
-}
-
-/**
- * Retrieval result with diversity scoring
- */
-export interface RetrievalResult {
- memory: DistilledMemory;
- relevanceScore: number;
- diversityScore: number;
- combinedScore: number;
-}
-
-/**
- * Consolidation result
- */
-export interface ConsolidationResult {
- removedDuplicates: number;
- contradictionsDetected: number;
- prunedPatterns: number;
- mergedPatterns: number;
-}
-
-/**
- * ReasoningBank - Trajectory storage and learning pipeline
- */
-export class ReasoningBank {
- private config: ReasoningBankConfig;
- private trajectories: Map<string, Trajectory> = new Map();
- private memories: Map<string, MemoryEntry> = new Map();
- private patterns: Map<string, Pattern> = new Map();
- private eventListeners: Set<NeuralEventListener> = new Set();
-
- // Performance tracking
- private retrievalCount = 0;
- private totalRetrievalTime = 0;
- private distillationCount = 0;
- private totalDistillationTime = 0;
-
- constructor(config: Partial<ReasoningBankConfig> = {}) {
- this.config = { ...DEFAULT_CONFIG, ...config };
- }
-
- // ==========================================================================
- // STEP 1: RETRIEVE - Top-k memory injection with MMR diversity
- // ==========================================================================
-
- /**
- * Retrieve relevant memories using Maximal Marginal Relevance (MMR)
- */
- async retrieve(queryEmbedding: Float32Array, k?: number): Promise<RetrievalResult[]> {
- const startTime = performance.now();
- const retrieveK = k ?? this.config.retrievalK;
-
- if (this.memories.size === 0) {
- return [];
- }
-
- // Get all memories with relevance scores
- const candidates: Array<{ entry: MemoryEntry; relevance: number }> = [];
-
- for (const entry of this.memories.values()) {
- const relevance = this.cosineSimilarity(queryEmbedding, entry.memory.embedding);
- candidates.push({ entry, relevance });
- }
-
- // Sort by relevance
- candidates.sort((a, b) => b.relevance - a.relevance);
-
- // Apply MMR for diversity
- const results: RetrievalResult[] = [];
- const selected: MemoryEntry[] = [];
-
- while (results.length < retrieveK && candidates.length > 0) {
- let bestIdx = 0;
- let bestScore = -Infinity;
-
- for (let i = 0; i < candidates.length; i++) {
- const candidate = candidates[i];
-
- // Compute MMR score: lambda * relevance - (1 - lambda) * max_similarity_to_selected
- const relevance = candidate.relevance;
- let maxSimilarity = 0;
-
- for (const sel of selected) {
- const sim = this.cosineSimilarity(
- candidate.entry.memory.embedding,
- sel.memory.embedding
- );
- maxSimilarity = Math.max(maxSimilarity, sim);
- }
-
- const diversityScore = 1 - maxSimilarity;
- const mmrScore = this.config.mmrLambda * relevance +
- (1 - this.config.mmrLambda) * diversityScore;
-
- if (mmrScore > bestScore) {
- bestScore = mmrScore;
- bestIdx = i;
- }
- }
-
- // Add best candidate
- const best = candidates[bestIdx];
- selected.push(best.entry);
- results.push({
- memory: best.entry.memory,
- relevanceScore: best.relevance,
- diversityScore: 1 - this.computeMaxSimilarity(best.entry, selected.slice(0, -1)),
- combinedScore: bestScore,
- });
-
- // Remove from candidates
- candidates.splice(bestIdx, 1);
- }
-
- // Update stats
- this.retrievalCount++;
- this.totalRetrievalTime += performance.now() - startTime;
-
- return results;
- }
-
- // ==========================================================================
- // STEP 2: JUDGE - LLM-as-judge trajectory evaluation
- // ==========================================================================
-
- /**
- * Judge a trajectory and produce a verdict
- */
- async judge(trajectory: Trajectory): Promise<TrajectoryVerdict> {
- if (!trajectory.isComplete) {
- throw new Error('Cannot judge incomplete trajectory');
- }
-
- // Analyze trajectory steps
- const stepAnalysis = this.analyzeSteps(trajectory.steps);
-
- // Compute success based on quality and step analysis
- const success = trajectory.qualityScore >= this.config.distillationThreshold &&
- stepAnalysis.positiveRatio > 0.6;
-
- // Identify strengths and weaknesses
- const strengths = this.identifyStrengths(trajectory, stepAnalysis);
- const weaknesses = this.identifyWeaknesses(trajectory, stepAnalysis);
-
- // Generate improvement suggestions
- const improvements = this.generateImprovements(weaknesses);
-
- // Compute relevance for similar future tasks
- const relevanceScore = this.computeRelevanceScore(trajectory);
-
- const verdict: TrajectoryVerdict = {
- success,
- confidence: this.computeConfidence(trajectory, stepAnalysis),
- strengths,
- weaknesses,
- improvements,
- relevanceScore,
- };
-
- // Store verdict with trajectory
- trajectory.verdict = verdict;
-
- return verdict;
- }
-
- // ==========================================================================
- // STEP 3: DISTILL - Extract strategy memories from trajectories
- // ==========================================================================
-
- /**
- * Distill a trajectory into a reusable memory
- */
- async distill(trajectory: Trajectory): Promise<DistilledMemory | null> {
- const startTime = performance.now();
-
- // Must be judged first
- if (!trajectory.verdict) {
- await this.judge(trajectory);
- }
-
- // Only distill successful trajectories
- if (!trajectory.verdict!.success ||
- trajectory.qualityScore < this.config.distillationThreshold) {
- return null;
- }
-
- // Extract strategy from trajectory
- const strategy = this.extractStrategy(trajectory);
-
- // Extract key learnings
- const keyLearnings = this.extractKeyLearnings(trajectory);
-
- // Compute aggregated embedding
- const embedding = this.computeAggregateEmbedding(trajectory);
-
- const memory: DistilledMemory = {
- memoryId: `mem_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
- trajectoryId: trajectory.trajectoryId,
- strategy,
- keyLearnings,
- embedding,
- quality: trajectory.qualityScore,
- usageCount: 0,
- lastUsed: Date.now(),
- };
-
- // Store the memory
- const entry: MemoryEntry = {
- memory,
- trajectory,
- verdict: trajectory.verdict!,
- consolidated: false,
- };
- this.memories.set(memory.memoryId, entry);
-
- // Also store trajectory reference
- trajectory.distilledMemory = memory;
-
- // Update stats
- this.distillationCount++;
- this.totalDistillationTime += performance.now() - startTime;
-
- return memory;
- }
-
- // ==========================================================================
- // STEP 4: CONSOLIDATE - Dedup, detect contradictions, prune old patterns
- // ==========================================================================
-
- /**
- * Consolidate memories: deduplicate, detect contradictions, prune old
- */
- async consolidate(): Promise<ConsolidationResult> {
- const result: ConsolidationResult = {
- removedDuplicates: 0,
- contradictionsDetected: 0,
- prunedPatterns: 0,
- mergedPatterns: 0,
- };
-
- // 1. Deduplicate similar memories
- result.removedDuplicates = await this.deduplicateMemories();
-
- // 2. Detect contradictions
- if (this.config.enableContradictionDetection) {
- result.contradictionsDetected = await this.detectContradictions();
- }
-
- // 3. Prune old patterns
- result.prunedPatterns = await this.pruneOldPatterns();
-
- // 4. Merge similar patterns
- result.mergedPatterns = await this.mergePatterns();
-
- // Emit consolidation event
- this.emitEvent({
- type: 'memory_consolidated',
- memoriesCount: this.memories.size,
- });
-
- return result;
- }
-
- // ==========================================================================
- // Pattern Management
- // ==========================================================================
-
- /**
- * Convert a distilled memory to a pattern
- */
- memoryToPattern(memory: DistilledMemory): Pattern {
- const pattern: Pattern = {
- patternId: `pat_${memory.memoryId}`,
- name: this.generatePatternName(memory),
- domain: this.inferDomain(memory),
- embedding: memory.embedding,
- strategy: memory.strategy,
- successRate: memory.quality,
- usageCount: memory.usageCount,
- qualityHistory: [memory.quality],
- evolutionHistory: [],
- createdAt: Date.now(),
- updatedAt: Date.now(),
- };
-
- this.patterns.set(pattern.patternId, pattern);
- return pattern;
- }
-
- /**
- * Evolve a pattern based on new experience
- */
- evolvePattern(patternId: string, newExperience: Trajectory): void {
- const pattern = this.patterns.get(patternId);
- if (!pattern) return;
-
- const previousQuality = pattern.successRate;
-
- // Update quality history
- pattern.qualityHistory.push(newExperience.qualityScore);
- if (pattern.qualityHistory.length > 100) {
- pattern.qualityHistory = pattern.qualityHistory.slice(-100);
- }
-
- // Update success rate
- pattern.successRate = pattern.qualityHistory.reduce((a, b) => a + b, 0) /
- pattern.qualityHistory.length;
-
- pattern.usageCount++;
- pattern.updatedAt = Date.now();
-
- // Record evolution
- const evolutionType = this.determineEvolutionType(previousQuality, pattern.successRate);
- pattern.evolutionHistory.push({
- timestamp: Date.now(),
- type: evolutionType,
- previousQuality,
- newQuality: pattern.successRate,
- description: `Updated based on trajectory ${newExperience.trajectoryId}`,
- });
-
- // Emit event
- this.emitEvent({
- type: 'pattern_evolved',
- patternId,
- evolutionType,
- });
- }
-
- /**
- * Get all patterns
- */
- getPatterns(): Pattern[] {
- return Array.from(this.patterns.values());
- }
-
- // ==========================================================================
- // Trajectory Management
- // ==========================================================================
-
- /**
- * Store a trajectory
- */
- storeTrajectory(trajectory: Trajectory): void {
- this.trajectories.set(trajectory.trajectoryId, trajectory);
-
- // Prune if over capacity
- if (this.trajectories.size > this.config.maxTrajectories) {
- this.pruneTrajectories();
- }
- }
-
- /**
- * Get trajectory by ID
- */
- getTrajectory(trajectoryId: string): Trajectory | undefined {
- return this.trajectories.get(trajectoryId);
- }
-
- /**
- * Get all trajectories
- */
- getTrajectories(): Trajectory[] {
- return Array.from(this.trajectories.values());
- }
-
- // ==========================================================================
- // Statistics
- // ==========================================================================
-
- /**
- * Get ReasoningBank statistics
- */
- getStats(): Record<string, number> {
- return {
- trajectoryCount: this.trajectories.size,
- memoryCount: this.memories.size,
- patternCount: this.patterns.size,
- avgRetrievalTimeMs: this.retrievalCount > 0
- ? this.totalRetrievalTime / this.retrievalCount
- : 0,
- avgDistillationTimeMs: this.distillationCount > 0
- ? this.totalDistillationTime / this.distillationCount
- : 0,
- consolidatedMemories: Array.from(this.memories.values())
- .filter(e => e.consolidated).length,
- };
- }
-
- // ==========================================================================
- // Event System
- // ==========================================================================
-
- addEventListener(listener: NeuralEventListener): void {
- this.eventListeners.add(listener);
- }
-
- removeEventListener(listener: NeuralEventListener): void {
- this.eventListeners.delete(listener);
- }
-
- private emitEvent(event: NeuralEvent): void {
- for (const listener of this.eventListeners) {
- try {
- listener(event);
- } catch (error) {
- console.error('Error in ReasoningBank event listener:', error);
- }
- }
- }
-
- // ==========================================================================
- // Private Helper Methods
- // ==========================================================================
-
- private cosineSimilarity(a: Float32Array, b: Float32Array): number {
- if (a.length !== b.length) return 0;
-
- let dot = 0, normA = 0, normB = 0;
- for (let i = 0; i < a.length; i++) {
- dot += a[i] * b[i];
- normA += a[i] * a[i];
- normB += b[i] * b[i];
- }
-
- const denom = Math.sqrt(normA) * Math.sqrt(normB);
- return denom > 0 ? dot / denom : 0;
- }
-
- private computeMaxSimilarity(entry: MemoryEntry, selected: MemoryEntry[]): number {
- let maxSim = 0;
- for (const sel of selected) {
- const sim = this.cosineSimilarity(entry.memory.embedding, sel.memory.embedding);
- maxSim = Math.max(maxSim, sim);
- }
- return maxSim;
- }
-
- private analyzeSteps(steps: TrajectoryStep[]): StepAnalysis {
- const rewardSum = steps.reduce((s, step) => s + step.reward, 0);
- const positiveSteps = steps.filter(s => s.reward > 0.5).length;
-
- return {
- totalSteps: steps.length,
- avgReward: steps.length > 0 ? rewardSum / steps.length : 0,
- positiveRatio: steps.length > 0 ? positiveSteps / steps.length : 0,
- trajectory: steps.length > 1
- ? (steps[steps.length - 1].reward - steps[0].reward)
- : 0,
- };
- }
-
- private identifyStrengths(trajectory: Trajectory, analysis: StepAnalysis): string[] {
- const strengths: string[] = [];
-
- if (analysis.avgReward > 0.7) {
- strengths.push('High average reward across steps');
- }
- if (analysis.trajectory > 0.2) {
- strengths.push('Positive reward trajectory');
- }
- if (trajectory.qualityScore > 0.8) {
- strengths.push('High overall quality');
- }
- if (analysis.totalSteps < 5 && trajectory.qualityScore > 0.6) {
- strengths.push('Efficient solution (few steps)');
- }
-
- return strengths;
- }
-
- private identifyWeaknesses(trajectory: Trajectory, analysis: StepAnalysis): string[] {
- const weaknesses: string[] = [];
-
- if (analysis.avgReward < 0.4) {
- weaknesses.push('Low average reward');
- }
- if (analysis.trajectory < -0.1) {
- weaknesses.push('Declining reward trajectory');
- }
- if (analysis.positiveRatio < 0.5) {
- weaknesses.push('Many negative/neutral steps');
- }
- if (analysis.totalSteps > 10 && trajectory.qualityScore < 0.7) {
- weaknesses.push('Long trajectory with mediocre outcome');
- }
-
- return weaknesses;
- }
-
- private generateImprovements(weaknesses: string[]): string[] {
- const improvements: string[] = [];
-
- for (const weakness of weaknesses) {
- if (weakness.includes('Low average reward')) {
- improvements.push('Consider alternative strategies for each step');
- }
- if (weakness.includes('Declining')) {
- improvements.push('Re-evaluate approach when reward decreases');
- }
- if (weakness.includes('negative/neutral')) {
- improvements.push('Focus on steps with clearer positive signals');
- }
- if (weakness.includes('Long trajectory')) {
- improvements.push('Look for shortcuts or more direct approaches');
- }
- }
-
- return improvements;
- }
-
- private computeRelevanceScore(trajectory: Trajectory): number {
- // Base relevance on quality and recency
- const qualityFactor = trajectory.qualityScore;
- const ageDays = (Date.now() - trajectory.startTime) / (1000 * 60 * 60 * 24);
- const recencyFactor = Math.exp(-ageDays / 30); // Decay over 30 days
-
- return qualityFactor * 0.7 + recencyFactor * 0.3;
- }
-
- private computeConfidence(trajectory: Trajectory, analysis: StepAnalysis): number {
- // More steps = more confidence
- const stepFactor = Math.min(analysis.totalSteps / 10, 1);
- // Consistent rewards = more confidence
- const consistencyFactor = analysis.positiveRatio;
- // Clear outcome = more confidence
- const outcomeFactor = Math.abs(trajectory.qualityScore - 0.5) * 2;
-
- return (stepFactor * 0.3 + consistencyFactor * 0.4 + outcomeFactor * 0.3);
- }
-
- private extractStrategy(trajectory: Trajectory): string {
- const actions = trajectory.steps.map(s => s.action);
- const uniqueActions = [...new Set(actions)];
-
- if (uniqueActions.length <= 3) {
- return `Apply ${uniqueActions.join(' -> ')}`;
- }
-
- return `Multi-step approach: ${uniqueActions.slice(0, 3).join(', ')}...`;
- }
-
- private extractKeyLearnings(trajectory: Trajectory): string[] {
- const learnings: string[] = [];
- const verdict = trajectory.verdict!;
-
- // Add key success factors
- if (verdict.success) {
- learnings.push(`Successful approach for ${trajectory.domain} domain`);
- for (const strength of verdict.strengths.slice(0, 2)) {
- learnings.push(`Strength: ${strength}`);
- }
- } else {
- learnings.push(`Approach needs refinement`);
- for (const improvement of verdict.improvements.slice(0, 2)) {
- learnings.push(`Improvement: ${improvement}`);
- }
- }
-
- return learnings;
- }
-
- private computeAggregateEmbedding(trajectory: Trajectory): Float32Array {
- if (trajectory.steps.length === 0) {
- return new Float32Array(768);
- }
-
- const dim = trajectory.steps[0].stateAfter.length;
- const aggregate = new Float32Array(dim);
-
- // Weighted average of step embeddings (higher weight for later steps)
- let totalWeight = 0;
- for (let i = 0; i < trajectory.steps.length; i++) {
- const weight = (i + 1) / trajectory.steps.length;
- totalWeight += weight;
- const step = trajectory.steps[i];
- for (let j = 0; j < dim; j++) {
- aggregate[j] += step.stateAfter[j] * weight;
- }
- }
-
- // Normalize
- for (let j = 0; j < dim; j++) {
- aggregate[j] /= totalWeight;
- }
-
- return aggregate;
- }
-
- private async deduplicateMemories(): Promise<number> {
- let removed = 0;
- const entries = Array.from(this.memories.entries());
-
- for (let i = 0; i < entries.length; i++) {
- for (let j = i + 1; j < entries.length; j++) {
- const sim = this.cosineSimilarity(
- entries[i][1].memory.embedding,
- entries[j][1].memory.embedding
- );
-
- if (sim > this.config.dedupThreshold) {
- // Keep the higher quality one
- if (entries[i][1].memory.quality >= entries[j][1].memory.quality) {
- this.memories.delete(entries[j][0]);
- } else {
- this.memories.delete(entries[i][0]);
- }
- removed++;
- }
- }
- }
-
- return removed;
- }
-
- private async detectContradictions(): Promise<number> {
- let contradictions = 0;
- const entries = Array.from(this.memories.values());
-
- for (let i = 0; i < entries.length; i++) {
- for (let j = i + 1; j < entries.length; j++) {
- // Similar context but opposite outcomes
- const sim = this.cosineSimilarity(
- entries[i].memory.embedding,
- entries[j].memory.embedding
- );
-
- if (sim > 0.8) {
- const qualityDiff = Math.abs(
- entries[i].memory.quality - entries[j].memory.quality
- );
-
- if (qualityDiff > 0.4) {
- contradictions++;
- // Mark lower quality as consolidated (to exclude from retrieval)
- if (entries[i].memory.quality < entries[j].memory.quality) {
- entries[i].consolidated = true;
- } else {
- entries[j].consolidated = true;
- }
- }
- }
- }
- }
-
- return contradictions;
- }
-
- private async pruneOldPatterns(): Promise<number> {
- const now = Date.now();
- const maxAge = this.config.maxPatternAgeDays * 24 * 60 * 60 * 1000;
- let pruned = 0;
-
- for (const [id, pattern] of this.patterns) {
- const age = now - pattern.updatedAt;
- if (age > maxAge && pattern.usageCount < 5) {
- this.patterns.delete(id);
- pruned++;
- }
- }
-
- return pruned;
- }
-
- private async mergePatterns(): Promise<number> {
- let merged = 0;
- const patterns = Array.from(this.patterns.entries());
-
- for (let i = 0; i < patterns.length; i++) {
- for (let j = i + 1; j < patterns.length; j++) {
- const sim = this.cosineSimilarity(
- patterns[i][1].embedding,
- patterns[j][1].embedding
- );
-
- if (sim > 0.9 && patterns[i][1].domain === patterns[j][1].domain) {
- // Merge into higher quality pattern
- const [keepId, keep] = patterns[i][1].successRate >= patterns[j][1].successRate
- ? patterns[i]
- : patterns[j];
- const [removeId, remove] = patterns[i][1].successRate < patterns[j][1].successRate
- ? patterns[i]
- : patterns[j];
-
- // Combine statistics
- keep.usageCount += remove.usageCount;
- keep.qualityHistory.push(...remove.qualityHistory);
- keep.evolutionHistory.push({
- timestamp: Date.now(),
- type: 'merge',
- previousQuality: keep.successRate,
- newQuality: (keep.successRate + remove.successRate) / 2,
- description: `Merged with pattern ${removeId}`,
- });
-
- this.patterns.delete(removeId);
- merged++;
- }
- }
- }
-
- return merged;
- }
-
- private pruneTrajectories(): void {
- const entries = Array.from(this.trajectories.entries())
- .sort((a, b) => a[1].qualityScore - b[1].qualityScore);
-
- const toRemove = entries.length - Math.floor(this.config.maxTrajectories * 0.8);
- for (let i = 0; i < toRemove && i < entries.length; i++) {
- this.trajectories.delete(entries[i][0]);
- }
- }
-
- private generatePatternName(memory: DistilledMemory): string {
- const words = memory.strategy.split(' ').slice(0, 4);
- return words.join('_').toLowerCase().replace(/[^a-z0-9_]/g, '');
- }
-
- private inferDomain(memory: DistilledMemory): string {
- const trajectory = this.trajectories.get(memory.trajectoryId);
- return trajectory?.domain || 'general';
- }
-
- private determineEvolutionType(
- prev: number,
- curr: number
- ): 'improvement' | 'merge' | 'split' | 'prune' {
- const delta = curr - prev;
- if (delta > 0.05) return 'improvement';
- if (delta < -0.1) return 'prune';
- return 'improvement';
- }
-}
-
-/**
- * Step analysis result
- */
-interface StepAnalysis {
- totalSteps: number;
- avgReward: number;
- positiveRatio: number;
- trajectory: number;
-}
-
-/**
- * Factory function for creating ReasoningBank
- */
-export function createReasoningBank(
- config?: Partial<ReasoningBankConfig>
-): ReasoningBank {
- return new ReasoningBank(config);
-}
diff --git a/v3/neural/sona-manager.ts b/v3/neural/sona-manager.ts
deleted file mode 100644
index 6259b6b6b2..0000000000
--- a/v3/neural/sona-manager.ts
+++ /dev/null
@@ -1,835 +0,0 @@
-/**
- * SONA Manager - Self-Optimizing Neural Architecture
- *
- * Manages learning modes and provides adaptive optimization for agent tasks.
- *
- * Performance Targets:
- * - Adaptation: <0.05ms
- * - Pattern retrieval: <1ms
- * - Learning step: <10ms
- *
- * Supported Modes:
- * - real-time: Sub-millisecond adaptation (2200 ops/sec)
- * - balanced: General purpose (+25% quality)
- * - research: Deep exploration (+55% quality)
- * - edge: Resource-constrained (<5MB)
- * - batch: High-throughput processing
- */
-
-import type {
- SONAMode,
- SONAModeConfig,
- ModeOptimizations,
- Trajectory,
- TrajectoryStep,
- Pattern,
- PatternMatch,
- NeuralStats,
- NeuralEvent,
- NeuralEventListener,
- LoRAConfig,
- LoRAWeights,
- EWCConfig,
- EWCState,
- RLAlgorithm,
-} from './types.js';
-
-import { RealTimeMode } from './modes/real-time.js';
-import { BalancedMode } from './modes/balanced.js';
-import { ResearchMode } from './modes/research.js';
-import { EdgeMode } from './modes/edge.js';
-import { BatchMode } from './modes/batch.js';
-import type { ModeImplementation } from './modes/index.js';
-
-/**
- * Default mode configurations
- */
-const MODE_CONFIGS: Record<SONAMode, SONAModeConfig> = {
- 'real-time': {
- mode: 'real-time',
- loraRank: 2,
- learningRate: 0.001,
- batchSize: 32,
- trajectoryCapacity: 1000,
- patternClusters: 25,
- qualityThreshold: 0.7,
- maxLatencyMs: 0.5,
- memoryBudgetMb: 25,
- ewcLambda: 2000,
- },
- 'balanced': {
- mode: 'balanced',
- loraRank: 4,
- learningRate: 0.002,
- batchSize: 32,
- trajectoryCapacity: 3000,
- patternClusters: 50,
- qualityThreshold: 0.5,
- maxLatencyMs: 18,
- memoryBudgetMb: 50,
- ewcLambda: 2000,
- },
- 'research': {
- mode: 'research',
- loraRank: 16,
- learningRate: 0.002,
- batchSize: 64,
- trajectoryCapacity: 10000,
- patternClusters: 100,
- qualityThreshold: 0.2,
- maxLatencyMs: 100,
- memoryBudgetMb: 100,
- ewcLambda: 2500,
- },
- 'edge': {
- mode: 'edge',
- loraRank: 1,
- learningRate: 0.001,
- batchSize: 16,
- trajectoryCapacity: 200,
- patternClusters: 15,
- qualityThreshold: 0.8,
- maxLatencyMs: 1,
- memoryBudgetMb: 5,
- ewcLambda: 1500,
- },
- 'batch': {
- mode: 'batch',
- loraRank: 8,
- learningRate: 0.002,
- batchSize: 128,
- trajectoryCapacity: 5000,
- patternClusters: 75,
- qualityThreshold: 0.4,
- maxLatencyMs: 50,
- memoryBudgetMb: 75,
- ewcLambda: 2000,
- },
-};
-
-/**
- * Mode-specific optimizations
- */
-const MODE_OPTIMIZATIONS: Record<SONAMode, ModeOptimizations> = {
- 'real-time': {
- enableSIMD: true,
- useMicroLoRA: true,
- gradientCheckpointing: false,
- useHalfPrecision: true,
- patternCaching: true,
- asyncUpdates: true,
- },
- 'balanced': {
- enableSIMD: true,
- useMicroLoRA: false,
- gradientCheckpointing: false,
- useHalfPrecision: false,
- patternCaching: true,
- asyncUpdates: false,
- },
- 'research': {
- enableSIMD: true,
- useMicroLoRA: false,
- gradientCheckpointing: true,
- useHalfPrecision: false,
- patternCaching: true,
- asyncUpdates: false,
- },
- 'edge': {
- enableSIMD: false,
- useMicroLoRA: true,
- gradientCheckpointing: false,
- useHalfPrecision: true,
- patternCaching: false,
- asyncUpdates: true,
- },
- 'batch': {
- enableSIMD: true,
- useMicroLoRA: false,
- gradientCheckpointing: true,
- useHalfPrecision: true,
- patternCaching: true,
- asyncUpdates: true,
- },
-};
-
-/**
- * SONA Manager - Main orchestrator for neural learning
- */
-export class SONAManager {
- private currentMode: SONAMode;
- private config: SONAModeConfig;
- private optimizations: ModeOptimizations;
- private modeImpl: ModeImplementation;
-
- private trajectories: Map<string, Trajectory> = new Map();
- private patterns: Map<string, Pattern> = new Map();
- private loraWeights: Map<string, LoRAWeights> = new Map();
- private ewcState: EWCState | null = null;
-
- private eventListeners: Set<NeuralEventListener> = new Set();
- private stats: NeuralStats;
- private isInitialized = false;
-
- // Performance tracking
- private operationCount = 0;
- private totalLatencyMs = 0;
- private learningCycles = 0;
- private lastStatsUpdate = Date.now();
-
- constructor(mode: SONAMode = 'balanced') {
- this.currentMode = mode;
- this.config = { ...MODE_CONFIGS[mode] };
- this.optimizations = { ...MODE_OPTIMIZATIONS[mode] };
- this.modeImpl = this.createModeImplementation(mode);
- this.stats = this.createInitialStats();
- }
-
- /**
- * Initialize the SONA manager
- */
- async initialize(): Promise<void> {
- if (this.isInitialized) return;
-
- // Initialize mode implementation
- await this.modeImpl.initialize();
-
- // Initialize EWC state for continual learning
- this.ewcState = {
- means: new Map(),
- fisher: new Map(),
- taskCount: 0,
- lastConsolidation: Date.now(),
- };
-
- this.isInitialized = true;
- }
-
- /**
- * Change the current learning mode
- */
- async setMode(mode: SONAMode): Promise<void> {
- if (mode === this.currentMode) return;
-
- const previousMode = this.currentMode;
-
- // Cleanup current mode
- await this.modeImpl.cleanup();
-
- // Update configuration
- this.currentMode = mode;
- this.config = { ...MODE_CONFIGS[mode] };
- this.optimizations = { ...MODE_OPTIMIZATIONS[mode] };
-
- // Create new mode implementation
- this.modeImpl = this.createModeImplementation(mode);
- await this.modeImpl.initialize();
-
- // Emit mode change event
- this.emitEvent({
- type: 'mode_changed',
- fromMode: previousMode,
- toMode: mode,
- });
- }
-
- /**
- * Get current mode and configuration
- */
- getConfig(): { mode: SONAMode; config: SONAModeConfig; optimizations: ModeOptimizations } {
- return {
- mode: this.currentMode,
- config: { ...this.config },
- optimizations: { ...this.optimizations },
- };
- }
-
- // ==========================================================================
- // Trajectory Management
- // ==========================================================================
-
- /**
- * Begin a new trajectory for a task
- */
- beginTrajectory(context: string, domain: Trajectory['domain'] = 'general'): string {
- const startTime = performance.now();
-
- const trajectoryId = `traj_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
-
- const trajectory: Trajectory = {
- trajectoryId,
- context,
- domain,
- steps: [],
- qualityScore: 0,
- isComplete: false,
- startTime: Date.now(),
- };
-
- this.trajectories.set(trajectoryId, trajectory);
-
- this.emitEvent({
- type: 'trajectory_started',
- trajectoryId,
- context,
- });
-
- this.trackLatency(performance.now() - startTime);
- return trajectoryId;
- }
-
- /**
- * Record a step in a trajectory
- */
- recordStep(
- trajectoryId: string,
- action: string,
- reward: number,
- stateEmbedding: Float32Array,
- metadata?: Record<string, unknown>
- ): void {
- const startTime = performance.now();
-
- const trajectory = this.trajectories.get(trajectoryId);
- if (!trajectory || trajectory.isComplete) return;
-
- const step: TrajectoryStep = {
- stepId: `step_${trajectory.steps.length}`,
- timestamp: Date.now(),
- action,
- stateBefore: trajectory.steps.length > 0
- ? trajectory.steps[trajectory.steps.length - 1].stateAfter
- : stateEmbedding,
- stateAfter: stateEmbedding,
- reward,
- metadata,
- };
-
- trajectory.steps.push(step);
-
- // Update running quality score
- trajectory.qualityScore = this.calculateQualityScore(trajectory);
-
- this.trackLatency(performance.now() - startTime);
- }
-
- /**
- * Complete a trajectory
- */
- completeTrajectory(trajectoryId: string, finalQuality?: number): Trajectory | null {
- const startTime = performance.now();
-
- const trajectory = this.trajectories.get(trajectoryId);
- if (!trajectory || trajectory.isComplete) return null;
-
- trajectory.isComplete = true;
- trajectory.endTime = Date.now();
-
- if (finalQuality !== undefined) {
- trajectory.qualityScore = finalQuality;
- } else {
- trajectory.qualityScore = this.calculateQualityScore(trajectory);
- }
-
- this.emitEvent({
- type: 'trajectory_completed',
- trajectoryId,
- qualityScore: trajectory.qualityScore,
- });
-
- // Check if we should trigger learning
- this.checkLearningTrigger();
-
- this.trackLatency(performance.now() - startTime);
- return trajectory;
- }
-
- /**
- * Get a trajectory by ID
- */
- getTrajectory(trajectoryId: string): Trajectory | undefined {
- return this.trajectories.get(trajectoryId);
- }
-
- // ==========================================================================
- // Pattern Matching
- // ==========================================================================
-
- /**
- * Find similar patterns for a given context (k=3 optimal)
- */
- async findSimilarPatterns(
- embedding: Float32Array,
- k: number = 3
- ): Promise<PatternMatch[]> {
- const startTime = performance.now();
-
- const matches = await this.modeImpl.findPatterns(embedding, k, Array.from(this.patterns.values()));
-
- // Track pattern match events
- for (const match of matches) {
- this.emitEvent({
- type: 'pattern_matched',
- patternId: match.pattern.patternId,
- similarity: match.similarity,
- });
- }
-
- const latency = performance.now() - startTime;
-
- // Add latency to matches
- return matches.map(m => ({ ...m, latencyMs: latency }));
- }
-
- /**
- * Store a new pattern
- */
- storePattern(pattern: Omit<Pattern, 'patternId' | 'createdAt' | 'updatedAt'>): Pattern {
- const startTime = performance.now();
-
- const fullPattern: Pattern = {
- ...pattern,
- patternId: `pat_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
- createdAt: Date.now(),
- updatedAt: Date.now(),
- };
-
- this.patterns.set(fullPattern.patternId, fullPattern);
-
- this.trackLatency(performance.now() - startTime);
- return fullPattern;
- }
-
- /**
- * Update pattern based on usage
- */
- updatePatternUsage(patternId: string, quality: number): void {
- const pattern = this.patterns.get(patternId);
- if (!pattern) return;
-
- pattern.usageCount++;
- pattern.qualityHistory.push(quality);
-
- // Keep only last 100 quality scores
- if (pattern.qualityHistory.length > 100) {
- pattern.qualityHistory = pattern.qualityHistory.slice(-100);
- }
-
- // Update success rate
- pattern.successRate = pattern.qualityHistory.reduce((a, b) => a + b, 0) / pattern.qualityHistory.length;
- pattern.updatedAt = Date.now();
- }
-
- // ==========================================================================
- // Learning
- // ==========================================================================
-
- /**
- * Trigger a learning cycle
- */
- async triggerLearning(reason: string = 'manual'): Promise<void> {
- const startTime = performance.now();
-
- const completedTrajectories = Array.from(this.trajectories.values())
- .filter(t => t.isComplete && t.qualityScore >= this.config.qualityThreshold);
-
- if (completedTrajectories.length === 0) return;
-
- this.emitEvent({
- type: 'learning_triggered',
- reason,
- trajectoryCount: completedTrajectories.length,
- });
-
- // Perform learning via mode implementation
- const improvementDelta = await this.modeImpl.learn(
- completedTrajectories,
- this.config,
- this.ewcState!
- );
-
- this.learningCycles++;
-
- this.emitEvent({
- type: 'learning_completed',
- improvementDelta,
- });
-
- // Prune old trajectories if over capacity
- this.pruneTrajectories();
-
- this.trackLatency(performance.now() - startTime);
- }
-
- /**
- * Apply learned adaptations to processing
- */
- async applyAdaptations(
- input: Float32Array,
- domain?: string
- ): Promise<Float32Array> {
- const startTime = performance.now();
-
- // Get relevant LoRA weights
- const weights = domain
- ? this.loraWeights.get(domain)
- : this.loraWeights.get('default');
-
- // Apply adaptations via mode implementation
- const output = await this.modeImpl.applyLoRA(input, weights);
-
- const latency = performance.now() - startTime;
-
- // Verify performance target
- if (latency > 0.05 && this.currentMode !== 'research' && this.currentMode !== 'batch') {
- console.warn(`SONA adaptation exceeded target: ${latency.toFixed(3)}ms > 0.05ms`);
- }
-
- return output;
- }
-
- // ==========================================================================
- // LoRA Management
- // ==========================================================================
-
- /**
- * Get LoRA configuration for current mode
- */
- getLoRAConfig(): LoRAConfig {
- return {
- rank: this.config.loraRank,
- alpha: this.config.loraRank * 2,
- dropout: 0.05,
- targetModules: ['q_proj', 'v_proj', 'k_proj', 'o_proj'],
- microLoRA: this.optimizations.useMicroLoRA,
- };
- }
-
- /**
- * Initialize LoRA weights for a domain
- */
- initializeLoRAWeights(domain: string = 'default'): LoRAWeights {
- const config = this.getLoRAConfig();
-
- const weights: LoRAWeights = {
- adapterId: `lora_${domain}_${Date.now()}`,
- A: new Map(),
- B: new Map(),
- createdAt: Date.now(),
- updatedAt: Date.now(),
- iterations: 0,
- domain,
- };
-
- // Initialize A and B matrices for each target module
- for (const module of config.targetModules) {
- // A: (hidden_dim, rank) initialized with small random values
- // B: (rank, hidden_dim) initialized to zero
- const hiddenDim = 768; // Typical transformer hidden dim
- const A = new Float32Array(hiddenDim * config.rank);
- const B = new Float32Array(config.rank * hiddenDim);
-
- // Initialize A with small random values
- for (let i = 0; i < A.length; i++) {
- A[i] = (Math.random() - 0.5) * 0.02;
- }
-
- weights.A.set(module, A);
- weights.B.set(module, B);
- }
-
- this.loraWeights.set(domain, weights);
- return weights;
- }
-
- // ==========================================================================
- // EWC (Elastic Weight Consolidation)
- // ==========================================================================
-
- /**
- * Get EWC configuration
- */
- getEWCConfig(): EWCConfig {
- return {
- lambda: this.config.ewcLambda,
- decay: 0.9,
- fisherSamples: 100,
- minFisher: 1e-8,
- online: true,
- };
- }
-
- /**
- * Consolidate EWC after learning a new task
- */
- consolidateEWC(): void {
- if (!this.ewcState) return;
-
- const config = this.getEWCConfig();
-
- // Update Fisher information with decay
- for (const [key, fisher] of this.ewcState.fisher) {
- for (let i = 0; i < fisher.length; i++) {
- fisher[i] *= config.decay;
- }
- }
-
- this.ewcState.taskCount++;
- this.ewcState.lastConsolidation = Date.now();
- }
-
- // ==========================================================================
- // Statistics
- // ==========================================================================
-
- /**
- * Get current neural system statistics
- */
- getStats(): NeuralStats {
- this.updateStats();
- return { ...this.stats };
- }
-
- // ==========================================================================
- // Event System
- // ==========================================================================
-
- /**
- * Add an event listener
- */
- addEventListener(listener: NeuralEventListener): void {
- this.eventListeners.add(listener);
- }
-
- /**
- * Remove an event listener
- */
- removeEventListener(listener: NeuralEventListener): void {
- this.eventListeners.delete(listener);
- }
-
- // ==========================================================================
- // Cleanup
- // ==========================================================================
-
- /**
- * Cleanup resources
- */
- async cleanup(): Promise<void> {
- await this.modeImpl.cleanup();
- this.trajectories.clear();
- this.patterns.clear();
- this.loraWeights.clear();
- this.eventListeners.clear();
- this.isInitialized = false;
- }
-
- // ==========================================================================
- // Private Methods
- // ==========================================================================
-
- private createModeImplementation(mode: SONAMode): ModeImplementation {
- switch (mode) {
- case 'real-time':
- return new RealTimeMode(MODE_CONFIGS[mode], MODE_OPTIMIZATIONS[mode]);
- case 'balanced':
- return new BalancedMode(MODE_CONFIGS[mode], MODE_OPTIMIZATIONS[mode]);
- case 'research':
- return new ResearchMode(MODE_CONFIGS[mode], MODE_OPTIMIZATIONS[mode]);
- case 'edge':
- return new EdgeMode(MODE_CONFIGS[mode], MODE_OPTIMIZATIONS[mode]);
- case 'batch':
- return new BatchMode(MODE_CONFIGS[mode], MODE_OPTIMIZATIONS[mode]);
- default:
- return new BalancedMode(MODE_CONFIGS['balanced'], MODE_OPTIMIZATIONS['balanced']);
- }
- }
-
- private calculateQualityScore(trajectory: Trajectory): number {
- if (trajectory.steps.length === 0) return 0;
-
- // Average reward across steps
- const avgReward = trajectory.steps.reduce((sum, step) => sum + step.reward, 0) / trajectory.steps.length;
-
- // Discount factor for trajectory length (longer trajectories may accumulate errors)
- const lengthFactor = Math.min(1, 10 / trajectory.steps.length);
-
- return avgReward * 0.8 + lengthFactor * 0.2;
- }
-
- private checkLearningTrigger(): void {
- const completedCount = Array.from(this.trajectories.values())
- .filter(t => t.isComplete).length;
-
- const utilization = completedCount / this.config.trajectoryCapacity;
-
- // Trigger learning at 80% utilization
- if (utilization >= 0.8) {
- this.triggerLearning('capacity_threshold');
- }
- }
-
- private pruneTrajectories(): void {
- const completed = Array.from(this.trajectories.entries())
- .filter(([_, t]) => t.isComplete)
- .sort((a, b) => a[1].qualityScore - b[1].qualityScore);
-
- // Remove lowest quality trajectories if over capacity
- const toRemove = completed.length - Math.floor(this.config.trajectoryCapacity * 0.5);
-
- if (toRemove > 0) {
- for (let i = 0; i < toRemove && i < completed.length; i++) {
- this.trajectories.delete(completed[i][0]);
- }
- }
- }
-
- private trackLatency(latencyMs: number): void {
- this.operationCount++;
- this.totalLatencyMs += latencyMs;
- }
-
- private emitEvent(event: NeuralEvent): void {
- for (const listener of this.eventListeners) {
- try {
- listener(event);
- } catch (error) {
- console.error('Error in neural event listener:', error);
- }
- }
- }
-
- private createInitialStats(): NeuralStats {
- return {
- trajectories: {
- total: 0,
- active: 0,
- completed: 0,
- utilization: 0,
- },
- performance: {
- avgQualityScore: 0,
- opsPerSecond: 0,
- learningCycles: 0,
- avgLatencyMs: 0,
- },
- patterns: {
- totalPatterns: 0,
- avgMatchTime: 0,
- cacheHitRate: 0,
- evolutionCount: 0,
- },
- memory: {
- usedMb: 0,
- budgetMb: this.config.memoryBudgetMb,
- trajectoryBytes: 0,
- patternBytes: 0,
- },
- config: {
- mode: this.currentMode,
- loraRank: this.config.loraRank,
- learningRate: this.config.learningRate,
- algorithm: 'ppo',
- },
- };
- }
-
- private updateStats(): void {
- const now = Date.now();
- const elapsed = (now - this.lastStatsUpdate) / 1000;
-
- const trajectoryArray = Array.from(this.trajectories.values());
- const completed = trajectoryArray.filter(t => t.isComplete);
-
- this.stats = {
- trajectories: {
- total: trajectoryArray.length,
- active: trajectoryArray.filter(t => !t.isComplete).length,
- completed: completed.length,
- utilization: trajectoryArray.length / this.config.trajectoryCapacity,
- },
- performance: {
- avgQualityScore: completed.length > 0
- ? completed.reduce((sum, t) => sum + t.qualityScore, 0) / completed.length
- : 0,
- opsPerSecond: elapsed > 0 ? this.operationCount / elapsed : 0,
- learningCycles: this.learningCycles,
- avgLatencyMs: this.operationCount > 0
- ? this.totalLatencyMs / this.operationCount
- : 0,
- },
- patterns: {
- totalPatterns: this.patterns.size,
- avgMatchTime: 0, // Updated by mode implementation
- cacheHitRate: 0, // Updated by mode implementation
- evolutionCount: Array.from(this.patterns.values())
- .reduce((sum, p) => sum + p.evolutionHistory.length, 0),
- },
- memory: {
- usedMb: this.estimateMemoryUsage(),
- budgetMb: this.config.memoryBudgetMb,
- trajectoryBytes: this.estimateTrajectoryBytes(),
- patternBytes: this.estimatePatternBytes(),
- },
- config: {
- mode: this.currentMode,
- loraRank: this.config.loraRank,
- learningRate: this.config.learningRate,
- algorithm: 'ppo',
- },
- };
-
- this.lastStatsUpdate = now;
- this.operationCount = 0;
- this.totalLatencyMs = 0;
- }
-
- private estimateMemoryUsage(): number {
- // Rough estimation in MB
- return (this.estimateTrajectoryBytes() + this.estimatePatternBytes()) / (1024 * 1024);
- }
-
- private estimateTrajectoryBytes(): number {
- let bytes = 0;
- for (const trajectory of this.trajectories.values()) {
- bytes += 200; // Base trajectory overhead
- bytes += trajectory.context.length * 2;
- bytes += trajectory.steps.length * (64 + 4 * 768 * 4); // Step overhead + embeddings
- }
- return bytes;
- }
-
- private estimatePatternBytes(): number {
- let bytes = 0;
- for (const pattern of this.patterns.values()) {
- bytes += 100; // Base pattern overhead
- bytes += pattern.name.length * 2;
- bytes += pattern.strategy.length * 2;
- bytes += pattern.embedding.byteLength;
- bytes += pattern.qualityHistory.length * 8;
- bytes += pattern.evolutionHistory.length * 100;
- }
- return bytes;
- }
-}
-
-/**
- * Factory function for creating SONA manager
- */
-export function createSONAManager(mode: SONAMode = 'balanced'): SONAManager {
- return new SONAManager(mode);
-}
-
-/**
- * Get default configuration for a mode
- */
-export function getModeConfig(mode: SONAMode): SONAModeConfig {
- return { ...MODE_CONFIGS[mode] };
-}
-
-/**
- * Get optimizations for a mode
- */
-export function getModeOptimizations(mode: SONAMode): ModeOptimizations {
- return { ...MODE_OPTIMIZATIONS[mode] };
-}
diff --git a/v3/neural/types.ts b/v3/neural/types.ts
deleted file mode 100644
index aeb45fb24b..0000000000
--- a/v3/neural/types.ts
+++ /dev/null
@@ -1,590 +0,0 @@
-/**
- * V3 Neural/Learning System Types
- * Core type definitions for SONA learning modes and ReasoningBank integration
- *
- * Performance Targets:
- * - SONA adaptation: <0.05ms
- * - Pattern matching: <1ms
- * - Learning step: <10ms
- */
-
-// ============================================================================
-// SONA Learning Mode Types
-// ============================================================================
-
-/**
- * Available SONA learning modes with their characteristics
- */
-export type SONAMode = 'real-time' | 'balanced' | 'research' | 'edge' | 'batch';
-
-/**
- * Configuration for each SONA mode
- */
-export interface SONAModeConfig {
- /** Mode identifier */
- mode: SONAMode;
-
- /** LoRA rank (1-16, higher = more expressive but slower) */
- loraRank: number;
-
- /** Learning rate (0.001-0.01, sweet spot is 0.002) */
- learningRate: number;
-
- /** Batch size for updates */
- batchSize: number;
-
- /** Maximum trajectory capacity */
- trajectoryCapacity: number;
-
- /** Number of pattern clusters */
- patternClusters: number;
-
- /** Quality threshold (0-1) for accepting patterns */
- qualityThreshold: number;
-
- /** Maximum latency allowed in milliseconds */
- maxLatencyMs: number;
-
- /** Memory budget in MB */
- memoryBudgetMb: number;
-
- /** EWC lambda for catastrophic forgetting prevention */
- ewcLambda: number;
-}
-
-/**
- * Mode-specific optimizations
- */
-export interface ModeOptimizations {
- /** Enable SIMD vectorization */
- enableSIMD: boolean;
-
- /** Use micro-LoRA (reduced parameter count) */
- useMicroLoRA: boolean;
-
- /** Enable gradient checkpointing */
- gradientCheckpointing: boolean;
-
- /** Use half-precision (FP16) */
- useHalfPrecision: boolean;
-
- /** Enable pattern caching */
- patternCaching: boolean;
-
- /** Async learning updates */
- asyncUpdates: boolean;
-}
-
-// ============================================================================
-// Trajectory Types (ReasoningBank)
-// ============================================================================
-
-/**
- * A single step in a reasoning trajectory
- */
-export interface TrajectoryStep {
- /** Unique step identifier */
- stepId: string;
-
- /** Timestamp of the step */
- timestamp: number;
-
- /** Action taken */
- action: string;
-
- /** State before action (embedding) */
- stateBefore: Float32Array;
-
- /** State after action (embedding) */
- stateAfter: Float32Array;
-
- /** Reward/quality signal (0-1) */
- reward: number;
-
- /** Attention weights from model */
- attentionWeights?: Float32Array;
-
- /** Layer activations (optional) */
- layerActivations?: Float32Array[];
-
- /** Additional metadata */
- metadata?: Record<string, unknown>;
-}
-
-/**
- * Complete reasoning trajectory
- */
-export interface Trajectory {
- /** Unique trajectory identifier */
- trajectoryId: string;
-
- /** Task context/description */
- context: string;
-
- /** Domain classification */
- domain: 'code' | 'creative' | 'reasoning' | 'chat' | 'math' | 'general';
-
- /** Sequence of steps */
- steps: TrajectoryStep[];
-
- /** Overall quality score (0-1) */
- qualityScore: number;
-
- /** Whether trajectory is complete */
- isComplete: boolean;
-
- /** Start timestamp */
- startTime: number;
-
- /** End timestamp (if complete) */
- endTime?: number;
-
- /** Verdict from judgment */
- verdict?: TrajectoryVerdict;
-
- /** Distilled memory (if processed) */
- distilledMemory?: DistilledMemory;
-}
-
-/**
- * Verdict from trajectory judgment
- */
-export interface TrajectoryVerdict {
- /** Whether trajectory was successful */
- success: boolean;
-
- /** Confidence in the verdict (0-1) */
- confidence: number;
-
- /** Identified strengths */
- strengths: string[];
-
- /** Identified weaknesses */
- weaknesses: string[];
-
- /** Suggested improvements */
- improvements: string[];
-
- /** Relevance score for similar tasks */
- relevanceScore: number;
-}
-
-/**
- * Distilled memory from trajectory
- */
-export interface DistilledMemory {
- /** Unique memory identifier */
- memoryId: string;
-
- /** Source trajectory ID */
- trajectoryId: string;
-
- /** Extracted strategy pattern */
- strategy: string;
-
- /** Key learnings */
- keyLearnings: string[];
-
- /** Embedding for similarity search */
- embedding: Float32Array;
-
- /** Quality score */
- quality: number;
-
- /** Usage count */
- usageCount: number;
-
- /** Last used timestamp */
- lastUsed: number;
-}
-
-// ============================================================================
-// Pattern Learning Types
-// ============================================================================
-
-/**
- * A learned pattern from experience
- */
-export interface Pattern {
- /** Unique pattern identifier */
- patternId: string;
-
- /** Pattern name/description */
- name: string;
-
- /** Domain this pattern applies to */
- domain: string;
-
- /** Pattern embedding for similarity */
- embedding: Float32Array;
-
- /** Strategy this pattern represents */
- strategy: string;
-
- /** Success rate when applying this pattern */
- successRate: number;
-
- /** Number of times pattern was used */
- usageCount: number;
-
- /** Quality scores from applications */
- qualityHistory: number[];
-
- /** Evolution history */
- evolutionHistory: PatternEvolution[];
-
- /** Creation timestamp */
- createdAt: number;
-
- /** Last update timestamp */
- updatedAt: number;
-}
-
-/**
- * Pattern evolution record
- */
-export interface PatternEvolution {
- /** When evolution occurred */
- timestamp: number;
-
- /** Type of evolution */
- type: 'improvement' | 'merge' | 'split' | 'prune';
-
- /** Previous quality */
- previousQuality: number;
-
- /** New quality */
- newQuality: number;
-
- /** Description of change */
- description: string;
-}
-
-/**
- * Pattern match result
- */
-export interface PatternMatch {
- /** Matched pattern */
- pattern: Pattern;
-
- /** Similarity score (0-1) */
- similarity: number;
-
- /** Confidence in match */
- confidence: number;
-
- /** Retrieval latency in ms */
- latencyMs: number;
-}
-
-// ============================================================================
-// RL Algorithm Types
-// ============================================================================
-
-/**
- * Supported RL algorithms
- */
-export type RLAlgorithm =
- | 'ppo'
- | 'dqn'
- | 'a2c'
- | 'decision-transformer'
- | 'q-learning'
- | 'sarsa'
- | 'curiosity';
-
-/**
- * Base RL algorithm configuration
- */
-export interface RLConfig {
- /** Algorithm identifier */
- algorithm: RLAlgorithm;
-
- /** Learning rate */
- learningRate: number;
-
- /** Discount factor (gamma) */
- gamma: number;
-
- /** Entropy coefficient */
- entropyCoef: number;
-
- /** Value loss coefficient */
- valueLossCoef: number;
-
- /** Maximum gradient norm */
- maxGradNorm: number;
-
- /** Number of epochs per update */
- epochs: number;
-
- /** Mini-batch size */
- miniBatchSize: number;
-}
-
-/**
- * PPO-specific configuration
- */
-export interface PPOConfig extends RLConfig {
- algorithm: 'ppo';
-
- /** Clip range for policy */
- clipRange: number;
-
- /** Clip range for value function */
- clipRangeVf: number | null;
-
- /** Target KL divergence */
- targetKL: number;
-
- /** GAE lambda */
- gaeLambda: number;
-}
-
-/**
- * DQN-specific configuration
- */
-export interface DQNConfig extends RLConfig {
- algorithm: 'dqn';
-
- /** Replay buffer size */
- bufferSize: number;
-
- /** Initial exploration rate */
- explorationInitial: number;
-
- /** Final exploration rate */
- explorationFinal: number;
-
- /** Exploration decay steps */
- explorationDecay: number;
-
- /** Target network update frequency */
- targetUpdateFreq: number;
-
- /** Use double DQN */
- doubleDQN: boolean;
-
- /** Use dueling network */
- duelingNetwork: boolean;
-}
-
-/**
- * Decision Transformer configuration
- */
-export interface DecisionTransformerConfig extends RLConfig {
- algorithm: 'decision-transformer';
-
- /** Context length */
- contextLength: number;
-
- /** Number of attention heads */
- numHeads: number;
-
- /** Number of transformer layers */
- numLayers: number;
-
- /** Hidden dimension */
- hiddenDim: number;
-
- /** Embedding dimension */
- embeddingDim: number;
-
- /** Dropout rate */
- dropout: number;
-}
-
-/**
- * Curiosity-driven exploration configuration
- */
-export interface CuriosityConfig extends RLConfig {
- algorithm: 'curiosity';
-
- /** Intrinsic reward coefficient */
- intrinsicCoef: number;
-
- /** Forward model learning rate */
- forwardLR: number;
-
- /** Inverse model learning rate */
- inverseLR: number;
-
- /** Feature dimension */
- featureDim: number;
-
- /** Use random network distillation */
- useRND: boolean;
-}
-
-// ============================================================================
-// LoRA Types
-// ============================================================================
-
-/**
- * LoRA adapter configuration
- */
-export interface LoRAConfig {
- /** Adapter rank (1, 2, 4, 8, 16) */
- rank: number;
-
- /** Alpha scaling factor */
- alpha: number;
-
- /** Dropout rate */
- dropout: number;
-
- /** Target modules to adapt */
- targetModules: string[];
-
- /** Use micro-LoRA (optimized for speed) */
- microLoRA: boolean;
-}
-
-/**
- * LoRA adapter weights
- */
-export interface LoRAWeights {
- /** Adapter identifier */
- adapterId: string;
-
- /** A matrices (down projection) */
- A: Map<string, Float32Array>;
-
- /** B matrices (up projection) */
- B: Map<string, Float32Array>;
-
- /** Creation timestamp */
- createdAt: number;
-
- /** Last update timestamp */
- updatedAt: number;
-
- /** Training iterations */
- iterations: number;
-
- /** Associated domain */
- domain?: string;
-}
-
-// ============================================================================
-// EWC Types (Elastic Weight Consolidation)
-// ============================================================================
-
-/**
- * EWC++ configuration for continual learning
- */
-export interface EWCConfig {
- /** Lambda (importance weight) */
- lambda: number;
-
- /** Decay rate for old Fisher information */
- decay: number;
-
- /** Number of samples for Fisher estimation */
- fisherSamples: number;
-
- /** Minimum Fisher value (for stability) */
- minFisher: number;
-
- /** Use online EWC (EWC++) */
- online: boolean;
-}
-
-/**
- * EWC state for a parameter set
- */
-export interface EWCState {
- /** Parameter means (optimal values) */
- means: Map<string, Float32Array>;
-
- /** Fisher information (importance weights) */
- fisher: Map<string, Float32Array>;
-
- /** Number of tasks learned */
- taskCount: number;
-
- /** Last consolidation timestamp */
- lastConsolidation: number;
-}
-
-// ============================================================================
-// Neural System Statistics
-// ============================================================================
-
-/**
- * Statistics for the neural/learning system
- */
-export interface NeuralStats {
- /** Trajectory statistics */
- trajectories: {
- total: number;
- active: number;
- completed: number;
- utilization: number;
- };
-
- /** Performance metrics */
- performance: {
- avgQualityScore: number;
- opsPerSecond: number;
- learningCycles: number;
- avgLatencyMs: number;
- };
-
- /** Pattern statistics */
- patterns: {
- totalPatterns: number;
- avgMatchTime: number;
- cacheHitRate: number;
- evolutionCount: number;
- };
-
- /** Memory usage */
- memory: {
- usedMb: number;
- budgetMb: number;
- trajectoryBytes: number;
- patternBytes: number;
- };
-
- /** Current configuration */
- config: {
- mode: SONAMode;
- loraRank: number;
- learningRate: number;
- algorithm: RLAlgorithm;
- };
-}
-
-// ============================================================================
-// Event Types
-// ============================================================================
-
-/**
- * Neural system events for monitoring and hooks
- */
-export type NeuralEvent =
- | { type: 'trajectory_started'; trajectoryId: string; context: string }
- | { type: 'trajectory_completed'; trajectoryId: string; qualityScore: number }
- | { type: 'pattern_matched'; patternId: string; similarity: number }
- | { type: 'pattern_evolved'; patternId: string; evolutionType: string }
- | { type: 'learning_triggered'; reason: string; trajectoryCount: number }
- | { type: 'learning_completed'; improvementDelta: number }
- | { type: 'mode_changed'; fromMode: SONAMode; toMode: SONAMode }
- | { type: 'memory_consolidated'; memoriesCount: number };
-
-/**
- * Event listener type
- */
-export type NeuralEventListener = (event: NeuralEvent) => void | Promise<void>;
-
-// ============================================================================
-// Module Exports
-// ============================================================================
-
-export type {
- SONAMode as LearningMode,
- SONAModeConfig as ModeConfig,
- Pattern as LearnedPattern,
- PatternMatch as PatternSearchResult,
-};
diff --git a/v3/security/CVE-REMEDIATION.ts b/v3/security/CVE-REMEDIATION.ts
deleted file mode 100644
index f5ff121d64..0000000000
--- a/v3/security/CVE-REMEDIATION.ts
+++ /dev/null
@@ -1,233 +0,0 @@
-/**
- * CVE Remediation Tracking
- *
- * This file documents all security vulnerabilities addressed in the V3 security module
- * and provides programmatic tracking of remediation status.
- *
- * @module v3/security/CVE-REMEDIATION
- */
-
-export interface CVEEntry {
- id: string;
- title: string;
- severity: 'critical' | 'high' | 'medium' | 'low';
- description: string;
- affectedFiles: string[];
- remediationFile: string;
- remediationStatus: 'fixed' | 'in_progress' | 'pending';
- testFile: string;
- testStatus: 'passing' | 'failing' | 'pending';
- timeline: {
- identified: string;
- remediated?: string;
- verified?: string;
- };
-}
-
-/**
- * Complete list of addressed CVEs and security issues
- */
-export const CVE_REGISTRY: CVEEntry[] = [
- {
- id: 'CVE-2',
- title: 'Weak Password Hashing',
- severity: 'critical',
- description: 'SHA-256 with hardcoded salt used for password hashing instead of bcrypt',
- affectedFiles: [
- 'v2/src/api/auth-service.ts:580-588',
- ],
- remediationFile: 'v3/security/password-hasher.ts',
- remediationStatus: 'fixed',
- testFile: 'v3/__tests__/security/password-hasher.test.ts',
- testStatus: 'passing',
- timeline: {
- identified: '2025-01-01',
- remediated: '2025-01-04',
- verified: '2025-01-04',
- },
- },
- {
- id: 'CVE-3',
- title: 'Hardcoded Default Credentials',
- severity: 'critical',
- description: 'Default admin/service credentials hardcoded in auth service initialization',
- affectedFiles: [
- 'v2/src/api/auth-service.ts:602-643',
- ],
- remediationFile: 'v3/security/credential-generator.ts',
- remediationStatus: 'fixed',
- testFile: 'v3/__tests__/security/credential-generator.test.ts',
- testStatus: 'passing',
- timeline: {
- identified: '2025-01-01',
- remediated: '2025-01-04',
- verified: '2025-01-04',
- },
- },
- {
- id: 'HIGH-1',
- title: 'Command Injection via Shell Execution',
- severity: 'high',
- description: 'spawn() and exec() calls with shell:true enable command injection',
- affectedFiles: [
- 'Multiple spawn() locations across codebase',
- ],
- remediationFile: 'v3/security/safe-executor.ts',
- remediationStatus: 'fixed',
- testFile: 'v3/__tests__/security/safe-executor.test.ts',
- testStatus: 'passing',
- timeline: {
- identified: '2025-01-01',
- remediated: '2025-01-04',
- verified: '2025-01-04',
- },
- },
- {
- id: 'HIGH-2',
- title: 'Path Traversal Vulnerability',
- severity: 'high',
- description: 'Unvalidated file paths allow directory traversal attacks',
- affectedFiles: [
- 'All file operation modules',
- ],
- remediationFile: 'v3/security/path-validator.ts',
- remediationStatus: 'fixed',
- testFile: 'v3/__tests__/security/path-validator.test.ts',
- testStatus: 'passing',
- timeline: {
- identified: '2025-01-01',
- remediated: '2025-01-04',
- verified: '2025-01-04',
- },
- },
-];
-
-/**
- * Security patterns implemented
- */
-export const SECURITY_PATTERNS = {
- passwordHashing: {
- algorithm: 'bcrypt',
- rounds: 12,
- rationale: 'Industry standard adaptive hashing with automatic salt generation',
- },
- credentialGeneration: {
- method: 'crypto.randomBytes',
- minPasswordLength: 32,
- minSecretLength: 64,
- rationale: 'Cryptographically secure random generation with sufficient entropy',
- },
- commandExecution: {
- method: 'execFile',
- shell: false,
- allowlist: true,
- rationale: 'No shell interpretation, command allowlist prevents injection',
- },
- pathValidation: {
- method: 'path.resolve + prefix check',
- symlinks: 'resolved',
- blockedPatterns: ['..', '%2e', null],
- rationale: 'Canonicalization prevents all traversal variations',
- },
- inputValidation: {
- library: 'zod',
- sanitization: true,
- rationale: 'Type-safe validation with runtime checks',
- },
-};
-
-/**
- * Summary of security improvements
- */
-export const SECURITY_SUMMARY = {
- cveCount: 4,
- fixedCount: 4,
- pendingCount: 0,
- criticalFixed: 2,
- highFixed: 2,
- testCoverage: '>95%',
- documentsCreated: [
- 'v3/security/password-hasher.ts',
- 'v3/security/credential-generator.ts',
- 'v3/security/safe-executor.ts',
- 'v3/security/path-validator.ts',
- 'v3/security/input-validator.ts',
- 'v3/security/token-generator.ts',
- 'v3/security/index.ts',
- 'v3/security/CVE-REMEDIATION.ts',
- ],
- testsCreated: [
- 'v3/__tests__/security/password-hasher.test.ts',
- 'v3/__tests__/security/credential-generator.test.ts',
- 'v3/__tests__/security/safe-executor.test.ts',
- 'v3/__tests__/security/path-validator.test.ts',
- 'v3/__tests__/security/input-validator.test.ts',
- 'v3/__tests__/security/token-generator.test.ts',
- ],
-};
-
-/**
- * Validates that all CVEs are addressed
- */
-export function validateRemediation(): {
- allFixed: boolean;
- issues: string[];
-} {
- const issues: string[] = [];
-
- for (const cve of CVE_REGISTRY) {
- if (cve.remediationStatus !== 'fixed') {
- issues.push(`${cve.id}: Remediation not complete (${cve.remediationStatus})`);
- }
- if (cve.testStatus !== 'passing') {
- issues.push(`${cve.id}: Tests not passing (${cve.testStatus})`);
- }
- }
-
- return {
- allFixed: issues.length === 0,
- issues,
- };
-}
-
-/**
- * Gets remediation report
- */
-export function getRemediationReport(): string {
- const lines = [
- '# V3 Security Remediation Report',
- '',
- '## Summary',
- `- Total CVEs/Issues: ${SECURITY_SUMMARY.cveCount}`,
- `- Fixed: ${SECURITY_SUMMARY.fixedCount}`,
- `- Pending: ${SECURITY_SUMMARY.pendingCount}`,
- `- Test Coverage: ${SECURITY_SUMMARY.testCoverage}`,
- '',
- '## Detailed Status',
- '',
- ];
-
- for (const cve of CVE_REGISTRY) {
- lines.push(`### ${cve.id}: ${cve.title}`);
- lines.push(`- Severity: ${cve.severity.toUpperCase()}`);
- lines.push(`- Status: ${cve.remediationStatus}`);
- lines.push(`- Test Status: ${cve.testStatus}`);
- lines.push(`- Remediation: \`${cve.remediationFile}\``);
- lines.push('');
- }
-
- lines.push('## Security Patterns Implemented');
- lines.push('');
- lines.push('| Pattern | Implementation | Rationale |');
- lines.push('|---------|---------------|-----------|');
-
- for (const [pattern, config] of Object.entries(SECURITY_PATTERNS)) {
- const impl = Object.entries(config)
- .filter(([k]) => k !== 'rationale')
- .map(([k, v]) => `${k}: ${v}`)
- .join(', ');
- lines.push(`| ${pattern} | ${impl} | ${config.rationale} |`);
- }
-
- return lines.join('\n');
-}
diff --git a/v3/security/credential-generator.ts b/v3/security/credential-generator.ts
deleted file mode 100644
index 7a93ec9870..0000000000
--- a/v3/security/credential-generator.ts
+++ /dev/null
@@ -1,351 +0,0 @@
-/**
- * Credential Generator - CVE-3 Remediation
- *
- * Fixes hardcoded default credentials by providing secure random
- * credential generation for installation and runtime.
- *
- * Security Properties:
- * - Uses crypto.randomBytes for cryptographically secure randomness
- * - Configurable entropy levels
- * - No hardcoded defaults stored in code
- * - Secure credential storage recommendations
- *
- * @module v3/security/credential-generator
- */
-
-import { randomBytes, randomUUID } from 'crypto';
-
-export interface CredentialConfig {
- /**
- * Length of generated passwords.
- * Default: 32 characters
- */
- passwordLength?: number;
-
- /**
- * Length of generated API keys.
- * Default: 48 characters
- */
- apiKeyLength?: number;
-
- /**
- * Length of generated secrets (JWT, session, etc.).
- * Default: 64 characters
- */
- secretLength?: number;
-
- /**
- * Character set for password generation.
- * Default: alphanumeric + special
- */
- passwordCharset?: string;
-
- /**
- * Character set for API key generation.
- * Default: alphanumeric only (URL-safe)
- */
- apiKeyCharset?: string;
-}
-
-export interface GeneratedCredentials {
- adminPassword: string;
- servicePassword: string;
- jwtSecret: string;
- sessionSecret: string;
- encryptionKey: string;
- generatedAt: Date;
- expiresAt?: Date;
-}
-
-export interface ApiKeyCredential {
- key: string;
- prefix: string;
- keyId: string;
- createdAt: Date;
-}
-
-export class CredentialGeneratorError extends Error {
- constructor(
- message: string,
- public readonly code: string,
- ) {
- super(message);
- this.name = 'CredentialGeneratorError';
- }
-}
-
-/**
- * Character sets for credential generation
- */
-const CHARSETS = {
- UPPERCASE: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
- LOWERCASE: 'abcdefghijklmnopqrstuvwxyz',
- DIGITS: '0123456789',
- SPECIAL: '!@#$%^&*()_+-=[]{}|;:,.<>?',
- // URL-safe characters for API keys
- URL_SAFE: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_',
- // Hex characters for secrets
- HEX: '0123456789abcdef',
-} as const;
-
-/**
- * Secure credential generator.
- *
- * This class provides cryptographically secure credential generation
- * to replace hardcoded default credentials.
- *
- * @example
- * ```typescript
- * const generator = new CredentialGenerator();
- * const credentials = generator.generateInstallationCredentials();
- * // Store credentials securely (environment variables, secrets manager)
- * ```
- */
-export class CredentialGenerator {
- private readonly config: Required<CredentialConfig>;
-
- constructor(config: CredentialConfig = {}) {
- this.config = {
- passwordLength: config.passwordLength ?? 32,
- apiKeyLength: config.apiKeyLength ?? 48,
- secretLength: config.secretLength ?? 64,
- passwordCharset: config.passwordCharset ??
- CHARSETS.UPPERCASE + CHARSETS.LOWERCASE + CHARSETS.DIGITS + CHARSETS.SPECIAL,
- apiKeyCharset: config.apiKeyCharset ?? CHARSETS.URL_SAFE,
- };
-
- this.validateConfig();
- }
-
- /**
- * Validates configuration parameters.
- */
- private validateConfig(): void {
- if (this.config.passwordLength < 16) {
- throw new CredentialGeneratorError(
- 'Password length must be at least 16 characters',
- 'INVALID_PASSWORD_LENGTH'
- );
- }
-
- if (this.config.apiKeyLength < 32) {
- throw new CredentialGeneratorError(
- 'API key length must be at least 32 characters',
- 'INVALID_API_KEY_LENGTH'
- );
- }
-
- if (this.config.secretLength < 32) {
- throw new CredentialGeneratorError(
- 'Secret length must be at least 32 characters',
- 'INVALID_SECRET_LENGTH'
- );
- }
- }
-
- /**
- * Generates a cryptographically secure random string.
- *
- * @param length - Length of the string to generate
- * @param charset - Character set to use
- * @returns Random string
- */
- private generateSecureString(length: number, charset: string): string {
- const charsetLength = charset.length;
- const randomBuffer = randomBytes(length);
- const result = new Array(length);
-
- for (let i = 0; i < length; i++) {
- // Use modulo with rejection sampling to avoid bias
- result[i] = charset[randomBuffer[i] % charsetLength];
- }
-
- return result.join('');
- }
-
- /**
- * Generates a secure random password.
- *
- * @param length - Optional custom length (default from config)
- * @returns Secure random password
- */
- generatePassword(length?: number): string {
- const len = length ?? this.config.passwordLength;
-
- // Ensure password contains at least one of each required character type
- const password = this.generateSecureString(len, this.config.passwordCharset);
-
- // Validate the generated password meets requirements
- if (!this.hasRequiredCharacterTypes(password)) {
- // Regenerate if requirements not met (rare case)
- return this.generatePassword(length);
- }
-
- return password;
- }
-
- /**
- * Checks if password has required character types.
- */
- private hasRequiredCharacterTypes(password: string): boolean {
- const hasUppercase = /[A-Z]/.test(password);
- const hasLowercase = /[a-z]/.test(password);
- const hasDigit = /\d/.test(password);
- const hasSpecial = /[!@#$%^&*()_+\-=\[\]{}|;:,.<>?]/.test(password);
-
- return hasUppercase && hasLowercase && hasDigit && hasSpecial;
- }
-
- /**
- * Generates a secure API key.
- *
- * @param prefix - Optional prefix for the key (e.g., 'cf_')
- * @returns API key credential with metadata
- */
- generateApiKey(prefix = 'cf_'): ApiKeyCredential {
- const keyBody = this.generateSecureString(
- this.config.apiKeyLength - prefix.length,
- this.config.apiKeyCharset
- );
-
- const key = `${prefix}${keyBody}`;
- const keyId = randomUUID();
-
- return {
- key,
- prefix,
- keyId,
- createdAt: new Date(),
- };
- }
-
- /**
- * Generates a secure secret for JWT, sessions, etc.
- *
- * @param length - Optional custom length (default from config)
- * @returns Hex-encoded secret
- */
- generateSecret(length?: number): string {
- const len = length ?? this.config.secretLength;
- // Generate raw bytes and encode as hex for consistent storage
- return randomBytes(Math.ceil(len / 2)).toString('hex').slice(0, len);
- }
-
- /**
- * Generates an encryption key suitable for AES-256.
- *
- * @returns 32-byte key encoded as hex (64 characters)
- */
- generateEncryptionKey(): string {
- return randomBytes(32).toString('hex');
- }
-
- /**
- * Generates a complete set of installation credentials.
- *
- * These should be stored securely (environment variables,
- * secrets manager, etc.) and NEVER committed to version control.
- *
- * @param expirationDays - Optional expiration period in days
- * @returns Complete credential set
- */
- generateInstallationCredentials(expirationDays?: number): GeneratedCredentials {
- const now = new Date();
- const expiresAt = expirationDays
- ? new Date(now.getTime() + expirationDays * 24 * 60 * 60 * 1000)
- : undefined;
-
- return {
- adminPassword: this.generatePassword(),
- servicePassword: this.generatePassword(),
- jwtSecret: this.generateSecret(64),
- sessionSecret: this.generateSecret(64),
- encryptionKey: this.generateEncryptionKey(),
- generatedAt: now,
- expiresAt,
- };
- }
-
- /**
- * Generates a secure session token.
- *
- * @returns URL-safe session token
- */
- generateSessionToken(): string {
- return this.generateSecureString(64, CHARSETS.URL_SAFE);
- }
-
- /**
- * Generates a secure CSRF token.
- *
- * @returns CSRF token
- */
- generateCsrfToken(): string {
- return randomBytes(32).toString('base64url');
- }
-
- /**
- * Generates a secure nonce for one-time use.
- *
- * @returns Unique nonce value
- */
- generateNonce(): string {
- return randomBytes(16).toString('hex');
- }
-
- /**
- * Creates a setup script output for secure credential deployment.
- *
- * @param credentials - Generated credentials
- * @returns Environment variable export script
- */
- createEnvScript(credentials: GeneratedCredentials): string {
- return `# Claude Flow V3 - Generated Credentials
-# Generated: ${credentials.generatedAt.toISOString()}
-# IMPORTANT: Store these securely and delete this file after use
-
-export CLAUDE_FLOW_ADMIN_PASSWORD="${credentials.adminPassword}"
-export CLAUDE_FLOW_SERVICE_PASSWORD="${credentials.servicePassword}"
-export CLAUDE_FLOW_JWT_SECRET="${credentials.jwtSecret}"
-export CLAUDE_FLOW_SESSION_SECRET="${credentials.sessionSecret}"
-export CLAUDE_FLOW_ENCRYPTION_KEY="${credentials.encryptionKey}"
-`;
- }
-
- /**
- * Creates a JSON configuration output for secure credential deployment.
- *
- * @param credentials - Generated credentials
- * @returns JSON configuration (for secrets manager import)
- */
- createJsonConfig(credentials: GeneratedCredentials): string {
- return JSON.stringify({
- 'claude-flow/admin-password': credentials.adminPassword,
- 'claude-flow/service-password': credentials.servicePassword,
- 'claude-flow/jwt-secret': credentials.jwtSecret,
- 'claude-flow/session-secret': credentials.sessionSecret,
- 'claude-flow/encryption-key': credentials.encryptionKey,
- 'claude-flow/generated-at': credentials.generatedAt.toISOString(),
- 'claude-flow/expires-at': credentials.expiresAt?.toISOString() ?? null,
- }, null, 2);
- }
-}
-
-/**
- * Factory function to create a production credential generator.
- *
- * @returns Configured CredentialGenerator instance
- */
-export function createCredentialGenerator(): CredentialGenerator {
- return new CredentialGenerator();
-}
-
-/**
- * Quick credential generation for CLI usage.
- *
- * @returns Generated installation credentials
- */
-export function generateCredentials(): GeneratedCredentials {
- const generator = new CredentialGenerator();
- return generator.generateInstallationCredentials();
-}
diff --git a/v3/security/index.ts b/v3/security/index.ts
deleted file mode 100644
index 44c91cdbdc..0000000000
--- a/v3/security/index.ts
+++ /dev/null
@@ -1,271 +0,0 @@
-/**
- * V3 Security Module
- *
- * Comprehensive security module addressing all identified vulnerabilities:
- * - CVE-2: Weak Password Hashing (password-hasher.ts)
- * - CVE-3: Hardcoded Default Credentials (credential-generator.ts)
- * - HIGH-1: Command Injection (safe-executor.ts)
- * - HIGH-2: Path Traversal (path-validator.ts)
- *
- * Also provides:
- * - Input validation with Zod schemas
- * - Secure token generation
- *
- * @module v3/security
- */
-
-// Password Hashing (CVE-2 Fix)
-export {
- PasswordHasher,
- PasswordHashError,
- createPasswordHasher,
- type PasswordHasherConfig,
- type PasswordValidationResult,
-} from './password-hasher.js';
-
-// Credential Generation (CVE-3 Fix)
-export {
- CredentialGenerator,
- CredentialGeneratorError,
- createCredentialGenerator,
- generateCredentials,
- type CredentialConfig,
- type GeneratedCredentials,
- type ApiKeyCredential,
-} from './credential-generator.js';
-
-// Safe Command Execution (HIGH-1 Fix)
-export {
- SafeExecutor,
- SafeExecutorError,
- createDevelopmentExecutor,
- createReadOnlyExecutor,
- type ExecutorConfig,
- type ExecutionResult,
- type StreamingExecutor,
-} from './safe-executor.js';
-
-// Path Validation (HIGH-2 Fix)
-export {
- PathValidator,
- PathValidatorError,
- createProjectPathValidator,
- createFullProjectPathValidator,
- type PathValidatorConfig,
- type PathValidationResult,
-} from './path-validator.js';
-
-// Input Validation
-export {
- InputValidator,
- sanitizeString,
- sanitizeHtml,
- sanitizePath,
- // Base schemas
- SafeStringSchema,
- IdentifierSchema,
- FilenameSchema,
- EmailSchema,
- PasswordSchema,
- UUIDSchema,
- HttpsUrlSchema,
- UrlSchema,
- SemverSchema,
- PortSchema,
- IPv4Schema,
- IPSchema,
- // Auth schemas
- UserRoleSchema,
- PermissionSchema,
- LoginRequestSchema,
- CreateUserSchema,
- CreateApiKeySchema,
- // Agent & Task schemas
- AgentTypeSchema,
- SpawnAgentSchema,
- TaskInputSchema,
- // Command & Path schemas
- CommandArgumentSchema,
- PathSchema,
- // Config schemas
- SecurityConfigSchema,
- ExecutorConfigSchema,
- // Utilities
- PATTERNS,
- LIMITS,
- z,
-} from './input-validator.js';
-
-// Token Generation
-export {
- TokenGenerator,
- TokenGeneratorError,
- createTokenGenerator,
- getDefaultGenerator,
- quickGenerate,
- type TokenConfig,
- type Token,
- type SignedToken,
- type VerificationCode,
-} from './token-generator.js';
-
-// ============================================================================
-// Convenience Factory Functions
-// ============================================================================
-
-import { PasswordHasher } from './password-hasher.js';
-import { CredentialGenerator } from './credential-generator.js';
-import { SafeExecutor } from './safe-executor.js';
-import { PathValidator } from './path-validator.js';
-import { TokenGenerator } from './token-generator.js';
-
-/**
- * Security module configuration
- */
-export interface SecurityModuleConfig {
- /**
- * Project root directory for path validation
- */
- projectRoot: string;
-
- /**
- * HMAC secret for token signing
- */
- hmacSecret: string;
-
- /**
- * Bcrypt rounds for password hashing
- * Default: 12
- */
- bcryptRounds?: number;
-
- /**
- * Allowed commands for safe executor
- * Default: ['git', 'npm', 'npx', 'node']
- */
- allowedCommands?: string[];
-}
-
-/**
- * Complete security module instance
- */
-export interface SecurityModule {
- passwordHasher: PasswordHasher;
- credentialGenerator: CredentialGenerator;
- safeExecutor: SafeExecutor;
- pathValidator: PathValidator;
- tokenGenerator: TokenGenerator;
-}
-
-/**
- * Creates a complete security module with all components configured.
- *
- * @param config - Module configuration
- * @returns Complete security module
- *
- * @example
- * ```typescript
- * const security = createSecurityModule({
- * projectRoot: '/workspaces/project',
- * hmacSecret: process.env.HMAC_SECRET!,
- * });
- *
- * // Hash password
- * const hash = await security.passwordHasher.hash('password');
- *
- * // Validate path
- * const result = await security.pathValidator.validate('/workspaces/project/src/file.ts');
- *
- * // Execute command safely
- * const output = await security.safeExecutor.execute('git', ['status']);
- * ```
- */
-export function createSecurityModule(config: SecurityModuleConfig): SecurityModule {
- return {
- passwordHasher: new PasswordHasher({
- rounds: config.bcryptRounds ?? 12,
- }),
- credentialGenerator: new CredentialGenerator(),
- safeExecutor: new SafeExecutor({
- allowedCommands: config.allowedCommands ?? ['git', 'npm', 'npx', 'node'],
- }),
- pathValidator: new PathValidator({
- allowedPrefixes: [config.projectRoot],
- allowHidden: true,
- }),
- tokenGenerator: new TokenGenerator({
- hmacSecret: config.hmacSecret,
- }),
- };
-}
-
-// ============================================================================
-// Security Constants
-// ============================================================================
-
-/**
- * Minimum recommended bcrypt rounds for production
- */
-export const MIN_BCRYPT_ROUNDS = 12;
-
-/**
- * Maximum recommended bcrypt rounds (performance consideration)
- */
-export const MAX_BCRYPT_ROUNDS = 14;
-
-/**
- * Minimum password length
- */
-export const MIN_PASSWORD_LENGTH = 8;
-
-/**
- * Maximum password length (bcrypt limitation)
- */
-export const MAX_PASSWORD_LENGTH = 72;
-
-/**
- * Default token expiration in seconds (1 hour)
- */
-export const DEFAULT_TOKEN_EXPIRATION = 3600;
-
-/**
- * Default session expiration in seconds (24 hours)
- */
-export const DEFAULT_SESSION_EXPIRATION = 86400;
-
-// ============================================================================
-// Security Audit Helper
-// ============================================================================
-
-/**
- * Checks security configuration for common issues.
- *
- * @param config - Configuration to audit
- * @returns Array of security warnings
- */
-export function auditSecurityConfig(config: Partial<SecurityModuleConfig>): string[] {
- const warnings: string[] = [];
-
- if (config.bcryptRounds && config.bcryptRounds < MIN_BCRYPT_ROUNDS) {
- warnings.push(`bcryptRounds (${config.bcryptRounds}) below recommended minimum (${MIN_BCRYPT_ROUNDS})`);
- }
-
- if (config.hmacSecret && config.hmacSecret.length < 32) {
- warnings.push('hmacSecret should be at least 32 characters');
- }
-
- if (!config.projectRoot) {
- warnings.push('projectRoot not configured - path validation may be disabled');
- }
-
- if (config.allowedCommands && config.allowedCommands.length === 0) {
- warnings.push('No commands allowed - executor will reject all commands');
- }
-
- return warnings;
-}
-
-/**
- * Security module version
- */
-export const SECURITY_MODULE_VERSION = '3.0.0-alpha.1';
diff --git a/v3/security/input-validator.ts b/v3/security/input-validator.ts
deleted file mode 100644
index 2597256b4e..0000000000
--- a/v3/security/input-validator.ts
+++ /dev/null
@@ -1,466 +0,0 @@
-/**
- * Input Validator - Comprehensive Input Validation
- *
- * Provides Zod-based validation schemas for all security-critical inputs.
- *
- * Security Properties:
- * - Type-safe validation
- * - Custom error messages
- * - Sanitization transforms
- * - Reusable schemas
- *
- * @module v3/security/input-validator
- */
-
-import { z } from 'zod';
-
-/**
- * Custom error map for security-focused messages
- */
-const securityErrorMap: z.ZodErrorMap = (issue, ctx) => {
- switch (issue.code) {
- case z.ZodIssueCode.too_big:
- return { message: `Input exceeds maximum allowed size` };
- case z.ZodIssueCode.too_small:
- return { message: `Input below minimum required size` };
- case z.ZodIssueCode.invalid_string:
- if (issue.validation === 'email') {
- return { message: 'Invalid email format' };
- }
- if (issue.validation === 'url') {
- return { message: 'Invalid URL format' };
- }
- if (issue.validation === 'uuid') {
- return { message: 'Invalid UUID format' };
- }
- return { message: 'Invalid string format' };
- default:
- return { message: ctx.defaultError };
- }
-};
-
-// Apply custom error map globally for this module
-z.setErrorMap(securityErrorMap);
-
-/**
- * Common validation patterns as reusable regex
- */
-const PATTERNS = {
- // Safe identifier: alphanumeric with underscore/hyphen
- SAFE_IDENTIFIER: /^[a-zA-Z][a-zA-Z0-9_-]*$/,
-
- // Safe filename: alphanumeric with dot, underscore, hyphen
- SAFE_FILENAME: /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/,
-
- // Safe path segment: no traversal
- SAFE_PATH_SEGMENT: /^[^<>:"|?*\x00-\x1f]+$/,
-
- // No shell metacharacters
- NO_SHELL_CHARS: /^[^;&|`$(){}><\n\r\0]+$/,
-
- // Semantic version
- SEMVER: /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/,
-};
-
-/**
- * Validation limits
- */
-const LIMITS = {
- MIN_PASSWORD_LENGTH: 8,
- MAX_PASSWORD_LENGTH: 128,
- MAX_EMAIL_LENGTH: 254,
- MAX_IDENTIFIER_LENGTH: 64,
- MAX_PATH_LENGTH: 4096,
- MAX_CONTENT_LENGTH: 1024 * 1024, // 1MB
- MAX_ARRAY_LENGTH: 1000,
- MAX_OBJECT_KEYS: 100,
-};
-
-// ============================================================================
-// Base Validation Schemas
-// ============================================================================
-
-/**
- * Safe string that cannot contain shell metacharacters
- */
-export const SafeStringSchema = z.string()
- .min(1, 'String cannot be empty')
- .max(LIMITS.MAX_CONTENT_LENGTH, 'String too long')
- .regex(PATTERNS.NO_SHELL_CHARS, 'String contains invalid characters');
-
-/**
- * Safe identifier for IDs, names, etc.
- */
-export const IdentifierSchema = z.string()
- .min(1, 'Identifier cannot be empty')
- .max(LIMITS.MAX_IDENTIFIER_LENGTH, 'Identifier too long')
- .regex(PATTERNS.SAFE_IDENTIFIER, 'Invalid identifier format');
-
-/**
- * Safe filename
- */
-export const FilenameSchema = z.string()
- .min(1, 'Filename cannot be empty')
- .max(255, 'Filename too long')
- .regex(PATTERNS.SAFE_FILENAME, 'Invalid filename format');
-
-/**
- * Email schema with length limit
- */
-export const EmailSchema = z.string()
- .email('Invalid email format')
- .max(LIMITS.MAX_EMAIL_LENGTH, 'Email too long')
- .toLowerCase();
-
-/**
- * Password schema with complexity requirements
- */
-export const PasswordSchema = z.string()
- .min(LIMITS.MIN_PASSWORD_LENGTH, `Password must be at least ${LIMITS.MIN_PASSWORD_LENGTH} characters`)
- .max(LIMITS.MAX_PASSWORD_LENGTH, `Password must not exceed ${LIMITS.MAX_PASSWORD_LENGTH} characters`)
- .refine((val) => /[A-Z]/.test(val), 'Password must contain uppercase letter')
- .refine((val) => /[a-z]/.test(val), 'Password must contain lowercase letter')
- .refine((val) => /\d/.test(val), 'Password must contain digit');
-
-/**
- * UUID schema
- */
-export const UUIDSchema = z.string().uuid('Invalid UUID format');
-
-/**
- * URL schema with HTTPS enforcement
- */
-export const HttpsUrlSchema = z.string()
- .url('Invalid URL format')
- .refine(
- (val) => val.startsWith('https://'),
- 'URL must use HTTPS'
- );
-
-/**
- * URL schema (allows HTTP for development)
- */
-export const UrlSchema = z.string()
- .url('Invalid URL format');
-
-/**
- * Semantic version schema
- */
-export const SemverSchema = z.string()
- .regex(PATTERNS.SEMVER, 'Invalid semantic version format');
-
-/**
- * Port number schema
- */
-export const PortSchema = z.number()
- .int('Port must be an integer')
- .min(1, 'Port must be at least 1')
- .max(65535, 'Port must be at most 65535');
-
-/**
- * IP address schema (v4)
- */
-export const IPv4Schema = z.string()
- .ip({ version: 'v4', message: 'Invalid IPv4 address' });
-
-/**
- * IP address schema (v4 or v6)
- */
-export const IPSchema = z.string()
- .ip({ message: 'Invalid IP address' });
-
-// ============================================================================
-// Authentication Schemas
-// ============================================================================
-
-/**
- * User role schema
- */
-export const UserRoleSchema = z.enum([
- 'admin',
- 'operator',
- 'developer',
- 'viewer',
- 'service',
-]);
-
-/**
- * Permission schema
- */
-export const PermissionSchema = z.enum([
- 'swarm.create',
- 'swarm.read',
- 'swarm.update',
- 'swarm.delete',
- 'swarm.scale',
- 'agent.spawn',
- 'agent.read',
- 'agent.terminate',
- 'task.create',
- 'task.read',
- 'task.cancel',
- 'metrics.read',
- 'system.admin',
- 'api.access',
-]);
-
-/**
- * Login request schema
- */
-export const LoginRequestSchema = z.object({
- email: EmailSchema,
- password: z.string().min(1, 'Password is required'),
- mfaCode: z.string().length(6, 'MFA code must be 6 digits').optional(),
-});
-
-/**
- * User creation schema
- */
-export const CreateUserSchema = z.object({
- email: EmailSchema,
- password: PasswordSchema,
- role: UserRoleSchema,
- permissions: z.array(PermissionSchema).optional(),
- isActive: z.boolean().optional().default(true),
-});
-
-/**
- * API key creation schema
- */
-export const CreateApiKeySchema = z.object({
- name: IdentifierSchema,
- permissions: z.array(PermissionSchema).optional(),
- expiresAt: z.date().optional(),
-});
-
-// ============================================================================
-// Agent & Task Schemas
-// ============================================================================
-
-/**
- * Agent type schema
- */
-export const AgentTypeSchema = z.enum([
- 'coder',
- 'reviewer',
- 'tester',
- 'planner',
- 'researcher',
- 'security-architect',
- 'security-auditor',
- 'memory-specialist',
- 'swarm-specialist',
- 'integration-architect',
- 'performance-engineer',
- 'core-architect',
- 'test-architect',
- 'queen-coordinator',
- 'project-coordinator',
-]);
-
-/**
- * Agent spawn request schema
- */
-export const SpawnAgentSchema = z.object({
- type: AgentTypeSchema,
- id: IdentifierSchema.optional(),
- config: z.record(z.unknown()).optional(),
- timeout: z.number().positive().optional(),
-});
-
-/**
- * Task input schema
- */
-export const TaskInputSchema = z.object({
- taskId: UUIDSchema,
- content: SafeStringSchema.max(10000, 'Task content too long'),
- agentType: AgentTypeSchema,
- priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
- metadata: z.record(z.unknown()).optional(),
-});
-
-// ============================================================================
-// Command & Path Schemas
-// ============================================================================
-
-/**
- * Command argument schema
- */
-export const CommandArgumentSchema = z.string()
- .max(1024, 'Argument too long')
- .refine(
- (val) => !val.includes('\0'),
- 'Argument contains null byte'
- )
- .refine(
- (val) => !/[;&|`$(){}><]/.test(val),
- 'Argument contains shell metacharacters'
- );
-
-/**
- * Path schema
- */
-export const PathSchema = z.string()
- .max(LIMITS.MAX_PATH_LENGTH, 'Path too long')
- .refine(
- (val) => !val.includes('\0'),
- 'Path contains null byte'
- )
- .refine(
- (val) => !val.includes('..'),
- 'Path contains traversal pattern'
- );
-
-// ============================================================================
-// Configuration Schemas
-// ============================================================================
-
-/**
- * Security configuration schema
- */
-export const SecurityConfigSchema = z.object({
- bcryptRounds: z.number().int().min(10).max(20).default(12),
- jwtExpiresIn: z.string().default('24h'),
- sessionTimeout: z.number().positive().default(3600000),
- maxLoginAttempts: z.number().int().positive().default(5),
- lockoutDuration: z.number().positive().default(900000),
- requireMFA: z.boolean().default(false),
-});
-
-/**
- * Executor configuration schema
- */
-export const ExecutorConfigSchema = z.object({
- allowedCommands: z.array(IdentifierSchema).min(1),
- blockedPatterns: z.array(z.string()).optional(),
- timeout: z.number().positive().default(30000),
- maxBuffer: z.number().positive().default(10 * 1024 * 1024),
- cwd: PathSchema.optional(),
- allowSudo: z.boolean().default(false),
-});
-
-// ============================================================================
-// Sanitization Functions
-// ============================================================================
-
-/**
- * Sanitizes a string by removing dangerous characters
- */
-export function sanitizeString(input: string): string {
- return input
- .replace(/\0/g, '') // Remove null bytes
- .replace(/[<>]/g, '') // Remove HTML brackets
- .replace(/javascript:/gi, '') // Remove javascript: protocol
- .replace(/data:/gi, '') // Remove data: protocol
- .trim();
-}
-
-/**
- * Sanitizes HTML entities
- */
-export function sanitizeHtml(input: string): string {
- return input
- .replace(/&/g, '&amp;')
- .replace(/</g, '&lt;')
- .replace(/>/g, '&gt;')
- .replace(/"/g, '&quot;')
- .replace(/'/g, '&#x27;');
-}
-
-/**
- * Sanitizes a path by removing traversal patterns
- */
-export function sanitizePath(input: string): string {
- return input
- .replace(/\0/g, '') // Remove null bytes
- .replace(/\.\./g, '') // Remove traversal patterns
- .replace(/\/+/g, '/') // Normalize slashes
- .replace(/^\//, '') // Remove leading slash
- .trim();
-}
-
-// ============================================================================
-// Validation Helper Class
-// ============================================================================
-
-export class InputValidator {
- /**
- * Validates input against a schema
- */
- static validate<T>(schema: z.ZodSchema<T>, input: unknown): T {
- return schema.parse(input);
- }
-
- /**
- * Safely validates input, returning result
- */
- static safeParse<T>(schema: z.ZodSchema<T>, input: unknown): z.SafeParseReturnType<unknown, T> {
- return schema.safeParse(input);
- }
-
- /**
- * Validates email
- */
- static validateEmail(email: string): string {
- return EmailSchema.parse(email);
- }
-
- /**
- * Validates password
- */
- static validatePassword(password: string): string {
- return PasswordSchema.parse(password);
- }
-
- /**
- * Validates identifier
- */
- static validateIdentifier(id: string): string {
- return IdentifierSchema.parse(id);
- }
-
- /**
- * Validates path
- */
- static validatePath(path: string): string {
- return PathSchema.parse(path);
- }
-
- /**
- * Validates command argument
- */
- static validateCommandArg(arg: string): string {
- return CommandArgumentSchema.parse(arg);
- }
-
- /**
- * Validates login request
- */
- static validateLoginRequest(data: unknown): z.infer<typeof LoginRequestSchema> {
- return LoginRequestSchema.parse(data);
- }
-
- /**
- * Validates user creation request
- */
- static validateCreateUser(data: unknown): z.infer<typeof CreateUserSchema> {
- return CreateUserSchema.parse(data);
- }
-
- /**
- * Validates task input
- */
- static validateTaskInput(data: unknown): z.infer<typeof TaskInputSchema> {
- return TaskInputSchema.parse(data);
- }
-}
-
-// ============================================================================
-// Export all schemas for direct use
-// ============================================================================
-
-export {
- z,
- PATTERNS,
- LIMITS,
-};
diff --git a/v3/security/password-hasher.ts b/v3/security/password-hasher.ts
deleted file mode 100644
index 8fe50fcd1b..0000000000
--- a/v3/security/password-hasher.ts
+++ /dev/null
@@ -1,270 +0,0 @@
-/**
- * Password Hasher - CVE-2 Remediation
- *
- * Fixes weak password hashing by replacing SHA-256 with hardcoded salt
- * with bcrypt using 12 rounds (configurable).
- *
- * Security Properties:
- * - bcrypt with adaptive cost factor (12 rounds)
- * - Automatic salt generation per password
- * - Timing-safe comparison
- * - Minimum password length enforcement
- *
- * @module v3/security/password-hasher
- */
-
-import * as bcrypt from 'bcrypt';
-
-export interface PasswordHasherConfig {
- /**
- * Number of bcrypt rounds (cost factor).
- * Default: 12 (recommended minimum for production)
- * Each increment doubles the computation time.
- */
- rounds?: number;
-
- /**
- * Minimum password length.
- * Default: 8 characters
- */
- minLength?: number;
-
- /**
- * Maximum password length.
- * Default: 128 characters (bcrypt limit is 72 bytes)
- */
- maxLength?: number;
-
- /**
- * Require at least one uppercase letter.
- * Default: true
- */
- requireUppercase?: boolean;
-
- /**
- * Require at least one lowercase letter.
- * Default: true
- */
- requireLowercase?: boolean;
-
- /**
- * Require at least one digit.
- * Default: true
- */
- requireDigit?: boolean;
-
- /**
- * Require at least one special character.
- * Default: false
- */
- requireSpecial?: boolean;
-}
-
-export interface PasswordValidationResult {
- isValid: boolean;
- errors: string[];
-}
-
-export class PasswordHashError extends Error {
- constructor(
- message: string,
- public readonly code: string,
- ) {
- super(message);
- this.name = 'PasswordHashError';
- }
-}
-
-/**
- * Secure password hasher using bcrypt.
- *
- * This class replaces the vulnerable SHA-256 + hardcoded salt implementation
- * with industry-standard bcrypt hashing.
- *
- * @example
- * ```typescript
- * const hasher = new PasswordHasher({ rounds: 12 });
- * const hash = await hasher.hash('securePassword123');
- * const isValid = await hasher.verify('securePassword123', hash);
- * ```
- */
-export class PasswordHasher {
- private readonly config: Required<PasswordHasherConfig>;
-
- constructor(config: PasswordHasherConfig = {}) {
- this.config = {
- rounds: config.rounds ?? 12,
- minLength: config.minLength ?? 8,
- maxLength: config.maxLength ?? 128,
- requireUppercase: config.requireUppercase ?? true,
- requireLowercase: config.requireLowercase ?? true,
- requireDigit: config.requireDigit ?? true,
- requireSpecial: config.requireSpecial ?? false,
- };
-
- // Validate configuration
- if (this.config.rounds < 10 || this.config.rounds > 20) {
- throw new PasswordHashError(
- 'Bcrypt rounds must be between 10 and 20 for security and performance balance',
- 'INVALID_ROUNDS'
- );
- }
-
- if (this.config.minLength < 8) {
- throw new PasswordHashError(
- 'Minimum password length must be at least 8 characters',
- 'INVALID_MIN_LENGTH'
- );
- }
- }
-
- /**
- * Validates password against configured requirements.
- *
- * @param password - The password to validate
- * @returns Validation result with errors if any
- */
- validate(password: string): PasswordValidationResult {
- const errors: string[] = [];
-
- if (!password) {
- errors.push('Password is required');
- return { isValid: false, errors };
- }
-
- if (password.length < this.config.minLength) {
- errors.push(`Password must be at least ${this.config.minLength} characters`);
- }
-
- if (password.length > this.config.maxLength) {
- errors.push(`Password must not exceed ${this.config.maxLength} characters`);
- }
-
- if (this.config.requireUppercase && !/[A-Z]/.test(password)) {
- errors.push('Password must contain at least one uppercase letter');
- }
-
- if (this.config.requireLowercase && !/[a-z]/.test(password)) {
- errors.push('Password must contain at least one lowercase letter');
- }
-
- if (this.config.requireDigit && !/\d/.test(password)) {
- errors.push('Password must contain at least one digit');
- }
-
- if (this.config.requireSpecial && !/[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]/.test(password)) {
- errors.push('Password must contain at least one special character');
- }
-
- return {
- isValid: errors.length === 0,
- errors,
- };
- }
-
- /**
- * Hashes a password using bcrypt.
- *
- * @param password - The plaintext password to hash
- * @returns The bcrypt hash
- * @throws PasswordHashError if password is invalid
- */
- async hash(password: string): Promise<string> {
- const validation = this.validate(password);
-
- if (!validation.isValid) {
- throw new PasswordHashError(
- validation.errors.join('; '),
- 'VALIDATION_FAILED'
- );
- }
-
- try {
- // bcrypt automatically generates a random salt per hash
- return await bcrypt.hash(password, this.config.rounds);
- } catch (error) {
- throw new PasswordHashError(
- 'Failed to hash password',
- 'HASH_FAILED'
- );
- }
- }
-
- /**
- * Verifies a password against a bcrypt hash.
- * Uses timing-safe comparison internally.
- *
- * @param password - The plaintext password to verify
- * @param hash - The bcrypt hash to compare against
- * @returns True if password matches, false otherwise
- */
- async verify(password: string, hash: string): Promise<boolean> {
- if (!password || !hash) {
- return false;
- }
-
- // Validate hash format (bcrypt hashes start with $2a$, $2b$, or $2y$)
- if (!this.isValidBcryptHash(hash)) {
- return false;
- }
-
- try {
- // bcrypt.compare uses timing-safe comparison
- return await bcrypt.compare(password, hash);
- } catch (error) {
- // Return false on any error to prevent timing attacks
- return false;
- }
- }
-
- /**
- * Checks if a hash needs to be rehashed with updated parameters.
- * Useful for upgrading hash strength over time.
- *
- * @param hash - The bcrypt hash to check
- * @returns True if hash should be updated
- */
- needsRehash(hash: string): boolean {
- if (!this.isValidBcryptHash(hash)) {
- return true;
- }
-
- // Extract rounds from hash (format: $2b$XX$...)
- const match = hash.match(/^\$2[aby]\$(\d{2})\$/);
- if (!match) {
- return true;
- }
-
- const hashRounds = parseInt(match[1], 10);
- return hashRounds < this.config.rounds;
- }
-
- /**
- * Validates bcrypt hash format.
- *
- * @param hash - The hash to validate
- * @returns True if valid bcrypt hash format
- */
- private isValidBcryptHash(hash: string): boolean {
- // bcrypt hash format: $2a$XX$22charsSalt31charsHash
- // Total length: 60 characters
- return /^\$2[aby]\$\d{2}\$[./A-Za-z0-9]{53}$/.test(hash);
- }
-
- /**
- * Returns current configuration (without sensitive defaults).
- */
- getConfig(): Readonly<Omit<Required<PasswordHasherConfig>, never>> {
- return { ...this.config };
- }
-}
-
-/**
- * Factory function to create a production-ready password hasher.
- *
- * @param rounds - Bcrypt rounds (default: 12)
- * @returns Configured PasswordHasher instance
- */
-export function createPasswordHasher(rounds = 12): PasswordHasher {
- return new PasswordHasher({ rounds });
-}
diff --git a/v3/security/path-validator.ts b/v3/security/path-validator.ts
deleted file mode 100644
index 5a71b1f36f..0000000000
--- a/v3/security/path-validator.ts
+++ /dev/null
@@ -1,525 +0,0 @@
-/**
- * Path Validator - HIGH-2 Remediation
- *
- * Fixes path traversal vulnerabilities by:
- * - Validating all file paths against allowed prefixes
- * - Using path.resolve() for canonicalization
- * - Blocking traversal patterns (../, etc.)
- * - Enforcing path length limits
- *
- * Security Properties:
- * - Path canonicalization
- * - Prefix validation
- * - Symlink resolution (optional)
- * - Traversal pattern detection
- *
- * @module v3/security/path-validator
- */
-
-import * as path from 'path';
-import * as fs from 'fs/promises';
-
-export interface PathValidatorConfig {
- /**
- * Allowed directory prefixes.
- * Paths must start with one of these after resolution.
- */
- allowedPrefixes: string[];
-
- /**
- * Blocked file extensions.
- * Files with these extensions are rejected.
- */
- blockedExtensions?: string[];
-
- /**
- * Blocked file names.
- * Files matching these names are rejected.
- */
- blockedNames?: string[];
-
- /**
- * Maximum path length.
- * Default: 4096 characters
- */
- maxPathLength?: number;
-
- /**
- * Whether to resolve symlinks.
- * Default: true
- */
- resolveSymlinks?: boolean;
-
- /**
- * Whether to allow paths that don't exist.
- * Default: true (for write operations)
- */
- allowNonExistent?: boolean;
-
- /**
- * Whether to allow hidden files/directories.
- * Default: false
- */
- allowHidden?: boolean;
-}
-
-export interface PathValidationResult {
- isValid: boolean;
- resolvedPath: string;
- relativePath: string;
- matchedPrefix: string;
- errors: string[];
-}
-
-export class PathValidatorError extends Error {
- constructor(
- message: string,
- public readonly code: string,
- public readonly path?: string,
- ) {
- super(message);
- this.name = 'PathValidatorError';
- }
-}
-
-/**
- * Dangerous path patterns that indicate traversal attempts.
- */
-const TRAVERSAL_PATTERNS = [
- /\.\.\//, // ../
- /\.\.\\/, // ..\
- /\.\./, // .. anywhere
- /%2e%2e/i, // URL-encoded ..
- /%252e%252e/i, // Double URL-encoded ..
- /\.%2e/i, // Mixed encoding
- /%2e\./i, // Mixed encoding
- /\0/, // Null byte
- /%00/, // URL-encoded null
-];
-
-/**
- * Default blocked file extensions (sensitive files).
- */
-const DEFAULT_BLOCKED_EXTENSIONS = [
- '.env',
- '.pem',
- '.key',
- '.crt',
- '.pfx',
- '.p12',
- '.jks',
- '.keystore',
- '.secret',
- '.credentials',
-];
-
-/**
- * Default blocked file names (sensitive files).
- */
-const DEFAULT_BLOCKED_NAMES = [
- 'id_rsa',
- 'id_dsa',
- 'id_ecdsa',
- 'id_ed25519',
- '.htpasswd',
- '.htaccess',
- 'shadow',
- 'passwd',
- 'authorized_keys',
- 'known_hosts',
- '.git',
- '.gitconfig',
- '.npmrc',
- '.docker',
-];
-
-/**
- * Path validator that prevents traversal attacks.
- *
- * This class validates file paths to ensure they stay within
- * allowed directories and don't access sensitive files.
- *
- * @example
- * ```typescript
- * const validator = new PathValidator({
- * allowedPrefixes: ['/workspaces/project']
- * });
- *
- * const result = await validator.validate('/workspaces/project/src/file.ts');
- * if (result.isValid) {
- * // Safe to use result.resolvedPath
- * }
- * ```
- */
-export class PathValidator {
- private readonly config: Required<PathValidatorConfig>;
- private readonly resolvedPrefixes: string[];
-
- constructor(config: PathValidatorConfig) {
- this.config = {
- allowedPrefixes: config.allowedPrefixes,
- blockedExtensions: config.blockedExtensions ?? DEFAULT_BLOCKED_EXTENSIONS,
- blockedNames: config.blockedNames ?? DEFAULT_BLOCKED_NAMES,
- maxPathLength: config.maxPathLength ?? 4096,
- resolveSymlinks: config.resolveSymlinks ?? true,
- allowNonExistent: config.allowNonExistent ?? true,
- allowHidden: config.allowHidden ?? false,
- };
-
- if (this.config.allowedPrefixes.length === 0) {
- throw new PathValidatorError(
- 'At least one allowed prefix must be specified',
- 'EMPTY_PREFIXES'
- );
- }
-
- // Pre-resolve all prefixes
- this.resolvedPrefixes = this.config.allowedPrefixes.map(p =>
- path.resolve(p)
- );
- }
-
- /**
- * Validates a path against security rules.
- *
- * @param inputPath - The path to validate
- * @returns Validation result with resolved path
- */
- async validate(inputPath: string): Promise<PathValidationResult> {
- const errors: string[] = [];
-
- // Check for empty path
- if (!inputPath || inputPath.trim() === '') {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: ['Path is empty'],
- };
- }
-
- // Check path length
- if (inputPath.length > this.config.maxPathLength) {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: [`Path exceeds maximum length of ${this.config.maxPathLength}`],
- };
- }
-
- // Check for traversal patterns
- for (const pattern of TRAVERSAL_PATTERNS) {
- if (pattern.test(inputPath)) {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: ['Path traversal pattern detected'],
- };
- }
- }
-
- // Resolve the path
- let resolvedPath: string;
- try {
- resolvedPath = path.resolve(inputPath);
-
- // Optionally resolve symlinks
- if (this.config.resolveSymlinks) {
- try {
- resolvedPath = await fs.realpath(resolvedPath);
- } catch (error: any) {
- // Path doesn't exist yet - use resolved path
- if (error.code !== 'ENOENT' || !this.config.allowNonExistent) {
- if (error.code === 'ENOENT') {
- errors.push('Path does not exist');
- } else {
- errors.push(`Failed to resolve path: ${error.message}`);
- }
- }
- }
- }
- } catch (error: any) {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: [`Invalid path: ${error.message}`],
- };
- }
-
- // Check against allowed prefixes
- let matchedPrefix = '';
- let relativePath = '';
- let prefixMatched = false;
-
- for (const prefix of this.resolvedPrefixes) {
- if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
- prefixMatched = true;
- matchedPrefix = prefix;
- relativePath = resolvedPath.slice(prefix.length);
- if (relativePath.startsWith(path.sep)) {
- relativePath = relativePath.slice(1);
- }
- break;
- }
- }
-
- if (!prefixMatched) {
- return {
- isValid: false,
- resolvedPath,
- relativePath: '',
- matchedPrefix: '',
- errors: ['Path is outside allowed directories'],
- };
- }
-
- // Check for hidden files
- const pathParts = resolvedPath.split(path.sep);
- if (!this.config.allowHidden) {
- for (const part of pathParts) {
- if (part.startsWith('.') && part !== '.' && part !== '..') {
- errors.push('Hidden files/directories are not allowed');
- break;
- }
- }
- }
-
- // Check blocked file names
- const basename = path.basename(resolvedPath);
- if (this.config.blockedNames.includes(basename)) {
- errors.push(`File name "${basename}" is blocked`);
- }
-
- // Check blocked extensions
- const ext = path.extname(resolvedPath).toLowerCase();
- if (this.config.blockedExtensions.includes(ext)) {
- errors.push(`File extension "${ext}" is blocked`);
- }
-
- // Also check for double extensions (e.g., .tar.gz, .config.json)
- const fullname = basename.toLowerCase();
- for (const blockedExt of this.config.blockedExtensions) {
- if (fullname.endsWith(blockedExt)) {
- errors.push(`File extension "${blockedExt}" is blocked`);
- break;
- }
- }
-
- return {
- isValid: errors.length === 0,
- resolvedPath,
- relativePath,
- matchedPrefix,
- errors,
- };
- }
-
- /**
- * Validates and returns resolved path, throwing on failure.
- *
- * @param inputPath - The path to validate
- * @returns Resolved path if valid
- * @throws PathValidatorError if validation fails
- */
- async validateOrThrow(inputPath: string): Promise<string> {
- const result = await this.validate(inputPath);
-
- if (!result.isValid) {
- throw new PathValidatorError(
- result.errors.join('; '),
- 'VALIDATION_FAILED',
- inputPath
- );
- }
-
- return result.resolvedPath;
- }
-
- /**
- * Synchronous validation (without symlink resolution).
- *
- * @param inputPath - The path to validate
- * @returns Validation result
- */
- validateSync(inputPath: string): PathValidationResult {
- const errors: string[] = [];
-
- if (!inputPath || inputPath.trim() === '') {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: ['Path is empty'],
- };
- }
-
- if (inputPath.length > this.config.maxPathLength) {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: [`Path exceeds maximum length of ${this.config.maxPathLength}`],
- };
- }
-
- for (const pattern of TRAVERSAL_PATTERNS) {
- if (pattern.test(inputPath)) {
- return {
- isValid: false,
- resolvedPath: '',
- relativePath: '',
- matchedPrefix: '',
- errors: ['Path traversal pattern detected'],
- };
- }
- }
-
- const resolvedPath = path.resolve(inputPath);
-
- let matchedPrefix = '';
- let relativePath = '';
- let prefixMatched = false;
-
- for (const prefix of this.resolvedPrefixes) {
- if (resolvedPath === prefix || resolvedPath.startsWith(prefix + path.sep)) {
- prefixMatched = true;
- matchedPrefix = prefix;
- relativePath = resolvedPath.slice(prefix.length);
- if (relativePath.startsWith(path.sep)) {
- relativePath = relativePath.slice(1);
- }
- break;
- }
- }
-
- if (!prefixMatched) {
- return {
- isValid: false,
- resolvedPath,
- relativePath: '',
- matchedPrefix: '',
- errors: ['Path is outside allowed directories'],
- };
- }
-
- const pathParts = resolvedPath.split(path.sep);
- if (!this.config.allowHidden) {
- for (const part of pathParts) {
- if (part.startsWith('.') && part !== '.' && part !== '..') {
- errors.push('Hidden files/directories are not allowed');
- break;
- }
- }
- }
-
- const basename = path.basename(resolvedPath);
- if (this.config.blockedNames.includes(basename)) {
- errors.push(`File name "${basename}" is blocked`);
- }
-
- const ext = path.extname(resolvedPath).toLowerCase();
- if (this.config.blockedExtensions.includes(ext)) {
- errors.push(`File extension "${ext}" is blocked`);
- }
-
- return {
- isValid: errors.length === 0,
- resolvedPath,
- relativePath,
- matchedPrefix,
- errors,
- };
- }
-
- /**
- * Securely joins path segments within allowed directories.
- *
- * @param prefix - Base directory (must be in allowedPrefixes)
- * @param segments - Path segments to join
- * @returns Validated resolved path
- */
- async securePath(prefix: string, ...segments: string[]): Promise<string> {
- // Join the segments
- const joined = path.join(prefix, ...segments);
-
- // Validate the result
- return this.validateOrThrow(joined);
- }
-
- /**
- * Adds a prefix to the allowed list at runtime.
- *
- * @param prefix - Prefix to add
- */
- addPrefix(prefix: string): void {
- const resolved = path.resolve(prefix);
- if (!this.resolvedPrefixes.includes(resolved)) {
- this.config.allowedPrefixes.push(prefix);
- this.resolvedPrefixes.push(resolved);
- }
- }
-
- /**
- * Returns the current allowed prefixes.
- */
- getAllowedPrefixes(): readonly string[] {
- return [...this.resolvedPrefixes];
- }
-
- /**
- * Checks if a path is within allowed prefixes (quick check).
- */
- isWithinAllowed(inputPath: string): boolean {
- try {
- const resolved = path.resolve(inputPath);
- return this.resolvedPrefixes.some(
- prefix => resolved === prefix || resolved.startsWith(prefix + path.sep)
- );
- } catch {
- return false;
- }
- }
-}
-
-/**
- * Factory function to create a path validator for a project directory.
- *
- * @param projectRoot - Root directory of the project
- * @returns Configured PathValidator
- */
-export function createProjectPathValidator(projectRoot: string): PathValidator {
- const srcDir = path.join(projectRoot, 'src');
- const testDir = path.join(projectRoot, 'tests');
- const docsDir = path.join(projectRoot, 'docs');
-
- return new PathValidator({
- allowedPrefixes: [srcDir, testDir, docsDir],
- allowHidden: false,
- });
-}
-
-/**
- * Factory function to create a path validator for the entire project.
- *
- * @param projectRoot - Root directory of the project
- * @returns Configured PathValidator
- */
-export function createFullProjectPathValidator(projectRoot: string): PathValidator {
- return new PathValidator({
- allowedPrefixes: [projectRoot],
- allowHidden: true, // Allow .gitignore, etc.
- blockedNames: [
- ...DEFAULT_BLOCKED_NAMES,
- 'node_modules', // Block access to node_modules
- ],
- });
-}
diff --git a/v3/security/safe-executor.ts b/v3/security/safe-executor.ts
deleted file mode 100644
index 8d8b2e0fc6..0000000000
--- a/v3/security/safe-executor.ts
+++ /dev/null
@@ -1,525 +0,0 @@
-/**
- * Safe Executor - HIGH-1 Remediation
- *
- * Fixes command injection vulnerabilities by:
- * - Using execFile instead of exec with shell
- * - Validating all command arguments
- * - Implementing command allowlist
- * - Sanitizing command inputs
- *
- * Security Properties:
- * - No shell interpretation
- * - Argument validation
- * - Command allowlist enforcement
- * - Timeout controls
- * - Resource limits
- *
- * @module v3/security/safe-executor
- */
-
-import { execFile, spawn, ChildProcess } from 'child_process';
-import { promisify } from 'util';
-import * as path from 'path';
-
-const execFileAsync = promisify(execFile);
-
-export interface ExecutorConfig {
- /**
- * Allowed commands (allowlist).
- * Only commands in this list can be executed.
- */
- allowedCommands: string[];
-
- /**
- * Blocked argument patterns (regex strings).
- * Arguments matching these patterns are rejected.
- */
- blockedPatterns?: string[];
-
- /**
- * Maximum execution timeout in milliseconds.
- * Default: 30000 (30 seconds)
- */
- timeout?: number;
-
- /**
- * Maximum buffer size for stdout/stderr.
- * Default: 10MB
- */
- maxBuffer?: number;
-
- /**
- * Working directory for command execution.
- * Default: process.cwd()
- */
- cwd?: string;
-
- /**
- * Environment variables to include.
- * Default: process.env
- */
- env?: NodeJS.ProcessEnv;
-
- /**
- * Whether to allow sudo commands.
- * Default: false
- */
- allowSudo?: boolean;
-}
-
-export interface ExecutionResult {
- stdout: string;
- stderr: string;
- exitCode: number;
- command: string;
- args: string[];
- duration: number;
-}
-
-export interface StreamingExecutor {
- process: ChildProcess;
- stdout: NodeJS.ReadableStream | null;
- stderr: NodeJS.ReadableStream | null;
- promise: Promise<ExecutionResult>;
-}
-
-export class SafeExecutorError extends Error {
- constructor(
- message: string,
- public readonly code: string,
- public readonly command?: string,
- public readonly args?: string[],
- ) {
- super(message);
- this.name = 'SafeExecutorError';
- }
-}
-
-/**
- * Default blocked argument patterns.
- * These patterns indicate potential command injection attempts.
- */
-const DEFAULT_BLOCKED_PATTERNS = [
- // Shell metacharacters
- ';',
- '&&',
- '||',
- '|',
- '`',
- '$(',
- '${',
- // Redirection
- '>',
- '<',
- '>>',
- // Background execution
- '&',
- // Newlines (command chaining)
- '\n',
- '\r',
- // Null byte injection
- '\0',
- // Command substitution
- '$()',
-];
-
-/**
- * Commands that are inherently dangerous and should never be allowed.
- */
-const DANGEROUS_COMMANDS = [
- 'rm',
- 'rmdir',
- 'del',
- 'format',
- 'mkfs',
- 'dd',
- 'chmod',
- 'chown',
- 'kill',
- 'killall',
- 'pkill',
- 'reboot',
- 'shutdown',
- 'init',
- 'poweroff',
- 'halt',
-];
-
-/**
- * Safe command executor that prevents command injection.
- *
- * This class replaces unsafe exec() and spawn({shell: true}) calls
- * with validated execFile() calls.
- *
- * @example
- * ```typescript
- * const executor = new SafeExecutor({
- * allowedCommands: ['git', 'npm', 'node']
- * });
- *
- * const result = await executor.execute('git', ['status']);
- * ```
- */
-export class SafeExecutor {
- private readonly config: Required<ExecutorConfig>;
- private readonly blockedPatterns: RegExp[];
-
- constructor(config: ExecutorConfig) {
- this.config = {
- allowedCommands: config.allowedCommands,
- blockedPatterns: config.blockedPatterns ?? DEFAULT_BLOCKED_PATTERNS,
- timeout: config.timeout ?? 30000,
- maxBuffer: config.maxBuffer ?? 10 * 1024 * 1024, // 10MB
- cwd: config.cwd ?? process.cwd(),
- env: config.env ?? process.env,
- allowSudo: config.allowSudo ?? false,
- };
-
- // Compile blocked patterns for performance
- this.blockedPatterns = this.config.blockedPatterns.map(
- pattern => new RegExp(this.escapeRegExp(pattern), 'i')
- );
-
- this.validateConfig();
- }
-
- /**
- * Escapes special regex characters.
- */
- private escapeRegExp(str: string): string {
- return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
- }
-
- /**
- * Validates executor configuration.
- */
- private validateConfig(): void {
- if (this.config.allowedCommands.length === 0) {
- throw new SafeExecutorError(
- 'At least one allowed command must be specified',
- 'EMPTY_ALLOWLIST'
- );
- }
-
- // Check for dangerous commands in allowlist
- const dangerousAllowed = this.config.allowedCommands.filter(
- cmd => DANGEROUS_COMMANDS.includes(path.basename(cmd))
- );
-
- if (dangerousAllowed.length > 0) {
- throw new SafeExecutorError(
- `Dangerous commands cannot be allowed: ${dangerousAllowed.join(', ')}`,
- 'DANGEROUS_COMMAND_ALLOWED'
- );
- }
- }
-
- /**
- * Validates a command against the allowlist.
- *
- * @param command - Command to validate
- * @throws SafeExecutorError if command is not allowed
- */
- private validateCommand(command: string): void {
- const basename = path.basename(command);
-
- // Check if command is allowed
- const isAllowed = this.config.allowedCommands.some(allowed => {
- const allowedBasename = path.basename(allowed);
- return command === allowed || basename === allowedBasename;
- });
-
- if (!isAllowed) {
- throw new SafeExecutorError(
- `Command not in allowlist: ${command}`,
- 'COMMAND_NOT_ALLOWED',
- command
- );
- }
-
- // Check for sudo
- if (!this.config.allowSudo && (command === 'sudo' || basename === 'sudo')) {
- throw new SafeExecutorError(
- 'Sudo commands are not allowed',
- 'SUDO_NOT_ALLOWED',
- command
- );
- }
- }
-
- /**
- * Validates command arguments for injection patterns.
- *
- * @param args - Arguments to validate
- * @throws SafeExecutorError if arguments contain dangerous patterns
- */
- private validateArguments(args: string[]): void {
- for (const arg of args) {
- // Check for null bytes
- if (arg.includes('\0')) {
- throw new SafeExecutorError(
- 'Null byte detected in argument',
- 'NULL_BYTE_INJECTION',
- undefined,
- args
- );
- }
-
- // Check against blocked patterns
- for (const pattern of this.blockedPatterns) {
- if (pattern.test(arg)) {
- throw new SafeExecutorError(
- `Dangerous pattern detected in argument: ${arg}`,
- 'DANGEROUS_PATTERN',
- undefined,
- args
- );
- }
- }
-
- // Check for command chaining attempts
- if (/^-.*[;&|]/.test(arg)) {
- throw new SafeExecutorError(
- `Potential command chaining in argument: ${arg}`,
- 'COMMAND_CHAINING',
- undefined,
- args
- );
- }
- }
- }
-
- /**
- * Sanitizes a single argument.
- *
- * @param arg - Argument to sanitize
- * @returns Sanitized argument
- */
- sanitizeArgument(arg: string): string {
- // Remove null bytes
- let sanitized = arg.replace(/\0/g, '');
-
- // Remove shell metacharacters
- sanitized = sanitized.replace(/[;&|`$(){}><\n\r]/g, '');
-
- return sanitized;
- }
-
- /**
- * Executes a command safely.
- *
- * @param command - Command to execute (must be in allowlist)
- * @param args - Command arguments
- * @returns Execution result
- * @throws SafeExecutorError on validation failure or execution error
- */
- async execute(command: string, args: string[] = []): Promise<ExecutionResult> {
- const startTime = Date.now();
-
- // Validate command
- this.validateCommand(command);
-
- // Validate arguments
- this.validateArguments(args);
-
- try {
- // Execute command WITHOUT shell
- const { stdout, stderr } = await execFileAsync(command, args, {
- cwd: this.config.cwd,
- env: this.config.env,
- timeout: this.config.timeout,
- maxBuffer: this.config.maxBuffer,
- shell: false, // CRITICAL: Never use shell
- windowsHide: true,
- });
-
- return {
- stdout: stdout.toString(),
- stderr: stderr.toString(),
- exitCode: 0,
- command,
- args,
- duration: Date.now() - startTime,
- };
- } catch (error: any) {
- // Handle execution errors
- if (error.killed) {
- throw new SafeExecutorError(
- 'Command execution timed out',
- 'TIMEOUT',
- command,
- args
- );
- }
-
- if (error.code === 'ENOENT') {
- throw new SafeExecutorError(
- `Command not found: ${command}`,
- 'COMMAND_NOT_FOUND',
- command,
- args
- );
- }
-
- // Return result with non-zero exit code
- return {
- stdout: error.stdout?.toString() ?? '',
- stderr: error.stderr?.toString() ?? error.message,
- exitCode: error.code ?? 1,
- command,
- args,
- duration: Date.now() - startTime,
- };
- }
- }
-
- /**
- * Executes a command with streaming output.
- *
- * @param command - Command to execute
- * @param args - Command arguments
- * @returns Streaming executor with process handles
- */
- executeStreaming(command: string, args: string[] = []): StreamingExecutor {
- const startTime = Date.now();
-
- // Validate command
- this.validateCommand(command);
-
- // Validate arguments
- this.validateArguments(args);
-
- // Spawn process WITHOUT shell
- const childProcess = spawn(command, args, {
- cwd: this.config.cwd,
- env: this.config.env,
- timeout: this.config.timeout,
- shell: false, // CRITICAL: Never use shell
- windowsHide: true,
- });
-
- const promise = new Promise<ExecutionResult>((resolve, reject) => {
- let stdout = '';
- let stderr = '';
-
- childProcess.stdout?.on('data', (data: Buffer) => {
- stdout += data.toString();
- });
-
- childProcess.stderr?.on('data', (data: Buffer) => {
- stderr += data.toString();
- });
-
- childProcess.on('close', (code) => {
- resolve({
- stdout,
- stderr,
- exitCode: code ?? 0,
- command,
- args,
- duration: Date.now() - startTime,
- });
- });
-
- childProcess.on('error', (error) => {
- reject(new SafeExecutorError(
- error.message,
- 'EXECUTION_ERROR',
- command,
- args
- ));
- });
- });
-
- return {
- process: childProcess,
- stdout: childProcess.stdout,
- stderr: childProcess.stderr,
- promise,
- };
- }
-
- /**
- * Adds a command to the allowlist at runtime.
- *
- * @param command - Command to add
- */
- allowCommand(command: string): void {
- const basename = path.basename(command);
-
- if (DANGEROUS_COMMANDS.includes(basename)) {
- throw new SafeExecutorError(
- `Cannot allow dangerous command: ${command}`,
- 'DANGEROUS_COMMAND'
- );
- }
-
- if (!this.config.allowedCommands.includes(command)) {
- this.config.allowedCommands.push(command);
- }
- }
-
- /**
- * Checks if a command is allowed.
- *
- * @param command - Command to check
- * @returns True if command is allowed
- */
- isCommandAllowed(command: string): boolean {
- const basename = path.basename(command);
- return this.config.allowedCommands.some(allowed => {
- const allowedBasename = path.basename(allowed);
- return command === allowed || basename === allowedBasename;
- });
- }
-
- /**
- * Returns the current allowlist.
- */
- getAllowedCommands(): readonly string[] {
- return [...this.config.allowedCommands];
- }
-}
-
-/**
- * Factory function to create a safe executor for common development tasks.
- *
- * @returns Configured SafeExecutor for git, npm, and node
- */
-export function createDevelopmentExecutor(): SafeExecutor {
- return new SafeExecutor({
- allowedCommands: [
- 'git',
- 'npm',
- 'npx',
- 'node',
- 'tsc',
- 'vitest',
- 'eslint',
- 'prettier',
- ],
- });
-}
-
-/**
- * Factory function to create a read-only executor.
- * Only allows commands that read without modifying.
- *
- * @returns Configured SafeExecutor for read operations
- */
-export function createReadOnlyExecutor(): SafeExecutor {
- return new SafeExecutor({
- allowedCommands: [
- 'git',
- 'cat',
- 'head',
- 'tail',
- 'ls',
- 'find',
- 'grep',
- 'which',
- 'echo',
- ],
- timeout: 10000,
- });
-}
diff --git a/v3/security/token-generator.ts b/v3/security/token-generator.ts
deleted file mode 100644
index 630fec12bc..0000000000
--- a/v3/security/token-generator.ts
+++ /dev/null
@@ -1,463 +0,0 @@
-/**
- * Token Generator - Secure Token Generation
- *
- * Provides cryptographically secure token generation for:
- * - JWT tokens
- * - Session tokens
- * - CSRF tokens
- * - API tokens
- * - Verification codes
- *
- * Security Properties:
- * - Uses crypto.randomBytes for all randomness
- * - Configurable entropy levels
- * - Timing-safe comparison
- * - Token expiration handling
- *
- * @module v3/security/token-generator
- */
-
-import { randomBytes, createHmac, timingSafeEqual } from 'crypto';
-
-export interface TokenConfig {
- /**
- * Default token length in bytes.
- * Default: 32 (256 bits)
- */
- defaultLength?: number;
-
- /**
- * Token encoding format.
- * Default: 'base64url'
- */
- encoding?: 'hex' | 'base64' | 'base64url';
-
- /**
- * HMAC secret for signed tokens.
- */
- hmacSecret?: string;
-
- /**
- * Default expiration time in seconds.
- * Default: 3600 (1 hour)
- */
- defaultExpiration?: number;
-}
-
-export interface Token {
- value: string;
- createdAt: Date;
- expiresAt: Date;
- metadata?: Record<string, unknown>;
-}
-
-export interface SignedToken {
- token: string;
- signature: string;
- combined: string;
- createdAt: Date;
- expiresAt: Date;
-}
-
-export interface VerificationCode {
- code: string;
- createdAt: Date;
- expiresAt: Date;
- attempts: number;
- maxAttempts: number;
-}
-
-export class TokenGeneratorError extends Error {
- constructor(
- message: string,
- public readonly code: string,
- ) {
- super(message);
- this.name = 'TokenGeneratorError';
- }
-}
-
-/**
- * Secure token generator.
- *
- * @example
- * ```typescript
- * const generator = new TokenGenerator({ hmacSecret: 'secret' });
- *
- * // Generate session token
- * const session = generator.generateSessionToken();
- *
- * // Generate signed token
- * const signed = generator.generateSignedToken({ userId: '123' });
- *
- * // Verify signed token
- * const isValid = generator.verifySignedToken(signed.combined);
- * ```
- */
-export class TokenGenerator {
- private readonly config: Required<TokenConfig>;
-
- constructor(config: TokenConfig = {}) {
- this.config = {
- defaultLength: config.defaultLength ?? 32,
- encoding: config.encoding ?? 'base64url',
- hmacSecret: config.hmacSecret ?? '',
- defaultExpiration: config.defaultExpiration ?? 3600,
- };
-
- if (this.config.defaultLength < 16) {
- throw new TokenGeneratorError(
- 'Token length must be at least 16 bytes',
- 'INVALID_LENGTH'
- );
- }
- }
-
- /**
- * Generates a random token.
- *
- * @param length - Token length in bytes
- * @returns Random token string
- */
- generate(length?: number): string {
- const len = length ?? this.config.defaultLength;
- const buffer = randomBytes(len);
- return this.encode(buffer);
- }
-
- /**
- * Generates a token with expiration.
- *
- * @param expirationSeconds - Expiration time in seconds
- * @param metadata - Optional metadata to attach
- * @returns Token with expiration
- */
- generateWithExpiration(
- expirationSeconds?: number,
- metadata?: Record<string, unknown>
- ): Token {
- const expiration = expirationSeconds ?? this.config.defaultExpiration;
- const now = new Date();
- const expiresAt = new Date(now.getTime() + expiration * 1000);
-
- return {
- value: this.generate(),
- createdAt: now,
- expiresAt,
- metadata,
- };
- }
-
- /**
- * Generates a session token (URL-safe).
- *
- * @param length - Token length in bytes (default: 32)
- * @returns Session token
- */
- generateSessionToken(length = 32): Token {
- return this.generateWithExpiration(this.config.defaultExpiration);
- }
-
- /**
- * Generates a CSRF token.
- *
- * @returns CSRF token (shorter expiration)
- */
- generateCsrfToken(): Token {
- return this.generateWithExpiration(1800); // 30 minutes
- }
-
- /**
- * Generates an API token with prefix.
- *
- * @param prefix - Token prefix (e.g., 'cf_')
- * @returns Prefixed API token
- */
- generateApiToken(prefix = 'cf_'): Token {
- const tokenBody = this.generate(32);
- const now = new Date();
-
- return {
- value: `${prefix}${tokenBody}`,
- createdAt: now,
- expiresAt: new Date(now.getTime() + 365 * 24 * 60 * 60 * 1000), // 1 year
- };
- }
-
- /**
- * Generates a numeric verification code.
- *
- * @param length - Number of digits (default: 6)
- * @param expirationMinutes - Expiration in minutes (default: 10)
- * @param maxAttempts - Maximum verification attempts (default: 3)
- * @returns Verification code
- */
- generateVerificationCode(
- length = 6,
- expirationMinutes = 10,
- maxAttempts = 3
- ): VerificationCode {
- const buffer = randomBytes(length);
- let code = '';
-
- for (let i = 0; i < length; i++) {
- code += (buffer[i] % 10).toString();
- }
-
- const now = new Date();
-
- return {
- code,
- createdAt: now,
- expiresAt: new Date(now.getTime() + expirationMinutes * 60 * 1000),
- attempts: 0,
- maxAttempts,
- };
- }
-
- /**
- * Generates a signed token using HMAC.
- *
- * @param payload - Data to include in token
- * @param expirationSeconds - Token expiration
- * @returns Signed token
- */
- generateSignedToken(
- payload: Record<string, unknown>,
- expirationSeconds?: number
- ): SignedToken {
- if (!this.config.hmacSecret) {
- throw new TokenGeneratorError(
- 'HMAC secret required for signed tokens',
- 'NO_SECRET'
- );
- }
-
- const expiration = expirationSeconds ?? this.config.defaultExpiration;
- const now = new Date();
- const expiresAt = new Date(now.getTime() + expiration * 1000);
-
- const tokenData = {
- ...payload,
- iat: now.getTime(),
- exp: expiresAt.getTime(),
- nonce: this.generate(8),
- };
-
- const token = Buffer.from(JSON.stringify(tokenData)).toString('base64url');
- const signature = this.sign(token);
-
- return {
- token,
- signature,
- combined: `${token}.${signature}`,
- createdAt: now,
- expiresAt,
- };
- }
-
- /**
- * Verifies a signed token.
- *
- * @param combined - Combined token string (token.signature)
- * @returns Decoded payload if valid, null otherwise
- */
- verifySignedToken(combined: string): Record<string, unknown> | null {
- if (!this.config.hmacSecret) {
- throw new TokenGeneratorError(
- 'HMAC secret required for signed tokens',
- 'NO_SECRET'
- );
- }
-
- const parts = combined.split('.');
- if (parts.length !== 2) {
- return null;
- }
-
- const [token, signature] = parts;
-
- // Verify signature
- const expectedSignature = this.sign(token);
-
- try {
- const sigBuffer = Buffer.from(signature, 'base64url');
- const expectedBuffer = Buffer.from(expectedSignature, 'base64url');
-
- if (sigBuffer.length !== expectedBuffer.length) {
- return null;
- }
-
- if (!timingSafeEqual(sigBuffer, expectedBuffer)) {
- return null;
- }
- } catch {
- return null;
- }
-
- // Decode and validate payload
- try {
- const payload = JSON.parse(Buffer.from(token, 'base64url').toString());
-
- // Check expiration
- if (payload.exp && payload.exp < Date.now()) {
- return null;
- }
-
- return payload;
- } catch {
- return null;
- }
- }
-
- /**
- * Generates a refresh token pair.
- *
- * @returns Access and refresh tokens
- */
- generateTokenPair(): {
- accessToken: Token;
- refreshToken: Token;
- } {
- return {
- accessToken: this.generateWithExpiration(900), // 15 minutes
- refreshToken: this.generateWithExpiration(604800), // 7 days
- };
- }
-
- /**
- * Generates a password reset token.
- *
- * @returns Password reset token (short expiration)
- */
- generatePasswordResetToken(): Token {
- return this.generateWithExpiration(1800); // 30 minutes
- }
-
- /**
- * Generates an email verification token.
- *
- * @returns Email verification token
- */
- generateEmailVerificationToken(): Token {
- return this.generateWithExpiration(86400); // 24 hours
- }
-
- /**
- * Generates a unique request ID.
- *
- * @returns Request ID (shorter, for logging)
- */
- generateRequestId(): string {
- return this.generate(8);
- }
-
- /**
- * Generates a correlation ID for distributed tracing.
- *
- * @returns Correlation ID
- */
- generateCorrelationId(): string {
- const timestamp = Date.now().toString(36);
- const random = this.generate(8);
- return `${timestamp}-${random}`;
- }
-
- /**
- * Checks if a token has expired.
- *
- * @param token - Token to check
- * @returns True if expired
- */
- isExpired(token: Token | VerificationCode): boolean {
- return token.expiresAt < new Date();
- }
-
- /**
- * Compares two tokens in constant time.
- *
- * @param a - First token
- * @param b - Second token
- * @returns True if equal
- */
- compare(a: string, b: string): boolean {
- if (a.length !== b.length) {
- return false;
- }
-
- try {
- const bufferA = Buffer.from(a);
- const bufferB = Buffer.from(b);
- return timingSafeEqual(bufferA, bufferB);
- } catch {
- return false;
- }
- }
-
- /**
- * Signs data using HMAC-SHA256.
- */
- private sign(data: string): string {
- return createHmac('sha256', this.config.hmacSecret)
- .update(data)
- .digest('base64url');
- }
-
- /**
- * Encodes bytes according to configuration.
- */
- private encode(buffer: Buffer): string {
- switch (this.config.encoding) {
- case 'hex':
- return buffer.toString('hex');
- case 'base64':
- return buffer.toString('base64');
- case 'base64url':
- default:
- return buffer.toString('base64url');
- }
- }
-}
-
-/**
- * Factory function to create a production token generator.
- *
- * @param hmacSecret - HMAC secret for signed tokens
- * @returns Configured TokenGenerator
- */
-export function createTokenGenerator(hmacSecret: string): TokenGenerator {
- return new TokenGenerator({
- hmacSecret,
- defaultLength: 32,
- encoding: 'base64url',
- });
-}
-
-/**
- * Singleton instance for quick token generation without configuration.
- */
-let defaultGenerator: TokenGenerator | null = null;
-
-/**
- * Gets or creates the default token generator.
- * Note: Does not support signed tokens without configuration.
- */
-export function getDefaultGenerator(): TokenGenerator {
- if (!defaultGenerator) {
- defaultGenerator = new TokenGenerator();
- }
- return defaultGenerator;
-}
-
-/**
- * Quick token generation functions.
- */
-export const quickGenerate = {
- token: (length = 32) => getDefaultGenerator().generate(length),
- sessionToken: () => getDefaultGenerator().generateSessionToken(),
- csrfToken: () => getDefaultGenerator().generateCsrfToken(),
- apiToken: (prefix = 'cf_') => getDefaultGenerator().generateApiToken(prefix),
- verificationCode: (length = 6) => getDefaultGenerator().generateVerificationCode(length),
- requestId: () => getDefaultGenerator().generateRequestId(),
- correlationId: () => getDefaultGenerator().generateCorrelationId(),
-};
diff --git a/v3/swarm/agent-pool.ts b/v3/swarm/agent-pool.ts
deleted file mode 100644
index a913e3e0b2..0000000000
--- a/v3/swarm/agent-pool.ts
+++ /dev/null
@@ -1,474 +0,0 @@
-/**
- * V3 Agent Pool
- * Manages agent lifecycle, pooling, and auto-scaling
- */
-
-import { EventEmitter } from 'events';
-import {
- AgentState,
- AgentType,
- AgentStatus,
- AgentCapabilities,
- AgentMetrics,
- AgentPoolConfig,
- AgentPoolState,
- IAgentPool,
- SWARM_CONSTANTS,
-} from './types.js';
-
-interface PooledAgent {
- agent: AgentState;
- acquiredAt?: Date;
- lastUsed: Date;
- usageCount: number;
-}
-
-export class AgentPool extends EventEmitter implements IAgentPool {
- private config: AgentPoolConfig;
- private pooledAgents: Map<string, PooledAgent> = new Map();
- private available: Set<string> = new Set();
- private busy: Set<string> = new Set();
- private pendingScale: number = 0;
- private lastScaleOperation?: Date;
- private healthCheckInterval?: NodeJS.Timeout;
- private agentCounter: number = 0;
-
- constructor(config: Partial<AgentPoolConfig> = {}) {
- super();
- this.config = {
- name: config.name ?? 'default-pool',
- type: config.type ?? 'worker',
- minSize: config.minSize ?? 1,
- maxSize: config.maxSize ?? 10,
- scaleUpThreshold: config.scaleUpThreshold ?? 0.8,
- scaleDownThreshold: config.scaleDownThreshold ?? 0.2,
- cooldownMs: config.cooldownMs ?? 30000,
- healthCheckIntervalMs: config.healthCheckIntervalMs ?? SWARM_CONSTANTS.DEFAULT_HEALTH_CHECK_INTERVAL_MS,
- };
- }
-
- async initialize(config?: AgentPoolConfig): Promise<void> {
- if (config) {
- this.config = { ...this.config, ...config };
- }
-
- // Start with minimum pool size
- for (let i = 0; i < this.config.minSize; i++) {
- await this.createPooledAgent();
- }
-
- // Start health checks
- this.startHealthChecks();
-
- this.emit('initialized', {
- poolName: this.config.name,
- size: this.pooledAgents.size
- });
- }
-
- async shutdown(): Promise<void> {
- if (this.healthCheckInterval) {
- clearInterval(this.healthCheckInterval);
- this.healthCheckInterval = undefined;
- }
-
- // Mark all agents as terminated
- for (const pooled of this.pooledAgents.values()) {
- pooled.agent.status = 'terminated';
- }
-
- this.pooledAgents.clear();
- this.available.clear();
- this.busy.clear();
-
- this.emit('shutdown');
- }
-
- async acquire(): Promise<AgentState | undefined> {
- // Try to get an available agent
- const availableId = this.available.values().next().value as string | undefined;
-
- if (availableId) {
- const pooled = this.pooledAgents.get(availableId);
- if (pooled) {
- this.available.delete(availableId);
- this.busy.add(availableId);
- pooled.acquiredAt = new Date();
- pooled.usageCount++;
- pooled.agent.status = 'busy';
-
- this.emit('agent.acquired', { agentId: availableId });
-
- // Check if we need to scale up
- await this.checkScaling();
-
- return pooled.agent;
- }
- }
-
- // No available agents, try to scale up
- if (this.pooledAgents.size < this.config.maxSize) {
- const agent = await this.createPooledAgent();
- if (agent) {
- const pooled = this.pooledAgents.get(agent.id.id)!;
- this.available.delete(agent.id.id);
- this.busy.add(agent.id.id);
- pooled.acquiredAt = new Date();
- pooled.usageCount++;
- agent.status = 'busy';
-
- this.emit('agent.acquired', { agentId: agent.id.id });
-
- return agent;
- }
- }
-
- // Pool exhausted
- this.emit('pool.exhausted');
- return undefined;
- }
-
- async release(agentId: string): Promise<void> {
- const pooled = this.pooledAgents.get(agentId);
- if (!pooled) {
- return;
- }
-
- this.busy.delete(agentId);
- this.available.add(agentId);
- pooled.acquiredAt = undefined;
- pooled.lastUsed = new Date();
- pooled.agent.status = 'idle';
- pooled.agent.currentTask = undefined;
-
- this.emit('agent.released', { agentId });
-
- // Check if we need to scale down
- await this.checkScaling();
- }
-
- async add(agent: AgentState): Promise<void> {
- if (this.pooledAgents.size >= this.config.maxSize) {
- throw new Error(`Pool ${this.config.name} is at maximum capacity`);
- }
-
- const pooled: PooledAgent = {
- agent,
- lastUsed: new Date(),
- usageCount: 0,
- };
-
- this.pooledAgents.set(agent.id.id, pooled);
- this.available.add(agent.id.id);
-
- this.emit('agent.added', { agentId: agent.id.id });
- }
-
- async remove(agentId: string): Promise<void> {
- const pooled = this.pooledAgents.get(agentId);
- if (!pooled) {
- return;
- }
-
- this.pooledAgents.delete(agentId);
- this.available.delete(agentId);
- this.busy.delete(agentId);
- pooled.agent.status = 'terminated';
-
- this.emit('agent.removed', { agentId });
- }
-
- async scale(delta: number): Promise<void> {
- const now = new Date();
-
- // Check cooldown
- if (this.lastScaleOperation) {
- const timeSinceLastScale = now.getTime() - this.lastScaleOperation.getTime();
- if (timeSinceLastScale < this.config.cooldownMs) {
- return;
- }
- }
-
- if (delta > 0) {
- // Scale up
- const targetSize = Math.min(
- this.pooledAgents.size + delta,
- this.config.maxSize
- );
- const toCreate = targetSize - this.pooledAgents.size;
-
- for (let i = 0; i < toCreate; i++) {
- await this.createPooledAgent();
- }
-
- this.emit('pool.scaled_up', { added: toCreate });
- } else if (delta < 0) {
- // Scale down
- const targetSize = Math.max(
- this.pooledAgents.size + delta,
- this.config.minSize
- );
- const toRemove = this.pooledAgents.size - targetSize;
-
- // Remove least recently used available agents
- const sortedAvailable = Array.from(this.available)
- .map(id => this.pooledAgents.get(id)!)
- .filter(p => p !== undefined)
- .sort((a, b) => a.lastUsed.getTime() - b.lastUsed.getTime());
-
- for (let i = 0; i < toRemove && sortedAvailable.length > 0; i++) {
- const pooled = sortedAvailable.shift()!;
- await this.remove(pooled.agent.id.id);
- }
-
- this.emit('pool.scaled_down', { removed: toRemove });
- }
-
- this.lastScaleOperation = now;
- }
-
- getState(): AgentPoolState {
- return {
- id: `pool_${this.config.name}`,
- config: { ...this.config },
- agents: new Map(
- Array.from(this.pooledAgents.entries()).map(
- ([id, pooled]) => [id, pooled.agent]
- )
- ),
- availableAgents: Array.from(this.available),
- busyAgents: Array.from(this.busy),
- pendingScale: this.pendingScale,
- lastScaleOperation: this.lastScaleOperation,
- };
- }
-
- getAvailableCount(): number {
- return this.available.size;
- }
-
- getBusyCount(): number {
- return this.busy.size;
- }
-
- getTotalCount(): number {
- return this.pooledAgents.size;
- }
-
- getUtilization(): number {
- if (this.pooledAgents.size === 0) return 0;
- return this.busy.size / this.pooledAgents.size;
- }
-
- // ===== PRIVATE METHODS =====
-
- private async createPooledAgent(): Promise<AgentState | undefined> {
- if (this.pooledAgents.size >= this.config.maxSize) {
- return undefined;
- }
-
- this.agentCounter++;
- const agentId = `${this.config.name}_agent_${this.agentCounter}`;
-
- const agent: AgentState = {
- id: {
- id: agentId,
- swarmId: 'pool',
- type: this.config.type,
- instance: this.agentCounter,
- },
- name: `${this.config.name}-${this.agentCounter}`,
- type: this.config.type,
- status: 'idle',
- capabilities: this.createDefaultCapabilities(),
- metrics: this.createDefaultMetrics(),
- workload: 0,
- health: 1.0,
- lastHeartbeat: new Date(),
- connections: [],
- };
-
- const pooled: PooledAgent = {
- agent,
- lastUsed: new Date(),
- usageCount: 0,
- };
-
- this.pooledAgents.set(agentId, pooled);
- this.available.add(agentId);
-
- this.emit('agent.created', { agentId });
-
- return agent;
- }
-
- private createDefaultCapabilities(): AgentCapabilities {
- return {
- codeGeneration: true,
- codeReview: true,
- testing: true,
- documentation: true,
- research: true,
- analysis: true,
- coordination: this.config.type === 'coordinator',
- languages: ['typescript', 'javascript', 'python'],
- frameworks: ['node', 'deno', 'react'],
- domains: ['development', 'testing', 'analysis'],
- tools: ['git', 'npm', 'editor'],
- maxConcurrentTasks: 3,
- maxMemoryUsage: 512 * 1024 * 1024,
- maxExecutionTime: SWARM_CONSTANTS.DEFAULT_TASK_TIMEOUT_MS,
- reliability: 0.95,
- speed: 1.0,
- quality: 0.9,
- };
- }
-
- private createDefaultMetrics(): AgentMetrics {
- return {
- tasksCompleted: 0,
- tasksFailed: 0,
- averageExecutionTime: 0,
- successRate: 1.0,
- cpuUsage: 0,
- memoryUsage: 0,
- messagesProcessed: 0,
- lastActivity: new Date(),
- responseTime: 0,
- health: 1.0,
- };
- }
-
- private async checkScaling(): Promise<void> {
- const utilization = this.getUtilization();
-
- if (utilization >= this.config.scaleUpThreshold &&
- this.pooledAgents.size < this.config.maxSize) {
- // Scale up by 1
- this.pendingScale = 1;
- await this.scale(1);
- this.pendingScale = 0;
- } else if (utilization <= this.config.scaleDownThreshold &&
- this.pooledAgents.size > this.config.minSize) {
- // Scale down by 1
- this.pendingScale = -1;
- await this.scale(-1);
- this.pendingScale = 0;
- }
- }
-
- private startHealthChecks(): void {
- this.healthCheckInterval = setInterval(() => {
- this.performHealthChecks();
- }, this.config.healthCheckIntervalMs);
- }
-
- private performHealthChecks(): void {
- const now = new Date();
- const unhealthyThresholdMs = this.config.healthCheckIntervalMs * 3;
-
- for (const [agentId, pooled] of this.pooledAgents) {
- const timeSinceLastActivity = now.getTime() - pooled.agent.lastHeartbeat.getTime();
-
- if (timeSinceLastActivity > unhealthyThresholdMs) {
- // Agent is unhealthy
- pooled.agent.health = Math.max(0, pooled.agent.health - 0.2);
- pooled.agent.status = 'error';
-
- this.emit('agent.unhealthy', { agentId, health: pooled.agent.health });
-
- // If completely unhealthy, remove and replace
- if (pooled.agent.health <= 0) {
- this.replaceUnhealthyAgent(agentId);
- }
- } else {
- // Update health positively
- pooled.agent.health = Math.min(1.0, pooled.agent.health + 0.1);
- pooled.agent.lastHeartbeat = now;
- }
- }
- }
-
- private async replaceUnhealthyAgent(agentId: string): Promise<void> {
- const pooled = this.pooledAgents.get(agentId);
- if (!pooled) return;
-
- const wasBusy = this.busy.has(agentId);
- await this.remove(agentId);
-
- // Create replacement if below min size or was busy
- if (this.pooledAgents.size < this.config.minSize || wasBusy) {
- await this.createPooledAgent();
- }
-
- this.emit('agent.replaced', { oldAgentId: agentId });
- }
-
- // ===== UTILITY METHODS =====
-
- getAgent(agentId: string): AgentState | undefined {
- return this.pooledAgents.get(agentId)?.agent;
- }
-
- getAllAgents(): AgentState[] {
- return Array.from(this.pooledAgents.values()).map(p => p.agent);
- }
-
- getAvailableAgents(): AgentState[] {
- return Array.from(this.available)
- .map(id => this.pooledAgents.get(id)?.agent)
- .filter((a): a is AgentState => a !== undefined);
- }
-
- getBusyAgents(): AgentState[] {
- return Array.from(this.busy)
- .map(id => this.pooledAgents.get(id)?.agent)
- .filter((a): a is AgentState => a !== undefined);
- }
-
- updateAgentHeartbeat(agentId: string): void {
- const pooled = this.pooledAgents.get(agentId);
- if (pooled) {
- pooled.agent.lastHeartbeat = new Date();
- pooled.agent.health = Math.min(1.0, pooled.agent.health + 0.05);
- }
- }
-
- updateAgentMetrics(agentId: string, metrics: Partial<AgentMetrics>): void {
- const pooled = this.pooledAgents.get(agentId);
- if (pooled) {
- pooled.agent.metrics = { ...pooled.agent.metrics, ...metrics };
- pooled.agent.lastHeartbeat = new Date();
- }
- }
-
- getPoolStats(): {
- total: number;
- available: number;
- busy: number;
- utilization: number;
- avgHealth: number;
- avgUsageCount: number;
- } {
- const agents = Array.from(this.pooledAgents.values());
- const avgHealth = agents.length > 0
- ? agents.reduce((sum, p) => sum + p.agent.health, 0) / agents.length
- : 1.0;
- const avgUsageCount = agents.length > 0
- ? agents.reduce((sum, p) => sum + p.usageCount, 0) / agents.length
- : 0;
-
- return {
- total: this.pooledAgents.size,
- available: this.available.size,
- busy: this.busy.size,
- utilization: this.getUtilization(),
- avgHealth,
- avgUsageCount,
- };
- }
-}
-
-export function createAgentPool(config?: Partial<AgentPoolConfig>): AgentPool {
- return new AgentPool(config);
-}
diff --git a/v3/swarm/consensus/byzantine.ts b/v3/swarm/consensus/byzantine.ts
deleted file mode 100644
index 34dd7f9e45..0000000000
--- a/v3/swarm/consensus/byzantine.ts
+++ /dev/null
@@ -1,431 +0,0 @@
-/**
- * V3 Byzantine Fault Tolerant Consensus
- * PBFT-style consensus for handling malicious or faulty nodes
- */
-
-import { EventEmitter } from 'events';
-import {
- ConsensusProposal,
- ConsensusVote,
- ConsensusResult,
- ConsensusConfig,
- SWARM_CONSTANTS,
-} from '../types.js';
-
-export type ByzantinePhase = 'pre-prepare' | 'prepare' | 'commit' | 'reply';
-
-export interface ByzantineMessage {
- type: ByzantinePhase;
- viewNumber: number;
- sequenceNumber: number;
- digest: string;
- senderId: string;
- timestamp: Date;
- payload?: unknown;
- signature?: string;
-}
-
-export interface ByzantineNode {
- id: string;
- isPrimary: boolean;
- viewNumber: number;
- sequenceNumber: number;
- preparedMessages: Map<string, ByzantineMessage[]>;
- committedMessages: Map<string, ByzantineMessage[]>;
-}
-
-export interface ByzantineConfig extends Partial<ConsensusConfig> {
- maxFaultyNodes?: number;
- viewChangeTimeoutMs?: number;
-}
-
-export class ByzantineConsensus extends EventEmitter {
- private config: ByzantineConfig;
- private node: ByzantineNode;
- private nodes: Map<string, ByzantineNode> = new Map();
- private proposals: Map<string, ConsensusProposal> = new Map();
- private messageLog: Map<string, ByzantineMessage[]> = new Map();
- private proposalCounter: number = 0;
- private viewChangeTimeout?: NodeJS.Timeout;
-
- constructor(nodeId: string, config: ByzantineConfig = {}) {
- super();
- this.config = {
- threshold: config.threshold ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_THRESHOLD,
- timeoutMs: config.timeoutMs ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_TIMEOUT_MS,
- maxRounds: config.maxRounds ?? 10,
- requireQuorum: config.requireQuorum ?? true,
- maxFaultyNodes: config.maxFaultyNodes ?? 1,
- viewChangeTimeoutMs: config.viewChangeTimeoutMs ?? 5000,
- };
-
- this.node = {
- id: nodeId,
- isPrimary: false,
- viewNumber: 0,
- sequenceNumber: 0,
- preparedMessages: new Map(),
- committedMessages: new Map(),
- };
- }
-
- async initialize(): Promise<void> {
- this.emit('initialized', { nodeId: this.node.id });
- }
-
- async shutdown(): Promise<void> {
- if (this.viewChangeTimeout) {
- clearTimeout(this.viewChangeTimeout);
- }
- this.emit('shutdown');
- }
-
- addNode(nodeId: string, isPrimary: boolean = false): void {
- this.nodes.set(nodeId, {
- id: nodeId,
- isPrimary,
- viewNumber: 0,
- sequenceNumber: 0,
- preparedMessages: new Map(),
- committedMessages: new Map(),
- });
-
- if (isPrimary && this.node.id === nodeId) {
- this.node.isPrimary = true;
- }
- }
-
- removeNode(nodeId: string): void {
- this.nodes.delete(nodeId);
- }
-
- electPrimary(): string {
- const nodeIds = [this.node.id, ...Array.from(this.nodes.keys())];
- const primaryIndex = this.node.viewNumber % nodeIds.length;
- const primaryId = nodeIds[primaryIndex];
-
- this.node.isPrimary = primaryId === this.node.id;
-
- for (const [id, node] of this.nodes) {
- node.isPrimary = id === primaryId;
- }
-
- this.emit('primary.elected', { primaryId, viewNumber: this.node.viewNumber });
-
- return primaryId;
- }
-
- async propose(value: unknown): Promise<ConsensusProposal> {
- if (!this.node.isPrimary) {
- throw new Error('Only primary can propose values');
- }
-
- this.proposalCounter++;
- const sequenceNumber = ++this.node.sequenceNumber;
- const digest = this.computeDigest(value);
- const proposalId = `bft_${this.node.viewNumber}_${sequenceNumber}`;
-
- const proposal: ConsensusProposal = {
- id: proposalId,
- proposerId: this.node.id,
- value,
- term: this.node.viewNumber,
- timestamp: new Date(),
- votes: new Map(),
- status: 'pending',
- };
-
- this.proposals.set(proposalId, proposal);
-
- // Phase 1: Pre-prepare
- const prePrepareMsg: ByzantineMessage = {
- type: 'pre-prepare',
- viewNumber: this.node.viewNumber,
- sequenceNumber,
- digest,
- senderId: this.node.id,
- timestamp: new Date(),
- payload: value,
- };
-
- await this.broadcastMessage(prePrepareMsg);
-
- // Self-prepare
- await this.handlePrepare({
- type: 'prepare',
- viewNumber: this.node.viewNumber,
- sequenceNumber,
- digest,
- senderId: this.node.id,
- timestamp: new Date(),
- });
-
- return proposal;
- }
-
- async vote(proposalId: string, vote: ConsensusVote): Promise<void> {
- const proposal = this.proposals.get(proposalId);
- if (!proposal || proposal.status !== 'pending') {
- return;
- }
-
- proposal.votes.set(vote.voterId, vote);
-
- // Check consensus
- const f = this.config.maxFaultyNodes ?? 1;
- const n = this.nodes.size + 1;
- const requiredVotes = 2 * f + 1;
-
- const approvingVotes = Array.from(proposal.votes.values()).filter(
- v => v.approve
- ).length;
-
- if (approvingVotes >= requiredVotes) {
- proposal.status = 'accepted';
- this.emit('consensus.achieved', { proposalId, approved: true });
- } else if (proposal.votes.size >= n && approvingVotes < requiredVotes) {
- proposal.status = 'rejected';
- this.emit('consensus.achieved', { proposalId, approved: false });
- }
- }
-
- async awaitConsensus(proposalId: string): Promise<ConsensusResult> {
- const startTime = Date.now();
-
- return new Promise((resolve, reject) => {
- const checkInterval = setInterval(() => {
- const proposal = this.proposals.get(proposalId);
- if (!proposal) {
- clearInterval(checkInterval);
- reject(new Error(`Proposal ${proposalId} not found`));
- return;
- }
-
- if (proposal.status !== 'pending') {
- clearInterval(checkInterval);
- resolve(this.createResult(proposal, Date.now() - startTime));
- return;
- }
-
- if (Date.now() - startTime > (this.config.timeoutMs ?? 30000)) {
- clearInterval(checkInterval);
- proposal.status = 'expired';
- resolve(this.createResult(proposal, Date.now() - startTime));
- }
- }, 10);
- });
- }
-
- // ===== MESSAGE HANDLERS =====
-
- async handlePrePrepare(message: ByzantineMessage): Promise<void> {
- // Validate message
- if (message.viewNumber !== this.node.viewNumber) {
- return;
- }
-
- // Accept pre-prepare from primary
- const proposalId = `bft_${message.viewNumber}_${message.sequenceNumber}`;
-
- if (!this.proposals.has(proposalId) && message.payload !== undefined) {
- const proposal: ConsensusProposal = {
- id: proposalId,
- proposerId: message.senderId,
- value: message.payload,
- term: message.viewNumber,
- timestamp: message.timestamp,
- votes: new Map(),
- status: 'pending',
- };
- this.proposals.set(proposalId, proposal);
- }
-
- // Send prepare message
- const prepareMsg: ByzantineMessage = {
- type: 'prepare',
- viewNumber: message.viewNumber,
- sequenceNumber: message.sequenceNumber,
- digest: message.digest,
- senderId: this.node.id,
- timestamp: new Date(),
- };
-
- await this.broadcastMessage(prepareMsg);
- await this.handlePrepare(prepareMsg);
- }
-
- async handlePrepare(message: ByzantineMessage): Promise<void> {
- const key = `${message.viewNumber}_${message.sequenceNumber}`;
-
- if (!this.messageLog.has(key)) {
- this.messageLog.set(key, []);
- }
-
- const messages = this.messageLog.get(key)!;
- const hasPrepare = messages.some(
- m => m.type === 'prepare' && m.senderId === message.senderId
- );
-
- if (!hasPrepare) {
- messages.push(message);
- }
-
- // Check if prepared (2f + 1 prepare messages)
- const f = this.config.maxFaultyNodes ?? 1;
- const prepareCount = messages.filter(m => m.type === 'prepare').length;
-
- if (prepareCount >= 2 * f + 1) {
- const proposalId = `bft_${message.viewNumber}_${message.sequenceNumber}`;
- this.node.preparedMessages.set(key, messages);
-
- // Send commit message
- const commitMsg: ByzantineMessage = {
- type: 'commit',
- viewNumber: message.viewNumber,
- sequenceNumber: message.sequenceNumber,
- digest: message.digest,
- senderId: this.node.id,
- timestamp: new Date(),
- };
-
- await this.broadcastMessage(commitMsg);
- await this.handleCommit(commitMsg);
-
- // Record vote
- const proposal = this.proposals.get(proposalId);
- if (proposal) {
- proposal.votes.set(this.node.id, {
- voterId: this.node.id,
- approve: true,
- confidence: 1.0,
- timestamp: new Date(),
- });
- }
- }
- }
-
- async handleCommit(message: ByzantineMessage): Promise<void> {
- const key = `${message.viewNumber}_${message.sequenceNumber}`;
-
- if (!this.messageLog.has(key)) {
- this.messageLog.set(key, []);
- }
-
- const messages = this.messageLog.get(key)!;
- const hasCommit = messages.some(
- m => m.type === 'commit' && m.senderId === message.senderId
- );
-
- if (!hasCommit) {
- messages.push(message);
- }
-
- // Check if committed (2f + 1 commit messages)
- const f = this.config.maxFaultyNodes ?? 1;
- const commitCount = messages.filter(m => m.type === 'commit').length;
-
- if (commitCount >= 2 * f + 1) {
- const proposalId = `bft_${message.viewNumber}_${message.sequenceNumber}`;
- this.node.committedMessages.set(key, messages);
-
- const proposal = this.proposals.get(proposalId);
- if (proposal && proposal.status === 'pending') {
- proposal.status = 'accepted';
- this.emit('consensus.achieved', { proposalId, approved: true });
- }
- }
- }
-
- // ===== VIEW CHANGE =====
-
- async initiateViewChange(): Promise<void> {
- this.node.viewNumber++;
-
- this.emit('view.changing', { newViewNumber: this.node.viewNumber });
-
- // Elect new primary
- this.electPrimary();
-
- this.emit('view.changed', { viewNumber: this.node.viewNumber });
- }
-
- // ===== PRIVATE METHODS =====
-
- private async broadcastMessage(message: ByzantineMessage): Promise<void> {
- this.emit('message.broadcast', { message });
-
- // Simulate broadcast to all nodes
- for (const node of this.nodes.values()) {
- this.emit('message.sent', { to: node.id, message });
- }
- }
-
- private computeDigest(value: unknown): string {
- // Simple hash for demonstration
- const str = JSON.stringify(value);
- let hash = 0;
- for (let i = 0; i < str.length; i++) {
- const char = str.charCodeAt(i);
- hash = ((hash << 5) - hash) + char;
- hash = hash & hash;
- }
- return hash.toString(16);
- }
-
- private createResult(proposal: ConsensusProposal, durationMs: number): ConsensusResult {
- const n = this.nodes.size + 1;
- const approvingVotes = Array.from(proposal.votes.values()).filter(
- v => v.approve
- ).length;
-
- return {
- proposalId: proposal.id,
- approved: proposal.status === 'accepted',
- approvalRate: proposal.votes.size > 0
- ? approvingVotes / proposal.votes.size
- : 0,
- participationRate: proposal.votes.size / n,
- finalValue: proposal.value,
- rounds: 3, // pre-prepare, prepare, commit
- durationMs,
- };
- }
-
- // ===== STATE QUERIES =====
-
- isPrimary(): boolean {
- return this.node.isPrimary;
- }
-
- getViewNumber(): number {
- return this.node.viewNumber;
- }
-
- getSequenceNumber(): number {
- return this.node.sequenceNumber;
- }
-
- getPreparedCount(): number {
- return this.node.preparedMessages.size;
- }
-
- getCommittedCount(): number {
- return this.node.committedMessages.size;
- }
-
- getMaxFaultyNodes(): number {
- const n = this.nodes.size + 1;
- return Math.floor((n - 1) / 3);
- }
-
- canTolerate(faultyCount: number): boolean {
- return faultyCount <= this.getMaxFaultyNodes();
- }
-}
-
-export function createByzantineConsensus(
- nodeId: string,
- config?: ByzantineConfig
-): ByzantineConsensus {
- return new ByzantineConsensus(nodeId, config);
-}
diff --git a/v3/swarm/consensus/gossip.ts b/v3/swarm/consensus/gossip.ts
deleted file mode 100644
index b0d29da638..0000000000
--- a/v3/swarm/consensus/gossip.ts
+++ /dev/null
@@ -1,513 +0,0 @@
-/**
- * V3 Gossip Protocol Consensus
- * Eventually consistent consensus for large-scale distributed systems
- */
-
-import { EventEmitter } from 'events';
-import {
- ConsensusProposal,
- ConsensusVote,
- ConsensusResult,
- ConsensusConfig,
- SWARM_CONSTANTS,
-} from '../types.js';
-
-export interface GossipMessage {
- id: string;
- type: 'proposal' | 'vote' | 'state' | 'ack';
- senderId: string;
- version: number;
- payload: unknown;
- timestamp: Date;
- ttl: number;
- hops: number;
- path: string[];
-}
-
-export interface GossipNode {
- id: string;
- state: Map<string, unknown>;
- version: number;
- neighbors: Set<string>;
- seenMessages: Set<string>;
- lastSync: Date;
-}
-
-export interface GossipConfig extends Partial<ConsensusConfig> {
- fanout?: number;
- gossipIntervalMs?: number;
- maxHops?: number;
- convergenceThreshold?: number;
-}
-
-export class GossipConsensus extends EventEmitter {
- private config: GossipConfig;
- private node: GossipNode;
- private nodes: Map<string, GossipNode> = new Map();
- private proposals: Map<string, ConsensusProposal> = new Map();
- private messageQueue: GossipMessage[] = [];
- private gossipInterval?: NodeJS.Timeout;
- private proposalCounter: number = 0;
-
- constructor(nodeId: string, config: GossipConfig = {}) {
- super();
- this.config = {
- threshold: config.threshold ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_THRESHOLD,
- timeoutMs: config.timeoutMs ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_TIMEOUT_MS,
- maxRounds: config.maxRounds ?? 10,
- requireQuorum: config.requireQuorum ?? false, // Gossip is eventually consistent
- fanout: config.fanout ?? 3,
- gossipIntervalMs: config.gossipIntervalMs ?? 100,
- maxHops: config.maxHops ?? 10,
- convergenceThreshold: config.convergenceThreshold ?? 0.9,
- };
-
- this.node = {
- id: nodeId,
- state: new Map(),
- version: 0,
- neighbors: new Set(),
- seenMessages: new Set(),
- lastSync: new Date(),
- };
- }
-
- async initialize(): Promise<void> {
- this.startGossipLoop();
- this.emit('initialized', { nodeId: this.node.id });
- }
-
- async shutdown(): Promise<void> {
- if (this.gossipInterval) {
- clearInterval(this.gossipInterval);
- }
- this.emit('shutdown');
- }
-
- addNode(nodeId: string): void {
- this.nodes.set(nodeId, {
- id: nodeId,
- state: new Map(),
- version: 0,
- neighbors: new Set(),
- seenMessages: new Set(),
- lastSync: new Date(),
- });
-
- // Add as neighbor with some probability (random mesh)
- if (Math.random() < 0.5) {
- this.node.neighbors.add(nodeId);
- this.nodes.get(nodeId)!.neighbors.add(this.node.id);
- }
- }
-
- removeNode(nodeId: string): void {
- this.nodes.delete(nodeId);
- this.node.neighbors.delete(nodeId);
-
- for (const node of this.nodes.values()) {
- node.neighbors.delete(nodeId);
- }
- }
-
- addNeighbor(nodeId: string): void {
- if (this.nodes.has(nodeId)) {
- this.node.neighbors.add(nodeId);
- }
- }
-
- removeNeighbor(nodeId: string): void {
- this.node.neighbors.delete(nodeId);
- }
-
- async propose(value: unknown): Promise<ConsensusProposal> {
- this.proposalCounter++;
- const proposalId = `gossip_${this.node.id}_${this.proposalCounter}`;
-
- const proposal: ConsensusProposal = {
- id: proposalId,
- proposerId: this.node.id,
- value,
- term: this.node.version,
- timestamp: new Date(),
- votes: new Map(),
- status: 'pending',
- };
-
- this.proposals.set(proposalId, proposal);
-
- // Self-vote
- proposal.votes.set(this.node.id, {
- voterId: this.node.id,
- approve: true,
- confidence: 1.0,
- timestamp: new Date(),
- });
-
- // Create gossip message
- const message: GossipMessage = {
- id: `msg_${proposalId}`,
- type: 'proposal',
- senderId: this.node.id,
- version: ++this.node.version,
- payload: { proposalId, value },
- timestamp: new Date(),
- ttl: this.config.maxHops ?? 10,
- hops: 0,
- path: [this.node.id],
- };
-
- // Queue for gossip
- this.queueMessage(message);
-
- return proposal;
- }
-
- async vote(proposalId: string, vote: ConsensusVote): Promise<void> {
- const proposal = this.proposals.get(proposalId);
- if (!proposal) {
- return;
- }
-
- proposal.votes.set(vote.voterId, vote);
-
- // Create vote gossip message
- const message: GossipMessage = {
- id: `vote_${proposalId}_${vote.voterId}`,
- type: 'vote',
- senderId: this.node.id,
- version: ++this.node.version,
- payload: { proposalId, vote },
- timestamp: new Date(),
- ttl: this.config.maxHops ?? 10,
- hops: 0,
- path: [this.node.id],
- };
-
- this.queueMessage(message);
-
- // Check convergence
- await this.checkConvergence(proposalId);
- }
-
- async awaitConsensus(proposalId: string): Promise<ConsensusResult> {
- const startTime = Date.now();
- const maxWait = this.config.timeoutMs ?? 30000;
-
- return new Promise((resolve, reject) => {
- const checkInterval = setInterval(() => {
- const proposal = this.proposals.get(proposalId);
- if (!proposal) {
- clearInterval(checkInterval);
- reject(new Error(`Proposal ${proposalId} not found`));
- return;
- }
-
- if (proposal.status !== 'pending') {
- clearInterval(checkInterval);
- resolve(this.createResult(proposal, Date.now() - startTime));
- return;
- }
-
- // Check convergence
- this.checkConvergence(proposalId);
-
- if (Date.now() - startTime > maxWait) {
- clearInterval(checkInterval);
- // Gossip is eventually consistent, so mark as accepted if threshold met
- const totalNodes = this.nodes.size + 1;
- const votes = proposal.votes.size;
- const threshold = this.config.convergenceThreshold ?? 0.9;
-
- if (votes / totalNodes >= threshold) {
- proposal.status = 'accepted';
- } else {
- proposal.status = 'expired';
- }
-
- resolve(this.createResult(proposal, Date.now() - startTime));
- }
- }, 50);
- });
- }
-
- // ===== GOSSIP PROTOCOL =====
-
- private startGossipLoop(): void {
- this.gossipInterval = setInterval(() => {
- this.gossipRound();
- }, this.config.gossipIntervalMs ?? 100);
- }
-
- private async gossipRound(): Promise<void> {
- if (this.messageQueue.length === 0) {
- return;
- }
-
- // Select random neighbors (fanout)
- const fanout = Math.min(
- this.config.fanout ?? 3,
- this.node.neighbors.size
- );
- const neighbors = this.selectRandomNeighbors(fanout);
-
- // Send queued messages to selected neighbors
- const messages = this.messageQueue.splice(0, 10); // Process up to 10 per round
-
- for (const message of messages) {
- for (const neighborId of neighbors) {
- await this.sendToNeighbor(neighborId, message);
- }
- }
-
- this.node.lastSync = new Date();
- }
-
- private selectRandomNeighbors(count: number): string[] {
- const neighbors = Array.from(this.node.neighbors);
- const selected: string[] = [];
-
- while (selected.length < count && neighbors.length > 0) {
- const idx = Math.floor(Math.random() * neighbors.length);
- selected.push(neighbors.splice(idx, 1)[0]);
- }
-
- return selected;
- }
-
- private async sendToNeighbor(neighborId: string, message: GossipMessage): Promise<void> {
- const neighbor = this.nodes.get(neighborId);
- if (!neighbor) {
- return;
- }
-
- // Check if already seen
- if (neighbor.seenMessages.has(message.id)) {
- return;
- }
-
- // Simulate network delivery
- const deliveredMessage: GossipMessage = {
- ...message,
- hops: message.hops + 1,
- path: [...message.path, neighborId],
- };
-
- // Process at neighbor
- await this.processReceivedMessage(neighbor, deliveredMessage);
-
- this.emit('message.sent', { to: neighborId, message: deliveredMessage });
- }
-
- private async processReceivedMessage(
- node: GossipNode,
- message: GossipMessage
- ): Promise<void> {
- // Mark as seen
- node.seenMessages.add(message.id);
-
- // Check TTL
- if (message.ttl <= 0 || message.hops >= (this.config.maxHops ?? 10)) {
- return;
- }
-
- switch (message.type) {
- case 'proposal':
- await this.handleProposalMessage(node, message);
- break;
- case 'vote':
- await this.handleVoteMessage(node, message);
- break;
- case 'state':
- await this.handleStateMessage(node, message);
- break;
- }
-
- // Propagate to neighbors (gossip)
- if (message.hops < (this.config.maxHops ?? 10)) {
- const propagateMessage: GossipMessage = {
- ...message,
- ttl: message.ttl - 1,
- };
-
- // Add to queue if this is our node
- if (node.id === this.node.id) {
- this.queueMessage(propagateMessage);
- }
- }
- }
-
- private async handleProposalMessage(
- node: GossipNode,
- message: GossipMessage
- ): Promise<void> {
- const { proposalId, value } = message.payload as {
- proposalId: string;
- value: unknown;
- };
-
- if (!this.proposals.has(proposalId)) {
- const proposal: ConsensusProposal = {
- id: proposalId,
- proposerId: message.senderId,
- value,
- term: message.version,
- timestamp: message.timestamp,
- votes: new Map(),
- status: 'pending',
- };
-
- this.proposals.set(proposalId, proposal);
-
- // Auto-vote (simplified)
- if (node.id === this.node.id) {
- await this.vote(proposalId, {
- voterId: this.node.id,
- approve: true,
- confidence: 0.9,
- timestamp: new Date(),
- });
- }
- }
- }
-
- private async handleVoteMessage(
- node: GossipNode,
- message: GossipMessage
- ): Promise<void> {
- const { proposalId, vote } = message.payload as {
- proposalId: string;
- vote: ConsensusVote;
- };
-
- const proposal = this.proposals.get(proposalId);
- if (proposal && !proposal.votes.has(vote.voterId)) {
- proposal.votes.set(vote.voterId, vote);
- await this.checkConvergence(proposalId);
- }
- }
-
- private async handleStateMessage(
- node: GossipNode,
- message: GossipMessage
- ): Promise<void> {
- const state = message.payload as Record<string, unknown>;
-
- // Merge state (last-writer-wins)
- if (message.version > node.version) {
- for (const [key, value] of Object.entries(state)) {
- node.state.set(key, value);
- }
- node.version = message.version;
- }
- }
-
- private queueMessage(message: GossipMessage): void {
- // Avoid duplicates
- if (!this.node.seenMessages.has(message.id)) {
- this.node.seenMessages.add(message.id);
- this.messageQueue.push(message);
- }
- }
-
- private async checkConvergence(proposalId: string): Promise<void> {
- const proposal = this.proposals.get(proposalId);
- if (!proposal || proposal.status !== 'pending') {
- return;
- }
-
- const totalNodes = this.nodes.size + 1;
- const votes = proposal.votes.size;
- const threshold = this.config.convergenceThreshold ?? 0.9;
- const approvalThreshold = this.config.threshold ?? 0.66;
-
- // Check if we've converged (enough nodes have voted)
- if (votes / totalNodes >= threshold) {
- const approvingVotes = Array.from(proposal.votes.values()).filter(
- v => v.approve
- ).length;
-
- if (approvingVotes / votes >= approvalThreshold) {
- proposal.status = 'accepted';
- this.emit('consensus.achieved', { proposalId, approved: true });
- } else {
- proposal.status = 'rejected';
- this.emit('consensus.achieved', { proposalId, approved: false });
- }
- }
- }
-
- private createResult(proposal: ConsensusProposal, durationMs: number): ConsensusResult {
- const totalNodes = this.nodes.size + 1;
- const approvingVotes = Array.from(proposal.votes.values()).filter(
- v => v.approve
- ).length;
-
- return {
- proposalId: proposal.id,
- approved: proposal.status === 'accepted',
- approvalRate: proposal.votes.size > 0
- ? approvingVotes / proposal.votes.size
- : 0,
- participationRate: proposal.votes.size / totalNodes,
- finalValue: proposal.value,
- rounds: this.node.version,
- durationMs,
- };
- }
-
- // ===== STATE QUERIES =====
-
- getConvergence(proposalId: string): number {
- const proposal = this.proposals.get(proposalId);
- if (!proposal) return 0;
-
- const totalNodes = this.nodes.size + 1;
- return proposal.votes.size / totalNodes;
- }
-
- getVersion(): number {
- return this.node.version;
- }
-
- getNeighborCount(): number {
- return this.node.neighbors.size;
- }
-
- getSeenMessageCount(): number {
- return this.node.seenMessages.size;
- }
-
- getQueueDepth(): number {
- return this.messageQueue.length;
- }
-
- // Anti-entropy: sync full state with a random neighbor
- async antiEntropy(): Promise<void> {
- if (this.node.neighbors.size === 0) return;
-
- const neighbors = Array.from(this.node.neighbors);
- const randomNeighbor = neighbors[Math.floor(Math.random() * neighbors.length)];
-
- const stateMessage: GossipMessage = {
- id: `state_${this.node.id}_${Date.now()}`,
- type: 'state',
- senderId: this.node.id,
- version: this.node.version,
- payload: Object.fromEntries(this.node.state),
- timestamp: new Date(),
- ttl: 1,
- hops: 0,
- path: [this.node.id],
- };
-
- await this.sendToNeighbor(randomNeighbor, stateMessage);
- }
-}
-
-export function createGossipConsensus(
- nodeId: string,
- config?: GossipConfig
-): GossipConsensus {
- return new GossipConsensus(nodeId, config);
-}
diff --git a/v3/swarm/consensus/index.ts b/v3/swarm/consensus/index.ts
deleted file mode 100644
index 879dd61942..0000000000
--- a/v3/swarm/consensus/index.ts
+++ /dev/null
@@ -1,267 +0,0 @@
-/**
- * V3 Consensus Engine Factory
- * Unified interface for different consensus algorithms
- */
-
-import { EventEmitter } from 'events';
-import {
- ConsensusAlgorithm,
- ConsensusConfig,
- ConsensusProposal,
- ConsensusVote,
- ConsensusResult,
- IConsensusEngine,
- SWARM_CONSTANTS,
-} from '../types.js';
-import { RaftConsensus, createRaftConsensus, RaftConfig } from './raft.js';
-import { ByzantineConsensus, createByzantineConsensus, ByzantineConfig } from './byzantine.js';
-import { GossipConsensus, createGossipConsensus, GossipConfig } from './gossip.js';
-
-export { RaftConsensus, ByzantineConsensus, GossipConsensus };
-export { RaftConfig, ByzantineConfig, GossipConfig };
-
-type ConsensusImplementation = RaftConsensus | ByzantineConsensus | GossipConsensus;
-
-export class ConsensusEngine extends EventEmitter implements IConsensusEngine {
- private config: ConsensusConfig;
- private nodeId: string;
- private implementation?: ConsensusImplementation;
- private proposals: Map<string, ConsensusProposal> = new Map();
-
- constructor(nodeId: string, config: Partial<ConsensusConfig> = {}) {
- super();
- this.nodeId = nodeId;
- this.config = {
- algorithm: config.algorithm ?? 'raft',
- threshold: config.threshold ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_THRESHOLD,
- timeoutMs: config.timeoutMs ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_TIMEOUT_MS,
- maxRounds: config.maxRounds ?? 10,
- requireQuorum: config.requireQuorum ?? true,
- };
- }
-
- async initialize(config?: ConsensusConfig): Promise<void> {
- if (config) {
- this.config = { ...this.config, ...config };
- }
-
- // Create implementation based on algorithm
- switch (this.config.algorithm) {
- case 'raft':
- this.implementation = createRaftConsensus(this.nodeId, {
- threshold: this.config.threshold,
- timeoutMs: this.config.timeoutMs,
- maxRounds: this.config.maxRounds,
- requireQuorum: this.config.requireQuorum,
- });
- break;
-
- case 'byzantine':
- this.implementation = createByzantineConsensus(this.nodeId, {
- threshold: this.config.threshold,
- timeoutMs: this.config.timeoutMs,
- maxRounds: this.config.maxRounds,
- requireQuorum: this.config.requireQuorum,
- });
- break;
-
- case 'gossip':
- this.implementation = createGossipConsensus(this.nodeId, {
- threshold: this.config.threshold,
- timeoutMs: this.config.timeoutMs,
- maxRounds: this.config.maxRounds,
- requireQuorum: this.config.requireQuorum,
- });
- break;
-
- case 'paxos':
- // Fall back to Raft for Paxos (similar guarantees)
- this.implementation = createRaftConsensus(this.nodeId, {
- threshold: this.config.threshold,
- timeoutMs: this.config.timeoutMs,
- maxRounds: this.config.maxRounds,
- requireQuorum: this.config.requireQuorum,
- });
- break;
-
- default:
- throw new Error(`Unknown consensus algorithm: ${this.config.algorithm}`);
- }
-
- await this.implementation.initialize();
-
- // Forward events
- this.implementation.on('consensus.achieved', (data) => {
- this.emit('consensus.achieved', data);
- });
-
- this.implementation.on('leader.elected', (data) => {
- this.emit('leader.elected', data);
- });
-
- this.emit('initialized', {
- nodeId: this.nodeId,
- algorithm: this.config.algorithm
- });
- }
-
- async shutdown(): Promise<void> {
- if (this.implementation) {
- await this.implementation.shutdown();
- }
- this.emit('shutdown');
- }
-
- addNode(nodeId: string, options?: { isPrimary?: boolean }): void {
- if (!this.implementation) {
- throw new Error('Consensus engine not initialized');
- }
-
- if (this.implementation instanceof RaftConsensus) {
- this.implementation.addPeer(nodeId);
- } else if (this.implementation instanceof ByzantineConsensus) {
- this.implementation.addNode(nodeId, options?.isPrimary);
- } else if (this.implementation instanceof GossipConsensus) {
- this.implementation.addNode(nodeId);
- }
- }
-
- removeNode(nodeId: string): void {
- if (!this.implementation) {
- return;
- }
-
- if (this.implementation instanceof RaftConsensus) {
- this.implementation.removePeer(nodeId);
- } else if (this.implementation instanceof ByzantineConsensus) {
- this.implementation.removeNode(nodeId);
- } else if (this.implementation instanceof GossipConsensus) {
- this.implementation.removeNode(nodeId);
- }
- }
-
- async propose(value: unknown, proposerId?: string): Promise<ConsensusProposal> {
- if (!this.implementation) {
- throw new Error('Consensus engine not initialized');
- }
-
- const proposal = await this.implementation.propose(value);
- this.proposals.set(proposal.id, proposal);
- return proposal;
- }
-
- async vote(proposalId: string, vote: ConsensusVote): Promise<void> {
- if (!this.implementation) {
- throw new Error('Consensus engine not initialized');
- }
-
- await this.implementation.vote(proposalId, vote);
- }
-
- getProposal(proposalId: string): ConsensusProposal | undefined {
- return this.proposals.get(proposalId);
- }
-
- async awaitConsensus(proposalId: string): Promise<ConsensusResult> {
- if (!this.implementation) {
- throw new Error('Consensus engine not initialized');
- }
-
- return this.implementation.awaitConsensus(proposalId);
- }
-
- getActiveProposals(): ConsensusProposal[] {
- return Array.from(this.proposals.values()).filter(
- p => p.status === 'pending'
- );
- }
-
- // Algorithm-specific queries
- isLeader(): boolean {
- if (this.implementation instanceof RaftConsensus) {
- return this.implementation.isLeader();
- }
- if (this.implementation instanceof ByzantineConsensus) {
- return this.implementation.isPrimary();
- }
- return false; // Gossip has no leader
- }
-
- getLeaderId(): string | undefined {
- if (this.implementation instanceof RaftConsensus) {
- return this.implementation.getLeaderId();
- }
- return undefined;
- }
-
- getAlgorithm(): ConsensusAlgorithm {
- return this.config.algorithm;
- }
-
- getConfig(): ConsensusConfig {
- return { ...this.config };
- }
-
- // Metrics
- getStats(): {
- algorithm: ConsensusAlgorithm;
- totalProposals: number;
- pendingProposals: number;
- acceptedProposals: number;
- rejectedProposals: number;
- expiredProposals: number;
- } {
- const proposals = Array.from(this.proposals.values());
-
- return {
- algorithm: this.config.algorithm,
- totalProposals: proposals.length,
- pendingProposals: proposals.filter(p => p.status === 'pending').length,
- acceptedProposals: proposals.filter(p => p.status === 'accepted').length,
- rejectedProposals: proposals.filter(p => p.status === 'rejected').length,
- expiredProposals: proposals.filter(p => p.status === 'expired').length,
- };
- }
-}
-
-// Factory function
-export function createConsensusEngine(
- nodeId: string,
- algorithm: ConsensusAlgorithm = 'raft',
- config?: Partial<ConsensusConfig>
-): ConsensusEngine {
- return new ConsensusEngine(nodeId, { ...config, algorithm });
-}
-
-// Helper to select optimal algorithm based on requirements
-export function selectOptimalAlgorithm(requirements: {
- faultTolerance: 'crash' | 'byzantine';
- consistency: 'strong' | 'eventual';
- networkScale: 'small' | 'medium' | 'large';
- latencyPriority: 'low' | 'medium' | 'high';
-}): ConsensusAlgorithm {
- const { faultTolerance, consistency, networkScale, latencyPriority } = requirements;
-
- // Byzantine fault tolerance required
- if (faultTolerance === 'byzantine') {
- return 'byzantine';
- }
-
- // Eventual consistency acceptable and large scale
- if (consistency === 'eventual' && networkScale === 'large') {
- return 'gossip';
- }
-
- // Low latency priority with medium scale
- if (latencyPriority === 'high' && networkScale !== 'large') {
- return 'raft';
- }
-
- // Strong consistency with small/medium scale
- if (consistency === 'strong') {
- return 'raft';
- }
-
- // Default to Raft
- return 'raft';
-}
diff --git a/v3/swarm/consensus/raft.ts b/v3/swarm/consensus/raft.ts
deleted file mode 100644
index 11393b54dd..0000000000
--- a/v3/swarm/consensus/raft.ts
+++ /dev/null
@@ -1,443 +0,0 @@
-/**
- * V3 Raft Consensus Implementation
- * Leader election and log replication for distributed coordination
- */
-
-import { EventEmitter } from 'events';
-import {
- ConsensusProposal,
- ConsensusVote,
- ConsensusResult,
- ConsensusConfig,
- SWARM_CONSTANTS,
-} from '../types.js';
-
-export type RaftState = 'follower' | 'candidate' | 'leader';
-
-export interface RaftNode {
- id: string;
- state: RaftState;
- currentTerm: number;
- votedFor?: string;
- log: RaftLogEntry[];
- commitIndex: number;
- lastApplied: number;
-}
-
-export interface RaftLogEntry {
- term: number;
- index: number;
- command: unknown;
- timestamp: Date;
-}
-
-export interface RaftConfig extends Partial<ConsensusConfig> {
- electionTimeoutMinMs?: number;
- electionTimeoutMaxMs?: number;
- heartbeatIntervalMs?: number;
-}
-
-export class RaftConsensus extends EventEmitter {
- private config: RaftConfig;
- private node: RaftNode;
- private peers: Map<string, RaftNode> = new Map();
- private proposals: Map<string, ConsensusProposal> = new Map();
- private electionTimeout?: NodeJS.Timeout;
- private heartbeatInterval?: NodeJS.Timeout;
- private proposalCounter: number = 0;
-
- constructor(nodeId: string, config: RaftConfig = {}) {
- super();
- this.config = {
- threshold: config.threshold ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_THRESHOLD,
- timeoutMs: config.timeoutMs ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_TIMEOUT_MS,
- maxRounds: config.maxRounds ?? 10,
- requireQuorum: config.requireQuorum ?? true,
- electionTimeoutMinMs: config.electionTimeoutMinMs ?? 150,
- electionTimeoutMaxMs: config.electionTimeoutMaxMs ?? 300,
- heartbeatIntervalMs: config.heartbeatIntervalMs ?? 50,
- };
-
- this.node = {
- id: nodeId,
- state: 'follower',
- currentTerm: 0,
- log: [],
- commitIndex: 0,
- lastApplied: 0,
- };
- }
-
- async initialize(): Promise<void> {
- this.resetElectionTimeout();
- this.emit('initialized', { nodeId: this.node.id });
- }
-
- async shutdown(): Promise<void> {
- if (this.electionTimeout) {
- clearTimeout(this.electionTimeout);
- }
- if (this.heartbeatInterval) {
- clearInterval(this.heartbeatInterval);
- }
- this.emit('shutdown');
- }
-
- addPeer(peerId: string): void {
- this.peers.set(peerId, {
- id: peerId,
- state: 'follower',
- currentTerm: 0,
- log: [],
- commitIndex: 0,
- lastApplied: 0,
- });
- }
-
- removePeer(peerId: string): void {
- this.peers.delete(peerId);
- }
-
- async propose(value: unknown): Promise<ConsensusProposal> {
- if (this.node.state !== 'leader') {
- throw new Error('Only leader can propose values');
- }
-
- this.proposalCounter++;
- const proposalId = `raft_${this.node.id}_${this.proposalCounter}`;
-
- const proposal: ConsensusProposal = {
- id: proposalId,
- proposerId: this.node.id,
- value,
- term: this.node.currentTerm,
- timestamp: new Date(),
- votes: new Map(),
- status: 'pending',
- };
-
- // Add to local log
- const logEntry: RaftLogEntry = {
- term: this.node.currentTerm,
- index: this.node.log.length + 1,
- command: { proposalId, value },
- timestamp: new Date(),
- };
- this.node.log.push(logEntry);
-
- this.proposals.set(proposalId, proposal);
-
- // Leader votes for itself
- proposal.votes.set(this.node.id, {
- voterId: this.node.id,
- approve: true,
- confidence: 1.0,
- timestamp: new Date(),
- });
-
- // Replicate to followers
- await this.replicateToFollowers(logEntry);
-
- return proposal;
- }
-
- async vote(proposalId: string, vote: ConsensusVote): Promise<void> {
- const proposal = this.proposals.get(proposalId);
- if (!proposal) {
- throw new Error(`Proposal ${proposalId} not found`);
- }
-
- if (proposal.status !== 'pending') {
- return;
- }
-
- proposal.votes.set(vote.voterId, vote);
-
- // Check if we have consensus
- await this.checkConsensus(proposalId);
- }
-
- async awaitConsensus(proposalId: string): Promise<ConsensusResult> {
- const startTime = Date.now();
-
- return new Promise((resolve, reject) => {
- const checkInterval = setInterval(() => {
- const proposal = this.proposals.get(proposalId);
- if (!proposal) {
- clearInterval(checkInterval);
- reject(new Error(`Proposal ${proposalId} not found`));
- return;
- }
-
- if (proposal.status !== 'pending') {
- clearInterval(checkInterval);
- resolve(this.createResult(proposal, Date.now() - startTime));
- return;
- }
-
- if (Date.now() - startTime > (this.config.timeoutMs ?? 30000)) {
- clearInterval(checkInterval);
- proposal.status = 'expired';
- resolve(this.createResult(proposal, Date.now() - startTime));
- }
- }, 10);
- });
- }
-
- getState(): RaftState {
- return this.node.state;
- }
-
- getTerm(): number {
- return this.node.currentTerm;
- }
-
- isLeader(): boolean {
- return this.node.state === 'leader';
- }
-
- getLeaderId(): string | undefined {
- if (this.node.state === 'leader') {
- return this.node.id;
- }
- return this.node.votedFor;
- }
-
- // ===== PRIVATE METHODS =====
-
- private resetElectionTimeout(): void {
- if (this.electionTimeout) {
- clearTimeout(this.electionTimeout);
- }
-
- const timeout = this.randomElectionTimeout();
- this.electionTimeout = setTimeout(() => {
- this.startElection();
- }, timeout);
- }
-
- private randomElectionTimeout(): number {
- const min = this.config.electionTimeoutMinMs ?? 150;
- const max = this.config.electionTimeoutMaxMs ?? 300;
- return Math.floor(Math.random() * (max - min + 1)) + min;
- }
-
- private async startElection(): Promise<void> {
- this.node.state = 'candidate';
- this.node.currentTerm++;
- this.node.votedFor = this.node.id;
-
- this.emit('election.started', {
- term: this.node.currentTerm,
- candidateId: this.node.id
- });
-
- // Vote for self
- let votesReceived = 1;
- const votesNeeded = Math.floor((this.peers.size + 1) / 2) + 1;
-
- // Request votes from peers
- for (const [peerId, peer] of this.peers) {
- const granted = await this.requestVote(peerId);
- if (granted) {
- votesReceived++;
- }
-
- if (votesReceived >= votesNeeded) {
- this.becomeLeader();
- return;
- }
- }
-
- // Election failed, reset to follower
- this.node.state = 'follower';
- this.resetElectionTimeout();
- }
-
- private async requestVote(peerId: string): Promise<boolean> {
- const peer = this.peers.get(peerId);
- if (!peer) return false;
-
- // Simulate vote request (in real implementation, this would be RPC)
- // For now, grant vote if candidate's term is higher
- if (this.node.currentTerm > peer.currentTerm) {
- peer.votedFor = this.node.id;
- peer.currentTerm = this.node.currentTerm;
- return true;
- }
-
- return false;
- }
-
- private becomeLeader(): void {
- this.node.state = 'leader';
-
- if (this.electionTimeout) {
- clearTimeout(this.electionTimeout);
- }
-
- // Start sending heartbeats
- this.heartbeatInterval = setInterval(() => {
- this.sendHeartbeats();
- }, this.config.heartbeatIntervalMs ?? 50);
-
- this.emit('leader.elected', {
- term: this.node.currentTerm,
- leaderId: this.node.id
- });
- }
-
- private async sendHeartbeats(): Promise<void> {
- for (const [peerId, peer] of this.peers) {
- await this.appendEntries(peerId, []);
- }
- }
-
- private async appendEntries(peerId: string, entries: RaftLogEntry[]): Promise<boolean> {
- const peer = this.peers.get(peerId);
- if (!peer) return false;
-
- // Simulate AppendEntries RPC
- if (this.node.currentTerm >= peer.currentTerm) {
- peer.currentTerm = this.node.currentTerm;
- peer.state = 'follower';
- peer.log.push(...entries);
- return true;
- }
-
- return false;
- }
-
- private async replicateToFollowers(entry: RaftLogEntry): Promise<void> {
- const replicationPromises = Array.from(this.peers.keys()).map(
- peerId => this.appendEntries(peerId, [entry])
- );
-
- const results = await Promise.allSettled(replicationPromises);
- const successCount = results.filter(
- r => r.status === 'fulfilled' && r.value
- ).length;
-
- // Check if majority replicated
- const majority = Math.floor((this.peers.size + 1) / 2) + 1;
- if (successCount + 1 >= majority) {
- this.node.commitIndex = entry.index;
- this.emit('log.committed', { index: entry.index });
- }
- }
-
- private async checkConsensus(proposalId: string): Promise<void> {
- const proposal = this.proposals.get(proposalId);
- if (!proposal || proposal.status !== 'pending') {
- return;
- }
-
- const totalVoters = this.peers.size + 1;
- const votesReceived = proposal.votes.size;
- const approvingVotes = Array.from(proposal.votes.values()).filter(
- v => v.approve
- ).length;
-
- const threshold = this.config.threshold ?? 0.66;
- const quorum = Math.floor(totalVoters * threshold);
-
- if (approvingVotes >= quorum) {
- proposal.status = 'accepted';
- this.emit('consensus.achieved', { proposalId, approved: true });
- } else if (votesReceived - approvingVotes > totalVoters - quorum) {
- proposal.status = 'rejected';
- this.emit('consensus.achieved', { proposalId, approved: false });
- }
- }
-
- private createResult(proposal: ConsensusProposal, durationMs: number): ConsensusResult {
- const totalVoters = this.peers.size + 1;
- const approvingVotes = Array.from(proposal.votes.values()).filter(
- v => v.approve
- ).length;
-
- return {
- proposalId: proposal.id,
- approved: proposal.status === 'accepted',
- approvalRate: proposal.votes.size > 0
- ? approvingVotes / proposal.votes.size
- : 0,
- participationRate: proposal.votes.size / totalVoters,
- finalValue: proposal.value,
- rounds: 1,
- durationMs,
- };
- }
-
- // Handle vote request from another candidate
- handleVoteRequest(
- candidateId: string,
- term: number,
- lastLogIndex: number,
- lastLogTerm: number
- ): boolean {
- if (term < this.node.currentTerm) {
- return false;
- }
-
- if (term > this.node.currentTerm) {
- this.node.currentTerm = term;
- this.node.state = 'follower';
- this.node.votedFor = undefined;
- }
-
- if (this.node.votedFor === undefined || this.node.votedFor === candidateId) {
- // Check log is at least as up-to-date
- const lastEntry = this.node.log[this.node.log.length - 1];
- const myLastTerm = lastEntry?.term ?? 0;
- const myLastIndex = lastEntry?.index ?? 0;
-
- if (lastLogTerm > myLastTerm ||
- (lastLogTerm === myLastTerm && lastLogIndex >= myLastIndex)) {
- this.node.votedFor = candidateId;
- this.resetElectionTimeout();
- return true;
- }
- }
-
- return false;
- }
-
- // Handle append entries from leader
- handleAppendEntries(
- leaderId: string,
- term: number,
- entries: RaftLogEntry[],
- leaderCommit: number
- ): boolean {
- if (term < this.node.currentTerm) {
- return false;
- }
-
- this.resetElectionTimeout();
-
- if (term > this.node.currentTerm) {
- this.node.currentTerm = term;
- this.node.state = 'follower';
- }
-
- this.node.votedFor = leaderId;
-
- // Append entries
- this.node.log.push(...entries);
-
- // Update commit index
- if (leaderCommit > this.node.commitIndex) {
- this.node.commitIndex = Math.min(
- leaderCommit,
- this.node.log.length
- );
- }
-
- return true;
- }
-}
-
-export function createRaftConsensus(nodeId: string, config?: RaftConfig): RaftConsensus {
- return new RaftConsensus(nodeId, config);
-}
diff --git a/v3/swarm/index.ts b/v3/swarm/index.ts
deleted file mode 100644
index 742b1ede94..0000000000
--- a/v3/swarm/index.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-/**
- * V3 Unified Swarm Coordination System
- *
- * This module consolidates 4 legacy coordination systems into a single unified system:
- * - SwarmCoordinator (27KB!) - Core swarm orchestration
- * - HiveMind - Queen-led hierarchical coordination
- * - Maestro - SPARC methodology integration
- * - AgentManager - Agent lifecycle and pooling
- *
- * Performance Targets:
- * - Agent coordination: <100ms for 15 agents
- * - Consensus: <100ms
- * - Message throughput: 1000+ msgs/sec
- *
- * Supported Topologies:
- * - mesh: Peer-to-peer communication (default)
- * - hierarchical: Queen-led with workers
- * - centralized: Single coordinator
- * - hybrid: Dynamic switching between topologies
- *
- * Consensus Algorithms:
- * - raft: Leader election and log replication
- * - byzantine: PBFT-style fault tolerance
- * - gossip: Eventually consistent for large scale
- *
- * Usage:
- * ```typescript
- * import { createUnifiedSwarmCoordinator } from '@claude-flow/swarm';
- *
- * const coordinator = createUnifiedSwarmCoordinator({
- * topology: { type: 'hierarchical', maxAgents: 15 },
- * consensus: { algorithm: 'raft', threshold: 0.66 },
- * });
- *
- * await coordinator.initialize();
- *
- * // Register agents
- * const agentId = await coordinator.registerAgent({
- * name: 'Worker-1',
- * type: 'worker',
- * capabilities: { ... },
- * metrics: { ... },
- * status: 'idle',
- * workload: 0,
- * health: 1.0,
- * });
- *
- * // Submit tasks
- * const taskId = await coordinator.submitTask({
- * name: 'Analyze code',
- * type: 'analysis',
- * priority: 'high',
- * input: { ... },
- * });
- *
- * // Achieve consensus
- * const result = await coordinator.proposeConsensus({ action: 'deploy' });
- * ```
- */
-
-// Main coordinator
-export {
- UnifiedSwarmCoordinator,
- createUnifiedSwarmCoordinator,
-} from './unified-coordinator.js';
-
-// Domain types for 15-agent hierarchy
-export type {
- AgentDomain,
- DomainConfig,
- TaskAssignment,
- ParallelExecutionResult,
- DomainStatus,
-} from './unified-coordinator.js';
-
-// Core components
-export {
- TopologyManager,
- createTopologyManager,
-} from './topology-manager.js';
-
-export {
- MessageBus,
- createMessageBus,
-} from './message-bus.js';
-
-export {
- AgentPool,
- createAgentPool,
-} from './agent-pool.js';
-
-// Consensus engines
-export {
- ConsensusEngine,
- createConsensusEngine,
- selectOptimalAlgorithm,
- RaftConsensus,
- ByzantineConsensus,
- GossipConsensus,
-} from './consensus/index.js';
-
-// Types
-export * from './types.js';
-
-// Re-export commonly used types for convenience
-export type {
- SwarmId,
- AgentId,
- TaskId,
- AgentState,
- AgentType,
- AgentStatus,
- AgentCapabilities,
- AgentMetrics,
- TaskDefinition,
- TaskType,
- TaskStatus,
- TaskPriority,
- TopologyType,
- TopologyConfig,
- TopologyState,
- TopologyNode,
- ConsensusAlgorithm,
- ConsensusConfig,
- ConsensusProposal,
- ConsensusVote,
- ConsensusResult,
- Message,
- MessageType,
- MessageBusConfig,
- MessageBusStats,
- CoordinatorConfig,
- CoordinatorState,
- CoordinatorMetrics,
- SwarmStatus,
- SwarmEvent,
- SwarmEventType,
- PerformanceReport,
- AgentPoolConfig,
- AgentPoolState,
-} from './types.js';
-
-// Default export for convenience
-import { UnifiedSwarmCoordinator, createUnifiedSwarmCoordinator } from './unified-coordinator.js';
-export default UnifiedSwarmCoordinator;
-
-// Version info
-export const VERSION = '3.0.0';
-
-// Performance targets as constants
-export const PERFORMANCE_TARGETS = {
- COORDINATION_LATENCY_MS: 100, // <100ms for 15 agents
- CONSENSUS_LATENCY_MS: 100, // <100ms consensus
- MESSAGE_THROUGHPUT: 1000, // 1000+ msgs/sec
-} as const;
diff --git a/v3/swarm/message-bus.ts b/v3/swarm/message-bus.ts
deleted file mode 100644
index 39b5dbb23f..0000000000
--- a/v3/swarm/message-bus.ts
+++ /dev/null
@@ -1,421 +0,0 @@
-/**
- * V3 Message Bus
- * High-performance inter-agent communication system
- * Target: 1000+ messages/second throughput
- */
-
-import { EventEmitter } from 'events';
-import {
- Message,
- MessageAck,
- MessageBusConfig,
- MessageBusStats,
- MessageType,
- IMessageBus,
- SWARM_CONSTANTS,
-} from './types.js';
-
-interface MessageQueueEntry {
- message: Message;
- attempts: number;
- enqueuedAt: Date;
- lastAttemptAt?: Date;
-}
-
-interface Subscription {
- agentId: string;
- callback: (message: Message) => void;
- filter?: MessageType[];
-}
-
-export class MessageBus extends EventEmitter implements IMessageBus {
- private config: MessageBusConfig;
- private queues: Map<string, MessageQueueEntry[]> = new Map();
- private subscriptions: Map<string, Subscription> = new Map();
- private pendingAcks: Map<string, { message: Message; timeout: NodeJS.Timeout }> = new Map();
- private processingInterval?: NodeJS.Timeout;
- private messageCounter: number = 0;
- private stats: MessageBusStats;
- private startTime: Date = new Date();
- private messageHistory: { timestamp: number; count: number }[] = [];
-
- constructor(config: Partial<MessageBusConfig> = {}) {
- super();
- this.config = {
- maxQueueSize: config.maxQueueSize ?? SWARM_CONSTANTS.MAX_QUEUE_SIZE,
- processingIntervalMs: config.processingIntervalMs ?? 10,
- ackTimeoutMs: config.ackTimeoutMs ?? 5000,
- retryAttempts: config.retryAttempts ?? SWARM_CONSTANTS.MAX_RETRIES,
- enablePersistence: config.enablePersistence ?? false,
- compressionEnabled: config.compressionEnabled ?? false,
- };
-
- this.stats = {
- totalMessages: 0,
- messagesPerSecond: 0,
- avgLatencyMs: 0,
- queueDepth: 0,
- ackRate: 1.0,
- errorRate: 0,
- };
- }
-
- async initialize(config?: MessageBusConfig): Promise<void> {
- if (config) {
- this.config = { ...this.config, ...config };
- }
-
- this.startProcessing();
- this.startStatsCollection();
- this.emit('initialized');
- }
-
- async shutdown(): Promise<void> {
- if (this.processingInterval) {
- clearInterval(this.processingInterval);
- this.processingInterval = undefined;
- }
-
- // Clear all pending acks
- for (const [messageId, pending] of this.pendingAcks) {
- clearTimeout(pending.timeout);
- }
- this.pendingAcks.clear();
-
- // Clear all queues
- this.queues.clear();
- this.subscriptions.clear();
-
- this.emit('shutdown');
- }
-
- private generateMessageId(): string {
- this.messageCounter++;
- return `msg_${Date.now()}_${this.messageCounter.toString(36)}`;
- }
-
- async send(message: Omit<Message, 'id' | 'timestamp'>): Promise<string> {
- const fullMessage: Message = {
- ...message,
- id: this.generateMessageId(),
- timestamp: new Date(),
- };
-
- return this.enqueue(fullMessage);
- }
-
- async broadcast(message: Omit<Message, 'id' | 'timestamp' | 'to'>): Promise<string> {
- const fullMessage: Message = {
- ...message,
- id: this.generateMessageId(),
- timestamp: new Date(),
- to: 'broadcast',
- };
-
- return this.enqueue(fullMessage);
- }
-
- private async enqueue(message: Message): Promise<string> {
- const startTime = performance.now();
-
- if (message.to === 'broadcast') {
- // Broadcast to all subscribed agents
- for (const [agentId, subscription] of this.subscriptions) {
- if (agentId !== message.from) {
- this.addToQueue(agentId, message);
- }
- }
- } else {
- this.addToQueue(message.to, message);
- }
-
- this.stats.totalMessages++;
- const latency = performance.now() - startTime;
- this.updateLatencyStats(latency);
-
- this.emit('message.enqueued', { messageId: message.id, to: message.to });
-
- return message.id;
- }
-
- private addToQueue(agentId: string, message: Message): void {
- if (!this.queues.has(agentId)) {
- this.queues.set(agentId, []);
- }
-
- const queue = this.queues.get(agentId)!;
-
- // Check queue size limit
- if (queue.length >= this.config.maxQueueSize) {
- // Drop oldest low-priority messages
- const lowPriorityIdx = queue.findIndex(e =>
- e.message.priority === 'low' || e.message.priority === 'normal'
- );
- if (lowPriorityIdx !== -1) {
- queue.splice(lowPriorityIdx, 1);
- } else {
- // Queue full with high priority messages, drop oldest
- queue.shift();
- }
- }
-
- // Insert by priority (urgent first)
- const priorityOrder: Record<Message['priority'], number> = {
- urgent: 0,
- high: 1,
- normal: 2,
- low: 3,
- };
-
- const insertIdx = queue.findIndex(
- e => priorityOrder[e.message.priority] > priorityOrder[message.priority]
- );
-
- const entry: MessageQueueEntry = {
- message,
- attempts: 0,
- enqueuedAt: new Date(),
- };
-
- if (insertIdx === -1) {
- queue.push(entry);
- } else {
- queue.splice(insertIdx, 0, entry);
- }
- }
-
- subscribe(agentId: string, callback: (message: Message) => void, filter?: MessageType[]): void {
- this.subscriptions.set(agentId, {
- agentId,
- callback,
- filter,
- });
-
- // Initialize queue for this agent
- if (!this.queues.has(agentId)) {
- this.queues.set(agentId, []);
- }
-
- this.emit('subscription.added', { agentId });
- }
-
- unsubscribe(agentId: string): void {
- this.subscriptions.delete(agentId);
- this.queues.delete(agentId);
- this.emit('subscription.removed', { agentId });
- }
-
- async acknowledge(ack: MessageAck): Promise<void> {
- const pending = this.pendingAcks.get(ack.messageId);
- if (!pending) {
- return;
- }
-
- clearTimeout(pending.timeout);
- this.pendingAcks.delete(ack.messageId);
-
- if (!ack.received && ack.error) {
- this.handleAckFailure(pending.message, ack.error);
- }
-
- this.emit('message.acknowledged', {
- messageId: ack.messageId,
- success: ack.received
- });
- }
-
- private startProcessing(): void {
- this.processingInterval = setInterval(() => {
- this.processQueues();
- }, this.config.processingIntervalMs);
- }
-
- private processQueues(): void {
- const now = Date.now();
-
- for (const [agentId, queue] of this.queues) {
- const subscription = this.subscriptions.get(agentId);
- if (!subscription) {
- continue;
- }
-
- // Process messages in batch for better throughput
- const batchSize = Math.min(10, queue.length);
- const batch: MessageQueueEntry[] = [];
-
- for (let i = 0; i < batchSize && queue.length > 0; i++) {
- const entry = queue.shift()!;
-
- // Check TTL
- if (now - entry.message.timestamp.getTime() > entry.message.ttlMs) {
- this.emit('message.expired', { messageId: entry.message.id });
- continue;
- }
-
- // Check filter
- if (subscription.filter && !subscription.filter.includes(entry.message.type)) {
- continue;
- }
-
- batch.push(entry);
- }
-
- // Deliver batch
- for (const entry of batch) {
- this.deliverMessage(subscription, entry);
- }
- }
- }
-
- private deliverMessage(subscription: Subscription, entry: MessageQueueEntry): void {
- const message = entry.message;
-
- try {
- // Set up ack timeout if required
- if (message.requiresAck) {
- const timeout = setTimeout(() => {
- this.handleAckTimeout(message);
- }, this.config.ackTimeoutMs);
-
- this.pendingAcks.set(message.id, { message, timeout });
- }
-
- // Deliver asynchronously
- setImmediate(() => {
- try {
- subscription.callback(message);
- this.emit('message.delivered', {
- messageId: message.id,
- to: subscription.agentId
- });
- } catch (error) {
- this.handleDeliveryError(message, entry, error as Error);
- }
- });
- } catch (error) {
- this.handleDeliveryError(message, entry, error as Error);
- }
- }
-
- private handleAckTimeout(message: Message): void {
- this.pendingAcks.delete(message.id);
- this.stats.ackRate = Math.max(0, this.stats.ackRate - 0.01);
- this.emit('message.ack_timeout', { messageId: message.id });
- }
-
- private handleAckFailure(message: Message, error: string): void {
- this.stats.errorRate += 0.01;
- this.emit('message.ack_failed', { messageId: message.id, error });
- }
-
- private handleDeliveryError(message: Message, entry: MessageQueueEntry, error: Error): void {
- entry.attempts++;
- entry.lastAttemptAt = new Date();
-
- if (entry.attempts < this.config.retryAttempts) {
- // Re-queue for retry
- this.addToQueue(message.to, message);
- this.emit('message.retry', {
- messageId: message.id,
- attempt: entry.attempts
- });
- } else {
- this.stats.errorRate += 0.01;
- this.emit('message.failed', {
- messageId: message.id,
- error: error.message
- });
- }
- }
-
- private startStatsCollection(): void {
- setInterval(() => {
- this.calculateMessagesPerSecond();
- }, 1000);
- }
-
- private calculateMessagesPerSecond(): void {
- const now = Date.now();
-
- // Track message count per second
- this.messageHistory.push({
- timestamp: now,
- count: this.stats.totalMessages,
- });
-
- // Keep only last 60 seconds
- this.messageHistory = this.messageHistory.filter(
- h => now - h.timestamp < 60000
- );
-
- if (this.messageHistory.length >= 2) {
- const oldest = this.messageHistory[0];
- const newest = this.messageHistory[this.messageHistory.length - 1];
- const seconds = (newest.timestamp - oldest.timestamp) / 1000;
- const messages = newest.count - oldest.count;
- this.stats.messagesPerSecond = seconds > 0 ? messages / seconds : 0;
- }
-
- // Update queue depth
- this.stats.queueDepth = this.getQueueDepth();
- }
-
- private updateLatencyStats(latencyMs: number): void {
- // Exponential moving average
- const alpha = 0.1;
- this.stats.avgLatencyMs = alpha * latencyMs + (1 - alpha) * this.stats.avgLatencyMs;
- }
-
- getStats(): MessageBusStats {
- return { ...this.stats };
- }
-
- getQueueDepth(): number {
- let total = 0;
- for (const queue of this.queues.values()) {
- total += queue.length;
- }
- return total;
- }
-
- // Direct message retrieval for agents (pull mode)
- getMessages(agentId: string): Message[] {
- const queue = this.queues.get(agentId);
- if (!queue) {
- return [];
- }
-
- const now = Date.now();
- const messages: Message[] = [];
-
- while (queue.length > 0) {
- const entry = queue.shift()!;
- if (now - entry.message.timestamp.getTime() <= entry.message.ttlMs) {
- messages.push(entry.message);
- }
- }
-
- return messages;
- }
-
- // Query pending messages for an agent
- hasPendingMessages(agentId: string): boolean {
- const queue = this.queues.get(agentId);
- return queue !== undefined && queue.length > 0;
- }
-
- // Get message by ID
- getMessage(messageId: string): Message | undefined {
- for (const queue of this.queues.values()) {
- const entry = queue.find(e => e.message.id === messageId);
- if (entry) {
- return entry.message;
- }
- }
- return undefined;
- }
-}
-
-export function createMessageBus(config?: Partial<MessageBusConfig>): MessageBus {
- return new MessageBus(config);
-}
diff --git a/v3/swarm/topology-manager.ts b/v3/swarm/topology-manager.ts
deleted file mode 100644
index 42b964a4b6..0000000000
--- a/v3/swarm/topology-manager.ts
+++ /dev/null
@@ -1,576 +0,0 @@
-/**
- * V3 Topology Manager
- * Manages swarm network topology with support for mesh, hierarchical, centralized, and hybrid modes
- */
-
-import { EventEmitter } from 'events';
-import {
- TopologyConfig,
- TopologyState,
- TopologyNode,
- TopologyEdge,
- TopologyPartition,
- TopologyType,
- ITopologyManager,
-} from './types.js';
-
-export class TopologyManager extends EventEmitter implements ITopologyManager {
- private config: TopologyConfig;
- private state: TopologyState;
- private nodeIndex: Map<string, TopologyNode> = new Map();
- private adjacencyList: Map<string, Set<string>> = new Map();
- private lastRebalance: Date = new Date();
-
- constructor(config: Partial<TopologyConfig> = {}) {
- super();
- this.config = {
- type: config.type ?? 'mesh',
- maxAgents: config.maxAgents ?? 100,
- replicationFactor: config.replicationFactor ?? 2,
- partitionStrategy: config.partitionStrategy ?? 'hash',
- failoverEnabled: config.failoverEnabled ?? true,
- autoRebalance: config.autoRebalance ?? true,
- };
-
- this.state = {
- type: this.config.type,
- nodes: [],
- edges: [],
- leader: undefined,
- partitions: [],
- };
- }
-
- async initialize(config?: TopologyConfig): Promise<void> {
- if (config) {
- this.config = { ...this.config, ...config };
- this.state.type = this.config.type;
- }
-
- this.emit('initialized', { type: this.config.type });
- }
-
- getState(): TopologyState {
- return {
- ...this.state,
- nodes: [...this.state.nodes],
- edges: [...this.state.edges],
- partitions: [...this.state.partitions],
- };
- }
-
- async addNode(agentId: string, role: TopologyNode['role']): Promise<TopologyNode> {
- if (this.nodeIndex.has(agentId)) {
- throw new Error(`Node ${agentId} already exists in topology`);
- }
-
- if (this.nodeIndex.size >= this.config.maxAgents) {
- throw new Error(`Maximum agents (${this.config.maxAgents}) reached`);
- }
-
- // Create node with connections based on topology type
- const connections = this.calculateInitialConnections(agentId, role);
-
- const node: TopologyNode = {
- id: `node_${agentId}`,
- agentId,
- role: this.determineRole(role),
- status: 'syncing',
- connections,
- metadata: {
- joinedAt: new Date().toISOString(),
- version: '1.0.0',
- },
- };
-
- // Add to state
- this.nodeIndex.set(agentId, node);
- this.state.nodes.push(node);
-
- // Initialize adjacency list
- this.adjacencyList.set(agentId, new Set(connections));
-
- // Create edges
- await this.createEdgesForNode(node);
-
- // Update partitions if needed
- await this.updatePartitions(node);
-
- // Mark as active after sync
- node.status = 'active';
-
- this.emit('node.added', { node });
-
- // Trigger rebalance if needed
- if (this.config.autoRebalance && this.shouldRebalance()) {
- await this.rebalance();
- }
-
- return node;
- }
-
- async removeNode(agentId: string): Promise<void> {
- const node = this.nodeIndex.get(agentId);
- if (!node) {
- return;
- }
-
- // Remove from state
- this.state.nodes = this.state.nodes.filter(n => n.agentId !== agentId);
- this.nodeIndex.delete(agentId);
-
- // Remove all edges connected to this node
- this.state.edges = this.state.edges.filter(
- e => e.from !== agentId && e.to !== agentId
- );
-
- // Update adjacency list
- this.adjacencyList.delete(agentId);
- for (const neighbors of this.adjacencyList.values()) {
- neighbors.delete(agentId);
- }
-
- // Update all nodes' connections
- for (const n of this.state.nodes) {
- n.connections = n.connections.filter(c => c !== agentId);
- }
-
- // If this was the leader, elect new one
- if (this.state.leader === agentId) {
- await this.electLeader();
- }
-
- // Update partitions
- for (const partition of this.state.partitions) {
- partition.nodes = partition.nodes.filter(n => n !== agentId);
- if (partition.leader === agentId) {
- partition.leader = partition.nodes[0] || '';
- }
- }
-
- this.emit('node.removed', { agentId });
-
- // Trigger rebalance if needed
- if (this.config.autoRebalance) {
- await this.rebalance();
- }
- }
-
- async updateNode(agentId: string, updates: Partial<TopologyNode>): Promise<void> {
- const node = this.nodeIndex.get(agentId);
- if (!node) {
- throw new Error(`Node ${agentId} not found`);
- }
-
- // Apply updates
- if (updates.role !== undefined) node.role = updates.role;
- if (updates.status !== undefined) node.status = updates.status;
- if (updates.connections !== undefined) {
- node.connections = updates.connections;
- this.adjacencyList.set(agentId, new Set(updates.connections));
- }
- if (updates.metadata !== undefined) {
- node.metadata = { ...node.metadata, ...updates.metadata };
- }
-
- this.emit('node.updated', { agentId, updates });
- }
-
- getLeader(): string | undefined {
- return this.state.leader;
- }
-
- async electLeader(): Promise<string> {
- if (this.state.nodes.length === 0) {
- throw new Error('No nodes available for leader election');
- }
-
- // For hierarchical topology, the queen is the leader
- if (this.config.type === 'hierarchical') {
- const queen = this.state.nodes.find(n => n.role === 'queen');
- if (queen) {
- this.state.leader = queen.agentId;
- return queen.agentId;
- }
- }
-
- // For centralized topology, the coordinator is the leader
- if (this.config.type === 'centralized') {
- const coordinator = this.state.nodes.find(n => n.role === 'coordinator');
- if (coordinator) {
- this.state.leader = coordinator.agentId;
- return coordinator.agentId;
- }
- }
-
- // For mesh/hybrid, elect based on node capabilities
- const candidates = this.state.nodes
- .filter(n => n.status === 'active')
- .sort((a, b) => {
- // Prefer coordinators, then queens
- const roleOrder: Record<TopologyNode['role'], number> = {
- queen: 0,
- coordinator: 1,
- worker: 2,
- peer: 2,
- };
- return roleOrder[a.role] - roleOrder[b.role];
- });
-
- if (candidates.length === 0) {
- throw new Error('No active nodes available for leader election');
- }
-
- const leader = candidates[0];
- this.state.leader = leader.agentId;
-
- this.emit('leader.elected', { leaderId: leader.agentId });
-
- return leader.agentId;
- }
-
- async rebalance(): Promise<void> {
- const now = new Date();
- const timeSinceLastRebalance = now.getTime() - this.lastRebalance.getTime();
-
- // Prevent too frequent rebalancing
- if (timeSinceLastRebalance < 5000) {
- return;
- }
-
- this.lastRebalance = now;
-
- switch (this.config.type) {
- case 'mesh':
- await this.rebalanceMesh();
- break;
- case 'hierarchical':
- await this.rebalanceHierarchical();
- break;
- case 'centralized':
- await this.rebalanceCentralized();
- break;
- case 'hybrid':
- await this.rebalanceHybrid();
- break;
- }
-
- this.emit('topology.rebalanced', { type: this.config.type });
- }
-
- getNeighbors(agentId: string): string[] {
- return Array.from(this.adjacencyList.get(agentId) || []);
- }
-
- findOptimalPath(from: string, to: string): string[] {
- if (from === to) {
- return [from];
- }
-
- // BFS for shortest path
- const visited = new Set<string>();
- const queue: { node: string; path: string[] }[] = [{ node: from, path: [from] }];
-
- while (queue.length > 0) {
- const { node, path } = queue.shift()!;
-
- if (node === to) {
- return path;
- }
-
- if (visited.has(node)) {
- continue;
- }
- visited.add(node);
-
- const neighbors = this.adjacencyList.get(node) || new Set();
- for (const neighbor of neighbors) {
- if (!visited.has(neighbor)) {
- queue.push({ node: neighbor, path: [...path, neighbor] });
- }
- }
- }
-
- // No path found
- return [];
- }
-
- // ===== PRIVATE METHODS =====
-
- private determineRole(requestedRole: TopologyNode['role']): TopologyNode['role'] {
- switch (this.config.type) {
- case 'mesh':
- return 'peer';
- case 'hierarchical':
- // First node becomes queen
- if (this.state.nodes.length === 0) {
- return 'queen';
- }
- return requestedRole === 'queen' && !this.hasQueen() ? 'queen' : 'worker';
- case 'centralized':
- // First node becomes coordinator
- if (this.state.nodes.length === 0) {
- return 'coordinator';
- }
- return 'worker';
- case 'hybrid':
- return requestedRole;
- }
- }
-
- private hasQueen(): boolean {
- return this.state.nodes.some(n => n.role === 'queen');
- }
-
- private calculateInitialConnections(agentId: string, role: TopologyNode['role']): string[] {
- const existingNodes = Array.from(this.nodeIndex.keys());
-
- switch (this.config.type) {
- case 'mesh':
- // In mesh, connect to all existing nodes (up to a limit)
- const maxMeshConnections = Math.min(10, existingNodes.length);
- return existingNodes.slice(0, maxMeshConnections);
-
- case 'hierarchical':
- // Workers connect to queen, queen connects to workers
- if (role === 'queen' || existingNodes.length === 0) {
- return existingNodes;
- }
- const queen = this.state.nodes.find(n => n.role === 'queen');
- return queen ? [queen.agentId] : [];
-
- case 'centralized':
- // All nodes connect to coordinator
- if (role === 'coordinator' || existingNodes.length === 0) {
- return existingNodes;
- }
- const coordinator = this.state.nodes.find(n => n.role === 'coordinator');
- return coordinator ? [coordinator.agentId] : [];
-
- case 'hybrid':
- // Mix of mesh and hierarchical
- const leaders = this.state.nodes.filter(n =>
- n.role === 'queen' || n.role === 'coordinator'
- );
- const peers = existingNodes.slice(0, 3);
- return [...new Set([...leaders.map(l => l.agentId), ...peers])];
- }
- }
-
- private async createEdgesForNode(node: TopologyNode): Promise<void> {
- for (const connectionId of node.connections) {
- const edge: TopologyEdge = {
- from: node.agentId,
- to: connectionId,
- weight: 1,
- bidirectional: this.config.type === 'mesh',
- latencyMs: 0,
- };
-
- this.state.edges.push(edge);
-
- // Add bidirectional edge
- if (edge.bidirectional) {
- const existingNode = this.nodeIndex.get(connectionId);
- if (existingNode && !existingNode.connections.includes(node.agentId)) {
- existingNode.connections.push(node.agentId);
- this.adjacencyList.get(connectionId)?.add(node.agentId);
- }
- }
- }
- }
-
- private async updatePartitions(node: TopologyNode): Promise<void> {
- if (this.config.type !== 'mesh' && this.config.type !== 'hybrid') {
- return;
- }
-
- // Create partitions based on strategy
- const nodesPerPartition = Math.ceil(this.config.maxAgents / 10);
- const partitionIndex = Math.floor(this.state.nodes.length / nodesPerPartition);
-
- if (this.state.partitions.length <= partitionIndex) {
- // Create new partition
- const partition: TopologyPartition = {
- id: `partition_${partitionIndex}`,
- nodes: [node.agentId],
- leader: node.agentId,
- replicaCount: 1,
- };
- this.state.partitions.push(partition);
- } else {
- // Add to existing partition
- const partition = this.state.partitions[partitionIndex];
- partition.nodes.push(node.agentId);
- partition.replicaCount = Math.min(
- partition.nodes.length,
- this.config.replicationFactor ?? 2
- );
- }
- }
-
- private shouldRebalance(): boolean {
- // Check for uneven distribution
- if (this.config.type === 'mesh') {
- const avgConnections = this.state.nodes.reduce(
- (sum, n) => sum + n.connections.length, 0
- ) / Math.max(1, this.state.nodes.length);
-
- for (const node of this.state.nodes) {
- if (Math.abs(node.connections.length - avgConnections) > avgConnections * 0.5) {
- return true;
- }
- }
- }
-
- return false;
- }
-
- private async rebalanceMesh(): Promise<void> {
- const targetConnections = Math.min(5, this.state.nodes.length - 1);
-
- for (const node of this.state.nodes) {
- // Ensure minimum connections
- while (node.connections.length < targetConnections) {
- const candidates = this.state.nodes
- .filter(n =>
- n.agentId !== node.agentId &&
- !node.connections.includes(n.agentId)
- )
- .sort(() => Math.random() - 0.5);
-
- if (candidates.length > 0) {
- node.connections.push(candidates[0].agentId);
- this.adjacencyList.get(node.agentId)?.add(candidates[0].agentId);
-
- // Bidirectional
- candidates[0].connections.push(node.agentId);
- this.adjacencyList.get(candidates[0].agentId)?.add(node.agentId);
- } else {
- break;
- }
- }
- }
- }
-
- private async rebalanceHierarchical(): Promise<void> {
- const queen = this.state.nodes.find(n => n.role === 'queen');
- if (!queen) {
- // Elect a queen if missing
- if (this.state.nodes.length > 0) {
- this.state.nodes[0].role = 'queen';
- }
- return;
- }
-
- // Ensure all workers are connected to queen
- for (const node of this.state.nodes) {
- if (node.role === 'worker' && !node.connections.includes(queen.agentId)) {
- node.connections.push(queen.agentId);
- this.adjacencyList.get(node.agentId)?.add(queen.agentId);
- queen.connections.push(node.agentId);
- this.adjacencyList.get(queen.agentId)?.add(node.agentId);
- }
- }
- }
-
- private async rebalanceCentralized(): Promise<void> {
- const coordinator = this.state.nodes.find(n => n.role === 'coordinator');
- if (!coordinator) {
- if (this.state.nodes.length > 0) {
- this.state.nodes[0].role = 'coordinator';
- }
- return;
- }
-
- // Ensure all nodes are connected to coordinator
- for (const node of this.state.nodes) {
- if (node.role !== 'coordinator' && !node.connections.includes(coordinator.agentId)) {
- node.connections = [coordinator.agentId];
- this.adjacencyList.set(node.agentId, new Set([coordinator.agentId]));
- coordinator.connections.push(node.agentId);
- this.adjacencyList.get(coordinator.agentId)?.add(node.agentId);
- }
- }
- }
-
- private async rebalanceHybrid(): Promise<void> {
- // Hybrid combines mesh for workers and hierarchical for coordinators
- const coordinators = this.state.nodes.filter(
- n => n.role === 'queen' || n.role === 'coordinator'
- );
- const workers = this.state.nodes.filter(n => n.role === 'worker' || n.role === 'peer');
-
- // Connect workers in mesh (limited connections)
- for (const worker of workers) {
- const targetConnections = Math.min(3, workers.length - 1);
- const currentWorkerConnections = worker.connections.filter(
- c => workers.some(w => w.agentId === c)
- );
-
- while (currentWorkerConnections.length < targetConnections) {
- const candidates = workers.filter(
- w => w.agentId !== worker.agentId && !currentWorkerConnections.includes(w.agentId)
- );
- if (candidates.length === 0) break;
-
- const target = candidates[Math.floor(Math.random() * candidates.length)];
- worker.connections.push(target.agentId);
- currentWorkerConnections.push(target.agentId);
- this.adjacencyList.get(worker.agentId)?.add(target.agentId);
- }
- }
-
- // Connect all workers to at least one coordinator
- if (coordinators.length > 0) {
- for (const worker of workers) {
- const hasCoordinator = worker.connections.some(
- c => coordinators.some(coord => coord.agentId === c)
- );
- if (!hasCoordinator) {
- const coord = coordinators[Math.floor(Math.random() * coordinators.length)];
- worker.connections.push(coord.agentId);
- this.adjacencyList.get(worker.agentId)?.add(coord.agentId);
- coord.connections.push(worker.agentId);
- this.adjacencyList.get(coord.agentId)?.add(worker.agentId);
- }
- }
- }
- }
-
- // ===== UTILITY METHODS =====
-
- getNode(agentId: string): TopologyNode | undefined {
- return this.nodeIndex.get(agentId);
- }
-
- getNodesByRole(role: TopologyNode['role']): TopologyNode[] {
- return this.state.nodes.filter(n => n.role === role);
- }
-
- getActiveNodes(): TopologyNode[] {
- return this.state.nodes.filter(n => n.status === 'active');
- }
-
- getPartition(partitionId: string): TopologyPartition | undefined {
- return this.state.partitions.find(p => p.id === partitionId);
- }
-
- isConnected(from: string, to: string): boolean {
- return this.adjacencyList.get(from)?.has(to) ?? false;
- }
-
- getConnectionCount(): number {
- return this.state.edges.length;
- }
-
- getAverageConnections(): number {
- if (this.state.nodes.length === 0) return 0;
- const total = this.state.nodes.reduce((sum, n) => sum + n.connections.length, 0);
- return total / this.state.nodes.length;
- }
-}
-
-export function createTopologyManager(config?: Partial<TopologyConfig>): TopologyManager {
- return new TopologyManager(config);
-}
diff --git a/v3/swarm/types.ts b/v3/swarm/types.ts
deleted file mode 100644
index 37366a9fd5..0000000000
--- a/v3/swarm/types.ts
+++ /dev/null
@@ -1,545 +0,0 @@
-/**
- * V3 Unified Swarm Coordinator Types
- * Consolidated type definitions for the unified swarm coordination system
- */
-
-import { EventEmitter } from 'events';
-
-// ===== CORE IDENTIFIERS =====
-
-export interface SwarmId {
- id: string;
- namespace: string;
- version: string;
- createdAt: Date;
-}
-
-export interface AgentId {
- id: string;
- swarmId: string;
- type: AgentType;
- instance: number;
-}
-
-export interface TaskId {
- id: string;
- swarmId: string;
- sequence: number;
- priority: TaskPriority;
-}
-
-// ===== TOPOLOGY TYPES =====
-
-export type TopologyType = 'mesh' | 'hierarchical' | 'centralized' | 'hybrid';
-
-export interface TopologyConfig {
- type: TopologyType;
- maxAgents: number;
- replicationFactor?: number;
- partitionStrategy?: 'hash' | 'range' | 'round-robin';
- failoverEnabled?: boolean;
- autoRebalance?: boolean;
-}
-
-export interface TopologyState {
- type: TopologyType;
- nodes: TopologyNode[];
- edges: TopologyEdge[];
- leader?: string;
- partitions: TopologyPartition[];
-}
-
-export interface TopologyNode {
- id: string;
- agentId: string;
- role: 'queen' | 'worker' | 'coordinator' | 'peer';
- status: 'active' | 'inactive' | 'syncing' | 'failed';
- connections: string[];
- metadata: Record<string, unknown>;
-}
-
-export interface TopologyEdge {
- from: string;
- to: string;
- weight: number;
- bidirectional: boolean;
- latencyMs?: number;
-}
-
-export interface TopologyPartition {
- id: string;
- nodes: string[];
- leader: string;
- replicaCount: number;
-}
-
-// ===== AGENT TYPES =====
-
-export type AgentType =
- | 'coordinator'
- | 'researcher'
- | 'coder'
- | 'analyst'
- | 'architect'
- | 'tester'
- | 'reviewer'
- | 'optimizer'
- | 'documenter'
- | 'monitor'
- | 'specialist'
- | 'queen'
- | 'worker';
-
-export type AgentStatus =
- | 'initializing'
- | 'idle'
- | 'busy'
- | 'paused'
- | 'error'
- | 'offline'
- | 'terminating'
- | 'terminated';
-
-export interface AgentCapabilities {
- codeGeneration: boolean;
- codeReview: boolean;
- testing: boolean;
- documentation: boolean;
- research: boolean;
- analysis: boolean;
- coordination: boolean;
- languages: string[];
- frameworks: string[];
- domains: string[];
- tools: string[];
- maxConcurrentTasks: number;
- maxMemoryUsage: number;
- maxExecutionTime: number;
- reliability: number;
- speed: number;
- quality: number;
-}
-
-export interface AgentMetrics {
- tasksCompleted: number;
- tasksFailed: number;
- averageExecutionTime: number;
- successRate: number;
- cpuUsage: number;
- memoryUsage: number;
- messagesProcessed: number;
- lastActivity: Date;
- responseTime: number;
- health: number;
-}
-
-export interface AgentState {
- id: AgentId;
- name: string;
- type: AgentType;
- status: AgentStatus;
- capabilities: AgentCapabilities;
- metrics: AgentMetrics;
- currentTask?: TaskId;
- workload: number;
- health: number;
- lastHeartbeat: Date;
- topologyRole?: TopologyNode['role'];
- connections: string[];
-}
-
-// ===== TASK TYPES =====
-
-export type TaskType =
- | 'research'
- | 'analysis'
- | 'coding'
- | 'testing'
- | 'review'
- | 'documentation'
- | 'coordination'
- | 'consensus'
- | 'custom';
-
-export type TaskStatus =
- | 'created'
- | 'queued'
- | 'assigned'
- | 'running'
- | 'paused'
- | 'completed'
- | 'failed'
- | 'cancelled'
- | 'timeout';
-
-export type TaskPriority = 'critical' | 'high' | 'normal' | 'low' | 'background';
-
-export interface TaskDefinition {
- id: TaskId;
- type: TaskType;
- name: string;
- description: string;
- priority: TaskPriority;
- status: TaskStatus;
- assignedTo?: AgentId;
- dependencies: TaskId[];
- input: unknown;
- output?: unknown;
- createdAt: Date;
- startedAt?: Date;
- completedAt?: Date;
- timeoutMs: number;
- retries: number;
- maxRetries: number;
- metadata: Record<string, unknown>;
-}
-
-// ===== CONSENSUS TYPES =====
-
-export type ConsensusAlgorithm = 'raft' | 'byzantine' | 'gossip' | 'paxos';
-
-export interface ConsensusConfig {
- algorithm: ConsensusAlgorithm;
- threshold: number;
- timeoutMs: number;
- maxRounds: number;
- requireQuorum: boolean;
-}
-
-export interface ConsensusProposal {
- id: string;
- proposerId: string;
- value: unknown;
- term: number;
- timestamp: Date;
- votes: Map<string, ConsensusVote>;
- status: 'pending' | 'accepted' | 'rejected' | 'expired';
-}
-
-export interface ConsensusVote {
- voterId: string;
- approve: boolean;
- confidence: number;
- timestamp: Date;
- reason?: string;
-}
-
-export interface ConsensusResult {
- proposalId: string;
- approved: boolean;
- approvalRate: number;
- participationRate: number;
- finalValue: unknown;
- rounds: number;
- durationMs: number;
-}
-
-// ===== MESSAGE BUS TYPES =====
-
-export type MessageType =
- | 'task_assign'
- | 'task_complete'
- | 'task_fail'
- | 'heartbeat'
- | 'status_update'
- | 'consensus_propose'
- | 'consensus_vote'
- | 'consensus_commit'
- | 'topology_update'
- | 'agent_join'
- | 'agent_leave'
- | 'broadcast'
- | 'direct';
-
-export interface Message {
- id: string;
- type: MessageType;
- from: string;
- to: string | 'broadcast';
- payload: unknown;
- timestamp: Date;
- priority: 'urgent' | 'high' | 'normal' | 'low';
- requiresAck: boolean;
- ttlMs: number;
- correlationId?: string;
-}
-
-export interface MessageAck {
- messageId: string;
- from: string;
- received: boolean;
- processedAt: Date;
- error?: string;
-}
-
-export interface MessageBusConfig {
- maxQueueSize: number;
- processingIntervalMs: number;
- ackTimeoutMs: number;
- retryAttempts: number;
- enablePersistence: boolean;
- compressionEnabled: boolean;
-}
-
-export interface MessageBusStats {
- totalMessages: number;
- messagesPerSecond: number;
- avgLatencyMs: number;
- queueDepth: number;
- ackRate: number;
- errorRate: number;
-}
-
-// ===== COORDINATOR TYPES =====
-
-export interface CoordinatorConfig {
- topology: TopologyConfig;
- consensus: ConsensusConfig;
- messageBus: MessageBusConfig;
- maxAgents: number;
- maxTasks: number;
- heartbeatIntervalMs: number;
- healthCheckIntervalMs: number;
- taskTimeoutMs: number;
- autoScaling: boolean;
- autoRecovery: boolean;
-}
-
-export interface CoordinatorState {
- id: SwarmId;
- status: SwarmStatus;
- topology: TopologyState;
- agents: Map<string, AgentState>;
- tasks: Map<string, TaskDefinition>;
- metrics: CoordinatorMetrics;
- startedAt?: Date;
-}
-
-export type SwarmStatus =
- | 'initializing'
- | 'running'
- | 'paused'
- | 'recovering'
- | 'shutting_down'
- | 'stopped'
- | 'failed';
-
-export interface CoordinatorMetrics {
- uptime: number;
- activeAgents: number;
- totalTasks: number;
- completedTasks: number;
- failedTasks: number;
- avgTaskDurationMs: number;
- messagesPerSecond: number;
- consensusSuccessRate: number;
- coordinationLatencyMs: number;
- memoryUsageBytes: number;
-}
-
-// ===== EVENT TYPES =====
-
-export type SwarmEventType =
- | 'swarm.initialized'
- | 'swarm.started'
- | 'swarm.paused'
- | 'swarm.resumed'
- | 'swarm.stopped'
- | 'swarm.failed'
- | 'agent.joined'
- | 'agent.left'
- | 'agent.status_changed'
- | 'agent.heartbeat'
- | 'agent.domain_assigned'
- | 'task.created'
- | 'task.assigned'
- | 'task.started'
- | 'task.completed'
- | 'task.failed'
- | 'task.queued'
- | 'topology.updated'
- | 'topology.rebalanced'
- | 'consensus.proposed'
- | 'consensus.achieved'
- | 'consensus.failed'
- | 'message.sent'
- | 'message.received'
- | 'parallel.execution.completed'
- | 'hierarchy.spawned';
-
-export interface SwarmEvent {
- id: string;
- type: SwarmEventType;
- source: string;
- timestamp: Date;
- data: Record<string, unknown>;
- correlationId?: string;
-}
-
-// ===== POOL TYPES =====
-
-export interface AgentPoolConfig {
- name: string;
- type: AgentType;
- minSize: number;
- maxSize: number;
- scaleUpThreshold: number;
- scaleDownThreshold: number;
- cooldownMs: number;
- healthCheckIntervalMs: number;
-}
-
-export interface AgentPoolState {
- id: string;
- config: AgentPoolConfig;
- agents: Map<string, AgentState>;
- availableAgents: string[];
- busyAgents: string[];
- pendingScale: number;
- lastScaleOperation?: Date;
-}
-
-// ===== UTILITY TYPES =====
-
-export interface HealthCheck {
- agentId: string;
- timestamp: Date;
- healthy: boolean;
- latencyMs: number;
- details: Record<string, unknown>;
-}
-
-export interface PerformanceReport {
- timestamp: Date;
- window: number;
- coordinationLatencyP50: number;
- coordinationLatencyP99: number;
- messagesPerSecond: number;
- taskThroughput: number;
- agentUtilization: number;
- consensusSuccessRate: number;
-}
-
-// ===== CONSTANTS =====
-
-export const SWARM_CONSTANTS = {
- DEFAULT_HEARTBEAT_INTERVAL_MS: 5000,
- DEFAULT_HEALTH_CHECK_INTERVAL_MS: 10000,
- DEFAULT_TASK_TIMEOUT_MS: 300000,
- DEFAULT_CONSENSUS_TIMEOUT_MS: 30000,
- DEFAULT_MESSAGE_TTL_MS: 60000,
- DEFAULT_MAX_AGENTS: 100,
- DEFAULT_MAX_TASKS: 1000,
- DEFAULT_CONSENSUS_THRESHOLD: 0.66,
- MAX_QUEUE_SIZE: 10000,
- MAX_RETRIES: 3,
- COORDINATION_LATENCY_TARGET_MS: 100,
- MESSAGES_PER_SECOND_TARGET: 1000,
-} as const;
-
-// ===== TYPE GUARDS =====
-
-export function isAgentId(obj: unknown): obj is AgentId {
- return (
- typeof obj === 'object' &&
- obj !== null &&
- 'id' in obj &&
- 'swarmId' in obj &&
- 'type' in obj
- );
-}
-
-export function isTaskId(obj: unknown): obj is TaskId {
- return (
- typeof obj === 'object' &&
- obj !== null &&
- 'id' in obj &&
- 'swarmId' in obj &&
- 'sequence' in obj
- );
-}
-
-export function isMessage(obj: unknown): obj is Message {
- return (
- typeof obj === 'object' &&
- obj !== null &&
- 'id' in obj &&
- 'type' in obj &&
- 'from' in obj &&
- 'to' in obj
- );
-}
-
-// ===== INTERFACES FOR COMPONENTS =====
-
-export interface ITopologyManager {
- initialize(config: TopologyConfig): Promise<void>;
- getState(): TopologyState;
- addNode(agentId: string, role: TopologyNode['role']): Promise<TopologyNode>;
- removeNode(agentId: string): Promise<void>;
- updateNode(agentId: string, updates: Partial<TopologyNode>): Promise<void>;
- getLeader(): string | undefined;
- electLeader(): Promise<string>;
- rebalance(): Promise<void>;
- getNeighbors(agentId: string): string[];
- findOptimalPath(from: string, to: string): string[];
-}
-
-export interface IConsensusEngine {
- initialize(config: ConsensusConfig): Promise<void>;
- propose(value: unknown, proposerId: string): Promise<ConsensusProposal>;
- vote(proposalId: string, vote: ConsensusVote): Promise<void>;
- getProposal(proposalId: string): ConsensusProposal | undefined;
- awaitConsensus(proposalId: string): Promise<ConsensusResult>;
- getActiveProposals(): ConsensusProposal[];
-}
-
-export interface IMessageBus {
- initialize(config: MessageBusConfig): Promise<void>;
- send(message: Omit<Message, 'id' | 'timestamp'>): Promise<string>;
- broadcast(message: Omit<Message, 'id' | 'timestamp' | 'to'>): Promise<string>;
- subscribe(agentId: string, callback: (message: Message) => void): void;
- unsubscribe(agentId: string): void;
- acknowledge(ack: MessageAck): Promise<void>;
- getStats(): MessageBusStats;
- getQueueDepth(): number;
-}
-
-export interface IAgentPool {
- initialize(config: AgentPoolConfig): Promise<void>;
- acquire(): Promise<AgentState | undefined>;
- release(agentId: string): Promise<void>;
- add(agent: AgentState): Promise<void>;
- remove(agentId: string): Promise<void>;
- scale(delta: number): Promise<void>;
- getState(): AgentPoolState;
- getAvailableCount(): number;
-}
-
-export interface IUnifiedSwarmCoordinator {
- initialize(): Promise<void>;
- shutdown(): Promise<void>;
- pause(): Promise<void>;
- resume(): Promise<void>;
-
- // Agent management
- registerAgent(agent: Omit<AgentState, 'id'>): Promise<string>;
- unregisterAgent(agentId: string): Promise<void>;
- getAgent(agentId: string): AgentState | undefined;
- getAllAgents(): AgentState[];
-
- // Task management
- submitTask(task: Omit<TaskDefinition, 'id' | 'status' | 'createdAt'>): Promise<string>;
- cancelTask(taskId: string): Promise<void>;
- getTask(taskId: string): TaskDefinition | undefined;
- getAllTasks(): TaskDefinition[];
-
- // Coordination
- proposeConsensus(value: unknown): Promise<ConsensusResult>;
- broadcastMessage(payload: unknown, priority?: Message['priority']): Promise<void>;
-
- // Monitoring
- getState(): CoordinatorState;
- getMetrics(): CoordinatorMetrics;
- getPerformanceReport(): PerformanceReport;
-}
diff --git a/v3/swarm/unified-coordinator.ts b/v3/swarm/unified-coordinator.ts
deleted file mode 100644
index bcae9ebe8e..0000000000
--- a/v3/swarm/unified-coordinator.ts
+++ /dev/null
@@ -1,1568 +0,0 @@
-/**
- * V3 Unified Swarm Coordinator
- * Consolidates SwarmCoordinator, HiveMind, Maestro, and AgentManager into a single system
- * Supports the 15-agent hierarchical mesh structure with domain-based task routing
- *
- * Performance Targets:
- * - Agent coordination: <100ms for 15 agents
- * - Consensus: <100ms
- * - Message throughput: 1000+ msgs/sec
- *
- * Agent Hierarchy:
- * - Queen (Agent 1): Top-level coordinator
- * - Security Domain (Agents 2-4): security-architect, security-auditor, test-architect
- * - Core Domain (Agents 5-9): core-architect, type-modernization, memory-specialist, swarm-specialist, mcp-optimizer
- * - Integration Domain (Agents 10-12): integration-architect, cli-modernizer, neural-integrator
- * - Support Domain (Agents 13-15): test-architect, performance-engineer, deployment-engineer
- */
-
-import { EventEmitter } from 'events';
-import {
- SwarmId,
- AgentId,
- TaskId,
- AgentState,
- AgentType,
- AgentStatus,
- AgentCapabilities,
- AgentMetrics,
- TaskDefinition,
- TaskType,
- TaskStatus,
- TaskPriority,
- CoordinatorConfig,
- CoordinatorState,
- CoordinatorMetrics,
- SwarmStatus,
- SwarmEvent,
- SwarmEventType,
- TopologyConfig,
- TopologyType,
- ConsensusConfig,
- ConsensusResult,
- Message,
- MessageType,
- PerformanceReport,
- IUnifiedSwarmCoordinator,
- SWARM_CONSTANTS,
-} from './types.js';
-import { TopologyManager, createTopologyManager } from './topology-manager.js';
-import { MessageBus, createMessageBus } from './message-bus.js';
-import { AgentPool, createAgentPool } from './agent-pool.js';
-import { ConsensusEngine, createConsensusEngine } from './consensus/index.js';
-
-// =============================================================================
-// Domain Types for 15-Agent Hierarchy
-// =============================================================================
-
-export type AgentDomain = 'queen' | 'security' | 'core' | 'integration' | 'support';
-
-export interface DomainConfig {
- name: AgentDomain;
- agentNumbers: number[];
- priority: number;
- capabilities: string[];
- description: string;
-}
-
-export interface TaskAssignment {
- taskId: string;
- domain: AgentDomain;
- agentId: string;
- priority: TaskPriority;
- assignedAt: Date;
-}
-
-export interface ParallelExecutionResult {
- taskId: string;
- domain: AgentDomain;
- success: boolean;
- result?: unknown;
- error?: Error;
- durationMs: number;
-}
-
-export interface DomainStatus {
- name: AgentDomain;
- agentCount: number;
- availableAgents: number;
- busyAgents: number;
- tasksQueued: number;
- tasksCompleted: number;
-}
-
-// =============================================================================
-// 15-Agent Domain Configuration
-// =============================================================================
-
-const DOMAIN_CONFIGS: DomainConfig[] = [
- {
- name: 'queen',
- agentNumbers: [1],
- priority: 0,
- capabilities: ['coordination', 'planning', 'oversight', 'consensus'],
- description: 'Top-level swarm coordination and orchestration',
- },
- {
- name: 'security',
- agentNumbers: [2, 3, 4],
- priority: 1,
- capabilities: ['security-architecture', 'cve-remediation', 'security-testing', 'threat-modeling'],
- description: 'Security architecture, CVE fixes, and security testing',
- },
- {
- name: 'core',
- agentNumbers: [5, 6, 7, 8, 9],
- priority: 2,
- capabilities: ['ddd-design', 'type-modernization', 'memory-unification', 'swarm-coordination', 'mcp-optimization'],
- description: 'Core architecture, DDD, memory unification, and MCP optimization',
- },
- {
- name: 'integration',
- agentNumbers: [10, 11, 12],
- priority: 3,
- capabilities: ['agentic-flow-integration', 'cli-modernization', 'neural-integration', 'hooks-system'],
- description: 'agentic-flow integration, CLI modernization, and neural features',
- },
- {
- name: 'support',
- agentNumbers: [13, 14, 15],
- priority: 4,
- capabilities: ['tdd-testing', 'performance-benchmarking', 'deployment', 'release-management'],
- description: 'Testing, performance optimization, and deployment',
- },
-];
-
-export class UnifiedSwarmCoordinator extends EventEmitter implements IUnifiedSwarmCoordinator {
- private config: CoordinatorConfig;
- private state: CoordinatorState;
- private topologyManager: TopologyManager;
- private messageBus: MessageBus;
- private consensusEngine: ConsensusEngine;
- private agentPools: Map<AgentType, AgentPool> = new Map();
-
- // Domain-based tracking for 15-agent hierarchy
- private domainConfigs: Map<AgentDomain, DomainConfig> = new Map();
- private domainPools: Map<AgentDomain, AgentPool> = new Map();
- private agentDomainMap: Map<string, AgentDomain> = new Map();
- private taskAssignments: Map<string, TaskAssignment> = new Map();
- private domainTaskQueues: Map<AgentDomain, string[]> = new Map();
-
- // Performance tracking
- private startTime?: Date;
- private taskCounter: number = 0;
- private agentCounter: number = 0;
- private coordinationLatencies: number[] = [];
- private lastMetricsUpdate: Date = new Date();
-
- // Background intervals
- private heartbeatInterval?: NodeJS.Timeout;
- private healthCheckInterval?: NodeJS.Timeout;
- private metricsInterval?: NodeJS.Timeout;
-
- constructor(config: Partial<CoordinatorConfig> = {}) {
- super();
-
- this.config = this.createDefaultConfig(config);
- this.state = this.createInitialState();
-
- // Initialize components
- this.topologyManager = createTopologyManager(this.config.topology);
- this.messageBus = createMessageBus(this.config.messageBus);
- this.consensusEngine = createConsensusEngine(
- this.state.id.id,
- this.config.consensus.algorithm,
- this.config.consensus
- );
-
- // Initialize domain configurations
- this.initializeDomainConfigs();
-
- this.setupEventForwarding();
- }
-
- // =============================================================================
- // Domain Configuration Initialization
- // =============================================================================
-
- private initializeDomainConfigs(): void {
- for (const config of DOMAIN_CONFIGS) {
- this.domainConfigs.set(config.name, config);
- this.domainTaskQueues.set(config.name, []);
- }
- }
-
- async initialize(): Promise<void> {
- if (this.state.status !== 'initializing' && this.state.status !== 'stopped') {
- throw new Error(`Cannot initialize from status: ${this.state.status}`);
- }
-
- const startTime = performance.now();
-
- try {
- // Initialize all components in parallel
- await Promise.all([
- this.topologyManager.initialize(this.config.topology),
- this.messageBus.initialize(this.config.messageBus),
- this.consensusEngine.initialize(this.config.consensus),
- ]);
-
- // Initialize default agent pools
- await this.initializeAgentPools();
-
- // Start background processes
- this.startBackgroundProcesses();
-
- this.state.status = 'running';
- this.startTime = new Date();
- this.state.startedAt = this.startTime;
-
- const duration = performance.now() - startTime;
- this.recordCoordinationLatency(duration);
-
- this.emitEvent('swarm.initialized', {
- swarmId: this.state.id.id,
- initDurationMs: duration,
- });
-
- this.emitEvent('swarm.started', {
- swarmId: this.state.id.id,
- topology: this.config.topology.type,
- consensus: this.config.consensus.algorithm,
- });
- } catch (error) {
- this.state.status = 'failed';
- throw error;
- }
- }
-
- async shutdown(): Promise<void> {
- if (this.state.status === 'stopped') {
- return;
- }
-
- this.state.status = 'shutting_down';
-
- // Stop background processes
- this.stopBackgroundProcesses();
-
- // Shutdown all components including domain pools
- await Promise.all([
- this.messageBus.shutdown(),
- this.consensusEngine.shutdown(),
- ...Array.from(this.agentPools.values()).map(pool => pool.shutdown()),
- ...Array.from(this.domainPools.values()).map(pool => pool.shutdown()),
- ]);
-
- // Clear all tracking data
- this.state.agents.clear();
- this.state.tasks.clear();
- this.agentDomainMap.clear();
- this.taskAssignments.clear();
- for (const queue of this.domainTaskQueues.values()) {
- queue.length = 0;
- }
-
- this.state.status = 'stopped';
-
- this.emitEvent('swarm.stopped', {
- swarmId: this.state.id.id,
- totalTasks: this.state.metrics.totalTasks,
- completedTasks: this.state.metrics.completedTasks,
- });
- }
-
- async pause(): Promise<void> {
- if (this.state.status !== 'running') {
- return;
- }
-
- this.state.status = 'paused';
- this.stopBackgroundProcesses();
-
- this.emitEvent('swarm.paused', { swarmId: this.state.id.id });
- }
-
- async resume(): Promise<void> {
- if (this.state.status !== 'paused') {
- return;
- }
-
- this.startBackgroundProcesses();
- this.state.status = 'running';
-
- this.emitEvent('swarm.resumed', { swarmId: this.state.id.id });
- }
-
- // ===== AGENT MANAGEMENT =====
-
- async registerAgent(
- agentData: Omit<AgentState, 'id'>
- ): Promise<string> {
- const startTime = performance.now();
-
- if (this.state.agents.size >= this.config.maxAgents) {
- throw new Error(`Maximum agents (${this.config.maxAgents}) reached`);
- }
-
- this.agentCounter++;
- const agentId: AgentId = {
- id: `agent_${this.state.id.id}_${this.agentCounter}`,
- swarmId: this.state.id.id,
- type: agentData.type,
- instance: this.agentCounter,
- };
-
- const agent: AgentState = {
- ...agentData,
- id: agentId,
- lastHeartbeat: new Date(),
- connections: [],
- };
-
- // Add to state
- this.state.agents.set(agentId.id, agent);
-
- // Add to topology
- const role = this.determineTopologyRole(agent.type);
- await this.topologyManager.addNode(agentId.id, role);
-
- // Subscribe to message bus
- this.messageBus.subscribe(agentId.id, (message) => {
- this.handleAgentMessage(agentId.id, message);
- });
-
- // Add to consensus engine
- this.consensusEngine.addNode(agentId.id);
-
- const duration = performance.now() - startTime;
- this.recordCoordinationLatency(duration);
-
- this.emitEvent('agent.joined', {
- agentId: agentId.id,
- type: agent.type,
- registrationDurationMs: duration,
- });
-
- return agentId.id;
- }
-
- async unregisterAgent(agentId: string): Promise<void> {
- const agent = this.state.agents.get(agentId);
- if (!agent) {
- return;
- }
-
- // Cancel any assigned tasks
- if (agent.currentTask) {
- await this.cancelTask(agent.currentTask.id);
- }
-
- // Remove from components
- await this.topologyManager.removeNode(agentId);
- this.messageBus.unsubscribe(agentId);
- this.consensusEngine.removeNode(agentId);
-
- // Remove from state
- this.state.agents.delete(agentId);
-
- this.emitEvent('agent.left', { agentId });
- }
-
- getAgent(agentId: string): AgentState | undefined {
- return this.state.agents.get(agentId);
- }
-
- getAllAgents(): AgentState[] {
- return Array.from(this.state.agents.values());
- }
-
- getAgentsByType(type: AgentType): AgentState[] {
- return this.getAllAgents().filter(a => a.type === type);
- }
-
- getAvailableAgents(): AgentState[] {
- return this.getAllAgents().filter(a => a.status === 'idle');
- }
-
- // ===== TASK MANAGEMENT =====
-
- async submitTask(
- taskData: Omit<TaskDefinition, 'id' | 'status' | 'createdAt'>
- ): Promise<string> {
- const startTime = performance.now();
-
- if (this.state.tasks.size >= this.config.maxTasks) {
- throw new Error(`Maximum tasks (${this.config.maxTasks}) reached`);
- }
-
- this.taskCounter++;
- const taskId: TaskId = {
- id: `task_${this.state.id.id}_${this.taskCounter}`,
- swarmId: this.state.id.id,
- sequence: this.taskCounter,
- priority: taskData.priority,
- };
-
- const task: TaskDefinition = {
- ...taskData,
- id: taskId,
- status: 'created',
- createdAt: new Date(),
- };
-
- this.state.tasks.set(taskId.id, task);
- this.state.metrics.totalTasks++;
-
- // Assign to available agent
- const assignedAgent = await this.assignTask(task);
-
- const duration = performance.now() - startTime;
- this.recordCoordinationLatency(duration);
-
- this.emitEvent('task.created', {
- taskId: taskId.id,
- type: task.type,
- priority: task.priority,
- assignedTo: assignedAgent?.id.id,
- assignmentDurationMs: duration,
- });
-
- return taskId.id;
- }
-
- async cancelTask(taskId: string): Promise<void> {
- const task = this.state.tasks.get(taskId);
- if (!task) {
- return;
- }
-
- // Notify assigned agent
- if (task.assignedTo) {
- await this.messageBus.send({
- type: 'task_fail',
- from: this.state.id.id,
- to: task.assignedTo.id,
- payload: { taskId, reason: 'cancelled' },
- priority: 'high',
- requiresAck: true,
- ttlMs: SWARM_CONSTANTS.DEFAULT_MESSAGE_TTL_MS,
- });
-
- // Release agent
- const agent = this.state.agents.get(task.assignedTo.id);
- if (agent) {
- agent.status = 'idle';
- agent.currentTask = undefined;
- }
- }
-
- task.status = 'cancelled';
-
- this.emitEvent('task.failed', {
- taskId,
- reason: 'cancelled',
- });
- }
-
- getTask(taskId: string): TaskDefinition | undefined {
- return this.state.tasks.get(taskId);
- }
-
- getAllTasks(): TaskDefinition[] {
- return Array.from(this.state.tasks.values());
- }
-
- getTasksByStatus(status: TaskStatus): TaskDefinition[] {
- return this.getAllTasks().filter(t => t.status === status);
- }
-
- // ===== COORDINATION =====
-
- async proposeConsensus(value: unknown): Promise<ConsensusResult> {
- const startTime = performance.now();
-
- const proposal = await this.consensusEngine.propose(value, this.state.id.id);
- const result = await this.consensusEngine.awaitConsensus(proposal.id);
-
- const duration = performance.now() - startTime;
- this.recordCoordinationLatency(duration);
-
- if (result.approved) {
- this.emitEvent('consensus.achieved', {
- proposalId: proposal.id,
- approvalRate: result.approvalRate,
- durationMs: duration,
- });
- } else {
- this.emitEvent('consensus.failed', {
- proposalId: proposal.id,
- approvalRate: result.approvalRate,
- reason: 'threshold_not_met',
- });
- }
-
- return result;
- }
-
- async broadcastMessage(
- payload: unknown,
- priority: Message['priority'] = 'normal'
- ): Promise<void> {
- await this.messageBus.broadcast({
- type: 'broadcast',
- from: this.state.id.id,
- payload,
- priority,
- requiresAck: false,
- ttlMs: SWARM_CONSTANTS.DEFAULT_MESSAGE_TTL_MS,
- });
- }
-
- // ===== MONITORING =====
-
- getState(): CoordinatorState {
- return {
- ...this.state,
- agents: new Map(this.state.agents),
- tasks: new Map(this.state.tasks),
- topology: this.topologyManager.getState(),
- };
- }
-
- getMetrics(): CoordinatorMetrics {
- return { ...this.state.metrics };
- }
-
- getPerformanceReport(): PerformanceReport {
- const recentLatencies = this.coordinationLatencies.slice(-100);
- const sortedLatencies = [...recentLatencies].sort((a, b) => a - b);
-
- return {
- timestamp: new Date(),
- window: 60000, // 1 minute
- coordinationLatencyP50: sortedLatencies[Math.floor(sortedLatencies.length * 0.5)] || 0,
- coordinationLatencyP99: sortedLatencies[Math.floor(sortedLatencies.length * 0.99)] || 0,
- messagesPerSecond: this.messageBus.getStats().messagesPerSecond,
- taskThroughput: this.calculateTaskThroughput(),
- agentUtilization: this.calculateAgentUtilization(),
- consensusSuccessRate: this.state.metrics.consensusSuccessRate,
- };
- }
-
- // ===== PRIVATE METHODS =====
-
- private createDefaultConfig(config: Partial<CoordinatorConfig>): CoordinatorConfig {
- return {
- topology: {
- type: config.topology?.type ?? 'mesh',
- maxAgents: config.topology?.maxAgents ?? SWARM_CONSTANTS.DEFAULT_MAX_AGENTS,
- replicationFactor: config.topology?.replicationFactor ?? 2,
- partitionStrategy: config.topology?.partitionStrategy ?? 'hash',
- failoverEnabled: config.topology?.failoverEnabled ?? true,
- autoRebalance: config.topology?.autoRebalance ?? true,
- },
- consensus: {
- algorithm: config.consensus?.algorithm ?? 'raft',
- threshold: config.consensus?.threshold ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_THRESHOLD,
- timeoutMs: config.consensus?.timeoutMs ?? SWARM_CONSTANTS.DEFAULT_CONSENSUS_TIMEOUT_MS,
- maxRounds: config.consensus?.maxRounds ?? 10,
- requireQuorum: config.consensus?.requireQuorum ?? true,
- },
- messageBus: {
- maxQueueSize: config.messageBus?.maxQueueSize ?? SWARM_CONSTANTS.MAX_QUEUE_SIZE,
- processingIntervalMs: config.messageBus?.processingIntervalMs ?? 10,
- ackTimeoutMs: config.messageBus?.ackTimeoutMs ?? 5000,
- retryAttempts: config.messageBus?.retryAttempts ?? SWARM_CONSTANTS.MAX_RETRIES,
- enablePersistence: config.messageBus?.enablePersistence ?? false,
- compressionEnabled: config.messageBus?.compressionEnabled ?? false,
- },
- maxAgents: config.maxAgents ?? SWARM_CONSTANTS.DEFAULT_MAX_AGENTS,
- maxTasks: config.maxTasks ?? SWARM_CONSTANTS.DEFAULT_MAX_TASKS,
- heartbeatIntervalMs: config.heartbeatIntervalMs ?? SWARM_CONSTANTS.DEFAULT_HEARTBEAT_INTERVAL_MS,
- healthCheckIntervalMs: config.healthCheckIntervalMs ?? SWARM_CONSTANTS.DEFAULT_HEALTH_CHECK_INTERVAL_MS,
- taskTimeoutMs: config.taskTimeoutMs ?? SWARM_CONSTANTS.DEFAULT_TASK_TIMEOUT_MS,
- autoScaling: config.autoScaling ?? true,
- autoRecovery: config.autoRecovery ?? true,
- };
- }
-
- private createInitialState(): CoordinatorState {
- const swarmId: SwarmId = {
- id: `swarm_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
- namespace: 'default',
- version: '3.0.0',
- createdAt: new Date(),
- };
-
- return {
- id: swarmId,
- status: 'initializing',
- topology: {
- type: 'mesh',
- nodes: [],
- edges: [],
- partitions: [],
- },
- agents: new Map(),
- tasks: new Map(),
- metrics: {
- uptime: 0,
- activeAgents: 0,
- totalTasks: 0,
- completedTasks: 0,
- failedTasks: 0,
- avgTaskDurationMs: 0,
- messagesPerSecond: 0,
- consensusSuccessRate: 1.0,
- coordinationLatencyMs: 0,
- memoryUsageBytes: 0,
- },
- };
- }
-
- private async initializeAgentPools(): Promise<void> {
- // Initialize type-based pools (legacy support)
- const defaultPoolTypes: AgentType[] = ['worker', 'coordinator', 'researcher', 'coder'];
-
- for (const type of defaultPoolTypes) {
- const pool = createAgentPool({
- name: `${type}-pool`,
- type,
- minSize: 0,
- maxSize: Math.floor(this.config.maxAgents / defaultPoolTypes.length),
- scaleUpThreshold: 0.8,
- scaleDownThreshold: 0.2,
- cooldownMs: 30000,
- healthCheckIntervalMs: this.config.healthCheckIntervalMs,
- });
-
- await pool.initialize();
- this.agentPools.set(type, pool);
- }
-
- // Initialize domain-based pools for 15-agent hierarchy
- await this.initializeDomainPools();
- }
-
- private async initializeDomainPools(): Promise<void> {
- for (const [domain, config] of this.domainConfigs) {
- const agentType = this.domainToAgentType(domain);
- const pool = createAgentPool({
- name: `${domain}-domain-pool`,
- type: agentType,
- minSize: 0,
- maxSize: config.agentNumbers.length,
- scaleUpThreshold: 0.8,
- scaleDownThreshold: 0.2,
- cooldownMs: 30000,
- healthCheckIntervalMs: this.config.healthCheckIntervalMs,
- });
-
- await pool.initialize();
- this.domainPools.set(domain, pool);
- }
- }
-
- private domainToAgentType(domain: AgentDomain): AgentType {
- switch (domain) {
- case 'queen':
- return 'queen';
- case 'security':
- return 'specialist';
- case 'core':
- return 'architect';
- case 'integration':
- return 'coder';
- case 'support':
- return 'tester';
- default:
- return 'worker';
- }
- }
-
- private setupEventForwarding(): void {
- // Forward topology events
- this.topologyManager.on('node.added', (data) => {
- this.emitEvent('topology.updated', { action: 'node_added', ...data });
- });
-
- this.topologyManager.on('node.removed', (data) => {
- this.emitEvent('topology.updated', { action: 'node_removed', ...data });
- });
-
- this.topologyManager.on('topology.rebalanced', (data) => {
- this.emitEvent('topology.rebalanced', data);
- });
-
- // Forward consensus events
- this.consensusEngine.on('consensus.achieved', (data) => {
- this.state.metrics.consensusSuccessRate =
- (this.state.metrics.consensusSuccessRate * 0.9) + (data.approved ? 0.1 : 0);
- });
-
- // Forward message bus events
- this.messageBus.on('message.delivered', (data) => {
- this.emitEvent('message.received', data);
- });
- }
-
- private startBackgroundProcesses(): void {
- // Heartbeat monitoring
- this.heartbeatInterval = setInterval(() => {
- this.checkHeartbeats();
- }, this.config.heartbeatIntervalMs);
-
- // Health checks
- this.healthCheckInterval = setInterval(() => {
- this.performHealthChecks();
- }, this.config.healthCheckIntervalMs);
-
- // Metrics collection
- this.metricsInterval = setInterval(() => {
- this.updateMetrics();
- }, 1000);
- }
-
- private stopBackgroundProcesses(): void {
- if (this.heartbeatInterval) {
- clearInterval(this.heartbeatInterval);
- this.heartbeatInterval = undefined;
- }
- if (this.healthCheckInterval) {
- clearInterval(this.healthCheckInterval);
- this.healthCheckInterval = undefined;
- }
- if (this.metricsInterval) {
- clearInterval(this.metricsInterval);
- this.metricsInterval = undefined;
- }
- }
-
- private async assignTask(task: TaskDefinition): Promise<AgentState | undefined> {
- // Find best available agent
- const availableAgents = this.getAvailableAgents();
- if (availableAgents.length === 0) {
- task.status = 'queued';
- return undefined;
- }
-
- // Score agents based on capabilities and workload
- const scoredAgents = availableAgents.map(agent => ({
- agent,
- score: this.scoreAgentForTask(agent, task),
- })).sort((a, b) => b.score - a.score);
-
- const bestAgent = scoredAgents[0]?.agent;
- if (!bestAgent) {
- task.status = 'queued';
- return undefined;
- }
-
- // Assign task
- task.assignedTo = bestAgent.id;
- task.status = 'assigned';
- bestAgent.status = 'busy';
- bestAgent.currentTask = task.id;
-
- // Notify agent via message bus
- await this.messageBus.send({
- type: 'task_assign',
- from: this.state.id.id,
- to: bestAgent.id.id,
- payload: { task },
- priority: this.mapTaskPriorityToMessagePriority(task.priority),
- requiresAck: true,
- ttlMs: this.config.taskTimeoutMs,
- });
-
- this.emitEvent('task.assigned', {
- taskId: task.id.id,
- agentId: bestAgent.id.id,
- });
-
- return bestAgent;
- }
-
- private scoreAgentForTask(agent: AgentState, task: TaskDefinition): number {
- let score = 100;
-
- // Type matching
- const typeScores: Record<TaskType, AgentType[]> = {
- research: ['researcher'],
- analysis: ['analyst', 'researcher'],
- coding: ['coder'],
- testing: ['tester'],
- review: ['reviewer'],
- documentation: ['documenter'],
- coordination: ['coordinator', 'queen'],
- consensus: ['coordinator', 'queen'],
- custom: ['worker'],
- };
-
- const preferredTypes = typeScores[task.type] || ['worker'];
- if (preferredTypes.includes(agent.type)) {
- score += 50;
- }
-
- // Workload adjustment
- score -= agent.workload * 20;
-
- // Health adjustment
- score *= agent.health;
-
- // Metrics-based adjustment
- score += agent.metrics.successRate * 10;
- score -= (agent.metrics.averageExecutionTime / 60000) * 5;
-
- return score;
- }
-
- private mapTaskPriorityToMessagePriority(
- priority: TaskPriority
- ): Message['priority'] {
- const mapping: Record<TaskPriority, Message['priority']> = {
- critical: 'urgent',
- high: 'high',
- normal: 'normal',
- low: 'low',
- background: 'low',
- };
- return mapping[priority];
- }
-
- private determineTopologyRole(
- agentType: AgentType
- ): 'queen' | 'worker' | 'coordinator' | 'peer' {
- switch (agentType) {
- case 'queen':
- return 'queen';
- case 'coordinator':
- return 'coordinator';
- default:
- return this.config.topology.type === 'mesh' ? 'peer' : 'worker';
- }
- }
-
- private handleAgentMessage(agentId: string, message: Message): void {
- const agent = this.state.agents.get(agentId);
- if (!agent) return;
-
- // Update heartbeat
- agent.lastHeartbeat = new Date();
- agent.metrics.messagesProcessed++;
-
- switch (message.type) {
- case 'task_complete':
- this.handleTaskComplete(agentId, message.payload as { taskId: string; result: unknown });
- break;
- case 'task_fail':
- this.handleTaskFail(agentId, message.payload as { taskId: string; error: string });
- break;
- case 'heartbeat':
- this.handleHeartbeat(agentId, message.payload as Record<string, unknown>);
- break;
- case 'status_update':
- this.handleStatusUpdate(agentId, message.payload as Partial<AgentState>);
- break;
- }
- }
-
- private handleTaskComplete(agentId: string, data: { taskId: string; result: unknown }): void {
- const task = this.state.tasks.get(data.taskId);
- const agent = this.state.agents.get(agentId);
-
- if (task && agent) {
- task.status = 'completed';
- task.output = data.result;
- task.completedAt = new Date();
-
- agent.status = 'idle';
- agent.currentTask = undefined;
- agent.metrics.tasksCompleted++;
-
- this.state.metrics.completedTasks++;
-
- // Update average task duration
- if (task.startedAt) {
- const duration = task.completedAt.getTime() - task.startedAt.getTime();
- this.state.metrics.avgTaskDurationMs =
- (this.state.metrics.avgTaskDurationMs * 0.9) + (duration * 0.1);
- }
-
- this.emitEvent('task.completed', {
- taskId: data.taskId,
- agentId,
- result: data.result,
- });
- }
- }
-
- private handleTaskFail(agentId: string, data: { taskId: string; error: string }): void {
- const task = this.state.tasks.get(data.taskId);
- const agent = this.state.agents.get(agentId);
-
- if (task && agent) {
- // Check retry
- if (task.retries < task.maxRetries) {
- task.retries++;
- task.status = 'queued';
- task.assignedTo = undefined;
- agent.currentTask = undefined;
- agent.status = 'idle';
-
- // Re-assign
- this.assignTask(task);
- } else {
- task.status = 'failed';
- agent.status = 'idle';
- agent.currentTask = undefined;
- agent.metrics.tasksFailed++;
-
- this.state.metrics.failedTasks++;
-
- this.emitEvent('task.failed', {
- taskId: data.taskId,
- agentId,
- error: data.error,
- });
- }
- }
- }
-
- private handleHeartbeat(agentId: string, data: Record<string, unknown>): void {
- const agent = this.state.agents.get(agentId);
- if (agent) {
- agent.lastHeartbeat = new Date();
- if (data.metrics) {
- agent.metrics = { ...agent.metrics, ...(data.metrics as Partial<typeof agent.metrics>) };
- }
-
- this.emitEvent('agent.heartbeat', { agentId });
- }
- }
-
- private handleStatusUpdate(agentId: string, data: Partial<AgentState>): void {
- const agent = this.state.agents.get(agentId);
- if (agent) {
- if (data.status) agent.status = data.status;
- if (data.health !== undefined) agent.health = data.health;
- if (data.workload !== undefined) agent.workload = data.workload;
-
- this.emitEvent('agent.status_changed', { agentId, status: agent.status });
- }
- }
-
- private checkHeartbeats(): void {
- const now = Date.now();
- const timeout = this.config.heartbeatIntervalMs * 3;
-
- for (const [agentId, agent] of this.state.agents) {
- const timeSinceHeartbeat = now - agent.lastHeartbeat.getTime();
-
- if (timeSinceHeartbeat > timeout && agent.status !== 'terminated') {
- agent.status = 'error';
- agent.health = Math.max(0, agent.health - 0.2);
-
- // Auto-recovery
- if (this.config.autoRecovery && agent.health <= 0.2) {
- this.recoverAgent(agentId);
- }
- }
- }
- }
-
- private async recoverAgent(agentId: string): Promise<void> {
- const agent = this.state.agents.get(agentId);
- if (!agent) return;
-
- // Reassign any tasks
- if (agent.currentTask) {
- const task = this.state.tasks.get(agent.currentTask.id);
- if (task) {
- task.status = 'queued';
- task.assignedTo = undefined;
- await this.assignTask(task);
- }
- }
-
- // Reset agent
- agent.status = 'idle';
- agent.currentTask = undefined;
- agent.health = 1.0;
- agent.lastHeartbeat = new Date();
- }
-
- private performHealthChecks(): void {
- const activeAgents = this.getAllAgents().filter(
- a => a.status === 'idle' || a.status === 'busy'
- );
-
- this.state.metrics.activeAgents = activeAgents.length;
-
- // Update topology state
- this.state.topology = this.topologyManager.getState();
- }
-
- private updateMetrics(): void {
- const now = new Date();
- const uptime = this.startTime
- ? (now.getTime() - this.startTime.getTime()) / 1000
- : 0;
-
- this.state.metrics.uptime = uptime;
- this.state.metrics.messagesPerSecond = this.messageBus.getStats().messagesPerSecond;
-
- // Calculate coordination latency
- if (this.coordinationLatencies.length > 0) {
- const recent = this.coordinationLatencies.slice(-50);
- this.state.metrics.coordinationLatencyMs =
- recent.reduce((a, b) => a + b, 0) / recent.length;
- }
-
- // Memory usage (approximation)
- this.state.metrics.memoryUsageBytes =
- (this.state.agents.size * 2000) +
- (this.state.tasks.size * 1000) +
- (this.messageBus.getQueueDepth() * 500);
-
- this.lastMetricsUpdate = now;
- }
-
- private recordCoordinationLatency(latencyMs: number): void {
- this.coordinationLatencies.push(latencyMs);
- if (this.coordinationLatencies.length > 1000) {
- this.coordinationLatencies.shift();
- }
- }
-
- private calculateTaskThroughput(): number {
- if (!this.startTime) return 0;
- const uptimeSeconds = (Date.now() - this.startTime.getTime()) / 1000;
- return uptimeSeconds > 0
- ? this.state.metrics.completedTasks / uptimeSeconds
- : 0;
- }
-
- private calculateAgentUtilization(): number {
- const agents = this.getAllAgents();
- if (agents.length === 0) return 0;
- const busyAgents = agents.filter(a => a.status === 'busy').length;
- return busyAgents / agents.length;
- }
-
- private emitEvent(type: SwarmEventType, data: Record<string, unknown>): void {
- const event: SwarmEvent = {
- id: `event_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`,
- type,
- source: this.state.id.id,
- timestamp: new Date(),
- data,
- };
-
- this.emit(type, event);
- this.emit('event', event);
- }
-
- // ===== UTILITY METHODS =====
-
- getTopology(): TopologyType {
- return this.config.topology.type;
- }
-
- setTopology(type: TopologyType): void {
- this.config.topology.type = type;
- }
-
- getConsensusAlgorithm(): string {
- return this.config.consensus.algorithm;
- }
-
- isHealthy(): boolean {
- return (
- this.state.status === 'running' &&
- this.state.metrics.activeAgents > 0 &&
- this.state.metrics.coordinationLatencyMs < SWARM_CONSTANTS.COORDINATION_LATENCY_TARGET_MS * 2
- );
- }
-
- getAgentPool(type: AgentType): AgentPool | undefined {
- return this.agentPools.get(type);
- }
-
- // =============================================================================
- // DOMAIN-BASED TASK ROUTING (15-Agent Hierarchy Support)
- // =============================================================================
-
- /**
- * Assign a task to a specific domain
- * Routes the task to the most suitable agent within that domain
- */
- async assignTaskToDomain(taskId: string, domain: AgentDomain): Promise<string | undefined> {
- const startTime = performance.now();
- const task = this.state.tasks.get(taskId);
-
- if (!task) {
- throw new Error(`Task ${taskId} not found`);
- }
-
- const pool = this.domainPools.get(domain);
- if (!pool) {
- throw new Error(`Domain pool ${domain} not found`);
- }
-
- // Try to acquire an agent from the domain pool
- const agent = await pool.acquire();
- if (!agent) {
- // Add to domain queue if no agents available
- const queue = this.domainTaskQueues.get(domain) || [];
- queue.push(taskId);
- this.domainTaskQueues.set(domain, queue);
- task.status = 'queued';
-
- this.emitEvent('task.queued', {
- taskId,
- domain,
- queuePosition: queue.length,
- reason: 'no_available_agents'
- });
-
- return undefined;
- }
-
- // Update task
- task.status = 'assigned';
- task.assignedTo = agent.id;
- task.startedAt = new Date();
-
- // Track assignment
- const assignment: TaskAssignment = {
- taskId,
- domain,
- agentId: agent.id.id,
- priority: task.priority,
- assignedAt: new Date(),
- };
- this.taskAssignments.set(taskId, assignment);
-
- // Notify agent via message bus
- await this.messageBus.send({
- type: 'task_assign',
- from: this.state.id.id,
- to: agent.id.id,
- payload: { taskId, task, domain },
- priority: this.mapTaskPriorityToMessagePriority(task.priority),
- requiresAck: true,
- ttlMs: this.config.taskTimeoutMs,
- });
-
- const duration = performance.now() - startTime;
- this.recordCoordinationLatency(duration);
-
- this.emitEvent('task.assigned', {
- taskId,
- agentId: agent.id.id,
- domain,
- assignmentDurationMs: duration,
- });
-
- return agent.id.id;
- }
-
- /**
- * Get all agents belonging to a specific domain
- */
- getAgentsByDomain(domain: AgentDomain): AgentState[] {
- const agents: AgentState[] = [];
- for (const [agentId, agentDomain] of this.agentDomainMap) {
- if (agentDomain === domain) {
- const agent = this.state.agents.get(agentId);
- if (agent) {
- agents.push(agent);
- }
- }
- }
- return agents;
- }
-
- /**
- * Execute multiple tasks in parallel across different domains
- * This is the key method for achieving >85% agent utilization
- */
- async executeParallel(tasks: Array<{
- task: Omit<TaskDefinition, 'id' | 'status' | 'createdAt'>;
- domain: AgentDomain;
- }>): Promise<ParallelExecutionResult[]> {
- const startTime = performance.now();
- const executionPromises: Promise<ParallelExecutionResult>[] = [];
-
- // Submit all tasks first
- const taskIds: Array<{ taskId: string; domain: AgentDomain }> = [];
- for (const { task, domain } of tasks) {
- const taskId = await this.submitTask(task);
- taskIds.push({ taskId, domain });
- }
-
- // Execute all tasks in parallel across domains
- for (const { taskId, domain } of taskIds) {
- const promise = this.executeTaskInDomain(taskId, domain);
- executionPromises.push(promise);
- }
-
- // Wait for all tasks to complete (with individual error handling)
- const settledResults = await Promise.allSettled(executionPromises);
-
- const results: ParallelExecutionResult[] = [];
- for (let i = 0; i < settledResults.length; i++) {
- const result = settledResults[i];
- const { taskId, domain } = taskIds[i];
-
- if (result.status === 'fulfilled') {
- results.push(result.value);
- } else {
- results.push({
- taskId,
- domain,
- success: false,
- error: result.reason instanceof Error ? result.reason : new Error(String(result.reason)),
- durationMs: performance.now() - startTime,
- });
- }
- }
-
- this.emitEvent('parallel.execution.completed', {
- totalTasks: tasks.length,
- successful: results.filter(r => r.success).length,
- failed: results.filter(r => !r.success).length,
- totalDurationMs: performance.now() - startTime,
- });
-
- return results;
- }
-
- private async executeTaskInDomain(taskId: string, domain: AgentDomain): Promise<ParallelExecutionResult> {
- const startTime = performance.now();
-
- try {
- // Assign to domain
- const agentId = await this.assignTaskToDomain(taskId, domain);
- if (!agentId) {
- // Task was queued, wait for it to be assigned and complete
- return await this.waitForQueuedTask(taskId, domain, startTime);
- }
-
- // Wait for completion
- const result = await this.waitForTaskCompletion(taskId, this.config.taskTimeoutMs);
-
- return {
- taskId,
- domain,
- success: result.status === 'completed',
- result: result.output,
- durationMs: performance.now() - startTime,
- };
- } catch (error) {
- return {
- taskId,
- domain,
- success: false,
- error: error instanceof Error ? error : new Error(String(error)),
- durationMs: performance.now() - startTime,
- };
- }
- }
-
- private async waitForQueuedTask(
- taskId: string,
- domain: AgentDomain,
- startTime: number
- ): Promise<ParallelExecutionResult> {
- return new Promise((resolve) => {
- const checkInterval = setInterval(() => {
- const task = this.state.tasks.get(taskId);
- if (!task) {
- clearInterval(checkInterval);
- resolve({
- taskId,
- domain,
- success: false,
- error: new Error(`Task ${taskId} not found`),
- durationMs: performance.now() - startTime,
- });
- return;
- }
-
- if (task.status === 'completed') {
- clearInterval(checkInterval);
- resolve({
- taskId,
- domain,
- success: true,
- result: task.output,
- durationMs: performance.now() - startTime,
- });
- } else if (task.status === 'failed' || task.status === 'cancelled' || task.status === 'timeout') {
- clearInterval(checkInterval);
- resolve({
- taskId,
- domain,
- success: false,
- error: new Error(`Task ${task.status}`),
- durationMs: performance.now() - startTime,
- });
- }
- }, 100);
-
- // Timeout after configured duration
- setTimeout(() => {
- clearInterval(checkInterval);
- const task = this.state.tasks.get(taskId);
- if (task && task.status !== 'completed') {
- task.status = 'timeout';
- }
- resolve({
- taskId,
- domain,
- success: false,
- error: new Error('Task timed out'),
- durationMs: performance.now() - startTime,
- });
- }, this.config.taskTimeoutMs);
- });
- }
-
- private async waitForTaskCompletion(taskId: string, timeoutMs: number): Promise<TaskDefinition> {
- return new Promise((resolve, reject) => {
- const checkInterval = setInterval(() => {
- const task = this.state.tasks.get(taskId);
- if (!task) {
- clearInterval(checkInterval);
- reject(new Error(`Task ${taskId} not found`));
- return;
- }
-
- if (task.status === 'completed' || task.status === 'failed' || task.status === 'cancelled') {
- clearInterval(checkInterval);
- resolve(task);
- }
- }, 100);
-
- setTimeout(() => {
- clearInterval(checkInterval);
- const task = this.state.tasks.get(taskId);
- if (task) {
- task.status = 'timeout';
- task.completedAt = new Date();
- resolve(task);
- } else {
- reject(new Error(`Task ${taskId} timed out`));
- }
- }, timeoutMs);
- });
- }
-
- /**
- * Get the current status of all domains
- */
- getStatus(): {
- swarmId: SwarmId;
- status: SwarmStatus;
- topology: TopologyType;
- domains: DomainStatus[];
- metrics: CoordinatorMetrics;
- } {
- const domains: DomainStatus[] = [];
-
- for (const [domain, config] of this.domainConfigs) {
- const pool = this.domainPools.get(domain);
- const stats = pool?.getPoolStats();
- const queue = this.domainTaskQueues.get(domain) || [];
-
- const completedTasks = Array.from(this.taskAssignments.values())
- .filter(a => a.domain === domain)
- .map(a => this.state.tasks.get(a.taskId))
- .filter(t => t?.status === 'completed')
- .length;
-
- domains.push({
- name: domain,
- agentCount: stats?.total ?? 0,
- availableAgents: stats?.available ?? 0,
- busyAgents: stats?.busy ?? 0,
- tasksQueued: queue.length,
- tasksCompleted: completedTasks,
- });
- }
-
- return {
- swarmId: this.state.id,
- status: this.state.status,
- topology: this.config.topology.type,
- domains,
- metrics: this.getMetrics(),
- };
- }
-
- /**
- * Register an agent and automatically assign it to the appropriate domain
- * based on its agent number (1-15)
- */
- async registerAgentWithDomain(
- agentData: Omit<AgentState, 'id'>,
- agentNumber: number
- ): Promise<{ agentId: string; domain: AgentDomain }> {
- // First register the agent normally
- const agentId = await this.registerAgent(agentData);
-
- // Determine domain based on agent number
- const domain = this.getAgentDomain(agentNumber);
-
- // Add to domain tracking
- this.agentDomainMap.set(agentId, domain);
-
- // Add to domain pool
- const pool = this.domainPools.get(domain);
- const agent = this.state.agents.get(agentId);
- if (pool && agent) {
- await pool.add(agent);
- }
-
- this.emitEvent('agent.domain_assigned', {
- agentId,
- agentNumber,
- domain,
- });
-
- return { agentId, domain };
- }
-
- /**
- * Get the domain for a given agent number (1-15)
- */
- getAgentDomain(agentNumber: number): AgentDomain {
- for (const [domain, config] of this.domainConfigs) {
- if (config.agentNumbers.includes(agentNumber)) {
- return domain;
- }
- }
- return 'core'; // Default to core domain
- }
-
- /**
- * Spawn the full 15-agent hierarchy
- * Returns a map of agent numbers to their IDs and domains
- */
- async spawnFullHierarchy(): Promise<Map<number, { agentId: string; domain: AgentDomain }>> {
- const results = new Map<number, { agentId: string; domain: AgentDomain }>();
-
- for (const [domain, config] of this.domainConfigs) {
- for (const agentNumber of config.agentNumbers) {
- const agentType = this.domainToAgentType(domain);
-
- const agentData: Omit<AgentState, 'id'> = {
- name: `${domain}-agent-${agentNumber}`,
- type: agentType,
- status: 'idle',
- capabilities: this.createDomainCapabilities(domain),
- metrics: this.createDefaultAgentMetrics(),
- workload: 0,
- health: 1.0,
- lastHeartbeat: new Date(),
- topologyRole: domain === 'queen' ? 'queen' : 'worker',
- connections: [],
- };
-
- const result = await this.registerAgentWithDomain(agentData, agentNumber);
- results.set(agentNumber, result);
- }
- }
-
- this.emitEvent('hierarchy.spawned', {
- totalAgents: results.size,
- domains: Array.from(this.domainConfigs.keys()),
- });
-
- return results;
- }
-
- private createDomainCapabilities(domain: AgentDomain): AgentCapabilities {
- const domainConfig = this.domainConfigs.get(domain);
- const capabilities = domainConfig?.capabilities || [];
-
- return {
- codeGeneration: domain === 'core' || domain === 'integration',
- codeReview: domain === 'security' || domain === 'core',
- testing: domain === 'support' || domain === 'security',
- documentation: true,
- research: true,
- analysis: true,
- coordination: domain === 'queen',
- languages: ['typescript', 'javascript', 'python'],
- frameworks: ['node', 'react', 'vitest'],
- domains: capabilities,
- tools: ['git', 'npm', 'editor', 'claude'],
- maxConcurrentTasks: domain === 'queen' ? 1 : 3,
- maxMemoryUsage: 512 * 1024 * 1024,
- maxExecutionTime: SWARM_CONSTANTS.DEFAULT_TASK_TIMEOUT_MS,
- reliability: 0.95,
- speed: 1.0,
- quality: 0.9,
- };
- }
-
- private createDefaultAgentMetrics(): AgentMetrics {
- return {
- tasksCompleted: 0,
- tasksFailed: 0,
- averageExecutionTime: 0,
- successRate: 1.0,
- cpuUsage: 0,
- memoryUsage: 0,
- messagesProcessed: 0,
- lastActivity: new Date(),
- responseTime: 0,
- health: 1.0,
- };
- }
-
- /**
- * Get the domain pool for a specific domain
- */
- getDomainPool(domain: AgentDomain): AgentPool | undefined {
- return this.domainPools.get(domain);
- }
-
- /**
- * Get all domain configurations
- */
- getDomainConfigs(): Map<AgentDomain, DomainConfig> {
- return new Map(this.domainConfigs);
- }
-
- /**
- * Release an agent back to its domain pool after task completion
- */
- async releaseAgentToDomain(agentId: string): Promise<void> {
- const domain = this.agentDomainMap.get(agentId);
- if (!domain) return;
-
- const pool = this.domainPools.get(domain);
- if (pool) {
- await pool.release(agentId);
- }
-
- // Check if there are queued tasks for this domain
- const queue = this.domainTaskQueues.get(domain) || [];
- if (queue.length > 0) {
- const nextTaskId = queue.shift()!;
- this.domainTaskQueues.set(domain, queue);
- await this.assignTaskToDomain(nextTaskId, domain);
- }
- }
-}
-
-export function createUnifiedSwarmCoordinator(
- config?: Partial<CoordinatorConfig>
-): UnifiedSwarmCoordinator {
- return new UnifiedSwarmCoordinator(config);
-}