jaw-bridge custom routing

이 저장소는 현재 정상 동작 중인 DeskRPG -> jaw-bridge -> CLI-JAW 커스텀 라우팅 구성을, 나중에 다시 clone -> install -> run으로 바로 복구할 수 있게 정리한 버전입니다.

핵심 원칙은 아래 3가지입니다.

• DeskRPG는 항상 jaw-bridge(http://localhost:8788)만 본다
• jaw-bridge는 config/agent-routing.json으로 agentId -> baseUrl을 명시적으로 해석한다
• route miss 시 silent fallback도 없고, 3462 기본 fallback도 없다

빠른 복구

git clone <YOUR_REPO_URL>
cd deskrpg-jaw-bridge-custom
npm install
cp .env.example .env
cp config/agent-routing.example.json config/agent-routing.json
npm run build
npm run start

실행 후 최소 확인:

bash scripts/check-ports.sh
bash scripts/check-routing.sh
curl -fsS http://localhost:8788/health

Architecture

구조는 단순합니다. 프론트는 개별 backend port를 몰라도 되고, bridge만 안정적으로 유지하면 됩니다.

flowchart LR
  DeskRPG["DeskRPG<br/>localhost:3000"] --> Bridge["jaw-bridge<br/>localhost:8788"]
  Bridge --> GD["game-director<br/>localhost:3462"]
  Bridge --> QA["qa-balance-lead<br/>localhost:3463"]
  Bridge --> UI["game-ui-director<br/>localhost:3464"]
  Bridge --> Content["content-director<br/>localhost:3465"]
  Bridge --> LiveOps["live-ops-planner<br/>localhost:3466"]

Loading

Ports

Service	Port	Notes
DeskRPG frontend	3000	Frontend only
jaw-bridge	8788	Only bridge endpoint DeskRPG should use
game-director	3462	CLI-JAW backend
qa-balance-lead	3463	CLI-JAW backend
game-ui-director	3464	CLI-JAW backend
content-director	3465	CLI-JAW backend
live-ops-planner	3466	CLI-JAW backend

설치

git clone <YOUR_REPO_URL>
cd deskrpg-jaw-bridge-custom
npm install
cp .env.example .env
cp config/agent-routing.example.json config/agent-routing.json

그 다음 config/agent-routing.json을 현재 맥의 실제 포트에 맞게 수정하세요.

실행

개발 실행:

bash scripts/dev-start.sh

빌드 후 실행:

npm run build
npm run start

최소 점검:

bash scripts/check-ports.sh
bash scripts/check-routing.sh
curl -fsS http://localhost:8788/health

Route Config

현재 기준 기본 매핑:

{
  "routes": {
    "game-director": "http://localhost:3462",
    "qa-balance-lead": "http://localhost:3463",
    "game-ui-director": "http://localhost:3464",
    "content-director": "http://localhost:3465",
    "live-ops-planner": "http://localhost:3466"
  },
  "aliases": {}
}

sendChat()의 agentId 해석 우선순위는 고정입니다.

1. payload.agentId
2. session state binding for sessionKey
3. sessionKey-based fallback parsing such as agent:<agentId>:...

해석에 실패하면 bridge는 즉시 명시적 에러를 내고 멈춥니다. 다른 backend로 조용히 우회하지 않습니다.

NPC 5인 예시

• game-director -> http://localhost:3462
• qa-balance-lead -> http://localhost:3463
• game-ui-director -> http://localhost:3464
• content-director -> http://localhost:3465
• live-ops-planner -> http://localhost:3466

핵심 보장

• payload.agentId가 session state보다 우선합니다
• 필수 5개 agent route가 없으면 시작 시 검증에서 실패합니다
• explicit alias만 허용됩니다
• silent fallback, implicit default, 3462 기본 fallback은 허용하지 않습니다

트러블슈팅

• ENABLE_STUB_MODE=true이면 현재 커스텀 라우팅 구성이 아니라 stub 어댑터가 켜집니다. 반드시 false로 유지하세요.
• No CLI-JAW route mapping for agentId=... 오류가 나오면 config/agent-routing.json에 해당 agent route가 없습니다.
• Missing required agent routes 오류가 나오면 필수 5명 route 중 하나 이상이 빠졌습니다.
• DeskRPG가 개별 backend port를 직접 보게 두지 말고 항상 http://localhost:8788만 보게 유지하세요.

자세한 문서:

• docs/CUSTOM_ROUTING.md
• docs/DEPLOY_OR_REINSTALL.md
• docs/CLI_JAW_DISCOVERY.md