가이드

OpenCode를 좌석으로

엔진 어댑터는 시스템 어댑터와 다릅니다. API를 감싸지 않고 에이전트 자체를 감쌉니다. OpenCode는 자기 세션을 유지하고, 어댑터의 일은 작업을 건네고, 원 대화와의 결속을 지키고, 실제로 무슨 일이 있었는지 보고하는 것입니다.

두 가지 전송

라우터에 닿는 방법이 두 가지입니다. 전송만 다르고, 그 아래 작업 처리는 같습니다.

v2-legacy — 기본: 루프백 라우터(8791)의 고정 좌석 주소. consumer가 임차를 스스로 갱신하고 SSE로 재연결합니다.
v3-autoreg — pc-agent가 좌석을 등록하는 사설 라우터(8797). 등록마다 주소가 바뀌고, 좌석 토큰은 메모리에만 있으며, 어댑터는 endpoint·local token 파일 **경로**만 갖습니다.

작업이 거치는 순서

순서가 중요합니다. 멱등 저널 → 세션 인계 → 결과 검증. 프로세스가 exit 0으로 끝났다는 것만으로는 성공이 아닙니다.

작업 ─▶ 저널(job_id 중복?) ─▶ 인계: 모델 고정, 새 세션
                                     │
                                     ▼
                             opencode가 작업 수행
                                     │
                                     ▼
                           검증(증거, diff 상한)
                                     │
              completed ◀────────────┴──────────▶ completed-output-unverified

상황이 바뀔 때

좌석 주소가 바뀌고, 스트림이 끊기고, PC가 잠들 수 있습니다. 어댑터는 각 경우를 무한 재시도 대신 명시적으로 다룹니다.

SSE 치명 오류(401/403/404/410) → 좌석을 release하고 250ms~20s 백오프로 **새 좌석 id**로 재연결
주소 변경(v3 재등록) → 이전 커서를 버리고 새 스트림으로 시작
재시작 시 미완료 작업 → 다시 실행하지 않고 blocked로 보류(모델이 이미 행동했을 수 있음)
중복 전달 → 저널이 같은 job_id의 두 번째 실행을 막음

설정과 한계

설정 파일은 전송, 좌석, 라우터 자격 **참조**, 절대 경로의 OpenCode 명령, 모델, 허용 디렉터리, 타임아웃을 담습니다. 자격은 참조이고 값은 배포에 남습니다.

한계: OpenCode가 설치되어 있고 바이너리 경로가 맞아야 합니다. Windows npm shim은 직접 spawn할 수 없어 실제 실행 파일을 써야 합니다. 모델 비용은 WMOS와 별도입니다. 어댑터는 잠든 기기를 깨우지 않고, 자동 스레드 반환을 주장하지 않습니다.