@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,142 @@
+---
+title: "Trabalhos recorrentes"
+description: "Avisos agendados em Cron que o agente executa por conta própria — resumos diários, relatórios semanais, pesquisas de hora em hora."
+---
+
+# Trabalhos recorrentes
+
+Um **trabalho recorrente** é um prompt executado em uma programação cron. É assim que o agente faz as coisas por conta própria: “todas as manhãs às 7h, resume meus e-mails noturnos”, “todas as segundas-feiras posto os números de inscrição da semana passada para Slack”, “a cada hora verifica se há rascunhos obsoletos e os exclui”.
+
+Os trabalhos recorrentes são acionados em um relógio. Para reagir a _eventos_ (uma reserva criada, um e-mail recebido) — mesmo formato de arquivo `jobs/` mais condições — consulte [Automations](/docs/automations).
+
+Os trabalhos ficam no [workspace](/docs/workspace) em `jobs/<name>.md` — apenas um arquivo Markdown com frontmatter YAML. Sem registro, sem fiação. Solte o arquivo e a estrutura o pegará.
+
+## Um arquivo de trabalho {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+É isso. O corpo é um prompt que o agente executa em cada disparo agendado. O agente tem acesso a todas as mesmas ferramentas e contexto de espaço de trabalho que possui em um chat interativo: actions, skills, memória, servidores MCP conectados, subagentes.
+
+## Princípio {#frontmatter}
+
+| Campo        | Tipo                          | Padrão          | Descrição                                                                                                                          |
+| ------------ | ----------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `schedule`   | expressão cron                | _(obrigatório)_ | Cron padrão de 5 campos. `"0 7 * * *"` = todos os dias às 07h00; `"0 */4 * * *"` = a cada 4 horas.                                 |
+| `enabled`    | booleano                      | `true`          | Mude para `false` para pausar sem excluir o trabalho.                                                                              |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`     | `"creator"` é executado com a identidade do proprietário do trabalho e `ANTHROPIC_API_KEY`. `"shared"` usa a chave da organização. |
+| `createdBy`  | e-mail                        | _(automático)_  | Preenchido quando o trabalho é criado por meio do espaço de trabalho UI ou pelo agente.                                            |
+| `orgId`      | string                        | _(automático)_  | Escopo da organização; herdado da organização ativa do criador.                                                                    |
+| `lastRun`    | Carimbo de data e hora ISO    | _(gerenciado)_  | Escrito pelo agendador após cada execução.                                                                                         |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(gerenciado)_  | Resultado mais recente.                                                                                                            |
+| `lastError`  | string                        | _(gerenciado)_  | Mensagem de erro se a última execução falhou.                                                                                      |
+| `nextRun`    | Carimbo de data e hora ISO    | _(gerenciado)_  | Calculado a partir de `schedule`; usado pelo agendador para decidir quando disparar em seguida.                                    |
+
+Os campos `last*` e `nextRun` são gravados pelo agendador. Você pode lê-los para ver o histórico, mas não os edite manualmente: a próxima execução será substituída.
+
+## Sintaxe do Cron {#cron}
+
+Cron padrão de 5 campos (minuto, hora, dia do mês, mês, dia da semana):
+
+| Cron           | Significado                 |
+| -------------- | --------------------------- |
+| `*/5 * * * *`  | A cada 5 minutos            |
+| `0 * * * *`    | De hora em hora             |
+| `0 */4 * * *`  | A cada 4 horas              |
+| `0 7 * * *`    | Todos os dias às 07:00      |
+| `0 9 * * 1`    | Toda segunda-feira às 09:00 |
+| `0 17 * * 1-5` | Dias úteis às 17h           |
+| `0 0 1 * *`    | Primeiro dia de cada mês    |
+
+A estrutura inclui utilitários cron (`isValidCron()` e `describeCron()`) para validar e renderizar strings cron, usados internamente pelas camadas de recurso e agendador.
+
+## Criando um trabalho {#creating}
+
+### Na guia Espaço de trabalho
+
+`+` → **Tarefa agendada** no painel da área de trabalho. Preencha o prompt e agende. Salva como `jobs/<slug>.md` e começa a ser executado no próximo tick correspondente.
+
+### Perguntando ao agente
+
+> "Crie uma tarefa agendada que resuma meus e-mails não lidos todas as manhãs às 7."
+
+O agente grava o arquivo para você.
+
+### Manualmente
+
+Solte um arquivo Markdown em `jobs/` por meio do recurso APIs da estrutura:
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## Como o agendador é executado {#how-scheduler-runs}
+
+O agendador é um plugin de estrutura (a rotina interna `processRecurringJobs()`) que é executado no processo: um `setInterval` é acionado a cada 60 segundos (com um atraso de inicialização de 10 segundos) dentro do plugin de chat do agente, onde quer que o servidor esteja em execução.
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## Depurando um trabalho {#debugging}
+
+- Abra `jobs/<name>.md` na área de trabalho — o frontmatter mostra `lastRun`, `lastStatus`, `lastError`, `nextRun`.
+- **Teste sem esperar:** não há ferramenta de disparo forçado. Para exercer o mesmo trabalho sob demanda, cole o prompt do trabalho no chat do agente e deixe-o ser executado lá ou defina temporariamente o agendamento para o próximo minuto para que o agendador o pegue no próximo tick (depois restaure o cron real).
+- **Pause:** vire `enabled: false`. O arquivo permanece no mesmo lugar, apenas para de ser executado.
+
+## Ferramenta de agente {#agent-tool}
+
+Uma única ferramenta `manage-jobs` é registrada em cada modelo. O parâmetro `action` seleciona a operação:
+
+| Ação     | Parâmetros                                                           | Propósito                                                                        |
+| -------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `create` | `name`, `schedule`, `instructions` (obrigatório); `scope`, `runAs`   | Crie um novo trabalho recorrente                                                 |
+| `list`   | `scope` (`personal`, `shared` ou todos)                              | Liste todos os trabalhos com status (agendado, ativado, última/próxima execução) |
+| `update` | `name` (obrigatório); `schedule`, `instructions`, `enabled`, `runAs` | Editar um trabalho existente                                                     |
+| `delete` | `name` (obrigatório)                                                 | Exclua um trabalho — sempre confirme primeiro com o usuário                      |
+
+**Escopo pessoal versus escopo compartilhado.** Cada trabalho reside no escopo pessoal (é executado como e é visível apenas para o criador) ou no escopo compartilhado/organizacional (é executado em nome do criador, mas é visível para os membros da organização). Os parâmetros `scope` e `runAs` controlam isso no momento da criação. Os administradores da organização podem atualizar ou excluir qualquer trabalho compartilhado; membros não administradores só podem gerenciar os seus próprios.
+
+## Diferente do pacote de agendamento {#vs-scheduling-package}
+
+Não confunda trabalhos recorrentes com `@agent-native/scheduling`:
+
+- **Trabalhos recorrentes (esta página)** — _prompts_ agendados em cron que o agente executa em segundo plano. Nível de estrutura. Mora no espaço de trabalho. Funciona em qualquer aplicativo nativo do agente.
+- **`@agent-native/scheduling`** — um pacote de domínio reutilizável para criar recursos de calendário/reserva (tipos de eventos, janelas de disponibilidade, reservas). Ativa o modelo `calendar` e superfícies de agendamento personalizadas.
+
+Trabalhos recorrentes são "como faço para o agente agir por conta própria?" O pacote de agendamento é "como faço para construir um aplicativo de calendário?" Preocupações diferentes.
+
+## O que vem a seguir
+
+- [**Automations**](/docs/automations) — adicione gatilhos de eventos e condições ao mesmo formato `jobs/`
+- [**Workspace**](/docs/workspace) — onde os trabalhos ficam junto com skills, memória e agentes personalizados
+- [**Actions**](/docs/actions) — as ferramentas que um trabalho exige
+- [**Agent Teams**](/docs/agent-teams) — jobs geralmente geram subagentes para fazer trabalho paralelo

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

@@ -0,0 +1,79 @@
+---
+title: "Roteamento"
+description: "Roteamento baseado em arquivo para aplicativos nativos de agente com React Router v7 — páginas, parâmetros dinâmicos e navegação."
+---
+
+# Roteamento
+
+Os aplicativos nativos do agente usam o **React Router v7** com roteamento baseado em arquivo via `flatRoutes()` de `@react-router/fs-routes`. Cada arquivo em `app/routes/` se torna um URL. Os modelos usam a convenção de notação de ponto: os pontos separam os segmentos URL dentro de um único nome de arquivo.
+
+## Roteamento baseado em arquivo {#file-based-routing}
+
+### Arquivo → Mapeamento URL
+
+| Arquivo               | URL                | Notas                                        |
+| --------------------- | ------------------ | -------------------------------------------- |
+| `_index.tsx`          | `/`                | Rota de índice                               |
+| `settings.tsx`        | `/settings`        | Página simples                               |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | Ponto = `/`, `$` = parâmetro dinâmico        |
+| `_app.tsx`            | (sem segmento URL) | Layout sem caminho — prefixo com `_`         |
+| `inbox/route.tsx`     | `/inbox`           | Formulário de pasta — `route.tsx` é o índice |
+
+Prefixe um segmento com `$` para um parâmetro dinâmico. Prefixe com `_` para torná-la uma rota de layout sem caminho (sem segmento URL). Os modelos usam `flatRoutes()` — o arquivo de notação de ponto acima é o principal; o formato de pasta aninhada `inbox/route.tsx` também funciona.
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## Adicionando uma nova página {#adding-a-page}
+
+Crie o arquivo e exporte um componente padrão:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+É isso aí - o roteador React coleta automaticamente, sem necessidade de registro.
+
+## Parâmetros dinâmicos {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## Navegação {#navigation}
+
+Use `<Link>` para navegação no lado do cliente e `useNavigate()` para navegação programática:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## O que vem a seguir
+
+- [**Client**](/docs/client) — os ganchos e utilitários do navegador nativos do agente
+- [**Server**](/docs/server) — rotas de servidor baseadas em arquivo e o namespace `/_agent-native/`

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

@@ -0,0 +1,227 @@
+---
+title: "Adaptadores"
+description: "As duas juntas de adaptadores da estrutura: os adaptadores sandbox trocam o back-end que executa a ferramenta de código de execução do agente e os adaptadores CLI fornecem ao agente acesso estruturado às ferramentas de linha de comando."
+search: "adaptadores adaptador sandbox adaptador cli run-code SandboxAdapter CliAdapter ShellCliAdapter durável runner remoto sandbox edge serverless child_process"
+---
+
+# Adaptadores
+
+> **Para quem se destina:** autores de host que estendem o tempo de execução. Desenvolvedores de aplicativos raramente
+> precisa disso — os padrões funcionam imediatamente.
+
+Agent-Native tem duas costuras de adaptador que eliminam a preocupação por trás de um estreito,
+interface trocável:
+
+- **Adaptadores sandbox** trocam o back-end que executa a ferramenta `run-code` do agente —
+  um processo filho local por padrão ou um executor Docker/remoto/durável.
+- **Adaptadores CLI** fornecem ao agente acesso estruturado a ferramentas de linha de comando
+  (`gh`, `ffmpeg`, `stripe`) com descoberta, verificações de disponibilidade e um
+  formato de resultado consistente.
+
+Ambos compartilham uma restrição de tempo de execução: eles dependem de ligações do sistema Node.js e fazem
+não é executado em tempos de execução de borda/trabalho — consulte [Edge and serverless](#edge-serverless).
+
+## Qual documento de codificação eu quero? {#which-doc}
+
+| Você quer…                                                                               | Usar                                         |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Troque o back-end que executa a **ferramenta `run-code`** do agente                      | **Adaptadores sandbox** (esta página)        |
+| Prepare uma ferramenta CLI (`gh`, `ffmpeg`) para o agente ligar                          | **Adaptadores CLI** (esta página)            |
+| Renderizar um espaço de trabalho de codificação estilo Claude/Codex **UI**               | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Execute o código Claude / Codex / Pi **como agente**, com seu próprio loop + ferramentas | [Harness Agents](/docs/harness-agents)       |
+
+# Adaptadores de sandbox
+
+A ferramenta `run-code` executa o JavaScript fornecido pelo agente em um ambiente isolado. **Adaptadores sandbox** eliminam a preocupação de _execução_ dessa ferramenta para que o back-end possa ser trocado (um processo filho local por padrão ou um Docker/executor remoto/durável) sem tocar no loop do agente, `run-code.ts`, a ponte localhost, o env scrub ou a formatação de saída.
+
+## Por que uma costura {#why}
+
+O back-end padrão gera um processo filho do Node local bloqueado. Isso é limitado pelo processo de hospedagem: na plataforma hospedada, ele compartilha o teto de execução suave do loop do agente (~40s antes do tempo limite/thrash de continuação). Um adaptador remoto ou durável é a alavanca para ultrapassar esse limite: ele executa grandes trabalhos de dados até a conclusão, independentemente do ciclo de vida da solicitação.
+
+Manter o contrato restrito significa que um adaptador remoto herda a mesma postura de segurança. O processo pai mantém a propriedade de tudo que contém segredo: ele cria o módulo sandbox, executa a ponte localhost (que mantém o contexto da solicitação e aplica listas de permissões de host + proteções SSRF), limpa o env e formata a saída. Um adaptador recebe apenas uma fonte de módulo **não secreta** já preparada, além de limites de recursos — ele é responsável exclusivamente por _executá-lo_ e capturar o status stdout/stderr/exit.
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## A interface {#interface}
+
+A costura reside no núcleo em `packages/core/src/coding-tools/sandbox/` — `adapter.ts` (o contrato), `index.ts` (seleção: `getSandboxAdapter()` / `registerSandboxAdapter()`) e `local-child-process-adapter.ts` (o padrão). Ele é conectado no pacote por `run-code.ts`; um host conecta um back-end diferente por meio do auxiliar de registro `index.ts` (ou, para um back-end do Docker, por meio do [blueprint](/docs/blueprint-installer) que edita esses arquivos diretamente).
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+Cada backend implementa `SandboxAdapter`:
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+A solicitação e o resultado são intencionalmente pequenos e opacos:
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## O padrão: `LocalChildProcessAdapter` {#default}
+
+Pronto para uso, `getSandboxAdapter()` retorna `LocalChildProcessAdapter` (`id: "local-child-process"`). Ele preserva o comportamento histórico do `run-code`, byte por byte:
+
+- A fonte do módulo preparado é gravada em um novo diretório temporário.
+- O filho é executado com o ambiente limpo (sem segredos), com `TMPDIR`/`TEMP`/`TMP` apontado para dentro do diretório sandbox.
+- Quando o modelo de permissão do Nó está disponível (`--permission` ou `--experimental-permission` no Nó 20), o filho tem acesso negado ao sistema de arquivos fora de seu diretório temporário, além de processos filhos, trabalhadores e complementos nativos. A rede de saída _não_ é bloqueada pelo modelo de permissão, mas a eliminação do ambiente significa que tais solicitações não carregam credenciais e todas as chamadas autenticadas passam pela ponte de loopback do pai.
+- Um tempo limite envia `SIGTERM` e, em seguida, `SIGKILL` após um período de carência de 2s.
+- Os arquivos temporários são limpos com o melhor esforço após a execução.
+
+> [!WARNING]
+> O adaptador padrão usa `node:child_process`, que não existe em tempos de execução de borda/trabalhador. Execute `run-code` em um ambiente Node.js padrão ou registre um adaptador remoto — consulte [Edge and serverless](#edge-serverless).
+
+## Selecionando um adaptador {#selection}
+
+Ordem de resolução — um adaptador registrado explicitamente vence; caso contrário, o env var seleciona um integrado; caso contrário, o padrão local será usado:
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### Var ambiente `AGENT_NATIVE_SANDBOX` {#env}
+
+Seleciona um adaptador integrado por ID. Atualmente apenas `local` (o padrão) está conectado; valores desconhecidos voltam para o local em vez de falhar na execução.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+Um processo host substitui o backend para todas as invocações `run-code` subsequentes por meio do `index.ts` da costura — por exemplo, para executar todas as chamadas em um contêiner remoto:
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## A costura para um corredor durável {#durable}
+
+Esta interface é deliberadamente a costura para uma futura sandbox remota/durável. Um adaptador remoto ou durável (Docker, um executor estilo Vercel-Sandbox ou um trabalhador em segundo plano na fila) faria:
+
+1. Implemente `SandboxAdapter.run` em um tempo de execução fora do processo.
+2. Coloque um túnel na ponte de loopback (ou chamadas da ponte proxy de volta para o pai).
+3. Permita que grandes trabalhos de dados sejam executados até a conclusão independentemente do ciclo de vida da solicitação, excedendo o limite máximo de execução de código hospedado de aproximadamente 40 anos que limita o adaptador de processo filho local.
+
+Registre-o com um novo valor `AGENT_NATIVE_SANDBOX` (por exemplo, `remote`) e/ou via `registerSandboxAdapter()`. O loop do agente e `run-code.ts` nunca mudam.
+
+> [!TIP]
+> O blueprint `agent-native add sandbox docker` emite uma receita completa e independente para implementar um adaptador Docker nessa junção. Consulte [Blueprint Installer](/docs/blueprint-installer).
+
+# Adaptadores CLI
+
+A outra junção do adaptador envolve uma única ferramenta de linha de comando (`gh`, `ffmpeg`, `stripe`, `aws`) para que o agente possa descobri-lo, verificar se está instalado e executá-lo com um resultado stdout/stderr/código de saída consistente. Cada adaptador CLI implementa `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+Para a maioria dos CLIs, `ShellCliAdapter` agrupa qualquer binário com padrões razoáveis ​​e `CliRegistry` coleta adaptadores para descoberta em tempo de execução:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+Envolva uma chamada CLI em `defineAction` para expô-la na superfície de ação. Consulte a referência rápida do [CLI Adapters](/docs/cli-adapters) para opções do `ShellCliAdapter`, adaptadores personalizados e o padrão de encapsulamento de ação.
+
+## Edge e sem servidor {#edge-serverless}
+
+> [!WARNING]
+> Ambas as costuras do adaptador dependem de ligações do sistema Node.js. Os adaptadores sandbox `LocalChildProcessAdapter` e CLI (`ShellCliAdapter` e adaptadores personalizados) usam `node:child_process` (`execFile`/`spawn`), que **não existe** em tempos de execução de borda/trabalhador, como Cloudflare Workers ou Netlify Edge Functions. Se você implantar rotas de servidor para essas predefinições de borda, a execução desses adaptadores gerará uma exceção de tempo de execução. Execute tarefas e endpoints do adaptador em um ambiente Node.js padrão (contêineres de servidor tradicionais ou funções de Node sem servidor) ou, para a costura de sandbox, registre um adaptador remoto que envia trabalho fora do processo.
+
+## O que vem a seguir
+
+- [**CLI Adapters**](/docs/cli-adapters) — a referência rápida para a costura CLI
+- [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker` imprime uma receita do adaptador Docker
+- [**Agent Teams**](/docs/agent-teams) — delegar trabalho pesado a subagentes
+- [**Security**](/docs/security) — a postura de limpeza de ambiente e lista de permissões de ponte