Catatan Teknik Naly: Codex CLI, JSON Terstruktur, dan Pekerja AI yang Aman untuk Cron

Abstrak

Naly menggunakan Codex CLI sebagai control plane untuk pekerjaan AI terjadwal: setiap entri cron menjalankan skrip yang sudah masuk repositori yang memulai tugas asisten yang dibatasi dengan pencarian web dan kontrak keluaran yang ketat, lalu menulis artefak JSON tervalidasi untuk publikasi hilir, replay, dan retry. Ini membuat kerja model berperilaku seperti pipeline operasional 8 command sama, skema eksplisit, artefak eksplisit 9 daripada alur kerja interaktif yang dapat berubah. Pada 2026-06-25, perbedaan ini adalah keunggulan keandalan untuk infrastruktur konten yang kritis bagi pertumbuhan.

Posisinya dalam Naly

Naly sudah memiliki prioritas GST aktif pada alur discovery, retensi, dan distribusi. Pola ini langsung cocok dengan lapisan eksekusinya secara langsung:

Cron job memanggil satu tsx skrip per use case sehingga setiap run tetap berada di dalam kode yang sudah terversi, bukan potongan shell ad hoc.
Codex CLI melakukan tugas reasoning dan retrieval, sementara Naly menangani kontrol orkestrasi: penjadwalan, retry, penguncian, dan artefak yang awet.
Output terstruktur memberi makan sistem hilir yang dibangun di atas Next.js, React, Drizzle ORM, dan Neon tanpa menebak-nebak skema hilir.
Log eksternal dan metadata run ditulis di bawah NALY_LOG_ROOT, membuat post-mortem dapat direproduksi secara independen dari buffering output proses.

Intinya adalah: untuk penggunaan produksi, kualitas LLM hanyalah separuh dari sistem; batasan yang deterministik di sekitar LLM adalah separuh lainnya.

Mekanisme teknis

1) Titik masuk worker berbasis kontrak terlebih dahulu

Setiap tugas dimulai dari tiga input yang tidak berubah:

Template prompt yang sudah dikodifikasi dan niat tugas.
Skema respons yang harus divalidasi.
Run envelope (run_id, source_query, attempt, env), disimpan sebelum pemanggilan API.

Naly memanggil Codex CLI dalam mode batch dari cron, bukan mode interaktif. Codex didokumentasikan sebagai agen coding lokal dan dirilis sebagai CLI mandiri dengan distribusi sumber terbuka dan rilis aktif, serta bisa dijalankan di lingkungan skrip Codex CLI, Repositori OpenAI Codex.

2) Mengapa output terstruktur adalah keharusan

Panduan output terstruktur OpenAI menjelaskan ekstraksi skema yang didukung parser dan perilaku mode ketat yang dibutuhkan untuk pipeline mesin. Di Naly, output model diperlakukan sebagai artefak intermediat, bukan kebenaran final, sehingga kontrak JSON adalah tempat keandalan ditegakkan:

field wajib (headline, evidence list, confidence, citations, failure reason)
field opsional dengan nilai default
confidence numerik dan enum terbatas
kegagalan parser yang eksplisit muncul sebagai error run, bukan teks yang dikoreksi otomatis secara diam-diam.

3) Siklus hidup cron-to-agent dengan kontrol konkurensi

Cron menjalankan baris terjadwal sesuai dengan field waktu standar 5-field dan meluncurkan perintah saat field cocok crontab. Untuk safety produksi Naly menambahkan:

pengaman kunci (satu run aktif per tugas)
kunci run idempotent
kebijakan retry terbatas dengan jitter
penangkapan log eksternal untuk setiap fase
pembaruan status pasca-run pada tabel database yang dikelola Drizzle/Neon.

flock dirancang tepat untuk pola guardrail ini: ambil lock, jalankan bagian kritis, keluar dengan bersih saat sudah terkunci flock. Karena state lock mengikuti file descriptor, jendela cron yang tumpang tindih secara eksplisit ditolak alih-alih merusak state.

4) Mengapa MCP penting dalam pola ini

Model Context Protocol memformalkan kontrak alat host/client/server menggunakan JSON-RPC, negosiasi kemampuan, dan pemanggilan tool terstruktur MCP. Di Naly, batasan bergaya MCP mengurangi coupling implisit: pencarian web dapat direpresentasikan sebagai antarmuka tool terkontrol dengan kemampuan eksplisit alih-alih perilaku tingkat shell yang bebas bentuk.

Apa yang dikatakan literatur

Riset terbaru menunjukkan bahwa keandalan tidak sama dengan kemampuan mentah. Paper AI Agent Reliability melaporkan kesenjangan besar antara akurasi tugas dan konsistensi antar run, serta mengusulkan dimensi keandalan yang eksplisit (consistency, robustness, predictability, safety) untuk evaluasi operasional Towards a Science of AI Agent Reliability. Ini mendukung desain run-state-first Naly: jika sebuah run sukses tetapi tidak bisa diulang dengan artefak yang jelas, maka itu tidak layak produksi.

Untuk output terstruktur, ToolPRM berargumen bahwa perilaku function-calling terstruktur membutuhkan supervisi eksplisit dan bahwa peningkatan kualitas sangat terasa saat memodelkan proses pemanggilan fungsi internal, bukan hanya outcome akhir ToolPRM: Fine-Grained Inference Scaling of Structured Outputs for Function Calling. Itu selaras dengan loop runner schema-first Naly: gerbang kualitas berada di batas antarmuka, bukan sekadar kefasihan konten.

Paper ketiga di frontier yang sama, SLOT, menunjukkan jalur alternatif praktis dengan menambahkan lapisan pembentuk output yang model-agnostic di atas LLM SLOT: Structuring the Output of Large Language Models. Ini menguatkan prinsip yang sama: reliabilitas struktur adalah persoalan engineering meski kualitas model dasar sangat tinggi.

Trade-off desain

Skema ketat vs portabilitas model: skema ketat mengurangi ambiguitas hilir tetapi bisa meningkatkan churn parse sesekali saat provider menginterpretasikan batasan secara berbeda.
Kesederhanaan cron vs elastisitas antrian: cron itu sederhana dan terlihat, tetapi beban kerja bursty memerlukan backoff yang sadar lock atau lapisan queue untuk menghindari run yang tumpang tindih dan window yang terlewat.
Pencarian web dalam tugas vs replay deterministik: pencarian web yang segar meningkatkan freshness tetapi memperkenalkan volatilitas sumber; karena itu, Naly menyimpan teks query, daftar sumber, dan referensi mentah di artefak run.
Log eksternal vs. log DB saja: log filesystem bertahan terhadap restart proses dan murah untuk ingestion; log DB menyederhanakan ergonomi query tapi bisa gagal karena open loops jika tidak dipartisi dengan cermat.

Mode kegagalan

Drift skema: output provider melanggar skema; mitigasinya adalah fail-fast validasi ketat, pinning versi skema, dan run dead-letter.
Eksekusi cron tumpang tindih: penulisan ganda atau tindakan eksternal duplikat; mitigasinya adalah advisory lock + process-exit guard.
Ketidakstabilan pencarian: respons tool di hulu berubah antar percobaan; mitigasinya adalah batas retry, delay eksponensial, dan referensi hulu yang dipertahankan.
Kejutan timing: perbedaan DST dan zona waktu host dapat memengaruhi makna jadwal; mitigasinya adalah kebijakan penjadwalan UTC dan pemeriksaan lingkungan yang eksplisit.
Penulisan parsial diam-diam: parse berhasil tetapi penulisan hilir gagal; mitigasinya adalah urutan persistensi transaksi dan upsert yang idempotent.
Kebocoran keamanan/konteks: jalur agen yang bisa menjalankan tool bisa berlebihan, jadi batasan least-privilege bergaya MCP dan asumsi consent/auth yang eksplisit dibutuhkan, terutama saat jalur eksekusi tool menyentuh sumber daya jaringan Catatan keamanan MCP.

Catatan implementasi

Pertahankan satu perintah worker per tugas bisnis di scripts/ dan biarkan cron memanggil hanya titik masuk itu.
Simpan hash file skema di metadata run agar ekspektasi parser dapat diaudit setelah upgrade model.
Setel set -euo pipefailperilaku bergaya -e pada skrip wrapper dan selalu sertakan run ID dalam nama log.
Tulis tiga checkpoint ke log: started, codex_result_parsed, artifact_persisted.
Gunakan NALY_LOG_ROOT agar jejak runtime tidak mencemari state repositori dan tetap bertahan saat konteks restart.
Pertahankan attempt, exit_code, retry_reason, dan validation_errors agar GST dan dashboard audit bisa membedakan infrastruktur yang fluktuatif dari regresi model yang benar-benar terjadi.