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

package/agentic-flow/docs/plans/agent-booster-cli-integration.md

@@ -0,0 +1,317 @@
+# Agent Booster CLI Integration Plan
+
+## Current State
+
+### What Works ✅
+- **MCP Server**: 3 Agent Booster tools available via `standalone-stdio.js`
+- **Standalone CLI**: `agent-booster` package works with JSON stdin
+- **Integration**: Uses `npx --yes agent-booster` (no dependency needed)
+
+### What Doesn't Work ❌
+- **CLI `--agent` mode**: `npx agentic-flow --agent coder` doesn't use Agent Booster
+- **Flag is cosmetic**: `--agent-booster` just prints info, doesn't integrate
+- **Performance**: Takes 26s instead of <1s for simple var→const edits
+
+## Problem Analysis
+
+### Current Flow (CLI Mode)
+```
+User: npx agentic-flow --agent coder --task "convert var to const"
+  ↓
+CLI Wrapper (claude-code-wrapper.ts)
+  ↓ Prints Agent Booster info (but doesn't integrate)
+  ↓
+Agent Executor (directApiAgent.ts)
+  ↓ Calls LLM with Edit tool
+  ↓
+LLM Response (26 seconds)
+  ↓
+File modified using LLM-generated edit
+```
+
+### Desired Flow (with Agent Booster)
+```
+User: npx agentic-flow --agent coder --task "convert var to const" --agent-booster
+  ↓
+CLI Wrapper
+  ↓ Pass agent-booster flag to agent
+  ↓
+Agent Executor
+  ↓ Detect if task is code edit
+  ↓
+Try Agent Booster first
+  ├─ High confidence (≥70%) → Apply edit (85ms)
+  └─ Low confidence (<70%) → Fallback to LLM (26s)
+```
+
+## Implementation Challenges
+
+### Challenge 1: CLI vs MCP Architecture
+
+**Problem**: Agent Booster is designed for **exact code replacements**, but CLI agents receive **vague natural language** tasks.
+
+Example:
+```bash
+# User input (vague)
+npx agentic-flow --agent coder --task "convert var to const in utils.js"
+
+# What Agent Booster needs (exact)
+{"code":"var x = 1;","edit":"const x = 1;"}
+```
+
+**Solution**: We need an intermediary step that:
+1. Reads the file
+2. Uses LLM to generate exact code replacement
+3. Passes to Agent Booster for fast application
+
+But this doesn't save time! We still need the LLM to generate the exact edit.
+
+### Challenge 2: When Agent Booster Actually Helps
+
+Agent Booster is fast **only** when you already have the exact code replacement:
+
+| Scenario | Agent Booster Helps? | Why |
+|----------|---------------------|-----|
+| User provides exact code | ✅ Yes | Skip LLM entirely (85ms vs 26s) |
+| User provides file + vague task | ❌ No | Still need LLM to generate edit |
+| Batch edits with pattern | ⚠️ Maybe | Need pattern detection first |
+
+### Challenge 3: Remote Package Installation
+
+**Current approach**: `npx --yes agent-booster` downloads on first use
+
+**Issues**:
+- 30s timeout for download
+- Network dependency
+- User doesn't know it's downloading
+- Fails in air-gapped environments
+
+**Better approach**: Add `agent-booster` as optional dependency
+
+## Proposed Solutions
+
+### Option 1: Add Pre-Processing Step (Hybrid)
+
+**Pros:**
+- Works with vague natural language
+- Can leverage Agent Booster when applicable
+- Graceful fallback to LLM
+
+**Cons:**
+- Complex flow
+- LLM still needed for generating edits
+- Minimal time savings (only skips LLM execution phase)
+
+**Implementation:**
+```typescript
+async function executeWithAgentBooster(task: string, file: string) {
+  // Step 1: Use fast LLM to generate exact edit
+  const edit = await generateExactEdit(task, file);  // 5-10s
+
+  // Step 2: Try Agent Booster
+  const result = await tryAgentBooster(edit);
+
+  if (result.confidence >= 0.7) {
+    return result;  // 85ms for applying
+  }
+
+  // Step 3: Fallback to full LLM
+  return await executeLLMAgent(task, file);  // 26s
+}
+```
+
+**Time saved**: ~1-2s (only application phase)
+
+### Option 2: Add Dependency (Simple)
+
+**Pros:**
+- No network delays
+- Works offline
+- Predictable behavior
+
+**Cons:**
+- Increases package size (1.4MB for WASM)
+- Installation time increased
+- Makes agent-booster non-optional
+
+**Implementation:**
+```json
+{
+  "dependencies": {
+    "agent-booster": "^0.1.1"
+  }
+}
+```
+
+### Option 3: Keep MCP-Only (Current State)
+
+**Pros:**
+- Clean separation of concerns
+- MCP tools work perfectly for exact edits
+- CLI agents work perfectly for reasoning
+- No complexity added
+
+**Cons:**
+- CLI users don't get Agent Booster performance
+- `--agent-booster` flag is misleading
+
+**Implementation:**
+- Remove `--agent-booster` flag from CLI
+- Update docs to clarify MCP-only
+- Focus on MCP integration quality
+
+### Option 4: Smart Pattern Detection
+
+**Pros:**
+- Detects simple patterns (var→const, add types)
+- Can use Agent Booster without LLM
+- Significant time savings for common tasks
+
+**Cons:**
+- Limited to known patterns
+- Complex pattern detection logic
+- May miss edge cases
+
+**Implementation:**
+```typescript
+async function detectPatternAndApply(task: string, file: string) {
+  // Detect common patterns
+  if (task.includes('var') && task.includes('const')) {
+    return await applyVarToConstPattern(file);  // 85ms
+  }
+
+  if (task.includes('add types') || task.includes('TypeScript')) {
+    return await applyTypeAnnotationPattern(file);  // 85ms + pattern detection
+  }
+
+  // Fall back to full LLM
+  return await executeLLMAgent(task, file);  // 26s
+}
+```
+
+## Recommendation
+
+**Choose Option 3: Keep MCP-Only**
+
+**Reasoning:**
+
+1. **Agent Booster's strength**: Exact code replacements
+   - Perfect for MCP tools (Claude generates exact code)
+   - Poor fit for CLI (user provides vague natural language)
+
+2. **Time savings reality**:
+   - MCP: 85ms (skip LLM entirely) ✅
+   - CLI: Still need LLM for edit generation = minimal savings ❌
+
+3. **User experience**:
+   - MCP users get 728x speedup for exact edits
+   - CLI users get full LLM reasoning for complex tasks
+   - Each mode uses the right tool for the job
+
+4. **Maintenance**:
+   - Simple, clean architecture
+   - No complex hybrid flows
+   - Focus on quality, not gimmicks
+
+### What to Change
+
+1. **Remove misleading flag**:
+   ```typescript
+   // DELETE: .option('--agent-booster', ...)
+   ```
+
+2. **Update README**:
+   ```markdown
+   ## Agent Booster
+
+   Agent Booster provides 728x faster code edits through the **MCP server** (for Claude Desktop/Cursor).
+
+   ⚠️ **CLI users**: The `--agent` mode uses standard LLM reasoning and does NOT use Agent Booster. This is by design - use Claude Desktop/Cursor for Agent Booster performance.
+   ```
+
+3. **Focus on MCP quality**:
+   - Improve MCP tool descriptions
+   - Add more examples
+   - Better error messages
+
+## Alternative: Limited CLI Integration
+
+If we **must** have CLI integration, here's the minimal viable approach:
+
+### Pattern-Based CLI (Limited Scope)
+
+Only support explicit patterns with `--pattern` flag:
+
+```bash
+# Explicit pattern (works with Agent Booster)
+npx agentic-flow --agent coder --pattern var-to-const --file utils.js
+# Result: 85ms
+
+# Vague task (uses LLM)
+npx agentic-flow --agent coder --task "improve error handling" --file utils.js
+# Result: 26s
+```
+
+**Supported patterns**:
+- `var-to-const`: Convert var to const/let
+- `add-types`: Add TypeScript type annotations
+- `arrow-functions`: Convert function() to () =>
+- `async-await`: Convert callbacks to async/await
+
+**Implementation**:
+```typescript
+const patterns = {
+  'var-to-const': async (file: string) => {
+    const code = fs.readFileSync(file, 'utf-8');
+    const edit = code.replace(/\bvar\b/g, 'const'); // Simplified
+    return await applyAgentBooster(code, edit);
+  }
+};
+
+if (options.pattern && patterns[options.pattern]) {
+  return await patterns[options.pattern](options.file);
+}
+```
+
+**Pros**:
+- Clear what works with Agent Booster
+- Fast for supported patterns
+- No false expectations
+
+**Cons**:
+- Limited pattern support
+- Requires pattern knowledge
+- Not natural language
+
+## Validation Strategy
+
+Before implementing ANY solution:
+
+1. **Test locally** with exact use cases
+2. **Publish to test npm registry** or local registry
+3. **Install from npm** (not local files)
+4. **Test in clean environment** (Docker container)
+5. **Verify performance claims** with real benchmarks
+
+### Test Checklist
+
+- [ ] MCP server tools work remotely (Claude Desktop)
+- [ ] CLI `--agent` mode works as expected
+- [ ] `npx agent-booster` CLI works standalone
+- [ ] No network timeouts or failures
+- [ ] Performance matches claims
+- [ ] Works in air-gapped environment (if dependency)
+
+## Conclusion
+
+**Recommended approach**: Keep Agent Booster as **MCP-only** (Option 3)
+
+**Why**: Agent Booster is designed for exact code replacements, which works perfectly with MCP tools but poorly with CLI natural language tasks. Trying to force CLI integration would add complexity without significant benefit.
+
+**Action items**:
+1. Remove misleading `--agent-booster` CLI flag
+2. Update documentation to clarify MCP-only
+3. Focus on making MCP integration excellent
+4. Let CLI mode use standard LLM reasoning (what it's good at)
+
+This keeps the architecture clean, user expectations clear, and each mode focused on what it does best.

package/agentic-flow/docs/plans/requesty/00-overview.md

@@ -0,0 +1,176 @@
+# Requesty.ai Integration - Overview
+
+## Executive Summary
+
+This document outlines the plan to integrate Requesty.ai as a new provider in the agentic-flow project, following the same architectural pattern as the existing OpenRouter integration.
+
+### What is Requesty.ai?
+
+Requesty.ai is a unified AI gateway that provides:
+- **300+ AI Models** - Access to models from OpenAI, Anthropic, Google, and other providers
+- **OpenAI-Compatible API** - Drop-in replacement for OpenAI SDK with `base_url` override
+- **Cost Optimization** - 80% cost savings through intelligent routing and caching
+- **Built-in Analytics** - Real-time usage tracking and performance monitoring
+- **Enterprise Features** - Zero downtime guarantee, automatic failover, load balancing
+
+### Integration Goals
+
+1. **Provider Parity** - Requesty should work alongside Anthropic, OpenRouter, Gemini, and ONNX
+2. **Minimal Code Changes** - Leverage existing proxy pattern from OpenRouter
+3. **Model Flexibility** - Support 300+ models through Requesty's router
+4. **Tool Support** - Maintain full MCP tool calling compatibility
+5. **Cost Optimization** - Enable users to access cheaper models with same quality
+
+### Key Differentiators from OpenRouter
+
+| Feature | OpenRouter | Requesty.ai |
+|---------|-----------|-------------|
+| Model Count | 100+ | 300+ |
+| API Format | OpenAI `/chat/completions` | OpenAI `/chat/completions` |
+| Base URL | `https://openrouter.ai/api/v1` | `https://router.requesty.ai/v1` |
+| Authentication | `Authorization: Bearer sk-or-...` | `Authorization: Bearer requesty-...` |
+| Cost Savings | ~90% vs Claude | ~80% vs Claude |
+| Tool Calling | Native OpenAI format | Native OpenAI format |
+| Unique Features | Leaderboard tracking | Auto-routing, caching, analytics |
+
+### Strategic Benefits
+
+1. **Provider Diversity** - Reduces dependency on single gateway
+2. **Model Access** - 300+ models vs OpenRouter's 100+
+3. **Cost Flexibility** - Users can choose based on price/performance
+4. **Redundancy** - Fallback option if OpenRouter has issues
+5. **Enterprise Features** - Built-in analytics and monitoring
+
+## Integration Approach
+
+### Architecture Pattern
+
+Requesty will follow the **same proxy architecture** as OpenRouter:
+
+```
+User Request (Anthropic Format)
+    ↓
+Agentic Flow CLI
+    ↓
+Provider Detection (--provider requesty)
+    ↓
+Anthropic-to-Requesty Proxy Server
+    ↓
+Format Conversion (Anthropic → OpenAI)
+    ↓
+Requesty Router (https://router.requesty.ai/v1)
+    ↓
+Model Execution (300+ models)
+    ↓
+Response Conversion (OpenAI → Anthropic)
+    ↓
+Return to User
+```
+
+### File Structure
+
+New files to create:
+```
+agentic-flow/
+├── src/
+│   └── proxy/
+│       └── anthropic-to-requesty.ts    # NEW - Requesty proxy (clone from OpenRouter)
+├── docs/
+│   └── plans/
+│       └── requesty/
+│           ├── 00-overview.md          # This file
+│           ├── 01-api-research.md
+│           ├── 02-architecture.md
+│           ├── 03-implementation-phases.md
+│           ├── 04-testing-strategy.md
+│           └── 05-migration-guide.md
+```
+
+Existing files to modify:
+```
+agentic-flow/
+├── src/
+│   ├── cli-proxy.ts                    # Add Requesty provider detection
+│   ├── agents/claudeAgent.ts           # Add Requesty to provider list
+│   └── utils/
+│       ├── modelCapabilities.ts        # Add Requesty model mappings
+│       └── modelOptimizer.ts           # Include Requesty models in optimizer
+```
+
+## Success Criteria
+
+### Must Have (MVP)
+- [ ] Users can use `--provider requesty` flag
+- [ ] Requesty API key via `REQUESTY_API_KEY` environment variable
+- [ ] Chat completions work with at least 10 tested models
+- [ ] Native tool calling support (MCP tools work)
+- [ ] Streaming responses supported
+- [ ] Error handling and logging
+- [ ] Model override via `--model` flag
+
+### Should Have (V1)
+- [ ] Tool emulation for models without native support
+- [ ] Model capability detection for Requesty models
+- [ ] Integration with model optimizer (`--optimize`)
+- [ ] Analytics and usage tracking
+- [ ] Proxy mode for Claude Code/Cursor
+- [ ] Cost estimation and reporting
+
+### Nice to Have (Future)
+- [ ] Auto-routing based on cost/performance
+- [ ] Caching integration
+- [ ] Fallback to other providers on error
+- [ ] Model benchmarking and comparison
+
+## Timeline Estimate
+
+| Phase | Tasks | Estimated Time |
+|-------|-------|----------------|
+| Phase 1 | Research & Planning | 2 hours (DONE) |
+| Phase 2 | Core Proxy Implementation | 4 hours |
+| Phase 3 | CLI Integration | 2 hours |
+| Phase 4 | Testing & Validation | 3 hours |
+| Phase 5 | Documentation | 2 hours |
+| **Total** | | **13 hours** |
+
+## Risk Assessment
+
+### Technical Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| API format differences from OpenRouter | Medium | Medium | Thorough testing, fallback handling |
+| Model compatibility issues | Low | Medium | Model capability detection system |
+| Tool calling format incompatibility | Low | High | Test with multiple models early |
+| Rate limiting differences | Medium | Low | Document limits, add retry logic |
+
+### Business Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|------------|--------|------------|
+| Requesty API changes | Medium | Medium | Version pinning, changelog monitoring |
+| Service availability issues | Low | High | Multi-provider support already in place |
+| Cost model changes | Low | Medium | Document pricing, update optimizer |
+
+## Next Steps
+
+1. Read `01-api-research.md` for detailed API analysis
+2. Review `02-architecture.md` for technical design
+3. Follow `03-implementation-phases.md` for step-by-step implementation
+4. Use `04-testing-strategy.md` for comprehensive testing
+5. Reference `05-migration-guide.md` for user documentation
+
+## Open Questions
+
+1. Does Requesty support streaming for all models or only specific ones?
+2. Are there any model-specific quirks in tool calling format?
+3. What are the exact rate limits per tier?
+4. Does Requesty offer a free tier for testing?
+5. How does auto-routing work - can we control it programmatically?
+
+## References
+
+- Requesty.ai Documentation: https://docs.requesty.ai
+- Requesty.ai Base URL: https://router.requesty.ai/v1
+- OpenRouter Integration (reference): `src/proxy/anthropic-to-openrouter.ts`
+- Gemini Integration (reference): `src/proxy/anthropic-to-gemini.ts`