spawn-agent: Yerel kodlama ajanlarını Vercel AI SDK modeli gibi kullanmayı sağlayan adaptör

Bu proje, kullanıcının bilgisayarında zaten kurulu olan çeşitli kodlama ajanlarını (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi) alt süreç olarak çalıştırıp bunları Vercel AI SDK'nin LanguageModelV3 arayüzünün arkasına gizleyen bir adaptör kütüphanesidir. İletişim için açık bir spesifikasyon olan Agent Client Protocol (ACP) doğrudan izlenir; standart giriş/çıkış üzerinde NDJSON ile JSON-RPC mesajları alışverişi yapılır. Yapı bir pnpm monorepo'dur; kütüphanenin kendisiyle birlikte deterministik ACP fixture'ları ve WebSocket köprüsü içeren gösterim ve test ortamı ayrı bir workspace olarak ayrılmıştır.

• Birlikte çalışabilirlik tasarımı: Kendi protokolünü oluşturmak yerine ACP standardını aynen kullanır; Cursor, Copilot, Gemini, OpenCode, Droid ve Pi gibi ACP'yi doğrudan konuşan CLI'lar olduğu gibi bağlanır, Claude Code ve Codex ise kendi dönüştürme paketlerinden geçerek aynı arayüz içinde birleştirilir. Spesifikasyonda olmayan özel ACP uygulamaları, kullanıcı tanımlı adaptör biçiminde sisteme eklenebilir.
• AI SDK entegrasyon biçimi: Her çağrıda yeni bir alt süreç başlatan tek seferlik mod ile, bir kez başlatılan alt süreç ve ACP oturumunu koruyarak sonraki çağrılara konuşma belleğini taşıyan oturum modu, aynı model arayüzü üzerinden sunulur. Oturum nesnesi AsyncDisposable uygular; bu sayede await using sözdizimiyle kaynakların serbest bırakılması zorunlu tutulur ve çok turlu konuşmalarda bile sızıntı olmadan kapanan bir akış sağlanır.
• Alt süreç işletim politikası: Standart hata çıktısında yalnızca belirli boyuttaki son bölüm tutulur ve anormal sonlanma durumunda tanılama için kullanılır; standart çıktıya sızan NDJSON dışı satırlar ise gürültü olarak ayrılıp standart hata kanalına taşınır. Kapatma aşamasında önce SIGTERM gönderilir, varsayılan 2 saniyelik bir bekleme süresinin ardından SIGKILL uygulanır; zaten sonlanmış bir sürece girdi gönderme denemesi ayrı bir hata olarak sınıflandırılır. Varsayılan 3 dakikalık etkinliksizlik watchdog'u, kimlik doğrulama başarısızlığı ve kullanım kotası aşımı için metin kalıbı tanıma, ayrıca ACP'nin tanımladığı kimlik doğrulama gerekli ve yöntem bulunamadı yanıt kodlarının eşlemesi de yer alır.
• İzinler ve yetenek pazarlığı: İzin politikası auto-allow, auto-allow-once, auto-reject, stream olmak üzere dört preset'i ve izin taleplerini doğrudan alıp yanıt üreten fonksiyon biçimini destekler. Dosya sistemi, terminal, ek çalışma dizinleri gibi isteğe bağlı özellikler yalnızca host bir handler sağladığında ACP yeteneği olarak ilan edilir; böylece izin yüzeyi daraltılır. İlan edilmemiş bir özelliğin çağrılması veya yeteneklerle uyumsuz prompt içeriği gelmesi durumunda bunlar farklı hata türleriyle reddedilir.
• Hata sınıflandırma sistemi: 16 hata türü tek bir üst sınıf altında hiyerarşik olarak düzenlenmiştir ve tür, tag alanı üzerinden ayırt edilebilir; bu da çağıran tarafta yeniden deneme politikasını dallandırmayı kolaylaştırır. Anormal sonlanma hataları, çıkış kodu veya sinyal ile birlikte standart hata çıktısının son kısmını da mesaja ekleyerek sonradan tanılamayı kolaylaştırır.
• Test yapısı: Başlatma, izinler, iptal, eşzamanlı oturumlar, wire fuzz, kimlik doğrulama yeniden denemesi, watchdog, standart hata üzerinde ölümcül sinyal algılama, harici SDK yükseltmelerine uyumluluk gibi 27 alan ayrı test dosyalarına bölünerek ele alınır. Sahte ajan modülü, kütüphanenin ayrı bir giriş noktası olarak sunulur; böylece kullanım tarafındaki kod da aynı deterministik fixture'ları doğrudan kullanabilir. Gösterim ortamındaki echo ajanı ise ağır bir LLM CLI gerektirmeden iletişim hattının tamamını gerçek bir alt süreç üzerinden doğrulayacak şekilde tasarlanmıştır.
• Mevcut aşama: Hem kök hem de paket sürümü 0.0.1 ve son commit'ler de aynı sürümü tekrar ediyor; bu nedenle proje kamuya açık npm dağıtımından hemen önceki son düzenleme aşamasında görünüyor. Peer bağımlılığı olarak ai@^6.0.0 kullanıyor ve Node 22+, pnpm 8+ gerektiriyor.

Özetle spawn-agent yeni bir ajan çerçevesi değil; halihazırda yerleşmiş ACP standardı ve dağınık kodlama CLI ekosistemi üzerine operasyon politikalarını kalın biçimde giydiren, pratik kullanıma yönelik bir adaptördür. İzin geçidi, etkinliksizlik watchdog'u, kontrollü kapatma süresi, yetenek pazarlığı ve tag tabanlı hata sınıflandırması gibi öğeleri tek yerde toplar ve bunları AI SDK kullanıcılarının alışık olduğu model arayüzü üzerinden sunar; pratik değeri de burada ortaya çıkar.