Чат-каналы

Как Telegram, веб-виджет, HTTP API и MCP-сервер подключаются к одному интерфейсу ChatChannel.

Все входящие в Cradle сообщения используют единый абстрактный интерфейс ChatChannel. Независимо от того, пришло сообщение из Telegram, виджета на сайте, REST-вызова или MCP-клиента, оно проходит через один и тот же triage, RAG и approval pipeline.

Интерфейс ChatChannel

type IncomingMessage = {
  channelId: 'telegram' | 'widget' | 'api'
  chatId: string
  userId?: string
  text: string
  timestamp: number
  attachments?: Array<{ type: string; url?: string; name?: string }>
  channelMeta: Record<string, unknown>
}

type SendMeta = { inReplyTo?: string; markdown?: boolean }

interface ChatChannel {
  id: string
  start(): Promise<void>
  stop(): Promise<void>
  onMessage(handler: (msg: IncomingMessage) => void): void
  sendMessage(chatId: string, text: string, meta?: SendMeta): Promise<void>
  sendAttachment?(chatId: string, attachment: unknown): Promise<void>
  markTyping?(chatId: string): Promise<void>
}

ChannelManager (src/core/channels/channel-manager.ts) ведёт реестр каналов, запускает и останавливает их согласно channels_config.enabled, и маршрутизирует исходящие ответы обратно в нужный канал.

TelegramChannel построен на grammY с long polling. Не требуется публичный URL, что подходит для on-premise-развёртываний за файрволом. Конфигурация — только токен бота в channels_config.telegram.config.botToken.

Веб-виджет

WidgetChannel поднимает Fastify-сервер в main process на порту 31415 по умолчанию. Раздаёт self-contained IIFE bundle (packages/widget/), который монтируется через shadow DOM и общается по WebSocket.

Embed-snippet:

<script
  src="https://cradle.example.com:31415/widget.js"
  data-cradle-widget
  data-api-key="wk_..."
  data-accent="#10b981"
  data-position="bottom-right"
  async></script>

Bundle ~49 KB gzipped. История хранится в браузерном localStorage, visitorId генерируется при первом открытии.

Endpoint	Назначение
`GET /widget.js`	Раздача bundle
`GET /api/widget/config/:apiKey`	Тема, позиция, locale
`POST /api/widget/message`	Приём сообщения посетителя
`WS /api/widget/ws`	Real-time ответы и typing

Аутентификация виджета — channel-level API key и опциональный allowedOrigins.

HTTP API

ApiChannel — REST-канал, подробно описан в HTTP API reference. Поддерживает sync, async и webhook режимы и предназначен для мобильных приложений, web-бэкендов, CLI-интеграций и инструментов автоматизации.

MCP-сервер

McpServerChannel выставляет возможности Cradle как MCP-tools через Streamable HTTP на порту 31417 по умолчанию. Это направление по умолчанию: Cradle — сервер, клиенты (SmartNotes, n8n, Claude Code) к нему подключаются.

Tool	Scope	Назначение
`cradle_search_kb`	`kb:read`	RAG-поиск
`cradle_list_kbs`	`kb:read`	Список баз знаний
`cradle_list_agents`	`agents:read`	Список агентов
`cradle_execute_agent`	`agents:execute`	Stateless вызов агента
`cradle_get_ticket`	`tickets:read`	Чтение тикета
`cradle_list_tickets`	`tickets:read`	Список тикетов
`cradle_summarize_notes`	`agents:execute`	Очистка и суммаризация заметок
`cradle_submit_issue`	`messages:write`	Создать тикет в общем Inbox

MCP-запросы reuse тот же Bearer / X-Api-Key middleware и scope-проверки, что и HTTP API, прежде чем попасть в MCP-транспорт.

SmartNotes flow

SmartNotes (MCP-клиент) отправляет все надиктованные заметки скопом в cradle_summarize_notes. Cradle очищает текст, делает summary и извлекает issues, возвращает их клиенту.
Оператор ревьюит issues в SmartNotes и отправляет выбранные через cradle_submit_issue. Cradle создаёт тикет в общем Inbox, прогоняет triage по всем проектам и маршрутизирует issue в проект победившего агента. Автоответа нет — каждый issue всегда уходит оператору на ревью.

Запуск и остановка каналов

Desktop-приложение показывает каждый канал в Integrations. На headless-сервере каналы стартуют автоматически, если включены в channels_config. CLI может показать список через cradle channels list.