@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/es-ES/observability.md

@@ -0,0 +1,294 @@
+---
+title: "Observabilidad"
+description: "Seguimientos de agentes, evaluaciones, comentarios, experimentos A/B y el panel integrado, todo sin configuración."
+---
+
+# Observabilidad del agente
+
+Cada aplicación nativa del agente obtiene capacidad de observación desde el primer momento. Los seguimientos, las evaluaciones automatizadas, los comentarios de los usuarios y los experimentos A/B funcionan sin configuración: todos los datos residen en la propia base de datos SQL de la aplicación.
+
+Esta página cubre las métricas de _calidad del agente_: seguimientos, costos, evaluaciones y comentarios almacenados en su base de datos. Para análisis de _producto_ (los eventos de su aplicación que fluyen a PostHog/Mixpanel/Amplitude), consulte [Tracking](/docs/tracking).
+
+## Tres cosas llamadas "evaluaciones"/"observabilidad": ¿cuáles quiero? {#which}
+
+Estas tres páginas son fáciles de confundir. Elija según la pregunta que esté haciendo:
+
+| Página                                                               | La pregunta que responde                                   | Cuando se ejecuta                                        | Preocupación   |
+| -------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------- | -------------- |
+| **Evaluaciones de observabilidad** (esta página, la pestaña _Evals_) | "¿Cómo les fue a mis tiradas de producción reales?"        | Pasivo, después de cada ejecución (muestra del juez LLM) | Calidad        |
+| **[CI Eval Gate](/docs/evals)** (`*.eval.ts`)                        | "¿El agente hace lo correcto en esta entrada fija?"        | Activo, determinista, una puerta de implementación/CI    | Calidad        |
+| **[Observational Memory](/docs/observational-memory)**               | "¿Este hilo largo se queda barato y dentro de la ventana?" | Compactación de fondo en hilos largos                    | Costo/contexto |
+
+La observabilidad y la puerta de evaluación de CI puntúan _calidad_ pero desde extremos opuestos: puntuación pasiva post-hoc del tráfico real frente a comprobaciones activas de aprobación/rechazo en entradas fijas. La Memoria Observacional no está relacionada con la calidad; se trata del costo simbólico y la presión de la ventana de contexto.
+
+## Qué se captura automáticamente {#captured}
+
+Cuando un usuario envía un mensaje, el marco registra automáticamente:
+
+- **Uso de token**: entrada, salida, lectura de caché, escritura de caché
+- **Costo**: calculado a partir del recuento de tokens y el precio del modelo
+- **Latencia**: duración total y tiempo por llamada de herramienta
+- **Llamadas a herramientas**: qué actions se invocaron, estado de éxito/error, duración
+- **Evaluaciones automatizadas**: 5 puntuaciones de calidad calculadas después de cada ejecución
+
+No se necesitan cambios de código. La instrumentación se conecta al `production-agent.ts` de forma transparente.
+
+```an-diagram title="Every run feeds the loop" summary="One agent run produces a trace, automated scores, and a feedback hook — all stored in the app's own SQL and surfaced on the dashboard. Experiments split traffic across config variants."
+{
+  "html": "<div class=\"obs-loop\"><div class=\"diagram-node\">Agent run<br><small class=\"diagram-muted\">production-agent.ts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Captured automatically</span><small class=\"diagram-muted\">tokens &middot; cost &middot; latency &middot; tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Traces &amp; spans</div><div class=\"diagram-box\">Evals (5 scorers + LLM judge)</div><div class=\"diagram-box\">Feedback &amp; frustration index</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Dashboard<br><small class=\"diagram-muted\">scoped to the signed-in user</small></div></div>",
+  "css": ".obs-loop{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.obs-loop .diagram-col{display:flex;flex-direction:column;gap:8px}.obs-loop .diagram-arrow{font-size:22px;line-height:1}.obs-loop .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## El panel {#dashboard}
+
+Agregue el panel a cualquier plantilla con una única ruta:
+
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+Todos los datos se limitan al usuario que inició sesión; hoy no hay una vista de administrador entre usuarios.
+
+El panel tiene 5 pestañas:
+
+| Pestaña                 | Qué muestra                                                                                                           |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Descripción general** | Métricas clave: ejecuciones, coste, latencia, tasa de éxito de la herramienta, satisfacción, puntuación de evaluación |
+| **Conversaciones**      | Lista de seguimiento con desglose de tramos individuales (agent_run, llm_call, tool_call)                             |
+| **Evaluaciones**        | Puntuaciones de evaluación automatizadas por criterios, tendencias a lo largo del tiempo                              |
+| **Experimentos**        | Lista de pruebas A/B con insignias de estado, resultados de variantes con intervalos de confianza                     |
+| **Comentarios**         | Aprobación/desaprobación, desglose de categorías, puntuaciones de frustración                                         |
+
+## Comentarios de los usuarios {#feedback}
+
+### Comentarios explícitos
+
+Los botones de pulgar hacia arriba/abajo se muestran en línea en cada mensaje de agente en el chat UI. El pulgar hacia abajo abre una ventana emergente de categoría (Inexacto, No útil, Herramienta incorrecta, Demasiado lento). Esto se conecta automáticamente a `AssistantChat.tsx`.
+
+### Retroalimentación implícita (índice de frustración)
+
+El marco calcula un índice de frustración (0-100) a partir de señales de conversación:
+
+| Señal                 | Peso | Qué detecta                                     |
+| --------------------- | ---- | ----------------------------------------------- |
+| Reformulación         | 30%  | El usuario repite mensajes similares            |
+| Reintentar patrones   | 20%  | "Inténtalo de nuevo", "no, eso está mal"        |
+| Abandono              | 20%  | La sesión finaliza poco después de la respuesta |
+| Sentimiento           | 15%  | Patrones de lenguaje negativos                  |
+| Tendencia de longitud | 15%  | Longitud de mensajes en disminución             |
+
+Interpretación de la puntuación: 0-20 = saludable, 20-40 = fricción, 40-60 = insatisfecho, 60+ = sesión interrumpida.
+
+## Evaluaciones automatizadas {#evals}
+
+Cinco puntuadores deterministas se ejecutan después de cada ejecución del agente:
+
+| Criterios           | Qué mide                                                                             | Rango de puntuación |
+| ------------------- | ------------------------------------------------------------------------------------ | ------------------- |
+| `tool_success_rate` | % de llamadas a herramientas sin errores                                             | 0-1                 |
+| `step_efficiency`   | Penaliza las iteraciones excesivas de LLM para ejecuciones que utilizan herramientas | 0-1                 |
+| `latency_score`     | Normalizado frente a 10s/línea base de herramienta                                   | 0-1                 |
+| `cost_efficiency`   | Normalizado respecto de la línea base de costos                                      | 0-1                 |
+| `error_recovery`    | ¿Se recuperó el agente de los errores de la herramienta?                             | 0 o 1               |
+
+### LLM-como-juez (opcional)
+
+Habilite la evaluación basada en LLM de muestra configurando `evalSampleRate`:
+
+```ts
+import { putSetting } from "@agent-native/core/settings";
+
+await putSetting("observability-config", {
+  enabled: true,
+  evalSampleRate: 0.05, // 5% of runs
+});
+```
+
+Los criterios personalizados utilizan rúbricas de lenguaje natural:
+
+```ts
+const criteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = unhelpful, 0.5 = partially helpful, 1.0 = fully resolved",
+};
+```
+
+## Experimentos A/B {#experiments}
+
+Pruebe diferentes modelos, temperaturas o configuraciones de agente:
+
+```ts
+// Create via API
+POST /_agent-native/observability/experiments
+{
+  "name": "model-a-vs-b",
+  "variants": [
+    { "id": "control", "weight": 50, "config": { "model": "<your-model-id>" } },
+    { "id": "treatment", "weight": 50, "config": { "model": "<other-model-id>" } }
+  ],
+  "metrics": ["cost", "latency", "satisfaction"]
+}
+
+// Start the experiment
+PUT /_agent-native/observability/experiments/:id
+{ "status": "running" }
+```
+
+Utilice los identificadores de modelo reales que acepta su motor en lugar de `<your-model-id>` / `<other-model-id>` (los nombres de los modelos cambian con frecuencia; consulte con su proveedor/motor para conocer los identificadores actuales). El bucle del agente resuelve automáticamente la variante del usuario y aplica la anulación de la configuración. La asignación utiliza hash consistente: el mismo usuario siempre obtiene la misma variante.
+
+```an-diagram title="Consistent-hash variant assignment" summary="Each user hashes to a stable variant, the loop applies that variant's config override, and results roll up per variant with confidence intervals."
+{
+  "html": "<div class=\"exp\"><div class=\"diagram-node\">User id<br><small class=\"diagram-muted\">consistent hash</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill\">control &middot; 50%</span><small class=\"diagram-muted\">config override A</small></div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">treatment &middot; 50%</span><small class=\"diagram-muted\">config override B</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Results per variant<br><small class=\"diagram-muted\">cost &middot; latency &middot; satisfaction</small></div></div>",
+  "css": ".exp{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.exp .diagram-col{display:flex;flex-direction:column;gap:8px}.exp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.exp .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Configuración {#config}
+
+Todas las configuraciones se almacenan en la clave `observability-config`:
+
+```ts
+{
+  enabled: true,           // Master switch
+  capturePrompts: false,   // Store prompt content in traces
+  captureToolArgs: false,  // Store action input arguments
+  captureToolResults: false, // Store action results
+  evalSampleRate: 0,       // 0-1, fraction of runs to LLM-judge
+  exporters: []            // OTLP export targets
+}
+```
+
+```an-callout
+{
+  "tone": "info",
+  "body": "Content is **redacted by default** — only token counts, costs, and timing are stored. `capturePrompts`, `captureToolArgs`, and `captureToolResults` are opt-in; turn them on only when you need prompt/argument content for debugging."
+}
+```
+
+## Puntos finales API {#api}
+
+Todo montado automáticamente en `/_agent-native/observability/`:
+
+| Método | Ruta                       | Propósito                                 |
+| ------ | -------------------------- | ----------------------------------------- |
+| GET    | `/`                        | Estadísticas generales                    |
+| GET    | `/traces`                  | Enumerar resúmenes de seguimiento         |
+| GET    | `/traces/:runId`           | Detalle de seguimiento (resumen + tramos) |
+| GET    | `/traces/:runId/evals`     | Evaluaciones para una ejecución           |
+| POST   | `/feedback`                | Enviar comentarios                        |
+| GET    | `/feedback`                | Enumerar comentarios                      |
+| GET    | `/feedback/stats`          | Agregación de comentarios                 |
+| GET    | `/satisfaction`            | Puntuaciones de satisfacción              |
+| GET    | `/evals/stats`             | Estadísticas de evaluación                |
+| POST   | `/experiments`             | Crear experimento                         |
+| GET    | `/experiments`             | Enumerar experimentos                     |
+| GET    | `/experiments/:id`         | Obtener detalles del experimento          |
+| PUT    | `/experiments/:id`         | Actualizar experimento                    |
+| POST   | `/experiments/:id/results` | Calcular resultados                       |
+| GET    | `/experiments/:id/results` | Obtener resultados                        |
+
+Todos los puntos finales admiten los parámetros de consulta `?since=N` (marca de tiempo ms) y `?limit=N`.
+
+## Exportar a plataformas externas {#export}
+
+Envíe seguimientos a Langfuse, Datadog, Grafana o cualquier backend compatible con OTel:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer sk-..." },
+    },
+  ],
+});
+```
+
+El marco emite convenciones semánticas `gen_ai.*` compatibles con la especificación OpenTelemetry GenAI.
+
+## Extensiones de OpenTelemetry {#otel}
+
+Aparte de la configuración `exporters` anterior (que envía los seguimientos internos a un punto final OTLP), el bucle del agente también puede emitir **intervalos de OpenTelemetry en vivo** para cada ejecución, llamada de modelo y llamada de herramienta, de modo que un host que ya ejecuta un recopilador OTel ve la actividad del agente junto con el resto de sus seguimientos distribuidos.
+
+Esta capa es **opcional y no operativa de forma predeterminada**:
+
+- `@opentelemetry/api` es una **dependencia opcional**. Si no está instalado, los asistentes se degradan a operaciones silenciosas y no operativas; aquí nada de lo anterior se incluye en el ciclo del agente.
+- Incluso cuando el paquete API _está_ presente, incluye un rastreador no operativo predeterminado. Los intervalos solo se vuelven reales una vez que el **host registra un `TracerProvider`** (a través de `@opentelemetry/sdk-node` o similar). El marco deliberadamente **no** depende de los pesados paquetes SDK/exporter ni registra un proveedor por sí mismo: la instrumentación es habilitada por la aplicación integrada.
+
+Entonces, el costo cuando no ha conectado OTel es un par de lecturas de propiedades almacenadas en caché por llamada. Para activarlo, instale el paquete api más su SDK y registre un proveedor al iniciar el servidor de la misma manera que lo haría con cualquier otro servicio de Node.
+
+El bucle del agente emite tres tipos de intervalos:
+
+| Lapso       | Cuándo                           | Atributos                                                         |
+| ----------- | -------------------------------- | ----------------------------------------------------------------- |
+| `agent.run` | una vez por ejecución de agente  | `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model` |
+| `tool.call` | una vez por invocación de acción | `tool.name`, más estado de éxito/error                            |
+| `llm.call`  | por llamada de modelo            | tiempo + estado correcto/error                                    |
+
+Los tramos finalizan con el estado OK/ERROR y registran el mensaje de error en caso de falla. Los valores de atributo cero/centinela se eliminan para que los intervalos no estén saturados de ruido. Esta capa OTel es puramente aditiva a las tablas internas `agent_trace_spans` / `agent_trace_summaries` que alimentan el tablero de arriba; ambas se producen a partir de los mismos eventos de ejecución.
+
+## Informe de errores (Sentry) {#sentry}
+
+Los errores del lado del servidor que escapan a los controladores de ruta Nitro se informan a Sentry cuando se configura un DSN. Sin él, el SDK no funciona silenciosamente, por lo que es seguro dejar las variables de entorno sin configurar en desarrollo. Los eventos del navegador y del servidor pueden ir al mismo proyecto Sentry; divídalos en proyectos separados solo cuando desee una separación operativa por propiedad, volumen, cuotas o enrutamiento de alertas.
+
+| Superficie         | SDK               | Var ambiente                                                 | Notas                                                                            |
+| ------------------ | ----------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Navegador / SPA    | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN`, `SENTRY_CLIENT_DSN` o `SENTRY_DSN` | Captura errores no controlados y rutas de navegación de cambio en el cliente.    |
+| Servidor Nitro     | `@sentry/node`    | `SENTRY_SERVER_DSN` o `SENTRY_DSN`                           | Captura respuestas 5xx y errores del ciclo de vida Nitro. Usuario por solicitud. |
+| `agent-native` CLI | `@sentry/node`    | _codificado_                                                 | Informes de fallos del binario CLI publicado; no configurable por el usuario.    |
+
+### Configuración del lado del servidor {#sentry-config}
+
+Configure `SENTRY_SERVER_DSN` o el `SENTRY_DSN` compartido en el entorno de implementación (panel de Netlify, secretos de Cloudflare, etc.). El marco monta automáticamente un complemento Nitro que:
+
+1. Llama a `Sentry.init` una vez al inicio (idempotente: es seguro llamar desde varios complementos).
+2. Resuelve el usuario a través de `getSession(event)` en cada solicitud de API/framework y adjunta `id` / `email` / `username` más una etiqueta `orgId` al alcance de aislamiento por solicitud de Sentry. Las rutas de recursos estáticos se omiten para evitar accesos adicionales a la base de datos.
+3. Captura cada ruta de marco 5xx con etiquetas `route`, `method` y `userAgent` con capacidad de búsqueda.
+
+Perillas opcionales:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (`0` flotante–`1`): opte por el seguimiento del rendimiento. El valor predeterminado es `0` (solo errores). Los valores no válidos se fijan en `0`.
+- `AGENT_NATIVE_RELEASE`: anula la etiqueta `release`. El valor predeterminado es `agent-native-server@<core-version>`.
+
+### Plantillas
+
+Cada plantilla hereda esto automáticamente: no hay nada que importar. Para las aplicaciones SSR, el servidor inyecta un pequeño script de configuración del navegador cuando `SENTRY_CLIENT_DSN`, `VITE_SENTRY_CLIENT_DSN` o `SENTRY_DSN` compartido está disponible en tiempo de ejecución, por lo que la captura del navegador no se limita al entorno de tiempo de compilación de Vite. Las plantillas que desean un comportamiento personalizado (etiquetas adicionales, DSN diferentes por plantilla, Sentry deshabilitado por completo) pueden anularse exportando su propio complemento desde `server/plugins/sentry.ts`:
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+El código DSN del CLI es intencional: el binario publicado para llamar a casa falla independientemente del entorno en el que se ejecute. El módulo de servidor nunca codifica un DSN porque se ejecuta dentro de los entornos del cliente donde los operadores deciden si los errores deben llegar a Sentry.
+
+### Privacidad y PII {#privacy}
+
+Tanto el servidor como CLI se inicializan con `sendDefaultPii: false` y un gancho `beforeSend` que elimina:
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (recopilado automáticamente sin consentimiento)
+- `contexts.runtime_env` (instantánea del entorno del proceso)
+- Cualquier evento cuyo tipo de excepción de nivel superior sea `ValidationError` (tratado como rechazo esperado de entrada del usuario, no como error).
+
+Los campos de identidad establecidos explícitamente a través de `setUser({ id, email, username })` se conservan.
+
+## ¿Qué sigue?
+
+- [**Tracking**](/docs/tracking): análisis de productos (PostHog, Mixpanel, Amplitude) para los eventos propios de tu aplicación
+- [**Actions**](/docs/actions): las operaciones que aparecen como llamadas a herramientas en los seguimientos
+- [**Security**](/docs/security): alcance de datos y manejo de credenciales

package/corpus/core/docs/content/locales/es-ES/observational-memory.md

@@ -0,0 +1,77 @@
+---
+title: "Memoria de observación"
+description: "Compactación de fondo de tres niveles (sin procesar recientes → observaciones → reflexiones) que mantiene los hilos largos del agente baratos y estables en el caché sin tocar las conversaciones cortas."
+---
+
+# Memoria de observación
+
+Un hilo de agente de larga duración acumula una transcripción enorme: cada mensaje, cada llamada a la herramienta, cada resultado. Reproducir toda esa historia en el modelo en cada turno es costoso y eventualmente arruina la ventana de contexto. **La memoria de observación (OM)** compacta la parte más antigua de un hilo largo en un resumen fechado y en capas para que el modelo aún sepa lo que sucedió (solo por una fracción del costo simbólico) mientras que los giros más recientes permanecen textuales.
+
+OM es completamente automático y está restringido al propietario. **Los subprocesos cortos no se ven afectados**: hasta que un subproceso cruza el primer umbral de compactación, OM no funciona y el contexto es byte por byte lo que sería sin él.
+
+## Los tres niveles {#tiers}
+
+OM representa un hilo largo de tres capas, desde la más destilada hasta la más reciente:
+
+| Nivel                               | Qué es                                                                                                                        |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Reflexiones**                     | Nivel más alto, condensado del registro de observación una vez que crece. El resumen extenso.                                 |
+| **Observaciones**                   | Entradas densas y fechadas que combinan una serie de mensajes sin procesar en un registro compacto de lo que sucedió.         |
+| **Mensajes sin procesar recientes** | Los últimos N turnos se mantienen **textualmente** (nunca se doblan) para que el agente siempre vea el contexto más reciente. |
+
+```an-diagram title="Three tiers, distilled to recent" summary="The older prefix folds into dated observations and a long-arc reflection; only the most recent turns stay verbatim."
+{
+  "html": "<div class=\"om\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Reflections</span><small class=\"diagram-muted\">long-arc summary, condensed from the observation log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observations</span><small class=\"diagram-muted\">dense, dated entries folding stretches of raw messages</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&uarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">Recent raw messages</span><small class=\"diagram-muted\">last N turns, kept <strong>verbatim</strong> — never folded</small></div></div>",
+  "css": ".om{display:flex;flex-direction:column-reverse;align-items:stretch;gap:8px}.om .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.om .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+En cada turno, el lado de lectura los ensambla en un único bloque `[Observational Memory]` autoetiquetado que reemplaza el prefijo anterior sin formato, mantiene intacta la ventana sin formato reciente y le indica al modelo que trate el registro compactado como autorizado (no rehaga el trabajo completado, confíe en las decisiones, nombres, fechas y estados registrados).
+
+## Cómo se ejecuta la compactación {#compaction}
+
+Dos pases se ejecutan como un paso de **disparar y olvidar, de mejor esfuerzo** _después_ de un giro limpio, por lo que nunca agregan latencia a la respuesta visible del usuario y cualquier falla se traga:
+
+1. **Observador**: una vez que los mensajes _no observados_ de un hilo superan el umbral del token de observación, los agrupa en una sola entrada de observación densa.
+2. **Reflector**: una vez que el registro de observación persistente supera el umbral del token de reflexión, condensa las observaciones en una reflexión de nivel superior.
+
+```an-diagram title="Two best-effort passes after a clean turn" summary="Each pass no-ops below its threshold, so running the compactor every turn is cheap. Failures are swallowed and never add latency."
+{
+  "html": "<div class=\"om-pass\"><div class=\"diagram-node\">Clean turn ends<br><small class=\"diagram-muted\">fire-and-forget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Observer</span><small class=\"diagram-muted\">unobserved tokens &gt; 30k? &rarr; fold into one observation</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Reflector</span><small class=\"diagram-muted\">observation log &gt; 40k? &rarr; condense into a reflection</small></div></div>",
+  "css": ".om-pass{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.om-pass .diagram-node,.om-pass .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.om-pass .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Ambos pasan el estado no operativo por debajo de sus umbrales, por lo que llamar al compactador después de cada turno es barato. Debido a que OM reemplaza el prefijo sin formato volátil con texto compacto estable, también mantiene el mensaje **caché estable** en todas las vueltas de un hilo largo.
+
+Los datos OM residen en la propia base de datos SQL de la aplicación, con alcance para el propietario (y la organización cuando esté presente): el mismo modelo de alcance que el resto del marco. Nunca se comparte entre usuarios.
+
+## Configuración {#config}
+
+Los valores predeterminados son conservadores. Un operador puede marcar la compactación en el momento de la implementación con las variables de entorno `AGENT_NATIVE_OM_*` (no es necesario volver a implementar el código de la aplicación); un valor no válido o faltante siempre vuelve al valor predeterminado nombrado.
+
+| Var ambiente                                  | Predeterminado | Qué controla                                                                                      |
+| --------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000`        | Fichas de mensajes no observados que hacen que el observador los combine en una sola observación. |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000`        | Fichas de registro de observación que activan el reflector para que se condense en un reflejo.    |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`           | Cuántos de los mensajes más recientes permanecen textuales (nunca incluidos en una observación).  |
+
+Los límites de salida de Observer y Reflector (4000/2000 tokens) evitan que una sola pasada de compactación arruine el presupuesto; se pueden ajustar en el código a través de `resolveObservationalMemoryConfig({ ... })` pero no están expuestos al entorno.
+
+> [!TIP]
+> Reduzca los umbrales para compactar antes (hilos largos más baratos, un poco más de resumen); levántelos para mantener más historia cruda en contexto antes de compactarla. Establezca `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` en un valor más alto si sus flujos de trabajo necesitan una cola palabra por palabra más larga.
+
+## Cuando hace efecto {#when}
+
+OM solo cambia el comportamiento de subprocesos lo suficientemente largos como para haber producido al menos una observación o reflexión. En concreto:
+
+- Un hilo nuevo o corto: todavía no hay entradas de OM → el contexto es la transcripción simple, sin cambios.
+- Un hilo largo que ha cruzado el umbral de observación: el prefijo más antiguo se reemplaza por el bloque `[Observational Memory]` compactado, la cola sin procesar reciente permanece palabra por palabra y el uso del token cae sustancialmente.
+
+La inyección es de mejor esfuerzo y segura en los límites: si no se puede encontrar un punto de recorte seguro (por ejemplo, un par de resultado/uso de herramienta pendiente se encuentra en el borde de la ventana), OM inyecta el bloque de memoria _aditivamente_ sin recortar en lugar de correr el riesgo de perder un resultado de herramienta pendiente.
+
+## Relacionado
+
+- [**Using Your Agent**](/docs/using-your-agent): el ciclo diario de trabajo con el agente acoplado junto a su aplicación.
+- [**Observability**](/docs/observability): métricas de costos y tokens por ejecución, donde se muestran los ahorros de OM.
+- [**Custom Agents & Teams**](/docs/agent-teams): las tiradas largas de subagente se benefician de la misma compactación.

package/corpus/core/docs/content/locales/es-ES/onboarding.md

@@ -0,0 +1,216 @@
+---
+title: "Incorporación y claves API"
+description: "Lista de verificación de instalación para la configuración de primera ejecución: claves API, OAuth y conexiones de proveedores"
+---
+
+# Incorporación
+
+Cuando abras por primera vez una aplicación creada en el marco nativo del agente, verás un
+Lista de verificación de **Configuración** en la barra lateral del agente. Mantiene cerrada la configuración de primera ejecución
+al chat del agente: conecte un motor de IA, opcionalmente apunte la aplicación a compartido
+infraestructura y agregue proveedores solo cuando los necesite.
+
+```an-diagram title="The setup checklist" summary="Only Connect an AI engine is required. The panel tracks completion and auto-hides once everything required is done."
+{
+  "html": "<div class=\"ob\"><div class=\"diagram-card\"><span class=\"diagram-pill warn\">required</span><strong>Connect an AI engine</strong><small class=\"diagram-muted\">Connect Builder (one click) or paste an LLM key</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Database</strong><small class=\"diagram-muted\">set <code>DATABASE_URL</code></small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Authentication</strong><small class=\"diagram-muted\">OAuth / access token</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">optional</span><strong>Email delivery</strong><small class=\"diagram-muted\">Resend / SendGrid</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">all required done &rarr; panel auto-hides</div></div>",
+  "css": ".ob{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ob .diagram-card{display:flex;flex-direction:column;gap:3px;padding:12px 14px}.ob .diagram-arrow{font-size:22px}"
+}
+```
+
+## Para usuarios finales
+
+### Lo que verás
+
+- Un panel de **Configuración** encima del chat del agente con una lista de verificación como "Conectar una IA
+  motor", "Entrega de correo electrónico", etc.
+- Un contador en la parte superior (por ejemplo, "1 de 4") muestra cuántos pasos están listos.
+- El paso actual se expande; los pasos terminados muestran una marca verde y permanecen
+  legibles si los abres.
+- Los pasos requeridos muestran una pequeña pastilla roja **obligatoria**. El panel permanece visible
+  hasta completar cada paso requerido.
+- Una vez hecho todo lo necesario, el panel se oculta automáticamente.
+- Todo el panel se puede contraer con el galón en la parte superior derecha, o
+  oculto por completo con **Ocultar configuración** en la parte inferior.
+
+### Cómo completar cada paso
+
+Los pasos ofrecen uno o más **métodos**: diferentes formas de satisfacer lo mismo
+requisito. La ruta principal se muestra primero; los caminos secundarios se mantienen compactos
+detrás de un selector o divulgación cuando un paso tiene varios proveedores equivalentes.
+
+- **Conectar un servicio (un clic)** — p.e. _Connect Builder_ para lo administrado
+  Puerta de entrada de IA. Haga clic en el botón, se abre una ventana, inicia sesión, la ventana se cierra
+  y el paso se marca como completo. No hay claves para copiar.
+- **Pegue una clave API o complete un formulario**, p. elija un proveedor LLM, base de datos,
+  Proveedor OAuth o proveedor de correo electrónico, pegue los valores y haga clic en **Guardar**.
+  Los campos secretos utilizan una entrada de contraseña para que el valor no se muestre en la pantalla. Guardado
+  Los valores van a su `.env` local (o configuración del espacio de trabajo) — consulte
+  [Security](/docs/security) para saber dónde viven.
+- **Abrir un vínculo**: algunos pasos apuntan a una página de inicio de sesión o a documentos. Haga clic
+  **Continuar** y finalizar el flujo en la nueva pestaña.
+- **Pregúntele al agente**: algunos pasos ofrecen la opción "Dejar que el agente lo configure".
+  Haz clic en él y el agente contestará en el chat y te guiará por cualquier
+  configuración externa (creación de credenciales OAuth, etc.).
+
+### Los pasos integrados que normalmente verás
+
+- **Conectar un motor de IA** (obligatorio): el único paso obligatorio. Conectar
+  Builder para una puerta de enlace administrada con un solo clic o abra la clave del proveedor secundario
+  selector y pega tu propia clave LLM.
+- **Base de datos** (opcional): configura `DATABASE_URL` cuando quieras usar una base de datos específica
+  Cadena de conexión a la base de datos SQL.
+- **Autenticación** (opcional): las cuentas de correo electrónico/contraseña integradas funcionan mediante
+  predeterminado. Agregue OAuth o inicie sesión con token de acceso solo cuando desee esas rutas.
+- **Entrega de correo electrónico** (opcional): útil antes de la implementación para restablecer contraseñas,
+  invitaciones a equipos y notificaciones para compartir. Utilice el proveedor que ya utiliza;
+  El desarrollo local puede funcionar sin él.
+
+Las plantillas pueden agregar sus propios pasos además de estos, p. una plantilla CRM podría
+agregue "Conectar Gmail", una plantilla de documentos podría agregar "Elija un espacio de trabajo predeterminado". Ver
+[Authentication](/docs/authentication) para obtener detalles de configuración de inicio de sesión.
+
+### Volviendo a la lista de verificación
+
+Si presionas **Ocultar configuración**, el panel desaparece para esa sesión del navegador.
+Los pasos obligatorios que aún no se han completado aparecerán nuevamente en la próxima carga. Una vez
+Todo lo necesario está hecho, el panel se oculta automáticamente para siempre, no hay nada
+Queda por hacer.
+
+## Para desarrolladores
+
+Si estás creando una plantilla, registra los pasos de incorporación para que aparezcan en
+la lista de verificación de la barra lateral del usuario. El marco maneja el renderizado y la finalización
+seguimiento y despido: simplemente declara cuál es el paso y cómo es
+satisfecho.
+
+El sistema se **monta automáticamente**. Las plantillas no necesitan conectar nada para obtener
+los cuatro pasos integrados (LLM, base de datos, autenticación, correo electrónico). Para agregar aplicaciones específicas
+pasos (Gmail, Slack, Notion, etc.), llame a `registerOnboardingStep()` desde un
+complemento de servidor.
+
+### Rutas montadas automáticamente
+
+Todas las rutas se encuentran bajo `/_agent-native/onboarding/`:
+
+| Ruta                                                | Propósito                                 |
+| --------------------------------------------------- | ----------------------------------------- |
+| `GET /_agent-native/onboarding/steps`               | Enumerar pasos con estado de finalización |
+| `POST /_agent-native/onboarding/steps/:id/complete` | Marcar paso como completo (anular)        |
+| `POST /_agent-native/onboarding/dismiss`            | Cerrar el banner de incorporación         |
+| `POST /_agent-native/onboarding/reopen`             | Despido claro (volver a mostrar panel)    |
+| `GET /_agent-native/onboarding/dismissed`           | Leer despido + bandera completa           |
+
+```an-api title="List onboarding steps"
+{
+  "method": "GET",
+  "path": "/_agent-native/onboarding/steps",
+  "summary": "List all registered steps with their completion status",
+  "description": "Drives the sidebar checklist — returns each step's id, title, methods, required flag, and whether `isComplete` currently passes.",
+  "responses": [
+    { "status": "200", "description": "Array of steps with completion status for the current user/app." }
+  ]
+}
+```
+
+### Agregar un paso desde una plantilla
+
+```an-annotated-code title="Registering a custom onboarding step"
+{
+  "filename": "server/plugins/my-onboarding.ts",
+  "language": "ts",
+  "code": "import { defineNitroPlugin } from \"@agent-native/core/server\";\nimport { registerOnboardingStep } from \"@agent-native/core/onboarding\";\nimport { listOAuthAccounts } from \"@agent-native/core/oauth-tokens\";\n\nexport default defineNitroPlugin(() => {\n  registerOnboardingStep({\n    id: \"gmail\",\n    order: 100,\n    title: \"Connect Gmail\",\n    description: \"Grant read/send access so the agent can work with email.\",\n    methods: [\n      {\n        id: \"oauth\",\n        kind: \"link\",\n        primary: true,\n        label: \"Sign in with Google\",\n        payload: { url: \"/_agent-native/google/auth-url?scope=mail\", external: false },\n      },\n      {\n        id: \"delegate\",\n        kind: \"agent-task\",\n        label: \"Let the agent set it up\",\n        badge: \"beta\",\n        payload: { prompt: \"Walk me through connecting Gmail. Set env vars as needed.\" },\n      },\n    ],\n    isComplete: async () => {\n      const accounts = await listOAuthAccounts(\"google\");\n      return accounts.length > 0;\n    },\n  });\n});",
+  "annotations": [
+    { "lines": "5", "label": "Auto-mounted", "note": "Register from a Nitro plugin — the framework handles rendering, completion tracking, and dismissal." },
+    { "lines": "7", "label": "Stable id", "note": "Re-registering with the same `id` after defaults load overrides a built-in step." },
+    { "lines": "12-19", "label": "Primary method", "note": "`primary: true` marks the big CTA. `kind: \"link\"` sends the user into the OAuth flow." },
+    { "lines": "20-26", "label": "Delegate path", "note": "`kind: \"agent-task\"` hands the setup to the agent chat with a prompt." },
+    { "lines": "28-31", "label": "Completion check", "note": "`isComplete` runs server-side. OAuth tokens live in the `oauth_tokens` store — check it, not `process.env.GMAIL_REFRESH_TOKEN`." }
+  ]
+}
+```
+
+### Comprobación de las conexiones del espacio de trabajo en la incorporación
+
+Al crear plantillas que interactúan con servicios externos (como Slack, Google Workspace, GitHub o HubSpot), debe verificar si el espacio de trabajo ya se ha conectado y ha otorgado la conexión de ese proveedor a su aplicación. Esto evita que los usuarios tengan que duplicar credenciales (como claves API o tokens de actualización) en sus variables de entorno local cuando existe una conexión central administrada.
+
+Puedes verificar la preparación de la conexión en tu devolución de llamada `isComplete` usando el catálogo de conexiones APIs:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+    appId: "mail",
+    templateUse: "mail",
+    provider: "gmail",
+  });
+  const connection = catalog.providers[0];
+
+  if (
+    connection?.readiness.status === "ready" &&
+    connection.workspaceConnection.grantState === "granted"
+  ) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+Consulte la documentación de [Workspace Connections](/docs/workspace-connections) para obtener la lista completa de métodos del catálogo de proveedores de conexión.
+
+### Tipos de métodos
+
+| Amable             | Carga útil                                            | Usar para                                               |
+| ------------------ | ----------------------------------------------------- | ------------------------------------------------------- |
+| `link`             | `{ url, external? }`                                  | Enviar usuario a una página de documentos o flujo OAuth |
+| `form`             | `{ fields, writeScope? }`                             | Recopilar variables de entorno (claves, secretos, URL)  |
+| `builder-cli-auth` | `{ scope: "llm" \| "browser" \| "image-generation" }` | Connect Builder (unlocks shared infra)                  |
+| `agent-task`       | `{ prompt }`                                          | Enviar un mensaje al chat del agente para manejar       |
+
+La bandera `primary: true` marca un método como el gran CTA para su paso.
+Utilice `badge: "soon"` más `disabled: true` cuando una ruta de configuración deba ser visible
+antes de que esté disponible.
+
+### Escaleras integradas
+
+| Identificación | Obligatorio | Descripción                                                 |
+| -------------- | ----------- | ----------------------------------------------------------- |
+| `llm`          | sí          | Conexión Builder o clave de proveedor LLM                   |
+| `database`     | no          | Base de datos predeterminada o cualquier SQL `DATABASE_URL` |
+| `auth`         | no          | Cuentas integradas, OAuth opcional o token de acceso        |
+| `email`        | no          | Reenviar o SendGrid para correo electrónico transaccional   |
+
+Cualquiera de estos puede anularse volviendo a registrarse con el mismo `id` después del
+carga predeterminada.
+
+### Uso del cliente
+
+El panel ya está dentro de `<AgentPanel>`. Para crear un diseño personalizado:
+
+```tsx
+import {
+  OnboardingPanel,
+  OnboardingBanner,
+  useOnboarding,
+} from "@agent-native/core/client/onboarding";
+
+function MySidebar() {
+  const { allComplete, dismissed, currentStepId } = useOnboarding();
+  if (allComplete || dismissed) return <Chat />;
+  return (
+    <>
+      <OnboardingPanel />
+      <Chat />
+    </>
+  );
+}
+```
+
+Para obtener información sobre dónde se almacenan los valores de los pasos y cómo se manejan los secretos,
+ver [Security](/docs/security). Para puntos de contacto de mensajería del usuario final (invitaciones,
+restablecimiento de contraseña) que dependen del paso **Entrega de correo electrónico**, consulte
+[Messaging](/docs/messaging).