@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/pt-BR/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "Bate-papo nativo UI"
+description: "Renderizadores de bate-papo nativos declarados por ação, saídas DataTable/DataChart reutilizáveis e como os tempos de execução do agente BYO devem se conectar ao bate-papo Agent-Native."
+---
+
+# Bate-papo nativo UI
+
+O bate-papo nativo UI é o caminho de renderização no aplicativo para a saída do agente primário. Um
+a ação retorna JSON estruturado, o tempo de execução do chat reconhece um widget explícito
+discriminante e `<AssistantChat>` renderiza um componente React real no
+conversa. Você não cria um iframe ou um artefato HTML único para o
+bate-papo normal do aplicativo.
+
+Use o chat nativo UI quando o usuário precisar inspecionar a saída onde o agente está
+já falando: resultados de consultas, insights de respostas, resumos de configuração,
+controles de aprovação/negação ou links para visualizações de aplicativos. Usar [MCP Apps](/docs/mcp-apps)
+quando um host externo como Claude, ChatGPT, Copilot ou Cursor deve ser renderizado
+uma rota in-line do seu aplicativo.
+
+```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 declarados por ação {#action-declared-widgets}
+
+O caminho nativo tem duas partes explícitas:
+
+- `outputSchema` valida o formato de resposta da ação.
+- `chatUI.renderer` seleciona o renderizador nativo React para o resultado validado.
+
+Os renderizadores de dados integrados usam um resultado JSON simples com `widget` mais o
+carga útil correspondente:
+
+| Widget            | Carga necessária           | Renderiza como                                              |
+| ----------------- | -------------------------- | ----------------------------------------------------------- |
+| `"data-table"`    | `table`                    | Uma tabela de dados nativa e reutilizável                   |
+| `"data-chart"`    | `chartSeries`              | Um gráfico nativo de barras, linhas ou áreas                |
+| `"data-insights"` | `table` e/ou `chartSeries` | Um cartão de insights combinado com saída de gráfico/tabela |
+
+O servidor actions deve importar os auxiliares e esquemas seguros para o servidor de
+`@agent-native/core/data-widgets`; o código do cliente pode importar os mesmos tipos de
+`@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."
+}
+```
+
+Quando um usuário solicita um gráfico, gráfico, tabela, tendência ou relatório compacto, os agentes de aplicativos
+deve preferir uma ação que declare um desses renderizadores nativos. A final
+o texto do assistente deve ser breve e permitir que o widget carregue os dados; não copie
+as mesmas linhas em uma tabela de descontos, a menos que o usuário solicite explicitamente um texto
+exportar.
+
+Quando não existe nenhuma ação de domínio, mas o agente já recuperou o compacto,
+dados verdadeiros, ele pode chamar a ação da estrutura `render-data-widget` com o
+mesma forma `data-table`, `data-chart` ou `data-insights` JSON. Somente esta ação
+valida e renderiza o widget; não é uma fonte de dados e não deve ser usado
+para inventar métricas de espaço reservado.
+
+## Saída DataTable {#data-table}
+
+`table` é intencionalmente simples, então listar, SQL, análises e configurar actions podem
+reutilize:
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+Prefira chaves de coluna estáveis ​​e valores de linha seguros para JSON. Use `totalRows`,
+`sampledRows` e `truncated` quando a ação mostra uma fatia maior
+conjunto de resultados.
+
+## Saída do DataChart {#data-chart}
+
+`chartSeries` oferece suporte aos formatos de gráfico comuns usados nas respostas dos agentes sem
+exigindo que cada modelo envie seu próprio 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;
+}
+```
+
+Mantenha os dados do gráfico compactos. Para grandes conjuntos de dados, agregue na ação e vincule
+para a visualização completa do aplicativo com metadados `display.primaryAction` ou ação `link`.
+
+## Widgets nativos versus aplicativos MCP {#native-vs-mcp-apps}
+
+Widgets de bate-papo nativos e aplicativos MCP são complementares:
+
+- **Widgets nativos** são para o tempo de execução de bate-papo do próprio aplicativo. O resultado da ação é
+  JSON, e a estrutura renderiza o widget React integrado.
+- **Aplicativos MCP** são para hosts externos. A ação declara `mcpApp` e normalmente
+  `link`, e o host renderiza uma rota de aplicativo real in-line quando compatível.
+- **Deep links** continuam sendo o substituto universal. Use a ação `link` ou
+  `display.primaryAction` para clientes CLI, hosts MCP mais antigos e transcrição simples
+  os leitores podem abrir a visualização completa do aplicativo.
+
+Quando uma carga útil de widget nativo e metadados de aplicativos MCP estão presentes, o arquivo no aplicativo
+o chat prefere o widget nativo. Hosts externos usam o recurso MCP Apps ou o
+substituto de link direto.
+
+## Renderizadores nativos personalizados {#custom-native-renderers}
+
+Registre componentes específicos do produto pelo ID exato do renderizador e, em seguida, declare esse ID
+na ação:
+
+```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 }),
+});
+```
+
+Use isso para o aplicativo original UI. Mantenha o iframe entre hosts UI em `mcpApp` e mantenha
+execução de consulta arbitrária por trás da leitura digitada actions em vez de SQL bruto no bate-papo.
+
+## Tempos de execução do agente BYO {#byo-agent-runtimes}
+
+`AgentChatRuntime` é o contrato traga seu próprio agente para o shell de bate-papo e
+esta seção é sua referência canônica. Ele permite que um agente que você criou em outro lugar
+transmitir eventos normalizados para a conversa Agent-Native de UI enquanto mantém o
+compositor compartilhado, renderização de transcrição, cartões de ferramentas, aprovações, widgets nativos,
+e layout do aplicativo ao redor. O [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+pontos do tutorial aqui para a história do tempo de execução e [Component API](/docs/components#agent-chat-ui)
+lista cada conector e adaptador com seu caminho de importação; o contrato em si é
+descrito abaixo.
+
+```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 os conectores são exportados de `@agent-native/core/client/chat` (e da raiz
+entrada `@agent-native/core/client`). Use o tempo de execução genérico HTTP quando seu agente
+pode expor um endpoint POST que retorna eventos de tempo de execução 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" />;
+}
+```
+
+Se o seu endpoint já transmite um protocolo de agente comum, use o protocolo correspondente
+conector e pule a gravação de um mapeador 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",
+});
+```
+
+O endpoint pode transmitir diretamente o formato do evento normalizado:
+
+```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 muito simples, uma resposta JSON `{ "text": "..." }` é aceita e
+convertido em uma única mensagem do assistente. Para agentes mais ricos, transmita
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+Eventos `usage`, `error` e `done`. Os resultados da ferramenta podem conter `mcpApp` ou
+Metadados `chatUI`, portanto, widgets nativos declarados por ação ainda são renderizados sem
+iframes.
+
+Quando desejar o transporte Agent-Native integrado como um objeto de tempo de execução, use:
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+Use `<AssistantChat createAdapter={...} />` somente quando precisar de full
+controle do adaptador assistant-ui. Use `PromptComposer` sozinho quando seu produto
+possui toda a transcrição externa e só quer o compositor de Agent-Native
+campo.
+
+Os fluxos OpenAI, AG-UI, Claude Agent SDK e Vercel AI SDK podem usar o padrão
+ajudantes de conector. ACP permanece interoperabilidade agente de codificação/editor, não o
+tempo de execução geral do app-chat para usuários finais. A2UI não é reivindicado como suportado aqui;
+se amadurecer, deverá se adaptar ao mesmo contrato explícito de tempo de execução/widget.
+
+## Documentos relacionados {#related-docs}
+
+- [Actions](/docs/actions) — defina as operações que retornam dados nativos do widget.
+- [Agent Surfaces](/docs/agent-surfaces): decida se você precisa de um aplicativo headless, chat, sidecar ou completo.
+- [Drop-in Agent](/docs/drop-in-agent) — o tutorial para montar o tempo de execução de chat padrão.
+- [Component API](/docs/components) — o mapa API por exportação para camadas de bate-papo, tempos de execução e renderizadores de ferramentas.
+- [MCP Apps](/docs/mcp-apps) — UI embutido para hosts MCP externos.
+- [Key Concepts](/docs/key-concepts#protocols) — status e posicionamento do protocolo.

package/corpus/core/docs/content/locales/pt-BR/notifications.md

@@ -0,0 +1,231 @@
+---
+title: "Notificações"
+description: "Notificações no aplicativo com canais conectáveis — caixa de entrada, webhook ou personalizado"
+---
+
+# Notificações
+
+Uma função, muitos destinos. Chame `notify()` a partir de qualquer código do lado do servidor – uma ação, uma automação, um plugin – e o evento chega à caixa de entrada do aplicativo do usuário e se espalha para todos os canais registrados. Vem com um componente UI suspenso que o modelo de host coloca em seu cabeçalho.
+
+As notificações são alertas unidirecionais na caixa de entrada do sino do aplicativo (além da distribuição de webhook). Para _conversar_ com seu agente por Slack/email/Telegram/WhatsApp, consulte [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}"
+}
+```
+
+## Gravidades {#severities}
+
+| Gravidade  | Usar para                              |
+| ---------- | -------------------------------------- |
+| `info`     | Confirmações, marcos de progresso, FYI |
+| `warning`  | Algo que o usuário deve ver em breve   |
+| `critical` | Requer atenção imediata                |
+
+A gravidade orienta o estilo do selo no menu suspenso e é transmitida aos canais para que eles possam diversificar com urgência.
+
+## Canais integrados {#channels}
+
+| Canal     | Entrega                                                 | Requer                                                         |
+| --------- | ------------------------------------------------------- | -------------------------------------------------------------- |
+| `inbox`   | Persiste na tabela `notifications`; toca a campainha UI | Sempre ligado — parte do primitivo.                            |
+| `webhook` | POST JSON para um URL configurado                       | `NOTIFICATIONS_WEBHOOK_URL` env var definida na inicialização. |
+
+O canal webhook resolve referências `${keys.NAME}` em URL e `NOTIFICATIONS_WEBHOOK_AUTH` em relação ao [secrets](/docs/security) ad-hoc do proprietário, de forma que o valor bruto nunca entre no contexto do agente. As listas de permissões URL por chave são aplicadas – a mesma regra que a ferramenta de automações `web-request` usa.
+
+```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}
+
+Entregue uma notificação. Sempre persiste na caixa de entrada, a menos que seja explicitamente excluído; canais registrados adicionais são executados em paralelo, melhor esforço.
+
+```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` é obrigatório — define o escopo da notificação para que apenas o usuário a veja no sino.
+
+### `registerNotificationChannel(channel)` {#register}
+
+Registre um canal personalizado de qualquer plugin de 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,
+      }),
+    });
+  },
+});
+```
+
+Os nomes dos canais são exclusivos – o novo registro substitui o canal anterior. `deliver()` é o melhor esforço; lançar registra o erro, mas não bloqueia outros canais ou a linha da caixa de entrada.
+
+### Listagem e leitura {#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 função tem escopo de proprietário — sem leituras entre usuários, sem gravações entre usuários.
+
+## A interface do 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}
+
+Montado em `/_agent-native/notifications/*` pelo plugin core-routes. Todas as rotas têm como escopo o e-mail da sessão autenticada.
+
+| Método   | Caminho                                             |
+| -------- | --------------------------------------------------- |
+| `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>
+  );
+}
+```
+
+Ícone de sino com selo de não lido. Clicar abre uma lista suspensa de notificações recentes. Usa tokens semânticos shadcn e se adapta ao tema claro/escuro do modelo de host.
+
+Passe `browserNotifications` para também disparar pop-ups do sistema `new Notification(...)` para cada novo item não lido - útil quando a guia do usuário está em segundo plano. A lista suspensa exibe um prompt "Ativar" até que o usuário conceda permissão; duplicatas são evitadas por ID por meio do campo Notificação `tag`.
+
+## Ferramentas do agente {#agent-tools}
+
+Uma única ferramenta `manage-notifications` é registrada em cada modelo. O parâmetro `action` seleciona a operação:
+
+| Ação   | Parâmetros                                                                          | Propósito                                                                      |
+| ------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `send` | `severity` (obrigatório), `title` (obrigatório), `body`, `metadataJson`, `channels` | Enviar uma notificação para a caixa de entrada do usuário e canais cadastrados |
+| `list` | `unreadOnly`, `limit` (máx. 200, padrão 20)                                         | Listar notificações recentes por contexto                                      |
+
+Automações (veja [Automations](/docs/automations)) podem chamar `manage-notifications` com `action=send` em seu corpo — este é o padrão canônico para transformar um evento externo em um alerta visível ao usuário.
+
+## Barramento de eventos {#event-bus}
+
+Cada entrega bem-sucedida emite `notification.sent` no [event bus](/docs/automations#event-bus):
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+As automações podem encadear isso - por exemplo. _"se uma notificação crítica for disparada, chame também de plantão."_
+
+## Como funciona {#internals}
+
+- **Escopo do proprietário** — cada linha tem uma coluna `owner`; cada consulta é filtrada; cada rota usa o email da sessão autenticada. Os usuários nunca veem as notificações uns dos outros.
+- **Integração de pesquisa** — cada mutação chama `recordChange()` para que os modelos que usam [`useDbSync`](/docs/client) sejam invalidados automaticamente sem qualquer conexão extra.
+- **Distribuição de melhor esforço** — erros de canal são detectados e registrados; um canal com falha não bloqueia outros ou a gravação da caixa de entrada.
+- **Disparar e esquecer** — `notify()` retorna após a conclusão da gravação da caixa de entrada; canais personalizados são executados em segundo plano.
+
+## O que vem a seguir
+
+- [**Automations**](/docs/automations) — o chamador mais comum de `notify()`
+- [**Security**](/docs/security) — a substituição `${keys.NAME}` que alimenta o canal webhook
+- [**Server plugins**](/docs/server) — onde os canais personalizados são registrados na inicialização