spawn-agent: Ein Adapter, der lokale Coding-Agenten wie Modelle im Vercel AI SDK behandelt

Dieses Projekt ist eine Adapter-Bibliothek, die verschiedene Coding-Agenten, die bereits auf dem Computer des Nutzers installiert sind (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi), als Kindprozesse startet und hinter der LanguageModelV3-Schnittstelle des Vercel AI SDK verbirgt. Die Kommunikation folgt unverändert der offenen Spezifikation Agent Client Protocol (ACP) und tauscht JSON-RPC-Nachrichten als NDJSON über Standard-Ein- und -Ausgabe aus. Es verwendet eine pnpm-Monorepo-Struktur; neben der eigentlichen Bibliothek sind eine Demo- und Testumgebung mit deterministischen ACP-F Fixtures und einer WebSocket-Bridge als separate Workspaces aufgeteilt.

• Interoperabilitätsdesign: Statt ein eigenes Protokoll zu entwickeln, wird der ACP-Standard unverändert verwendet. CLI-Tools, die ACP direkt sprechen, wie Cursor, Copilot, Gemini, OpenCode, Droid und Pi, können direkt angebunden werden; Claude Code und Codex werden jeweils über eigene Transformationspakete in dieselbe Schnittstelle integriert. Eigene ACP-Implementierungen, die nicht in der Spezifikation enthalten sind, lassen sich in Form benutzerdefinierter Adapter einfügen.
• Art der AI-SDK-Integration: Pro Aufruf wird entweder im Einmalmodus jedes Mal ein neuer Kindprozess gestartet, oder im Sitzungsmodus bleibt ein einmal gestarteter Kindprozess mitsamt ACP-Sitzung für den nächsten Aufruf erhalten, sodass Gesprächsspeicher bewahrt wird. Das Sitzungsobjekt implementiert AsyncDisposable, wodurch mit der Syntax await using die Freigabe von Ressourcen erzwungen wird und auch in Multi-Turn-Gesprächen ein sauberer Abschluss ohne Lecks sichergestellt werden kann.
• Betriebsrichtlinien für Kindprozesse: Von Standard Error wird nur ein letzter Abschnitt bis zu einer bestimmten Größe aufbewahrt und bei abnormaler Beendigung für Diagnosen verwendet; nicht als NDJSON formatierte Zeilen, die über Standard Output austreten, werden als Rauschen getrennt und in den Standard-Error-Kanal verschoben. In der Beendigungsphase wird zunächst SIGTERM gesendet und nach einer standardmäßigen Schonfrist von 2 Sekunden SIGKILL ausgelöst. Eingabeversuche an bereits beendete Prozesse werden als eigener Fehlertyp unterschieden. Enthalten sind außerdem ein standardmäßiger Inaktivitäts-Watchdog von 3 Minuten, texbasiertes Mustererkennen für Authentifizierungsfehler und überschrittene Nutzungslimits sowie die Zuordnung der von ACP definierten Antwortcodes für erforderliche Authentifizierung und fehlende Methoden.
• Berechtigungen und Funktionsaushandlung: Für die Berechtigungsrichtlinie gibt es die vier Presets auto-allow, auto-allow-once, auto-reject und stream, außerdem sind auch Funktionen zulässig, die Berechtigungsanfragen direkt entgegennehmen und Antworten erzeugen. Optionale Funktionen wie Dateisystem, Terminal oder zusätzliche Arbeitsverzeichnisse werden nur dann als ACP-Fähigkeiten angekündigt, wenn der Host entsprechende Handler bereitstellt, wodurch die Berechtigungsoberfläche verkleinert wird. Werden nicht angekündigte Funktionen aufgerufen oder Prompt-Inhalte übergeben, die nicht zu den Fähigkeiten passen, wird dies jeweils mit unterschiedlichen Fehlertypen abgewiesen.
• System zur Fehlerklassifizierung: 16 Fehlerarten sind unter einer gemeinsamen Oberklasse hierarchisch organisiert, und über ein Tag-Feld lässt sich der Typ unterscheiden, was es für den aufrufenden Code erleichtert, Retry-Richtlinien zu verzweigen. Fehler bei abnormaler Beendigung enthalten zusammen mit Exit-Code oder Signal auch einen Teil der letzten Standard-Error-Ausgabe in der Meldung, was die nachträgliche Diagnose unterstützt.
• Testaufbau: 27 Bereiche wie Initialisierung, Berechtigungen, Abbruch, parallele Sitzungen, Wire-Fuzzing, Authentifizierungs-Retries, Watchdog, Erkennung fataler Signale auf Standard Error sowie Kompatibilität mit Upgrades externer SDKs werden jeweils in eigenen Testdateien behandelt. Das Modul für Mock-Agenten wird als separater Einstiegspunkt der Bibliothek bereitgestellt, sodass auch Nutzungscode dieselben deterministischen Fixtures direkt übernehmen kann. Der Echo-Agent der Demo-Umgebung ist so konzipiert, dass die gesamte Kommunikationspipeline mit echten Kindprozessen auch ohne schwere LLM-CLI validiert werden kann.
• Aktueller Stand: Sowohl Root als auch Pakete tragen die Version 0.0.1, und auch die jüngsten Commits wiederholen dieselbe Version, was nach einer letzten Bereinigungsphase direkt vor der öffentlichen npm-Veröffentlichung aussieht. Als Peer-Abhängigkeit wird ai@^6.0.0 verwendet; erforderlich sind Node 22 oder höher sowie pnpm 8 oder höher.

Kurz gesagt ist spawn-agent kein neues Agenten-Framework, sondern ein praxisorientierter Adapter, der auf den bereits etablierten ACP-Standard und verstreute Coding-CLI-Ressourcen eine umfangreiche Betriebspolitik aufsetzt. Elemente wie Permission-Gates, Inaktivitäts-Watchdog, Beendigungsfrist, Capability-Aushandlung und tagbasierte Fehlerklassifizierung sind an einem Ort gebündelt und werden Nutzern des AI SDK über eine vertraute Modellschnittstelle zugänglich gemacht, was den praktischen Wert ausmacht.