@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/dispatch.md

@@ -0,0 +1,146 @@
+---
+title: "Expédition"
+description: "Le plan de contrôle de l'espace de travail : coffre-fort de secrets, hub d'intégration, délégué inter-applications et boîte de réception centrale pour Slack, e-mail, Telegram, WhatsApp."
+---
+
+# Expédition
+
+Dispatch est l'application centrale qui se trouve devant toutes les autres applications de votre espace de travail et gère les secrets, les intégrations, la messagerie et la délégation entre applications. Il s'agit du **plan de contrôle de l'espace de travail** : l'agent unique avec lequel votre équipe communique, les informations d'identification uniques en direct et le routeur unique qui décide quelle application spécialisée doit traiter une demande donnée.
+
+> **Distribuez le modèle par rapport au package `@agent-native/dispatch`.** Cette page couvre le concept d'application/modèle Dispatch : ce qu'il fait et pourquoi vous le souhaitez. Le package `@agent-native/dispatch` npm est le runtime publié séparément qui regroupe la logique de serveur du modèle Dispatch (coffre-fort, intégrations, destinations, tâches planifiées et délégation inter-applications) en tant que package drop-in pour les espaces de travail qui l'étendent. Pour l'application échafaudée elle-même (itinéraires, écrans, guide de l'agent), consultez le [Dispatch template](/docs/template-dispatch).
+
+Sans Dispatch, chaque application dans un espace de travail multi-applications finit par réimplémenter la même plomberie : son propre robot Slack, son propre magasin secret, ses propres tâches planifiées, sa propre copie des instructions de l'espace de travail. La rotation d’une clé API se transforme en dix redéploiements. L’ajout d’une nouvelle politique se transforme en dix copier-coller. Dispatch centralise tout cela dans une seule application afin que les autres restent concentrés sur leur domaine.
+
+```an-diagram title="Dispatch as the workspace control plane" summary="One inbox, one vault, one MCP gateway, and shared resources sit in front of the domain apps, which Dispatch reaches as A2A peers."
+{
+  "html": "<div class=\"dsp-hub\"><div class=\"diagram-node\">Users &amp; external agents<br><small class=\"diagram-muted\">Slack · email · Telegram · WhatsApp · MCP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel dsp-control\" data-rough><span class=\"diagram-pill accent\">Dispatch &mdash; control plane</span><div class=\"dsp-caps\"><span class=\"diagram-pill\">Central inbox</span><span class=\"diagram-pill\">Secret vault</span><span class=\"diagram-pill\">Cross-app delegation</span><span class=\"diagram-pill\">MCP gateway</span><span class=\"diagram-pill\">Workspace resources</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"dsp-peers\"><div class=\"diagram-box\" data-rough>Mail</div><div class=\"diagram-box\" data-rough>Calendar</div><div class=\"diagram-box\" data-rough>Analytics</div></div><small class=\"diagram-muted\">domain apps &mdash; A2A peers</small></div>",
+  "css": ".dsp-hub{display:flex;flex-direction:column;align-items:center;gap:10px}.dsp-hub .dsp-control{display:flex;flex-direction:column;align-items:center;gap:10px;width:100%}.dsp-hub .dsp-caps{display:flex;gap:8px;flex-wrap:wrap;justify-content:center}.dsp-hub .dsp-peers{display:flex;gap:10px;flex-wrap:wrap;justify-content:center}"
+}
+```
+
+## Quand vous souhaitez envoyer {#when}
+
+Contactez le répartiteur lorsque l'une de ces conditions est vraie :
+
+- Vous utilisez un [multi-app workspace](/docs/multi-app-workspace) (courrier, calendrier, analyses, contenu) et vous ne voulez pas d'un seul bot Slack par application.
+- Vous voulez **une boîte de réception pour "l'agent"** afin que les utilisateurs envoient un seul robot en DM et que la bonne application spécialisée se charge du travail en coulisses.
+- Vous disposez de **secrets à l'échelle de l'espace de travail** (clé Stripe, clé OpenAI, jetons API tiers) dont plusieurs applications ont besoin et vous souhaitez un seul coffre-fort au lieu de copier les valeurs dans chaque `.env`.
+- Vous souhaitez un **flux d'approbation d'exécution** avant les modifications sensibles (destinations enregistrées, modifications de stratégie) afin que les non-administrateurs puissent demander et que les administrateurs puissent se déconnecter sans déploiement de code.
+- Vous souhaitez que les **skills partagés, les instructions, les profils d'agent et les serveurs MCP** dont les applications de l'espace de travail héritent – changent une fois, atteignent tous.
+
+Si vous exécutez un seul modèle autonome, vous n'avez pas besoin de Dispatch : chaque modèle peut câbler directement ses propres intégrations de messagerie. Voir [Messaging](/docs/messaging) pour la configuration autonome.
+
+## Ce que fait Dispatch {#what-it-does}
+
+Sept fonctionnalités, toutes situées au-dessus de la même base de données d'espace de travail que celles utilisées par les autres applications :
+
+| Capacité                              | Ce que cela vous donne                                                                                 | Configurez-le                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| **Boîte de réception centrale**       | Slack, e-mail, Telegram, WhatsApp atteignent tous un seul agent avec mémoire partagée + outils         | **Paramètres → Messagerie** ([Messaging](/docs/messaging))     |
+| **Coffre secret**                     | Stockez chaque identifiant une fois ; effectuer une rotation au même endroit dans chaque application   | **Vault** + mode d'accès (toutes les applications ou manuel)   |
+| **Délégation inter-applications**     | Achemine une demande vers la bonne application spécialisée via A2A et répond dans le fil de discussion | Automatique ([A2A](/docs/a2a-protocol))                        |
+| **Passerelle unifiée MCP**            | Un connecteur MCP pour les agents externes atteint chaque application d'espace de travail accordée     | [External Agents](/docs/external-agents)                       |
+| **Ressources de l'espace de travail** | Auteur skills/instructions/profils une fois ; les applications en héritent au moment de l'exécution    | **Ressources** ([Workspace](/docs/workspace#global-resources)) |
+| **Rêves**                             | Examine les exécutions/commentaires passés et propose des améliorations durables à approuver           | Onglet **Rêves**                                               |
+| **Flux d'approbation**                | Gestion des modifications d'exécution sensibles derrière la révision par l'administrateur en ligne     | **Politique d'approbation d'expédition**                       |
+
+Chacun est détaillé ci-dessous.
+
+### Boîte de réception centrale
+
+Slack, les e-mails, Telegram et WhatsApp circulent tous dans la boucle des agents de Dispatch. Connectez chaque plateforme une fois dans **Paramètres → Messagerie** et chaque canal atteint le même agent avec la même mémoire et les mêmes outils. Un DM Slack et un e-mail adressé à `agent@yourcompany.com` se transforment en deux surfaces sur un seul historique de conversation, et non en deux robots déconnectés. Voir [Messaging](/docs/messaging) pour les informations d'identification et le webhook URL.
+
+### Coffre secret
+
+Stockez les informations d'identification une fois dans le coffre-fort de Dispatch. Par défaut, l'accès au coffre-fort s'effectue **toutes les applications** : chaque clé enregistrée est disponible pour chaque application d'espace de travail et `sync-vault-to-app` transfère l'intégralité du coffre-fort vers l'application cible. Les espaces de travail qui nécessitent une séparation plus stricte peuvent faire passer le coffre-fort en mode **manuel**, où des autorisations explicites par application sont requises avant la synchronisation. Les non-administrateurs peuvent **demander** un secret pour une application ; les administrateurs **approuvent**, ce qui crée le secret et, dans les flux de travail manuels, l'octroi. Chaque lecture, attribution, synchronisation et rotation est capturée dans un journal d'audit. C'est ce qui fait de la « rotation de la clé OpenAI » une opération en un seul clic sur dix applications au lieu de dix PR.
+
+### Délégation inter-applications
+
+Dispatch découvre automatiquement les autres applications de votre espace de travail en tant que pairs A2A : pas d'enregistrement manuel, pas de configuration par application. Lorsqu'un utilisateur demande « Résumer les inscriptions de la semaine dernière » dans Slack, Dispatch reconnaît cela comme une demande d'analyse et appelle l'application d'analyse via [A2A](/docs/a2a-protocol). Lorsqu'ils demandent « rédiger une réponse à Alice », cela est acheminé vers l'application de messagerie. Dispatch publie la réponse finale dans le fil de discussion d'origine. La règle de comportement réside dans les instructions du répartiteur : le travail de domaine appartient à l'application de domaine. Dispatch est l'orchestrateur, pas le spécialiste.
+
+### Passerelle unifiée MCP
+
+Dispatch peut être le connecteur MCP unique pour les agents externes : ajoutez `https://dispatch.agent-native.com/_agent-native/mcp` une fois dans Claude, ChatGPT, Codex ou Cursor, et une autorisation atteint chaque application d'espace de travail accordée au lieu d'un connecteur par application. Consultez [External Agents](/docs/external-agents) pour connaître le flux de connexion complet, les subventions d'application, OAuth et les aperçus de l'application MCP en ligne.
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "Unified MCP gateway endpoint",
+  "description": "The single MCP connector URL external agents add (e.g. `https://dispatch.agent-native.com/_agent-native/mcp`). One authorization here reaches every **granted** workspace app instead of wiring one connector per app. App grants, OAuth, and inline MCP App previews are covered in [External Agents](/docs/external-agents).",
+  "auth": "Standard remote MCP OAuth, handled by the framework. The granted-app set scopes which workspace apps the connector can reach.",
+  "responses": [
+    { "status": "200", "description": "MCP JSON-RPC response — tools, resources, and MCP App UI resources aggregated across granted workspace apps." }
+  ]
+}
+```
+
+### Ressources de l'espace de travail
+
+Skills, les instructions de garde-corps, les profils d'agent et les ressources de référence peuvent être créés une fois dans Dispatch et hérités par le reste de l'espace de travail. Les ressources avec la portée **Toutes les applications** sont globales : Dispatch les stocke une fois dans la portée de l'espace de travail et chaque agent d'application les lit au moment de l'exécution. Ils ne sont pas copiés dans chaque application et il n’y a pas d’étape de synchronisation manuelle espace de travail-ressource. Les ressources partagées de l'application et les ressources personnelles peuvent remplacer ou restreindre les paramètres par défaut de l'espace de travail localement.
+
+Voir [Workspace — Global resources](/docs/workspace#global-resources) pour le tableau des chemins canoniques, le pack de démarrage et le modèle de remplacement.
+
+Les ressources du serveur MCP utilisent JSON et sont intentionnellement réservées à HTTP. Stocker les jetons dans
+Distribuez Vault, accordez ou synchronisez ces clés avec les applications cibles et référencez-les
+à partir des en-têtes avec `${keys.NAME}` pour que les informations d'identification brutes ne vivent jamais dans le
+corps de ressource.
+
+La page **Ressources** met en évidence le pack de démarrage recommandé afin que les administrateurs puissent rapidement voir quels fichiers existent, restaurer les fichiers de démarrage manquants sans écraser ceux existants et modifier leur contenu. Développez n'importe quelle ressource pour prévisualiser sa pile d'exécution effective pour une application/un utilisateur sélectionné. Chaque fiche d'application dispose également d'une vue **Contexte** qui montre exactement ce que cette application reçoit.
+
+### Rêves
+
+Dispatch Dreams examine les exécutions précédentes des agents, les commentaires, les évaluations et les échecs répétés pour proposer des améliorations durables. Un rapport de rêve est une surface de révision, pas une réécriture silencieuse : il peut suggérer des mises à jour de la mémoire personnelle, un nettoyage de la mémoire obsolète, des modifications `LEARNINGS.md` partagées, des instructions/compétences/connaissances/ressources d'agent dans l'espace de travail, ou des tâches récurrentes, et chaque proposition renvoie aux exécutions qui la justifient. Les instructions partagées et les ressources à l'échelle de l'équipe doivent être examinées avant d'être appliquées, en particulier lorsque les preuves proviennent d'un Slack entrant, d'un courrier électronique, d'un télégramme, de WhatsApp ou d'un contenu Web.
+
+Avant de proposer une écriture, Dreams compare les preuves avec l'index de mémoire personnelle, les notes `memory/*.md` existantes et les `LEARNINGS.md` partagées. Si une leçon est déjà capturée, le rapport enregistre qu'elle a été ignorée ; si un souvenir personnel associé semble obsolète, la proposition cible cette note existante au lieu de créer un doublon.
+
+Démarrez à partir de l'onglet **Dreams** dans Dispatch. Exécutez d'abord une passe manuelle, ouvrez une feuille de révision de proposition pour comparer la cible actuelle avec le contenu proposé et les preuves sources, puis appliquez uniquement les modifications que vous souhaitez conserver. Une fois que les rapports sont constamment utiles, Dispatch peut créer une tâche de rêve récurrente qui continue de produire des propositions sans appliquer automatiquement des modifications partagées ou au niveau des instructions.
+
+### Flux d'approbation
+
+Dispatch peut gérer les modifications d'exécution sensibles après examen par l'administrateur. Aujourd'hui, cela couvre les **destinations enregistrées** (les canaux Slack et les adresses e-mail auxquelles l'agent peut envoyer de manière proactive), les **propositions de rêve** partagées/en équipe, les **ressources d'espace de travail** de toutes les applications créées/mises à jour/supprimées et la **politique d'approbation d'envoi** elle-même. Lorsque la stratégie est activée, la modification est mise en file d'attente et l'agent affiche un aperçu d'approbation en ligne directement dans le chat : les administrateurs approuvent ou rejettent sans quitter la conversation.
+
+## Comment un message Slack circule via Dispatch {#flow}
+
+Parcourez un exemple de bout en bout. Un utilisateur envoie un message privé au bot : _"résumer les inscriptions de la semaine dernière."_
+
+1. **Slack → webhook.** Slack `POST` à `/_agent-native/integrations/slack/webhook` sur l'application Dispatch. Le gestionnaire vérifie la signature et **insère une ligne dans `integration_pending_tasks`**, puis déclenche un `POST` auto-ciblé sur son propre processeur et renvoie immédiatement `200` afin que Slack ne réessaye pas.
+2. **Nouvelle exécution du processeur.** Le point de terminaison du processeur s'exécute dans une toute nouvelle exécution de fonction avec son propre délai d'attente complet. Il revendique atomiquement la tâche et démarre la boucle d'agent.
+3. **L'agent de répartition décide.** L'agent lit le message, reconnaît les « inscriptions » comme une intention d'analyse et appelle `call-agent` par rapport au [A2A endpoint](/docs/a2a-protocol) de l'application d'analyse. Le travail réel de SQL se déroule là-bas.
+4. **Réponse publiée dans le fil de discussion.** L'agent d'analyse renvoie un résultat. Dispatch le formate et le publie dans le même fil de discussion Slack dans lequel l'utilisateur a écrit, en utilisant l'identité liée s'il en existe une (de sorte que l'agent agit avec les autorisations du demandeur, et non celles du propriétaire de l'espace de travail).
+5. **Récupération en cas de panne.** Si le processeur plante en plein vol (délai d'expiration A2A, erreur de l'agent en aval, gel des fonctions), une nouvelle tentative balaie les tâches bloquées toutes les 60 secondes et relance le processeur. Jusqu'à trois tentatives avant que la tâche ne soit marquée `failed`.
+
+```an-diagram title="A Slack message through Dispatch" summary="Slack enqueues into SQL, a fresh execution drains it, the Dispatch agent delegates the domain work over A2A, and the reply lands back in the originating thread. A 60s retry job recovers anything that dies mid-flight."
+{
+  "html": "<div class=\"dsp-flow\"><div class=\"dsp-row\"><div class=\"diagram-node\">Slack DM<br><small class=\"diagram-muted\">\"summarize last week's signups\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/slack/webhook</strong><br><small class=\"diagram-muted\">verify + INSERT pending task</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">200</div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough><strong>fresh processor</strong><br><small class=\"diagram-muted\">claim task · start agent loop</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch agent decides</span><small class=\"diagram-muted\">analytics intent &rarr; call-agent</small></div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough>Analytics app<br><small class=\"diagram-muted\">A2A peer · runs the SQL work</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">reply posted in thread</div></div><div class=\"diagram-panel dsp-retry\" data-rough><span class=\"diagram-pill warn\">recovery</span> <span class=\"diagram-muted\">if the processor crashes &mdash; A2A timeout, downstream error, freeze &mdash; the 60s retry job re-fires it (&le;3 attempts) so the Slack reply still arrives</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</span></div></div>",
+  "css": ".dsp-flow{display:flex;flex-direction:column;gap:12px}.dsp-flow .dsp-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.dsp-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.dsp-flow .dsp-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+Le même flux s'applique aux e-mails, Telegram et WhatsApp : seul l'adaptateur change.
+
+## Histoire de fiabilité {#reliability}
+
+L'ensemble du pipeline est conçu pour survivre sur chaque hôte sans serveur (Netlify, Vercel, Cloudflare Workers) sans s'appuyer sur des API d'exécution en arrière-plan spécifiques à la plate-forme.
+
+- **Webhook → file d'attente SQL → processeur de nouvelle exécution.** La boucle d'agent ne s'exécute jamais à l'intérieur du gestionnaire de webhook. Le seul travail du gestionnaire est de vérifier, de mettre en file d'attente et de renvoyer 200. Une nouvelle exécution distincte draine la file d'attente, de sorte qu'une exécution lente de l'agent ne peut jamais bloquer le webhook entrant ni provoquer une nouvelle tentative de la plate-forme.
+- **Interrogation de continuation A2A.** Lorsque Dispatch délègue à une autre application, il interroge la tâche en aval avec un délai d'expiration limité. Si l'agent en aval prend trop de temps ou plante, Dispatch enregistre la suite et la tâche de nouvelle tentative la récupère : la réponse Slack de l'utilisateur arrive toujours.
+- **A2A inter-applications signé automatiquement.** Les espaces de travail multi-applications hébergés génèrent automatiquement des informations d'identification A2A par application au moment du déploiement, afin que les applications du même espace de travail puissent s'appeler sans jamais coller un secret JWT. La couche de découverte d'agent de Dispatch lit ces informations d'identification dans la base de données de l'espace de travail afin que les applications nouvellement ajoutées apparaissent automatiquement en tant que homologues appelables.
+
+## Configuration {#setup}
+
+Trois courtes étapes :
+
+1. **Élaborez un espace de travail qui inclut Dispatch.** Exécutez `npx @agent-native/core@latest create my-company-platform` et choisissez `dispatch` à côté des modèles de domaine de votre choix. Dispatch vit à `apps/dispatch` et le reste des applications se trouve à côté. Voir [Multi-App Workspace](/docs/multi-app-workspace).
+2. **Connectez la messagerie.** Ouvrez **Paramètres → Messagerie** dans Dispatch et cliquez sur Connecter pour Slack, Email, Telegram ou WhatsApp. Les champs du formulaire correspondent aux variables d'environnement dans le document [Messaging](/docs/messaging) – reportez-vous ici pour connaître les besoins de chaque plate-forme.
+3. **Ajoutez d'autres applications.** Exécutez `npx @agent-native/core@latest add-app` à partir de la racine de l'espace de travail pour chaque application de domaine. Ils apparaissent automatiquement en tant que pairs A2A dans `list-workspace-apps` de Dispatch — pas d'enregistrement manuel, pas de modification de la carte d'agent. Dispatch commencera à leur déléguer dès que leurs cartes d'agent seront accessibles.
+
+Ajoutez ensuite les informations d'identification au coffre-fort et (éventuellement) créez des ressources d'espace de travail globales sous **Ressources**. Les clés du coffre-fort peuvent toujours être synchronisées ou accordées en fonction du mode d'accès ; Les ressources de l’espace de travail de toutes les applications sont héritées automatiquement. Si vous avez besoin d'une isolation secrète par application, définissez le paramètre d'accès au coffre-fort sur manuel avant d'accorder des applications individuelles.
+
+## Voir aussi {#see-also}
+
+- [Dispatch template](/docs/template-dispatch) : la véritable application échafaudée, avec son catalogue d'actions complet et son guide d'agent
+- [Messaging](/docs/messaging) — connexion Slack, e-mail, Telegram, WhatsApp
+- [A2A Protocol](/docs/a2a-protocol) : comment fonctionne la délégation entre applications en coulisses
+- [Multi-App Workspace](/docs/multi-app-workspace) — la forme de déploiement pour laquelle Dispatch est conçu
+- [Workspace Governance](/docs/workspace-management) — gouvernance git/GitHub qui s'associe à la gouvernance d'exécution de Dispatch

package/corpus/core/docs/content/locales/fr-FR/drop-in-agent.md

@@ -0,0 +1,260 @@
+---
+title: "Agent sans rendez-vous"
+description: "Montez le chat de l'agent + l'espace de travail dans n'importe quelle application React avec <AgentPanel>, <AgentSidebar> et sendToAgentChat()."
+---
+
+# Agent sans rendez-vous
+
+> **Page développeur.** Cette page est destinée aux développeurs qui intègrent l'agent dans une application React. Pour connaître l'expérience de l'utilisateur final en matière d'utilisation de l'agent, voir [Using Your Agent](/docs/using-your-agent).
+
+Vous n'avez pas besoin de créer un agent natif à partir de zéro. Le chat de l'agent, l'onglet de l'espace de travail, le terminal CLI, la saisie vocale et toute l'infrastructure associée sont livrés sous la forme d'une poignée de composants React que vous déposez dans n'importe quelle application.
+
+> **Prérequis :** le serveur doit exécuter `agent-chat-plugin` (il se monte automatiquement dans chaque modèle). Si vous partez de zéro, voir [Server](/docs/server).
+>
+> Besoin de la carte publique API au lieu d'un didacticiel ? Voir [Component API](/docs/components).
+
+## Les composants en un coup d'œil {#components}
+
+| Composant             | Qu'est-ce que c'est                                                                                                     | Utilisez-le quand                                                                       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `<AgentSidebar>`      | Enveloppe la présentation de votre application racine et ajoute un panneau latéral basculable contenant l'agent complet | Vous souhaitez que l'agent soit disponible à côté de votre application sur chaque écran |
+| `<AgentToggleButton>` | Ouvre/ferme `<AgentSidebar>` (mettez-le dans votre en-tête)                                                             | Paire avec `<AgentSidebar>`                                                             |
+| `<AgentPanel>`        | Le panneau brut lui-même – chat + CLI + onglets de l'espace de travail                                                  | Vous souhaitez un contrôle total sur la mise en page ou une page d'agent dédiée         |
+| `<AgentChatSurface>`  | Une surface de discussion panneau/page pré-câblée                                                                       | Vous souhaitez discuter sans le wrapper de la barre latérale                            |
+| `<AssistantChat>`     | Rendu de chat de niveau inférieur avec crochets de composition/historique                                               | Vous avez besoin d'un chrome personnalisé autour de la conversation standard UI         |
+| `sendToAgentChat()`   | Envoyer un message au chat par programmation                                                                            | Un bouton qui confie le travail à l'agent au lieu de l'exécuter en ligne                |
+| `useActionMutation()` | Wrapper frontal Typesafe autour d'une action                                                                            | Le UI doit exécuter la même opération qu'un outil d'agent exécuterait                   |
+
+Tous ces éléments sont exportés depuis `@agent-native/core/client`.
+
+```an-diagram title="The mount model" summary="<AgentSidebar> wraps your existing layout. Your routes render in the main area; the agent panel mounts beside them. <AgentPanel> is the same panel without the wrapper."
+{
+  "html": "<div class=\"diagram-mount\"><div class=\"diagram-box sidebar\" data-rough><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><div class=\"inner\"><div class=\"diagram-node main\">Your app<br><small class=\"diagram-muted\">children: header + &lt;Outlet/&gt;</small></div><div class=\"diagram-node panel\">Agent panel<br><small class=\"diagram-muted\">chat &middot; CLI &middot; workspace</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card alt\"><span class=\"diagram-pill\">&lt;AgentPanel&gt;</span><small class=\"diagram-muted\">same panel, no wrapper &mdash; you own the layout</small></div></div>",
+  "css": ".diagram-mount{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mount .sidebar{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-mount .inner{display:flex;gap:10px}.diagram-mount .main{flex:2}.diagram-mount .panel{flex:1}.diagram-mount .alt{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-mount .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Le cas 80 % : `<AgentSidebar>` {#sidebar}
+
+La configuration la plus courante est une barre latérale qui s'ouvre depuis la droite sur n'importe quel écran.
+Enveloppez votre disposition racine existante avec `<AgentSidebar>` ; peu importe ce que vous faites passer
+les enfants restent dans la zone principale de l'application. Le chat de l'agent est le panneau latéral.
+
+```an-annotated-code title="Wrapping the root layout with <AgentSidebar>"
+{
+  "filename": "app/root.tsx",
+  "language": "tsx",
+  "code": "import { Outlet } from \"react-router\";\nimport { AgentSidebar, AgentToggleButton } from \"@agent-native/core/client\";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText=\"How can I help?\"\n      suggestions={[\n        \"Summarize my inbox\",\n        \"Draft a reply to the latest email\",\n        \"Show me yesterday's signup numbers\",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position=\"right\"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}",
+  "annotations": [
+    { "lines": "6", "label": "Wrapper", "note": "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area." },
+    { "lines": "8-12", "label": "Starter prompts", "note": "`suggestions` render as clickable chips on the empty chat." },
+    { "lines": "13", "label": "Context-aware chips", "note": "`dynamicSuggestions` merges screen-aware prompts (e.g. \"Summarize this selection\") with your static ones. On by default." },
+    { "lines": "18-20", "label": "Toggle button", "note": "Put `<AgentToggleButton />` anywhere in your header to open and close the panel." },
+    { "lines": "22-24", "label": "Your app", "note": "`<Outlet/>` (your routes) renders in the main area, untouched." }
+  ]
+}
+```
+
+C'est tout. L'utilisateur dispose désormais d'un agent commutable sur chaque page – avec historique des discussions, onglet espace de travail, terminal CLI, saisie vocale et mode plein écran. L'état persiste lors des rechargements via `localStorage`.
+
+### Accessoires
+
+- **`children`** : présentation et itinéraires normaux de votre application. Rendu dans la zone principale ; le panneau d'agent se monte à côté sur le bureau et par-dessus sur mobile/plein écran.
+- **`emptyStateText`** — message d'accueil affiché lorsque le chat n'a aucun message. Par défaut : `"How can I help you?"`.
+- **`suggestions`** — invites de démarrage affichées sous forme de puces cliquables lorsqu'elles sont vides.
+- **`dynamicSuggestions`** — puces d'invite contextuelles fusionnées avec `suggestions`. Activé par défaut ; transmettez `false` pour afficher uniquement les suggestions statiques, ou `{ max, includeStatic, getSuggestions }` pour personnaliser.
+- **`defaultSidebarWidth`** — largeur de pixel initiale (montage uniquement ; redimensionnement par l'utilisateur et remplacement de la valeur enregistrée). Par défaut : `380`.
+- **`position`** — `"left"` ou `"right"`. Par défaut : `"right"`.
+- **`defaultOpen`** — indique si la barre latérale démarre ouverte (bureau uniquement). Par défaut : `false`.
+
+## Les 20 % restants : `<AgentPanel>` {#panel}
+
+Lorsque vous avez besoin d'un contrôle total sur la mise en page (un itinéraire `/chat` dédié, un panneau intégré dans une colonne latérale que vous gérez ou une fenêtre contextuelle), effectuez le rendu direct de `<AgentPanel>` :
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>` vous donne les onglets bruts (Chat / CLI / Espace de travail) sans le wrapper de la barre latérale, le bouton de réduction ou toute persistance d'état. Placez-le où vous voulez ; vous gérez la mise en page.
+
+### Accessoires sélectionnés
+
+- **`defaultMode`** — `"chat"` ou `"cli"`. Par défaut : `"chat"`.
+- **`className`** — Classe CSS pour le conteneur externe.
+- **`onCollapse`** — s'il est fourni, un bouton de réduction apparaît dans l'en-tête.
+- **`isFullscreen`** / **`onToggleFullscreen`** – connectez l'état plein écran externe si vous souhaitez une colonne centrée de style Claude.
+- **`storageKey`** — espace de noms pour les clés `localStorage`. Utile lorsque vous affichez plusieurs panneaux (différentes instances d'application ou espaces de travail) sur la même page.
+
+Accessoires complets : `AgentPanelProps` dans `@agent-native/core/client`.
+
+## Messages programmatiques : `sendToAgentChat()` {#send}
+
+Un bouton qui confie le travail à l'agent (au lieu d'exécuter un appel `llm()` en ligne — l'anti-modèle du [ladder](/docs/what-is-agent-native#the-ladder)) :
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### Options
+
+- **`message`** — l'invite visible affichée dans le chat.
+- **`context`** — contexte masqué ajouté à l'invite (texte sélectionné, position du curseur, identifiant d'entité actuel — tout ce que l'agent doit savoir mais que l'utilisateur ne doit pas voir deux fois).
+- **`submit`** — `true` à exécuter automatiquement, `false` à pré-remplir mais attendre. Omettre d'utiliser la valeur par défaut du projet.
+- **`newTab`** : créez un fil de discussion distinct pour cette invite.
+- **`background`** — avec `newTab`, exécutez sans focaliser le nouveau thread. La course cachée est suivie dans `RunsTray`.
+- **`openSidebar`** — défini sur `false` pour les envois en arrière-plan/silencieux. La valeur par défaut ouvre la barre latérale pour que l'utilisateur voie la réponse.
+- **`type`** — `"content"` (par défaut) conserve le travail dans l'agent d'application intégré. `"code"` achemine vers le cadre d'édition de code (pour les modifications de code écrites par l'agent, voir [Frames](/docs/frames)).
+
+`sendToAgentChat` renvoie un `tabId` stable que vous pouvez utiliser pour suivre l'exécution du chat.
+
+Pour un travail silencieux, associez `newTab`, `background` et `openSidebar: false` :
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+Il s'agit toujours d'un agent complet exécuté avec des outils, actions, l'état du thread et une exécution
+suivi. Cela ne détourne tout simplement pas le focus de l'état actuel de la barre latérale de l'utilisateur.
+
+Lorsque le même itinéraire est intégré en tant qu'application MCP, soumis
+Les appels `sendToAgentChat()` sont transférés vers le chat hôte lorsque cela est pris en charge ; voir
+[Client](/docs/client#sendtoagentchat) pour le comportement du pont de l'application MCP.
+
+Si vous souhaitez un état de chargement, utilisez le hook `useSendToAgentChat()` : il renvoie à la fois `send` et `isGenerating` :
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## Lorsque la barre latérale d'origine ne convient pas {#custom-chat-ui}
+
+`<AgentSidebar>` et `<AgentPanel>` couvrent la plupart des applications. Quand vous devez posséder le
+disposition autour de l'agent, ou vous souhaitez alimenter la conversation avec un agent
+vous avez construit ailleurs, déposez une couche — mais continuez à laisser le framework s'approprier
+État d'exécution, actions et SQL :
+
+- **Possédez Chrome autour du runtime standard.** Utilisez `<AgentChatSurface>` pour
+  une route de chat dédiée, ou `<AssistantChat>` lorsque vous souhaitez des en-têtes personnalisés,
+  onglets et états vides autour de la conversation standard. La carte en couches complète —
+  chaque composant, hook, compositeur et adaptateur, avec les chemins d'importation, réside dans
+  [Component API](/docs/components#agent-chat-ui).
+- **Apportez votre propre environnement d'exécution d'agent.** Si un agent que vous avez créé ailleurs le devrait
+  alimentez la conversation pendant que Agent-Native conserve le compositeur, la transcription et l'outil
+  cartes, approbations et widgets natifs, transmettez un `AgentChatRuntime` à
+  `<AssistantChat runtime={...} />`. Les connecteurs
+  (`createHttpAgentChatRuntime()` et le OpenAI / Claude / Vercel AI / AG-UI
+  aides) et le contrat d'événement sont documentés dans
+  [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+Quelle que soit la couche que vous choisissez, conservez l'état des applications soutenues par actions et SQL comme contrat,
+et évitez de publier directement sur `/_agent-native/agent-chat` à partir du produit UI. Si un
+l'assistant nommé manque pour une véritable surface personnalisée, ajoutez d'abord cet assistant donc
+le code client n'apprend pas un deuxième transport ad hoc.
+
+## Typesafe actions du UI : `useActionMutation()` {#use-action-mutation}
+
+Lorsque le UI doit exécuter la même opération qu'un outil d'agent exécuterait (échelon 3 du [ladder](/docs/what-is-agent-native#rung-three)), utilisez `useActionMutation` :
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+Les arguments de type sécurisé proviennent du schéma zod de votre `defineAction()`. Voir [Actions](/docs/actions) pour le système d'action complet.
+
+```an-callout
+{
+  "tone": "decision",
+  "body": "**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button (\"Send reply\"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder)."
+}
+```
+
+## Sélection + connaissance du curseur {#selection}
+
+L'agent peut voir ce que l'utilisateur a sélectionné (texte, cellules, diapositives, contacts) via les touches `navigation` et `selection` dans l'état d'application. Le chat vide utilise également ces touches pour proposer des suggestions dynamiques telles que « Résumer cette sélection » ou « Améliorer cette diapositive » lorsque l'écran actuel les rend pertinentes. Si vous souhaitez que Cmd-I (ou similaire) envoie une plage sélectionnée dans le chat en tant que contexte, voir [Context Awareness](/docs/context-awareness).
+
+## Rassembler tout cela {#putting-it-together}
+
+Une configuration sans rendez-vous typique :
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+L'utilisateur voit un bouton de discussion dans l'en-tête, peut l'ouvrir et parler à l'agent. Vos boutons fonctionnent manuellement avec ce même agent au lieu d'exécuter des appels LLM ponctuels.
+
+## Quelle est la prochaine étape
+
+- [**Actions**](/docs/actions) — `defineAction()` et `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — sélection, navigation, écran d'affichage
+- [**Workspace**](/docs/workspace) : ce que contient l'onglet Espace de travail (skills, mémoire, serveurs MCP, tâches planifiées)
+- [**Voice Input**](/docs/voice-input) — le microphone dans l'éditeur de chat

package/corpus/core/docs/content/locales/fr-FR/durable-resume.md

@@ -0,0 +1,65 @@
+---
+title: "CV durable"
+description: "Lorsqu'une exécution d'un agent hébergé est interrompue et reprend, les appels d'outils à effets secondaires terminés ne sont pas réexécutés : un journal des appels d'outils dérivé du grand livre durable bloque les envois, les frais et les tickets en double."
+---
+
+# CV durable
+
+> **À qui s'adresse-t-il :** toute personne souhaitant comprendre le fonctionnement du framework
+> évite les effets secondaires en double. Il s'agit d'un comportement intégré — il y a
+> rien à câbler.
+
+L'exécution d'un agent hébergé est interrompue : une fonction sans serveur atteint son délai d'expiration en cours de route, une passerelle interrompt la connexion au bout de 45 s, un socket raccroche, la plate-forme démarre à froid. Le framework s'en récupère déjà en enregistrant le préfixe de conversation et en réexécutant l'appel LLM (« continuez là où vous vous êtes arrêté »). Mais la récupération seule a un avantage : si la tentative interrompue **a déjà envoyé un e-mail ou créé un ticket**, un CV naïf pourrait recommencer.
+
+Un CV durable comble cet écart. À la reprise, le framework sait quels appels d'outils à effets secondaires ont déjà été effectués et refuse de les réexécuter - sur deux couches.
+
+```an-diagram title="Two layers block duplicate side effects on resume" summary="The journal reads the durable ledger and classifies prior calls; layer 1 tells the model, layer 2 hard-blocks a re-dispatched write that matches a completed entry."
+{
+  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">Layer 2 · hard-block re-dispatched write</div></div></div>",
+  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Le journal des appels d'outils {#journal}
+
+Le journal est une **lecture pure sur le grand livre durable des événements d'exécution** : il n'y a pas de nouveau point d'enregistrement dans le chemin actif. Il classe les appels d'outils déjà enregistrés pour le tour en cours :
+
+- **Terminé** — un `tool_start` avec un `tool_done` correspondant. L'appel a été lancé, son effet secondaire s'est produit et son résultat a été enregistré. **Ne réexécutez pas.**
+- **Interrompu** — un `tool_start` avec **aucun** correspondant à `tool_done`. L’appel a commencé, ses effets secondaires ont peut-être eu lieu ou non, et l’interruption a rongé le résultat. Résultat inconnu.
+
+La correspondance reflète la façon dont les virages durables sont reconstruits ailleurs : un `tool_done` s'associe au plus ancien `tool_start` encore ouvert pour le même nom d'outil (FIFO par outil). Un événement `clear` (sortie partielle rejetée) réinitialise le décompte par tour afin que les partiels abandonnés ne laissent pas d'appels fantômes ouverts.
+
+## Couche 1 : note de journal au niveau de l'invite {#prompt-note}
+
+Lorsqu'une exécution reprend (délai d'expiration logiciel, délai d'expiration de la passerelle ou toute erreur de transport pouvant être reprise), le framework ajoute une **note de journal structuré** à l'invite de reprise, juste après le coup de pouce « reprendre là où vous vous êtes arrêté ». La note indique au modèle, en texte brut :
+
+- quel outil appelle **déjà terminé** (avec des résultats courts) afin qu'il les réutilise et ne les réexécute **pas**, et
+- quels appels d'outil ont été **interrompus avec un résultat inconnu** afin qu'il vérifie l'état avant de supposer un succès ou un échec.
+
+Lorsque le journal est vide (un tour sans activité d'outil ou une continuation propre), rien de plus n'est ajouté et le comportement de reprise est octet pour octet ce qu'il était avant. La note est de la meilleure des manières : un échec de lecture du grand livre ne bloque jamais une récupération qui autrement réussirait.
+
+## Couche 2 : bloc dur de la couche d'outils {#hard-block}
+
+La note d'invite est consultative : un modèle bien élevé en tient compte, mais un modèle n'est pas une garantie. La boucle l'applique donc également au niveau de la couche d'outils.
+
+Avant que la boucle ne s'exécute dans un morceau repris, elle prend un instantané du journal une fois (en capturant uniquement les morceaux **précédents** de ce tour logique). Lorsque le modèle réexpédie un outil **d'écriture** dont le nom d'outil **et l'entrée** correspondent à une entrée de journal terminée, la boucle court-circuite : elle renvoie le résultat journalisé au lieu d'exécuter l'action, avec une note indiquant que l'appel a déjà été terminé lors d'une tentative interrompue antérieure et n'a pas été réexécuté pour éviter un effet secondaire en double.
+
+Propriétés clés :
+
+- **Outils d'écriture uniquement.** Lecture seule (`readOnly` / GET) Les actions ne sont jamais bloqués — la relecture est sûre et idempotente.
+- **Contenu adressé.** La correspondance porte sur le nom de l'outil + la signature d'entrée, donc un appel repris à une position différente dans le tour correspond toujours ; un appel _différent_ (arguments différents) est traité comme nouveau et s'exécute normalement.
+- **À consommer une fois.** Chaque entrée terminée est réclamée lorsqu'elle correspond, de sorte que deux nouveaux appels identiques véritablement distincts au cours du même tour ne court-circuitent pas tous les deux lors d'une achèvement journalisée.
+- **Les nouveaux appels restent intacts.** Un appel au premier tour voit un journal vide ; rien ne change pour les exécutions normales.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "Together the two layers mean an interrupted run that already had a real side effect resumes **without repeating it** — no duplicate emails, charges, or tickets — while genuinely new work still runs. Read-only actions are never blocked; re-reading is always safe."
+}
+```
+
+## Connexe
+
+- [**Real-Time Sync**](/docs/real-time-collaboration) : comment le grand livre d'exécution durable est diffusé vers le client et rejoué lors de la reconnexion.
+- [**Actions**](/docs/actions) : `readOnly` indique que la lecture est sûre et peut être réexécutée ; tout le reste est traité comme un effet secondaire.
+- [**In-Loop Processors**](/docs/processors) — une autre couture de durcissement interne à la boucle.