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:

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

Конфиг:

{
  "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

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

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)

Схема контекста:

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)

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)
   • Использование токенов
   • Время выполнения

---

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