spawn-agent: adaptador para tratar agentes locales de programación como modelos del Vercel AI SDK

Este proyecto es una biblioteca adaptadora que inicia como procesos hijos varios agentes de programación ya instalados en la computadora del usuario (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi) y los oculta detrás de la interfaz LanguageModelV3 del Vercel AI SDK. La comunicación sigue tal cual la especificación pública Agent Client Protocol (ACP), intercambiando mensajes JSON-RPC en NDJSON sobre entrada y salida estándar. Está organizado como un monorepo con pnpm y, junto con la biblioteca principal, separa en workspaces distintos un entorno de demostración y pruebas con fixtures deterministas de ACP y un puente WebSocket.

• Diseño de interoperabilidad: no crea un protocolo propio, sino que usa directamente el estándar ACP. Los CLI que hablan ACP de forma nativa, como Cursor, Copilot, Gemini, OpenCode, Droid y Pi, se conectan tal cual, mientras que Claude Code y Codex se integran mediante sus respectivos paquetes de conversión para absorberse bajo la misma interfaz. Las implementaciones personalizadas de ACP que no estén en la especificación pueden insertarse en forma de adaptadores definidos por el usuario.
• Forma de integración con AI SDK: expone en la misma interfaz de modelo tanto un modo de un solo uso, que inicia un nuevo proceso hijo en cada llamada, como un modo de sesión, que mantiene el proceso hijo ya iniciado y la sesión ACP entre llamadas para conservar la memoria conversacional. Como el objeto de sesión implementa AsyncDisposable, se puede forzar la liberación de recursos con la sintaxis await using, lo que permite imponer un flujo de cierre sin fugas incluso en conversaciones de varios turnos.
• Política de operación de procesos hijos: el error estándar conserva solo el último tramo de tamaño limitado para usarlo en diagnósticos cuando hay una terminación anómala, y las líneas no NDJSON que se escapan por la salida estándar se separan como ruido y se redirigen al canal de error estándar. En la fase de cierre envía SIGTERM y, tras una espera predeterminada de 2 segundos, lanza SIGKILL. Los intentos de entrada cuando el proceso ya murió se distinguen como un error aparte. También incluye un watchdog de inactividad de 3 minutos por defecto, reconocimiento de patrones de texto para fallas de autenticación y exceso de cuota de uso, y mapeo de los códigos de respuesta de ACP para autenticación requerida y método inexistente.
• Permisos y negociación de capacidades: la política de permisos permite cuatro preajustes, auto-allow, auto-allow-once, auto-reject, stream, además de una forma basada en función que recibe directamente las solicitudes de permiso y genera la respuesta. Las funciones opcionales, como sistema de archivos, terminal y directorios de trabajo adicionales, solo se anuncian como capacidades de ACP cuando el host proporciona handlers, reduciendo así la superficie de permisos. Si se invoca una función no anunciada o entra contenido de prompt que no encaja con las capacidades, se rechaza con distintos tipos de error.
• Sistema de clasificación de errores: 16 tipos de error se organizan jerárquicamente bajo una sola clase base, y un campo de etiqueta permite identificar el tipo, lo que facilita ramificar políticas de reintento en el código que llama. Los errores por terminación anómala incluyen en el mensaje el código de salida, la señal y una parte del último error estándar para ayudar al diagnóstico posterior.
• Configuración de pruebas: cubre por separado en archivos de prueba 27 áreas, entre ellas inicialización, permisos, cancelación, sesiones concurrentes, fuzzing del wire, reintentos de autenticación, watchdog, detección de señales fatales en error estándar y compatibilidad con actualizaciones del SDK externo. El módulo de agente simulado se expone como un punto de entrada separado de la biblioteca, de modo que el código que lo use también pueda reutilizar directamente los fixtures deterministas, y el agente de eco del entorno de demostración está diseñado para validar todo el pipeline de comunicación como un proceso hijo real sin necesidad de un CLI de LLM pesado.
• Estado actual: tanto la raíz como los paquetes están en la versión 0.0.1, y los commits recientes también repiten esa misma versión, por lo que parece estar en una etapa de ajuste justo antes de una publicación pública en npm. Declara ai@^6.0.0 como peer y requiere Node 22 o superior y pnpm 8 o superior.

En resumen, spawn-agent no es un nuevo framework de agentes, sino un adaptador orientado al trabajo real que aplica una capa robusta de políticas operativas sobre el estándar ACP ya establecido y sobre activos dispersos de CLI de programación. Reúne en un solo lugar elementos como compuertas de permisos, watchdog de inactividad, gracia de terminación, negociación de capacidades y clasificación de errores basada en etiquetas, y los expone mediante una interfaz de modelo familiar para usuarios de AI SDK, lo que parece ser su valor práctico.