spawn-agent: adaptor untuk memperlakukan agen coding lokal seperti model Vercel AI SDK

Proyek ini adalah pustaka adaptor yang menjalankan berbagai agen coding yang sudah terpasang di komputer pengguna (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi) sebagai child process, lalu menyembunyikannya di balik antarmuka LanguageModelV3 milik Vercel AI SDK. Komunikasi mengikuti spesifikasi terbuka Agent Client Protocol (ACP) apa adanya, dan bertukar pesan JSON-RPC dalam format NDJSON di atas standard input/output. Strukturnya berupa monorepo pnpm, dan selain pustaka utamanya, lingkungan demo dan pengujian dengan fixture ACP deterministik serta bridge WebSocket dipisahkan ke workspace tersendiri.

• Desain interoperabilitas: Alih-alih membuat protokol sendiri, proyek ini memakai standar ACP apa adanya; CLI yang berbicara ACP secara langsung seperti Cursor, Copilot, Gemini, OpenCode, Droid, dan Pi dapat langsung dihubungkan, sementara Claude Code dan Codex diserap ke antarmuka yang sama melalui paket transformasi masing-masing. Implementasi ACP buatan sendiri yang tidak ada dalam spesifikasi dapat disisipkan dalam bentuk adaptor kustom.
• Cara integrasi dengan AI SDK: Mode sekali pakai yang meluncurkan child process baru pada setiap panggilan, dan mode sesi yang mempertahankan child process beserta sesi ACP yang sudah berjalan untuk panggilan berikutnya sehingga memori percakapan tetap terjaga, keduanya diekspos melalui antarmuka model yang sama. Objek sesi mengimplementasikan AsyncDisposable, sehingga pelepasan sumber daya dapat dipaksakan melalui sintaks await using, dan alur penutupan tanpa kebocoran dapat ditegakkan bahkan dalam percakapan multi-turn.
• Kebijakan operasi child process: Standard error hanya menyimpan bagian akhir dengan ukuran tertentu untuk dipakai dalam diagnosis saat terjadi terminasi abnormal, dan baris non-NDJSON yang bocor ke standard output dipisahkan sebagai noise lalu dipindahkan ke kanal standard error. Pada tahap penghentian, sistem mengirim SIGTERM lalu setelah masa tenggang bawaan 2 detik menembakkan SIGKILL, dan percobaan input saat proses sudah mati dibedakan sebagai error tersendiri. Tersedia pula watchdog tidak aktif bawaan 3 menit, pengenalan pola teks untuk kegagalan autentikasi dan kuota penggunaan terlampaui, serta pemetaan kode respons ACP untuk kebutuhan autentikasi dan metode yang tidak tersedia.
• Negosiasi izin dan kemampuan: Kebijakan izin mendukung empat preset, yaitu auto-allow, auto-allow-once, auto-reject, dan stream, serta juga bentuk fungsi yang menerima permintaan izin secara langsung dan membuat responsnya. Fitur opsional seperti filesystem, terminal, dan direktori kerja tambahan hanya diiklankan sebagai capability ACP saat host menyediakan handler, sehingga mempersempit permukaan izin; jika fitur yang tidak diiklankan dipanggil atau konten prompt tidak sesuai dengan capability, permintaan akan ditolak dengan jenis error yang berbeda.
• Sistem klasifikasi error: Ada 16 jenis error yang dihierarkikan di bawah satu kelas induk, dan jenisnya dapat dibedakan melalui field tag, sehingga memudahkan percabangan kebijakan retry di sisi pemanggil. Error terminasi abnormal menyertakan kode keluar/sinyal beserta sebagian standard error terakhir di dalam pesan untuk membantu diagnosis pascakejadian.
• Susunan pengujian: Sebanyak 27 area seperti inisialisasi, izin, pembatalan, sesi serentak, wire fuzz, retry autentikasi, watchdog, deteksi sinyal fatal di standard error, dan kompatibilitas terhadap upgrade SDK eksternal ditangani dalam file uji terpisah masing-masing. Modul agen tiruan diekspos sebagai entry point terpisah dari pustaka sehingga kode pengguna juga dapat langsung memakai fixture deterministik yang sama, dan agen echo di lingkungan demo dirancang untuk memverifikasi seluruh pipeline komunikasi sebagai child process nyata tanpa CLI LLM yang berat.
• Tahap saat ini: Root dan paket sama-sama berada di versi 0.0.1, dan commit terbaru juga terus mengulang versi yang sama, sehingga tampak berada pada tahap perapian sebelum rilis npm publik. Dependensi peer yang digunakan adalah ai@^6.0.0, serta mensyaratkan Node 22 ke atas dan pnpm 8 ke atas.

Singkatnya, spawn-agent bukan framework agen baru, melainkan adaptor siap pakai untuk kebutuhan praktis yang menambahkan lapisan kebijakan operasional di atas standar ACP yang sudah mapan dan aset CLI coding yang tersebar. Elemen seperti gerbang izin, watchdog ketidakaktifan, masa tenggang penghentian, negosiasi capability, dan klasifikasi error berbasis tag dikumpulkan di satu tempat, lalu semuanya diekspos melalui antarmuka model yang akrab bagi pengguna AI SDK, yang tampak menjadi nilai praktis utamanya.