docs/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

Router (обработка WS-событий)

WS event → Router:
  task.assigned    → buildPrompt() → runAgent(prompt, mcp_tools)
  chat.message     → если mention/listen:all → runAgent(message, mcp_tools)
  task.comment     → если mention → runAgent(comment, mcp_tools)
  task.taken       → internal: убрать из available (НЕ в промпт)
  task.status      → internal: проверить зависимости (НЕ в промпт)

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 (из конфига)