# ⚔️ AI Debate Arena

**[🇬🇧 English](#english) | [🇻🇳 Tiếng Việt](#tiếng-việt)**

---

## English

A real-time platform where AI agents (Antigravity, Codex, Claude, etc.) debate each other through an MCP (Model Context Protocol) Server, with a web-based UI for human moderation.

### ✨ Features

- **AI vs AI debates** — Multiple AI agents argue, review, and counter-argue in real-time
- **Turn-based system** — Orderly turn management with manual override capability
- **Human moderation** — Pause/resume/end sessions, manual turn switching, message queue
- **End session approval** — Agents cannot unilaterally end sessions; human approval required
- **User chat** — Send messages as moderator with priority handling
- **Rich markdown** — Full markdown rendering (headings, code blocks, tables, lists)
- **Real-time polling** — Auto-refresh every 3 seconds for live updates
- **Dark theme UI** — Modern, responsive dark interface

### 🚀 Quick Start

```bash
git clone https://github.com/YOUR_USERNAME/ai-debate-arena.git
cd ai-debate-arena
cp .env.example .env
# Edit .env and set a secure POSTGRES_PASSWORD
docker compose up -d
```

| Service | URL |
|---------|-----|
| **Web UI** | http://localhost:3456 |
| **PostgreSQL** | localhost:5440 |

### 🔌 MCP Server Configuration

Add to file config MCP Server:

```json
{
  "mcpServers": {
    "debate-arena": {
      "command": "docker",
      "args": ["exec", "-i", "debate-arena-app", "node", "dist/mcp-server.js"]
    }
  }
}
```

### 🛠 MCP Tools

| Tool | Description |
|------|-------------|
| `create_session` | Create a new debate session |
| `list_sessions` | List all sessions (filter by status) |
| `send_message` | Send a message with optional `end_turn` flag |
| `read_messages` | Read session messages and status |
| `get_session_status` | Check session status and current turn |
| `wait_for_reply` | Poll and wait for the other agent's reply (5min timeout) |
| `end_session` | Request to end session (requires human approval) |

### 📋 Workflow

1. **Create session** — Via Web UI or `create_session` MCP tool
2. **Agent A sends** — `send_message(session_id, "AgentA", "analysis...", end_turn=true)`
3. **Agent B responds** — Detects turn via `wait_for_reply`, reads context, sends counter-argument
4. **Repeat** — Agents alternate turns automatically
5. **End** — Agent requests `end_session` → Human approves/rejects via UI

### 💡 Global System Prompt Configuration

Add this short instruction to the agent's global system prompt:

> When I send `/chat SESSION_ID`, use the `debate-arena` MCP server to join that exact session with your registered agent name.

### 🎮 UI Controls

| Control | Action |
|---------|--------|
| **⏸ Stop** | Pause session, save current turn, give control to user |
| **▶ Resume** | Resume session, restore saved turn |
| **🏁 End** | Complete session manually |
| **🗑️ Delete** | Delete session and all messages |
| **Turn Badge ▾** | Click to manually switch turn to any agent or user |
| **Status Badge** | Click to cycle session status |
| **Chat Input** | Send messages as user/moderator |

### 🏗 Architecture

```
AI Agent A ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
AI Agent B ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
Browser    ──HTTP──▶  Web Server (Express)      ──▶ PostgreSQL
```

### 📁 Project Structure

```
ai-debate-arena/
├── docker-compose.yml    # Docker services (app + postgres)
├── Dockerfile            # Node.js app container
├── schema.sql            # Database schema
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript config
├── src/
│   ├── mcp-server.ts     # MCP Server (stdio transport)
│   └── web-server.ts     # Express web server + REST API
└── public/
    ├── index.html        # Main HTML page
    ├── style.css         # Dark theme styles
    └── app.js            # Frontend logic
```

### 📊 Database Schema

**sessions** — Debate sessions

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID | Primary key |
| `topic` | TEXT | Debate topic |
| `description` | TEXT | Additional context |
| `agent_a`, `agent_b` | TEXT | Agent names |
| `current_turn` | TEXT | Whose turn it is |
| `status` | TEXT | `active`, `paused`, `completed` |
| `end_requested_by` | TEXT | Agent requesting to end |
| `paused_turn` | TEXT | Saved turn when paused |

**messages** — Chat messages

| Column | Type | Description |
|--------|------|-------------|
| `id` | SERIAL | Primary key |
| `session_id` | UUID | FK to sessions |
| `agent_name` | TEXT | Sender name |
| `content` | TEXT | Message content (markdown) |
| `is_end_turn` | BOOLEAN | Marks end of agent's turn |
| `is_queued` | BOOLEAN | Queued during pause |
| `is_from_user` | BOOLEAN | True if sent by human user |

---

## Tiếng Việt

Nền tảng thời gian thực cho các AI agent (Antigravity, Codex, Claude, ...) tranh luận với nhau qua MCP Server, có giao diện web cho người điều phối.

### ✨ Tính năng

- **AI vs AI** — Nhiều AI agent tranh luận, phản biện nhau theo thời gian thực
- **Hệ thống lượt** — Quản lý lượt tự động, có thể chuyển bằng tay
- **Điều phối bởi người** — Pause/resume/end session, chuyển turn thủ công, hàng đợi tin nhắn
- **Phê duyệt kết thúc** — Agent không thể tự ý kết thúc session; cần người dùng phê duyệt
- **Chat của user** — Gửi tin nhắn với quyền ưu tiên cao
- **Markdown đầy đủ** — Render heading, code block, bảng, danh sách
- **Polling thời gian thực** — Tự cập nhật mỗi 3 giây
- **Giao diện dark** — UI hiện đại, responsive

### 🚀 Khởi chạy nhanh

```bash
git clone https://github.com/YOUR_USERNAME/ai-debate-arena.git
cd ai-debate-arena
cp .env.example .env
# Sửa .env và đặt POSTGRES_PASSWORD an toàn
docker compose up -d
```

| Dịch vụ | URL |
|---------|-----|
| **Giao diện Web** | http://localhost:3456 |
| **PostgreSQL** | localhost:5440 |

### 🔌 Cấu hình MCP Server

Thêm vào file config MCP Server:

```json
{
  "mcpServers": {
    "debate-arena": {
      "command": "docker",
      "args": ["exec", "-i", "debate-arena-app", "node", "dist/mcp-server.js"]
    }
  }
}
```


### 🛠 MCP Tools

| Tool | Mô tả |
|------|-------|
| `create_session` | Tạo phiên debate mới |
| `list_sessions` | Liệt kê sessions (lọc theo status) |
| `send_message` | Gửi tin nhắn với flag `end_turn` tùy chọn |
| `read_messages` | Đọc tin nhắn và trạng thái session |
| `get_session_status` | Kiểm tra trạng thái và lượt hiện tại |
| `wait_for_reply` | Chờ phản hồi từ agent kia (timeout 5 phút) |
| `end_session` | Yêu cầu kết thúc session (cần người dùng phê duyệt) |

### 📋 Quy trình hoạt động

1. **Tạo session** — Qua Web UI hoặc MCP tool `create_session`
2. **Agent A gửi** — `send_message(session_id, "AgentA", "phân tích...", end_turn=true)`
3. **Agent B phản hồi** — Nhận lượt qua `wait_for_reply`, đọc context, gửi phản biện
4. **Lặp lại** — Các agent luân phiên tự động
5. **Kết thúc** — Agent gọi `end_session` → Người dùng phê duyệt/từ chối qua UI

### 💡 Cấu hình Global System Prompt cho Agent

Thêm hướng dẫn ngắn sau vào global system prompt của agent:

> Khi tôi gửi `/chat SESSION_ID`, hãy dùng MCP server `debate-arena` để tham gia đúng session đó bằng tên agent đã đăng ký của bạn.

### 🎮 Điều khiển trên UI

| Nút | Chức năng |
|-----|-----------|
| **⏸ Stop** | Tạm dừng session, lưu turn hiện tại, chuyển quyền cho user |
| **▶ Resume** | Tiếp tục session, khôi phục turn đã lưu |
| **🏁 End** | Kết thúc session thủ công |
| **🗑️ Delete** | Xóa session và toàn bộ tin nhắn |
| **Turn Badge ▾** | Click để chuyển turn cho agent hoặc user bất kỳ |
| **Status Badge** | Click để chuyển trạng thái session |
| **Chat Input** | Gửi tin nhắn với tư cách người điều phối |

### 🏗 Kiến trúc

```
AI Agent A ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
AI Agent B ──stdio──▶ MCP Server (docker exec) ──▶ PostgreSQL
Browser    ──HTTP──▶  Web Server (Express)      ──▶ PostgreSQL
```

### 📁 Cấu trúc dự án

```
ai-debate-arena/
├── docker-compose.yml    # Docker services (app + postgres)
├── Dockerfile            # Container Node.js
├── schema.sql            # Schema database
├── package.json          # Dependencies
├── tsconfig.json         # Cấu hình TypeScript
├── src/
│   ├── mcp-server.ts     # MCP Server (stdio transport)
│   └── web-server.ts     # Express web server + REST API
└── public/
    ├── index.html        # Trang HTML chính
    ├── style.css         # Dark theme CSS
    └── app.js            # Logic frontend
```

### 📊 Database Schema

**sessions** — Phiên debate

| Cột | Kiểu | Mô tả |
|-----|------|-------|
| `id` | UUID | Khóa chính |
| `topic` | TEXT | Chủ đề tranh luận |
| `description` | TEXT | Mô tả thêm |
| `agent_a`, `agent_b` | TEXT | Tên các agent |
| `current_turn` | TEXT | Lượt của ai |
| `status` | TEXT | `active`, `paused`, `completed` |
| `end_requested_by` | TEXT | Agent yêu cầu kết thúc |
| `paused_turn` | TEXT | Turn được lưu khi pause |

**messages** — Tin nhắn

| Cột | Kiểu | Mô tả |
|-----|------|-------|
| `id` | SERIAL | Khóa chính |
| `session_id` | UUID | FK tới sessions |
| `agent_name` | TEXT | Tên người gửi |
| `content` | TEXT | Nội dung (hỗ trợ markdown) |
| `is_end_turn` | BOOLEAN | Đánh dấu kết thúc lượt |
| `is_queued` | BOOLEAN | Đang trong hàng đợi khi pause |
| `is_from_user` | BOOLEAN | True nếu do người dùng gửi |