mcp-agent-foundry 1.3.0 → 2.0.0

package/README.md

@@ -5,7 +5,7 @@
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js >=20](https://img.shields.io/badge/Node.js-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 [![npm version](https://img.shields.io/npm/v/mcp-agent-foundry.svg)](https://www.npmjs.com/package/mcp-agent-foundry)
-[![Tests](https://img.shields.io/badge/tests-131%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests/)
 
 Agent Foundry extends Claude Code with multi-provider AI orchestration and git worktree isolation. Each coding agent receives its own isolated worktree - a separate checkout on a dedicated branch - enabling true parallel development without file conflicts. Get second opinions from external AI models without leaving Claude Code.
 
@@ -13,6 +13,8 @@ Agent Foundry extends Claude Code with multi-provider AI orchestration and git w
 
 ## Features
 
+- **Zero-Config Setup** - Auto-registers with Claude Code on npm install
+- **13+ AI Providers** - From budget (DeepSeek, Groq) to premium (OpenAI, Anthropic)
 - **Multi-Provider AI Orchestration** - Route tasks to Anthropic, OpenAI, Google Gemini, DeepSeek, Z.AI (GLM-4), Kimi, or local Ollama models
 - **Git Worktree Isolation** - Each coding agent works in an isolated directory on its own branch
 - **Pipeline Execution** - Multi-step DAG workflows with dependency ordering and parallel execution
@@ -22,6 +24,11 @@ Agent Foundry extends Claude Code with multi-provider AI orchestration and git w
 - **State Persistence** - Survives server restarts with automatic state recovery
 - **Crash Recovery** - Orphan detection, stuck worktree handling, and cleanup commands
 - **Intelligent Failover** - Automatic provider switching with health tracking, circuit breakers, and cost-aware routing
+- **Context Manager** - Token tracking per provider/model with 40+ model limits, auto-compact at 90%, blocking at 98%
+- **Hooks System** - 9 event types for customizing agent behavior with variable substitution and hot-reload
+- **Background Task Runner** - Queue-based async task execution with AbortController cancellation and progress tracking
+- **MCP Auto Mode** - Intelligent tool selection under context pressure with priority-based deferral
+- **Skills Hot-Reload** - Custom skill definitions with auto-discovery from user and project directories
 
 ---
 
@@ -33,7 +40,12 @@ Agent Foundry extends Claude Code with multi-provider AI orchestration and git w
 npm install -g mcp-agent-foundry
 ```
 
-### Setup
+That's it! Agent Foundry automatically registers with Claude Code during installation.
+Restart Claude Code to activate.
+
+To verify: Run `/mcp` in Claude Code - you should see `agent-foundry · ✓ connected`
+
+### Initial Setup
 
 ```bash
 agent-foundry setup
@@ -45,34 +57,6 @@ This interactive wizard will:
 3. Set up agent roles
 4. Create your configuration file
 
-### Connect to Claude Code
-
-Add to your Claude Code configuration (`~/.claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "agent-foundry": {
-      "command": "agent-foundry",
-      "args": ["start"]
-    }
-  }
-}
-```
-
-Or specify the full path:
-
-```json
-{
-  "mcpServers": {
-    "agent-foundry": {
-      "command": "node",
-      "args": ["/path/to/agent-foundry/dist/index.js"]
-    }
-  }
-}
-```
-
 ---
 
 ## How It Works
@@ -125,6 +109,218 @@ Or specify the full path:
 
 ---
 
+## Intelligent Failover System
+
+Agent Foundry includes automatic provider failover with health tracking:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Request to Role                          │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │ Primary Provider │
+                    │   (e.g. DeepSeek)│
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+         ✓ Success                    ✗ Error (429, 500, etc.)
+              │                             │
+              ▼                             ▼
+         Return Result            ┌─────────────────┐
+                                  │ Health Tracker   │
+                                  │ marks unhealthy  │
+                                  └────────┬────────┘
+                                           │
+                                           ▼
+                                  ┌─────────────────┐
+                                  │ Circuit Breaker │
+                                  │ checks state    │
+                                  └────────┬────────┘
+                                           │
+                                           ▼
+                                  ┌─────────────────┐
+                                  │ Fallback Chain  │
+                                  │ (OpenAI → Anthropic)│
+                                  └────────┬────────┘
+                                           │
+                                           ▼
+                                    Next Provider
+```
+
+### Key Features
+
+- **Automatic Retry** - Exponential backoff on transient errors
+- **Health Tracking** - Monitors provider success/failure rates
+- **Cooldown Periods** - Unhealthy providers are temporarily skipped
+- **Circuit Breakers** - Prevents cascading failures
+- **Cost-Aware Routing** - Optionally prefer cheaper providers
+- **Configurable Error Codes** - Define which errors trigger failover
+- **Rate Limit Warnings** - Proactive warnings at 70% capacity with header parsing for OpenAI/Anthropic/generic formats
+
+---
+
+## Hooks System
+
+Agent Foundry provides a flexible hooks system that lets you customize agent behavior by running commands at key lifecycle events.
+
+### Supported Events
+
+| Event | Description |
+|-------|-------------|
+| `PreToolUse` | Before a tool is invoked |
+| `PostToolUse` | After a tool completes |
+| `Setup` | During agent initialization |
+| `ToolError` | When a tool encounters an error |
+| `TaskStart` | When a task begins execution |
+| `TaskComplete` | When a task finishes successfully |
+| `TaskFail` | When a task fails |
+| `ProviderError` | When an AI provider returns an error |
+| `Failover` | When switching to a fallback provider |
+
+### Configuration
+
+```yaml
+# In ~/.config/agent-foundry/config.yaml
+hooks:
+  enabled: true
+  configPath: ~/.agent-foundry/hooks.yaml
+  events:
+    PreToolUse:
+      - command: "echo 'Tool: ${TOOL_NAME}'"
+        timeout_ms: 5000
+        filter:
+          tools: ["execute_task", "invoke_agent"]
+    TaskComplete:
+      - command: "./notify.sh ${TASK_ID}"
+        timeout_ms: 10000
+    ProviderError:
+      - command: "logger -t agent-foundry 'Provider ${PROVIDER} failed: ${ERROR}'"
+```
+
+### Variable Substitution
+
+Hooks support variable substitution with context-specific values:
+- `${TOOL_NAME}` - Name of the tool being invoked
+- `${TASK_ID}` - Current task identifier
+- `${PROVIDER}` - AI provider name
+- `${ERROR}` - Error message (for error events)
+- `${RESULT}` - Result data (for post-completion events)
+
+### Features
+
+- **Filtering** - Run hooks only for specific tools, providers, or roles
+- **Timeouts** - Configurable per-hook timeouts prevent blocking
+- **Hot-Reload** - Changes to hooks.yaml are picked up automatically
+
+---
+
+## Skills Hot-Reload
+
+Define custom skills that extend agent capabilities with automatic discovery and hot-reload.
+
+### Skill Locations
+
+Skills are loaded from:
+1. `~/.agent-foundry/skills/` - User-level skills (shared across projects)
+2. `.agent-foundry/skills/` - Project-level skills (project-specific)
+
+### Skill Definition
+
+```yaml
+# ~/.agent-foundry/skills/code-review.yaml
+name: code-review
+description: Comprehensive code review skill
+context_mode: inherit  # inherit | fork | isolated
+
+prompts:
+  system: |
+    You are an expert code reviewer focusing on:
+    - Security vulnerabilities
+    - Performance issues
+    - Best practices
+    - Code clarity
+
+triggers:
+  - pattern: "review this code"
+  - pattern: "code review"
+
+actions:
+  - type: invoke_agent
+    role: reviewer
+```
+
+### Context Modes
+
+| Mode | Description |
+|------|-------------|
+| `inherit` | Skill runs in the parent agent's context |
+| `fork` | Skill gets a copy of the parent context |
+| `isolated` | Skill runs with a fresh, empty context |
+
+### Features
+
+- **Auto-Discovery** - Skills are automatically loaded on startup
+- **Hot-Reload** - Changes to skill files are picked up without restart
+- **Priority Ordering** - Project skills override user skills with the same name
+
+---
+
+## Context Manager
+
+Agent Foundry includes intelligent context management to prevent token limit issues and optimize AI provider usage.
+
+### Features
+
+- **Token Tracking** - Tracks token usage per provider/model with 40+ pre-configured model limits
+- **Auto-Compact** - Automatically compacts context when reaching 90% capacity
+- **Blocking Threshold** - Blocks new requests at 98% to prevent errors
+- **Visualization** - Context usage visible in debug logs and status commands
+
+### Configuration
+
+```yaml
+# In ~/.config/agent-foundry/config.yaml
+context:
+  autoCompact: true
+  compactThreshold: 0.9    # Trigger compaction at 90%
+  blockThreshold: 0.98     # Block new requests at 98%
+```
+
+### Supported Model Limits
+
+Pre-configured limits for 40+ models including:
+- OpenAI: GPT-4o (128K), GPT-4 Turbo (128K), o1 (200K)
+- Anthropic: Claude 3.5/4 (200K)
+- Google: Gemini 2.5 Pro (1M), Gemini 2.5 Flash (1M)
+- DeepSeek: DeepSeek R1 (64K), DeepSeek Chat (128K)
+- And many more...
+
+---
+
+## MCP Auto Mode
+
+When context pressure builds, MCP Auto Mode intelligently manages tool availability.
+
+### How It Works
+
+1. **Context Budget** - Tool descriptions are deferred when exceeding 10% of context budget
+2. **Priority-Based Selection** - High-priority tools remain available; lower-priority tools are deferred
+3. **Automatic Restoration** - Deferred tools become available again when context decreases
+
+### Tool Priorities
+
+| Priority | Tools |
+|----------|-------|
+| Critical | `invoke_agent`, `execute_task` |
+| High | `list_agents`, `get_task_status` |
+| Medium | `execute_pipeline`, `compare_agents` |
+| Low | `cleanup_worktrees`, `list_worktrees` |
+
+---
+
 ## MCP Tools
 
 | Tool | Description |
@@ -143,6 +339,7 @@ Or specify the full path:
 | `cleanup_worktrees` | Clean up stale or orphaned worktrees |
 | `resolve_conflicts` | Resolve merge conflicts using various strategies |
 | `get_worktree_status` | Get detailed status of a specific worktree |
+| `delete_task` | Delete a task from the queue |
 
 ---
 
@@ -162,19 +359,24 @@ providers:
   openai:
     api_key: ${OPENAI_API_KEY}
     default_model: gpt-4o
-  deepseek:
-    api_key: ${DEEPSEEK_API_KEY}
-    base_url: https://api.deepseek.com
-    default_model: deepseek-reasoner
   anthropic:
     api_key: ${ANTHROPIC_API_KEY}
     default_model: claude-sonnet-4-20250514
+  deepseek:
+    api_key: ${DEEPSEEK_API_KEY}
+    default_model: deepseek-reasoner
   google:
     api_key: ${GOOGLE_API_KEY}
     default_model: gemini-2.5-pro
+  groq:
+    api_key: ${GROQ_API_KEY}
+    default_model: llama-3.3-70b-versatile
+  openrouter:
+    api_key: ${OPENROUTER_API_KEY}
+    default_model: anthropic/claude-3.5-sonnet
   ollama:
     base_url: http://localhost:11434
-    default_model: llama3.2
+    default_model: llama3.3:70b
 
 roles:
   coder:
@@ -243,19 +445,62 @@ worktrees:
     enabled: true
     minAvailable: 2
     maxSize: 5
+
+# Hooks configuration
+hooks:
+  enabled: true
+  configPath: ~/.agent-foundry/hooks.yaml
+  events:
+    PreToolUse:
+      - command: "echo 'Tool: ${TOOL_NAME}'"
+        timeout_ms: 5000
+    TaskComplete:
+      - command: "./notify.sh ${TASK_ID}"
+
+# Skills configuration
+skills:
+  enabled: true
+  directories:
+    - ~/.agent-foundry/skills
+    - .agent-foundry/skills
+  hotReload: true
+
+# Context management
+context:
+  autoCompact: true
+  compactThreshold: 0.9    # Auto-compact at 90% capacity
+  blockThreshold: 0.98     # Block new requests at 98% capacity
 ```
 
 ### Environment Variables
 
-Set your API keys as environment variables:
-
 ```bash
-export OPENAI_API_KEY="sk-..."
+# Premium Providers
 export ANTHROPIC_API_KEY="sk-ant-..."
-export DEEPSEEK_API_KEY="sk-..."
+export OPENAI_API_KEY="sk-..."
 export GOOGLE_API_KEY="..."
-export ZAI_API_KEY="..."        # Z.AI GLM-4
-export KIMI_API_KEY="..."       # Moonshot Kimi
+
+# Budget-Friendly Providers
+export DEEPSEEK_API_KEY="sk-..."
+export ZAI_API_KEY="..."
+export KIMI_API_KEY="..."
+export KIMI_CODE_API_KEY="..."     # Kimi Code subscription
+
+# Router/Aggregator
+export OPENROUTER_API_KEY="sk-or-..."
+
+# Fast Inference
+export GROQ_API_KEY="gsk_..."
+export TOGETHER_API_KEY="..."
+export FIREWORKS_API_KEY="..."
+
+# Web Search
+export PERPLEXITY_API_KEY="pplx-..."
+
+# Debug/Observability
+export AGENT_FOUNDRY_DEBUG=true                    # Enable debug logging
+export AGENT_FOUNDRY_DEBUG_FILE=/path/to/debug.log # Write debug logs to file
+export AGENT_FOUNDRY_DEBUG_VERBOSE=true            # Include verbose details
 ```
 
 ---
@@ -310,15 +555,23 @@ agent-foundry help          # Show help
 
 ## Supported Providers
 
-| Provider | Models | Access Mode | Cost |
-|----------|--------|-------------|------|
-| **Anthropic** | Claude Sonnet 4, Claude Opus 4 | API | $$$ |
-| **OpenAI** | GPT-4o, GPT-4 Turbo, o1, o1-mini | API | $$$ |
-| **Google Gemini** | Gemini 2.5 Pro, Gemini 2.5 Flash | API | $$ |
-| **DeepSeek** | DeepSeek R1, DeepSeek Chat | API | $ (cheapest) |
-| **Z.AI** | GLM-4, GLM-4.7 | API | $ |
-| **Kimi** | Moonshot v1 | API | $ |
-| **Ollama** | Llama 3.2, Mistral, CodeLlama, etc. | Local | Free |
+| Provider | Models | API Key Env Var | Cost |
+|----------|--------|-----------------|------|
+| **Anthropic** | Claude Opus 4, Claude Sonnet 4 | `ANTHROPIC_API_KEY` | $$$ |
+| **OpenAI** | GPT-4o, GPT-4 Turbo, o1, o1-mini, o3-mini | `OPENAI_API_KEY` | $$$ |
+| **Google Gemini** | Gemini 2.5 Pro, Gemini 2.5 Flash | `GOOGLE_API_KEY` | $$ |
+| **DeepSeek** | DeepSeek R1, DeepSeek Chat, DeepSeek Coder | `DEEPSEEK_API_KEY` | $ |
+| **OpenRouter** | Access 100+ models via single API | `OPENROUTER_API_KEY` | Varies |
+| **Perplexity** | pplx-70b-online, pplx-7b-online (web search) | `PERPLEXITY_API_KEY` | $$ |
+| **Groq** | Llama 3.3 70B, Mixtral (ultra-fast inference) | `GROQ_API_KEY` | $ |
+| **Together AI** | Llama, Mistral, CodeLlama, Qwen | `TOGETHER_API_KEY` | $ |
+| **Fireworks AI** | Llama, Mixtral (optimized inference) | `FIREWORKS_API_KEY` | $ |
+| **Z.AI** | GLM-4, GLM-4.7 | `ZAI_API_KEY` | $ |
+| **Kimi (Moonshot)** | moonshot-v1-128k | `KIMI_API_KEY` | $ |
+| **Kimi Code** | Kimi coding assistant (subscription) | `KIMI_CODE_API_KEY` | Subscription |
+| **Ollama** | Llama 3.3, Mistral, CodeLlama, Qwen, etc. | N/A (local) | Free |
+
+**Cost Legend**: $ = Budget, $$ = Moderate, $$$ = Premium
 
 ---
 
@@ -398,7 +651,8 @@ agent-foundry/
 │   ├── cli/                  # CLI command implementations
 │   ├── mcp/
 │   │   ├── tools/            # MCP tool implementations
-│   │   └── transport/        # stdio transport
+│   │   ├── transport/        # stdio transport
+│   │   └── auto-mode.ts      # MCP Auto Mode - intelligent tool selection
 │   ├── worktrees/
 │   │   ├── manager.ts        # Worktree lifecycle
 │   │   ├── branch.ts         # Branch operations
@@ -412,9 +666,31 @@ agent-foundry/
 │   │   ├── anthropic.ts      # Anthropic Claude
 │   │   ├── openai.ts         # OpenAI GPT-4o
 │   │   ├── gemini.ts         # Google Gemini
+│   │   ├── deepseek.ts       # DeepSeek R1
 │   │   ├── ollama.ts         # Local Ollama
 │   │   ├── zai.ts            # Z.AI GLM
-│   │   └── kimi.ts           # Moonshot Kimi
+│   │   ├── kimi.ts           # Moonshot Kimi
+│   │   ├── openrouter.ts     # OpenRouter (100+ models)
+│   │   ├── perplexity.ts     # Perplexity (web search)
+│   │   ├── groq.ts           # Groq (fast inference)
+│   │   ├── together.ts       # Together AI
+│   │   └── fireworks.ts      # Fireworks AI
+│   ├── failover/
+│   │   ├── orchestrator.ts   # Retry and failover logic
+│   │   ├── health-tracker.ts # Provider health monitoring
+│   │   └── pricing.ts        # Cost-aware routing
+│   ├── background/           # Background task execution
+│   │   └── task-runner.ts    # Queue-based async task runner
+│   ├── hooks/                # Hook system
+│   │   ├── hook-executor.ts  # Hook command execution
+│   │   └── hook-manager.ts   # Hook registration and dispatch
+│   ├── skills/               # Skills hot-reload
+│   │   ├── skill-loader.ts   # Skill file discovery and parsing
+│   │   ├── skill-executor.ts # Skill action execution
+│   │   └── hot-reloader.ts   # File watcher for hot-reload
+│   ├── observability/        # Logging and debugging
+│   │   ├── logger.ts         # Structured logging
+│   │   └── debug-logger.ts   # Debug output with environment control
 │   ├── persistence/          # State persistence
 │   ├── config/               # Configuration management
 │   └── router/               # Routing engine
@@ -449,6 +725,28 @@ pnpm lint:fix
 pnpm typecheck
 ```
 
+### Debug Logging
+
+Agent Foundry provides enhanced debug logging controlled via environment variables:
+
+```bash
+# Enable debug logging
+export AGENT_FOUNDRY_DEBUG=true
+
+# Write debug logs to a file
+export AGENT_FOUNDRY_DEBUG_FILE=/path/to/debug.log
+
+# Include verbose details (API payloads, full stack traces)
+export AGENT_FOUNDRY_DEBUG_VERBOSE=true
+```
+
+Debug logging includes:
+- Provider API calls and responses
+- Failover decisions and health tracking
+- Hook execution and timing
+- Skill loading and hot-reload events
+- Context manager token tracking
+
 ---
 
 ## Security

package/dist/background/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Background Module
+ *
+ * Provides background task execution for non-blocking agent invocations
+ * and pipeline steps. Supports concurrency control, cancellation,
+ * progress tracking, and event-based notifications.
+ *
+ * @example
+ * ```typescript
+ * import { BackgroundTaskRunner } from './background/index.js';
+ *
+ * const runner = new BackgroundTaskRunner({ maxConcurrent: 3 }, logger);
+ *
+ * // Submit a background agent invocation
+ * const taskId = await runner.run(
+ *   'agent_invocation',
+ *   'Review authentication code',
+ *   async () => {
+ *     return await orchestrator.executeWithFailover('reviewer', messages, options);
+ *   },
+ *   { role: 'reviewer', provider: 'openai' }
+ * );
+ *
+ * // Check status later
+ * const task = runner.getTask(taskId);
+ *
+ * // Or wait for completion
+ * const completed = await runner.waitFor(taskId, 60000);
+ * ```
+ */
+export * from './types.js';
+export { BackgroundTaskRunner } from './task-runner.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/background/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/background/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/background/index.js

@@ -0,0 +1,33 @@
+/**
+ * Background Module
+ *
+ * Provides background task execution for non-blocking agent invocations
+ * and pipeline steps. Supports concurrency control, cancellation,
+ * progress tracking, and event-based notifications.
+ *
+ * @example
+ * ```typescript
+ * import { BackgroundTaskRunner } from './background/index.js';
+ *
+ * const runner = new BackgroundTaskRunner({ maxConcurrent: 3 }, logger);
+ *
+ * // Submit a background agent invocation
+ * const taskId = await runner.run(
+ *   'agent_invocation',
+ *   'Review authentication code',
+ *   async () => {
+ *     return await orchestrator.executeWithFailover('reviewer', messages, options);
+ *   },
+ *   { role: 'reviewer', provider: 'openai' }
+ * );
+ *
+ * // Check status later
+ * const task = runner.getTask(taskId);
+ *
+ * // Or wait for completion
+ * const completed = await runner.waitFor(taskId, 60000);
+ * ```
+ */
+export * from './types.js';
+export { BackgroundTaskRunner } from './task-runner.js';
+//# sourceMappingURL=index.js.map

package/dist/background/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/background/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}