Canaux de chat

Toutes les entrées Cradle partagent une seule abstraction ChatChannel. Qu'un message arrive de Telegram, d'un widget de site web, d'un appel REST ou d'un client MCP, il passe par le même pipeline de triage, RAG et approbation.

Interface 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) maintient un registre des canaux, les démarre et arrête selon channels_config.enabled, et route les réponses sortantes vers le bon canal.

Telegram

TelegramChannel est construit sur grammY avec du long polling. Aucune URL publique n'est requise, ce qui convient aux déploiements on-premise derrière des pare-feu. La configuration se limite au jeton de bot dans channels_config.telegram.config.botToken.

Widget web

WidgetChannel héberge un serveur Fastify dans le processus principal sur le port 31415 par défaut. Il sert un bundle IIFE autonome (packages/widget/) qui se monte via shadow DOM et communique par WebSocket.

Snippet d'intégration :

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

Le bundle fait ~49 KB gzippé. L'historique est stocké dans le localStorage du navigateur, et visitorId est généré à la première ouverture.

L'authentification widget utilise une clé API de niveau canal et une liste optionnelle allowedOrigins.

HTTP API

ApiChannel est le canal REST décrit dans la référence HTTP API. Il supporte les modes sync, async et webhook, et est destiné aux apps mobiles, backends web, intégrations CLI et outils d'automatisation.

Serveur MCP

McpServerChannel expose les capacités Cradle comme des outils MCP sur Streamable HTTP sur le port 31417 par défaut. C'est le sens par défaut : Cradle est le serveur, et des clients comme SmartNotes, n8n ou Claude Code l'appellent.

Les requêtes MCP réutilisent le même middleware Bearer / X-Api-Key et les mêmes vérifications de scope que l'API HTTP avant d'atteindre le transport MCP.

Flux SmartNotes

1. SmartNotes envoie les notes dictées à cradle_summarize_notes. Cradle nettoie le texte, le résume et extrait des problèmes, les renvoyant au client.
2. L'opérateur examine les problèmes dans SmartNotes et envoie ceux sélectionnés via cradle_submit_issue. Cradle crée un ticket dans la Boîte de réception partagée, exécute le triage sur tous les projets, et route le problème vers le projet de l'agent gagnant. Il n'y a pas de réponse automatique ; chaque problème soumis atterrit en revue opérateur.

Démarrer et arrêter les canaux

L'application de bureau affiche chaque canal dans Intégrations. Sur un serveur headless, les canaux démarrent automatiquement s'ils sont activés dans channels_config. Le CLI peut lister les canaux avec cradle channels list.