docs/RESEARCH.md

# Team Board — Research: Agent Integration

Исследование возможностей подключения AI-агентов к Team Board.

---

## Текущие возможности OpenClaw

### 1. sessions_spawn — спавн изолированных субагентов

```
Task → Spawn → Isolated Session → Result → Announce back
```

**Параметры:**
- `task` (required) — задача для агента
- `label` — метка для логов
- `agentId` — ID агента (если разрешён в allowlist)
- `model` — переопределение модели
- `runTimeoutSeconds` — таймаут
- `cleanup` — `delete|keep`

**Поведение:**
- Создаёт новую сессию `agent:<agentId>:subagent:<uuid>`
- Субагенты имеют полный набор инструментов минус session tools
- Не блокирует: возвращает `{ status: "accepted", runId, childSessionKey }`
- После завершения — announce в исходный чат

---

### 2. sessions_send — отправка между сессиями

```
Agent A → sessions_send → Agent B → Response
```

**Параметры:**
- `sessionKey` (required)
- `message` (required)
- `timeoutSeconds` — 0 = fire-and-forget

**Поведение:**
- Поддерживает ping-pong между агентами (до 5 итераций)
- Контекст сохраняется
- Провenance маркируется как `inter_session`

---

### 3. sessions_list / sessions_history

- Список активных сессий
- История сообщений сессии
- Фильтры по типу, времени, каналу

---

### 4. Multi-Agent Routing

Несколько агентов в одном gateway:

```yaml
agents:
  list:
    - id: main
      workspace: ~/.openclaw/workspace
    - id: coder
      workspace: ~/projects/coder-workspace
    - id: reviewer
      workspace: ~/projects/reviewer-workspace
```

**Каждый агент имеет:**
- Свой workspace (файлы, AGENTS.md, SOUL.md)
- Свой state directory
- Своё хранилище сессий
- Свои auth profiles

---

### 5. ACP (Agent Client Protocol)

Стандартный протокол для подключения внешних агентов.

```
External Agent ↔ ACP ↔ OpenClaw Gateway
```

**Реализация в OpenClaw:**
- `src/acp/server.ts` — ACP сервер
- `src/acp/client.ts` — ACP клиент
- Использует `@agentclientprotocol/sdk`

**Dangerous tools требуют approval:**
- exec, spawn, shell
- sessions_spawn, sessions_send
- gateway
- fs_write, fs_delete, fs_move

---

## Варианты интеграции для Team Board

### Вариант 1: OpenClaw Multi-Agent (рекомендуется)

```
Team Board API
      ↓
OpenClaw Gateway
      ↓
┌─────────────────────────────────┐
│  Agent: main (Lead)             │
│  Agent: coder (Developer)       │
│  Agent: reviewer (QA)           │
│  Agent: analyst (Research)      │
└─────────────────────────────────┘
```

**Плюсы:**
- Готовая инфраструктура
- Сохранение контекста через сессии
- Единый API
- Безопасность (sandbox, permissions)
- Инструменты (exec, browser, files)

**Реализация:**
1. Добавить агентов в `openclaw.json`
2. Team Board вызывает `sessions_spawn` / `sessions_send` через Gateway API
3. Результаты через webhook или polling

**Конфиг:**
```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace"
      },
      {
        "id": "coder",
        "workspace": "~/workspaces/coder",
        "model": "anthropic/claude-sonnet-4-20250514"
      }
    ],
    "defaults": {
      "subagents": {
        "allowAgents": ["main", "coder", "reviewer"]
      }
    }
  }
}
```

---

### Вариант 2: ACP Bridge для CLI агентов

Для подключения Claude Code CLI без траты API токенов.

```
Claude Code CLI (Max subscription)
      ↓
ACP Client Wrapper
      ↓
OpenClaw Gateway
      ↓
Team Board
```

**Компоненты:**

1. **PTY Session Manager**
```python
import pexpect

class CliSession:
    def __init__(self, command="claude"):
        self.child = pexpect.spawn(command)
    
    def send(self, message: str) -> str:
        self.child.sendline(message)
        self.child.expect(r'\n>')  # wait for prompt
        return self.child.before.decode()
```

2. **ACP Translator**
```python
class AcpCliBridge:
    def handle_request(self, request):
        response = self.cli_session.send(request.message)
        return AcpResponse(content=response)
```

**Сложности:**
- CLI интерактивный, не headless
- Нужно парсить вывод
- Контекст внутри CLI сессии

---

### Вариант 3: Direct API + Context Store

Прямые вызовы API с хранением контекста в БД.

```
Team Board
      ↓
Agent Service
      ↓
┌──────────────────────────────────┐
│  Claude API  │  Codex  │  Gemini │
└──────────────────────────────────┘
      ↓
Context Store (PostgreSQL)
```

**Схема контекста:**
```sql
CREATE TABLE agent_contexts (
    id UUID PRIMARY KEY,
    agent_id UUID REFERENCES agents(id),
    session_id UUID REFERENCES sessions(id),
    messages JSONB,  -- история сообщений
    metadata JSONB,  -- system prompt, tools, etc.
    created_at TIMESTAMPTZ,
    updated_at TIMESTAMPTZ
);
```

**При каждом запросе:**
1. Загрузить контекст из БД
2. Добавить новое сообщение
3. Вызвать API с полным контекстом
4. Сохранить ответ в БД

---

## Web Terminal Interface

### Архитектура

```
Browser (xterm.js)
      ↓ WebSocket
Team Board Frontend
      ↓ WebSocket
Team Board Backend (Session Manager)
      ↓ PTY / API
Agent (OpenClaw / CLI / API)
```

### Компоненты

**Frontend:**
- xterm.js — терминальный эмулятор
- WebSocket клиент
- Session selector UI

**Backend:**
- WebSocket сервер
- Session Manager
- PTY spawner (для CLI агентов)
- OpenClaw Gateway client (для OpenClaw агентов)

### Пример кода (Backend)

```python
from fastapi import WebSocket
import asyncio

class AgentSessionManager:
    def __init__(self):
        self.sessions = {}
    
    async def create_session(self, agent_type: str, config: dict):
        if agent_type == "openclaw":
            return OpenClawSession(config)
        elif agent_type == "cli":
            return CliSession(config)
        elif agent_type == "api":
            return ApiSession(config)
    
    async def handle_websocket(self, ws: WebSocket, session_id: str):
        session = self.sessions[session_id]
        
        async for message in ws.iter_text():
            response = await session.send(message)
            await ws.send_text(response)
```

---

## Сравнение вариантов

| Критерий | OpenClaw Multi-Agent | ACP CLI Bridge | Direct API |
|----------|---------------------|----------------|------------|
| Сложность | Низкая | Высокая | Средняя |
| Контекст | ✓ Автоматический | ✓ В CLI | Ручной |
| Инструменты | ✓ Полный набор | ✓ CLI tools | ✗ Нет |
| API токены | Нужны | Не нужны (Max) | Нужны |
| Готовность | Сейчас | Требует разработки | Требует разработки |

---

## Рекомендуемый план

### Фаза 1: OpenClaw Multi-Agent (быстрый старт)

1. Добавить агентов в конфиг OpenClaw
2. Team Board API вызывает Gateway
3. Использовать `sessions_spawn` для задач
4. Использовать `sessions_send` для коммуникации

**Результат:** Рабочая система с несколькими агентами

### Фаза 2: Web Terminal UI

1. xterm.js на фронте
2. WebSocket сервер
3. Прямое взаимодействие с агентами

**Результат:** Terminal-like опыт в браузере

### Фаза 3: ACP CLI Bridge (опционально)

1. PTY wrapper для Claude Code CLI
2. ACP транслятор
3. Интеграция с Gateway

**Результат:** CLI агенты без API токенов

---

## Открытые вопросы

1. **Headless mode в Claude Code CLI?**
   - Нужно проверить `claude --help`
   - Возможно есть `--message` или `--non-interactive`

2. **Как шарить файлы между агентами?**
   - Общий workspace?
   - Git как source of truth?
   - Копирование через API?

3. **Rate limiting для API агентов?**
   - Очередь задач
   - Приоритеты
   - Backoff при ошибках

4. **Мониторинг агентов?**
   - Статус (idle/working/error)
   - Использование токенов
   - Время выполнения

---

*Документ обновляется по мере исследования.*