@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,349 @@
+---
+title: "Agentes de aproveitamento"
+description: "Execute código Claude, Codex, Pi e outros equipamentos de codificação completos como agentes incorporados dentro do Agent-Native, com seu próprio loop, sandbox, ferramentas nativas e sessões recuperáveis apoiadas por SQL."
+search: "agentes de aproveitamento AgentHarness ai-sdk HarnessAgent Código Claude Codex Pi Cursor Mastra agente de codificação incorporado resolveAgentHarness startAgentHarnessRun ferramentas de host de sandbox de sessão recuperável"
+---
+
+# Agentes de aproveitamento
+
+> **Para quem se destina:** autores de host conectando um tempo de execução de codificação completo (Código Claude,
+> Codex, Pi) em Agent-Native como agente. Construindo um aplicativo? Comece com
+> [Creating Templates](/docs/creating-templates).
+
+Um agente de aproveitamento é um tempo de execução de agente completo — Código Claude, Codex, Pi e similares —
+que possui seu próprio loop, espaço de trabalho, ferramentas de arquivo nativas, estado de sessão, compactação,
+modelo de aprovação e comportamento do sandbox. Agent-Native executa isso através do
+**`AgentHarness`** substrato em `@agent-native/core/agent/harness`, transmite seu
+eventos na transcrição normal e persiste sua sessão nativa em um thread
+pode pausar e retomar.
+
+Isso é diferente do agente de bate-papo integrado e de trazer seu próprio bate-papo
+tempo de execução. O agente integrado e `AgentEngine` são para um modelo de ida e volta
+abaixo de `runAgentLoop`. Um chicote não é um provedor `AgentEngine` — ele executa seu
+próprio loop de ponta a ponta, então Agent-Native o conduz como uma sessão, não como uma única
+chamada de modelo.
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Qual documento de codificação eu quero? {#which-doc}
+
+| Você quer…                                                                               | Usar                                         |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Execute o código Claude / Codex / Pi **como agente**, com seu próprio loop + ferramentas | **Agentes de aproveitamento** (esta página)  |
+| Renderizar um espaço de trabalho de codificação estilo Claude/Codex **UI**               | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Troque o back-end que executa a **ferramenta `run-code`** do agente                      | [Adapters](/docs/sandbox-adapters)           |
+| Prepare uma ferramenta CLI (`gh`, `ffmpeg`) para o agente ligar                          | [Adapters](/docs/sandbox-adapters)           |
+
+Superfícies adjacentes: coloque um agente que você construiu em outro lugar atrás do bate-papo de Agent-Native
+UI com [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes); deixe um
+chamada de host MCP externa em seu aplicativo via [External Agents](/docs/external-agents);
+gerar execução de segundo plano/subagente com [Custom Agents & Teams](/docs/agent-teams).
+
+## Arnês embutidos {#built-in}
+
+`registerBuiltinAgentHarnesses()` registra três adaptadores apoiados pelo AI SDK
+`HarnessAgent`:
+
+| Nome                         | Tempo de execução | Caixa de areia | Aprovações |
+| ---------------------------- | ----------------- | -------------- | ---------- |
+| `ai-sdk-harness:claude-code` | Código Claude     | sim            | sim        |
+| `ai-sdk-harness:codex`       | Codex             | sim            | não        |
+| `ai-sdk-harness:pi`          | Pi                | não            | sim        |
+
+Seus pacotes de tempo de execução são **dependências de pares opcionais** e carregam lentamente, portanto,
+aplicativo que nunca usa arnês não paga por isso. Cada adaptador carrega um
+Dica `installPackage` (por exemplo `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness` lança uma instalação clara
+erro se os pacotes estiverem faltando e `isAgentHarnessPackageInstalled(entry)`
+permite verificar primeiro.
+
+`registerBuiltinAgentHarnesses()` também registra os chicotes [ACP](#acp)
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## Agentes ACP {#acp}
+
+Agent-Native pode atuar como um [ACP](https://agentclientprotocol.com) (Agente Cliente
+Protocolo) **cliente** e acione um agente de codificação local — Gemini CLI, Claude Code,
+ou qualquer agente compatível com ACP — através deste mesmo substrato. O agente é executado como um
+subprocesso local que fala JSON-RPC delimitado por nova linha sobre stdio; Editor do ACP
+↔ o modelo do agente tem exatamente esse formato.
+
+Este adaptador tem como escopo **codificação local**. O processo filho herda o
+ambiente pai, para que o agente reutilize qualquer login CLI local que já possua
+(por exemplo, autenticação `gemini` ou `claude` no diretório inicial do usuário). Não é um
+transporte hospedado ou em sandbox, e não é um transporte chat/A2A — para esses,
+veja [Agent Surfaces](/docs/agent-surfaces).
+
+| Nome              | Comando padrão                                 | Recuperável\* |
+| ----------------- | ---------------------------------------------- | ------------- |
+| `acp`             | _(forneça `command`/`args` via configuração)_  | sim           |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | sim           |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | sim           |
+
+\*Resume funciona quando o agente anuncia o recurso `loadSession` e
+caso contrário, será degradado para uma nova sessão.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+O transporte do protocolo (`@zed-industries/agent-client-protocol`) é opcional
+dependência carregada lentamente através da dica `installPackage`, assim como o AI SDK
+arreios. O próprio binário do agente (`@google/gemini-cli`,
+`@zed-industries/claude-code-acp`,…) é um CLI externo separado; as predefinições
+inicie-o através de `npx` e o comando/args permanecerá substituível porque o agente ACP
+os sinalizadores de entrada ainda evoluem.
+
+`permissionMode` mapeia para ACP `session/request_permission` usando a chamada de ferramenta
+digite os relatórios do agente: leituras sempre executadas, edições executadas em `allow-edits` e
+tudo que é arriscado avisa, a menos que `allow-all`. As aprovações aparecem normalmente
+Eventos `approval-request`. O adaptador serve `fs/read_text_file` e
+`fs/write_text_file` no espaço de trabalho da sessão (recusando caminhos que escapam
+it) e as gravações emitem eventos `file-change`; métodos de terminal não são anunciados,
+portanto, o agente usa seu próprio shell.
+
+## Autenticação Codex: Código UI versus sandboxes de chicote {#codex-auth}
+
+Existem duas superfícies Codex e elas autenticam de maneira diferente:
+
+- **Agent-Native Code / Desktop** executa `codex exec` na máquina do usuário. Se
+  o usuário executou `codex login`, esta execução local reutiliza qualquer ChatGPT
+  assinatura ou chave API autentica os relatórios Codex CLI instalados por meio de
+  `codex login status`.
+- **`ai-sdk-harness:codex`** carrega `@ai-sdk/harness-codex`, que aciona Codex
+  dentro da caixa de proteção do chicote através de `@openai/codex-sdk`. Não acontece silenciosamente
+  herdar o login do usuário Desktop `~/.codex` porque o sandbox pode ser remoto
+  ou isolado. Para sandboxes confiáveis/privadas, opte por `codexCliAuth: true`;
+  Agent-Native copia o arquivo de autenticação local Codex CLI para o sandbox antes do
+  arnês começa. Para sandboxes hospedados ou compartilhados, configure API-key/gateway
+  autenticação.
+
+Então, se alguém perguntar qual pacote carrega o caminho Codex OAuth: para codificação local
+sessões, use `@agent-native/core` / Desktop mais o instalado
+`@openai/codex` CLI e `codex login`. Para `ai-sdk-harness:codex` em sandbox,
+use a opção `codexCliAuth` explícita ao copiar esse login para o sandbox
+é aceitável.
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` lê `CODEX_HOME/auth.json` ou `~/.codex/auth.json`. Para
+aponte para um login local diferente, passe
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` ou
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## Registrar e resolver {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` retorna um `AgentHarnessAdapter`. O
+O `config` opcional é encaminhado para a fábrica do adaptador — para os adaptadores AI SDK
+que mapeia para `AiSdkHarnessAdapterOptions` (`label`, `description`,
+`permissionMode`, `harnessOptions`, `agentOptions` e Codex somente
+`codexCliAuth`). Use `listAgentHarnesses()` para enumerar o que está registrado
+um seletor.
+
+## Fazer uma curva {#run-a-turn}
+
+`startAgentHarnessRun` conecta uma sessão de aproveitamento ao gerenciador de execução compartilhado
+ciclo de vida. Ele cria (ou reutiliza) a sessão nativa, persiste, transmite o
+por sua vez, traduz cada evento de aproveitamento em eventos de transcrição e desanexa o
+estado retomável quando o turno termina.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun` retorna o `ActiveRun` do run-manager, então é a vez
+aparece através das rotas de corrida, transcrição e cancelamento existentes, assim como
+qualquer outro agente executado. Passe um `session` já criado em vez de `createSession`
+para continuar uma sessão que você está mantendo na memória.
+
+## Sessões e currículo {#sessions}
+
+Um chicote possui um estado de sessão nativo de longa duração. Agent-Native persiste em SQL
+para que um thread possa sobreviver entre turnos, processos e implantações. O `resumeState`
+é **opaco** — Agent-Native armazena e devolve, mas nunca inspeciona ou
+interpreta.
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+A loja também expõe `saveAgentHarnessSession`, `updateAgentHarnessSession`,
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped` e `ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun` chama os caminhos salvar/atualizar/parar para você; alcançá-los
+diretamente apenas em um host personalizado.
+
+## Ferramentas e permissões do host {#host-tools}
+
+Um chicote traz suas próprias ferramentas nativas (leitura, edição, gravação, shell e assim por diante), então
+você **não** expõe novamente a edição de arquivos como ferramentas de host. Passe apenas por **estreito,
+conjunto intencional** de Agent-Native actions até `createSession.tools` quando você
+deseja que o equipamento atinja operações específicas do aplicativo e mantenha `defineAction`
+autenticação, contexto de solicitação, tempos limite, truncamento e metadados somente leitura intactos quando
+você faz.
+
+`permissionMode` determina o que o chicote pode fazer sem aprovação:
+
+| Modo          | Significado                                                       |
+| ------------- | ----------------------------------------------------------------- |
+| `allow-reads` | Padrão. Leituras executadas; edições e prompt actions arriscado   |
+| `allow-edits` | Leituras e edições são executadas; outro prompt actions arriscado |
+| `allow-all`   | Sem restrição de aprovação                                        |
+
+Quando um arnês faz uma pausa para aprovação, ele emite um evento `approval-request` e o
+a sessão é marcada como `idle` com a aprovação pendente registrada, para que UI possa
+dê-lo à tona e retome a decisão do usuário. Veja
+[Human Approval](/docs/human-approval) para a superfície de aprovação.
+
+## Eventos {#events}
+
+Uma sessão de aproveitamento transmite valores `AgentHarnessEvent`, que Agent-Native
+traduz-se para o fluxo `AgentChatEvent` padrão com
+`agentHarnessEventToAgentChatEvents`. A união de eventos cobre `text-delta`,
+`thinking-delta`, `activity`, `tool-start`, `tool-done` (que pode carregar um
+carga útil `mcpApp` para widgets nativos), `approval-request`, `file-change`,
+`compaction`, `usage`, `error` e `done`. Como os resultados da ferramenta fluem pelo
+mesma tradução, widgets nativos declarados por ação ainda são renderizados — consulte
+[Native Chat UI](/docs/native-chat-ui).
+
+## Execuções em segundo plano e UI {#background-runs}
+
+O Harness executa o projeto no formato `BackgroundAgentRun` compartilhado com
+`createAgentHarnessBackgroundAgentController()` e estão disponíveis através do
+rotas de execução existentes como `goalId=agent-harness`. Isso significa um Claude de longa duração
+O código ou a sessão Codex aparece nas mesmas superfícies de execução em segundo plano e de transcrição
+como equipes de agentes e outros adaptadores, com `listAgentHarnessBackgroundRuns`,
+`listAgentHarnessBackgroundTranscriptEvents`, `getAgentHarnessBackgroundRun` e
+`stopAgentHarnessBackgroundRun` disponível para hosts personalizados.
+
+## Adaptadores personalizados {#custom-adapters}
+
+Para agrupar um tempo de execução que não seja um dos integrados, implemente
+`AgentHarnessAdapter` e registre-o. O adaptador declara seus recursos e
+cria sessões; uma sessão expõe `streamTurn` e `continueTurn` opcional,
+`approve`, `detach`, `stop` e `destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+Mantenha o pacote de tempo de execução opcional com uma importação dinâmica em `createSession` e um
+Dica `installPackage`. Para chicotes de codificação apoiados por ponte, é necessário um
+provedor de sandbox/espaço de trabalho em vez de executar um agente de codificação arbitrário no
+processo host — consulte [Sandbox Adapters](/docs/sandbox-adapters). O adaptador AI SDK
+(`createAiSdkHarnessAdapter`, apoiado por `HarnessAgent` de `@ai-sdk/harness`) é
+uma implementação deste contrato, não a abstração pública.
+
+## Não {#donts}
+
+- Não adicione código Claude, Codex, Cursor, Mastra ou Pi como um `AgentEngine`. Eles
+  possuem seu loop; executar um em `AgentEngine.stream()` executa o loop duas vezes
+  e perde a semântica do ciclo de vida da sessão.
+- Não reproduza todo o histórico de bate-papo do Agent-Native em um chicote a cada turno. Currículo
+  a sessão de aproveitamento com seu `resumeState`.
+- Não armazene `resumeState` em `application_state`. Pertence ao arnês
+  tabela da sessão SQL.
+- Não exponha todas as ações do aplicativo a todas as sessões de aproveitamento por padrão. Entregue um
+  conjunto de ferramentas pequeno e intencional.
+
+## Documentos relacionados {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) — coloque seu próprio agente por trás do bate-papo UI com `AgentChatRuntime`.
+- [Agent Surfaces](/docs/agent-surfaces) — escolha headless, chat, sidecar ou aplicativo completo.
+- [Agent-Native Code UI](/docs/code-agents-ui) — a superfície reutilizável do espaço de trabalho de codificação.
+- [Custom Agents & Teams](/docs/agent-teams) — execuções em segundo plano e delegação de subagentes.
+- [Sandbox Adapters](/docs/sandbox-adapters) — back-ends de execução conectáveis para chicotes de codificação.
+- [Human Approval](/docs/human-approval) — o chicote de superfície aprovado é usado.

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

@@ -0,0 +1,86 @@
+---
+title: "Aprovações humanizadas"
+description: "Pause o agente antes que uma ação de alta consequência seja executada — o portão needApproval de defineAction emite um evento aprovado_required, o humano aprova e só então a ferramenta é executada."
+---
+
+# Aprovações humanas
+
+A maioria dos actions deve simplesmente rodar. Alguns – enviar um e-mail, cobrar um cartão, excluir uma conta – são externos e difíceis de desfazer, e você não quer que o agente os faça de forma autônoma. Para esses, `defineAction` tem uma **porta de aprovação** opcional: quando o agente tenta chamar a ação, o loop faz uma pausa, apresenta uma affordance de aprovação/negação para o humano e executa a ação _somente_ depois que o humano aprovar aquela chamada específica.
+
+> [!WARNING]
+> Mantenha as aprovações raras. Cada ação bloqueada é uma parada brusca no loop do agente – ela interrompe a execução e exige uma ida e volta humana. Use `needsApproval` apenas para operações externas genuinamente de alta consequência, difíceis de desfazer. Se você estiver bloqueando leituras ou gravações de rotina, estará errado. O padrão é **desativado** e quase todas as ações devem deixá-lo desativado.
+
+## O portão `needsApproval` {#needs-approval}
+
+Defina `needsApproval` em um `defineAction`. Aceita um booleano ou um predicado:
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** — sempre exige aprovação.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** — requer aprovação somente quando o predicado retornar verdadeiro. Gate condicionalmente, por ex. apenas para destinatários externos ou apenas acima do limite em dólares:
+
+  ```ts
+  needsApproval: (args) => !args.to.endsWith("@sua-empresa.com"),
+  ```
+
+  Mantenha o predicado puro e rápido. **Falha ao fechar**: se o predicado for lançado, a estrutura tratará isso como "aprovação necessária" em vez de executar silenciosamente uma ação de alta consequência.
+
+Quando `needsApproval` é omitido, o comportamento permanece inalterado byte por byte — não há custo extra no caminho comum.
+
+Isso funciona da mesma forma para actions estilo `parameters` herdado e actions baseado em esquema, e para agentes no aplicativo, subagentes, chamadores A2A e MCP (cada superfície de agente roteia pelo mesmo loop).
+
+## Como o loop pausa {#loop}
+
+Quando o agente chama uma ação bloqueada e essa chamada específica **não** já foi aprovada, o loop **não** executa `run()`. Em vez disso:
+
+1. Resolve o portão. Para um predicado, chama `needsApproval(input, ctx)`; um lançamento é tratado como "deve ser aprovado" (falha fechada).
+2. Emite um evento `tool_start` (para que o UI mostre a chamada) seguido imediatamente por um evento **`approval_required`** e então interrompe o turno. O efeito colateral da ação nunca acontece.
+
+O evento `approval_required` carrega tudo que o cliente precisa para renderizar uma affordance:
+
+| Campo         | Tipo     | Notas                                                                   |
+| ------------- | -------- | ----------------------------------------------------------------------- |
+| `tool`        | `string` | O nome da ação que o agente tentou chamar.                              |
+| `input`       | objeto   | Os argumentos que o agente passou.                                      |
+| `approvalKey` | `string` | **Chave estável** o cliente responde para aprovar _esta chamada exata_. |
+| `toolCallId`  | `string` | O ID de chamada de ferramenta do lado do modelo, quando disponível.     |
+
+O `approvalKey` é derivado deterministicamente do nome da ferramenta mais sua entrada, portanto a mesma chamada lógica sempre produz a mesma chave. O modelo nunca o vê ou define – é puramente um aperto de mão entre a estrutura e a capacidade de aprovação humana.
+
+A ferramenta pausada retorna um resultado informando ao modelo que a curva está pausada e não deve tentar novamente, para que o modelo não gire.
+
+## Como o humano aprova {#approve}
+
+Em `approval_required`, o chat UI renderiza uma affordance **Aprovar/Negar** na chamada de ferramenta pausada. Isso é conectado automaticamente no `AssistantChat` — você não o constrói por modelo.
+
+- **Approve** reemite o turno (uma mensagem de continuação comum) carregando a chave da chamada em `approvedToolCalls: [approvalKey]`. Na volta reemitida, o portão vê a chave no conjunto aprovado e permite que aquela chamada específica seja executada normalmente.
+- **Deny** descarta a affordance localmente; nada é reemitido, então a ação nunca é executada.
+
+`approvedToolCalls` é um campo na solicitação de chat (`AgentChatRequest.approvedToolCalls`). As teclas não presentes permanecem pausadas – a aprovação de uma chamada nunca aprova outras em branco. Como a chave é endereçada ao conteúdo, uma aprovação autoriza _essa chamada com esses argumentos_; se o modelo posteriormente propor um envio diferente, será uma nova chave e uma nova aprovação.
+
+## De ponta a ponta {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+O uso canônico (e intencionalmente raro) dessa porta na estrutura é a ação `send-email` do modelo Mail, que define `needsApproval: true` para que o agente possa rascunhar e enfileirar-se livremente, mas nunca possa realmente enviar uma mensagem sem que um humano aprove o envio específico.
+
+## Relacionado
+
+- [**Actions**](/docs/actions#needs-approval) — a superfície `defineAction` completa, incluindo `outputSchema` para validação de valores de retorno.
+- [**Security**](/docs/security) — quando alcançar um portão de aprovação em vez de ocultar uma ação do modelo.
+- [**Mail template**](/docs/template-mail) — `send-email` é o exemplo de referência.

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

@@ -1,15 +1,18 @@
 ---
 title: "Internacionalização"
-description: "Localize apps Agent Native com catálogos compartilhados, seletor de idioma, fallback do navegador e conteúdo de docs por locale."
+description: "Localize aplicativos Agent Native com catálogos de localidade compartilhados, um seletor de idioma, substituto de idioma do navegador e conteúdo de documentos com reconhecimento de localidade."
 ---
 
 # Internacionalização
 
-Apps Agent Native podem localizar a UI do framework e dos templates com o runtime compartilhado `@agent-native/core/client/i18n`. O framework armazena a escolha de idioma do usuário em settings SQL, expõe essa preferência como actions e volta para English quando uma app ainda não traduziu uma string.
+Os aplicativos Agent Native podem localizar a estrutura e o modelo UI por meio do compartilhamento
+Tempo de execução `@agent-native/core/client/i18n`. A estrutura armazena
+escolha de idioma nas configurações de SQL, expõe-no como actions e volta para
+Inglês quando um aplicativo ainda não traduziu uma string.
 
-## Runtime {#runtime}
+## Tempo de execução
 
-Use o provider por meio de `AppProviders`:
+Use o provedor por meio de `AppProviders`:
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()` define o `lang`, `dir` e `window.__AGENT_NATIVE_LOCALE__` iniciais antes da hydration do React. Rotas SSR públicas podem chamar `resolveLocaleFromRequest()` de `@agent-native/core/server` e passar o locale/catalog resolvido para o script, evitando divergências de hydration.
+`getLocaleInitScript()` define os valores iniciais `lang`, `dir` e
+`window.__AGENT_NATIVE_LOCALE__` antes de React hidratar. Rotas públicas SSR podem
+chame `resolveLocaleFromRequest()` de `@agent-native/core/server` e passe o
+localidade/catálogo resolvidos nesse script para evitar incompatibilidades de hidratação.
 
-## Catálogos {#catalogs}
+## Catálogos
 
-Cada template localizado mantém catálogos em `app/i18n/`:
+Cada modelo localizado mantém catálogos em `app/i18n/`:
 
 ```ts
 // app/i18n/index.ts
@@ -52,51 +58,88 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-Sempre inclua `en-US` no bundle. Importe dinamicamente catálogos que não sejam English para que usuários baixem apenas o locale ativo. Os locale codes suportados são `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` e `ar-SA`.
+Sempre inclua `en-US`. Importação dinâmica de catálogos em idiomas diferentes do inglês apenas para usuários
+baixe a localidade ativa. Os códigos de localidade suportados são `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` e `ar-SA`.
 
-## UI {#ui}
+## UI
 
-Use `useT()` para textos de interface e `<LanguagePicker />` em settings:
+Use `useT()` para strings de interface e coloque `<LanguagePicker />` no aplicativo
+Página `/settings`. Os aplicativos da barra lateral devem expor **Configurações** na barra lateral do aplicativo;
+o ícone do idioma do cabeçalho é apenas um atalho.
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-Use `useFormatters()` para datas, números, tempo relativo e listas. Não coloque formatação sensível a locale dentro de strings traduzidas.
+O controle "Configurações do agente" deve abrir a guia Configurações da barra lateral direita do agente
+para modelo, chave API, automação, voz e outros controles em nível de estrutura.
+Os aplicativos podem duplicar configurações de estrutura de alto valor em suas próprias páginas de configurações
+quando a configuração é central para o aplicativo, mas a guia de configurações da barra lateral permanece a mesma
+fonte da verdade.
+
+Use `useFormatters()` para datas, números, tempo relativo e listas. Não coloque
+formatação de data/número sensível à localidade dentro de strings de tradução.
 
-## Conteúdo do site de docs {#docs-site-content}
+## Conteúdo do site do Documentos {#docs-site-content}
 
-Páginas públicas de docs usam o mesmo core provider, mas com `persistPreference={false}` para que tráfego anônimo use localStorage e o idioma do navegador em vez de actions de settings SQL. A fonte English continua em `packages/core/docs/content/*.md`. Overrides localizados ficam em `packages/core/docs/content/locales/<locale>/<slug>.md`.
+As páginas de documentos públicos usam o mesmo provedor principal, mas com
+`persistPreference={false}` para que o tráfego de documentos anônimos use localStorage e o
+idioma do navegador em vez das configurações SQL actions. A fonte em inglês permanece em
+`packages/core/docs/content/*.md`. As substituições de página localizadas ficam ao lado dela em
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-Use os mesmos BCP-47 locale codes dos catálogos de app. Mantenha o mesmo slug da fonte English, preserve anchors estáveis com `{#anchor}` em headings traduzidos e não traduza routes, action names, protocol fields, env vars ou provider names. Se um locale não tiver Markdown traduzido para uma página, o site cai para English nessa página enquanto continua localizando navegação e chrome.
+Use os mesmos códigos de localidade BCP-47 dos catálogos de aplicativos. Mantenha o mesmo slug do
+Fonte em inglês, preserve âncoras estáveis com `{#anchor}` em títulos traduzidos,
+e deixe rotas, nomes de ações, campos de protocolo, variáveis de ambiente e nomes de provedores
+não traduzido. Se uma localidade não tiver Markdown traduzido para uma página, o site de documentos
+volta para o inglês para essa página enquanto ainda localiza a navegação e o Chrome.
 
-## Actions e persistência {#actions-and-persistence}
+## Actions e persistência
 
-Toda app herda:
+Todo aplicativo herda:
 
 - `get-localization-preference` — lê o `{ locale }` do usuário atual
-- `set-localization-preference` — define `"system"` ou um locale suportado
+- `set-localization-preference` — defina `"system"` ou uma localidade compatível
 
-O valor durável fica em settings SQL com escopo de usuário sob `localization`. `localStorage` só é usado para pre-hydration e fallback anônimo. O locale ativo é espelhado no application state como contexto ambiente para que agents vejam o idioma atual da interface.
+O valor durável reside nas configurações SQL com escopo do usuário em `localization`.
+`localStorage` é usado apenas para pré-hidratação e reserva anônima. O ativo
+a localidade é espelhada no estado do aplicativo como contexto do ambiente para que os agentes possam ver
+o idioma da interface atual.
 
-## Guard {#guard}
+## Guarda
 
-Rode:
+Executar:
 
 ```bash
 pnpm guard:i18n-catalogs
 ```
 
-O guard verifica nomes de arquivos locale suportados, key parity, placeholder parity, stale keys e categorias plurais CLDR via `Intl.PluralRules`. Ele verifica estrutura, não qualidade de tradução; strings de alta visibilidade ainda precisam de revisão humana.
+O guarda verifica nomes de arquivos de localidade suportados, paridade de chave, paridade de espaço reservado,
+chaves obsoletas e categorias plurais CLDR por meio de `Intl.PluralRules`. Ele verifica
+estrutura, não qualidade da tradução; strings de alta visibilidade ainda precisam de humanos
+revisão.
 
-Não traduza identificadores estáveis como action names, routes, enum values, app-state keys, database values, protocol fields, env var names ou provider names.
+Não traduza identificadores estáveis, como nomes de ações, rotas, valores enum,
+chaves de estado do aplicativo, valores de banco de dados, campos de protocolo, nomes de variáveis de ambiente ou provedor
+nomes.