agentic-flow 1.0.4 → 1.0.6

package/README.md

@@ -40,7 +40,7 @@ Traditional AI frameworks require persistent infrastructure and complex orchestr
 
 ## 🚀 Quick Start
 
-### Local Installation (Recommended for Development)
+### Installation
 
 ```bash
 # Global installation
@@ -48,11 +48,29 @@ npm install -g agentic-flow
 
 # Or use directly with npx (no installation)
 npx agentic-flow --help
+```
 
-# Set your API key
-export ANTHROPIC_API_KEY=sk-ant-...
+### Configuration Wizard (Interactive Setup)
+
+```bash
+# Launch interactive configuration wizard
+npx agentic-flow config
+
+# Or use direct commands
+npx agentic-flow config set ANTHROPIC_API_KEY sk-ant-xxxxx
+npx agentic-flow config set PROVIDER anthropic
+npx agentic-flow config list
 ```
 
+The wizard helps you configure:
+- **API Keys** - Anthropic, OpenRouter with validation
+- **Provider Settings** - Choose default provider (anthropic/openrouter/onnx)
+- **Model Selection** - Set default models
+- **Custom Paths** - Configure agents directory
+- **Advanced Options** - Proxy port, feature flags
+
+All configuration is saved to `.env` with helpful comments.
+
 ### Your First Agent (Local Execution)
 
 ```bash
@@ -429,6 +447,40 @@ Docker: Infrastructure costs (AWS/GCP/Azure) + Claude API costs.*
 
 ## 📋 Commands
 
+### Configuration Management
+
+```bash
+# Interactive configuration wizard
+npx agentic-flow config
+
+# Direct configuration commands
+npx agentic-flow config set ANTHROPIC_API_KEY sk-ant-xxxxx
+npx agentic-flow config set OPENROUTER_API_KEY sk-or-v1-xxxxx
+npx agentic-flow config set PROVIDER openrouter
+npx agentic-flow config set COMPLETION_MODEL meta-llama/llama-3.1-8b-instruct
+
+# View configuration
+npx agentic-flow config list
+npx agentic-flow config get PROVIDER
+
+# Manage configuration
+npx agentic-flow config delete OPENROUTER_API_KEY
+npx agentic-flow config reset
+
+# Get help
+npx agentic-flow config help
+```
+
+**Available Configuration Keys:**
+- `ANTHROPIC_API_KEY` - Anthropic API key (validated: must start with `sk-ant-`)
+- `OPENROUTER_API_KEY` - OpenRouter API key (validated: must start with `sk-or-`)
+- `COMPLETION_MODEL` - Default model name
+- `PROVIDER` - Default provider (anthropic, openrouter, onnx)
+- `AGENTS_DIR` - Custom agents directory path
+- `PROXY_PORT` - Proxy server port (default: 3000)
+- `USE_OPENROUTER` - Force OpenRouter usage (true/false)
+- `USE_ONNX` - Use ONNX local inference (true/false)
+
 ### Basic Operations (Works Locally, Docker, Cloud)
 
 ```bash
@@ -445,12 +497,15 @@ npx agentic-flow --agent coder --task "Build API" --stream
 npx agentic-flow  # Requires TOPIC, DIFF, DATASET env vars
 ```
 
-### Environment Configuration
+### Environment Configuration (Alternative to Config Wizard)
 
 ```bash
-# Required
+# Required (use config wizard instead for better UX)
 export ANTHROPIC_API_KEY=sk-ant-...
 
+# Or use OpenRouter
+export OPENROUTER_API_KEY=sk-or-v1-...
+
 # Agent mode (optional)
 export AGENT=researcher
 export TASK="Your task description"

package/dist/agents/directApiAgent.js

@@ -3,9 +3,24 @@ import Anthropic from '@anthropic-ai/sdk';
 import { logger } from '../utils/logger.js';
 import { withRetry } from '../utils/retry.js';
 import { execSync } from 'child_process';
-const anthropic = new Anthropic({
-    apiKey: process.env.ANTHROPIC_API_KEY
-});
+// Lazy initialize Anthropic client to allow runtime API key validation
+let anthropic = null;
+function getAnthropicClient() {
+    if (!anthropic) {
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        // Validate API key format
+        if (!apiKey) {
+            throw new Error('ANTHROPIC_API_KEY is required but not set');
+        }
+        if (!apiKey.startsWith('sk-ant-')) {
+            throw new Error(`Invalid ANTHROPIC_API_KEY format. Expected format: sk-ant-...\n` +
+                `Got: ${apiKey.substring(0, 10)}...\n\n` +
+                `Please check your API key at: https://console.anthropic.com/settings/keys`);
+        }
+        anthropic = new Anthropic({ apiKey });
+    }
+    return anthropic;
+}
 // Define claude-flow tools as native Anthropic tool definitions
 const claudeFlowTools = [
     {
@@ -179,13 +194,34 @@ export async function directApiAgent(agent, input, onStream) {
         // Agentic loop: keep calling API until no more tool uses
         while (toolUseCount < maxToolUses) {
             logger.debug('API call iteration', { toolUseCount, messagesLength: messages.length });
-            const response = await anthropic.messages.create({
-                model: 'claude-sonnet-4-5-20250929',
-                max_tokens: 8192,
-                system: agent.systemPrompt || 'You are a helpful AI assistant.',
-                messages,
-                tools: claudeFlowTools
-            });
+            const client = getAnthropicClient();
+            let response;
+            try {
+                response = await client.messages.create({
+                    model: 'claude-sonnet-4-5-20250929',
+                    max_tokens: 8192,
+                    system: agent.systemPrompt || 'You are a helpful AI assistant.',
+                    messages,
+                    tools: claudeFlowTools
+                });
+            }
+            catch (error) {
+                // Enhance authentication errors with helpful guidance
+                if (error?.status === 401) {
+                    const apiKey = process.env.ANTHROPIC_API_KEY;
+                    throw new Error(`❌ Anthropic API authentication failed (401)\n\n` +
+                        `Your API key is invalid, expired, or lacks permissions.\n` +
+                        `Current key: ${apiKey?.substring(0, 15)}...\n\n` +
+                        `Please:\n` +
+                        `  1. Check your key at: https://console.anthropic.com/settings/keys\n` +
+                        `  2. Verify it's not expired\n` +
+                        `  3. Ensure it has proper permissions\n` +
+                        `  4. Update your .env file with: ANTHROPIC_API_KEY=sk-ant-...\n\n` +
+                        `Alternative: Use OpenRouter instead (--model "meta-llama/llama-3.1-8b-instruct")\n` +
+                        `Or use local ONNX (--provider onnx)`);
+                }
+                throw error;
+            }
             logger.debug('API response', {
                 stopReason: response.stop_reason,
                 contentBlocks: response.content.length

package/dist/cli/config-wizard.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+/**
+ * Interactive CLI wizard for agentic-flow configuration
+ * Supports both interactive mode and direct CLI arguments
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { createInterface } from 'readline';
+const CONFIG_DEFINITIONS = [
+    {
+        key: 'ANTHROPIC_API_KEY',
+        value: '',
+        description: 'Anthropic API key for Claude models (sk-ant-...)',
+        required: false,
+        validation: (val) => val.startsWith('sk-ant-') || 'Must start with sk-ant-'
+    },
+    {
+        key: 'OPENROUTER_API_KEY',
+        value: '',
+        description: 'OpenRouter API key for alternative models (sk-or-v1-...)',
+        required: false,
+        validation: (val) => val.startsWith('sk-or-') || 'Must start with sk-or-'
+    },
+    {
+        key: 'COMPLETION_MODEL',
+        value: 'claude-sonnet-4-5-20250929',
+        description: 'Default model for completions',
+        required: false
+    },
+    {
+        key: 'PROVIDER',
+        value: 'anthropic',
+        description: 'Default provider (anthropic, openrouter, onnx)',
+        required: false,
+        validation: (val) => ['anthropic', 'openrouter', 'onnx'].includes(val) || 'Must be anthropic, openrouter, or onnx'
+    },
+    {
+        key: 'AGENTS_DIR',
+        value: '',
+        description: 'Custom agents directory path (optional)',
+        required: false
+    },
+    {
+        key: 'PROXY_PORT',
+        value: '3000',
+        description: 'Proxy server port for OpenRouter',
+        required: false,
+        validation: (val) => !isNaN(parseInt(val)) || 'Must be a number'
+    },
+    {
+        key: 'USE_OPENROUTER',
+        value: 'false',
+        description: 'Force OpenRouter usage (true/false)',
+        required: false,
+        validation: (val) => ['true', 'false'].includes(val) || 'Must be true or false'
+    },
+    {
+        key: 'USE_ONNX',
+        value: 'false',
+        description: 'Use ONNX local inference (true/false)',
+        required: false,
+        validation: (val) => ['true', 'false'].includes(val) || 'Must be true or false'
+    }
+];
+export class ConfigWizard {
+    envPath;
+    currentConfig = new Map();
+    constructor(envPath) {
+        this.envPath = envPath || resolve(process.cwd(), '.env');
+        this.loadExistingConfig();
+    }
+    loadExistingConfig() {
+        if (existsSync(this.envPath)) {
+            const content = readFileSync(this.envPath, 'utf-8');
+            content.split('\n').forEach(line => {
+                const trimmed = line.trim();
+                if (trimmed && !trimmed.startsWith('#')) {
+                    const [key, ...valueParts] = trimmed.split('=');
+                    const value = valueParts.join('=');
+                    if (key && value) {
+                        this.currentConfig.set(key, value);
+                    }
+                }
+            });
+        }
+    }
+    saveConfig() {
+        const lines = [
+            '# Agentic Flow Configuration',
+            '# Generated by agentic-flow config wizard',
+            `# Created: ${new Date().toISOString()}`,
+            ''
+        ];
+        CONFIG_DEFINITIONS.forEach(def => {
+            const value = this.currentConfig.get(def.key) || def.value;
+            if (value) {
+                lines.push(`# ${def.description}`);
+                lines.push(`${def.key}=${value}`);
+                lines.push('');
+            }
+        });
+        // Preserve other env vars not in CONFIG_DEFINITIONS
+        this.currentConfig.forEach((value, key) => {
+            if (!CONFIG_DEFINITIONS.find(d => d.key === key)) {
+                lines.push(`${key}=${value}`);
+            }
+        });
+        writeFileSync(this.envPath, lines.join('\n'), 'utf-8');
+    }
+    // Interactive wizard mode
+    async runInteractive() {
+        console.log('\n🤖 Agentic Flow Configuration Wizard\n');
+        console.log('Configure your environment variables for agentic-flow.');
+        console.log('Press Enter to keep current value, or type new value.\n');
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+        const question = (prompt) => {
+            return new Promise((resolve) => {
+                rl.question(prompt, resolve);
+            });
+        };
+        try {
+            for (const def of CONFIG_DEFINITIONS) {
+                const currentValue = this.currentConfig.get(def.key) || def.value;
+                const displayValue = currentValue
+                    ? (def.key.includes('KEY') ? `${currentValue.substring(0, 15)}...` : currentValue)
+                    : '(not set)';
+                console.log(`\n📝 ${def.key}`);
+                console.log(`   ${def.description}`);
+                let input;
+                let isValid = false;
+                while (!isValid) {
+                    input = await question(`   Current: ${displayValue}\n   New value: `);
+                    // Keep current if empty
+                    if (!input.trim()) {
+                        input = currentValue;
+                    }
+                    // Validate if validator exists
+                    if (input && def.validation) {
+                        const validationResult = def.validation(input);
+                        if (validationResult === true) {
+                            isValid = true;
+                        }
+                        else {
+                            console.log(`   ❌ Invalid: ${validationResult}`);
+                        }
+                    }
+                    else {
+                        isValid = true;
+                    }
+                    if (isValid && input) {
+                        this.currentConfig.set(def.key, input);
+                    }
+                    else if (isValid && !input) {
+                        // Remove if empty
+                        this.currentConfig.delete(def.key);
+                    }
+                }
+            }
+            console.log('\n💾 Saving configuration...');
+            this.saveConfig();
+            console.log(`✅ Configuration saved to: ${this.envPath}\n`);
+            // Show summary
+            this.showSummary();
+        }
+        finally {
+            rl.close();
+        }
+    }
+    // Direct CLI mode - set single value
+    set(key, value) {
+        const def = CONFIG_DEFINITIONS.find(d => d.key === key);
+        if (!def) {
+            throw new Error(`Unknown configuration key: ${key}\nAvailable keys: ${CONFIG_DEFINITIONS.map(d => d.key).join(', ')}`);
+        }
+        // Validate
+        if (def.validation) {
+            const result = def.validation(value);
+            if (result !== true) {
+                throw new Error(`Invalid value for ${key}: ${result}`);
+            }
+        }
+        this.currentConfig.set(key, value);
+        this.saveConfig();
+        console.log(`✅ Set ${key}=${value.substring(0, 20)}${value.length > 20 ? '...' : ''}`);
+    }
+    // Get single value
+    get(key) {
+        const value = this.currentConfig.get(key);
+        if (value) {
+            // Mask API keys
+            if (key.includes('KEY')) {
+                console.log(`${key}=${value.substring(0, 15)}...`);
+            }
+            else {
+                console.log(`${key}=${value}`);
+            }
+        }
+        else {
+            console.log(`${key} is not set`);
+        }
+    }
+    // Delete value
+    delete(key) {
+        if (this.currentConfig.has(key)) {
+            this.currentConfig.delete(key);
+            this.saveConfig();
+            console.log(`✅ Deleted ${key}`);
+        }
+        else {
+            console.log(`❌ ${key} is not set`);
+        }
+    }
+    // List all values
+    list() {
+        console.log('\n📋 Current Configuration:\n');
+        CONFIG_DEFINITIONS.forEach(def => {
+            const value = this.currentConfig.get(def.key);
+            const displayValue = value
+                ? (def.key.includes('KEY') ? `${value.substring(0, 15)}...` : value)
+                : '(not set)';
+            console.log(`${def.key.padEnd(25)} = ${displayValue}`);
+            console.log(`  ${def.description}`);
+            console.log('');
+        });
+    }
+    // Show configuration summary
+    showSummary() {
+        console.log('📊 Configuration Summary:\n');
+        const hasAnthropic = this.currentConfig.has('ANTHROPIC_API_KEY');
+        const hasOpenRouter = this.currentConfig.has('OPENROUTER_API_KEY');
+        const provider = this.currentConfig.get('PROVIDER') || 'anthropic';
+        console.log('Providers configured:');
+        console.log(`  ${hasAnthropic ? '✅' : '❌'} Anthropic (Claude)`);
+        console.log(`  ${hasOpenRouter ? '✅' : '❌'} OpenRouter (Alternative models)`);
+        console.log(`  ⚙️  ONNX (Local inference) - always available`);
+        console.log('');
+        console.log(`Default provider: ${provider}`);
+        console.log('');
+        if (!hasAnthropic && !hasOpenRouter) {
+            console.log('⚠️  Warning: No API keys configured!');
+            console.log('   You can use ONNX local inference, but quality may be limited.');
+            console.log('   Run with --provider onnx to use local inference.\n');
+        }
+        console.log('Next steps:');
+        console.log('  npx agentic-flow --list              # List available agents');
+        console.log('  npx agentic-flow --agent coder --task "Your task"  # Run agent');
+        console.log('');
+    }
+    // Reset to defaults
+    reset() {
+        console.log('⚠️  Resetting configuration to defaults...');
+        this.currentConfig.clear();
+        CONFIG_DEFINITIONS.forEach(def => {
+            if (def.value) {
+                this.currentConfig.set(def.key, def.value);
+            }
+        });
+        this.saveConfig();
+        console.log('✅ Configuration reset to defaults');
+    }
+}
+// CLI handler
+export async function handleConfigCommand(args) {
+    const command = args[0];
+    const wizard = new ConfigWizard();
+    switch (command) {
+        case undefined:
+        case 'wizard':
+        case 'interactive':
+            await wizard.runInteractive();
+            break;
+        case 'set':
+            if (args.length < 3) {
+                console.error('Usage: config set <KEY> <VALUE>');
+                process.exit(1);
+            }
+            wizard.set(args[1], args[2]);
+            break;
+        case 'get':
+            if (args.length < 2) {
+                console.error('Usage: config get <KEY>');
+                process.exit(1);
+            }
+            wizard.get(args[1]);
+            break;
+        case 'delete':
+        case 'remove':
+            if (args.length < 2) {
+                console.error('Usage: config delete <KEY>');
+                process.exit(1);
+            }
+            wizard.delete(args[1]);
+            break;
+        case 'list':
+            wizard.list();
+            break;
+        case 'reset':
+            wizard.reset();
+            break;
+        case 'help':
+            printConfigHelp();
+            break;
+        default:
+            console.error(`Unknown config command: ${command}`);
+            printConfigHelp();
+            process.exit(1);
+    }
+}
+function printConfigHelp() {
+    console.log(`
+🤖 Agentic Flow Configuration Manager
+
+USAGE:
+  npx agentic-flow config [COMMAND] [OPTIONS]
+
+COMMANDS:
+  (none), wizard, interactive  Launch interactive configuration wizard
+  set <KEY> <VALUE>           Set a configuration value
+  get <KEY>                   Get a configuration value
+  delete <KEY>                Delete a configuration value
+  list                        List all configuration values
+  reset                       Reset to default configuration
+  help                        Show this help message
+
+EXAMPLES:
+  # Interactive wizard
+  npx agentic-flow config
+
+  # Direct commands
+  npx agentic-flow config set ANTHROPIC_API_KEY sk-ant-xxxxx
+  npx agentic-flow config set PROVIDER openrouter
+  npx agentic-flow config get PROVIDER
+  npx agentic-flow config list
+  npx agentic-flow config delete OPENROUTER_API_KEY
+
+AVAILABLE CONFIGURATION KEYS:
+  ANTHROPIC_API_KEY     - Anthropic API key (sk-ant-...)
+  OPENROUTER_API_KEY    - OpenRouter API key (sk-or-v1-...)
+  COMPLETION_MODEL      - Default model name
+  PROVIDER              - Default provider (anthropic, openrouter, onnx)
+  AGENTS_DIR            - Custom agents directory
+  PROXY_PORT            - Proxy server port (default: 3000)
+  USE_OPENROUTER        - Force OpenRouter (true/false)
+  USE_ONNX              - Use ONNX local inference (true/false)
+
+For more information: https://github.com/ruvnet/agentic-flow
+  `);
+}
+// If run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const args = process.argv.slice(2);
+    handleConfigCommand(args).catch(err => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}

package/dist/cli-proxy.js

@@ -9,6 +9,7 @@ import { logger } from "./utils/logger.js";
 import { parseArgs } from "./utils/cli.js";
 import { getAgent, listAgents } from "./utils/agentLoader.js";
 import { directApiAgent } from "./agents/directApiAgent.js";
+import { handleConfigCommand } from "./cli/config-wizard.js";
 import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -29,6 +30,12 @@ class AgenticFlowCLI {
             this.listAgents();
             process.exit(0);
         }
+        if (options.mode === 'config') {
+            // Handle config wizard
+            const configArgs = process.argv.slice(3); // Skip 'node', 'cli-proxy.js', 'config'
+            await handleConfigCommand(configArgs);
+            process.exit(0);
+        }
         if (options.mode === 'mcp') {
             // Run standalone MCP server directly
             const { spawn } = await import('child_process');
@@ -226,10 +233,19 @@ USAGE:
   npx agentic-flow [COMMAND] [OPTIONS]
 
 COMMANDS:
+  config [subcommand]     Manage environment configuration (interactive wizard)
   mcp <command> [server]  Manage MCP servers (start, stop, status, list)
   --list, -l              List all available agents
   --agent, -a <name>      Run specific agent mode
 
+CONFIG COMMANDS:
+  npx agentic-flow config              # Interactive wizard
+  npx agentic-flow config set KEY VAL  # Set configuration value
+  npx agentic-flow config get KEY      # Get configuration value
+  npx agentic-flow config list         # List all configuration
+  npx agentic-flow config delete KEY   # Delete configuration value
+  npx agentic-flow config reset        # Reset to defaults
+
 MCP COMMANDS:
   npx agentic-flow mcp start [server]    Start MCP server(s)
   npx agentic-flow mcp stop [server]     Stop MCP server(s)

package/dist/mcp/standalone-stdio.js

@@ -3,10 +3,6 @@
 import { FastMCP } from 'fastmcp';
 import { z } from 'zod';
 import { execSync } from 'child_process';
-import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 // Suppress FastMCP internal warnings for cleaner output
 const originalConsoleWarn = console.warn;
 console.warn = (...args) => {
@@ -23,7 +19,7 @@ console.error('🚀 Starting Agentic-Flow MCP Server (stdio)...');
 console.error('📦 Local agentic-flow tools available');
 const server = new FastMCP({
     name: 'agentic-flow',
-    version: '1.0.3'
+    version: '1.0.6'
 });
 // Tool: Run agentic-flow agent
 server.addTool({
@@ -36,12 +32,12 @@ server.addTool({
     }),
     execute: async ({ agent, task, stream }) => {
         try {
-            const cliPath = resolve(__dirname, '../../cli-proxy.js');
-            const cmd = `node "${cliPath}" --agent "${agent}" --task "${task}"${stream ? ' --stream' : ''}`;
+            // Use npx to run agentic-flow from npm registry
+            const cmd = `npx --yes agentic-flow --agent "${agent}" --task "${task}"${stream ? ' --stream' : ''}`;
             const result = execSync(cmd, {
                 encoding: 'utf-8',
                 maxBuffer: 10 * 1024 * 1024,
-                cwd: resolve(__dirname, '../..')
+                timeout: 300000 // 5 minute timeout
             });
             return JSON.stringify({
                 success: true,
@@ -62,11 +58,12 @@ server.addTool({
     parameters: z.object({}),
     execute: async () => {
         try {
-            const cliPath = resolve(__dirname, '../../cli-proxy.js');
-            const cmd = `node "${cliPath}" --mode list`;
+            // Use npx to run agentic-flow from npm registry
+            const cmd = `npx --yes agentic-flow --list`;
             const result = execSync(cmd, {
                 encoding: 'utf-8',
-                cwd: resolve(__dirname, '../..')
+                maxBuffer: 5 * 1024 * 1024,
+                timeout: 30000
             });
             return JSON.stringify({
                 success: true,

package/dist/utils/cli.js

@@ -11,6 +11,11 @@ export function parseArgs() {
         options.mcpServer = args[2] || 'all'; // default to all servers
         return options;
     }
+    // Check for config command
+    if (args[0] === 'config') {
+        options.mode = 'config';
+        return options;
+    }
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         switch (arg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 111 MCP tools, 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",