agentic-flow 1.0.0

package/docs/integrations/FLOW-NEXUS-INTEGRATION.md

@@ -0,0 +1,319 @@
+# Flow Nexus Integration Guide
+
+## Overview
+
+Agentic Flow now integrates with **Flow Nexus**, a cloud platform for AI development, adding **96 additional MCP tools** for cloud sandboxes, distributed swarms, neural training, and more.
+
+## Total MCP Tools: 203
+
+| Server | Tools | Description |
+|--------|-------|-------------|
+| **claude-flow** | 101 | Core orchestration, memory, GitHub, neural networks |
+| **flow-nexus** | 96 | Cloud sandboxes, distributed swarms, workflows, challenges |
+| **claude-flow-sdk** | 6 | In-process memory and coordination tools |
+| **TOTAL** | **203** | Complete AI orchestration toolkit |
+
+---
+
+## Flow Nexus Features
+
+### ☁️ Cloud Sandboxes (E2B)
+Create isolated execution environments for code development and testing:
+
+- `sandbox_create` - Create Node.js, Python, React, or Next.js sandboxes
+- `sandbox_execute` - Run code in isolated environment
+- `sandbox_upload` - Upload files to sandbox
+- `sandbox_status` - Check sandbox health
+- `sandbox_logs` - View execution logs
+- `sandbox_delete` - Clean up resources
+
+### 🤖 Distributed Swarms
+Deploy multi-agent swarms in the cloud with auto-scaling:
+
+- `swarm_init` - Initialize cloud swarm with topology
+- `swarm_scale` - Scale agents up or down
+- `agent_spawn` - Create specialized agents
+- `task_orchestrate` - Distribute tasks across agents
+- `swarm_status` - Monitor swarm health
+
+### 🧠 Distributed Neural Training
+Train neural networks across multiple cloud sandboxes:
+
+- `neural_train` - Train models with distributed compute
+- `neural_predict` - Run inference on trained models
+- `neural_cluster_init` - Initialize training cluster
+- `neural_node_deploy` - Deploy training nodes
+- `neural_training_status` - Monitor training progress
+
+### ⚡ Workflow Automation
+Event-driven workflow orchestration with message queues:
+
+- `workflow_create` - Define automated workflows
+- `workflow_execute` - Run workflows asynchronously
+- `workflow_status` - Check workflow progress
+- `workflow_queue_status` - Monitor message queues
+
+### 🎯 Challenges & Gamification
+Coding challenges with leaderboards and achievements:
+
+- `challenges_list` - Browse available challenges
+- `challenge_submit` - Submit solution for validation
+- `leaderboard_get` - View rankings
+- `achievements_list` - Track user achievements
+
+### 💰 Credit Management
+Pay-as-you-go pricing with auto-refill:
+
+- `check_balance` - View current credit balance
+- `create_payment_link` - Generate payment link
+- `configure_auto_refill` - Set up automatic refills
+- `get_payment_history` - View transaction history
+
+### 📦 Templates & App Store
+Pre-built project templates and marketplace:
+
+- `template_list` - Browse available templates
+- `template_deploy` - Deploy template to sandbox
+- `app_search` - Search marketplace apps
+- `app_get` - Get application details
+
+---
+
+## Authentication
+
+Flow Nexus requires authentication to access cloud features.
+
+### Register New Account
+
+```bash
+# Using CLI
+npx agentic-flow --agent flow-nexus-auth \
+  --task "Register account with email: user@example.com, password: secure123"
+
+# Or via MCP tool directly
+mcp__flow-nexus__user_register({
+  email: "user@example.com",
+  password: "secure123",
+  full_name: "Your Name"
+})
+```
+
+### Login to Existing Account
+
+```bash
+# Using CLI
+npx agentic-flow --agent flow-nexus-auth \
+  --task "Login with email: user@example.com, password: secure123"
+
+# Or via MCP tool directly
+mcp__flow-nexus__user_login({
+  email: "user@example.com",
+  password: "secure123"
+})
+```
+
+### Check Authentication Status
+
+```bash
+npx agentic-flow --agent flow-nexus-user-tools \
+  --task "Check my authentication status and profile"
+```
+
+---
+
+## Usage Examples
+
+### Create and Execute in Sandbox
+
+```bash
+npx agentic-flow --agent flow-nexus-sandbox \
+  --task "Create a Node.js sandbox named 'api-dev', execute 'console.log(process.version)', and show the output"
+```
+
+### Deploy Distributed Swarm
+
+```bash
+npx agentic-flow --agent flow-nexus-swarm \
+  --task "Initialize a mesh topology swarm with 5 agents, then orchestrate building a REST API with authentication"
+```
+
+### Train Neural Network
+
+```bash
+npx agentic-flow --agent flow-nexus-neural \
+  --task "Train a classification neural network using distributed training across 3 nodes"
+```
+
+### Create Workflow
+
+```bash
+npx agentic-flow --agent flow-nexus-workflow \
+  --task "Create an event-driven workflow that triggers on git push, runs tests, and deploys on success"
+```
+
+### Check Credits
+
+```bash
+npx agentic-flow --agent flow-nexus-payments \
+  --task "Check my current credit balance and payment history"
+```
+
+---
+
+## Validation Results
+
+### Local Validation ✅
+
+```bash
+node validation/test-flow-nexus.js user@example.com password123
+```
+
+**Results:**
+- ✅ **203 total MCP tools discovered**
+  - 101 from claude-flow
+  - 96 from flow-nexus
+  - 6 from claude-flow-sdk
+- ✅ **Authentication successful**
+  - Login working
+  - Session persistence
+  - User profile accessible
+- ✅ **System health verified**
+  - Database: Healthy
+  - Version: 2.0.0
+  - All services operational
+- ⚠️ **Sandbox creation** (requires 10 credits minimum)
+
+### Docker Validation ✅
+
+```bash
+docker build -t agentic-flow:flow-nexus .
+docker run --rm -e ANTHROPIC_API_KEY=sk-ant-... agentic-flow:flow-nexus --help
+```
+
+**Results:**
+- ✅ Docker image builds successfully (~5 minutes)
+- ✅ All three MCP servers initialized in container
+- ✅ CLI functional with Flow Nexus integration
+- ✅ 75 agents loaded including flow-nexus specialists
+
+---
+
+## Pricing
+
+Flow Nexus uses a credit-based system:
+
+| Resource | Cost (Credits) |
+|----------|----------------|
+| Sandbox (hourly) | 10 credits |
+| Swarm agent (hourly) | 5 credits |
+| Neural training (job) | 20-100 credits |
+| Workflow execution | 1-5 credits |
+
+**Credit Packages:**
+- Starter: $10 = 100 credits
+- Developer: $50 = 550 credits (10% bonus)
+- Professional: $200 = 2400 credits (20% bonus)
+
+**Auto-refill Available:**
+- Set threshold (e.g., 20 credits)
+- Automatic recharge when balance drops
+- Configurable refill amount
+
+---
+
+## Architecture
+
+### Triple MCP Server Setup
+
+```typescript
+// src/agents/claudeAgent.ts
+mcpServers: {
+  // 1. In-SDK Server (6 tools, in-process)
+  'claude-flow-sdk': claudeFlowSdkServer,
+
+  // 2. Claude Flow (101 tools, subprocess)
+  'claude-flow': {
+    command: 'npx',
+    args: ['claude-flow@alpha', 'mcp', 'start']
+  },
+
+  // 3. Flow Nexus (96 tools, subprocess)
+  'flow-nexus': {
+    command: 'npx',
+    args: ['flow-nexus@latest', 'mcp', 'start']
+  }
+}
+```
+
+### Agent Coordination
+
+Flow Nexus agents automatically coordinate with claude-flow for:
+- **Memory sharing** - Store sandbox IDs and workflow results
+- **Swarm coordination** - Combine local and cloud agents
+- **Task orchestration** - Distribute work across environments
+- **Performance monitoring** - Track resource usage
+
+---
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem:** Login fails with "Invalid credentials"
+
+**Solution:**
+1. Verify email/password are correct
+2. Check if account is registered: `mcp__flow-nexus__user_register`
+3. Reset password if needed: `mcp__flow-nexus__user_reset_password`
+
+### Insufficient Credits
+
+**Problem:** "Insufficient credits to create sandbox"
+
+**Solution:**
+1. Check balance: `mcp__flow-nexus__check_balance`
+2. Create payment link: `mcp__flow-nexus__create_payment_link({ amount: 10 })`
+3. Enable auto-refill: `mcp__flow-nexus__configure_auto_refill({ enabled: true, threshold: 20, amount: 100 })`
+
+### MCP Server Connection
+
+**Problem:** Flow Nexus tools not appearing
+
+**Solution:**
+1. Verify installation: `npm ls flow-nexus`
+2. Check MCP server status in logs
+3. Restart with: `npx flow-nexus@latest mcp start`
+
+### Docker Environment
+
+**Problem:** Flow Nexus not working in Docker
+
+**Solution:**
+1. Ensure `ANTHROPIC_API_KEY` is set
+2. Verify network connectivity for MCP subprocesses
+3. Check logs: `docker logs <container_id>`
+
+---
+
+## Security Notes
+
+⚠️ **Important Security Practices:**
+
+1. **Never hardcode credentials** in source code or Docker images
+2. **Use environment variables** for sensitive data
+3. **Rotate API keys regularly** for production deployments
+4. **Enable 2FA** on Flow Nexus account for production use
+5. **Use separate accounts** for development vs production
+
+---
+
+## Support
+
+- **Flow Nexus Docs**: https://github.com/ruvnet/flow-nexus
+- **Agentic Flow Issues**: https://github.com/ruvnet/agentic-flow/issues
+- **MCP Protocol**: https://modelcontextprotocol.io
+- **Claude Agent SDK**: https://docs.claude.com/en/api/agent-sdk
+
+---
+
+**Ready to build with cloud-powered AI agents? 🚀**

package/docs/integrations/README.md

@@ -0,0 +1,18 @@
+# Integration Documentation
+
+Integration guides for external services and frameworks.
+
+## Claude Ecosystem
+
+- [Claude Agents Integration](CLAUDE_AGENTS_INTEGRATION.md) - Integrating with Claude agents
+- [Claude Flow Integration](CLAUDE_FLOW_INTEGRATION.md) - Claude Flow orchestration setup
+
+## MCP (Model Context Protocol)
+
+- [FastMCP CLI Integration](FASTMCP_CLI_INTEGRATION.md) - Command-line MCP integration
+- [FastMCP Implementation Plan](fastmcp-implementation-plan.md) - Detailed implementation strategy
+- [FastMCP POC Integration](fastmcp-poc-integration.md) - Proof of concept integration
+
+## Cloud Platforms
+
+- [Flow Nexus Integration](FLOW-NEXUS-INTEGRATION.md) - Flow Nexus cloud platform integration