Notas de ingeniería de Naly: Codex CLI, JSON estructurado y trabajadores de IA seguros para cron

Resumen

Naly usa a Codex CLI como plano de control para trabajo de IA programado: cada entrada de cron ejecuta un script controlado que lanza una tarea acotada del asistente con búsqueda web y un contrato de salida estricto, luego escribe artefactos JSON validados para publicación posterior, reproducción y reintentos. Esto hace que el trabajo del modelo se comporte como una canalización operacional—mismo comando, esquema explícito, artefactos explícitos—en lugar de un flujo de trabajo interactivo mutable. A partir de 2026-06-25, esta distinción es la ventaja de confiabilidad para la infraestructura de contenido crítica para el crecimiento.

Dónde encaja en Naly

Naly ya tiene prioridades activas de GST en torno a descubrimiento, retención y flujos de distribución. Este patrón encaja directamente en esa capa de ejecución:

Los trabajos de cron invocan una sola tsx script por caso de uso para que cada ejecución permanezca dentro de código versionado, no de fragmentos de shell ad hoc.
Codex CLI realiza el razonamiento y la recuperación, mientras Naly maneja el control de orquestación: programación, reintentos, bloqueo y artefactos persistentes.
La salida estructurada alimenta sistemas downstream construidos en Next.js, React, Drizzle ORM y Neon sin suposiciones de esquema aguas abajo.
Los logs externos y metadatos de ejecución se escriben bajo NALY_LOG_ROOT, haciendo reproducibles los post-mortems de manera independiente del almacenamiento en búfer de salida del proceso.

La tesis es: para producción, la calidad del LLM es solo la mitad del sistema; los límites deterministas alrededor de ese LLM son la otra mitad.

Mecanismo técnico

1) Punto de entrada del trabajador centrado en contrato

Cada tarea parte de tres entradas inmutables:

Una plantilla de prompt codificada y la intención de la tarea.
Un esquema de respuesta que debe validarse.
Un paquete de ejecución (run_id, source_query, attempt, env), persistido antes de la llamada a la API.

Naly invoca a Codex CLI en modo batch desde cron, no en modo interactivo. Codex está documentado como un agente de codificación local y se entrega como una CLI independiente con distribución de código abierto y lanzamientos activos, y puede ejecutarse en un entorno de scripts Codex CLI, repositorio de OpenAI Codex.

2) Por qué la salida estructurada es innegociable

Las guías de salida estructurada de OpenAI describen la extracción de esquema compatible con parser y el comportamiento de modo estricto necesario para canalizaciones automáticas. En Naly, la salida del modelo se trata como un artefacto intermedio, no como la verdad final, por lo que el contrato JSON es donde se aplica la confiabilidad:

campos obligatorios (headline, evidence list, confidence, citations, failure reason)
campos opcionales con valores predeterminados
confianza numérica y enumeraciones acotadas
fallos explícitos del parser que se muestran como errores de ejecución, no como texto corregido automáticamente en silencio.

3) Ciclo de vida cron-a-agente con control de concurrencia

Cron ejecuta líneas programadas según los campos de tiempo estándar de 5 campos y lanza un comando cuando los campos coinciden crontab. Para seguridad de producción, Naly añade:

protección de bloqueo (una ejecución activa por tarea)
clave de ejecución idempotente
política de reintento acotada con jitter
captura de logs externa para cada fase
actualización del estado posterior a la ejecución en tablas de base de datos gestionadas por Drizzle/Neon.

flock está diseñada exactamente para este patrón de barrera: adquirir un bloqueo, ejecutar la sección crítica, salir limpiamente cuando ya está bloqueado flock. Dado que el estado del bloqueo sigue a los descriptores de archivo, las ventanas de cron superpuestas se deniegan explícitamente en lugar de corromper el estado.

4) Por qué MCP importa en este patrón

Model Context Protocol formaliza contratos host/cliente/servidor de herramientas usando JSON-RPC, negociación de capacidades y llamadas de herramienta estructuradas MCP. En Naly, los límites con estilo MCP reducen el acoplamiento implícito: la búsqueda web puede representarse como una interfaz de herramienta controlada con capacidades explícitas en lugar de un comportamiento de shell de forma libre.

Qué dice la literatura

Investigaciones recientes muestran que la confiabilidad no equivale a capacidad bruta. El paper AI Agent Reliability informa brechas sustanciales entre precisión de tarea y consistencia entre ejecuciones, y propone dimensiones explícitas de confiabilidad (consistency, robustness, predictability, safety) para evaluación operativa Towards a Science of AI Agent Reliability. Esto respalda el diseño run-state-first de Naly: si una ejecución tiene éxito pero no puede repetirse con artefactos claros, no tiene calidad de producción.

Para salidas estructuradas, ToolPRM argumenta que el comportamiento de llamadas a herramientas estructuradas necesita supervisión explícita y que las mejoras son especialmente fuertes cuando se modela el proceso interno de llamada de funciones en lugar de solo los resultados finales ToolPRM: Fine-Grained Inference Scaling of Structured Outputs for Function Calling. Eso se alinea con el ciclo de ejecución schema-first de Naly: la puerta de calidad está en los límites de la interfaz, no solo en la fluidez del contenido.

Un tercer trabajo en esa misma frontera, SLOT, muestra un camino alternativo práctico al añadir una capa de conformado de salida agnóstica al modelo sobre los LLM SLOT: Structuring the Output of Large Language Models. Refuerza el mismo principio: la confiabilidad de la estructura es un problema de ingeniería incluso cuando la calidad del modelo base es fuerte.

Compromisos de diseño

Esquema estricto vs. portabilidad del modelo: los esquemas estrictos reducen la ambigüedad downstream pero pueden aumentar el churn ocasional de parsing cuando los proveedores interpretan las restricciones de forma distinta.
Simplicidad de cron vs. elasticidad de cola: cron es simple y visible, pero las cargas de trabajo de ráfaga necesitan backoff consciente del bloqueo o una capa de cola para evitar ejecuciones superpuestas y ventanas perdidas.
Búsqueda web dentro de la tarea vs. reproducción determinista: la búsqueda web fresca mejora la actualidad pero introduce volatilidad de fuentes; por eso, Naly guarda el texto de consulta, la lista de fuentes y referencias en bruto en los artefactos de ejecución.
Logs externos vs. solo logs de BD: los logs de sistema de archivos sobreviven a reinicios de proceso y son económicos para ingestión; los logs de BD simplifican la ergonomía de consultas pero pueden fallar en loops abiertos si no se particionan cuidadosamente.

Modos de falla

Desviación de esquema: la salida del proveedor viola el esquema; la mitigación es validación estricta fail-fast, fijación de versión de esquema y ejecuciones dead-letter.
Ejecuciones cron superpuestas: escrituras dobles o acciones externas duplicadas; la mitigación es bloqueo consultivo + guardia de salida de proceso.
Inestabilidad de búsqueda: la respuesta de la herramienta upstream cambia entre intentos; la mitigación es límite de reintentos, retraso exponencial y referencias upstream persistentes.
Sorpresas de tiempo: las diferencias de DST y zona horaria del host pueden afectar la semántica de programación; la mitigación es una política de programación UTC y verificaciones explícitas de entorno.
Escrituras parciales silenciosas: el parseo tiene éxito pero falla la escritura downstream; la mitigación es orden de persistencia transaccional y upserts idempotentes.
Fuga de seguridad/contexto: cualquier ruta de agente con capacidad de herramientas puede exceder su alcance, por lo que son necesarios límites de mínimo privilegio tipo MCP y supuestos explícitos de consentimiento/autenticación, especialmente donde las rutas de ejecución de herramientas tocan recursos de red Notas de seguridad de MCP.

Notas de implementación

Mantén un comando de trabajador por tarea de negocio en scripts/ y deja que cron llame solo a ese punto de entrada.
Almacena el hash del archivo de esquema en los metadatos de ejecución para que las expectativas del parser sean auditables después de una actualización de modelo.
Configura set -euo pipefailcomportamiento tipo set -euo pipefail en scripts wrapper y siempre incluye los IDs de ejecución en los nombres de logs.
Escribe tres checkpoints en los logs: started, codex_result_parsed, artifact_persisted.
Usa NALY_LOG_ROOT para que las trazas de ejecución nunca contaminen el estado del repositorio y sobrevivan a contextos de reinicio.
Persistir attempt, exit_code, retry_reason, y validation_errors para permitir que los tableros de GST y auditoría separen la infraestructura inestable de las regresiones reales del modelo.