iop/HANDOFF.md

Handoff - dev-corp OpenAI-compatible passthrough rollout

작성 시각

2026-07-09

현재 타겟

• 작업: dev-corp gemma4:26b OpenAI-compatible provider model group을 normalized SubmitRun 경로가 아니라 provider tunnel passthrough 경로로 전환 배포
• 코드 기준 ref: ff73306 refactor: reject transformed mode and responses for provider-pool/tunnel routes
• 다음 작업 환경 요구: 172.24.63.178 및 내부 provider nodes에 접근 가능한 환경

이번 세션에서 확인한 사실

• 로컬 main과 origin/main은 ff73306 기준 동기화되어 있었다.
• G06 code-review는 PASS로 종결되어 agent-task/archive/2026/07/openai_passthrough_model_groups/에 archive되어 있다.
• toki@toki-labs.com 접속은 가능했지만, 해당 runtime은 /Users/toki/agent-work/iop-dev-corp이고 git checkout이 아니라 runtime 디렉터리였다.
• toki@toki-labs.com:/Users/toki/agent-work/iop는 source checkout이지만 dirty 상태였으므로 직접 reset하지 않고 별도 clean worktree를 사용했다.
• 새 Edge binary는 ff73306 worktree에서 빌드했고 아래 검증을 통과했다.
  • /opt/homebrew/bin/go test ./apps/edge/internal/openai -count=1
  • /opt/homebrew/bin/go test ./apps/edge/... -count=1
  • 새 binary config check --config /Users/toki/agent-work/iop-dev-corp/build/dev-corp-runtime/edge.yaml
  • 새 binary config refresh --mode dry-run --addr 127.0.0.1:19094
• toki-labs.com runtime config는 provider model group 형태이고 models에는 gemma4:26b가 잡혀 있었다.

Edge-only 배포 시도 결과

• 새 Edge binary를 runtime에 교체하고 Edge process만 재시작했다.
• 새 Edge PID: 68069
• 정상 확인:
  • /healthz OK
  • /v1/models local/public 모두 gemma4:26b
  • metadata.iop_response_mode="transformed" Chat 요청은 400 invalid_request_error
  • provider model group /v1/responses 요청은 400 invalid_request_error
• 실패 확인:
  • omitted-mode /v1/chat/completions 요청은 response body 없이 timeout
  • think:false, max_tokens:8로 줄인 요청도 120초 timeout
• 해석:
  • Edge handler 변경은 적용됐지만, 새 Edge가 보내는 ProviderTunnelRequest에 대해 현재 connected provider Node가 ProviderTunnelFrame을 반환하지 못하는 상태로 보인다.
  • rollback 후 기존 transformed Chat 요청은 200으로 응답했으므로 provider backend 자체나 기존 normalized SubmitRun 경로는 살아 있었다.

Rollback 상태

• 서비스 보호를 위해 새 Edge-only 배포는 rollback했다.
• 백업 binary: /Users/toki/agent-work/iop-dev-corp/build/dev-corp-runtime/backups/iop-edge.20260709132709.bak
• rollback 후 Edge PID: 74660
• rollback 후 확인:
  • /healthz OK
  • /v1/models gemma4:26b OK
  • 기존 transformed Chat 200 OK
  • Control Plane status에서 connected provider nodes는 2개로 관측됨
  • observed providers: corp-dgx-spark-01-vllm, corp-dgx-spark-02-vllm, both in_flight=0, queued=0, health=healthy

현재 원인 판단

Edge-only로는 부족하다. 원인은 현재 연결된 provider Node runtime이 ff73306 Edge의 provider tunnel passthrough 경로와 맞지 않는 ref/binary 상태였기 때문으로 보는 것이 가장 타당하다.

다음 배포는 Edge와 provider Nodes를 같은 source ref로 맞춰야 한다. 단순히 Edge만 다시 교체하면 Chat Completions omitted mode가 다시 timeout 날 가능성이 높다.

다음 세션 첫 진입점

1. 172.24.63.178에 접근 가능한 환경에서 mac-mini runtime checkout과 Node host 접근을 먼저 확인한다.
2. source ref ff73306 기준으로 Edge + provider Node binaries를 같은 ref에서 빌드한다.
3. provider Node별 기존 process/binary/config 경로를 확인하고 Node binary를 교체/재시작한다.
4. Edge binary를 교체/재시작한다.
5. 아래 smoke를 순서대로 확인한다.
   • /healthz
   • /v1/models exposes gemma4:26b
   • Chat metadata.iop_response_mode="transformed" returns 400
   • /v1/responses provider model group returns 400 until raw parity exists
   • omitted Chat Completions returns 200 with no X-IOP-Response-Mode header
   • passthrough+sideband returns provider tunnel response plus sideband
   • Control Plane provider snapshots recover to in_flight=0, queued=0

주의사항

• toki@toki-labs.com에서는 provider node SSH가 No route to host 또는 timeout으로 실패했다. Node 배포까지 진행하려면 172.24.63.178 및 내부 provider hosts에 닿는 작업 환경이 필요하다.
• toki@toki-labs.com:/Users/toki/agent-work/iop-dev-corp는 runtime 디렉터리이고 git checkout이 아니다.
• secret/API key/token 원문은 handoff나 git commit에 남기지 않는다.