@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,330 @@
+---
+title: "Segurança"
+description: "Modelo de segurança para aplicativos nativos de agente: validação de entrada, prevenção de injeção SQL, XSS, escopo de dados, gerenciamento de segredos e padrões de autenticação."
+---
+
+# Segurança
+
+Os aplicativos nativos do agente são projetados para serem seguros por padrão. A estrutura fornece proteções automáticas em várias camadas: você obtém isolamento de dados no nível SQL, consultas parametrizadas, validação de entrada e autenticação prontas para uso.
+
+## O que você ganha de graça e o que você possui {#what-you-own}
+
+```an-diagram title="Defense in layers" summary="The framework owns most of the threat surface; you own two things — tagging tables for scoping and validating external input."
+{
+  "html": "<div class=\"sec-layers\"><div class=\"diagram-card free\"><span class=\"diagram-pill ok\">Framework owns</span><small class=\"diagram-muted\">SQL isolation &middot; parameterized queries &middot; XSS escaping &middot; auth guard &middot; CSRF cookies &middot; secret encryption</small></div><div class=\"diagram-card you\"><span class=\"diagram-pill warn\">You own</span><small class=\"diagram-muted\">A. tag tables with ownableColumns() &amp; route through access guards<br>B. give every action a Zod schema &amp; send user URLs through the SSRF guard</small></div></div>",
+  "css": ".sec-layers{display:flex;flex-direction:column;gap:12px}.sec-layers .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+Quando você desenvolve os padrões padrão, a estrutura já lida com a maior parte da superfície de ameaças para você:
+
+- **Isolamento de dados** — o agente SQL foi reescrito para poder ver apenas as linhas do usuário atual (e da organização ativa). Consulte [Data Scoping](#data-scoping).
+- **Injeção SQL** — `db-query`/`db-exec` e Drizzle sempre parametrizam. Consulte [SQL Injection Prevention](#sql-injection).
+- **XSS** — React escapa automaticamente, TipTap e `react-markdown` higienizam. Consulte [XSS Prevention](#xss).
+- **Auth & CSRF** — todo `defineAction` é protegido por autenticação; os cookies são `httpOnly` + `SameSite=lax`. Consulte [Authentication](#auth).
+- **Criptografia secreta** — as credenciais e o cofre são criptografados em repouso. Consulte [Secrets Management](#secrets).
+
+Isso deixa uma pequena superfície na qual você realmente precisa pensar:
+
+- **A. Marque suas tabelas para definir o escopo.** Adicione `owner_email` (e `org_id` para dados da equipe) por meio de [`ownableColumns()`](#data-scoping) e roteie leituras/gravações de Drizzle por meio de [access guards](#access-guards).
+- **B. Valide e roteie a entrada externa.** Dê a cada ação um Zod [`schema:`](#input-validation) e envie qualquer busca do lado do servidor de um usuário/agente URL por meio do [SSRF guard](#ssrf).
+
+Acerte esses dois e o resto será o padrão. O [Production Checklist](#production-checklist) é a confirmação de uma página antes do envio.
+
+## Segurança desde o projeto {#secure-by-design}
+
+A arquitetura da estrutura evita vulnerabilidades comuns quando você usa os padrões padrão:
+
+| Vulnerabilidade      | Proteção de estrutura                                                                |
+| -------------------- | ------------------------------------------------------------------------------------ |
+| Injeção SQL          | Consultas parametrizadas em `db-query`/`db-exec` e Drizzle ORM                       |
+| XSS                  | React escapa automaticamente de JSX; TipTap limpa rich text                          |
+| Vazamento de dados   | Escopo no nível SQL por meio de visualizações temporárias (`owner_email`, `org_id`)  |
+| Ignorar autenticação | A proteção de autenticação protege automaticamente todos os endpoints `defineAction` |
+| Injeção de entrada   | Validação do esquema Zod em `defineAction`                                           |
+| CSRF                 | Biscoitos `SameSite=lax` + `httpOnly`                                                |
+| Exposição secreta    | `.env` gitignorado; credenciais e cofre criptografados em repouso (AES-256-GCM)      |
+| SSRF                 | `ssrfSafeFetch` bloqueia alvos internos/metadados + religação de redirecionamento    |
+
+## Validação de entrada {#input-validation}
+
+Use `defineAction` com um Zod `schema:` para cada ação. A estrutura valida a entrada automaticamente antes da execução do código:
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200).describe("Note title"),
+    content: z.string().optional().describe("Note body"),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — invalid input never reaches here
+  },
+});
+```
+
+Entrada inválida retorna mensagens de erro claras (400 para HTTP, erro estruturado para chamadas de agente). O formato herdado `parameters:` não fornece validação de tempo de execução.
+
+## Prevenção de injeção SQL {#sql-injection}
+
+As ferramentas `db-query` e `db-exec` da estrutura usam consultas parametrizadas. A entrada do usuário é passada como argumentos, nunca interpolada na string SQL:
+
+```ts
+// SAFE — parameterized query (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] });
+
+// SAFE — Drizzle ORM (always generates parameterized queries)
+await db.insert(notes).values({ title, ownerEmail: email });
+
+// DANGEROUS — string concatenation (never do this)
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`);
+```
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "Never build SQL by string concatenation or template literals. Pass user input as `args` to `exec` / `db-query`, or use Drizzle — both always parameterize. The `pnpm guards` checks catch unscoped and concatenated queries at CI time."
+}
+```
+
+## Prevenção XSS {#xss}
+
+React escapa automaticamente de todas as expressões JSX. Diretrizes adicionais:
+
+- Nunca use `dangerouslySetInnerHTML` com conteúdo controlado pelo usuário
+- Nunca use `innerHTML`, `eval()` ou `document.write()`
+- Para edição de rich text, use TipTap (framework dependency) — ele limpa através de seu esquema
+- Para renderizar markdown, use `react-markdown` — ele converte em elementos React com segurança
+
+## Busca no lado do servidor (SSRF) {#ssrf}
+
+Qualquer `fetch` do lado do servidor de um URL controlado por usuário ou agente deve passar pela proteção da estrutura SSRF ou pode ser apontado para metadados de nuvem (`169.254.169.254`), `localhost` ou serviços internos:
+
+```ts
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+
+const res = await ssrfSafeFetch(userProvidedUrl, {}, { maxRedirects: 3 });
+```
+
+`ssrfSafeFetch` bloqueia alvos privados/internos, verifica novamente o IP resolvido no momento da conexão (religação DNS) e revalida cada salto de redirecionamento para que um URL público não possa redirecionar para a rede privada. O proxy iframe de extensão, `upload-image`, e o importador de token de design passam por ele. Para uma verificação apenas antes do voo, use `isBlockedExtensionUrlWithDns(url)` com `redirect: "manual"`.
+
+## Escopo de dados {#data-scoping}
+
+Na produção, a estrutura restringe automaticamente as consultas do agente SQL aos dados do usuário atual. Isso é aplicado no nível SQL – os agentes não podem ignorá-lo. Esta seção é a referência canônica para o pipeline de escopo; os documentos [Authentication](/docs/authentication) e [Multi-Tenancy](/docs/multi-tenancy) têm link aqui para a mecânica.
+
+### O pipeline de escopo {#scoping-pipeline}
+
+O escopo flui da sessão autenticada até o SQL que o agente executa:
+
+```
+session.orgId → AGENT_ORG_ID → SQL row scoping
+```
+
+```an-diagram title="The scoping pipeline" summary="Agent SQL never touches base tables directly — it reads through a temporary view scoped to the current identity, so a bare table name can only return owned rows."
+{
+  "html": "<div class=\"scope-pipe\"><div class=\"diagram-node\">Signed-in session<br><small class=\"diagram-muted\">email &middot; orgId</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Request context<br><small class=\"diagram-muted\">AGENT_ORG_ID</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Temporary VIEW<br><small class=\"diagram-muted\">WHERE owner_email = ? AND org_id = ?</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Agent SQL<br><small class=\"diagram-muted\">bare table names only</small></div></div>",
+  "css": ".scope-pipe{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.scope-pipe .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.scope-pipe .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+A sessão conectada carrega `email` e (quando uma organização está ativa) `orgId`. A estrutura estabelece o contexto de solicitação dessa sessão, expõe a organização ativa ao agente SQL como `AGENT_ORG_ID` e reescreve cada consulta para que possa ver apenas as linhas que a identidade atual possui. O mesmo caminho se aplica quer a consulta venha do UI, de uma ação ou do agente — o agente não pode ler dados de uma organização da qual o usuário não é membro.
+
+### Escopo por usuário (`owner_email`)
+
+Toda tabela com dados específicos do usuário **deve** ter uma coluna de texto `owner_email`. Use o nome da propriedade camelCase Drizzle — `accessFilter` lê `resourceTable.ownerEmail`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  ownableColumns,
+} from "@agent-native/core/db/schema";
+
+// Minimal: just the owner column
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ownerEmail: text("owner_email").notNull(), // REQUIRED — camelCase property
+});
+
+// Or use ownableColumns() to add owner_email + org_id + visibility in one call
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ...ownableColumns(),
+});
+```
+
+A estrutura cria visualizações SQL temporárias que filtram consultas automaticamente:
+
+```sql
+CREATE TEMPORARY VIEW "notes" AS
+  SELECT * FROM main."notes"
+  WHERE "owner_email" = 'alice@example.com';
+```
+
+As instruções INSERT são injetadas automaticamente em `owner_email` quando a coluna ainda não está presente.
+
+As ferramentas `db-query`/`db-exec` rejeitam referências de tabela qualificadas pelo esquema (`public.<table>`, `main.<table>`) — um nome qualificado é resolvido para a tabela base e ignoraria a visualização temporária acima. Os agentes usam nomes de tabelas simples; o escopo é aplicado automaticamente.
+
+### Escopo por organização (`org_id`)
+
+Para aplicativos multiusuário em que as equipes compartilham dados, adicione uma coluna `org_id`. Quando ambas as colunas estão presentes, as consultas têm escopo definido por ambas: `WHERE owner_email = ? AND org_id = ?`.
+
+O auxiliar de esquema `ownableColumns()` adiciona `owner_email`, `org_id` e `visibility` em uma chamada, para que novas tabelas com reconhecimento de locatário obtenham o contrato de escopo completo por padrão:
+
+```ts
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  ...ownableColumns(), // adds owner_email + org_id + visibility
+});
+```
+
+```an-schema title="What ownableColumns() adds" summary="The three columns that make a table tenant-aware and shareable."
+{
+  "entities": [
+    {
+      "id": "ownable",
+      "name": "ownable resource",
+      "note": "Any table that spreads ...ownableColumns()",
+      "fields": [
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "Creator. Auto-filled by write actions; auto-injected on INSERT." },
+        { "name": "org_id", "type": "text", "nullable": true, "note": "Owner's active org at creation. Drives org-visibility checks." },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "private | org | public — coarse default, defaults to private." }
+      ]
+    }
+  ]
+}
+```
+
+### Proteções de acesso em actions {#access-guards}
+
+O agente bruto SQL tem o escopo definido pelas visualizações temporárias acima. O código de ação que consulta diretamente com Drizzle deve passar pelos auxiliares de acesso da estrutura para que as leituras e gravações permaneçam no escopo da identidade atual:
+
+- **`accessFilter`** — retorna o predicado `WHERE` que limita uma consulta às linhas que o usuário/organização atual pode ver. Use-o em consultas de lista/leitura.
+- **`resolveAccess`** — resolve o escopo de acesso efetivo (proprietário, organização, compartilhado) da solicitação atual.
+- **`assertAccess`** — protege uma gravação ou leitura de registro único, lançando se a identidade atual não atuar na linha de destino.
+
+As tabelas criadas com `ownableColumns()` exigem essas leituras e gravações com escopo definido; rotas Nitro personalizadas devem estabelecer o contexto da solicitação antes de consultar dados proprietários. A verificação `guard-no-unscoped-queries` (executada via `pnpm guards`) impõe isso no momento do CI. Veja a habilidade `sharing` para o ajudante completo API.
+
+### Validação
+
+```bash
+pnpm action db-check-scoping           # Check all tables have owner_email
+pnpm action db-check-scoping --require-org  # Also require org_id
+```
+
+## Gerenciamento de segredos {#secrets}
+
+| Tipo de segredo                                     | Onde armazenar                                                  |
+| --------------------------------------------------- | --------------------------------------------------------------- |
+| Chaves no nível da implantação (uma por aplicativo) | Arquivo `.env` (gitignored, somente no lado do servidor)        |
+| Chaves API por usuário/por organização              | `saveCredential`/`resolveCredential` (criptografado em repouso) |
+| Segredos registrados (cofre da barra lateral)       | Cofre `app_secrets` (criptografado em repouso)                  |
+| Tokens OAuth (Google, GitHub)                       | Armazenamento `oauth_tokens` via `saveOAuthTokens()`            |
+| Tokens de sessão                                    | Automático (melhor autenticação lida com isso)                  |
+
+As credenciais por usuário/por organização e o cofre são criptografados em repouso com AES-256-GCM, codificados por `SECRETS_ENCRYPTION_KEY` (retrocedendo para `BETTER_AUTH_SECRET`); a produção se recusa a começar sem ele. Para criptografar quaisquer linhas de credenciais de texto simples pré-existentes, execute `pnpm action db-migrate-encrypt-credentials` (idempotente, não destrutivo).
+
+Nunca armazene segredos em `settings`, `application_state`, código-fonte ou respostas de ação. Use as credenciais/cofre APIs acima: elas lidam com criptografia e escopo por usuário.
+
+## Autenticação {#auth}
+
+A autenticação é automática. Consulte a documentação do [Authentication](/docs/authentication) para a configuração completa.
+
+**Pontos-chave para segurança:**
+
+- Os endpoints `defineAction` são protegidos automaticamente pela proteção de autenticação
+- Rotas `/api/` personalizadas devem chamar `getSession(event)` e verificar o resultado
+- As operações de mudança de estado devem usar POST (o padrão para actions)
+- Os cookies `SameSite=lax` + `httpOnly` evitam a maioria dos ataques CSRF
+
+## Verificação de identidade A2A {#a2a-identity}
+
+Quando os aplicativos ligam entre si por meio do protocolo A2A, eles verificam a identidade usando tokens JWT assinados com um segredo compartilhado:
+
+```bash
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+1. O aplicativo A assina um JWT contendo `sub: "steve@example.com"`
+2. O aplicativo B verifica a assinatura JWT com o mesmo segredo
+3. O aplicativo B lê a declaração `sub` verificada no contexto da solicitação
+4. O escopo dos dados se aplica: o aplicativo B mostra apenas os dados de Steve
+
+Sem `A2A_SECRET` em produção, cada endpoint A2A e o endpoint de disparo automático `/_agent-native/integrations/process-task` retornam **503**. Configure-o em todos os aplicativos que chamam ou recebem tráfego A2A. (Para desenvolvimento local, a estrutura ainda permite chamadas não autenticadas.)
+
+## Entrada Webhooks {#webhooks}
+
+Os manipuladores de webhook de entrada (Resend, SendGrid, Slack, Telegram, WhatsApp, Recall.ai, Deepgram, Zoom, Google Docs Pub/Sub) recusam solicitações forjadas por padrão na produção: quando a variável de env secreta de assinatura correspondente está faltando, o manipulador retorna 401 em vez de aceitar e despachar.
+
+Anteriormente, essa era uma postura de "avisar e aceitar" - defina o segredo que de outra forma estaria faltando ou opte novamente pelo comportamento antigo com `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` apenas para desenvolvedores locais. Consulte [Messaging](/docs/messaging#env-vars) para obter as variáveis secretas de assinatura por integração.
+
+## Lista de verificação de produção {#production-checklist}
+
+### Autenticação e segredos
+
+- [ ] `BETTER_AUTH_SECRET` definido como uma string aleatória com mais de 32 caracteres (`openssl rand -hex 32`), a menos que esta seja uma implantação de espaço de trabalho hospedado derivada de `A2A_SECRET`
+- [ ] `OAUTH_STATE_SECRET` definido como uma string aleatória separada com mais de 32 caracteres (não reutilize `BETTER_AUTH_SECRET`) — consulte [OAuth State Signing](#oauth-state)
+- [ ] `A2A_SECRET` definido em cada aplicativo que chama ou recebe tráfego A2A — consulte [A2A Identity Verification](#a2a-identity)
+- [ ] conjunto `SECRETS_ENCRYPTION_KEY` (ou confie no substituto `BETTER_AUTH_SECRET`) — consulte [Secrets Management](#secrets)
+- [ ] `AUTH_SKIP_EMAIL_VERIFICATION` **não** é definido em produção (ou definido apenas em implantações de visualização de controle de qualidade)
+
+### Segredos do webhook (defina aqueles para integrações que você usa)
+
+- [ ] Conjunto de segredos de assinatura para cada integração de entrada habilitada — consulte [Inbound Webhooks](#webhooks) e [Messaging](/docs/messaging#env-vars) para obter a lista por integração
+- [ ] `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` **não** está definido no produto
+
+### Esquema
+
+- [ ] Cada tabela voltada para o usuário tem `owner_email`, tabelas multiusuário também `org_id` - consulte [Data Scoping](#data-scoping)
+- [ ] Leituras/gravações de tabelas próprias passam pelo [access guards](#access-guards)
+- [ ] Todos os actions usam `defineAction` com Zod `schema:` — veja [Input Validation](#input-validation)
+- [ ] As buscas do lado do servidor de usuários/agentes URLs passam por `ssrfSafeFetch` — consulte [SSRF](#ssrf)
+- [ ] Nenhum `dangerouslySetInnerHTML` com conteúdo do usuário (ou a saída é executada por meio do DOMPurify)
+- [ ] Nenhum SQL concatenado com string
+- [ ] `pnpm guards` está limpo (`guard-no-unscoped-queries`, `guard-no-env-credentials`, `guard-no-env-mutation`, `guard-no-localhost-fallback`, `guard-no-unscoped-credentials`, `guard-no-drizzle-push`)
+- [ ] Testado com duas contas de usuário para verificar o isolamento de dados
+
+### Endurecimento diverso
+
+- [ ] `AGENT_NATIVE_DEBUG_ERRORS` **não** é definido em produção real (somente em visualizações de depuração)
+- [ ] `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK` **não** é definido, a menos que sua organização realmente compartilhe chaves de espaço de trabalho — consulte [Cross-User Tooling Secrets](#tooling-secrets)
+- [ ] Em implantações multilocatários, **os usuários trazem seu próprio `ANTHROPIC_API_KEY`** — a estrutura se recusa a voltar para o ambiente de nível de implantação var
+
+---
+
+As seções abaixo abordam sinalizadores de ambiente de nicho que você só alcança em implantações específicas. A maioria dos aplicativos nunca toca neles.
+
+## Assinatura de estado OAuth {#oauth-state}
+
+Fluxos OAuth (Google, Atlassian, Zoom) assinam seu envelope de estado com uma chave HMAC dedicada:
+
+```bash
+OAUTH_STATE_SECRET=$(openssl rand -hex 32)
+```
+
+Isso costumava recorrer a `GOOGLE_CLIENT_SECRET` (uma credencial compartilhada com o Google) — um vazamento do segredo do Google teria permitido que invasores falsificassem envelopes de estado OAuth. A chave dedicada é independente de qualquer segredo de terceiros. Se `OAUTH_STATE_SECRET` não estiver definido, a estrutura retornará para `BETTER_AUTH_SECRET`; implantações de espaço de trabalho hospedado também podem derivar uma chave OAuth específica do `A2A_SECRET` já necessário. Se nenhum desses segredos do servidor estiver disponível, os fluxos OAuth falharão na produção.
+
+Os parâmetros de consulta `redirect_uri` também são validados em uma lista de permissões (mesma origem + caminhos da estrutura `/_agent-native/...`). Os fluxos OAuth personalizados em modelos devem usar o auxiliar `isAllowedOAuthRedirectUri()` da estrutura antes de assinar o estado.
+
+## Segredos de ferramentas para vários usuários {#tooling-secrets}
+
+Ferramentas e automações que fazem referência a `${keys.NAME}` resolvem segredos por usuário por padrão. O substituto do escopo do espaço de trabalho está **desativado por padrão** nesta versão. Caso contrário, um membro mal-intencionado da organização poderia plantar um espaço de trabalho `OPENAI_API_KEY` e coletar chamadas API de outros membros.
+
+Se sua organização realmente compartilha chaves para todo o espaço de trabalho (por exemplo, uma única chave Stripe corporativa), opte novamente pelo comportamento antigo com:
+
+```bash
+AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
+```
+
+As gravações secretas no escopo do workspace ainda exigem a função de proprietário/administrador da organização, independentemente dessa sinalização.

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

@@ -0,0 +1,253 @@
+---
+title: "Servidor"
+description: "Rotas de servidor Nitro, plug-ins, rotas montadas em estrutura, contexto de solicitação e sincronização apoiada por SQL."
+---
+
+# Servidor
+
+Aplicativos nativos de agente usam [Nitro](https://nitro.build) para rotas de servidor e plug-ins. A maior parte do comportamento do produto deve residir em [Actions](/docs/actions); rotas personalizadas são para superfícies de protocolo nas quais actions não cabem: uploads, streaming, páginas públicas, retornos de chamada webhooks, OAuth e APIs específicos do provedor.
+
+```an-diagram title="What runs on the server" summary="Actions are the default. Custom file routes and framework-mounted routes share the same Nitro app and the same SQL database."
+{
+  "html": "<div class=\"diagram-server\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">Browser / UI</div><div class=\"diagram-node\">Agent loop</div><div class=\"diagram-node\">External clients<br><small class=\"diagram-muted\">HTTP · MCP · A2A</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>Nitro server</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">default surface</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">/_agent-native/*</span><small class=\"diagram-muted\">framework routes</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">/api/*</span><small class=\"diagram-muted\">custom file routes</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">plugins</span><small class=\"diagram-muted\">startup: migrations, jobs</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL database<br><small class=\"diagram-muted\">Drizzle · the coordination point</small></div></div>",
+  "css": ".diagram-server{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-server .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-server .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px}.diagram-server .diagram-row{display:flex;align-items:center;gap:8px}.diagram-server .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Rotas baseadas em arquivo {#file-based-routes}
+
+As rotas residem em `server/routes/` e Nitro mapeia nomes de arquivos para métodos e caminhos:
+
+```text
+server/routes/
+  api/
+    health.get.ts              -> GET  /api/health
+    uploads.post.ts            -> POST /api/uploads
+    webhooks/
+      stripe.post.ts           -> POST /api/webhooks/stripe
+  [...page].get.ts             -> SSR catch-all for public pages
+```
+
+Cada rota exporta um `defineEventHandler`:
+
+```ts
+// server/routes/api/health.get.ts
+import { defineEventHandler } from "h3";
+
+export default defineEventHandler(() => ({
+  ok: true,
+  service: "my-template",
+}));
+```
+
+### Convenções de nomenclatura de rotas {#route-naming-conventions}
+
+| Padrão de nome de arquivo | Método HTTP | Caminho de exemplo          |
+| ------------------------- | ----------- | --------------------------- |
+| `index.get.ts`            | GET         | `/api/items`                |
+| `index.post.ts`           | POST        | `/api/items`                |
+| `[id].get.ts`             | GET         | `/api/items/:id`            |
+| `[id].patch.ts`           | PATCH       | `/api/items/:id`            |
+| `[id].delete.ts`          | DELETE      | `/api/items/:id`            |
+| `[...slug].get.ts`        | GET         | `/api/items/*` ou pega-tudo |
+
+## Prefira Actions para operações de aplicativos {#actions-first}
+
+Se o UI e o agente precisarem fazer algo, defina uma ação em vez de uma rota API personalizada. Actions torna-se automaticamente:
+
+- Ferramentas do agente.
+- Ganchos de front-end digitados.
+- Endpoints HTTP em `/_agent-native/actions/:name`.
+- Ferramentas que podem ser chamadas de MCP e A2A.
+- Comandos CLI para desenvolvimento.
+
+Use rotas `/api/*` personalizadas somente quando precisar de um protocolo em formato de rota ou comportamento binário/streaming. Consulte [Actions](/docs/actions).
+
+## Completamento de texto único {#complete-text}
+
+A maior parte do trabalho de IA deve passar pelo chat do agente para que os usuários possam ver, orientar e auditar
+o que aconteceu. Para transformações estreitas do lado do servidor que intencionalmente não precisam
+ferramentas, histórico de bate-papo ou estado de execução, use `completeText()` como um escape explícito
+hachurada.
+
+```ts
+// actions/classify-message.ts
+import { defineAction } from "@agent-native/core/action";
+import { completeText } from "@agent-native/core/server";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Classify a short message",
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => {
+    const result = await completeText({
+      systemPrompt:
+        "Return exactly one label: urgent, follow-up, waiting, or archive.",
+      input: body,
+      maxOutputTokens: 16,
+      temperature: 0,
+    });
+
+    return { label: result.text.trim() };
+  },
+});
+```
+
+`completeText()` é executado na mesma camada de mecanismo configurada que o agente
+bate-papo, incluindo provedores Builder, Anthropic, AI SDK, padrões de modelo de usuário/aplicativo,
+segredos com escopo de solicitação e erros normalizados pelo mecanismo. É apenas para servidor; não
+chamar provedores de modelo a partir do código do cliente. Se a operação for voltada para o usuário, envolva-a
+em uma ação para que UI e o agente compartilhem a mesma capacidade.
+
+## Solicitar contexto e acesso {#request-context}
+
+Actions montado pela estrutura é executado automaticamente com contexto de solicitação. Rotas personalizadas não. Se uma rota personalizada lê ou grava recursos proprietários, carregue a sessão e finalize o trabalho:
+
+```an-annotated-code title="Scoping a custom route to the request user"
+{
+  "filename": "server/routes/api/projects.get.ts",
+  "language": "ts",
+  "code": "import { defineEventHandler, createError } from \"h3\";\nimport { getSession, runWithRequestContext } from \"@agent-native/core/server\";\nimport { getDb } from \"../../db/index.js\";\nimport { accessFilter } from \"@agent-native/core/sharing\";\nimport * as schema from \"../../db/schema\";\n\nexport default defineEventHandler(async (event) => {\n  const session = await getSession(event);\n  if (!session?.email) {\n    throw createError({ statusCode: 401, statusMessage: \"Unauthorized\" });\n  }\n\n  return runWithRequestContext(\n    { userEmail: session.email, orgId: session.orgId },\n    async () => {\n      const db = getDb();\n      return db\n        .select()\n        .from(schema.projects)\n        .where(accessFilter(schema.projects, schema.projectShares));\n    },\n  );\n});",
+  "annotations": [
+    { "lines": "7-10", "label": "Custom routes have no auto-context", "note": "Unlike actions, a file route must load the session itself and fail closed when there is no authenticated user." },
+    { "lines": "12-13", "label": "Establish request context", "note": "`runWithRequestContext` makes the user/org available to scoping helpers for the duration of the work." },
+    { "lines": "18-19", "label": "Scope ownable reads", "note": "`accessFilter` constrains the query to rows the caller may see. Never run an unscoped `db.select().from(ownableTable)` here." }
+  ]
+}
+```
+
+`getDb` é criado por aplicativo via `createGetDb(schema)` em `server/db/index.ts`, portanto, rotas personalizadas importam-no do modelo (`../../db/index.js`), não de `@agent-native/core/db`; veja [Database — Where the DB Client Lives](/docs/database#db-client). Não execute `db.select().from(ownableTable)` sem escopo em rotas personalizadas.
+
+## Plugins de servidor {#server-plugins}
+
+Os plug-ins ficam no `server/plugins/` e são executados na inicialização. Use-os para migrações, configuração de provedores, trabalhos recorrentes, adaptadores de integração e configuração de plug-ins de estrutura.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+As migrações devem ser aditivas. Nunca coloque SQL destrutivo em plugins de inicialização.
+
+## Rotas montadas em estrutura {#framework-routes}
+
+A estrutura monta suas próprias rotas em `/_agent-native/`. Trate esse namespace como reservado.
+
+| Prefixo da rota                  | Propósito                                                                                   |
+| -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `/_agent-native/actions/:name`   | Endpoints de ação HTTP                                                                      |
+| `/_agent-native/agent-chat`      | Loop de bate-papo do agente                                                                 |
+| `/_agent-native/poll`            | Sincronização UI suportada por SQL                                                          |
+| `/_agent-native/resources/*`     | Recursos do espaço de trabalho                                                              |
+| `/_agent-native/extensions/*`    | Extensões de tempo de execução e proxy de extensão (alias legado: `/_agent-native/tools/*`) |
+| `/_agent-native/integrations/*`  | Integrações de mensagens/webhook                                                            |
+| `/_agent-native/a2a`             | Agente para agente JSON-RPC                                                                 |
+| `/_agent-native/mcp`             | Ponto final MCP                                                                             |
+| `/_agent-native/onboarding/*`    | Lista de verificação de configuração                                                        |
+| `/_agent-native/observability/*` | Traces, feedback, avaliações, experimentos                                                  |
+| `/_agent-native/file-upload`     | Endpoint do provedor de upload de arquivos                                                  |
+
+As rotas de aplicativos personalizados devem usar `/api/*`, caminhos de aplicativos públicos ou caminhos de retorno de chamada específicos do provedor que não colidam com `/_agent-native/`.
+
+## Sincronização apoiada por SQL {#sync}
+
+O agente nativo não depende de observadores do sistema de arquivos ou de estado fixo na memória. Quando actions ou auxiliares de estrutura alteram dados, a versão de sincronização do banco de dados aumenta. O gancho do cliente `useDbSync()` pesquisa `/_agent-native/poll` e invalida os caches de consulta React.
+
+Isso funciona em implantações sem servidor e com várias instâncias porque o banco de dados é o ponto de coordenação. Se você escrever mutações personalizadas fora de actions, use auxiliares de estrutura ou emita a invalidação de sincronização apropriada para abrir a atualização de UIs.
+
+```an-diagram title="SQL-backed sync loop" summary="No watchers, no sticky state. A write bumps a version in SQL; every client polls the version and refetches."
+{
+  "html": "<div class=\"diagram-sync\"><div class=\"diagram-box\" data-rough>Action / helper<br><small class=\"diagram-muted\">mutates data</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong><small class=\"diagram-muted\">sync version increments</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">useDbSync()<br><small class=\"diagram-muted\">polls /_agent-native/poll</small></div><div class=\"diagram-pill ok\">invalidate caches &rarr; UI refreshes</div></div></div>",
+  "css": ".diagram-sync{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sync .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:flex-start}.diagram-sync .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The poll endpoint" method="GET" path="/_agent-native/poll"
+{
+  "method": "GET",
+  "path": "/_agent-native/poll",
+  "summary": "Return the current per-source database sync versions so the client can detect changes.",
+  "description": "`useDbSync()` calls this on an interval (and falls back to it when SSE is unavailable). When a returned version is higher than the client's last-seen value, the matching React Query caches are invalidated and refetch.",
+  "auth": "Session cookie (request-scoped identity)",
+  "responses": [
+    { "status": "200", "description": "Current sync versions keyed by source." }
+  ]
+}
+```
+
+## Webhooks {#webhooks}
+
+A entrada webhooks deve verificar, persistir e retornar rapidamente. O trabalho de agente de longa duração deve usar o padrão de fila de integração:
+
+1. Verifique a assinatura ou desafio da plataforma.
+2. Insira trabalho durável em SQL.
+3. Autodisparar uma rota de processador assinada.
+4. Devolva 200 imediatamente.
+5. Deixe a nova execução do processador executar o loop do agente e postar o resultado.
+
+```an-diagram title="Integration queue pattern" summary="The webhook handler returns in milliseconds; a separate signed execution runs the slow agent work."
+{
+  "html": "<div class=\"diagram-webhook\"><div class=\"diagram-box\" data-rough>Inbound webhook<br><small class=\"diagram-muted\">Slack · Stripe · email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>Handler</strong><div class=\"diagram-step\"><span class=\"diagram-pill\">1</span><small class=\"diagram-muted\">verify signature</small></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><small class=\"diagram-muted\">insert work into SQL</small></div><div class=\"diagram-step\"><span class=\"diagram-pill\">3</span><small class=\"diagram-muted\">self-fire processor</small></div><div class=\"diagram-step\"><span class=\"diagram-pill ok\">4</span><small class=\"diagram-muted\">return 200 now</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Signed processor<br><small class=\"diagram-muted\">runs agent loop, posts result</small></div></div>",
+  "css": ".diagram-webhook{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-webhook .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-webhook .diagram-step{display:flex;align-items:center;gap:8px}.diagram-webhook .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+> [!WARNING]
+> Não confie em promessas inesperadas após retornar uma resposta — hosts sem servidor congelam a execução. Consulte [Messaging](/docs/messaging) para ver a fila de integração canônica.
+
+## Avançado: Escotilhas de Fuga {#advanced-escape-hatches}
+
+A maioria dos modelos nunca precisa disso. Rotas de arquivo Nitro e agente do framework
+o plug-in de bate-papo já conecta o servidor do aplicativo e o manipulador do agente de produção.
+Alcance-os somente ao criar uma integração de servidor personalizada fora do
+pilha de plug-ins de modelo padrão.
+
+### Servidores H3 programáticos {#create-server}
+
+Para pacotes personalizados ou testes que precisam de um aplicativo H3 diretamente, `createServer()`
+retorna um aplicativo e um roteador pré-configurados:
+
+```ts
+import { createServer } from "@agent-native/core/server";
+import { defineEventHandler } from "h3";
+
+const { app, router } = createServer();
+
+router.get(
+  "/api/health",
+  defineEventHandler(() => ({ ok: true })),
+);
+```
+
+### Manipulador de agente de produção {#agent-handler}
+
+O plugin de chat do agente da estrutura já monta o manipulador do agente de produção
+para modelos. Chame `createProductionAgentHandler()` apenas diretamente ao construir
+uma integração de servidor personalizada fora da pilha de plug-ins de modelo padrão —
+caso contrário, personalize o agente por meio de `AGENTS.md`, skills, actions e
+plug-in de bate-papo do agente.
+
+```ts
+import { createProductionAgentHandler } from "@agent-native/core/server";
+
+const handler = createProductionAgentHandler({
+  scripts,
+  systemPrompt: "You are the app agent...",
+});
+```