@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,106 @@
+---
+title: "Processadores em loop"
+description: "Ganchos de observador/guardrail internos em loop que observam a saída transmitida do modelo e as chamadas de ferramenta no meio da execução e podem abortá-lo - a costura para guardrails em tempo real e portões de prova de conclusão."
+---
+
+# Processadores em loop
+
+Um `Processor` é um **observador/guardrail** interno de loop para a execução do agente. Ele observa a saída transmitida do modelo e a ferramenta chama as solicitações _conforme a execução avança_, mantém seu próprio estado inicial e pode **abortar** a execução antes que um "pronto" seja reivindicado. Este é o pré-requisito estrutural para proteções em tempo real (bloquear a saída não permitida no meio do fluxo) e uma porta de prova/cobertura (inspecionar o que o modelo está prestes a fazer e interrompê-lo).
+
+```an-diagram title="Where the three hooks fire in the run" summary="processOutputStream watches every chunk, processOutputStep gates tool calls per response, processOutputResult records a verdict at the end. Any hook can abort with a TripWire."
+{
+  "html": "<div class=\"diagram-proc\"><div class=\"diagram-node\" data-rough>stream chunks<br><small class=\"diagram-muted\">processOutputStream</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>per model response<br><small class=\"diagram-muted\">processOutputStep — gate tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>run end<br><small class=\"diagram-muted\">processOutputResult — verdict</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-pill warn\">abort() &rarr; TripWire &rarr; tripwire event</div></div>",
+  "css": ".diagram-proc{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-proc .diagram-arrow{font-size:22px;line-height:1}.diagram-proc .diagram-pill{flex-basis:100%}"
+}
+```
+
+> [!WARNING]
+> Um processador é **configuração**, não é uma ferramenta, não é uma ação e não é um DSL de autoria. Os processadores apenas observam, alteram seu próprio estado com escopo de fluxo e `abort()`. Eles nunca definem o comportamento do aplicativo, substituem actions ou aparecem para o modelo. As operações do aplicativo pertencem a [actions](/docs/actions).
+
+## Os ganchos {#hooks}
+
+Um processador implementa qualquer subconjunto de três ganchos de ciclo de vida opcionais (a forma é emprestada dos processadores de saída do Mastra):
+
+| Gancho                | Incêndios…                                                                 | Use-o para…                                                                            |
+| --------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `processOutputStream` | por pedaço transmitido (deltas de texto/pensamento) enquanto o modelo gera | reaja à saída antes do turno completo acontecer                                        |
+| `processOutputStep`   | uma vez por resposta do modelo, próximo à execução da ferramenta           | inspecione as chamadas de ferramenta que o modelo está prestes a executar; bloqueie-os |
+| `processOutputResult` | uma vez no final da execução, com o texto final do assistente              | registrar um veredicto/prova de conclusão sobre a resposta completa                    |
+
+Cada processador obtém seu próprio objeto `state` mutável com escopo de execução que persiste em cada uma de suas invocações de gancho em uma única execução e é **isolado** do estado de outros processadores.
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## Abortando com `TripWire` {#tripwire}
+
+Um gancho interrompe a execução chamando `abort(reason, meta?)`, que lança um **`TripWire`**. O loop o detecta, emite um único **evento `tripwire`**, para de forma limpa e revela o motivo como a mensagem final do assistente.
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+O evento `tripwire` carrega:
+
+| Campo       | Tipo     | Notas                                                      |
+| ----------- | -------- | ---------------------------------------------------------- |
+| `reason`    | `string` | O motivo legível passado para `abort`.                     |
+| `processor` | `string` | Nome do processador que abortou quando declarou um `name`. |
+
+`TripWire` também carrega `meta` estruturado opcional e o nome `processor` de origem para consumidores programáticos que `instanceof` o verificam. Como uma parada é normal, `processOutputResult` ainda é acionado no texto final (interrompido) para que um processador de prova de conclusão possa registrar seu veredicto mesmo quando a execução foi abortada.
+
+## Fiação de processadores {#wiring}
+
+Os processadores são configurados em código por meio do array `processors` em `runAgentLoop`:
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**Zero sobrecarga quando não utilizado.** O loop cria a cadeia do processador somente quando pelo menos um processador é fornecido; quando `processors` é omitido ou vazio, nenhum código de costura é executado e o loop permanece inalterado byte por byte. Os ganchos são executados em ordem de registro e podem ser sincronizados ou assíncronos.
+
+> [!NOTE]
+> A junção em nível de loop é entregue hoje e pode ser chamada diretamente por subagentes, A2A, MCP e testes. Encadear `processors` por meio do manipulador de bate-papo HTTP (para que um resolvedor por solicitação possa configurá-los sem chamar `runAgentLoop` diretamente) é um encanamento de conveniência que ainda não está conectado. Configure os processadores no site de chamada `runAgentLoop` por enquanto.
+
+## Relacionado
+
+- [**Durable Resume**](/docs/durable-resume) — como o loop sobrevive a interrupções sem executar novamente os efeitos colaterais concluídos.
+- [**Custom Agents & Teams**](/docs/agent-teams) — os subagentes executam o mesmo loop e podem carregar seus próprios processadores.
+- [**Observability**](/docs/observability) — registra veredictos do processador juntamente com rastreamentos de execução.

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

@@ -0,0 +1,199 @@
+---
+title: "Progresso"
+description: "Sinal de progresso em tempo real para tarefas de agente de longa duração — iniciar, atualizar, concluir"
+---
+
+# Progresso
+
+Tarefas longas de agente não devem se esconder atrás de um botão giratório. `progress_runs` oferece ao agente uma maneira de anunciar _"Estou trabalhando nisso, terminei 45%, aqui está a etapa atual"_ - que o UI renderiza como uma bandeja de execuções flutuante com uma barra de porcentagem.
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+Preocupação separada de [notifications](/docs/notifications): as notificações são disparadas uma vez (_"X aconteceu"_), o progresso é um estado contínuo (_"X está 45% concluído"_). Os dois compõem - `completeRun` seguido de `notify(..., severity: "info")` informa ao usuário quando o trabalho termina, mesmo que ele não esteja observando a bandeja.
+
+## O ciclo de vida {#lifecycle}
+
+| Status      | Transição                         |
+| ----------- | --------------------------------- |
+| `running`   | Inicial — definido por `startRun` |
+| `succeeded` | Terminal de caminho feliz         |
+| `failed`    | Erro no terminal                  |
+| `cancelled` | Usuário interrompido              |
+
+```an-diagram title="Run lifecycle" summary="startRun opens a running row; updateRunProgress patches it; completeRun moves it to one terminal status and stamps completed_at."
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Status do terminal definidos como `completed_at`. A bandeja UI mostra apenas linhas `running`; as linhas concluídas permanecem no banco de dados para consultas `action=list`.
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+Crie uma corrida. Retorna o `AgentRun` completo com um ID gerado.
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+Emite `run.progress.started` no barramento de eventos.
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+Corrija qualquer campo de uma execução em execução. Qualquer campo omitido permanece inalterado.
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+Emite `run.progress.updated` no barramento de eventos. Retorna o `AgentRun` atualizado ou `null` se a execução não existir ou não pertencer ao chamador.
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+Transição para um status de terminal. `succeeded` define implicitamente `percent=100`.
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+Também emite `run.progress.updated` com o status do terminal.
+
+### Listagem {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+Montado em `/_agent-native/runs/*` pelo plugin core-routes. **Somente leitura em HTTP** — as gravações passam pelas ferramentas do agente, pois o agente é o gravador canônico. Todas as rotas têm escopo do proprietário.
+
+| Método   | Caminho                           |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="List active runs" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## Componente UI {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+Widget de cabeçalho embutido – monte-o próximo ao sino de notificações. Mostra um ícone giratório + emblema de contagem quando as corridas estão ativas; clicar abre um menu suspenso com uma barra percentual ativa por execução. Oculta totalmente o gatilho quando não há execução ativa. Pesquisa `/_agent-native/runs?active=true` a cada `pollMs` (padrão 3 s). Usa tokens semânticos shadcn e se adapta a temas claros e escuros.
+
+## Ferramenta de agente {#agent-tool}
+
+Uma única ferramenta `manage-progress` é registrada em cada modelo. O parâmetro `action` seleciona a operação:
+
+| Ação       | Propósito                                                        |
+| ---------- | ---------------------------------------------------------------- |
+| `start`    | Chame no início de uma tarefa longa. Retorna um runId.           |
+| `update`   | Chame periodicamente durante a tarefa com `percent` e/ou `step`. |
+| `complete` | Terminal — um dos `succeeded`, `failed`, `cancelled`.            |
+| `list`     | Inspecione execuções recentes (filtre por `active=true`).        |
+
+### Quando iniciar uma corrida {#when-to-start}
+
+- Use para qualquer coisa > ~5 segundos. Um botão giratório sem contexto parece congelado.
+- Atualização em pontos de verificação naturais, não em todas as iterações. Cada 5–10% é suficiente.
+- **Sempre** chame `manage-progress` com `action=complete`, inclusive em caminhos de erro. Uma linha `running` órfã é pior do que nenhuma linha.
+- Emparelhe com `notify` ao concluir para que o usuário veja o resultado quando não estiver observando ativamente a bandeja.
+
+## Barramento de eventos {#event-bus}
+
+Dois eventos emitidos no [event bus](/docs/automations#event-bus):
+
+| Evento                 | Carga útil                         |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) pode assinar estes — por exemplo, _"se uma corrida demorar mais de 5 minutos, avise-me"_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## Como funciona {#internals}
+
+- **Escopo do proprietário** — cada linha tem uma coluna `owner`; cada consulta é filtrada nela. Os usuários veem apenas suas próprias corridas.
+- **Integração de pesquisa** — cada mutação chama `recordChange()` para que os modelos que usam [`useDbSync`](/docs/client) sejam invalidados automaticamente sem qualquer conexão extra.
+- **Nome da tabela** — a estrutura também possui uma tabela `agent_runs` para rastreamento interno do ciclo de vida do turno de bate-papo entre agentes. A primitiva de progresso usa `progress_runs` para manter os dois interesses separados.
+- **Ajuste percentual** — os valores são fixados em `[0, 100]` e arredondados para um número inteiro na gravação.
+
+## O que vem a seguir
+
+- [**Notifications**](/docs/notifications) — emparelhe com `manage-progress` (`action=complete`) para informar ao usuário quando o trabalho terminar
+- [**Automations**](/docs/automations) — execuções lentas do watchdog via `run.progress.updated`
+- [**Client**](/docs/client) — `useDbSync` para invalidação de cache em tempo real

package/corpus/core/docs/content/locales/pt-BR/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "Aplicativos de agente puro"
+description: "Aplicativos em que o agente é o produto completo: o loop app-agent é a porta de entrada e UI é adicionado apenas quando humanos precisam dele."
+---
+
+# Aplicativos de agente puro
+
+Um aplicativo de agente puro é o fim mínimo do agente nativo: o loop app-agent é o
+produto, não um painel. Você envia uma solicitação do terminal, Slack, email, um
+trabalho agendado, outro agente ou bate-papo — "resumir meus e-mails não lidos", "postar o
+métricas diárias para Slack" — e o agente atua e retorna o resultado onde quer que esteja
+pertence. Ainda é um aplicativo real: actions, sessões, estado do aplicativo, histórico,
+configurações, credenciais e registros de compartilhamento, todos ativos em SQL.
+
+```an-diagram title="The app-agent loop is the front door" summary="Many entry points reach one agent loop over SQL-backed actions and state; results return to wherever the request came from. UI is added only when humans need to supervise."
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · email</div><div class=\"diagram-pill\">Scheduled job</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">App-agent loop</span><small class=\"diagram-muted\">actions · sessions · app state in SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Result returns<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+Alcance esta forma quando o trabalho é executado em segundo plano, a saída sai do
+aplicativo, o domínio é único ou você está criando um protótipo. O agente ainda precisa de um UI —
+não é um painel, mas um lugar para humanos supervisionarem, configurarem e orientarem —
+é por isso que mesmo aplicativos de agente puro geralmente montam o shell de bate-papo integrado.
+
+Este é o formato do produto **sem cabeça**. O guia de decisão completo, o que vem dentro
+a caixa, o scaffold, o acesso ao repositório e o compartilhamento de execução agora estão em um só lugar:
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## O que vem a seguir
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) — o guia completo de decisão sem cabeça e APIs
+- [**Getting Started**](/docs/getting-started) — crie primeiro um aplicativo de bate-papo ou um agente sem cabeça
+- [**Dispatch**](/docs/template-dispatch) — o modelo de espaço de trabalho que é um excelente ponto de partida para agente puro
+- [**Messaging the agent**](/docs/messaging) — como os usuários conversam com o agente pela web, Slack, Telegram, e-mail
+- [**Recurring Jobs**](/docs/recurring-jobs) — prompts agendados que o agente executa sozinho
+- [**Actions**](/docs/actions) — as ferramentas que seu agente puro chamará