@sparkleideas/agentic-flow 2.0.2-alpha-patch.1

package/agentic-flow/docs/IMPROVEMENT_ROADMAP.md

@@ -0,0 +1,184 @@
+# E2B Swarm & P2P Coordination - Improvement Roadmap
+
+## Current State Analysis
+
+### ✅ What's Working
+- E2B Firecracker sandboxes (live cloud execution)
+- Basic swarm orchestration
+- Simulated IPFS/GunDB/WebRTC coordination
+- AES-256-GCM encryption
+- ruv-swarm-transport WASM integration
+
+### ⚠️ Current Limitations
+1. **Simulated P2P** - Not using real GunDB/IPFS connections
+2. **Output capture** - E2B Python output sometimes missing
+3. **No persistence** - Learning patterns lost between sessions
+4. **Single region** - No geographic distribution
+5. **No real QUIC** - Using HTTP fallback
+
+---
+
+## Priority Improvements
+
+### 🔴 Critical (Immediate)
+
+#### 1. Real GunDB Integration
+```bash
+npm install gun
+```
+- Connect to actual GunDB relays
+- Real-time swarm state sync
+- Offline-first with auto-reconnect
+
+#### 2. Real IPFS Pinning
+```bash
+npm install @web3-storage/w3up-client
+```
+- Pin learning patterns to IPFS
+- Content-addressed retrieval
+- Free 5GB via web3.storage
+
+#### 3. Fix E2B Output Capture
+- Use `runCode` with proper stdout handling
+- Add retry logic for output retrieval
+- Stream output in real-time
+
+### 🟡 High Priority (This Week)
+
+#### 4. Persistent Learning Storage
+- Save SONA patterns to AgentDB
+- Export/import swarm state
+- Cross-session memory retention
+
+#### 5. Real WebRTC Mesh
+```bash
+npm install peerjs
+```
+- Direct agent-to-agent connections
+- Bypass relay servers
+- Lower latency coordination
+
+#### 6. OrbitDB Integration
+```bash
+npm install @orbitdb/core
+```
+- CRDT-based P2P database
+- Automatic conflict resolution
+- libp2p pubsub
+
+### 🟢 Medium Priority (This Month)
+
+#### 7. Geographic Distribution
+- Multi-region E2B sandboxes
+- Nearest-shard memory recall
+- Regional consensus groups
+
+#### 8. Real QUIC Transport
+- Use `@aspect-build/rules_js` for QUIC
+- 0-RTT connection resumption
+- Stream multiplexing
+
+#### 9. Advanced Compression
+- Real PQ quantization
+- Binary gradient compression
+- Adaptive bandwidth detection
+
+#### 10. Circuit Breaker (TinyDancer)
+- Integrate @ruvector/tiny-dancer
+- Auto-failover between providers
+- 99.9% uptime target
+
+---
+
+## Implementation Plan
+
+### Phase 1: Real P2P (2-3 days)
+```
+1. npm install gun @web3-storage/w3up-client peerjs
+2. Replace simulated clients with real ones
+3. Add connection health monitoring
+4. Test with multiple E2B sandboxes
+```
+
+### Phase 2: Persistence (1-2 days)
+```
+1. Integrate AgentDB for pattern storage
+2. Add swarm state export/import
+3. Implement cross-session memory
+4. Add HNSW index for pattern search
+```
+
+### Phase 3: Production Ready (1 week)
+```
+1. Add circuit breakers
+2. Multi-region support
+3. Real QUIC transport
+4. Comprehensive error handling
+5. Monitoring & metrics
+```
+
+---
+
+## Quick Wins (Can Do Now)
+
+### 1. Add Real GunDB Relay
+```javascript
+import Gun from 'gun';
+const gun = Gun(['https://gun-manhattan.herokuapp.com/gun']);
+const swarm = gun.get('agentic-flow-swarm');
+```
+
+### 2. Add web3.storage
+```javascript
+import { create } from '@web3-storage/w3up-client';
+const client = await create();
+// Free 5GB storage
+```
+
+### 3. Fix Output Capture
+```javascript
+// In e2b-sandbox.ts
+const result = await this.sandbox.runCode(code);
+// Check result.logs, result.text, result.results
+```
+
+### 4. Add PeerJS
+```javascript
+import { Peer } from 'peerjs';
+const peer = new Peer('swarm-' + swarmId);
+```
+
+---
+
+## Metrics to Track
+
+| Metric | Current | Target |
+|--------|---------|--------|
+| P2P Connection Rate | Simulated | 99%+ real |
+| Learning Persistence | 0% | 100% |
+| Output Capture | ~70% | 99%+ |
+| Multi-region | 1 | 3+ |
+| QUIC Usage | 0% | 80%+ |
+
+---
+
+## Cost Analysis
+
+| Provider | Current | After Improvement |
+|----------|---------|-------------------|
+| E2B | ~$0.10/sandbox | Same |
+| GunDB | $0 | $0 |
+| IPFS (web3.storage) | $0 | $0 (5GB free) |
+| WebRTC (PeerJS) | $0 | $0 |
+| **Total** | **~$0** | **~$0** |
+
+---
+
+## Next Steps
+
+1. [ ] Install real P2P packages (gun, @web3-storage, peerjs)
+2. [ ] Update swarm coordinator to use real connections
+3. [ ] Fix E2B output capture
+4. [ ] Add persistent storage for learning patterns
+5. [ ] Test multi-sandbox coordination
+6. [ ] Add monitoring dashboard

package/agentic-flow/docs/ISSUE-55-VALIDATION.md

@@ -0,0 +1,171 @@
+# Issue #55 Validation Report
+
+## Summary
+Successfully validated fix for Gemini API compatibility with Claude Code's tool definitions containing `exclusiveMinimum` and `exclusiveMaximum` JSON Schema properties.
+
+## Problem
+Claude Code's tools use JSON Schema Draft 7 properties (`exclusiveMinimum`, `exclusiveMaximum`) for parameter validation. The Gemini API doesn't support these properties and returns 400 errors:
+
+```json
+{
+  "error": {
+    "code": 400,
+    "message": "Invalid JSON payload received. Unknown name \"exclusiveMinimum\" at 'tools[0].function_declarations[27].parameters.properties[0].value': Cannot find field."
+  }
+}
+```
+
+## Solution
+Updated the `cleanSchema` function in `src/proxy/anthropic-to-gemini.ts` to strip these properties before sending to Gemini:
+
+```typescript
+const cleanSchema = (schema: any): any => {
+  if (!schema || typeof schema !== 'object') return schema;
+
+  const {
+    $schema,
+    additionalProperties,
+    exclusiveMinimum,      // NEW: Strip this property
+    exclusiveMaximum,      // NEW: Strip this property
+    ...rest
+  } = schema;
+  const cleaned: any = { ...rest };
+
+  // Recursively clean nested objects
+  if (cleaned.properties) {
+    cleaned.properties = Object.fromEntries(
+      Object.entries(cleaned.properties).map(([key, value]: [string, any]) => [
+        key,
+        cleanSchema(value)
+      ])
+    );
+  }
+
+  // Clean items if present
+  if (cleaned.items) {
+    cleaned.items = cleanSchema(cleaned.items);
+  }
+
+  return cleaned;
+};
+```
+
+## Validation Results
+
+### Test Environment
+- **Proxy:** Gemini proxy running on localhost:3001
+- **API:** Real Gemini API (generativelanguage.googleapis.com)
+- **Credentials:** Actual API key from .env
+- **Models Tested:** 4 Gemini models (all versions)
+
+### Test Tool Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "limit": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "description": "Limit parameter (must be > 0)"
+    },
+    "offset": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "exclusiveMaximum": 1000,
+      "description": "Offset parameter"
+    },
+    "name": {
+      "type": "string",
+      "description": "Name parameter (should be preserved)"
+    }
+  },
+  "required": ["limit"]
+}
+```
+
+### Results
+✅ **All Tests Passed**
+
+- ✅ Tool definition sent successfully
+- ✅ exclusiveMinimum handled correctly
+- ✅ exclusiveMaximum handled correctly
+- ✅ No 400 errors from Gemini API
+- ✅ Valid response received (HTTP 200)
+- ✅ No "Unknown name 'exclusiveMinimum'" errors
+
+### Multi-Model Test Results
+
+**All 4 Gemini Models Tested Successfully:**
+
+| Model | Status | Response Time | Result |
+|-------|--------|---------------|--------|
+| gemini-2.0-flash-exp | ✅ PASS | 754ms | Success |
+| gemini-1.5-pro | ✅ PASS | 520ms | Success |
+| gemini-1.5-flash | ✅ PASS | 655ms | Success |
+| gemini-1.5-flash-8b | ✅ PASS | 389ms | Success |
+
+**Statistics:**
+- Total Models: 4
+- Success Rate: 100% (4/4)
+- Schema Errors: 0
+- Average Response Time: 580ms
+- No `exclusiveMinimum` or `exclusiveMaximum` errors detected
+
+### Sample Response
+```json
+{
+  "id": "msg_1762536509022",
+  "type": "message",
+  "role": "assistant",
+  "model": "gemini-2.0-flash-exp",
+  "content": [
+    {
+      "type": "text",
+      "text": "..."
+    }
+  ],
+  "stop_reason": "end_turn",
+  "usage": {
+    "input_tokens": 157,
+    "output_tokens": 12
+  }
+}
+```
+
+## Impact
+
+### Before Fix
+- ❌ Gemini API rejected all requests with Claude Code tools
+- ❌ Users couldn't use Claude Code with Gemini provider
+- ❌ Error: "Unknown name 'exclusiveMinimum'"
+
+### After Fix
+- ✅ Gemini API accepts all Claude Code tool definitions
+- ✅ Full Claude Code compatibility with Gemini
+- ✅ All JSON Schema properties preserved except exclusiveMinimum/Maximum
+- ✅ Zero breaking changes for users
+
+## Files Modified
+- `src/proxy/anthropic-to-gemini.ts` (lines 307-336)
+
+## Commit
+- Hash: `ededa5f`
+- Message: "fix: Strip exclusiveMinimum/Maximum from Gemini tool schemas"
+
+## Testing
+- **Unit Test:** `/tmp/test-exclusiveMinimum-fix.js` - All tests passed
+- **Integration Test:** `validation/test-gemini-exclusiveMinimum-fix.ts` - All tests passed
+- **Multi-Model Test:** `validation/test-gemini-models.ts` - 4/4 models passed
+- **Real API Test:** Validated with actual Gemini API credentials across all models
+
+## Status
+✅ **RESOLVED AND VALIDATED**
+
+Issue #55 closed on 2025-11-07 after successful validation with real Gemini API environment.
+
+---
+
+**Validated by:** Claude Code validation suite
+**Date:** 2025-11-07
+**Environment:** Docker + Real Gemini API
+**Test Results:** 100% Pass Rate

package/agentic-flow/docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Claude Flow Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agentic-flow/docs/NPX_AGENTDB_SETUP.md

@@ -0,0 +1,175 @@
+# 🚀 How to Use `npx agentdb` with Frontier Features
+
+## Current Situation
+
+The NEW AgentDB CLI with frontier features (17 commands) is configured in the `agentic-flow` package:
+
+**Package:** `agentic-flow`
+**Binary:** `dist/agentdb/cli/agentdb-cli.js`
+**Features:** Causal Memory, Reflexion, Skills, Nightly Learner, etc.
+
+## Testing Locally (Before Publishing)
+
+### Option 1: Link the Package Locally
+
+```bash
+cd /workspaces/agentic-flow/agentic-flow
+
+# Build the package
+npm run build
+
+# Link it globally
+npm link
+
+# Now npx agentdb will use your local version
+npx agentdb --help
+```
+
+### Option 2: Use Node Directly
+
+```bash
+cd /workspaces/agentic-flow/agentic-flow
+node dist/agentdb/cli/agentdb-cli.js --help
+```
+
+## After Publishing to NPM
+
+Once you publish `agentic-flow` package to npm, users can run:
+
+```bash
+# Install globally
+npm install -g agentic-flow
+
+# Or use npx directly (no install needed)
+npx agentdb --help
+```
+
+## Publish Checklist
+
+Before publishing to npm:
+
+1. ✅ Verify CLI works locally
+```bash
+cd /workspaces/agentic-flow/agentic-flow
+npm run build
+node dist/agentdb/cli/agentdb-cli.js --help
+```
+
+2. ✅ Test with npm link
+```bash
+npm link
+npx agentdb --help
+```
+
+3. ✅ Update version in package.json
+
+4. ✅ Publish to npm
+```bash
+npm publish
+```
+
+5. ✅ Test the published version
+```bash
+npx agentdb@latest --help
+```
+
+## What Users Will See
+
+After publishing, when users run `npx agentdb`, they'll see:
+
+```
+█▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █▀▄ █▄▄
+█▀█ █▄█ ██▄ █░▀█ ░█░ █▄▀ █▄█
+
+AgentDB CLI - Frontier Memory Features
+
+USAGE:
+  agentdb <command> <subcommand> [options]
+
+CAUSAL COMMANDS:
+  agentdb causal add-edge ...
+  agentdb causal experiment create ...
+  ...
+
+REFLEXION COMMANDS:
+  agentdb reflexion store ...
+  agentdb reflexion retrieve ...
+  ...
+
+SKILL COMMANDS:
+  agentdb skill create ...
+  agentdb skill search ...
+  ...
+
+[And 8 more command categories with 17 total commands]
+```
+
+## Current Package Structure
+
+```
+agentic-flow/
+├── package.json
+│   ├── "name": "agentic-flow"
+│   ├── "bin": {
+│   │     "agentic-flow": "dist/cli-proxy.js",
+│   │     "agentdb": "dist/agentdb/cli/agentdb-cli.js"  ← THIS
+│   │   }
+├── src/
+│   └── agentdb/
+│       ├── cli/
+│       │   └── agentdb-cli.ts  ← NEW CLI WITH 17 COMMANDS
+│       ├── controllers/
+│       │   ├── CausalMemoryGraph.ts
+│       │   ├── CausalRecall.ts
+│       │   ├── ExplainableRecall.ts
+│       │   ├── NightlyLearner.ts
+│       │   ├── ReflexionMemory.ts
+│       │   └── SkillLibrary.ts
+│       └── ...
+└── dist/
+    └── agentdb/
+        └── cli/
+            └── agentdb-cli.js  ← COMPILED CLI
+```
+
+## Testing Right Now
+
+To test `npx agentdb` locally RIGHT NOW:
+
+```bash
+cd /workspaces/agentic-flow/agentic-flow
+
+# Unlink any old version
+npm unlink -g agentdb 2>/dev/null || true
+npm unlink -g agentic-flow 2>/dev/null || true
+
+# Build and link
+npm run build
+npm link
+
+# Test it
+npx agentdb --help
+
+# Should show the new ASCII banner and 17 commands!
+```
+
+## Quick Test Commands
+
+```bash
+# Store an episode
+AGENTDB_PATH=./test.db npx agentdb reflexion store \
+  "test-1" "my_task" 0.95 true "Success!" "input" "output" 1000 500
+
+# Retrieve it
+AGENTDB_PATH=./test.db npx agentdb reflexion retrieve "my_task" 5 0.5
+
+# Check stats
+AGENTDB_PATH=./test.db npx agentdb db stats
+```
+
+## Summary
+
+✅ **The CLI is ready** - All 17 commands with frontier features are implemented
+✅ **Binary is configured** - package.json has `"agentdb": "dist/agentdb/cli/agentdb-cli.js"`
+✅ **Works locally** - Use `npm link` to test `npx agentdb` now
+🚀 **Ready to publish** - When you publish to npm, `npx agentdb` will work globally