fix(zcode): attach over the proxy Responses route instead of Chat Completions

devlog/_plan/260912_zcode_protocol_and_catalog/000_plan.md

@@ -0,0 +1,45 @@
+# 000 — ZCode 프로토콜 정렬 + GLM-5.3 모달리티 정정
+
+## 목표
+
+ZCode 연동에서 확인된 세 가지 결함을 1차 근거와 함께 고친다.
+
+1. ocx가 ZCode에 내보내는 프로바이더 블록이 `kind: "openai-compatible"`(Chat Completions)로 붙는다.
+   ocx는 Responses-우선 프록시라 Chat 인바운드는 Responses로 번역된 뒤 다시 Chat으로 역번역된다.
+   ZCode는 `kind: "openai"`로 `{baseURL}/responses`를 직접 호출할 수 있으므로 번역을 0회로 줄인다.
+2. `zai`와 `zhipu-bigmodel-coding` 행이 `glm-5.3-flash`의 입력 모달리티를 음수 선언
+   (`noVisionModels` 제외)으로만 다뤄서, 클라이언트 export 피커에 네이티브 VLM이 text-only로 나간다.
+3. `zai` 행이 Chat Completions 한 갈래에 고정되어 있다. Z.AI 는 같은 키로 Responses 도 서빙하고
+   (`https://api.z.ai/api/v1`) 실사용에서 Chat 경로가 불안정하다. Responses 를 기본으로 돌리고
+   Chat 은 opt-in 으로 남긴다.
+
+## 제약
+
+- 로컬 상태(`~/.opencodex`, `~/.zcode`, `zcode-ocx-sidecar`)는 건드리지 않는다. 사용자 지시.
+- `zai` 행은 제자리에서 Responses 로 전환한다. 별도 행을 추가하지 않는다 — 사용자 결정
+  ("다 통합하고 chat optin 으로, 기존 사용자도 response 전환"). 초안에 있던 로스터 손실 우려는
+  실측으로 반증됐다: glm-5.2 / glm-5.1 / glm-5 / glm-4.6 / glm-5-turbo 전부 Responses 에서 200 이다
+  (030 라이브 표). 030 이 wp4 의 SSOT 다.
+- 프로토콜 전환은 조용히 일어나므로 릴리스 노트에 적는다. Chat 전용 키를 가진 사용자는
+  `modelAdapters` 로 모델마다 `openai-chat` 을 지정해야 한다. 마이그레이션 코드는 넣지 않는다.
+- wp2 와 wp3 는 서로 독립이다. wp4 는 wp3 가 넣는 `ZAI_GLM_5X_INPUT_MODALITIES` 상수에 의존하므로
+  wp3 가 `dev` 에 들어간 뒤에 올린다. 각 수정은 자기 이슈를 닫는 PR 로 가고 베이스는 `dev` 다.
+
+## 작업 단계
+
+| work-phase | 내용 | 이슈 | 문서 |
+|---|---|---|---|
+| wp1 | 조사 + 로드맵 + 이슈 3건 등록 (docs-only) | — | 000-003 |
+| wp2 | ZCode export를 `kind: "openai"`(Responses)로 | [#4295](https://github.com/lidge-jun/opencodex/issues/4295) | 010 |
+| wp3 | `glm-5.3-flash` 양수 모달리티 선언 | [#4296](https://github.com/lidge-jun/opencodex/issues/4296) | 020 |
+| wp4 | `zai` 를 Responses 기본으로 전환 + `chatCompletionsPath` 로 Chat opt-in | [#4297](https://github.com/lidge-jun/opencodex/issues/4297) | 030 |
+
+wp2 는 독립이다. wp4 는 wp3 뒤에 온다(위 제약).
+
+## 검증
+
+- `bun run typecheck`
+- `bun test tests/providers/zcode-client.test.ts tests/config/client-config-export.test.ts`
+- `bun test tests/providers/provider-registry-parity.test.ts`
+- `bun run structure:check` (structure/clients/integrations.md 소유 영역 변경 시)
+- PR-ready 게이트로 `bun run test`

devlog/_plan/260912_zcode_protocol_and_catalog/001_research_zai_model_facts.md

@@ -0,0 +1,61 @@
+# 001 — Z.AI GLM-5.3 계열 1차 근거 (Aside 세션 조사)
+
+수집 경로: `aside exec --permission full-access` (CLI 1.26.902, 세션 `cye9q0tV093bZeFJ`), 2026-09-12.
+아래 인용은 Aside 에이전트가 실제로 연 공식 문서 페이지에서 그대로 가져온 문장이다.
+
+## 입력 모달리티
+
+| 모델 | 입력 모달리티 | 컨텍스트 | 최대 출력 | reasoning 사다리 | 출처 |
+|---|---|---|---|---|---|
+| GLM-5.3 | text only | 1M | 128K | low / high / max (비활성화 불가) | https://docs.z.ai/guides/llm/glm-5.3 |
+| GLM-5.3-Flash | video / image / text / file | 1M | 128K | low / high / max (비활성화 불가) | https://docs.z.ai/guides/vlm/glm-5.3-flash |
+
+verbatim:
+
+> "GLM-5.3 currently supports text-only inputs, with a 1M-token context window and a maximum output length of 128K tokens."
+> — https://docs.z.ai/guides/llm/glm-5.3
+
+> "GLM-5.3 目前仅支持处理文本模态信息，支持 1M 上下文窗口，最大输出 Tokens 为 128K。"
+> — https://docs.bigmodel.cn/cn/guide/models/text/glm-5.3
+
+> "GLM-5.3-Flash is the first native multimodal model in the GLM-5 series"
+> "Input Modality: Video / Image / Text / File"
+> — https://docs.z.ai/guides/vlm/glm-5.3-flash
+
+> "GLM-5.3 is a text-only model, so uncheck Support Images; GLM-5.3-FLASH is a multimodal model, so Support Images can be checked"
+> — https://docs.z.ai/devpack/latest-model
+
+이미지 입력 전달 방식:
+
+> "Image Parameters: Add a content block with type: image_url to messages[].content[], and pass the image URL (recommended) or a Base64 Data URL through image_url.url."
+> — https://docs.z.ai/guides/vlm/glm-5.3-flash
+
+## reasoning effort
+
+> "reasoning_effort: Controls the degree of reasoning within the thought chain... Available values: max (default and recommended, deep inference), high (enhanced inference), low (mild inference, only supported by GLM-5.3 and GLM-5.3-FLASH)"
+> "For GLM-5.3 and GLM-5.3-FLASH, only max, high and low are supported. Any other input will result in an error."
+> — https://docs.z.ai/guides/capabilities/thinking
+
+리포지토리의 `ZAI_GLM_53_REASONING_EFFORTS = ["low", "high", "max"]` 와 일치한다.
+
+## 프로토콜 엔드포인트 (세 갈래)
+
+> "| Protocol | Base URL |
+> | OpenAI Chat Completion Protocol | https://api.z.ai/api/coding/paas/v4 |
+> | OpenAI Response Protocol | https://api.z.ai/api/v1 |
+> | Anthropic Message Protocol | https://api.z.ai/api/anthropic |"
+> — https://docs.z.ai/guides/llm/glm-5.3
+
+> "Claude Code / Goose (Anthropic-compatible): https://api.z.ai/api/anthropic
+> Codex: https://api.z.ai/api/v1
+> Other OpenAI-compatible tools: https://api.z.ai/api/coding/paas/v4"
+> — https://docs.z.ai/devpack/latest-model
+
+상충하는 단서 하나 (해결 필요):
+
+> "If you have previously subscribed to a GLM Coding Plan, including an expired subscription, you can currently access the model API only through the OpenAI Chat Completion-compatible protocol."
+> — https://docs.z.ai/guides/llm/glm-5.3
+
+즉 Coding Plan 구독 이력이 있는 키는 Responses 엔드포인트에서 거절될 수 있다. Responses 전환을
+제안하기 전에 실제 키로 확인이 필요하다.
+

devlog/_plan/260912_zcode_protocol_and_catalog/002_research_zcode_bundle_schema.md

@@ -0,0 +1,87 @@
+# 002 — ZCode 3.11.2 번들 스키마 (app.asar 추출)
+
+조사 대상: `/Applications/ZCode.app/Contents/Resources/app.asar` (307MB, `rg -a`로 추출).
+버전 확인: 실행 로그 `[arms] electron initialized env=prod version=3.11.2`.
+리포지토리 주석은 3.7.7 / 3.8.1 기준이라 3.11.2 재확인이 필요했다.
+
+## kind enum — 정확히 3값
+
+```js
+bt=t.enum(["anthropic","openai","openai-compatible"])
+mh=t.enum(["anthropic-messages","openai-chat-completions","openai-responses"])
+```
+
+`mh`는 내부 `apiFormat` 표현이고 `bt`가 사용자 config의 `kind`다.
+
+## kind → 요청 경로
+
+```js
+function fL(e){switch(e){case"anthropic":return"/v1/messages";case"openai":return"/responses";case"openai-compatible":return"/chat/completions"}}
+s(fL,"getDefaultModelProviderEndpointPathForKind")
+
+function IHe(e,t){let n=t.replace(/\/+$/,"");switch(e){case"anthropic":return`${n}/v1/messages`;case"openai_chat":return`${n}/chat/completions`;case"openai_responses":return`${n}/responses`;case"gemini":return n}}
+s(IHe,"buildConnectivityRequestUrl")
+```
+
+baseURL 정규화는 kind별 접미사를 자동으로 떼어낸다:
+
+```js
+function lp(e,o){let r={anthropic:["/v1/messages","/messages"],openai:["/responses"],"openai-compatible":["/chat/completions"]},...}
+s(lp,"normalizeModelProviderBaseUrlForKind")
+```
+
+따라서 `kind:"openai"` + `baseURL:"http://127.0.0.1:10100/v1"` → `POST http://127.0.0.1:10100/v1/responses`.
+ocx는 그 경로를 실제로 서빙한다(`src/server/index.ts:1994`).
+
+## reasoning 필드
+
+사용자 config 모델 엔트리는 `variants`/`defaultVariant` 형태다:
+
+```js
+XWe=Q.object({enabled:Q.boolean().optional(),variants:Q.array(Q.string().min(1)).optional(),defaultVariant:Q.string().min(1).optional(),aliases:Q.record(Q.string(),Q.string()).optional()}).passthrough()
+```
+
+내부 카탈로그는 `levels`/`defaultLevel`이고 양방향 변환기(`openCodeReasoningToModelReasoning`)가 있다.
+즉 현재 export가 쓰는 `variants`/`defaultVariant`는 kind를 바꿔도 그대로 유효하다.
+
+wire 변환은 kind마다 다르다:
+
+| kind | 요청 필드 |
+|---|---|
+| openai-compatible | `reasoning_effort` |
+| openai | `reasoning: { effort }` |
+| anthropic | `output_config: { effort }` (+ 선택 `thinking`) |
+
+`kind:"openai"`가 보내는 `reasoning.effort`는 ocx `/v1/responses`가 네이티브로 읽는 필드다.
+
+## 모달리티
+
+```js
+Zse=Q.enum(["text","image","video","audio","pdf"])
+modalities:Q.object({input:Q.array(Zse).optional(),output:Q.array(Zse).optional()}).optional()
+```
+
+kind별 제한이 없고, `image`가 있으면 `supportsImages` 케파빌리티로 투영된다:
+
+```js
+w.supportsImages=y.modalities.input.includes("image")
+```
+
+## options / apiKeyRequired
+
+`options`는 `Q.record(Q.string(),Q.unknown())` 자유형이고, `apiKeyRequired:false`면 크리덴셜 요구를
+건너뛴다:
+
+```js
+function yA(e){if(e.apiKeyRequired===!1)return!0;...}s(yA,"hasRuntimeCredential")
+```
+
+## anthropic kind의 추가 요구사항 — 없음
+
+```js
+function rje(e){return e.kind?e.kind:...}s(rje,"resolveOpenCodeProviderDefaultKind")
+```
+
+명시된 `kind`가 최우선이고 `defaultKind`/`apiFormat`/`providerMappings`는 전부 optional 폴백이다.
+세 kind 어느 쪽으로 내보내도 추가 필드는 필요 없다.
+

devlog/_plan/260912_zcode_protocol_and_catalog/003_research_ocx_internals.md

@@ -0,0 +1,75 @@
+# 003 — ocx 내부 경로 (서브에이전트 3레인 조사)
+
+## 인바운드 라우트
+
+| 경로 | 등록 |
+|---|---|
+| `POST /v1/responses` | `src/server/index.ts:1994` |
+| `POST /v1/messages` | `src/server/index.ts:2065` |
+| `POST /v1/messages/count_tokens` | `src/server/index.ts:2047` |
+| `POST /v1/chat/completions` | `src/server/index.ts:2097` |
+
+Anthropic과 Chat 인바운드는 둘 다 본문을 Responses 형태로 번역해 내부적으로 `handleResponses`로
+리플레이한다(`src/server/claude-messages.ts:2-7`, `src/server/chat-completions.ts:2-4`,
+`claude-messages.ts:900`의 `new Request("http://localhost/v1/responses", ...)`).
+Responses 인바운드만 번역이 0회다.
+
+ocx 자신도 ZCode를 Responses 클라이언트로 이미 인지하고 있다:
+
+> "Generic Responses-API clients (AI-SDK apps such as ZCode) omit `store`"
+> — `tests/responses/responses-inbound-store-default.test.ts:2`
+
+## 업스트림 와이어 결정
+
+인바운드가 아니라 라우트된 프로바이더의 `adapter`가 결정한다
+(`src/server/adapter-resolve.ts:13-15`, 하드핀 → 모델별 오버라이드 → 레지스트리 기본 → `provider.adapter`).
+`zai`는 `adapter: "openai-chat"`이므로 어떤 인바운드로 들어와도 업스트림은 Chat Completions다.
+
+## 클라이언트 export 프로토콜 지형
+
+| 클라이언트 | 프로토콜 | baseURL 규칙 |
+|---|---|---|
+| zcode | `kind:"openai-compatible"` → chat | base + `/v1` |
+| mcode | `api:"anthropic-messages"` | base에서 `/v1` 제거 |
+| dsh | `api:"openai-responses"` | base 그대로(`/v1` 포함) |
+| omp / raycast | chat completions | base 그대로 |
+
+즉 Responses로 붙는 클라이언트(dsh)와 Anthropic으로 붙는 클라이언트(mcode) 선례가 둘 다 있다.
+
+## ZCode 소유권 정책
+
+`src/integrations/ownership-policy.ts:66-84`가 refreshable로 인정하는 경로는
+`models.<id>.reasoning`, `models.<id>.limit.output`, (권위 컨텍스트 부재 시) `models.<id>.limit.context` 뿐이다.
+`kind`는 보호 필드다:
+
+> "Provider identity and connection fields (`name`, `kind`, `enabled`, `source`, and every `options` member), model membership, model names, modalities, and authoritative context limits remain protected. Changing any of them stays `conflict / foreign-edit`."
+> — `structure/clients/integrations.md:112-114`
+
+이건 사용자 편집에 대한 규칙이다. ocx가 생성 계약 자체를 바꾸면 desired contribution이 달라지므로
+기존 기록과 대조해 refresh 경로를 타야 한다. wp2에서 마이그레이션 동작을 반드시 확인한다.
+
+## 모달리티 전파 경로
+
+`registry.ts` → `configuredInputModalities`(`src/codex/catalog/provider-fetch.ts:674-677`)
+→ vision sidecar 보정(`provider-fetch.ts:787-798`) → 카탈로그 `input_modalities`
+→ `inputModalitiesForClient`(`src/clients/config-export/model-metadata.ts:61-72`) → 각 클라이언트 export.
+
+`zai` / `zhipu-bigmodel-coding` 행은 `modelInputModalities`를 아예 선언하지 않고
+`noVisionModels`(음수 선언)만 쓴다. 그래서 `glm-5.3-flash`는 sidecar 우회는 면하지만
+양수 선언이 없어 export 피커에서 `["text"]` 플로어로 떨어진다.
+
+`zhipu-bigmodel-responses` 행은 반대로 양수 선언을 갖는다
+(`modelInputModalities: { "glm-5.3": ["text"], "glm-5.3-flash": ["text", "image"], "glm-5-turbo": ["text"] }`).
+
+## 상류 권위 카탈로그 (라이브 확인, 2026-09-12)
+
+`GET https://api.z.ai/api/v1/models` → 200, Codex 형식 카탈로그:
+
+```json
+{"slug": "glm-5.3", "input_modalities": ["text"], "context_window": 1048576, "default_reasoning_level": "max"}
+{"slug": "glm-5.3-flash", "input_modalities": ["text", "image"], "context_window": 1048576, "default_reasoning_level": "max"}
+```
+
+전체 응답은 `evidence/zai-responses-models.json`. `POST https://api.z.ai/api/v1/responses`도 200을 반환했으므로
+"Coding Plan 구독 이력 키는 Chat만 가능"이라는 문서 문장은 이 키에 적용되지 않는다.
+

devlog/_plan/260912_zcode_protocol_and_catalog/010_wp2_zcode_export_responses.md

@@ -0,0 +1,82 @@
+# 010 — wp2 / ISSUE-1: ZCode export를 Responses kind로
+
+## 결함
+
+src/clients/config-export/zcode.ts 가 kind "openai-compatible" 을 내보낸다. ZCode 는 그 kind 에서
+{baseURL}/chat/completions 를 호출하고, ocx 의 Chat 인바운드는 본문을 Responses 로 번역해
+handleResponses 로 리플레이한 뒤 응답을 다시 Chat SSE 로 역번역한다. 왕복 2회 번역이고 그 과정에서
+tool-call delta 와 reasoning 블록이 형태를 바꾼다.
+
+ZCode 는 kind "openai" 로 {baseURL}/responses 를 직접 호출한다(002 문서의 fL / IHe 인용).
+ocx 는 POST /v1/responses 를 네이티브로 서빙한다(src/server/index.ts:1994). 번역 0회.
+
+## 변경
+
+### MODIFY src/clients/config-export/zcode.ts
+
+다섯 지점이다. 타입 리터럴(33행), 빌더 값(94행), 그리고 세 주석 블록(10-11행, 49-54행, 76-78행).
+
+    - kind: "openai-compatible";
+    + kind: "openai";
+
+    -        kind: "openai-compatible",
+    +        kind: "openai",
+
+주석은 3.11.2 번들에서 재추출한 사실로 갱신한다: getDefaultModelProviderEndpointPathForKind 가
+anthropic 을 /v1/messages, openai 를 /responses, openai-compatible 을 /chat/completions 로 보낸다는
+것과, Responses 가 프록시의 네이티브 인바운드라 이전 배선이 턴마다 번역 두 번을 냈다는 것.
+
+baseURL 은 그대로 ctx.baseUrl 에서 /v1 을 떼고 다시 "/v1" 을 붙인 값이다. ZCode 의
+normalizeModelProviderBaseUrlForKind 는 openai kind 에서 /responses 접미사만 떼므로 /v1 은 보존되고
+최종 URL 은 http://127.0.0.1:<port>/v1/responses 가 된다.
+
+reasoning 블록(enabled / variants / defaultVariant)은 kind 와 무관하게 같은 스키마다. openai kind 에서는
+선택된 variant 가 reasoning.effort 로 나가고, 그건 ocx /v1/responses 가 네이티브로 읽는 필드다.
+
+76-78행 주석이 "ZCode forwards the selected variant as reasoning_effort" 라고 말하는데 그건
+openai-compatible kind 의 wire 필드다. openai kind 는 reasoning.effort 로 보낸다(002 문서의
+withOpenAiResponsesThoughtLevel 인용). 동작은 스키마가 같아 그대로지만 주석은 틀리므로 함께 고친다.
+
+### MODIFY tests/providers/zcode-client.test.ts
+
+    -    expect(provider.kind).toBe("openai-compatible");
+    +    expect(provider.kind).toBe("openai");
+
+options 기대값(baseURL http://127.0.0.1:10100/v1)은 바뀌지 않는다. 같은 describe 에 회귀 테스트를
+하나 추가해, ZCode 가 openai kind 에서 조립하는 최종 URL 이 프록시가 실제로 서빙하는 경로와
+일치한다는 것을 고정한다.
+
+    test("the exported kind resolves to the proxy's native Responses route", () => {
+      const document = buildClientConfig("zcode", context()) as ZcodeGeneratedConfig;
+      const provider = document.provider[OPENCODE_PROVIDER_ID]!;
+      // ZCode 3.11.2 getDefaultModelProviderEndpointPathForKind: openai -> "/responses".
+      expect(provider.kind).toBe("openai");
+      expect(provider.options.baseURL + "/responses").toBe("http://127.0.0.1:10100/v1/responses");
+    });
+
+### MODIFY tests/config/client-config-export.test.ts
+
+123행 직렬화 바이트 고정값에서 "kind":"openai-compatible" 을 "kind":"openai" 로 바꾼다.
+나머지 필드 순서와 값은 동일하다.
+
+## 마이그레이션 — 기대 결과는 stale -> rewrite
+
+감사에서 확정됐다. kind 는 refreshable 경로가 아니지만(ownership-policy.ts:66-84), 사용자가 파일을
+손대지 않았다면 recordedBlockIsOwned 가 기존 지문으로 true 를 돌려주고(integrations/state.ts:213)
+desired 지문만 달라져 상태가 stale 이 된다(state.ts:411). JSON 클라이언트인 zcode 는 stale refresh 에서
+프래그먼트를 다시 쓴다. 즉 미수정 설치는 자동으로 따라온다.
+
+--overwrite-conflict 는 사용자가 kind 나 options 를 직접 고쳐 이미 foreign-edit 인 경우에만 필요하다.
+tests/clients/integrations-writer.test.ts:525 의 conflict 케이스는 사용자가 baseURL 을 편집한 상황이지
+ocx 가 kind 를 바꾸는 상황이 아니다.
+
+회귀 테스트는 구성 가능한 쪽으로 넣는다. 이전 빌드가 쓴 기록(옛 지문)을 이 하네스에서 만들 수 없어
+"옛 기록 + 새 계약 -> stale" 은 직접 재현할 수 없다. 그 경로는 코드로만 확인된다
+(state.ts:213 recordedBlockIsOwned, state.ts:405-411 stale 분류, writer.ts:390-391 재작성).
+대신 보완 관계인 보호 쪽을 고정한다: 사용자가 kind 를 손으로 되돌리면 여전히 conflict / foreign-edit 이고
+apply 가 거부된다. baseURL 편집에만 있던 보호를 kind 에도 명시적으로 건다.
+
+## 검증
+
+    bun test tests/providers/zcode-client.test.ts tests/config/client-config-export.test.ts tests/clients/integrations-writer.test.ts
+    bun run typecheck