Notas de Engenharia Naly: Codex CLI, JSON estruturado e workers de IA compatíveis com cron

Resumo

A Naly usa o Codex CLI como plano de controle para o trabalho de IA agendado: cada entrada de cron executa um script versionado que inicia uma tarefa assistente delimitada com busca web e um contrato de saída rígido, depois grava artefatos JSON validados para publicação downstream, replay e retries. Isso faz o trabalho do modelo se comportar como um pipeline operacional—mesmo comando, esquema explícito, artefatos explícitos—em vez de um fluxo interativo mutável. Em 2026-06-25, essa distinção é a vantagem de confiabilidade para infraestrutura de conteúdo crítica para crescimento.

Onde ela se encaixa na Naly

A Naly já tem prioridades GST ativas em torno de fluxos de descoberta, retenção e distribuição. Esse padrão encaixa-se diretamente nessa camada de execução:

As tarefas cron invocam um único tsx script por caso de uso, para que cada execução fique dentro de código versionado, não em trechos de shell ad hoc.
O Codex CLI realiza o raciocínio e a recuperação, enquanto a Naly cuida do controle de orquestração: agenda, retries, bloqueio e artefatos duráveis.
A saída estruturada alimenta sistemas downstream construídos em Next.js, React, Drizzle ORM e Neon sem suposição de schema downstream.
Logs externos e metadados de execução são gravados em NALY_LOG_ROOT, tornando post-mortems reproduzíveis independentemente do buffer de saída do processo.

A tese é: para uso em produção, a qualidade do LLM é apenas metade do sistema; os limites determinísticos em torno desse LLM são a outra metade.

Mecanismo técnico

1) Ponto de entrada do worker orientado por contrato

Cada tarefa começa com três entradas imutáveis:

Um template de prompt codificado e intenção da tarefa.
Um esquema de resposta que deve ser validado.
Um envelope de execução (run_id, source_query, attempt, env), persistido antes da chamada da API.

A Naly invoca o Codex CLI em modo batch a partir do cron, não em modo interativo. O Codex é documentado como um agente de codificação local e distribuído como CLI independente com distribuição open source e releases ativos, e pode ser executado em ambiente com scripts Codex CLI, repositório OpenAI Codex.

2) Por que saída estruturada é não negociável

Os guias de saída estruturada da OpenAI descrevem extração de esquema com suporte de parser e o comportamento em modo estrito necessário para pipelines de máquina. Na Naly, a saída do modelo é tratada como um artefato intermediário, não como verdade final, então o contrato JSON é onde a confiabilidade é aplicada:

campos obrigatórios (headline, evidence list, confidence, citations, failure reason)
campos opcionais com valores padrão
confiança numérica e enums delimitados
falhas explícitas de parser expostas como erros de execução, e não correções de texto silenciosas.

3) Ciclo cron-para-agente com controle de concorrência

O cron executa linhas agendadas conforme os campos padrão de 5 colunas e inicia um comando quando os campos correspondem crontab. Para segurança em produção, a Naly adiciona:

guarda de bloqueio (uma execução ativa por tarefa)
chave de execução idempotente
política de retry com limite e jitter
captura de logs externos para cada fase
atualização de estado pós-execução em tabelas de banco gerenciadas por Drizzle/Neon.

flock foi desenhado exatamente para esse padrão de guarda-rail: adquirir um lock, executar seção crítica, sair limpo quando já estiver bloqueado flock. Como o estado do lock segue descritores de arquivo, janelas cron sobrepostas são explicitamente negadas em vez de corromper estado.

4) Por que MCP importa nesse padrão

O Model Context Protocol formaliza contratos host/cliente/servidor de ferramentas usando JSON-RPC, negociação de capacidade e chamadas de ferramenta estruturadas MCP. Na Naly, limites no estilo MCP reduzem acoplamento implícito: a busca web pode ser representada como uma interface de ferramenta controlada com capacidades explícitas, em vez de comportamento livre em nível de shell.

O que a literatura diz

Pesquisas recentes mostram que confiabilidade não é equivalente à capacidade bruta. O paper AI Agent Reliability reporta lacunas substanciais entre a precisão da tarefa e a consistência entre execuções, e propõe dimensões explícitas de confiabilidade (consistência, robustez, previsibilidade, segurança) para avaliação operacional Towards a Science of AI Agent Reliability. Isso sustenta o design orientado a run-state da Naly: se uma execução tem sucesso, mas não pode ser repetida com artefatos claros, ela não é de nível de produção.

Para saídas estruturadas, o ToolPRM argumenta que o comportamento de chamada de ferramentas estruturadas precisa de supervisão explícita e que as melhorias são especialmente fortes quando se modela o processo interno de function calling, e não apenas resultados finais ToolPRM: Fine-Grained Inference Scaling of Structured Outputs for Function Calling. Isso se alinha ao loop runner schema-first da Naly: o gate de qualidade está nas fronteiras de interface, não apenas na fluência de conteúdo.

Um terceiro paper na mesma fronteira, SLOT, mostra um caminho alternativo prático ao adicionar uma camada de model-agnostic output-shaping em cima de LLMs SLOT: Structuring the Output of Large Language Models. Isso reforça o mesmo princípio: confiabilidade de estrutura é um problema de engenharia mesmo quando a qualidade do modelo base é alta.

Trade-offs de projeto

Esquema rígido vs. portabilidade de modelo: esquemas rígidos reduzem ambiguidade downstream, mas podem aumentar churn ocasional de parse quando provedores interpretam restrições de maneira diferente.
Simplicidade do cron vs. elasticidade de fila: cron é simples e visível, mas cargas de trabalho em rajada precisam de backoff ciente de lock ou de uma camada de fila para evitar execuções sobrepostas e janelas perdidas.
Busca web na tarefa vs. replay determinístico: busca web fresca melhora atualidade, mas introduz volatilidade da fonte; portanto, a Naly armazena texto da consulta, lista de fontes e referências brutas nos artefatos da execução.
Logs externos vs. logs apenas em DB: logs no sistema de arquivos sobrevivem a reinícios de processo e são baratos para ingestão; logs em DB simplificam ergonomia de consulta, mas podem falhar em loops abertos se não forem particionados com cuidado.

Modos de falha

Desvio de esquema: a saída do provedor viola o esquema; mitigação é validação strict fail-fast, fixação de versão de esquema e runs para dead-letter.
Execuções cron sobrepostas: gravações duplicadas ou ações externas duplicadas; mitigação é lock advisory + guarda de encerramento de processo.
Instabilidade de busca: mudanças da resposta da ferramenta upstream entre tentativas; mitigação é teto de retries, atraso exponencial e referências upstream persistidas.
Surpresas de timing: diferenças de DST e de fuso horário do host podem afetar semântica de schedule; mitigação é política de agendamento em UTC e checagens explícitas de ambiente.
Escritas parciais silenciosas: parse tem sucesso, mas gravação downstream falha; mitigação é ordenação de persistência transacional e upserts idempotentes.
Vazamento de segurança/contexto: qualquer caminho de agente com capacidade de ferramenta pode extrapolar, por isso limites de mínimo privilégio no estilo MCP e suposições explícitas de consentimento/autorização são necessários, especialmente onde os caminhos de execução da ferramenta tocam recursos de rede Notas de segurança do MCP.

Notas de implementação

Mantenha um único comando worker por tarefa de negócio em scripts/ e permita que o cron chame apenas esse entrypoint.
Armazene o hash do arquivo de schema nos metadados de execução para que as expectativas do parser sejam auditáveis após uma atualização de modelo.
Defina set -euo pipefail-style em scripts wrapper e inclua sempre run IDs nos nomes de log.
Escreva três pontos de verificação nos logs: started, codex_result_parsed, artifact_persisted.
Use NALY_LOG_ROOT para que rastros de runtime nunca contaminem o estado do repositório e sobrevivam a contextos de reinício.
Persista attempt, exit_code, retry_reasone validation_errors para permitir que dashboards de GST e auditoria separem falhas de infraestrutura intermitente de regressões genuínas do modelo.