docs/archive/BRAINSTORM-PROTOCOL-2026-02-20.md

# Брейншторм: Протокол Picogent ↔ Tracker
Дата: 2026-02-20

## Принцип

Два слоя, чётко разделены:

1. **WebSocket** — real-time: события (push от трекера) + сообщения чата
2. **REST (через MCP tools)** — все мутации: задачи, этапы, файлы, статусы

Агент (LLM) не знает про WS-протокол. Он вызывает MCP tools.
Router (picogent) получает WS-события и решает: показать агенту или обработать внутренне.

## WebSocket Protocol

### Инфраструктура (Agent ↔ Tracker)

```
Agent → Tracker:
  {type: "auth", token: "...", agent: {name, slug, capabilities}}
  {type: "heartbeat", status: "idle|busy", current_tasks: [...]}
  {type: "ack", id: "event-uuid"}

Tracker → Agent:
  {type: "auth.ok", agent_id: "uuid"}
  {type: "auth.error", message: "..."}
```

### События (Tracker → Agent, push)

```
{type: "event", id: "uuid", event: "<event_type>", data: {...}}
```

| Событие | В промпт LLM? | Описание |
|---------|---------------|----------|
| task.assigned | ✅ Да | Тебе назначена задача → начать работу |
| task.taken | ❌ Нет | Кто-то взял задачу → убрать из доступных (internal) |
| task.status_changed | ⚠️ Иногда | Только если зависимость разблокировалась |
| task.comment_added | ✅ Если mention | Новый комментарий → ответить/исправить |
| chat.message | ✅ По режиму | listen:all → всё, listen:mentions → только с @mention |
| agent.status_changed | ❌ Нет | Internal state |

### Сообщения чата (Agent → Tracker, через WS)

```
Agent → Tracker:
  {type: "chat.send", chat_id: "uuid", content: "текст", mentions: ["slug"]}

Tracker → Agent:
  {type: "event", event: "chat.message", data: {chat_id, author_slug, content, mentions}}
```

## MCP Tools (Agent → Tracker REST API)

Все мутации — только REST. MCP tools вызывает LLM по своему усмотрению.

### Задачи
| Tool | Method | Endpoint | Описание |
|------|--------|----------|----------|
| get_task | GET | /tasks/{id} | Получить задачу |
| list_tasks | GET | /tasks?project_id=&status=&assignee= | Список с фильтрами |
| create_task | POST | /tasks | Создать задачу/подзадачу |
| update_task | PATCH | /tasks/{id} | Обновить поля (status, priority...) |
| take_task | POST | /tasks/{id}/take | Взять себе (атомарно) |
| reject_task | POST | /tasks/{id}/reject | Отклонить с причиной |

### Этапы (Steps)
| Tool | Method | Endpoint | Описание |
|------|--------|----------|----------|
| add_step | POST | /tasks/{id}/steps | Добавить этап |
| complete_step | PATCH | /tasks/{id}/steps/{index} | Отметить выполненным |
| list_steps | GET | /tasks/{id}/steps | Текущие этапы |

### Комментарии
| Tool | Method | Endpoint | Описание |
|------|--------|----------|----------|
| add_comment | POST | /tasks/{id}/comments | Комментарий (с mentions) |
| list_comments | GET | /tasks/{id}/comments | Прочитать комментарии |

### Чат (альтернатива WS, fallback)
| Tool | Method | Endpoint | Описание |
|------|--------|----------|----------|
| send_message | POST | /chats/{id}/messages | Отправить сообщение |
| read_messages | GET | /chats/{id}/messages?limit= | Прочитать историю |

### Файлы
| Tool | Method | Endpoint | Описание |
|------|--------|----------|----------|
| upload_file | POST | /tasks/{id}/files | Прикрепить файл |
| list_files | GET | /tasks/{id}/files | Список файлов |

## Prompt Guidelines (заметки для промпта агента)

```
## Работа с задачами

- Получил задачу → прочитай описание через get_task()
- Если задача сложная → разбей на этапы через add_step()
- Обновляй этапы по мере работы через complete_step()
- Если нужно декомпозировать → создай подзадачи через create_task(parent_id=...)
- Если не можешь выполнить → отклони через reject_task() с объяснением
- После завершения → комментарий через add_comment() + update_task(status="review")

## Коммуникация

- Вопрос другому агенту → send_message() в чат с @mention
- Пришло сообщение с @mention → ответь
- Системные уведомления (task.taken, status changes) обрабатываются автоматически
```

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

### Принцип: максимум разговорной речи
Все события приходят агенту как **текстовые сообщения**. Агент — LLM, он сам понимает что делать.
Router не строит промпты, не вызывает API — просто передаёт текст.

### Одна сессия на агента
НЕ создавать отдельные сессии на задачу/чат. Всё в одном контексте:
задачи, чат, ответы — чтобы агент видел полную картину.

### Router (обработка WS-событий)
```
WS event → Router:
  task.assigned    → текст "Тебе назначена задача TB-42: ..." → runAgent(текст)
  chat.message     → если mention/listen:all → текст "[чат] @author: ..." → runAgent(текст)
  task.comment     → если mention → текст "[комментарий к TB-42] @author: ..." → runAgent(текст)
  task.taken       → internal: убрать из available (НЕ в промпт)
  task.status      → internal: проверить зависимости (НЕ в промпт)
```
Агент сам решает: вызвать get_task(), add_step(), send_message() — через MCP tools.

### MCP Tools (регистрация)
```
MCP Server → tools:
  get_task, list_tasks, create_task, update_task, take_task, reject_task
  add_step, complete_step, list_steps
  add_comment, list_comments
  send_message, read_messages
  upload_file, list_files
```

Каждый tool = HTTP request к Tracker REST API с Bearer token.

## Идея: Web MCP Server (на будущее)

Отдельный MCP Server (HTTP transport) для Tracker REST API.
Позволяет **любому LLM-клиенту** (Claude Code CLI, Cursor, Windsurf, Cline, OpenClaw)
работать с трекером через MCP без WebSocket и без Picogent.

- Отдельный пакет: `team-board/mcp-server`
- Человек говорит LLM: "возьми задачу #42" → LLM вызывает MCP tool → REST
- Не автономный (нет push-событий), но полностью функциональный
- Использует тот же REST API что и Picogent

Статус: **идея, не реализуем сейчас.**

## Что менять

### В Tracker:
1. WS handler: auth/auth.ok/event dispatch/ack
2. REST API: steps CRUD, reject_task, take_task (atomic)
3. Event dispatch: при assign/take/comment → WS push

### В Picogent:
1. MCP tools provider (обёртка над TrackerClient REST)
2. Router: разделить "в промпт" vs "internal"
3. WS протокол: согласовать с трекером
4. Listen modes: all vs mentions-only (из конфига)