@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,146 @@
+---
+title: "Envio"
+description: "O plano de controle do espaço de trabalho: cofre de segredos, hub de integração, delegado entre aplicativos e caixa de entrada central para Slack, e-mail, Telegram, WhatsApp."
+---
+
+# Envio
+
+Dispatch é o aplicativo central que fica na frente de todos os outros aplicativos em seu espaço de trabalho e lida com segredos, integrações, mensagens e delegação entre aplicativos. É o **plano de controle do espaço de trabalho**: o agente único com quem sua equipe conversa, as credenciais de local único ativas e o roteador único que decide qual aplicativo especializado deve lidar com uma determinada solicitação.
+
+> **Dispatch o modelo versus `@agent-native/dispatch` o pacote.** Esta página aborda o conceito de aplicativo/modelo Dispatch — o que ele faz e por que você o deseja. O pacote `@agent-native/dispatch` npm é o tempo de execução publicado separadamente que agrupa a lógica do servidor do modelo Dispatch (cofre, integrações, destinos, trabalhos agendados e delegação entre aplicativos) como um pacote drop-in para espaços de trabalho que o estendem. Para o próprio aplicativo de scaffolding (rotas, telas, guia do agente), consulte o [Dispatch template](/docs/template-dispatch).
+
+Sem o Dispatch, cada aplicativo em um espaço de trabalho com vários aplicativos acaba reimplementando o mesmo encanamento: seu próprio bot Slack, seu próprio armazenamento secreto, seus próprios trabalhos agendados, sua própria cópia das instruções do espaço de trabalho. A rotação de uma chave API se transforma em dez reimplantações. Adicionar uma nova política se transforma em dez copiar e colar. O Dispatch centraliza tudo isso em um aplicativo para que os outros permaneçam focados em seus domínios.
+
+```an-diagram title="Dispatch as the workspace control plane" summary="One inbox, one vault, one MCP gateway, and shared resources sit in front of the domain apps, which Dispatch reaches as A2A peers."
+{
+  "html": "<div class=\"dsp-hub\"><div class=\"diagram-node\">Users &amp; external agents<br><small class=\"diagram-muted\">Slack · email · Telegram · WhatsApp · MCP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel dsp-control\" data-rough><span class=\"diagram-pill accent\">Dispatch &mdash; control plane</span><div class=\"dsp-caps\"><span class=\"diagram-pill\">Central inbox</span><span class=\"diagram-pill\">Secret vault</span><span class=\"diagram-pill\">Cross-app delegation</span><span class=\"diagram-pill\">MCP gateway</span><span class=\"diagram-pill\">Workspace resources</span></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"dsp-peers\"><div class=\"diagram-box\" data-rough>Mail</div><div class=\"diagram-box\" data-rough>Calendar</div><div class=\"diagram-box\" data-rough>Analytics</div></div><small class=\"diagram-muted\">domain apps &mdash; A2A peers</small></div>",
+  "css": ".dsp-hub{display:flex;flex-direction:column;align-items:center;gap:10px}.dsp-hub .dsp-control{display:flex;flex-direction:column;align-items:center;gap:10px;width:100%}.dsp-hub .dsp-caps{display:flex;gap:8px;flex-wrap:wrap;justify-content:center}.dsp-hub .dsp-peers{display:flex;gap:10px;flex-wrap:wrap;justify-content:center}"
+}
+```
+
+## Quando você deseja despacho {#when}
+
+Entre em contato com o Dispatch quando alguma destas situações for verdadeira:
+
+- Você está executando um [multi-app workspace](/docs/multi-app-workspace) (e-mail, calendário, análise, conteúdo) e não quer um bot Slack por aplicativo.
+- Você deseja **uma caixa de entrada para "o agente"** para que os usuários enviem mensagens diretas para um único bot e o aplicativo especializado certo faça o trabalho nos bastidores.
+- Você tem **segredos para todo o espaço de trabalho** (chave Stripe, chave OpenAI, tokens API de terceiros) que vários aplicativos precisam e deseja um cofre em vez de copiar valores em cada `.env`.
+- Você deseja um **fluxo de aprovação em tempo de execução** antes de alterações confidenciais (destinos salvos, edições de políticas) para que não administradores possam solicitar e administradores possam assinar sem uma implantação de código.
+- Você deseja **skills, instruções, perfis de agente e servidores MCP compartilhados** que os aplicativos no espaço de trabalho herdam. Altere uma vez e alcance todos.
+
+Se você estiver executando um único modelo independente, não precisará do Dispatch — cada modelo pode conectar suas próprias integrações de mensagens diretamente. Consulte [Messaging](/docs/messaging) para configuração independente.
+
+## O que o Dispatch faz {#what-it-does}
+
+Sete recursos, todos localizados no mesmo banco de dados de espaço de trabalho usado por outros aplicativos:
+
+| Capacidade                         | O que isso oferece                                                                                  | Configure                                                    |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| **Caixa de entrada central**       | Slack, e-mail, Telegram, WhatsApp, todos alcançam um agente com memória compartilhada e ferramentas | **Configurações → Mensagens** ([Messaging](/docs/messaging)) |
+| **Cofre secreto**                  | Armazene cada credencial uma vez; gire em um só lugar em todos os apps                              | **Vault** + modo de acesso (todos os aplicativos ou manual)  |
+| **Delegação entre aplicativos**    | Encaminha uma solicitação para o aplicativo especializado certo via A2A e responde no tópico        | Automático ([A2A](/docs/a2a-protocol))                       |
+| **Gateway MCP unificado**          | Um conector MCP para agentes externos alcança todos os aplicativos de espaço de trabalho concedidos | [External Agents](/docs/external-agents)                     |
+| **Recursos do espaço de trabalho** | Autor skills/instruções/perfis uma vez; os aplicativos os herdam em tempo de execução               | **Recursos** ([Workspace](/docs/workspace#global-resources)) |
+| **Sonhos**                         | Analisa execuções/feedback anteriores e propõe melhorias duradouras para você aprovar               | **Guia Sonhos**                                              |
+| **Fluxo de aprovação**             | Proteger alterações sensíveis no tempo de execução por meio de revisão administrativa in-line       | **política de aprovação de envio**                           |
+
+Cada um é detalhado abaixo.
+
+### Caixa de entrada central
+
+Slack, e-mail, Telegram e WhatsApp fluem para o circuito de agente do Dispatch. Conecte cada plataforma uma vez em **Configurações → Mensagens** e cada canal chega ao mesmo agente com a mesma memória e ferramentas. Um DM Slack e um e-mail para `agent@yourcompany.com` acabam como duas superfícies em um histórico de conversa, e não como dois bots desconectados. Consulte [Messaging](/docs/messaging) para obter as credenciais e webhook URLs.
+
+### Cofre secreto
+
+Armazene as credenciais uma vez no cofre do Dispatch. Por padrão, o acesso ao cofre é **todos os aplicativos**: cada chave salva está disponível para todos os aplicativos do workspace e `sync-vault-to-app` envia o cofre completo para o aplicativo de destino. Os espaços de trabalho que precisam de uma separação mais rigorosa podem mudar o cofre para o modo **manual**, onde são necessárias concessões explícitas por aplicativo antes da sincronização. Não administradores podem **solicitar** um segredo para um aplicativo; administradores **aprovam**, que cria o segredo e, em fluxos de trabalho manuais, a concessão. Cada leitura, concessão, sincronização e rotação é capturada em um log de auditoria. É isso que faz com que "girar a chave OpenAI" seja uma operação de um clique em dez aplicativos em vez de dez PRs.
+
+### Delegação entre aplicativos
+
+O Dispatch descobre automaticamente os outros aplicativos em seu espaço de trabalho como pares A2A — sem registro manual, sem configuração por aplicativo. Quando um usuário pede “resuma as inscrições da semana passada” em Slack, o Dispatch reconhece isso como uma solicitação de análise e chama o aplicativo de análise por meio de [A2A](/docs/a2a-protocol). Quando eles pedem "esboce uma resposta para Alice", ela é encaminhada para o aplicativo de e-mail. O Dispatch publica a resposta final no tópico de origem. A regra comportamental reside nas instruções do agente de despacho: o trabalho do domínio pertence ao aplicativo do domínio. O despacho é o orquestrador, não o especialista.
+
+### Gateway MCP unificado
+
+O Dispatch pode ser o único conector MCP para agentes externos: adicione `https://dispatch.agent-native.com/_agent-native/mcp` uma vez em Claude, ChatGPT, Codex ou Cursor, e uma autorização atinge cada aplicativo de espaço de trabalho concedido em vez de um conector por aplicativo. Consulte [External Agents](/docs/external-agents) para ver o fluxo de conexão completo, concessões de aplicativos, OAuth e visualizações de aplicativos in-line MCP.
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "Unified MCP gateway endpoint",
+  "description": "The single MCP connector URL external agents add (e.g. `https://dispatch.agent-native.com/_agent-native/mcp`). One authorization here reaches every **granted** workspace app instead of wiring one connector per app. App grants, OAuth, and inline MCP App previews are covered in [External Agents](/docs/external-agents).",
+  "auth": "Standard remote MCP OAuth, handled by the framework. The granted-app set scopes which workspace apps the connector can reach.",
+  "responses": [
+    { "status": "200", "description": "MCP JSON-RPC response — tools, resources, and MCP App UI resources aggregated across granted workspace apps." }
+  ]
+}
+```
+
+### Recursos do espaço de trabalho
+
+Skills, instruções de proteção, perfis de agente e recursos de referência podem ser criados uma vez no Dispatch e herdados pelo restante do espaço de trabalho. Os recursos com escopo **Todos os aplicativos** são globais: o Dispatch os armazena uma vez no escopo do espaço de trabalho e cada agente de aplicativo os lê em tempo de execução. Eles não são copiados em cada aplicativo e não há etapa manual de sincronização de recursos do espaço de trabalho. Os recursos compartilhados do app e os recursos pessoais podem substituir ou restringir os padrões do espaço de trabalho localmente.
+
+Consulte [Workspace — Global resources](/docs/workspace#global-resources) para obter a tabela de caminho canônico, pacote inicial e modelo de substituição.
+
+Os recursos do servidor MCP usam JSON e são intencionalmente apenas HTTP. Armazenar tokens em
+Envie o Vault, conceda ou sincronize essas chaves com os aplicativos de destino e faça referência a eles
+dos cabeçalhos com `${keys.NAME}` para que a credencial bruta nunca fique no
+corpo do recurso.
+
+A página **Recursos** destaca o pacote inicial recomendado para que os administradores possam ver rapidamente quais arquivos existem, restaurar arquivos iniciais ausentes sem substituir os existentes e editar seu conteúdo. Expanda qualquer recurso para visualizar sua pilha de tempo de execução efetiva para um aplicativo/usuário selecionado. Cada cartão de app também tem uma visualização de **Contexto** que mostra exatamente o que o app recebe.
+
+### Sonhos
+
+O Dispatch Dreams analisa execuções anteriores dos agentes, feedback, avaliações e falhas repetidas para propor melhorias duradouras. Um relatório de sonho é uma superfície de revisão, não uma reescrita silenciosa: ele pode sugerir atualizações de memória pessoal, limpeza de memória obsoleta, edições `LEARNINGS.md` compartilhadas, instrução/habilidade/conhecimento/recursos de agente no espaço de trabalho ou trabalhos recorrentes, e cada proposta está vinculada às execuções que a justificam. Instruções compartilhadas e recursos para toda a equipe exigem revisão antes de serem aplicados, especialmente quando as evidências vêm de Slack de entrada, e-mail, Telegram, WhatsApp ou conteúdo da web.
+
+Antes de propor uma escrita, Dreams compara as evidências com o índice de memória pessoal, notas `memory/*.md` existentes e `LEARNINGS.md` compartilhado. Se uma aula já foi capturada, o relatório registra que ela foi ignorada; se uma memória pessoal relacionada parecer obsoleta, a proposta direcionará essa nota existente em vez de criar uma duplicata.
+
+Comece na guia **Sonhos** no Dispatch. Execute primeiro uma aprovação manual, abra uma planilha de revisão da proposta para comparar a meta atual com o conteúdo proposto e as evidências de origem e, em seguida, aplique apenas as alterações que deseja manter. Depois que os relatórios forem consistentemente úteis, o Dispatch poderá criar um trabalho dos sonhos recorrente que continua produzindo propostas sem aplicar automaticamente alterações compartilhadas ou no nível de instrução.
+
+### Fluxo de aprovação
+
+O Dispatch pode bloquear alterações confidenciais no tempo de execução após a revisão do administrador. Hoje, isso abrange **destinos salvos** (os canais Slack e endereços de e-mail para os quais o agente pode enviar proativamente), **propostas dos sonhos** compartilhadas/da equipe, **recursos de espaço de trabalho** para todos os aplicativos criam/atualizam/exclui e a própria **política de aprovação de despacho**. Quando a política é ativada, a alteração é colocada na fila e o agente exibe uma visualização de aprovação em linha diretamente no chat. Os administradores aprovam ou rejeitam sem sair da conversa.
+
+## Como uma mensagem Slack flui pelo Dispatch {#flow}
+
+Examine um exemplo de ponta a ponta. Um usuário manda uma DM para o bot: _"resuma as inscrições da semana passada."_
+
+1. **Slack → webhook.** Slack `POST`s para `/_agent-native/integrations/slack/webhook` no aplicativo Dispatch. O manipulador verifica a assinatura e **insere uma linha em `integration_pending_tasks`**, depois dispara um `POST` autodirecionado para seu próprio processador e retorna `200` imediatamente para que Slack não tente novamente.
+2. **Nova execução do processador.** O endpoint do processador é executado em uma execução de função totalmente nova com seu próprio tempo limite completo. Ele reivindica a tarefa atomicamente e inicia o loop do agente.
+3. **O agente de despacho decide.** O agente lê a mensagem, reconhece "inscrições" como uma intenção de análise e invoca `call-agent` no [A2A endpoint](/docs/a2a-protocol) do aplicativo de análise. O trabalho real do SQL é executado ali.
+4. **Resposta postada no tópico.** O agente de análise retorna um resultado. O Dispatch o formata e publica de volta no mesmo thread Slack em que o usuário escreveu, usando a identidade vinculada, se houver (para que o agente atue com as permissões do solicitante, não do proprietário do espaço de trabalho).
+5. **Recuperação se alguma coisa morrer.** Se o processador travar no meio do voo — tempo limite A2A, erro do agente downstream, congelamento de função — um trabalho de nova tentativa varre tarefas travadas a cada 60 segundos e reinicia o processador. Até três tentativas antes que a tarefa seja marcada como `failed`.
+
+```an-diagram title="A Slack message through Dispatch" summary="Slack enqueues into SQL, a fresh execution drains it, the Dispatch agent delegates the domain work over A2A, and the reply lands back in the originating thread. A 60s retry job recovers anything that dies mid-flight."
+{
+  "html": "<div class=\"dsp-flow\"><div class=\"dsp-row\"><div class=\"diagram-node\">Slack DM<br><small class=\"diagram-muted\">\"summarize last week's signups\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/slack/webhook</strong><br><small class=\"diagram-muted\">verify + INSERT pending task</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">200</div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough><strong>fresh processor</strong><br><small class=\"diagram-muted\">claim task · start agent loop</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\">Dispatch agent decides</span><small class=\"diagram-muted\">analytics intent &rarr; call-agent</small></div></div><div class=\"dsp-row\"><div class=\"diagram-box\" data-rough>Analytics app<br><small class=\"diagram-muted\">A2A peer · runs the SQL work</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">reply posted in thread</div></div><div class=\"diagram-panel dsp-retry\" data-rough><span class=\"diagram-pill warn\">recovery</span> <span class=\"diagram-muted\">if the processor crashes &mdash; A2A timeout, downstream error, freeze &mdash; the 60s retry job re-fires it (&le;3 attempts) so the Slack reply still arrives</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</span></div></div>",
+  "css": ".dsp-flow{display:flex;flex-direction:column;gap:12px}.dsp-flow .dsp-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.dsp-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.dsp-flow .dsp-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+O mesmo fluxo se aplica a e-mail, Telegram e WhatsApp — apenas o adaptador muda.
+
+## História de confiabilidade {#reliability}
+
+Todo o pipeline foi criado para sobreviver em todos os hosts sem servidor (Netlify, Vercel, Cloudflare Workers) sem depender de APIs de execução em segundo plano específicos da plataforma.
+
+- **Webhook → fila SQL → processador de nova execução.** O loop do agente nunca é executado dentro do manipulador de webhook. A única tarefa do manipulador é verificar, enfileirar e retornar 200. Uma nova execução separada esgota a fila, de modo que uma execução lenta do agente nunca pode amarrar o webhook de entrada ou fazer com que a plataforma tente novamente.
+- ** Sondagem de continuação A2A.** Quando o Dispatch delega para outro aplicativo, ele sonda a tarefa downstream com um tempo limite limitado. Se o agente downstream demorar muito ou travar, o Dispatch registrará a continuação e o trabalho de nova tentativa a pegará — a resposta Slack do usuário ainda chegará.
+- **A2A entre aplicativos assinados automaticamente.** Os espaços de trabalho de vários aplicativos hospedados geram automaticamente credenciais A2A por aplicativo no momento da implantação, para que os aplicativos no mesmo espaço de trabalho possam ligar entre si sem que você nunca cole um segredo JWT. A camada de descoberta de agente do Dispatch lê essas credenciais do banco de dados do espaço de trabalho para que os aplicativos recém-adicionados apareçam automaticamente como peers que podem ser chamados.
+
+## Configuração {#setup}
+
+Três passos curtos:
+
+1. **Crie um espaço de trabalho que inclua o Dispatch.** Execute `npx @agent-native/core@latest create my-company-platform` e escolha `dispatch` junto com os modelos de domínio desejados. O Dispatch fica em `apps/dispatch` e o restante dos aplicativos fica ao lado dele. Consulte [Multi-App Workspace](/docs/multi-app-workspace).
+2. **Conectar mensagens.** Abra **Configurações → Mensagens** no Dispatch e clique em conectar para Slack, Email, Telegram ou WhatsApp. Os campos do formulário correspondem às variáveis de ambiente no documento [Messaging](/docs/messaging). Consulte-o para saber o que cada plataforma precisa.
+3. **Adicione outros aplicativos.** Execute `npx @agent-native/core@latest add-app` na raiz do espaço de trabalho para cada aplicativo de domínio. Eles aparecem automaticamente como pares A2A no `list-workspace-apps` do Dispatch — sem registro manual, sem edição de cartão de agente. O Dispatch começará a delegar a eles assim que seus cartões de agente estiverem acessíveis.
+
+Em seguida, adicione credenciais ao cofre e (opcionalmente) crie recursos de espaço de trabalho global em **Recursos**. As chaves do cofre ainda podem ser sincronizadas ou concedidas dependendo do modo de acesso; Os recursos do espaço de trabalho de todos os aplicativos são herdados automaticamente. Se você precisar de isolamento secreto por aplicativo, altere a configuração de acesso ao cofre para manual antes de conceder aplicativos individuais.
+
+## Veja também {#see-also}
+
+- [Dispatch template](/docs/template-dispatch) — o verdadeiro aplicativo scaffoldado, com seu catálogo completo de ações e guia do agente
+- [Messaging](/docs/messaging) — conectando Slack, e-mail, Telegram, WhatsApp
+- [A2A Protocol](/docs/a2a-protocol) — como funciona a delegação entre aplicativos
+- [Multi-App Workspace](/docs/multi-app-workspace) — o formato de implantação para o qual o Dispatch foi criado
+- [Workspace Governance](/docs/workspace-management) — governança git/GitHub que combina com a governança de tempo de execução do Dispatch

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

@@ -0,0 +1,260 @@
+---
+title: "Agente de visita"
+description: "Monte o chat do agente + espaço de trabalho em qualquer aplicativo React com <AgentPanel>, <AgentSidebar> e sendToAgentChat()."
+---
+
+# Agente de visita
+
+> **Página do desenvolvedor.** Esta página é para desenvolvedores que incorporam o agente em um aplicativo React. Para conhecer a experiência do usuário final ao trabalhar com o agente, consulte [Using Your Agent](/docs/using-your-agent).
+
+Você não precisa criar um agente nativo do zero. O bate-papo do agente, a guia do espaço de trabalho, o terminal CLI, a entrada de voz e toda a infraestrutura relacionada são fornecidos como um punhado de componentes React que você coloca em qualquer aplicativo.
+
+> **Pré-requisito:** o servidor deve estar executando o `agent-chat-plugin` (ele é montado automaticamente em cada modelo). Se você está começando do zero, consulte [Server](/docs/server).
+>
+> Precisa do mapa público API em vez de um tutorial? Consulte [Component API](/docs/components).
+
+## Resumo dos componentes {#components}
+
+| Componente            | O que é                                                                                                    | Use quando                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `<AgentSidebar>`      | Envolve o layout do seu aplicativo raiz e adiciona um painel lateral alternável contendo o agente completo | Você deseja que o agente esteja disponível junto com seu aplicativo em todas as telas |
+| `<AgentToggleButton>` | Abre/fecha `<AgentSidebar>` (coloque no seu cabeçalho)                                                     | Parear com `<AgentSidebar>`                                                           |
+| `<AgentPanel>`        | O próprio painel bruto — chat + CLI + guias da área de trabalho                                            | Você deseja controle total sobre o layout ou uma página de agente dedicada            |
+| `<AgentChatSurface>`  | Uma superfície de chat de painel/página pré-instalada                                                      | Você quer conversar sem o wrapper da barra lateral                                    |
+| `<AssistantChat>`     | Renderizador de bate-papo de nível inferior com ganchos de compositor/histórico                            | Você precisa de um cromo personalizado em torno da conversa padrão UI                 |
+| `sendToAgentChat()`   | Enviar programaticamente uma mensagem para o chat                                                          | Um botão que entrega o trabalho ao agente em vez de executar inline                   |
+| `useActionMutation()` | Wrapper de front-end Typesafe em torno de uma ação                                                         | O UI precisa executar a mesma operação que uma ferramenta de agente executaria        |
+
+Todos eles são exportados de `@agent-native/core/client`.
+
+```an-diagram title="The mount model" summary="<AgentSidebar> wraps your existing layout. Your routes render in the main area; the agent panel mounts beside them. <AgentPanel> is the same panel without the wrapper."
+{
+  "html": "<div class=\"diagram-mount\"><div class=\"diagram-box sidebar\" data-rough><span class=\"diagram-pill accent\">&lt;AgentSidebar&gt;</span><div class=\"inner\"><div class=\"diagram-node main\">Your app<br><small class=\"diagram-muted\">children: header + &lt;Outlet/&gt;</small></div><div class=\"diagram-node panel\">Agent panel<br><small class=\"diagram-muted\">chat &middot; CLI &middot; workspace</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card alt\"><span class=\"diagram-pill\">&lt;AgentPanel&gt;</span><small class=\"diagram-muted\">same panel, no wrapper &mdash; you own the layout</small></div></div>",
+  "css": ".diagram-mount{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-mount .sidebar{display:flex;flex-direction:column;gap:8px;padding:14px}.diagram-mount .inner{display:flex;gap:10px}.diagram-mount .main{flex:2}.diagram-mount .panel{flex:1}.diagram-mount .alt{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-mount .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## O caso 80%: `<AgentSidebar>` {#sidebar}
+
+A configuração mais comum é uma barra lateral que abre à direita em qualquer tela.
+Envolva seu layout raiz existente com `<AgentSidebar>`; seja lá o que você passar
+as crianças ficam na área principal do aplicativo. O chat do agente é o painel lateral.
+
+```an-annotated-code title="Wrapping the root layout with <AgentSidebar>"
+{
+  "filename": "app/root.tsx",
+  "language": "tsx",
+  "code": "import { Outlet } from \"react-router\";\nimport { AgentSidebar, AgentToggleButton } from \"@agent-native/core/client\";\n\nexport default function Root() {\n  return (\n    <AgentSidebar\n      emptyStateText=\"How can I help?\"\n      suggestions={[\n        \"Summarize my inbox\",\n        \"Draft a reply to the latest email\",\n        \"Show me yesterday's signup numbers\",\n      ]}\n      dynamicSuggestions\n      defaultSidebarWidth={420}\n      position=\"right\"\n    >\n      <header>\n        <AgentToggleButton />\n      </header>\n\n      <main>\n        <Outlet />\n      </main>\n    </AgentSidebar>\n  );\n}",
+  "annotations": [
+    { "lines": "6", "label": "Wrapper", "note": "`<AgentSidebar>` wraps your whole layout. It adds the toggleable side panel; everything you pass as children stays in the main app area." },
+    { "lines": "8-12", "label": "Starter prompts", "note": "`suggestions` render as clickable chips on the empty chat." },
+    { "lines": "13", "label": "Context-aware chips", "note": "`dynamicSuggestions` merges screen-aware prompts (e.g. \"Summarize this selection\") with your static ones. On by default." },
+    { "lines": "18-20", "label": "Toggle button", "note": "Put `<AgentToggleButton />` anywhere in your header to open and close the panel." },
+    { "lines": "22-24", "label": "Your app", "note": "`<Outlet/>` (your routes) renders in the main area, untouched." }
+  ]
+}
+```
+
+É isso. O usuário agora tem um agente alternável em cada página – com histórico de bate-papo, guia da área de trabalho, terminal CLI, entrada de voz e modo de tela cheia. O estado persiste durante as recargas via `localStorage`.
+
+### Acessórios
+
+- **`children`** — layout e rotas normais do seu aplicativo. Renderizado na área principal; o painel do agente é montado ao lado dele no desktop e acima dele no celular/tela cheia.
+- **`emptyStateText`** — saudação mostrada quando o chat não tem mensagens. Padrão: `"How can I help you?"`.
+- **`suggestions`** — prompts iniciais renderizados como chips clicáveis quando vazios.
+- **`dynamicSuggestions`** — chips de prompt com reconhecimento de contexto mesclados com `suggestions`. Habilitado por padrão; passe `false` para mostrar apenas sugestões estáticas ou `{ max, includeStatic, getSuggestions }` para personalizar.
+- **`defaultSidebarWidth`** — largura inicial do pixel (somente montagem; redimensionamento do usuário e substituição do valor salvo). Padrão: `380`.
+- **`position`** — `"left"` ou `"right"`. Padrão: `"right"`.
+- **`defaultOpen`** — se a barra lateral começa aberta (somente desktop). Padrão: `false`.
+
+## Os outros 20%: `<AgentPanel>` {#panel}
+
+Quando você precisar de controle total sobre o layout — uma rota `/chat` dedicada, um painel incorporado em uma coluna lateral que você gerencia ou um pop-up — renderize `<AgentPanel>` diretamente:
+
+```tsx
+// app/routes/agent.tsx
+import { AgentPanel } from "@agent-native/core/client";
+
+export default function AgentRoute() {
+  return (
+    <div className="h-screen">
+      <AgentPanel defaultMode="chat" className="h-full" />
+    </div>
+  );
+}
+```
+
+`<AgentPanel>` fornece as guias brutas (Chat / CLI / Workspace) sem o wrapper da barra lateral, o botão de recolhimento ou qualquer persistência de estado. Coloque onde quiser; você cuida do layout.
+
+### Adereços selecionados
+
+- **`defaultMode`** — `"chat"` ou `"cli"`. Padrão: `"chat"`.
+- **`className`** — Classe CSS para o contêiner externo.
+- **`onCollapse`** — se fornecido, um botão de recolhimento aparece no cabeçalho.
+- **`isFullscreen`** / **`onToggleFullscreen`** — conecte o estado de tela cheia externa se desejar uma coluna centralizada no estilo Claude.
+- **`storageKey`** — namespace para chaves `localStorage`. Útil quando você renderiza vários painéis (diferentes instâncias de aplicativos ou espaços de trabalho) na mesma página.
+
+Acessórios completos: `AgentPanelProps` em `@agent-native/core/client`.
+
+## Mensagens programáticas: `sendToAgentChat()` {#send}
+
+Um botão que transfere o trabalho para o agente (em vez de executar uma chamada `llm()` em linha — o antipadrão do [ladder](/docs/what-is-agent-native#the-ladder)):
+
+```tsx
+import { sendToAgentChat } from "@agent-native/core/client";
+
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Generate a chart showing signups by source",
+      context: `Dashboard ID: ${dashboardId}, date range: last 30 days`,
+      submit: true,
+    })
+  }
+>
+  Generate chart
+</Button>;
+```
+
+### Opções
+
+- **`message`** — o prompt visível mostrado no bate-papo.
+- **`context`** — contexto oculto anexado ao prompt (texto selecionado, posição do cursor, ID da entidade atual — qualquer coisa que o agente deva saber, mas o usuário não deve ver duas vezes).
+- **`submit`** — `true` para execução automática, `false` para pré-preenchimento, mas espere. Omita o uso do padrão do projeto.
+- **`newTab`** — crie uma conversa de bate-papo separada para este prompt.
+- **`background`** — com `newTab`, execute sem focar o novo thread. A execução oculta é rastreada em `RunsTray`.
+- **`openSidebar`** — definido como `false` para envios em segundo plano/silenciosos. O padrão abre a barra lateral para que o usuário veja a resposta.
+- **`type`** — `"content"` (padrão) mantém o trabalho no agente de aplicativo integrado. `"code"` é roteado para o quadro de edição de código (para alterações de código escritas pelo agente, consulte [Frames](/docs/frames)).
+
+`sendToAgentChat` retorna um `tabId` estável que você pode usar para monitorar a execução do chat.
+
+Para trabalho silencioso, emparelhe `newTab`, `background` e `openSidebar: false`:
+
+```ts
+sendToAgentChat({
+  message: "Summarize the selected thread and save the summary",
+  context: `Thread id: ${threadId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+Este ainda é um agente completo executado com ferramentas, actions, estado do thread e execução
+rastreamento. Ele simplesmente não rouba o foco do estado atual da barra lateral do usuário.
+
+Quando a mesma rota é incorporada como um aplicativo MCP, enviado
+As chamadas `sendToAgentChat()` são encaminhadas para o chat do host quando houver suporte; veja
+[Client](/docs/client#sendtoagentchat) para o comportamento da ponte do aplicativo MCP.
+
+Se você deseja um estado de carregamento, use o gancho `useSendToAgentChat()` — ele retorna `send` e `isGenerating`:
+
+```ts
+import { useSendToAgentChat } from "@agent-native/core/client";
+
+const { send, isGenerating } = useSendToAgentChat();
+```
+
+## Quando a barra lateral de estoque não é adequada {#custom-chat-ui}
+
+`<AgentSidebar>` e `<AgentPanel>` cobrem a maioria dos aplicativos. Quando você precisa possuir o
+layout em torno do agente ou você deseja potencializar a conversa com um agente
+você construiu em outro lugar, desça uma camada — mas continue deixando a estrutura possuir a
+tempo de execução, actions e estado apoiado por SQL:
+
+- **Adquira o Chrome em torno do tempo de execução padrão.** Use `<AgentChatSurface>` para
+  uma rota de chat dedicada, ou `<AssistantChat>` quando você quiser cabeçalhos personalizados,
+  guias e estados vazios em torno da conversa padrão. O mapa de camadas completo —
+  cada componente, gancho, compositor e adaptador, com caminhos de importação — reside em
+  [Component API](/docs/components#agent-chat-ui).
+- **Traga seu próprio tempo de execução de agente.** Se um agente que você criou em outro lugar deveria
+  dinamize a conversa enquanto Agent-Native mantém o compositor, a transcrição e a ferramenta
+  cartões, aprovações e widgets nativos, passe um `AgentChatRuntime` para
+  `<AssistantChat runtime={...} />`. Os conectores
+  (`createHttpAgentChatRuntime()` e OpenAI / Claude / Vercel AI / AG-UI
+  ajudantes) e o contrato do evento estão documentados em
+  [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+Qualquer camada que você escolher, mantenha o estado do aplicativo com suporte actions e SQL como contrato,
+e evite postar diretamente em `/_agent-native/agent-chat` do produto UI. Se um
+o auxiliar nomeado está faltando para uma superfície personalizada real, adicione esse auxiliar primeiro, então
+o código do cliente não aprende um segundo transporte ad hoc.
+
+## Typesafe actions do UI: `useActionMutation()` {#use-action-mutation}
+
+Quando o UI precisar executar a mesma operação que uma ferramenta de agente executaria — linha 3 do [ladder](/docs/what-is-agent-native#rung-three) — use `useActionMutation`:
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("reply-to-email");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+Argumentos de tipo seguro vêm do esquema zod em seu `defineAction()`. Consulte [Actions](/docs/actions) para o sistema de ação completo.
+
+```an-callout
+{
+  "tone": "decision",
+  "body": "**`useActionMutation` vs `sendToAgentChat`.** Run the operation directly with `useActionMutation` when the user clicked a deterministic button (\"Send reply\"). Hand it to `sendToAgentChat` when the work needs the agent's reasoning, tools, or multi-step planning. Never call an inline `llm()` from UI — that is rung 1 of the [ladder](/docs/what-is-agent-native#the-ladder)."
+}
+```
+
+## Seleção + reconhecimento do cursor {#selection}
+
+O agente pode ver o que o usuário selecionou — texto, células, slides, contatos — por meio das teclas `navigation` e `selection` no estado do aplicativo. O chat vazio também utiliza essas teclas para oferecer sugestões dinâmicas como “Resumir esta seleção” ou “Melhorar este slide” quando a tela atual as torna relevantes. Se desejar que Cmd-I (ou similar) envie um intervalo selecionado para o chat como contexto, consulte [Context Awareness](/docs/context-awareness).
+
+## Juntando tudo {#putting-it-together}
+
+Uma configuração típica de drop-in:
+
+```tsx
+// app/root.tsx
+import {
+  AgentSidebar,
+  AgentToggleButton,
+  sendToAgentChat,
+} from "@agent-native/core/client";
+
+export default function Root() {
+  return (
+    <AgentSidebar suggestions={["Draft a reply", "Summarize selection"]}>
+      <Header>
+        <AgentToggleButton />
+      </Header>
+
+      <Main>
+        <YourRoutes />
+      </Main>
+    </AgentSidebar>
+  );
+}
+```
+
+```tsx
+// Anywhere else in the app
+<Button
+  onClick={() =>
+    sendToAgentChat({
+      message: "Summarize this thread",
+      context: `Thread id: ${threadId}`,
+      submit: true,
+    })
+  }
+>
+  Summarize
+</Button>
+```
+
+O usuário vê um botão de bate-papo no cabeçalho, pode abri-lo e falar com o agente. Seus botões funcionam manualmente para o mesmo agente, em vez de executar chamadas LLM únicas.
+
+## O que vem a seguir
+
+- [**Actions**](/docs/actions) — `defineAction()` e `useActionMutation()`
+- [**Context Awareness**](/docs/context-awareness) — seleção, navegação, tela de visualização
+- [**Workspace**](/docs/workspace) — o que a guia Espaço de trabalho contém (skills, memória, servidores MCP, trabalhos agendados)
+- [**Voice Input**](/docs/voice-input) — o microfone no compositor de bate-papo

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

@@ -0,0 +1,65 @@
+---
+title: "Currículo Durável"
+description: "Quando a execução de um agente hospedado é interrompida e reiniciada, as chamadas de ferramenta de efeito colateral concluídas não são executadas novamente. Um diário de chamadas de ferramenta derivado do livro-razão durável bloqueia envios, cobranças e tickets duplicados."
+---
+
+# Currículo Durável
+
+> **A quem se destina:** qualquer pessoa que queira entender como o framework funciona
+> evita efeitos colaterais duplicados. Este é um comportamento integrado — existe
+> nada para conectar.
+
+As execuções do agente hospedado são interrompidas: uma função sem servidor atinge seu tempo limite máximo no meio do fluxo, um gateway interrompe a conexão aos 45s, um soquete desliga, a plataforma inicia a frio. A estrutura já se recupera salvando o prefixo da conversa e executando novamente a chamada LLM ("continuar de onde você parou"). Mas a recuperação por si só tem uma vantagem: se a tentativa interrompida **já enviou um e-mail ou criou um ticket**, um currículo ingênuo poderia fazê-lo novamente.
+
+Um currículo durável preenche essa lacuna. Resumindo, a estrutura sabe quais chamadas de ferramentas de efeitos colaterais já foram concluídas e se recusa a executá-las novamente – em duas camadas.
+
+```an-diagram title="Two layers block duplicate side effects on resume" summary="The journal reads the durable ledger and classifies prior calls; layer 1 tells the model, layer 2 hard-blocks a re-dispatched write that matches a completed entry."
+{
+  "html": "<div class=\"diagram-durable\"><div class=\"diagram-box\" data-rough>Run-event ledger<br><small class=\"diagram-muted\">tool_start / tool_done</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Tool-call journal</strong><small class=\"diagram-ok\">completed = start+done</small><small class=\"diagram-warn\">interrupted = start, no done</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">Layer 1 · prompt note &rarr; model</div><div class=\"diagram-pill accent\">Layer 2 · hard-block re-dispatched write</div></div></div>",
+  "css": ".diagram-durable{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-durable .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-durable .diagram-arrow{font-size:22px;line-height:1}.diagram-durable .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## O diário de chamadas de ferramenta {#journal}
+
+O diário é uma **leitura pura do registro durável de eventos de execução** — não há nenhum novo gancho de gravação no caminho ativo. Classifica as chamadas de ferramenta já gravadas para o turno atual:
+
+- **Concluído** — um `tool_start` com um `tool_done` correspondente. A ligação foi executada, seu efeito colateral aconteceu e seu resultado foi registrado. **Não execute novamente.**
+- **Interrompido** — um `tool_start` sem **nenhuma** correspondência com `tool_done`. A ligação começou, seu efeito colateral pode ou não ter surgido e a interrupção comeu o resultado. Resultado desconhecido.
+
+A correspondência reflete como curvas duráveis são reconstruídas em outro lugar: um `tool_done` emparelha com o `tool_start` mais antigo ainda aberto para o mesmo nome de ferramenta (FIFO por ferramenta). Um evento `clear` (saída parcial descartada) redefine a contagem por turno para que parciais abandonados não deixem chamadas abertas fantasmas.
+
+## Camada 1: nota de diário em nível de prompt {#prompt-note}
+
+Quando uma execução é retomada (tempo limite de software, tempo limite de gateway ou qualquer erro de transporte recuperável), a estrutura anexa uma **nota de diário estruturada** ao prompt de continuação, logo após o empurrão "continuar de onde você parou". A nota informa ao modelo, em texto simples:
+
+- quais chamadas de ferramenta **já concluídas** (com resultados curtos), então ela as reutiliza e **não** as executa novamente, e
+- quais chamadas de ferramenta foram **interrompidas com resultado desconhecido** para que ele verifique o estado antes de assumir sucesso ou falha.
+
+Quando o diário está vazio (um turno sem atividade de ferramenta ou uma continuação limpa), nada extra é acrescentado e o comportamento de retomada é, byte por byte, o que era antes. A observação é o melhor esforço: uma leitura do razão com falha nunca bloqueia uma recuperação que de outra forma seria bem-sucedida.
+
+## Camada 2: bloco rígido da camada de ferramenta {#hard-block}
+
+A nota de alerta é um aviso – um modelo bem comportado acata, mas um modelo não é uma garantia. Portanto, o loop também aplica isso na camada de ferramenta.
+
+Antes que o loop seja executado em um bloco retomado, ele captura o diário uma vez (capturando apenas blocos **anteriores** dessa curva lógica). Quando o modelo reenvia uma ferramenta de **gravação** cujo nome da ferramenta **e entrada** correspondem a uma entrada de diário concluída, o loop entra em curto-circuito: ele retorna o resultado registrado no diário em vez de executar a ação, com uma observação de que a chamada já foi concluída em uma tentativa interrompida anteriormente e não foi executada novamente para evitar um efeito colateral duplicado.
+
+Principais propriedades:
+
+- **Somente ferramentas de gravação.** Somente leitura (`readOnly` / GET) actions nunca são bloqueados — a releitura é segura e idempotente.
+- **Content-addressed.** A correspondência está no nome da ferramenta + assinatura de entrada, portanto, uma chamada retomada em uma posição diferente no turno ainda corresponde; uma chamada _diferente_ (argumentos diferentes) é tratada como nova e executada normalmente.
+- **Consumir uma vez.** Cada entrada concluída é reivindicada quando correspondida, de modo que duas novas chamadas idênticas e genuinamente distintas no mesmo turno não entrem em curto-circuito em uma conclusão registrada no diário.
+- **Novas chamadas intocadas.** Uma chamada de primeira vez vê um diário vazio; nada muda para execuções normais.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "Together the two layers mean an interrupted run that already had a real side effect resumes **without repeating it** — no duplicate emails, charges, or tickets — while genuinely new work still runs. Read-only actions are never blocked; re-reading is always safe."
+}
+```
+
+## Relacionado
+
+- [**Real-Time Sync**](/docs/real-time-collaboration) — como o registro de execução durável é transmitido para o cliente e reproduzido na reconexão.
+- [**Actions**](/docs/actions) — `readOnly` marca a leitura como segura para reexecução; todo o resto é tratado como efeito colateral.
+- [**In-Loop Processors**](/docs/processors) — outra costura de endurecimento interna em loop.