spawn-agent: adaptador para tratar agentes locais de programação como modelos do Vercel AI SDK

Este projeto é uma biblioteca adaptadora que inicia como processos-filho vários agentes de programação já instalados no computador do usuário (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi) e os esconde por trás da interface LanguageModelV3 do Vercel AI SDK. A comunicação segue exatamente a especificação pública Agent Client Protocol (ACP), trocando mensagens JSON-RPC em NDJSON sobre entrada e saída padrão. A estrutura é um monorepo pnpm e, além da biblioteca principal, o ambiente de demonstração e testes com fixtures ACP determinísticos e uma ponte WebSocket fica separado em workspaces próprios.

• Projeto de interoperabilidade: em vez de criar um protocolo próprio, usa o padrão ACP como está; CLIs que falam ACP diretamente, como Cursor, Copilot, Gemini, OpenCode, Droid e Pi, conectam-se sem mudanças, enquanto Claude Code e Codex são absorvidos na mesma interface por meio de pacotes de conversão próprios. Implementações ACP próprias fora da especificação podem ser encaixadas como adaptadores personalizados.
• Forma de integração com o AI SDK: expõe, na mesma interface de modelo, tanto o modo descartável que inicia um novo processo-filho a cada chamada quanto o modo de sessão, que mantém o processo-filho e a sessão ACP para preservar a memória da conversa até a próxima chamada. Como o objeto de sessão implementa AsyncDisposable, o uso de await using força a liberação de recursos, permitindo encerrar fluxos de conversas multi-turno sem vazamentos.
• Política de operação dos processos-filho: o erro padrão preserva apenas a parte final dentro de um tamanho fixo para diagnóstico em caso de encerramento anormal, e linhas não-NDJSON que escapam pela saída padrão são separadas como ruído e movidas para o canal de erro padrão. Na etapa de encerramento, envia SIGTERM e, após a carência padrão de 2 segundos, dispara SIGKILL; tentativas de entrada quando o processo já morreu são tratadas como um erro separado. Também inclui watchdog de inatividade com padrão de 3 minutos, reconhecimento de padrões de texto para falha de autenticação e estouro de limite de uso, além do mapeamento dos códigos de resposta de autenticação necessária e método ausente definidos pelo ACP.
• Permissões e negociação de capacidades: a política de permissões aceita os quatro presets auto-allow, auto-allow-once, auto-reject, stream, além de uma função que recebe diretamente solicitações de permissão e monta a resposta. Recursos opcionais como sistema de arquivos, terminal e diretórios de trabalho adicionais só são anunciados como capacidades ACP quando o host fornece handlers, reduzindo a superfície de permissões; se um recurso não anunciado for chamado ou se entrar conteúdo de prompt incompatível com as capacidades, a chamada é rejeitada com tipos de erro diferentes em cada caso.
• Sistema de classificação de erros: 16 tipos de erro são organizados em hierarquia sob uma única classe base, e o tipo pode ser identificado por um campo de tag, o que facilita ramificar políticas de retry no lado chamador. Erros de encerramento anormal também carregam, junto com o código de saída e o sinal, parte final do erro padrão na mensagem para ajudar na análise posterior.
• Composição dos testes: 27 áreas, incluindo inicialização, permissões, cancelamento, sessões simultâneas, fuzzing do wire, retry de autenticação, watchdog, detecção de sinal fatal no erro padrão e compatibilidade com upgrades de SDKs externos, são tratadas em arquivos de teste separados. O módulo de agente simulado é exposto como um ponto de entrada separado da biblioteca, permitindo que o código consumidor reutilize os mesmos fixtures determinísticos, e o agente de eco do ambiente de demonstração foi projetado para validar todo o pipeline de comunicação como processo-filho real sem depender de um CLI de LLM pesado.
• Estágio atual: tanto a raiz quanto os pacotes estão na versão 0.0.1, e os commits recentes repetem a mesma versão, o que sugere uma fase de ajustes imediatamente anterior à publicação pública no npm. O projeto define ai@^6.0.0 como peer e exige Node 22 ou superior e pnpm 8 ou superior.

Em resumo, spawn-agent não é um novo framework de agentes, mas um adaptador voltado ao uso prático que aplica políticas operacionais robustas sobre o padrão ACP já estabelecido e o conjunto disperso de CLIs de programação. Elementos como gate de permissões, watchdog de inatividade, carência de encerramento, negociação de capacidades e classificação de erros baseada em tags ficam reunidos em um só lugar, e o valor prático parece estar em expor tudo isso por meio de uma interface de modelo familiar para usuários do AI SDK.