🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
checkpoint: File edit:
rUve6150422422e
diff --git a/v3/@claude-flow/deployment/src/publisher.ts b/v3/@claude-flow/deployment/src/publisher.tsindex 80945f9982..f8f61eb1db 100644--- a/v3/@claude-flow/deployment/src/publisher.ts+++ b/v3/@claude-flow/deployment/src/publisher.ts@@ -3,7 +3,7 @@* Handles npm package publishing with tag support*/-import { execSync } from 'child_process';+import { execSync, execFileSync } from 'child_process';import { readFileSync, existsSync } from 'fs';import { join } from 'path';import type { PublishOptions, PublishResult, PackageInfo } from './types.js';@@ -116,7 +116,7 @@ export class Publisher {*/async checkVersionExists(packageName: string, version: string): Promise<boolean> {try {- const output = this.execCommand(`npm view ${packageName}@${version} version`, true);+ const output = this.execNpmCommand(['view', `${packageName}@${version}`, 'version'], true);return output.trim() === version;} catch {return false;@@ -128,7 +128,7 @@ export class Publisher {*/async getLatestVersion(packageName: string, tag = 'latest'): Promise<string | null> {try {- const output = this.execCommand(`npm view ${packageName}@${tag} version`, true);+ const output = this.execNpmCommand(['view', `${packageName}@${tag}`, 'version'], true);return output.trim();} catch {return null;@@ -140,7 +140,7 @@ export class Publisher {*/async getPackageInfo(packageName: string): Promise<PackageInfo | null> {try {- const output = this.execCommand(`npm view ${packageName} --json`, true);+ const output = this.execNpmCommand(['view', packageName, '--json'], true);return JSON.parse(output);} catch {return null;@@ -152,7 +152,7 @@ export class Publisher {*/async verifyAuth(): Promise<boolean> {try {- const output = this.execCommand('npm whoami', true);+ const output = this.execNpmCommand(['whoami'], true);return output.trim().length > 0;} catch {return false;@@ -164,7 +164,7 @@ export class Publisher {*/async getRegistry(): Promise<string> {try {- const output = this.execCommand('npm config get registry', true);+ const output = this.execNpmCommand(['config', 'get', 'registry'], true);return output.trim();} catch {return 'https://registry.npmjs.org/';@@ -190,9 +190,42 @@ export class Publisher {}/**- * Execute command+ * Execute npm command safely using execFileSync+ */+ private execNpmCommand(args: string[], returnOutput = false): string {+ try {+ // Validate args don't contain shell metacharacters+ for (const arg of args) {+ if (/[;&|`$()<>]/.test(arg)) {+ throw new Error(`Invalid argument: contains shell metacharacters`);+ }+ }+ const output = execFileSync('npm', args, {+ cwd: this.cwd,+ encoding: 'utf-8',+ shell: false,+ stdio: returnOutput ? ['pipe', 'pipe', 'pipe'] : 'inherit'+ });+ return returnOutput ? output : '';+ } catch (error) {+ throw error;+ }+ }++ /**+ * Execute command (for build scripts only - validated)*/private execCommand(cmd: string, returnOutput = false): string {+ // Only allow npm/npx build commands for safety+ const allowedPrefixes = ['npm run ', 'npm ', 'npx ', 'pnpm ', 'yarn '];+ const isAllowed = allowedPrefixes.some(prefix => cmd.startsWith(prefix));+ if (!isAllowed) {+ throw new Error(`Disallowed command: only npm/npx/pnpm/yarn commands are permitted`);+ }+ // Validate no dangerous shell metacharacters+ if (/[;&|`$()<>]/.test(cmd)) {+ throw new Error(`Invalid command: contains shell metacharacters`);+ }try {const output = execSync(cmd, {cwd: this.cwd,@@ -201,9 +234,6 @@ export class Publisher {});return returnOutput ? output : '';} catch (error) {- if (returnOutput && error instanceof Error) {- throw error;- }throw error;}}diff --git a/v3/@claude-flow/hooks/src/reasoningbank/index.ts b/v3/@claude-flow/hooks/src/reasoningbank/index.tsindex b21c92a5d5..75f716aabc 100644--- a/v3/@claude-flow/hooks/src/reasoningbank/index.ts+++ b/v3/@claude-flow/hooks/src/reasoningbank/index.ts@@ -974,10 +974,14 @@ class FallbackEmbeddingService implements IEmbeddingService {// Try agentic-flow ONNX embeddings firsttry {- const { execSync } = await import('child_process');- const result = execSync(- `npx agentic-flow@alpha embeddings generate "${text.replace(/"/g, '\\"').slice(0, 500)}" --format json 2>/dev/null`,- { encoding: 'utf-8', timeout: 10000 }+ const { execFileSync } = await import('child_process');+ // Use execFileSync with shell: false to prevent command injection+ // Pass text as argument array to avoid shell interpolation+ const safeText = text.slice(0, 500).replace(/[\x00-\x1f]/g, ''); // Remove control chars+ const result = execFileSync(+ 'npx',+ ['agentic-flow@alpha', 'embeddings', 'generate', safeText, '--format', 'json'],+ { encoding: 'utf-8', timeout: 10000, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });const parsed = JSON.parse(result);const embedding = new Float32Array(parsed.embedding || parsed);diff --git a/v3/@claude-flow/providers/README.md b/v3/@claude-flow/providers/README.mdnew file mode 100644index 0000000000..863353e9ba--- /dev/null+++ b/v3/@claude-flow/providers/README.md@@ -0,0 +1,574 @@+# @claude-flow/providers++[](https://www.npmjs.com/package/@claude-flow/providers)+[](https://www.npmjs.com/package/@claude-flow/providers)+[](https://opensource.org/licenses/MIT)+[](https://www.typescriptlang.org/)+[](https://github.com/ruvnet/claude-flow)++> Multi-LLM Provider System for Claude Flow V3 - unified interface for Anthropic, OpenAI, Google, Cohere, Ollama, and RuVector with intelligent load balancing, automatic failover, and cost optimization.++## Features++- **6+ LLM Providers** - Anthropic, OpenAI, Google, Cohere, Ollama, RuVector+- **Load Balancing** - Round-robin, latency-based, least-loaded, cost-based strategies+- **Automatic Failover** - Seamless provider switching on failures+- **Request Caching** - LRU cache with configurable TTL+- **Cost Optimization** - Up to 85%+ savings with intelligent routing+- **Streaming Support** - Full streaming for all providers+- **Tool Calling** - Unified tool/function calling interface+- **Health Monitoring** - Real-time provider health checks+- **Cost Tracking** - Per-request and aggregate cost metrics++## Supported Providers & Models++### Anthropic (Claude)+- `claude-3-5-sonnet-20241022`, `claude-3-5-sonnet-latest`+- `claude-3-opus-20240229`+- `claude-3-sonnet-20240229`+- `claude-3-haiku-20240307`++### OpenAI (GPT)+- `gpt-4o`, `gpt-4o-mini`+- `gpt-4-turbo`, `gpt-4`+- `gpt-3.5-turbo`+- `o1-preview`, `o1-mini`, `o3-mini`++### Google (Gemini)+- `gemini-2.0-flash`+- `gemini-1.5-pro`, `gemini-1.5-flash`+- `gemini-pro`++### Cohere+- `command-r-plus`, `command-r`+- `command-light`, `command`++### Ollama (Local)+- `llama3.2`, `llama3.1`+- `mistral`, `mixtral`+- `codellama`, `phi-4`+- `deepseek-coder`++### RuVector+- Custom models via @ruvector/ruvllm++## Installation++```bash+npm install @claude-flow/providers+```++## Quick Start++```typescript+import { createProviderManager } from '@claude-flow/providers';++// Create provider manager with multiple providers+const manager = await createProviderManager({+ providers: [+ {+ provider: 'anthropic',+ apiKey: process.env.ANTHROPIC_API_KEY!,+ model: 'claude-3-5-sonnet-latest',+ },+ {+ provider: 'openai',+ apiKey: process.env.OPENAI_API_KEY!,+ model: 'gpt-4o',+ },+ ],+ loadBalancing: {+ enabled: true,+ strategy: 'cost-based',+ },+ fallback: {+ enabled: true,+ maxAttempts: 2,+ },+ cache: {+ enabled: true,+ ttl: 300000,+ maxSize: 1000,+ },+});++// Make a completion request+const response = await manager.complete({+ messages: [+ { role: 'user', content: 'Hello, how are you?' }+ ],+ maxTokens: 100,+});++console.log('Response:', response.content);+console.log('Provider:', response.provider);+console.log('Cost:', response.cost?.totalCost);+```++## API Reference++### ProviderManager++```typescript+import { ProviderManager, createProviderManager } from '@claude-flow/providers';++// Create and initialize+const manager = await createProviderManager(config);++// Or manually initialize+const manager = new ProviderManager(config);+await manager.initialize();+```++#### Methods++```typescript+// Complete a request+const response = await manager.complete(request, preferredProvider?);++// Stream completion+for await (const event of manager.streamComplete(request, preferredProvider?)) {+ if (event.type === 'content') {+ process.stdout.write(event.delta?.content || '');+ }+}++// Health check all providers+const health = await manager.healthCheck();+health.forEach((result, provider) => {+ console.log(`${provider}: ${result.healthy ? 'OK' : 'FAIL'}`);+});++// Estimate costs across providers+const estimates = await manager.estimateCost(request);+estimates.forEach((estimate, provider) => {+ console.log(`${provider}: $${estimate.estimatedCost.total.toFixed(4)}`);+});++// Get aggregated usage+const usage = await manager.getUsage('day');+console.log(`Total cost: $${usage.cost.total}`);++// Get provider metrics+const metrics = manager.getMetrics();+metrics.forEach((m, provider) => {+ console.log(`${provider}: ${m.latency}ms avg, ${m.errorRate * 100}% errors`);+});++// List available providers+const providers = manager.listProviders();++// Get specific provider+const anthropic = manager.getProvider('anthropic');++// Clear cache+manager.clearCache();++// Shutdown+manager.destroy();+```++### Individual Providers++```typescript+import {+ AnthropicProvider,+ OpenAIProvider,+ GoogleProvider,+ CohereProvider,+ OllamaProvider,+ RuVectorProvider,+} from '@claude-flow/providers';++// Create provider directly+const anthropic = new AnthropicProvider({+ config: {+ provider: 'anthropic',+ apiKey: process.env.ANTHROPIC_API_KEY!,+ model: 'claude-3-5-sonnet-latest',+ temperature: 0.7,+ maxTokens: 1000,+ },+});++await anthropic.initialize();++const response = await anthropic.complete({+ messages: [{ role: 'user', content: 'Hello!' }],+});++// Stream response+for await (const event of anthropic.streamComplete({+ messages: [{ role: 'user', content: 'Tell me a story' }],+})) {+ if (event.type === 'content') {+ process.stdout.write(event.delta?.content || '');+ }+}+```++### Load Balancing Strategies++```typescript+const manager = await createProviderManager({+ providers: [...],+ loadBalancing: {+ enabled: true,+ strategy: 'round-robin', // or 'least-loaded', 'latency-based', 'cost-based'+ },+});+```++| Strategy | Description | Best For |+|----------|-------------|----------|+| `round-robin` | Rotate through providers | Even distribution |+| `least-loaded` | Use provider with lowest load | High throughput |+| `latency-based` | Use fastest provider | Low latency |+| `cost-based` | Use cheapest provider | Cost optimization |++### Automatic Failover++```typescript+const manager = await createProviderManager({+ providers: [...],+ fallback: {+ enabled: true,+ maxAttempts: 3, // Try up to 3 providers+ },+});++// Events for monitoring+manager.on('fallback_success', ({ originalProvider, fallbackProvider, attempts }) => {+ console.log(`Fallback from ${originalProvider} to ${fallbackProvider}`);+});++manager.on('fallback_exhausted', ({ originalProvider, attempts }) => {+ console.error(`All ${attempts} fallback attempts failed`);+});+```++### Request Caching++```typescript+const manager = await createProviderManager({+ providers: [...],+ cache: {+ enabled: true,+ ttl: 300000, // 5 minutes+ maxSize: 1000, // Max cached responses+ },+});++// Cache is keyed by: messages + model + temperature + maxTokens+// Identical requests return cached responses++// Clear cache when needed+manager.clearCache();+```++### Cost Optimization++```typescript+const manager = await createProviderManager({+ providers: [...],+ costOptimization: {+ enabled: true,+ maxCostPerRequest: 0.10, // Max $0.10 per request+ },+});++// Request with cost constraints+const response = await manager.complete({+ messages: [...],+ costConstraints: {+ maxCost: 0.05,+ preferredModels: ['gpt-4o-mini', 'claude-3-haiku-20240307'],+ },+});++// Get cost breakdown+console.log('Cost:', {+ prompt: response.cost?.promptCost,+ completion: response.cost?.completionCost,+ total: response.cost?.totalCost,+ currency: response.cost?.currency,+});+```++### Tool Calling++```typescript+const response = await manager.complete({+ messages: [+ { role: 'user', content: 'What is the weather in San Francisco?' }+ ],+ tools: [+ {+ type: 'function',+ function: {+ name: 'get_weather',+ description: 'Get weather for a location',+ parameters: {+ type: 'object',+ properties: {+ location: { type: 'string', description: 'City name' },+ unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },+ },+ required: ['location'],+ },+ },+ },+ ],+ toolChoice: 'auto',+});++// Check for tool calls+if (response.toolCalls) {+ for (const call of response.toolCalls) {+ console.log('Tool:', call.function.name);+ console.log('Args:', JSON.parse(call.function.arguments));+ }+}+```++### Streaming++```typescript+// Async iterator streaming+for await (const event of manager.streamComplete(request)) {+ switch (event.type) {+ case 'content':+ process.stdout.write(event.delta?.content || '');+ break;+ case 'tool_call':+ console.log('Tool call:', event.delta?.toolCall);+ break;+ case 'error':+ console.error('Error:', event.error);+ break;+ case 'done':+ console.log('\nUsage:', event.usage);+ console.log('Cost:', event.cost);+ break;+ }+}+```++### Multimodal (Vision/Audio)++```typescript+// Image input (OpenAI, Anthropic, Google)+const response = await manager.complete({+ messages: [+ {+ role: 'user',+ content: [+ { type: 'text', text: 'What is in this image?' },+ { type: 'image', imageUrl: 'https://example.com/image.jpg' },+ // or imageBase64: 'base64-encoded-image'+ ],+ },+ ],+});+```++## TypeScript Types++```typescript+import type {+ // Provider types+ LLMProvider,+ LLMModel,+ LLMProviderConfig,+ ILLMProvider,+ ProviderCapabilities,++ // Message types+ LLMMessage,+ LLMContentPart,+ LLMToolCall,+ LLMTool,++ // Request/Response+ LLMRequest,+ LLMResponse,+ LLMStreamEvent,++ // Manager types+ ProviderManagerConfig,+ LoadBalancingStrategy,++ // Status types+ HealthCheckResult,+ ProviderStatus,+ CostEstimate,+ UsageStats,++ // Error types+ LLMProviderError,+ RateLimitError,+ AuthenticationError,+ ModelNotFoundError,+ ProviderUnavailableError,+} from '@claude-flow/providers';+```++## Error Handling++```typescript+import {+ LLMProviderError,+ RateLimitError,+ AuthenticationError,+ isLLMProviderError,+ isRateLimitError,+} from '@claude-flow/providers';++try {+ const response = await manager.complete(request);+} catch (error) {+ if (isRateLimitError(error)) {+ console.log(`Rate limited. Retry after: ${error.retryAfter}ms`);+ } else if (isLLMProviderError(error)) {+ console.log(`Provider error: ${error.code}`);+ console.log(`Retryable: ${error.retryable}`);+ }+}+```++### Error Types++| Error | Code | HTTP | Retryable |+|-------|------|------|-----------|+| `RateLimitError` | `RATE_LIMIT` | 429 | Yes |+| `AuthenticationError` | `AUTHENTICATION` | 401 | No |+| `ModelNotFoundError` | `MODEL_NOT_FOUND` | 404 | No |+| `ProviderUnavailableError` | `PROVIDER_UNAVAILABLE` | 503 | Yes |++## Environment Variables++```bash+# API Keys+ANTHROPIC_API_KEY=sk-ant-...+OPENAI_API_KEY=sk-...+GOOGLE_API_KEY=...+COHERE_API_KEY=...++# Ollama (local)+OLLAMA_BASE_URL=http://localhost:11434++# Optional overrides+ANTHROPIC_BASE_URL=https://api.anthropic.com+OPENAI_BASE_URL=https://api.openai.com/v1+```++## Provider Configuration++### Anthropic++```typescript+{+ provider: 'anthropic',+ apiKey: process.env.ANTHROPIC_API_KEY!,+ model: 'claude-3-5-sonnet-latest',+ temperature: 0.7,+ maxTokens: 4096,+ timeout: 60000,+ retryAttempts: 3,+}+```++### OpenAI++```typescript+{+ provider: 'openai',+ apiKey: process.env.OPENAI_API_KEY!,+ model: 'gpt-4o',+ temperature: 0.7,+ maxTokens: 4096,+ frequencyPenalty: 0,+ presencePenalty: 0,+}+```+++```typescript+{+ provider: 'google',+ apiKey: process.env.GOOGLE_API_KEY!,+ model: 'gemini-1.5-pro',+ temperature: 0.7,+ maxTokens: 8192,+ topK: 40,+}+```++### Cohere++```typescript+{+ provider: 'cohere',+ apiKey: process.env.COHERE_API_KEY!,+ model: 'command-r-plus',+ temperature: 0.7,+ maxTokens: 4000,+}+```++### Ollama (Local)++```typescript+{+ provider: 'ollama',+ apiUrl: 'http://localhost:11434',+ model: 'llama3.2',+ temperature: 0.7,+ maxTokens: 4096,+}+```++## Performance++| Metric | Target |+|--------|--------|+| Provider initialization | <500ms |+| Request routing | <5ms |+| Cache lookup | <1ms |+| Health check | <2s |++## Integration with Claude Flow++```typescript+import { createProviderManager } from '@claude-flow/providers';+import { createUnifiedSwarmCoordinator } from '@claude-flow/swarm';++// Create provider manager+const providers = await createProviderManager({+ providers: [+ { provider: 'anthropic', apiKey: '...', model: 'claude-3-5-sonnet-latest' },+ { provider: 'openai', apiKey: '...', model: 'gpt-4o' },+ ],+ loadBalancing: { enabled: true, strategy: 'cost-based' },+});++// Use with swarm coordinator+const coordinator = createUnifiedSwarmCoordinator({+ // Agents can use provider manager for LLM calls+ extensions: {+ providers,+ },+});+```++## Related Packages++- [@claude-flow/embeddings](../embeddings) - Embedding generation+- [@claude-flow/memory](../memory) - Vector storage and retrieval+- [@claude-flow/swarm](../swarm) - Multi-agent coordination+- [@claude-flow/neural](../neural) - SONA learning integration++## License++MIT