@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,171 @@
+---
+title: "Equipes de agentes"
+description: "Os agentes delegados principais trabalham para subagentes que executam seus próprios threads e aparecem como chips de visualização ao vivo in-line no chat."
+---
+
+# Equipes de agentes
+
+O chat do agente é um **orquestrador**, não um monólito. Quando o agente principal realiza uma tarefa que pertence melhor a um especialista — “escrever este e-mail com minha voz”, “executar uma análise do BigQuery”, “revisar este PR” — ele gera um subagente em seu próprio thread, ferramentas e contexto. O subagente aparece como um **chip** de visualização ao vivo embutido no chat principal; clique nele para abrir a conversa completa como uma guia.
+
+Isso mantém o thread principal focado, permite que os subagentes sejam executados em paralelo e fornece uma trilha de auditoria limpa para qualquer trabalho delegado.
+
+O Agent Teams é executado no run-manager principal: os eventos são transmitidos e persistidos, os abortos são propagados por meio do SQL e as tarefas sobrevivem às inicializações a frio sem servidor.
+
+## O modelo mental {#mental-model}
+
+- **Chat principal** — o orquestrador. Lê o seu pedido, delegados. Raramente realiza trabalho pesado.
+- **Subagentes** — executam com seu próprio thread, seu próprio prompt de sistema, seu próprio conjunto de ferramentas. Cada um mapeia para um perfil de "agente personalizado" no [workspace](/docs/workspace).
+- **Chips** — o cartão de visualização avançado que aparece embutido no chat principal, mostrando a etapa atual do subagente, a saída do streaming e o resumo final. Recolhido por padrão; expande para a conversa completa ao clicar.
+- **Mensagens bidirecionais** — o agente principal pode enviar acompanhamentos para um subagente em execução; um subagente pode responder quando chegar a um ponto ambíguo.
+
+O estado do subagente é persistido na tabela `application_state` SQL (em `agent-task:<taskId>`), para que as tarefas sobrevivam a inicializações a frio sem servidor e funcionem em vários processos.
+
+```an-diagram title="Orchestrator and specialists" summary="The main chat delegates to sub-agents that run in their own threads and report back as inline chips."
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">Main chat</span><small class=\"diagram-muted\">orchestrator &mdash; reads your request, delegates</small></div><div class=\"at-fan\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"at-subs\"><div class=\"diagram-box\">Code review<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery analysis<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">Email in voice<br><small class=\"diagram-muted\">own context</small></div></div></div><div class=\"diagram-pill\">each appears inline as a live chip &#8635;</div></div>",
+  "css": ".at-orc{display:flex;flex-direction:column;align-items:center;gap:12px}.at-orc .diagram-card{padding:14px 18px;display:flex;flex-direction:column;gap:4px;align-items:center}.at-orc .at-fan{display:flex;flex-direction:column;align-items:center;gap:8px}.at-orc .diagram-arrow{font-size:22px}.at-orc .at-subs{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.at-orc .diagram-box{text-align:center}"
+}
+```
+
+## Quando gerar um subagente {#when-to-spawn}
+
+Aparece quando a tarefa:
+
+- É necessário um **prompt de sistema** diferente (uma voz ou tom especializado, por exemplo, "revisão de código").
+- Tem uma cadeia de ferramentas de **longa execução** que poluiria o contexto principal.
+- Pode ser executado **em paralelo** com outro trabalho que o agente principal esteja realizando.
+- Pertence a uma **equipe diferente** que já tem um perfil de agente personalizado.
+
+Não crie trabalhos triviais de uma única ação — chame a ação diretamente.
+
+## Invocando um subagente {#invoking}
+
+Três maneiras de iniciar um subagente, da menos à mais explícita:
+
+### 1. `@mention` um agente personalizado {#mention}
+
+O usuário digita `@agent-name` no compositor do chat. Uma lista suspensa de subagentes do espaço de trabalho é exibida. Selecionar um insere um chip; ao enviar, o agente principal delega a mensagem a esse subagente.
+
+Os agentes personalizados residem no espaço de trabalho em `agents/<slug>.md` — um arquivo Markdown com frontmatter YAML. Consulte [Custom Agents](/docs/workspace#custom-agents) para obter o formato.
+
+### 2. O agente principal delega automaticamente {#auto-delegate}
+
+A estrutura fornece ao agente principal uma ferramenta `agent-teams`. Quando o modelo decide que uma tarefa se ajusta a um perfil de subagente registrado, ele chama a ferramenta com `action: "spawn"` e um parâmetro `agent` opcional nomeando um perfil de `agents/*.md`. Um chip aparece; o subagente é executado. O agente principal espera (ou segue em paralelo) e incorpora o resultado quando o subagente termina.
+
+O conjunto completo de ações `agent-teams` é:
+
+| Ação          | Propósito                                         |
+| ------------- | ------------------------------------------------- |
+| `spawn`       | Iniciar uma nova tarefa de subagente              |
+| `status`      | Verificar o progresso de um subagente em execução |
+| `read-result` | Obtenha a saída final de um subagente             |
+| `send`        | Enviar mensagem para um subagente em execução     |
+| `list`        | Ver todas as tarefas do usuário atual             |
+
+### 3. Geração programática {#programmatic-spawn}
+
+Para integrações em nível de estrutura, use `spawnTask()` de `@agent-native/core/server`:
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from memory/MEMORY.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
+  parentSend: emit, // streaming sender for the parent chat response
+});
+```
+
+A maior parte do código do aplicativo não chama isso diretamente — a estrutura faz isso nos bastidores para `@mentions` e para a ferramenta `agent-teams`. Alcance `spawnTask()` somente quando estiver conectando um novo ponto de entrada (por exemplo, um botão que inicia um trabalho em segundo plano executado como um subagente).
+
+## Ciclo de vida da tarefa {#lifecycle}
+
+```an-diagram title="What spawnTask() does" summary="Each spawn creates a thread, persists state to SQL, and streams chip events through to completion."
+{
+  "html": "<div class=\"at-life\"><div class=\"diagram-box\"><code>spawnTask()</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">create thread</span><small class=\"diagram-muted\">new row in <code>chat_threads</code>, description as first message</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">persist state</span><small class=\"diagram-muted\"><code>agent-task:&lt;id&gt;</code> &rarr; <code>application_state</code>, status=running</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">stream</span><small class=\"diagram-muted\"><code>agent_task_started</code> &rarr; chip appears; <code>agent_task_step</code> &rarr; chip updates live</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">complete</span><small class=\"diagram-muted\">status=completed, write summary + preview, emit <code>agent_task_done</code></small></div></div>",
+  "css": ".at-life{display:flex;flex-direction:column;align-items:stretch;gap:6px;max-width:560px}.at-life .diagram-card{display:flex;flex-direction:column;gap:3px;padding:10px 14px}.at-life .diagram-box{align-self:flex-start}.at-life .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+A qualquer momento o agente pai pode retomar o subagente com acompanhamento via `sendToTask(taskId, message)`. Se o subagente cometer erros, `markTaskErrored(taskId, reason)` registra a falha e a apresenta ao usuário.
+
+As mensagens bidirecionais são duráveis. O acompanhamento dos pais aos subagentes em execução é
+entregue durante o ciclo de vida da tarefa; se o subagente não puder consumi-los em
+na etapa atual, eles devem permanecer na fila e ser aplicados em um local seguro
+ponto de continuação. Os subagentes também podem responder quando precisarem de esclarecimentos
+em vez de bloquear de forma invisível.
+
+## Leitura do estado da tarefa {#reading-state}
+
+Do código do servidor ou outro actions:
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+Campos-chave `AgentTask`:
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
+}
+```
+
+## Perfis de agentes personalizados {#profiles}
+
+Mapeamento de subagentes para perfis de agentes personalizados — arquivos Markdown em `agents/<slug>.md` no espaço de trabalho que aparecem no menu suspenso `@mention` e servem como alvos de delegação. [Workspace — Custom Agents](/docs/workspace#custom-agents) possui o formato completo (frontmatter, `tools`, `delegate-default`, substituições de modelo).
+
+## Proteção de profundidade de delegação {#depth-guard}
+
+Subagentes podem gerar subagentes, o que é um risco descontrolado/de custo: uma cadeia ilimitada de delegações pode se espalhar indefinidamente. A estrutura impõe um **limite rígido na profundidade da delegação**, no lado do servidor, independente de qualquer proteção no nível da ferramenta.
+
+O bate-papo de nível superior é profundo `0`. Um subagente gerado é a profundidade `1`; esse subagente pode aparecer mais uma vez (profundidade `2`); um spawn que criaria um subagente de profundidade `3` é **recusado**. O limite padrão é **2**.
+
+```an-diagram title="Delegation depth guard (default cap 2)" summary="Each level may spawn one deeper until the cap; a spawn past it is refused server-side."
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>Top-level chat</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>Sub-agent</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card warn\"><span class=\"diagram-pill warn\">depth 2</span><strong>Sub-agent's sub-agent</strong><small class=\"diagram-muted\">at the cap &mdash; may NOT spawn</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">depth 3</span><strong>Refused</strong><small class=\"diagram-muted\">server-side error</small></div></div>",
+  "css": ".at-depth{display:flex;flex-direction:column;gap:8px}.at-depth .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.at-depth .rung-1,.at-depth .diagram-card:nth-child(2){margin-inline-start:24px}.at-depth .diagram-card:nth-child(3){margin-inline-start:48px}.at-depth .diagram-card:nth-child(4){margin-inline-start:72px}"
+}
+```
+
+A aplicação é ambiental: cada subagente é executado dentro de um `AsyncLocalStorage` que registra sua própria profundidade, portanto, qualquer `spawnTask` alcançado transitivamente a partir dessa execução lê a profundidade de seu pai e recusa quando o limite é atingido - mesmo que a ferramenta `agent-teams` tenha sido entregue a um subagente que não deveria tê-la. A decisão é exposta como um `evaluateSubagentDepth(parentDepth)` puro e testável em unidade. Uma geração recusada retorna um erro claro: _"Limite de profundidade de delegação atingido (máx. N); não é possível gerar outro subagente."_
+
+### Configurando o limite {#depth-guard-config}
+
+Substitua o padrão no momento da implantação com `AGENT_NATIVE_MAX_SUBAGENT_DEPTH`:
+
+| Valor          | Efeito                                                                                                                                                               |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(desativado)_ | Limite padrão de `2`.                                                                                                                                                |
+| `0`            | **Nenhum subagente pode ser gerado** — o agente de nível superior faz todo o trabalho.                                                                               |
+| `1`…`16`       | São muitos níveis de delegação.                                                                                                                                      |
+| inválido/`>16` | Um valor não inteiro/negativo/NaN retorna para `2`; qualquer coisa acima de `16` é fixada em `16`, portanto, um erro de digitação nunca poderá desativar a proteção. |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+Quando um subagente está no limite ou abaixo dele, a estrutura injeta uma linha em seu contexto de tempo de execução informando a profundidade dele e se pode delegar mais, para que o modelo gaste seu orçamento de maneira adequada.
+
+## O que vem a seguir
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — o formato do perfil
+- [**A2A Protocol**](/docs/a2a-protocol) — quando o "subagente" mora em um aplicativo totalmente diferente
+- [**Actions**](/docs/actions) — as ferramentas que um subagente chama

package/corpus/core/docs/content/locales/pt-BR/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "Web de agente público"
+description: "Torne as rotas públicas rastreáveis, legíveis, citáveis e opcionalmente chamadas por agentes — robots.txt, llms.txt, espelhos de remarcação, JSON-LD e uma superfície pública MCP."
+---
+
+# Web de agente público
+
+A web pública do agente torna as rotas Agent-Native públicas fáceis para os agentes rastrearem, lerem, citarem e ligarem. O objetivo não é tornar públicos todos os endpoints do aplicativo. O objetivo é publicar uma superfície pública limpa para páginas que já são públicas, mantendo dados privados e acesso a ferramentas sob controles explícitos.
+
+O site de documentos é a implementação de referência. Hoje é enviado:
+
+- `/robots.txt` com uma política de rastreador que permite a recuperação, mas não permite o treinamento por padrão.
+- `/sitemap.xml` com URLs canônicos absolutos e `lastmod` quando o arquivo de origem o expõe.
+- `/llms.txt` e `/llms-full.txt` para descoberta de conteúdo amigável ao agente.
+- Espelhos Markdown como `/docs/getting-started.md`.
+- Respostas `Accept: text/markdown` para páginas de documentos públicos após uma compilação de produção.
+- JSON-LD para organização base, site e metadados de página.
+- Uma auditoria CLI (`npx @agent-native/core@latest audit-agent-web`) que verifica todos os itens acima.
+
+A configuração de `publicMcp: true` também expõe o actions ativado como um endpoint MCP público, permitindo que agentes externos liguem para eles diretamente (consulte [MCP Protocol](/docs/mcp-protocol)).
+
+```an-diagram title="What a public route publishes" summary="A public route fans out into agent-friendly representations. Reading the route is separate from calling tools — tool access stays opt-in."
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>Public route<br><small class=\"diagram-muted\">derived from route access settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">robots.txt</span><span class=\"diagram-pill\">sitemap.xml</span><span class=\"diagram-pill\">llms.txt</span><span class=\"diagram-pill\">.md mirror</span><span class=\"diagram-pill\">JSON-LD</span><span class=\"diagram-pill\">text/markdown</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col gate\"><span class=\"diagram-pill warn\">Tools stay private</span><small class=\"diagram-muted\">publicMcp + publicAgent.expose required</small></div></div>",
+  "css": ".diagram-web{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-web .diagram-arrow{font-size:22px;line-height:1}.diagram-web .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.diagram-web .gate{display:flex;flex-direction:column;gap:4px;align-items:flex-start}"
+}
+```
+
+## Configuração {#config}
+
+Adicione `agentWeb` na configuração do aplicativo de espaço de trabalho existente (no `package.json` do seu aplicativo na chave `agent-native` — ou equivalentemente `workspace.agentWeb`, `agentWeb` ou `root.agentWeb`). A lista de rotas públicas ainda é derivada das configurações de acesso à rota do aplicativo; `agentWeb` controla como essa superfície pública é representada para os agentes.
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin/*"],
+      "agentWeb": {
+        "discoverable": true,
+        "markdownTwins": true,
+        "llmsTxt": true,
+        "jsonLd": true,
+        "publicAgentCard": true,
+        "publicMcp": false,
+        "crawlerPolicy": "discoverable-no-training",
+        "crawlers": {
+          "training": "disallow",
+          "search": "allow",
+          "userTriggered": "allow",
+          "codingAgents": "allow",
+          "autonomousAgents": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+Para a maioria dos aplicativos, deixe os padrões como estão. Se um aplicativo tiver alguma rota pública, `discoverable` será ativado por padrão. A política padrão do rastreador é "detectável, não treinável": pesquisa, recuperação acionada pelo usuário, agentes de codificação e agentes de navegação autônomos são permitidos; rastreadores de treinamento não são permitidos.
+
+## Fonte da verdade da rota {#route-source}
+
+A descoberta na Web do agente segue o modelo de acesso por rota:
+
+- Aplicativos públicos expõem todas as rotas, exceto `protectedPaths`.
+- Aplicativos internos expõem apenas `publicPaths`.
+- As páginas de compartilhamento público e de formulário podem ser lidas pelos agentes.
+- Dados privados enviados, painéis autenticados e estado do usuário/organização nunca são incluídos apenas porque uma página próxima é pública.
+
+Isso mantém os aplicativos mistos naturais. Um aplicativo de formulários pode expor uma página de formulário pública e manter os envios privados. Um aplicativo de conteúdo pode expor postagens publicadas e manter o editor privado. Um site de documentos pode expor tudo, exceto ferramentas administrativas.
+
+## Páginas públicas não são ferramentas públicas {#public-tools}
+
+O acesso à página pública e o acesso à ferramenta pública são separados. Uma rota pública significa apenas que os agentes podem ler essa rota como HTML, Markdown, entradas de mapa do site, entradas de llms e dados estruturados.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "**A public page is not a public tool.** Making a route crawlable never exposes an action. Tool access requires an explicit `publicAgent.expose` opt-in on the action *and* `publicMcp: true` on the app."
+}
+```
+
+Para expor uma ação por meio de um protocolo de agente público, a ação deve aceitar:
+
+```an-annotated-code title="Opting one safe action onto the public surface"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Search published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"Search published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "Explicit opt-in", "note": "Without `publicAgent.expose === true`, the action never appears on any public agent surface — no matter how public its routes are." },
+    { "lines": "5-7", "label": "Self-describe safety", "note": "Mark it read-only, declare whether it needs auth, and flag whether it is consequential. Public MCP excludes consequential/write actions unless policy explicitly allows them." }
+  ]
+}
+```
+
+`agentWeb.publicMcp` permanece `false` por padrão. Quando MCP público estiver habilitado, o servidor deverá expor apenas actions com `publicAgent.expose === true` e ainda deverá excluir actions consequente ou de gravação, a menos que a ação e a política de autenticação permitam explicitamente.
+
+## Arquivos em tempo de compilação {#build-time}
+
+Os utilitários de estrutura em `@agent-native/core/agent-web` geram os arquivos comuns a partir de uma lista de páginas:
+
+```ts
+import {
+  buildAgentWebStaticFiles,
+  normalizeAgentWebConfig,
+} from "@agent-native/core/agent-web";
+
+const config = normalizeAgentWebConfig(
+  { crawlerPolicy: "discoverable-no-training" },
+  { hasPublicRoutes: true },
+);
+
+const files = buildAgentWebStaticFiles({
+  siteName: "My Agent-Native App",
+  siteUrl: "https://example.com",
+  description: "Public docs for my app.",
+  config,
+  pages: [
+    {
+      path: "/docs",
+      title: "Docs",
+      description: "Start here.",
+      markdown: "# Docs\n\nStart here.\n",
+      markdownPath: "/docs/getting-started.md",
+      lastmod: new Date(),
+    },
+  ],
+});
+```
+
+Os aplicativos Vite podem usar `createAgentWebVitePlugin` de `@agent-native/core/vite` para gravar esses arquivos em `public`, `dist`, `dist/client`, `dist/server/public` ou `build/client` durante compilações de produção.
+
+## Auditar um site {#audit}
+
+Use a auditoria CLI em um site implantado ou em um servidor de produção local:
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+A auditoria verifica:
+
+- SSR HTML visível.
+- URLs canônicos.
+- JSON-LD.
+- Política `robots.txt` e mapa do site absoluto URL.
+- Entradas absolutas no mapa do site.
+- `/llms.txt` e `/llms-full.txt`.
+- Espelhos Markdown.
+- `Accept: text/markdown`.
+- Nenhum bloqueio 401/403 acidental para agentes comuns de recuperação de agentes.
+
+A auditoria sai diferente de zero se uma superfície pública obrigatória estiver faltando.
+
+## O que vem a seguir
+
+- [**Actions**](/docs/actions) — como incluir actions no protocolo de agente público
+- [**MCP Protocol**](/docs/mcp-protocol) — a superfície MCP que `publicMcp: true` permite
+- [**Deployment**](/docs/deployment) — onde esses arquivos estáticos são gravados durante as compilações

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

@@ -0,0 +1,111 @@
+---
+title: "Registro de auditoria"
+description: "Um registro durável, apenas anexado, de quem alterou quais dados do aplicativo, quando e se foi você ou o agente, capturado automaticamente no processo de ação."
+---
+
+# Registro de auditoria
+
+Cada aplicativo nativo do agente recebe um log de auditoria pronto para uso: um registro durável, completo, com escopo de acesso e somente acréscimo de **quem alterou quais dados do aplicativo, quando, de onde e - quando foi o agente - em qual execução.** A captura é automática no processo de ação; você não escreve nenhum código para isso.
+
+Como o agente pode alterar dados em seu nome, a pergunta principal que um registro de auditoria responde aqui não é apenas "quem editou este registro" — é **"fui eu ou o agente, e qual turno causou isso?"** Nenhum outro sistema na estrutura pode responder a isso.
+
+## Auditoria x observabilidade x rastreamento {#which}
+
+Três sistemas registram “o que aconteceu”, por três razões diferentes. Escolha pela pergunta que você está fazendo:
+
+| Sistema                                  | A pergunta que ele responde                          | Fidelidade                          | Público                                  |
+| ---------------------------------------- | ---------------------------------------------------- | ----------------------------------- | ---------------------------------------- |
+| **Registro de auditoria** (esta página)  | "Quem alterou este registro, quando e foi o agente?" | **Completo, durável, com escopo**   | Usuário, administrador, o próprio agente |
+| **[Observability](/docs/observability)** | "Por que o agente fez isso e quanto custou?"         | Telemetria de intervalo amostrado   | Desenvolvedor                            |
+| **[Tracking](/docs/tracking)**           | "Como as pessoas estão usando o produto?"            | Dispare e esqueça para SaaS externo | PM / crescimento                         |
+
+Um registro de auditoria que é amostrado ou enviado para um provedor de análise é inútil — o ponto principal é que ele seja completo, local e consultável. Portanto, é um subsistema próprio, não um modo dos outros dois.
+
+## O que é capturado automaticamente {#captured}
+
+Quando qualquer ação de **mutação** é executada (qualquer coisa que não seja um `GET` somente leitura), a estrutura anexa uma linha a `agent_audit_log` com:
+
+- **Ação** — o nome da ação (por exemplo, `delete-recording`).
+- **Ator** — `agent`, `human` ou `system`, além do e-mail do ator — preenchido **mesmo para chamadas de agente**, para que você obtenha "o agente, atuando em nome de alice@, …".
+- **Run linkage** — o agente `threadId` / `turnId` que acionou a chamada (uma chamada de ferramenta), portanto, uma mutação remonta ao turno exato do agente.
+- **Superfície** — `tool` (agente), `frontend`, `http`, `cli`, `mcp` ou `a2a`.
+- **Resultado** — `success`, `error` (com um código de erro) ou `denied` (bloqueado por um portão de aprovação humana).
+- **Entradas** — os argumentos da chamada, com valores em formato de credencial [redacted](#privacy).
+- **Destino e proprietário** — o recurso que a ação alterou, usado para [scope reads](#reading).
+
+Não é necessária fiação — a captura se conecta ao `defineAction` de forma transparente. actions somente leitura são ignorados, e algumas estruturas de alta frequência actions (sincronização de estado do aplicativo, raio X de contexto, navegação) são ignoradas por padrão para evitar inundar o log.
+
+## Declare o que uma ação mudou {#target}
+
+Por padrão, um evento tem como escopo o **ator** — você vê suas próprias alterações e as alterações do agente em seu nome. Para fazer com que uma alteração em um recurso _compartilhado_ também apareça na trilha do **proprietário** e para rotular eventos por recurso, declare um `target`:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+Tudo em `audit` é opcional. A adição mínima útil é `target: () => ({ type, id })`.
+
+### Captura de ajuste {#tuning}
+
+| Opção                | Efeito                                                                       |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `audit.target`       | Rotule o evento com o recurso e as leituras do escopo para seu proprietário. |
+| `audit.summary`      | Uma linha curta e legível para o evento.                                     |
+| `audit.onRead`       | Audite uma **leitura** confidencial (acesso secreto, exportação em massa).   |
+| `audit.enabled`      | `true` força captura; `false` desativa uma mutação barulhenta.               |
+| `audit.recordInputs` | `false` ignora a captura dos argumentos (já redigidos).                      |
+
+## Lendo a trilha {#reading}
+
+Duas leituras actions estão disponíveis para o agente **e** o frontend em cada aplicativo, com escopo SQL para o chamador — eles nunca retornam as linhas de outro locatário:
+
+- **`list-audit-events`** — filtrar por `targetType` / `targetId`, `actorKind` (`agent` | `human` | `system`), `status`, `threadId` / `turnId`, `action`, `sinceMs` e `limit`.
+- **`get-audit-event`** — um evento por ID, incluindo sua carga útil de entrada editada.
+
+Crie um feed de atividades ou uma linha "quem mudou isto" chamando `list-audit-events` do UI com `useActionQuery` — nunca escreva manualmente uma busca na tabela de auditoria:
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+O agente pode chamar a mesma ação - pergunte "o que você mudou nesta gravação?" e responde pela trilha.
+
+## Privacidade e retenção {#privacy}
+
+- **Redação** — antes de qualquer entrada ser armazenada, chaves e valores em formato de credencial (tokens, segredos, senhas, strings de portador) são removidos e cargas úteis superdimensionadas são truncadas. O log de auditoria nunca se torna um armazenamento secundário de segredos. Mantenha o texto `summary` livre de dados confidenciais também.
+- **Apenas acréscimo** — não há ação de atualização ou exclusão para linhas de auditoria. A única exclusão é a eliminação da retenção, o que torna o registro confiável como trilha de auditoria.
+- **Isolamento do locatário** — as leituras têm como escopo a identidade e a organização do chamador; sem identidade, nada corresponde.
+
+Configurar via ambiente:
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — por quanto tempo as linhas são mantidas (padrão `365`; `0` = manter para sempre).
+- `AGENT_NATIVE_AUDIT_ENABLED=false` — interruptor de interrupção global.
+
+## O que vem a seguir
+
+- [**Actions**](/docs/actions) — a costura `defineAction` onde a captura acontece
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — actions fechado, registrado como `denied`
+- [**Security & Data Scoping**](/docs/security) — a auditoria do modelo de propriedade indica reutilização
+- [**Observability**](/docs/observability) — telemetria executada pelo agente (o outro "o que aconteceu")