spawn-agent: 로컬 코딩 에이전트를 Vercel AI SDK 모델처럼 다루는 어댑터

이 프로젝트는 사용자의 컴퓨터에 이미 설치된 여러 코딩 에이전트(Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi)를 자식 프로세스로 띄워, Vercel AI SDK의 LanguageModelV3 인터페이스 뒤로 감추어 주는 어댑터 라이브러리입니다. 통신은 공개 명세인 Agent Client Protocol(ACP)을 그대로 따르며, 표준 입출력 위에서 NDJSON으로 JSON-RPC 메시지를 주고받습니다. pnpm 모노레포 구조이고, 라이브러리 본체와 함께 결정적 ACP 픽스처와 WebSocket 브리지를 갖춘 시연·테스트 환경이 별도 워크스페이스로 분리되어 있습니다.

• 상호운용 설계: 자체 프로토콜을 만들지 않고 ACP 표준을 그대로 사용하며, Cursor, Copilot, Gemini, OpenCode, Droid, Pi처럼 ACP를 직접 말하는 CLI는 그대로 붙고, Claude Code와 Codex는 각각의 변환 패키지를 거쳐 동일한 인터페이스로 흡수됩니다. 명세에 없는 자체 ACP 구현체는 사용자 정의 어댑터 형태로 끼워 넣을 수 있습니다.
• AI SDK 통합 방식: 매 호출마다 자식 프로세스를 새로 띄우는 일회성 모드와, 한 번 띄운 자식 프로세스와 ACP 세션을 그대로 유지해 다음 호출까지 대화 메모리를 보존하는 세션 모드를 같은 모델 인터페이스로 노출합니다. 세션 객체는 AsyncDisposable을 구현하므로 await using 구문으로 자원 해제가 강제되어, 멀티턴 대화에서도 누수 없이 닫히는 흐름을 강제할 수 있습니다.
• 자식 프로세스 운영 정책: 표준 에러는 일정 크기의 마지막 구간만 보존해 비정상 종료 시 진단에 사용하고, 표준 출력으로 새어 나오는 비-NDJSON 라인은 노이즈로 분리해 표준 에러 채널로 옮깁니다. 종료 단계에서는 SIGTERM을 보낸 뒤 기본 2초의 유예 후 SIGKILL을 발사하며, 이미 죽은 상태에서의 입력 시도는 별도 오류로 구분합니다. 기본 3분의 비활동 워치독, 인증 실패와 사용량 한도 초과를 위한 텍스트 패턴 인식, ACP가 정의한 인증 필요·메서드 부재 응답 코드 매핑이 함께 들어가 있습니다.
• 권한과 기능 협상: 권한 정책은 auto-allow, auto-allow-once, auto-reject, stream 네 프리셋과, 권한 요청을 직접 받아 응답을 만드는 함수 형태까지 허용합니다. 파일시스템, 터미널, 추가 작업 디렉터리 같은 선택 기능은 호스트가 핸들러를 제공할 때만 ACP 능력으로 광고되어 권한 표면을 좁히며, 광고되지 않은 기능을 호출하거나 능력에 맞지 않는 프롬프트 콘텐츠가 들어오면 각각 다른 종류의 오류로 거절합니다.
• 오류 분류 체계: 16종의 오류가 하나의 상위 클래스 아래 계층화되어 있고, 태그 필드로 종류를 판별할 수 있어 호출부에서 재시도 정책을 분기하기 좋습니다. 비정상 종료 오류는 종료 코드·시그널과 함께 마지막 표준 에러 일부를 메시지에 함께 담아 사후 진단을 돕습니다.
• 테스트 구성: 초기화, 권한, 취소, 동시 세션, 와이어 퍼즈, 인증 재시도, 워치독, 표준 에러 치명 신호 감지, 외부 SDK 업그레이드 호환 등 27개 영역을 각각의 테스트 파일로 분리해 다룹니다. 모의 에이전트 모듈은 라이브러리의 별도 진입점으로 노출되어 사용처 코드에서도 결정적 픽스처를 그대로 가져다 쓸 수 있고, 시연 환경의 에코 에이전트는 무거운 LLM CLI 없이 통신 파이프라인 전체를 실제 자식 프로세스로 검증하도록 설계되어 있습니다.
• 현재 단계: 루트와 패키지 모두 버전이 0.0.1이고 최근 커밋도 같은 버전을 반복하고 있어 공개 npm 배포 직전의 정비 단계로 보입니다. peer로 ai@^6.0.0을 잡고 있으며 Node 22 이상, pnpm 8 이상을 요구합니다.

정리하자면 spawn-agent는 새로운 에이전트 프레임워크가 아니라, 이미 자리잡은 ACP 표준과 흩어진 코딩 CLI 자산 위에 운영 정책을 두껍게 입힌 실무용 어댑터입니다. 권한 게이트, 비활동 워치독, 종료 유예, 능력 협상, 태그 기반 오류 분류 같은 요소들이 한곳에 모여 있으며, AI SDK 사용자에게 익숙한 모델 인터페이스로 이 모두를 노출한다는 점이 실용적 가치로 보입니다.