@sparkleideas/integration 3.5.2-patch.1

package/README.md

@@ -0,0 +1,270 @@
+# @claude-flow/integration
+
+[![npm version](https://img.shields.io/npm/v/@claude-flow/integration.svg)](https://www.npmjs.com/package/@claude-flow/integration)
+[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/integration.svg)](https://www.npmjs.com/package/@claude-flow/integration)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![ADR-001](https://img.shields.io/badge/ADR--001-Compliant-green.svg)](https://github.com/ruvnet/claude-flow)
+
+> Deep agentic-flow@alpha integration module for Claude Flow V3 - ADR-001 compliance, code deduplication, SONA adapter, and Flash Attention coordinator.
+
+## Features
+
+- **ADR-001 Compliance** - Eliminates 10,000+ duplicate lines by building on agentic-flow
+- **SONA Adapter** - Seamless integration with SONA learning systems
+- **Flash Attention** - 2.49x-7.47x speedup with attention coordination
+- **SDK Bridge** - Version negotiation and API compatibility layer
+- **Feature Flags** - Dynamic feature enabling/disabling
+- **Runtime Detection** - Auto-select optimal runtime (NAPI, WASM, JS)
+- **Graceful Fallback** - Works with or without agentic-flow installed
+
+## Installation
+
+```bash
+npm install @claude-flow/integration
+
+# Optional: Install agentic-flow for optimal performance
+npm install agentic-flow@alpha
+```
+
+## Quick Start
+
+```typescript
+import { AgenticFlowBridge, createAgenticFlowBridge } from '@claude-flow/integration';
+
+// Create and initialize bridge
+const bridge = await createAgenticFlowBridge({
+  features: {
+    enableSONA: true,
+    enableFlashAttention: true,
+    enableAgentDB: true
+  }
+});
+
+// Check if agentic-flow is connected
+if (bridge.isAgenticFlowConnected()) {
+  console.log('Using optimized agentic-flow implementation');
+} else {
+  console.log('Using local fallback implementation');
+}
+
+// Get SONA adapter
+const sona = await bridge.getSONAAdapter();
+await sona.setMode('balanced');
+
+// Get Attention coordinator
+const attention = await bridge.getAttentionCoordinator();
+const result = await attention.compute({ query, key, value });
+```
+
+## API Reference
+
+### AgenticFlowBridge
+
+```typescript
+import { AgenticFlowBridge } from '@claude-flow/integration';
+
+const bridge = new AgenticFlowBridge({
+  sona: {
+    mode: 'balanced',
+    learningRate: 0.001,
+    similarityThreshold: 0.7
+  },
+  attention: {
+    mechanism: 'flash',
+    numHeads: 8,
+    flashOptLevel: 2
+  },
+  agentdb: {
+    dimension: 1536,
+    indexType: 'hnsw',
+    metric: 'cosine'
+  },
+  features: {
+    enableSONA: true,
+    enableFlashAttention: true,
+    enableAgentDB: true
+  },
+  runtimePreference: ['napi', 'wasm', 'js'],
+  lazyLoad: true,
+  debug: false
+});
+
+await bridge.initialize();
+
+// Component access
+const sona = await bridge.getSONAAdapter();
+const attention = await bridge.getAttentionCoordinator();
+const sdk = await bridge.getSDKBridge();
+
+// Feature management
+bridge.isFeatureEnabled('enableSONA');
+await bridge.enableFeature('enableFlashAttention');
+await bridge.disableFeature('enableAgentDB');
+
+// Health & status
+const status = bridge.getStatus();
+const health = await bridge.healthCheck();
+const flags = bridge.getFeatureFlags();
+
+// Direct agentic-flow access (when available)
+const core = bridge.getAgenticFlowCore();
+if (core) {
+  const patterns = await core.sona.findPatterns(query);
+}
+
+// Cleanup
+await bridge.shutdown();
+```
+
+### SONA Adapter
+
+```typescript
+const sona = await bridge.getSONAAdapter();
+
+// Mode management
+await sona.setMode('real-time');  // 'real-time' | 'balanced' | 'research' | 'edge' | 'batch'
+
+// Pattern operations
+const patternId = await sona.storePattern({
+  context: 'code-review',
+  strategy: 'analyze-then-comment',
+  embedding: vector
+});
+
+const patterns = await sona.findPatterns(queryEmbedding, {
+  limit: 5,
+  threshold: 0.7
+});
+
+// Statistics
+const stats = await sona.getStats();
+```
+
+### Attention Coordinator
+
+```typescript
+const attention = await bridge.getAttentionCoordinator();
+
+// Set attention mechanism
+await attention.setMechanism('flash');  // 'flash' | 'standard' | 'linear'
+
+// Compute attention
+const result = await attention.compute({
+  query: queryTensor,
+  key: keyTensor,
+  value: valueTensor,
+  mask: optionalMask
+});
+
+// Get metrics
+const metrics = await attention.getMetrics();
+// { avgLatencyMs, speedupRatio, memoryUsage }
+```
+
+### SDK Bridge
+
+```typescript
+const sdk = await bridge.getSDKBridge();
+
+// Version negotiation
+const version = sdk.getVersion();
+const isCompatible = sdk.isCompatible('0.1.0');
+
+// Health check
+await sdk.ping();
+```
+
+## Feature Flags
+
+```typescript
+const flags = bridge.getFeatureFlags();
+
+{
+  enableSONA: true,              // SONA learning integration
+  enableFlashAttention: true,    // Flash Attention optimization
+  enableAgentDB: true,           // AgentDB vector storage
+  enableTrajectoryTracking: true,// Trajectory recording
+  enableGNN: true,               // Graph Neural Network
+  enableIntelligenceBridge: true,// Intelligence bridge
+  enableQUICTransport: false,    // QUIC transport (experimental)
+  enableNightlyLearning: false,  // Background learning
+  enableAutoConsolidation: true  // Auto memory consolidation
+}
+```
+
+## Runtime Detection
+
+The bridge automatically selects the best runtime:
+
+| Runtime | Performance | Requirements |
+|---------|-------------|--------------|
+| **NAPI** | Optimal | Native bindings, non-Windows or x64 |
+| **WASM** | Good | WebAssembly support |
+| **JS** | Fallback | Always available |
+
+```typescript
+const status = bridge.getStatus();
+console.log(status.runtime);
+// { runtime: 'napi', platform: 'linux', arch: 'x64', performanceTier: 'optimal' }
+```
+
+## Event System
+
+```typescript
+bridge.on('initialized', ({ duration, components, agenticFlowConnected }) => {
+  console.log(`Initialized in ${duration}ms`);
+});
+
+bridge.on('agentic-flow:connected', ({ version, features }) => {
+  console.log(`Connected to agentic-flow ${version}`);
+});
+
+bridge.on('agentic-flow:fallback', ({ reason }) => {
+  console.log(`Using fallback: ${reason}`);
+});
+
+bridge.on('feature-enabled', ({ feature }) => {
+  console.log(`Enabled: ${feature}`);
+});
+
+bridge.on('health-check', ({ results }) => {
+  console.log(`Health: ${JSON.stringify(results)}`);
+});
+```
+
+## Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| Flash Attention speedup | 2.49x-7.47x |
+| AgentDB search | 150x-12,500x faster |
+| SONA adaptation | <0.05ms |
+| Memory reduction | 50-75% |
+
+## TypeScript Types
+
+```typescript
+import type {
+  IntegrationConfig,
+  IntegrationStatus,
+  RuntimeInfo,
+  ComponentHealth,
+  FeatureFlags,
+  AgenticFlowCore
+} from '@claude-flow/integration';
+```
+
+## Peer Dependencies
+
+- `agentic-flow@^0.1.0` (optional, for optimal performance)
+
+## Related Packages
+
+- [@claude-flow/neural](../neural) - SONA learning module
+- [@claude-flow/memory](../memory) - AgentDB memory
+- [@claude-flow/performance](../performance) - Benchmarking
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@sparkleideas/integration",
+  "version": "3.5.2-patch.1",
+  "type": "module",
+  "description": "Integration module - agentic-flow@alpha deep integration, ADR-001 compliance, TokenOptimizer",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./token-optimizer": "./dist/token-optimizer.js",
+    "./*": "./dist/*.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc"
+  },
+  "keywords": [
+    "claude-flow",
+    "agentic-flow",
+    "token-optimizer",
+    "agent-booster",
+    "reasoningbank",
+    "anti-drift",
+    "swarm"
+  ],
+  "peerDependencies": {
+    "@sparkleideas/agentic-flow": "^2.0.0-alpha"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "v3alpha"
+  },
+  "optionalDependencies": {
+    "agent-booster": "^0.2.2"
+  },
+  "claude-flow": {
+    "optionalComponents": {
+      "TokenOptimizer": {
+        "description": "Token reduction via agentic-flow Agent Booster integration",
+        "savings": "30-50%",
+        "features": [
+          "ReasoningBank",
+          "cache",
+          "anti-drift-config"
+        ],
+        "requires": [
+          "agentic-flow"
+        ]
+      }
+    }
+  }
+}

package/src/__tests__/agent-adapter.test.ts

@@ -0,0 +1,271 @@
+/**
+ * AgentAdapter Test Suite
+ *
+ * Tests for ADR-001 agent adapter and delegation patterns
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { AgentAdapter, createAgentAdapter } from '../agent-adapter.js';
+import { AgenticFlowAgent } from '../agentic-flow-agent.js';
+
+describe('AgentAdapter', () => {
+  let adapter: AgentAdapter;
+
+  beforeEach(async () => {
+    adapter = new AgentAdapter({
+      enableSync: true,
+      autoConvert: true,
+      fallbackOnError: true,
+      debug: false,
+    });
+
+    await adapter.initialize();
+  });
+
+  afterEach(async () => {
+    if (adapter) {
+      await adapter.shutdown();
+    }
+  });
+
+  describe('Initialization', () => {
+    it('should initialize successfully', async () => {
+      const freshAdapter = new AgentAdapter();
+      await freshAdapter.initialize();
+
+      expect(freshAdapter).toBeDefined();
+
+      await freshAdapter.shutdown();
+    });
+
+    it('should be idempotent on multiple initialize calls', async () => {
+      await adapter.initialize();
+      await adapter.initialize();
+
+      expect(adapter).toBeDefined();
+    });
+  });
+
+  describe('Agent Creation with Delegation', () => {
+    it('should create an agent with delegation support', async () => {
+      const agent = await adapter.createWithDelegation({
+        id: 'delegated-agent-1',
+        name: 'Delegated Agent',
+        type: 'coder',
+        capabilities: ['code-generation'],
+        maxConcurrentTasks: 3,
+        priority: 5,
+      });
+
+      expect(agent).toBeInstanceOf(AgenticFlowAgent);
+      expect(agent.id).toBe('delegated-agent-1');
+      expect(agent.status).toBe('idle'); // Should be initialized
+    });
+
+    it('should track created agents', async () => {
+      const agent1 = await adapter.createWithDelegation({
+        id: 'agent-1',
+        name: 'Agent 1',
+        type: 'coder',
+        capabilities: [],
+        maxConcurrentTasks: 1,
+        priority: 1,
+      });
+
+      const agent2 = await adapter.createWithDelegation({
+        id: 'agent-2',
+        name: 'Agent 2',
+        type: 'tester',
+        capabilities: [],
+        maxConcurrentTasks: 1,
+        priority: 1,
+      });
+
+      const allAgents = adapter.getAllAgents();
+      expect(allAgents).toHaveLength(2);
+      expect(allAgents).toContain(agent1);
+      expect(allAgents).toContain(agent2);
+    });
+  });
+
+  describe('Agent Retrieval', () => {
+    let testAgent: AgenticFlowAgent;
+
+    beforeEach(async () => {
+      testAgent = await adapter.createWithDelegation({
+        id: 'retrieval-agent',
+        name: 'Retrieval Test Agent',
+        type: 'researcher',
+        capabilities: ['research'],
+        maxConcurrentTasks: 2,
+        priority: 3,
+      });
+    });
+
+    it('should retrieve agent by ID', () => {
+      const retrieved = adapter.getAgent('retrieval-agent');
+
+      expect(retrieved).toBe(testAgent);
+    });
+
+    it('should return undefined for non-existent agent', () => {
+      const retrieved = adapter.getAgent('non-existent-agent');
+
+      expect(retrieved).toBeUndefined();
+    });
+
+    it('should get all agents', () => {
+      const allAgents = adapter.getAllAgents();
+
+      expect(allAgents).toHaveLength(1);
+      expect(allAgents[0]).toBe(testAgent);
+    });
+  });
+
+  describe('Agent Removal', () => {
+    it('should remove an agent', async () => {
+      const agent = await adapter.createWithDelegation({
+        id: 'removal-agent',
+        name: 'Removal Test',
+        type: 'coder',
+        capabilities: [],
+        maxConcurrentTasks: 1,
+        priority: 1,
+      });
+
+      expect(adapter.getAgent('removal-agent')).toBe(agent);
+
+      const removed = await adapter.removeAgent('removal-agent');
+
+      expect(removed).toBe(true);
+      expect(adapter.getAgent('removal-agent')).toBeUndefined();
+    });
+
+    it('should return false when removing non-existent agent', async () => {
+      const removed = await adapter.removeAgent('non-existent');
+
+      expect(removed).toBe(false);
+    });
+  });
+
+  describe('Agent Conversion from @sparkleideas/agentic-flow', () => {
+    it('should convert @sparkleideas/agentic-flow agent format', () => {
+      const mockAgenticFlowAgent = {
+        id: 'mock-agent-1',
+        name: 'Mock Agent',
+        type: 'coder',
+        status: 'ready',
+        config: {
+          capabilities: ['code-generation', 'refactoring'],
+          maxConcurrentTasks: 3,
+          priority: 5,
+        },
+      };
+
+      const result = adapter.fromAgenticFlow(mockAgenticFlowAgent);
+
+      expect(result.success).toBe(true);
+      expect(result.agent).toBeInstanceOf(AgenticFlowAgent);
+      expect(result.agent.id).toBe('mock-agent-1');
+      expect(result.agent.name).toBe('Mock Agent');
+      expect(result.warnings).toHaveLength(0);
+    });
+
+    it('should handle conversion warnings for unknown agent types', () => {
+      const mockAgenticFlowAgent = {
+        id: 'mock-agent-2',
+        name: 'Mock Agent',
+        type: 'unknown-type',
+        status: 'ready',
+        config: {
+          capabilities: [],
+        },
+      };
+
+      const result = adapter.fromAgenticFlow(mockAgenticFlowAgent);
+
+      expect(result.success).toBe(true);
+      expect(result.warnings.length).toBeGreaterThan(0);
+      expect(result.warnings[0]).toContain('unknown-type');
+    });
+  });
+
+  describe('Agent Conversion to @sparkleideas/agentic-flow', () => {
+    it('should convert Claude Flow agent to @sparkleideas/agentic-flow format', async () => {
+      const agent = await adapter.createWithDelegation({
+        id: 'convert-agent',
+        name: 'Convert Test',
+        type: 'coder',
+        capabilities: ['code-generation'],
+        maxConcurrentTasks: 2,
+        priority: 4,
+      });
+
+      const agenticFlowFormat = adapter.toAgenticFlow(agent);
+
+      expect(agenticFlowFormat.id).toBe('convert-agent');
+      expect(agenticFlowFormat.name).toBe('Convert Test');
+      expect(agenticFlowFormat.type).toBe('coder');
+      expect(agenticFlowFormat.config).toBeDefined();
+    });
+  });
+
+  describe('Delegation Status', () => {
+    it('should track delegation status', async () => {
+      const agent = await adapter.createWithDelegation({
+        id: 'delegation-check-agent',
+        name: 'Delegation Check',
+        type: 'coder',
+        capabilities: [],
+        maxConcurrentTasks: 1,
+        priority: 1,
+      });
+
+      // Note: isDelegated will be false unless @sparkleideas/agentic-flow is actually available
+      const isDelegated = adapter.isDelegated('delegation-check-agent');
+
+      expect(typeof isDelegated).toBe('boolean');
+    });
+  });
+
+  describe('Shutdown', () => {
+    it('should shutdown all managed agents', async () => {
+      await adapter.createWithDelegation({
+        id: 'shutdown-agent-1',
+        name: 'Shutdown Test 1',
+        type: 'coder',
+        capabilities: [],
+        maxConcurrentTasks: 1,
+        priority: 1,
+      });
+
+      await adapter.createWithDelegation({
+        id: 'shutdown-agent-2',
+        name: 'Shutdown Test 2',
+        type: 'tester',
+        capabilities: [],
+        maxConcurrentTasks: 1,
+        priority: 1,
+      });
+
+      expect(adapter.getAllAgents()).toHaveLength(2);
+
+      await adapter.shutdown();
+
+      expect(adapter.getAllAgents()).toHaveLength(0);
+    });
+  });
+});
+
+describe('createAgentAdapter', () => {
+  it('should create and initialize an adapter', async () => {
+    const adapter = await createAgentAdapter({
+      enableSync: true,
+      debug: false,
+    });
+
+    expect(adapter).toBeInstanceOf(AgentAdapter);
+
+    await adapter.shutdown();
+  });
+});