# agent-discussion-mcp

Model Context Protocol (MCP) server for reusable role-based agents, autonomous task execution in workspaces, structured multi-agent debates, peer critiques, and independent judge consensus.

Supports **Solo** autonomous execution with workspace tools (file editing, shell execution, heartbeat, watchdog protection) and bounded **Discussion** mode: independent proposals, parallel critique, an independent judge, bounded revision rounds, and SQLite event logs with WAL mode.

See [dsaa.md](dsaa.md) for the original project vision and architectural notes (Russian).

---

## ✨ Features

- **Role Profiles ("Gems")**: Reusable agent profiles with custom roles, system prompts, model overrides, routing tags, temperature, and output token limits.
- **Solo Autonomous Execution (`run_solo`)**:
  - Run single-agent tasks directly by agent name, or route by tags.
  - Pass `working_dir` (or `workspace_path`) to grant the agent full autonomous workspace execution capabilities:
    - `list_files`: Find files matching glob patterns.
    - `read_file`: Inspect file contents.
    - `write_file`: Create or overwrite files.
    - `replace_in_file`: Targeted surgical text replacement.
    - `run_command`: Execute bash shell commands directly inside the workspace directory (e.g. running tests, linters, or build commands).
  - Pass custom `prompt` to override or augment the profile's instructions for a specific task.
- **Heartbeat & Inactivity Watchdog Protection**:
  - **Heartbeat reporting**: Emits periodic MCP progress notifications (`ctx.report_progress`) every 15s (`heartbeat_interval_seconds`) so the calling agent or client knows the agent is alive and progressing.
  - **Inactivity Watchdog**: Automatically detects hung or frozen processes (`inactivity_timeout_seconds`, default 300s) and aborts stuck tasks.
  - **Step Limit**: Prevents runaway execution loops (`max_steps`, default 25).
  - **Repetition Detector**: Detects and breaks out of repetitive identical tool failure loops.
- **Structured Discussion Mode (`run_discussion`)**:
  1. **Independent Proposals**: Participating agents draft proposals in parallel without seeing other agents' work.
  2. **Peer Critique**: Agents review all proposals and produce structured critiques (strengths, concerns, questions).
  3. **Independent Judge**: A designated judge evaluates the blackboard and decides consensus vs. no-consensus with a defensible final answer and confidence score.
  4. **Bounded Revision**: If no consensus is reached, agents revise their proposals addressing critiques for up to `max_rounds`.
- **Shared Token Budget**: Dynamic token reservation and settlement preventing token overrun in concurrent calls.
- **Event Sourcing & Audit Log**: Monotonic append-only SQLite log (`session_events`) recording all proposals, critiques, tool calls, verdicts, and errors in WAL mode.
- **Transient Error Resilience**: Exponential backoff with jitter on network/HTTP status errors (408, 409, 429, 5xx) and fallback verdict if a judge fails.

---

## 🚀 Quick Start

### Installation & Running

```bash
# Clone the repository
git clone https://github.com/ewanni/agent-discussion-mcp.git
cd agent-discussion-mcp

# Install dependencies with uv
uv sync --extra test

# Configure provider settings
export AGENT_DISCUSSION_API_KEY="your-openai-or-compatible-key"
export AGENT_DISCUSSION_BASE_URL="https://api.openai.com/v1"
export AGENT_DISCUSSION_MODEL="gpt-4o-mini"

# Run the MCP server over stdio
uv run agent-discussion-mcp
```

*(Note: legacy `API_AGENT_*` environment variables and `api-agent-mcp` CLI binary are also supported for backwards compatibility).*

---

## 🛠️ MCP Tools & Resources

### Tools

- **`create_agent`**: Register a new agent profile (name, role, system_prompt, model, tags, temperature, max_output_tokens).
- **`update_agent`**: Modify fields of an existing profile.
- **`list_agents`**: Inspect all registered profiles (omits private system prompts / credentials).
- **`run_solo`**: Execute a task with an agent.
  - `task` (required): Task description.
  - `working_dir` (optional): Path to working directory. When provided, the agent receives workspace tools (`read_file`, `write_file`, `replace_in_file`, `list_files`, `run_command`).
  - `prompt` (optional): Custom system prompt or additional instructions.
  - `agent` (optional): Name of the agent profile (or routed by task tags).
  - `max_steps` (optional, default 25): Maximum ReAct tool steps before terminating.
  - `inactivity_timeout_seconds` (optional, default 300): Watchdog threshold to prevent hanging.
  - `heartbeat_interval_seconds` (optional, default 15): Interval for MCP progress heartbeat notifications.
- **`run_discussion`**: Run a bounded debate with 2–5 participant agents, a separate judge, round limit (1–5), and a shared completion token budget.

### Resources

- **`agent://profiles/{name}`**: Read a specific agent profile configuration as JSON.

---

## ⚙️ Configuration & Environment Variables

| Variable | Fallback (Legacy) | Default | Description |
|---|---|---|---|
| `AGENT_DISCUSSION_API_KEY` | `API_AGENT_API_KEY` | `""` | API key for OpenAI-compatible endpoint |
| `AGENT_DISCUSSION_BASE_URL` | `API_AGENT_BASE_URL` | `https://api.openai.com/v1` | Base URL for `/chat/completions` |
| `AGENT_DISCUSSION_MODEL` | `API_AGENT_MODEL` | `gpt-4o-mini` | Default model for agents without custom override |
| `AGENT_DISCUSSION_DB` | `API_AGENT_DB` | `~/.agent_discussion_mcp/data.db` | SQLite database path for profiles and session audit events |
| `AGENT_DISCUSSION_TIMEOUT` | `API_AGENT_TIMEOUT` | `120` | HTTP request timeout in seconds |

---

## 🧪 Testing & Development

Run the test suite with `pytest`:

```bash
uv run pytest
```

---

## 🗺️ Roadmap

1. ✅ Solo mode and profile registry
2. ✅ Bounded Discussion with independent proposals, critics, judge, blackboard, and output-token budget
3. ✅ Solo autonomous workspace execution (file tools, bash commands, heartbeat, and watchdog)
4. ⏳ Subagent verification during discussions and resumable background sessions

---

## 📄 License

MIT