agentic-flow 1.9.4 → 1.10.0

package/docs/README.md

@@ -0,0 +1,217 @@
+# Agentic-Flow Documentation
+
+Complete documentation for the agentic-flow platform - AI agent orchestration with 66 specialized agents, 213 MCP tools, ReasoningBank learning memory, and autonomous multi-agent swarms.
+
+## 📚 Documentation Structure
+
+### Core Documentation
+- **[CLAUDE.md](CLAUDE.md)** - Claude Code configuration and SPARC development environment setup
+
+### Quick Start & Guides
+- **[guides/](guides/)** - User guides, tutorials, and how-to documentation
+  - [Quick Start Guide](guides/QUICK-START-v1.7.1.md)
+  - [MCP Tools](guides/MCP-TOOLS.md)
+  - [Claude Code Integration](guides/CLAUDE-CODE-INTEGRATION.md)
+  - [Agent Booster](guides/AGENT-BOOSTER.md)
+  - [ReasoningBank](guides/REASONINGBANK.md)
+  - [Multi-Model Router](guides/MULTI-MODEL-ROUTER.md)
+  - [Deployment Guide](guides/DEPLOYMENT.md)
+
+### Architecture & Design
+- **[architecture/](architecture/)** - System architecture and design documents
+  - [Executive Summary](architecture/EXECUTIVE_SUMMARY.md)
+  - [Package Structure](architecture/PACKAGE_STRUCTURE.md)
+  - [QUIC Implementation](architecture/QUIC-IMPLEMENTATION-SUMMARY.md)
+  - [Integration Status](architecture/INTEGRATION-STATUS.md)
+  - [Improvement Plan](architecture/IMPROVEMENT_PLAN.md)
+
+### Integration Documentation
+- **[integration-docs/](integration-docs/)** - Integration guides and implementation summaries
+- **[integrations/](integrations/)** - Specific integration implementations
+  - [Claude Flow Integration](integrations/CLAUDE_FLOW_INTEGRATION.md)
+  - [Flow Nexus Integration](integrations/FLOW-NEXUS-INTEGRATION.md)
+  - [FastMCP Integration](integrations/FASTMCP_CLI_INTEGRATION.md)
+
+### Feature Documentation
+
+#### Provider & Router
+- **[providers/](providers/)** - Provider fallback and configuration
+  - [Provider Fallback Guide](providers/PROVIDER-FALLBACK-GUIDE.md)
+  - [Provider Fallback Summary](providers/PROVIDER-FALLBACK-SUMMARY.md)
+  - [Landing Page Provider Content](providers/LANDING-PAGE-PROVIDER-CONTENT.md)
+- **[router/](router/)** - Multi-model router documentation
+  - [Router User Guide](router/ROUTER_USER_GUIDE.md)
+  - [Router Config Reference](router/ROUTER_CONFIG_REFERENCE.md)
+
+#### QUIC Transport
+- **[quic/](quic/)** - QUIC protocol implementation
+  - [QUIC Status](quic/QUIC-STATUS.md)
+  - [Implementation Complete](quic/IMPLEMENTATION-COMPLETE-SUMMARY.md)
+  - [Final Validation](quic/FINAL-VALIDATION.md)
+  - [Performance Validation](quic/PERFORMANCE-VALIDATION.md)
+
+#### ReasoningBank
+- **[reasoningbank/](reasoningbank/)** - ReasoningBank learning memory system
+  - [Architecture](reasoningbank/REASONINGBANK_ARCHITECTURE.md)
+  - [Backends](reasoningbank/REASONINGBANK_BACKENDS.md)
+  - [Benchmark Results](reasoningbank/REASONINGBANK-BENCHMARK-RESULTS.md)
+  - [Validation](reasoningbank/REASONINGBANK-VALIDATION.md)
+
+#### Supabase Integration
+- **[supabase/](supabase/)** - Supabase realtime federation
+  - [Quick Start](supabase/QUICKSTART.md)
+  - [Implementation Summary](supabase/IMPLEMENTATION-SUMMARY.md)
+  - [Test Report](supabase/TEST-REPORT.md)
+
+#### Federation
+- **[federation/](federation/)** - Agent federation and deployment
+  - [Deployment Validation](federation/DEPLOYMENT-VALIDATION-SUCCESS.md)
+  - [Debug Streaming](federation/DEBUG-STREAMING-COMPLETE.md)
+
+### Testing & Validation
+- **[testing/](testing/)** - Test documentation and results
+  - [Agent System Validation](testing/AGENT-SYSTEM-VALIDATION.md)
+  - [Final Testing Summary](testing/FINAL-TESTING-SUMMARY.md)
+  - [Regression Test Results](testing/REGRESSION-TEST-RESULTS.md)
+- **[validation/](validation/)** - Validation reports and processes
+- **[validation-reports/](validation-reports/)** - Detailed validation results
+  - [Docker Validation](validation-reports/DOCKER_VALIDATION_RESULTS.md)
+  - [No Regressions Confirmed](validation-reports/NO_REGRESSIONS_CONFIRMED.md)
+- **[docker-tests/](docker-tests/)** - Docker test configurations
+
+### MCP Validation
+- **[mcp-validation/](mcp-validation/)** - Model Context Protocol validation
+  - [MCP CLI Validation Report](mcp-validation/MCP-CLI-VALIDATION-REPORT.md)
+  - [Implementation Summary](mcp-validation/IMPLEMENTATION-SUMMARY.md)
+
+### Benchmarks & Performance
+- **[benchmarks/](benchmarks/)** - Performance benchmarks
+  - [QUIC Results](benchmarks/quic-results.md)
+  - [Optimization Guide](benchmarks/optimization-guide.md)
+
+### Release Information
+- **[releases/](releases/)** - Release notes and GitHub issues
+  - [v1.8.13 Release](releases/RELEASE-v1.8.13.md)
+  - [v1.5.14 QUIC Transport](releases/v1.5.14-QUIC-TRANSPORT.md)
+  - [v1.4.6 ReasoningBank](releases/v1.4.6-reasoningbank-release.md)
+- **[version-releases/](version-releases/)** - Version-specific release documentation
+
+### Planning & Research
+- **[plans/](plans/)** - Feature plans and roadmaps
+  - [QUIC Implementation](plans/QUIC/)
+  - [Agent Booster](plans/agent-booster/)
+  - [Requesty](plans/requesty/)
+- **[quantum-goap/](quantum-goap/)** - Goal-Oriented Action Planning
+- **[quantum-research/](quantum-research/)** - Quantum research literature
+
+### Issues & Reports
+- **[issues/](issues/)** - Known issues and troubleshooting
+  - [Supabase Integration Issue](issues/ISSUE-SUPABASE-INTEGRATION.md)
+  - [Xenova Transformers Dependency](issues/ISSUE-xenova-transformers-dependency.md)
+- **[reports/](reports/)** - Status reports and completion summaries
+- **[reviews/](reviews/)** - Code and implementation reviews
+
+### Archived Documentation
+- **[archived/](archived/)** - Historical documentation (kept for reference)
+  - Old validation reports
+  - Deprecated integration guides
+  - Previous version documentation
+
+## 🚀 Quick Links
+
+### Getting Started
+1. [Quick Start Guide](guides/QUICK-START-v1.7.1.md)
+2. [Claude Code Setup](CLAUDE.md)
+3. [Installation Guide](guides/DEPLOYMENT.md)
+
+### Core Features
+- [66 Specialized Agents](CLAUDE.md#-available-agents-54-total)
+- [213 MCP Tools](guides/MCP-TOOLS.md)
+- [ReasoningBank Learning](reasoningbank/README.md)
+- [Multi-Model Router](router/README.md)
+- [QUIC Transport](quic/QUIC-STATUS.md)
+
+### Integration
+- [Claude Flow](integrations/CLAUDE_FLOW_INTEGRATION.md)
+- [Flow Nexus](integrations/FLOW-NEXUS-INTEGRATION.md)
+- [FastMCP](integrations/FASTMCP_CLI_INTEGRATION.md)
+- [Supabase](supabase/README.md)
+
+### Development
+- [Architecture Overview](architecture/EXECUTIVE_SUMMARY.md)
+- [SPARC Methodology](CLAUDE.md#sparc-workflow-phases)
+- [Testing Guide](testing/README.md)
+
+## 📖 Documentation Standards
+
+### File Organization
+- Use descriptive filenames in UPPERCASE-WITH-DASHES.md format
+- Group related docs in topic-specific directories
+- Keep root directory minimal (README, CLAUDE, LICENSE only)
+
+### Content Guidelines
+- Start with a clear title and description
+- Include table of contents for docs > 200 lines
+- Use code blocks with language identifiers
+- Add examples and use cases where applicable
+
+### Directory Structure
+```
+docs/
+├── README.md              # This file
+├── CLAUDE.md             # Claude Code config
+├── LICENSE               # License file
+├── architecture/         # System architecture
+├── guides/              # User guides
+├── integration-docs/    # Integration documentation
+├── integrations/        # Specific integrations
+├── testing/            # Test documentation
+├── releases/           # Release notes
+├── issues/             # Known issues
+├── providers/          # Provider configuration
+├── quic/              # QUIC implementation
+├── reasoningbank/     # ReasoningBank docs
+├── router/            # Router documentation
+├── supabase/          # Supabase integration
+└── archived/          # Historical docs
+```
+
+## 🔍 Search Tips
+
+### Finding Documentation
+- Use `grep -r "keyword" docs/` to search all docs
+- Check the appropriate category directory first
+- Look in archived/ for historical documentation
+
+### Common Topics
+- **Setup**: See guides/ and CLAUDE.md
+- **API Reference**: See integration-docs/
+- **Troubleshooting**: See issues/
+- **Performance**: See benchmarks/
+- **Releases**: See releases/ and version-releases/
+
+## 🤝 Contributing to Docs
+
+### Adding New Documentation
+1. Identify the appropriate directory
+2. Follow naming conventions
+3. Include proper frontmatter/headers
+4. Update this README index
+5. Add cross-references as needed
+
+### Updating Existing Docs
+1. Keep archived versions if major changes
+2. Update last modified date
+3. Maintain backward compatibility links
+4. Test all code examples
+
+## 📞 Support
+
+- **GitHub Issues**: https://github.com/ruvnet/agentic-flow/issues
+- **Documentation Updates**: Submit PR to docs/ directory
+- **Questions**: Check issues/ directory first
+
+---
+
+**Last Updated**: November 6, 2025
+**Version**: 1.9.1

package/docs/issues/ISSUE-xenova-transformers-dependency.md

@@ -0,0 +1,380 @@
+# Issue: npm install fails with @xenova/transformers version conflict
+
+## Problem Description
+
+Users report installation failure when running:
+```bash
+npm i -g claude-flow@alpha
+```
+
+**Error:**
+```
+npm error code ETARGET
+npm error notarget No matching version found for @xenova/transformers@^3.2.0.
+npm error notarget In most cases you or one of your dependencies are requesting
+npm error notarget a package version that doesn't exist.
+```
+
+## Root Cause Analysis
+
+### Version Mismatch
+- **Requested version**: `@xenova/transformers@^3.2.0` (doesn't exist)
+- **Latest available version**: `2.17.2`
+- **Our package.json**: Correctly specifies `^2.17.2`
+
+### Source of Conflict - IDENTIFIED! ✅
+
+**The problem is in `claude-flow@alpha` package:**
+
+```
+User runs: npm i -g claude-flow@alpha
+
+Dependency chain:
+└── claude-flow@2.7.28 (alpha tag)
+    └── agentic-flow@^1.8.10
+        ├── @xenova/transformers@^2.17.2 ✅ (correct)
+        └── agentdb@^1.4.3
+            └── NO @xenova/transformers ❌ (missing!)
+```
+
+**The issue:**
+- `claude-flow@alpha` (v2.7.28) depends on `agentic-flow@^1.8.10`
+- `agentic-flow@1.8.10` depends on `agentdb@^1.4.3`
+- **`agentdb@1.4.3` does NOT have `@xenova/transformers` in dependencies**
+- But `agentdb@1.5.0+` DOES include `@xenova/transformers@^2.17.2`
+
+**Why the error occurs:**
+- User installs `claude-flow@alpha` globally
+- npm resolves to `agentic-flow@1.8.10` → `agentdb@1.4.3`
+- `agentdb@1.4.3` is OLD and missing transformers dependency
+- Somewhere in the dependency resolution, npm gets confused about version requirements
+- Reports non-existent `^3.2.0` (likely npm registry corruption or cache issue)
+
+**Published versions:**
+- ✅ `agentdb@1.4.3` - No transformers (OLD)
+- ✅ `agentdb@1.5.0+` - Has transformers@^2.17.2 (FIXED)
+- ✅ `agentdb@1.6.1` - Has transformers@^2.17.2 (CURRENT)
+- ✅ `agentic-flow@1.8.10` - Has transformers@^2.17.2 (used by claude-flow@alpha)
+- ✅ `agentic-flow@1.9.1` - Has transformers@^2.17.2 (LATEST, not published as alpha)
+
+### Current Usage in Codebase
+
+**Files using @xenova/transformers:**
+1. `packages/agentdb/src/controllers/EmbeddingService.ts:32` - Dynamic import
+2. `agentic-flow/src/agentdb/controllers/EmbeddingService.ts:32` - Dynamic import
+3. `agentic-flow/src/router/providers/onnx.ts:33` - Dynamic import
+4. `agentic-flow/src/reasoningbank/utils/embeddings.ts:6` - Static import
+
+**Key observation**: Most imports are **dynamic** (`await import()`) except embeddings.ts which uses static import.
+
+## Impact
+
+- **Severity**: HIGH - Blocks all global installations of `claude-flow@alpha`
+- **Affected package**: `claude-flow@alpha` (v2.7.28)
+- **Dependency chain**: `claude-flow@alpha` → `agentic-flow@1.8.10` → `agentdb@1.4.3` (missing transformers)
+- **User impact**: Cannot install `claude-flow@alpha` globally
+- **Root package**: This repository (`agentic-flow`) needs to coordinate fix with `claude-flow`
+- **Workaround**: Update `claude-flow@alpha` to use `agentic-flow@^1.9.0` which depends on newer `agentdb`
+
+## Proposed Solution
+
+### IMMEDIATE FIX: Update claude-flow@alpha dependency (REQUIRED)
+
+**The `claude-flow` package needs to be updated:**
+
+```json
+// claude-flow/package.json
+{
+  "dependencies": {
+    "agentic-flow": "^1.9.0"  // Change from ^1.8.10 to ^1.9.0
+  }
+}
+```
+
+This ensures it pulls `agentdb@1.6.x` which has the transformers dependency.
+
+**Action required:**
+1. Update `claude-flow` repository to bump `agentic-flow` to `^1.9.0`
+2. Publish new `claude-flow@alpha` version
+3. Test global installation: `npm i -g claude-flow@alpha`
+
+---
+
+### Strategy 1: Make @xenova/transformers Optional (LONG-TERM, RECOMMENDED)
+
+Convert `@xenova/transformers` to an **optional peer dependency** with lazy loading:
+
+**Benefits:**
+- ✅ Users only install ONNX libraries when actually needed
+- ✅ Reduces package size (23MB+ model downloads)
+- ✅ Avoids dependency conflicts
+- ✅ Faster installation for users not using embeddings
+- ✅ Graceful fallback to hash-based embeddings
+
+**Implementation:**
+
+#### 1. Update package.json dependencies
+
+**packages/agentdb/package.json:**
+```json
+{
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "hnswlib-node": "^3.0.0",
+    "sql.js": "^1.13.0",
+    "zod": "^3.25.76"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.8.1",
+    "@xenova/transformers": "^2.17.2"
+  },
+  "peerDependenciesMeta": {
+    "@xenova/transformers": {
+      "optional": true
+    }
+  }
+}
+```
+
+**agentic-flow/package.json:**
+```json
+{
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.5",
+    "@anthropic-ai/sdk": "^0.65.0",
+    "agentdb": "^1.4.3",
+    // ... other deps
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
+  "peerDependenciesMeta": {
+    "@xenova/transformers": {
+      "optional": true
+    }
+  }
+}
+```
+
+#### 2. Update static import to dynamic
+
+**agentic-flow/src/reasoningbank/utils/embeddings.ts:**
+
+```typescript
+// BEFORE (line 6):
+import { pipeline, env } from '@xenova/transformers';
+
+// AFTER:
+let transformersModule: any = null;
+
+async function loadTransformers() {
+  if (!transformersModule) {
+    try {
+      transformersModule = await import('@xenova/transformers');
+      return transformersModule;
+    } catch (error) {
+      console.warn('[Embeddings] @xenova/transformers not installed. Using hash-based fallback.');
+      console.warn('[Embeddings] For semantic embeddings: npm install @xenova/transformers');
+      return null;
+    }
+  }
+  return transformersModule;
+}
+
+// Update line 11-12:
+async function configureTransformers() {
+  const transformers = await loadTransformers();
+  if (transformers?.env) {
+    transformers.env.backends.onnx.wasm.proxy = false;
+    transformers.env.backends.onnx.wasm.numThreads = 1;
+  }
+}
+
+// Update initializeEmbeddings() function:
+async function initializeEmbeddings(): Promise<void> {
+  // ... existing npx detection code ...
+
+  const transformers = await loadTransformers();
+  if (!transformers) {
+    console.log('[Embeddings] Transformers not available - using hash-based embeddings');
+    isInitializing = false;
+    return;
+  }
+
+  try {
+    embeddingPipeline = await transformers.pipeline(
+      'feature-extraction',
+      'Xenova/all-MiniLM-L6-v2',
+      { quantized: true }
+    );
+    console.log('[Embeddings] Local model ready! (384 dimensions)');
+  } catch (error: any) {
+    console.error('[Embeddings] Failed to initialize:', error?.message || error);
+    console.warn('[Embeddings] Falling back to hash-based embeddings');
+  } finally {
+    isInitializing = false;
+  }
+}
+```
+
+#### 3. Clean up lock files
+
+```bash
+# Remove lock files that may have stale dependencies
+rm -f packages/agentdb/package-lock.json
+rm -f agentic-flow/package-lock.json
+rm -f package-lock.json
+
+# Regenerate with correct versions
+npm install
+```
+
+#### 4. Add installation documentation
+
+**README.md addition:**
+```markdown
+## Optional Dependencies
+
+### Semantic Embeddings (@xenova/transformers)
+
+For semantic similarity search with ReasoningBank and AgentDB, install:
+
+```bash
+npm install @xenova/transformers
+```
+
+**Without this package:** Hash-based embeddings are used (fast, deterministic, no semantic meaning)
+**With this package:** True semantic embeddings (slower, requires 23MB model download, better accuracy)
+
+The package will work without @xenova/transformers installed, using a fast hash-based fallback.
+```
+
+### Strategy 2: Fix Transitive Dependency (Alternative)
+
+**Investigation steps:**
+```bash
+# Find which dependency requires 3.2.0
+npm ls @xenova/transformers
+npm explain @xenova/transformers
+
+# Check for outdated dependencies
+npm outdated
+```
+
+**If found, update the problematic dependency:**
+```bash
+npm update <problematic-package>
+```
+
+### Strategy 3: Use npm overrides (Quick Fix)
+
+**package.json:**
+```json
+{
+  "overrides": {
+    "@xenova/transformers": "^2.17.2"
+  }
+}
+```
+
+This forces all dependencies to use version 2.17.2.
+
+## Recommended Implementation Order
+
+1. ✅ **Immediate**: Add npm overrides to force correct version (Strategy 3)
+2. ✅ **Next release**: Implement optional dependencies (Strategy 1)
+3. ✅ **Investigation**: Identify and update problematic transitive dependency (Strategy 2)
+
+## Testing Plan
+
+### Unit Tests
+- ✅ Test EmbeddingService with transformers installed
+- ✅ Test EmbeddingService without transformers (fallback)
+- ✅ Test ReasoningBank embeddings with/without transformers
+- ✅ Verify hash-based fallback accuracy
+
+### Integration Tests
+```bash
+# Test global installation
+npm uninstall -g claude-flow
+npm install -g claude-flow@alpha
+
+# Test with transformers
+npm install @xenova/transformers
+npx claude-flow reasoningbank test
+
+# Test without transformers
+npm uninstall @xenova/transformers
+npx claude-flow reasoningbank test
+```
+
+### Performance Validation
+- Measure installation time (with vs without transformers)
+- Measure embedding generation speed (semantic vs hash)
+- Memory usage comparison
+
+## Migration Guide
+
+### For Users
+
+**Current behavior:**
+```bash
+npm i -g claude-flow@alpha  # FAILS with version error
+```
+
+**After fix:**
+```bash
+npm i -g claude-flow@alpha  # ✅ Works, uses hash-based embeddings
+
+# Optional: Install for semantic embeddings
+npm install -g @xenova/transformers
+```
+
+### For Developers
+
+No API changes required. All existing code continues to work:
+- `computeEmbedding()` - Automatically uses available method
+- `computeEmbeddingBatch()` - Same behavior
+- Error handling already exists for transformer failures
+
+## Related Files
+
+### To Modify:
+- `packages/agentdb/package.json` - Move to optionalDependencies
+- `agentic-flow/package.json` - Move to optionalDependencies
+- `agentic-flow/src/reasoningbank/utils/embeddings.ts` - Convert static import to dynamic
+
+### Already Correct (using dynamic imports):
+- `packages/agentdb/src/controllers/EmbeddingService.ts`
+- `agentic-flow/src/agentdb/controllers/EmbeddingService.ts`
+- `agentic-flow/src/router/providers/onnx.ts`
+
+## Success Criteria
+
+- ✅ `npm install -g claude-flow@alpha` completes successfully
+- ✅ Package works without @xenova/transformers (hash fallback)
+- ✅ Package works with @xenova/transformers (semantic embeddings)
+- ✅ Installation time reduced by ~5 seconds (no 23MB download)
+- ✅ Package size reduced by ~50MB (ONNX models optional)
+- ✅ All existing tests pass
+- ✅ Documentation updated with optional dependency info
+
+## Timeline
+
+- **Investigation**: 30 minutes (identify transitive dependency)
+- **Implementation**: 2 hours (package.json changes, dynamic imports, tests)
+- **Testing**: 1 hour (installation, functionality, performance)
+- **Documentation**: 30 minutes (README, migration guide)
+- **Total**: ~4 hours
+
+## Priority: HIGH
+
+This blocks all global installations and should be fixed immediately.
+
+---
+
+**Labels**: bug, dependencies, installation, high-priority
+**Milestone**: v1.9.2 (patch release)
+**Assignee**: @ruvnet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow",
-  "version": "1.9.4",
+  "version": "1.10.0",
   "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, ReasoningBank learning memory, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/claude

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+/**
+ * Simple claude command wrapper
+ * This script makes the claude command available by running npx claude
+ */
+
+import { spawn } from 'child_process';
+
+// Get all arguments passed to this script (excluding node and script path)
+const args = process.argv.slice(2);
+
+// Spawn npx claude with all the arguments
+const claudeProcess = spawn('npx', ['claude', ...args], {
+  stdio: 'inherit',
+  env: process.env
+});
+
+// Handle process exit
+claudeProcess.on('exit', (code) => {
+  process.exit(code || 0);
+});
+
+// Handle signals
+process.on('SIGINT', () => {
+  claudeProcess.kill('SIGINT');
+});
+
+process.on('SIGTERM', () => {
+  claudeProcess.kill('SIGTERM');
+});