@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "Chat nativo UI"
+description: "Representadores de chat nativos declarados por acción, salidas reutilizables de DataTable/DataChart y cómo los tiempos de ejecución del agente BYO deben conectarse al chat Agent-Native."
+---
+
+# Chat nativo UI
+
+El chat nativo UI es la ruta de procesamiento en la aplicación para la salida del agente propio. Un
+La acción devuelve JSON estructurado, el tiempo de ejecución del chat reconoce un widget explícito
+discriminante, y `<AssistantChat>` representa un componente React real en el
+conversación. No creas un iframe o un artefacto HTML único para el
+chat normal de la aplicación.
+
+Utilice el chat nativo UI cuando el usuario deba inspeccionar la salida donde está el agente
+ya estamos hablando: resultados de consultas, información sobre respuestas, resúmenes de configuración,
+controles de aprobación/denegación o enlaces a vistas de aplicaciones. Utilice [MCP Apps](/docs/mcp-apps)
+cuándo debe renderizar un host externo como Claude, ChatGPT, Copilot o Cursor
+una ruta en línea desde tu aplicación.
+
+```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 de acción declarada {#action-declared-widgets}
+
+La ruta nativa tiene dos partes explícitas:
+
+- `outputSchema` valida la forma de respuesta de la acción.
+- `chatUI.renderer` selecciona el renderizador nativo React para el resultado validado.
+
+Los renderizadores de datos integrados utilizan un resultado simple JSON con `widget` más
+carga útil coincidente:
+
+| Aparato           | Carga útil requerida      | Representa como                                                      |
+| ----------------- | ------------------------- | -------------------------------------------------------------------- |
+| `"data-table"`    | `table`                   | Una tabla de datos nativa y reutilizable                             |
+| `"data-chart"`    | `chartSeries`             | Un gráfico nativo de barras, líneas o áreas                          |
+| `"data-insights"` | `table` y/o `chartSeries` | Una tarjeta de información combinada con resultados de gráfico/tabla |
+
+El servidor actions debe importar los esquemas y ayudantes seguros para el servidor
+`@agent-native/core/data-widgets`; El código del cliente puede importar los mismos tipos desde
+`@agent-native/core/client/chat` o `@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."
+}
+```
+
+Cuando un usuario solicita un cuadro, gráfico, tabla, tendencia o informe compacto, los agentes de la aplicación
+debería preferir una acción que declare uno de estos renderizadores nativos. La final
+el texto del asistente debe ser breve y permitir que el widget lleve los datos; no copiar
+las mismas filas en una tabla de rebajas a menos que el usuario solicite explícitamente un texto
+exportar.
+
+Cuando no existe ninguna acción de dominio pero el agente ya ha recuperado el compacto,
+datos veraces, puede llamar a la acción framework `render-data-widget` con el
+misma forma `data-table`, `data-chart` o `data-insights` JSON. Sólo esta acción
+valida y representa el widget; no es una fuente de datos y no debe utilizarse
+para inventar métricas de marcador de posición.
+
+## Salida de tabla de datos {#data-table}
+
+`table` es intencionalmente simple, por lo que la lista, SQL, el análisis y la configuración de actions pueden hacerlo
+reutilizarlo:
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+Prefiere claves de columna estables y valores de fila seguros para JSON. Utilice `totalRows`,
+`sampledRows` y `truncated` cuando la acción muestra una porción de un tamaño más grande
+conjunto de resultados.
+
+## Salida del gráfico de datos {#data-chart}
+
+`chartSeries` admite las formas de gráficos comunes utilizadas en las respuestas de los agentes sin
+requerir que cada plantilla envíe su propio renderizador 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;
+}
+```
+
+Mantenga los datos del gráfico compactos. Para conjuntos de datos grandes, agregue en la acción y vincule
+a la vista completa de la aplicación con metadatos `display.primaryAction` o acción `link`.
+
+## Widgets nativos frente a aplicaciones MCP {#native-vs-mcp-apps}
+
+Los widgets de chat nativos y las aplicaciones MCP son complementarios:
+
+- **Los widgets nativos** son para el tiempo de ejecución del chat propio de la aplicación. El resultado de la acción es
+  JSON y el marco representa el widget React integrado.
+- **Las aplicaciones MCP** son para hosts externos. La acción declara `mcpApp` y normalmente
+  `link` y el host genera una ruta de aplicación real en línea cuando es compatible.
+- Los **enlaces profundos** siguen siendo la alternativa universal. Utilice la acción `link` o
+  `display.primaryAction` entonces clientes CLI, hosts MCP más antiguos y transcripción simple
+  los lectores pueden abrir la vista completa de la aplicación.
+
+Cuando están presentes una carga útil de widget nativo y metadatos de aplicaciones MCP, la aplicación
+el chat prefiere el widget nativo. Los hosts externos utilizan el recurso de aplicaciones MCP o el
+respaldo de enlaces profundos.
+
+## Representadores nativos personalizados {#custom-native-renderers}
+
+Registrar componentes específicos del producto por ID de renderizador exacto y luego declarar ese ID
+sobre la acción:
+
+```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 }),
+});
+```
+
+Utilice esto para la aplicación propia UI. Mantenga el iframe entre hosts UI en `mcpApp` y mantenga
+ejecución de consultas arbitrarias detrás de la lectura escrita actions en lugar de SQL sin formato en el chat.
+
+## Tiempos de ejecución del agente BYO {#byo-agent-runtimes}
+
+`AgentChatRuntime` es el contrato de traiga su propio agente para el shell de chat, y
+esta sección es su referencia canónica. Permite que un agente que haya creado en otro lugar
+transmita eventos normalizados a la conversación UI de Agent-Native manteniendo el
+compositor compartido, renderizado de transcripciones, tarjetas de herramientas, aprobaciones, widgets nativos,
+y el diseño de la aplicación circundante. El [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+puntos tutoriales aquí para la historia en tiempo de ejecución y [Component API](/docs/components#agent-chat-ui)
+enumera cada conector y adaptador con su ruta de importación; el contrato en sí es
+se describe a continuación.
+
+```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}"
+}
+```
+
+Todos los conectores se exportan desde `@agent-native/core/client/chat` (y la raíz
+entrada `@agent-native/core/client`). Utilice el tiempo de ejecución genérico HTTP cuando su agente
+puede exponer un punto final POST que devuelve eventos de tiempo de ejecución SSE o 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 su terminal ya transmite un protocolo de agente común, utilice el correspondiente
+conector y omita escribir un asignador personalizado:
+
+```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",
+});
+```
+
+El punto final puede transmitir la forma del evento normalizado directamente:
+
+```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"}
+```
+
+Para agentes muy simples, se acepta una respuesta JSON `{ "text": "..." }` y
+convertido en un único mensaje de asistente. Para agentes más ricos, transmita
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+Eventos `usage`, `error` y `done`. Los resultados de la herramienta pueden llevar `mcpApp` o
+Metadatos `chatUI`, por lo que los widgets nativos con acción declarada aún se muestran sin
+iframes.
+
+Cuando desee el transporte Agent-Native integrado como objeto de tiempo de ejecución, utilice:
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+Utiliza `<AssistantChat createAdapter={...} />` solo cuando lo necesites completo
+control del adaptador de interfaz de usuario del asistente. Utilice `PromptComposer` solo cuando su producto
+posee toda la transcripción externa y solo quiere el compositor de Agent-Native
+campo.
+
+Las transmisiones OpenAI, AG-UI, Claude Agent SDK y Vercel AI SDK pueden usar el estándar
+ayudantes de conector. ACP sigue siendo la interoperabilidad entre agente de codificación y editor, no la
+Tiempo de ejecución general de chat de aplicaciones para usuarios finales. Aquí no se afirma que A2UI sea compatible;
+Si madura, debería adaptarse a este mismo contrato explícito de tiempo de ejecución/widget.
+
+## Documentos relacionados {#related-docs}
+
+- [Actions](/docs/actions): define las operaciones que devuelven datos del widget nativo.
+- [Agent Surfaces](/docs/agent-surfaces): decide si necesitas una aplicación headless, chat, sidecar o completa.
+- [Drop-in Agent](/docs/drop-in-agent): el tutorial para montar el tiempo de ejecución de chat estándar.
+- [Component API](/docs/components): el mapa API por exportación para capas de chat, tiempos de ejecución y renderizadores de herramientas.
+- [MCP Apps](/docs/mcp-apps): UI en línea para hosts MCP externos.
+- [Key Concepts](/docs/key-concepts#protocols): estado y posicionamiento del protocolo.

package/docs/content/locales/es-ES/notifications.md

@@ -0,0 +1,231 @@
+---
+title: "Notificaciones"
+description: "Notificaciones en la aplicación con canales conectables: bandeja de entrada, webhook o personalizado"
+---
+
+# Notificaciones
+
+Una función, muchos destinos. Llame a `notify()` desde cualquier código del lado del servidor (una acción, una automatización, un complemento) y el evento llega a la bandeja de entrada de la aplicación del usuario y se distribuye en todos los canales registrados. Se envía con un componente UI con campana y menú desplegable que la plantilla de host coloca en su encabezado.
+
+Las notificaciones son alertas unidireccionales que se envían a la bandeja de entrada de la aplicación (más distribución del webhook). Para _conversar_ con tu agente desde Slack/email/Telegram/WhatsApp, consulta [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}"
+}
+```
+
+## Severidades {#severities}
+
+| Severidad  | Usar para                                |
+| ---------- | ---------------------------------------- |
+| `info`     | Confirmaciones, hitos de progreso, FYI   |
+| `warning`  | Algo que el usuario debería mirar pronto |
+| `critical` | Necesita atención inmediata              |
+
+La gravedad determina el estilo de la insignia en el menú desplegable y se transmite a los canales para que puedan bifurcarse según la urgencia.
+
+## Canales integrados {#channels}
+
+| Canal     | Entrega                                                     | Requiere                                                       |
+| --------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
+| `inbox`   | Persiste en la tabla `notifications`; acciona la campana UI | Siempre activo: parte de la primitiva.                         |
+| `webhook` | POST JSON a un URL configurado                              | Var entorno `NOTIFICATIONS_WEBHOOK_URL` configurada al inicio. |
+
+El canal de webhook resuelve las referencias de `${keys.NAME}` tanto en URL como en `NOTIFICATIONS_WEBHOOK_AUTH` contra el [secrets](/docs/security) ad-hoc del propietario, por lo que el valor sin procesar nunca ingresa al contexto del agente. Se aplican listas de permitidos URL por clave: la misma regla que utiliza la herramienta de automatizaciones `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}
+
+Entregar una notificación. Siempre persiste en la bandeja de entrada a menos que se excluya explícitamente; Los canales registrados adicionales se ejecutan en paralelo, con el mejor esfuerzo.
+
+```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" },
+);
+```
+
+Se requiere `meta.owner`: limita la notificación para que solo el usuario la vea en la campana.
+
+### `registerNotificationChannel(channel)` {#register}
+
+Registra un canal personalizado desde cualquier complemento del servidor.
+
+```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,
+      }),
+    });
+  },
+});
+```
+
+Los nombres de los canales son únicos: volver a registrarse reemplaza el canal anterior. `deliver()` es el mejor esfuerzo; lanzar registra el error pero no bloquea otros canales ni la fila de la bandeja de entrada.
+
+### Listado y lectura {#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");
+```
+
+Cada función tiene un alcance de propietario: no hay lecturas ni escrituras entre usuarios.
+
+## La interfaz del canal de notificaciones {#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}
+
+Montado en `/_agent-native/notifications/*` por el complemento core-routes. Todas las rutas tienen como alcance el correo electrónico de la sesión autenticada.
+
+| Método   | Ruta                                                |
+| -------- | --------------------------------------------------- |
+| `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." }
+  ]
+}
+```
+
+## Componente 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>
+  );
+}
+```
+
+Icono de campana con distintivo no leído. Al hacer clic, se abre un menú desplegable de notificaciones recientes. Utiliza tokens semánticos shadcn y se adapta al tema claro/oscuro de la plantilla del host.
+
+Pase `browserNotifications` para activar también las ventanas emergentes `new Notification(...)` del sistema por cada elemento nuevo no leído, lo que resulta útil cuando la pestaña del usuario está en segundo plano. El menú desplegable muestra un mensaje "Habilitar" hasta que el usuario otorga permiso; Se evitan duplicados por ID a través del campo Notificación `tag`.
+
+## Herramientas del agente {#agent-tools}
+
+En cada plantilla se registra una única herramienta `manage-notifications`. El parámetro `action` selecciona la operación:
+
+| Acción | Parámetros                                                                          | Propósito                                                                               |
+| ------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `send` | `severity` (obligatorio), `title` (obligatorio), `body`, `metadataJson`, `channels` | Enviar una notificación a la bandeja de entrada del usuario y a los canales registrados |
+| `list` | `unreadOnly`, `limit` (máximo 200, predeterminado 20)                               | Enumerar notificaciones recientes para contextualizar                                   |
+
+Las automatizaciones (ver [Automations](/docs/automations)) pueden llamar a `manage-notifications` con `action=send` en su cuerpo; este es el patrón canónico para convertir un evento externo en una alerta visible para el usuario.
+
+## Autobús de eventos {#event-bus}
+
+Cada entrega exitosa emite `notification.sent` en el [event bus](/docs/automations#event-bus):
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+Las automatizaciones pueden encadenar esto, p. _"si se activa una notificación crítica, también llame a la persona de guardia."_
+
+## Cómo funciona {#internals}
+
+- **Alcance del propietario**: cada fila tiene una columna `owner`; cada consulta se filtra por él; cada ruta utiliza el correo electrónico de la sesión autenticada. Los usuarios nunca ven las notificaciones de los demás.
+- **Integración de encuesta**: cada mutación llama a `recordChange()`, por lo que las plantillas que utilizan [`useDbSync`](/docs/client) se invalidan automáticamente sin ningún cableado adicional.
+- **Distribución con el mejor esfuerzo**: los errores de canal se detectan y registran; un canal que falla no bloquea otros ni la escritura en la bandeja de entrada.
+- **Disparar y olvidar**: `notify()` regresa después de que se completa la escritura en la bandeja de entrada; Los canales personalizados se ejecutan en segundo plano.
+
+## ¿Qué sigue?
+
+- [**Automations**](/docs/automations): la persona que llama más comúnmente a `notify()`
+- [**Security**](/docs/security): la sustitución de `${keys.NAME}` que impulsa el canal webhook
+- [**Server plugins**](/docs/server): donde se registran los canales personalizados al inicio