@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,411 @@
+---
+title: "Crear plantillas"
+description: "Cómo crear y publicar sus propias plantillas de aplicaciones nativas del agente."
+---
+
+# Creación de plantillas
+
+Las plantillas son aplicaciones nativas del agente completas y bifurcables que resuelven un flujo de trabajo real. Las plantillas propias se crean con la misma superficie de marco que usted utiliza: rutas React para UI, Drizzle SQL para datos, actions para operaciones, recursos del espacio de trabajo para el comportamiento del agente y sincronización de sondeos para que el agente y UI permanezcan alineados.
+
+Una buena plantilla:
+
+- Resuelve un flujo de trabajo de principio a fin, con datos iniciales útiles o un flujo de estado vacío.
+- Almacena el estado duradero en archivos SQL, no en archivos JSON.
+- Define las operaciones de la aplicación como `defineAction()` actions.
+- Expone la navegación y la selección a través del estado de la aplicación.
+- Se envía un `AGENTS.md` claro y un skills enfocado para flujos de trabajo no obvios.
+- Registra los pasos de incorporación para los proveedores y secretos requeridos.
+- Funciona como una aplicación independiente y como parte de un espacio de trabajo de múltiples aplicaciones.
+
+## Empezar desde el chat {#start-from-chat}
+
+Utilice la plantilla de Chat cuando desee una aplicación mínima con el cableado del marco ya instalado:
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+Para un espacio de trabajo con varias aplicaciones, ejecute el selector e incluya Chat con las plantillas de dominio que desee:
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+Chat le brinda autenticación, hilos de chat duraderos, recursos respaldados por SQL, herramientas, estado de la aplicación, actions y sincronización de sondeo. Agregas el modelo de dominio y el producto UI.
+
+Si aún no está creando una plantilla UI reutilizable, use la rampa de acceso sin cabeza en [Getting Started](/docs/getting-started#1-create-your-app): defina una acción, ejecútela con `pnpm agent` y agregue UI más adelante cuando el flujo de trabajo necesite una superficie duradera.
+
+## Estructura del proyecto {#project-structure}
+
+Cada plantilla sigue el mismo diseño general:
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+No agregue un directorio `data/` para el estado de la aplicación. Los datos duraderos de la aplicación pertenecen a SQL y el UI los lee a través de actions o controladores de servidor escritos.
+
+Las cuatro áreas de cada plantilla se conectan a través de una superficie de acción compartida y una base de datos SQL: el agente y el UI son socios iguales en las mismas operaciones:
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Datos del modelo en SQL {#data-models}
+
+Defina tablas de dominio con los asistentes del marco Drizzle para que los esquemas sigan siendo portátiles en SQLite, Postgres, D1, Turso, Supabase, Neon y otros backends compatibles:
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+Los cambios de esquema deben ser aditivos. Agregue tablas y columnas a través de `runMigrations()` en `server/plugins/db.ts`; nunca utilice SQL, `drizzle-kit push`, cambios de nombre de tablas ni eliminación de columnas destructivos.
+
+Para lecturas y escrituras de aplicaciones, utilice el generador de consultas de Drizzle y los operadores portátiles de `drizzle-orm`. No escriba código de producto con SQL sin formato cuando Drizzle pueda expresar la consulta y no importe desde `drizzle-orm/sqlite-core` o `drizzle-orm/pg-core` en plantillas.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+Utilice los documentos [Database](/docs/database) y [Security](/docs/security) antes de agregar esquemas que contengan datos de usuarios u organizaciones.
+
+## Definir operaciones como Actions {#actions}
+
+Actions son la única fuente de información sobre el comportamiento de las aplicaciones. El agente los llama como herramientas, el frontend los llama a través de enlaces y otras aplicaciones pueden acceder a ellos a través de MCP/A2A.
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "Contrato tipado", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+Utilice `http: { method: "GET" }` o `readOnly: true` para actions de solo lectura. Utilice `parallelSafe: true` solo para mutar actions que sea seguro ejecutar al mismo tiempo que llamadas a herramientas en el mismo turno. Utilice `toolCallable: false` para actions con un radio de explosión alto que no debe ejecutarse desde herramientas de espacio aislado.
+
+## Construye el UI {#ui}
+
+Las rutas se encuentran en `app/routes/` y utilizan el enrutamiento de archivos React Router v7. Consulta datos a través de los controladores actions o API y haz que las mutaciones sean optimistas de forma predeterminada.
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+Conecte la sincronización en vivo una vez cerca del shell de la aplicación para que los cachés de consultas React se actualicen cuando el agente, otra pestaña o una acción cambien los datos:
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**La promesa nativa del agente: las escrituras del agente aparecen en el UI sin una actualización manual.** `useActionQuery` es el camino fácil: cada gancho se recupera cuando una acción mutante emite `source: "action"`. Si busca `useQuery` sin procesar con una clave personalizada (por ejemplo, un asistente de cliente de bajo nivel que lee el estado de la integración), doble el contador por fuente en queryKey para actualizaciones específicas:
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+Fuentes comunes: `"action"` (cada acción exitosa del agente: el respaldo confiable), `"app-state"`, `"settings"`, además de cualquier fuente de recursos personalizada que su tienda emita a través de `recordChange`. Consulta la habilidad `real-time-sync` para ver el patrón completo.
+
+## Agregar estado de aplicación {#application-state}
+
+El estado de la aplicación es cómo el agente sabe lo que está viendo el usuario. Como mínimo, agregue:
+
+- Un gancho UI que escribe el estado semántico de `navigation` cuando cambian las rutas, los registros seleccionados, las pestañas activas o las selecciones del editor.
+- Una acción `view-screen` que lee ese estado y devuelve la instantánea de la pantalla actual.
+- Una acción de `navigate` que escribe un comando `navigate` de una sola vez para que lo consuma el UI.
+
+Utilice `useAgentRouteState` para el gancho UI para que las escrituras en el estado de la aplicación, las lecturas de comandos con alcance de tabulación, la eliminación después de la lectura y la protección de comandos duplicados sean consistentes:
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+Mantener filtros compartibles en los parámetros de consulta URL. El marco los expone al agente como `<current-url>` y el agente integrado puede cambiarlos con `set-search-params`; `navigation` debe contener identificadores y alias semánticos, no una segunda copia de la cadena de consulta completa.
+
+Para la navegación de aplicaciones, prefiera un comando `navigate` que incluya un mismo origen
+`path` cuando se conoce el URL. No escribas también `__set_url__` para el mismo movimiento;
+Esa clave está reservada para las herramientas del marco URL y los cambios de filtro exclusivos de URL.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+Consulta [Context Awareness](/docs/context-awareness) para ver el patrón completo.
+
+## Utilice las rutas API con moderación {#api-routes}
+
+Prefiere actions para las operaciones de la aplicación. Cree rutas Nitro personalizadas solo para superficies que no se pueden actions limpiamente:
+
+- Carga de archivos o transmisión binaria.
+- Páginas públicas anónimas y webhooks.
+- Devoluciones de llamada OAuth y controladores de protocolo específicos del proveedor.
+- Contenido público renderizado por el servidor.
+
+Las rutas personalizadas que tocan datos de propiedad deben llamar a `getSession(event)` y envolver el trabajo de la base de datos en `runWithRequestContext({ userEmail, orgId }, fn)` antes de usar ayudantes de acceso.
+
+## Escribir instrucciones del agente {#write-agents-md}
+
+`AGENTS.md` es el mapa del agente de su aplicación: un archivo pequeño y examinable con un
+línea de propósito, reglas básicas, claves de estado de la aplicación, una tabla de acciones y un skills
+índice:
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+Actualice `AGENTS.md` cada vez que agregue una nueva acción, ruta, clave de estado o recurrente
+flujo de trabajo. [Writing Agent Instructions](/docs/writing-agent-instructions) es el
+guía completa: cómo mantener el `AGENTS.md` skimmable, qué pertenece a cada uno de los cuatro
+superficies de orientación y cómo redactar descripciones de habilidades y herramientas para que el agente
+los activa de forma fiable.
+
+## Agregar Skills {#skills}
+
+Utilice skills para patrones detallados que inflarían a `AGENTS.md`: API específicos del proveedor, formatos de importación/exportación, flujos de edición complejos o terminología de dominio.
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+Plantilla de tienda skills en `.agents/skills/<name>/SKILL.md`. Si los usuarios deberían poder editar la guía en tiempo de ejecución, muéstrela también a través de los recursos del espacio de trabajo.
+
+## Pasos de configuración del registro {#onboarding}
+
+Si una plantilla necesita una clave API, una conexión OAuth o una cuenta de proveedor, registre un paso de incorporación en lugar de enterrar el requisito en un README.
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+Ver [Onboarding & API Keys](/docs/onboarding).
+
+## Prepárelo para el espacio de trabajo {#workspace-ready}
+
+Las plantillas deben encajar naturalmente en [Multi-App Workspaces](/docs/multi-app-workspace), generalmente coordinadas por [Dispatch](/docs/dispatch).
+
+Lista de verificación:
+
+- Monte A2A a través del complemento de chat del agente marco o `mountA2A()` para que las aplicaciones hermanas puedan llamar a su agente.
+- Mantenga las descripciones de las tarjetas de agente lo suficientemente específicas para que Dispatch pueda enrutar el trabajo con precisión.
+- Registre los secretos/incorporación requeridos para que la configuración aparezca en la barra lateral y Dispatch pueda administrar las credenciales compartidas.
+- Mantenga instrucciones transversales en el espacio de trabajo `AGENTS.md` o en los recursos del espacio de trabajo, no las copie en todas las aplicaciones.
+- Utilice ayudas para compartir/acceder a todos los recursos propios para que los espacios de trabajo dentro del ámbito de la organización permanezcan aislados.
+
+## Publicar una plantilla {#publishing}
+
+Antes de compartir:
+
+1. Ejecute `pnpm install`, `pnpm typecheck` y las pruebas de la plantilla.
+2. Verifique que funcione sin claves de proveedor opcionales configuradas.
+3. Compruebe la autenticación, el uso compartido y el aislamiento de datos de dos usuarios.
+4. Documente las variables de entorno requeridas y los pasos de incorporación.
+5. Incluya ejemplos o filas de semillas a través de migraciones aditivas, no archivos de datos de tiempo de ejecución rastreados.
+
+Se pueden crear plantillas de comunidad desde un repositorio GitHub:
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## Contribuyendo al marco monorepo {#contributing}
+
+### Probar cambios en el marco no publicados {#test-unpublished-framework-changes}
+
+Cuando estás trabajando dentro del framework monorepo y necesitas un generado
+espacio de trabajo para usar paquetes no publicados o cambios de plantilla, ejecute crear con
+marca del paquete local:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+El espacio de trabajo generado vincula el `@agent-native/core` local y
+Paquetes `@agent-native/dispatch`, por lo que se realizan cambios en Core API, espacio de trabajo de envío
+el comportamiento o las plantillas propias se pueden probar antes de publicarlas. El paquete
+Los scripts `prepack` crean `dist` antes de vincularlos, lo que mantiene el generado
+espacio de trabajo apuntado al resultado de la compilación actual.

package/corpus/core/docs/content/locales/es-ES/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "SSO entre aplicaciones"
+description: "Inicie sesión una vez en cada aplicación nativa del agente alojada a través de la federación de identidades con Dispatch como autoridad de identidad: suscripción por aplicación, reversible con una única variable de entorno."
+---
+
+# SSO entre aplicaciones
+
+Cada aplicación alojada en `*.agent-native.com` ejecuta su propia implementación con su **propio almacén de usuarios independiente**. `mail.agent-native.com` y `calendar.agent-native.com` no comparten una base de datos, una tabla de sesión ni un dominio de cookies. Por lo tanto, "iniciar sesión una vez, usar todas las aplicaciones" no puede ser una cookie compartida; tiene que ser una **federación de identidad**, con [Dispatch](/docs/dispatch) actuando como autoridad de identidad para el espacio de trabajo.
+
+Esta es la misma primitiva de confianza que ya usan [A2A](/docs/a2a-protocol) y [External Agents](/docs/external-agents) (una JWT firmada por `A2A_SECRET` verificada en el límite de la solicitud) aplicada a la ruta de inicio de sesión humano en lugar de llamadas de agente a agente.
+
+> **Implementación unificada frente a implementación por dominio.** Si aloja todas las aplicaciones en un origen (`your-agents.com/mail`, `your-agents.com/calendar`), ya obtiene un inicio de sesión compartido a través de un único dominio de cookies, sin necesidad de federación. Cross-App SSO solo es necesario cuando las aplicaciones se ejecutan en dominios separados. Ver [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+## Qué y por qué {#what-why}
+
+Las tiendas de usuario por aplicación significan que no existe un único lugar en el que pueda alojarse una cookie del navegador en el que confíen todas las aplicaciones. En cambio, el modelo de federación nombra una aplicación, **Dispatch**, como autoridad de identidad. Cualquier otra aplicación puede delegar "¿quién es esta persona?" a Dispatch, obtenga una afirmación firmada de corta duración del correo electrónico verificado del usuario y luego **vincúlelo a su propia cuenta local por correo electrónico**.
+
+La regla de vinculación es deliberadamente estrecha y aditiva:
+
+- **Usuario existente con el mismo correo electrónico → vinculado.** La cuenta local coincide con el correo electrónico verificado y se reutiliza tal cual. **Nunca se modifica, se le cambia el nombre ni se elimina**; la capa de federación solo lo lee y crea una sesión para él.
+- **Nuevo correo electrónico → creado.** Se crea una nueva cuenta local para ese correo electrónico verificado y luego se crea una sesión local normal.
+
+Esto hace que la implementación sea segura aunque cierre la sesión de las personas. **Se espera cerrar sesión.** Cuando una aplicación activa esta opción, las sesiones existentes finalizan y los usuarios se vuelven a autenticar a través de Dispatch. Pero siempre vuelven a iniciar sesión en la **misma cuenta de correo electrónico coincidente, con todos sus datos intactos**, porque las filas de identidad solo se _añaden_, nunca se destruyen, no se les cambia el nombre ni se les redirige.
+
+## Cómo funciona {#how-it-works}
+
+El flujo es una autorización estándar → token firmado → redireccionamiento de devolución de llamada, con el correo electrónico como lo único que cruza el límite de confianza.
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **Aplicación → Envío (autorizar).** La aplicación envía al usuario a la autoridad de identidad:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title="Punto final de autorización de identidad"
+   {
+     "método": "GET",
+     "ruta": "/_agente-nativo/identidad/autorizar",
+     "summary": "El envío (autoridad de identidad) autentica al ser humano y lo redirecciona con un token de identidad firmado",
+     "auth": "Sesión de envío (inicio de sesión interactivo si no hay ninguno)",
+     "parámetros": [
+       { "name": "app", "in": "query", "type": "string", "required": true, "description": "El identificador de la aplicación solicitante". },
+       { "name": "redirect_uri", "in": "query", "type": "string", "required": true, "description": "Devolución de llamada de la aplicación URL. Validado con una lista de permitidos estricta (`*.agent-native.com` o localhost de forma predeterminada)." },
+       { "name": "state", "in": "query", "type": "string", "required": true, "description": "El estado de CSRF se repitió en la redirección". }
+     ],
+     "respuestas": [
+       { "status": "302", "description": "Redirecciona a `redirect_uri` con una identidad de corta duración firmada por `A2A_SECRET`, JWT (`scope: \"identity\"`, `exp` ≤ 2 minutos) más el `state` original." },
+       { "status": "400", "description": "`redirect_uri` falló en la validación de la lista de permitidos (`//host` de origen cruzado, relativo al esquema o sufijo no listado)". }
+     ]
+   }
+   ```
+
+2. **Dispatch autentica al ser humano.** Si el usuario ya tiene una sesión de Dispatch, esto es transparente. De lo contrario, Dispatch muestra su propio inicio de sesión normal (correo electrónico/contraseña, Google, etc.; consulte [Authentication](/docs/authentication)). Aquí Dispatch es solo una aplicación nativa del agente normal; no está ejecutando un modo de autenticación especial.
+
+3. **Dispatch → Aplicación (token de identidad firmado).** Dispatch valida `redirect_uri` contra una lista de permitidos estricta y redirecciona 302 al `redirect_uri` de la aplicación que lleva una identidad de corta duración **`A2A_SECRET` firmada por JWT**. Los reclamos del token son intencionalmente mínimos:
+
+   | Reclamación  | Significado                                                                  |
+   | ------------ | ---------------------------------------------------------------------------- |
+   | `sub`        | Identificación de usuario estable en la autoridad de identidad               |
+   | `email`      | El correo electrónico **verificado** del usuario: la única clave para unirse |
+   | `name`       | Nombre para mostrar (no autorizado, solo para UI)                            |
+   | `org_domain` | Dominio de espacio de trabajo/organización, cuando esté presente             |
+   | `scope`      | Siempre `"identity"`: este token solo autoriza el inicio de sesión           |
+   | `exp`        | **≤ 2 minutos** desde el problema                                            |
+
+4. **La aplicación verifica los enlaces JIT por correo electrónico.** La aplicación verifica la firma del token con su propio `A2A_SECRET`, verifica `scope: "identity"` y `exp` y luego realiza **enlace justo a tiempo estrictamente mediante correo electrónico verificado**:
+   - Si existe un usuario local con ese correo electrónico → reutilícelo sin cambios.
+   - Si no → crea un usuario local para ese correo electrónico.
+
+5. **La aplicación crea una sesión local normal.** A partir de aquí, el usuario tiene una sesión local normal en la propia tienda de esa aplicación: cada verificación de acceso, alcance de organización y protección de acciones existentes funciona exactamente como antes. La federación sólo ocurrió en la puerta grande.
+
+### Aceptar {#opt-in}
+
+Una aplicación participa **solo** cuando esta variable de entorno está configurada en su implementación:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Establecer** → la aplicación muestra una opción **"Iniciar sesión con Agent-Native"** que ejecuta el flujo anterior. El inicio de sesión local directo (correo electrónico/contraseña, Google) todavía funciona junto con él.
+- **Desarmado (predeterminado)** → **cero cambio de comportamiento.** La aplicación se autentica exactamente como lo hacía antes; la ruta del código de federación está inactiva. No hay ningún cambio de esquema ni nada que migrar, por lo que activar o desactivar la variable es totalmente reversible en cualquier momento.
+
+## Seguridad {#security}
+
+Todo el modelo se basa en unas pocas garantías deliberadamente pequeñas:
+
+- **Token firmado de corta duración.** La afirmación de identidad es un JWT firmado por `A2A_SECRET` con una caducidad de **≤ 2 minutos** y `scope: "identity"`. Autoriza un inicio de sesión único y no se puede reproducir por mucho tiempo ni reutilizar para acceder a API/A2A.
+- **Lista de permitidos estricta de `redirect_uri`.** Dispatch solo redirige a `*.agent-native.com` o localhost de forma predeterminada. Se rechazan los objetivos de redireccionamiento arbitrarios, relativos al esquema (`//host`) y de origen cruzado, por lo que la autoridad no se puede convertir en un oráculo de redireccionamiento abierto o de exfiltración de tokens.
+- **Únase solo por correo electrónico desde un token verificado.** Lo _único_ que cruza el límite de confianza es el correo electrónico verificado en un token firmado. La aplicación no acepta una identificación de usuario, función, membresía de organización ni ningún estado privilegiado de la conexión; deriva todo localmente de la cuenta coincidente.
+- **Escrituras de identidad solo aditivas.** La vinculación reutiliza una misma cuenta de correo electrónico existente intacta o inserta una nueva. Nunca se realizan actualizaciones, cambios de nombre, redireccionamiento ni eliminación de filas de identidad en esta ruta.
+- **Desactivado de forma predeterminada.** Con `AGENT_NATIVE_IDENTITY_HUB_URL` sin configurar, toda la función es inerte.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+El enlace justo a tiempo es una decisión única basada completamente en el correo electrónico verificado:
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Autohospedaje {#self-hosting}
+
+Cualquier implementación de Dispatch puede servir como centro de identidad; no está limitado a `dispatch.agent-native.com`. Configure `AGENT_NATIVE_IDENTITY_HUB_URL` en cada aplicación cliente para que apunte a su instancia de Dispatch:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**Lista permitida de redireccionamiento.** El concentrador (despacho) valida `redirect_uri` en el punto final autorizado antes de emitir un token. La lista de permitidos está configurada en `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **Predeterminado:** `*.agent-native.com` y localhost únicamente (la constante `DEFAULT_ALLOWED_HOST_SUFFIXES`).
+- **Extendiéndolo:** establezca la variable de entorno `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` en la implementación de Dispatch con una lista separada por comas de sufijos de host adicionales:
+
+  ```bash
+  # Permitir subdominios de suempresa.com además de los predeterminados
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".tuempresa.com,.puesta en escena.tuempresa.com"
+  ```
+
+  Cada entrada está normalizada a un sufijo con prefijo de punto (`.yourcompany.com`), por lo que una verificación del sufijo es suficiente y menos propensa a las pisadas: no hay una lista por aplicación para mantener sincronizada. Las entradas que coincidan con todo (vacías o solo `.`) se filtran.
+
+- **Localhost** siempre está permitido para el desarrollo local de aplicaciones del lado del cliente independientemente de `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
+
+Sin `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, un Dispatch autohospedado solo puede emitir tokens para aplicaciones en `*.agent-native.com`. Configure la variable de entorno en su implementación de Dispatch para desbloquear otros dominios.
+
+## Runbook de implementación de Canary {#canary-rollout}
+
+La transición y la reversión son **una única variable de entorno por implementación de aplicación**. Implemente una aplicación a la vez, verifíquela y luego expanda. No establezca la variable en todas las aplicaciones a la vez.
+
+**1. Implemente el código, sin cambios de comportamiento.**
+Envíe la versión a todas las aplicaciones con `AGENT_NATIVE_IDENTITY_HUB_URL` **desconfigurado en todas partes**. Confirma que los inicios de sesión normales aún funcionan en un par de aplicaciones.
+
+**2. Habilite el canario en la aplicación ONE a la vez.**
+Establecer, en una sola implementación:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+Deje el entorno de todas las demás aplicaciones sin configurar. Vuelva a implementar/reiniciar para que recoja la variable.
+
+**3. Verificar el canario (lista de verificación).**
+
+- Cerrar sesión\*\* en la aplicación.
+- La pantalla de inicio de sesión ahora muestra **"Iniciar sesión con Agent-Native"**. Haz clic en él.
+- Se le dirigirá a **Dispatch** y completará su inicio de sesión (o pasará directamente si ya inició sesión allí).
+- Se le redirige **de nuevo a la aplicación, inicia sesión** y es la **misma cuenta preexistente** (mismo correo electrónico) que tenía antes, no una nueva.
+- **Los datos de la aplicación están intactos**: sus registros, configuraciones y alcance de la organización existentes son exactamente como estaban.
+- **Los inicios de sesión directos existentes aún funcionan**: el correo electrónico/contraseña y el inicio de sesión de Google siguen funcionando junto con SSO.
+
+Si falla alguna comprobación, vaya directamente al paso 4 (revertir): es instantáneo y protege los datos.
+
+**4. Expandir aplicación por aplicación.**
+Una vez verificada una aplicación, repita los pasos 2 y 3 para la siguiente aplicación: configure `AGENT_NATIVE_IDENTITY_HUB_URL` en una implementación a la vez. Nunca habilite por lotes.
+
+**5. Rollback = desarmar la var de entorno en la implementación de esa aplicación.**
+Para revertir cualquier aplicación, **elimine `AGENT_NATIVE_IDENTITY_HUB_URL` del entorno de esa aplicación y vuelva a implementarla/reiníciela.** La aplicación vuelve inmediatamente a su comportamiento de autenticación anterior. No hay **ningún cambio de datos para deshacer**: las filas de identidad solo se agregaron y desarmar la variable simplemente hace que la ruta de federación vuelva a estar inactiva. La transición y la reversión de cada aplicación son independientes y reversibles.
+
+> Rollout cierra la sesión de los usuarios cuando se habilita cada aplicación (se vuelven a autenticar a través de Dispatch), pero siempre vuelven a iniciar sesión en la **misma cuenta de correo electrónico coincidente con los datos intactos**, porque las filas de identidad nunca se destruyen ni se les cambia el nombre, solo se agregan.
+
+## Relacionado {#related}
+
+- [Authentication](/docs/authentication): modos de autenticación locales, sesiones, organizaciones, la var. de entorno `A2A_SECRET`.
+- [A2A Protocol](/docs/a2a-protocol): modelo de confianza firmado JWT con verificación en el límite que se reutiliza.
+- [External Agents](/docs/external-agents): el mismo patrón de identidad firmado por `A2A_SECRET` aplicado a las conexiones de agentes y enlaces profundos.
+- [Dispatch](/docs/dispatch): autoridad de identidad del espacio de trabajo y centro de enrutamiento.
+- [Security & Data Scoping](/docs/security): escrituras de datos solo aditivas y alcance por cuenta.
+- [Multi-App Workspaces](/docs/multi-app-workspace): la implementación unificada de origen único que evita por completo el SSO entre dominios.