@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/messaging.md

@@ -0,0 +1,461 @@
+---
+title: "Messagerie"
+description: "Parlez à votre agent depuis Slack, par e-mail, Telegram ou WhatsApp : même agent, même mémoire, mêmes outils."
+---
+
+# Messagerie
+
+Connectez votre agent à Slack, à la messagerie électronique, à Telegram ou à WhatsApp afin de pouvoir discuter avec lui à partir des applications que vous utilisez déjà. Il s'agit du même agent : même mémoire, mêmes outils, mêmes threads, accessible depuis plusieurs endroits.
+
+> **Vous utilisez le modèle Dispatch ?** Tout cela est configuré pour vous dans **Paramètres → Messagerie**. Cliquez pour connecter chaque plateforme. Vous n'avez pas besoin de lire le reste de cette page, sauf si vous personnalisez ou créez votre propre modèle. Voir [Dispatch](/docs/dispatch) ou [Dispatch template reference](/docs/template-dispatch).
+
+## Ce que vous pouvez faire {#what-you-can-do}
+
+- **Envoyez un e-mail à votre agent** à une adresse telle que `agent@yourcompany.com` : il répond dans le fil de discussion, tout comme le ferait un collègue.
+- **CC votre agent** sur un fil de discussion : il lira et interviendra lorsque vous le demanderez.
+- **DM l'agent sur Slack**, ou `@mention` sur n'importe quel canal.
+- **Envoyez un message à l'agent sur Telegram ou WhatsApp** depuis votre téléphone.
+- **Même agent, même mémoire.** Tout ce que vous lui dites sur Slack est mémorisé lorsque vous l'enverrez par e-mail plus tard. Le chat Web et les messages externes partagent un historique de fil de discussion.
+- Pour les alertes unidirectionnelles dans l'application (icône en forme de cloche, webhooks), voir [Notifications](/docs/notifications).
+
+```an-diagram title="Many channels, one agent" summary="Every platform fans into the same agent loop and the same SQL thread history — so a Slack DM and an email continue the same conversation."
+{
+  "html": "<div class=\"msg-fanin\"><div class=\"diagram-col\"><div class=\"diagram-node\">Slack</div><div class=\"diagram-node\">Email</div><div class=\"diagram-node\">Telegram</div><div class=\"diagram-node\">WhatsApp</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">One agent loop</span><small class=\"diagram-muted\">same memory · same tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>One SQL thread history<br><small class=\"diagram-muted\">web chat + external messages share it</small></div></div>",
+  "css": ".msg-fanin{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.msg-fanin .diagram-col{display:flex;flex-direction:column;gap:8px}.msg-fanin .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Configurer Slack {#slack}
+
+### Ce dont vous aurez besoin
+
+- Un espace de travail Slack dans lequel vous pouvez installer des applications (accès administrateur)
+- Environ 5 minutes
+
+### Étapes
+
+1. Accédez à **[api.slack.com/apps](https://api.slack.com/apps)** et cliquez sur **Créer une nouvelle application** → **À partir de zéro**. Nommez-le (par exemple "Agent") et choisissez votre espace de travail.
+2. Dans la barre latérale gauche, ouvrez **OAuth et autorisations**. Sous **Étendues des jetons de bot**, ajoutez :
+   - `chat:write` : permet à l'agent d'envoyer des messages
+   - `app_mentions:read` — permet à l'agent de voir quand il est @-mentionné (facultatif)
+   - `im:history` — permet à l'agent de lire les DM qui lui sont envoyés
+   - `assistant:write` — facultatif ; permet à Slack d'afficher le statut natif "pense..." dans les fils de discussion de l'assistant
+   - `users:read.email` — facultatif ; aide les modèles tels que Mail à vérifier l'e-mail de l'expéditeur Slack pour l'identité de la file d'attente des brouillons
+3. Cliquez sur **Installer sur Workspace** en haut de cette page. Slack vous donnera un **Jeton OAuth d'utilisateur de robot** qui commence par `xoxb-`. Copiez-le.
+4. Accédez à **Informations de base** dans la barre latérale et copiez le **Secret de signature**.
+5. Ouvrez les paramètres de votre application (ou le panneau des variables d'environnement de votre fournisseur d'hébergement) et collez :
+   - `SLACK_BOT_TOKEN` — le jeton `xoxb-…`
+   - `SLACK_SIGNING_SECRET` — le secret de signature
+   - `SLACK_ALLOWED_TEAM_IDS` — recommandé en production ; ID d'espace de travail/d'équipe Slack séparés par des virgules autorisés à envoyer des événements
+   - `SLACK_ALLOWED_API_APP_IDS` : recommandé pour les applications multi-espaces de travail ; ID d'application Slack séparés par des virgules autorisés à utiliser ce secret de signature
+6. De retour dans Slack, ouvrez **Abonnements aux événements**, activez-le et collez cette demande URL :
+
+   ```texte
+   https://your-app.example.com/_agent-native/integrations/slack/webhook
+   ```
+
+   Ensuite, sous **S'abonner aux événements du bot**, ajoutez `message.im` (pour les DM) et éventuellement `app_mention` (pour les mentions de chaîne). Enregistrer.
+
+7. Envoyez un DM à votre bot dans Slack. Il devrait répondre.
+
+### Facultatif : l'application se déploie
+
+L'application Slack se déploie, permettant à une application de remplacer l'aperçu du lien normal de Slack par un aperçu plus riche
+aperçu. Clips l'utilise pour les aperçus vidéo lisibles de style Loom.
+
+Ajoutez ces étendues de robot supplémentaires lorsque votre application a besoin de se déployer :
+
+- `links:read` : permet à Slack d'avertir l'application lorsque des domaines enregistrés sont publiés
+- `links:write` : permet à l'application de remplacer l'aperçu par défaut de Slack
+- `links.embed:write` : permet à l'application d'intégrer des médias/lecteurs URL approuvés
+
+Ensuite, abonnez-vous à l'événement `link_shared` et enregistrez vos domaines d'application publics
+sous **Domaines de déploiement d'application**. Pour les aperçus lisibles uniquement des clips, définissez le paramètre Slack
+Demande d'abonnement aux événements URL à :
+
+```text
+https://your-clips.example.com/api/slack/unfurl
+```
+
+Une application Slack possède une demande d'événements API URL. Si la même application Slack doit gérer
+les événements de discussion des agents et les clips se déroulent, acheminent les événements Slack via un petit
+répartiteur qui envoie des événements de message à `/_agent-native/integrations/slack/webhook`
+et les événements `link_shared` vers le gestionnaire de déploiement des clips.
+
+### Conseils
+
+- **Mentions de canal** : le bot ne répond dans les canaux que lorsqu'il est mentionné par @, pour éviter le bruit.
+- **DMs** — chaque DM est traité comme une conversation privée avec l'agent.
+- **Même identité, tous les canaux** — si un utilisateur Slack a la même adresse e-mail qu'un utilisateur enregistré dans votre application, l'agent le traite comme la même personne.
+- **Listes autorisées de production** : définissez `SLACK_ALLOWED_TEAM_IDS` et, pour les applications Slack partagées, `SLACK_ALLOWED_API_APP_IDS` afin qu'un secret de signature valide ne puisse pas être réutilisé par un espace de travail inattendu.
+- **L'application Clips se déploie** — Les clips Agent-Native installables pour Slack utilisent `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET` et `/api/slack/oauth/callback`. Chaque espace de travail Slack connecté obtient son propre jeton de bot crypté dans `app_secrets` ; `SLACK_BOT_TOKEN` n'est qu'une solution de secours héritée pour un seul espace de travail.
+
+## Configurer Telegram {#telegram}
+
+### Ce dont vous aurez besoin
+
+- L'application Telegram sur votre téléphone
+- Environ 3 minutes
+
+### Étapes
+
+1. Ouvrez le télégramme et envoyez le message **[@BotFather](https://t.me/BotFather)**.
+2. Envoyez `/newbot` et suivez les instructions pour nommer votre bot. BotFather répondra avec un **jeton HTTP API**. Copiez-le.
+3. Dans les variables d'environnement de votre application, définissez :
+   - `TELEGRAM_BOT_TOKEN` — le jeton de BotFather
+4. Après le déploiement, enregistrez le webhook en `POST`ing sur votre application à l'adresse :
+
+   ```texte
+   POST https://your-app.example.com/_agent-native/integrations/telegram/setup
+   ```
+
+   Cela indique à Telegram d'envoyer des messages au webhook de votre application. Vous ne devez le faire qu'une seule fois par déploiement.
+
+5. Trouvez votre bot dans Telegram (recherchez le nom d'utilisateur que BotFather vous a donné) et envoyez-lui un message.
+
+## Configurer la messagerie {#email}
+
+La messagerie électronique constitue l'intégration la plus puissante : votre agent obtient sa propre adresse, répond dans le fil de discussion, peut être mis en copie des conversations et utilise l'adresse électronique de l'expéditeur comme identité. Aucune commande `/link` n'est nécessaire.
+
+### Ce dont vous aurez besoin
+
+- Un domaine que vous contrôlez (ou vous pouvez utiliser un sous-domaine Renvoyer gratuit – voir ci-dessous)
+- Un compte avec **Resend** ou **SendGrid** pour gérer le courrier entrant et sortant
+- Environ 10 minutes
+
+### Étapes (avec Renvoyer — le plus simple)
+
+1. Inscrivez-vous sur **[resend.com](https://resend.com)**. L'offre gratuite est suffisante pour commencer.
+2. Choisissez à quoi ressemblera l'adresse e-mail de l'agent :
+   - **Le plus simple :** utilisez une adresse `<your-slug>.resend.app` gratuite — aucun DNS n'est nécessaire.
+   - **Branded :** ajoutez un domaine personnalisé (comme `yourcompany.com`) dans la page **Domaines** de Renvoyer et suivez les étapes DNS.
+3. Dans Renvoyer, ouvrez **Webhooks** → **Ajouter un point de terminaison** et pointez-le vers :
+
+   ```texte
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+   Abonnez-vous à l'événement **`email.received`**. Renvoyer vous donnera un secret de signature : copiez-le.
+
+4. Dans les variables d'environnement de votre application, définissez :
+   - `EMAIL_AGENT_ADDRESS` — l'adresse à laquelle l'agent reçoit le courrier (par exemple `agent@yourcompany.com`)
+   - `RESEND_API_KEY` — votre clé de renvoi API
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` : le secret de signature de Renvoyer (recommandé ; utilisé pour la vérification de la signature)
+
+5. Envoyer un e-mail à l'adresse de l'agent. Il répondra dans le même fil de discussion.
+
+### Étapes (avec SendGrid)
+
+1. Inscrivez-vous sur **[sendgrid.com](https://sendgrid.com)**.
+2. Ajoutez l'enregistrement MX pour votre domaine afin que le courrier entrant soit envoyé vers SendGrid :
+   ```texte
+   MX yourcompany.com → mx.sendgrid.net (priorité 10)
+   ```
+3. Ouvrez **Paramètres → Analyse entrante**, cliquez sur **Ajouter un hôte et URL** et définissez la destination sur :
+
+   ```texte
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+4. Définir les variables d'environnement :
+   - `EMAIL_AGENT_ADDRESS` — l'adresse à laquelle l'agent reçoit
+   - `SENDGRID_API_KEY` — votre clé SendGrid API
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` – secret de signature Svix facultatif si vous avez configuré un webhooks signé
+
+5. Envoyer un e-mail à l'adresse de l'agent.
+
+### Conseils
+
+- **CC l'agent** pour l'introduire dans un fil de discussion. Lorsque l'agent est mis en copie, il répondra à tous afin que l'ensemble du thread voie la réponse.
+- **Le thread fonctionne tout simplement** : l'agent utilise les en-têtes standards `Message-ID` / `In-Reply-To` / `References`, de sorte que les réponses restent dans le bon fil de discussion dans n'importe quel client de messagerie.
+- **L'identité est l'e-mail de l'expéditeur.** Si `alice@acme.com` envoie un e-mail à l'agent, c'est _c'est_ son identité – pas de lien ni de flux d'inscription.
+- **Réponses riches** — la démarque dans la réponse de l'agent est rendue sous la forme HTML dans l'e-mail.
+- **Domaines autorisés** : limitez les personnes pouvant envoyer un e-mail à l'agent en définissant `allowedDomains` dans la configuration de l'intégration ; les messages provenant d'autres domaines sont supprimés.
+- **Limite de débit** : 20 messages entrants par heure et par expéditeur.
+
+## Configurer WhatsApp {#whatsapp}
+
+### Ce dont vous aurez besoin
+
+- Un compte développeur Meta (Facebook)
+- Un numéro de téléphone que vous pouvez dédier au bot
+- Environ 15 minutes (la configuration de Meta comporte le plus d'étapes)
+
+### Étapes
+
+1. Accédez à **[Meta Developer Portal](https://developers.facebook.com/)**, cliquez sur **Créer une application** et sélectionnez le type **Business**.
+2. Ajoutez le produit **WhatsApp** à votre application et configurez un numéro de téléphone à utiliser en tant qu'expéditeur.
+3. Depuis la page de configuration de WhatsApp, saisissez :
+   - **Jeton d'accès** (le jeton temporaire convient aux tests ; générez un jeton permanent avant la mise en ligne)
+   - **Identifiant du numéro de téléphone**
+4. Choisissez n'importe quelle chaîne aléatoire à utiliser comme jeton de vérification : vous entrerez la même valeur à deux endroits ci-dessous.
+5. Dans les variables d'environnement de votre application, définissez :
+   - `WHATSAPP_ACCESS_TOKEN` — votre jeton d'accès
+   - `WHATSAPP_PHONE_NUMBER_ID` – l'identifiant du numéro de téléphone
+   - `WHATSAPP_VERIFY_TOKEN` — la chaîne aléatoire que vous avez choisie
+6. De retour dans la configuration WhatsApp de Meta, ouvrez la section webhook et définissez :
+
+   ```texte
+   Rappel URL : https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
+   Vérifier le jeton : la même chaîne aléatoire que vous avez définie comme WHATSAPP_VERIFY_TOKEN
+   ```
+
+   Abonnez-vous au champ `messages`.
+
+7. Envoyez un message WhatsApp au numéro de téléphone du bot.
+
+## Utilisez Dispatch comme boîte de réception centrale de votre agent {#dispatch}
+
+Si vous exécutez plusieurs applications natives d'agent (courrier, calendrier, analyses, etc.), le modèle recommandé consiste à configurer la messagerie sur **[Dispatch](/docs/dispatch)** (voir également [template reference](/docs/template-dispatch)) et à la laisser acheminer le travail vers vos applications de domaine via [A2A](/docs/a2a-protocol).
+
+Pourquoi c'est sympa :
+
+- **Un agent, une boîte de réception.** Tous vos canaux (Slack, e-mail, Telegram, WhatsApp) circulent dans Dispatch. Vous ne configurez les intégrations qu'une seule fois.
+- **Répartir les délégués.** Demander « résumer les inscriptions de la semaine dernière » – Dispatch appelle l'agent d'analyse. Demandez « rédigez une réponse à Alice » – Dispatch appelle l'agent de messagerie.
+- **Clics, pas de configuration.** La page **Paramètres → Messagerie** de Dispatch comporte des boutons de connexion pour chaque plate-forme avec les champs env-var intégrés.
+
+Si vous n'avez pas besoin d'un orchestrateur, n'importe quel modèle peut connecter la messagerie directement à l'aide des variables d'environnement de cette page.
+
+---
+
+## Pour les développeurs {#for-developers}
+
+Tout ce qui suit est la référence technique. Si vous avez terminé les étapes de configuration ci-dessus, vous pouvez vous arrêter ici, sauf si vous personnalisez le plug-in d'intégration ou créez votre propre adaptateur.
+
+### Comment ça marche {#how-it-works}
+
+La plate-forme entrante webhooks utilise un modèle de file d'attente SQL multiplateforme afin de fonctionner sur chaque hôte sans serveur (Netlify, Vercel, Cloudflare Workers, Fly, Render, Node) sans s'appuyer sur les API d'exécution en arrière-plan spécifiques à la plate-forme.
+
+1. La plateforme `POST`s à `/_agent-native/integrations/<platform>/webhook`. Le gestionnaire vérifie la signature, analyse la charge utile dans un `IncomingMessage` et **insère une ligne dans `integration_pending_tasks`** avec `status='pending'`.
+2. Le gestionnaire tire un `POST /_agent-native/integrations/process-task` « feu et oubli » et renvoie immédiatement le `200`, bien à l'intérieur du SLA de 3 secondes du Slack.
+3. Le point de terminaison du processeur s'exécute dans une **nouvelle exécution de fonction** avec son propre budget d'expiration complet. Il revendique atomiquement la tâche (`pending` → `processing` via `claimPendingTask`), exécute la boucle d'agent, publie la réponse via l'adaptateur et marque la tâche `completed`.
+4. Une nouvelle tentative récurrente (`startPendingTasksRetryJob`, toutes les 60 s) balaie les tâches bloquées dans `pending` > 90 s ou `processing` > 5 min et relance le processeur. Plafonné à 3 tentatives, puis marqué `failed`.
+
+```an-diagram title="Inbound webhook lifecycle" summary="The webhook only verifies, enqueues, and returns 200. A fresh function execution drains the queue and runs the agent loop, with a 60s retry job as the safety net."
+{
+  "html": "<div class=\"msg-flow\"><div class=\"msg-row\"><div class=\"diagram-node\">Platform<br><small class=\"diagram-muted\">Slack · email · etc.</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/webhook</strong><br><small class=\"diagram-muted\">verify signature + parse</small><br><span class=\"diagram-pill\">INSERT pending task</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">return 200</div></div><div class=\"msg-fire\"><span class=\"diagram-muted\">fire-and-forget</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</span></div><div class=\"msg-row\"><div class=\"diagram-box\" data-rough><strong>/process-task</strong><br><small class=\"diagram-muted\">fresh execution · own timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">claim</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">agent loop</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">adapter.sendResponse</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">completed</div></div><div class=\"diagram-panel msg-retry\" data-rough><span class=\"diagram-pill warn\">every 60s</span> <span class=\"diagram-muted\">retry job sweeps stuck tasks (pending &gt;90s · processing &gt;5min) and re-fires /process-task &mdash; capped at 3 attempts, then <strong>failed</strong></span></div></div>",
+  "css": ".msg-flow{display:flex;flex-direction:column;gap:12px}.msg-flow .msg-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.msg-flow .msg-fire{display:flex;align-items:center;gap:8px;padding-inline-start:12px}.msg-flow .msg-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+Les conversations entrantes et sortantes vivent dans le même fil de discussion SQL, vous pouvez donc continuer un DM Slack depuis le Web UI ou vice versa.
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/integrations/slack/webhook",
+  "summary": "Slack Events API inbound webhook",
+  "description": "Receives Slack events (DMs and channel `app_mention`s). Verifies the request signature, parses the payload into an `IncomingMessage`, inserts a `pending` row into `integration_pending_tasks`, fires the fresh-execution processor, and returns **200 immediately** — well inside Slack's 3-second SLA. The same route shape exists per platform under `/_agent-native/integrations/<platform>/webhook`.",
+  "auth": "HMAC-SHA256 of the raw body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. In production also gated by `SLACK_ALLOWED_TEAM_IDS` / `SLACK_ALLOWED_API_APP_IDS`.",
+  "params": [
+    { "name": "X-Slack-Signature", "in": "header", "type": "string", "required": true, "description": "Slack request signature, verified before any processing." },
+    { "name": "X-Slack-Request-Timestamp", "in": "header", "type": "string", "required": true, "description": "Timestamp used in the signature base string." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"type\": \"event_callback\",\n  \"team_id\": \"T0123\",\n  \"api_app_id\": \"A0123\",\n  \"event\": {\n    \"type\": \"message\",\n    \"channel_type\": \"im\",\n    \"user\": \"U0123\",\n    \"text\": \"summarize last week's signups\"\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "Acknowledged immediately. The agent loop runs in the separate /process-task execution. The first time a Request URL is saved, Slack POSTs a `url_verification` challenge and the adapter replies with the `challenge` value automatically.", "example": "{ \"ok\": true }" },
+    { "status": "401", "description": "Signature verification failed, or the team/app id is not in the production allowlist." }
+  ]
+}
+```
+
+#### Pourquoi ce modèle (et non les raccourcis natifs de la plateforme) {#why-this-pattern}
+
+Les fonctions sans serveur se bloquent au moment où la réponse est envoyée. Tout ce qui est encore en cours d'exécution, y compris une promesse de tir et d'oubli, un appel LLM différé ou un outil en vol, est tué en cours d'exécution. La seule façon de maintenir une boucle d'agent en vie est de démarrer une **nouvelle** exécution de fonction pour celle-ci, ce que fait le `/process-task` POST auto-déclenché.
+
+NOT utilise-t-il l'une de ces alternatives :
+
+- **Fonctions d'arrière-plan Netlify** – Netlify uniquement, nécessite un suffixe de nom de fichier `-background.ts`, s'interrompt sur tous les autres hôtes.
+- **Cloudflare `event.waitUntil()`** – CF Workers uniquement, non portable.
+- **Vercel `after()` / Fluid** – Vercel uniquement, protégé par des durées d'exécution spécifiques.
+- **Promesses nues de tirer et d'oublier après `return`** — tué silencieusement lorsque la fonction se bloque ; aucune erreur dans les journaux, l'utilisateur ne reçoit tout simplement jamais de réponse.
+
+La combinaison file d'attente SQL + auto-webhook + nouvelle tentative de tâche est la seule chose qui fonctionne de manière identique sur chaque hôte pris en charge. La tâche de nouvelle tentative constitue le filet de sécurité : ne supposez jamais que la répartition initiale a été vidée avant que la fonction ne se fige.
+
+### Le plugin d'intégrations {#plugin}
+
+Le plugin se monte automatiquement lorsqu'aucune version personnalisée n'existe. Pour personnaliser, créez :
+
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
+
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
+
+Les plates-formes actives dépendent des variables d'environnement définies. Le plugin enregistre les routes de webhook pour chacune d'entre elles sous `/_agent-native/integrations/`.
+
+### Webhook URL {#webhook-urls}
+
+```text
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+/_agent-native/integrations/email/webhook
+```
+
+Telegram expose également un point de terminaison de configuration unique :
+
+```text
+POST /_agent-native/integrations/telegram/setup
+```
+
+### Variables d'environnement {#env-vars}
+
+| Plateforme | Obligatoire                                                                  | Facultatif                                            |
+| ---------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Slack      | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                    | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
+| Télégramme | `TELEGRAM_BOT_TOKEN`                                                         | —                                                     |
+| E-mail     | `EMAIL_AGENT_ADDRESS`, plus un parmi `RESEND_API_KEY` ou `SENDGRID_API_KEY`  | `EMAIL_INBOUND_WEBHOOK_SECRET`                        |
+| WhatsApp   | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` | —                                                     |
+
+Toutes les informations d'identification résident dans les variables d'environnement – jamais dans la base de données, jamais dans le code source. Utilisez les paramètres de la barre latérale UI ou le panneau d'environnement de votre fournisseur d'hébergement.
+
+### Threading et identité {#threading-and-identity}
+
+Chaque conversation externe est mappée à un thread persistant dans la base de données native de l'agent :
+
+- **Slack DM** → un thread par utilisateur Slack.
+- **Canal Slack @mention** → un thread par canal.
+- **Chat Telegram** → un fil de discussion par chat Telegram.
+- **Conversation WhatsApp** → un fil de discussion par numéro WhatsApp.
+- **Email** → threading dérivé des en-têtes `Message-ID` / `In-Reply-To` / `References`.
+
+Les fils de discussion externes apparaissent sur le Web UI aux côtés des fils de discussion d'origine Web, étiquetés avec leur plate-forme source. Résolution d'identité : lorsqu'un utilisateur Slack/e-mail correspond à un utilisateur enregistré (généralement par e-mail), il est lié à ce compte.
+
+### Sécurité {#security}
+
+Chaque webhook entrant est vérifié par sa signature avant d'être traité :
+
+- **Slack** — HMAC-SHA256 du corps utilisant `SLACK_SIGNING_SECRET`, vérifié par rapport à l'en-tête `X-Slack-Signature`. La première fois que vous enregistrez une demande URL dans le panneau Abonnements aux événements de Slack, Slack POST un défi `url_verification` ; l'adaptateur du framework détecte cela et répond automatiquement avec la valeur `challenge`, de sorte que le URL devient vert dans Slack sans aucun travail supplémentaire de votre part.
+- **Telegram** : jeton secret défini lors de l'enregistrement du webhook.
+- **WhatsApp** – Défi de vérification de Meta (à l'aide de `WHATSAPP_VERIFY_TOKEN`) plus signature de charge utile.
+- **Email** — Vérification de signature de style Svix lorsque `EMAIL_INBOUND_WEBHOOK_SECRET` est défini (Resend et SendGrid utilisent tous deux ce format). Si le secret n'est pas défini, le webhook est accepté mais un avertissement est enregistré.
+
+L'adaptateur de messagerie applique également :
+
+- **Domaines autorisés** : tableau `allowedDomains` facultatif dans la ligne `integration_configs` de l'intégration ; les expéditeurs en dehors de la liste sont supprimés.
+- ** Limite de débit ** : limite de débit soutenue par la file d'attente SQL de 20 messages entrants par expéditeur et par heure.
+
+### Envois proactifs {#proactive-sends}
+
+L'agent peut envoyer des messages de sa propre initiative (notifications, rappels, résumés planifiés) en appelant l'action `send-platform-message` avec un champ `platform` de `"slack"`, `"telegram"`, `"whatsapp"` ou `"email"`. L'action se trouve dans le package Dispatch sur `packages/dispatch/src/actions/send-platform-message.ts` et vous pouvez la copier/l'adapter pour n'importe quel modèle.
+
+### Adaptateurs personnalisés {#custom-adapters}
+
+Pour ajouter une nouvelle plateforme de messagerie, implémentez l'interface `PlatformAdapter` :
+
+```ts
+import type { H3Event } from "h3";
+import type {
+  PlatformAdapter,
+  IncomingMessage,
+  OutgoingMessage,
+} from "@agent-native/core/server";
+import type { EnvKeyConfig } from "@agent-native/core/server";
+
+const myAdapter: PlatformAdapter = {
+  platform: "discord",
+  label: "Discord",
+
+  // Env keys this adapter needs (rendered in the settings UI)
+  getRequiredEnvKeys(): EnvKeyConfig[] {
+    return [
+      { key: "DISCORD_BOT_TOKEN", label: "Discord Bot Token", required: true },
+    ];
+  },
+
+  // Handle platform-specific verification challenges (e.g. Slack's
+  // url_verification). Return { handled: true, response } to short-circuit.
+  async handleVerification(event: H3Event) {
+    return { handled: false };
+  },
+
+  // Validate the webhook request signature
+  async verifyWebhook(event: H3Event): Promise<boolean> {
+    // Validate signature headers; return true if authentic
+    return true;
+  },
+
+  // Parse the webhook payload into a normalized IncomingMessage.
+  // Return null to silently ignore the event (bot messages, edits, etc.).
+  async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
+    return {
+      platform: "discord",
+      externalThreadId: "channel-or-thread-id",
+      text: "the user's message",
+      senderId: "discord-user-id",
+      platformContext: { channelId: "channel-id" },
+      timestamp: Date.now(),
+    };
+  },
+
+  // Format plain agent text into a platform-appropriate OutgoingMessage.
+  // opts.threadDeepLinkUrl, when provided, is a URL back to the originating
+  // thread in the dispatch UI — render it as a button (Slack) or inline link.
+  formatAgentResponse(
+    text: string,
+    opts?: { threadDeepLinkUrl?: string },
+  ): OutgoingMessage {
+    return { text, platformContext: {} };
+  },
+
+  // Post the agent's response back to the platform
+  async sendResponse(
+    message: OutgoingMessage,
+    context: IncomingMessage,
+  ): Promise<void> {
+    // Call the platform's API, using context.platformContext for routing
+  },
+
+  // Return current connection/configuration status for the settings UI.
+  // baseUrl is the app's public URL, used for status checks that need it.
+  async getStatus(baseUrl?: string) {
+    return {
+      platform: "discord",
+      label: "Discord",
+      enabled: true,
+      configured: !!process.env.DISCORD_BOT_TOKEN,
+    };
+  },
+};
+```
+
+Enregistrez-le dans votre plugin d'intégrations :
+
+```ts
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  adapters: [myAdapter],
+});
+```
+
+Les implémentations de référence existent dans `packages/core/src/integrations/adapters/` (`slack.ts`, `telegram.ts`, `whatsapp.ts`, `email.ts`) : l'adaptateur de messagerie est l'exemple le plus complet, incluant la vérification de signature, le threading, la limitation de débit et le rendu HTML.
+
+### Fiabilité via Dispatch + suites A2A {#reliability}
+
+Lorsque [Dispatch](/docs/dispatch) délègue une requête à une autre application via [A2A](/docs/a2a-protocol#continuations), le flux de continuation-récupération garantit que l'utilisateur reçoit une réponse Slack/e-mail même si l'agent en aval plante en cours d'exécution. La tâche de webhook d'origine reste dans `processing` jusqu'à ce que la suite soit résolue ou que la nouvelle tentative de balayage la marque bloquée ; dans tous les cas, le fil de discussion de la plateforme obtient une réponse finale plutôt que de rester silencieux.
+
+Cela signifie qu'un espace de travail multi-applications géré par Dispatch est plus résilient qu'un modèle unique connecté directement à la messagerie : les échecs dans n'importe quelle application en aval se dégradent en un message d'erreur élégant au lieu d'une réponse abandonnée. Voir [A2A continuations](/docs/a2a-protocol#continuations) pour l'histoire complète de la garantie de livraison.
+
+### Pièges courants {#pitfalls}
+
+- **Ne lisez pas deux fois le corps de la requête.** Le flux de corps de h3 v2 est à consommer une fois : si vous appelez `readBody(event)` après que le framework a déjà analysé `event.node.req.body` (ou vice versa), la deuxième lecture bloque la requête indéfiniment. Cela apparaît le plus souvent avec Resend et SendGrid : les deux diffusent la charge utile entrante et la lecture en suspens ne se résout jamais, la plate-forme expire et le webhook est réessayé jusqu'à ce qu'il soit dédoublé. Si vous enveloppez le gestionnaire de webhook du framework dans votre propre middleware, transmettez le `IncomingMessage` déjà analysé via l'option `incoming` plutôt que de laisser le gestionnaire ré-analyser.
+- **N'exécutez pas de boucles d'agent à l'intérieur du gestionnaire de webhook.** Le gestionnaire doit être mis en file d'attente et revenir — la boucle d'agent s'exécute dans la nouvelle exécution du processeur. Le mettre en ligne garantit que le gel sans serveur tue l'exécution. De plus, les intégrations de passerelles publiques (telles que Netlify ou Vercel) appliquent des limites strictes de délai d'expiration HTTP (par exemple, la limite de requête de 10 secondes de Netlify). Étant donné que l'exécution des agents et des outils prend souvent plus de temps que cette fenêtre, la tentative d'exécution de la boucle de manière synchrone dans la requête webhook entraînera l'arrêt de la connexion par la passerelle, ce qui entraînera l'exécution interrompue et l'abandon des réponses. Le modèle de file d'attente `/process-task` auto-webhook signé HMAC est le seul moyen de satisfaire aux limites de la passerelle tout en exécutant la boucle complète de l'agent en toute sécurité.
+- **Ne comptez pas sur la mémoire de déduplication lors des démarrages à froid.** La clé de déduplication réside dans l'index unique SQL `(platform, external_event_key)`, et non dans une carte en cours de processus. Si vous remplacez la file d'attente, conservez la déduplication au niveau SQL ou les tentatives en double de Slack déclencheront des exécutions d'agent en double.
+- **Gardez l'auto-webhook URL accessible.** Le processeur URL est construit à partir de `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`, en retombant sur les en-têtes de requêtes entrantes. Lors des déploiements en version préliminaire avec des noms d'hôte réécrits, définissez-en un explicitement, sinon la répartition atteindra un 404.
+
+### Voir aussi {#see-also}
+
+- [Dispatch](/docs/dispatch) – Présentation du concept d'utilisation d'une boîte de réception centrale dans toutes les applications
+- [Dispatch template reference](/docs/template-dispatch) : boîte de réception centrale recommandée pour les espaces de travail multi-applications
+- [A2A Protocol](/docs/a2a-protocol) : comment les délégués de répartition fonctionnent avec d'autres agents, y compris la récupération continue
+- [Agent Mentions](/docs/agent-mentions) – Agents mentionnant `@` dans le chat Web

package/docs/content/locales/fr-FR/migration-workbench.md

@@ -0,0 +1,33 @@
+---
+title: "Migration vers Agent-Native (/migrate)"
+description: "La migration est un objectif /migrate intégré dans l'espace de travail Code Agent-Native, et non une application distincte. Voir le code Agent-Native UI pour le guide complet."
+---
+
+# Migration vers Agent-Native (/migrate)
+
+La migration n'est **pas un produit ou un modèle distinct** : il s'agit du produit intégré
+Objectif `/migrate` dans l'espace de travail [Agent-Native Code](/docs/code-agents-ui).
+Il s'exécute comme une session de code normale que vous pouvez reprendre, attacher, inspecter et arrêter.
+
+```an-diagram title="/migrate is a Code session, not a separate app" summary="A path, URL, or description goes in; the run shares the same store, transcript, and controls as every other Code session, and can emit a portable dossier."
+{
+  "html": "<div class=\"diagram-migrate\"><div class=\"diagram-col\"><div class=\"diagram-pill\">./local-app</div><div class=\"diagram-pill\">https://example.com</div><div class=\"diagram-pill\">--describe \\\"...\\\"</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">/migrate goal</span><small class=\"diagram-muted\">same store · transcript · run controls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>Migrated app</div><div class=\"diagram-pill ok\">--emit dossier</div></div></div>",
+  "css": ".diagram-migrate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-migrate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-migrate .diagram-arrow{font-size:22px;line-height:1}.diagram-migrate .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+```bash
+npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
+npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus dashboard"
+npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app   # shortcut into the same goal
+```
+
+Le guide complet — formes d'entrée (chemin / URL / description), dossiers `--emit`,
+Mode Plan vs Auto, contrôles d'exécution, informations d'identification, liens profonds sur le bureau et
+Exportations de packages `@agent-native/migrate` – réside dans
+[Agent-Native Code UI → Migrating to Agent-Native](/docs/code-agents-ui#migrate).
+
+> [!NOTE]
+> L'ancienne application de détails cachée `migration` a été supprimée. Utilisez le code
+> espace de travail, l'onglet Desktop Code ou un dossier émis comme pris en charge
+> surfaces.