agentic-flow 3.0.0 → 3.1.0

package/docs/guides/PROXY-ARCHITECTURE-AND-EXTENSION.md

@@ -110,6 +110,7 @@ private convertOpenAIStreamToAnthropic(chunk: string): string {
 ```typescript
 import express, { Request, Response } from 'express';
 import { logger } from '../utils/logger.js';
+import { createProxyAuthMiddleware, resolveProxyHost, resolveProxyToken } from './proxy-auth.js';
 
 interface MistralMessage {
   role: 'system' | 'user' | 'assistant';
@@ -124,18 +125,23 @@ interface MistralRequest {
   stream?: boolean;
 }
 
+// Every proxy that holds an upstream key must bind loopback and require a
+// token (3.0.0+). proxy-auth.ts gives you both.
 export class AnthropicToMistralProxy {
   private app: express.Application;
   private mistralApiKey: string;
   private mistralBaseUrl: string;
   private defaultModel: string;
+  private authToken: string;
 
   constructor(config: {
     mistralApiKey: string;
     mistralBaseUrl?: string;
     defaultModel?: string;
+    authToken?: string; // default: AGENTIC_FLOW_PROXY_TOKEN or a random token
   }) {
     this.app = express();
+    this.authToken = config.authToken || resolveProxyToken();
     this.mistralApiKey = config.mistralApiKey;
     this.mistralBaseUrl = config.mistralBaseUrl || 'https://api.mistral.ai/v1';
     this.defaultModel = config.defaultModel || 'mistral-large-latest';
@@ -144,7 +150,13 @@ export class AnthropicToMistralProxy {
     this.setupRoutes();
   }
 
+  public getAuthToken(): string {
+    return this.authToken;
+  }
+
   private setupMiddleware(): void {
+    // Reject callers without the token before parsing their body. /health stays open.
+    this.app.use(createProxyAuthMiddleware(this.authToken));
     this.app.use(express.json({ limit: '50mb' }));
   }
 
@@ -246,10 +258,11 @@ export class AnthropicToMistralProxy {
     };
   }
 
-  public start(port: number): void {
-    this.app.listen(port, () => {
-      logger.info('Mistral proxy started', { port });
-      console.log(`\n✅ Mistral Proxy running at http://localhost:${port}\n`);
+  public start(port: number, host: string = resolveProxyHost()): void {
+    this.app.listen(port, host, () => {
+      logger.info('Mistral proxy started', { port, host });
+      console.log(`\n✅ Mistral Proxy running at http://${host}:${port}`);
+      console.log(`   export ANTHROPIC_API_KEY=${this.authToken}\n`);
     });
   }
 }
@@ -283,7 +296,7 @@ node dist/proxy/anthropic-to-mistral.js
 
 # Terminal 2: Use with Claude Code
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=dummy-key
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 npx agentic-flow --agent coder --task "Write hello world"
 ```
 
@@ -440,7 +453,7 @@ node dist/proxy/anthropic-to-ollama.js
 
 # Terminal 2: Use with agents
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=dummy-key
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 npx agentic-flow --agent coder --task "Write hello world"
 ```
 
@@ -621,7 +634,7 @@ describe('Mistral Proxy', () => {
   it('should convert Anthropic request to Mistral format', async () => {
     const response = await fetch(`http://localhost:${port}/v1/messages`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: { 'Content-Type': 'application/json', 'x-api-key': proxy.getAuthToken() },
       body: JSON.stringify({
         model: 'claude-3-5-sonnet-20241022',
         messages: [{ role: 'user', content: 'Hello!' }],
@@ -672,9 +685,9 @@ if (options.provider === 'mistral' || process.env.USE_MISTRAL) {
   });
   proxy.start(3000);
 
-  // Set environment for SDK
+  // Set environment for SDK; the proxy rejects requests without its token
   process.env.ANTHROPIC_BASE_URL = 'http://localhost:3000';
-  process.env.ANTHROPIC_API_KEY = 'dummy-key';
+  process.env.ANTHROPIC_API_KEY = proxy.getAuthToken();
 }
 ```
 

package/docs/guides/STANDALONE_PROXY_GUIDE.md

@@ -52,7 +52,7 @@ npx agentic-flow proxy --provider openrouter
 ```bash
 # Point Claude Code to the proxy
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key  # Any value works
+export ANTHROPIC_API_KEY='<token printed by the proxy>'  # required; see below
 
 # Now use Claude Code normally
 claude
@@ -63,6 +63,14 @@ claude --agent coder --task "Create a REST API in Python"
 
 **That's it!** Claude Code will now route all requests through the proxy, using Gemini or OpenRouter instead of Anthropic.
 
+**Authentication (3.0.0+).** The proxy binds `127.0.0.1` and rejects any
+`/v1/messages` request without its token, so nobody else on your network can
+spend your provider key. On start it prints a random per-run token; pass it as
+`ANTHROPIC_API_KEY` (sent as `x-api-key`) or as `Authorization: Bearer`. To
+keep the same token across restarts, set `AGENTIC_FLOW_PROXY_TOKEN` before
+starting the proxy and use that value. `AGENTIC_FLOW_PROXY_HOST` changes the
+bind address; only widen it on a network you trust. `/health` needs no token.
+
 ## Usage with Cursor IDE
 
 **Status:** Cursor does not currently support custom `ANTHROPIC_BASE_URL` for Anthropic models.
@@ -79,7 +87,7 @@ npx agentic-flow proxy
 # Configure Cursor
 Settings → API Keys
   Anthropic Base URL: http://localhost:3000
-  Anthropic API Key: sk-ant-proxy-dummy-key
+  Anthropic API Key: <token printed by the proxy>
 ```
 
 ## Full Command Reference
@@ -106,6 +114,8 @@ npx agentic-flow proxy [OPTIONS]
 | `GOOGLE_GEMINI_API_KEY` | Gemini | Your Google Gemini API key |
 | `OPENROUTER_API_KEY` | OpenRouter | Your OpenRouter API key |
 | `COMPLETION_MODEL` | Optional | Override default model |
+| `AGENTIC_FLOW_PROXY_TOKEN` | Optional | Token clients must send (default: random per run, printed on start) |
+| `AGENTIC_FLOW_PROXY_HOST` | Optional | Bind address (default: `127.0.0.1`) |
 
 ## Examples
 
@@ -117,7 +127,7 @@ npx agentic-flow proxy --port 8080
 
 # In another terminal
 export ANTHROPIC_BASE_URL=http://localhost:8080
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 claude
 ```
 
@@ -129,7 +139,7 @@ npx agentic-flow proxy --provider openrouter --model "anthropic/claude-3.5-sonne
 
 # Use Claude Code
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 claude --agent researcher --task "Analyze market trends"
 ```
 
@@ -141,7 +151,7 @@ npx agentic-flow proxy --provider openrouter --model "deepseek/deepseek-chat-v3.
 
 # 98% cost savings vs Claude Sonnet!
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 claude --agent coder --task "Build a web scraper"
 ```
 
@@ -233,7 +243,7 @@ npx agentic-flow proxy
 # Enable MCP in Claude Code
 export ENABLE_CLAUDE_FLOW_SDK=true
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 
 # MCP tools will be forwarded to Gemini/OpenRouter
 claude --agent coder --task "Use memory_store to save config"

package/docs/integrations/FASTMCP_CLI_INTEGRATION.md

@@ -367,7 +367,7 @@ npm run build
 npm publish
 
 # Users can then use:
-npx agentic-flow@latest mcp start
+npx agentic-flow@3.1.0 mcp start
 ```
 
 ## 🚀 Advanced Usage

package/docs/plans/requesty/02-architecture.md

@@ -133,9 +133,8 @@ private async startRequestyProxy(modelOverride?: string): Promise<void> {
 
   process.env.ANTHROPIC_BASE_URL = `http://localhost:${this.proxyPort}`;
 
-  if (!process.env.ANTHROPIC_API_KEY) {
-    process.env.ANTHROPIC_API_KEY = 'sk-ant-proxy-dummy-key';
-  }
+  // The proxy rejects requests without its per-run token (3.0.0+)
+  process.env.ANTHROPIC_API_KEY = proxy.getAuthToken();
 
   console.log(`🔗 Proxy Mode: Requesty`);
   console.log(`🔧 Proxy URL: http://localhost:${this.proxyPort}`);
@@ -478,7 +477,7 @@ User CLI Command
          │
          ├─> Set Environment Variables
          │    ├─ ANTHROPIC_BASE_URL = http://localhost:3000
-         │    └─ ANTHROPIC_API_KEY = sk-ant-proxy-dummy-key
+         │    └─ ANTHROPIC_API_KEY = <proxy's per-run token>
          │
          └─> Execute Agent (claudeAgent.ts)
               │
@@ -932,12 +931,12 @@ Support running Requesty proxy as standalone server:
 
 ```bash
 # Terminal 1 - Run proxy
+export REQUESTY_API_KEY=requesty-xxxxx
 npx agentic-flow proxy --provider requesty --port 3000 --model "openai/gpt-4o-mini"
 
 # Terminal 2 - Use with Claude Code
 export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
-export REQUESTY_API_KEY=requesty-xxxxx
+export ANTHROPIC_API_KEY='<token printed by the proxy>'
 claude
 ```
 

package/docs/plans/requesty/03-implementation-phases.md

@@ -286,10 +286,9 @@ private async startRequestyProxy(modelOverride?: string): Promise<void> {
   // Set ANTHROPIC_BASE_URL to proxy
   process.env.ANTHROPIC_BASE_URL = `http://localhost:${this.proxyPort}`;
 
-  // Set dummy ANTHROPIC_API_KEY for proxy (actual auth uses REQUESTY_API_KEY)
-  if (!process.env.ANTHROPIC_API_KEY) {
-    process.env.ANTHROPIC_API_KEY = 'sk-ant-proxy-dummy-key';
-  }
+  // The proxy rejects requests without its per-run token (3.0.0+);
+  // the upstream call still uses REQUESTY_API_KEY
+  process.env.ANTHROPIC_API_KEY = proxy.getAuthToken();
 
   console.log(`🔗 Proxy Mode: Requesty`);
   console.log(`🔧 Proxy URL: http://localhost:${this.proxyPort}`);

package/docs/plans/requesty/05-migration-guide.md

@@ -258,6 +258,7 @@ npx agentic-flow --agent coder \
 #### Terminal 1 - Start Proxy
 
 ```bash
+export REQUESTY_API_KEY="requesty-xxxxx"
 npx agentic-flow proxy --provider requesty --port 3000
 ```
 
@@ -265,8 +266,7 @@ npx agentic-flow proxy --provider requesty --port 3000
 
 ```bash
 export ANTHROPIC_BASE_URL="http://localhost:3000"
-export ANTHROPIC_API_KEY="sk-ant-proxy-dummy-key"
-export REQUESTY_API_KEY="requesty-xxxxx"
+export ANTHROPIC_API_KEY="<token printed by the proxy>"  # the proxy rejects any other key (3.0.0+)
 
 claude
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "The agentic meta-harness — freeze the model, evolve the harness. An open runtime that routes each query to the cost-optimal model, evolves its own harness (planner/context/reviewer/retry/tool/memory/score policy) and autonomously repairs code, then orchestrates 66 specialized agents, 213 MCP tools, ReasoningBank memory, and multi-agent swarms on top. Built by @ruvnet on the Claude Agent SDK.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/validate-providers.sh

@@ -7,6 +7,9 @@ echo "🧪 Agentic Flow - Provider Validation Suite"
 echo "==========================================="
 echo ""
 
+# Exactly this checkout's version (override with AGENTIC_FLOW_SPEC), never a dist-tag
+AF_SPEC="${AGENTIC_FLOW_SPEC:-agentic-flow@$(node -p "require('$(cd "$(dirname "$0")/.." && pwd)/package.json').version")}"
+
 # Colors
 GREEN='\033[0;32m'
 BLUE='\033[0;34m'
@@ -15,7 +18,7 @@ NC='\033[0m' # No Color
 # Test 1: Anthropic Provider
 if [ -n "$ANTHROPIC_API_KEY" ]; then
     echo -e "${BLUE}1️⃣ Testing Anthropic Provider...${NC}"
-    npx agentic-flow@latest --agent coder --task "Write hello world" --provider anthropic 2>&1 | grep -q "Completed" && \
+    npx "$AF_SPEC" --agent coder --task "Write hello world" --provider anthropic 2>&1 | grep -q "Completed" && \
         echo -e "${GREEN}✅ Anthropic provider works${NC}" || \
         echo "❌ Anthropic provider failed"
 else
@@ -27,19 +30,19 @@ echo ""
 # Test 2: OpenRouter Provider - Meta Llama
 if [ -n "$OPENROUTER_API_KEY" ]; then
     echo -e "${BLUE}2️⃣ Testing OpenRouter - Meta Llama 3.1...${NC}"
-    npx agentic-flow@latest --agent coder --task "Write hello world" --model "meta-llama/llama-3.1-8b-instruct" 2>&1 | grep -q "Completed" && \
+    npx "$AF_SPEC" --agent coder --task "Write hello world" --model "meta-llama/llama-3.1-8b-instruct" 2>&1 | grep -q "Completed" && \
         echo -e "${GREEN}✅ OpenRouter (Meta Llama) works${NC}" || \
         echo "❌ OpenRouter (Meta Llama) failed"
 
     echo ""
     echo -e "${BLUE}3️⃣ Testing OpenRouter - DeepSeek...${NC}"
-    npx agentic-flow@latest --agent coder --task "Write hello world" --model "deepseek/deepseek-chat" 2>&1 | grep -q "Completed" && \
+    npx "$AF_SPEC" --agent coder --task "Write hello world" --model "deepseek/deepseek-chat" 2>&1 | grep -q "Completed" && \
         echo -e "${GREEN}✅ OpenRouter (DeepSeek) works${NC}" || \
         echo "❌ OpenRouter (DeepSeek) failed"
 
     echo ""
     echo -e "${BLUE}4️⃣ Testing OpenRouter - Gemini Free...${NC}"
-    npx agentic-flow@latest --agent coder --task "Write hello world" --model "google/gemini-2.0-flash-exp:free" 2>&1 | grep -q "Completed" && \
+    npx "$AF_SPEC" --agent coder --task "Write hello world" --model "google/gemini-2.0-flash-exp:free" 2>&1 | grep -q "Completed" && \
         echo -e "${GREEN}✅ OpenRouter (Gemini) works${NC}" || \
         echo "❌ OpenRouter (Gemini) failed"
 else