@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/es-ES/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "Trabajos recurrentes"
+description: "Solicitudes programadas por cron que el agente ejecuta por sí solo: resúmenes diarios, informes semanales, sondeos cada hora."
+---
+
+# Trabajos recurrentes
+
+Un **trabajo recurrente** es un mensaje que se ejecuta según una programación cron. Así es como el agente hace las cosas por sí solo: "cada mañana a las 7 resume mis correos electrónicos nocturnos", "todos los lunes publica los números de registro de la semana pasada en Slack", "cada hora busca borradores obsoletos y los elimina".
+
+Los trabajos recurrentes se activan en un reloj. Para reaccionar a _eventos_ (una reserva creada, un correo electrónico recibido), el mismo formato de archivo `jobs/` más las condiciones, consulte [Automations](/docs/automations).
+
+Los trabajos se encuentran en [workspace](/docs/workspace) en `jobs/<name>.md`: solo un archivo Markdown con texto frontal de YAML. Sin registro, sin cableado. Suelte el archivo y el marco lo recogerá.
+
+## Un archivo de trabajo {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+Eso es todo. El cuerpo es un mensaje que el agente ejecuta en cada disparo programado. El agente tiene acceso a las mismas herramientas y contexto de espacio de trabajo que tiene en un chat interactivo: actions, skills, memoria, servidores MCP conectados, subagentes.
+
+## Antecedentes {#frontmatter}
+
+| Campo        | Tipo                          | Predeterminado  | Descripción                                                                                                                                |
+| ------------ | ----------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `schedule`   | expresión cron                | _(obligatorio)_ | Cron estándar de 5 campos. `"0 7 * * *"` = todos los días a las 07:00 horas; `"0 */4 * * *"` = cada 4 horas.                               |
+| `enabled`    | booleano                      | `true`          | Pase a `false` para pausar sin eliminar el trabajo.                                                                                        |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`     | `"creator"` se ejecuta con la identidad del propietario del trabajo y `ANTHROPIC_API_KEY`. `"shared"` utiliza la clave de la organización. |
+| `createdBy`  | correo electrónico            | _(automático)_  | Se completa cuando el trabajo se crea a través del espacio de trabajo UI o por el agente.                                                  |
+| `orgId`      | cadena                        | _(automático)_  | Alcance de la organización; heredado de la organización activa del creador.                                                                |
+| `lastRun`    | Marca de tiempo ISO           | _(gestionado)_  | Escrito por el planificador después de cada ejecución.                                                                                     |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(gestionado)_  | Último resultado.                                                                                                                          |
+| `lastError`  | cadena                        | _(gestionado)_  | Mensaje de error si la última ejecución falló.                                                                                             |
+| `nextRun`    | Marca de tiempo ISO           | _(gestionado)_  | Calculado a partir de `schedule`; utilizado por el programador para decidir cuándo disparar a continuación.                                |
+
+Los campos `last*` y `nextRun` los escribe el programador. Puedes leerlos para ver el historial, pero no los edites manualmente: la siguiente ejecución los sobrescribirá.
+
+## Sintaxis cron {#cron}
+
+Cron estándar de 5 campos (minuto, hora, día del mes, mes, día de la semana):
+
+| Cron           | Significado                 |
+| -------------- | --------------------------- |
+| `*/5 * * * *`  | Cada 5 minutos              |
+| `0 * * * *`    | Cada hora en punto          |
+| `0 */4 * * *`  | Cada 4 horas                |
+| `0 7 * * *`    | Todos los días a las 07:00  |
+| `0 9 * * 1`    | Todos los lunes a las 09:00 |
+| `0 17 * * 1-5` | Días laborables a las 17:00 |
+| `0 0 1 * *`    | Primer día de cada mes      |
+
+El marco incluye utilidades cron (`isValidCron()` y `describeCron()`) para validar y representar cadenas cron, utilizadas internamente por las capas de recursos y programador.
+
+## Creando un trabajo {#creating}
+
+### Desde la pestaña Espacio de trabajo
+
+`+` → **Tarea programada** en el panel del espacio de trabajo. Complete el mensaje y el cronograma. Se guarda como `jobs/<slug>.md` y comienza a ejecutarse en el siguiente tick coincidente.
+
+### Preguntando al agente
+
+> "Crear una tarea programada que resuma mis correos electrónicos no leídos todas las mañanas a las 7."
+
+El agente escribe el archivo por usted.
+
+### A mano
+
+Coloque un archivo Markdown en `jobs/` a través del recurso APIs del marco:
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## Cómo se ejecuta el programador {#how-scheduler-runs}
+
+El programador es un complemento de marco (la rutina interna `processRecurringJobs()`) que se ejecuta durante el proceso: un `setInterval` se activa cada 60 segundos (con un retraso de inicio de 10 segundos) dentro del complemento de chat del agente, dondequiera que se esté ejecutando el servidor.
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## Depurar un trabajo {#debugging}
+
+- Abra `jobs/<name>.md` en el espacio de trabajo; el frontmatter muestra `lastRun`, `lastStatus`, `lastError`, `nextRun`.
+- **Pruébalo sin esperar:** no hay ninguna herramienta de disparo forzado. Para realizar el mismo trabajo bajo demanda, pegue el mensaje del trabajo en el chat del agente y déjelo ejecutar allí, o configure temporalmente el cronograma para el siguiente minuto para que el programador lo retome en el siguiente tick (luego restaure el cron real).
+- **Pausa:** voltea `enabled: false`. El archivo permanece ahí, simplemente deja de ejecutarse.
+
+## Herramienta de agente {#agent-tool}
+
+Se registra una única herramienta `manage-jobs` en cada plantilla. El parámetro `action` selecciona la operación:
+
+| Acción   | Parámetros                                                           | Propósito                                                                                   |
+| -------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `create` | `name`, `schedule`, `instructions` (obligatorio); `scope`, `runAs`   | Crear un nuevo trabajo recurrente                                                           |
+| `list`   | `scope` (`personal`, `shared` o todos)                               | Enumerar todos los trabajos con estado (programado, habilitado, última/siguiente ejecución) |
+| `update` | `name` (obligatorio); `schedule`, `instructions`, `enabled`, `runAs` | Editar un trabajo existente                                                                 |
+| `delete` | `name` (obligatorio)                                                 | Eliminar un trabajo: confírmalo siempre primero con el usuario                              |
+
+**Ámbito personal versus compartido.** Cada trabajo se encuentra en un ámbito personal (se ejecuta y es visible solo para el creador) o en un ámbito compartido/orgánico (se ejecuta en nombre del creador pero es visible para los miembros de la organización). Los parámetros `scope` y `runAs` controlan esto en el momento de la creación. Los administradores de la organización pueden actualizar o eliminar cualquier trabajo compartido; los miembros no administradores solo pueden administrar los suyos propios.
+
+## Diferente del paquete de programación {#vs-scheduling-package}
+
+No confunda trabajos recurrentes con `@agent-native/scheduling`:
+
+- **Trabajos recurrentes (esta página)**: _avisos_ programados cron que el agente ejecuta en segundo plano. Nivel de marco. Vive en el espacio de trabajo. Se ejecuta en cualquier aplicación nativa del agente.
+- **`@agent-native/scheduling`**: un paquete de dominio reutilizable para crear funciones de calendario/reservas (tipos de eventos, períodos de disponibilidad, reservas). Impulsa la plantilla `calendar` y las superficies de programación personalizadas.
+
+Los trabajos recurrentes son "¿cómo hago para que el agente actúe por sí solo?" El paquete de programación es "¿cómo creo una aplicación de calendario?" Diferentes preocupaciones.
+
+## ¿Qué sigue?
+
+- [**Automations**](/docs/automations): agregue activadores de eventos y condiciones al mismo formato `jobs/`
+- [**Workspace**](/docs/workspace): donde los trabajos conviven con skills, la memoria y los agentes personalizados
+- [**Actions**](/docs/actions): las herramientas que requiere un trabajo
+- [**Agent Teams**](/docs/agent-teams): los trabajos a menudo generan subagentes para realizar trabajos paralelos

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

@@ -0,0 +1,79 @@
+---
+title: "Enrutamiento"
+description: "Enrutamiento basado en archivos para aplicaciones nativas del agente con React Router v7: páginas, parámetros dinámicos y navegación."
+---
+
+# Enrutamiento
+
+Las aplicaciones nativas del agente utilizan **React Router v7** con enrutamiento basado en archivos a través de `flatRoutes()` desde `@react-router/fs-routes`. Cada archivo en `app/routes/` se convierte en un URL. Las plantillas utilizan la convención de notación de puntos: los puntos separan los segmentos URL dentro de un único nombre de archivo.
+
+## Enrutamiento basado en archivos {#file-based-routing}
+
+### Archivo → Mapeo URL
+
+| Archivo               | URL                | Notas                                           |
+| --------------------- | ------------------ | ----------------------------------------------- |
+| `_index.tsx`          | `/`                | Ruta de índice                                  |
+| `settings.tsx`        | `/settings`        | Página sencilla                                 |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | Punto = `/`, `$` = parámetro dinámico           |
+| `_app.tsx`            | (sin segmento URL) | Diseño sin rutas: prefijo con `_`               |
+| `inbox/route.tsx`     | `/inbox`           | Formulario de carpeta: `route.tsx` es el índice |
+
+Prefije un segmento con `$` para un parámetro dinámico. Prefije `_` para que sea una ruta de diseño sin ruta (sin segmento URL). Las plantillas usan `flatRoutes()`: el archivo de notación de puntos anterior es principal; el formato de carpeta anidada `inbox/route.tsx` también funciona.
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## Agregar una nueva página {#adding-a-page}
+
+Cree el archivo y exporte un componente predeterminado:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+Eso es todo: el enrutador React lo detecta automáticamente, no es necesario registrarse.
+
+## Parámetros dinámicos {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## Navegación {#navigation}
+
+Utilice `<Link>` para navegación del lado del cliente y `useNavigate()` para navegación programática:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## ¿Qué sigue?
+
+- [**Client**](/docs/client): utilidades y ganchos del navegador nativo del agente
+- [**Server**](/docs/server): rutas de servidor basadas en archivos y el espacio de nombres `/_agent-native/`

package/docs/content/locales/es-ES/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "Adaptadores"
+description: "Las dos uniones de adaptadores del marco: los adaptadores sandbox intercambian el backend que ejecuta la herramienta de código de ejecución del agente, y los adaptadores CLI le dan al agente acceso estructurado a las herramientas de línea de comandos."
+search: "adaptadores sandbox adaptador cli adaptador run-code SandboxAdapter CliAdapter ShellCliAdapter durable runner remoto sandbox edge serverless child_process"
+---
+
+# Adaptadores
+
+> **Para quién es:** autores del host que amplían el tiempo de ejecución. Los desarrolladores de aplicaciones rara vez
+> necesita esto: los valores predeterminados funcionan de inmediato.
+
+Agent-Native tiene dos costuras adaptadoras que eliminan un problema detrás de un estrecho,
+interfaz intercambiable:
+
+- **Los adaptadores Sandbox** intercambian el backend que ejecuta la herramienta `run-code` del agente:
+  un proceso secundario local de forma predeterminada o un ejecutor Docker/remoto/duradero.
+- **Los adaptadores CLI** brindan al agente acceso estructurado a herramientas de línea de comandos
+  (`gh`, `ffmpeg`, `stripe`) con descubrimiento, comprobaciones de disponibilidad y
+  forma de resultado consistente.
+
+Ambos comparten una restricción de tiempo de ejecución: dependen de los enlaces del sistema Node.js y lo hacen
+no se ejecuta en tiempos de ejecución de borde/trabajador; consulte [Edge and serverless](#edge-serverless).
+
+## ¿Qué documento de codificación quiero? {#which-doc}
+
+| Quieres...                                                                           | Usar                                         |
+| ------------------------------------------------------------------------------------ | -------------------------------------------- |
+| Cambiar el backend que ejecuta la **herramienta `run-code`**                         | **Adaptadores Sandbox** (esta página)        |
+| Preparar una herramienta CLI (`gh`, `ffmpeg`) para que el agente la llame            | **Adaptadores CLI** (esta página)            |
+| Renderizar un código Claude/estilo Codex **espacio de trabajo de codificación UI**   | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Ejecute Claude Code / Codex / Pi **como agente**, con su propio bucle + herramientas | [Harness Agents](/docs/harness-agents)       |
+
+# Adaptadores de zona de pruebas
+
+La herramienta `run-code` ejecuta JavaScript proporcionado por el agente en un entorno aislado. **Los adaptadores Sandbox** eliminan la preocupación por la _ejecución_ de esa herramienta para que el backend pueda intercambiarse (un proceso secundario local de forma predeterminada o un ejecutor Docker/remoto/durable) sin tocar el bucle del agente, `run-code.ts`, el puente localhost, el entorno de limpieza o el formato de salida.
+
+## Por qué una costura {#why}
+
+El backend predeterminado genera un proceso secundario de Nodo local bloqueado. Eso está limitado por el proceso de alojamiento: en la plataforma alojada comparte el límite de ejecución suave del bucle del agente (~40 segundos antes del tiempo de espera/continuación). Un adaptador remoto o duradero es la palanca para superar ese límite: ejecuta grandes trabajos de datos hasta su finalización independientemente del ciclo de vida de la solicitud.
+
+Mantener el contrato restringido significa que un adaptador remoto hereda la misma postura de seguridad. El proceso principal mantiene la propiedad de todo lo que contiene secretos: construye el módulo sandbox, ejecuta el puente localhost (que contiene el contexto de solicitud y aplica listas de host permitidas + guardias SSRF), limpia el entorno y formatea la salida. Un adaptador solo recibe un origen de módulo **no secreto** ya preparado más límites de recursos; es responsable únicamente de _ejecutarlo_ y capturar el estado stdout/stderr/exit.
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## La interfaz {#interface}
+
+La costura se encuentra en el núcleo en `packages/core/src/coding-tools/sandbox/` — `adapter.ts` (el contrato), `index.ts` (selección: `getSandboxAdapter()` / `registerSandboxAdapter()`) y `local-child-process-adapter.ts` (el valor predeterminado). Está cableado en el paquete por `run-code.ts`; un host conecta un backend diferente a través del asistente de registro `index.ts` (o, para un backend Docker, a través del [blueprint](/docs/blueprint-installer) que edita estos archivos directamente).
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+Cada backend implementa `SandboxAdapter`:
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+La solicitud y el resultado son intencionalmente pequeños y opacos:
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## El valor predeterminado: `LocalChildProcessAdapter` {#default}
+
+De fábrica, `getSandboxAdapter()` devuelve `LocalChildProcessAdapter` (`id: "local-child-process"`). Preserva el comportamiento histórico de `run-code` byte por byte:
+
+- La fuente del módulo preparado se escribe en un directorio temporal nuevo.
+- El niño ejecuta con el entorno eliminado (sin secretos), con `TMPDIR`/`TEMP`/`TMP` apuntando dentro del directorio sandbox.
+- Cuando el modelo de permisos de Nodo está disponible (`--permission` o `--experimental-permission` en el Nodo 20), al niño se le niega el acceso al sistema de archivos fuera de su directorio temporal, además de los procesos secundarios, trabajadores y complementos nativos. La red saliente _no_ está bloqueada por el modelo de permisos, pero la limpieza ambiental significa que dichas solicitudes no llevan credenciales y todas las llamadas autenticadas pasan por el puente loopback principal.
+- Un tiempo de espera envía `SIGTERM`, luego `SIGKILL` después de un período de gracia de 2 s.
+- Los archivos temporales se limpian con el mayor esfuerzo posible después de la ejecución.
+
+> [!WARNING]
+> El adaptador predeterminado utiliza `node:child_process`, que no existe en tiempos de ejecución de borde/trabajador. Ejecute `run-code` en un entorno Node.js estándar o registre un adaptador remoto; consulte [Edge and serverless](#edge-serverless).
+
+## Seleccionar un adaptador {#selection}
+
+Orden de resolución: gana un adaptador registrado explícitamente; de lo contrario, la var env selecciona una función integrada; de lo contrario, se utiliza el valor predeterminado local:
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### Var entorno `AGENT_NATIVE_SANDBOX` {#env}
+
+Selecciona un adaptador integrado por id. Actualmente, solo está cableado `local` (el predeterminado); los valores desconocidos recurren al local en lugar de fallar la ejecución.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+Un proceso de host anula el backend para todas las invocaciones posteriores de `run-code` a través del `index.ts` de la costura, por ejemplo, para ejecutar cada llamada en un contenedor remoto:
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## La costura para un corredor duradero {#durable}
+
+Esta interfaz es deliberadamente la unión para una futura zona de pruebas remota/duradera. Un adaptador remoto o duradero (Docker, un ejecutor estilo Vercel-Sandbox o un trabajador en segundo plano en cola) haría lo siguiente:
+
+1. Implemente `SandboxAdapter.run` en un tiempo de ejecución fuera de proceso.
+2. Haz un túnel para el puente loopback (o las llamadas del puente proxy al padre).
+3. Permita que los trabajos de datos grandes se ejecuten hasta su finalización independientemente del ciclo de vida de la solicitud, superando el límite máximo de ejecución de código alojado de ~40 s que limita el adaptador de proceso secundario local.
+
+Regístrelo con un nuevo valor `AGENT_NATIVE_SANDBOX` (por ejemplo, `remote`) y/o mediante `registerSandboxAdapter()`. El bucle del agente y `run-code.ts` nunca cambian.
+
+> [!TIP]
+> El plano `agent-native add sandbox docker` emite una receta completa e independiente para implementar un adaptador Docker en esta unión. Ver [Blueprint Installer](/docs/blueprint-installer).
+
+# Adaptadores CLI
+
+La otra unión del adaptador envuelve una única herramienta de línea de comandos (`gh`, `ffmpeg`, `stripe`, `aws`) para que el agente pueda descubrirla, verificar si está instalada y ejecutarla con un resultado stdout/stderr/código de salida consistente. Cada adaptador CLI implementa `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+Para la mayoría de los CLI, `ShellCliAdapter` encapsula cualquier binario con valores predeterminados razonables y `CliRegistry` recopila adaptadores para el descubrimiento en tiempo de ejecución:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+Envuelva una llamada CLI en `defineAction` para exponerla en la superficie de acción. Consulte la referencia rápida de [CLI Adapters](/docs/cli-adapters) para conocer las opciones de `ShellCliAdapter`, los adaptadores personalizados y el patrón de ajuste de acciones.
+
+## Edge y sin servidor {#edge-serverless}
+
+> [!WARNING]
+> Ambas costuras adaptadoras se basan en fijaciones del sistema Node.js. Los adaptadores sandbox `LocalChildProcessAdapter` y CLI (`ShellCliAdapter` y adaptadores personalizados) usan `node:child_process` (`execFile` / `spawn`), que **no existe** en tiempos de ejecución de borde/trabajador como Cloudflare Workers o Netlify Edge Functions. Si implementa rutas de servidor en estos ajustes preestablecidos de borde, la ejecución de estos adaptadores genera una excepción de tiempo de ejecución. Ejecute tareas y puntos finales del adaptador en un entorno Node.js estándar (contenedores de servidores tradicionales o funciones de nodo sin servidor) o, para la zona de pruebas, registre un adaptador remoto que envíe el trabajo fuera del proceso.
+
+## ¿Qué sigue?
+
+- [**CLI Adapters**](/docs/cli-adapters): la referencia rápida para la costura CLI
+- [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker` imprime una receta de adaptador Docker
+- [**Agent Teams**](/docs/agent-teams): delegar el trabajo pesado a subagentes
+- [**Security**](/docs/security): la postura de lista de permitidos de puente y limpieza de entorno