@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/harness-agents.md

@@ -0,0 +1,349 @@
+---
+title: "Aprovecha a los agentes"
+description: "Ejecute Claude Code, Codex, Pi y otros sistemas de codificación completos como agentes integrados dentro de Agent-Native, con su propio bucle, zona de pruebas, herramientas nativas y sesiones reanudables respaldadas por SQL."
+search: "agentes de aprovechamiento AgentHarness ai-sdk HarnessAgent Claude Código Codex Pi Cursor Mastra agente de codificación integrado resolveAgentHarness startAgentHarnessRun herramientas de host de espacio aislado de sesión reanudable"
+---
+
+# Aprovecha a los agentes
+
+> **¿Para quién es?** autores de hosts que conectan un tiempo de ejecución de codificación completo (código Claude,
+> Codex, Pi) en Agent-Native como agente. ¿Creando una aplicación? Empezar con
+> [Creating Templates](/docs/creating-templates).
+
+Un agente de aprovechamiento es un tiempo de ejecución de agente completo (código Claude, Codex, Pi y similares)
+que posee su propio bucle, espacio de trabajo, herramientas de archivos nativos, estado de sesión, compactación,
+modelo de aprobación y comportamiento de la zona de pruebas. Agent-Native los ejecuta a través del
+**`AgentHarness`** sustrato en `@agent-native/core/agent/harness`, transmite su
+eventos en la transcripción normal y persiste su sesión nativa en un hilo
+puede pausar y reanudar.
+
+Esto es diferente del agente de chat integrado y de traer tu propio chat
+tiempo de ejecución. El agente incorporado y `AgentEngine` son para un modelo de ida y vuelta
+debajo de `runAgentLoop`. Un arnés no es un proveedor `AgentEngine`: ejecuta su
+propio bucle de extremo a extremo, por lo que Agent-Native lo controla como una sesión, no como una sola
+llamada modelo.
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## ¿Qué documento de codificación quiero? {#which-doc}
+
+| Quieres...                                                                           | Usar                                         |
+| ------------------------------------------------------------------------------------ | -------------------------------------------- |
+| Ejecute Claude Code / Codex / Pi **como agente**, con su propio bucle + herramientas | **Aprovecha a los agentes** (esta página)    |
+| Renderizar un código Claude/estilo Codex **espacio de trabajo de codificación UI**   | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Cambiar el backend que ejecuta la **herramienta `run-code`**                         | [Adapters](/docs/sandbox-adapters)           |
+| Preparar una herramienta CLI (`gh`, `ffmpeg`) para que el agente la llame            | [Adapters](/docs/sandbox-adapters)           |
+
+Superficies adyacentes: coloque un agente que haya creado en otro lugar detrás del chat de Agent-Native
+UI con [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes); deja un
+llamada de host externo MCP a su aplicación a través de [External Agents](/docs/external-agents);
+El fondo generado/el subagente se ejecuta con [Custom Agents & Teams](/docs/agent-teams).
+
+## Arneses incorporados {#built-in}
+
+`registerBuiltinAgentHarnesses()` registra tres adaptadores respaldados por AI SDK
+`HarnessAgent`:
+
+| Nombre                       | Tiempo de ejecución | Caja de arena | Aprobaciones |
+| ---------------------------- | ------------------- | ------------- | ------------ |
+| `ai-sdk-harness:claude-code` | Código Claude       | sí            | sí           |
+| `ai-sdk-harness:codex`       | Codex               | sí            | no           |
+| `ai-sdk-harness:pi`          | Pi                  | no            | sí           |
+
+Sus paquetes de tiempo de ejecución son **dependencias de pares opcionales** y se cargan con pereza, por lo que
+la aplicación que nunca usa un arnés no paga por ello. Cada adaptador lleva un
+Pista `installPackage` (por ejemplo `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness` genera una instalación clara
+error si faltan los paquetes y `isAgentHarnessPackageInstalled(entry)`
+te permite comprobarlo primero.
+
+`registerBuiltinAgentHarnesses()` también registra los arneses [ACP](#acp)
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## Agentes ACP {#acp}
+
+Agent-Native puede actuar como [ACP](https://agentclientprotocol.com) (Cliente Agente
+Protocolo) **cliente** y maneja un agente de codificación local: Gemini CLI, Claude Code,
+o cualquier agente compatible con ACP, a través de este mismo sustrato. El agente se ejecuta como
+subproceso local que habla JSON-RPC delimitado por nueva línea sobre stdio; Editor de ACP
+↔ el modelo de agente tiene exactamente esta forma.
+
+Este adaptador tiene como alcance **codificación local**. El proceso hijo hereda el
+entorno principal, por lo que el agente reutiliza cualquier inicio de sesión local CLI que ya tenga
+(por ejemplo, autenticación `gemini` o `claude` en el directorio de inicio del usuario). No es un
+transporte alojado o en espacio aislado, y no es un transporte de chat/A2A, para esos,
+ver [Agent Surfaces](/docs/agent-surfaces).
+
+| Nombre            | Comando predeterminado                                 | Reanudable\* |
+| ----------------- | ------------------------------------------------------ | ------------ |
+| `acp`             | _(suministro `command`/`args` mediante configuración)_ | sí           |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp`         | sí           |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`               | sí           |
+
+\*El currículum funciona cuando el agente anuncia la capacidad `loadSession` y
+de lo contrario, se degrada a una sesión nueva.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+El transporte de protocolo (`@zed-industries/agent-client-protocol`) es opcional
+dependencia cargada de forma perezosa a través de la sugerencia `installPackage`, al igual que la IA SDK
+arneses. El propio binario del agente (`@google/gemini-cli`,
+`@zed-industries/claude-code-acp`, …) es un CLI externo independiente; los ajustes preestablecidos
+ejecútelo a través de `npx` y el comando/argumentos permanecerán anulables porque el agente ACP
+las banderas de entrada aún evolucionan.
+
+`permissionMode` se asigna a ACP `session/request_permission` usando la llamada de herramienta
+escriba los informes del agente: las lecturas siempre se ejecutan, las ediciones se ejecutan en `allow-edits` y
+Todo lo que sea riesgoso indica a menos que `allow-all`. Las aprobaciones aparecen como de costumbre
+Eventos `approval-request`. El adaptador sirve para `fs/read_text_file` y
+`fs/write_text_file` contra el espacio de trabajo de la sesión (rechazando rutas de escape
+it) y las escrituras emiten eventos `file-change`; Los métodos de terminal no se anuncian,
+entonces el agente usa su propio shell.
+
+## Autenticación Codex: código UI frente a entornos sandbox de arnés {#codex-auth}
+
+Hay dos superficies Codex y se autentican de forma diferente:
+
+- **Agent-Native Código/Escritorio** ejecuta `codex exec` en la máquina del usuario. Si
+  el usuario ha ejecutado `codex login`, esta ejecución local reutiliza cualquier ChatGPT
+  La suscripción o la clave API autentican los informes Codex CLI instalados a través de
+  `codex login status`.
+- **`ai-sdk-harness:codex`** carga `@ai-sdk/harness-codex`, que impulsa Codex
+  dentro del arenero del arnés a través de `@openai/codex-sdk`. No lo hace en silencio
+  heredar el inicio de sesión `~/.codex` del escritorio del usuario porque la zona de pruebas puede ser remota
+  o aislado. Para zonas de pruebas privadas o de confianza, regístrese con `codexCliAuth: true`;
+  Agent-Native copia el archivo de autenticación local Codex CLI en el entorno de pruebas antes del
+  se inicia el arnés. Para entornos sandbox alojados o compartidos, configure API-key/gateway
+  autenticación en su lugar.
+
+Entonces, si alguien pregunta qué paquete lleva la ruta Codex OAuth: para codificación local
+sesiones, use `@agent-native/core` / Desktop más el instalado
+`@openai/codex` CLI y `codex login`. Para `ai-sdk-harness:codex` en zona de pruebas,
+use la opción de suscripción explícita `codexCliAuth` al copiar ese inicio de sesión en el sandbox
+es aceptable.
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` lee `CODEX_HOME/auth.json` o `~/.codex/auth.json`. Para
+apunta a un inicio de sesión local diferente, pasa
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` o
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## Registrarse y resolver {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` devuelve un `AgentHarnessAdapter`. El
+El `config` opcional se envía a la fábrica del adaptador, para los adaptadores AI SDK
+que se asigna a `AiSdkHarnessAdapterOptions` (`label`, `description`,
+`permissionMode`, `harnessOptions`, `agentOptions` y Codex únicamente
+`codexCliAuth`). Utilice `listAgentHarnesses()` para enumerar para qué está registrado
+un recolector.
+
+## Correr un giro {#run-a-turn}
+
+`startAgentHarnessRun` conecta una sesión de arnés con el administrador de ejecución compartido
+ciclo de vida. Crea (o reutiliza) la sesión nativa, la conserva y la transmite
+gira, traduce cada evento de arnés en eventos de transcripción y separa el
+estado reanudable cuando se completa el turno.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun` devuelve el `ActiveRun` del administrador de ejecución, por lo que el turno
+aparece a través de las rutas de ejecución existentes, la transcripción y la cancelación al igual que
+cualquier otro agente ejecutado. Pase un `session` ya creado en lugar de `createSession`
+para continuar una sesión que estás manteniendo en la memoria.
+
+## Sesiones y currículum {#sessions}
+
+Un arnés posee un estado de sesión nativo de larga duración. Agent-Native lo persiste en SQL
+para que un hilo pueda sobrevivir a través de turnos, procesos e implementaciones. El `resumeState`
+es **opaco**: Agent-Native lo guarda y lo devuelve, pero nunca lo inspecciona ni
+lo interpreta.
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+La tienda también expone `saveAgentHarnessSession`, `updateAgentHarnessSession`,
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped` y `ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun` llama a las rutas de guardar/actualizar/detener por usted; alcanzarlos
+directamente sólo en un host personalizado.
+
+## Herramientas y permisos del host {#host-tools}
+
+Un arnés trae sus propias herramientas nativas (lectura, edición, escritura, shell, etc.), por lo que
+**No** vuelves a exponer la edición de archivos como herramientas host. Pase sólo un **estrecho,
+conjunto intencional** de Agent-Native actions a `createSession.tools` cuando
+quiero que el arnés llegue a operaciones específicas de la aplicación y mantenga `defineAction`
+autenticación, contexto de solicitud, tiempos de espera, truncamiento y metadatos de solo lectura intactos cuando
+Sí,
+
+`permissionMode` indica lo que el arnés puede hacer sin aprobación:
+
+| Modo          | Significado                                                                      |
+| ------------- | -------------------------------------------------------------------------------- |
+| `allow-reads` | Predeterminado. Las lecturas se ejecutan; ediciones y mensaje arriesgado actions |
+| `allow-edits` | Se ejecutan lecturas y ediciones; otro aviso arriesgado actions                  |
+| `allow-all`   | Sin control de aprobación                                                        |
+
+Cuando un arnés se detiene para su aprobación, emite un evento `approval-request` y el
+La sesión está marcada como `idle` con la aprobación pendiente registrada, por lo que UI puede
+sacarlo a la superficie y continuar según la decisión del usuario. Ver
+[Human Approval](/docs/human-approval) para la superficie de aprobación.
+
+## Eventos {#events}
+
+Una sesión de aprovechamiento transmite valores `AgentHarnessEvent`, que Agent-Native
+se traduce a la transmisión estándar `AgentChatEvent` con
+`agentHarnessEventToAgentChatEvents`. La unión del evento cubre `text-delta`,
+`thinking-delta`, `activity`, `tool-start`, `tool-done` (que pueden llevar un
+Carga útil `mcpApp` para widgets nativos), `approval-request`, `file-change`,
+`compaction`, `usage`, `error` y `done`. Porque los resultados de la herramienta fluyen a través del
+misma traducción, los widgets nativos con acción declarada aún se muestran - ver
+[Native Chat UI](/docs/native-chat-ui).
+
+## Ejecuciones en segundo plano y el UI {#background-runs}
+
+Aproveche el proyecto en la forma `BackgroundAgentRun` compartida con
+`createAgentHarnessBackgroundAgentController()` y están disponibles a través del
+rutas de ejecución existentes como `goalId=agent-harness`. Eso significa un Claude de larga duración
+El código o la sesión Codex aparecen en las mismas superficies de ejecución en segundo plano y de transcripción
+como Agent Teams y otros adaptadores, con `listAgentHarnessBackgroundRuns`,
+`listAgentHarnessBackgroundTranscriptEvents`, `getAgentHarnessBackgroundRun` y
+`stopAgentHarnessBackgroundRun` disponible para hosts personalizados.
+
+## Adaptadores personalizados {#custom-adapters}
+
+Para empaquetar un tiempo de ejecución que no es uno de los integrados, implemente
+`AgentHarnessAdapter` y regístrelo. El adaptador declara sus capacidades y
+crea sesiones; una sesión expone `streamTurn` y `continueTurn` opcional,
+`approve`, `detach`, `stop` y `destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+Mantenga el paquete de ejecución opcional con una importación dinámica en `createSession` y un
+Pista `installPackage`. Para arneses de codificación respaldados por puentes, se requiere un
+proveedor de zona de pruebas/espacio de trabajo en lugar de ejecutar un agente de codificación arbitrario en el
+proceso de host: consulte [Sandbox Adapters](/docs/sandbox-adapters). El adaptador AI SDK
+(`createAiSdkHarnessAdapter`, respaldado por `HarnessAgent` de `@ai-sdk/harness`) es
+una implementación de este contrato, no la abstracción pública.
+
+## No {#donts}
+
+- No agregue el código Claude, Codex, Cursor, Mastra o Pi como `AgentEngine`. Ellos
+  poseer su bucle; ejecutar uno bajo `AgentEngine.stream()` ejecuta el bucle dos veces
+  y pierde la semántica del ciclo de vida de la sesión.
+- No reproduzcas el historial de chat completo de Agent-Native en un arnés en cada turno. Currículum
+  la sesión de arnés con su `resumeState` en su lugar.
+- No almacene `resumeState` en `application_state`. Pertenece al arnés
+  tabla de sesión SQL.
+- No expongas todas las acciones de la aplicación a cada sesión de aprovechamiento de forma predeterminada. Dale un
+  conjunto de herramientas pequeño e intencionado.
+
+## Documentos relacionados {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui): pon tu propio agente detrás del chat UI con `AgentChatRuntime`.
+- [Agent Surfaces](/docs/agent-surfaces): elige sin cabeza, chat, sidecar o aplicación completa.
+- [Agent-Native Code UI](/docs/code-agents-ui): la superficie del espacio de trabajo de codificación reutilizable.
+- [Custom Agents & Teams](/docs/agent-teams): ejecuciones en segundo plano y delegación de subagente.
+- [Sandbox Adapters](/docs/sandbox-adapters): backends de ejecución conectables para arneses de codificación.
+- [Human Approval](/docs/human-approval): uso del arnés de superficie de aprobación.

package/docs/content/locales/es-ES/human-approval.md

@@ -0,0 +1,86 @@
+---
+title: "Aprobaciones Human-in-The-Loop"
+description: "Pause el agente antes de que se ejecute una acción de alta consecuencia: la puerta de aprobación de necesidades de defineAction emite un evento de aprobación_required, el humano lo aprueba y solo entonces se ejecuta la herramienta."
+---
+
+# Aprobaciones Human-in-The-Loop
+
+La mayoría de actions deberían simplemente ejecutarse. Algunos (enviar un correo electrónico, cargar una tarjeta, eliminar una cuenta) son externos y difíciles de deshacer, y no desea que el agente los haga de forma autónoma. Para ellos, `defineAction` tiene una **puerta de aprobación** opcional: cuando el agente intenta llamar a la acción, el bucle se detiene, muestra una autorización de Aprobación/Denegación al humano y ejecuta la acción _solo_ después de que el humano aprueba esa llamada específica.
+
+> [!WARNING]
+> Mantenga las aprobaciones raras. Cada acción cerrada es una parada brusca en el ciclo del agente: interrumpe la ejecución y exige un viaje de ida y vuelta humano. Utilice `needsApproval` solo para operaciones orientadas al exterior, difíciles de deshacer y de verdaderas consecuencias importantes. Si se encuentra activando lecturas o escrituras de rutina, lo está haciendo mal. El valor predeterminado es **desactivado** y casi todas las acciones deberían dejarlo desactivado.
+
+## La puerta `needsApproval` {#needs-approval}
+
+Establezca `needsApproval` en un `defineAction`. Acepta un booleano o un predicado:
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`**: siempre requiere aprobación.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`**: requiere aprobación solo cuando el predicado devuelve verdadero. Puerta condicional, p.e. solo para destinatarios externos o solo por encima de un umbral en dólares:
+
+  ```ts
+  necesita aprobación: (args) => !args.to.endsWith("@su-empresa.com"),
+  ```
+
+  Mantenga el predicado puro y rápido. **El cierre falla**: si el predicado arroja resultados, el marco lo trata como "se requiere aprobación" en lugar de ejecutar silenciosamente una acción de altas consecuencias.
+
+Cuando se omite `needsApproval`, el comportamiento no cambia byte por byte; no hay ningún coste adicional en la ruta común.
+
+Esto funciona de la misma manera para actions de estilo `parameters` heredado y actions basado en esquema, y para los llamantes del agente en la aplicación, los subagentes, A2A y MCP (cada superficie de agente se enruta a través del mismo bucle).
+
+## Cómo se detiene el bucle {#loop}
+
+Cuando el agente llama a una acción cerrada y esta llamada específica **no** ya ha sido aprobada, el bucle **no** ejecuta `run()`. En su lugar:
+
+1. Resuelve la puerta. Para un predicado, llama a `needsApproval(input, ctx)`; un lanzamiento se trata como "debe aprobarse" (falla cerrada).
+2. Emite un evento `tool_start` (para que el UI muestre la llamada) seguido inmediatamente por un evento **`approval_required`** y luego detiene el giro. El efecto secundario de la acción nunca ocurre.
+
+El evento `approval_required` incluye todo lo que el cliente necesita para ofrecer un beneficio:
+
+| Campo         | Tipo     | Notas                                                                        |
+| ------------- | -------- | ---------------------------------------------------------------------------- |
+| `tool`        | `string` | El nombre de la acción que el agente intentó llamar.                         |
+| `input`       | objeto   | Los argumentos que pasó el agente.                                           |
+| `approvalKey` | `string` | **Clave estable** el cliente responde para aprobar _esta llamada exacta_.    |
+| `toolCallId`  | `string` | El ID de llamada de herramienta del lado del modelo, cuando esté disponible. |
+
+El `approvalKey` se deriva de manera determinista del nombre de la herramienta más su entrada, por lo que la misma llamada lógica siempre produce la misma clave. El modelo nunca lo ve ni lo configura; es simplemente un apretón de manos entre el marco y la capacidad de aprobación del ser humano.
+
+La herramienta en pausa devuelve un resultado que le indica al modelo que el giro está en pausa y que no debe volver a intentarlo, por lo que el modelo no gira.
+
+## Cómo lo aprueba el ser humano {#approve}
+
+En `approval_required`, el chat UI muestra una opción **Aprobar/Denegar** en la llamada de herramienta en pausa. Esto se conecta automáticamente en `AssistantChat`; no lo crea por plantilla.
+
+- **Aprobar** vuelve a emitir el turno (un mensaje de continuación ordinario) que lleva la clave de la llamada en `approvedToolCalls: [approvalKey]`. En el turno reemitido, la puerta ve la llave en el conjunto aprobado y permite que esa llamada específica se ejecute normalmente.
+- **Denegar** descarta la prestación localmente; no se vuelve a emitir nada, por lo que la acción nunca se ejecuta.
+
+`approvedToolCalls` es un campo en la solicitud de chat (`AgentChatRequest.approvedToolCalls`). Las claves que no están presentes en él permanecen en pausa: aprobar una llamada nunca aprueba otras sin comprender. Debido a que la clave está dirigida al contenido, una aprobación autoriza _esa llamada con esos argumentos_; si el modelo luego propone un envío diferente, se trata de una nueva clave y una nueva aprobación.
+
+## De un extremo a otro {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+El uso canónico (e intencionalmente raro) de esta puerta en el marco es la acción `send-email` de la plantilla de correo, que configura `needsApproval: true` para que el agente pueda redactar y hacer cola libremente, pero nunca pueda enviar un mensaje sin que un humano apruebe el envío específico.
+
+## Relacionado
+
+- [**Actions**](/docs/actions#needs-approval): la superficie `defineAction` completa, incluido `outputSchema` para validar los valores de retorno.
+- [**Security**](/docs/security): cuándo alcanzar una puerta de aprobación o cuándo ocultar una acción al modelo.
+- [**Mail template**](/docs/template-mail): `send-email` es el ejemplo de referencia.

package/docs/content/locales/es-ES/internationalization.md

@@ -1,15 +1,18 @@
 ---
 title: "Internacionalización"
-description: "Localiza apps Agent Native con catálogos compartidos, selector de idioma, fallback al navegador y contenido de docs por locale."
+description: "Localice aplicaciones Agent Native con catálogos de configuración regional compartidos, un selector de idioma, respaldo de idioma del navegador y contenido de documentos compatible con la configuración regional."
 ---
 
 # Internacionalización
 
-Las apps Agent Native pueden localizar la UI del framework y de las plantillas con el runtime compartido `@agent-native/core/client/i18n`. El framework guarda la elección de idioma del usuario en settings SQL, la expone como actions y vuelve a English cuando una app aún no tradujo una cadena.
+Las aplicaciones Agent Native pueden localizar el marco y la plantilla UI a través del recurso compartido
+Tiempo de ejecución `@agent-native/core/client/i18n`. El marco almacena el usuario
+elección de idioma en la configuración de SQL, lo expone como actions y vuelve a
+Inglés cuando una aplicación aún no ha traducido una cadena.
 
-## Runtime {#runtime}
+## Tiempo de ejecución
 
-Usa el provider a través de `AppProviders`:
+Utilice el proveedor a través de `AppProviders`:
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,9 +30,12 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()` define el `lang`, `dir` y `window.__AGENT_NATIVE_LOCALE__` iniciales antes de que React hidrate. Las rutas SSR públicas pueden llamar a `resolveLocaleFromRequest()` desde `@agent-native/core/server` y pasar el locale/catalog resuelto al script para evitar desajustes de hydration.
+`getLocaleInitScript()` establece los valores iniciales `lang`, `dir` y
+`window.__AGENT_NATIVE_LOCALE__` antes de que React se hidrate. Las rutas públicas SSR pueden
+llamar a `resolveLocaleFromRequest()` desde `@agent-native/core/server` y pasar el
+Resolvió la configuración regional/catálogo en ese script para evitar discrepancias en la hidratación.
 
-## Catálogos {#catalogs}
+## Catálogos
 
 Cada plantilla localizada mantiene catálogos en `app/i18n/`:
 
@@ -52,51 +58,88 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-Incluye siempre `en-US`. Importa dinámicamente los catálogos que no sean English para que cada usuario descargue solo el locale activo. Los locale codes admitidos son `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` y `ar-SA`.
+Siempre incluya `en-US`. Importación dinámica de catálogos que no están en inglés para que sean solo usuarios
+descargar la configuración regional activa. Los códigos locales admitidos son `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` y `ar-SA`.
 
-## UI {#ui}
+## UI
 
-Usa `useT()` para textos de interfaz y `<LanguagePicker />` en settings:
+Utilice `useT()` para cadenas de interfaz y coloque `<LanguagePicker />` en la aplicación
+Página `/settings`. Las aplicaciones de la barra lateral deben exponer **Configuración** en la barra lateral de la aplicación;
+el ícono de idioma del encabezado es solo un acceso directo.
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-Usa `useFormatters()` para fechas, números, tiempo relativo y listas. No pongas formatos sensibles al locale dentro de cadenas traducidas.
+El control "Configuración del agente" debería abrir la pestaña Configuración de la barra lateral derecha del agente
+para modelo, clave API, automatización, voz y otros controles a nivel de marco.
+Las aplicaciones pueden duplicar configuraciones de marco de alto valor en su propia página de configuración
+cuando la configuración es central para la aplicación, pero la pestaña de configuración de la barra lateral sigue siendo la
+fuente de la verdad.
+
+Utilice `useFormatters()` para fechas, números, tiempo relativo y listas. No poner
+Formato de fecha/número sensible a la configuración regional dentro de las cadenas de traducción.
 
-## Contenido del sitio de docs {#docs-site-content}
+## Contenido del sitio de documentos {#docs-site-content}
 
-Las páginas públicas de docs usan el mismo core provider, pero con `persistPreference={false}` para que el tráfico anónimo use localStorage y el idioma del navegador en vez de actions de settings SQL. La fuente English queda en `packages/core/docs/content/*.md`. Las páginas localizadas que sobrescriben esa fuente viven en `packages/core/docs/content/locales/<locale>/<slug>.md`.
+Las páginas de documentos públicos utilizan el mismo proveedor principal, pero con
+`persistPreference={false}`, por lo que el tráfico de documentos anónimos utiliza localStorage y
+idioma del navegador en lugar de configuración de SQL actions. La fuente inglesa permanece en
+`packages/core/docs/content/*.md`. Las anulaciones de páginas localizadas aparecen junto a ella en
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-Usa los mismos BCP-47 locale codes que los catálogos de app. Conserva el mismo slug que la fuente English, preserva anclas estables con `{#anchor}` en headings traducidos y no traduzcas routes, action names, protocol fields, env vars ni provider names. Si un locale no tiene Markdown traducido para una página, el sitio cae a English para esa página mientras sigue localizando la navegación y el chrome.
+Utilice los mismos códigos locales BCP-47 que los catálogos de aplicaciones. Mantenga la misma babosa que el
+Fuente en inglés, conserva anclajes estables con `{#anchor}` en los títulos traducidos,
+y dejar rutas, nombres de acciones, campos de protocolo, variables de entorno y nombres de proveedores
+sin traducir. Si una configuración regional no tiene Markdown traducido para una página, el sitio de documentos
+vuelve al inglés para esa página sin dejar de localizar la navegación y Chrome.
 
-## Actions y persistencia {#actions-and-persistence}
+## Actions y persistencia
 
-Cada app hereda:
+Cada aplicación hereda:
 
-- `get-localization-preference` — lee el `{ locale }` del usuario actual
-- `set-localization-preference` — define `"system"` o un locale admitido
+- `get-localization-preference`: lee el `{ locale }` del usuario actual
+- `set-localization-preference`: configure `"system"` o una configuración regional compatible
 
-El valor durable vive en settings SQL con alcance de usuario bajo `localization`. `localStorage` solo se usa para pre-hydration y fallback anónimo. El locale activo se refleja en application state como contexto ambiental para que los agents vean el idioma actual de la interfaz.
+El valor duradero se encuentra en la configuración SQL definida por el usuario en `localization`.
+`localStorage` solo se usa para prehidratación y respaldo anónimo. El activo
+La configuración regional se refleja en el estado de la aplicación como contexto ambiental para que los agentes puedan ver
+el idioma actual de la interfaz.
 
-## Guard {#guard}
+## Guardia
 
-Ejecuta:
+Ejecutar:
 
 ```bash
 pnpm guard:i18n-catalogs
 ```
 
-El guard verifica nombres de archivos locale admitidos, key parity, placeholder parity, stale keys y categorías plurales CLDR mediante `Intl.PluralRules`. Revisa estructura, no calidad de traducción; las cadenas de alta visibilidad necesitan revisión humana.
+El guardia verifica los nombres de archivos locales admitidos, la paridad de claves, la paridad de marcadores de posición,
+claves obsoletas y categorías plurales de CLDR hasta `Intl.PluralRules`. Se comprueba
+estructura, no calidad de la traducción; Las cadenas de alta visibilidad todavía necesitan humanos
+revisar.
 
-No traduzcas identificadores estables como action names, routes, enum values, app-state keys, database values, protocol fields, env var names o provider names.
+No traduzca identificadores estables como nombres de acciones, rutas, valores de enumeración,
+claves de estado de aplicación, valores de base de datos, campos de protocolo, nombres de var de entorno o proveedor
+nombres.