spawn-agent : un adaptateur pour utiliser des agents de code locaux comme des modèles du SDK IA de Vercel

Ce projet est une bibliothèque d’adaptation qui lance en processus enfants plusieurs agents de code déjà installés sur l’ordinateur de l’utilisateur (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi) et les masque derrière l’interface LanguageModelV3 du SDK IA de Vercel. La communication suit telle quelle l’Agent Client Protocol (ACP), une spécification publique, et échange des messages JSON-RPC en NDJSON sur les entrées/sorties standard. La structure est un monorepo pnpm, et l’environnement de démonstration et de test, doté de fixtures ACP déterministes et d’un pont WebSocket, est séparé en un workspace distinct à côté de la bibliothèque principale.

• Conception axée sur l’interopérabilité : au lieu de créer un protocole maison, le projet utilise directement le standard ACP. Les CLI qui parlent nativement ACP, comme Cursor, Copilot, Gemini, OpenCode, Droid et Pi, se branchent telles quelles, tandis que Claude Code et Codex sont absorbés dans la même interface via leurs paquets de conversion respectifs. Les implémentations ACP non prévues par la spécification peuvent être ajoutées sous forme d’adaptateurs personnalisés.
• Mode d’intégration au SDK IA : le même modèle d’interface expose à la fois un mode éphémère, qui relance un nouveau processus enfant à chaque appel, et un mode session, qui conserve le processus enfant et la session ACP entre les appels suivants afin de préserver la mémoire conversationnelle. L’objet de session implémente AsyncDisposable, ce qui permet d’imposer la libération des ressources avec la syntaxe await using et de garantir une fermeture sans fuite, y compris dans les conversations multi-tours.
• Politique d’exploitation des processus enfants : la sortie d’erreur standard ne conserve qu’une portion finale de taille fixe pour le diagnostic en cas d’arrêt anormal, et les lignes non-NDJSON qui fuient vers la sortie standard sont isolées comme bruit puis redirigées vers le canal d’erreur standard. À l’arrêt, le processus envoie SIGTERM puis, après un délai de grâce de 2 secondes par défaut, déclenche SIGKILL. Les tentatives d’écriture alors que le processus est déjà mort sont distinguées comme une erreur séparée. Le projet inclut aussi un watchdog d’inactivité de 3 minutes par défaut, une détection par motifs textuels pour les échecs d’authentification et les dépassements de quota d’usage, ainsi qu’un mappage des codes de réponse ACP pour les cas « authentification requise » et « méthode absente ».
• Négociation des permissions et des fonctionnalités : la politique d’autorisation propose quatre préréglages — auto-allow, auto-allow-once, auto-reject, stream — ainsi qu’une forme fonctionnelle qui reçoit directement les demandes d’autorisation et construit la réponse. Les fonctionnalités optionnelles comme le système de fichiers, le terminal ou des répertoires de travail supplémentaires ne sont annoncées comme capacités ACP que lorsque l’hôte fournit effectivement les handlers correspondants, ce qui réduit la surface d’autorisation. Si une fonctionnalité non annoncée est appelée, ou si un contenu de prompt n’est pas compatible avec les capacités disponibles, la requête est rejetée avec des types d’erreurs distincts.
• Système de classification des erreurs : 16 types d’erreurs sont hiérarchisés sous une même classe parente, et un champ de tag permet d’en identifier la nature, ce qui facilite le branchement des politiques de retry côté appelant. Les erreurs de terminaison anormale incluent dans leur message le code de sortie, le signal et une portion finale de la sortie d’erreur standard afin d’aider au diagnostic a posteriori.
• Organisation des tests : 27 domaines de test sont traités chacun dans un fichier dédié, notamment l’initialisation, les permissions, l’annulation, les sessions concurrentes, le wire fuzzing, le retry d’authentification, le watchdog, la détection des signaux fatals sur stderr et la compatibilité après mise à niveau d’un SDK externe. Le module d’agent simulé est exposé comme un point d’entrée séparé de la bibliothèque, ce qui permet au code consommateur de réutiliser tel quel les fixtures déterministes, tandis que l’agent écho de l’environnement de démonstration est conçu pour valider toute la chaîne de communication via un véritable processus enfant, sans dépendre d’un CLI LLM lourd.
• État actuel : la racine comme les paquets sont tous en version 0.0.1, et les commits récents répètent la même version, ce qui laisse penser à une phase de finalisation juste avant une publication publique sur npm. Le projet déclare ai@^6.0.0 en peer dependency et requiert Node 22 ou plus, ainsi que pnpm 8 ou plus.

En résumé, spawn-agent n’est pas un nouveau framework d’agents, mais un adaptateur orienté usage réel qui applique une politique d’exploitation étoffée au standard ACP déjà établi et à un ensemble dispersé de CLI de code. Des éléments comme la barrière d’autorisations, le watchdog d’inactivité, le délai de grâce à l’arrêt, la négociation de capacités et la classification des erreurs par tags sont réunis au même endroit, puis exposés via une interface de modèle familière aux utilisateurs du SDK IA, ce qui semble constituer sa principale valeur pratique.