프로토콜 개요

프로토콜 개요는 snowpea 데몬과 클라이언트가 WebSocket JSON-RPC로 통신하는 방식, 버전 규칙, 레퍼런스 읽는 순서를 설명합니다.

이 문서에서 다루는 내용

• 생성 방식 이해하기
• 연결 방식 확인하기
• 연결 시작하기
• 버전 규칙 확인하기
• 읽을 순서 고르기
• 실제 데이터 확인하기

생성 방식 이해하기

프로토콜은 core/snowpea_core/server/protocol.py 에 정의됩니다. 이 파일은 PROTOCOL_VERSION, 모든 메서드의 파라미터·결과 스키마, 모든 이벤트 페이로드를 포함합니다.

생성물은 레퍼런스 문서와 TypeScript 바인딩(sdk/src/protocol.ts)입니다. 두 생성물은 손으로 편집하지 않으며, 어긋나면 CI가 빌드를 실패시킵니다.

uv run python scripts/gen_protocol.py --check

항목	위치 또는 값
프로토콜 정의	core/snowpea_core/server/protocol.py
버전 상수	PROTOCOL_VERSION
TypeScript 바인딩	sdk/src/protocol.ts
생성 검증 명령	uv run python scripts/gen_protocol.py --check
레퍼런스	프로토콜 레퍼런스

현재 버전은 1.5.0 입니다.

연결 방식 확인하기

데몬은 시작할 때 루프백 전용 포트를 하나 고릅니다. 데몬은 포트와 인증 정보를 $SNOWPEA_HOME/daemon.json 에 {port, pid, token, startedAt, protocolVersion} 로 기록합니다.

클라이언트는 연결 전에 $SNOWPEA_HOME/daemon.json 을 읽습니다.

표면	엔드포인트	용도
WebSocket	ws://127.0.0.1:<port>/ws	JSON-RPC 2.0, 양방향
HTTP GET	/health	살아 있는지 확인
HTTP GET	/protocol.json	이 스키마를 JSON으로
HTTP GET	/version	서버와 프로토콜 버전

데몬은 네트워크에 노출되지 않습니다. 다른 호스트의 코드를 다루는 방식은 포트 개방이 아니라 백엔드 (docker, ssh) 선택입니다.

연결 시작하기

연결 직후 클라이언트는 system.hello 를 호출합니다. 파라미터는 $SNOWPEA_HOME/token 에서 읽은 토큰, 클라이언트 버전, 클라이언트가 빌드된 프로토콜 버전입니다.

{"jsonrpc":"2.0","id":1,"method":"system.hello",
 "params":{"token":"…","clientVersion":"0.1.0","protocolVersion":"1.5.0"}}

1. WebSocket 엔드포인트 ws://127.0.0.1:<port>/ws 에 연결합니다. 연결이 열리면 JSON-RPC 2.0 메시지를 보낼 수 있습니다.
2. system.hello 를 위 JSON-RPC 요청으로 호출합니다. 성공하면 결과에 protocolVersion, serverVersion, capabilities 목록이 포함됩니다.
3. system.hello 전에 다른 메서드를 호출합니다. 요청은 unauthorized 로 실패합니다.
4. 메이저 버전이 맞지 않는 프로토콜 버전으로 system.hello 를 호출합니다. 요청은 protocol_incompatible 로 거절됩니다.

버전이 동결된 뒤 기능 협상은 capabilities 로 이루어집니다.

버전 규칙 확인하기

PROTOCOL_VERSION 은 semver입니다.

변경 유형	규칙
동결 기준	버전 1.0.0, 연속된 세 릴리스 태그 동안 레퍼런스와 생성 스키마에 변화가 없을 것, 그 세 번 모두 SDK 계약 테스트가 통과할 것
추가 변경	마이너 범프와 system.hello 의 capabilities 협상
메이저 변경	모든 클라이언트를 동시에 릴리스해야 하는 변경

읽을 순서 고르기

레퍼런스 는 다음 순서로 읽습니다.

1. Transport와 Handshake 를 확인합니다. 전송 방식과 system.hello 절차를 확인할 수 있습니다.
2. Methods 를 확인합니다. session.*, turn.*, approval.*, agent.*, gateway.*, schedule.*, memory.*, audio.*, settings.*, system.* 메서드의 파라미터와 결과 스키마가 표로 제공됩니다.
3. Events 를 확인합니다. 데몬이 밀어 주는 message.delta, message.done, tool.call, tool.result, diff, subagent.*, team.task.update, mode.changed, usage, error, turn.done 이벤트가 정의됩니다.
4. Versioning 을 확인합니다. 동결 게이트와 버전 변경 규칙을 확인할 수 있습니다.

클라이언트를 구현할 때 배경 설명은 코어 매뉴얼의 프로토콜 페이지를 함께 확인합니다. 생성 레퍼런스는 정확한 스키마를 제공합니다.

실제 데이터 확인하기

헤드리스 CLI는 이 프로토콜을 사용합니다. --json 을 붙이면 이벤트가 JSON Lines로 출력됩니다.

snowpea -c "README.md 를 요약해줘" --json

데몬에서 스키마를 직접 받을 수 있습니다.

curl "http://127.0.0.1:<port>/protocol.json"

<port> 는 $SNOWPEA_HOME/daemon.json 에 있습니다.

---

다음 단계

전체 스키마 보기생성된 레퍼런스를 확인합니다.→작동 방식 이해하기데몬과 클라이언트의 관계를 확인합니다.→