@agent-native/core 0.88.0 → 0.90.2

package/corpus/core/docs/content/locales/pt-BR/data-programs.mdx

@@ -0,0 +1,329 @@
+---
+title: "Programas de dados"
+description: "Scripts JS armazenados e escritos pelo agente que buscam, unem e agregam dados no servidor, armazenados em cache no SQL e renderizados por painéis de dashboard — o meio-termo de dados ao vivo entre uma consulta run-code pontual e uma action de provedor codificada."
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# Programas de dados
+
+Um **programa de dados** é um script JS nomeado, armazenado e escrito pelo agente que busca, une, filtra ou agrega dados — APIs de provedores via `providerFetch` / `providerFetchAll` / `providerSearchAll`, dados de app via `appAction`, ou arquivos de workspace baseados em Resources — e chama `emit(rows, schema)` exatamente uma vez com o resultado. O resultado é armazenado em cache no SQL, e qualquer componente de gráfico/tabela pode renderizá-lo, atualizado conforme uma política que você escolher em vez de a cada visualização de página.
+
+Ele é disponibilizado automaticamente onde quer que [`run-code`](/docs/actions) esteja disponível — não há nada para montar ou configurar por app. Se sua app já tem o run-code habilitado, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program` e `delete-data-program` já são actions registradas.
+
+<Diagram id="doc-block-dp-overview" title={"De consulta pontual a painel ao vivo"} summary={"Um script run-code se torna um programa armazenado assim que chama emit(); qualquer painel de dashboard pode se vincular a ele, e a política de cache/atualização assume a partir daí."}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">Painel de dashboard</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Por que isso existe {#why}
+
+Sem um programa de dados armazenado, "construir uma visão ao vivo de X" costuma terminar em um de dois lugares ruins:
+
+- **Uma action codificada por fornecedor/formato de consulta.** Frágil, e não consegue antecipar as propriedades personalizadas de cada cliente, um join entre provedores, ou um filtro arbitrário que você não pensou em incluir.
+- **Reexecutar a mesma lógica de busca/join do zero a cada visualização de página.** Lento, e volta a gastar a mesma cota de API do provedor toda vez que alguém olha para um gráfico.
+
+Um programa de dados é o meio-termo: escreva a lógica de busca/join/agregação uma vez como `run-code` comum, salve-a, e deixe que o cache e a política de atualização decidam com que frequência ela realmente precisa ser reexecutada.
+
+## Quando usar um {#when-to-use-one}
+
+| Situação                                                                                                                                                                                              | Recorra a                                                                              |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Um rollup padrão já tem uma action de primeira classe (um filtro `hubspot-deals` predefinido, uma métrica embutida)                                                                                   | A action existente — não a envolva em um programa                                      |
+| Uma pergunta de chat pontual que você nunca mais vai olhar                                                                                                                                            | `run-code` simples ou `provider-api-request` — responda diretamente, não persista nada |
+| Uma extensão precisa de um pequeno widget interativo por usuário com sua própria UI                                                                                                                   | [Extensões](/docs/extensions) — um programa de dados não tem UI própria                |
+| Uma coorte precisa de um filtro de propriedade arbitrário, uma busca IN sobre valores personalizados, ou um join entre dois provedores, **e** alguém vai querer vê-la novamente com dados atualizados | Um programa de dados                                                                   |
+| Um painel de dashboard deve mostrar esse resultado unido/agregado e atualizar conforme a política de cache                                                                                            | Um programa de dados vinculado a um painel `"program"`                                 |
+
+Uma comparação com as outras opções no formato run-code:
+
+|                                                | `run-code` pontual         | Action de provedor codificada                      | Programa de dados                                         |
+| ---------------------------------------------- | -------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
+| **Persiste entre chamadas**                    | Não                        | N/A (é código-fonte)                               | Sim — linha armazenada + cache de resultado               |
+| **Resultado é armazenado em cache/atualizado** | Não, reexecuta toda vez    | Sem cache embutido                                 | Sim — `refreshMode`/`refreshTtlMs`                        |
+| **Lida com filtros/joins arbitrários**         | Sim, mas descartado depois | Não — limitado ao que o schema da action expõe     | Sim — ainda é código comum                                |
+| **Vinculável a um painel de dashboard**        | Não                        | Só se uma fonte de painel foi construída para isso | Sim — a fonte genérica `"program"`                        |
+| **Requer um deploy**                           | Não                        | Sim (nova action = mudança de código)              | Não — criado pelo agente em tempo de execução             |
+| **Credenciais usadas no momento da leitura**   | Do chamador                | Do chamador                                        | **Do visualizador**, resolvidas por leitura (veja abaixo) |
+
+## Fluxo de autoria {#authoring-workflow}
+
+1. **Prototipe no chat primeiro.** Escreva a lógica de busca/join/agregação como um script `run-code` normal e confirme que ele retorna as linhas esperadas.
+2. **Altere-o para chamar `emit(rows, schema?)` exatamente uma vez** no final, em vez de retornar ou imprimir o resultado.
+3. **Salve-o** com `save-data-program`. Isso **executa um dry-run do código com `defaultParams` antes de persistir** e rejeita o salvamento com um erro estruturado se falhar, de modo que um programa quebrado nunca é armazenado. Em caso de sucesso, retorna `{ programId, rowCount, columns, sampleRows }` — trate isso como prova de que o programa produz as linhas esperadas antes de dizer ao usuário que está pronto.
+4. **Vincule um painel de dashboard a ele**, ou chame `run-data-program` diretamente do seu próprio caminho de leitura. Não há encanamento específico de dashboard embutido na própria primitiva — a fonte de painel `"program"` do template de analytics (abaixo) é uma adoção, não um padrão obrigatório.
+5. **Itere sem persistir** via `preview-data-program({ code, params? })` — o mesmo caminho de dry-run, sem linha armazenada.
+
+### Um exemplo realista
+
+Suponha que uma app queira uma tabela ao vivo de "tickets de suporte recentes de alto valor" obtida de um provedor de suporte, filtrada por um limiar que nenhuma action embutida expõe:
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+Salvando-o:
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+A resposta traz `{ programId, rowCount, columns, sampleRows }` — a prova de conclusão do dry-run. A partir daí, `run-data-program({ programId, params: { minValue: 10000 } })` o reexecuta (ou serve o cache) para um limiar diferente, e um painel de dashboard pode se vincular a `programId` da mesma forma.
+
+## A superfície do sandbox {#sandbox-surface}
+
+Um programa de dados roda exatamente pelo mesmo sandbox `executeSandboxCode` que o `run-code` — não existe novo código de sandboxing, credenciais, SSRF ou cota para essa primitiva. Ele obtém os mesmos globals (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`, `webFetch`, helpers de Resources `workspace*`) mais duas adições de um pequeno preâmbulo injetado pelo framework:
+
+- **`params`** — um objeto global **congelado** contendo os params desta execução (`defaultParams` mesclado com o que foi passado para `run-data-program` ou o descritor do painel). Lê-lo é seguro; mutá-lo lança um erro.
+- **`emit(rows, schema?)`** — chame isso **exatamente uma vez**, no final. Uma segunda chamada lança um erro. `rows` deve ser um array de objetos simples. `schema`, quando fornecido, é `{ name: string, type: string }[]`; quando omitido, é inferido das primeiras 50 linhas (uma coluna é `"json"` se as linhas discordarem sobre o tipo primitivo na amostra, caso contrário `"number"` / `"string"` / `"boolean"`). `console.log` permanece completamente livre para depuração — o runner captura stdout/stderr combinados e só remove a linha sentinela que `emit()` escreve ao analisar o resultado.
+
+Limites aplicados em cada execução (não configuráveis por programa):
+
+| Limite                                                           | Valor                                                                                                                                                         |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Máx. de linhas emitidas                                          | 10.000 — linhas além disso são descartadas, `truncated: true`                                                                                                 |
+| Tamanho máx. do resultado emitido                                | 4 MiB — linhas descartadas do final para caber; uma única linha acima do limite é uma falha rígida `result_too_large`, já que não há nada seguro para truncar |
+| Máx. de programas ativos (não arquivados) por app                | 200 — arquive os não utilizados para liberar espaço                                                                                                           |
+| TTL mínimo de atualização                                        | 60.000 ms                                                                                                                                                     |
+| Linhas de execução mantidas por (programa, params, visualizador) | 5 mais recentes — as mais antigas são removidas automaticamente a cada escrita                                                                                |
+
+O truncamento é sempre explícito (`truncated: true` no resultado) — nunca uma perda silenciosa.
+
+## Params e vinculação de painel de dashboard {#params-and-panel-binding}
+
+Programas declaram um `paramsSchema` opcional (JSON Schema descrevendo os params aceitos) e `defaultParams`. Um dashboard adota a fonte de painel `"program"` colocando um pequeno descritor JSON no campo de consulta do painel em vez de uma string de consulta:
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+O painel renderiza através exatamente dos mesmos componentes de gráfico/tabela que qualquer outra fonte de painel — ele só recebe `{ rows, schema }` de volta. Vincular um painel a um programa é apenas "qual programa armazenado, com quais sobrescritas de params"; não há nenhum caminho de execução específico de dashboard duplicado em outro lugar.
+
+## Semântica de atualização, TTL e cache {#refresh-and-caching}
+
+Cada par `(programId, paramsHash)` tem seu próprio histórico de execução em `data_program_runs`, e `paramsHash` incorpora **o visualizador**, não apenas os params (veja a seção de segurança para entender o motivo). O que acontece a cada leitura:
+
+| Situação                                                                                           | Comportamento                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cache fresco (mais recente que `refreshTtlMs`, ou `refreshMode: "manual"` com um sucesso anterior) | Retorna as linhas em cache instantaneamente, `cacheHit: true`                                                                                                                                                                   |
+| O cache é mais antigo que o TTL                                                                    | Reexecuta sincronamente — um orçamento de 25s para leituras acionadas por visualização de painel, 120s para chamadas de agente/manuais — e substitui o cache em caso de sucesso                                                 |
+| `refreshMode: "manual"`                                                                            | Nunca atualiza automaticamente; apenas um `forceRefresh: true` explícito (ou uma action de UI de atualização manual) o reexecuta                                                                                                |
+| Ainda sem cache                                                                                    | Executa sincronamente como uma primeira busca normal                                                                                                                                                                            |
+| Programa `background: true`, sem cache fresco                                                      | Serve a última execução bem-sucedida imediatamente com `stale: true` e enfileira uma execução em segundo plano durável (orçamento de 10 minutos); uma chamada posterior finaliza o resultado assim que a execução for concluída |
+| Programa em segundo plano ainda em execução, sem sucesso anterior                                  | Falha `background_pending` — exiba um estado explícito "ainda calculando", nunca um resultado em branco                                                                                                                         |
+| A execução falha (timeout, erro de sandbox, formato de `emit()` inválido)                          | Uma falha estruturada `{ code, message }`; se existir um sucesso anterior, ele é anexado como `lastGoodRun` para que um painel possa servir dados obsoletos em vez de ficar em branco                                           |
+| O programa foi arquivado (soft-delete via `delete-data-program`)                                   | Falha explícita `archived` — nunca um painel em branco silencioso                                                                                                                                                               |
+
+Recorra a `background: true` apenas para programas que rotineiramente excedem o timeout em primeiro plano — grandes joins multi-provedor, paginação profunda. Todo o resto deve permanecer em primeiro plano: é mais simples de raciocinar e serve dados atualizados mais rápido.
+
+### Por que o cache é delimitado por visualizador {#per-viewer-cache}
+
+`providerFetch` dentro de um programa resolve a autenticação usando **o próprio contexto de requisição do visualizador que chama** — nunca o do autor do programa. Isso é verdade quer a chamada venha do agente, de uma chamada `run-data-program`, ou de um painel de dashboard sendo visto por um colega de equipe. Dois visualizadores diferentes executando o mesmo programa com os mesmos params podem legitimamente obter dois resultados diferentes: um tem uma chave do HubSpot configurada e o outro não, ou as permissões de provedor em nível de linha diferem por pessoa.
+
+Por causa disso, `hashDataProgramParams` incorpora a identidade do chamador na chave de cache junto com os params canonicalizados. Isso importa mais para **dashboards compartilhados**: se o cache fosse indexado apenas por params, a primeira pessoa a visualizar um painel determinaria silenciosamente o que cada outro visualizador vê, incluindo um visualizador sem as credenciais que produziram aquele resultado em cache. A delimitação por visualizador significa que um colega de equipe sem uma credencial vê seu próprio erro de autenticação naquele painel, não os dados de outra pessoa.
+
+## Modelo de segurança {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**Tokens brutos de provedor nunca chegam ao modelo ou ao navegador.** A única coisa que sai do sandbox é o `{ rows, schema }` que uma chamada `emit()` produz — a mesma fronteira de confiança que qualquer outra execução run-code e qualquer outra fonte de painel de dashboard.
+
+</Callout>
+
+- **Somente do lado do servidor.** O código de um programa de dados executa exclusivamente dentro de `executeSandboxCode` no servidor. Nem o código-fonte armazenado nem qualquer credencial que ele toque é enviado ao navegador ou ao modelo — apenas as linhas/schema emitidos e metadados compactos de execução (contagem de linhas, colunas, linhas de amostra) são.
+- **Credenciais são sempre do visualizador que chama, nunca do autor original do programa.** Veja [Semântica de atualização, TTL e cache](#per-viewer-cache) acima para entender por que isso também determina a chave de cache.
+- **`allowPublic: false` é um invariante rígido, não um padrão.** Programas de dados se registram no registro de sharing da mesma forma que as [Extensões](/docs/extensions#security), com o compartilhamento público desabilitado. Um programa público permitiria que qualquer usuário autenticado executasse código arbitrário armazenado sob seu próprio token — compartilhar um programa é limitado à sua organização, e significa apenas "colegas de equipe podem ver seu resultado em cache e disparar reexecuções", nunca "a internet em geral pode executar isso".
+- **As actions que mutam e executam não são invocáveis como ferramenta a partir da bridge de extensão/iframe em sandbox.** `save-data-program`, `preview-data-program`, `run-data-program` e `delete-data-program` são `toolCallable: false` — apenas o agente ou um caminho de leitura do lado do servidor pode invocá-las, nunca um iframe de extensão sob a sessão de quem o abriu. `list-data-programs` e `get-data-program` são somente leitura e delimitados por acesso através dos mesmos helpers de sharing que qualquer outro recurso ownable.
+- **Programas são delimitados à app que os criou.** Passar `appId` para uma busca significa que um programa criado em uma app não é executável a partir do chat do agente de outra app em um deploy de banco de dados compartilhado, mesmo para um chamador que de outra forma teria acesso em nível de linha (owner/org/share) a ele.
+- **Só se vincule a ou visualize um programa em que confie.** Como a execução sempre usa as próprias credenciais do visualizador, visualizar o resultado de um programa compartilhado é exatamente como abrir a extensão de outra pessoa — confie no código, não apenas na concessão de acesso.
+
+## O exemplo trabalhado do Risk Meeting {#risk-meeting-example}
+
+O template de analytics traz um estudo de caso concreto e executável: a action `ensure-risk-meeting-dashboard` instala de forma idempotente dois programas de dados mais um dashboard "Risk Meeting" de dois painéis, demonstrando três coisas que uma action codificada não consegue antecipar para cada cliente.
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Instalador do Risk Meeting"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "action idempotente: atualiza ambos os programas por nome estável, depois o dashboard por id",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "payload de programa armazenado — texto JS simples, não um arquivo-fonte de build",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "o programa complementar de alerta antecipado",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** — busca uma coorte configurável de deals de CRM por uma propriedade `risk_status` arbitrária (uma busca IN sobre valores personalizados que uma action predefinida não consegue antecipar), resolve a empresa de cada deal através de uma busca de associação em lote, resolve o domínio de cada empresa, busca o sentimento de conta de um segundo provedor não relacionado, e une os dois por domínio:
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** — a visão complementar: contas já sinalizadas como em risco pelo sentimento de suporte que **ainda não** apareceram na coorte de CRM acima. Essa lacuna — sinal de suporte ultrapassando o sinal de CRM — requer excluir a coorte de um provedor da de outro, exatamente o tipo de lógica de conjuntos entre provedores que nenhuma action de fornecedor único consegue expressar.
+
+Ambos os programas são instalados e mantidos atualizados pelo `ensure-risk-meeting-dashboard`, que:
+
+- Atualiza cada programa pelo seu `name` estável, de modo que reexecutar o instalador atualiza as mesmas linhas em vez de duplicá-las.
+- Não requer credenciais de CRM/suporte no momento da instalação — a autenticação do provedor é resolvida por visualizador somente quando um painel é realmente renderizado ou `run-data-program` é chamado, consistente com a delimitação de cache por visualizador acima.
+- Constrói um dashboard de dois painéis cujos painéis usam `source: "program"`, vinculados ao id de cada programa.
+
+Veja a skill `data-programs` para a fonte totalmente anotada.
+
+## Como outras apps adotam a fonte de painel {#adopting-the-panel-source}
+
+A fonte de painel de dashboard `"program"` é uma adoção da primitiva, implementada inteiramente na própria camada de consulta de painéis da app hospedeira — nada específico de dashboard está embutido no próprio `@agent-native/core/data-programs`. A implementação do template de analytics é uma referência útil para conectar a sua:
+
+- A coluna `sql` do painel carrega um pequeno descritor JSON — `{ programId, params? }` — em vez de uma string de consulta.
+- Renderizar um painel chama `runDataProgram` com `triggeredBy: "panel_view"` e a identidade do visualizador atual, de modo que o cache por visualizador e a resolução de credenciais se apliquem automaticamente.
+- Em caso de sucesso, o painel obtém `{ rows, schema }` — o mesmo formato que qualquer outra fonte de painel retorna, de modo que flui sem modificações pelos componentes de gráfico/tabela existentes.
+- Em caso de falha, um `lastGoodRun` é preferido a um painel quebrado sempre que existir um; somente quando não há sucesso anterior o painel exibe um erro estruturado (com texto mais amigável para códigos comuns como `access_denied`, `archived` e `background_pending`).
+
+Qualquer app pode implementar a mesma adoção para seus próprios dashboards/tabelas: chame `run-data-program` (ou `runDataProgram` diretamente se estiver no mesmo processo de servidor) a partir do seu próprio caminho de leitura, e passe os `rows`/`schema` retornados para seus próprios componentes de renderização.
+
+## Docs relacionadas {#related}
+
+- [Extensões](/docs/extensions) — a primitiva de mini-app em sandbox com a qual os programas de dados compartilham uma postura de segurança e um modelo de sharing, mas com uma UI própria.
+- [Actions](/docs/actions) — as convenções de `run-code` e os globals de sandbox (`providerFetch`, `appAction`, etc.) sobre os quais os programas de dados são construídos.
+- [Sharing e privacidade](/docs/sharing) — o modelo de sharing interno à organização, nunca público, que os programas de dados usam.
+- [Segurança](/docs/security) — os invariantes de tratamento de credenciais e delimitação de acesso do framework.

package/corpus/core/docs/content/locales/pt-BR/deployment.mdx

@@ -384,24 +384,23 @@ Alterne-os substituindo o env var em cada instância e reimplantando. As sessõe
 ## Ferramentas do agente de produção {#production-agent-tools}
 
 Os agentes de produção obtêm o actions registrado do aplicativo, além das ferramentas de estrutura de
-o plugin de chat do agente. As gravações no banco de dados são habilitadas por padrão porque o banco de dados bruto
-as ferramentas têm como escopo o usuário/organização autenticado, mas os proprietários de aplicativos podem restringir o
-descobre quando uma implantação deveria ser mais opinativa:
+o plugin de bate-papo do agente. A inspeção SQL fica habilitada por padrão; as gravações
+passam por actions tipadas do app, a menos que o app habilite explicitamente ferramentas de escrita SQL bruta:
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` — padrão. Registra `db-schema`, `db-query`,
-  `db-exec` e `db-patch`. As gravações têm como escopo o usuário/organização atual e
-  as alterações de esquema estão bloqueadas.
-- `databaseTools: "read"` — registra apenas `db-schema` e `db-query`; agentes
-  inspecione os dados com SQL, mas deve usar o aplicativo digitado actions para gravações.
+- `databaseTools: "read"` — padrão. Registra apenas `db-schema` e `db-query`;
+  os agentes inspecionam dados com SQL, mas devem usar actions tipadas do app para gravar.
+- `databaseTools: "write"` ou `true` — também registra `db-exec` e `db-patch`
+  para manutenção SQL bruta deliberada. As gravações são limitadas ao usuário/
+  organização atual e alterações de esquema são bloqueadas.
 - `databaseTools: "off"` ou `false` — remove ferramentas de banco de dados brutos do
   superfície do agente para que o actions do aplicativo seja o único caminho de acesso aos dados.
 - `extensionTools: false` — remove o gerenciamento de extensão da estrutura actions e

package/corpus/core/docs/content/locales/pt-BR/extensions.mdx

@@ -34,7 +34,7 @@ agente de aplicativo intacto.
     <div class="ext-helpers">
       <span class="diagram-pill">appAction</span
       ><span class="diagram-pill">appFetch</span
-      ><span class="diagram-pill">dbQuery / dbExec</span
+      ><span class="diagram-pill">dbQuery</span
       ><span class="diagram-pill">extensionData</span
       ><span class="diagram-pill">extensionFetch</span>
     </div>
@@ -227,7 +227,7 @@ Dentro da sandbox iframe, cada extensão tem estes auxiliares em `window`:
 | `appAction(name, params)`                        | Chame qualquer actions do modelo de host                       | `appAction('list-emails', { view: 'inbox' })`             |
 | `appFetch(path, options)`                        | Chamar endpoints de estrutura permitidos em `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')` |
 | `dbQuery(sql, args)`                             | Ler de SQL (com escopo automático para o usuário)              | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | Escrever para SQL                                              | `dbExec('INSERT INTO ...')`                               |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions          | Prefer `appAction` for app data writes                    |
 | `extensionFetch(url, options)`                   | Atingir APIs externos através de um proxy seguro com segredos  | `extensionFetch('https://api.github.com/user')`           |
 | `extensionData.set(collection, id, data, opts?)` | Persistir dados por extensão (escopo de usuário/organização)   | `extensionData.set('notes', id, { text: '...' })`         |
 | `extensionData.list(collection, opts?)`          | Listar itens persistentes                                      | `extensionData.list('notes', { scope: 'all' })`           |
@@ -397,7 +397,7 @@ As extensões locais têm um modelo de permissão v1 mais rígido:
 
 - `extensionData` está disponível para estado de tempo de execução pequeno, a menos que esteja desativado.
 - As chamadas `appAction` devem ser listadas explicitamente em `permissions.appActions`.
-- `dbQuery`, `dbExec` e `extensionFetch` estão bloqueados por enquanto.
+- `dbQuery` e `extensionFetch` estão bloqueados por enquanto.
 - Atualização, exclusão, compartilhamento e histórico apoiados por SQL actions retornam uma mensagem que
   aponta para o arquivo de entrada local.
 
@@ -430,6 +430,8 @@ A estrutura permite que o agente edite o código-fonte do aplicativo diretamente
 
 Regra geral: **se for para um usuário ou uma equipe, é uma extensão.** Se todos os usuários do modelo quiserem obtê-lo, envie-o como um recurso real.
 
+Para busca de dados personalizada que deva alimentar gráficos e tabelas nativos em vez de uma UI de widget sob medida, veja [Programas de dados](/docs/data-programs) — um script `run-code` armazenado e atualizável ao qual os painéis de dashboard se vinculam diretamente, sem nenhum iframe de extensão envolvido.
+
 ## Segurança {#security}
 
 <Callout id="doc-block-frp4nq" tone="success">
@@ -444,7 +446,7 @@ As extensões são executadas em um iframe em sandbox:
 - **Injeção de segredo no lado do servidor** por meio do modelo `${keys.NAME}` — o valor real da chave nunca chega ao navegador.
 - **Segredos bloqueados por domínio** — cada chave está vinculada a uma lista de permissões URL; o proxy recusa solicitações para outros hosts.
 - **Proteção de rede privada** — as extensões não podem alcançar endereços internos.
-- **Autenticação necessária** — as extensões são executadas apenas para usuários logados, e as chamadas `dbQuery`/`dbExec` têm escopo automático.
+- **Autenticação necessária** — as extensões são executadas apenas para usuários logados, e as chamadas `dbQuery` têm escopo automático.
 
 ## Algumas coisas que você deve saber sobre nomenclatura {#naming-back-compat}
 

package/corpus/core/docs/content/locales/pt-BR/key-concepts.mdx

@@ -239,21 +239,17 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# Ações principais para inspeção rápida do banco de dados e manutenção pontual
+# Ações principais para inspeção rápida do banco de dados
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
-# Cirúrgico find/replace em uma coluna de texto grande — envia uma comparação, não o valor inteiro
-pnpm action db-patch --table documents --column content \
-  --where "id='doc-1'" --find "old heading" --replace "new heading"
 ```
 
-O plug-in de bate-papo do agente de produção permite gravações de banco de dados brutos por padrão
-(`databaseTools: "write"`) para que os agentes possam corrigir dados de propriedade do aplicativo sem esperar por um
-nova ação digitada. Essas gravações têm como escopo o usuário/organização autenticado. Definir
-`databaseTools: "read"` para manter apenas a inspeção `db-schema` / `db-query` ou
-`databaseTools: "off"` / `false` para exigir o aplicativo digitado actions para todos os dados
-acesso.
+O plug-in de bate-papo do agente de produção deixa as ferramentas SQL brutas em modo somente leitura por padrão
+(`databaseTools: "read"`). Os agentes inspecionam dados do app com `db-schema` /
+`db-query` e escrevem por meio de actions tipadas do app. Defina
+`databaseTools: "write"` (ou `true`) apenas para superfícies de manutenção
+intencionais que também devam expor `db-exec` / `db-patch` com escopo; use
+`databaseTools: "off"` / `false` para exigir actions tipadas para todo acesso a dados.
 
 ## Ponte de bate-papo do agente {#agent-chat-bridge}
 
@@ -437,6 +433,7 @@ Eles estão no mesmo contrato e têm seus próprios aprofundamentos:
 
 - **[Dispatch](/docs/dispatch)** — o plano de controle do espaço de trabalho: caixa de entrada compartilhada, cofre de segredos, trabalhos agendados e um orquestrador que delega A2A a aplicativos especializados.
 - **[Extensions](/docs/extensions)** — miniaplicativos Alpine.js em sandbox que o agente cria em tempo de execução, sem alterações de origem ou migrações.
+- **[Programas de dados](/docs/data-programs)** — scripts `run-code` armazenados e escritos pelo agente que fornecem aos painéis de dashboard um resultado em cache e atualizável, em vez de uma action de provedor codificada.
 - **[A2A Protocol](/docs/a2a-protocol)** — como aplicativos no mesmo espaço de trabalho descobrem e chamam uns aos outros por meio de JSON-RPC.
 
 ## O que você ganha de graça {#what-you-get-for-free}

package/corpus/core/docs/content/locales/pt-BR/real-time-collaboration.mdx

@@ -261,11 +261,8 @@ export default createCollabPlugin({
 ### 4. Use o gancho do cliente
 
 ```ts
-import {
-  useCollaborativeDoc,
-  emailToColor,
-  emailToName,
-} from "@agent-native/core/client";
+import { useCollaborativeDoc } from "@agent-native/core/client";
+import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
 
@@ -367,12 +364,14 @@ Importe a presença e o editor do lado do cliente UI do subcaminho do navegador
 
 ```ts
 import {
-  PresenceBar,
-  LiveCursorOverlay,
-  RemoteSelectionRings,
   useCollaborativeDoc,
   usePresence,
 } from "@agent-native/core/client/collab";
+import {
+  PresenceBar,
+  LiveCursorOverlay,
+  RemoteSelectionRings,
+} from "@agent-native/toolkit/collab-ui";
 ```
 
 Os auxiliares de presença do agente do lado do servidor permanecem no pacote de colaboração de nível inferior:
@@ -458,7 +457,7 @@ O agente (AGENT_CLIENT_ID) aparece como um participante de primeira classe com `
 Renderiza cursores remotos como rótulos absolutamente posicionados sobre um elemento contêiner:
 
 ```tsx
-import { LiveCursorOverlay } from "@agent-native/core/client";
+import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 
 // cursor positions stored as { x, y } normalized 0–1 under presence.cursor
 <div ref={containerRef} style={{ position: "relative" }}>
@@ -478,7 +477,7 @@ O cursor do agente é renderizado distintamente com um ícone brilhante. Os curs
 Renderiza anéis de contorno coloridos + tags de nome sobre elementos selecionados remotamente:
 
 ```tsx
-import { RemoteSelectionRings } from "@agent-native/core/client";
+import { RemoteSelectionRings } from "@agent-native/toolkit/collab-ui";
 
 <div ref={containerRef} style={{ position: "relative" }}>
   {content}