spawn-agent - 코딩 에이전트를 Vercel AI SDK 모델처럼 다루는 어댑터
로컬 코딩 에이전트(Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Factory Droid, Pi)를 Vercel AI SDK의 LanguageModelV3 인터페이스 뒤로 감추는 어댑터 라이브러리.
핵심 개요
| 항목 | 값 |
|---|---|
| 언어 | TypeScript |
| 구조 | pnpm 모노레포 |
| 의존성 | ai@^6.0.0 |
| 최소 Node | 22+ |
| 버전 | 0.0.1 |
| Points | 1 |
지원하는 코딩 에이전트
- ACP 직접 지원: Cursor, Copilot, Gemini, OpenCode, Droid, Pi
- 변환 필요: Claude Code, Codex (각각 변환 패키지)
주요 설계
ACP 표준 채택
자신의 프로토콜이 아닌 Agent Client Protocol(ACP) 표준을 그대로 사용. STDIO + NDJSON으로 통신.
2가지 실행 모드
- 일회성 모드: 매 호출마다 자식 프로세스 새로 띄움
- 세션 모드: 한 번 띄운 프로세스와 대화 메모리 유지
세션 객체는 AsyncDisposable 구현으로 await using으로 강제 자원 해제.
운영 정책
- 워치독: 기본 3분 비활동 타임아웃
- 종료 정책: SIGTERM → 2초 대기 → SIGKILL
- 에러 처리: 종료 코드·시그널 + 마지막 stderr 일부를 메시지에 포함
- 인증 감지: 텍스트 패턴 인식으로 인증 실패/사용량 초과 감지
권한 관리
| 프리셋 | 설명 |
|---|---|
auto-allow | 자동 허용 |
auto-allow-once | 1회 허용 |
auto-reject | 자동 거부 |
stream | 스트림 |
| 함수형 | 직접 응답하는 핸들러 |
선택적 기능(파일시스템, 터미널 등)은 핸들러 제공 시에만 ACP 능력으로 광고.
오류 분류
16종 오류가 하나의 상위 클래스 아래 계층화. 태그 필드로 재시도 정책 분기 가능.
테스트 구성
27개 테스트 영역: 초기화, 권한, 취소, 동시 세션, 와이어 퍼즈, 워치독, SDK 업그레이드 호환 등.
실용적 가치
새로운 에이전트 프레임워크가 아니라, ACP 표준 위에 운영 정책(권한 게이트, 워치독, 종료 유예, 능력 협상, 오류 분류)을 두른 실무용 어댑터.
관련 도구
- moc-claude-code - Anthropic Claude Code CLI
- codex - OpenAI Codex CLI
- cursor - Cursor AI IDE
- opencode - Native Rust/GPUI AI 코딩 에이전트
출처
- 원본: github.com/millionco/spawn-agent
- GeekNews: https://news.hada.io/topic?id=29043