ADR-056: agentic-flow 3.0.0-alpha.1 Integration

Status

Accepted (2026-02-27)

Date

2026-02-27

Context

The agentic-flow package is the upstream coordination engine that powers claude-flow's ReasoningBank, Router, Agent Booster, QUIC transport, and intelligence subsystems. The major version upgrade from 2.0.7 to 3.0.0-alpha.1 introduces breaking changes, new modules, and a complete rewrite of the build pipeline.

Previous State (2.0.7)

• Older SDK integration (@anthropic-ai/sdk ^0.39)
• No WASM modules
• No ReasoningBank pipeline
• No FastMCP 3.x support
• No Federation or Billing subsystems
• Known transitive vulnerabilities (sqlite3, tar)

Upgrade Motivation

1. Zero vulnerabilities — sqlite3 removed from agentdb peer deps, vitest upgraded to v4
2. FastMCP 3.x — Zod-validated MCP tools with streaming support
3. WASM acceleration — ReasoningBank (211 KB) and QUIC transport (127 KB)
4. AgentDB v3 controllers — 8 controllers now fully exported (ADR-055 Phase 2)
5. Claude Agent SDK — @anthropic-ai/claude-agent-sdk ^0.1.5 integration
6. Modern dependencies — Express 5.1, Anthropic SDK 0.65, Zod 3.25

Decision

Upgrade agentic-flow from ^2.0.7 to ^3.0.0-alpha.1 in @claude-flow/cli, preserving all lazy-import patterns and fallback behavior.

Package Overview

Export Subpaths

Module Architecture (37 dist directories)

dist/
├── agentdb/         # AgentDB CLI and controllers
├── agents/          # 7 agent types (claudeAgent, directApi, webResearch, codeReview, data, claudeFlow, claudeAgentDirect)
├── benchmarks/      # Performance benchmarking
├── billing/         # 5-tier metering and subscriptions
├── cli/             # CLI proxy and wrappers
├── config/          # Configuration management
├── coordination/    # Multi-agent coordination primitives
├── core/            # Core engine and types
├── dashboard/       # Monitoring dashboard
├── db/              # Database layer
├── embeddings/      # Vector embedding engine
├── federation/      # EphemeralAgent, FederationHub
├── hooks/           # Hook system (pre/post edit/command/task)
├── intelligence/    # RuVector: SONA, HNSW, EWC++, EmbeddingCache, EmbeddingService
├── llm/             # Multi-provider LLM integration
├── mcp/             # FastMCP 3.x servers + 33+ MCP tools
├── memory/          # Memory management
├── middleware/       # Rate limiting
├── optimizations/   # Performance optimizations
├── orchestration/   # Workflow orchestration
├── packages/        # Sub-package management
├── proxy/           # Anthropic→OpenRouter proxy, QUIC proxy
├── reasoningbank/   # 4-step learning pipeline with WASM
├── router/          # Model routing (4+ providers)
├── routing/         # Request routing
├── sdk/             # E2B, plugins, security, streaming
├── security/        # Input validation, threat detection
├── services/        # Background services
├── swarm/           # Swarm orchestration
├── transport/       # QUIC/UDP transport
├── types/           # TypeScript type definitions
├── utils/           # Shared utilities
├── wasm/            # WASM module loaders
└── workers/         # Background workers

MCP Tools (33+ via FastMCP 3.x)

FastMCP Server Modes

Intelligence Modules

ReasoningBank Modules

Key Dependencies (20 runtime)

Breaking Changes from 2.x

1. Export subpaths: New conditional exports for ./reasoningbank (node vs browser)
2. FastMCP 3.x: All MCP tools migrated from custom protocol to Zod-validated FastMCP
3. WASM requirement: ReasoningBank and QUIC modules load WASM; fallback to JS for environments without WASM support
4. Express 5.1: HTTP transport uses Express 5 (breaking from Express 4.x middleware patterns)
5. agentdb ^1.4.3: New controller exports (HierarchicalMemory, MemoryConsolidation, SemanticRouter, GNNService, RVFOptimizer, MutationGuard, AttestationLog, GuardedVectorBackend)
6. Provider-specific keys: No more fallback from ANTHROPIC_API_KEY to other providers

Integration Surface

Files That Import agentic-flow (Updated)

All imports use lazy dynamic import() with .catch(() => null) fallbacks. The CLI functions correctly without agentic-flow installed — it degrades gracefully to local-only embeddings and no WASM acceleration.

Integration Changes Made

Compatibility Assessment

Version Alignment

Consequences

Positive

1. Zero production vulnerabilities — sqlite3 removed from agentdb peer deps, all transitive vuln chains broken
2. WASM acceleration available — ReasoningBank (211 KB) and QUIC (127 KB) WASM modules for native-speed operations
3. FastMCP 3.x — 33+ Zod-validated MCP tools with proper error handling and streaming
4. Richer intelligence — RuVectorIntelligence with SONA, HNSW, EWC++, Flash Attention
5. Federation support — EphemeralAgent and FederationHub for cross-instance coordination
6. Billing infrastructure — 5-tier metering system for commercial deployment
7. Modern SDK — Claude Agent SDK 0.1.5 for native agent spawning

Negative

1. Package size — 32 MB installed (up from ~18 MB for 2.0.7) due to WASM and expanded module set
2. WASM environment requirement — Some CI environments may not support WASM; fallbacks exist but with reduced performance
3. Alpha stability — 3.0.0-alpha.1 may have API changes before stable release

Risks

1. WASM fallback path: If WASM fails to load, JS fallbacks activate automatically. Performance degrades but functionality is preserved.
2. Express 5 compatibility: HTTP transport uses Express 5. Any middleware that depends on Express 4 patterns needs migration.
3. FastMCP Zod schemas: All MCP tool inputs are now Zod-validated. Invalid inputs get clear error messages instead of silent failures.

Verification

# Verify installation
node -e "require('agentic-flow/package.json').version"  # → 3.0.0-alpha.1

# Verify WASM modules present
ls node_modules/agentic-flow/wasm/reasoningbank/*.wasm  # → 211K
ls node_modules/agentic-flow/wasm/quic/*.wasm           # → 127K

# Verify exports resolve
node -e "import('agentic-flow').then(m => console.log('Core:', !!m))"
node -e "import('agentic-flow/reasoningbank').then(m => console.log('RB:', !!m))"
node -e "import('agentic-flow/router').then(m => console.log('Router:', !!m))"

# Verify CLI tests pass
cd v3/@claude-flow/cli && npm test  # → 445 passed

# Verify zero production vulnerabilities
npm audit --omit=dev  # → 0 vulnerabilities

Related ADRs

• ADR-053: AgentDB v3 Controller Activation — Initial 8 controllers + 6 MCP tools
• ADR-054: RVF-Powered Plugin Marketplace — IPFS plugin registry
• ADR-055: AgentDB Controller Bug Remediation — Fixed 30 security findings, upgraded stubs to real implementations