Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Operar AX Code en trabajos de larga duración

Estado: Activo Alcance: estado actual Última revisión: 2026-09-13 Responsable: mantenedores de AX Code

AX Code limita una ejecución interactiva Super-Long a 72 horas. Para operar durante días o semanas, ejecuta un proceso ax-code serve supervisado y divide el trabajo en ocurrencias programadas duraderas. El supervisor reinicia el servidor; la base de datos del proyecto conserva las programaciones y el estado de la cola.

Espacio de trabajo interactivo persistente

Para el trabajo local que debe continuar después de cerrar la terminal, activa un entorno de ejecución del proyecto:

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

runtime attach también inicia el entorno de ejecución cuando no existe ninguno. El entorno se identifica por el directorio canónico del proyecto; los arranques simultáneos reutilizan un solo proceso. La TUI muestra su host de ejecución y una acción Desconectar. Desconectar cierra el cliente y mantiene en marcha el trabajo aceptado. runtime stop apaga el entorno de ejecución de ese proyecto e interrumpe su trabajo activo. Un ax-code ordinario conserva su ciclo de vida en primer plano existente.

Los seguimientos aceptados que se envían mientras una sesión está ocupada se guardan en el servidor. De forma predeterminada empiezan cuando termina el turno en curso, de modo que una solicitud ajena nunca desvía el trabajo en marcha. Para corregir el turno en curso, pulsa ctrl+s (input_submit_steer en keybinds) con un borrador solo de texto: el texto se admite en la generación activa y se escribe como mensaje de usuario en el siguiente límite de paso del bucle, después de que se asienten las llamadas a herramientas en curso y antes de la siguiente solicitud al modelo. Una corrección admitida mientras el turno está terminando alarga la ejecución una iteración en lugar de descartarse. La dirección es de mejor esfuerzo: si ya no hay una generación activa, el borrador se envía por la vía ordinaria; si un hook lo veta, el borrador permanece en el compositor con el motivo. Los borradores con adjuntos y comandos de barra siempre usan la cola de seguimientos. La misma entrega está disponible para otros clientes mediante la API de dirección descrita en controles del harness. Los seguimientos guardados también se pueden dirigir a posteriori: pulsar ctrl+s con un compositor vacío promueve, en orden, el prefijo dirigible de la cola y se detiene en la primera fila no dirigible, y la sección Seguimientos de la barra lateral y el diálogo /queue ofrecen la misma acción de dirigir ahora por fila. Las filas en pausa son dirigibles en su sitio: interrumpir un turno pausa los seguimientos en espera, y dirigir uno entrega su texto sin reanudar el resto de la cola. Solo las filas que no son seguimientos (comandos de barra en cola, comandos de shell), las filas con adjuntos, el texto vacío o demasiado grande y las filas que ya se ejecutan o han terminado son barreras. Las filas dirigidas se cancelan con un rastro de auditoría steeredInto y siguen visibles en el historial /queue. Cuando no hay una generación activa, dirigir ahora pasa a dar prioridad a la fila al frente de la cola: sigue empezando solo después de que termine el turno. El compositor se vacía solo después del acuse. Vuelve a conectar la misma sesión y usa /queue para inspeccionarlos, pausarlos, editarlos, reanudarlos o cancelarlos. Editar primero pausa el elemento y conserva los adjuntos y la selección de modelo; guardar no lo reanuda. Las ediciones obsoletas simultáneas se rechazan. En /queue, Ctrl+R incluye el historial completado y cancelado. Las terminales estrechas también muestran un encabezado Follow-ups en el que se puede hacer clic. Una vista desconectada está en caché y no puede cambiar elementos. Interrumpir el turno activo pausa los seguimientos pendientes para que no inicien de inmediato otro turno. Reanúdalos de forma explícita cuando estés listo.

Tras un reinicio del backend, los seguimientos en espera ya aceptados pueden reanudarse. Un prompt ordinario en curso interrumpido por ese reinicio se marca como fallido y exige inspección antes de reintentar; restaurar los registros de la cola no restaura un proceso de shell en ejecución. Un acuse perdido se puede reintentar desde el compositor sin cambios con la misma identidad de solicitud durante esa sesión de cliente. Los borradores no guardados no son trabajos aceptados, y esto no garantiza efectos externos exactamente una vez.

Este modo no instala un servicio de inicio de sesión, no reinicia automáticamente un servidor caído ni se ejecuta mientras el host está en reposo o apagado. Vuelve a iniciar o a conectar después de un fallo; usa los ejemplos de servicio supervisado de abajo para reinicios del servidor sin supervisión. Quienes usen SSH deben ejecutar el entorno en un host remoto despierto y conectar allí. No expongas el puerto HTTP de forma pública.

El descubrimiento del entorno de ejecución guarda una capacidad privada y un registro bajo la carpeta runtime/ del directorio de estado de AX Code. La salida de estado omite la capacidad. El apagado exige una identidad de entorno autenticada y coincidente, no solo un PID guardado. Un proceso en vivo no disponible, un registro dañado o una versión que no coincide exigen inspección; la CLI se niega a matar un proceso no verificado. Detén un entorno sano antes de actualizar y reinícialo con el ejecutable nuevo.

Modelo de fiabilidad

Esta recuperación evita duplicados; no es una entrega exactamente una vez para efectos externos arbitrarios. Las integraciones que escriben en sistemas externos deben seguir usando sus propias claves de idempotencia.

Antes de instalar un servicio

1. Instala y prueba el ejecutable ax-code como el mismo usuario que ejecutará el servicio.
2. Elige una ruta absoluta de proyecto. Defínela como AX_CODE_PROJECT para que el arranque del servidor precaliente ese proyecto e inicie su programador.
3. Mantén el servidor en 127.0.0.1; el servidor de AX Code es solo local.
4. Pon las credenciales del proveedor en el entorno protegido del supervisor, no en un archivo de servicio confirmado en el repositorio.
5. Sustituye cada marcador /absolute/path/... del ejemplo elegido.

Los ejemplos usan un puerto fijo para que los clientes de Desktop o del SDK puedan reconectar:

ax-code serve --hostname=127.0.0.1 --port=4096

Servicio de usuario de systemd

Copia el ejemplo de systemd en ~/.config/systemd/user/ax-code.service, sustituye sus rutas absolutas y, si quieres, pon las credenciales en ~/.config/ax-code/server.env.

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

Usa loginctl enable-linger "$USER" solo si la política operativa permite que el servicio de usuario se ejecute mientras el usuario no ha iniciado sesión.

Agente de launchd

Copia el ejemplo de launchd en ~/Library/LaunchAgents/com.axcode.server.plist, sustituye sus rutas absolutas y luego valídalo y cárgalo:

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd no expande variables de shell en ProgramArguments. Usa rutas absolutas y aporta las credenciales necesarias mediante un mecanismo gestionado por el operador.

PM2

Copia el ejemplo de PM2, sustituye sus rutas e inícialo:

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

Sigue las instrucciones de arranque específicas de la plataforma de PM2 si el proceso debe volver después de reiniciar el host.

Plazos, puesta al día y recuperación

Las tareas programadas usan de forma predeterminada catchUpPolicy: "run_once". Tras una interrupción, AX Code ejecuta una ocurrencia fusionada en lugar de crear una cola pendiente sin límite. Elige "skip" cuando el trabajo tardío sería engañoso o inseguro.

Cada tarea programada puede definir maxRunDurationMs desde 1 segundo hasta 72 horas. La ejecución de la cola de tareas, en otro caso, usa el techo de 72 horas. Los elementos activos actualizan una marca de tiempo de latido cada 30 segundos, y el estado final y los detalles del error permanecen en la base de datos del proyecto.

Los endpoints asíncronos de prompt, comando y shell devuelven el elemento duradero de la cola en su respuesta HTTP 202. Los clientes deben conservar su id y consultar GET /task-queue/:id hasta completed, failed o cancelled; la aceptación por sí sola no es la finalización.

Al arrancar, un backend persistente de AX Code reanuda los elementos de cola programados y los elementos asíncronos marcados de forma explícita que se confirmaron pero no habían empezado. Los comandos de CLI de un solo uso no toman la propiedad de esos elementos. El trabajo de prompt ya iniciado se marca como fallido con una explicación de reinicio para que un operador pueda inspeccionar los efectos secundarios antes de reintentar.

Ver qué hacen las tareas programadas

Cada ocurrencia de una tarea programada es visible mientras ocurre y auditable después:

• Iniciar, completar, fallar, omitir y las pausas automáticas por fallos persistentes generan cada una una notificación en la aplicación que nombra la tarea.
• El comando de TUI /schedule enumera cada tarea con su estado, programación, próxima hora de ejecución y último error, y abre su historial de ejecuciones recientes. Desde ahí puedes pausar, reanudar, ejecutar ahora, eliminar (pulsa ctrl+d dos veces para confirmar) y saltar a la sesión que produjo una ejecución. Las herramientas list_scheduled_tasks y list_scheduled_task_runs del agente responden a las mismas preguntas en conversación.
• Cada ejecución se hace en una sesión nueva titulada con el título de la tarea, así que los resultados están a una entrada de la lista de sesiones aunque se haya perdido una notificación.
• Si una ejecución pide un permiso o una respuesta mientras ves otra conversación, un aviso nombra la sesión que te necesita; /attention enumera las solicitudes pendientes conocidas y abre la sesión que las pidió. Las solicitudes se pueden responder en esa sesión o en la vista de un antecesor cargado, incluidas las sesiones hijas y nietas. Abrir una solicitud nunca la aprueba de forma automática.
• Una tarea de una sola vez se desactiva solo después de una ejecución correcta. Una ocurrencia fallida se reintenta con una espera creciente acotada, y los fallos repetidos pausan la tarea con una notificación: un recordatorio ya no puede desaparecer en silencio.

Comprobaciones operativas

• Vigila el recuento de reinicios del supervisor y los registros del servidor.
• Inspecciona los elementos fallidos de la cola de tareas y los errores de las tareas programadas antes de reintentar.
• Confirma que hay espacio de disco suficiente para la base de datos SQLite del proyecto y los registros.
• Prueba un ejecutar ahora manual después de cambiar credenciales, modelos o rutas del servicio.
• Detén mediante el supervisor para que AX Code reciba SIGTERM; los ejemplos permiten hasta 90 segundos para un apagado ordenado.

/loop es, a propósito, local al proceso y no sobrevive a un reinicio. Usa tareas programadas para el trabajo duradero sin supervisión.

Navegar por sesiones en paralelo

Con 146 columnas de terminal o más, una barra lateral de navegación a la izquierda muestra las sesiones del espacio de trabajo actual y sus agentes hijos cargados. Expande una fila con su control + y haz clic en un título para abrirla. Las sesiones fijadas conservan su orden y sus números de atajo. Las etiquetas de actividad completas distinguen trabajo, reintento, aprobaciones y preguntas; los padres también reflejan las solicitudes de los descendientes. Estas etiquetas no significan que una tarea haya superado la verificación. La barra lateral derecha existente conserva el contexto y los controles de la sesión actual.

El encabezado Proyecto identifica el directorio actual. Haz clic en él o usa /navigation-info para ver la ruta completa del proyecto y el título de la sesión actual. Recientes muestra las sesiones cargadas; Activas conserva los árboles de sesión que trabajan o esperan y el árbol de la sesión actual. El filtro se comparte con el selector de navegación y se recuerda. Usa /navigation-filter para alternarlo desde el teclado. Durante la desconexión muestra sesiones en caché en lugar de inferir qué sesiones están activas. Borrar (o /navigation-clear) pide confirmación y luego oculta las filas históricas solo del carril izquierdo y del selector de navegación. No borra sesiones; /sessions sigue enumerándolas. El árbol de la sesión actual, las sesiones fijadas y los árboles de trabajo o espera observados permanecen en el carril. Abrir una sesión desde /sessions la devuelve a la lista.

Usa /navigation-width o la acción Ancho de la navegación para elegir 20, 24, 28, 30, 32, 36 o 40 columnas (predeterminado 28). La barra lateral de sesión de la derecha tiene la misma acción Ancho y /sidebar-width (predeterminado 32). Ambas preferencias se recuerdan y se reducen de forma automática cuando hace falta para conservar el contenido principal. Usa /navigation para ocultar o restaurar el carril de navegación izquierdo en terminales anchas. /sidebar oculta o restaura la barra lateral de sesión derecha del mismo modo. En terminales más estrechas /navigation abre un selector de sesión y agente. Una barra Sesiones visible ofrece la misma acción siempre que falta el carril de navegación. Su acción Pendientes aparece cuando hay solicitudes conocidas que necesitan entrada; un asterisco marca un recuento en caché durante la desconexión. /sessions sigue abriendo el selector de sesiones normal. /attention está disponible en cualquier ancho. Durante la desconexión, su lista se etiqueta como en caché; abrir entradas en caché sigue siendo posible, pero las solicitudes pueden haberse respondido ya en otro lugar. La acción Solicitudes conocidas de la barra lateral abre las solicitudes pendientes de los espacios de trabajo conocidos, mientras que su árbol de sesiones sigue limitado al proyecto actual. Todas estas vistas están acotadas por la instancia conectada y los datos de sesión cargados; este recuento no es un inventario completo de otros servidores o espacios de trabajo no cargados.

Los borradores no enviados se aíslan por proyecto y sesión dentro de la TUI en ejecución. Cambiar de sesión conserva el texto, los adjuntos, la posición del cursor y el modo de shell; al volver se restaura el borrador correspondiente. Estos borradores solo están en memoria y no sobreviven al cierre de la TUI.

La notificación opcional de finalización ahora dice Session idle. Sigue el trabajo observado en el subárbol de la sesión vista y espera a que los descendientes activos observados queden inactivos de forma explícita, sin solicitudes pendientes. Las desconexiones, las resincronizaciones, el estado ausente, los errores y la cancelación pueden suprimir el aviso. Es una notificación de ciclo de vida, no una prueba de que las pruebas hayan pasado o de que un objetivo se haya completado.

Tareas nuevas y configuración

El arranque normal abre la superficie de trabajo Nueva tarea con un compositor inferior y navegación de sesiones. Abrirla o escribir un borrador no crea una sesión guardada; la sesión se crea cuando envías. Usa /sessions o la navegación izquierda para reanudar el trabajo existente. El comportamiento explícito de --session, --continue y --prompt sigue disponible; el arranque no activa la reanudación automática.

La configuración de proveedores no se abre sola. Usa la acción visible /connect en el área de trabajo cuando no hay un proveedor configurado. Con un proveedor configurado pero sin un modelo válido seleccionado, la acción cambia a /models. Un descubrimiento de proveedor fallido apunta a /status; /connect y /providers siguen disponibles para reparar la configuración. Un modelo seleccionado es una elección de configuración, no una credencial ni una comprobación de preparación del entorno de ejecución. Las indicaciones también aparecen para quienes vuelven y cuya configuración necesita atención.