@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,332 @@
+---
+title: "Autenticación"
+description: "Mejor integración de autenticación con correo electrónico/contraseña, proveedores sociales, organizaciones y credenciales de portador MCP."
+---
+
+# Autenticación
+
+Las aplicaciones nativas del agente utilizan [Better Auth](https://better-auth.com) para la autenticación con un diseño que prioriza la cuenta. Los usuarios crean una cuenta en la primera visita y obtienen una identidad real desde el primer día.
+
+## Descripción general {#overview}
+
+La autenticación se configura automáticamente a través de `autoMountAuth(app)` en el complemento del servidor de autenticación. Hay tres modos:
+
+- **Predeterminado:** Mejor autenticación con correo electrónico/contraseña + proveedores sociales. Página de incorporación mostrada en la primera visita.
+- **MCP OAuth remoto:** OAuth 2.1 estándar para hosts MCP como el código Claude y los conectores ChatGPT.
+- **Personalizado:** Traiga su propia autenticación a través de la devolución de llamada `getSession`.
+
+```an-diagram title="Three ways in, one session" summary="Browser visitors, programmatic MCP clients, and custom providers all resolve to the same AuthSession that downstream scoping reads."
+{
+  "html": "<div class=\"auth-modes\"><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default</span><strong>Better Auth</strong><small class=\"diagram-muted\">email/password &middot; Google &middot; GitHub</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Remote MCP OAuth</span><strong>OAuth 2.1 + PKCE</strong><small class=\"diagram-muted\">Claude Code, ChatGPT connectors</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Custom</span><strong>getSession callback</strong><small class=\"diagram-muted\">Clerk &middot; Auth0 &middot; Firebase</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill ok\">AuthSession</span><small class=\"diagram-muted\">email &middot; orgId &middot; orgRole</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Request context &amp; data scoping</div></div>",
+  "css": ".auth-modes{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.auth-modes .diagram-col{display:flex;flex-direction:column;gap:10px}.auth-modes .diagram-card{display:flex;flex-direction:column;gap:4px;padding:10px 12px}.auth-modes .diagram-arrow{font-size:22px;line-height:1}.auth-modes .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+El flujo del navegador es el mismo flujo de Better Auth en todas partes: **no hay derivación de autenticación del desarrollador** y `getSession()` nunca recurre a un centinela `local@localhost`. Lo que cambia entre entornos es la fricción en el registro, no el muro de inicio de sesión:
+
+| Medio ambiente                      | Comportamiento de la primera carga                                                                              | Verificación por correo electrónico                                               |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Desarrollador local**             | Crea automáticamente una cuenta de desarrollador desechable y te registra (sin muro de inicio de sesión)        | Omitido de forma predeterminada (y cuando no hay proveedor de correo electrónico) |
+| **Control de calidad/vista previa** | Registro normal, pero se puede omitir la verificación para que los evaluadores no esperen el correo electrónico | Saltar con `AUTH_SKIP_EMAIL_VERIFICATION=1`                                       |
+| **Producción**                      | Registro/inicio de sesión de autenticación normal y mejorada                                                    | Obligatorio (cuando se configura un proveedor de correo electrónico)              |
+
+Algunas banderas sintonizan esto; Los detalles completos se encuentran en la tabla [Environment Variables](#environment-variables):
+
+- `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1`: utilice la página de registro normal en el desarrollador local en lugar de la cuenta de desarrollo automático.
+- `AUTH_DISABLED=true`: omita el inicio de sesión/registro por completo y ejecute cada solicitud como un usuario compartido (solo desarrollo local, vistas previas y demostraciones, nunca producción con usuarios reales).
+- `AUTH_MODE=local`: afecta solo a CLI/identidad del agente (con el que se ejecuta el usuario de desarrollo `pnpm action`); **no** es una omisión de inicio de sesión en el navegador.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "`AUTH_DISABLED=true` runs **every request as one shared user**. Use it only for local dev, previews, or demos — never in production with real users, where it would expose all data to anyone."
+}
+```
+
+## Mejor autenticación (predeterminada) {#better-auth}
+
+De forma predeterminada, Better Auth potencia la autenticación. Proporciona:
+
+- Registro e inicio de sesión por correo electrónico/contraseña
+- Proveedores de redes sociales (Google, GitHub y más de 35 personas más)
+- Organizaciones con roles e invitaciones
+- Tokens JWT para acceso a API y A2A
+- Compatibilidad con tokens de portador para clientes programáticos
+
+Se montan mejores rutas de autenticación en `/_agent-native/auth/ba/*`. El marco también proporciona puntos finales compatibles con versiones anteriores:
+
+- `GET /_agent-native/auth/session` — obtener la sesión actual
+- `POST /_agent-native/auth/login` — inicio de sesión con correo electrónico/contraseña
+- `POST /_agent-native/auth/register` — crear cuenta
+- `POST /_agent-native/auth/logout`: cerrar sesión
+
+## Reinos de las cookies {#cookie-realms}
+
+El dominio de la cookie de sesión sigue la forma de implementación, por lo que las aplicaciones que comparten una
+Inicio de sesión compartido de base de datos/origen y aplicaciones que no permanecen aisladas:
+
+| Forma de implementación                                 | Reino de las cookies                                                                                                                                                     |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Aplicación independiente                                | Aislado por aplicación por slug (`APP_NAME` o nombre del paquete en el desarrollo local); Prefijo `an` estable en producción                                             |
+| Modo de espacio de trabajo (`AGENT_NATIVE_WORKSPACE=1`) | Un ámbito compartido: las aplicaciones del espacio de trabajo comparten un origen y una base de datos                                                                    |
+| Subdominios personalizados de la misma base de datos    | Aceptar cookies compartidas con `COOKIE_DOMAIN`                                                                                                                          |
+| Alojado propio (`*.agent-native.com`)                   | Espacio de nombres aislado por aplicación (cada una tiene su propia base de datos de autenticación); `COOKIE_DOMAIN=.agent-native.com` se ignora de forma predeterminada |
+
+Las aplicaciones alojadas propias tienen cada una su propia base de datos de autenticación, por lo que el inicio de sesión entre aplicaciones
+pasa por [Cross-App SSO](/docs/cross-app-sso) en lugar de una cookie compartida.
+Estas implementaciones deben proporcionar `APP_NAME` o una aplicación derivable URL (`APP_URL`, `URL`,
+`DEPLOY_PRIME_URL` o `DEPLOY_URL`); de lo contrario, el inicio falla en lugar de caer
+volver al nombre compartido `an_session`. Compartir intencionalmente una base de datos de autenticación
+en todos los subdominios, establezca `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` al lado
+`COOKIE_DOMAIN`.
+
+## Cuentas de control de calidad {#qa-accounts}
+
+Las pruebas y el desarrollo local omiten la verificación del correo electrónico de registro de forma predeterminada, por lo que
+puede crear cuentas de correo electrónico/contraseña reales sin esperar en una bandeja de entrada. Forzar
+verificación local mientras prueba ese flujo, configure `AUTH_SKIP_EMAIL_VERIFICATION=0`.
+
+Para entornos de control de calidad alojados donde los evaluadores necesitan cuentas reales pero no deben esperar
+al enviar el correo electrónico, configure:
+
+```bash
+AUTH_SKIP_EMAIL_VERIFICATION=1
+```
+
+Cuando se establece esta marca, el registro de correo electrónico/contraseña no requiere correo electrónico
+no se envía la verificación y el correo electrónico de verificación de registro. Úselo solo para control de calidad
+o obtener una vista previa de los entornos y nombrar cuentas de prueba con una dirección `+qa`
+(`name+qa@example.com`) para que sean fáciles de identificar.
+
+## Proveedores sociales {#social-providers}
+
+Establezca variables de entorno para habilitar el inicio de sesión social. Better Auth los detecta automáticamente:
+
+```bash
+# Google OAuth
+GOOGLE_SIGN_IN_CLIENT_ID=your-low-scope-sign-in-client-id
+GOOGLE_SIGN_IN_CLIENT_SECRET=your-low-scope-sign-in-client-secret
+
+# Backwards-compatible fallback, and provider OAuth credentials for templates
+# that connect to Google APIs such as Gmail or Calendar.
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-client-id
+GITHUB_CLIENT_SECRET=your-client-secret
+```
+
+Las plantillas que utilizan `createGoogleAuthPlugin()` muestran una página "Iniciar sesión con Google". La devolución de llamada de Google OAuth gestiona automáticamente los enlaces profundos móviles para aplicaciones nativas.
+
+Prefiere `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` para normal
+inicio de sesión de la aplicación. Ese cliente debe solicitar solo ámbitos de identidad. Mantener
+`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` para integraciones de productos que necesiten
+Alcances de Google API o como respaldo heredado cuando una implementación no se ha dividido
+todavía. Las aplicaciones de estilo Correo y Calendario deben utilizar clientes de su propio proveedor OAuth para que
+Las pantallas de consentimiento de alto alcance no afectan el inicio de sesión en aplicaciones genéricas.
+
+### OAuth Firma de estado {#oauth-state-secret}
+
+Establezca `OAUTH_STATE_SECRET` en un valor aleatorio de más de 32 caracteres en producción para que los sobres de estado de OAuth (Google, Atlassian, Zoom) estén firmados por HMAC con una clave dedicada independiente de cualquier secreto de terceros. Consulte [Security — OAuth State Signing](/docs/security#oauth-state) para conocer todos los requisitos y el modelo de amenazas.
+
+## Organizaciones {#organizations}
+
+El marco proporciona un sistema de organización integrado. Este es el módulo `org/` propio del marco, respaldado por las tablas `organizations` y `org_members`, no el complemento de organización de Better Auth, que intencionalmente no está registrado. Cada aplicación admite:
+
+- Creando organizaciones
+- Invitar a miembros con roles (`owner`, `admin`, `member`)
+- Cambiar organización activa
+- Alcance de datos por organización a través de columnas `org_id`
+
+Se realiza un seguimiento de la organización activa en la sesión como `session.orgId`, y el cambio de organización cambia los datos que ven el usuario y el agente. El alcance de los datos en sí ocurre más abajo en la pila; consulte [Security & Data Scoping](/docs/security#data-scoping) para conocer el proceso completo de `session.orgId → AGENT_ORG_ID → SQL` y los guardias de acceso. Los documentos [Multi-Tenancy](/docs/multi-tenancy) cubren la superficie de gestión de organizaciones.
+
+## Fichas portadoras estáticas MCP {#access-tokens}
+
+`ACCESS_TOKEN` y `ACCESS_TOKENS` no son autenticación del navegador y no hacen que una aplicación sea privada. Permanecen solo como credenciales de portador estáticas para clientes MCP/connect que no pueden usar el flujo OAuth.
+
+```bash
+# Single token
+ACCESS_TOKEN=my-secret-token
+
+# Multiple tokens
+ACCESS_TOKENS=token1,token2,token3
+```
+
+La configuración de estas variables nunca muestra una página de inicio de sesión simbólica para los visitantes. El inicio de sesión web permanece en Better Auth o en su proveedor `getSession` personalizado.
+
+## Remoto MCP OAuth {#remote-mcp-oauth}
+
+El punto final MCP de cada aplicación puede actuar como un recurso MCP protegido estándar. Los clientes compatibles con OAuth se pueden configurar solo con el MCP URL remoto:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+```
+
+Las solicitudes MCP no autenticadas devuelven un desafío `WWW-Authenticate` que apunta a `/.well-known/oauth-protected-resource`. Luego, el cliente descubre los metadatos OAuth de la aplicación, registra dinámicamente un cliente público, abre la página de autorización de la aplicación e intercambia un código de autorización con PKCE para acceder y actualizar tokens.
+
+```an-diagram title="Remote MCP OAuth handshake" summary="An OAuth-capable client bootstraps from just the MCP URL — challenge, discovery, dynamic registration, then a PKCE code exchange."
+{
+  "html": "<div class=\"mcp-flow\"><div class=\"diagram-node\">1 &middot; MCP request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node warn\">2 &middot; 401 challenge<br><small class=\"diagram-muted\">WWW-Authenticate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">3 &middot; Discover metadata<br><small class=\"diagram-muted\">.well-known</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">4 &middot; Register client<br><small class=\"diagram-muted\">dynamic, public</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">5 &middot; Authorize + PKCE<br><small class=\"diagram-muted\">code exchange</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">6 &middot; Access + refresh<br><small class=\"diagram-muted\">audience-bound</small></div></div>",
+  "css": ".mcp-flow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.mcp-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.mcp-flow .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+Los tokens de acceso se firman con `A2A_SECRET` cuando se configuran; de lo contrario, `BETTER_AUTH_SECRET`. Llevan la identidad de usuario/organización firmada y los alcances `mcp:read`, `mcp:write` y/o `mcp:apps`, y están vinculados a la audiencia al recurso MCP exacto URL. Los tokens de actualización se almacenan solo como hashes y rotan en cada actualización. Las llamadas a herramientas y las lecturas de recursos de las aplicaciones MCP se ejecutan dentro del mismo contexto de solicitud que el usuario que inició sesión; el iframe integrado de la aplicación MCP nunca recibe tokens OAuth sin procesar.
+
+`npx @agent-native/core@latest connect <url> --client claude-code` escribe la entrada MCP exclusiva de URL para este flujo estándar. Para los clientes que no pueden realizar MCP OAuth remoto, use la página Conectar o el respaldo `npx @agent-native/core@latest connect --token <token>` para escribir una entrada explícita de token de portador.
+
+## Traiga su propia autenticación {#byoa}
+
+Pase una devolución de llamada personalizada `getSession` para usar cualquier proveedor de autenticación (Clerk, Auth0, Firebase, etc.):
+
+```ts
+// server/plugins/auth.ts
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  getSession: async (event) => {
+    // Your custom auth logic here
+    const session = await myAuthProvider.verify(event);
+    if (!session) return null;
+    return { email: session.email };
+  },
+  publicPaths: ["/api/webhooks"],
+});
+```
+
+## Aplicaciones de espacios de trabajo públicos {#public-workspace-apps}
+
+Las aplicaciones de Workspace son internas de forma predeterminada. Para permitir que visitantes anónimos carguen un público
+sitio mientras mantiene las páginas de administración detrás de la autenticación, declara el acceso a la ruta en
+`apps/<id>/package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+Para la forma inversa, mantenga la audiencia interna predeterminada y exponga solo
+páginas públicas específicas:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+`publicPaths` y `protectedPaths` usan coincidencia de prefijos, por lo que `"/admin"` también
+cubre `"/admin/users"`. Estas configuraciones solo abren la navegación de la página. Marco
+rutas (`/_agent-native/*`) y las rutas API personalizadas (`/api/*`) aún requieren autenticación
+a menos que la aplicación agregue explícitamente esos prefijos a
+`createAuthPlugin({ publicPaths: [...] })`.
+
+## Sesión API {#session-api}
+
+El objeto de sesión devuelto por `getSession(event)` tiene esta forma:
+
+```ts
+interface AuthSession {
+  email: string; // User's email (primary identifier)
+  userId?: string; // Better Auth user ID
+  token?: string; // Session token
+  name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
+  orgId?: string; // Active organization ID
+  orgRole?: string; // Role in active org (owner/admin/member)
+}
+```
+
+En el cliente, utilice el enlace `useSession()`:
+
+```ts
+import { useSession } from "@agent-native/core/client";
+
+function MyComponent() {
+  const { session, isLoading } = useSession();
+  if (isLoading) return <p>Loading...</p>;
+  if (!session) return <p>Not signed in</p>;
+  return <p>Hello, {session.email}</p>;
+}
+```
+
+## Iniciar sesión con devolución URL {#sign-in-return-url}
+
+Las plantillas con **páginas públicas** (enlaces compartidos, incrustaciones, páginas de marketing) a menudo necesitan un CTA en la página que solicita a los espectadores anónimos que inicien sesión y los devuelve a la página en la que se encontraban. El marco proporciona un único punto de entrada para esto:
+
+```
+/_agent-native/sign-in?return=<same-origin-path>
+```
+
+Cuando un espectador anónimo accede a este URL, se muestra la página de inicio de sesión del marco. Después de un inicio de sesión exitoso (cualquier flujo: token, correo electrónico/contraseña o Google OAuth), el espectador pasa a la ruta 302 a `return`.
+
+El parámetro `return` se valida como **ruta del mismo origen**. Las referencias de ruta de red (`//evil.com/...`), los esquemas URL absolutos, `data:`/`javascript:` y los caracteres de control integrados recurren a `/`. La ruta validada se reconstruye a partir del analizador URL, no se repite desde la entrada.
+
+**De un componente React:**
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+function SignInCta() {
+  const onClick = () => {
+    const ret = window.location.pathname + window.location.search;
+    window.location.href =
+      "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+  };
+  return <Button onClick={onClick}>Sign in</Button>;
+}
+```
+
+### Rutas privadas marcadas
+
+Cuando un usuario anónimo navega directamente a una ruta privada como `/dashboard`, el marco ya muestra la página de inicio de sesión en ese URL; después de iniciar sesión correctamente, la página se vuelve a cargar y el usuario llega a `/dashboard`. No se necesita manipulación especial; esto funciona para token, correo electrónico/contraseña y **y** Google OAuth.
+
+### Detrás de escena: Google OAuth
+
+Ambos flujos (el punto de entrada explícito `/_agent-native/sign-in` y el caso de ruta marcada) enhebran el retorno URL a través del estado OAuth. El estado está firmado por HMAC, por lo que no se puede falsificar en tránsito. En la devolución de llamada, la devolución URL se revalida como del mismo origen antes de la redirección, por lo que una clave de firma filtrada aún no se puede convertir en un oráculo de redirección abierta.
+
+Si su plantilla envuelve `/_agent-native/google/auth-url` directamente (por ejemplo, las plantillas de correo y calendario lo hacen, para ampliar el alcance), acepte una consulta `?return=<path>` y reenvíela a través del formulario de objeto de opciones de `encodeOAuthState`:
+
+```ts
+const returnUrl = getQuery(event).return;
+const state = encodeOAuthState({
+  redirectUri,
+  desktop,
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
+```
+
+La ruta `/_agent-native/google/auth-url` predeterminada hace esto automáticamente; solo se anula si su plantilla necesita un manejo personalizado de OAuth.
+
+## Variables de entorno {#environment-variables}
+
+| Variables                               | Propósito                                                                                                                                                                                                                   |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`                    | Clave de firma para una mejor autenticación (generada automáticamente si no está configurada)                                                                                                                               |
+| `AUTH_SKIP_EMAIL_VERIFICATION`          | Establezca en `1` en entornos de control de calidad/vista previa para permitir que los registros de correo electrónico/contraseña se realicen sin verificación; El desarrollo/prueba local se salta de forma predeterminada |
+| `AUTH_DISABLED`                         | Establezca en `true` o `1` para omitir el inicio de sesión/registro; todas las solicitudes se ejecutan como un usuario compartido (solo desarrollo/vista previa local, no para producción con usuarios reales)              |
+| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Establezca en `1` para deshabilitar el inicio de sesión automático de localhost en una base de datos de desarrollo nueva                                                                                                    |
+| `AUTH_MODE`                             | `local` resuelve solo la identidad de CLI/agente (con la que se ejecuta el usuario de desarrollo `pnpm action`); nunca una omisión de inicio de sesión del navegador                                                        |
+| `COOKIE_DOMAIN`                         | Opte por las cookies de sesión compartida entre subdominios de la misma base de datos (consulte [Cookie Realms](#cookie-realms))                                                                                            |
+| `AGENT_NATIVE_WORKSPACE`                | `1` se ejecuta en modo de espacio de trabajo: un ámbito de sesión compartido entre aplicaciones de espacio de trabajo                                                                                                       |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | Configurar con `COOKIE_DOMAIN` para compartir una base de datos de autenticación entre subdominios propios                                                                                                                  |
+| `OAUTH_STATE_SECRET`                    | Clave HMAC dedicada para envolventes de estado OAuth (ver [Security — OAuth State Signing](/docs/security#oauth-state))                                                                                                     |
+| `GOOGLE_SIGN_IN_CLIENT_ID`              | ID de cliente OAuth de Google de alcance reducido preferido para iniciar sesión en la aplicación                                                                                                                            |
+| `GOOGLE_SIGN_IN_CLIENT_SECRET`          | Secreto OAuth de Google de bajo alcance preferido para iniciar sesión en la aplicación                                                                                                                                      |
+| `GOOGLE_CLIENT_ID`                      | Respaldo de inicio de sesión de Google antiguo e ID de cliente del proveedor OAuth para integraciones de Google API                                                                                                         |
+| `GOOGLE_CLIENT_SECRET`                  | Respaldo de inicio de sesión de Google antiguo y secreto del proveedor OAuth para integraciones de Google API                                                                                                               |
+| `GITHUB_CLIENT_ID`                      | Habilitar GitHub OAuth                                                                                                                                                                                                      |
+| `GITHUB_CLIENT_SECRET`                  | GitHub OAuth secreto                                                                                                                                                                                                        |
+| `ACCESS_TOKEN`                          | Reserva de portador estático para clientes MCP/connect; no autenticación del navegador                                                                                                                                      |
+| `ACCESS_TOKENS`                         | Reservas de portadores estáticos separados por comas para clientes MCP/connect; no autenticación del navegador                                                                                                              |
+| `A2A_SECRET`                            | Secreto compartido para la verificación de identidad entre aplicaciones A2A firmada por JWT y, cuando esté presente, firma de token de acceso MCP OAuth                                                                     |

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

@@ -0,0 +1,268 @@
+---
+title: "Automatizaciones"
+description: "Automatizaciones programadas y activadas por eventos con condiciones de lenguaje natural"
+---
+
+# Automatizaciones
+
+Una **automatización** es una regla: _cuando sucede X, haz Y_, descrita en lenguaje natural. El agente ejecuta las instrucciones, por lo que las automatizaciones tienen acceso a cada acción, herramienta y servidor MCP que el agente puede usar en un chat interactivo.
+
+Las automatizaciones amplían [recurring jobs](/docs/recurring-jobs) con **activadores de eventos**, **condiciones de lenguaje natural** y **HTTP saliente** a través de la herramienta `web-request`. Utilizan el mismo formato de archivo `jobs/<name>.md`, almacenamiento y flujo de trabajo de "creación de tres formas" que los trabajos recurrentes; consulte [Recurring Jobs](/docs/recurring-jobs#job-file) para conocer el formato compartido. Esta página cubre solo las novedades de las automatizaciones basadas en eventos.
+
+```an-diagram title="When X happens, do Y" summary="An event fires on the bus, an optional natural-language condition gates it, and the agent runs the automation body with full tool access."
+{
+  "html": "<div class=\"auto-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Event</span><small class=\"diagram-muted\"><code>calendar.booking.created</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Condition</span><small class=\"diagram-muted\">Haiku checks: &ldquo;email ends with @builder.io&rdquo;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">Agent runs the body</span><small class=\"diagram-muted\">actions &middot; web-request &middot; MCP &middot; sub-agents</small></div></div>",
+  "css": ".auto-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.auto-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.auto-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## Dos tipos de activadores {#trigger-types}
+
+| Tipo       | Se dispara cuando                                                | Campo clave       |
+| ---------- | ---------------------------------------------------------------- | ----------------- |
+| `schedule` | Una expresión cron coincide (igual que los trabajos recurrentes) | `schedule` (cron) |
+| `event`    | Se emite un evento coincidente en el bus de eventos del marco    | `event` (nombre)  |
+
+Los desencadenantes de eventos pueden incluir un `condition`, una cadena en lenguaje natural evaluada por Haiku con respecto a la carga útil del evento antes del envío. Si la condición no coincide, la automatización se omite silenciosamente.
+
+## Crear automatizaciones {#creating}
+
+### Preguntando al agente
+
+> "Cuando alguien reserva una reunión con un correo electrónico @builder.io, envíame un mensaje en Slack."
+
+El agente descubre eventos disponibles, confirma el plan y escribe la automatización por usted.
+
+### Desde la configuración UI
+
+Las automatizaciones aparecen en el panel de configuración. Los usuarios pueden verlos, habilitarlos/deshabilitarlos y eliminarlos allí.
+
+La tercera ruta (escribir el archivo `jobs/<name>.md` a mano mediante `resourcePut`) funciona exactamente igual que para [recurring jobs](/docs/recurring-jobs#creating). Para una automatización basada en eventos, agregue el frontmatter de activación de eventos a continuación al mismo archivo. Un trabajo desencadenado por evento establece `schedule: ""` y proporciona `triggerType: event`, un nombre de `event` y un `condition` opcional:
+
+```an-annotated-code title="An event-triggered automation"
+{
+  "filename": "jobs/slack-on-builder-booking.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"\"\nenabled: true\ntriggerType: event\nevent: calendar.booking.created\ncondition: \"attendee email ends with @builder.io\"\nmode: agentic\ndomain: calendar\nrunAs: creator\n---\nSend a Slack message to #sales with the booking details.\nUse the web-request tool to POST to ${keys.SLACK_WEBHOOK}.",
+  "annotations": [
+    { "lines": "2", "label": "No cron", "note": "Event triggers set `schedule` to `\"\"` — the cron field stays empty." },
+    { "lines": "4-5", "label": "The trigger", "note": "`triggerType: event` plus the `event` name subscribes this automation to the bus." },
+    { "lines": "6", "label": "Gate", "note": "An optional natural-language `condition`, evaluated by Haiku against the payload before dispatch." },
+    { "lines": "12", "label": "Server-side secret", "note": "`${keys.SLACK_WEBHOOK}` is resolved server-side — the raw value never enters the agent's context." }
+  ]
+}
+```
+
+## Antecedentes de la automatización {#frontmatter}
+
+Las automatizaciones comparten todos los campos del [recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter). Estos campos adicionales controlan los desencadenadores de eventos, las condiciones y el modo de ejecución:
+
+| Campo         | Tipo                             | Predeterminado | Descripción                                                                                                                                                                                                  |
+| ------------- | -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"`   | Cómo se activa la automatización                                                                                                                                                                             |
+| `event`       | cadena                           | _(opcional)_   | Nombre del evento al que suscribirse (solo activadores de eventos)                                                                                                                                           |
+| `condition`   | cadena                           | _(opcional)_   | Condición del lenguaje natural evaluada antes del envío                                                                                                                                                      |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`    | Bucle de agente completo. (`"deterministic"` está reservado pero aún no se ha implementado; las automatizaciones que lo configuran se omiten. Utilice `"agentic"` para todas las automatizaciones actuales). |
+| `domain`      | cadena                           | _(opcional)_   | Etiqueta de agrupación (correo, calendario, clips, etc.)                                                                                                                                                     |
+
+Para un desencadenador de evento, `schedule` es `""` (vacío); para un desencadenador de programación, lleva la expresión cron. El despachador también escribe los mismos campos administrados `lastRun` / `lastStatus` / `lastError` que escribe el programador, además de un estado `"skipped"` cuando una condición se evalúa como falsa.
+
+## El autobús de eventos {#event-bus}
+
+Las integraciones registran eventos en el momento de carga del módulo. El bus valida las cargas útiles con respecto a las definiciones de [Standard Schema](https://standardschema.dev) y las envía a los suscriptores.
+
+### Eventos integrados {#built-in-events}
+
+| Evento                 | Fuente                                               |
+| ---------------------- | ---------------------------------------------------- |
+| `test.event.fired`     | Manual / `manage-automations` acción=prueba de fuego |
+| `agent.turn.completed` | Chat del agente                                      |
+| `calendar.*`           | Integración de calendario                            |
+| `clip.*`               | Integración de clips                                 |
+| `mail.*`               | Integración de correo                                |
+
+Llame a `manage-automations` con `action=list-events` desde el agente para ver todos los eventos registrados con descripciones y esquemas de carga útil para la plantilla actual.
+
+### Emitir eventos personalizados {#emitting-events}
+
+Registrar un tipo de evento en un complemento de servidor y luego emitirlo desde actions o controladores de webhook:
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register the event type (once, at module load)
+registerEvent({
+  name: "order.completed",
+  description: "A customer completed an order",
+  payloadSchema: z.object({
+    orderId: z.string(),
+    customerEmail: z.string(),
+    total: z.number(),
+  }),
+  example: {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit(
+  "order.completed",
+  {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+  { owner: "steve@builder.io" },
+);
+```
+
+El `owner` en los alcances de metadatos de emisión que activan las automatizaciones; solo se evalúan las automatizaciones que pertenecen al mismo usuario (o automatizaciones compartidas).
+
+## Condiciones {#conditions}
+
+Las condiciones son cadenas de lenguaje natural evaluadas por Claude Haiku frente a la carga útil del evento. Esta es una clasificación de sí/no, no una tarea de generación.
+
+- **Condición vacía o faltante** = incondicional (siempre se activa).
+- Los resultados se memorizan (SHA-256 de condición + carga útil) con un caché TTL de 5 minutos y LRU de 500 entradas.
+- La carga útil se trunca a 4000 caracteres antes de enviarla a Haiku.
+- En caso de falla de API, la condición se evalúa como `false` (valor predeterminado seguro: se omite la automatización).
+
+Ejemplos de condiciones:
+
+- `"attendee email ends with @builder.io"`
+- `"the order total is greater than $100"`
+- `"the message contains the word 'urgent'"`
+
+## La herramienta de solicitud web {#web-request}
+
+Las automatizaciones utilizan la herramienta `web-request` para HTTP saliente. Admite marcadores de posición `${keys.NAME}` en URL, encabezados y cuerpo:
+
+```
+POST to ${keys.SLACK_WEBHOOK}
+
+Headers: {"Authorization": "Bearer ${keys.API_TOKEN}"}
+
+Body: {"text": "New booking from ${attendeeEmail}"}
+```
+
+Los marcadores de posición se resuelven **del lado del servidor** después de que el agente emite la llamada a la herramienta; el valor secreto sin procesar nunca ingresa al contexto del agente.
+
+### Parámetros {#web-request-params}
+
+| Parámetro    | Tipo   | Predeterminado | Descripción                                                |
+| ------------ | ------ | -------------- | ---------------------------------------------------------- |
+| `url`        | cadena | —              | URL completo. Puede contener referencias a `${keys.NAME}`. |
+| `method`     | cadena | `GET`          | Método HTTP (GET, POST, PUT, PATCH, DELETE, HEAD).         |
+| `headers`    | cadena | `{}`           | JSON objeto de encabezados. Puede contener `${keys.NAME}`. |
+| `body`       | cadena | —              | Cuerpo de la solicitud. Puede contener `${keys.NAME}`.     |
+| `timeout_ms` | número | 15000          | Tiempo de espera en milisegundos (máximo 30000).           |
+
+## Claves {#keys}
+
+Las claves son secretos ad hoc creados por los usuarios o el agente para su uso en automatización (por ejemplo, `SLACK_WEBHOOK`, `HUBSPOT_API_KEY`). Se diferencian de los secretos registrados (`registerRequiredSecret`) en que no tienen metadatos definidos por plantilla ni paso de incorporación.
+
+- Creado a través de la configuración UI o `/_agent-native/secrets/adhoc` API.
+- Cada clave puede tener una **lista de permitidos URL** que restringe a qué orígenes se puede enviar la clave (coincidencia a nivel de origen).
+- El valor bruto nunca se expone a la IA; solo aparecen marcadores de posición `${keys.NAME}` en el contexto del agente.
+- La resolución retrocede del ámbito del usuario al ámbito del espacio de trabajo, para que los usuarios puedan anular las claves compartidas.
+
+## Herramientas del agente {#agent-tools}
+
+Se accede a todas las operaciones de automatización a través de una única herramienta `manage-automations` con un parámetro `action`:
+
+| Acción        | Propósito                                                                             |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `list-events` | Descubre todos los eventos registrados con descripciones y esquemas de carga útil     |
+| `list`        | Enumerar todas las automatizaciones con estado; filtrar por dominio o habilitado      |
+| `define`      | Crear una nueva automatización (nombre, tipo de activador, evento, condición, cuerpo) |
+| `update`      | Actualizar una automatización existente (habilitada, condición, cuerpo)               |
+| `delete`      | Eliminar una automatización (siempre confirma primero con el usuario)                 |
+| `fire-test`   | Emitir un evento `test.event.fired` para validar automatizaciones                     |
+
+Herramienta adicional: `web-request`: HTTP saliente con sustitución de `${keys.NAME}`.
+
+## Puntos finales API {#api}
+
+| Punto final                            | Método | Descripción                                      |
+| -------------------------------------- | ------ | ------------------------------------------------ |
+| `/_agent-native/automations`           | GET    | Enumerar todas las automatizaciones (analizadas) |
+| `/_agent-native/automations/fire-test` | POST   | Emitir un evento `test.event.fired`              |
+| `/_agent-native/secrets/adhoc`         | GET    | Lista de claves ad-hoc (sin valores)             |
+| `/_agent-native/secrets/adhoc`         | POST   | Crear o actualizar una clave ad-hoc              |
+| `/_agent-native/secrets/adhoc/:name`   | DELETE | Eliminar una clave ad hoc                        |
+
+```an-api title="Fire a test event"
+{
+  "method": "POST",
+  "path": "/_agent-native/automations/fire-test",
+  "summary": "Emit a test.event.fired event to validate event-triggered automations",
+  "description": "Confirm an automation's wiring and condition without waiting for a real provider event. Equivalent to the `manage-automations` action `fire-test`.",
+  "responses": [
+    { "status": "200", "description": "Event emitted; matching automations are dispatched through the normal condition + ownership path." }
+  ]
+}
+```
+
+## Cómo funciona el despacho {#dispatch}
+
+```an-diagram title="The dispatch path" summary="From a fired event to a completed agent run, gated by ownership scope and the natural-language condition."
+{
+  "html": "<div class=\"disp\"><div class=\"diagram-box accent\">event fired on the bus</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">match</span><small class=\"diagram-muted\">load enabled automations subscribed to this event name</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">scope</span><small class=\"diagram-muted\">keep only those owned by the event's owner (or shared)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">condition</span><small class=\"diagram-muted\">Haiku yes/no on the payload &mdash; false &rarr; <code>skipped</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">run</span><small class=\"diagram-muted\"><code>runAgentLoop</code> with body as prompt, payload as context, 5-min timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code></small></div></div>",
+  "css": ".disp{display:flex;flex-direction:column;gap:6px;max-width:540px}.disp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.disp .diagram-box{align-self:flex-start}.disp .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+## Ejemplo {#example}
+
+**Usuario:** "Cuando alguien reserva con un correo electrónico @builder.io, envíame un mensaje en Slack."
+
+**Flujo de agentes:**
+
+1. Llama a `manage-automations` con `action=list-events`: encuentra `calendar.booking.created`.
+2. Confirma el plan con el usuario.
+3. Llama a `manage-automations` con `action=define`:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @builder.io`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+4. La automatización se guarda como `jobs/slack-on-builder-booking.md` y comienza a escucharse inmediatamente.
+
+## Más ejemplos {#more-examples}
+
+### Notificar mediante webhook cuando se comenta un plan
+
+Pregúntele al agente del plan: _"Cuando alguien agrega un comentario humano en un plan, POST a
+notificación a mi webhook."_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+Establezca `NOTIFY_WEBHOOK` en cualquier punto final HTTP: un webhook entrante Slack, un genérico
+servicio de notificaciones o un receptor personalizado. La herramienta `web-request` resuelve
+`${keys.NOTIFY_WEBHOOK}` del lado del servidor; el URL sin procesar nunca aparece en el del agente
+contexto. Ver [Visual Plans — Events and notifications](/docs/template-plan#events)
+para obtener la referencia completa de la carga útil de `plan.commented` y los cuatro eventos del plan.
+
+## ¿Qué sigue?
+
+- [**Recurring Jobs**](/docs/recurring-jobs): las automatizaciones activadas por programación reutilizan el mismo programador
+- [**Actions**](/docs/actions): las automatizaciones pueden invocar cualquier acción registrada a través del bucle del agente
+- [**Security**](/docs/security): validación de entradas y manejo de secretos
+- [**Visual Plans — Events**](/docs/template-plan#events): referencia de eventos de planificación y recetas de automatización