spawn-agent: bộ chuyển đổi giúp xử lý coding agent cục bộ như mô hình của Vercel AI SDK

Dự án này là một thư viện adapter khởi chạy nhiều coding agent đã được cài sẵn trên máy người dùng (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi) dưới dạng tiến trình con, rồi ẩn chúng phía sau giao diện LanguageModelV3 của Vercel AI SDK. Việc giao tiếp tuân theo nguyên bản đặc tả công khai Agent Client Protocol (ACP), trao đổi thông điệp JSON-RPC bằng NDJSON trên standard input/output. Dự án dùng cấu trúc pnpm monorepo, và ngoài phần thư viện chính còn tách riêng môi trường demo/kiểm thử với fixture ACP mang tính quyết định cùng cầu nối WebSocket thành các workspace riêng biệt.

• Thiết kế tương tác liên vận: Không tạo giao thức riêng mà dùng nguyên chuẩn ACP; các CLI nói trực tiếp ACP như Cursor, Copilot, Gemini, OpenCode, Droid, Pi có thể gắn vào ngay, còn Claude Code và Codex được hấp thụ vào cùng một giao diện thông qua các gói chuyển đổi tương ứng. Các triển khai ACP tùy chỉnh không có trong đặc tả cũng có thể được cắm vào dưới dạng adapter do người dùng tự định nghĩa.
• Cách tích hợp với AI SDK: Thư viện cung cấp trên cùng một giao diện model cả chế độ dùng một lần, nơi mỗi lần gọi đều khởi chạy tiến trình con mới, lẫn chế độ phiên, nơi giữ nguyên tiến trình con và phiên ACP đã mở để bảo toàn bộ nhớ hội thoại cho lần gọi tiếp theo. Đối tượng phiên triển khai AsyncDisposable, vì vậy có thể dùng cú pháp await using để buộc giải phóng tài nguyên, giúp đảm bảo luồng đóng sạch không rò rỉ ngay cả trong hội thoại nhiều lượt.
• Chính sách vận hành tiến trình con: Standard error chỉ giữ lại phần cuối với kích thước nhất định để phục vụ chẩn đoán khi thoát bất thường, còn các dòng không phải NDJSON rò ra standard output sẽ được tách thành nhiễu và chuyển sang kênh standard error. Ở bước kết thúc, thư viện gửi SIGTERM rồi chờ mặc định 2 giây trước khi phát SIGKILL; các lần thử ghi dữ liệu khi tiến trình đã chết được phân loại thành lỗi riêng. Đi kèm còn có watchdog không hoạt động mặc định 3 phút, nhận diện mẫu văn bản cho lỗi xác thực và vượt hạn mức sử dụng, cùng ánh xạ mã phản hồi ACP cho các trường hợp yêu cầu xác thực hoặc không có phương thức được định nghĩa.
• Đàm phán quyền hạn và tính năng: Chính sách quyền hỗ trợ bốn preset auto-allow, auto-allow-once, auto-reject, stream, đồng thời cho phép truyền vào một hàm tự nhận yêu cầu quyền và tạo phản hồi. Các tính năng tùy chọn như filesystem, terminal, thư mục làm việc bổ sung chỉ được quảng bá như capability ACP khi host thực sự cung cấp handler, qua đó thu hẹp bề mặt quyền. Nếu gọi một tính năng chưa được quảng bá hoặc đưa vào nội dung prompt không phù hợp với capability, hệ thống sẽ từ chối bằng các loại lỗi khác nhau.
• Hệ thống phân loại lỗi: Có 16 loại lỗi được phân cấp dưới một lớp cha duy nhất, và có thể dùng trường tag để phân biệt loại, thuận tiện cho phía gọi phân nhánh chính sách retry. Lỗi thoát bất thường sẽ kèm mã thoát, signal và một phần standard error cuối trong thông điệp để hỗ trợ chẩn đoán hậu kiểm.
• Cấu trúc kiểm thử: 27 mảng gồm khởi tạo, quyền hạn, hủy, phiên đồng thời, wire fuzz, retry xác thực, watchdog, phát hiện tín hiệu nghiêm trọng từ standard error, tương thích khi nâng cấp SDK bên ngoài... được tách thành các file test riêng. Module agent giả lập được xuất ra như một entry point riêng của thư viện, nên mã phía sử dụng cũng có thể mang các fixture mang tính quyết định vào dùng nguyên xi; còn echo agent trong môi trường demo được thiết kế để kiểm chứng toàn bộ pipeline giao tiếp bằng tiến trình con thực mà không cần CLI LLM nặng.
• Giai đoạn hiện tại: Cả root lẫn package đều đang ở phiên bản 0.0.1, và các commit gần đây cũng lặp lại cùng phiên bản này, cho thấy dự án đang trong giai đoạn hoàn thiện trước khi phát hành công khai lên npm. Dự án khai báo peer ai@^6.0.0, đồng thời yêu cầu Node 22 trở lên và pnpm 8 trở lên.

Tóm lại, spawn-agent không phải một framework agent mới mà là một adapter thực dụng, đặt các chính sách vận hành dày dặn lên trên chuẩn ACP đã định hình và các tài sản coding CLI đang phân tán. Các yếu tố như cổng quyền hạn, watchdog không hoạt động, thời gian ân hạn khi kết thúc, đàm phán capability, và phân loại lỗi dựa trên tag đều được gom vào một chỗ, rồi được phơi bày qua giao diện model quen thuộc với người dùng AI SDK, tạo nên giá trị thực tiễn rõ rệt.