@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "Chat natif UI"
+description: "Renduurs de chat natifs déclarés par action, sorties DataTable/DataChart réutilisables et manière dont les environnements d'exécution de l'agent BYO doivent se connecter au chat Agent-Native."
+---
+
+# Chat natif UI
+
+Le chat natif UI est le chemin de rendu dans l'application pour la sortie des agents propriétaires. Un
+l'action renvoie un JSON structuré, le runtime de chat reconnaît un widget explicite
+discriminant, et `<AssistantChat>` restitue un véritable composant React dans le
+conversation. Vous ne créez pas d'iframe ou d'artefact HTML unique pour le
+chat normal dans l'application.
+
+Utiliser le chat natif UI lorsque l'utilisateur doit inspecter la sortie là où se trouve l'agent
+déjà parlant : résultats de requêtes, informations sur les réponses, résumés de configuration,
+contrôles d'approbation/refus ou liens vers des vues d'application. Utilisez [MCP Apps](/docs/mcp-apps)
+quand un hôte externe tel que Claude, ChatGPT, Copilot ou Cursor doit effectuer le rendu
+un itinéraire en ligne depuis votre application.
+
+```an-diagram title="The native render path" summary="An action returns JSON; the runtime matches an explicit widget discriminant or chatUI.renderer; AssistantChat mounts a real React component. No iframe, no HTML execution."
+{
+  "html": "<div class=\"diagram-render\"><div class=\"diagram-node\">Action runs<br><small class=\"diagram-muted\">returns structured JSON</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\">Match</span><small class=\"diagram-muted\">explicit widget &middot; chatUI.renderer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;AssistantChat&gt;<br><small class=\"diagram-muted\">mounts a React widget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill ok\">DataTable</div><div class=\"diagram-pill ok\">DataChart</div><div class=\"diagram-pill ok\">DataInsights</div></div></div>",
+  "css": ".diagram-render{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-render .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-render .col{display:flex;flex-direction:column;gap:6px;padding:12px}.diagram-render .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Widgets déclarés par action {#action-declared-widgets}
+
+Le chemin natif comporte deux parties explicites :
+
+- `outputSchema` valide la forme de réponse de l'action.
+- `chatUI.renderer` sélectionne le moteur de rendu natif React pour le résultat validé.
+
+Les moteurs de rendu de données intégrés utilisent un résultat JSON simple avec `widget` plus le
+charge utile correspondante :
+
+| Widget            | Charge utile requise        | Rendu comme                                                         |
+| ----------------- | --------------------------- | ------------------------------------------------------------------- |
+| `"data-table"`    | `table`                     | Une table de données native et réutilisable                         |
+| `"data-chart"`    | `chartSeries`               | Un graphique natif à barres, à courbes ou à aires                   |
+| `"data-insights"` | `table` et/ou `chartSeries` | Une carte d'informations combinée avec une sortie graphique/tableau |
+
+Le serveur actions doit importer les assistants et les schémas sécurisés pour le serveur à partir de
+`@agent-native/core/data-widgets` ; le code client peut importer les mêmes types depuis
+`@agent-native/core/client/chat` ou `@agent-native/core/client`.
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataInsightsWidgetResult,
+  dataInsightsWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Analyze form responses.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+    title: "Response insights",
+  },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response insights",
+      display: {
+        title: "42 responses",
+        description: "Completion rate rose this week.",
+        primaryAction: {
+          label: "Open response insights",
+          href: "/response-insights",
+        },
+      },
+      chartSeries: {
+        type: "bar",
+        title: "Responses by day",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 8 },
+          { day: "Tue", responses: 13 },
+        ],
+      },
+      table: {
+        title: "Top answers",
+        columns: [
+          { key: "answer", label: "Answer" },
+          { key: "count", label: "Count", align: "right" },
+        ],
+        rows: [
+          { answer: "Yes", count: 31 },
+          { answer: "No", count: 11 },
+        ],
+        totalRows: 2,
+      },
+    }),
+});
+```
+
+```an-callout
+{
+  "tone": "success",
+  "body": "The renderer only takes over when the action declares `chatUI` **or** the result carries an explicit known `widget` discriminant. It never shape-infers arbitrary objects and never executes HTML or JavaScript from tool results — so a native widget can't become an injection vector."
+}
+```
+
+Lorsqu'un utilisateur demande un graphique, un tableau, une tendance ou un rapport compact, les agents de l'application
+devrait préférer une action qui déclare l'un de ces moteurs de rendu natifs. La finale
+le texte de l'assistant doit rester bref et laisser le widget transporter les données ; ne copiez pas
+les mêmes lignes dans un tableau de démarques sauf si l'utilisateur demande explicitement un texte
+exporter.
+
+Lorsqu'aucune action de domaine n'existe mais que l'agent a déjà récupéré le compact,
+données véridiques, il peut appeler l'action du framework `render-data-widget` avec le
+même forme `data-table`, `data-chart` ou `data-insights` JSON. Cette action uniquement
+valide et restitue le widget ; ce n'est pas une source de données et ne doit pas être utilisé
+pour inventer des métriques d'espace réservé.
+
+## Sortie DataTable {#data-table}
+
+`table` est intentionnellement simple, donc la liste, SQL, les analyses et la configuration de actions peuvent
+réutilisez-le :
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+Préférez les clés de colonne stables et les valeurs de ligne sécurisées JSON. Utilisez `totalRows`,
+`sampledRows` et `truncated` lorsque l'action affiche une tranche d'un plus grand
+ensemble de résultats.
+
+## Sortie DataChart {#data-chart}
+
+`chartSeries` prend en charge les formes de graphique courantes utilisées dans les réponses des agents sans
+exiger que chaque modèle soit livré avec son propre moteur de rendu de chat :
+
+```ts
+{
+  type: "bar" | "line" | "area";
+  title?: string;
+  xKey: string;
+  series: Array<{ key: string; label: string; color?: string }>;
+  data: Array<Record<string, unknown>>;
+  sampled?: boolean;
+}
+```
+
+Gardez les données du graphique compactes. Pour les ensembles de données volumineux, regroupez-les dans l'action et liez
+vers la vue complète de l'application avec les métadonnées `display.primaryAction` ou l'action `link`.
+
+## Widgets natifs vs applications MCP {#native-vs-mcp-apps}
+
+Les widgets de chat natifs et les applications MCP sont complémentaires :
+
+- **Les widgets natifs** sont destinés au propre environnement de discussion de l'application. Le résultat de l'action est
+  JSON, et le framework restitue le widget React intégré.
+- **Les applications MCP** sont destinées aux hôtes externes. L'action déclare `mcpApp` et généralement
+  `link`, et l'hôte restitue un véritable itinéraire d'application en ligne lorsqu'il est pris en charge.
+- **Les liens profonds** restent la solution de repli universelle. Utilisez l'action `link` ou
+  `display.primaryAction` donc clients CLI, anciens hôtes MCP et transcription simple
+  les lecteurs peuvent ouvrir la vue complète de l'application.
+
+Lorsqu'une charge utile de widget natif et des métadonnées d'applications MCP sont présentes, l'application intégrée
+le chat préfère le widget natif. Les hôtes externes utilisent la ressource MCP Apps ou le
+Repli des liens profonds.
+
+## Rendu natifs personnalisés {#custom-native-renderers}
+
+Enregistrez les composants spécifiques au produit par identifiant exact du moteur de rendu, puis déclarez cet identifiant
+sur l'action :
+
+```tsx
+import { registerActionChatRenderer } from "@agent-native/core/client/chat";
+
+registerActionChatRenderer({
+  id: "crm.deal-card",
+  renderer: "crm.deal-card",
+  Component: ({ context }) => <DealCard result={context.resultJson} />,
+});
+```
+
+```ts
+export default defineAction({
+  description: "Show a deal card.",
+  outputSchema: dealCardSchema,
+  chatUI: { renderer: "crm.deal-card" },
+  run: async () => ({ dealId: "deal_123", amount: 42000 }),
+});
+```
+
+Utilisez-le pour l'application propriétaire UI. Conservez l'iframe multi-hôtes UI dans `mcpApp` et conservez
+exécution de requêtes arbitraires derrière une lecture tapée actions plutôt que SQL brute dans le chat.
+
+## Environnements d'exécution de l'agent BYO {#byo-agent-runtimes}
+
+`AgentChatRuntime` est le contrat « apportez votre propre agent » pour le shell de chat, et
+cette section est sa référence canonique. Il permet à un agent que vous avez créé ailleurs
+diffusez des événements normalisés dans la conversation UI de Agent-Native tout en conservant
+compositeur partagé, rendu des transcriptions, fiches outils, approbations, widgets natifs,
+et la disposition de l'application environnante. Le [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+points du didacticiel ici pour l'histoire d'exécution et [Component API](/docs/components#agent-chat-ui)
+répertorie chaque connecteur et adaptateur avec son chemin d'importation ; le contrat lui-même est
+décrit ci-dessous.
+
+```an-diagram title="BYO runtime keeps the Agent-Native chat shell" summary="Your external agent streams normalized events through a connector; Agent-Native keeps the composer, transcript, tool cards, approvals, and native widgets."
+{
+  "html": "<div class=\"diagram-byo\"><div class=\"diagram-box\" data-rough>Your agent<br><small class=\"diagram-muted\">OpenAI &middot; Claude &middot; Vercel AI &middot; AG-UI &middot; HTTP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">connector</span><small class=\"diagram-muted\">normalized message-* / tool-* events</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill\">&lt;AssistantChat runtime=&hellip; /&gt;</div><small class=\"diagram-muted\">composer &middot; transcript &middot; tool cards</small><small class=\"diagram-muted\">approvals &middot; native widgets</small></div></div>",
+  "css": ".diagram-byo{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-byo .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-byo .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-byo .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Tous les connecteurs sont exportés depuis `@agent-native/core/client/chat` (et la racine
+Entrée `@agent-native/core/client`). Utilisez le runtime générique HTTP lorsque votre agent
+peut exposer un point de terminaison POST qui renvoie des événements d'exécution SSE ou NDJSON :
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+Si votre point de terminaison diffuse déjà un protocole d'agent commun, utilisez le protocole correspondant
+connecteur et ignorez l'écriture d'un mappeur personnalisé :
+
+```ts
+import {
+  createAgUiChatRuntime,
+  createClaudeAgentChatRuntime,
+  createOpenAIAgentsChatRuntime,
+  createOpenAIResponsesChatRuntime,
+  createVercelAiChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agents/chat",
+});
+
+const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
+  endpoint: "/api/openai-responses/chat",
+});
+
+const claudeAgentRuntime = createClaudeAgentChatRuntime({
+  endpoint: "/api/claude-agent/chat",
+});
+
+const vercelAiRuntime = createVercelAiChatRuntime({
+  endpoint: "/api/vercel-ai/chat",
+});
+
+const agUiRuntime = createAgUiChatRuntime({
+  endpoint: "/api/ag-ui/chat",
+});
+```
+
+Le point de terminaison peut diffuser directement la forme d'événement normalisée :
+
+```text
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+Pour les agents très simples, une réponse JSON `{ "text": "..." }` est acceptée et
+converti en un seul message d'assistant. Pour les agents plus riches, diffusez
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+Événements `usage`, `error` et `done`. Les résultats de l'outil peuvent porter `mcpApp` ou
+Métadonnées `chatUI`, donc les widgets natifs déclarés par action s'affichent toujours sans
+iframe.
+
+Lorsque vous souhaitez que le transport Agent-Native intégré soit un objet d'exécution, utilisez :
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+Utilisez `<AssistantChat createAdapter={...} />` uniquement lorsque vous en avez besoin
+Contrôle de l'adaptateur assistant-ui. Utilisez `PromptComposer` seul lorsque votre produit
+possède l'intégralité de la transcription externe et ne souhaite que le compositeur de Agent-Native
+champ.
+
+Les flux OpenAI, AG-UI, Claude Agent SDK et Vercel AI SDK peuvent utiliser la norme
+assistants de connecteur. ACP reste l'interopérabilité agent de codage/éditeur, pas le
+environnement d'exécution général du chat d'application pour les utilisateurs finaux. A2UI n'est pas déclaré comme pris en charge ici ;
+S'il arrive à maturité, il devrait s'adapter à ce même contrat explicite d'exécution/widget.
+
+## Documents associés {#related-docs}
+
+- [Actions](/docs/actions) : définissez les opérations qui renvoient les données natives du widget.
+- [Agent Surfaces](/docs/agent-surfaces) : décidez si vous avez besoin d'une application sans interface, de chat, side-car ou complète.
+- [Drop-in Agent](/docs/drop-in-agent) — le didacticiel pour monter le runtime de chat standard.
+- [Component API](/docs/components) : la carte API par exportation pour les couches de discussion, les environnements d'exécution et les moteurs de rendu d'outils.
+- [MCP Apps](/docs/mcp-apps) — UI en ligne pour les hôtes MCP externes.
+- [Key Concepts](/docs/key-concepts#protocols) — état et positionnement du protocole.

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

@@ -0,0 +1,231 @@
+---
+title: "Notifications"
+description: "Notifications dans l'application avec canaux enfichables : boîte de réception, webhook ou personnalisé"
+---
+
+# Notifications
+
+Une fonction, plusieurs destinations. Appelez `notify()` à partir de n'importe quel code côté serveur (une action, une automatisation, un plugin) et l'événement atterrit dans la boîte de réception de l'application de l'utilisateur et se diffuse sur chaque chaîne enregistrée. Livré avec un composant UI en forme de cloche et de liste déroulante que le modèle hôte dépose dans son en-tête.
+
+Les notifications sont des alertes unidirectionnelles envoyées dans la boîte de réception de l'application (plus la diffusion du webhook). Pour _converser_ avec votre agent depuis Slack/email/Telegram/WhatsApp, voir [Messaging](/docs/messaging).
+
+```ts
+import { notify } from "@agent-native/core/notifications";
+
+await notify(
+  { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
+  { owner: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One call, many destinations" summary="notify() always writes the owner-scoped inbox row, fans out to every registered channel in parallel (best-effort), then emits notification.sent on the event bus."
+{
+  "html": "<div class=\"diagram-notify\"><div class=\"diagram-node\">notify(input, { owner })<br><small class=\"diagram-muted\">any server code &middot; action, automation, plugin</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel fan\" data-rough><div class=\"fan-row\"><span class=\"diagram-pill accent\">inbox</span><div class=\"diagram-box\" data-rough>notifications table &rarr; bell UI<br><small class=\"diagram-muted\">always on &middot; owner-scoped</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">webhook</span><div class=\"diagram-box\" data-rough>POST JSON to NOTIFICATIONS_WEBHOOK_URL<br><small class=\"diagram-muted\">best-effort</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">custom</span><div class=\"diagram-box\" data-rough>registerNotificationChannel(...)<br><small class=\"diagram-muted\">best-effort &middot; runs in parallel</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">notification.sent</span><small class=\"diagram-muted\">event bus &middot; automations can chain</small></div></div>",
+  "css": ".diagram-notify{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-notify .fan{display:flex;flex-direction:column;gap:10px;padding:14px}.diagram-notify .fan-row{display:flex;align-items:center;gap:10px}.diagram-notify .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-notify .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Gravités {#severities}
+
+| Gravité    | Utiliser pour                                             |
+| ---------- | --------------------------------------------------------- |
+| `info`     | Confirmations, étapes de progression, FYI                 |
+| `warning`  | Quelque chose que l'utilisateur devrait bientôt consulter |
+| `critical` | Besoin d'une attention immédiate                          |
+
+La gravité détermine le style du badge dans la liste déroulante et est transmise aux canaux afin qu'ils puissent effectuer une branche en cas d'urgence.
+
+## Canaux intégrés {#channels}
+
+| Chaîne    | Livraison                                                      | Requiert                                                              |
+| --------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `inbox`   | Persiste dans la table `notifications` ; entraîne la cloche UI | Toujours activé – fait partie de la primitive.                        |
+| `webhook` | POST JSON vers un URL configuré                                | Var d'environnement `NOTIFICATIONS_WEBHOOK_URL` définie au démarrage. |
+
+Le canal webhook résout les références `${keys.NAME}` dans les URL et `NOTIFICATIONS_WEBHOOK_AUTH` par rapport au [secrets](/docs/security) ad hoc du propriétaire, de sorte que la valeur brute n'entre jamais dans le contexte de l'agent. Les listes d'autorisation URL par clé sont appliquées – même règle que celle utilisée par l'outil d'automatisation `web-request`.
+
+```an-diagram title="Channels and severity" summary="inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."
+{
+  "html": "<div class=\"diagram-channels\"><div class=\"diagram-panel col\" data-rough><strong>Channels</strong><div class=\"diagram-box\" data-rough>inbox<br><small class=\"diagram-muted\">always on &mdash; part of the primitive</small></div><div class=\"diagram-box\" data-rough>webhook<br><small class=\"diagram-muted\">needs NOTIFICATIONS_WEBHOOK_URL</small></div><div class=\"diagram-box\" data-rough>custom<br><small class=\"diagram-muted\">registerNotificationChannel()</small></div></div><div class=\"diagram-panel col\" data-rough><strong>Severity drives the badge</strong><div class=\"sev-row\"><span class=\"diagram-pill\">info</span><span class=\"diagram-muted\">confirmations, FYI</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">warning</span><span class=\"diagram-muted\">look at soon</span></div><div class=\"sev-row\"><span class=\"diagram-pill accent\">critical</span><span class=\"diagram-muted\">needs immediate attention</span></div></div></div>",
+  "css": ".diagram-channels{display:flex;gap:16px;flex-wrap:wrap;align-items:flex-start}.diagram-channels .col{display:flex;flex-direction:column;gap:10px;padding:14px;min-width:240px}.diagram-channels .sev-row{display:flex;align-items:center;gap:10px}"
+}
+```
+
+## API {#api}
+
+### `notify(input, meta)` {#notify}
+
+Envoyez une notification. Conserve toujours dans la boîte de réception, sauf exclusion explicite ; des chaînes enregistrées supplémentaires fonctionnent en parallèle, au mieux.
+
+```ts
+await notify(
+  {
+    severity: "critical",
+    title: "Database offline",
+    body: "Primary dropped connections",
+    metadata: { runbookUrl: "https://runbooks/db-offline" },
+    channels: ["inbox", "webhook"], // optional allowlist; omit to run all
+  },
+  { owner: "ops@company.com" },
+);
+```
+
+`meta.owner` est obligatoire : la notification s'étend de manière à ce que seul cet utilisateur la voie dans la cloche.
+
+### `registerNotificationChannel(channel)` {#register}
+
+Enregistrez un canal personnalisé à partir de n'importe quel plugin de serveur.
+
+```ts
+import { registerNotificationChannel } from "@agent-native/core/notifications";
+
+registerNotificationChannel({
+  name: "slack-ops",
+  async deliver(input, meta) {
+    await fetch(process.env.OPS_SLACK_WEBHOOK!, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `*${input.severity.toUpperCase()}* — ${input.title}\n${input.body ?? ""}`,
+        owner: meta.owner,
+      }),
+    });
+  },
+});
+```
+
+Les noms des chaînes sont uniques : le réenregistrement remplace la chaîne précédente. `deliver()` est le meilleur effort ; le lancement enregistre l'erreur mais ne bloque pas les autres canaux ni la ligne de la boîte de réception.
+
+### Liste et lecture {#read}
+
+```ts
+import {
+  listNotifications,
+  countUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  deleteNotification,
+} from "@agent-native/core/notifications";
+
+const rows = await listNotifications("steve@builder.io", {
+  unreadOnly: true,
+  limit: 50,
+});
+const unread = await countUnread("steve@builder.io");
+await markNotificationRead(rows[0].id, "steve@builder.io");
+await markAllNotificationsRead("steve@builder.io");
+await deleteNotification(rows[0].id, "steve@builder.io");
+```
+
+Chaque fonction est limitée au propriétaire : aucune lecture ni écriture entre utilisateurs.
+
+## L'interface NotificationChannel {#channel-interface}
+
+```ts
+interface NotificationChannel {
+  name: string;
+  deliver(
+    input: NotificationInput,
+    meta: NotificationMeta,
+  ): void | Promise<void>;
+}
+
+interface NotificationInput {
+  severity: "info" | "warning" | "critical";
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  channels?: string[];
+}
+
+interface NotificationMeta {
+  owner: string;
+}
+```
+
+## HTTP API {#http}
+
+Monté sur `/_agent-native/notifications/*` par le plugin core-routes. Toutes les routes sont limitées à l'e-mail de la session authentifiée.
+
+| Méthode  | Chemin                                              |
+| -------- | --------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
+| `GET`    | `/_agent-native/notifications/count`                |
+| `POST`   | `/_agent-native/notifications/:id/read`             |
+| `POST`   | `/_agent-native/notifications/read-all`             |
+| `DELETE` | `/_agent-native/notifications/:id`                  |
+
+```an-api title="List notifications" summary="The route behind listNotifications() — scoped to the authenticated session's email."
+{
+  "method": "GET",
+  "path": "/_agent-native/notifications?unread=true&limit=50",
+  "summary": "List recent notifications for the current user",
+  "auth": "Authenticated session; results are scoped to the session's email.",
+  "params": [
+    { "name": "unread", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only unread notifications." },
+    { "name": "limit", "in": "query", "type": "number", "required": false, "description": "Max rows to return." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Owner-scoped notification rows, newest first." }
+  ]
+}
+```
+
+## Composant UI {#ui}
+
+```tsx
+import { NotificationsBell } from "@agent-native/core/client/notifications";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <NotificationsBell browserNotifications />
+    </header>
+  );
+}
+```
+
+Icône en forme de cloche avec badge non lu. En cliquant, vous ouvrez une liste déroulante des notifications récentes. Utilise des jetons sémantiques shadcn, s'adapte au thème clair/sombre du modèle hôte.
+
+Transmettez `browserNotifications` pour déclencher également les fenêtres contextuelles `new Notification(...)` du système pour chaque nouvel élément non lu – utile lorsque l'onglet de l'utilisateur est en arrière-plan. La liste déroulante affiche une invite « Activer » jusqu'à ce que l'utilisateur accorde l'autorisation ; les doublons sont évités par identifiant via le champ Notification `tag`.
+
+## Outils d'agent {#agent-tools}
+
+Un seul outil `manage-notifications` est enregistré dans chaque modèle. Le paramètre `action` sélectionne l'opération :
+
+| Actions | Paramètres                                                                          | Objectif                                                                                      |
+| ------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `send`  | `severity` (obligatoire), `title` (obligatoire), `body`, `metadataJson`, `channels` | Envoyer une notification à la boîte de réception de l'utilisateur et aux chaînes enregistrées |
+| `list`  | `unreadOnly`, `limit` (max 200, 20 par défaut)                                      | Répertorier les notifications récentes pour le contexte                                       |
+
+Les automatisations (voir [Automations](/docs/automations)) peuvent appeler `manage-notifications` avec `action=send` dans leur corps — il s'agit du modèle canonique pour transformer un événement externe en une alerte visible par l'utilisateur.
+
+## Bus d'événements {#event-bus}
+
+Chaque livraison réussie émet `notification.sent` sur le [event bus](/docs/automations#event-bus) :
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+Les automatisations peuvent enchaîner cela – par ex. _"si une notification critique se déclenche, avertissez également."_
+
+## Comment ça marche {#internals}
+
+- **Portée du propriétaire** — chaque ligne a une colonne `owner` ; chaque requête est filtrée dessus ; chaque itinéraire utilise l'e-mail de la session authentifiée. Les utilisateurs ne voient jamais les notifications des autres.
+- **Intégration de sondage** — chaque mutation appelle `recordChange()` afin que les modèles utilisant [`useDbSync`](/docs/client) s'invalident automatiquement sans aucun câblage supplémentaire.
+- **Distribution au mieux** : les erreurs de canal sont détectées et enregistrées ; un canal défaillant ne bloque pas les autres ni l'écriture dans la boîte de réception.
+- **Fire-and-forget** — `notify()` revient une fois l'écriture de la boîte de réception terminée ; les canaux personnalisés s'exécutent en arrière-plan.
+
+## Quelle est la prochaine étape
+
+- [**Automations**](/docs/automations) — l'appelant le plus courant de `notify()`
+- [**Security**](/docs/security) — la substitution `${keys.NAME}` qui alimente le canal webhook
+- [**Server plugins**](/docs/server) — où les canaux personnalisés sont enregistrés au démarrage