bolikoto commited on
Commit
67d18ac
·
verified ·
1 Parent(s): fba327f

Deploy minimal Docker Space

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. Dockerfile +18 -0
  2. README.md +10 -6
  3. bun.lock +99 -0
  4. config.example.yaml +185 -0
  5. package.json +26 -0
  6. src/android/control.ts +389 -0
  7. src/async/bridge.ts +524 -0
  8. src/async/client.ts +259 -0
  9. src/async/handler.ts +482 -0
  10. src/async/keepalive.ts +88 -0
  11. src/async/openai-stream-adapter.ts +135 -0
  12. src/async/types.ts +101 -0
  13. src/auth/jwt-age.ts +39 -0
  14. src/auth/manager.ts +39 -0
  15. src/auth/oauth.ts +575 -0
  16. src/auth/resolver.ts +170 -0
  17. src/auth/store.ts +158 -0
  18. src/auth/types.ts +41 -0
  19. src/claim/client.ts +225 -0
  20. src/claim/runtime.ts +147 -0
  21. src/claim/scheduler.ts +186 -0
  22. src/claim/types.ts +66 -0
  23. src/config/edit.ts +38 -0
  24. src/config/loader.ts +393 -0
  25. src/config/template.ts +109 -0
  26. src/config/types.ts +222 -0
  27. src/index.ts +596 -0
  28. src/mcp/client.ts +315 -0
  29. src/mcp/glm-tools.ts +192 -0
  30. src/provider/models.ts +28 -0
  31. src/provider/providers.ts +36 -0
  32. src/provider/reasoning.ts +124 -0
  33. src/provider/types.ts +29 -0
  34. src/proxy/body-transformer.ts +194 -0
  35. src/proxy/captcha-cpu-governor.ts +206 -0
  36. src/proxy/captcha-happy.ts +0 -0
  37. src/proxy/captcha-pool.ts +721 -0
  38. src/proxy/captcha-retry.ts +186 -0
  39. src/proxy/captcha-solver.ts +30 -0
  40. src/proxy/captcha-token.ts +32 -0
  41. src/proxy/captcha.ts +101 -0
  42. src/proxy/client-session.ts +264 -0
  43. src/proxy/client-signing.ts +595 -0
  44. src/proxy/dump.ts +93 -0
  45. src/proxy/endpoint-routing.ts +215 -0
  46. src/proxy/handler.ts +988 -0
  47. src/proxy/identity.ts +195 -0
  48. src/proxy/inflate.ts +53 -0
  49. src/proxy/ordered-transport.ts +297 -0
  50. src/proxy/responses-handler.ts +467 -0
Dockerfile ADDED
@@ -0,0 +1,18 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # syntax=docker/dockerfile:1
2
+
3
+ FROM oven/bun:1-alpine AS deps
4
+ WORKDIR /app
5
+ COPY package.json bun.lock ./
6
+ RUN bun install --frozen-lockfile
7
+
8
+ FROM oven/bun:1-alpine
9
+ WORKDIR /app
10
+ COPY --from=deps /app/node_modules ./node_modules
11
+ COPY package.json tsconfig.json config.example.yaml ./
12
+ COPY src ./src
13
+ RUN mkdir -p /data && chown bun:bun /data
14
+ ENV ZCODE_PROXY_PORT=8080
15
+ ENV ZCODE_PROXY_CONFIG=/data/config.yaml
16
+ EXPOSE 8080
17
+ USER bun
18
+ CMD ["bun", "run", "src/index.ts", "serve"]
README.md CHANGED
@@ -1,10 +1,14 @@
1
  ---
2
- title: Zcode Api
3
- emoji: 🏃
4
- colorFrom: pink
5
- colorTo: green
6
  sdk: docker
7
- pinned: false
8
  ---
9
 
10
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
1
  ---
2
+ title: ZCode Proxy
3
+ emoji: 🔌
4
+ colorFrom: blue
5
+ colorTo: purple
6
  sdk: docker
7
+ app_port: 8080
8
  ---
9
 
10
+ # ZCode Proxy
11
+
12
+ Minimal Docker Space deployment of the upstream `TriDefender/zcode-api`.
13
+
14
+ The upstream credential store must be provisioned before chat requests can work.
bun.lock ADDED
@@ -0,0 +1,99 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "lockfileVersion": 1,
3
+ "configVersion": 1,
4
+ "workspaces": {
5
+ "": {
6
+ "name": "zcode-proxy",
7
+ "dependencies": {
8
+ "happy-dom": "^20.11.6",
9
+ "undici": "^8.10.0",
10
+ "yaml": "^2.5.0",
11
+ },
12
+ "devDependencies": {
13
+ "@types/bun": "latest",
14
+ "esbuild": "^0.28.1",
15
+ },
16
+ },
17
+ },
18
+ "packages": {
19
+ "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.28.1", "", { "os": "aix", "cpu": "ppc64" }, "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ=="],
20
+
21
+ "@esbuild/android-arm": ["@esbuild/android-arm@0.28.1", "", { "os": "android", "cpu": "arm" }, "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ=="],
22
+
23
+ "@esbuild/android-arm64": ["@esbuild/android-arm64@0.28.1", "", { "os": "android", "cpu": "arm64" }, "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg=="],
24
+
25
+ "@esbuild/android-x64": ["@esbuild/android-x64@0.28.1", "", { "os": "android", "cpu": "x64" }, "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng=="],
26
+
27
+ "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.28.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q=="],
28
+
29
+ "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.28.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ=="],
30
+
31
+ "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.28.1", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw=="],
32
+
33
+ "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.28.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ=="],
34
+
35
+ "@esbuild/linux-arm": ["@esbuild/linux-arm@0.28.1", "", { "os": "linux", "cpu": "arm" }, "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ=="],
36
+
37
+ "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.28.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g=="],
38
+
39
+ "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.28.1", "", { "os": "linux", "cpu": "ia32" }, "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w=="],
40
+
41
+ "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg=="],
42
+
43
+ "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ=="],
44
+
45
+ "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.28.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ=="],
46
+
47
+ "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ=="],
48
+
49
+ "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.28.1", "", { "os": "linux", "cpu": "s390x" }, "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag=="],
50
+
51
+ "@esbuild/linux-x64": ["@esbuild/linux-x64@0.28.1", "", { "os": "linux", "cpu": "x64" }, "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA=="],
52
+
53
+ "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw=="],
54
+
55
+ "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.28.1", "", { "os": "none", "cpu": "x64" }, "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg=="],
56
+
57
+ "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.28.1", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q=="],
58
+
59
+ "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.28.1", "", { "os": "openbsd", "cpu": "x64" }, "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw=="],
60
+
61
+ "@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg=="],
62
+
63
+ "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.28.1", "", { "os": "sunos", "cpu": "x64" }, "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ=="],
64
+
65
+ "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.28.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA=="],
66
+
67
+ "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.28.1", "", { "os": "win32", "cpu": "ia32" }, "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg=="],
68
+
69
+ "@esbuild/win32-x64": ["@esbuild/win32-x64@0.28.1", "", { "os": "win32", "cpu": "x64" }, "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A=="],
70
+
71
+ "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
72
+
73
+ "@types/node": ["@types/node@25.9.3", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg=="],
74
+
75
+ "@types/whatwg-mimetype": ["@types/whatwg-mimetype@3.0.2", "", {}, "sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA=="],
76
+
77
+ "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
78
+
79
+ "buffer-image-size": ["buffer-image-size@0.6.4", "", { "dependencies": { "@types/node": "*" } }, "sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ=="],
80
+
81
+ "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
82
+
83
+ "entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
84
+
85
+ "esbuild": ["esbuild@0.28.1", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.28.1", "@esbuild/android-arm": "0.28.1", "@esbuild/android-arm64": "0.28.1", "@esbuild/android-x64": "0.28.1", "@esbuild/darwin-arm64": "0.28.1", "@esbuild/darwin-x64": "0.28.1", "@esbuild/freebsd-arm64": "0.28.1", "@esbuild/freebsd-x64": "0.28.1", "@esbuild/linux-arm": "0.28.1", "@esbuild/linux-arm64": "0.28.1", "@esbuild/linux-ia32": "0.28.1", "@esbuild/linux-loong64": "0.28.1", "@esbuild/linux-mips64el": "0.28.1", "@esbuild/linux-ppc64": "0.28.1", "@esbuild/linux-riscv64": "0.28.1", "@esbuild/linux-s390x": "0.28.1", "@esbuild/linux-x64": "0.28.1", "@esbuild/netbsd-arm64": "0.28.1", "@esbuild/netbsd-x64": "0.28.1", "@esbuild/openbsd-arm64": "0.28.1", "@esbuild/openbsd-x64": "0.28.1", "@esbuild/openharmony-arm64": "0.28.1", "@esbuild/sunos-x64": "0.28.1", "@esbuild/win32-arm64": "0.28.1", "@esbuild/win32-ia32": "0.28.1", "@esbuild/win32-x64": "0.28.1" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw=="],
86
+
87
+ "happy-dom": ["happy-dom@20.11.6", "", { "dependencies": { "@types/node": ">=20.0.0", "@types/whatwg-mimetype": "^3.0.2", "@types/ws": "^8.18.1", "buffer-image-size": "^0.6.4", "entities": "^7.0.1", "whatwg-mimetype": "^3.0.0", "ws": "^8.21.0" } }, "sha512-Hldbg8AdAa5a5oDcZpjqnGitp7JB0hqWmfv/8qr+kft4vzSD8BHsbdRfzYvL/0QcbKcURC/yyoygbeDQarPvYg=="],
88
+
89
+ "undici": ["undici@8.10.0", "", {}, "sha512-HvltHd7avK13QIw/oLe4qoOLyoVSoafqJ2jYOrtMRBkbYT31eiBQ8O0ehRKZiEZCMEyLFQNIADpgCWC5fALvYQ=="],
90
+
91
+ "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
92
+
93
+ "whatwg-mimetype": ["whatwg-mimetype@3.0.0", "", {}, "sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q=="],
94
+
95
+ "ws": ["ws@8.21.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],
96
+
97
+ "yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="],
98
+ }
99
+ }
config.example.yaml ADDED
@@ -0,0 +1,185 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ server:
2
+ port: 8080
3
+ host: "0.0.0.0"
4
+
5
+ auth:
6
+ # Key that clients must provide to use the proxy.
7
+ # Set to null/omit to disable client auth.
8
+ proxyApiKey: "your-proxy-secret"
9
+
10
+ # Upstream credentials come from the OAuth login flow — run this first:
11
+ # bun run src/index.ts auth login <zai|bigmodel>
12
+ # Parsed but currently not honored — the credential store path is fixed at
13
+ # ~/.zcode-proxy/credentials.json:
14
+ # oauthCredentialsPath: "~/.zcode-proxy/credentials.json"
15
+
16
+ # Which upstream provider to use: "zai" or "bigmodel"
17
+ provider: zai
18
+
19
+ # Which plan tier to use:
20
+ # "coding-plan" (default) — direct upstream endpoints, permanent API key
21
+ # "start-plan" — routes through zcode.z.ai with JWT auth (requires `auth login`)
22
+ plan: coding-plan
23
+
24
+ providers:
25
+ zai:
26
+ anthropicBase: "https://api.z.ai/api/anthropic"
27
+ openaiBase: "https://api.z.ai/api/coding/paas/v4"
28
+ bigmodel:
29
+ anthropicBase: "https://open.bigmodel.cn/api/anthropic"
30
+ openaiBase: "https://open.bigmodel.cn/api/coding/paas/v4"
31
+
32
+ defaultModel: glm-4.6
33
+
34
+ models:
35
+ - glm-4.5-air
36
+ - glm-4.6
37
+ - glm-4.6v
38
+ - glm-4.7
39
+ - glm-5
40
+ - glm-5-turbo
41
+ - glm-5v-turbo
42
+ - glm-5.1
43
+ - glm-5.2
44
+ - glm-5.3
45
+ - glm-5.3-flash
46
+
47
+ # Configurable identity headers injected on every upstream request to mimic the
48
+ # ZCode desktop client (User-Agent, X-ZCode-App-Version, X-Title,
49
+ # X-ZCode-Agent, HTTP-Referer). Runtime platform headers (X-Platform,
50
+ # X-Os-Category, X-Os-Version) are detected dynamically and are not configured
51
+ # here. All fields below are optional; env vars override YAML, which overrides
52
+ # defaults.
53
+ identity:
54
+ # Mirrors process.env.ZCODE_APP_VERSION in the ZCode bundle.
55
+ # Must be printable ASCII; non-conforming values fall back to the default.
56
+ # Default: "3.11.2" (current ZCode release). Override to match your real client.
57
+ appVersion: "3.11.2"
58
+ # X-Title suffix → "Z Code@{sourceTitle}". Default "cli".
59
+ sourceTitle: "cli"
60
+ # HTTP-Referer URL. Default "https://zcode.z.ai".
61
+ refererOrigin: "https://zcode.z.ai"
62
+ # Device identity (X-Device-Mid) — random UUIDv4, generated ONCE and reused
63
+ # forever (mirrors ZCode's telemetry deviceMid; no hardware values involved).
64
+ # Auto-generated into this file at first `auth login` or config creation.
65
+ # Leave empty on Android — the app injects ZCODE_IDENTITY_DEVICE_MID instead.
66
+ deviceMid: ""
67
+
68
+ # Local client-session inference for cache-affinity experiments.
69
+ # "observe" (default) logs inferred sessions in debug mode but does not change
70
+ # upstream x-session-id. "enforce" reuses a stable x-session-id for inferred
71
+ # coding-plan sessions. "off" disables inference entirely.
72
+ clientIdentity:
73
+ mode: observe
74
+ ttlSeconds: 900
75
+ maxSessions: 1024
76
+
77
+ # Responses API (/v1/responses) — Codex CLI / OpenAI Agents SDK endpoint.
78
+ # Translates Responses requests through Chat Completions to the Anthropic-format
79
+ # upstream (both plans post Anthropic upstream).
80
+ # State (previous_response_id) is held in-memory (cleared on restart, 24h TTL).
81
+ responses:
82
+ enabled: true
83
+ store:
84
+ maxEntries: 1000
85
+ ttlMs: 86400000
86
+
87
+ # GLM MCP hosted-tool integration — NOT currently wired into production.
88
+ # These keys are parsed but have no effect: hosted tools (`mcp`,
89
+ # `web_search_preview`, ...) are silently stripped by the Responses
90
+ # translator, and the MCP client subsystem (src/mcp) is retained for a
91
+ # future function-injection design. Endpoints are derived from `provider`:
92
+ # zai → https://api.z.ai/api/mcp/{tool}/mcp
93
+ # bigmodel → https://open.bigmodel.cn/api/mcp/{tool}/mcp
94
+ # Auth reuses the logged-in upstream credential — no extra key needed.
95
+ mcp:
96
+ enabled: true
97
+ # (planned) Intercept `web_search`/`web_search_preview` hosted tools via
98
+ # GLM's `web_search_prime` MCP.
99
+ webSearch: true
100
+ # (planned) Inject `webReader` as a function tool the model can call directly.
101
+ webReader: false
102
+ # (planned) Inject the three `zread` tools (search_doc/get_repo_structure/read_file).
103
+ zread: false
104
+
105
+ # Async (off-peak / "idle plan") bridge.
106
+ # When enabled, exposes POST /async/v1/messages and /async/v1/chat/completions
107
+ # that route through ZCode's off-peak ticket-queue backend — free compute when
108
+ # the GLM cluster has idle capacity. The proxy holds the connection open with
109
+ # SSE keepalives during queue wait, forwards the LLM stream once a ticket is
110
+ # ready, and auto-retries on ticket-expired (up to maxRetries).
111
+ #
112
+ # IMPORTANT: off-peak needs the JWT captured by `auth login`. A credential
113
+ # without a JWT makes the route return 400 `async_credentials_unavailable`.
114
+ # Off-peak is a coding-plan feature: when `plan: start-plan`, the /async/*
115
+ # routes return 400 `async_plan_unsupported` even when enabled: true.
116
+ #
117
+ # Env overrides: ZCODE_ASYNC_ENABLED, ZCODE_ASYNC_ORIGIN,
118
+ # ZCODE_ASYNC_MAX_RETRIES, ZCODE_ASYNC_MAX_WAIT_MS.
119
+ async:
120
+ enabled: false
121
+ origin: "https://zcode.z.ai"
122
+ pollIntervalMs: 5000
123
+ keepAliveIntervalMs: 3000
124
+ # Maximum total wait for ticket to become ready, in ms. 0 = unlimited.
125
+ maxWaitMs: 0
126
+ maxRetries: 3
127
+ settleTimeoutMs: 8000
128
+ controlTimeoutMs: 15000
129
+ # Optional model override; empty uses the request's `model`.
130
+ defaultModel: ""
131
+
132
+ # Manual claim ("weekend plan") — mirrors the ZCode 3.10 desktop client's
133
+ # manualClaimPlan feature. When enabled, the proxy periodically lists claimable
134
+ # trial plans ({origin}/api/v1/zcode-plan/billing/preview) and auto-claims the
135
+ # highest-priority one ({origin}/api/v1/zcode-plan/billing/claim) using the
136
+ # OAuth JWT + an Aliyun captcha token (same solver as start-plan). Weekend
137
+ # campaigns are quota-limited first-come-first-served; claimed plans activate
138
+ # at the campaign's `starts_at` and land as Start-Plan quota.
139
+ #
140
+ # IMPORTANT: requires a logged-in credential (claim uses the JWT from
141
+ # `auth login`), and identity.appVersion must be >= the campaign's minimum
142
+ # client version (default 3.11.2) or the server rejects with `ineligible`.
143
+ #
144
+ # Env overrides: ZCODE_CLAIM_ENABLED, ZCODE_CLAIM_AUTO, ZCODE_CLAIM_ORIGIN,
145
+ # ZCODE_CLAIM_POLL_INTERVAL_MS.
146
+ claim:
147
+ # On by default: the scheduler polls the preview endpoint every 5 min and
148
+ # idles until a campaign goes live (404 preview = nothing to claim).
149
+ # `false` = CLI-only (`zcode-proxy claim [list|now]` still works).
150
+ enabled: true
151
+ # Auto-claim in the background while serving. `false` = CLI-only
152
+ # (`zcode-proxy claim` still works when `enabled: true`).
153
+ auto: true
154
+ origin: "https://zcode.z.ai"
155
+ # Preview poll cadence (5 min default).
156
+ pollIntervalMs: 300000
157
+ # Backoff after failed attempts (10 min default); quota_exhausted /
158
+ # already_claimed back off to the server-provided next window instead.
159
+ cooldownMs: 600000
160
+ # Optional: claim a specific plan_id. Empty = highest-priority preview.
161
+ planId: ""
162
+
163
+ # Server-controlled upstream URL remapping (mirrors the ZCode client's
164
+ # ProviderEndpointRoutingService). The proxy periodically fetches
165
+ # {origin}/api/v1/agent/configs and rewrites matching upstream URLs per the
166
+ # returned proxyEndpoint.mapping table (currently the coding-plan Anthropic
167
+ # endpoints -> zcode.z.ai ultra endpoints). Fail-open: any fetch/parse error
168
+ # keeps the original URLs. Env override: ZCODE_ENDPOINT_ROUTING=false.
169
+ endpointRouting:
170
+ enabled: true
171
+ origin: "https://zcode.z.ai"
172
+
173
+ # Client request signing V4 (mirrors the ZCode 3.9.1 ClientRequestSigningV4Signer).
174
+ # When enabled, the proxy probes {origin}/api/v1/agent/configs (cached 1h) and,
175
+ # only if the server sets data.codingPlanSignature.enable=true, signs coding-plan
176
+ # requests: handshake against {provider}/api/paas/c1f3a7e2/v2/client, Ed25519
177
+ # signature + proof-of-work headers on every request, fail-open retry ladder
178
+ # (two 401 VERIFY rejections -> permanent unsigned bypass). Start-plan and
179
+ # off-peak paths are never signed. Env override: ZCODE_CLIENT_SIGNING=false.
180
+ clientSigning:
181
+ enabled: true
182
+ origin: "https://zcode.z.ai"
183
+
184
+ logging:
185
+ level: info
package.json ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "name": "zcode-proxy",
3
+ "version": "4.6.3",
4
+ "type": "module",
5
+ "scripts": {
6
+ "dev": "bun run src/index.ts",
7
+ "start": "bun run src/index.ts",
8
+ "test": "bun test",
9
+ "build": "bun build --compile --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy.exe",
10
+ "build:linux-x64": "bun build --compile --target bun-linux-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-x64",
11
+ "build:linux-arm64": "bun build --compile --target bun-linux-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-arm64",
12
+ "build:darwin-x64": "bun build --compile --target bun-darwin-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-x64",
13
+ "build:darwin-arm64": "bun build --compile --target bun-darwin-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-arm64",
14
+ "build:android-bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/android/server.cjs --define:process.env.NODE_ENV=\\\"production\\\"",
15
+ "build:android-apk": "bash scripts/build-android-apk.sh"
16
+ },
17
+ "dependencies": {
18
+ "happy-dom": "^20.11.6",
19
+ "undici": "^8.10.0",
20
+ "yaml": "^2.5.0"
21
+ },
22
+ "devDependencies": {
23
+ "@types/bun": "latest",
24
+ "esbuild": "^0.28.1"
25
+ }
26
+ }
src/android/control.ts ADDED
@@ -0,0 +1,389 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Localhost-only HTTP control listener for the Android app's Kotlin shell.
3
+ *
4
+ * The Kotlin foreground service starts the Node.js proxy server and a small
5
+ * control listener on a separate port (passed via env `ZCODE_CONTROL_PORT`).
6
+ * The proxy listener serves `/v1/*`, `/webui`, `/health`; the control listener
7
+ * serves only `POST /control` and is bound to `127.0.0.1` so other devices on
8
+ * the LAN cannot reach it. Two layers enforce loopback-only access:
9
+ *
10
+ * 1. `server.listen(port, "127.0.0.1", ...)` — never binds to `0.0.0.0`.
11
+ * 2. Per-request `req.socket.remoteAddress` check — defends against a future
12
+ * bind regression where the listener accidentally widens.
13
+ *
14
+ * The listener exposes a JSON command protocol so Kotlin can drive OAuth
15
+ * (via embedded WebView), start/stop the proxy server, update runtime config
16
+ * (provider/plan), poll logs, and shut down the Node process.
17
+ */
18
+ import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
19
+ import type { ProviderId } from "../provider/types.js";
20
+ import type { Credential } from "../auth/types.js";
21
+ import {
22
+ ZaiOAuthClient,
23
+ BigmodelOAuthClient,
24
+ AuthCodeOAuthClient,
25
+ type OAuthFlowClient,
26
+ } from "../auth/oauth.js";
27
+ import { KeyResolver } from "../auth/resolver.js";
28
+ import { saveCredential, clearCredential, loadCredential } from "../auth/store.js";
29
+
30
+ /** Supported plan tiers. Mirrors `ProxyConfig.plan`. */
31
+ export type PlanTier = "coding-plan" | "start-plan";
32
+
33
+ /** The control protocol: request shape for `POST /control`. */
34
+ export type ControlCommand =
35
+ | { cmd: "status" }
36
+ | { cmd: "startOAuth"; provider: ProviderId }
37
+ | { cmd: "deliverOAuthCode"; provider: ProviderId; code: string; state: string }
38
+ | { cmd: "logout" }
39
+ | { cmd: "setConfig"; provider?: ProviderId; plan?: PlanTier }
40
+ | { cmd: "startProxy" }
41
+ | { cmd: "stopProxy" }
42
+ | { cmd: "getLogs"; since?: number }
43
+ | { cmd: "shutdown" };
44
+
45
+ /** Successful response envelope. */
46
+ export type ControlOk =
47
+ | { ok: true; state: "running"; provider: ProviderId; plan: PlanTier; proxyPort: number; loggedIn: boolean }
48
+ | { ok: true; event: "oauthUrl"; authorizeUrl: string; callbackPort: number }
49
+ | { ok: true; event: "loginOk"; provider: ProviderId }
50
+ | { ok: true; event: "loggedOut" }
51
+ | { ok: true; event: "configUpdated"; provider: ProviderId; plan: PlanTier }
52
+ | { ok: true; event: "proxyStarted"; port: number }
53
+ | { ok: true; event: "proxyStopped" }
54
+ | { ok: true; event: "logs"; nextSince: number; lines: string[] }
55
+ | { ok: true; event: "shuttingDown" };
56
+
57
+ /** Failure response envelope. */
58
+ export interface ControlError {
59
+ ok: false;
60
+ error: string;
61
+ }
62
+
63
+ export type ControlResponse = ControlOk | ControlError;
64
+
65
+ /** Result type returned by lifecycle hooks (start/stop proxy). */
66
+ export type LifecycleResult =
67
+ | { ok: true; port: number }
68
+ | { ok: false; error: string };
69
+
70
+ /** Result type returned by `setConfig` hook. */
71
+ export type ConfigUpdateResult =
72
+ | { ok: true; provider: ProviderId; plan: PlanTier }
73
+ | { ok: false; error: string };
74
+
75
+ /** Internal mutable state shared with the proxy entry. */
76
+ export interface ControlState {
77
+ provider: ProviderId;
78
+ plan: PlanTier;
79
+ /** Currently-bound proxy server port. 0 when proxy is stopped. */
80
+ proxyPort: number;
81
+ /** Active OAuth client while a flow is in flight; nulled on completion. */
82
+ activeOauth?: {
83
+ client: OAuthFlowClient;
84
+ callbackUrl: string;
85
+ state: string;
86
+ };
87
+ }
88
+
89
+ interface StartControlOpts {
90
+ port: number;
91
+ state: ControlState;
92
+ /** Start the proxy server. Returns the bound port on success. */
93
+ onStartProxy?: () => Promise<LifecycleResult>;
94
+ /** Stop the proxy server. */
95
+ onStopProxy?: () => Promise<{ ok: true } | { ok: false; error: string }>;
96
+ /** Update runtime config (provider and/or plan). */
97
+ onSetConfig?: (changes: { provider?: ProviderId; plan?: PlanTier }) => Promise<ConfigUpdateResult>;
98
+ /** Hook for graceful shutdown (called by the `shutdown` command). */
99
+ onShutdown?: () => Promise<void> | void;
100
+ /** Log buffer polled by `getLogs`. If omitted, an internal one is used. */
101
+ logBuffer?: LogBuffer;
102
+ }
103
+
104
+ /** Bounded ring buffer for runtime log lines with monotonic sequence numbers. */
105
+ export class LogBuffer {
106
+ private readonly lines: string[] = [];
107
+ private readonly capacity: number;
108
+ private nextSeq = 0;
109
+
110
+ constructor(capacity = 500) {
111
+ this.capacity = capacity;
112
+ }
113
+
114
+ push(line: string): void {
115
+ this.lines.push(line);
116
+ this.nextSeq++;
117
+ if (this.lines.length > this.capacity) {
118
+ this.lines.splice(0, this.lines.length - this.capacity);
119
+ }
120
+ }
121
+
122
+ /**
123
+ * Returns lines whose logical sequence number is `>= since`, plus the
124
+ * next-since cursor (use as the next `since` value for incremental polling).
125
+ */
126
+ since(since: number): { nextSince: number; lines: string[] } {
127
+ const baseSeq = Math.max(0, this.nextSeq - this.lines.length);
128
+ const wantStart = Math.max(since, baseSeq);
129
+ const offset = wantStart - baseSeq;
130
+ if (offset >= this.lines.length) {
131
+ return { nextSince: this.nextSeq, lines: [] };
132
+ }
133
+ return { nextSince: this.nextSeq, lines: this.lines.slice(offset) };
134
+ }
135
+
136
+ /** Returns all lines currently in the buffer. */
137
+ snapshot(): readonly string[] {
138
+ return this.lines;
139
+ }
140
+
141
+ /** Monotonic cursor; safe to expose externally. */
142
+ get cursor(): number {
143
+ return this.nextSeq;
144
+ }
145
+ }
146
+
147
+ /** Start the control listener bound to 127.0.0.1. Resolves once listening. */
148
+ export function startControlListener(opts: StartControlOpts): Promise<{ close(): Promise<void> }> {
149
+ const logBuffer = opts.logBuffer ?? new LogBuffer();
150
+ const server: Server = createServer(async (req, res) => {
151
+ try {
152
+ const result = await handleControlRequest(req, opts.state, {
153
+ onStartProxy: opts.onStartProxy,
154
+ onStopProxy: opts.onStopProxy,
155
+ onSetConfig: opts.onSetConfig,
156
+ onShutdown: opts.onShutdown,
157
+ logBuffer,
158
+ });
159
+ writeJson(res, result.status, result.body);
160
+ } catch (err) {
161
+ writeJson(res, 500, { ok: false, error: `internal_error: ${(err as Error).message}` });
162
+ }
163
+ });
164
+
165
+ return new Promise((resolve, reject) => {
166
+ server.on("error", reject);
167
+ server.listen(opts.port, "127.0.0.1", () => resolve({
168
+ close: () => new Promise<void>((r) => server.close(() => r())),
169
+ }));
170
+ });
171
+ }
172
+
173
+ export interface ControlHandlerResult {
174
+ status: number;
175
+ body: ControlResponse;
176
+ }
177
+
178
+ /** Context passed to `handleControlRequest` for hook wiring + log access. */
179
+ export interface HandlerContext {
180
+ onStartProxy?: () => Promise<LifecycleResult>;
181
+ onStopProxy?: () => Promise<{ ok: true } | { ok: false; error: string }>;
182
+ onSetConfig?: (changes: { provider?: ProviderId; plan?: PlanTier }) => Promise<ConfigUpdateResult>;
183
+ onShutdown?: () => Promise<void> | void;
184
+ logBuffer: LogBuffer;
185
+ }
186
+
187
+ export function handleControlRequestForTest(
188
+ req: IncomingMessage,
189
+ state: ControlState,
190
+ onShutdown?: () => Promise<void> | void,
191
+ ): Promise<ControlHandlerResult> {
192
+ // Backwards-compatible shape: only `onShutdown` is wired.
193
+ const ctx: HandlerContext = { onShutdown, logBuffer: new LogBuffer() };
194
+ return handleControlRequest(req, state, ctx);
195
+ }
196
+
197
+ /**
198
+ * Test entry that allows wiring all lifecycle hooks. Prefer this in new tests
199
+ * for startProxy/stopProxy/setConfig/getLogs coverage.
200
+ */
201
+ export function handleControlRequestWithHooksForTest(
202
+ req: IncomingMessage,
203
+ state: ControlState,
204
+ ctx: HandlerContext,
205
+ ): Promise<ControlHandlerResult> {
206
+ return handleControlRequest(req, state, ctx);
207
+ }
208
+
209
+ async function handleControlRequest(
210
+ req: IncomingMessage,
211
+ state: ControlState,
212
+ ctx: HandlerContext,
213
+ ): Promise<ControlHandlerResult> {
214
+ if (!isLoopback(req.socket.remoteAddress)) {
215
+ return { status: 403, body: { ok: false, error: "forbidden: non-loopback remote address" } };
216
+ }
217
+
218
+ const parsed = new URL(req.url ?? "/", "http://127.0.0.1");
219
+ if (req.method !== "POST" || parsed.pathname !== "/control") {
220
+ return { status: 404, body: { ok: false, error: `not_found: ${req.method} ${parsed.pathname}` } };
221
+ }
222
+
223
+ const body = await readBody(req);
224
+ let cmd: ControlCommand;
225
+ try {
226
+ cmd = JSON.parse(body) as ControlCommand;
227
+ } catch {
228
+ return { status: 400, body: { ok: false, error: "invalid_json" } };
229
+ }
230
+
231
+ const result = await dispatch(cmd, state, ctx);
232
+ return { status: 200, body: result };
233
+ }
234
+
235
+ async function dispatch(
236
+ cmd: ControlCommand,
237
+ state: ControlState,
238
+ ctx: HandlerContext,
239
+ ): Promise<ControlResponse> {
240
+ switch (cmd.cmd) {
241
+ case "status": {
242
+ const cred = await loadCredential().catch(() => null);
243
+ return {
244
+ ok: true,
245
+ state: "running",
246
+ provider: state.provider,
247
+ plan: state.plan,
248
+ proxyPort: state.proxyPort,
249
+ loggedIn: cred != null,
250
+ };
251
+ }
252
+
253
+ case "startOAuth": {
254
+ // Tear down any previous in-flight flow so its callback port is released.
255
+ if (state.activeOauth) {
256
+ await state.activeOauth.client.close().catch(() => {});
257
+ state.activeOauth = undefined;
258
+ }
259
+ // Z.AI uses the server-mediated cli login (no local callback); bigmodel
260
+ // keeps the classic localhost auth-code callback server.
261
+ const client: OAuthFlowClient =
262
+ cmd.provider === "bigmodel" ? new BigmodelOAuthClient() : new ZaiOAuthClient();
263
+ const started = await client.start();
264
+ const callbackPort = started.callbackUrl
265
+ ? Number(new URL(started.callbackUrl).port) || 80
266
+ : 0;
267
+ state.activeOauth = {
268
+ client,
269
+ callbackUrl: started.callbackUrl,
270
+ state: started.state,
271
+ };
272
+ client.complete(started).then(async (tokens) => {
273
+ const resolver = new KeyResolver();
274
+ const cred: Credential = await resolver.resolveCodingPlanCredential(tokens.accessToken, cmd.provider, tokens.userId);
275
+ if (tokens.jwt) cred.jwt = tokens.jwt;
276
+ await saveCredential(cred);
277
+ console.log(`OAuth completed for ${cmd.provider}`);
278
+ }).catch((err: unknown) => {
279
+ // Timeouts / rejections are expected when the user abandons the
280
+ // browser; nothing to surface beyond the log buffer.
281
+ console.error(`OAuth flow ended without success: ${(err as Error)?.message ?? String(err)}`);
282
+ }).finally(() => {
283
+ // MUST run on rejection too — otherwise the callback port leaks until
284
+ // process death (Android: only a device reboot clears it).
285
+ void client.close().catch(() => {});
286
+ if (state.activeOauth?.state === started.state) state.activeOauth = undefined;
287
+ });
288
+ return {
289
+ ok: true,
290
+ event: "oauthUrl",
291
+ authorizeUrl: started.authorizeUrl,
292
+ callbackPort,
293
+ };
294
+ }
295
+
296
+ case "deliverOAuthCode": {
297
+ const active = state.activeOauth;
298
+ // Code delivery only applies to callback-based (auth-code) flows — the
299
+ // Z.AI cli login completes via server polling and has no code to deliver.
300
+ if (!(active?.client instanceof AuthCodeOAuthClient) || active.state !== cmd.state) {
301
+ return { ok: false, error: "no_matching_oauth_flow" };
302
+ }
303
+ try {
304
+ const { accessToken, userId, jwt } = await active.client.exchangeCode(
305
+ cmd.code,
306
+ active.callbackUrl,
307
+ cmd.state,
308
+ );
309
+ const resolver = new KeyResolver();
310
+ const cred: Credential = await resolver.resolveCodingPlanCredential(accessToken, cmd.provider, userId);
311
+ if (jwt) cred.jwt = jwt;
312
+ await saveCredential(cred);
313
+ state.activeOauth = undefined;
314
+ await active.client.close().catch(() => {});
315
+ return { ok: true, event: "loginOk", provider: cmd.provider };
316
+ } catch (err) {
317
+ state.activeOauth = undefined;
318
+ await active.client.close().catch(() => {});
319
+ return { ok: false, error: `oauth_exchange_failed: ${(err as Error).message}` };
320
+ }
321
+ }
322
+
323
+ case "logout": {
324
+ await clearCredential();
325
+ return { ok: true, event: "loggedOut" };
326
+ }
327
+
328
+ case "setConfig": {
329
+ if (!ctx.onSetConfig) return { ok: false, error: "config_update_unavailable" };
330
+ const result = await ctx.onSetConfig({ provider: cmd.provider, plan: cmd.plan });
331
+ if (!result.ok) return result;
332
+ state.provider = result.provider;
333
+ state.plan = result.plan;
334
+ return { ok: true, event: "configUpdated", provider: result.provider, plan: result.plan };
335
+ }
336
+
337
+ case "startProxy": {
338
+ if (!ctx.onStartProxy) return { ok: false, error: "proxy_lifecycle_unavailable" };
339
+ const result = await ctx.onStartProxy();
340
+ if (!result.ok) return result;
341
+ state.proxyPort = result.port;
342
+ return { ok: true, event: "proxyStarted", port: result.port };
343
+ }
344
+
345
+ case "stopProxy": {
346
+ if (!ctx.onStopProxy) return { ok: false, error: "proxy_lifecycle_unavailable" };
347
+ const result = await ctx.onStopProxy();
348
+ if (!result.ok) return result;
349
+ state.proxyPort = 0;
350
+ return { ok: true, event: "proxyStopped" };
351
+ }
352
+
353
+ case "getLogs": {
354
+ const since = typeof cmd.since === "number" ? cmd.since : 0;
355
+ const { nextSince, lines } = ctx.logBuffer.since(since);
356
+ return { ok: true, event: "logs", nextSince, lines: [...lines] };
357
+ }
358
+
359
+ case "shutdown": {
360
+ if (ctx.onShutdown) await ctx.onShutdown();
361
+ return { ok: true, event: "shuttingDown" };
362
+ }
363
+
364
+ default:
365
+ return { ok: false, error: `unknown_cmd: ${(cmd as { cmd: string }).cmd}` };
366
+ }
367
+ }
368
+
369
+ function isLoopback(addr: string | undefined): boolean {
370
+ return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
371
+ }
372
+
373
+ function writeJson(res: ServerResponse, status: number, body: unknown): void {
374
+ const json = JSON.stringify(body);
375
+ res.writeHead(status, {
376
+ "content-type": "application/json; charset=utf-8",
377
+ "content-length": Buffer.byteLength(json),
378
+ });
379
+ res.end(json);
380
+ }
381
+
382
+ function readBody(req: IncomingMessage): Promise<string> {
383
+ return new Promise((resolve, reject) => {
384
+ const chunks: Buffer[] = [];
385
+ req.on("data", (c: Buffer) => chunks.push(c));
386
+ req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
387
+ req.on("error", reject);
388
+ });
389
+ }
src/async/bridge.ts ADDED
@@ -0,0 +1,524 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Async bridge: core state machine turning sync client stream expectation
3
+ * into off-peak async reality. See `.omo/plans/async-off-peak-bridge.md` §3.
4
+ *
5
+ * State machine:
6
+ * WAIT (queued) → poll every pollIntervalMs (signal-aware); emit keepalives
7
+ * READY (ready/active) → forward LLM call upstream with X-Off-Peak-Ticket-ID
8
+ * EXPIRED (ticket revoked) → settleOnce(old); if attempt < maxRetries take new ticket → WAIT; else terminal error
9
+ * DONE (stream completed) → settleOnce(current); close stream
10
+ * ABORT (client disconnect) → settleOnce(current); release resources
11
+ *
12
+ * Anti-patterns enforced (see plan §9):
13
+ * #1 — pure `: keepalive\n\n` comments during wait; no custom data events
14
+ * #2 — every takeTicket matched by exactly one settleOnce (idempotent)
15
+ * #3 — retry resends original prompt (no NOe placeholder)
16
+ * #5 — settle is fire-and-forget, never blocks stream closure
17
+ *
18
+ * Output: homogeneous byte stream (keepalives + upstream Anthropic bytes + terminal error events).
19
+ */
20
+ import type { OffPeakClient } from "./client.js";
21
+ import type { OffPeakCredentials, TakeTicketResult, TicketState } from "./types.js";
22
+ import { isTicketExpired, isTicketReady } from "./types.js";
23
+ import { keepaliveFrame } from "./keepalive.js";
24
+ import { buildIdentityHeaders } from "../proxy/identity.js";
25
+ import type { ProxyIdentity } from "../config/types.js";
26
+
27
+ const EXPIRED_MARKER = "off-peak-ticket-expired";
28
+
29
+ export interface BridgeOptions {
30
+ client: OffPeakClient;
31
+ credentials: OffPeakCredentials;
32
+ origin: string;
33
+ identity: ProxyIdentity;
34
+ llmRequestBody: string;
35
+ initialTicket: TakeTicketResult;
36
+ taskId: string;
37
+ pollIntervalMs: number;
38
+ keepAliveIntervalMs: number;
39
+ maxRetries: number;
40
+ /** Total wait cap across ALL retries (not per-ticket). 0 = unlimited. */
41
+ maxWaitMs: number;
42
+ clientSignal?: AbortSignal;
43
+ fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
44
+ onTransition?: (info: BridgeTransition) => void;
45
+ }
46
+
47
+ export interface BridgeTransition {
48
+ phase: "wait" | "ready" | "expired" | "done" | "abort" | "error";
49
+ attempt: number;
50
+ ticketId: string;
51
+ state?: TicketState;
52
+ message?: string;
53
+ }
54
+
55
+ export interface BridgeOutcome {
56
+ attempts: number;
57
+ finalTicketId: string;
58
+ terminalPhase: BridgeTransition["phase"];
59
+ }
60
+
61
+ export function runAsyncBridge(opts: BridgeOptions): { stream: ReadableStream<Uint8Array>; outcome: Promise<BridgeOutcome> } {
62
+ const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
63
+ const encoder = new TextEncoder();
64
+ let outcomeResolve!: (o: BridgeOutcome) => void;
65
+ const outcome = new Promise<BridgeOutcome>((r) => {
66
+ outcomeResolve = r;
67
+ });
68
+ let outcomeResolved = false;
69
+ function resolveOutcome(o: BridgeOutcome): void {
70
+ if (outcomeResolved) return;
71
+ outcomeResolved = true;
72
+ outcomeResolve(o);
73
+ }
74
+
75
+ let aborted = false;
76
+ const settledTickets = new Set<string>();
77
+ function settleOnce(ticketId: string): void {
78
+ if (settledTickets.has(ticketId)) return;
79
+ settledTickets.add(ticketId);
80
+ void opts.client.settle(ticketId).catch(() => {
81
+ // best-effort; settle failure is non-fatal
82
+ });
83
+ }
84
+
85
+ function log(info: BridgeTransition): void {
86
+ try {
87
+ opts.onTransition?.(info);
88
+ } catch {
89
+ // observability hook must never break the bridge
90
+ }
91
+ }
92
+
93
+ function emitKeepalive(controller: ReadableStreamDefaultController<Uint8Array>): void {
94
+ if (aborted) return;
95
+ try {
96
+ controller.enqueue(keepaliveFrame());
97
+ } catch {
98
+ // controller closed by consumer
99
+ }
100
+ }
101
+
102
+ function emitTerminalError(controller: ReadableStreamDefaultController<Uint8Array>, message: string, type: string = "api_error"): void {
103
+ if (aborted) return;
104
+ const payload = JSON.stringify({ type: "error", error: { type, message } });
105
+ try {
106
+ controller.enqueue(encoder.encode(`event: error\ndata: ${payload}\n\n`));
107
+ } catch {
108
+ // already closed
109
+ }
110
+ }
111
+
112
+ /**
113
+ * Wait until ticket becomes ready/active OR expired/not_found OR abort OR total maxWaitMs exceeded.
114
+ * `settled` and unknown states are treated as expired (server can't dispatch this ticket again).
115
+ * Polls respect clientSignal for immediate cancellation.
116
+ *
117
+ * `maxWaitExceeded: true` marks a CLIENT-SIDE deadline overrun (distinct from
118
+ * a server-side ticket expiry) so the caller terminates with a timeout error
119
+ * instead of misreading it as "ticket expired" and burning retakes.
120
+ */
121
+ async function waitForReady(ticketId: string, deadlineAt: number): Promise<{ state: TicketState; maxWaitExceeded?: boolean }> {
122
+ while (true) {
123
+ if (aborted) return { state: "expired" as TicketState };
124
+ const result = await pollBatchStatusWithRetry(ticketId);
125
+ if (aborted) return { state: "expired" as TicketState };
126
+ const ticket = result.tickets[0];
127
+ if (!ticket) return { state: "not_found" as TicketState };
128
+ if (isTicketReady(ticket.state)) return { state: ticket.state };
129
+ // `settled`, `expired`, `not_found`, or any unknown state → unusable, treat as expired
130
+ if (ticket.state !== "queued") return { state: "expired" as TicketState };
131
+
132
+ const delay = result.nextPollAfterMs ?? opts.pollIntervalMs;
133
+ if (opts.maxWaitMs > 0 && Date.now() + delay > deadlineAt) {
134
+ // The NEXT poll would overrun the total wait budget. Sleep out the
135
+ // remainder and report a deadline overrun (NOT "expired" — an early
136
+ // `expired` here used to send the caller into the retake loop against
137
+ // the same deadline until maxRetries burned out).
138
+ await sleep(Math.max(0, deadlineAt - Date.now()), opts.clientSignal);
139
+ return { state: "expired" as TicketState, maxWaitExceeded: true };
140
+ }
141
+ await sleep(delay, opts.clientSignal);
142
+ }
143
+ }
144
+
145
+ /**
146
+ * Single batchStatus poll with local tolerance for transient control-plane
147
+ * errors: up to POLL_RETRY_LIMIT consecutive failures (backoff
148
+ * min(pollIntervalMs, 2s) between them) before the error escapes. A single
149
+ * network blip must not kill an hours-long queue wait — the sync path
150
+ * (proxy/handler.ts connect-retry) retries the same class of failure.
151
+ * Abandon immediately (no retry) once the client has aborted.
152
+ */
153
+ async function pollBatchStatusWithRetry(ticketId: string): Promise<Awaited<ReturnType<OffPeakClient["batchStatus"]>>> {
154
+ const POLL_RETRY_LIMIT = 3;
155
+ const retryDelayMs = Math.min(opts.pollIntervalMs, 2000);
156
+ let lastErr: unknown;
157
+ for (let attempt = 1; attempt <= POLL_RETRY_LIMIT; attempt++) {
158
+ if (aborted || opts.clientSignal?.aborted) throw lastErr ?? new Error("client aborted during poll");
159
+ try {
160
+ return await opts.client.batchStatus([ticketId], opts.clientSignal);
161
+ } catch (err) {
162
+ lastErr = err;
163
+ // Client disconnected mid-poll — retrying would delay the abort path.
164
+ if (aborted || opts.clientSignal?.aborted) throw err;
165
+ if (attempt < POLL_RETRY_LIMIT) await sleep(retryDelayMs, opts.clientSignal);
166
+ }
167
+ }
168
+ throw lastErr;
169
+ }
170
+
171
+ async function forwardLLM(ticketId: string): Promise<{ response: Response; expiredInBody: boolean }> {
172
+ const url = `${opts.origin.replace(/\/+$/, "")}/api/v1/off-peak/anthropic/v1/messages`;
173
+ const headers: Record<string, string> = {
174
+ "content-type": "application/json",
175
+ authorization: `Bearer ${opts.credentials.jwt}`,
176
+ "x-coding-plan-api-key": opts.credentials.codingPlanApiKey,
177
+ "x-off-peak-ticket-id": ticketId,
178
+ ...buildIdentityHeaders(opts.identity),
179
+ };
180
+ if (opts.credentials.bigmodelOrganization) headers["bigmodel-organization"] = opts.credentials.bigmodelOrganization;
181
+ if (opts.credentials.bigmodelProject) headers["bigmodel-project"] = opts.credentials.bigmodelProject;
182
+
183
+ const resp = await fetchImpl(url, {
184
+ method: "POST",
185
+ headers,
186
+ body: opts.llmRequestBody,
187
+ signal: opts.clientSignal,
188
+ });
189
+
190
+ if (!resp.ok) {
191
+ const bodyText = await resp.text().catch(() => "");
192
+ if (bodyText.includes(EXPIRED_MARKER)) {
193
+ return { response: new Response(bodyText, { status: resp.status, headers: resp.headers }), expiredInBody: true };
194
+ }
195
+ return { response: new Response(bodyText, { status: resp.status, headers: resp.headers }), expiredInBody: false };
196
+ }
197
+ return { response: resp, expiredInBody: false };
198
+ }
199
+
200
+ const stream = new ReadableStream<Uint8Array>({
201
+ async start(controller) {
202
+ // External signal → local aborted flag. Both paths (consumer cancel + signal abort) converge here.
203
+ if (opts.clientSignal) {
204
+ if (opts.clientSignal.aborted) aborted = true;
205
+ else opts.clientSignal.addEventListener("abort", () => { aborted = true; }, { once: true });
206
+ }
207
+
208
+ // Keepalive runs ONLY during WAIT/retry phases; stopped before LLM streaming to
209
+ // avoid inserting `: keepalive\n\n` inside a partial SSE frame split across chunks.
210
+ let keepAliveTimer: ReturnType<typeof setInterval> | undefined;
211
+ function startKeepalive(): void {
212
+ if (keepAliveTimer) return;
213
+ keepAliveTimer = setInterval(() => emitKeepalive(controller), opts.keepAliveIntervalMs);
214
+ }
215
+ function stopKeepalive(): void {
216
+ if (keepAliveTimer) {
217
+ clearInterval(keepAliveTimer);
218
+ keepAliveTimer = undefined;
219
+ }
220
+ }
221
+
222
+ // Total wait deadline across all retries (B11: was per-ticket, leaked to (maxRetries+1)*maxWaitMs).
223
+ const requestStartedAt = Date.now();
224
+ const deadlineAt = opts.maxWaitMs > 0 ? requestStartedAt + opts.maxWaitMs : Number.MAX_SAFE_INTEGER;
225
+
226
+ let currentTicket = opts.initialTicket;
227
+ let attempt = 0;
228
+
229
+ try {
230
+ while (true) {
231
+ if (aborted) {
232
+ log({ phase: "abort", attempt, ticketId: currentTicket.ticketId });
233
+ settleOnce(currentTicket.ticketId);
234
+ return;
235
+ }
236
+
237
+ // WAIT phase
238
+ if (!isTicketReady(currentTicket.state)) {
239
+ log({ phase: "wait", attempt, ticketId: currentTicket.ticketId, state: currentTicket.state });
240
+ startKeepalive();
241
+ const wait = await waitForReady(currentTicket.ticketId, deadlineAt);
242
+ if (aborted) {
243
+ stopKeepalive();
244
+ log({ phase: "abort", attempt, ticketId: currentTicket.ticketId });
245
+ settleOnce(currentTicket.ticketId);
246
+ return;
247
+ }
248
+ if (wait.maxWaitExceeded) {
249
+ // CL-02: client-side maxWaitMs overrun — terminal timeout, NOT a
250
+ // server expiry. Retaking would just re-wait against the same
251
+ // (already blown) deadline until maxRetries exhausts.
252
+ stopKeepalive();
253
+ settleOnce(currentTicket.ticketId);
254
+ emitTerminalError(controller, `async max wait timeout (${opts.maxWaitMs}ms exceeded)`, "timeout");
255
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
256
+ return;
257
+ }
258
+ if (isTicketExpired(wait.state)) {
259
+ stopKeepalive();
260
+ settleOnce(currentTicket.ticketId);
261
+ // Check if this was a client-side maxWaitMs timeout (not server expiration).
262
+ // Distinguish the error so users don't chase server-side ticket issues.
263
+ if (opts.maxWaitMs > 0 && Date.now() >= deadlineAt) {
264
+ emitTerminalError(controller, `async max wait timeout (${opts.maxWaitMs}ms exceeded)`, "timeout");
265
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
266
+ return;
267
+ }
268
+ log({ phase: "expired", attempt, ticketId: currentTicket.ticketId, state: wait.state, message: "expired in queue" });
269
+ attempt++;
270
+ if (attempt > opts.maxRetries) {
271
+ emitTerminalError(controller, `async upstream exhausted retries (ticket expired in queue ${attempt}x)`, "api_error");
272
+ resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
273
+ return;
274
+ }
275
+ try {
276
+ currentTicket = await opts.client.takeTicket(opts.taskId, opts.clientSignal);
277
+ } catch (takeErr) {
278
+ emitTerminalError(controller, `async retake failed: ${(takeErr as Error).message}`, "api_error");
279
+ resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
280
+ return;
281
+ }
282
+ continue;
283
+ }
284
+ stopKeepalive();
285
+ }
286
+
287
+ // READY phase — NO keepalive (would corrupt SSE frames split across chunks)
288
+ log({ phase: "ready", attempt, ticketId: currentTicket.ticketId });
289
+ let resp: Response;
290
+ let expiredInBody: boolean;
291
+ try {
292
+ const forward = await forwardLLM(currentTicket.ticketId);
293
+ resp = forward.response;
294
+ expiredInBody = forward.expiredInBody;
295
+ } catch (err) {
296
+ if (aborted) {
297
+ settleOnce(currentTicket.ticketId);
298
+ return;
299
+ }
300
+ emitTerminalError(controller, `async upstream network error: ${(err as Error).message}`, "api_error");
301
+ settleOnce(currentTicket.ticketId);
302
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
303
+ return;
304
+ }
305
+
306
+ if (!resp.ok || expiredInBody) {
307
+ const bodyText = await resp.text().catch(() => "");
308
+ if (expiredInBody || bodyText.includes(EXPIRED_MARKER)) {
309
+ log({ phase: "expired", attempt, ticketId: currentTicket.ticketId, message: "expired during LLM (pre-stream)" });
310
+ settleOnce(currentTicket.ticketId);
311
+ attempt++;
312
+ if (attempt > opts.maxRetries) {
313
+ emitTerminalError(controller, `async upstream exhausted retries (ticket expired during LLM ${attempt}x)`, "api_error");
314
+ resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
315
+ return;
316
+ }
317
+ try {
318
+ currentTicket = await opts.client.takeTicket(opts.taskId, opts.clientSignal);
319
+ } catch (takeErr) {
320
+ emitTerminalError(controller, `async retake failed: ${(takeErr as Error).message}`, "api_error");
321
+ resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
322
+ return;
323
+ }
324
+ continue;
325
+ }
326
+ // Non-expired upstream error → emit standard Anthropic error event.
327
+ // Sanitized message: status only; body omitted to avoid leaking upstream internals.
328
+ emitTerminalError(controller, `async upstream HTTP ${resp.status}`, "api_error");
329
+ settleOnce(currentTicket.ticketId);
330
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
331
+ return;
332
+ }
333
+
334
+ // Stream upstream body with complete-frame buffering.
335
+ //
336
+ // DESIGN (fixes R3-2/R3-3/R4-1/R4-3 + bounds memory R4-5):
337
+ // - One TextDecoder for the whole streaming phase (handles partial
338
+ // multibyte UTF-8 correctly across chunk boundaries).
339
+ // - Accumulate decoded text until a complete SSE frame (`\n\n` boundary).
340
+ // - Scan the COMPLETE frame for the expired marker before forwarding.
341
+ // This catches markers split across any number of network chunks.
342
+ // - Forward via `encoder.encode(frame)` — re-encoding Unicode codepoints
343
+ // through UTF-16→UTF-8 is lossless for valid input, and avoids the
344
+ // raw-vs-decoded byte mismatch that previously dropped pre-commit
345
+ // chunks when the boundary spanned chunks.
346
+ // - Cap `pending` at MAX_PENDING_FRAME_BYTES to prevent a malicious
347
+ // upstream from exhausting memory by streaming without `\n\n`.
348
+ //
349
+ // State machine:
350
+ // Pre-commit (no frame forwarded yet): marker found → transparent retry.
351
+ // Post-commit (≥1 frame forwarded): marker found → terminal error
352
+ // (cannot retry — client already saw message_start; retrying would
353
+ // produce duplicate lifecycle events).
354
+ let midStreamExpiredPreCommit = false;
355
+ let midStreamExpiredPostCommit = false;
356
+ let committed = false;
357
+ if (resp.body) {
358
+ const reader = resp.body.getReader();
359
+ const streamDecoder = new TextDecoder();
360
+ let pending = "";
361
+ const MAX_PENDING_FRAME_BYTES = 1 * 1024 * 1024;
362
+ try {
363
+ while (true) {
364
+ if (aborted) {
365
+ await reader.cancel().catch(() => {});
366
+ settleOnce(currentTicket.ticketId);
367
+ return;
368
+ }
369
+ const { done, value } = await reader.read();
370
+ if (done) {
371
+ // SSE spec: discard pending data at EOF if it lacks a terminating
372
+ // blank line (incomplete event). Only flush if marker-free AND
373
+ // properly terminated.
374
+ if (pending.length > 0 && !aborted && !midStreamExpiredPreCommit && !midStreamExpiredPostCommit) {
375
+ if (pending.includes(EXPIRED_MARKER)) {
376
+ if (!committed) midStreamExpiredPreCommit = true;
377
+ else midStreamExpiredPostCommit = true;
378
+ } else if (pending.endsWith("\n\n")) {
379
+ // Properly terminated final frame — safe to forward.
380
+ try { controller.enqueue(encoder.encode(pending)); } catch {}
381
+ }
382
+ // else: unterminated event at EOF — discard per SSE spec.
383
+ pending = "";
384
+ }
385
+ break;
386
+ }
387
+ if (aborted) break;
388
+ pending += streamDecoder.decode(value, { stream: true }).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
389
+
390
+ // Bounded buffer: if pending exceeds the cap without a frame boundary,
391
+ // the upstream is malformed or malicious — terminate.
392
+ if (pending.length > MAX_PENDING_FRAME_BYTES) {
393
+ await reader.cancel().catch(() => {});
394
+ emitTerminalError(controller, "async upstream SSE frame exceeded 1 MiB boundary", "api_error");
395
+ settleOnce(currentTicket.ticketId);
396
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
397
+ return;
398
+ }
399
+
400
+ // Process all complete frames in `pending`.
401
+ let frameBoundaryFound = false;
402
+ while (true) {
403
+ const idx = pending.indexOf("\n\n");
404
+ if (idx === -1) break;
405
+ const frame = pending.slice(0, idx + 2);
406
+ pending = pending.slice(idx + 2);
407
+
408
+ if (frame.includes(EXPIRED_MARKER)) {
409
+ if (!committed) {
410
+ midStreamExpiredPreCommit = true;
411
+ } else {
412
+ midStreamExpiredPostCommit = true;
413
+ }
414
+ await reader.cancel().catch(() => {});
415
+ frameBoundaryFound = true;
416
+ break;
417
+ }
418
+ try {
419
+ controller.enqueue(encoder.encode(frame));
420
+ committed = true;
421
+ } catch {
422
+ await reader.cancel().catch(() => {});
423
+ frameBoundaryFound = true;
424
+ break;
425
+ }
426
+ }
427
+ if (midStreamExpiredPreCommit || midStreamExpiredPostCommit || frameBoundaryFound) break;
428
+ }
429
+ // Flush decoder (no stream flag) to release internal partial-byte state.
430
+ streamDecoder.decode();
431
+ } finally {
432
+ reader.releaseLock?.();
433
+ }
434
+ }
435
+
436
+ if (midStreamExpiredPreCommit && !aborted) {
437
+ log({ phase: "expired", attempt, ticketId: currentTicket.ticketId, message: "expired during LLM (mid-stream, pre-commit)" });
438
+ settleOnce(currentTicket.ticketId);
439
+ attempt++;
440
+ if (attempt > opts.maxRetries) {
441
+ emitTerminalError(controller, `async upstream exhausted retries (ticket expired mid-stream ${attempt}x)`, "api_error");
442
+ resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
443
+ return;
444
+ }
445
+ try {
446
+ currentTicket = await opts.client.takeTicket(opts.taskId, opts.clientSignal);
447
+ } catch (takeErr) {
448
+ emitTerminalError(controller, `async retake failed: ${(takeErr as Error).message}`, "api_error");
449
+ resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
450
+ return;
451
+ }
452
+ continue;
453
+ }
454
+
455
+ if (midStreamExpiredPostCommit && !aborted) {
456
+ // Cannot retry transparently — client already saw message_start.
457
+ // Emit terminal error and close.
458
+ log({ phase: "error", attempt, ticketId: currentTicket.ticketId, message: "expired mid-stream after commit; cannot retry" });
459
+ settleOnce(currentTicket.ticketId);
460
+ emitTerminalError(controller, "async upstream ticket expired mid-stream after output started", "api_error");
461
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
462
+ return;
463
+ }
464
+
465
+ if (aborted) {
466
+ log({ phase: "abort", attempt, ticketId: currentTicket.ticketId });
467
+ settleOnce(currentTicket.ticketId);
468
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "abort" });
469
+ return;
470
+ }
471
+
472
+ log({ phase: "done", attempt, ticketId: currentTicket.ticketId });
473
+ settleOnce(currentTicket.ticketId);
474
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "done" });
475
+ return;
476
+ }
477
+ } catch (err) {
478
+ if (!aborted) {
479
+ emitTerminalError(controller, `async bridge internal error: ${(err as Error).message}`, "api_error");
480
+ }
481
+ settleOnce(currentTicket.ticketId);
482
+ resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" });
483
+ } finally {
484
+ stopKeepalive();
485
+ try {
486
+ controller.close();
487
+ } catch {
488
+ // already closed
489
+ }
490
+ // Abort paths return without calling resolveOutcome; resolve here as a fallback
491
+ // so `await outcome` never hangs. Idempotent — explicit calls above take precedence.
492
+ resolveOutcome({
493
+ attempts: attempt + 1,
494
+ finalTicketId: currentTicket.ticketId,
495
+ terminalPhase: aborted ? "abort" : "error",
496
+ });
497
+ }
498
+ },
499
+
500
+ cancel() {
501
+ aborted = true;
502
+ },
503
+ });
504
+
505
+ return { stream, outcome };
506
+ }
507
+
508
+ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
509
+ return new Promise((resolve) => {
510
+ if (signal?.aborted) {
511
+ resolve();
512
+ return;
513
+ }
514
+ const t = setTimeout(() => {
515
+ signal?.removeEventListener("abort", onAbort);
516
+ resolve();
517
+ }, ms);
518
+ const onAbort = (): void => {
519
+ clearTimeout(t);
520
+ resolve();
521
+ };
522
+ signal?.addEventListener("abort", onAbort, { once: true });
523
+ });
524
+ }
src/async/client.ts ADDED
@@ -0,0 +1,259 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * HTTP client for ZCode's off-peak ticket-queue backend.
3
+ *
4
+ * Implements the 4 control-plane endpoints documented in `_reverse/NOTEPAD.md`:
5
+ * - `GET /ticket/availability` — probe queue availability
6
+ * - `POST /ticket` — take a number (queue entry)
7
+ * - `POST /ticket/status` — batch poll ticket states
8
+ * - `POST /ticket/{id}/settle` — close-out (success/abort/cancel)
9
+ *
10
+ * Each method has its own short timeout (default 15s) via `setTimeout + abort`.
11
+ * 4xx on `settle` resolves as success (server already cleaned up — see `settleOne`
12
+ * in the bundle). Other 4xx/5xx throw `OffPeakServerError`.
13
+ *
14
+ * @see _reverse/NOTEPAD.md "Off-Peak / Idle Plan" → "Endpoints" / "Headers"
15
+ */
16
+ import type {
17
+ AvailabilityResult,
18
+ BatchStatusResult,
19
+ OffPeakCredentials,
20
+ TakeTicketResult,
21
+ TicketState,
22
+ TicketStatusResult,
23
+ } from "./types.js";
24
+ import { OffPeakServerError } from "./types.js";
25
+
26
+ export interface OffPeakClientOptions {
27
+ origin: string;
28
+ credentials: OffPeakCredentials;
29
+ /** Per-call timeout in ms (default 15000). Applies to all 4 methods. */
30
+ controlTimeoutMs?: number;
31
+ /** DI seam for tests. Default `globalThis.fetch`. */
32
+ fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
33
+ /** Settle-specific timeout override (default = controlTimeoutMs). Set lower for fire-and-forget abort paths. */
34
+ settleTimeoutMs?: number;
35
+ }
36
+
37
+ const DEFAULT_CONTROL_TIMEOUT_MS = 15_000;
38
+
39
+ /** Maximum tickets per `/ticket/status` batch (server cap, mirrors bundle behavior). */
40
+ const MAX_BATCH_STATUS = 100;
41
+
42
+ export interface OffPeakClient {
43
+ getAvailability(signal?: AbortSignal): Promise<AvailabilityResult>;
44
+ takeTicket(taskId: string, signal?: AbortSignal): Promise<TakeTicketResult>;
45
+ batchStatus(ticketIds: string[], signal?: AbortSignal): Promise<BatchStatusResult>;
46
+ /** Settle a ticket. `settleAsSuccess` controls 4xx behavior: if true (default), 4xx resolves as success (server already cleaned up). */
47
+ settle(ticketId: string, opts?: { settleAsSuccess?: boolean; signal?: AbortSignal }): Promise<void>;
48
+ }
49
+
50
+ export function createOffPeakClient(opts: OffPeakClientOptions): OffPeakClient {
51
+ const origin = opts.origin.replace(/\/+$/, "");
52
+ const credentials = opts.credentials;
53
+ const controlTimeoutMs = opts.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS;
54
+ const settleTimeoutMs = opts.settleTimeoutMs ?? controlTimeoutMs;
55
+ const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
56
+
57
+ function buildHeaders(hasBody: boolean): Record<string, string> {
58
+ const h: Record<string, string> = {
59
+ authorization: `Bearer ${credentials.jwt}`,
60
+ "x-coding-plan-api-key": credentials.codingPlanApiKey,
61
+ };
62
+ if (hasBody) h["content-type"] = "application/json";
63
+ if (credentials.bigmodelOrganization) h["bigmodel-organization"] = credentials.bigmodelOrganization;
64
+ if (credentials.bigmodelProject) h["bigmodel-project"] = credentials.bigmodelProject;
65
+ return h;
66
+ }
67
+
68
+ async function request(
69
+ method: string,
70
+ path: string,
71
+ body: unknown | undefined,
72
+ timeoutMs: number,
73
+ externalSignal: AbortSignal | undefined,
74
+ isSettle: boolean,
75
+ settleAsSuccess: boolean,
76
+ ): Promise<unknown> {
77
+ const controller = new AbortController();
78
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
79
+ const onExternalAbort = (): void => controller.abort();
80
+ if (externalSignal) {
81
+ if (externalSignal.aborted) controller.abort();
82
+ else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
83
+ }
84
+
85
+ const url = `${origin}/api/v1/off-peak${path}`;
86
+ const init: RequestInit = {
87
+ method,
88
+ headers: buildHeaders(body !== undefined),
89
+ signal: controller.signal,
90
+ };
91
+ if (body !== undefined) init.body = JSON.stringify(body);
92
+
93
+ // Single outer try/finally covers BOTH fetch + body consumption.
94
+ // Round 4 found that fetch rejection bypassed the body-phase cleanup,
95
+ // leaving timer + listener leaked. Outer finally guarantees cleanup on every path.
96
+ let resp: Response | undefined;
97
+ let raw = "";
98
+ try {
99
+ try {
100
+ resp = await fetchImpl(url, init);
101
+ } catch (err) {
102
+ const msg = (err as Error)?.message ?? String(err);
103
+ if (/abort/i.test(msg)) throw new OffPeakServerError(`off-peak request aborted: ${method} ${path}`, 0);
104
+ throw new OffPeakServerError(`off-peak network error: ${method} ${path}: ${msg}`, 0);
105
+ }
106
+ raw = await resp.text();
107
+ } finally {
108
+ clearTimeout(timer);
109
+ externalSignal?.removeEventListener("abort", onExternalAbort);
110
+ }
111
+
112
+ if (!resp.ok) {
113
+ // Settle-specific: 4xx means server already cleaned up (ticket expired/not_found) — treat as success.
114
+ if (isSettle && settleAsSuccess && resp.status >= 400 && resp.status < 500) {
115
+ return undefined;
116
+ }
117
+ let bizCode: string | undefined;
118
+ let serverMsg = `HTTP ${resp.status}`;
119
+ try {
120
+ const parsed = JSON.parse(raw);
121
+ bizCode = parsed?.code !== undefined ? String(parsed.code) : undefined;
122
+ if (parsed?.msg) serverMsg = String(parsed.msg);
123
+ else if (parsed?.message) serverMsg = String(parsed.message);
124
+ } catch {
125
+ if (raw.length > 0 && raw.length < 200) serverMsg = raw;
126
+ }
127
+ throw new OffPeakServerError(
128
+ `off-peak ${method} ${path} failed: ${serverMsg}`,
129
+ resp.status,
130
+ bizCode,
131
+ );
132
+ }
133
+
134
+ if (raw.length === 0) return undefined;
135
+ let parsedJson: unknown;
136
+ try {
137
+ parsedJson = JSON.parse(raw);
138
+ } catch {
139
+ return undefined;
140
+ }
141
+ // Unwrap canonical envelope `{code:0, data:{...}}`. Non-zero `code` on HTTP 200
142
+ // is a business-level error (mirrors `requestBizApi` in `auth/resolver.ts` and
143
+ // the bundle's `n` helper: `y.code===0 ? y.data : y`).
144
+ if (parsedJson && typeof parsedJson === "object") {
145
+ const obj = parsedJson as { code?: unknown; data?: unknown; msg?: unknown; message?: unknown };
146
+ if ("code" in obj || "data" in obj) {
147
+ // NOTEPAD spec: canonical success is numeric `code === 0` ONLY (bundle's
148
+ // `n` helper: `y.code===0 ? y.data : y`). Strict `===` rejects string "0",
149
+ // numeric 200, undefined, etc. Responses without a numeric `code` field
150
+ // but with `data` are NOT unwrapped (avoids masking biz errors).
151
+ const code = obj.code;
152
+ if (code !== 0) {
153
+ if (code === undefined) {
154
+ // Ambiguous envelope ({data:...} without code) — be conservative, don't unwrap.
155
+ // Return parsedJson as-is so the caller sees the wrapper.
156
+ } else {
157
+ const msg = obj.msg ?? obj.message ?? `biz code ${String(code)}`;
158
+ throw new OffPeakServerError(
159
+ `off-peak ${method} ${path} biz error: ${msg}`,
160
+ resp?.status ?? 0,
161
+ String(code),
162
+ );
163
+ }
164
+ } else if (obj.data !== undefined) {
165
+ return obj.data;
166
+ }
167
+ }
168
+ }
169
+ return parsedJson;
170
+ }
171
+
172
+ return {
173
+ async getAvailability(signal?: AbortSignal): Promise<AvailabilityResult> {
174
+ const data = (await request("GET", "/ticket/availability", undefined, controlTimeoutMs, signal, false, false)) as
175
+ | { can_take_number?: boolean; next_take_at?: number }
176
+ | undefined;
177
+ if (!data) throw new OffPeakServerError("off-peak availability empty response", 0);
178
+ const canTakeNumber = data.can_take_number === true;
179
+ if (!canTakeNumber && data.next_take_at === undefined) {
180
+ throw new OffPeakServerError("off-peak availability missing next_take_at while unavailable", 0);
181
+ }
182
+ const result: AvailabilityResult = { canTakeNumber };
183
+ if (data.next_take_at !== undefined) result.nextTakeAt = data.next_take_at;
184
+ return result;
185
+ },
186
+
187
+ async takeTicket(taskId: string, signal?: AbortSignal): Promise<TakeTicketResult> {
188
+ if (!taskId || typeof taskId !== "string") {
189
+ throw new Error("takeTicket: taskId must be a non-empty string");
190
+ }
191
+ const data = (await request("POST", "/ticket", { task_id: taskId }, controlTimeoutMs, signal, false, false)) as
192
+ | { ticket_id?: string; state?: string; position?: number; next_poll_after?: number }
193
+ | undefined;
194
+ if (!data || typeof data.ticket_id !== "string" || typeof data.state !== "string") {
195
+ throw new OffPeakServerError("off-peak takeTicket malformed response", 0);
196
+ }
197
+ const state = data.state as TicketState;
198
+ const result: TakeTicketResult = {
199
+ ticketId: data.ticket_id,
200
+ state,
201
+ registeredAt: Date.now(),
202
+ };
203
+ if (data.position != null) result.position = data.position;
204
+ if (data.next_poll_after !== undefined) result.nextPollAfterMs = data.next_poll_after * 1000;
205
+ return result;
206
+ },
207
+
208
+ async batchStatus(ticketIds: string[], signal?: AbortSignal): Promise<BatchStatusResult> {
209
+ if (ticketIds.length === 0) return { tickets: [] };
210
+ const truncated = ticketIds.slice(0, MAX_BATCH_STATUS);
211
+ const data = (await request(
212
+ "POST",
213
+ "/ticket/status",
214
+ { ticket_ids: truncated },
215
+ controlTimeoutMs,
216
+ signal,
217
+ false,
218
+ false,
219
+ )) as
220
+ | { next_poll_after?: number; tickets?: Array<{ ticket_id?: string; state?: string; position?: number; active_deadline?: number }> }
221
+ | undefined;
222
+ if (!data || !Array.isArray(data.tickets)) {
223
+ throw new OffPeakServerError("off-peak batchStatus malformed response", 0);
224
+ }
225
+ const result: BatchStatusResult = {
226
+ tickets: data.tickets.map((t): TicketStatusResult => {
227
+ if (typeof t.ticket_id !== "string" || typeof t.state !== "string") {
228
+ throw new OffPeakServerError("off-peak batchStatus ticket entry malformed", 0);
229
+ }
230
+ const item: TicketStatusResult = {
231
+ ticketId: t.ticket_id,
232
+ state: t.state as TicketState,
233
+ };
234
+ if (t.position != null) item.position = t.position;
235
+ if (t.active_deadline !== undefined) item.activeDeadline = t.active_deadline;
236
+ return item;
237
+ }),
238
+ };
239
+ if (data.next_poll_after !== undefined) result.nextPollAfterMs = data.next_poll_after * 1000;
240
+ return result;
241
+ },
242
+
243
+ async settle(
244
+ ticketId: string,
245
+ opts: { settleAsSuccess?: boolean; signal?: AbortSignal } = {},
246
+ ): Promise<void> {
247
+ const settleAsSuccess = opts.settleAsSuccess !== false;
248
+ await request(
249
+ "POST",
250
+ `/ticket/${encodeURIComponent(ticketId)}/settle`,
251
+ undefined,
252
+ settleTimeoutMs,
253
+ opts.signal,
254
+ true,
255
+ settleAsSuccess,
256
+ );
257
+ },
258
+ };
259
+ }
src/async/handler.ts ADDED
@@ -0,0 +1,482 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Async route handlers — wrap the bridge with format-specific translation.
3
+ *
4
+ * Three handlers:
5
+ * - `handleAsyncMessages` (Anthropic client, POST /async/v1/messages) — passthrough
6
+ * - `handleAsyncChat` (OpenAI client, POST /async/v1/chat/completions) — request OAI→ANT, response ANT SSE→OAI SSE
7
+ * - `handleAsyncHealth` (GET /async/v1/health) — probe queue availability
8
+ *
9
+ * Common pre-flight (B1 fix: validate BEFORE takeTicket so we never leak a ticket
10
+ * on JSON parse / model-missing / translation failures):
11
+ * 1. Verify credential has `jwt` (login-captured JWT; absent on imported keys)
12
+ * 2. Read + parse client body (skip for health)
13
+ * 3. Validate required fields + build the Anthropic-format upstream body
14
+ * 4. ONLY THEN takeTicket (any failure above returns 4xx WITHOUT a ticket)
15
+ *
16
+ * For non-stream (B5+B10): internally force `stream:true` upstream; return a
17
+ * chunked `application/json` response that emits legal leading whitespace during
18
+ * wait (defeats client TCP idle) and writes the final aggregated JSON at the end.
19
+ *
20
+ * @see .omo/plans/async-off-peak-bridge.md §3 for full design.
21
+ */
22
+ import type { ProxyConfig } from "../config/types.js";
23
+ import type { AuthManager } from "../auth/manager.js";
24
+ import type { Credential } from "../auth/types.js";
25
+ import { credentialString } from "../auth/types.js";
26
+ import { errorResponse } from "../proxy/handler.js";
27
+ import { transformRequestBody } from "../proxy/body-transformer.js";
28
+ import { inflateWithCap } from "../proxy/inflate.js";
29
+ import { translateRequestOpenAIToAnthropic, translateResponseAnthropicToOpenAI } from "../translator/openai-to-anthropic.js";
30
+ import { anthropicSseToOpenaiSseWithKeepalive } from "./openai-stream-adapter.js";
31
+ import type { AnthropicMessagesRequest, OpenAIChatRequest, AnthropicMessagesResponse } from "../translator/types.js";
32
+ import { createOffPeakClient, type OffPeakClient } from "./client.js";
33
+ import type { OffPeakCredentials, TakeTicketResult } from "./types.js";
34
+ import { runAsyncBridge } from "./bridge.js";
35
+
36
+ /** Cap request body size to prevent memory exhaustion (B16). */
37
+ const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
38
+
39
+ /** Single space byte — used for non-stream chunked JSON whitespace keepalive. */
40
+ const SINGLE_SPACE = new Uint8Array([32]);
41
+
42
+ export interface AsyncHandlerOptions {
43
+ config: ProxyConfig;
44
+ auth: AuthManager;
45
+ fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
46
+ debug?: boolean;
47
+ }
48
+
49
+ function buildCredentials(cred: Credential): OffPeakCredentials {
50
+ return {
51
+ jwt: cred.jwt ?? "",
52
+ codingPlanApiKey: credentialString(cred),
53
+ };
54
+ }
55
+
56
+ function generateTaskId(): string {
57
+ return `proxy-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
58
+ }
59
+
60
+ function resolveModel(req: { model?: string }, config: ProxyConfig): string {
61
+ const explicit = typeof req.model === "string" ? req.model.trim() : "";
62
+ if (explicit) return explicit;
63
+ if (config.async.defaultModel && config.async.defaultModel.trim()) return config.async.defaultModel.trim();
64
+ return config.defaultModel;
65
+ }
66
+
67
+ async function readBody(req: Request): Promise<{ ok: true; body: string } | { ok: false; response: Response }> {
68
+ // Reject oversized Content-Length up front; otherwise drain the stream incrementally
69
+ // and abort as soon as we exceed the cap. This prevents an attacker from exhausting
70
+ // memory by sending a huge chunked body with no Content-Length.
71
+ const contentLength = req.headers.get("content-length");
72
+ if (contentLength) {
73
+ const cl = parseInt(contentLength, 10);
74
+ if (Number.isFinite(cl) && cl > MAX_REQUEST_BODY_BYTES) {
75
+ // Cancel the request body stream so the underlying socket releases; otherwise
76
+ // the client can keep the connection alive despite the 413 response.
77
+ req.body?.cancel().catch(() => {});
78
+ return { ok: false, response: errorResponse(413, "request_too_large", `body exceeds ${MAX_REQUEST_BODY_BYTES} byte cap`) };
79
+ }
80
+ }
81
+ if (!req.body) {
82
+ return { ok: false, response: errorResponse(400, "invalid_request_error", "missing request body") };
83
+ }
84
+ const reader = req.body.getReader();
85
+ const chunks: Uint8Array[] = [];
86
+ let total = 0;
87
+ try {
88
+ while (true) {
89
+ const { done, value } = await reader.read();
90
+ if (done) break;
91
+ total += value.byteLength;
92
+ if (total > MAX_REQUEST_BODY_BYTES) {
93
+ await reader.cancel().catch(() => {});
94
+ return { ok: false, response: errorResponse(413, "request_too_large", `body exceeds ${MAX_REQUEST_BODY_BYTES} byte cap`) };
95
+ }
96
+ chunks.push(value);
97
+ }
98
+ } catch {
99
+ return { ok: false, response: errorResponse(400, "invalid_request_error", "could not read request body") };
100
+ } finally {
101
+ reader.releaseLock?.();
102
+ }
103
+ // Inflate `content-encoding: gzip` request bodies with the cap enforced on
104
+ // the DECOMPRESSED size — a small gzip bomb must not bypass the byte cap.
105
+ const encoding = req.headers.get("content-encoding")?.toLowerCase().trim() ?? "";
106
+ let bytes: Uint8Array = Buffer.concat(chunks);
107
+ if (encoding === "gzip" || encoding === "x-gzip") {
108
+ const inflated = await inflateWithCap(bytes, MAX_REQUEST_BODY_BYTES);
109
+ if (!inflated.ok) {
110
+ if (inflated.reason === "too_large") {
111
+ return { ok: false, response: errorResponse(413, "request_too_large", `decompressed body exceeds ${MAX_REQUEST_BODY_BYTES} byte cap`) };
112
+ }
113
+ return { ok: false, response: errorResponse(400, "invalid_request_error", "could not decompress gzip request body") };
114
+ }
115
+ bytes = inflated.bytes;
116
+ }
117
+ const body = new TextDecoder().decode(bytes);
118
+ if (!body || body.length === 0) {
119
+ return { ok: false, response: errorResponse(400, "invalid_request_error", "empty request body") };
120
+ }
121
+ return { ok: true, body };
122
+ }
123
+
124
+ async function resolveCredential(opts: AsyncHandlerOptions): Promise<{ ok: true; cred: Credential; credentials: OffPeakCredentials } | { ok: false; response: Response }> {
125
+ let cred: Credential;
126
+ try {
127
+ cred = await opts.auth.getCredential();
128
+ } catch (err) {
129
+ return { ok: false, response: errorResponse(401, "authentication_error", `credential resolution failed: ${(err as Error).message}`) };
130
+ }
131
+ if (!cred.jwt) {
132
+ return {
133
+ ok: false,
134
+ response: errorResponse(
135
+ 400,
136
+ "async_credentials_unavailable",
137
+ "async endpoints require a logged-in oauth credential (JWT missing). Re-run `auth login` or use sync /v1/* endpoints.",
138
+ ),
139
+ };
140
+ }
141
+ return { ok: true, cred, credentials: buildCredentials(cred) };
142
+ }
143
+
144
+ function buildClient(opts: AsyncHandlerOptions, credentials: OffPeakCredentials): OffPeakClient {
145
+ return createOffPeakClient({
146
+ origin: opts.config.async.origin,
147
+ credentials,
148
+ controlTimeoutMs: opts.config.async.controlTimeoutMs,
149
+ settleTimeoutMs: opts.config.async.settleTimeoutMs,
150
+ fetchImpl: opts.fetchImpl,
151
+ });
152
+ }
153
+
154
+ async function takeTicketOr502(client: OffPeakClient, taskId: string, opts: AsyncHandlerOptions, signal: AbortSignal | undefined): Promise<{ ok: true; ticket: TakeTicketResult } | { ok: false; response: Response }> {
155
+ try {
156
+ const ticket = await client.takeTicket(taskId, signal);
157
+ return { ok: true, ticket };
158
+ } catch (err) {
159
+ return { ok: false, response: errorResponse(502, "async_take_ticket_failed", `off-peak takeTicket failed: ${(err as Error).message}`) };
160
+ }
161
+ }
162
+
163
+ function buildBridge(opts: AsyncHandlerOptions, client: OffPeakClient, credentials: OffPeakCredentials, llmRequestBody: string, initialTicket: TakeTicketResult, taskId: string, req: Request) {
164
+ return runAsyncBridge({
165
+ client,
166
+ credentials,
167
+ origin: opts.config.async.origin,
168
+ identity: opts.config.identity,
169
+ llmRequestBody,
170
+ initialTicket,
171
+ taskId,
172
+ pollIntervalMs: opts.config.async.pollIntervalMs,
173
+ keepAliveIntervalMs: opts.config.async.keepAliveIntervalMs,
174
+ maxRetries: opts.config.async.maxRetries,
175
+ maxWaitMs: opts.config.async.maxWaitMs,
176
+ clientSignal: req.signal,
177
+ fetchImpl: opts.fetchImpl,
178
+ onTransition: opts.debug
179
+ ? (info) => {
180
+ console.log(`[async] task=${taskId} ticket=${info.ticketId} phase=${info.phase} attempt=${info.attempt}${info.state ? ` state=${info.state}` : ""}${info.message ? ` msg=${info.message}` : ""}`);
181
+ }
182
+ : undefined,
183
+ });
184
+ }
185
+
186
+ function sseHeaders(): Record<string, string> {
187
+ return {
188
+ "content-type": "text/event-stream; charset=utf-8",
189
+ "cache-control": "no-cache",
190
+ connection: "keep-alive",
191
+ };
192
+ }
193
+
194
+ export async function handleAsyncMessages(req: Request, opts: AsyncHandlerOptions): Promise<Response> {
195
+ // B1: validate everything before ticket acquisition
196
+ const cred = await resolveCredential(opts);
197
+ if (!cred.ok) return cred.response;
198
+
199
+ const bodyResult = await readBody(req);
200
+ if (!bodyResult.ok) return bodyResult.response;
201
+
202
+ let parsedBody: Record<string, unknown>;
203
+ try {
204
+ const raw = JSON.parse(bodyResult.body);
205
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
206
+ return errorResponse(400, "invalid_request_error", "request body must be a JSON object");
207
+ }
208
+ parsedBody = raw as Record<string, unknown>;
209
+ } catch {
210
+ return errorResponse(400, "invalid_request_error", "request body is not valid JSON");
211
+ }
212
+ if (!Array.isArray(parsedBody.messages) || parsedBody.messages.length === 0) {
213
+ return errorResponse(400, "invalid_request_error", "missing or invalid `messages` field");
214
+ }
215
+ // Anthropic spec: omitted `stream` defaults to non-streaming (false).
216
+ const clientWantsStream = parsedBody.stream === true;
217
+
218
+ const modelStr = typeof parsedBody.model === "string" ? parsedBody.model : undefined;
219
+ // Anthropic spec: omitted `stream` defaults to non-streaming (false).
220
+ // Validated: parsedBody is a plain object with messages[]. Remaining fields
221
+ // (max_tokens, tools, etc.) are forwarded as-is — upstream rejects invalid shapes.
222
+ const upstreamBody = {
223
+ ...parsedBody,
224
+ model: resolveModel({ model: modelStr }, opts.config),
225
+ stream: true,
226
+ } as AnthropicMessagesRequest;
227
+ const upstreamBodyText = transformRequestBody(JSON.stringify(upstreamBody), { format: "anthropic", userId: cred.cred.userId }) ?? JSON.stringify(upstreamBody);
228
+
229
+ // Now we're safe to take a ticket
230
+ const client = buildClient(opts, cred.credentials);
231
+ const taskId = generateTaskId();
232
+ const ticket = await takeTicketOr502(client, taskId, opts, req.signal);
233
+ if (!ticket.ok) return ticket.response;
234
+
235
+ const { stream, outcome } = buildBridge(opts, client, cred.credentials, upstreamBodyText, ticket.ticket, taskId, req);
236
+ void outcome;
237
+
238
+ if (clientWantsStream) {
239
+ return new Response(stream, { status: 200, headers: sseHeaders() });
240
+ }
241
+
242
+ // Non-stream: chunked response with leading whitespace during wait + final JSON (B10).
243
+ // NOTE: no explicit `transfer-encoding` header — it is a forbidden Response
244
+ // constructor header (runtimes drop/override it) and Node http already sends
245
+ // chunked when no content-length is set.
246
+ return new Response(nonStreamChunkedJson(stream), {
247
+ status: 200,
248
+ headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-cache" },
249
+ });
250
+ }
251
+
252
+ export async function handleAsyncChat(req: Request, opts: AsyncHandlerOptions): Promise<Response> {
253
+ const cred = await resolveCredential(opts);
254
+ if (!cred.ok) return cred.response;
255
+
256
+ const bodyResult = await readBody(req);
257
+ if (!bodyResult.ok) return bodyResult.response;
258
+
259
+ let openaiReq: OpenAIChatRequest;
260
+ try {
261
+ openaiReq = JSON.parse(bodyResult.body) as OpenAIChatRequest;
262
+ } catch {
263
+ return errorResponse(400, "invalid_request_error", "request body is not valid JSON");
264
+ }
265
+ if (!Array.isArray(openaiReq.messages) || openaiReq.messages.length === 0) {
266
+ return errorResponse(400, "invalid_request_error", "missing or invalid `messages` field");
267
+ }
268
+ openaiReq.model = resolveModel(openaiReq, opts.config);
269
+ const clientWantsStream = openaiReq.stream === true;
270
+
271
+ let anthropicReq: AnthropicMessagesRequest;
272
+ try {
273
+ anthropicReq = translateRequestOpenAIToAnthropic(openaiReq);
274
+ } catch (err) {
275
+ return errorResponse(400, "invalid_request_error", `OpenAI→Anthropic translation failed: ${(err as Error).message}`);
276
+ }
277
+ anthropicReq.stream = true;
278
+ const upstreamBodyText = transformRequestBody(JSON.stringify(anthropicReq), { format: "anthropic", userId: cred.cred.userId }) ?? JSON.stringify(anthropicReq);
279
+
280
+ const client = buildClient(opts, cred.credentials);
281
+ const taskId = generateTaskId();
282
+ const ticket = await takeTicketOr502(client, taskId, opts, req.signal);
283
+ if (!ticket.ok) return ticket.response;
284
+
285
+ const { stream: rawStream, outcome } = buildBridge(opts, client, cred.credentials, upstreamBodyText, ticket.ticket, taskId, req);
286
+ void outcome;
287
+
288
+ if (clientWantsStream) {
289
+ // B4: custom translator that preserves `: keepalive` comments and converts Anthropic errors
290
+ const openaiStream = anthropicSseToOpenaiSseWithKeepalive(rawStream, openaiReq.model);
291
+ return new Response(openaiStream, { status: 200, headers: sseHeaders() });
292
+ }
293
+
294
+ return new Response(nonStreamChunkedJson(rawStream, { translate: "openai", model: openaiReq.model }), {
295
+ status: 200,
296
+ headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-cache" },
297
+ });
298
+ }
299
+
300
+ export async function handleAsyncHealth(_req: Request, opts: AsyncHandlerOptions): Promise<Response> {
301
+ const cred = await resolveCredential(opts);
302
+ if (!cred.ok) return cred.response;
303
+ const client = buildClient(opts, cred.credentials);
304
+ try {
305
+ const avail = await client.getAvailability();
306
+ return new Response(JSON.stringify(avail), { status: 200, headers: { "content-type": "application/json" } });
307
+ } catch (err) {
308
+ return errorResponse(502, "async_health_failed", (err as Error).message);
309
+ }
310
+ }
311
+
312
+ /**
313
+ * Wrap the SSE byte stream as a non-stream JSON response. Emits leading whitespace
314
+ * during ticket-queue wait (defeats client TCP idle), then a single JSON document.
315
+ *
316
+ * Two modes:
317
+ * - default: Anthropic batch JSON shape
318
+ * - {translate: "openai"}: OpenAI batch JSON shape (translated from Anthropic)
319
+ */
320
+ function nonStreamChunkedJson(
321
+ bridgeStream: ReadableStream<Uint8Array>,
322
+ translateOpts?: { translate: "openai"; model: string },
323
+ ): ReadableStream<Uint8Array> {
324
+ const encoder = new TextEncoder();
325
+ return new ReadableStream<Uint8Array>({
326
+ async start(controller) {
327
+ const reader = bridgeStream.getReader();
328
+ const decoder = new TextDecoder();
329
+ let sseBuffer = "";
330
+ try {
331
+ while (true) {
332
+ const { done, value } = await reader.read();
333
+ if (done) break;
334
+ // One space byte per received chunk (not per char). Resets TCP idle timer
335
+ // while keeping allocation count proportional to chunk count, not byte count.
336
+ try {
337
+ controller.enqueue(SINGLE_SPACE);
338
+ } catch {
339
+ return;
340
+ }
341
+ sseBuffer += decoder.decode(value, { stream: true });
342
+ }
343
+ sseBuffer += decoder.decode();
344
+ } finally {
345
+ reader.releaseLock?.();
346
+ }
347
+
348
+ // Reconstruct Anthropic batch JSON from accumulated SSE
349
+ const anthropicMsg = reconstructAnthropicBatch(sseBuffer);
350
+ if (!anthropicMsg) {
351
+ const errPayload = { error: { type: "async_aggregation_failed", message: "could not reconstruct response from bridge stream" } };
352
+ try {
353
+ controller.enqueue(encoder.encode(JSON.stringify(errPayload)));
354
+ } catch {
355
+ // closed
356
+ }
357
+ controller.close();
358
+ return;
359
+ }
360
+
361
+ const finalJson = translateOpts?.translate === "openai"
362
+ ? JSON.stringify(translateResponseAnthropicToOpenAI(anthropicMsg, translateOpts.model))
363
+ : JSON.stringify(anthropicMsg);
364
+ try {
365
+ controller.enqueue(encoder.encode(finalJson));
366
+ } catch {
367
+ // closed
368
+ }
369
+ controller.close();
370
+ },
371
+ });
372
+ }
373
+
374
+ /**
375
+ * Reconstruct a synthetic `AnthropicMessagesResponse` from a stream of Anthropic SSE bytes.
376
+ * Handles message_start, content_block_start/delta/stop, message_delta, message_stop.
377
+ *
378
+ * Fail-closed: returns null if `message_stop` not seen, or on `event: error`.
379
+ * Preserves `signature_delta` for thinking blocks. No production `any`.
380
+ */
381
+ function reconstructAnthropicBatch(sseText: string): AnthropicMessagesResponse | null {
382
+ const blocks = sseText.split("\n\n");
383
+ type ContentBlock =
384
+ | { type: "text"; text: string }
385
+ | { type: "thinking"; thinking: string; signature?: string }
386
+ | { type: "tool_use"; id: string; name: string; input: unknown };
387
+ let message: Partial<AnthropicMessagesResponse> | null = null;
388
+ const content: ContentBlock[] = [];
389
+ let currentBlock: ContentBlock | null = null;
390
+ let currentToolJson = "";
391
+ let sawMessageStop = false;
392
+ let sawError = false;
393
+
394
+ for (const block of blocks) {
395
+ const lines = block.split("\n");
396
+ let eventType: string | undefined;
397
+ let data: string | undefined;
398
+ for (const line of lines) {
399
+ if (line.startsWith("event:")) eventType = line.slice(6).trim();
400
+ else if (line.startsWith("data:")) data = line.slice(5).trim();
401
+ }
402
+ if (!data) continue;
403
+ let parsed: Record<string, unknown>;
404
+ try {
405
+ parsed = JSON.parse(data) as Record<string, unknown>;
406
+ } catch {
407
+ continue;
408
+ }
409
+
410
+ const type = (eventType ?? parsed.type) as string;
411
+ switch (type) {
412
+ case "message_start": {
413
+ const msg = parsed.message as Partial<AnthropicMessagesResponse> | undefined;
414
+ message = { ...(msg ?? {}) };
415
+ break;
416
+ }
417
+ case "content_block_start": {
418
+ const cb = parsed.content_block as Partial<ContentBlock> | undefined;
419
+ if (!cb || !cb.type) break;
420
+ if (cb.type === "text") currentBlock = { type: "text", text: "" };
421
+ else if (cb.type === "thinking") currentBlock = { type: "thinking", thinking: "" };
422
+ else if (cb.type === "tool_use" && typeof cb.id === "string" && typeof cb.name === "string") {
423
+ currentBlock = { type: "tool_use", id: cb.id, name: cb.name, input: {} };
424
+ currentToolJson = "";
425
+ }
426
+ break;
427
+ }
428
+ case "content_block_delta": {
429
+ const delta = parsed.delta as Record<string, unknown> | undefined;
430
+ if (!currentBlock || !delta) break;
431
+ if (delta.type === "text_delta" && currentBlock.type === "text" && typeof delta.text === "string") {
432
+ currentBlock.text += delta.text;
433
+ } else if (delta.type === "thinking_delta" && currentBlock.type === "thinking" && typeof delta.thinking === "string") {
434
+ currentBlock.thinking += delta.thinking;
435
+ } else if (delta.type === "signature_delta" && currentBlock.type === "thinking" && typeof delta.signature === "string") {
436
+ currentBlock.signature = (currentBlock.signature ?? "") + delta.signature;
437
+ } else if (delta.type === "input_json_delta" && currentBlock.type === "tool_use" && typeof delta.partial_json === "string") {
438
+ currentToolJson += delta.partial_json;
439
+ }
440
+ break;
441
+ }
442
+ case "content_block_stop": {
443
+ if (currentBlock) {
444
+ if (currentBlock.type === "tool_use") {
445
+ try {
446
+ currentBlock.input = JSON.parse(currentToolJson || "{}");
447
+ } catch {
448
+ currentBlock.input = {};
449
+ }
450
+ currentToolJson = "";
451
+ }
452
+ content.push(currentBlock);
453
+ currentBlock = null;
454
+ }
455
+ break;
456
+ }
457
+ case "message_delta": {
458
+ const delta = parsed.delta as Partial<AnthropicMessagesResponse> | undefined;
459
+ const usage = parsed.usage as Record<string, number> | undefined;
460
+ if (delta && message) Object.assign(message, delta);
461
+ if (usage && message) message.usage = { ...(message.usage ?? { input_tokens: 0, output_tokens: 0 }), ...usage } as AnthropicMessagesResponse["usage"];
462
+ break;
463
+ }
464
+ case "message_stop":
465
+ sawMessageStop = true;
466
+ break;
467
+ case "error":
468
+ sawError = true;
469
+ break;
470
+ default:
471
+ // ignore ping / unknown
472
+ break;
473
+ }
474
+ }
475
+
476
+ if (sawError || !sawMessageStop || !message) return null;
477
+ message.content = content as AnthropicMessagesResponse["content"];
478
+ if (!message.stop_reason) message.stop_reason = "end_turn";
479
+ if (!message.role) message.role = "assistant";
480
+ if (!message.usage) message.usage = { input_tokens: 0, output_tokens: 0 };
481
+ return message as AnthropicMessagesResponse;
482
+ }
src/async/keepalive.ts ADDED
@@ -0,0 +1,88 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * SSE keepalive stream generator.
3
+ *
4
+ * Emits pure SSE comment frames (`: keepalive\n\n`) at a fixed interval.
5
+ * Used by the async bridge to keep the client connection alive during
6
+ * ticket-queue wait — comment frames are universally ignored by spec-compliant
7
+ * SSE clients (OpenAI / Anthropic SDKs) but reset their idle-timeout timers.
8
+ *
9
+ * Never emits `data:` frames — those carry semantic events and would confuse
10
+ * strict SDK parsers (e.g. `@ai-sdk/anthropic` zod schemas throw on unknown
11
+ * `type` values, killing the stream — see plan §3.6 anti-pattern #1).
12
+ */
13
+
14
+ export interface KeepaliveOptions {
15
+ /** Interval between comment frames in ms. */
16
+ intervalMs: number;
17
+ /** Comment text. Default `"keepalive"`. Must not contain newlines. */
18
+ text?: string;
19
+ /** External abort — when fired, the stream closes gracefully. */
20
+ signal?: AbortSignal;
21
+ }
22
+
23
+ /**
24
+ * Build a `ReadableStream<Uint8Array>` that emits `: ${text}\n\n` every
25
+ * `intervalMs`. The stream closes when `signal` aborts. Text encoder is
26
+ * reused across frames; the underlying buffer is fresh per emit.
27
+ *
28
+ * Cadence guarantee: first emit happens after `intervalMs` (NOT immediately)
29
+ * so callers can compose with upstream-output streams without a leading comment.
30
+ */
31
+ export function keepaliveStream(opts: KeepaliveOptions): ReadableStream<Uint8Array> {
32
+ const text = (opts.text ?? "keepalive").replace(/[\r\n]/g, " ");
33
+ const frame = new TextEncoder().encode(`: ${text}\n\n`);
34
+ let timer: ReturnType<typeof setTimeout> | undefined;
35
+ let aborted = false;
36
+
37
+ return new ReadableStream<Uint8Array>({
38
+ start(controller) {
39
+ if (opts.signal) {
40
+ if (opts.signal.aborted) {
41
+ aborted = true;
42
+ controller.close();
43
+ return;
44
+ }
45
+ opts.signal.addEventListener("abort", () => {
46
+ aborted = true;
47
+ if (timer) {
48
+ clearTimeout(timer);
49
+ timer = undefined;
50
+ }
51
+ try { controller.close(); } catch { /* already closed */ }
52
+ }, { once: true });
53
+ }
54
+
55
+ const tick = (): void => {
56
+ if (aborted) return;
57
+ try {
58
+ controller.enqueue(frame);
59
+ } catch {
60
+ // Controller closed by consumer; stop the timer.
61
+ if (timer) {
62
+ clearTimeout(timer);
63
+ timer = undefined;
64
+ }
65
+ return;
66
+ }
67
+ timer = setTimeout(tick, opts.intervalMs);
68
+ };
69
+ timer = setTimeout(tick, opts.intervalMs);
70
+ },
71
+ cancel() {
72
+ aborted = true;
73
+ if (timer) {
74
+ clearTimeout(timer);
75
+ timer = undefined;
76
+ }
77
+ },
78
+ });
79
+ }
80
+
81
+ /**
82
+ * Emit a single immediate keepalive frame as a `Uint8Array`.
83
+ * Useful for flushing one frame before pausing on a long upstream call.
84
+ */
85
+ export function keepaliveFrame(text: string = "keepalive"): Uint8Array {
86
+ const clean = text.replace(/[\r\n]/g, " ");
87
+ return new TextEncoder().encode(`: ${clean}\n\n`);
88
+ }
src/async/openai-stream-adapter.ts ADDED
@@ -0,0 +1,135 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * OpenAI SSE stream adapter for the async path.
3
+ *
4
+ * Single persistent state machine for the whole stream — preserves message ID,
5
+ * usage, tool-call index mapping, and finish state across events. Re-using the
6
+ * same translation state is what the existing `anthropicSseToOpenaiSse` does;
7
+ * we add two extra concerns for the async bridge:
8
+ *
9
+ * 1. Preserve `: keepalive` comments (the existing translator drops them).
10
+ * Comments are the only queue-wait liveness signal; dropping them defeats
11
+ * the bridge design.
12
+ * 2. Convert Anthropic `event: error` events to OpenAI
13
+ * `data: {"error":...}` + terminal `[DONE]`. The existing translator
14
+ * silently drops Anthropic errors, which would mask permanent bridge
15
+ * failures as a clean `[DONE]`.
16
+ *
17
+ * Anti-pattern: NEVER create a fresh translator per event. State (messageId,
18
+ * toolCallIndex, finishReasonSent, usage) must persist across the whole stream
19
+ * or downstream clients see inconsistent IDs, missing tool arguments, and
20
+ * duplicate finish reasons.
21
+ */
22
+ import { initState, parseSSEChunk, translateEvent, SSE_FRAME_SPLIT, type TranslationState, type ParsedSSE } from "../translator/sse-translator.js";
23
+
24
+ export function anthropicSseToOpenaiSseWithKeepalive(
25
+ upstream: ReadableStream<Uint8Array>,
26
+ model: string = "glm-4.6",
27
+ ): ReadableStream<Uint8Array> {
28
+ const encoder = new TextEncoder();
29
+ const decoder = new TextDecoder();
30
+ const state: TranslationState = initState(model);
31
+ let doneSent = false;
32
+ let errored = false;
33
+
34
+ function emit(out: string): void {
35
+ if (errored) return;
36
+ try {
37
+ controller0.enqueue(encoder.encode(out));
38
+ } catch {
39
+ // controller closed by consumer
40
+ }
41
+ }
42
+
43
+ // Hoisted controller reference so `emit()` can be defined above the ReadableStream
44
+ // constructor without forward-let noise.
45
+ let controller0: ReadableStreamDefaultController<Uint8Array>;
46
+
47
+ return new ReadableStream<Uint8Array>({
48
+ start(controller) {
49
+ controller0 = controller;
50
+ const reader = upstream.getReader();
51
+ let buffer = "";
52
+
53
+ reader.read().then(function pump({ done, value }): Promise<unknown> | undefined {
54
+ if (done) {
55
+ // Flush trailing buffer
56
+ if (buffer.trim()) processBlock(buffer, state);
57
+ buffer = "";
58
+ emitDone();
59
+ try { controller.close(); } catch {}
60
+ return;
61
+ }
62
+ buffer += decoder.decode(value, { stream: true });
63
+ const blocks = buffer.split(SSE_FRAME_SPLIT);
64
+ buffer = blocks.pop() ?? "";
65
+ for (const block of blocks) {
66
+ processBlock(block, state);
67
+ if (errored) {
68
+ try { controller.close(); } catch {}
69
+ return;
70
+ }
71
+ }
72
+ return reader.read().then(pump);
73
+ }).catch((err) => {
74
+ if (!errored) {
75
+ const errPayload = JSON.stringify({ error: { message: `async stream error: ${(err as Error).message}`, type: "server_error" } });
76
+ emit(`data: ${errPayload}\n\n`);
77
+ emitDone();
78
+ }
79
+ try { controller.close(); } catch {}
80
+ }).finally(() => {
81
+ reader.releaseLock?.();
82
+ });
83
+ },
84
+ });
85
+
86
+ function processBlock(block: string, st: TranslationState): void {
87
+ const trimmed = block.trim();
88
+ if (trimmed === "") return;
89
+
90
+ // Pure comment frame — pass through unchanged
91
+ if (trimmed.startsWith(":")) {
92
+ emit(block + "\n\n");
93
+ return;
94
+ }
95
+
96
+ // Detect Anthropic error event before parseSSEChunk would silently drop it
97
+ // (parseSSEChunk only returns events with data; error events have data too,
98
+ // but the existing translateEvent doesn't handle `type:"error"`).
99
+ if (trimmed.startsWith("event: error") || trimmed.startsWith("event:error")) {
100
+ const dataLine = block.split("\n").find((l) => l.startsWith("data:"));
101
+ let anthropicMsg = "unknown error";
102
+ let anthropicType = "api_error";
103
+ if (dataLine) {
104
+ try {
105
+ const data = JSON.parse(dataLine.slice(5).trim());
106
+ if (data?.error?.message) anthropicMsg = String(data.error.message);
107
+ if (data?.error?.type) anthropicType = String(data.error.type);
108
+ } catch {
109
+ // leave defaults
110
+ }
111
+ }
112
+ const oaiPayload = JSON.stringify({ error: { message: anthropicMsg, type: anthropicType } });
113
+ emit(`data: ${oaiPayload}\n\n`);
114
+ emitDone();
115
+ errored = true;
116
+ return;
117
+ }
118
+
119
+ // Standard Anthropic event — parse + translate using shared state.
120
+ const parsed = parseSSEChunk(block);
121
+ for (const p of parsed) {
122
+ const out = translateEvent(st, p);
123
+ if (out) emit(out);
124
+ }
125
+ }
126
+
127
+ function emitDone(): void {
128
+ if (doneSent) return;
129
+ doneSent = true;
130
+ emit("data: [DONE]\n\n");
131
+ }
132
+ }
133
+
134
+ // Re-export for tests
135
+ export type { ParsedSSE, TranslationState };
src/async/types.ts ADDED
@@ -0,0 +1,101 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Async (off-peak) types: ticket states, server response shapes, error classes.
3
+ *
4
+ * Server-side response fields are snake_case (e.g. `ticket_id`, `next_poll_after`).
5
+ * The client converts them to camelCase on the way out; callers never see the
6
+ * raw server shape.
7
+ *
8
+ * @see _reverse/NOTEPAD.md "Off-Peak / Idle Plan" section for upstream protocol.
9
+ */
10
+
11
+ /** Ticket lifecycle states reported by the server. */
12
+ export type TicketState = "queued" | "ready" | "active" | "settled" | "expired" | "not_found";
13
+
14
+ /** Non-terminal states — ticket may still become `ready`. */
15
+ export const TICKET_PENDING_STATES: readonly TicketState[] = ["queued"] as const;
16
+ /** Terminal states — no further transitions; ticket can be settled. */
17
+ export const TICKET_TERMINAL_STATES: readonly TicketState[] = ["settled", "expired", "not_found"] as const;
18
+
19
+ export function isTicketReady(s: TicketState): boolean {
20
+ return s === "ready" || s === "active";
21
+ }
22
+
23
+ export function isTicketExpired(s: TicketState): boolean {
24
+ return s === "expired" || s === "not_found";
25
+ }
26
+
27
+ /** Result of `GET /ticket/availability`. */
28
+ export interface AvailabilityResult {
29
+ canTakeNumber: boolean;
30
+ /** Unix seconds — earliest time the user can retry taking a number. Present when `canTakeNumber === false`. */
31
+ nextTakeAt?: number;
32
+ }
33
+
34
+ /** Result of `POST /ticket` (take a number). */
35
+ export interface TakeTicketResult {
36
+ ticketId: string;
37
+ state: TicketState;
38
+ /** Queue position (1-indexed). Present while `state === "queued"`. */
39
+ position?: number;
40
+ /** Server-suggested next poll delay in ms. Present when server has a backoff recommendation. */
41
+ nextPollAfterMs?: number;
42
+ /** Local timestamp (ms) when the ticket was registered. */
43
+ registeredAt: number;
44
+ }
45
+
46
+ /** Status of a single ticket from `POST /ticket/status`. */
47
+ export interface TicketStatusResult {
48
+ ticketId: string;
49
+ state: TicketState;
50
+ position?: number;
51
+ /** Unix seconds — deadline by which the client must use a `ready` ticket. Present on `ready`. */
52
+ activeDeadline?: number;
53
+ }
54
+
55
+ /** Result of `POST /ticket/status` (batch poll). */
56
+ export interface BatchStatusResult {
57
+ /** Server-suggested next poll delay in ms (applies to all returned tickets). */
58
+ nextPollAfterMs?: number;
59
+ tickets: TicketStatusResult[];
60
+ }
61
+
62
+ /** Credentials needed to authenticate with the off-peak backend. */
63
+ export interface OffPeakCredentials {
64
+ /** ZCode plan JWT — goes in `Authorization: Bearer ${jwt}`. Source: `Credential.jwt`. */
65
+ jwt: string;
66
+ /** Coding-plan API key — goes in `X-Coding-Plan-Api-Key`. Source: `Credential.apiKey`. */
67
+ codingPlanApiKey: string;
68
+ /** Optional Bigmodel-team org/project headers. */
69
+ bigmodelOrganization?: string;
70
+ bigmodelProject?: string;
71
+ }
72
+
73
+ /** HTTP-status-bearing error from the off-peak server. */
74
+ export class OffPeakServerError extends Error {
75
+ readonly httpStatus: number;
76
+ readonly bizCode?: string;
77
+ constructor(message: string, httpStatus: number, bizCode?: string) {
78
+ super(message);
79
+ this.name = "OffPeakServerError";
80
+ this.httpStatus = httpStatus;
81
+ this.bizCode = bizCode;
82
+ }
83
+ }
84
+
85
+ /** Thrown when credentials lack the JWT required for off-peak auth. */
86
+ export class OffPeakCredentialsUnavailableError extends Error {
87
+ constructor(message: string = "off-peak requires a logged-in oauth credential (jwt missing)") {
88
+ super(message);
89
+ this.name = "OffPeakCredentialsUnavailableError";
90
+ }
91
+ }
92
+
93
+ /** Detects the upstream "off-peak-ticket-expired" error signal in any error message. */
94
+ export function isOffPeakTicketExpiredError(e: unknown): boolean {
95
+ if (e == null) return false;
96
+ if (typeof e === "string") return e.includes("off-peak-ticket-expired");
97
+ if (e instanceof Error) {
98
+ return e.message.includes("off-peak-ticket-expired") || e.name === "OffPeakTicketExpiredError";
99
+ }
100
+ return false;
101
+ }
src/auth/jwt-age.ts ADDED
@@ -0,0 +1,39 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * JWT age inspection for the stored start-plan token.
3
+ *
4
+ * Informational only: the token payload carries `iat` but no `exp`, and the
5
+ * billing gateway does NOT reject by age — an 8-day-old JWT still serves
6
+ * `billing/balance` (verified live). Re-login is only needed when the gateway
7
+ * actually returns 401 / 3012. The age is surfaced so operators can see how
8
+ * fresh the credential is.
9
+ */
10
+ export interface JwtInfo {
11
+ /** Unix seconds when the token was issued. */
12
+ iat: number;
13
+ /** Token age in hours at the time of inspection. */
14
+ ageHours: number;
15
+ userId?: string;
16
+ }
17
+
18
+ /** Decode a zcode-plan JWT payload without verifying the signature. */
19
+ export function inspectJwt(jwt: string): JwtInfo | null {
20
+ const parts = jwt.split(".");
21
+ if (parts.length !== 3) return null;
22
+ try {
23
+ const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
24
+ const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4));
25
+ const payload = JSON.parse(Buffer.from(b64 + pad, "base64").toString("utf8")) as {
26
+ iat?: number;
27
+ user_id?: string;
28
+ sub?: string;
29
+ };
30
+ if (typeof payload.iat !== "number") return null;
31
+ return {
32
+ iat: payload.iat,
33
+ ageHours: Math.max(0, (Date.now() / 1000 - payload.iat) / 3600),
34
+ ...(payload.user_id ? { userId: payload.user_id } : {}),
35
+ };
36
+ } catch {
37
+ return null;
38
+ }
39
+ }
src/auth/manager.ts ADDED
@@ -0,0 +1,39 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Auth manager — resolves the upstream credential from the OAuth login flow.
3
+ * @see .omo/plans/zcode-proxy.md Task 4
4
+ */
5
+ import type { Credential } from "./types.js";
6
+
7
+ /**
8
+ * Resolves the upstream credential to inject into proxied requests.
9
+ *
10
+ * The credential comes from `auth login` and is injected via
11
+ * {@link setOAuthCredential} at startup (and re-loaded on Android's
12
+ * `startProxy` so a fresh login after restart is picked up).
13
+ */
14
+ export class AuthManager {
15
+ private oauthCred: Credential | null = null;
16
+
17
+ /**
18
+ * Returns the current credential or throws when none is stored.
19
+ *
20
+ * There is no proactive refresh: the login flows never populate
21
+ * `expiresAt`, so expiry surfaces as an upstream 401, not here. The guard
22
+ * below is retained for the day a flow starts filling `expiresAt`.
23
+ */
24
+ async getCredential(): Promise<Credential> {
25
+ if (this.oauthCred) {
26
+ if (this.oauthCred.expiresAt && Date.now() >= this.oauthCred.expiresAt) {
27
+ this.oauthCred = null;
28
+ throw new Error("OAuth credential expired; re-authentication required — run: zcode-proxy auth login");
29
+ }
30
+ return this.oauthCred;
31
+ }
32
+ throw new Error("OAuth credential not available — run: zcode-proxy auth login");
33
+ }
34
+
35
+ /** Set the OAuth credential (used by the `auth login` flow). */
36
+ setOAuthCredential(cred: Credential): void {
37
+ this.oauthCred = cred;
38
+ }
39
+ }
src/auth/oauth.ts ADDED
@@ -0,0 +1,575 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * OAuth flow handlers for Z.AI and Bigmodel.
3
+ *
4
+ * The two providers use **different flows** (verified against the ZCode 3.10
5
+ * desktop bundle `loginZCodeCli` / `loginBigmodelCodingPlan`, and live-probed
6
+ * 2026-08-29):
7
+ *
8
+ * - Z.AI: **server-mediated CLI login**. The client POSTs `{provider:"zai"}` to
9
+ * `zcode.z.ai/api/v1/oauth/cli/init` and gets back a server-generated
10
+ * authorize URL whose redirect_uri is zcode.z.ai's OWN callback
11
+ * (`/api/v1/oauth/cli/callback/zai`) — NOT localhost. After the user
12
+ * authorizes in the browser, the client polls `/oauth/cli/poll/{flow_id}`
13
+ * until the server reports `ready` with the tokens. No local callback server
14
+ * exists for Z.AI. Building the old 3.1.x-style direct chat.z.ai authorize
15
+ * URL with a localhost redirect_uri is rejected upstream with
16
+ * `{"detail":"Redirect URI not registered for this client"}`.
17
+ * - Bigmodel: **classic auth-code flow** — local callback server on 127.0.0.1,
18
+ * authorize at `bigmodel.cn/login?appId&redirect&state`, then exchange the
19
+ * returned code at the shared zcode.z.ai token endpoint.
20
+ *
21
+ * @see _reverse/NOTEPAD.md "Method 1: OAuth Flow"
22
+ */
23
+ import type { ProviderId } from "../provider/types.js";
24
+ import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
25
+ import { randomBytes } from "node:crypto";
26
+
27
+ // ---------------------------------------------------------------------------
28
+ // Constants (from bundle)
29
+ // ---------------------------------------------------------------------------
30
+
31
+ /** zcode.z.ai API base (bundle `A3o`; cli-login + token endpoints hang off it). */
32
+ const ZCODE_API_BASE = "https://zcode.z.ai/api/v1";
33
+ /** Shared token-exchange endpoint (bigmodel auth-code flow). Bundle: `tokenUrl`. */
34
+ const ZCODE_TOKEN_ENDPOINT = `${ZCODE_API_BASE}/oauth/token`;
35
+ /** Default Bigmodel authorize host (bundle `BIGMODEL_OAUTH_AUTHORIZE_URL`). */
36
+ const BIGMODEL_HOST = "https://bigmodel.cn";
37
+ /** Default Bigmodel app id (bundle `BIGMODEL_OAUTH_APP_ID`). */
38
+ const BIGMODEL_APP_ID = "zcode";
39
+
40
+ /** Overall login timeout shared by both flows (bundle `tln`). */
41
+ export const LOGIN_TIMEOUT_MS = 300_000;
42
+
43
+ // ---------------------------------------------------------------------------
44
+ // Shared types
45
+ // ---------------------------------------------------------------------------
46
+
47
+ export interface OAuthResult {
48
+ accessToken: string;
49
+ provider: ProviderId;
50
+ /** Upstream user identifier, when the OAuth response included one. Passed through to `metadata.user_id` on Anthropic-format requests. */
51
+ userId?: string;
52
+ /** ZCode plan JWT for start-plan (zcode.z.ai). The token-exchange response includes this alongside the provider access_token. */
53
+ jwt?: string;
54
+ }
55
+
56
+ export type FetchFn = typeof fetch;
57
+
58
+ /** Flow handle returned by `start()`. */
59
+ export interface OAuthFlowStart {
60
+ authorizeUrl: string;
61
+ /** Local callback URL when the flow uses one (bigmodel); `""` otherwise (zai cli flow). */
62
+ callbackUrl: string;
63
+ /** CSRF state (auth-code) / server flow_id (zai cli flow) — opaque bookkeeping. */
64
+ state: string;
65
+ }
66
+
67
+ /** Credentials produced by a completed flow, pre-`KeyResolver`. */
68
+ export interface OAuthFlowTokens {
69
+ accessToken: string;
70
+ userId?: string;
71
+ jwt?: string;
72
+ }
73
+
74
+ /** Shape of the zcode.z.ai `{code, data, msg}` envelope (token + cli-login endpoints). */
75
+ interface ZcodeEnvelope {
76
+ code?: number;
77
+ data?: unknown;
78
+ msg?: string;
79
+ }
80
+
81
+ // ---------------------------------------------------------------------------
82
+ // Shared flow base
83
+ // ---------------------------------------------------------------------------
84
+
85
+ /**
86
+ * Common lifecycle for both login flows: `start()` produces the authorize URL,
87
+ * `complete()` blocks until the flow finishes (callback redirect or server
88
+ * poll), `authorize()` chains them for the CLI. `src/android/control.ts`
89
+ * drives `start()` + `complete()` so the authorize URL can be surfaced to the
90
+ * app while completion continues in the background.
91
+ */
92
+ export abstract class OAuthFlowClient {
93
+ constructor(
94
+ readonly provider: ProviderId,
95
+ protected readonly fetchImpl: FetchFn,
96
+ ) {}
97
+
98
+ abstract start(): Promise<OAuthFlowStart>;
99
+ abstract complete(started: OAuthFlowStart, timeoutMs?: number): Promise<OAuthFlowTokens>;
100
+ abstract close(): Promise<void>;
101
+
102
+ /** Run the full flow end-to-end: surface authorize URL, wait, close. */
103
+ async authorize(
104
+ onAuthorizeUrl?: (url: string) => void,
105
+ timeoutMs: number = LOGIN_TIMEOUT_MS,
106
+ ): Promise<OAuthResult> {
107
+ const started = await this.start();
108
+ onAuthorizeUrl?.(started.authorizeUrl);
109
+ try {
110
+ const tokens = await this.complete(started, timeoutMs);
111
+ return { accessToken: tokens.accessToken, provider: this.provider, userId: tokens.userId, jwt: tokens.jwt };
112
+ } finally {
113
+ await this.close();
114
+ }
115
+ }
116
+ }
117
+
118
+ /**
119
+ * POST/GET a zcode.z.ai endpoint and unwrap the `{code, data, msg}` envelope
120
+ * (mirrors the bundle's `H2r`: numeric code required, non-2xx or `code !== 0`
121
+ * surfaces the server `msg`).
122
+ */
123
+ async function requestZcodeEnvelope(
124
+ fetchImpl: FetchFn,
125
+ url: string,
126
+ init: RequestInit,
127
+ label: string,
128
+ ): Promise<unknown> {
129
+ const resp = await fetchImpl(url, init);
130
+ const raw = safeJsonParse(await resp.text()) as ZcodeEnvelope | null;
131
+ if (!raw || typeof raw.code !== "number") {
132
+ throw new Error(`${label}: invalid response envelope (status=${resp.status})`);
133
+ }
134
+ if (!resp.ok || raw.code !== 0) {
135
+ throw new Error(`${label} failed: status=${resp.status} msg=${raw.msg ?? "(none)"}`);
136
+ }
137
+ return raw.data;
138
+ }
139
+
140
+ // ---------------------------------------------------------------------------
141
+ // Z.AI — server-mediated CLI login (init + poll, no local callback)
142
+ // ---------------------------------------------------------------------------
143
+
144
+ /** `data` of a successful `/oauth/cli/init` call (bundle `D3o`). */
145
+ interface ZaiCliInitData {
146
+ flow_id: string;
147
+ /** Server-issued poll token; informational — poll re-sends the client Bearer. */
148
+ poll_token: string;
149
+ authorize_url: string;
150
+ /** Unix seconds. */
151
+ expires_at: number;
152
+ poll_interval_sec: number;
153
+ }
154
+
155
+ /** `data` of a `/oauth/cli/poll/{flow_id}` call: pending/failed, or ready (bundle `N3o`/`L3o`). */
156
+ interface ZaiCliPollData {
157
+ status: string;
158
+ token?: string;
159
+ user?: { user_id?: unknown };
160
+ zai?: { access_token?: unknown };
161
+ }
162
+
163
+ /**
164
+ * Z.AI login client, mirroring ZCode 3.10 `loginZCodeCli`:
165
+ *
166
+ * 1. Generate a client poll token (32 random bytes, hex) — sent as
167
+ * `Authorization: Bearer` on BOTH init and poll.
168
+ * 2. `POST {ZCODE_API_BASE}/oauth/cli/init` body `{provider:"zai"}` →
169
+ * `{flow_id, poll_token, authorize_url, expires_at, poll_interval_sec}`.
170
+ * 3. Open the server-provided `authorize_url` (its redirect_uri is
171
+ * zcode.z.ai's own `/oauth/cli/callback/zai` — the browser never comes
172
+ * back to localhost).
173
+ * 4. `GET {ZCODE_API_BASE}/oauth/cli/poll/{flow_id}` every
174
+ * `poll_interval_sec` until `status:"ready"` → `{token, user, zai}` —
175
+ * or `"failed"`, or the `expires_at`/timeout deadline passes.
176
+ */
177
+ export class ZaiOAuthClient extends OAuthFlowClient {
178
+ private flow: ZaiCliInitData | null = null;
179
+ private pollToken = "";
180
+
181
+ constructor(
182
+ fetchImpl: FetchFn = fetch,
183
+ /** Injectable pause between polls (tests pass a no-op). */
184
+ private readonly sleep: (ms: number) => Promise<void> = defaultSleep,
185
+ ) {
186
+ super("zai", fetchImpl);
187
+ }
188
+
189
+ start(): Promise<OAuthFlowStart> {
190
+ this.flow = null;
191
+ this.pollToken = randomBytes(32).toString("hex");
192
+ return (async () => {
193
+ const data = (await requestZcodeEnvelope(
194
+ this.fetchImpl,
195
+ `${ZCODE_API_BASE}/oauth/cli/init`,
196
+ {
197
+ method: "POST",
198
+ headers: { authorization: `Bearer ${this.pollToken}`, "content-type": "application/json" },
199
+ body: JSON.stringify({ provider: this.provider }),
200
+ },
201
+ "Z.AI login init",
202
+ )) as Partial<ZaiCliInitData> | null;
203
+ if (
204
+ !data ||
205
+ typeof data.flow_id !== "string" ||
206
+ typeof data.authorize_url !== "string" ||
207
+ typeof data.expires_at !== "number" ||
208
+ typeof data.poll_interval_sec !== "number"
209
+ ) {
210
+ throw new Error("Z.AI login init: invalid response data");
211
+ }
212
+ this.flow = data as ZaiCliInitData;
213
+ return { authorizeUrl: this.flow.authorize_url, callbackUrl: "", state: this.flow.flow_id };
214
+ })();
215
+ }
216
+
217
+ async complete(_started: OAuthFlowStart, timeoutMs: number = LOGIN_TIMEOUT_MS): Promise<OAuthFlowTokens> {
218
+ const flow = this.flow;
219
+ if (!flow) throw new Error("Z.AI login not started");
220
+ const deadlineMs = Math.min(Date.now() + timeoutMs, flow.expires_at * 1000);
221
+ const intervalMs = Math.max(1_000, flow.poll_interval_sec * 1000);
222
+
223
+ for (;;) {
224
+ if (Date.now() >= deadlineMs) {
225
+ throw new Error("Authorization timed out. Please retry login.");
226
+ }
227
+ const data = (await requestZcodeEnvelope(
228
+ this.fetchImpl,
229
+ `${ZCODE_API_BASE}/oauth/cli/poll/${encodeURIComponent(flow.flow_id)}`,
230
+ { method: "GET", headers: { authorization: `Bearer ${this.pollToken}` } },
231
+ "Z.AI login poll",
232
+ )) as Partial<ZaiCliPollData> | null;
233
+
234
+ if (data?.status === "ready") {
235
+ const accessToken = typeof data.zai?.access_token === "string" ? data.zai.access_token.trim() : "";
236
+ if (!accessToken) {
237
+ throw new Error("Z.AI login poll: response missing data.zai.access_token");
238
+ }
239
+ return {
240
+ accessToken,
241
+ jwt: typeof data.token === "string" ? data.token.trim() : undefined,
242
+ userId: typeof data.user?.user_id === "string" ? data.user.user_id : undefined,
243
+ };
244
+ }
245
+ if (data?.status === "failed") {
246
+ throw new Error("Authorization failed. Please retry login.");
247
+ }
248
+ if (data?.status !== "pending") {
249
+ throw new Error(`Z.AI login poll: unexpected status ${String(data?.status ?? "(none)")}`);
250
+ }
251
+ await this.sleep(Math.min(intervalMs, Math.max(0, deadlineMs - Date.now())));
252
+ }
253
+ }
254
+
255
+ async close(): Promise<void> {
256
+ this.flow = null;
257
+ }
258
+ }
259
+
260
+ // ---------------------------------------------------------------------------
261
+ // Bigmodel — classic auth-code flow with a localhost callback server
262
+ // ---------------------------------------------------------------------------
263
+
264
+ /**
265
+ * Per-provider auth-code configuration (Bigmodel only since Z.AI moved to the
266
+ * cli login flow).
267
+ */
268
+ interface AuthCodeConfig {
269
+ readonly provider: ProviderId;
270
+ /** Base authorize URL (`?appId=&redirect=&state=` appended). */
271
+ readonly authorizeUrl: string;
272
+ readonly appId: string;
273
+ /** Shared zcode.z.ai token-exchange endpoint. */
274
+ readonly tokenUrl: string;
275
+ /** Path served by the localhost callback server. */
276
+ readonly callbackPath: string;
277
+ /** Key under `data` holding the provider access token: `data[field].access_token`. */
278
+ readonly accessTokenField: string;
279
+ }
280
+
281
+ /** Shape of the zcode.z.ai token-exchange response (`{code, data, msg}`). */
282
+ interface TokenExchangeResponse {
283
+ code?: number;
284
+ data?: {
285
+ token?: string;
286
+ user?: { user_id?: string };
287
+ } & Record<string, unknown>;
288
+ msg?: string;
289
+ }
290
+
291
+ /**
292
+ * Auth-code OAuth client: localhost callback server + token exchange.
293
+ *
294
+ * Flow (mirrors the ZCode desktop `loginBigmodelCodingPlan`):
295
+ * 1. Start localhost HTTP server on a random port
296
+ * 2. Build authorize URL: `{authorizeUrl}?appId={appId}&redirect={localhost}&state={state}`
297
+ * 3. User opens the URL, authorizes on the provider's site
298
+ * 4. Provider redirects to localhost callback with `?authCode=...&state=...`
299
+ * 5. POST `{tokenUrl}` body `{provider, code, redirect_uri, state}`
300
+ * 6. zcode.z.ai exchanges (holding the app secret server-side) and returns
301
+ * `{code:0, data:{token:<jwt>, <provider>:{access_token}, user:{user_id}}}`
302
+ */
303
+ export class AuthCodeOAuthClient extends OAuthFlowClient {
304
+ private server: Server | null = null;
305
+ private callbackResult: { code: string; error: string | null } | null = null;
306
+ private callbackWaiters: Array<(result: { code: string; error: string | null }) => void> = [];
307
+
308
+ constructor(
309
+ config: AuthCodeConfig,
310
+ fetchImpl: FetchFn = fetch,
311
+ ) {
312
+ super(config.provider, fetchImpl);
313
+ this.config = config;
314
+ }
315
+
316
+ private readonly config: AuthCodeConfig;
317
+
318
+ /** Build the provider authorize URL with the localhost redirect + state. */
319
+ protected buildAuthorizeUrl(callbackUrl: string, state: string): string {
320
+ const params = new URLSearchParams({
321
+ appId: this.config.appId,
322
+ redirect: callbackUrl,
323
+ state,
324
+ });
325
+ return `${this.config.authorizeUrl}?${params.toString()}`;
326
+ }
327
+
328
+ /**
329
+ * Start the localhost callback server and return the authorize URL.
330
+ * Call `waitForCallback()` (or `authorize()`) afterwards, then `close()`.
331
+ *
332
+ * The bind port is `0` (OS-assigned random) unless the env var
333
+ * `ZCODE_OAUTH_CALLBACK_PORT` is set, in which case that exact port is used.
334
+ * The Android entry sets the env var so the Custom Tabs redirect URL is
335
+ * predictable across launches.
336
+ */
337
+ start(): Promise<OAuthFlowStart> {
338
+ const state = randomBytes(32).toString("hex");
339
+ const requestedPort = Number(process.env.ZCODE_OAUTH_CALLBACK_PORT ?? 0) || 0;
340
+
341
+ return new Promise((resolve, reject) => {
342
+ this.server = createServer((req: IncomingMessage, res: ServerResponse) => {
343
+ this.handleCallback(req, res, state);
344
+ });
345
+
346
+ this.server.on("error", (err) => {
347
+ this.server = null;
348
+ reject(err);
349
+ });
350
+ this.server.listen(requestedPort, "127.0.0.1", () => {
351
+ const addr = this.server!.address();
352
+ if (!addr || typeof addr !== "object") {
353
+ reject(new Error("Failed to bind localhost callback server"));
354
+ return;
355
+ }
356
+ const callbackUrl = `http://127.0.0.1:${addr.port}${this.config.callbackPath}`;
357
+ const authorizeUrl = this.buildAuthorizeUrl(callbackUrl, state);
358
+ resolve({ authorizeUrl, callbackUrl, state });
359
+ });
360
+ });
361
+ }
362
+
363
+ private handleCallback(req: IncomingMessage, res: ServerResponse, expectedState: string): void {
364
+ const url = new URL(req.url ?? "/", "http://127.0.0.1");
365
+ if (url.pathname !== this.config.callbackPath) {
366
+ res.writeHead(404, { "Content-Type": "text/plain" });
367
+ res.end("Not found");
368
+ return;
369
+ }
370
+
371
+ const state = url.searchParams.get("state") ?? "";
372
+ const code = url.searchParams.get("authCode") ?? url.searchParams.get("code") ?? "";
373
+
374
+ if (state !== expectedState || !code) {
375
+ res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
376
+ res.end("Authorization failed: state mismatch or missing code.");
377
+ if (!this.callbackResult) {
378
+ this.callbackResult = { code: "", error: "OAuth callback state mismatch or missing code." };
379
+ this.callbackWaiters.forEach((fn) => fn(this.callbackResult!));
380
+ }
381
+ return;
382
+ }
383
+
384
+ res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
385
+ res.end("Authorization successful! You may close this window and return to the CLI.");
386
+
387
+ if (!this.callbackResult) {
388
+ this.callbackResult = { code, error: null };
389
+ this.callbackWaiters.forEach((fn) => fn(this.callbackResult!));
390
+ }
391
+ }
392
+
393
+ /** Wait for the OAuth callback redirect. Resolves with the auth code. */
394
+ waitForCallback(timeoutMs: number = LOGIN_TIMEOUT_MS): Promise<string> {
395
+ if (this.callbackResult?.code) {
396
+ return Promise.resolve(this.callbackResult.code);
397
+ }
398
+ if (this.callbackResult?.error) {
399
+ return Promise.reject(new Error(this.callbackResult.error));
400
+ }
401
+
402
+ return new Promise<string>((resolve, reject) => {
403
+ const timer = setTimeout(() => {
404
+ reject(new Error("Authorization timed out. Please retry login."));
405
+ }, timeoutMs);
406
+
407
+ this.callbackWaiters.push((result) => {
408
+ clearTimeout(timer);
409
+ if (result.error) {
410
+ reject(new Error(result.error));
411
+ } else {
412
+ resolve(result.code);
413
+ }
414
+ });
415
+ });
416
+ }
417
+
418
+ /**
419
+ * Exchange the auth code at the shared zcode.z.ai token endpoint.
420
+ * The ZCode server holds the app secret and performs the real provider exchange.
421
+ * Returns `{ accessToken, userId, jwt }`.
422
+ */
423
+ async exchangeCode(
424
+ authCode: string,
425
+ redirectUri: string,
426
+ state: string,
427
+ ): Promise<OAuthFlowTokens> {
428
+ const resp = await this.fetchImpl(this.config.tokenUrl, {
429
+ method: "POST",
430
+ headers: { "content-type": "application/json" },
431
+ body: JSON.stringify({
432
+ provider: this.config.provider,
433
+ code: authCode,
434
+ redirect_uri: redirectUri,
435
+ state,
436
+ }),
437
+ });
438
+
439
+ const raw = safeJsonParse(await resp.text()) as TokenExchangeResponse | null;
440
+
441
+ if (!resp.ok || (raw && typeof raw.code === "number" && raw.code !== 0)) {
442
+ const label = this.config.provider;
443
+ throw new Error(
444
+ `${label} token exchange failed: status=${resp.status} msg=${raw?.msg ?? "(none)"}`,
445
+ );
446
+ }
447
+
448
+ const providerToken = raw?.data?.[this.config.accessTokenField] as
449
+ | { access_token?: string }
450
+ | undefined;
451
+ const accessToken = providerToken?.access_token?.trim() ?? "";
452
+
453
+ if (!accessToken) {
454
+ throw new Error(`${this.config.provider} token response missing data.${this.config.accessTokenField}.access_token`);
455
+ }
456
+
457
+ const userId = raw?.data?.user?.user_id;
458
+ const jwt = raw?.data?.token?.trim() ?? undefined;
459
+ return { accessToken, userId: typeof userId === "string" ? userId : undefined, jwt };
460
+ }
461
+
462
+ /** Wait for the browser callback, then exchange the code. */
463
+ async complete(started: OAuthFlowStart, timeoutMs: number = LOGIN_TIMEOUT_MS): Promise<OAuthFlowTokens> {
464
+ const code = await this.waitForCallback(timeoutMs);
465
+ return this.exchangeCode(code, started.callbackUrl, started.state);
466
+ }
467
+
468
+ async close(): Promise<void> {
469
+ if (this.server) {
470
+ const server = this.server;
471
+ this.server = null;
472
+ // Drop idle keep-alive connections so the port is released immediately
473
+ // (plain close() would wait for them to time out).
474
+ server.closeAllConnections?.();
475
+ await new Promise<void>((resolve) => {
476
+ server.close(() => resolve());
477
+ });
478
+ }
479
+ }
480
+ }
481
+
482
+ // ---------------------------------------------------------------------------
483
+ // Provider clients
484
+ // ---------------------------------------------------------------------------
485
+
486
+ /**
487
+ * Bigmodel auth-code config.
488
+ * Bundle `ed`: authorizeUrl `bigmodel.cn/login`, appId `zcode`,
489
+ * token field `data.bigmodel.access_token`.
490
+ */
491
+ const BIGMODEL_AUTH_CODE_CONFIG: AuthCodeConfig = {
492
+ provider: "bigmodel",
493
+ authorizeUrl: `${BIGMODEL_HOST}/login`,
494
+ appId: BIGMODEL_APP_ID,
495
+ tokenUrl: ZCODE_TOKEN_ENDPOINT,
496
+ callbackPath: "/oauth/callback/bigmodel",
497
+ accessTokenField: "bigmodel",
498
+ };
499
+
500
+ /**
501
+ * Bigmodel OAuth client (auth-code flow via bigmodel.cn + zcode.z.ai token
502
+ * exchange). `host`/`appId` are overridable to mirror the bundle's env vars
503
+ * (`BIGMODEL_OAUTH_AUTHORIZE_URL`, `BIGMODEL_OAUTH_APP_ID`).
504
+ */
505
+ export class BigmodelOAuthClient extends AuthCodeOAuthClient {
506
+ constructor(
507
+ fetchImpl: FetchFn = fetch,
508
+ host: string = BIGMODEL_HOST,
509
+ appId: string = BIGMODEL_APP_ID,
510
+ ) {
511
+ super(
512
+ { ...BIGMODEL_AUTH_CODE_CONFIG, authorizeUrl: `${host}/login`, appId },
513
+ fetchImpl,
514
+ );
515
+ }
516
+ }
517
+
518
+ // ---------------------------------------------------------------------------
519
+ // Headless paste login (auth-code flow)
520
+ // ---------------------------------------------------------------------------
521
+
522
+ /**
523
+ * Parse a callback URL the user pasted back into the terminal (headless
524
+ * `--paste` login, mirroring gcloud/gh CLI). Only the query string is
525
+ * inspected — the pathname/host are whatever the browser's address bar shows
526
+ * and are never validated. Tolerates copy artifacts from web pages: wrapping
527
+ * quotes/brackets, surrounding whitespace, and `&amp;` entities (a paste from
528
+ * a rendered page splits the query at the `&` inside `&amp;`, which breaks
529
+ * `state`). Returns the auth code (`authCode` or `code` param); throws on a
530
+ * CSRF `state` mismatch or a missing code.
531
+ */
532
+ export function parsePastedCallbackUrl(raw: string, expectedState: string): string {
533
+ let text = raw.trim().replace(/^["'`<([{]+/, "").replace(/["'`>\])}]+$/, "");
534
+ text = text.replace(/&amp;/gi, "&");
535
+
536
+ const q = text.indexOf("?");
537
+ const query = (q >= 0 ? text.slice(q + 1) : text).split("#")[0];
538
+ const params = new URLSearchParams(query);
539
+
540
+ const state = params.get("state") ?? "";
541
+ if (!state || state !== expectedState) {
542
+ throw new Error(
543
+ "OAuth state mismatch — the pasted URL does not belong to this login " +
544
+ "session (possible CSRF). Retry the login.",
545
+ );
546
+ }
547
+
548
+ const providerError = params.get("error");
549
+ const code = params.get("authCode") ?? params.get("code") ?? "";
550
+ if (!code) {
551
+ throw new Error(
552
+ providerError
553
+ ? `Authorization failed: provider returned error=${providerError}`
554
+ : "No authorization code in the pasted URL — paste the redirected " +
555
+ "127.0.0.1 callback URL (the one that failed to load), not the authorize URL.",
556
+ );
557
+ }
558
+ return code;
559
+ }
560
+
561
+ // ---------------------------------------------------------------------------
562
+ // Utility
563
+ // ---------------------------------------------------------------------------
564
+
565
+ function defaultSleep(ms: number): Promise<void> {
566
+ return new Promise((resolve) => setTimeout(resolve, ms));
567
+ }
568
+
569
+ function safeJsonParse(text: string): unknown {
570
+ try {
571
+ return JSON.parse(text);
572
+ } catch {
573
+ return null;
574
+ }
575
+ }
src/auth/resolver.ts ADDED
@@ -0,0 +1,170 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import type { Credential } from "./types.js";
2
+ import type { ProviderId } from "../provider/types.js";
3
+ import type { FetchFn } from "./oauth.js";
4
+
5
+ const ZAI_API_KEY_NAME = "zcode-api-key";
6
+ const DEFAULT_ORG_MARKER = "\u9ED8\u8BA4\u673A\u6784"; // 默认机构
7
+ const DEFAULT_PROJECT_MARKER = "\u9ED8\u8BA4\u9879\u76EE"; // 默认项目
8
+
9
+ async function requestBizApi(
10
+ fetchImpl: FetchFn,
11
+ url: string,
12
+ authorization: string,
13
+ init?: RequestInit,
14
+ ): Promise<any> {
15
+ const resp = await fetchImpl(url, {
16
+ ...init,
17
+ headers: {
18
+ Authorization: authorization,
19
+ "Content-Type": "application/json",
20
+ ...(init?.headers ?? {}),
21
+ },
22
+ });
23
+ if (!resp.ok) {
24
+ throw new Error(`Biz API ${url} failed: ${resp.status}`);
25
+ }
26
+ const body = await resp.json();
27
+ const code = body.code ?? body.status;
28
+ if (code != null && code !== 0 && code !== 200 && code !== "0" && code !== "200") {
29
+ throw new Error(body.msg ?? `Biz API error ${code}`);
30
+ }
31
+ return body.data ?? body;
32
+ }
33
+
34
+ export class KeyResolver {
35
+ constructor(private fetchImpl: FetchFn = fetch) {}
36
+
37
+ async resolveZaiBizToken(accessToken: string): Promise<string> {
38
+ const resp = await this.fetchImpl("https://api.z.ai/api/auth/z/login", {
39
+ method: "POST",
40
+ headers: { "content-type": "application/json" },
41
+ body: JSON.stringify({ token: accessToken }),
42
+ });
43
+ if (!resp.ok) {
44
+ throw new Error(`z/login failed: ${resp.status}`);
45
+ }
46
+ const data = await resp.json();
47
+ const token = data.access_token ?? data.accessToken ?? data.data?.access_token;
48
+ // Shape guard: silently returning undefined used to store a bogus
49
+ // credential that surfaced only as cryptic upstream 401s.
50
+ if (typeof token !== "string" || token.length === 0) {
51
+ throw new Error("z/login returned unexpected shape: access_token missing or empty");
52
+ }
53
+ return token;
54
+ }
55
+
56
+ async resolveCustomerInfo(
57
+ host: string,
58
+ authorization: string,
59
+ ): Promise<{ orgId: string; projectId: string }> {
60
+ const data = await requestBizApi(
61
+ this.fetchImpl,
62
+ `${host}/api/biz/customer/getCustomerInfo`,
63
+ authorization,
64
+ { method: "GET" },
65
+ );
66
+
67
+ const orgs: any[] = data.organizations ?? data.orgs ?? [];
68
+ if (!Array.isArray(orgs) || orgs.length === 0) {
69
+ throw new Error("No organizations found");
70
+ }
71
+ const org = orgs.find((o) =>
72
+ (o.organizationName ?? o.name ?? "").includes(DEFAULT_ORG_MARKER),
73
+ ) ?? orgs[0];
74
+ const orgId = org.organizationId ?? org.id ?? org.orgId;
75
+
76
+ const projects: any[] = org.projects ?? [];
77
+ if (!Array.isArray(projects) || projects.length === 0) {
78
+ throw new Error("No projects found in default organization");
79
+ }
80
+ const project = projects.find((p) =>
81
+ (p.projectName ?? p.name ?? "").includes(DEFAULT_PROJECT_MARKER),
82
+ ) ?? projects[0];
83
+ const projectId = project.projectId ?? project.id;
84
+
85
+ return { orgId, projectId };
86
+ }
87
+
88
+ async findOrCreateApiKey(
89
+ host: string,
90
+ authorization: string,
91
+ orgId: string,
92
+ projectId: string,
93
+ ): Promise<{ apiKey: string }> {
94
+ const listUrl = `${host}/api/biz/v1/organization/${orgId}/projects/${projectId}/api_keys`;
95
+
96
+ let existing: any[] = [];
97
+ try {
98
+ existing = await requestBizApi(this.fetchImpl, listUrl, authorization, { method: "GET" }) ?? [];
99
+ } catch { /* ignore — will create */ }
100
+
101
+ if (Array.isArray(existing)) {
102
+ const found = existing.find((k: any) => k.name === ZAI_API_KEY_NAME);
103
+ // Reuse the listed key only when it has a usable shape; a malformed
104
+ // entry falls through to the create path instead of poisoning the
105
+ // stored credential.
106
+ if (found && typeof found.apiKey === "string" && found.apiKey.length > 0) {
107
+ return { apiKey: found.apiKey };
108
+ }
109
+ }
110
+
111
+ const created = await requestBizApi(this.fetchImpl, listUrl, authorization, {
112
+ method: "POST",
113
+ body: JSON.stringify({ name: ZAI_API_KEY_NAME }),
114
+ });
115
+ // Shape guard (CL-06): an upstream response drift (renamed/nested field)
116
+ // must fail the login with a clear error — not store the string
117
+ // "undefined" and 401 on every later request.
118
+ if (typeof created?.apiKey !== "string" || created.apiKey.length === 0) {
119
+ throw new Error("API key creation returned unexpected shape: apiKey missing or empty");
120
+ }
121
+ return { apiKey: created.apiKey };
122
+ }
123
+
124
+ async getSecretKey(
125
+ host: string,
126
+ authorization: string,
127
+ orgId: string,
128
+ projectId: string,
129
+ apiKey: string,
130
+ ): Promise<string> {
131
+ const url = `${host}/api/biz/v1/organization/${orgId}/projects/${projectId}/api_keys/copy/${encodeURIComponent(apiKey)}`;
132
+ const data = await requestBizApi(this.fetchImpl, url, authorization, { method: "GET" });
133
+ return data.secretKey ?? data.secret_key ?? "";
134
+ }
135
+
136
+ async resolveCodingPlanCredential(
137
+ accessToken: string,
138
+ provider: ProviderId,
139
+ userId?: string,
140
+ ): Promise<Credential> {
141
+ if (provider === "zai") {
142
+ const bizToken = await this.resolveZaiBizToken(accessToken);
143
+ const host = "https://api.z.ai";
144
+ const authorization = `Bearer ${bizToken}`;
145
+
146
+ const { orgId, projectId } = await this.resolveCustomerInfo(host, authorization);
147
+ const { apiKey } = await this.findOrCreateApiKey(host, authorization, orgId, projectId);
148
+ let secret: string | undefined;
149
+ try {
150
+ secret = await this.getSecretKey(host, authorization, orgId, projectId, apiKey);
151
+ } catch { /* credential will be apiKey-only */ }
152
+
153
+ return { apiKey, secret: secret || undefined, provider: "zai", userId };
154
+ }
155
+
156
+ const host = "https://bigmodel.cn";
157
+ const authorization = accessToken;
158
+
159
+ const { orgId, projectId } = await this.resolveCustomerInfo(host, authorization);
160
+ const { apiKey } = await this.findOrCreateApiKey(host, authorization, orgId, projectId);
161
+
162
+ let fullKey = apiKey;
163
+ try {
164
+ const secret = await this.getSecretKey(host, authorization, orgId, projectId, apiKey);
165
+ if (secret) fullKey = `${apiKey}.${secret}`;
166
+ } catch { /* use apiKey only */ }
167
+
168
+ return { apiKey: fullKey, provider: "bigmodel", userId };
169
+ }
170
+ }
src/auth/store.ts ADDED
@@ -0,0 +1,158 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Encrypted file-based credential store.
3
+ * @see .omo/plans/zcode-proxy.md Task 14
4
+ */
5
+ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
6
+ import { join, dirname } from "node:path";
7
+ import { homedir } from "node:os";
8
+ import { createHash } from "node:crypto";
9
+ import type { Credential } from "./types.js";
10
+
11
+ const STORE_DIR = join(homedir(), ".zcode-proxy");
12
+ const STORE_FILE = join(STORE_DIR, "credentials.json");
13
+ const ENV_SECRET = "ZCODE_PROXY_CREDENTIAL_SECRET";
14
+
15
+ /**
16
+ * Derive the AES-GCM key as SHA-256(seed) (audit R2-13). The previous XOR-fold
17
+ * construction was a pseudo-KDF: a seed shorter than 32 bytes left zero blocks
18
+ * in the key. Scope note: on default machine-derived seeds the security gain
19
+ * is ~0 (any same-user process can re-derive the seed either way, 0o600 only
20
+ * stops other users) — the motivation is structural: env-secret deployments
21
+ * (`ZCODE_PROXY_CREDENTIAL_SECRET`) get real 32-byte diffusion, and the
22
+ * misleading "KDF" is gone.
23
+ */
24
+ function getEncryptionKey(): Uint8Array {
25
+ const seed = process.env[ENV_SECRET] ?? `${homedir()}-${process.platform}-${process.arch}`;
26
+ return new Uint8Array(createHash("sha256").update(seed, "utf-8").digest());
27
+ }
28
+
29
+ /**
30
+ * Legacy XOR-fold key (pre-SHA-256 store format). Kept ONLY for the one-shot
31
+ * migration decrypt in {@link loadCredential} — never used for new writes.
32
+ */
33
+ function getLegacyEncryptionKey(): Uint8Array {
34
+ const hash = new Uint8Array(new ArrayBuffer(32));
35
+ const encoder = new TextEncoder();
36
+
37
+ const seed = process.env[ENV_SECRET] ?? `${homedir()}-${process.platform}-${process.arch}`;
38
+ const seedBytes = encoder.encode(seed);
39
+ for (let i = 0; i < seedBytes.length; i++) {
40
+ hash[i % 32] ^= seedBytes[i];
41
+ }
42
+ return hash;
43
+ }
44
+
45
+ /** Atomic store write: temp file (0o600) + rename over the target. */
46
+ function atomicWriteStore(contents: string): void {
47
+ const tmp = `${STORE_FILE}.tmp-${process.pid}-${Date.now()}`;
48
+ writeFileSync(tmp, contents, { mode: 0o600 });
49
+ renameSync(tmp, STORE_FILE);
50
+ }
51
+
52
+ async function importAesKey(raw: Uint8Array): Promise<CryptoKey> {
53
+ // Copy into a plain ArrayBuffer: bun-types types Uint8Array as
54
+ // ArrayBufferLike, which is not assignable to BufferSource.
55
+ const ab = new ArrayBuffer(raw.byteLength);
56
+ new Uint8Array(ab).set(raw);
57
+ return crypto.subtle.importKey(
58
+ "raw",
59
+ ab,
60
+ { name: "AES-GCM" },
61
+ false,
62
+ ["encrypt", "decrypt"],
63
+ );
64
+ }
65
+
66
+ async function encryptWith(key: Uint8Array, plaintext: string): Promise<string> {
67
+ const aesKey = await importAesKey(key);
68
+
69
+ const iv = crypto.getRandomValues(new Uint8Array(12));
70
+ const encoder = new TextEncoder();
71
+ const encrypted = await crypto.subtle.encrypt(
72
+ { name: "AES-GCM", iv },
73
+ aesKey,
74
+ encoder.encode(plaintext),
75
+ );
76
+
77
+ const combined = new Uint8Array(iv.length + encrypted.byteLength);
78
+ combined.set(iv, 0);
79
+ combined.set(new Uint8Array(encrypted), iv.length);
80
+
81
+ return Buffer.from(combined).toString("base64");
82
+ }
83
+
84
+ async function decryptWith(key: Uint8Array, ciphertext: string): Promise<string> {
85
+ const aesKey = await importAesKey(key);
86
+
87
+ const combined = Buffer.from(ciphertext, "base64");
88
+ const iv = combined.slice(0, 12);
89
+ const data = combined.slice(12);
90
+
91
+ const decrypted = await crypto.subtle.decrypt(
92
+ { name: "AES-GCM", iv },
93
+ aesKey,
94
+ data,
95
+ );
96
+
97
+ return new TextDecoder().decode(decrypted);
98
+ }
99
+
100
+ async function encrypt(plaintext: string): Promise<string> {
101
+ return encryptWith(getEncryptionKey(), plaintext);
102
+ }
103
+
104
+ export async function saveCredential(cred: Credential): Promise<void> {
105
+ mkdirSync(dirname(STORE_FILE), { recursive: true });
106
+ const json = JSON.stringify(cred);
107
+ const encrypted = await encrypt(json);
108
+ atomicWriteStore(JSON.stringify({ encrypted }));
109
+ }
110
+
111
+ export async function loadCredential(): Promise<Credential | null> {
112
+ if (!existsSync(STORE_FILE)) return null;
113
+ const raw = readFileSync(STORE_FILE, "utf-8");
114
+ const parsed = JSON.parse(raw);
115
+ if (!parsed.encrypted) return null;
116
+
117
+ let json: string;
118
+ try {
119
+ json = await decryptWith(getEncryptionKey(), parsed.encrypted);
120
+ } catch {
121
+ // Not decryptable under the new SHA-256 KDF — try the legacy XOR-fold key
122
+ // (one-shot migration), then transparently re-store under the new format.
123
+ try {
124
+ json = await decryptWith(getLegacyEncryptionKey(), parsed.encrypted);
125
+ } catch (e) {
126
+ // Stale/corrupt credential file — key derivation is machine-specific
127
+ // ({homedir}-{platform}-{arch}), so cross-machine copies or OS reinstalls
128
+ // produce undecryptable ciphertext. Silently treat as "not logged in".
129
+ console.warn(`Ignoring corrupted or stale credentials at ${STORE_FILE}: ${(e as Error).message}`);
130
+ return null;
131
+ }
132
+ // Re-store under the new KDF. Best-effort by design: the credential is
133
+ // already decrypted in memory, so a failed re-write (read-only dir, AV
134
+ // lock on Windows, ...) must NOT fail this load — it retries next boot.
135
+ try {
136
+ atomicWriteStore(JSON.stringify({ encrypted: await encrypt(json) }));
137
+ } catch (e) {
138
+ console.warn(`Credential re-encryption under the new key derivation failed (will retry on next load): ${(e as Error).message}`);
139
+ }
140
+ }
141
+
142
+ try {
143
+ return JSON.parse(json) as Credential;
144
+ } catch (e) {
145
+ console.warn(`Ignoring corrupted credentials at ${STORE_FILE}: ${(e as Error).message}`);
146
+ return null;
147
+ }
148
+ }
149
+
150
+ export function clearCredential(): void {
151
+ if (existsSync(STORE_FILE)) {
152
+ unlinkSync(STORE_FILE);
153
+ }
154
+ }
155
+
156
+ export function getStorePath(): string {
157
+ return STORE_FILE;
158
+ }
src/auth/types.ts ADDED
@@ -0,0 +1,41 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Credential and auth type definitions.
3
+ * @see .omo/plans/zcode-proxy.md Task 4
4
+ * @see _reverse/NOTEPAD.md "How Credential is Used"
5
+ */
6
+ import type { ProviderId } from "../provider/types.js";
7
+
8
+ /** A resolved credential ready to be injected into upstream requests. */
9
+ export interface Credential {
10
+ /** The API key portion (e.g. Z.AI API key id, or Bigmodel API key). */
11
+ apiKey: string;
12
+ /** The secret portion (Z.AI only — appended as `{apiKey}.{secret}`). */
13
+ secret?: string;
14
+ /** Which provider this credential is for. */
15
+ provider: ProviderId;
16
+ /** Unix timestamp (ms) when the credential expires. Present only for OAuth. */
17
+ expiresAt?: number;
18
+ /** Upstream user identifier (OAuth only). Injected as `metadata.user_id` on Anthropic-format requests. */
19
+ userId?: string;
20
+ /** JWT token for start-plan (zcode.z.ai). Present when login captured the ZCode plan token. */
21
+ jwt?: string;
22
+ }
23
+
24
+ /**
25
+ * Convert a `Credential` to the string sent upstream.
26
+ *
27
+ * - Z.AI: `{apiKey}.{secret}` (secret required)
28
+ * - Bigmodel: `{apiKey}` (no secret)
29
+ */
30
+ export function credentialString(cred: Credential): string {
31
+ if (cred.secret) {
32
+ return `${cred.apiKey}.${cred.secret}`;
33
+ }
34
+ return cred.apiKey;
35
+ }
36
+
37
+ /** Check whether a credential has expired. */
38
+ export function isExpired(cred: Credential, now: number = Date.now()): boolean {
39
+ if (cred.expiresAt === undefined) return false;
40
+ return now >= cred.expiresAt;
41
+ }
src/claim/client.ts ADDED
@@ -0,0 +1,225 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * HTTP client for ZCode's manual-claim billing endpoints (weekend plans).
3
+ *
4
+ * Mirrors the ZCode 3.10 desktop client's `getManualClaimPlanPreviews` /
5
+ * `claimManualPlan`:
6
+ * - `GET {origin}/api/v1/zcode-plan/billing/preview?app_version=&platform=`
7
+ * - `POST {origin}/api/v1/zcode-plan/billing/claim` body `{plan_id}`
8
+ *
9
+ * Claim headers: `Authorization: Bearer {jwt}` (OAuth), Aliyun captcha
10
+ * verify param/region (same token source as the start-plan gateway),
11
+ * `X-ZCode-App-Version` and `X-Platform` (part of server-side eligibility).
12
+ *
13
+ * Since the 0828 weekend campaign the gateway REJECTS preview/claim with
14
+ * biz 3001 "parameter error" unless the request carries a UUID-format
15
+ * `X-Device-Mid` (empirically verified 2026-08-28: only that header is
16
+ * validated; non-UUID values still 3001). Pass `identity` so both calls
17
+ * carry the full identity set minus `X-ZCode-Agent` — same header set the
18
+ * endpoint-routing config fetch uses for zcode.z.ai control-plane calls.
19
+ *
20
+ * @see _reverse/NOTEPAD.md (billing/claim endpoints section).
21
+ */
22
+ import type { ClaimablePlan, ClaimOutcome, PlanEntitlement } from "./types.js";
23
+ import { classifyClaimCode } from "./types.js";
24
+ import { buildIdentityHeaders } from "../proxy/identity.js";
25
+ import type { ProxyIdentity } from "../config/types.js";
26
+
27
+ export interface ClaimClientOptions {
28
+ origin: string;
29
+ /** OAuth JWT (`zcodejwttoken`); preview works without it, claim does not. */
30
+ jwt?: string;
31
+ appVersion: string;
32
+ /** `${process.platform}-${process.arch}` in the real client. */
33
+ platform: string;
34
+ /**
35
+ * Identity block driving the zcode.z.ai control-plane header set
36
+ * (incl. the server-required `X-Device-Mid`). When omitted the client
37
+ * falls back to the minimal legacy set (version + platform headers only).
38
+ */
39
+ identity?: ProxyIdentity;
40
+ /** Per-call timeout in ms. Default `15000`. */
41
+ timeoutMs?: number;
42
+ /** DI seam for tests. Default `globalThis.fetch`. */
43
+ fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
44
+ }
45
+
46
+ export interface ClaimClient {
47
+ getPreviews(signal?: AbortSignal): Promise<ClaimablePlan[]>;
48
+ claim(planId: string, captcha: { verifyParam: string; region?: string }, signal?: AbortSignal): Promise<ClaimOutcome>;
49
+ }
50
+
51
+ const DEFAULT_TIMEOUT_MS = 15_000;
52
+
53
+ /** Preview failure with the HTTP status preserved (404 = campaign not deployed yet). */
54
+ export class ClaimPreviewError extends Error {
55
+ readonly status: number;
56
+ readonly code: number | string;
57
+ constructor(message: string, status: number, code: number | string) {
58
+ super(message);
59
+ this.name = "ClaimPreviewError";
60
+ this.status = status;
61
+ this.code = code;
62
+ }
63
+ }
64
+
65
+ interface RawEntitlement {
66
+ entitlement_id?: string;
67
+ show_name?: string;
68
+ meter?: string;
69
+ unit_type?: string;
70
+ capabilities?: string[];
71
+ grant_units?: number;
72
+ period?: string;
73
+ priority?: number;
74
+ effective_at?: number;
75
+ }
76
+
77
+ interface RawPlan {
78
+ plan_id?: string;
79
+ name?: string;
80
+ description?: string;
81
+ priority?: number;
82
+ entitlements?: RawEntitlement[];
83
+ starts_at?: number;
84
+ ends_at?: number;
85
+ }
86
+
87
+ export function createClaimClient(opts: ClaimClientOptions): ClaimClient {
88
+ const origin = opts.origin.replace(/\/+$/, "");
89
+ const jwt = opts.jwt?.trim() || undefined;
90
+ const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
91
+ const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
92
+ // Identity set minus X-ZCode-Agent (zcode.z.ai control-plane precedent —
93
+ // see endpoint-routing.ts); the no-identity fallback keeps the legacy shape.
94
+ const identityHeaders: Record<string, string> = opts.identity
95
+ ? Object.fromEntries(
96
+ Object.entries(buildIdentityHeaders(opts.identity)).filter(([name]) => name !== "X-ZCode-Agent"),
97
+ )
98
+ : { "X-ZCode-App-Version": opts.appVersion, "X-Platform": opts.platform };
99
+
100
+ function parseEntitlement(c: RawEntitlement): PlanEntitlement | null {
101
+ const entitlementId = c.entitlement_id?.trim() ?? "";
102
+ if (!entitlementId) return null;
103
+ const e: PlanEntitlement = {
104
+ entitlementId,
105
+ showName: c.show_name?.trim() ?? "",
106
+ meter: c.meter?.trim() ?? "",
107
+ unitType: c.unit_type?.trim() ?? "",
108
+ capabilities: Array.isArray(c.capabilities) ? c.capabilities : [],
109
+ grantUnits: Number.isFinite(c.grant_units) ? (c.grant_units as number) : 0,
110
+ period: c.period?.trim() ?? "",
111
+ priority: Number.isFinite(c.priority) ? (c.priority as number) : 0,
112
+ };
113
+ if (Number.isFinite(c.effective_at)) e.effectiveAt = c.effective_at as number;
114
+ return e;
115
+ }
116
+
117
+ function parsePlan(p: RawPlan): ClaimablePlan | null {
118
+ const planId = p.plan_id?.trim() ?? "";
119
+ if (!planId) return null;
120
+ const plan: ClaimablePlan = {
121
+ planId,
122
+ name: p.name?.trim() || planId,
123
+ description: p.description?.trim() ?? "",
124
+ priority: Number.isFinite(p.priority) ? (p.priority as number) : 0,
125
+ entitlements: (p.entitlements ?? []).flatMap((c) => {
126
+ const e = parseEntitlement(c);
127
+ return e ? [e] : [];
128
+ }),
129
+ };
130
+ if (Number.isFinite(p.starts_at)) plan.startsAt = p.starts_at as number;
131
+ if (Number.isFinite(p.ends_at)) plan.endsAt = p.ends_at as number;
132
+ return plan;
133
+ }
134
+
135
+ async function request(
136
+ method: string,
137
+ path: string,
138
+ init: { body?: unknown; headers?: Record<string, string>; signal?: AbortSignal },
139
+ ): Promise<{ status: number; json: Record<string, unknown> | undefined; text: string }> {
140
+ const controller = new AbortController();
141
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
142
+ const onExternalAbort = (): void => controller.abort();
143
+ if (init.signal) {
144
+ if (init.signal.aborted) controller.abort();
145
+ else init.signal.addEventListener("abort", onExternalAbort, { once: true });
146
+ }
147
+ let resp: Response;
148
+ try {
149
+ resp = await fetchImpl(`${origin}${path}`, {
150
+ method,
151
+ headers: init.headers,
152
+ body: init.body === undefined ? undefined : JSON.stringify(init.body),
153
+ signal: controller.signal,
154
+ });
155
+ const text = await resp.text();
156
+ let json: Record<string, unknown> | undefined;
157
+ try {
158
+ const parsed = JSON.parse(text) as unknown;
159
+ if (parsed && typeof parsed === "object") json = parsed as Record<string, unknown>;
160
+ } catch { /* non-JSON body surfaced via text */ }
161
+ return { status: resp.status, json, text };
162
+ } finally {
163
+ clearTimeout(timer);
164
+ init.signal?.removeEventListener("abort", onExternalAbort);
165
+ }
166
+ }
167
+
168
+ function unwrapError(json: Record<string, unknown> | undefined, status: number, text: string): { code: number | string; message: string } {
169
+ const code = json?.code !== undefined ? (json.code as number | string) : status >= 400 ? status : -1;
170
+ const rawMsg = json?.msg ?? json?.message;
171
+ const message = typeof rawMsg === "string" && rawMsg.trim() ? rawMsg.trim() : text.length > 0 && text.length < 200 ? text : `HTTP ${status}`;
172
+ return { code, message };
173
+ }
174
+
175
+ return {
176
+ async getPreviews(signal?: AbortSignal): Promise<ClaimablePlan[]> {
177
+ const url = `/api/v1/zcode-plan/billing/preview?app_version=${encodeURIComponent(opts.appVersion)}&platform=${encodeURIComponent(opts.platform)}`;
178
+ const headers: Record<string, string> = { ...identityHeaders };
179
+ if (jwt) headers.authorization = `Bearer ${jwt}`;
180
+ const { status, json, text } = await request("GET", url, { headers, signal });
181
+ if (status < 200 || status >= 300 || (json?.code !== undefined && json.code !== 0) || json?.data === undefined) {
182
+ const { code, message } = unwrapError(json, status, text);
183
+ throw new ClaimPreviewError(`claim preview failed (${code}): ${message}`, status, code);
184
+ }
185
+ const data = json.data as { plans?: RawPlan[] };
186
+ return (data.plans ?? []).flatMap((p) => {
187
+ const plan = parsePlan(p);
188
+ return plan ? [plan] : [];
189
+ });
190
+ },
191
+
192
+ async claim(planId: string, captcha: { verifyParam: string; region?: string }, signal?: AbortSignal): Promise<ClaimOutcome> {
193
+ if (!jwt) return { ok: false, planId, failureKind: "login_required", code: 401, message: "manual_claim_login_required" };
194
+ const headers: Record<string, string> = {
195
+ ...identityHeaders,
196
+ authorization: `Bearer ${jwt}`,
197
+ "content-type": "application/json",
198
+ "X-Aliyun-Captcha-Verify-Param": captcha.verifyParam,
199
+ };
200
+ if (captcha.region) headers["X-Aliyun-Captcha-Verify-Region"] = captcha.region;
201
+ const { status, json, text } = await request("POST", "/api/v1/zcode-plan/billing/claim", { body: { plan_id: planId }, headers, signal });
202
+
203
+ const data = json?.data as { plan?: RawPlan } | undefined;
204
+ const bizCode = json?.code !== undefined ? (json.code as number) : undefined;
205
+ const plan = data?.plan;
206
+ if (status >= 200 && status < 300 && bizCode === 0 && plan) {
207
+ const out: ClaimOutcome = { ok: true, planId };
208
+ if (Number.isFinite(plan.starts_at)) out.startsAt = plan.starts_at as number;
209
+ if (Number.isFinite(plan.ends_at)) out.endsAt = plan.ends_at as number;
210
+ return out;
211
+ }
212
+ const { code, message } = unwrapError(json, status, text);
213
+ const failureEndsAt = Number.isFinite(plan?.ends_at) ? (plan?.ends_at as number) : undefined;
214
+ const httpDerived = status >= 400 && bizCode === undefined;
215
+ return {
216
+ ok: false,
217
+ planId,
218
+ failureKind: httpDerived ? (status === 401 ? "login_required" : "http_error") : classifyClaimCode(code),
219
+ code,
220
+ message,
221
+ ...(failureEndsAt !== undefined ? { failureEndsAt } : {}),
222
+ };
223
+ },
224
+ };
225
+ }
src/claim/runtime.ts ADDED
@@ -0,0 +1,147 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Wiring between the claim subsystem and the rest of the proxy: builds a
3
+ * scheduler from a loaded `ProxyConfig` + `AuthManager` (serve path) and
4
+ * implements the one-shot CLI flow (`zcode-proxy claim [list|now]`).
5
+ */
6
+ import type { AuthManager } from "../auth/manager.js";
7
+ import type { ProxyConfig } from "../config/types.js";
8
+ import type { ClaimablePlan, ClaimOutcome } from "./types.js";
9
+ import { createClaimClient, ClaimPreviewError } from "./client.js";
10
+ import { ClaimScheduler } from "./scheduler.js";
11
+ import { getCaptchaToken } from "../proxy/captcha.js";
12
+ import { loadCredential } from "../auth/store.js";
13
+
14
+ /** `${process.platform}-${process.arch}` — mirrors the client's `TH()`. */
15
+ export function claimPlatform(): string {
16
+ return `${process.platform}-${process.arch}`;
17
+ }
18
+
19
+ export function startAutoClaim(config: ProxyConfig, auth: AuthManager): ClaimScheduler {
20
+ const scheduler = new ClaimScheduler({
21
+ // AuthManager first (fresh), then the encrypted store — on Android the
22
+ // login can land in the store after boot while auth hasn't been reloaded.
23
+ getJwt: async () => {
24
+ try {
25
+ const cred = await auth.getCredential();
26
+ if (cred.jwt) return cred.jwt;
27
+ } catch { /* fall through to the store */ }
28
+ const stored = await loadCredential().catch(() => null);
29
+ return stored?.jwt;
30
+ },
31
+ createClient: (jwt) =>
32
+ createClaimClient({
33
+ origin: config.claim.origin,
34
+ jwt,
35
+ appVersion: config.identity.appVersion,
36
+ platform: claimPlatform(),
37
+ identity: config.identity,
38
+ }),
39
+ getCaptcha: async () => {
40
+ const { verifyParam, region } = await getCaptchaToken(config.identity.appVersion);
41
+ return { verifyParam, region: region || undefined };
42
+ },
43
+ config: {
44
+ planId: config.claim.planId || undefined,
45
+ pollIntervalMs: config.claim.pollIntervalMs,
46
+ cooldownMs: config.claim.cooldownMs,
47
+ },
48
+ log: (message) => console.log(`[claim] ${message}`),
49
+ });
50
+ scheduler.start();
51
+ return scheduler;
52
+ }
53
+
54
+ const FAILURE_LABELS: Record<string, string> = {
55
+ not_found: "plan does not exist",
56
+ unavailable: "campaign ended or not claimable yet",
57
+ already_claimed: "already claimed on this account",
58
+ ineligible: "account or client version not eligible (needs appVersion >= campaign minimum)",
59
+ quota_exhausted: "daily claim quota exhausted",
60
+ invalid_request: "invalid request",
61
+ captcha: "captcha verification failed",
62
+ login_required: "not logged in",
63
+ http_error: "HTTP error",
64
+ unknown: "unknown failure",
65
+ };
66
+
67
+ /** One-shot CLI: `list` prints previews; `now` claims the target plan. */
68
+ export async function runClaimCli(config: ProxyConfig, mode: "list" | "now"): Promise<void> {
69
+ const cred = await loadCredential();
70
+ const jwt = cred?.jwt;
71
+ if (!jwt) {
72
+ console.error("Claim requires a logged-in oauth credential (no JWT stored). Run: zcode-proxy auth login <zai|bigmodel>");
73
+ process.exit(1);
74
+ }
75
+ const client = createClaimClient({
76
+ origin: config.claim.origin,
77
+ jwt,
78
+ appVersion: config.identity.appVersion,
79
+ platform: claimPlatform(),
80
+ identity: config.identity,
81
+ });
82
+
83
+ let plans: ClaimablePlan[];
84
+ try {
85
+ plans = await client.getPreviews();
86
+ } catch (err) {
87
+ if (err instanceof ClaimPreviewError && err.status === 404) {
88
+ console.log("No claimable plans: the campaign endpoint is not deployed yet (404).");
89
+ console.log("Weekend campaigns typically go live shortly before the window — keep the proxy");
90
+ console.log("serving with claim.enabled, or re-run this command later.");
91
+ return;
92
+ }
93
+ throw err;
94
+ }
95
+ if (plans.length === 0) {
96
+ console.log("No claimable plans right now.");
97
+ return;
98
+ }
99
+ printPlans(plans);
100
+
101
+ if (mode === "list") return;
102
+
103
+ const wanted = config.claim.planId.trim();
104
+ const target = wanted ? plans.find((p) => p.planId === wanted) : [...plans].sort((a, b) => b.priority - a.priority)[0];
105
+ if (!target) {
106
+ console.error(`Configured claim.planId "${wanted}" not in the preview list.`);
107
+ process.exit(1);
108
+ }
109
+ if (target.planId !== plans[0].planId) console.log(`Claiming configured plan: ${target.planId}`);
110
+
111
+ const captcha = await getCaptchaToken(config.identity.appVersion);
112
+ const outcome = await client.claim(target.planId, { verifyParam: captcha.verifyParam, region: captcha.region || undefined });
113
+ printOutcome(outcome);
114
+ if (!outcome.ok) process.exit(1);
115
+ }
116
+
117
+ function printPlans(plans: ClaimablePlan[]): void {
118
+ console.log(`Claimable plans (${plans.length}):`);
119
+ for (const p of plans) {
120
+ const window = [fmtTime(p.startsAt), fmtTime(p.endsAt)].filter(Boolean).join(" → ");
121
+ console.log(` - ${p.planId} "${p.name}" priority=${p.priority}${window ? ` ${window}` : ""}`);
122
+ for (const e of p.entitlements) {
123
+ const quota = e.grantUnits > 0 ? ` ${e.grantUnits} ${e.unitType}` : "";
124
+ const activate = e.effectiveAt !== undefined ? ` (activates ${new Date(e.effectiveAt * 1000).toISOString()})` : "";
125
+ console.log(` · ${e.showName || e.entitlementId}${quota}${activate}`);
126
+ }
127
+ }
128
+ }
129
+
130
+ function printOutcome(outcome: ClaimOutcome): void {
131
+ if (outcome.ok) {
132
+ console.log(`\nClaimed: ${outcome.planId}`);
133
+ if (outcome.startsAt !== undefined) console.log(` activates: ${new Date(outcome.startsAt * 1000).toISOString()}`);
134
+ if (outcome.endsAt !== undefined) console.log(` expires: ${new Date(outcome.endsAt * 1000).toISOString()}`);
135
+ if (outcome.startsAt === undefined && outcome.endsAt === undefined) console.log(" active immediately");
136
+ return;
137
+ }
138
+ const label = FAILURE_LABELS[outcome.failureKind] ?? FAILURE_LABELS.unknown;
139
+ console.error(`\nClaim failed: ${label} (code ${String(outcome.code)}) — ${outcome.message}`);
140
+ if (outcome.failureEndsAt !== undefined) {
141
+ console.error(` retry window opens: ${new Date(outcome.failureEndsAt * 1000).toISOString()}`);
142
+ }
143
+ }
144
+
145
+ function fmtTime(sec: number | undefined): string {
146
+ return sec === undefined ? "" : new Date(sec * 1000).toISOString();
147
+ }
src/claim/scheduler.ts ADDED
@@ -0,0 +1,186 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Auto-claim scheduler — polls the manual-claim preview endpoint and claims
3
+ * weekend/trial plans the moment they become available (first-come-first-served:
4
+ * the server caps daily claims with biz code 1005).
5
+ *
6
+ * Backoff semantics per failure kind (biz codes from the desktop client):
7
+ * - success / already_claimed → hold until the plan's `ends_at` (unix sec)
8
+ * - quota_exhausted → hold until `failureEndsAt` (next window) else cooldown
9
+ * - ineligible / unavailable / not_found → cooldown
10
+ * - captcha / network / unknown → cooldown (retry next window)
11
+ * - login_required → stop (needs re-login)
12
+ *
13
+ * `starts_at` / `ends_at` / `failureEndsAt` are unix SECONDS (the desktop
14
+ * client compares them against `Date.now()/1e3`).
15
+ */
16
+ import type { ClaimOutcome, ClaimablePlan } from "./types.js";
17
+ import { ClaimPreviewError } from "./client.js";
18
+
19
+ interface ClaimGateway {
20
+ getPreviews(): Promise<ClaimablePlan[]>;
21
+ claim(planId: string, captcha: { verifyParam: string; region?: string }): Promise<ClaimOutcome>;
22
+ }
23
+
24
+ export interface ClaimSchedulerConfig {
25
+ /** Claim this plan_id; empty = highest-priority preview. */
26
+ planId?: string;
27
+ pollIntervalMs: number;
28
+ cooldownMs: number;
29
+ }
30
+
31
+ export interface ClaimSchedulerDeps {
32
+ getJwt(): Promise<string | undefined>;
33
+ createClient(jwt: string): ClaimGateway;
34
+ getCaptcha(): Promise<{ verifyParam: string; region?: string }>;
35
+ config: ClaimSchedulerConfig;
36
+ log?: (message: string) => void;
37
+ now?: () => number;
38
+ }
39
+
40
+ export type TickResult =
41
+ | { action: "skipped_hold" }
42
+ | { action: "stopped" }
43
+ | { action: "idle" }
44
+ | { action: "claimed"; planId: string; startsAt?: number; endsAt?: number }
45
+ | { action: "failed"; outcome: Extract<ClaimOutcome, { ok: false }>; holdMs: number }
46
+ | { action: "error"; message: string; holdMs: number };
47
+
48
+ export class ClaimScheduler {
49
+ private stopped = false;
50
+ private holdUntil = 0;
51
+ private timer: ReturnType<typeof setTimeout> | null = null;
52
+ private readonly now: () => number;
53
+ private readonly log: (message: string) => void;
54
+
55
+ constructor(private readonly deps: ClaimSchedulerDeps) {
56
+ this.now = deps.now ?? Date.now;
57
+ this.log = deps.log ?? (() => {});
58
+ }
59
+
60
+ isStopped(): boolean {
61
+ return this.stopped;
62
+ }
63
+
64
+ start(): void {
65
+ if (this.stopped) return;
66
+ this.scheduleNext(0);
67
+ }
68
+
69
+ stop(): void {
70
+ this.stopped = true;
71
+ if (this.timer !== null) {
72
+ clearTimeout(this.timer);
73
+ this.timer = null;
74
+ }
75
+ }
76
+
77
+ /** One poll→claim cycle. Exposed for tests; `start()` drives it on a timer. */
78
+ async tick(): Promise<TickResult> {
79
+ if (this.stopped) return { action: "stopped" };
80
+ const nowMs = this.now();
81
+ if (nowMs < this.holdUntil) return { action: "skipped_hold" };
82
+
83
+ let jwt: string | undefined;
84
+ try {
85
+ jwt = await this.deps.getJwt();
86
+ } catch (err) {
87
+ return this.errorBackoff(`credential resolution failed: ${(err as Error).message}`);
88
+ }
89
+ if (!jwt) {
90
+ // Missing JWT is "login pending" (Android logs in after boot), not fatal:
91
+ // back off and retry — the login_required CLAIM FAILURE (server 401) is
92
+ // the terminal case handled below.
93
+ return this.errorBackoff("no JWT available (oauth login pending)");
94
+ }
95
+
96
+ const client = this.deps.createClient(jwt);
97
+ let plans: ClaimablePlan[];
98
+ try {
99
+ plans = await client.getPreviews();
100
+ } catch (err) {
101
+ // 404 = campaign endpoint not deployed yet (the expected pre-launch state
102
+ // for weekend plans); poll at normal cadence instead of error backoff.
103
+ if (err instanceof ClaimPreviewError && err.status === 404) {
104
+ this.holdUntil = nowMs + this.deps.config.pollIntervalMs;
105
+ return { action: "idle" };
106
+ }
107
+ return this.errorBackoff(`preview failed: ${(err as Error).message}`);
108
+ }
109
+ if (plans.length === 0) {
110
+ this.holdUntil = nowMs + this.deps.config.pollIntervalMs;
111
+ return { action: "idle" };
112
+ }
113
+
114
+ const target = this.pickPlan(plans);
115
+ if (!target) {
116
+ // Configured planId not in the current preview list — plain poll cadence.
117
+ this.holdUntil = nowMs + this.deps.config.pollIntervalMs;
118
+ return { action: "idle" };
119
+ }
120
+
121
+ let captcha: { verifyParam: string; region?: string };
122
+ try {
123
+ captcha = await this.deps.getCaptcha();
124
+ } catch (err) {
125
+ return this.errorBackoff(`captcha token failed: ${(err as Error).message}`);
126
+ }
127
+
128
+ let outcome: ClaimOutcome;
129
+ try {
130
+ outcome = await client.claim(target.planId, captcha);
131
+ } catch (err) {
132
+ return this.errorBackoff(`claim request failed: ${(err as Error).message}`);
133
+ }
134
+
135
+ if (outcome.ok) {
136
+ const endsAtMs = outcome.endsAt !== undefined ? outcome.endsAt * 1000 : undefined;
137
+ this.holdUntil = endsAtMs ?? nowMs + this.deps.config.pollIntervalMs;
138
+ this.log(`claim: claimed plan ${target.planId}${outcome.startsAt !== undefined ? ` (activates ${new Date(outcome.startsAt * 1000).toISOString()})` : ""}`);
139
+ return { action: "claimed", planId: target.planId, startsAt: outcome.startsAt, endsAt: outcome.endsAt };
140
+ }
141
+
142
+ const holdMs = this.holdForFailure(outcome.failureKind, outcome.failureEndsAt, nowMs);
143
+ this.holdUntil = nowMs + holdMs;
144
+ this.log(`claim: ${outcome.failureKind} (${outcome.code}) — ${outcome.message}; retry in ${Math.round(holdMs / 1000)}s`);
145
+ if (outcome.failureKind === "login_required") {
146
+ this.stop();
147
+ }
148
+ return { action: "failed", outcome, holdMs };
149
+ }
150
+
151
+ private pickPlan(plans: ClaimablePlan[]): ClaimablePlan | null {
152
+ const wanted = this.deps.config.planId?.trim();
153
+ if (wanted) return plans.find((p) => p.planId === wanted) ?? null;
154
+ // Server order first, highest priority breaks ties (stable sort).
155
+ const sorted = [...plans].sort((a, b) => b.priority - a.priority);
156
+ return sorted[0] ?? null;
157
+ }
158
+
159
+ private holdForFailure(kind: Extract<ClaimOutcome, { ok: false }>["failureKind"], failureEndsAtSec: number | undefined, nowMs: number): number {
160
+ if ((kind === "already_claimed" || kind === "quota_exhausted") && Number.isFinite(failureEndsAtSec)) {
161
+ const untilMs = (failureEndsAtSec as number) * 1000;
162
+ if (untilMs > nowMs) return Math.min(untilMs - nowMs, 24 * 60 * 60 * 1000);
163
+ }
164
+ return this.deps.config.cooldownMs;
165
+ }
166
+
167
+ private errorBackoff(message: string): TickResult {
168
+ const holdMs = this.deps.config.cooldownMs;
169
+ this.holdUntil = this.now() + holdMs;
170
+ this.log(`claim: ${message}; retry in ${Math.round(holdMs / 1000)}s`);
171
+ return { action: "error", message, holdMs };
172
+ }
173
+
174
+ private scheduleNext(delayMs: number): void {
175
+ if (this.stopped) return;
176
+ this.timer = setTimeout(() => {
177
+ this.timer = null;
178
+ void this.tick().finally(() => this.scheduleNext(this.nextDelay()));
179
+ }, delayMs);
180
+ }
181
+
182
+ private nextDelay(): number {
183
+ const remaining = this.holdUntil - this.now();
184
+ return remaining > 0 ? remaining : this.deps.config.pollIntervalMs;
185
+ }
186
+ }
src/claim/types.ts ADDED
@@ -0,0 +1,66 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Types for the manual-claim ("weekend plan") subsystem — mirrors the ZCode
3
+ * 3.10 desktop client's `manualClaimPlan` feature.
4
+ *
5
+ * Server biz codes → failure kinds match the desktop client's `$vt` mapper:
6
+ * 1001 notFound, 1002 unavailable, 1003 alreadyClaimed, 1004 ineligible,
7
+ * 1005 quotaExhausted, 3001 invalidRequest, 3007 captcha, 401 loginRequired.
8
+ *
9
+ * @see _reverse/NOTEPAD.md "Manual Claim Plan" section.
10
+ */
11
+
12
+ /** One entitlement inside a claimable plan (normalized from snake_case upstream). */
13
+ export interface PlanEntitlement {
14
+ entitlementId: string;
15
+ showName: string;
16
+ meter: string;
17
+ unitType: string;
18
+ capabilities: string[];
19
+ grantUnits: number;
20
+ period: string;
21
+ priority: number;
22
+ /** Unix seconds when the entitlement activates (weekend plans activate late). */
23
+ effectiveAt?: number;
24
+ }
25
+
26
+ /** A claimable trial plan from `GET /api/v1/zcode-plan/billing/preview`. */
27
+ export interface ClaimablePlan {
28
+ planId: string;
29
+ name: string;
30
+ description: string;
31
+ priority: number;
32
+ entitlements: PlanEntitlement[];
33
+ startsAt?: number;
34
+ endsAt?: number;
35
+ }
36
+
37
+ export type ClaimFailureKind =
38
+ | "not_found"
39
+ | "unavailable"
40
+ | "already_claimed"
41
+ | "ineligible"
42
+ | "quota_exhausted"
43
+ | "invalid_request"
44
+ | "captcha"
45
+ | "login_required"
46
+ | "http_error"
47
+ | "unknown";
48
+
49
+ export type ClaimOutcome =
50
+ | { ok: true; planId: string; startsAt?: number; endsAt?: number }
51
+ | { ok: false; planId: string; failureKind: ClaimFailureKind; code: number | string; message: string; failureEndsAt?: number };
52
+
53
+ /** Map a server biz code to the client failure kind (mirrors `$vt` in the desktop bundle). */
54
+ export function classifyClaimCode(code: number | string | undefined): ClaimFailureKind {
55
+ switch (typeof code === "string" ? Number.parseInt(code, 10) : code) {
56
+ case 1001: return "not_found";
57
+ case 1002: return "unavailable";
58
+ case 1003: return "already_claimed";
59
+ case 1004: return "ineligible";
60
+ case 1005: return "quota_exhausted";
61
+ case 3001: return "invalid_request";
62
+ case 3007: return "captcha";
63
+ case 401: return "login_required";
64
+ default: return "unknown";
65
+ }
66
+ }
src/config/edit.ts ADDED
@@ -0,0 +1,38 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Targeted YAML config editing helpers shared by the CLI entries (serve /
3
+ * android / tui) and the TUI runtime.
4
+ */
5
+ import { parseDocument } from "yaml";
6
+ import { readFileSync, writeFileSync, existsSync } from "node:fs";
7
+ import type { ProviderId } from "../provider/types.js";
8
+ import { EXAMPLE_CONFIG_YAML } from "./template.js";
9
+
10
+ /**
11
+ * Targeted YAML update of top-level `provider` and `plan` keys.
12
+ *
13
+ * Uses `yaml`'s document model (`parseDocument` → `set` → `String(doc)`) so
14
+ * comments and formatting in the rest of the file survive the edit — the old
15
+ * `parse`/`stringify` round-trip dropped every comment, and this file is what
16
+ * users see (and edit) in config.yaml.
17
+ */
18
+ export function updateConfigYaml(
19
+ path: string,
20
+ fields: { provider: ProviderId; plan: "coding-plan" | "start-plan" },
21
+ ): void {
22
+ const doc = parseDocument(readFileSync(path, "utf-8"));
23
+ doc.set("provider", fields.provider);
24
+ doc.set("plan", fields.plan);
25
+ writeFileSync(path, String(doc), "utf-8");
26
+ }
27
+
28
+ /**
29
+ * Create the config file from the bundled template when missing.
30
+ * Shared by the CLI entries (serve / android / auth login) and the TUI —
31
+ * they used to each hand-roll this block. Returns true when the file was
32
+ * created, false when it already existed.
33
+ */
34
+ export function ensureConfigFile(path: string): boolean {
35
+ if (existsSync(path)) return false;
36
+ writeFileSync(path, EXAMPLE_CONFIG_YAML, "utf-8");
37
+ return true;
38
+ }
src/config/loader.ts ADDED
@@ -0,0 +1,393 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * YAML config loader with env-var overrides and validation.
3
+ * @see .omo/plans/zcode-proxy.md Task 2
4
+ */
5
+ import { readFileSync, existsSync } from "node:fs";
6
+ import { parse } from "yaml";
7
+ import type { ClientIdentityConfig, ProxyConfig, ProviderEndpoints, ProxyIdentity, ResponsesConfig, McpConfig, AsyncConfig, EndpointRoutingConfig, ClientSigningConfig, ClaimConfig } from "./types.js";
8
+
9
+ /** Environment variable keys that override YAML values. */
10
+ const ENV = {
11
+ PORT: "ZCODE_PROXY_PORT",
12
+ PROXY_API_KEY: "ZCODE_PROXY_API_KEY",
13
+ PROVIDER: "ZCODE_PROVIDER",
14
+ APP_VERSION: "ZCODE_APP_VERSION",
15
+ SOURCE_TITLE: "ZCODE_SOURCE_TITLE",
16
+ REFERER_ORIGIN: "ZCODE_REFERER_ORIGIN",
17
+ ASYNC_ENABLED: "ZCODE_ASYNC_ENABLED",
18
+ ASYNC_ORIGIN: "ZCODE_ASYNC_ORIGIN",
19
+ ASYNC_MAX_RETRIES: "ZCODE_ASYNC_MAX_RETRIES",
20
+ ASYNC_MAX_WAIT_MS: "ZCODE_ASYNC_MAX_WAIT_MS",
21
+ CLAIM_ENABLED: "ZCODE_CLAIM_ENABLED",
22
+ CLAIM_AUTO: "ZCODE_CLAIM_AUTO",
23
+ CLAIM_ORIGIN: "ZCODE_CLAIM_ORIGIN",
24
+ CLAIM_POLL_INTERVAL_MS: "ZCODE_CLAIM_POLL_INTERVAL_MS",
25
+ ENDPOINT_ROUTING_ENABLED: "ZCODE_ENDPOINT_ROUTING",
26
+ CLIENT_SIGNING_ENABLED: "ZCODE_CLIENT_SIGNING",
27
+ } as const;
28
+
29
+ const DEFAULTS = {
30
+ PORT: 8080,
31
+ HOST: "0.0.0.0",
32
+ PROVIDER: "zai" as const,
33
+ PLAN: "coding-plan" as const,
34
+ DEFAULT_MODEL: "glm-4.6",
35
+ LOG_LEVEL: "info" as const,
36
+ ZAI_ANTHROPIC_BASE: "https://api.z.ai/api/anthropic",
37
+ ZAI_OPENAI_BASE: "https://api.z.ai/api/coding/paas/v4",
38
+ BIGMODEL_ANTHROPIC_BASE: "https://open.bigmodel.cn/api/anthropic",
39
+ BIGMODEL_OPENAI_BASE: "https://open.bigmodel.cn/api/coding/paas/v4",
40
+ APP_VERSION: "3.11.2",
41
+ SOURCE_TITLE: "cli",
42
+ REFERER_ORIGIN: "https://zcode.z.ai",
43
+ CLIENT_IDENTITY_MODE: "observe" as const,
44
+ CLIENT_IDENTITY_TTL_SECONDS: 900,
45
+ CLIENT_IDENTITY_MAX_SESSIONS: 1024,
46
+ RESPONSES_ENABLED: true,
47
+ RESPONSES_STORE_MAX_ENTRIES: 1000,
48
+ RESPONSES_STORE_TTL_MS: 24 * 60 * 60 * 1000,
49
+ MCP_ENABLED: true,
50
+ MCP_WEB_SEARCH: true,
51
+ MCP_WEB_READER: false,
52
+ MCP_ZREAD: false,
53
+ ASYNC_ENABLED: false,
54
+ ASYNC_ORIGIN: "https://zcode.z.ai",
55
+ ASYNC_POLL_INTERVAL_MS: 5000,
56
+ ASYNC_KEEPALIVE_INTERVAL_MS: 3000,
57
+ ASYNC_MAX_WAIT_MS: 0,
58
+ ASYNC_MAX_RETRIES: 3,
59
+ ASYNC_SETTLE_TIMEOUT_MS: 8000,
60
+ ASYNC_CONTROL_TIMEOUT_MS: 15000,
61
+ ASYNC_DEFAULT_MODEL: "",
62
+ CLAIM_ENABLED: true,
63
+ CLAIM_AUTO: true,
64
+ CLAIM_ORIGIN: "https://zcode.z.ai",
65
+ CLAIM_POLL_INTERVAL_MS: 300000,
66
+ CLAIM_COOLDOWN_MS: 600000,
67
+ CLAIM_PLAN_ID: "",
68
+ ENDPOINT_ROUTING_ENABLED: true,
69
+ ENDPOINT_ROUTING_ORIGIN: "https://zcode.z.ai",
70
+ CLIENT_SIGNING_ENABLED: true,
71
+ CLIENT_SIGNING_ORIGIN: "https://zcode.z.ai",
72
+ };
73
+
74
+ /** Printable-ASCII gate copied from the ZCode bundle's `rYn` helper. */
75
+ const ASCII_PRINTABLE = /^[\x20-\x7e]+$/;
76
+
77
+ /**
78
+ * Load and validate proxy configuration from a YAML file, applying env overrides.
79
+ * @throws Error if file not found or required fields are invalid.
80
+ */
81
+ export function loadConfig(path: string): ProxyConfig {
82
+ if (!existsSync(path)) {
83
+ throw new Error(`Config file not found: ${path}`);
84
+ }
85
+
86
+ const raw = readFileSync(path, "utf-8");
87
+ const parsed = parse(raw) ?? {};
88
+
89
+ // --- server ---
90
+ const port = resolvePort(process.env[ENV.PORT] ?? parsed?.server?.port);
91
+ const host = typeof parsed?.server?.host === "string" ? parsed.server.host : DEFAULTS.HOST;
92
+
93
+ // --- auth ---
94
+ const proxyApiKey = process.env[ENV.PROXY_API_KEY] ?? parsed?.auth?.proxyApiKey;
95
+ const oauthCredentialsPath = parsed?.auth?.oauthCredentialsPath;
96
+
97
+ // --- provider ---
98
+ const provider = resolveProvider(process.env[ENV.PROVIDER] ?? parsed?.provider);
99
+ const plan = resolvePlan(parsed?.plan);
100
+
101
+ // --- providers ---
102
+ const zai: ProviderEndpoints = {
103
+ anthropicBase: parsed?.providers?.zai?.anthropicBase ?? DEFAULTS.ZAI_ANTHROPIC_BASE,
104
+ openaiBase: parsed?.providers?.zai?.openaiBase ?? DEFAULTS.ZAI_OPENAI_BASE,
105
+ };
106
+ const bigmodel: ProviderEndpoints = {
107
+ anthropicBase: parsed?.providers?.bigmodel?.anthropicBase ?? DEFAULTS.BIGMODEL_ANTHROPIC_BASE,
108
+ openaiBase: parsed?.providers?.bigmodel?.openaiBase ?? DEFAULTS.BIGMODEL_OPENAI_BASE,
109
+ };
110
+
111
+ // --- models ---
112
+ const defaultModel = typeof parsed?.defaultModel === "string" ? parsed.defaultModel : DEFAULTS.DEFAULT_MODEL;
113
+ const models = Array.isArray(parsed?.models) ? parsed.models : [defaultModel];
114
+
115
+ // --- logging ---
116
+ const logLevel = resolveLogLevel(parsed?.logging?.level);
117
+
118
+ // --- identity ---
119
+ const identity = resolveIdentity({
120
+ appVersionEnv: process.env[ENV.APP_VERSION],
121
+ appVersionYaml: parsed?.identity?.appVersion,
122
+ sourceTitleEnv: process.env[ENV.SOURCE_TITLE],
123
+ sourceTitleYaml: parsed?.identity?.sourceTitle,
124
+ refererEnv: process.env[ENV.REFERER_ORIGIN],
125
+ refererYaml: parsed?.identity?.refererOrigin,
126
+ deviceMidYaml: parsed?.identity?.deviceMid,
127
+ });
128
+
129
+ const clientIdentity = resolveClientIdentity(parsed?.clientIdentity);
130
+ const responses = resolveResponsesConfig(parsed?.responses);
131
+ const mcp = resolveMcpConfig(parsed?.mcp);
132
+ const asyncCfg = resolveAsyncConfig(parsed?.async);
133
+ const claimCfg = resolveClaimConfig(parsed?.claim);
134
+ const endpointRouting = resolveEndpointRoutingConfig(parsed?.endpointRouting);
135
+ const clientSigning = resolveClientSigningConfig(parsed?.clientSigning);
136
+
137
+ const config: ProxyConfig = {
138
+ server: { port, host },
139
+ auth: { proxyApiKey, oauthCredentialsPath },
140
+ provider,
141
+ plan,
142
+ providers: { zai, bigmodel },
143
+ defaultModel,
144
+ models,
145
+ identity,
146
+ clientIdentity,
147
+ responses,
148
+ endpointRouting,
149
+ clientSigning,
150
+ mcp,
151
+ async: asyncCfg,
152
+ claim: claimCfg,
153
+ logging: { level: logLevel },
154
+ };
155
+
156
+ validate(config);
157
+ return config;
158
+ }
159
+
160
+ function resolveClientIdentity(raw: unknown): ClientIdentityConfig {
161
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
162
+ const mode = resolveClientIdentityMode(obj.mode);
163
+ const ttlSeconds = resolvePositiveInt(obj.ttlSeconds, DEFAULTS.CLIENT_IDENTITY_TTL_SECONDS, "clientIdentity.ttlSeconds");
164
+ const maxSessions = resolvePositiveInt(obj.maxSessions, DEFAULTS.CLIENT_IDENTITY_MAX_SESSIONS, "clientIdentity.maxSessions");
165
+ return { mode, ttlSeconds, maxSessions };
166
+ }
167
+
168
+ function resolveClientIdentityMode(raw: unknown): ClientIdentityConfig["mode"] {
169
+ if (raw === undefined || raw === null) return DEFAULTS.CLIENT_IDENTITY_MODE;
170
+ if (raw === "off" || raw === "observe" || raw === "enforce") return raw;
171
+ throw new Error(`Invalid clientIdentity.mode "${String(raw)}": must be "off", "observe", or "enforce"`);
172
+ }
173
+
174
+ function resolveResponsesConfig(raw: unknown): ResponsesConfig {
175
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
176
+ const storeRaw = obj.store && typeof obj.store === "object" ? obj.store as Record<string, unknown> : {};
177
+ return {
178
+ enabled: resolveBool(obj.enabled, DEFAULTS.RESPONSES_ENABLED),
179
+ storeMaxEntries: resolvePositiveInt(storeRaw.maxEntries, DEFAULTS.RESPONSES_STORE_MAX_ENTRIES, "responses.store.maxEntries"),
180
+ storeTtlMs: resolvePositiveInt(storeRaw.ttlMs, DEFAULTS.RESPONSES_STORE_TTL_MS, "responses.store.ttlMs"),
181
+ };
182
+ }
183
+
184
+ function resolveMcpConfig(raw: unknown): McpConfig {
185
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
186
+ return {
187
+ enabled: resolveBool(obj.enabled, DEFAULTS.MCP_ENABLED),
188
+ webSearch: resolveBool(obj.webSearch ?? obj.web_search, DEFAULTS.MCP_WEB_SEARCH),
189
+ webReader: resolveBool(obj.webReader ?? obj.web_reader, DEFAULTS.MCP_WEB_READER),
190
+ zread: resolveBool(obj.zread, DEFAULTS.MCP_ZREAD),
191
+ };
192
+ }
193
+
194
+ function resolveAsyncConfig(raw: unknown): AsyncConfig {
195
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
196
+ const enabledEnv = process.env[ENV.ASYNC_ENABLED];
197
+ const originEnv = process.env[ENV.ASYNC_ORIGIN];
198
+ const maxRetriesEnv = process.env[ENV.ASYNC_MAX_RETRIES];
199
+ const maxWaitMsEnv = process.env[ENV.ASYNC_MAX_WAIT_MS];
200
+
201
+ const origin = (originEnv ?? (typeof obj.origin === "string" ? obj.origin : DEFAULTS.ASYNC_ORIGIN)).trim() || DEFAULTS.ASYNC_ORIGIN;
202
+ validateOrigin(origin, "async.origin");
203
+
204
+ return {
205
+ enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.ASYNC_ENABLED) : resolveBool(obj.enabled, DEFAULTS.ASYNC_ENABLED),
206
+ origin,
207
+ pollIntervalMs: resolvePositiveInt(obj.pollIntervalMs ?? obj.poll_interval_ms, DEFAULTS.ASYNC_POLL_INTERVAL_MS, "async.pollIntervalMs"),
208
+ keepAliveIntervalMs: resolvePositiveInt(obj.keepAliveIntervalMs ?? obj.keepalive_interval_ms, DEFAULTS.ASYNC_KEEPALIVE_INTERVAL_MS, "async.keepAliveIntervalMs"),
209
+ maxWaitMs: resolveNonNegativeInt(maxWaitMsEnv ?? obj.maxWaitMs ?? obj.max_wait_ms, DEFAULTS.ASYNC_MAX_WAIT_MS, "async.maxWaitMs"),
210
+ maxRetries: resolveNonNegativeInt(maxRetriesEnv ?? obj.maxRetries ?? obj.max_retries, DEFAULTS.ASYNC_MAX_RETRIES, "async.maxRetries"),
211
+ settleTimeoutMs: resolvePositiveInt(obj.settleTimeoutMs ?? obj.settle_timeout_ms, DEFAULTS.ASYNC_SETTLE_TIMEOUT_MS, "async.settleTimeoutMs"),
212
+ controlTimeoutMs: resolvePositiveInt(obj.controlTimeoutMs ?? obj.control_timeout_ms, DEFAULTS.ASYNC_CONTROL_TIMEOUT_MS, "async.controlTimeoutMs"),
213
+ defaultModel: typeof obj.defaultModel === "string" ? obj.defaultModel : DEFAULTS.ASYNC_DEFAULT_MODEL,
214
+ };
215
+ }
216
+
217
+ function validateOrigin(origin: string, name: string): void {
218
+ let parsed: URL;
219
+ try {
220
+ parsed = new URL(origin);
221
+ } catch {
222
+ throw new Error(`${name} "${origin}" is not a valid URL`);
223
+ }
224
+ // Scheme allowlist: only http/https. Other schemes (ftp:, file:, etc.) rejected.
225
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
226
+ throw new Error(`${name} must use http: or https: scheme (got ${parsed.protocol})`);
227
+ }
228
+ // Cleartext HTTP only for loopback (dev/mock mode). Real off-peak backend requires
229
+ // HTTPS — cleartext would leak the JWT + coding-plan API key to any network observer.
230
+ const hostname = parsed.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets
231
+ const isLoopback = hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
232
+ if (parsed.protocol === "http:" && !isLoopback) {
233
+ throw new Error(`${name} http:// is only allowed for loopback hosts (got ${hostname}). Use https:// for remote origins.`);
234
+ }
235
+ if (parsed.username || parsed.password) {
236
+ throw new Error(`${name} must not contain userinfo`);
237
+ }
238
+ if (parsed.hash) {
239
+ throw new Error(`${name} must not contain a fragment`);
240
+ }
241
+ if (parsed.pathname !== "/" && parsed.pathname !== "") {
242
+ throw new Error(`${name} must not contain a path (got "${parsed.pathname}"); clients append their own paths`);
243
+ }
244
+ if (parsed.search) {
245
+ throw new Error(`${name} must not contain a query string`);
246
+ }
247
+ }
248
+
249
+ function resolveEndpointRoutingConfig(raw: unknown): EndpointRoutingConfig {
250
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
251
+ const enabledEnv = process.env[ENV.ENDPOINT_ROUTING_ENABLED];
252
+ const origin = (typeof obj.origin === "string" ? obj.origin : DEFAULTS.ENDPOINT_ROUTING_ORIGIN).trim()
253
+ || DEFAULTS.ENDPOINT_ROUTING_ORIGIN;
254
+ validateOrigin(origin, "endpointRouting.origin");
255
+ return {
256
+ enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.ENDPOINT_ROUTING_ENABLED) : resolveBool(obj.enabled, DEFAULTS.ENDPOINT_ROUTING_ENABLED),
257
+ origin,
258
+ };
259
+ }
260
+
261
+ function resolveClientSigningConfig(raw: unknown): ClientSigningConfig {
262
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
263
+ const enabledEnv = process.env[ENV.CLIENT_SIGNING_ENABLED];
264
+ const origin = (typeof obj.origin === "string" ? obj.origin : DEFAULTS.CLIENT_SIGNING_ORIGIN).trim()
265
+ || DEFAULTS.CLIENT_SIGNING_ORIGIN;
266
+ validateOrigin(origin, "clientSigning.origin");
267
+ return {
268
+ enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.CLIENT_SIGNING_ENABLED) : resolveBool(obj.enabled, DEFAULTS.CLIENT_SIGNING_ENABLED),
269
+ origin,
270
+ };
271
+ }
272
+
273
+ function resolveBool(raw: unknown, fallback: boolean): boolean {
274
+ if (typeof raw === "boolean") return raw;
275
+ if (typeof raw === "string") return raw === "true" || raw === "1";
276
+ return fallback;
277
+ }
278
+
279
+ function resolvePositiveInt(raw: unknown, fallback: number, name: string): number {
280
+ if (raw === undefined || raw === null) return fallback;
281
+ const n = typeof raw === "number" ? raw : parseInt(String(raw), 10);
282
+ if (!Number.isInteger(n) || n < 1) {
283
+ throw new Error(`${name} must be a positive integer`);
284
+ }
285
+ return n;
286
+ }
287
+
288
+ function resolveNonNegativeInt(raw: unknown, fallback: number, name: string): number {
289
+ if (raw === undefined || raw === null) return fallback;
290
+ const n = typeof raw === "number" ? raw : parseInt(String(raw), 10);
291
+ if (!Number.isInteger(n) || n < 0) {
292
+ throw new Error(`${name} must be a non-negative integer`);
293
+ }
294
+ return n;
295
+ }
296
+
297
+ /** Resolve port from raw value (YAML or env), defaulting to 8080. */
298
+ function resolvePort(raw: unknown): number {
299
+ if (raw === undefined || raw === null) return DEFAULTS.PORT;
300
+ const n = typeof raw === "number" ? raw : parseInt(String(raw), 10);
301
+ if (!Number.isFinite(n)) {
302
+ throw new Error("server.port must be a valid number");
303
+ }
304
+ return n;
305
+ }
306
+
307
+ /** Resolve and validate provider string. */
308
+ function resolveProvider(raw: unknown): "zai" | "bigmodel" {
309
+ const v = typeof raw === "string" ? raw : DEFAULTS.PROVIDER;
310
+ if (v !== "zai" && v !== "bigmodel") {
311
+ throw new Error(`Invalid provider "${v}": must be "zai" or "bigmodel"`);
312
+ }
313
+ return v;
314
+ }
315
+
316
+ /**
317
+ * Resolve and validate the plan tier. Mirrors `resolveProvider`'s hard
318
+ * validation style: an unrecognized value (e.g. `start_plan`/`startplan`
319
+ * typos) THROWS instead of silently falling back to coding-plan — a silent
320
+ * fallback sent users to the wrong upstream (401/403, no captcha/quota flow)
321
+ * with nothing pointing at the config typo.
322
+ */
323
+ function resolvePlan(raw: unknown): "coding-plan" | "start-plan" {
324
+ if (raw === undefined || raw === null) return DEFAULTS.PLAN;
325
+ if (raw === "coding-plan" || raw === "start-plan") return raw;
326
+ throw new Error(`Invalid plan "${String(raw)}": must be "coding-plan" or "start-plan"`);
327
+ }
328
+
329
+ /** Resolve log level with fallback. */
330
+ function resolveLogLevel(raw: unknown): "debug" | "info" | "warn" | "error" {
331
+ const levels = ["debug", "info", "warn", "error"] as const;
332
+ if (typeof raw === "string" && (levels as readonly string[]).includes(raw)) {
333
+ return raw as "debug" | "info" | "warn" | "error";
334
+ }
335
+ return DEFAULTS.LOG_LEVEL;
336
+ }
337
+
338
+ interface IdentityInputs {
339
+ appVersionEnv?: string;
340
+ appVersionYaml?: string;
341
+ sourceTitleEnv?: string;
342
+ sourceTitleYaml?: string;
343
+ refererEnv?: string;
344
+ refererYaml?: string;
345
+ deviceMidYaml?: string;
346
+ }
347
+
348
+ /** Resolve identity fields (env > YAML > default). Non-ASCII `appVersion` silently falls back to the default. */
349
+ function resolveIdentity(inp: IdentityInputs): ProxyIdentity {
350
+ const rawVersion = (inp.appVersionEnv ?? inp.appVersionYaml ?? DEFAULTS.APP_VERSION).trim();
351
+ const appVersion = ASCII_PRINTABLE.test(rawVersion) ? rawVersion : DEFAULTS.APP_VERSION;
352
+
353
+ const sourceTitle = (inp.sourceTitleEnv ?? inp.sourceTitleYaml ?? DEFAULTS.SOURCE_TITLE).trim()
354
+ || DEFAULTS.SOURCE_TITLE;
355
+
356
+ const refererOrigin = (inp.refererEnv ?? inp.refererYaml ?? DEFAULTS.REFERER_ORIGIN).trim()
357
+ || DEFAULTS.REFERER_ORIGIN;
358
+
359
+ const deviceMid = typeof inp.deviceMidYaml === "string" ? inp.deviceMidYaml.trim() : "";
360
+ return { appVersion, sourceTitle, refererOrigin, ...(deviceMid ? { deviceMid } : {}) };
361
+ }
362
+
363
+ /** Cross-field validation after all fields are resolved. */
364
+ function resolveClaimConfig(raw: unknown): ClaimConfig {
365
+ const obj = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
366
+ const enabledEnv = process.env[ENV.CLAIM_ENABLED];
367
+ const autoEnv = process.env[ENV.CLAIM_AUTO];
368
+ const originEnv = process.env[ENV.CLAIM_ORIGIN];
369
+ const pollIntervalEnv = process.env[ENV.CLAIM_POLL_INTERVAL_MS];
370
+
371
+ const origin = (originEnv ?? (typeof obj.origin === "string" ? obj.origin : DEFAULTS.CLAIM_ORIGIN)).trim() || DEFAULTS.CLAIM_ORIGIN;
372
+ validateOrigin(origin, "claim.origin");
373
+
374
+ return {
375
+ enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.CLAIM_ENABLED) : resolveBool(obj.enabled, DEFAULTS.CLAIM_ENABLED),
376
+ auto: autoEnv !== undefined ? resolveBool(autoEnv, DEFAULTS.CLAIM_AUTO) : resolveBool(obj.auto, DEFAULTS.CLAIM_AUTO),
377
+ origin,
378
+ pollIntervalMs: resolvePositiveInt(pollIntervalEnv ?? obj.pollIntervalMs ?? obj.poll_interval_ms, DEFAULTS.CLAIM_POLL_INTERVAL_MS, "claim.pollIntervalMs"),
379
+ cooldownMs: resolvePositiveInt(obj.cooldownMs ?? obj.cooldown_ms, DEFAULTS.CLAIM_COOLDOWN_MS, "claim.cooldownMs"),
380
+ planId: typeof obj.planId === "string" ? obj.planId.trim() : DEFAULTS.CLAIM_PLAN_ID,
381
+ };
382
+ }
383
+
384
+ function validate(config: ProxyConfig): void {
385
+ if (config.server.port < 1 || config.server.port > 65535) {
386
+ throw new Error(`server.port ${config.server.port} is out of range (1-65535)`);
387
+ }
388
+
389
+ if (!config.models.includes(config.defaultModel)) {
390
+ // defaultModel not in the models list — add it automatically
391
+ config.models.push(config.defaultModel);
392
+ }
393
+ }
src/config/template.ts ADDED
@@ -0,0 +1,109 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Bundled config template — inlined as a string constant so it compiles into
3
+ * the single-file binary (`bun build --compile`) without requiring a sidecar
4
+ * `config.example.yaml` file at runtime.
5
+ *
6
+ * Source of truth: config.example.yaml at repo root. When editing the schema,
7
+ * update BOTH this file AND config.example.yaml to keep them in sync.
8
+ */
9
+
10
+ export const EXAMPLE_CONFIG_YAML: string = `server:
11
+ port: 8080
12
+ host: "0.0.0.0"
13
+
14
+ auth:
15
+ # Key that clients must provide to use the proxy.
16
+ # Set to null/omit to disable client auth.
17
+ proxyApiKey: "your-proxy-secret"
18
+
19
+ # Upstream credentials come from the OAuth login flow — run this first:
20
+ # bun run src/index.ts auth login <zai|bigmodel>
21
+ # Parsed but currently not honored — the credential store path is fixed at
22
+ # ~/.zcode-proxy/credentials.json:
23
+ # oauthCredentialsPath: "~/.zcode-proxy/credentials.json"
24
+
25
+ # Which upstream provider to use: "zai" or "bigmodel"
26
+ provider: zai
27
+
28
+ # Which plan tier to use:
29
+ # "coding-plan" (default) — direct upstream endpoints, permanent API key
30
+ # "start-plan" — routes through zcode.z.ai with JWT auth (requires \`auth login\`)
31
+ plan: coding-plan
32
+
33
+ providers:
34
+ zai:
35
+ anthropicBase: "https://api.z.ai/api/anthropic"
36
+ openaiBase: "https://api.z.ai/api/coding/paas/v4"
37
+ bigmodel:
38
+ anthropicBase: "https://open.bigmodel.cn/api/anthropic"
39
+ openaiBase: "https://open.bigmodel.cn/api/coding/paas/v4"
40
+
41
+ defaultModel: glm-4.6
42
+
43
+ models:
44
+ - glm-4.5-air
45
+ - glm-4.6
46
+ - glm-4.6v
47
+ - glm-4.7
48
+ - glm-5
49
+ - glm-5-turbo
50
+ - glm-5v-turbo
51
+ - glm-5.1
52
+ - glm-5.2
53
+ - glm-5.3
54
+ - glm-5.3-flash
55
+
56
+ # Configurable identity headers injected on every upstream request to mimic the
57
+ # ZCode desktop client (User-Agent, X-ZCode-App-Version, X-Title,
58
+ # X-ZCode-Agent, HTTP-Referer). Runtime platform headers (X-Platform,
59
+ # X-Os-Category, X-Os-Version) are detected dynamically and are not configured
60
+ # here. All fields below are optional; env vars override YAML, which overrides
61
+ # defaults.
62
+ identity:
63
+ # Mirrors process.env.ZCODE_APP_VERSION in the ZCode bundle.
64
+ # Must be printable ASCII; non-conforming values fall back to the default.
65
+ # Default: "3.11.2" (current ZCode release). Override to match your real client.
66
+ appVersion: "3.11.2"
67
+ # X-Title suffix → "Z Code@{sourceTitle}". Default "cli".
68
+ sourceTitle: "cli"
69
+ # HTTP-Referer URL. Default "https://zcode.z.ai".
70
+ refererOrigin: "https://zcode.z.ai"
71
+ # Device identity (X-Device-Mid) — random UUIDv4, generated ONCE and reused
72
+ # forever (mirrors ZCode's telemetry deviceMid; no hardware values involved).
73
+ # Auto-generated into this file at first \`auth login\` or config creation.
74
+ # Leave empty on Android — the app injects ZCODE_IDENTITY_DEVICE_MID instead.
75
+ deviceMid: ""
76
+
77
+ # Local client-session inference for cache-affinity experiments.
78
+ # "observe" (default) logs inferred sessions in debug mode but does not change
79
+ # upstream x-session-id. "enforce" reuses a stable x-session-id for inferred
80
+ # coding-plan sessions. "off" disables inference entirely.
81
+ clientIdentity:
82
+ mode: observe
83
+ ttlSeconds: 900
84
+ maxSessions: 1024
85
+
86
+ # Server-controlled upstream URL remapping (mirrors the ZCode client's
87
+ # ProviderEndpointRoutingService). The proxy periodically fetches
88
+ # {origin}/api/v1/agent/configs and rewrites matching upstream URLs per the
89
+ # returned proxyEndpoint.mapping table (currently the coding-plan Anthropic
90
+ # endpoints -> zcode.z.ai ultra endpoints). Fail-open: any fetch/parse error
91
+ # keeps the original URLs. Env override: ZCODE_ENDPOINT_ROUTING=false.
92
+ endpointRouting:
93
+ enabled: true
94
+ origin: "https://zcode.z.ai"
95
+
96
+ # Client request signing V4 (mirrors the ZCode 3.9.1 ClientRequestSigningV4Signer).
97
+ # When enabled, the proxy probes {origin}/api/v1/agent/configs (cached 1h) and,
98
+ # only if the server sets data.codingPlanSignature.enable=true, signs coding-plan
99
+ # requests: handshake against {provider}/api/paas/c1f3a7e2/v2/client, Ed25519
100
+ # signature + proof-of-work headers on every request, fail-open retry ladder
101
+ # (two 401 VERIFY rejections -> permanent unsigned bypass). Start-plan and
102
+ # off-peak paths are never signed. Env override: ZCODE_CLIENT_SIGNING=false.
103
+ clientSigning:
104
+ enabled: true
105
+ origin: "https://zcode.z.ai"
106
+
107
+ logging:
108
+ level: info
109
+ `;
src/config/types.ts ADDED
@@ -0,0 +1,222 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Configuration types for zcode-proxy.
3
+ * @see .omo/plans/zcode-proxy.md Task 2
4
+ */
5
+
6
+ /** Provider endpoint configuration (one per upstream provider). */
7
+ export interface ProviderEndpoints {
8
+ /** Base URL for Anthropic-format API, e.g. "https://api.z.ai/api/anthropic". */
9
+ anthropicBase: string;
10
+ /** Base URL for OpenAI-format API, e.g. "https://api.z.ai/api/coding/paas/v4". */
11
+ openaiBase: string;
12
+ }
13
+
14
+ /** Auth section of the proxy configuration. */
15
+ interface AuthConfig {
16
+ /**
17
+ * Key that clients must provide to use the proxy (via `Authorization: Bearer {proxyApiKey}`).
18
+ * If unset, the proxy does not require client auth.
19
+ */
20
+ proxyApiKey?: string;
21
+ /** Path to stored OAuth credentials created by `auth login`. */
22
+ oauthCredentialsPath?: string;
23
+ }
24
+
25
+ /**
26
+ * Identity headers injected on every upstream request to mimic the ZCode
27
+ * desktop client. Mirrors the `pio` builder in the reverse-engineered bundle
28
+ * (`_reverse/zcode.cjs`); see `_reverse/NOTEPAD.md` "How Credential is Used".
29
+ *
30
+ * Resolution: env var (matches ZCode's own convention) → YAML override → default.
31
+ * `appVersion` must be printable ASCII (`/^[\x20-\x7e]+$/`); non-conforming
32
+ * values are silently dropped and fall back to the default (current ZCode
33
+ * release), exactly like `fio` in the bundle.
34
+ */
35
+ export interface ProxyIdentity {
36
+ appVersion: string;
37
+ sourceTitle: string;
38
+ refererOrigin: string;
39
+ /**
40
+ * Device identity for `X-Device-Mid` (mirrors ZCode's telemetry deviceMid:
41
+ * a random UUIDv4 generated ONCE and reused forever — no hardware values).
42
+ * Empty/undefined omits the header. Desktop: persisted in config.yaml
43
+ * (`ensureDeviceMidInConfig`). Android: injected via the
44
+ * `ZCODE_IDENTITY_DEVICE_MID` env var (NodeRunner, app-private file) — env
45
+ * wins over YAML. Must stay stable per anti-pattern #13; never randomize
46
+ * per-request.
47
+ */
48
+ deviceMid?: string;
49
+ }
50
+
51
+ /** Local client-session inference mode for upstream session affinity. */
52
+ export interface ClientIdentityConfig {
53
+ /** "observe" logs/instruments only; "enforce" reuses upstream x-session-id; "off" disables inference. */
54
+ mode: "off" | "observe" | "enforce";
55
+ /** In-memory session TTL in seconds. */
56
+ ttlSeconds: number;
57
+ /** Maximum number of inferred sessions retained in memory. */
58
+ maxSessions: number;
59
+ }
60
+
61
+ /**
62
+ * Responses-API (`/v1/responses`) configuration. When `enabled`, the proxy
63
+ * translates Codex-style Responses requests to the GLM Chat Completions upstream.
64
+ */
65
+ export interface ResponsesConfig {
66
+ /** Enable the `/v1/responses` route. Default `true`. */
67
+ enabled: boolean;
68
+ /** Max stored responses (LRU). Default 1000. */
69
+ storeMaxEntries: number;
70
+ /** Stored-response TTL in ms. Default 24h (in-memory; cleared on restart). */
71
+ storeTtlMs: number;
72
+ }
73
+
74
+ /** GLM MCP hosted-tool configuration. Endpoints are derived from the active provider. */
75
+ export interface McpConfig {
76
+ /** Enable MCP interception (web_search) and function-tool injection (web_reader/zread). Default `true`. */
77
+ enabled: boolean;
78
+ /** Intercept `web_search` / `web_search_preview` hosted tools via GLM `web_search_prime` MCP. Default `true`. */
79
+ webSearch: boolean;
80
+ /** Inject `webReader` as a function tool the model can call. Default `false` (off by default to limit scope). */
81
+ webReader: boolean;
82
+ /** Inject the three `zread` tools as function tools. Default `false`. */
83
+ zread: boolean;
84
+ }
85
+
86
+ /**
87
+ * Async (off-peak / idle-plan) bridge configuration. When `enabled`, exposes
88
+ * `/async/v1/messages` and `/async/v1/chat/completions` that route to ZCode's
89
+ * off-peak ticket-queue backend. The proxy keeps the client connection alive
90
+ * with SSE comments during ticket-queue wait, forwards the LLM stream once
91
+ * the ticket is `ready`, and auto-retries on ticket-expired (up to `maxRetries`).
92
+ *
93
+ * Requires a logged-in oauth credential (off-peak needs both
94
+ * `Authorization: Bearer ${jwt}` and `X-Coding-Plan-Api-Key` headers). A
95
+ * credential lacking the JWT makes the route entry return 400
96
+ * `async_credentials_unavailable`.
97
+ *
98
+ * @see _reverse/NOTEPAD.md "Off-Peak / Idle Plan" section for full upstream protocol.
99
+ */
100
+ export interface AsyncConfig {
101
+ /** Enable the `/async/*` routes. Default `false`. */
102
+ enabled: boolean;
103
+ /** Base origin for off-peak endpoints. Default `"https://zcode.z.ai"`. */
104
+ origin: string;
105
+ /** Ticket-status poll interval in ms. Default `5000`. */
106
+ pollIntervalMs: number;
107
+ /** SSE keepalive comment interval during ticket-queue wait, in ms. Default `3000`. */
108
+ keepAliveIntervalMs: number;
109
+ /** Maximum total wait time for a ticket to become `ready`, in ms. `0` = unlimited. Default `0`. */
110
+ maxWaitMs: number;
111
+ /** Maximum auto-retry count on `off-peak-ticket-expired`. Default `3`. */
112
+ maxRetries: number;
113
+ /** Settle call timeout in ms (best-effort close-out on completion/abort). Default `8000`. */
114
+ settleTimeoutMs: number;
115
+ /** Control-plane call (takeTicket/pollStatus) timeout in ms. Default `15000`. */
116
+ controlTimeoutMs: number;
117
+ /** Optional model override; empty string uses the request's `model`. Default `""`. */
118
+ defaultModel: string;
119
+ }
120
+
121
+ /**
122
+ * Manual claim ("weekend plan") — mirrors the ZCode 3.10 desktop client's
123
+ * `manualClaimPlan` feature: periodically list claimable trial plans
124
+ * (`GET {origin}/api/v1/zcode-plan/billing/preview`) and, when one is
125
+ * available, claim it (`POST {origin}/api/v1/zcode-plan/billing/claim`) with
126
+ * the OAuth JWT and an Aliyun captcha token. Claimed plans grant Start-Plan
127
+ * style quota with delayed activation (`effective_at` / `starts_at`).
128
+ *
129
+ * Requires `auth.mode: oauth` (claim uses `Authorization: Bearer ${jwt}`).
130
+ *
131
+ * @see _reverse/NOTEPAD.md "Manual Claim Plan" section for the protocol.
132
+ */
133
+ export interface ClaimConfig {
134
+ /** Enable the claim subsystem (CLI `claim` command + auto scheduler). Default `true`. */
135
+ enabled: boolean;
136
+ /** Auto-claim in the background while the proxy is serving. Default `true` (effective when `enabled`). */
137
+ auto: boolean;
138
+ /** Base origin of the zcode-plan billing endpoints. Default `"https://zcode.z.ai"`. */
139
+ origin: string;
140
+ /** Preview poll interval in ms. Default `300000` (5 min). */
141
+ pollIntervalMs: number;
142
+ /** Backoff after a failed claim attempt in ms. Default `600000` (10 min). */
143
+ cooldownMs: number;
144
+ /** Optional `plan_id` to claim; empty string claims the highest-priority preview. Default `""`. */
145
+ planId: string;
146
+ }
147
+
148
+ /**
149
+ * Provider endpoint routing — mirrors the ZCode client's
150
+ * `ProviderEndpointRoutingService`: periodically fetch
151
+ * `GET {configUrl}/api/v1/agent/configs` and rewrite matching upstream URLs
152
+ * per the server-controlled `data.proxyEndpoint.mapping` table. As of
153
+ * 2026-08-19 only the coding-plan Anthropic endpoints are mapped (to
154
+ * `zcode.z.ai/api/v1/ultra[-zai]/...`); resolution is generic so future
155
+ * entries apply automatically. Always fail-open.
156
+ */
157
+ export interface EndpointRoutingConfig {
158
+ /** Enable URL remapping. Default `true`. */
159
+ enabled: boolean;
160
+ /** Base origin of the agent-configs endpoint. Default `"https://zcode.z.ai"`. */
161
+ origin: string;
162
+ }
163
+
164
+ /**
165
+ * Client request signing V4 — mirrors the ZCode 3.9.1
166
+ * `ClientRequestSigningV4Signer`. When enabled, the proxy probes the same
167
+ * feature gate the client uses (`GET {origin}/api/v1/agent/configs` →
168
+ * `data.codingPlanSignature.enable`) and, only if the server turns the feature
169
+ * on, signs coding-plan upstream requests (handshake + Ed25519 + proof-of-work,
170
+ * with the client's fail-open retry ladder). Start-plan and off-peak paths are
171
+ * permanently exempt.
172
+ */
173
+ export interface ClientSigningConfig {
174
+ /** Enable gate probing + signing. Default `true`. */
175
+ enabled: boolean;
176
+ /** Base origin of the feature-gate endpoint. Default `"https://zcode.z.ai"`. */
177
+ origin: string;
178
+ }
179
+
180
+ /** Top-level proxy configuration. */
181
+ export interface ProxyConfig {
182
+ server: {
183
+ port: number;
184
+ host: string;
185
+ };
186
+ auth: AuthConfig;
187
+ /** Active upstream provider. */
188
+ provider: "zai" | "bigmodel";
189
+ /** Which plan tier to use. "coding-plan" (default) uses direct upstream endpoints; "start-plan" routes through zcode.z.ai with JWT auth. */
190
+ plan: "coding-plan" | "start-plan";
191
+ /** Per-provider endpoint overrides. */
192
+ providers: {
193
+ zai: ProviderEndpoints;
194
+ bigmodel: ProviderEndpoints;
195
+ };
196
+ /** Default model id used when client request omits `model`. */
197
+ defaultModel: string;
198
+ /** Whitelist of allowed model ids. */
199
+ models: string[];
200
+ /**
201
+ * Identity headers injected upstream. Always present after `loadConfig`;
202
+ * defaults mirror the production ZCode desktop client.
203
+ */
204
+ identity: ProxyIdentity;
205
+ /** Local client session inference for cache-affinity experiments. */
206
+ clientIdentity: ClientIdentityConfig;
207
+ /** Responses-API (`/v1/responses`) configuration. */
208
+ responses: ResponsesConfig;
209
+ /** Server-controlled upstream URL remapping (ultra endpoints). */
210
+ endpointRouting: EndpointRoutingConfig;
211
+ /** Client request signing V4 (Ed25519 + PoW, gate-driven). */
212
+ clientSigning: ClientSigningConfig;
213
+ /** GLM MCP hosted-tool configuration. */
214
+ mcp: McpConfig;
215
+ /** Async (off-peak / idle-plan) bridge configuration. */
216
+ async: AsyncConfig;
217
+ /** Manual claim ("weekend plan") configuration. */
218
+ claim: ClaimConfig;
219
+ logging: {
220
+ level: "debug" | "info" | "warn" | "error";
221
+ };
222
+ }
src/index.ts ADDED
@@ -0,0 +1,596 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Entry point — load config, create auth manager, start proxy server.
3
+ * @see .omo/plans/zcode-proxy.md Task 7
4
+ */
5
+ import { loadConfig } from "./config/loader.js";
6
+ import { AuthManager } from "./auth/manager.js";
7
+ import { startServer, type ProxyServer } from "./server/server.js";
8
+ import { startControlListener, LogBuffer, type ControlState } from "./android/control.js";
9
+ import { loadCredential, saveCredential, clearCredential, getStorePath } from "./auth/store.js";
10
+ import { ZaiOAuthClient, BigmodelOAuthClient, LOGIN_TIMEOUT_MS, parsePastedCallbackUrl, type OAuthResult } from "./auth/oauth.js";
11
+ import { KeyResolver } from "./auth/resolver.js";
12
+ import type { Credential } from "./auth/types.js";
13
+ import type { ProviderId } from "./provider/types.js";
14
+ import type { ProxyConfig } from "./config/types.js";
15
+ import { updateConfigYaml, ensureConfigFile } from "./config/edit.js";
16
+ import { openBrowser } from "./runtime/open-browser.js";
17
+ import { pasteLoginInstructions, readPastedLine, boldIfTTY } from "./runtime/paste-login.js";
18
+ import { buildServerOptions } from "./server/server-options.js";
19
+ import { readFileSync, existsSync, writeFileSync } from "node:fs";
20
+ import { join } from "node:path";
21
+ import { homedir } from "node:os";
22
+ import { randomUUID } from "node:crypto";
23
+ import { ensureNodeFetchNoTimeouts } from "./runtime/node-fetch-compat.js";
24
+
25
+ export const VERSION = "4.6.3";
26
+
27
+ if (require.main === module) main();
28
+
29
+ export interface ServeArgs {
30
+ configPath?: string;
31
+ debug: boolean;
32
+ }
33
+
34
+ /**
35
+ * Parse `serve` subcommand arguments. The token `debug` toggles debug mode;
36
+ * any other token is treated as the config path. Order-independent:
37
+ * [] → { debug: false }
38
+ * ["debug"] → { debug: true }
39
+ * ["my.yaml"] → { configPath: "my.yaml", debug: false }
40
+ * ["debug","x.yaml"] → { configPath: "x.yaml", debug: true }
41
+ * ["x.yaml","debug"] → { configPath: "x.yaml", debug: true }
42
+ */
43
+ export function parseServeArgs(args: string[]): ServeArgs {
44
+ const debug = args.includes("debug");
45
+ const configPath = args.find((a) => a !== "debug");
46
+ return { configPath, debug };
47
+ }
48
+
49
+ export function main(): void {
50
+ // Fire-and-forget is race-safe: the dynamic import resolves in a microtask,
51
+ // before the listener's event-loop callback can admit a request.
52
+ void ensureNodeFetchNoTimeouts();
53
+ try {
54
+ runCli();
55
+ } catch (err) {
56
+ process.stderr.write(`zcode-proxy: uncaught error: ${(err as Error).stack ?? String(err)}\n`);
57
+ process.exit(1);
58
+ }
59
+ }
60
+
61
+ function runCli(): void {
62
+ const args = process.argv.slice(2);
63
+
64
+ // `--cli` opts out of the default TUI and restores the classic CLI dispatch
65
+ // (bare `--cli` = the old no-arg default: serve).
66
+ if (args[0] === "--cli") {
67
+ dispatchCli(args.slice(1));
68
+ return;
69
+ }
70
+ // Default surface is the TUI. Bare invocation, the retired `tui` token
71
+ // (kept as a silent alias), and tui-style args (`debug`, `*.yaml`) all land
72
+ // here — the former `tui <args>` subcommand simply dropped its prefix.
73
+ if (
74
+ args.length === 0 ||
75
+ args[0] === "tui" ||
76
+ args[0] === "debug" ||
77
+ args[0].endsWith(".yaml") ||
78
+ args[0].endsWith(".yml")
79
+ ) {
80
+ launchTui(parseServeArgs(args[0] === "tui" ? args.slice(1) : args));
81
+ return;
82
+ }
83
+ dispatchCli(args);
84
+ }
85
+
86
+ /** Classic CLI dispatch — subcommand routing where bare = serve. */
87
+ function dispatchCli(args: string[]): void {
88
+ const cmd = args[0] ?? "serve";
89
+
90
+ if (cmd === "auth") {
91
+ authCommand(args.slice(1));
92
+ } else if (cmd === "claim") {
93
+ void claimCommand(args.slice(1));
94
+ } else if (cmd === "android") {
95
+ // Explicit catch: an async startup failure (e.g. control port already
96
+ // bound by an orphaned process) must exit non-zero deterministically, not
97
+ // surface as an unhandled rejection.
98
+ runAndroid().catch((err: unknown) => {
99
+ process.stderr.write(`zcode-proxy: android entry failed: ${(err as Error).stack ?? String(err)}\n`);
100
+ process.exit(1);
101
+ });
102
+ } else if (cmd === "tui") {
103
+ // Kept for muscle memory under `--cli`: the default dispatch already
104
+ // routes `tui` to the TUI, but `--cli tui` should not regress to an error.
105
+ launchTui(parseServeArgs(args.slice(1)));
106
+ } else if (cmd === "serve" || cmd.endsWith(".yaml") || cmd.endsWith(".yml")) {
107
+ const serveArgs = cmd === "serve"
108
+ ? parseServeArgs(args.slice(1))
109
+ : parseServeArgs(args);
110
+ serve(serveArgs.configPath, serveArgs.debug);
111
+ } else if (cmd === "version" || cmd === "--version" || cmd === "-v") {
112
+ console.log(`zcode-proxy ${VERSION}`);
113
+ } else if (cmd === "help" || cmd === "--help" || cmd === "-h") {
114
+ printHelp();
115
+ } else {
116
+ console.error(`Unknown command: ${cmd}\n`);
117
+ printHelp();
118
+ process.exit(1);
119
+ }
120
+ }
121
+
122
+ function launchTui(args: ServeArgs): void {
123
+ // Dynamic import: the TUI module imports helpers back from this file, so a
124
+ // static edge would create a load-time cycle (same pattern as claimCommand).
125
+ import("./tui/app.js")
126
+ .then((m) => m.runTui(args))
127
+ .catch((err: unknown) => {
128
+ process.stderr.write(`zcode-proxy: tui failed: ${(err as Error).stack ?? String(err)}\n`);
129
+ process.exit(1);
130
+ });
131
+ }
132
+
133
+ function printHelp(): void {
134
+ console.log(`zcode-proxy ${VERSION}
135
+
136
+ Usage:
137
+ zcode-proxy Interactive terminal UI (default):
138
+ login, start/stop, live logs
139
+ zcode-proxy [debug] [config.yaml] Same, with debug diagnostics / custom config
140
+ zcode-proxy serve [config.yaml] Start the proxy server (classic CLI mode)
141
+ zcode-proxy serve debug [config.yaml]
142
+ Start with verbose per-request diagnostics
143
+ zcode-proxy --cli Classic CLI mode (bare --cli = serve)
144
+ zcode-proxy android Android entry: proxy + localhost control listener
145
+ zcode-proxy auth login <provider> Login via OAuth (provider: zai | bigmodel)
146
+ zcode-proxy auth login <provider> --import
147
+ Import API key from ~/.zcode/v2/config.json
148
+ zcode-proxy auth logout Clear stored credentials
149
+ zcode-proxy auth status Show current authentication state
150
+ zcode-proxy claim [list|now] List / claim weekend-plan trial packages
151
+ zcode-proxy version Show version
152
+ zcode-proxy help Show this help
153
+
154
+ Examples:
155
+ zcode-proxy Terminal UI: login, start/stop, live logs
156
+ zcode-proxy debug Terminal UI with per-request diagnostics
157
+ zcode-proxy serve debug CLI: start with extra debug logging
158
+ zcode-proxy auth login bigmodel OAuth login for Bigmodel
159
+ zcode-proxy auth login bigmodel --import
160
+ Import existing key from ZCode config
161
+ zcode-proxy auth status Check if logged in
162
+ `);
163
+ }
164
+
165
+ async function serve(configPath: string | undefined, debug: boolean): Promise<void> {
166
+ const path = configPath ?? process.env.ZCODE_PROXY_CONFIG ?? "config.yaml";
167
+ if (ensureConfigFile(path)) {
168
+ ensureDeviceMidInConfig(path);
169
+ console.log(`Created ${path} from bundled template.`);
170
+ console.log(`Run: zcode-proxy auth login <zai|bigmodel>\n`);
171
+ }
172
+ const config = loadConfig(path);
173
+
174
+ const auth = new AuthManager();
175
+ const cred = await loadCredential();
176
+ if (!cred) {
177
+ console.error("Not logged in. Run: zcode-proxy auth login " + config.provider);
178
+ process.exit(1);
179
+ }
180
+ auth.setOAuthCredential(cred);
181
+
182
+ if (debug) printDebugBanner(config, path, cred);
183
+
184
+ const server = await startServer(buildServerOptions(config, auth, debug));
185
+ const url = `http://${server.hostname}:${server.port}`;
186
+ console.log(`zcode-proxy listening on ${url}`);
187
+ if (config.plan === "start-plan") {
188
+ // Pre-solve the captcha token pool in the background so first requests
189
+ // don't pay the full solve latency (in-process happy-dom backend).
190
+ import("./proxy/captcha.js")
191
+ .then((m) => m.startCaptchaPool(config.identity.appVersion))
192
+ .catch((err) => console.error(`[captcha] pool warmup failed: ${(err as Error).message}`));
193
+ }
194
+ if (config.claim.enabled && config.claim.auto) {
195
+ import("./claim/runtime.js")
196
+ .then((m) => {
197
+ m.startAutoClaim(config, auth);
198
+ console.log(` claim: auto ON (poll ${Math.round(config.claim.pollIntervalMs / 1000)}s)`);
199
+ })
200
+ .catch((err) => console.error(`[claim] scheduler failed to start: ${(err as Error).message}`));
201
+ }
202
+ console.log(` provider: ${config.provider}`);
203
+ console.log(` plan: ${config.plan}`);
204
+ console.log(` models: ${config.models.length} available`);
205
+ if (config.responses.enabled) console.log(` /v1/responses: ON`);
206
+ if (config.async.enabled) {
207
+ console.log(config.plan === "coding-plan" ? ` /async/v1/*: ON` : ` /async/v1/*: OFF (requires plan "coding-plan")`);
208
+ }
209
+ if (debug) console.log(` debug: ON`);
210
+
211
+ process.on("SIGINT", () => {
212
+ console.log("\nShutting down...");
213
+ server.stop(true);
214
+ });
215
+ process.on("SIGTERM", () => {
216
+ server.stop(true);
217
+ });
218
+ }
219
+
220
+ /**
221
+ * Desktop-Linux identity defaults for the Android entry (anti-pattern #34).
222
+ * Without these, the Node process on Android reports its true host values:
223
+ * `X-Platform: linux-arm64` and `X-Os-Version: 6.1.xx-android14-…` — a kernel
224
+ * string no real ZCode desktop emits. `identity.ts` reads these env vars per
225
+ * request, so setting them once here retargets every upstream call. Values are
226
+ * deliberately CONSTANT (Ubuntu 24.04 x64 profile — the largest desktop-Linux
227
+ * population): kernel strings are shared by millions of real machines, and
228
+ * stability is required by anti-pattern #13 (never randomize fingerprints).
229
+ * Explicit env values (adb shell setprop / NodeRunner) still win — each is set
230
+ * with `??`, not unconditionally.
231
+ */
232
+ export function applyAndroidIdentityDefaults(): void {
233
+ process.env.ZCODE_IDENTITY_PLATFORM = process.env.ZCODE_IDENTITY_PLATFORM ?? "linux";
234
+ process.env.ZCODE_IDENTITY_ARCH = process.env.ZCODE_IDENTITY_ARCH ?? "x64";
235
+ process.env.ZCODE_IDENTITY_RELEASE = process.env.ZCODE_IDENTITY_RELEASE ?? "6.8.0-49-generic";
236
+ }
237
+
238
+ /**
239
+ * Android entry — starts the proxy plus a localhost control listener.
240
+ * Caller (Kotlin shell) must set env: ZCODE_CONTROL_PORT (control listener),
241
+ * ZCODE_OAUTH_CALLBACK_PORT (fixed OAuth callback port for WebView redirect).
242
+ */
243
+ async function runAndroid(): Promise<void> {
244
+ applyAndroidIdentityDefaults();
245
+ const path = process.env.ZCODE_PROXY_CONFIG ?? "config.yaml";
246
+ ensureConfigFile(path);
247
+ const config = loadConfig(path);
248
+
249
+ const logBuffer = new LogBuffer();
250
+ const origLog = console.log;
251
+ const origErr = console.error;
252
+ const origWarn = console.warn;
253
+ console.log = (...args: unknown[]) => { logBuffer.push(args.join(" ")); origLog(...args); };
254
+ console.error = (...args: unknown[]) => { logBuffer.push("[error] " + args.join(" ")); origErr(...args); };
255
+ console.warn = (...args: unknown[]) => { logBuffer.push("[warn] " + args.join(" ")); origWarn(...args); };
256
+
257
+ const auth = new AuthManager();
258
+
259
+ const serverRef: { current: ProxyServer | null } = { current: null };
260
+
261
+ async function startProxy(): Promise<{ ok: true; port: number } | { ok: false; error: string }> {
262
+ if (serverRef.current) return { ok: false, error: "already_running" };
263
+ const cred = await loadCredential().catch(() => null);
264
+ if (!cred) return { ok: false, error: "not_logged_in" };
265
+ auth.setOAuthCredential(cred);
266
+ try {
267
+ const s = await startServer(buildServerOptions(config, auth, false));
268
+ serverRef.current = s;
269
+ console.log(`zcode-proxy listening on http://${s.hostname}:${s.port}`);
270
+ return { ok: true, port: s.port };
271
+ } catch (err) {
272
+ return { ok: false, error: (err as Error).message };
273
+ }
274
+ }
275
+
276
+ async function stopProxy(): Promise<{ ok: true } | { ok: false; error: string }> {
277
+ const s = serverRef.current;
278
+ if (!s) return { ok: false, error: "not_running" };
279
+ try {
280
+ s.stop(false);
281
+ serverRef.current = null;
282
+ console.log("zcode-proxy stopped");
283
+ return { ok: true };
284
+ } catch (err) {
285
+ return { ok: false, error: (err as Error).message };
286
+ }
287
+ }
288
+
289
+ async function setConfig(changes: {
290
+ provider?: ProviderId;
291
+ plan?: "coding-plan" | "start-plan";
292
+ }): Promise<{ ok: true; provider: ProviderId; plan: "coding-plan" | "start-plan" } | { ok: false; error: string }> {
293
+ if (serverRef.current) return { ok: false, error: "stop_proxy_first" };
294
+ if (changes.provider) config.provider = changes.provider;
295
+ if (changes.plan) config.plan = changes.plan;
296
+ updateConfigYaml(path, { provider: config.provider, plan: config.plan });
297
+ console.log(`config updated: provider=${config.provider} plan=${config.plan}`);
298
+ return { ok: true, provider: config.provider, plan: config.plan };
299
+ }
300
+
301
+ console.log("control listener ready; proxy stopped — use startProxy command to start");
302
+
303
+ if (config.claim.enabled && config.claim.auto) {
304
+ import("./claim/runtime.js")
305
+ .then((m) => {
306
+ m.startAutoClaim(config, auth);
307
+ console.log(`[claim] auto ON (poll ${Math.round(config.claim.pollIntervalMs / 1000)}s; waits for login)`);
308
+ })
309
+ .catch((err) => console.error(`[claim] scheduler failed to start: ${(err as Error).message}`));
310
+ }
311
+
312
+ const controlPort = Number(process.env.ZCODE_CONTROL_PORT ?? 0) || 0;
313
+ const controlState: ControlState = {
314
+ provider: config.provider,
315
+ plan: config.plan,
316
+ proxyPort: serverRef.current?.port ?? 0,
317
+ };
318
+ const controlListener = await startControlListener({
319
+ port: controlPort,
320
+ state: controlState,
321
+ logBuffer,
322
+ onStartProxy: startProxy,
323
+ onStopProxy: stopProxy,
324
+ onSetConfig: setConfig,
325
+ onShutdown: async () => {
326
+ serverRef.current?.stop(true);
327
+ },
328
+ });
329
+
330
+ console.log(`control listener: 127.0.0.1:${controlPort}`);
331
+ console.log(`provider: ${config.provider}`);
332
+ console.log(`plan: ${config.plan}`);
333
+
334
+ process.on("SIGINT", () => {
335
+ void controlListener.close().then(() => serverRef.current?.stop(true));
336
+ });
337
+ process.on("SIGTERM", () => {
338
+ void controlListener.close().then(() => serverRef.current?.stop(true));
339
+ });
340
+ }
341
+
342
+ function printDebugBanner(config: ProxyConfig, path: string, cred: Credential | null): void {
343
+ const credShape = cred
344
+ ? `${cred.apiKey.slice(0, 6)}...${cred.apiKey.slice(-4)} (${cred.apiKey.length} chars)`
345
+ : "(none)";
346
+ const active = config.providers[config.provider];
347
+ console.log("=== zcode-proxy DEBUG MODE ===");
348
+ console.log(` config file: ${path}`);
349
+ console.log(` server: ${config.server.host}:${config.server.port}`);
350
+ console.log(` proxy api key: ${config.auth.proxyApiKey ? "required" : "open (no client auth)"}`);
351
+ console.log(` provider: ${config.provider}`);
352
+ console.log(` plan: ${config.plan}`);
353
+ console.log(` identity: appVersion=${config.identity.appVersion} sourceTitle=${config.identity.sourceTitle} referer=${config.identity.refererOrigin}`);
354
+ console.log(` client identity: mode=${config.clientIdentity.mode} ttl=${config.clientIdentity.ttlSeconds}s max=${config.clientIdentity.maxSessions}`);
355
+ console.log(` anthropic base: ${active.anthropicBase}`);
356
+ console.log(` openai base: ${active.openaiBase}`);
357
+ console.log(` credential: ${credShape}`);
358
+ console.log(` models (${config.models.length}): ${config.models.join(", ")}`);
359
+ console.log(` log level: ${config.logging.level}`);
360
+ console.log("===============================");
361
+ }
362
+
363
+ function authCommand(args: string[]): void {
364
+ const sub = args[0];
365
+
366
+ if (sub === "login") {
367
+ authLogin(args.slice(1));
368
+ } else if (sub === "logout") {
369
+ authLogout();
370
+ } else if (sub === "status") {
371
+ authStatus();
372
+ } else {
373
+ console.error("Usage: zcode-proxy auth <login|logout|status>");
374
+ process.exit(1);
375
+ }
376
+ }
377
+
378
+ async function claimCommand(args: string[]): Promise<void> {
379
+ const sub = args[0] ?? "now";
380
+ if (sub !== "list" && sub !== "now") {
381
+ console.error("Usage: zcode-proxy claim [list|now]");
382
+ process.exit(1);
383
+ }
384
+ const path = process.env.ZCODE_PROXY_CONFIG ?? "config.yaml";
385
+ if (!existsSync(path)) {
386
+ console.error(`Config file not found: ${path} (run serve once or create it).`);
387
+ process.exit(1);
388
+ }
389
+ // The billing gateway requires a stable X-Device-Mid — self-heal configs
390
+ // created before the deviceMid feature (idempotent: reuses existing value).
391
+ ensureDeviceMidInConfig(path);
392
+ const config = loadConfig(path);
393
+ try {
394
+ const { runClaimCli } = await import("./claim/runtime.js");
395
+ await runClaimCli(config, sub);
396
+ } catch (err) {
397
+ console.error(`claim failed: ${(err as Error).message}`);
398
+ process.exit(1);
399
+ }
400
+ }
401
+
402
+ async function authLogin(args: string[]): Promise<void> {
403
+ const provider = args[0] as ProviderId | undefined;
404
+ const importMode = args.includes("--import");
405
+ // Headless paste login: --paste flag or ZCODE_OAUTH_PASTE=1 (docker-friendly).
406
+ const pasteMode =
407
+ args.includes("--paste") || /^(1|true|yes)$/i.test(process.env.ZCODE_OAUTH_PASTE ?? "");
408
+
409
+ if (!provider || (provider !== "zai" && provider !== "bigmodel")) {
410
+ console.error("Usage: zcode-proxy auth login <zai|bigmodel> [--import] [--paste]");
411
+ process.exit(1);
412
+ }
413
+ if (pasteMode && provider !== "bigmodel") {
414
+ console.error("--paste applies to the bigmodel auth-code flow only.");
415
+ console.error("zai login is server-mediated (no localhost callback) and already works headless.");
416
+ process.exit(1);
417
+ }
418
+
419
+ ensureConfigWithDeviceMid();
420
+
421
+ const mode = importMode ? "(import)" : pasteMode ? "(OAuth, paste)" : "(OAuth)";
422
+ console.log(`Logging in: ${provider} ${mode}\n`);
423
+
424
+ let cred: Credential;
425
+
426
+ if (importMode) {
427
+ cred = importFromZCodeConfig(provider);
428
+ } else {
429
+ const { accessToken, userId, jwt } = await runOAuth(provider, pasteMode);
430
+ console.log("\nResolving API key...");
431
+ const resolver = new KeyResolver();
432
+ cred = await resolver.resolveCodingPlanCredential(accessToken, provider, userId);
433
+ if (jwt) cred.jwt = jwt;
434
+ }
435
+
436
+ await saveCredential(cred);
437
+ console.log(`\nLogged in as ${provider}.`);
438
+ console.log(` API Key: ${cred.apiKey.substring(0, 12)}...`);
439
+ if (cred.userId) console.log(` User ID: ${cred.userId}`);
440
+ console.log(` Stored: ${getStorePath()}`);
441
+ }
442
+
443
+ /**
444
+ * Ensure config.yaml exists and carries a stable `identity.deviceMid`.
445
+ * Creates the file from the bundled template when missing (desktop flow;
446
+ * Android's mid comes from NodeRunner env injection instead and is never
447
+ * written here). Returns the mid (existing or freshly generated).
448
+ */
449
+ function ensureConfigWithDeviceMid(): string {
450
+ const path = process.env.ZCODE_PROXY_CONFIG ?? "config.yaml";
451
+ if (ensureConfigFile(path)) {
452
+ console.log(`Created ${path} from bundled template.`);
453
+ }
454
+ return ensureDeviceMidInConfig(path);
455
+ }
456
+
457
+ /**
458
+ * Generate-or-reuse `identity.deviceMid` in a YAML config via targeted line
459
+ * edit (comments preserved): fills an empty `deviceMid:` value, inserts one
460
+ * under a block-style `identity:` key, or appends a new `identity:` block when
461
+ * the key is absent entirely. Idempotent — an existing non-empty value is
462
+ * returned untouched. The regexes are function-local on purpose: `main()` runs
463
+ * synchronously at module top (before later top-level statements initialize),
464
+ * so any module-level const this function touches would still be undefined on
465
+ * the boot-time `serve` path.
466
+ */
467
+ export function ensureDeviceMidInConfig(path: string): string {
468
+ const deviceMidLine = /^(\s*)deviceMid:\s*(.*)$/m;
469
+ const identityBlockLine = /^identity:\s*$/m;
470
+ const raw = readFileSync(path, "utf-8");
471
+
472
+ const existing = deviceMidLine.exec(raw);
473
+ if (existing) {
474
+ const value = existing[2].trim().replace(/^"|"$/g, "");
475
+ if (value.length > 0) return value;
476
+ }
477
+
478
+ const mid = randomUUID();
479
+ let updated: string;
480
+ if (existing) {
481
+ updated = raw.replace(deviceMidLine, `${existing[1]}deviceMid: "${mid}"`);
482
+ } else if (identityBlockLine.test(raw)) {
483
+ updated = raw.replace(identityBlockLine, `identity:\n deviceMid: "${mid}"`);
484
+ } else {
485
+ const block = `identity:\n deviceMid: "${mid}"\n`;
486
+ updated = raw.endsWith("\n") || raw.length === 0 ? raw + block : raw + "\n" + block;
487
+ }
488
+ writeFileSync(path, updated, "utf-8");
489
+ console.log(`Device identity generated: ${mid.slice(0, 8)}… (stored in ${path})`);
490
+ return mid;
491
+ }
492
+
493
+ function authLogout(): void {
494
+ if (!existsSync(getStorePath())) {
495
+ console.log("Not logged in.");
496
+ return;
497
+ }
498
+ clearCredential();
499
+ console.log("Logged out. Credentials removed.");
500
+ }
501
+
502
+ async function authStatus(): Promise<void> {
503
+ const cred = await loadCredential();
504
+ if (!cred) {
505
+ console.log("Not logged in.");
506
+ console.log("Run: zcode-proxy auth login <zai|bigmodel>");
507
+ return;
508
+ }
509
+ console.log(`Logged in: ${cred.provider}`);
510
+ console.log(` API Key: ${cred.apiKey.substring(0, 12)}...`);
511
+ console.log(` Store: ${getStorePath()}`);
512
+ }
513
+
514
+ async function runOAuth(provider: ProviderId, pasteMode: boolean): Promise<OAuthResult> {
515
+ if (provider === "bigmodel") {
516
+ const oauth = new BigmodelOAuthClient();
517
+ if (pasteMode) return runPasteLogin(oauth);
518
+ const result = await oauth.authorize((url) => {
519
+ console.log("Open this URL to authorize:\n");
520
+ console.log(` ${url}\n`);
521
+ console.log("Waiting for authorization... (expires in 300s)\n");
522
+ console.log(
523
+ "Headless/Docker? The callback page will NOT load here — Ctrl-C and " +
524
+ "re-run with `auth login bigmodel --paste` to paste the redirected URL instead.\n",
525
+ );
526
+ openBrowser(url);
527
+ });
528
+ return result;
529
+ }
530
+
531
+ const oauth = new ZaiOAuthClient();
532
+ const result = await oauth.authorize((url) => {
533
+ console.log("Open this URL to authorize:\n");
534
+ console.log(` ${url}\n`);
535
+ console.log("Waiting for authorization... (expires in 300s)\n");
536
+ openBrowser(url);
537
+ });
538
+ return result;
539
+ }
540
+
541
+ /**
542
+ * Headless bigmodel login (`auth login bigmodel --paste`): the localhost
543
+ * callback server is still bound — it defines the redirect port and the
544
+ * browser can never reach it from inside a container anyway — but instead of
545
+ * waiting on it, the user pastes the redirected URL back. The exact
546
+ * `started.callbackUrl` string is used BOTH as the authorize `redirect` param
547
+ * and as the exchange `redirect_uri` (the token endpoint requires them to
548
+ * match), so the pair stays consistent by construction.
549
+ */
550
+ async function runPasteLogin(oauth: BigmodelOAuthClient): Promise<OAuthResult> {
551
+ const started = await oauth.start();
552
+ try {
553
+ console.log(pasteLoginInstructions(started.authorizeUrl, started.callbackUrl, LOGIN_TIMEOUT_MS));
554
+ openBrowser(started.authorizeUrl);
555
+ process.stdout.write("\n" + boldIfTTY("Paste the FULL redirected URL here, then press Enter:") + "\n> ");
556
+ const pasted = await readPastedLine(LOGIN_TIMEOUT_MS);
557
+ const code = parsePastedCallbackUrl(pasted, started.state);
558
+ console.log("\nExchanging authorization code...");
559
+ const tokens = await oauth.exchangeCode(code, started.callbackUrl, started.state);
560
+ return { accessToken: tokens.accessToken, provider: "bigmodel", userId: tokens.userId, jwt: tokens.jwt };
561
+ } finally {
562
+ await oauth.close();
563
+ }
564
+ }
565
+
566
+ function importFromZCodeConfig(provider: ProviderId): Credential {
567
+ const configPath = join(homedir(), ".zcode", "v2", "config.json");
568
+ let raw: string;
569
+ try {
570
+ raw = readFileSync(configPath, "utf-8");
571
+ } catch {
572
+ console.error(`Cannot read ${configPath}.`);
573
+ console.error("Make sure ZCode is installed and you've logged in at least once.");
574
+ process.exit(1);
575
+ }
576
+
577
+ const config = JSON.parse(raw) as {
578
+ provider?: Record<string, { options?: { apiKey?: string }; enabled?: boolean }>;
579
+ };
580
+
581
+ const providerKey = `builtin:${provider}-coding-plan`;
582
+ const entry = config.provider?.[providerKey];
583
+ const apiKey = entry?.options?.apiKey?.trim();
584
+
585
+ if (!apiKey) {
586
+ console.error(`No API key for ${providerKey} in ZCode config.`);
587
+ process.exit(1);
588
+ }
589
+
590
+ const startPlanKey = `builtin:${provider}-start-plan`;
591
+ const jwt = config.provider?.[startPlanKey]?.options?.apiKey?.trim() || undefined;
592
+
593
+ console.log(`Imported from ${configPath}`);
594
+ if (jwt) console.log(` Start-plan JWT: ${jwt.slice(0, 12)}...`);
595
+ return { apiKey, provider, jwt };
596
+ }
src/mcp/client.ts ADDED
@@ -0,0 +1,315 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Minimal MCP (Model Context Protocol) JSON-RPC client for GLM's remote MCP
3
+ * servers. Designed for the GLM wire shape verified by live probing (see
4
+ * `_reverse/NOTEPAD.md` and the exploration notes):
5
+ *
6
+ * - Transport: Streamable HTTP over POST; responses are ALWAYS
7
+ * `text/event-stream` (server ignores `Accept: application/json`).
8
+ * - Each SSE frame is a 3-line block:
9
+ * `id:1` (SSE event id, fixed — NOT the JSON-RPC id, ignore it)
10
+ * `event:message`
11
+ * `data:{<json-rpc payload>}`
12
+ * - Sessions are mandatory: `initialize` returns `Mcp-Session-Id`, and every
13
+ * subsequent request MUST carry it back as a header.
14
+ * - Protocol version: client sends `2025-06-18`; server downgrades to
15
+ * `2024-11-05`. We accept whatever the server returns.
16
+ * - `notifications/initialized` must be sent once after `initialize` (HTTP
17
+ * 200 with empty body, no SSE).
18
+ * - Auth failure returns HTTP 200 with a non-JSON-RPC envelope:
19
+ * `{"code":1001,"msg":"...","success":false}` (not a JSON-RPC error) —
20
+ * the client detects this and throws `McpAuthError`.
21
+ * - Tool results carry a `content[]` array of `{type:"text",text}` blocks;
22
+ * some tools (web_search_prime) return a *doubly-encoded* JSON string in
23
+ * `text` (a stringified JSON array) — the caller decodes.
24
+ *
25
+ * No external dependencies. Pure `fetch()`. Works on both Bun and Node.
26
+ *
27
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle
28
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/server/tools
29
+ */
30
+ import type { ProviderId } from "../provider/types.js";
31
+
32
+ /** MCP tool definition (subset we care about). */
33
+ export interface McpToolDef {
34
+ name: string;
35
+ description?: string;
36
+ inputSchema?: Record<string, unknown>;
37
+ }
38
+
39
+ /** Result of a successful tools/call. */
40
+ export interface McpToolCallResult {
41
+ content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType?: string }>;
42
+ isError: boolean;
43
+ }
44
+
45
+ /** Thrown when the server returns the non-JSON-RPC auth envelope. */
46
+ export class McpAuthError extends Error {
47
+ readonly code: number;
48
+ constructor(code: number, msg: string) {
49
+ super(`MCP auth error (code=${code}): ${msg}`);
50
+ this.name = "McpAuthError";
51
+ this.code = code;
52
+ }
53
+ }
54
+
55
+ /** Thrown when the server returns a JSON-RPC `error` object. */
56
+ export class McpRpcError extends Error {
57
+ readonly code: number;
58
+ constructor(code: number, message: string) {
59
+ super(`MCP RPC error (code=${code}): ${message}`);
60
+ this.name = "McpRpcError";
61
+ this.code = code;
62
+ }
63
+ }
64
+
65
+ export interface McpClientOptions {
66
+ /** Full MCP endpoint URL, e.g. `https://open.bigmodel.cn/api/mcp/web_search_prime/mcp`. */
67
+ url: string;
68
+ /** Bearer credential — same GLM API key used for the LLM upstream. */
69
+ apiKey: string;
70
+ /** Protocol version to advertise in `initialize`; default `2025-06-18`. */
71
+ protocolVersion?: string;
72
+ /** Per-request timeout in ms; default 30000. */
73
+ timeoutMs?: number;
74
+ /** DI seam for tests. Defaults to global `fetch`. */
75
+ fetchImpl?: typeof fetch;
76
+ }
77
+
78
+ interface JsonRpcResponse {
79
+ jsonrpc: "2.0";
80
+ id?: number | string;
81
+ result?: unknown;
82
+ error?: { code: number; message: string; data?: unknown };
83
+ }
84
+
85
+ const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
86
+ const DEFAULT_TIMEOUT_MS = 30000;
87
+
88
+ /**
89
+ * Stateless-per-instance is forbidden by GLM (session is required), so a client
90
+ * owns its session. One instance per (server, apiKey) — pool via `GlmMcpPool`.
91
+ */
92
+ export class McpClient {
93
+ private readonly url: string;
94
+ private readonly apiKey: string;
95
+ private readonly protocolVersion: string;
96
+ private readonly timeoutMs: number;
97
+ private readonly fetchImpl: typeof fetch;
98
+ private sessionId: string | undefined;
99
+ private nextId = 1;
100
+ private initialized = false;
101
+
102
+ constructor(opts: McpClientOptions) {
103
+ this.url = opts.url;
104
+ this.apiKey = opts.apiKey;
105
+ this.protocolVersion = opts.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
106
+ this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
107
+ this.fetchImpl = opts.fetchImpl ?? fetch;
108
+ }
109
+
110
+ /**
111
+ * Perform the MCP handshake: `initialize` (captures session id) +
112
+ * `notifications/initialized`. Idempotent — subsequent calls are no-ops.
113
+ * Called lazily by `listTools` / `callTool`.
114
+ */
115
+ async initialize(): Promise<void> {
116
+ if (this.initialized) return;
117
+ const initResp = await this.postRpc("initialize", {
118
+ protocolVersion: this.protocolVersion,
119
+ capabilities: {},
120
+ clientInfo: { name: "zcode-proxy", version: "2.2.0" },
121
+ });
122
+ const result = initResp.json.result as { protocolVersion?: string } | undefined;
123
+ // GLM downgrades the version; we accept the server's choice silently.
124
+ void result?.protocolVersion;
125
+ this.initialized = true;
126
+ // notifications/initialized has no response body; swallow the empty SSE.
127
+ try {
128
+ await this.postRpc("notifications/initialized", undefined);
129
+ } catch {
130
+ // Some servers return empty bodies that fail SSE parse — safe to ignore.
131
+ }
132
+ }
133
+
134
+ /** List the tools the server exposes. */
135
+ async listTools(): Promise<McpToolDef[]> {
136
+ await this.initialize();
137
+ const resp = await this.postRpc("tools/list", {});
138
+ const result = resp.json.result as { tools?: McpToolDef[] } | undefined;
139
+ return result?.tools ?? [];
140
+ }
141
+
142
+ /** Invoke a tool. Returns the raw `content[]`; callers decode per-tool. */
143
+ async callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult> {
144
+ await this.initialize();
145
+ const resp = await this.postRpc("tools/call", { name, arguments: args });
146
+ const result = resp.json.result as McpToolCallResult | undefined;
147
+ if (!result || !Array.isArray(result.content)) {
148
+ throw new McpRpcError(-32603, `tool "${name}" returned malformed result`);
149
+ }
150
+ return result;
151
+ }
152
+
153
+ /** Drop the session. Next call re-initializes. Safe to call when not initialized. */
154
+ reset(): void {
155
+ this.sessionId = undefined;
156
+ this.initialized = false;
157
+ }
158
+
159
+ /**
160
+ * Send a JSON-RPC request and parse the SSE response. For notifications
161
+ * (no `id`) the response is empty — the parser tolerates a 0-event stream.
162
+ */
163
+ private async postRpc(
164
+ method: string,
165
+ params: unknown,
166
+ ): Promise<{ json: JsonRpcResponse; headers: Headers }> {
167
+ const id = method.startsWith("notifications/") ? undefined : this.nextId++;
168
+ const body: string = JSON.stringify({
169
+ jsonrpc: "2.0",
170
+ ...(id !== undefined ? { id } : {}),
171
+ method,
172
+ ...(params !== undefined ? { params } : {}),
173
+ });
174
+
175
+ const controller = new AbortController();
176
+ const timer = setTimeout(() => controller.abort(), this.timeoutMs);
177
+ let httpResp: Response;
178
+ try {
179
+ httpResp = await this.fetchImpl(this.url, {
180
+ method: "POST",
181
+ headers: {
182
+ "content-type": "application/json",
183
+ accept: "application/json, text/event-stream",
184
+ authorization: `Bearer ${this.apiKey}`,
185
+ ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
186
+ },
187
+ body,
188
+ signal: controller.signal,
189
+ });
190
+ } finally {
191
+ clearTimeout(timer);
192
+ }
193
+
194
+ if (!httpResp.ok) {
195
+ throw new McpRpcError(-32000, `HTTP ${httpResp.status} ${httpResp.statusText}`);
196
+ }
197
+
198
+ // Capture the session id on the FIRST response (initialize).
199
+ if (!this.sessionId) {
200
+ const sid = httpResp.headers.get("mcp-session-id");
201
+ if (sid) this.sessionId = sid;
202
+ }
203
+
204
+ const contentType = httpResp.headers.get("content-type") ?? "";
205
+ const raw = await httpResp.text();
206
+
207
+ // GLM's auth failures are HTTP 200 + a non-JSON-RPC envelope.
208
+ if (!contentType.includes("event-stream") && !contentType.includes("application/json")) {
209
+ // Still inspect the body — some auth failures come back without a proper CT.
210
+ throw this.classifyEnvelope(raw);
211
+ }
212
+
213
+ // Empty body (notifications/initialized) → no JSON-RPC payload to return.
214
+ if (raw.length === 0 || raw.trim() === "") {
215
+ return { json: { jsonrpc: "2.0" }, headers: httpResp.headers };
216
+ }
217
+
218
+ const payload = contentType.includes("event-stream")
219
+ ? parseSseFrame(raw)
220
+ : safeParseJson(raw);
221
+
222
+ if (payload === null) {
223
+ // Could be the auth envelope on a 200 with no/odd CT.
224
+ throw this.classifyEnvelope(raw);
225
+ }
226
+
227
+ // Detect GLM's auth envelope even when it leaks into a JSON-looking CT.
228
+ if (
229
+ typeof payload === "object"
230
+ && payload !== null
231
+ && "success" in payload
232
+ && payload.success === false
233
+ && typeof (payload as { code?: unknown }).code === "number"
234
+ && !("jsonrpc" in payload)
235
+ ) {
236
+ const env = payload as unknown as { code: number; msg?: string };
237
+ throw new McpAuthError(env.code, env.msg ?? "auth failed");
238
+ }
239
+
240
+ const jsonRpc = payload as JsonRpcResponse;
241
+ if (jsonRpc.error) {
242
+ throw new McpRpcError(jsonRpc.error.code, jsonRpc.error.message);
243
+ }
244
+ return { json: jsonRpc, headers: httpResp.headers };
245
+ }
246
+
247
+ /** Parse a body as JSON; if it looks like GLM's `{code, msg, success:false}` envelope, return the right error. */
248
+ private classifyEnvelope(raw: string): Error {
249
+ const parsed = safeParseJson(raw);
250
+ if (
251
+ parsed !== null
252
+ && typeof parsed === "object"
253
+ && parsed !== null
254
+ && "success" in parsed
255
+ && (parsed as { success?: unknown }).success === false
256
+ && typeof (parsed as { code?: unknown }).code === "number"
257
+ ) {
258
+ const env = parsed as unknown as { code: number; msg?: string };
259
+ return new McpAuthError(env.code, env.msg ?? "auth failed");
260
+ }
261
+ return new McpRpcError(-32700, `unparseable MCP response (content-type missing, body: ${raw.slice(0, 200)})`);
262
+ }
263
+ }
264
+
265
+ /**
266
+ * Parse one SSE frame from GLM's response into a JSON value.
267
+ *
268
+ * GLM emits exactly one `data:` line per response, so this is simpler than a
269
+ * full streaming parser. The frame shape (verified by probing):
270
+ *
271
+ * id:1
272
+ * event:message
273
+ * data:{"jsonrpc":"2.0",...}
274
+ *
275
+ * `id:1` is the SSE event id (fixed at 1 by the server — not the JSON-RPC id).
276
+ * We ignore it and parse only the `data:` payload.
277
+ */
278
+ function parseSseFrame(raw: string): unknown {
279
+ let dataLine: string | null = null;
280
+ for (const line of raw.split(/\r?\n/)) {
281
+ if (line.startsWith("data:")) {
282
+ // GLM uses `data:{...}` (no space). Tolerate both forms.
283
+ dataLine = line.slice(5).replace(/^\s/, "");
284
+ break;
285
+ }
286
+ }
287
+ if (dataLine === null) return null;
288
+ return safeParseJson(dataLine);
289
+ }
290
+
291
+ function safeParseJson(raw: string): unknown {
292
+ try {
293
+ return JSON.parse(raw);
294
+ } catch {
295
+ return null;
296
+ }
297
+ }
298
+
299
+ // ─────────────────────────────────────────────
300
+ // Provider-aware endpoint derivation
301
+ // ─────────────────────────────────────────────
302
+
303
+ /** GLM MCP host per provider (verified: both providers serve identical MCP shapes). */
304
+ const MCP_HOSTS: Record<ProviderId, string> = {
305
+ bigmodel: "https://open.bigmodel.cn",
306
+ zai: "https://api.z.ai",
307
+ };
308
+
309
+ /** GLM MCP server identifiers. Path is `/api/mcp/{server}/mcp` for both providers. */
310
+ export type GlmMcpServerId = "web_search_prime" | "web_reader" | "zread";
311
+
312
+ /** Build the full MCP endpoint URL for a (provider, server) pair. */
313
+ export function glmMcpEndpoint(provider: ProviderId, server: GlmMcpServerId): string {
314
+ return `${MCP_HOSTS[provider]}/api/mcp/${server}/mcp`;
315
+ }
src/mcp/glm-tools.ts ADDED
@@ -0,0 +1,192 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * GLM MCP server registry + tool-call wrappers for the three official remote
3
+ * MCP servers (web_search_prime / web_reader / zread). All three use the same
4
+ * GLM API key as the LLM upstream, and their endpoints are derived from the
5
+ * active provider (see `glmMcpEndpoint`).
6
+ *
7
+ * Used by the Responses handler to:
8
+ * - intercept `web_search` / `web_search_preview` hosted tools and route
9
+ * them to GLM's `web_search_prime` MCP tool,
10
+ * - (P2, off by default) inject `web_reader` / `zread` as function tools the
11
+ * model can call directly.
12
+ *
13
+ * Each wrapper decodes the MCP result into a typed shape. `web_search_prime` is
14
+ * the trickiest: its `content[0].text` is a *doubly-encoded* JSON string (a
15
+ * stringified JSON array). The wrapper does `JSON.parse` once to unwrap the
16
+ * array, leaving consumers with a clean `WebSearchHit[]`.
17
+ */
18
+ import { McpClient, glmMcpEndpoint, type GlmMcpServerId, type McpClientOptions } from "./client.js";
19
+ import type { ProviderId } from "../provider/types.js";
20
+
21
+ // ─────────────────────────────────────────────
22
+ // Result types
23
+ // ─────────────────────────────────────────────
24
+
25
+ export interface WebSearchHit {
26
+ title: string;
27
+ link: string;
28
+ content: string;
29
+ /** GLM's per-result reference id (e.g. "ref_1"). */
30
+ refer?: string;
31
+ }
32
+
33
+ export interface WebPageContent {
34
+ /** Decoded page content (markdown or text, per `return_format`). */
35
+ text: string;
36
+ /** Raw MCP content blocks (preserved for future field extraction). */
37
+ raw: Array<{ type: string; text?: string }>;
38
+ }
39
+
40
+ export interface ZreadSearchResult {
41
+ // GLM zread returns free-form text content; keep it loose.
42
+ text: string;
43
+ }
44
+
45
+ export interface ZreadRepoStructure {
46
+ text: string;
47
+ }
48
+
49
+ export interface ZreadFileContent {
50
+ text: string;
51
+ }
52
+
53
+ // ─────────────────────────────────────────────
54
+ // Pool: one McpClient per (provider, server) — reuses the session.
55
+ // ─────────────────────────────────────────────
56
+
57
+ export interface GlmMcpPoolOptions {
58
+ provider: ProviderId;
59
+ apiKey: string;
60
+ fetchImpl?: typeof fetch;
61
+ timeoutMs?: number;
62
+ }
63
+
64
+ /**
65
+ * Lazily-initialised pool of MCP clients keyed by server id. Reuses sessions
66
+ * across calls (GLM sessions are stateful and expensive to re-establish).
67
+ * Call `close()` on shutdown to reset all sessions (best-effort).
68
+ */
69
+ export class GlmMcpPool {
70
+ private readonly opts: GlmMcpPoolOptions;
71
+ private readonly clients = new Map<GlmMcpServerId, McpClient>();
72
+
73
+ constructor(opts: GlmMcpPoolOptions) {
74
+ this.opts = opts;
75
+ }
76
+
77
+ private client(server: GlmMcpServerId): McpClient {
78
+ let c = this.clients.get(server);
79
+ if (!c) {
80
+ const clientOpts: McpClientOptions = {
81
+ url: glmMcpEndpoint(this.opts.provider, server),
82
+ apiKey: this.opts.apiKey,
83
+ fetchImpl: this.opts.fetchImpl,
84
+ timeoutMs: this.opts.timeoutMs,
85
+ };
86
+ c = new McpClient(clientOpts);
87
+ this.clients.set(server, c);
88
+ }
89
+ return c;
90
+ }
91
+
92
+ /** Reset all cached sessions (e.g. on credential rotation). */
93
+ reset(): void {
94
+ for (const c of this.clients.values()) c.reset();
95
+ }
96
+
97
+ // ── web_search_prime ──
98
+ /**
99
+ * Search the web via GLM's MCP. `arguments` mirror GLM's inputSchema
100
+ * (verified by live `tools/list`):
101
+ * - `search_query` (required)
102
+ * - `search_domain_filter`, `search_recency_filter`, `content_size`, `location`
103
+ */
104
+ async webSearch(args: {
105
+ search_query: string;
106
+ search_domain_filter?: string;
107
+ search_recency_filter?: "oneDay" | "oneWeek" | "oneMonth" | "oneYear" | "noLimit";
108
+ content_size?: "medium" | "high";
109
+ location?: "cn" | "us";
110
+ }): Promise<WebSearchHit[]> {
111
+ const result = await this.client("web_search_prime").callTool("web_search_prime", args as Record<string, unknown>);
112
+ return decodeWebSearchResult(result.content);
113
+ }
114
+
115
+ // ── web_reader ──
116
+ /** Fetch a URL's content via GLM's MCP `webReader` tool. */
117
+ async webRead(args: {
118
+ url: string;
119
+ return_format?: "markdown" | "text";
120
+ no_cache?: boolean;
121
+ retain_images?: boolean;
122
+ no_gfm?: boolean;
123
+ with_images_summary?: boolean;
124
+ with_links_summary?: boolean;
125
+ timeout?: number;
126
+ }): Promise<WebPageContent> {
127
+ const result = await this.client("web_reader").callTool("webReader", args as Record<string, unknown>);
128
+ return { text: joinText(result.content), raw: result.content as Array<{ type: string; text?: string }> };
129
+ }
130
+
131
+ // ── zread ──
132
+ /** Search a GitHub repo's docs/issues/commits via GLM's `zread` MCP. */
133
+ async zreadSearchDoc(args: { repo_name: string; query: string; language?: "zh" | "en" }): Promise<ZreadSearchResult> {
134
+ const result = await this.client("zread").callTool("search_doc", args as Record<string, unknown>);
135
+ return { text: joinText(result.content) };
136
+ }
137
+
138
+ /** Get a GitHub repo's directory structure via GLM's `zread` MCP. */
139
+ async zreadGetRepoStructure(args: { repo_name: string; dir_path?: string }): Promise<ZreadRepoStructure> {
140
+ const result = await this.client("zread").callTool("get_repo_structure", args as Record<string, unknown>);
141
+ return { text: joinText(result.content) };
142
+ }
143
+
144
+ /** Read a file in a GitHub repo via GLM's `zread` MCP. */
145
+ async zreadReadFile(args: { repo_name: string; file_path: string }): Promise<ZreadFileContent> {
146
+ const result = await this.client("zread").callTool("read_file", args as Record<string, unknown>);
147
+ return { text: joinText(result.content) };
148
+ }
149
+ }
150
+
151
+ // ─────────────────────────────────────────────
152
+ // Decoders
153
+ // ─────────────────────────────────────────────
154
+
155
+ /**
156
+ * Decode `web_search_prime`'s doubly-encoded result. The MCP `content[0].text`
157
+ * field holds a JSON-stringified array: `"[{\"title\":...,\"link\":..., ...}]"`.
158
+ * Caller-friendly: returns `[]` on any parse failure rather than throwing.
159
+ */
160
+ export function decodeWebSearchResult(contentBlocks: Array<{ type: string; text?: string }>): WebSearchHit[] {
161
+ const text = contentBlocks.find((c) => c.type === "text")?.text;
162
+ if (!text) return [];
163
+ // First unwrap: text → JSON array string.
164
+ let arrayStr: string;
165
+ try {
166
+ // The text field itself may be a quoted JSON string ("[...]" → [...])
167
+ const unquoted = JSON.parse(text);
168
+ arrayStr = typeof unquoted === "string" ? unquoted : text;
169
+ } catch {
170
+ arrayStr = text;
171
+ }
172
+ let arr: unknown;
173
+ try {
174
+ arr = JSON.parse(arrayStr);
175
+ } catch {
176
+ return [];
177
+ }
178
+ if (!Array.isArray(arr)) return [];
179
+ return arr.filter((h): h is WebSearchHit => {
180
+ if (typeof h !== "object" || h === null) return false;
181
+ const hit = h as Record<string, unknown>;
182
+ return typeof hit.title === "string" && typeof hit.link === "string";
183
+ });
184
+ }
185
+
186
+ /** Concatenate all `text` blocks in an MCP result into a single string. */
187
+ function joinText(content: Array<{ type: string; text?: string }>): string {
188
+ return content
189
+ .filter((c) => c.type === "text" && typeof c.text === "string")
190
+ .map((c) => c.text as string)
191
+ .join("\n");
192
+ }
src/provider/models.ts ADDED
@@ -0,0 +1,28 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Pinned model catalog for GLM coding plan.
3
+ *
4
+ * Hardcoded to the exact models available on the Z.AI / Bigmodel coding-plan
5
+ * tier. This replaces the previous `_reverse/models_catalog.json` import,
6
+ * removing that runtime dependency. Update this list when new GLM models are
7
+ * released or specs change.
8
+ *
9
+ * @see .omo/plans/zcode-proxy.md Task 3
10
+ */
11
+ import type { ModelDef } from "./types.js";
12
+
13
+ /** All models available on the GLM coding plan, pinned with verified specs. */
14
+ export const MODELS: ModelDef[] = [
15
+ { id: "glm-4.5-air", name: "GLM 4.5 Air", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true },
16
+ { id: "glm-4.6", name: "GLM 4.6", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true },
17
+ { id: "glm-4.6v", name: "GLM 4.6V", contextWindow: 200_000, maxOutputTokens: 128_000 },
18
+ { id: "glm-4.7", name: "GLM 4.7", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true },
19
+ { id: "glm-5", name: "GLM 5", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true },
20
+ { id: "glm-5-turbo", name: "GLM 5 Turbo", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true },
21
+ { id: "glm-5v-turbo", name: "GLM 5V Turbo", contextWindow: 200_000, maxOutputTokens: 128_000 },
22
+ { id: "glm-5.1", name: "GLM 5.1", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true },
23
+ { id: "glm-5.2", name: "GLM 5.2", contextWindow: 1_000_000, maxOutputTokens: 128_000, reasoning: true },
24
+ { id: "glm-5.3", name: "GLM 5.3", contextWindow: 1_000_000, maxOutputTokens: 128_000, reasoning: true },
25
+ // start-plan gateway serves the -flash variant (used by claimed trial plans
26
+ // like the weekend package); advertised so client-side discovery lists it.
27
+ { id: "glm-5.3-flash", name: "GLM 5.3 Flash", contextWindow: 1_000_000, maxOutputTokens: 128_000, reasoning: true },
28
+ ];
src/provider/providers.ts ADDED
@@ -0,0 +1,36 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Z.AI and Bigmodel provider definitions.
3
+ * @see .omo/plans/zcode-proxy.md Task 3
4
+ * @see _reverse/NOTEPAD.md "Provider Endpoints"
5
+ */
6
+ import type { ProviderDef, ProviderId } from "./types.js";
7
+
8
+ export const ZAI_PROVIDER: ProviderDef = {
9
+ id: "zai",
10
+ displayName: "Z.AI",
11
+ anthropicBaseURL: "https://api.z.ai/api/anthropic",
12
+ openaiBaseURL: "https://api.z.ai/api/coding/paas/v4",
13
+ bizHost: "https://api.z.ai",
14
+ };
15
+
16
+ export const BIGMODEL_PROVIDER: ProviderDef = {
17
+ id: "bigmodel",
18
+ displayName: "BigModel / 智谱",
19
+ anthropicBaseURL: "https://open.bigmodel.cn/api/anthropic",
20
+ openaiBaseURL: "https://open.bigmodel.cn/api/coding/paas/v4",
21
+ bizHost: "https://open.bigmodel.cn",
22
+ };
23
+
24
+ const PROVIDERS: Record<ProviderId, ProviderDef> = {
25
+ zai: ZAI_PROVIDER,
26
+ bigmodel: BIGMODEL_PROVIDER,
27
+ };
28
+
29
+ /** Look up a provider definition by id. */
30
+ export function getProvider(id: ProviderId): ProviderDef {
31
+ const def = PROVIDERS[id];
32
+ if (!def) {
33
+ throw new Error(`Unknown provider: "${id}"`);
34
+ }
35
+ return def;
36
+ }
src/provider/reasoning.ts ADDED
@@ -0,0 +1,124 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * GLM-5.3 family reasoning-effort contract.
3
+ *
4
+ * The Anthropic upstream ignores the OpenAI `reasoning_effort` field entirely
5
+ * for this model family — `output_config.effort` is the only channel that
6
+ * actually changes how much the model thinks, and it must be paired with a
7
+ * matching `thinking.budget_tokens` (the effort label alone still produces
8
+ * near-zero thinking). Values below come from ZCode's own model catalog
9
+ * entry for `glm-5.3` (`defaultLevel: "max"`, three effort levels each
10
+ * setting both fields) plus live upstream verification.
11
+ */
12
+
13
+ /** The three legal `output_config.effort` levels for GLM-5.3 models (module-local; the type below is the public contract). */
14
+ const GLM53_EFFORT_LEVELS = ["low", "high", "max"] as const;
15
+
16
+ /** One of the three legal GLM-5.3 effort levels. */
17
+ export type Glm53Effort = (typeof GLM53_EFFORT_LEVELS)[number];
18
+
19
+ /** ZCode catalog's `defaultLevel` for glm-5.3 — used when no effort is requested. */
20
+ export const GLM53_DEFAULT_EFFORT: Glm53Effort = "max";
21
+
22
+ /**
23
+ * Thinking token budgets ZCode's catalog pairs with each effort level.
24
+ * Sending `output_config.effort` without a matching `thinking.budget_tokens`
25
+ * leaves the upstream at its own near-zero default.
26
+ */
27
+ export const GLM53_THINKING_BUDGETS: Readonly<Record<Glm53Effort, number>> = {
28
+ low: 8_000,
29
+ high: 16_000,
30
+ max: 32_000,
31
+ };
32
+
33
+ /**
34
+ * Floor below which a thinking budget stops being useful — measured live
35
+ * against the upstream (a budget this small collapses back to near-zero
36
+ * thinking output).
37
+ */
38
+ export const GLM53_MIN_THINKING_BUDGET = 1_024;
39
+
40
+ /**
41
+ * Tokens reserved for the actual answer once the thinking budget is
42
+ * subtracted from `max_tokens` — see `fitGlm53Budget`. ZCode's own clamp
43
+ * (`Math.min(budgetTokens, maxOutputTokens - 1)`) is written against the
44
+ * *model's* maxOutputTokens ceiling, a large fixed number (128,000 for
45
+ * glm-5.3) where reserving a single token for the answer is harmless.
46
+ * Applying that same "-1" literally against a small per-request
47
+ * `max_tokens` is not — it leaves the response with essentially nothing to
48
+ * work with. 1,024 tokens (matching `GLM53_MIN_THINKING_BUDGET`'s own
49
+ * granularity) is a defensible floor: enough for a short but real answer,
50
+ * without meaningfully eating into a large thinking budget when
51
+ * `max_tokens` is generous.
52
+ */
53
+ export const GLM53_ANSWER_RESERVE = 1_024;
54
+
55
+ /**
56
+ * Match the GLM-5.3 model family, including `glm-5.3-flash`, case-insensitively
57
+ * (the upstream also accepts `GLM-5.3`). Deliberately excludes `glm-5`,
58
+ * `glm-5.1`, and `glm-5.2` — the negative lookahead rejects a trailing digit
59
+ * so `glm-5.30` (were it ever added) would not falsely match either.
60
+ */
61
+ const GLM53_MODEL_PATTERN = /glm-5\.3(?![0-9])/i;
62
+
63
+ /** True when `model` belongs to the GLM-5.3 family (`glm-5.3`, `glm-5.3-flash`, ...). */
64
+ export function isGlm53Model(model: string | undefined): boolean {
65
+ if (!model) return false;
66
+ return GLM53_MODEL_PATTERN.test(model);
67
+ }
68
+
69
+ /**
70
+ * Map an OpenAI `reasoning_effort` value onto the three GLM-5.3 effort
71
+ * levels, per Z.AI's official mapping table. Unrecognized or absent values
72
+ * fall back to the catalog default (`max`) rather than the OpenAI-side
73
+ * default (`medium`), since ZCode's own `defaultLevel` for this family is
74
+ * `max`. The mapping rounds UP, not to nearest — `medium` maps to `high`,
75
+ * not `low`.
76
+ */
77
+ export function normalizeGlm53Effort(effort: string | undefined): Glm53Effort {
78
+ switch (effort) {
79
+ case "none":
80
+ case "minimal":
81
+ case "light":
82
+ case "low":
83
+ return "low";
84
+ case "medium":
85
+ case "high":
86
+ return "high";
87
+ case "xhigh":
88
+ case "max":
89
+ case "ultra":
90
+ return "max";
91
+ default:
92
+ return GLM53_DEFAULT_EFFORT;
93
+ }
94
+ }
95
+
96
+ /** Build the paired `thinking` + `output_config` fields for a GLM-5.3 effort level. */
97
+ export function buildGlm53Reasoning(effort: Glm53Effort): {
98
+ thinking: { type: "enabled"; budget_tokens: number };
99
+ output_config: { effort: Glm53Effort };
100
+ } {
101
+ return {
102
+ thinking: { type: "enabled", budget_tokens: GLM53_THINKING_BUDGETS[effort] },
103
+ output_config: { effort },
104
+ };
105
+ }
106
+
107
+ /**
108
+ * Clamp a thinking budget to fit inside `max_tokens`, reserving
109
+ * `GLM53_ANSWER_RESERVE` tokens for the answer — ZCode's catalog spends the
110
+ * thinking budget out of the same token pool as the response, so a budget
111
+ * that eats the whole of `max_tokens` (or all but one token of it) would
112
+ * leave no meaningful room for output. Returns `undefined` when the clamped
113
+ * budget falls below `GLM53_MIN_THINKING_BUDGET` (the caller should then
114
+ * fall back to `{type:"enabled"}` with no explicit budget). Passes `budget`
115
+ * through unchanged when `maxTokens` isn't a finite number — the upstream
116
+ * doesn't validate this either, so there is nothing useful to clamp against.
117
+ */
118
+ export function fitGlm53Budget(budget: number, maxTokens: unknown): number | undefined {
119
+ if (typeof maxTokens !== "number" || !Number.isFinite(maxTokens)) return budget;
120
+ // Floor first: JSON permits a fractional `max_tokens`, and a fractional
121
+ // `budget_tokens` is not a value the upstream should ever be handed.
122
+ const clamped = Math.min(budget, Math.floor(maxTokens) - GLM53_ANSWER_RESERVE);
123
+ return clamped >= GLM53_MIN_THINKING_BUDGET ? clamped : undefined;
124
+ }
src/provider/types.ts ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Provider and model type definitions.
3
+ * @see .omo/plans/zcode-proxy.md Task 3
4
+ */
5
+
6
+ /** Supported provider identifiers. */
7
+ export type ProviderId = "zai" | "bigmodel";
8
+
9
+ /** Static provider definition with endpoint URLs. */
10
+ export interface ProviderDef {
11
+ id: ProviderId;
12
+ displayName: string;
13
+ /** Base URL for Anthropic-format requests (no trailing slash). */
14
+ anthropicBaseURL: string;
15
+ /** Base URL for OpenAI-format requests (no trailing slash). */
16
+ openaiBaseURL: string;
17
+ /** Host for OAuth/API-key resolution business APIs. */
18
+ bizHost: string;
19
+ }
20
+
21
+ /** Model definition derived from the catalog. */
22
+ export interface ModelDef {
23
+ id: string;
24
+ name: string;
25
+ contextWindow: number;
26
+ maxOutputTokens?: number;
27
+ /** Whether the model supports reasoning/thinking mode. */
28
+ reasoning?: boolean;
29
+ }
src/proxy/body-transformer.ts ADDED
@@ -0,0 +1,194 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Request body transformer — applies ZCode-equivalent body mutations before
3
+ * forwarding upstream. All transformations are no-ops on parse failure (the
4
+ * original body is returned unchanged) so a malformed body never breaks the
5
+ * proxy: it just loses the optimization.
6
+ *
7
+ * Transformations applied:
8
+ * 1. OpenAI + `stream: true` → inject `stream_options.include_usage: true`
9
+ * (matches `@ai-sdk/openai-compatible` default in `_reverse/zcode.cjs`).
10
+ * 2. start-plan → prepend ZCode gateway system blocks. OpenAI upstream gets
11
+ * system messages; Anthropic-shaped input gets the Anthropic `system` field.
12
+ * 3. Anthropic format → clear existing `cache_control` markers on all
13
+ * non-system messages, then add `{ type: "ephemeral" }` to the last
14
+ * content block of the last non-system message (mirrors the bundle's
15
+ * `zsi`+`Fsi` pair). Anthropic's API silently ignores `cache_control`
16
+ * below the per-model token floor, so unconditional marking is safe and
17
+ * matches ZCode's `applyCacheControl: true` default.
18
+ * 4. Anthropic format + `ctx.userId` set → inject `metadata: { user_id }`.
19
+ * Mirrors `user_id: B.metadata.userId` at bundle offset ~4760586.
20
+ *
21
+ * @see _reverse/NOTEPAD.md "How Credential is Used for LLM Calls"
22
+ */
23
+ import type { Format } from "../translator/types.js";
24
+ import { buildStartPlanSystem } from "./system-prompt.js";
25
+
26
+ interface TransformContext {
27
+ format: Format;
28
+ /** When set (OAuth mode), the Anthropic-format body gets `metadata.user_id` injected. */
29
+ userId?: string;
30
+ /** When true (start-plan), prepend ZCode gateway system blocks. */
31
+ startPlan?: boolean;
32
+ }
33
+
34
+ /**
35
+ * Apply body transformations. Returns the original `body` string when nothing
36
+ * changed OR when parsing failed; otherwise returns the re-serialized body.
37
+ */
38
+ export function transformRequestBody(body: string | undefined, ctx: TransformContext): string | undefined {
39
+ if (body === undefined || body.length === 0) return body;
40
+
41
+ let parsed: unknown;
42
+ try {
43
+ parsed = JSON.parse(body);
44
+ } catch {
45
+ return body;
46
+ }
47
+ if (typeof parsed !== "object" || parsed === null) return body;
48
+
49
+ let modified = false;
50
+
51
+ if (ctx.format === "openai") {
52
+ if (ctx.startPlan) {
53
+ modified = applyStartPlanOpenAISystem(parsed as Record<string, unknown>) || modified;
54
+ }
55
+ modified = applyStreamOptionsIncludeUsage(parsed as Record<string, unknown>) || modified;
56
+ }
57
+ if (ctx.format === "anthropic") {
58
+ const obj = parsed as Record<string, unknown>;
59
+ if (ctx.startPlan) {
60
+ modified = applyStartPlanSystem(obj) || modified;
61
+ }
62
+ modified = applyAnthropicCacheControl(obj) || modified;
63
+ if (ctx.userId) {
64
+ modified = applyAnthropicUserId(obj, ctx.userId) || modified;
65
+ }
66
+ }
67
+
68
+ return modified ? JSON.stringify(parsed) : body;
69
+ }
70
+
71
+ /** OpenAI streaming: ensure `stream_options.include_usage: true`. */
72
+ function applyStreamOptionsIncludeUsage(body: Record<string, unknown>): boolean {
73
+ if (body.stream !== true) return false;
74
+ const existing = body.stream_options;
75
+ if (isPlainObject(existing) && existing.include_usage === true) {
76
+ return false;
77
+ }
78
+ const merged: Record<string, unknown> = isPlainObject(existing) ? { ...existing } : {};
79
+ merged.include_usage = true;
80
+ body.stream_options = merged;
81
+ return true;
82
+ }
83
+
84
+ function isPlainObject(v: unknown): v is Record<string, unknown> {
85
+ return typeof v === "object" && v !== null;
86
+ }
87
+
88
+ /**
89
+ * Anthropic: two-phase cache_control injection, mirroring the bundle's
90
+ * `zsi` (clear) + `Fsi` (mark) pair:
91
+ * (1) strip `cache_control` from every content block of every NON-system
92
+ * message (string content carries no marker to clear);
93
+ * (2) mark the last content block of the LAST non-system message (existing
94
+ * location algorithm) with `{type: "ephemeral"}`; string content is
95
+ * converted to a block array first (kept from the previous behavior).
96
+ *
97
+ * Without the clear phase, client-supplied `cache_control` on earlier messages
98
+ * would pass through alongside our marker → multiple cache breakpoints and
99
+ * more cache writes than the real client produces. The top-level `system`
100
+ * field is untouched. The bundle's skipCacheWrite variant (marks the
101
+ * second-to-last message instead) is NOT implemented — this proxy always
102
+ * writes cache.
103
+ *
104
+ * Output-stable: applying this to an already-canonical body yields the same
105
+ * bytes (no duplicate markers, target block unchanged). Note the function
106
+ * still reports `modified` in that case — the clear phase strips the target
107
+ * block's own marker before phase 2 re-adds the identical one — so callers
108
+ * re-serialize once more; harmless (byte-identical output), just not free.
109
+ */
110
+ function applyAnthropicCacheControl(body: Record<string, unknown>): boolean {
111
+ const messages = body.messages;
112
+ if (!Array.isArray(messages) || messages.length === 0) return false;
113
+
114
+ // Phase 1 (bundle `zsi`): clear stale markers on non-system messages.
115
+ let cleaned = false;
116
+ for (const msg of messages) {
117
+ if (typeof msg !== "object" || msg === null) continue;
118
+ if (msg.role === "system") continue;
119
+ if (!Array.isArray(msg.content)) continue;
120
+ for (const block of msg.content) {
121
+ if (typeof block === "object" && block !== null && "cache_control" in block) {
122
+ delete block.cache_control;
123
+ cleaned = true;
124
+ }
125
+ }
126
+ }
127
+
128
+ // Phase 2 (bundle `Fsi`): mark the last non-system message's last block.
129
+ for (let i = messages.length - 1; i >= 0; i--) {
130
+ const msg = messages[i];
131
+ if (typeof msg !== "object" || msg === null) continue;
132
+ if (msg.role === "system") continue;
133
+
134
+ if (typeof msg.content === "string") {
135
+ msg.content = [{ type: "text", text: msg.content, cache_control: { type: "ephemeral" } }];
136
+ return true;
137
+ }
138
+ if (Array.isArray(msg.content) && msg.content.length > 0) {
139
+ const lastBlock = msg.content[msg.content.length - 1];
140
+ if (typeof lastBlock === "object" && lastBlock !== null && !lastBlock.cache_control) {
141
+ lastBlock.cache_control = { type: "ephemeral" };
142
+ return true;
143
+ }
144
+ // Already marked — only report modified if the clear phase stripped
145
+ // stray markers elsewhere (idempotency: avoid needless re-serialize).
146
+ return cleaned;
147
+ }
148
+ return cleaned;
149
+ }
150
+ return cleaned;
151
+ }
152
+
153
+ /**
154
+ * Anthropic: inject `metadata: { user_id }` when not already set.
155
+ * Preserves any existing `metadata.*` fields other than `user_id`.
156
+ */
157
+ function applyAnthropicUserId(body: Record<string, unknown>, userId: string): boolean {
158
+ const existing = body.metadata;
159
+ if (isPlainObject(existing) && existing.user_id === userId) {
160
+ return false;
161
+ }
162
+ body.metadata = {
163
+ ...(isPlainObject(existing) ? existing : {}),
164
+ user_id: userId,
165
+ };
166
+ return true;
167
+ }
168
+
169
+ /**
170
+ * start-plan: prepend ZCode gateway system blocks. The gateway rejects
171
+ * requests without these identity blocks with 3012 "method not allowed".
172
+ * Forwards `body.model` so `buildStartPlanSystem` can merge the dynamic
173
+ * "You are powered by the model named ${model}." line into the trailing
174
+ * Environment block (matches bundle 3.11.2 `T9o`/buildEnvInfoSection — the
175
+ * line lives INSIDE the Environment text, not as a separate block).
176
+ */
177
+ function applyStartPlanSystem(body: Record<string, unknown>): boolean {
178
+ const model = typeof body.model === "string" ? body.model : undefined;
179
+ body.system = buildStartPlanSystem(body.system, model);
180
+ return true;
181
+ }
182
+
183
+ function applyStartPlanOpenAISystem(body: Record<string, unknown>): boolean {
184
+ const messages = body.messages;
185
+ if (!Array.isArray(messages)) return false;
186
+
187
+ const model = typeof body.model === "string" ? body.model : undefined;
188
+ const official = buildStartPlanSystem(undefined, model).map((block) => ({
189
+ role: "system",
190
+ content: typeof block === "object" && block !== null && "text" in block ? String(block.text) : "",
191
+ }));
192
+ body.messages = [...official, ...messages];
193
+ return true;
194
+ }
src/proxy/captcha-cpu-governor.ts ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import fs from "node:fs/promises";
2
+ import os from "node:os";
3
+
4
+ export type CpuGovernorConfig = {
5
+ /** Host CPU ceiling — 100 = all vCPUs saturated (0 disables governor). */
6
+ cpuLimitPercent: number;
7
+ /** Hysteresis band below limit before ramping up again. */
8
+ hysteresisPercent: number;
9
+ poolSizeMin: number;
10
+ poolSizeMax: number;
11
+ maxSolveConcurrency: number;
12
+ intervalMs: number;
13
+ };
14
+
15
+ export type CpuGovernorSnapshot = {
16
+ cpuPercent: number;
17
+ limitPercent: number;
18
+ concurrency: number;
19
+ maxEffectiveTarget: number;
20
+ throttled: boolean;
21
+ };
22
+
23
+ /** 100 = entire host (all vCPUs) may be used; governor prevents exceeding that. */
24
+ const DEFAULT_CPU_LIMIT = Number(process.env.CAPTCHA_CPU_LIMIT_PCT || 100);
25
+ const DEFAULT_INTERVAL_MS = Number(process.env.CAPTCHA_CPU_GOVERNOR_INTERVAL_MS || 2_000);
26
+ const TARGET_STEP = 15;
27
+
28
+ type CpuCounters = { idle: number; total: number };
29
+
30
+ async function readCpuCounters(): Promise<CpuCounters> {
31
+ try {
32
+ const stat = await fs.readFile("/proc/stat", "utf8");
33
+ const line = stat.split("\n")[0] ?? "";
34
+ const parts = line.split(/\s+/).slice(1).map((v) => Number(v) || 0);
35
+ const idle = (parts[3] ?? 0) + (parts[4] ?? 0);
36
+ const total = parts.reduce((sum, n) => sum + n, 0);
37
+ return { idle, total };
38
+ } catch {
39
+ const load = os.loadavg()[0] ?? 0;
40
+ const cpus = Math.max(1, os.cpus().length);
41
+ const pct = (load / cpus) * 100;
42
+ return { idle: 100 - pct, total: 100 };
43
+ }
44
+ }
45
+
46
+ /** Samples host-wide CPU via /proc/stat (100% = all cores busy). */
47
+ export class CaptchaCpuGovernor {
48
+ private prevCpu: CpuCounters | null = null;
49
+ private lastCpuPercent = 0;
50
+ private concurrency: number;
51
+ private maxEffectiveTarget: number;
52
+ private timer: ReturnType<typeof setInterval> | null = null;
53
+
54
+ constructor(private cfg: CpuGovernorConfig) {
55
+ this.concurrency = 1;
56
+ this.maxEffectiveTarget = cfg.poolSizeMin;
57
+ }
58
+
59
+ get enabled(): boolean {
60
+ return this.cfg.cpuLimitPercent > 0;
61
+ }
62
+
63
+ configure(partial: Partial<CpuGovernorConfig>): void {
64
+ this.cfg = { ...this.cfg, ...partial };
65
+ this.maxEffectiveTarget = Math.max(
66
+ this.cfg.poolSizeMin,
67
+ Math.min(this.maxEffectiveTarget, this.cfg.poolSizeMax),
68
+ );
69
+ this.concurrency = Math.min(this.concurrency, this.cfg.maxSolveConcurrency);
70
+ }
71
+
72
+ start(): void {
73
+ if (!this.enabled || this.timer) return;
74
+ void this.tick();
75
+ this.timer = setInterval(() => void this.tick(), this.cfg.intervalMs);
76
+ }
77
+
78
+ stop(): void {
79
+ if (this.timer) {
80
+ clearInterval(this.timer);
81
+ this.timer = null;
82
+ }
83
+ }
84
+
85
+ snapshot(): CpuGovernorSnapshot {
86
+ const limit = this.cfg.cpuLimitPercent;
87
+ return {
88
+ cpuPercent: Math.round(this.lastCpuPercent * 10) / 10,
89
+ limitPercent: limit,
90
+ concurrency: this.concurrency,
91
+ maxEffectiveTarget: this.maxEffectiveTarget,
92
+ throttled: this.lastCpuPercent >= limit - 3,
93
+ };
94
+ }
95
+
96
+ /** Parallel background solves allowed right now (may be 0 when pool is warm). */
97
+ backgroundConcurrency(readyTokens: number): number {
98
+ if (!this.enabled) return this.cfg.maxSolveConcurrency;
99
+
100
+ const cpu = this.lastCpuPercent;
101
+ const limit = this.cfg.cpuLimitPercent;
102
+ let allowed = this.concurrency;
103
+
104
+ if (cpu >= limit) {
105
+ allowed = 0;
106
+ } else if (cpu >= limit - 4) {
107
+ allowed = Math.min(allowed, 1);
108
+ } else if (cpu >= limit - 10) {
109
+ allowed = Math.min(allowed, 2);
110
+ }
111
+
112
+ if (readyTokens < this.cfg.poolSizeMin) {
113
+ return Math.max(1, allowed);
114
+ }
115
+
116
+ return allowed;
117
+ }
118
+
119
+ maxPoolTarget(): number {
120
+ return this.maxEffectiveTarget;
121
+ }
122
+
123
+ private async tick(): Promise<void> {
124
+ const cpu = await this.sampleCpuPercent();
125
+ this.lastCpuPercent = cpu;
126
+
127
+ const limit = this.cfg.cpuLimitPercent;
128
+ const rampThreshold = limit - this.cfg.hysteresisPercent;
129
+
130
+ if (cpu >= limit) {
131
+ this.concurrency = 1;
132
+ this.maxEffectiveTarget = this.cfg.poolSizeMin;
133
+ } else if (cpu >= limit - 4) {
134
+ if (this.concurrency > 1) this.concurrency -= 1;
135
+ this.maxEffectiveTarget = this.cfg.poolSizeMin;
136
+ } else if (cpu >= limit - 10) {
137
+ if (this.concurrency > 2) this.concurrency -= 1;
138
+ this.maxEffectiveTarget = Math.max(
139
+ this.cfg.poolSizeMin,
140
+ this.maxEffectiveTarget - TARGET_STEP,
141
+ );
142
+ } else if (cpu <= rampThreshold) {
143
+ if (this.concurrency < this.cfg.maxSolveConcurrency) {
144
+ this.concurrency += 1;
145
+ }
146
+ if (this.maxEffectiveTarget < this.cfg.poolSizeMax) {
147
+ this.maxEffectiveTarget = Math.min(
148
+ this.cfg.poolSizeMax,
149
+ this.maxEffectiveTarget + TARGET_STEP,
150
+ );
151
+ }
152
+ }
153
+ }
154
+
155
+ private async sampleCpuPercent(): Promise<number> {
156
+ const cur = await readCpuCounters();
157
+ if (!this.prevCpu) {
158
+ this.prevCpu = cur;
159
+ return this.lastCpuPercent;
160
+ }
161
+ const idleDelta = cur.idle - this.prevCpu.idle;
162
+ const totalDelta = cur.total - this.prevCpu.total;
163
+ this.prevCpu = cur;
164
+ if (totalDelta <= 0) return this.lastCpuPercent;
165
+ const used = ((totalDelta - idleDelta) / totalDelta) * 100;
166
+ return Math.max(0, Math.min(100, used));
167
+ }
168
+ }
169
+
170
+ export function resolveCpuGovernorConfig(opts: {
171
+ poolSizeMin?: number;
172
+ poolSizeMax?: number;
173
+ solveConcurrency?: number;
174
+ cpuLimitPercent?: number;
175
+ cpuGovernorIntervalSec?: number;
176
+ }): CpuGovernorConfig {
177
+ const poolSizeMin = opts.poolSizeMin ?? Number(process.env.CAPTCHA_POOL_MIN || 40);
178
+ const poolSizeMax = Math.max(
179
+ poolSizeMin,
180
+ opts.poolSizeMax ?? Number(process.env.CAPTCHA_POOL_MAX || 120),
181
+ );
182
+ const maxSolveConcurrency =
183
+ opts.solveConcurrency ??
184
+ Number(
185
+ process.env.CAPTCHA_SOLVE_CONCURRENCY ||
186
+ (process.env.ZCODE_CAPTCHA_LOW_CPU === "1" ? 3 : 6),
187
+ );
188
+
189
+ const cpuLimitPercent =
190
+ opts.cpuLimitPercent ??
191
+ (process.env.CAPTCHA_CPU_GOVERNOR === "0" ? 0 : DEFAULT_CPU_LIMIT);
192
+
193
+ const intervalMs =
194
+ opts.cpuGovernorIntervalSec != null
195
+ ? opts.cpuGovernorIntervalSec * 1000
196
+ : DEFAULT_INTERVAL_MS;
197
+
198
+ return {
199
+ cpuLimitPercent,
200
+ hysteresisPercent: 5,
201
+ poolSizeMin,
202
+ poolSizeMax,
203
+ maxSolveConcurrency,
204
+ intervalMs,
205
+ };
206
+ }
src/proxy/captcha-happy.ts ADDED
The diff for this file is too large to render. See raw diff
 
src/proxy/captcha-pool.ts ADDED
@@ -0,0 +1,721 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import {
2
+ CaptchaCpuGovernor,
3
+ resolveCpuGovernorConfig,
4
+ type CpuGovernorSnapshot,
5
+ } from "./captcha-cpu-governor.js";
6
+ import {
7
+ captchaSolverConcurrency,
8
+ runCaptchaSolve,
9
+ setCaptchaSolverConcurrency,
10
+ shutdownCaptchaSolver,
11
+ } from "./captcha-solver.js";
12
+ import { isCaptchaDuplicateError, isCaptchaIpBlockError, parseCertifyId } from "./captcha-token.js";
13
+
14
+ export interface CaptchaPoolOptions {
15
+ /** @deprecated Use poolSizeMax — kept as max cap alias. */
16
+ poolSize?: number;
17
+ poolSizeMin?: number;
18
+ poolSizeMax?: number;
19
+ /** Idle seconds before shrinking toward min (default 120). */
20
+ scaleDownIdleMs?: number;
21
+ /** Deep-idle floor: pool target decays to this after sustained zero traffic
22
+ * (default 1). First token take restores the full poolSizeMin. */
23
+ idleFloor?: number;
24
+ /** Zero-traffic seconds after which background solving stops entirely —
25
+ * target floor decays to 0 (default 900). One banked token is still kept
26
+ * for an instant serve on wake-up. */
27
+ deepIdleAfterMs?: number;
28
+ tokenTtlMs?: number;
29
+ refillIntervalMs?: number;
30
+ solveRetries?: number;
31
+ staggerMs?: number;
32
+ solveConcurrency?: number;
33
+ /** Parallel solves raced when a take finds the pool empty (default 2). */
34
+ emptyTakeRace?: number;
35
+ /** Host CPU ceiling for captcha workers (default 100, 0 = off). */
36
+ cpuLimitPercent?: number;
37
+ cpuGovernorIntervalSec?: number;
38
+ /**
39
+ * Called when minting fails with an IP-level block ("too many captcha
40
+ * requests" family). The proxy wires this to the Telegram network reset so
41
+ * an Aliyun IP block self-heals instead of stranding the token pool.
42
+ */
43
+ onCaptchaIpBlock?: (reason: string) => void;
44
+ }
45
+
46
+ type TokenEntry = { param: string; cachedAt: number; certifyId: string | null };
47
+
48
+ /** Tracks certifyIds already handed out or queued — prevents F008 duplicate usage. */
49
+ class CertifyIdRegistry {
50
+ private seen = new Map<string, number>();
51
+
52
+ constructor(private ttlMs: number) {}
53
+
54
+ setTtlMs(ttlMs: number): void {
55
+ this.ttlMs = ttlMs;
56
+ }
57
+
58
+ prune(): void {
59
+ const cutoff = Date.now() - this.ttlMs;
60
+ for (const [id, at] of this.seen) {
61
+ if (at < cutoff) this.seen.delete(id);
62
+ }
63
+ }
64
+
65
+ has(id: string): boolean {
66
+ this.prune();
67
+ return this.seen.has(id);
68
+ }
69
+
70
+ add(id: string): void {
71
+ this.prune();
72
+ this.seen.set(id, Date.now());
73
+ }
74
+
75
+ clear(): void {
76
+ this.seen.clear();
77
+ }
78
+ }
79
+
80
+ const DEFAULT_POOL_MIN = Number(process.env.CAPTCHA_POOL_MIN || 40);
81
+ const DEFAULT_POOL_MAX = Number(process.env.CAPTCHA_POOL_MAX || 120);
82
+ const DEFAULT_TOKEN_TTL_MS = Number(process.env.CAPTCHA_CACHE_TTL_MS || 95_000);
83
+ const DEFAULT_REFILL_INTERVAL_MS = Number(process.env.CAPTCHA_REFILL_INTERVAL_MS || 1_000);
84
+ const DEFAULT_STAGGER_MS = Number(process.env.CAPTCHA_SOLVE_STAGGER_MS || 0);
85
+ const DEFAULT_SOLVE_CONCURRENCY = Number(
86
+ process.env.CAPTCHA_SOLVE_CONCURRENCY ||
87
+ (process.env.ZCODE_CAPTCHA_LOW_CPU === "1" ? 3 : 8),
88
+ );
89
+ const DEFAULT_SCALE_DOWN_IDLE_MS = Number(process.env.CAPTCHA_POOL_SCALE_DOWN_IDLE_MS || 120_000);
90
+ const DEFAULT_IDLE_FLOOR = Number(process.env.CAPTCHA_POOL_IDLE_FLOOR || 1);
91
+ // Zero-traffic beyond this stops background solving entirely (floor 0): no
92
+ // mint churn, near-zero CPU. The next token take restores poolSizeMin.
93
+ const DEFAULT_DEEP_IDLE_AFTER_MS = Number(process.env.CAPTCHA_DEEP_IDLE_AFTER_MS || 900_000);
94
+ // Parallel solves raced on an empty-pool take — first success serves the
95
+ // client, the twins top up the pool. Cuts worst-case cold TTFB and widens
96
+ // odds against a bad rotated pe bundle stalling one racer.
97
+ const EMPTY_TAKE_RACE = Math.max(1, Number(process.env.CAPTCHA_EMPTY_TAKE_RACE || 3));
98
+ const SOLVE_RETRIES = Number(process.env.ZCODE_CAPTCHA_RETRIES || 4);
99
+ const SCALE_UP_STEP = 20;
100
+ const TAKE_RATE_WINDOW_MS = 120_000;
101
+
102
+ type ResolvedPoolOpts = {
103
+ poolSizeMin: number;
104
+ poolSizeMax: number;
105
+ idleFloor: number;
106
+ deepIdleAfterMs: number;
107
+ scaleDownIdleMs: number;
108
+ tokenTtlMs: number;
109
+ refillIntervalMs: number;
110
+ solveRetries: number;
111
+ staggerMs: number;
112
+ solveConcurrency: number;
113
+ emptyTakeRace: number;
114
+ onCaptchaIpBlock?: (reason: string) => void;
115
+ };
116
+
117
+ function resolvePoolOpts(opts: CaptchaPoolOptions): ResolvedPoolOpts {
118
+ const max = opts.poolSizeMax ?? opts.poolSize ?? DEFAULT_POOL_MAX;
119
+ const min = Math.min(opts.poolSizeMin ?? DEFAULT_POOL_MIN, max);
120
+ return {
121
+ poolSizeMin: min,
122
+ poolSizeMax: max,
123
+ idleFloor: Math.min(opts.idleFloor ?? DEFAULT_IDLE_FLOOR, min),
124
+ deepIdleAfterMs: Math.max(
125
+ opts.deepIdleAfterMs ?? DEFAULT_DEEP_IDLE_AFTER_MS,
126
+ opts.scaleDownIdleMs ?? DEFAULT_SCALE_DOWN_IDLE_MS,
127
+ ),
128
+ scaleDownIdleMs: opts.scaleDownIdleMs ?? DEFAULT_SCALE_DOWN_IDLE_MS,
129
+ tokenTtlMs: opts.tokenTtlMs ?? DEFAULT_TOKEN_TTL_MS,
130
+ refillIntervalMs: opts.refillIntervalMs ?? DEFAULT_REFILL_INTERVAL_MS,
131
+ solveRetries: opts.solveRetries ?? SOLVE_RETRIES,
132
+ staggerMs: opts.staggerMs ?? DEFAULT_STAGGER_MS,
133
+ solveConcurrency: opts.solveConcurrency ?? DEFAULT_SOLVE_CONCURRENCY,
134
+ emptyTakeRace: Math.max(1, opts.emptyTakeRace ?? EMPTY_TAKE_RACE),
135
+ onCaptchaIpBlock: opts.onCaptchaIpBlock,
136
+ };
137
+ }
138
+
139
+ export class CaptchaTokenPool {
140
+ private tokens: TokenEntry[] = [];
141
+ private opts: ResolvedPoolOpts;
142
+ private effectiveTarget: number;
143
+ private refillTimer: ReturnType<typeof setInterval> | null = null;
144
+ private refillInFlight = false;
145
+ private lastSolveAt = 0;
146
+ private activeSolves = 0;
147
+ private cfg: CaptchaConfig | null = null;
148
+ private pausedUntil = 0;
149
+ private lastTakeAt: number;
150
+ private takeTimestamps: number[] = [];
151
+ private certifyIds: CertifyIdRegistry;
152
+ private governor: CaptchaCpuGovernor | null = null;
153
+ // Mint-storm detection: sliding windows of failed vs successful mint
154
+ // attempts. A burst of failures with zero successes means velocity/IP
155
+ // flagging — fire the telegram IP reset automatically.
156
+ private mintFailures: number[] = [];
157
+ private mintSuccesses: number[] = [];
158
+ private lastStormResetAt = 0;
159
+
160
+ constructor(opts: CaptchaPoolOptions = {}) {
161
+ // The module-level singleton constructs with no opts before config load;
162
+ // resolvePoolOpts would fall back to env/global defaults there (e.g.
163
+ // poolSizeMin 40) and configure()'s clamp would preserve that as the
164
+ // starting target — minting a storm of soon-expired tokens at every
165
+ // boot. With no explicit opts, defer sizing to the first configure().
166
+ const hasOpts = Object.keys(opts).length > 0;
167
+ this.opts = resolvePoolOpts(opts);
168
+ this.effectiveTarget = hasOpts ? this.opts.poolSizeMin : 0;
169
+ // Seed idle clock at startup so a no-traffic proxy decays to idleFloor
170
+ // instead of solving 40-60 tokens forever (lastTakeAt=0 disabled decay).
171
+ this.lastTakeAt = Date.now();
172
+ this.certifyIds = new CertifyIdRegistry(this.opts.tokenTtlMs);
173
+ this.initGovernor(opts);
174
+ setCaptchaSolverConcurrency(this.opts.solveConcurrency);
175
+ }
176
+
177
+ configure(opts: CaptchaPoolOptions): void {
178
+ this.opts = resolvePoolOpts({ ...this.opts, ...opts });
179
+ this.certifyIds.setTtlMs(this.opts.tokenTtlMs);
180
+ this.effectiveTarget = Math.max(
181
+ this.opts.poolSizeMin,
182
+ Math.min(this.effectiveTarget, this.opts.poolSizeMax),
183
+ );
184
+ this.initGovernor(opts);
185
+ // Propagate the resolved concurrency to the solver daemon — the
186
+ // import-time constructor runs before config load and would otherwise
187
+ // leave the daemon at its fallback (8) instead of the configured value.
188
+ setCaptchaSolverConcurrency(this.opts.solveConcurrency);
189
+ this.trimToTarget();
190
+ }
191
+
192
+ stats(): {
193
+ ready: number;
194
+ target: number;
195
+ min: number;
196
+ max: number;
197
+ activeSolves: number;
198
+ solverWorkers: number;
199
+ cpu?: CpuGovernorSnapshot;
200
+ } {
201
+ this.pruneExpired();
202
+ return {
203
+ ready: this.tokens.length,
204
+ target: this.effectiveTarget,
205
+ min: this.opts.poolSizeMin,
206
+ max: this.opts.poolSizeMax,
207
+ activeSolves: this.activeSolves,
208
+ solverWorkers: captchaSolverConcurrency(),
209
+ cpu: this.governor?.enabled ? this.governor.snapshot() : undefined,
210
+ };
211
+ }
212
+
213
+ invalidate(): void {
214
+ this.tokens = [];
215
+ this.certifyIds.clear();
216
+ this.pausedUntil = Date.now() + this.opts.staggerMs;
217
+ }
218
+
219
+ startBackgroundRefill(cfg: CaptchaConfig): void {
220
+ this.cfg = cfg;
221
+ this.stopBackgroundRefill();
222
+ this.governor?.start();
223
+ void this.refill({ urgent: false });
224
+ this.refillTimer = setInterval(() => {
225
+ void this.refill({ urgent: false });
226
+ }, this.opts.refillIntervalMs);
227
+ }
228
+
229
+ stopBackgroundRefill(): void {
230
+ this.governor?.stop();
231
+ if (this.refillTimer) {
232
+ clearInterval(this.refillTimer);
233
+ this.refillTimer = null;
234
+ }
235
+ }
236
+
237
+ async takeToken(cfg: CaptchaConfig): Promise<string> {
238
+ this.cfg = cfg;
239
+
240
+ const readyBefore = this.tokens.length;
241
+ const token = this.popFresh();
242
+ if (token) {
243
+ this.onTokenTaken(false, readyBefore - 1);
244
+ void this.refill({ urgent: true });
245
+ return token;
246
+ }
247
+
248
+ this.onTokenTaken(true, 0);
249
+ // Re-size immediately from current demand (this take is already in the
250
+ // window) so an empty-pool arrival widens the buffer right away.
251
+ this.effectiveTarget = Math.max(this.effectiveTarget, this.computeActiveTarget());
252
+ let param: string;
253
+ try {
254
+ // Overall deadline for the racing chain: during mint storms a racer can
255
+ // grind through its retry budget (~30-45s) — cap the client-facing wait
256
+ // and let the background waves finish the job instead.
257
+ const raceDeadlineMs = Number(process.env.CAPTCHA_SOLVE_RACE_DEADLINE_MS || 25_000);
258
+ param = await Promise.race([
259
+ this.solveRaced(cfg),
260
+ new Promise<never>((_, rej) =>
261
+ setTimeout(
262
+ () => rej(new Error(`captcha take deadline (${raceDeadlineMs}ms)`)),
263
+ Math.max(1_000, raceDeadlineMs),
264
+ ),
265
+ ),
266
+ ]);
267
+ } catch (err) {
268
+ // Mints fail in clusters (pe-stall storms, F008 velocity). Background
269
+ // refill waves keep retrying — give them a short window to land a
270
+ // token before surfacing a failure to the client. This converts most
271
+ // storm-window 503s into slower successes.
272
+ const graceMs = Number(process.env.CAPTCHA_TAKE_GRACE_MS || 10_000);
273
+ const deadline = Date.now() + Math.max(0, graceMs);
274
+ while (Date.now() < deadline) {
275
+ await new Promise((r) => setTimeout(r, 400));
276
+ const token = this.popFresh();
277
+ if (token) {
278
+ this.markParamIssued(token);
279
+ void this.refill({ urgent: true });
280
+ return token;
281
+ }
282
+ }
283
+ throw err;
284
+ }
285
+ this.markParamIssued(param);
286
+ void this.refill({ urgent: true });
287
+ return param;
288
+ }
289
+
290
+ async prefill(cfg: CaptchaConfig, count?: number): Promise<void> {
291
+ this.cfg = cfg;
292
+ const target = Math.min(count ?? this.effectiveTarget, this.effectiveTarget);
293
+ while (this.tokens.length + this.activeSolves < target) {
294
+ const need = target - this.tokens.length - this.activeSolves;
295
+ if (need <= 0) break;
296
+ const concurrency = this.governor?.enabled
297
+ ? this.governor.backgroundConcurrency(this.tokens.length)
298
+ : this.opts.solveConcurrency;
299
+ await this.solveBatch(cfg, need, Math.max(1, concurrency));
300
+ }
301
+ }
302
+
303
+ requestUrgentRefill(): void {
304
+ void this.refill({ urgent: true });
305
+ }
306
+
307
+ private poolHasCertifyId(certifyId: string): boolean {
308
+ return this.tokens.some((t) => t.certifyId === certifyId);
309
+ }
310
+
311
+ private isDuplicateParam(param: string): boolean {
312
+ const certifyId = parseCertifyId(param);
313
+ if (!certifyId) return false;
314
+ return this.certifyIds.has(certifyId) || this.poolHasCertifyId(certifyId);
315
+ }
316
+
317
+ private markParamIssued(param: string): void {
318
+ const certifyId = parseCertifyId(param);
319
+ if (certifyId) this.certifyIds.add(certifyId);
320
+ }
321
+
322
+ private popFresh(): string | null {
323
+ this.pruneExpired();
324
+ while (this.tokens.length > 0) {
325
+ const entry = this.tokens.pop()!;
326
+ if (entry.certifyId && this.certifyIds.has(entry.certifyId)) continue;
327
+ this.markParamIssued(entry.param);
328
+ return entry.param;
329
+ }
330
+ return null;
331
+ }
332
+
333
+ private pushToken(param: string): void {
334
+ this.pruneExpired();
335
+ if (this.tokens.length >= this.effectiveTarget) return;
336
+ const certifyId = parseCertifyId(param);
337
+ if (certifyId && (this.certifyIds.has(certifyId) || this.poolHasCertifyId(certifyId))) {
338
+ return;
339
+ }
340
+ this.tokens.push({ param, cachedAt: Date.now(), certifyId });
341
+ }
342
+
343
+ private pruneExpired(): void {
344
+ const now = Date.now();
345
+ this.tokens = this.tokens.filter((t) => now - t.cachedAt < this.opts.tokenTtlMs);
346
+ }
347
+
348
+ private deficit(): number {
349
+ this.pruneExpired();
350
+ return Math.max(0, this.effectiveTarget - this.tokens.length - this.activeSolves);
351
+ }
352
+
353
+ private pruneTakeWindow(): void {
354
+ const cutoff = Date.now() - TAKE_RATE_WINDOW_MS;
355
+ this.takeTimestamps = this.takeTimestamps.filter((t) => t > cutoff);
356
+ }
357
+
358
+ private demandTarget(): number {
359
+ this.pruneTakeWindow();
360
+ if (this.takeTimestamps.length === 0) return this.opts.poolSizeMin;
361
+ const ratePerSec = this.takeTimestamps.length / (TAKE_RATE_WINDOW_MS / 1000);
362
+ const ttlSec = this.opts.tokenTtlMs / 1000;
363
+ return Math.ceil(ratePerSec * ttlSec * 1.25);
364
+ }
365
+
366
+ /**
367
+ * Target while traffic is recent: measured demand (take rate × TTL ×
368
+ * margin) plus one token of arrival-jitter headroom, floored at
369
+ * poolSizeMin, capped by governor + poolSizeMax. This is the ONLY sizing
370
+ * authority while active — bursts raise demand, quiet periods drain it.
371
+ */
372
+ private computeActiveTarget(): number {
373
+ const demand = Math.max(this.demandTarget(), this.opts.poolSizeMin);
374
+ const raw = Math.ceil(demand * 1.25) + 1;
375
+ const governorMax = this.governor?.maxPoolTarget() ?? this.opts.poolSizeMax;
376
+ return Math.max(
377
+ this.currentFloor(),
378
+ Math.min(this.opts.poolSizeMax, governorMax, raw),
379
+ );
380
+ }
381
+
382
+ private onTokenTaken(wasEmpty: boolean, readyAfter: number): void {
383
+ this.lastTakeAt = Date.now();
384
+ this.takeTimestamps.push(this.lastTakeAt);
385
+ this.pruneTakeWindow();
386
+ this.wakeFromIdle();
387
+ // Sizing is demand-driven via computeActiveTarget() on the next refill
388
+ // tick; takes only need to restore the active floor instantly.
389
+ }
390
+
391
+ private maybeScaleDown(): void {
392
+ if (this.lastTakeAt === 0) return;
393
+ const idleMs = Date.now() - this.lastTakeAt;
394
+ if (idleMs < this.opts.scaleDownIdleMs) return;
395
+
396
+ this.pruneTakeWindow();
397
+ const recentTakes = this.takeTimestamps.filter((t) => t > Date.now() - 60_000).length;
398
+ if (recentTakes > 1) return;
399
+
400
+ // Deep idle: decay the effective floor itself so Chromium workers and
401
+ // solve churn wind down — first toward idleFloor, then to zero after
402
+ // deepIdleAfterMs (no background mints at all). Any token take snaps the
403
+ // floor back to full poolSizeMin.
404
+ const floor = this.currentFloor();
405
+ if (this.effectiveTarget > floor) {
406
+ this.effectiveTarget = Math.max(floor, this.effectiveTarget - SCALE_UP_STEP);
407
+ this.trimToTarget();
408
+ }
409
+ }
410
+
411
+ /**
412
+ * Active traffic → poolSizeMin. After scaleDownIdleMs of no takes →
413
+ * idleFloor (keeper churn ≈ 1 mint/TTL). After deepIdleAfterMs → 0:
414
+ * background solving stops; the banked token still serves a wake-up take.
415
+ */
416
+ private currentFloor(): number {
417
+ if (this.lastTakeAt === 0) return this.opts.poolSizeMin;
418
+ const idleMs = Date.now() - this.lastTakeAt;
419
+ if (idleMs >= this.opts.deepIdleAfterMs) return 0;
420
+ if (idleMs >= this.opts.scaleDownIdleMs) {
421
+ return Math.min(this.opts.idleFloor, this.opts.poolSizeMin);
422
+ }
423
+ return this.opts.poolSizeMin;
424
+ }
425
+
426
+ /** Traffic returned: restore the full configured floor immediately. */
427
+ private wakeFromIdle(): void {
428
+ if (this.effectiveTarget < this.opts.poolSizeMin) {
429
+ this.effectiveTarget = this.opts.poolSizeMin;
430
+ }
431
+ }
432
+
433
+ private trimToTarget(): void {
434
+ this.pruneExpired();
435
+ // Never trim the last banked token: it serves a wake-up take instantly
436
+ // (free TTFB) and expires naturally via pruneExpired.
437
+ const floor = Math.max(this.effectiveTarget, 1);
438
+ while (this.tokens.length > floor) {
439
+ this.tokens.shift();
440
+ }
441
+ }
442
+
443
+ private applyGovernorCaps(): void {
444
+ if (!this.governor?.enabled) return;
445
+ const governorMax = this.governor.maxPoolTarget();
446
+ // Floor is idle-aware (idleFloor → 0 past deepIdleAfterMs) — don't clamp
447
+ // it back up (that would refill forever during idle).
448
+ const floor = this.currentFloor();
449
+ this.effectiveTarget = Math.max(
450
+ floor,
451
+ Math.min(this.effectiveTarget, governorMax, this.opts.poolSizeMax),
452
+ );
453
+ }
454
+
455
+ private async refill(opts: { urgent: boolean }): Promise<void> {
456
+ if (!this.cfg) return;
457
+ // Refresh sizing BEFORE the in-flight guard: a fill batch with slow or
458
+ // stalling solves can hold refillInFlight for minutes, and freezing the
459
+ // target that whole time starves the buffer exactly when demand exists.
460
+ const idleDecay =
461
+ this.lastTakeAt > 0 && Date.now() - this.lastTakeAt >= this.opts.scaleDownIdleMs;
462
+ if (!idleDecay) {
463
+ this.effectiveTarget = this.computeActiveTarget();
464
+ } else {
465
+ this.maybeScaleDown();
466
+ }
467
+
468
+ // Idle decay: drop the target toward the current floor (idleFloor → 0
469
+ // past deepIdleAfterMs) and skip background solves while enough banked
470
+ // tokens remain. This is what stops mint churn at zero traffic.
471
+ if (!opts.urgent && idleDecay) {
472
+ if (this.tokens.length >= Math.max(this.currentFloor(), 1)) return;
473
+ }
474
+
475
+ if (this.refillInFlight || Date.now() < this.pausedUntil) return;
476
+
477
+ this.applyGovernorCaps();
478
+
479
+ const ready = this.tokens.length;
480
+ const concurrency = this.governor?.enabled
481
+ ? opts.urgent
482
+ ? Math.max(1, this.governor.backgroundConcurrency(ready) || this.governor.snapshot().concurrency)
483
+ : this.governor.backgroundConcurrency(ready)
484
+ : this.opts.solveConcurrency;
485
+
486
+ if (!opts.urgent && concurrency === 0 && ready >= this.opts.poolSizeMin) {
487
+ return;
488
+ }
489
+
490
+ const need = this.deficit();
491
+ if (need <= 0) return;
492
+
493
+ this.refillInFlight = true;
494
+ try {
495
+ await this.solveBatch(this.cfg, need, Math.max(1, concurrency));
496
+ } finally {
497
+ this.refillInFlight = false;
498
+ }
499
+ }
500
+
501
+ /** Fire up to `need` solves in parallel waves of solveConcurrency. */
502
+ private async solveBatch(cfg: CaptchaConfig, need: number, concurrency = this.opts.solveConcurrency): Promise<void> {
503
+ let remaining = need;
504
+ while (remaining > 0 && this.tokens.length + this.activeSolves < this.effectiveTarget) {
505
+ const wave = Math.min(remaining, concurrency, this.deficit());
506
+ if (wave <= 0) break;
507
+ if (this.opts.staggerMs > 0) await this.waitForStagger();
508
+ const results = await Promise.allSettled(
509
+ Array.from({ length: wave }, () => this.solveOne(cfg)),
510
+ );
511
+ for (const r of results) {
512
+ if (r.status === "fulfilled") {
513
+ this.pushToken(r.value);
514
+ } else {
515
+ console.warn("[captcha-pool] parallel solve failed:", r.reason);
516
+ }
517
+ }
518
+ remaining -= wave;
519
+ if (results.every((r) => r.status === "rejected")) break;
520
+ }
521
+ }
522
+
523
+ private async waitForStagger(): Promise<void> {
524
+ const elapsed = Date.now() - this.lastSolveAt;
525
+ const wait = this.opts.staggerMs - elapsed;
526
+ if (wait > 0) {
527
+ await new Promise((r) => setTimeout(r, wait));
528
+ }
529
+ }
530
+
531
+ private noteMintFailure(reason: string): void {
532
+ const now = Date.now();
533
+ this.mintFailures.push(now);
534
+ const cutoff = now - 360_000;
535
+ this.mintFailures = this.mintFailures.filter((t) => t > cutoff);
536
+ this.maybeFireMintStormReset(reason);
537
+ }
538
+
539
+ private noteMintSuccess(): void {
540
+ const now = Date.now();
541
+ this.mintSuccesses.push(now);
542
+ const cutoff = now - 360_000;
543
+ this.mintSuccesses = this.mintSuccesses.filter((t) => t > cutoff);
544
+ }
545
+
546
+ /** Velocity/IP flagging signature: many failed mints in the last 5 min
547
+ * while nothing succeeded in the last 3. Fires the telegram IP reset at
548
+ * most once per cooldown — requestCaptchaIpResetSync dedupes further. */
549
+ private maybeFireMintStormReset(latestReason: string): void {
550
+ const now = Date.now();
551
+ const fails = this.mintFailures.filter((t) => t > now - 300_000).length;
552
+ const succs = this.mintSuccesses.filter((t) => t > now - 180_000).length;
553
+ if (fails < 8 || succs > 0) return;
554
+ if (now - this.lastStormResetAt < 12 * 60_000) return;
555
+ this.lastStormResetAt = now;
556
+ console.warn(
557
+ `[captcha] mint storm detected (${fails} failures/5min, ${succs} successes/3min; latest: ${latestReason.slice(0, 120)}) -> requesting IP reset`,
558
+ );
559
+ try {
560
+ this.opts.onCaptchaIpBlock?.(`mint storm: ${fails} failed mints in 5min`);
561
+ } catch {
562
+ // callback is best-effort; never break the pool
563
+ }
564
+ }
565
+
566
+ private async solveFresh(cfg: CaptchaConfig): Promise<string> {
567
+ this.activeSolves += 1;
568
+ this.lastSolveAt = Date.now();
569
+ try {
570
+ let lastErr: string | null = null;
571
+ let sawIpBlock = false;
572
+ for (let attempt = 1; attempt <= this.opts.solveRetries; attempt += 1) {
573
+ try {
574
+ const param = await runCaptchaSolve(cfg.sceneId, cfg.region, cfg.prefix);
575
+ if (!param) {
576
+ lastErr = "solver returned empty";
577
+ continue;
578
+ }
579
+ if (this.isDuplicateParam(param)) {
580
+ lastErr = `duplicate certifyId ${parseCertifyId(param) ?? "?"}`;
581
+ continue;
582
+ }
583
+ this.noteMintSuccess();
584
+ return param;
585
+ } catch (err) {
586
+ lastErr = err instanceof Error ? err.message : String(err);
587
+ if (isCaptchaDuplicateError(lastErr)) {
588
+ lastErr = `duplicate certifyId (F008)`;
589
+ } else if (isCaptchaIpBlockError(lastErr)) {
590
+ sawIpBlock = true;
591
+ }
592
+ this.noteMintFailure(lastErr);
593
+ }
594
+ }
595
+ // All retries failed. If any failure was an IP-level block, ask the
596
+ // caller to rotate the egress (Telegram network reset) so the next
597
+ // mint has a fresh IP instead of being stuck unable to mint.
598
+ if (sawIpBlock && this.opts.onCaptchaIpBlock) {
599
+ try {
600
+ this.opts.onCaptchaIpBlock(lastErr ?? "captcha ip block");
601
+ } catch (_) {
602
+ // callback is best-effort; never let it break the pool
603
+ }
604
+ }
605
+ throw new Error(`captcha failed after ${this.opts.solveRetries} attempts: ${lastErr ?? "unknown"}`);
606
+ } finally {
607
+ this.activeSolves -= 1;
608
+ }
609
+ }
610
+
611
+ private async solveOne(cfg: CaptchaConfig): Promise<string> {
612
+ return this.solveFresh(cfg);
613
+ }
614
+
615
+ /**
616
+ * Empty-pool serve: race up to `emptyTakeRace` solves in parallel and
617
+ * resolve with the first success so the client waits for one mint, not a
618
+ * sequential retry chain. Extra successes are banked into the pool instead
619
+ * of being wasted; the race only rejects when every racer fails.
620
+ */
621
+ private solveRaced(cfg: CaptchaConfig): Promise<string> {
622
+ const racers = Math.max(1, Math.min(this.opts.emptyTakeRace, this.opts.solveConcurrency));
623
+ if (racers <= 1) return this.solveFresh(cfg);
624
+
625
+ return new Promise<string>((resolve, reject) => {
626
+ let pending = racers;
627
+ let served = false;
628
+ let lastErr: unknown = null;
629
+ for (let i = 0; i < racers; i += 1) {
630
+ this.solveFresh(cfg).then(
631
+ (param) => {
632
+ if (served) {
633
+ // Lost the race but minted a valid token — bank it.
634
+ this.pushToken(param);
635
+ } else {
636
+ served = true;
637
+ resolve(param);
638
+ }
639
+ },
640
+ (err) => {
641
+ lastErr = err ?? lastErr;
642
+ },
643
+ ).finally(() => {
644
+ pending -= 1;
645
+ if (pending === 0 && !served) {
646
+ reject(
647
+ lastErr instanceof Error
648
+ ? lastErr
649
+ : new Error(String(lastErr ?? "captcha race failed")),
650
+ );
651
+ }
652
+ });
653
+ }
654
+ });
655
+ }
656
+
657
+ private initGovernor(opts: CaptchaPoolOptions): void {
658
+ const cfg = resolveCpuGovernorConfig({
659
+ poolSizeMin: this.opts.poolSizeMin,
660
+ poolSizeMax: this.opts.poolSizeMax,
661
+ solveConcurrency: this.opts.solveConcurrency,
662
+ cpuLimitPercent: opts.cpuLimitPercent,
663
+ cpuGovernorIntervalSec: opts.cpuGovernorIntervalSec,
664
+ });
665
+ if (!this.governor) {
666
+ this.governor = new CaptchaCpuGovernor(cfg);
667
+ } else {
668
+ this.governor.configure(cfg);
669
+ }
670
+ }
671
+ }
672
+
673
+ export interface CaptchaConfig {
674
+ enabled: boolean;
675
+ prefix: string;
676
+ sceneId: string;
677
+ region: string;
678
+ }
679
+
680
+ const pool = new CaptchaTokenPool();
681
+
682
+ export function configureCaptchaPool(opts: CaptchaPoolOptions): void {
683
+ pool.configure(opts);
684
+ }
685
+
686
+ export function getCaptchaPoolStats(): {
687
+ ready: number;
688
+ target: number;
689
+ min?: number;
690
+ max?: number;
691
+ activeSolves: number;
692
+ solverWorkers?: number;
693
+ } {
694
+ return pool.stats();
695
+ }
696
+
697
+ export function stopCaptchaPool(): void {
698
+ pool.stopBackgroundRefill();
699
+ shutdownCaptchaSolver();
700
+ }
701
+
702
+ export async function takeCaptchaToken(cfg: CaptchaConfig): Promise<string> {
703
+ if (!cfg.enabled || !cfg.prefix || !cfg.sceneId) {
704
+ throw new Error("Captcha config unavailable from ZCode API");
705
+ }
706
+ return pool.takeToken(cfg);
707
+ }
708
+
709
+ export function startCaptchaPoolRefill(cfg: CaptchaConfig): void {
710
+ if (!cfg.enabled || !cfg.prefix || !cfg.sceneId) return;
711
+ pool.startBackgroundRefill(cfg);
712
+ }
713
+
714
+ export async function prefillCaptchaPool(cfg: CaptchaConfig, count?: number): Promise<void> {
715
+ if (!cfg.enabled || !cfg.prefix || !cfg.sceneId) return;
716
+ await pool.prefill(cfg, count);
717
+ }
718
+
719
+ export function urgentCaptchaRefill(): void {
720
+ pool.requestUrgentRefill();
721
+ }
src/proxy/captcha-retry.ts ADDED
@@ -0,0 +1,186 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Shared captcha (3007) challenge detection + single-retry flow.
3
+ *
4
+ * The challenge arrives in two variants (observed 2026-08-29, PR #38):
5
+ * 1. response-header variant — `x-aliyun-captcha-verify-param` set on a
6
+ * non-2xx response (`captcha.detectCaptchaChallenge`);
7
+ * 2. in-body variant — HTTP 400 with `{"code":3007,...}` in the JSON body
8
+ * and no captcha header.
9
+ *
10
+ * Both the chat hot path (handler.ts) and /v1/responses (responses-handler.ts)
11
+ * used to hand-roll this detection and the re-solve/retry, and the copies had
12
+ * drifted (error mapping, peek handling). This module is the unified seam.
13
+ *
14
+ * Runtime-import discipline: only TYPE imports from ./captcha.js — the real
15
+ * module (which drags in the happy-dom solver) is lazily loaded by the
16
+ * callers and passed in as a value, so non-start-plan processes never pay
17
+ * its startup cost.
18
+ */
19
+ import type * as CaptchaExports from "./captcha.js";
20
+
21
+ /** Shape the callers pass in — satisfied by the real captcha module or test fakes. */
22
+ export type CaptchaModuleLike = Pick<typeof CaptchaExports, "detectCaptchaChallenge" | "getCaptchaToken" | "RETRY_HEADERS">;
23
+
24
+ /** Magic strings of the in-body challenge, for both JSON spacing styles. */
25
+ export const IN_BODY_CHALLENGE_MARKERS = ['"code":3007', '"code": 3007'] as const;
26
+
27
+ /** Bound on how many raw (possibly compressed) body bytes a challenge peek reads. */
28
+ export const MAX_CHALLENGE_PEEK_BYTES = 64 * 1024;
29
+
30
+ /** Bound on decompressed sniff output — error bodies are small; more is waste. */
31
+ const MAX_SNIFF_INFLATED_BYTES = 256 * 1024;
32
+
33
+ /**
34
+ * Peek (bounded) the body of a non-ok, non-SSE response and detect the
35
+ * in-body 3007 challenge. The response stays consumable for the error path:
36
+ * the peek reads a CLONE, so the original body is untouched.
37
+ *
38
+ * Covers both passthrough transports where the body may arrive still
39
+ * gzip-compressed (Bun fetch `decompress:false`, ordered raw-TCP): when the
40
+ * response advertises `content-encoding: gzip|x-gzip`, the peek inflates
41
+ * before sniffing. On a runtime that already auto-inflated the body while
42
+ * keeping the header (Node undici), inflation fails and the raw bytes are
43
+ * sniffed as-is.
44
+ */
45
+ export async function detectInBodyChallenge(resp: Response): Promise<boolean> {
46
+ if (resp.ok) return false;
47
+ const ctype = resp.headers.get("content-type") ?? "";
48
+ if (ctype.includes("text/event-stream")) return false;
49
+ let bytes: Uint8Array;
50
+ try {
51
+ bytes = await peekBodyBytes(resp, MAX_CHALLENGE_PEEK_BYTES);
52
+ } catch {
53
+ return false;
54
+ }
55
+ if (bytes.byteLength === 0) return false;
56
+ const text = await decodeMaybeGzip(bytes, resp.headers.get("content-encoding"));
57
+ return IN_BODY_CHALLENGE_MARKERS.some((marker) => text.includes(marker));
58
+ }
59
+
60
+ /** Unified challenge check: response-header variant first, then in-body peek. */
61
+ export async function isCaptchaChallenged(
62
+ resp: Response,
63
+ captcha: Pick<typeof CaptchaExports, "detectCaptchaChallenge">,
64
+ ): Promise<boolean> {
65
+ if (captcha.detectCaptchaChallenge(resp) !== null) return true;
66
+ return detectInBodyChallenge(resp);
67
+ }
68
+
69
+ export interface CaptchaRetryArgs {
70
+ captcha: CaptchaModuleLike;
71
+ appVersion: string;
72
+ /** The challenged response; its body is cancelled before the retry. */
73
+ challengedResp: Response;
74
+ /** Dispatch the retry. Receives the fresh captcha headers; must return the upstream Response. */
75
+ solveAndRetry: (retryHeaders: Record<string, string>) => Promise<Response>;
76
+ /**
77
+ * Error mapping (unified contract, mirrors handler.ts's correct shape):
78
+ * "solver" → the re-solve (getCaptchaToken) failed
79
+ * "dispatch" → the retry dispatch failed at the network level
80
+ */
81
+ mapError: (err: Error, phase: "solver" | "dispatch") => Response;
82
+ /** Optional debug line sink. */
83
+ debug?: (message: string) => void;
84
+ }
85
+
86
+ /**
87
+ * Shared single-retry flow for a detected captcha challenge: cancel the old
88
+ * body, re-solve a fresh token, rebuild + re-dispatch ONCE (the challenged
89
+ * token was already consumed by this request). Never loops.
90
+ *
91
+ * The caller MUST return `ok:false` responses directly to the client — they
92
+ * are already fully-formed error responses (solver → 503 captcha_solver_failed,
93
+ * dispatch → 502 upstream_unreachable); feeding them back through the
94
+ * upstream `!ok` branch would wrap the error body a second time.
95
+ */
96
+ export async function retryOnCaptchaChallenge(args: CaptchaRetryArgs): Promise<{ ok: true; resp: Response } | { ok: false; resp: Response }> {
97
+ const { captcha, appVersion, challengedResp, solveAndRetry, mapError, debug } = args;
98
+ debug?.("captcha challenge — re-solving and retrying once");
99
+ try {
100
+ await challengedResp.body?.cancel();
101
+ } catch {
102
+ // already drained/cancelled
103
+ }
104
+ let fresh: { verifyParam: string; region: string };
105
+ try {
106
+ fresh = await captcha.getCaptchaToken(appVersion);
107
+ } catch (err) {
108
+ return { ok: false, resp: mapError(err as Error, "solver") };
109
+ }
110
+ const retryHeaders: Record<string, string> = {
111
+ [captcha.RETRY_HEADERS.PARAM]: fresh.verifyParam,
112
+ [captcha.RETRY_HEADERS.REGION]: fresh.region,
113
+ };
114
+ try {
115
+ return { ok: true, resp: await solveAndRetry(retryHeaders) };
116
+ } catch (err) {
117
+ return { ok: false, resp: mapError(err as Error, "dispatch") };
118
+ }
119
+ }
120
+
121
+ /** Read at most `limit` bytes from a clone of the response body. */
122
+ async function peekBodyBytes(resp: Response, limit: number): Promise<Uint8Array> {
123
+ const body = resp.clone().body;
124
+ if (!body) return new Uint8Array(0);
125
+ const reader = body.getReader();
126
+ const parts: Uint8Array[] = [];
127
+ let total = 0;
128
+ try {
129
+ for (;;) {
130
+ const { done, value } = await reader.read();
131
+ if (done) break;
132
+ parts.push(value);
133
+ total += value.byteLength;
134
+ if (total >= limit) break;
135
+ }
136
+ } finally {
137
+ reader.cancel().catch(() => {});
138
+ reader.releaseLock?.();
139
+ }
140
+ const all = Buffer.concat(parts);
141
+ return all.byteLength > limit ? all.subarray(0, limit) : all;
142
+ }
143
+
144
+ /**
145
+ * Decode sniff bytes, inflating first when the response is labeled gzip.
146
+ * TextDecoder is non-fatal, so invalid UTF-8 degrades to replacement chars —
147
+ * the ASCII magic strings still match.
148
+ */
149
+ async function decodeMaybeGzip(bytes: Uint8Array, encodingHeader: string | null): Promise<string> {
150
+ const enc = encodingHeader?.toLowerCase().trim() ?? "";
151
+ if (enc === "gzip" || enc === "x-gzip") {
152
+ try {
153
+ return new TextDecoder().decode(await inflateBounded(bytes));
154
+ } catch {
155
+ // Runtime already inflated the body while keeping the header (Node
156
+ // undici) — sniff the bytes as-is.
157
+ }
158
+ }
159
+ return new TextDecoder().decode(bytes);
160
+ }
161
+
162
+ async function inflateBounded(bytes: Uint8Array): Promise<Uint8Array> {
163
+ const gunzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
164
+ const source = new ReadableStream<Uint8Array>({
165
+ start(controller) {
166
+ controller.enqueue(bytes);
167
+ controller.close();
168
+ },
169
+ });
170
+ const reader = source.pipeThrough(gunzip).getReader();
171
+ const parts: Uint8Array[] = [];
172
+ let total = 0;
173
+ try {
174
+ for (;;) {
175
+ const { done, value } = await reader.read();
176
+ if (done) break;
177
+ parts.push(value);
178
+ total += value.byteLength;
179
+ if (total >= MAX_SNIFF_INFLATED_BYTES) break;
180
+ }
181
+ } finally {
182
+ reader.cancel().catch(() => {});
183
+ reader.releaseLock?.();
184
+ }
185
+ return Buffer.concat(parts);
186
+ }
src/proxy/captcha-solver.ts ADDED
@@ -0,0 +1,30 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Solver backend dispatch — fully in-process, self-contained.
3
+ *
4
+ * Backend (ZCODE_CAPTCHA_BACKEND): "happy" (default) — the happy-dom solver
5
+ * in src/proxy/captcha-happy.ts. Runs inside the Bun process; bundled into
6
+ * the single-file release binary by `bun build --compile`. No external
7
+ * Node.js, no browser. (The historical jsdom and Node-daemon/playwright
8
+ * backends have been removed.)
9
+ */
10
+ const BACKEND = process.env.ZCODE_CAPTCHA_BACKEND?.trim().toLowerCase() || "happy";
11
+
12
+ let happyMod: typeof import("./captcha-happy.js") | null = null;
13
+
14
+ export async function runCaptchaSolve(scene: string, region: string, prefix: string): Promise<string> {
15
+ if (BACKEND !== "happy") {
16
+ throw new Error(`captcha backend "${BACKEND}" is not available; use ZCODE_CAPTCHA_BACKEND=happy`);
17
+ }
18
+ if (!happyMod) happyMod = await import("./captcha-happy.js");
19
+ return happyMod.solveTraceless({ scene, region, prefix });
20
+ }
21
+
22
+ /** In-process solving needs no worker pool management — kept for the pool API. */
23
+ export function setCaptchaSolverConcurrency(_n: number): void {}
24
+
25
+ /** In-process solving needs no worker pool management — kept for the pool API. */
26
+ export function shutdownCaptchaSolver(): void {}
27
+
28
+ export function captchaSolverConcurrency(): number {
29
+ return Number(process.env.CAPTCHA_DAEMON_CONCURRENCY || 4);
30
+ }
src/proxy/captcha-token.ts ADDED
@@ -0,0 +1,32 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /** Decode certifyId from a base64 Aliyun verify-param blob. */
2
+ export function parseCertifyId(param: string): string | null {
3
+ try {
4
+ const json = JSON.parse(Buffer.from(param, "base64").toString("utf8")) as {
5
+ certifyId?: unknown;
6
+ };
7
+ return typeof json.certifyId === "string" && json.certifyId.length > 0
8
+ ? json.certifyId
9
+ : null;
10
+ } catch {
11
+ return null;
12
+ }
13
+ }
14
+
15
+ /** Aliyun F008 — certifyId / verify token already consumed or duplicated. */
16
+ export function isCaptchaDuplicateError(message: string): boolean {
17
+ return /F008|"verifyCode"\s*:\s*"F008"/i.test(message);
18
+ }
19
+
20
+ /**
21
+ * Aliyun IP-block family: no-captcha possible because the mint IP has been
22
+ * flagged ("too many captcha requests"). Distinct from F008 (duplicate
23
+ * certifyId) and from pe-VM stalls/timeouts, which are local-side issues that
24
+ * a retry can fix without rotating the IP.
25
+ */
26
+ const CAPTCHA_IP_BLOCK_RE =
27
+ /too many|request was denied|risk control|frequent|rate\s*limit|exceeded.*(?:request|limit)|ip\s*suspicious|denied due to|retry later/i;
28
+
29
+ export function isCaptchaIpBlockError(message: string): boolean {
30
+ if (isCaptchaDuplicateError(message)) return false;
31
+ return CAPTCHA_IP_BLOCK_RE.test(message);
32
+ }
src/proxy/captcha.ts ADDED
@@ -0,0 +1,101 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Aliyun Captcha V3 front-end — config fetch + pre-solved token pool.
3
+ *
4
+ * Solving itself lives in captcha-happy.ts (in-process happy-dom solver,
5
+ * production-proven, self-contained: bundled into the single-file release
6
+ * binary — no external Node.js, no browser, no jsdom). Tokens are minted
7
+ * into a pool (captcha-pool.ts); requests take an already-solved token
8
+ * (sub-ms) while background refills keep the pool warm — the hot path
9
+ * never waits on a solve.
10
+ *
11
+ * Fingerprint stability: the happy-dom solver's polyfill/guest-patch values
12
+ * are deterministic and STABLE (never randomized) — Aliyun's risk engine
13
+ * correlates fingerprint stability across requests; randomizing per-solve
14
+ * flags it as `verifyCode: F001`. See captcha-happy.ts.
15
+ */
16
+ import { shutdownCaptchaSolver } from "./captcha-solver.js";
17
+ import {
18
+ configureCaptchaPool,
19
+ getCaptchaPoolStats,
20
+ prefillCaptchaPool,
21
+ takeCaptchaToken,
22
+ startCaptchaPoolRefill,
23
+ stopCaptchaPool,
24
+ urgentCaptchaRefill,
25
+ type CaptchaConfig,
26
+ } from "./captcha-pool.js";
27
+
28
+ const CAPTCHA_HEADER = "x-aliyun-captcha-verify-param";
29
+ const REGION_HEADER = "x-aliyun-captcha-verify-region";
30
+ const CONFIGS_API = "https://zcode.z.ai/api/v1/client/configs";
31
+
32
+ interface FetchedCaptchaConfig { enabled: boolean; prefix: string; sceneId: string; region: string; }
33
+ let cachedConfig: { value: FetchedCaptchaConfig | null; expiresAt: number } = { value: null, expiresAt: 0 };
34
+
35
+ export function detectCaptchaChallenge(resp: Response): string | null {
36
+ const v = resp.headers.get(CAPTCHA_HEADER);
37
+ return v && v.trim().length > 0 ? v.trim() : null;
38
+ }
39
+
40
+
41
+ async function fetchCaptchaConfig(appVersion: string): Promise<FetchedCaptchaConfig | null> {
42
+ if (cachedConfig.value && cachedConfig.expiresAt > Date.now()) return cachedConfig.value;
43
+ try {
44
+ const resp = await fetch(`${CONFIGS_API}?app_version=${encodeURIComponent(appVersion)}&platform=win32-x64`);
45
+ const json = (await resp.json()) as { data?: { configs?: { captcha?: FetchedCaptchaConfig } } };
46
+ const cfg = json?.data?.configs?.captcha ?? null;
47
+ cachedConfig = { value: cfg, expiresAt: Date.now() + 60000 };
48
+ return cfg;
49
+ } catch { return null; }
50
+ }
51
+
52
+ /**
53
+ * Solve backend: in-process happy-dom (captcha-happy.ts) served through the
54
+ * pre-solved token pool. Retries are handled inside the pool
55
+ * (ZCODE_CAPTCHA_RETRIES attempts with a fresh solve per retry).
56
+ */
57
+ export async function getCaptchaToken(appVersion: string): Promise<{ verifyParam: string; region: string }> {
58
+ const cfg = await fetchCaptchaConfig(appVersion);
59
+ if (!cfg || !cfg.enabled || !cfg.prefix || !cfg.sceneId) throw new Error("Captcha config unavailable");
60
+ // Pre-solved token pool: requests take an already-minted token (sub-ms)
61
+ // while background solves refill — the hot path never waits on a solve.
62
+ const verifyParam = await takeCaptchaToken(cfg);
63
+ return { verifyParam, region: cfg.region };
64
+ }
65
+
66
+ export function shutdownCaptcha(): void {
67
+ try { shutdownCaptchaSolver(); } catch {}
68
+ try { stopCaptchaPool(); } catch {}
69
+ }
70
+
71
+ /**
72
+ * Start background pre-solving of the token pool (happy backend).
73
+ * Warms only the idle minimum; the pool grows on demand with traffic.
74
+ */
75
+ export async function startCaptchaPool(appVersion: string): Promise<void> {
76
+ const cfg = await fetchCaptchaConfig(appVersion);
77
+ if (!cfg || !cfg.enabled) return;
78
+ // Size the pool before prefill: the module-level pool defers sizing to the
79
+ // first configure() so a cold boot doesn't mint a storm of soon-expired
80
+ // tokens. CAPTCHA_POOL_MIN/CAPTCHA_POOL_MAX env vars override the defaults.
81
+ const min = Number(process.env.CAPTCHA_POOL_MIN || 20);
82
+ const max = Number(process.env.CAPTCHA_POOL_MAX || Math.max(min * 6, 120));
83
+ configureCaptchaPool({ poolSizeMin: min, poolSizeMax: max });
84
+ startCaptchaPoolRefill(cfg as CaptchaConfig);
85
+ await prefillCaptchaPool(cfg as CaptchaConfig, min);
86
+ }
87
+
88
+ /** Request an urgent refill burst (e.g. after a challenge/retry). */
89
+ export function urgentCaptcha(): void {
90
+ urgentCaptchaRefill();
91
+ }
92
+
93
+ export function captchaPoolStats(): { ready: number; target: number; activeSolves: number } {
94
+ return getCaptchaPoolStats();
95
+ }
96
+
97
+ export function configureCaptchaSolving(opts: Parameters<typeof configureCaptchaPool>[0]): void {
98
+ configureCaptchaPool(opts);
99
+ }
100
+
101
+ export const RETRY_HEADERS = { PARAM: CAPTCHA_HEADER, REGION: REGION_HEADER };
src/proxy/client-session.ts ADDED
@@ -0,0 +1,264 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Local client-session inference for cache-affinity experiments.
3
+ *
4
+ * The resolver stores only hashes and generated IDs. It deliberately avoids
5
+ * prompt markers, response mutation, and full prompt persistence.
6
+ */
7
+ import nodeCrypto from "node:crypto";
8
+ import type { Format } from "../translator/types.js";
9
+ import type { ClientIdentityConfig } from "../config/types.js";
10
+
11
+ export type ClientSessionSource = "none" | "explicit" | "lineage";
12
+ export type ClientSessionAction = "off" | "observe" | "enforce";
13
+
14
+ export interface ClientSessionResult {
15
+ source: ClientSessionSource;
16
+ action: ClientSessionAction;
17
+ confidence: number;
18
+ sessionId?: string;
19
+ upstreamSessionId?: string;
20
+ requestId?: string;
21
+ traceId?: string;
22
+ queryId?: string;
23
+ }
24
+
25
+ interface StoredNode {
26
+ nodeHash: string;
27
+ sessionId: string;
28
+ upstreamSessionId: string;
29
+ lastSeenAt: number;
30
+ }
31
+
32
+ interface CanonicalRequest {
33
+ model: string;
34
+ identity: unknown;
35
+ messages: unknown[];
36
+ }
37
+
38
+ interface ExplicitTraceContext {
39
+ requestId?: string;
40
+ traceId?: string;
41
+ queryId?: string;
42
+ sessionId?: string;
43
+ }
44
+
45
+ export interface ClientSessionResolver {
46
+ resolve(req: Request, body: string | undefined, format: Format, model: string, config: ClientIdentityConfig): ClientSessionResult;
47
+ }
48
+
49
+ export function createClientSessionResolver(now: () => number = () => Date.now()): ClientSessionResolver {
50
+ const nodes = new Map<string, StoredNode>();
51
+ const sessions = new Map<string, StoredNode>();
52
+
53
+ function remember(nodeHash: string, session: StoredNode, config: ClientIdentityConfig): void {
54
+ const stored = { ...session, nodeHash, lastSeenAt: now() };
55
+ nodes.set(nodeHash, stored);
56
+ sessions.set(stored.sessionId, stored);
57
+ prune(config);
58
+ }
59
+
60
+ function prune(config: ClientIdentityConfig): void {
61
+ const cutoff = now() - config.ttlSeconds * 1000;
62
+ for (const [hash, node] of nodes.entries()) {
63
+ if (node.lastSeenAt < cutoff) nodes.delete(hash);
64
+ }
65
+ for (const [id, node] of sessions.entries()) {
66
+ if (node.lastSeenAt < cutoff) sessions.delete(id);
67
+ }
68
+ while (sessions.size > config.maxSessions) {
69
+ let oldestId = "";
70
+ let oldestAt = Infinity;
71
+ for (const [id, node] of sessions.entries()) {
72
+ if (node.lastSeenAt < oldestAt) {
73
+ oldestAt = node.lastSeenAt;
74
+ oldestId = id;
75
+ }
76
+ }
77
+ if (!oldestId) break;
78
+ sessions.delete(oldestId);
79
+ for (const [hash, node] of nodes.entries()) {
80
+ if (node.sessionId === oldestId) nodes.delete(hash);
81
+ }
82
+ }
83
+ }
84
+
85
+ function action(config: ClientIdentityConfig): ClientSessionAction {
86
+ return config.mode;
87
+ }
88
+
89
+ return {
90
+ resolve(req, body, format, model, config) {
91
+ if (config.mode === "off") return { source: "none", action: "off", confidence: 0 };
92
+
93
+ prune(config);
94
+ const explicitTrace = requestTraceContext(req, body);
95
+ if (explicitTrace.sessionId) return explicitResult(explicitTrace, config);
96
+
97
+ const canonical = canonicalize(body, format, model);
98
+ if (!canonical) {
99
+ if (hasTraceContext(explicitTrace)) return explicitResult(explicitTrace, config);
100
+ return { source: "none", action: action(config), confidence: 0 };
101
+ }
102
+
103
+ const nodeHash = hashJson(canonical.identity);
104
+ const existing = nodes.get(nodeHash);
105
+ if (existing) {
106
+ remember(nodeHash, existing, config);
107
+ return withTraceContext(result("lineage", action(config), existing, 0.95), explicitTrace);
108
+ }
109
+
110
+ const parent = findLinearParent(canonical, nodes);
111
+ if (parent) {
112
+ remember(nodeHash, parent, config);
113
+ return withTraceContext(result("lineage", action(config), parent, 0.9), explicitTrace);
114
+ }
115
+
116
+ const fresh = newSession();
117
+ remember(nodeHash, fresh, config);
118
+ return withTraceContext(result("lineage", action(config), fresh, 0.75), explicitTrace);
119
+ },
120
+ };
121
+ }
122
+
123
+ export const defaultClientSessionResolver = createClientSessionResolver();
124
+
125
+ function result(source: ClientSessionSource, action: ClientSessionAction, node: StoredNode, confidence: number): ClientSessionResult {
126
+ return {
127
+ source,
128
+ action,
129
+ confidence,
130
+ sessionId: node.sessionId,
131
+ upstreamSessionId: node.upstreamSessionId,
132
+ };
133
+ }
134
+
135
+ function requestTraceContext(req: Request, body: string | undefined): ExplicitTraceContext {
136
+ const bodyTrace = bodyMetadataTrace(body);
137
+ return {
138
+ requestId: firstHeader(req.headers, ["x-request-id"]) ?? bodyTrace.requestId,
139
+ traceId: firstHeader(req.headers, ["x-zcode-trace-id"]) ?? bodyTrace.traceId,
140
+ queryId: firstHeader(req.headers, ["x-query-id"]) ?? bodyTrace.queryId,
141
+ sessionId: firstHeader(req.headers, ["x-opencode-session", "x-claude-code-session-id", "x-session-id", "x-parent-session-id", "helicone-session-id"])
142
+ ?? bodyTrace.sessionId,
143
+ };
144
+ }
145
+
146
+ function explicitResult(trace: ExplicitTraceContext, config: ClientIdentityConfig): ClientSessionResult {
147
+ return {
148
+ source: "explicit",
149
+ action: config.mode,
150
+ confidence: 1,
151
+ ...(trace.requestId ? { requestId: trace.requestId } : {}),
152
+ ...(trace.traceId ? { traceId: trace.traceId } : {}),
153
+ ...(trace.queryId ? { queryId: trace.queryId } : {}),
154
+ ...(trace.sessionId ? { sessionId: trace.sessionId, upstreamSessionId: trace.sessionId } : {}),
155
+ };
156
+ }
157
+
158
+ function withTraceContext(session: ClientSessionResult, trace: ExplicitTraceContext): ClientSessionResult {
159
+ if (!trace.requestId && !trace.traceId && !trace.queryId) return session;
160
+ return {
161
+ ...session,
162
+ ...(trace.requestId ? { requestId: trace.requestId } : {}),
163
+ ...(trace.traceId ? { traceId: trace.traceId } : {}),
164
+ ...(trace.queryId ? { queryId: trace.queryId } : {}),
165
+ };
166
+ }
167
+
168
+ function hasTraceContext(trace: ExplicitTraceContext): boolean {
169
+ return Boolean(trace.requestId || trace.traceId || trace.queryId || trace.sessionId);
170
+ }
171
+
172
+ function firstHeader(headers: Headers, names: string[]): string | null {
173
+ for (const name of names) {
174
+ const value = headers.get(name);
175
+ if (value && value.trim()) return value.trim();
176
+ }
177
+ return null;
178
+ }
179
+
180
+ function bodyMetadataTrace(body: string | undefined): ExplicitTraceContext {
181
+ if (!body) return {};
182
+ try {
183
+ const parsed = JSON.parse(body) as Record<string, unknown>;
184
+ const metadata = parsed?.metadata as Record<string, unknown> | undefined;
185
+ if (!metadata || typeof metadata !== "object") return {};
186
+ return {
187
+ requestId: stringProperty(metadata, ["requestId", "request_id"]),
188
+ traceId: stringProperty(metadata, ["traceId", "trace_id"]),
189
+ queryId: stringProperty(metadata, ["queryId", "query_id"]),
190
+ sessionId: stringProperty(metadata, ["sessionId", "session_id", "conversationId", "conversation_id"]),
191
+ };
192
+ } catch {
193
+ return {};
194
+ }
195
+ }
196
+
197
+ function stringProperty(obj: Record<string, unknown>, names: string[]): string | undefined {
198
+ for (const name of names) {
199
+ const value = obj[name];
200
+ if (typeof value === "string" && value.trim()) return value.trim();
201
+ }
202
+ return undefined;
203
+ }
204
+
205
+ function canonicalize(body: string | undefined, format: Format, fallbackModel: string): CanonicalRequest | null {
206
+ if (!body) return null;
207
+ let parsed: Record<string, unknown>;
208
+ try {
209
+ parsed = JSON.parse(body);
210
+ } catch {
211
+ return null;
212
+ }
213
+ if (!parsed || typeof parsed !== "object") return null;
214
+
215
+ const model = typeof parsed.model === "string" ? parsed.model : fallbackModel;
216
+ const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
217
+ if (messages.length === 0) return null;
218
+
219
+ const identity = {
220
+ format,
221
+ model,
222
+ system: parsed.system,
223
+ developer: messages.filter((m: unknown) => typeof m === "object" && m !== null && (m as Record<string, unknown>).role === "developer"),
224
+ tools: parsed.tools,
225
+ tool_choice: parsed.tool_choice,
226
+ messages,
227
+ };
228
+ return { model, identity, messages };
229
+ }
230
+
231
+ function findLinearParent(canonical: CanonicalRequest, nodes: Map<string, StoredNode>): StoredNode | null {
232
+ if (canonical.messages.length < 3) return null;
233
+ const prefix = {
234
+ ...(canonical.identity as Record<string, unknown>),
235
+ messages: canonical.messages.slice(0, -2),
236
+ };
237
+ if ((prefix.messages as unknown[]).length === 0) return null;
238
+ return nodes.get(hashJson(prefix)) ?? null;
239
+ }
240
+
241
+ function newSession(): StoredNode {
242
+ const upstreamSessionId = crypto.randomUUID();
243
+ return {
244
+ nodeHash: "",
245
+ sessionId: `ses_${upstreamSessionId.replace(/-/g, "").slice(0, 12)}`,
246
+ upstreamSessionId,
247
+ lastSeenAt: Date.now(),
248
+ };
249
+ }
250
+
251
+ function hashJson(value: unknown): string {
252
+ return hashString(stableStringify(value));
253
+ }
254
+
255
+ function hashString(value: string): string {
256
+ return nodeCrypto.createHash("sha256").update(value, "utf-8").digest("hex");
257
+ }
258
+
259
+ function stableStringify(value: unknown): string {
260
+ if (value === null || typeof value !== "object") return JSON.stringify(value);
261
+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
262
+ const obj = value as Record<string, unknown>;
263
+ return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
264
+ }
src/proxy/client-signing.ts ADDED
@@ -0,0 +1,595 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Client Request Signing V4 — mirrors the ZCode 3.9.1 `ClientRequestSigningV4Signer`.
3
+ *
4
+ * Per-request Ed25519 signatures + proof-of-work over coding-plan traffic.
5
+ * Everything here is fail-open, matching the client: gate disabled/unreachable
6
+ * → unsigned; handshake failure → unsigned; two consecutive 401 VERIFY_*
7
+ * rejections → permanent bypass for that (origin, credential) pair.
8
+ *
9
+ * Start-plan gateway and off-peak LLM paths are permanently exempt (the
10
+ * client's `isUnsignedModelRequestPath` set). Credentials without the
11
+ * `{apiKeyId}.{apiKeySecret}` separator (legacy bigmodel keys issued before
12
+ * the copy endpoint returned secretKeys) are silently skipped — the client
13
+ * hard-throws there; skipping is a deliberate fail-open deviation. Both
14
+ * providers now issue two-part keys, which sign normally.
15
+ *
16
+ * Full protocol: `_reverse/NOTEPAD.md` "Client Request Signing V4".
17
+ */
18
+ import type { UpstreamHeaderPair } from "./upstream.js";
19
+ import { buildIdentityHeaders, identityCacheKey } from "./identity.js";
20
+ import type { ProxyIdentity } from "../config/types.js";
21
+
22
+ const DEFAULT_ORIGIN = "https://zcode.z.ai";
23
+ const GATE_PATH = "/api/v1/agent/configs";
24
+ const HANDSHAKE_PATH = "/api/paas/c1f3a7e2/v2/client";
25
+ const APP_ID = "zcode";
26
+ const POW_BITS = 8;
27
+ const NONCE_BYTES = 16;
28
+ const POW_NONCE_BYTES = 12;
29
+ const KDF_SALT = "WD_CLIENT_SIGN_KDF_SALT";
30
+ const KDF_INFO_HMAC = "getSignKey_hmac";
31
+ const KDF_INFO_ED25519 = "ed25519_priv";
32
+ const HANDSHAKE_METHOD = "get_sign_key";
33
+ const GATE_TTL_MS = 3_600_000;
34
+ /** Negative-cache cooldown after a gate fetch network failure. */
35
+ const GATE_FAILURE_COOLDOWN_MS = 60_000;
36
+ /** Negative-cache cooldown for "unavailable" gate responses (non-2xx / bad envelope). */
37
+ const GATE_UNAVAILABLE_COOLDOWN_MS = 30_000;
38
+ const GATE_TIMEOUT_MS = 15_000;
39
+ const HANDSHAKE_TIMEOUT_MS = 10_000;
40
+ const VERIFY_SIGNATURE_INVALID = "VERIFY_SIGNATURE_INVALID";
41
+ const VERIFY_APIKEY_EXPIRED = "VERIFY_APIKEY_EXPIRED";
42
+
43
+ /** Paths the client never signs (decoded, trailing-slash-stripped). */
44
+ const UNSIGNED_PATHS = new Set([
45
+ "/api/v1/zcode-plan/anthropic/v1/messages",
46
+ "/api/v1/zcode-plan/chat/completions",
47
+ "/api/v1/off-peak/anthropic/v1/messages",
48
+ ]);
49
+
50
+ const SIGNING_HEADER_NAMES = new Set([
51
+ "x-client-ts",
52
+ "x-client-version",
53
+ "x-client-sig",
54
+ "x-client-nonce",
55
+ "x-app-id",
56
+ "x-client-pow",
57
+ "x-client-sign-verified",
58
+ ]);
59
+
60
+ export interface SigningCredential {
61
+ credential: string;
62
+ appVersion: string;
63
+ }
64
+
65
+ export interface SignOutcome {
66
+ pairs: UpstreamHeaderPair[];
67
+ signed: boolean;
68
+ }
69
+
70
+ interface ParsedCredential {
71
+ apiKeyId: string;
72
+ apiKeySecret: string;
73
+ }
74
+
75
+ interface SignerState {
76
+ gateEnabled: boolean;
77
+ gateExpiresAt: number;
78
+ gateNegUntil: number;
79
+ gatePromise?: Promise<boolean>;
80
+ privKey?: CryptoKey;
81
+ handshake?: Promise<CryptoKey>;
82
+ epoch: number;
83
+ bypass: boolean;
84
+ }
85
+
86
+ const encoder = new TextEncoder();
87
+
88
+ type Bytes = Uint8Array<ArrayBuffer>;
89
+
90
+ function encodeUtf8(value: string): Bytes {
91
+ const bytes = encoder.encode(value);
92
+ const out = new Uint8Array(bytes.byteLength);
93
+ out.set(bytes);
94
+ return out;
95
+ }
96
+
97
+ function bytesToBase64(bytes: Uint8Array): string {
98
+ let binary = "";
99
+ for (const b of bytes) binary += String.fromCharCode(b);
100
+ return btoa(binary);
101
+ }
102
+
103
+ function bytesToHex(bytes: Uint8Array): string {
104
+ return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
105
+ }
106
+
107
+ function randomHex(byteCount: number): string {
108
+ return bytesToHex(crypto.getRandomValues(new Uint8Array(byteCount)));
109
+ }
110
+
111
+ function base64ToBytes(value: string): Bytes {
112
+ if (!value || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
113
+ throw new Error("invalid base64");
114
+ }
115
+ const binary = atob(value);
116
+ const out = new Uint8Array(binary.length);
117
+ for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
118
+ return out;
119
+ }
120
+
121
+ async function hkdfBytes(secret: string, info: string): Promise<Bytes> {
122
+ const key = await crypto.subtle.importKey("raw", encodeUtf8(secret), "HKDF", false, ["deriveBits"]);
123
+ return new Uint8Array(await crypto.subtle.deriveBits(
124
+ { name: "HKDF", hash: "SHA-256", salt: encodeUtf8(KDF_SALT), info: encodeUtf8(info) },
125
+ key,
126
+ 256,
127
+ ));
128
+ }
129
+
130
+ async function handshakeSignature(secret: string, message: string): Promise<string> {
131
+ const bits = await hkdfBytes(secret, KDF_INFO_HMAC);
132
+ try {
133
+ const key = await crypto.subtle.importKey("raw", bits, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
134
+ const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, encodeUtf8(message)));
135
+ try {
136
+ return bytesToBase64(mac);
137
+ } finally {
138
+ mac.fill(0);
139
+ }
140
+ } finally {
141
+ bits.fill(0);
142
+ }
143
+ }
144
+
145
+ async function decryptSigningPrivateKey(apiKeyId: string, secret: string, privateCipher: string): Promise<CryptoKey> {
146
+ const cipher = base64ToBytes(privateCipher);
147
+ if (cipher.byteLength <= 12 + 16) throw new Error("privateCipher is too short");
148
+ const aesKeyBits = await hkdfBytes(secret, KDF_INFO_ED25519);
149
+ try {
150
+ const aesKey = await crypto.subtle.importKey("raw", aesKeyBits, "AES-GCM", false, ["decrypt"]);
151
+ const plain = new Uint8Array(
152
+ await crypto.subtle.decrypt(
153
+ { name: "AES-GCM", iv: cipher.slice(0, 12), additionalData: encodeUtf8(apiKeyId), tagLength: 128 },
154
+ aesKey,
155
+ cipher.slice(12),
156
+ ),
157
+ );
158
+ try {
159
+ const pkcs8 = base64ToBytes(new TextDecoder().decode(plain));
160
+ return await crypto.subtle.importKey("pkcs8", pkcs8, "Ed25519", false, ["sign"]);
161
+ } finally {
162
+ plain.fill(0);
163
+ }
164
+ } finally {
165
+ aesKeyBits.fill(0);
166
+ }
167
+ }
168
+
169
+ async function signBusinessMessage(privateKey: CryptoKey, message: string): Promise<string> {
170
+ const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, encodeUtf8(message)));
171
+ try {
172
+ return bytesToBase64(sig);
173
+ } finally {
174
+ sig.fill(0);
175
+ }
176
+ }
177
+
178
+ function hasLeadingZeroBits(bytes: Uint8Array, bits: number): boolean {
179
+ const fullBytes = Math.floor(bits / 8);
180
+ for (let i = 0; i < fullBytes; i++) {
181
+ if (bytes[i] !== 0) return false;
182
+ }
183
+ const remainder = bits % 8;
184
+ if (remainder === 0) return true;
185
+ const mask = (255 << (8 - remainder)) & 255;
186
+ return ((bytes[fullBytes] ?? 255) & mask) === 0;
187
+ }
188
+
189
+ async function createProofOfWork(apiKeyId: string, sessionId: string, ts: string, signal?: AbortSignal): Promise<string> {
190
+ const seedDigest = new Uint8Array(
191
+ await crypto.subtle.digest("SHA-256", encodeUtf8(`${apiKeyId}\n${APP_ID}\n${sessionId}\n${ts}`)),
192
+ );
193
+ const seed = bytesToHex(seedDigest).slice(0, 32);
194
+ const nonce = randomHex(POW_NONCE_BYTES);
195
+ for (let counter = 0; counter <= 4_294_967_295; counter++) {
196
+ signal?.throwIfAborted();
197
+ const candidate = `${nonce}${counter.toString(16).padStart(8, "0")}`;
198
+ const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encodeUtf8(`${seed}\n${candidate}`)));
199
+ if (hasLeadingZeroBits(digest, POW_BITS)) return candidate;
200
+ }
201
+ throw new Error("Unable to solve client request proof of work");
202
+ }
203
+
204
+ function parseSigningCredential(credential: string): ParsedCredential | undefined {
205
+ const dot = credential.indexOf(".");
206
+ if (dot <= 0 || dot !== credential.lastIndexOf(".")) return undefined;
207
+ const apiKeyId = credential.slice(0, dot);
208
+ const apiKeySecret = credential.slice(dot + 1);
209
+ if (!apiKeyId.trim() || !apiKeySecret.trim()) return undefined;
210
+ return { apiKeyId, apiKeySecret };
211
+ }
212
+
213
+ function isUnsignedPath(pathname: string): boolean {
214
+ let path = pathname;
215
+ try {
216
+ path = decodeURIComponent(pathname);
217
+ } catch {
218
+ // keep raw path
219
+ }
220
+ path = path.replace(/\/+$/u, "");
221
+ return UNSIGNED_PATHS.has(path);
222
+ }
223
+
224
+ function findHeader(pairs: UpstreamHeaderPair[], name: string): string | undefined {
225
+ const lower = name.toLowerCase();
226
+ for (const [key, value] of pairs) {
227
+ if (key.toLowerCase() === lower) return value;
228
+ }
229
+ return undefined;
230
+ }
231
+
232
+ export class ClientSigningManager {
233
+ private readonly gateUrl: string;
234
+ private readonly identity: ProxyIdentity;
235
+ private readonly fetchImpl: typeof fetch;
236
+ private readonly now: () => number;
237
+ private readonly states = new Map<string, SignerState>();
238
+ private readonly notedKeys = new Set<string>();
239
+ onEvent?: (message: string) => void;
240
+
241
+ constructor(opts: {
242
+ identity: ProxyIdentity;
243
+ origin?: string;
244
+ fetchImpl?: typeof fetch;
245
+ now?: () => number;
246
+ onEvent?: (message: string) => void;
247
+ }) {
248
+ this.gateUrl = `${(opts.origin?.trim() || DEFAULT_ORIGIN).replace(/\/+$/u, "")}${GATE_PATH}`;
249
+ this.identity = opts.identity;
250
+ this.fetchImpl = opts.fetchImpl ?? fetch;
251
+ this.now = opts.now ?? Date.now;
252
+ this.onEvent = opts.onEvent;
253
+ }
254
+
255
+ /**
256
+ * Add the V4 signing headers to an upstream header-pair list. Returns the
257
+ * input pairs unchanged whenever signing does not apply: exempt path,
258
+ * bypass, non-signable credential, missing session id, gate off/unreachable,
259
+ * or handshake failure. Never throws.
260
+ */
261
+ async sign(url: string, pairs: UpstreamHeaderPair[], cred: SigningCredential): Promise<UpstreamHeaderPair[]> {
262
+ return (await this.signWithStatus(url, pairs, cred)).pairs;
263
+ }
264
+
265
+ /**
266
+ * `sign` with a `signed` flag so the retry ladder can distinguish
267
+ * "signed but rejected" from "never signed" without identity checks on the
268
+ * returned array reference. Cheap local eligibility checks (credential
269
+ * separator, session id) run BEFORE the gate probe so non-signable
270
+ * credentials never pay for network fetches.
271
+ */
272
+ async signWithStatus(url: string, pairs: UpstreamHeaderPair[], cred: SigningCredential): Promise<SignOutcome> {
273
+ let parsed: URL;
274
+ try {
275
+ parsed = new URL(url);
276
+ } catch {
277
+ return { pairs, signed: false };
278
+ }
279
+ if (parsed.protocol !== "https:") return { pairs, signed: false };
280
+ if (isUnsignedPath(parsed.pathname)) return { pairs, signed: false };
281
+ if (pairs.some(([k]) => k.toLowerCase() === "x-client-sig")) return { pairs, signed: false };
282
+
283
+ const stateKey = `${parsed.origin}\n${cred.credential}`;
284
+ const state = this.stateFor(stateKey);
285
+ if (state.bypass) return { pairs, signed: false };
286
+
287
+ const parsedCred = parseSigningCredential(cred.credential);
288
+ if (!parsedCred) {
289
+ this.noteOnce(stateKey, "credential has no {apiKeyId}.{apiKeySecret} separator — signing skipped");
290
+ return { pairs, signed: false };
291
+ }
292
+
293
+ const sessionId = findHeader(pairs, "x-session-id")?.trim();
294
+ if (!sessionId) {
295
+ this.noteOnce(stateKey, "upstream request has no x-session-id — signing skipped");
296
+ return { pairs, signed: false };
297
+ }
298
+
299
+ if (!(await this.gateEnabled(state, cred))) return { pairs, signed: false };
300
+
301
+ let privateKey: CryptoKey;
302
+ try {
303
+ privateKey = await this.ensurePrivateKey(state, stateKey, parsedCred, parsed.origin);
304
+ } catch {
305
+ this.noteOnce(stateKey, "signing handshake failed — sending unsigned");
306
+ this.invalidateState(stateKey);
307
+ return { pairs, signed: false };
308
+ }
309
+ const signedPairs = await this.buildSignedPairs(stateKey, pairs, privateKey, parsedCred, sessionId, cred.appVersion);
310
+ return signedPairs ? { pairs: signedPairs, signed: true } : { pairs, signed: false };
311
+ }
312
+
313
+ private async buildSignedPairs(
314
+ stateKey: string,
315
+ pairs: UpstreamHeaderPair[],
316
+ privateKey: CryptoKey,
317
+ parsedCred: ParsedCredential,
318
+ sessionId: string,
319
+ appVersion: string,
320
+ ): Promise<UpstreamHeaderPair[] | null> {
321
+ const ts = String(Date.now());
322
+ const nonce = randomHex(NONCE_BYTES);
323
+ let pow: string;
324
+ let sig: string;
325
+ try {
326
+ pow = await createProofOfWork(parsedCred.apiKeyId, sessionId, ts);
327
+ sig = await signBusinessMessage(
328
+ privateKey,
329
+ `${parsedCred.apiKeyId}\n${ts}\n${appVersion}\n${sessionId}\n${nonce}`,
330
+ );
331
+ } catch (err) {
332
+ if ((err as Error).name !== "AbortError") {
333
+ this.noteOnce(stateKey, `signing failed (${(err as Error).message}) — sending unsigned`);
334
+ }
335
+ return null;
336
+ }
337
+ const cleaned = pairs.filter(([k]) => {
338
+ const lower = k.toLowerCase();
339
+ return !SIGNING_HEADER_NAMES.has(lower) && lower !== "x-session-id";
340
+ });
341
+ return [
342
+ ...cleaned,
343
+ ["X-Client-Ts", ts],
344
+ ["X-Client-Version", appVersion],
345
+ ["X-Client-Sig", sig],
346
+ // canonical case replaces the lowercase trace copy in this append position
347
+ // (mirrors the client's i.set("X-Session-Id") Headers.set semantics)
348
+ ["X-Session-Id", sessionId],
349
+ ["X-Client-Nonce", nonce],
350
+ ["X-App-Id", APP_ID],
351
+ ["X-Client-Pow", pow],
352
+ ];
353
+ }
354
+
355
+ /**
356
+ * True when the response is a signing rejection the client retries on:
357
+ * HTTP 401 whose envelope mentions VERIFY_SIGNATURE_INVALID / VERIFY_APIKEY_EXPIRED.
358
+ * Reads a clone; the response body stays consumable by the caller.
359
+ */
360
+ async isVerifyFailure(resp: Response): Promise<boolean> {
361
+ if (resp.status !== 401) return false;
362
+ try {
363
+ const body = await resp.clone().json() as Record<string, unknown>;
364
+ if (!body || typeof body !== "object" || Array.isArray(body)) return false;
365
+ const data = body.data as Record<string, unknown> | undefined;
366
+ const error = body.error as Record<string, unknown> | undefined;
367
+ const candidates = [body.msg, body.reason, data?.reason, error?.reason, error?.message];
368
+ return candidates.some((v) => v === VERIFY_SIGNATURE_INVALID || v === VERIFY_APIKEY_EXPIRED);
369
+ } catch {
370
+ return false;
371
+ }
372
+ }
373
+
374
+ /** Drop the cached signing key for a (origin, credential) pair after a VERIFY rejection. */
375
+ invalidate(url: string, credential: string): void {
376
+ try {
377
+ const stateKey = `${new URL(url).origin}\n${credential}`;
378
+ this.invalidateState(stateKey);
379
+ } catch {
380
+ // unreachable URL — nothing cached under it
381
+ }
382
+ }
383
+
384
+ /** Permanently stop signing for a (origin, credential) pair (two VERIFY rejections). */
385
+ setBypass(url: string, credential: string): void {
386
+ try {
387
+ const stateKey = `${new URL(url).origin}\n${credential}`;
388
+ const state = this.stateFor(stateKey);
389
+ state.bypass = true;
390
+ this.invalidateState(stateKey);
391
+ this.onEvent?.("client-signing: VERIFY rejection persisted — bypassing signing for this credential");
392
+ } catch {
393
+ // unreachable URL
394
+ }
395
+ }
396
+
397
+ private invalidateState(stateKey: string): void {
398
+ const state = this.states.get(stateKey);
399
+ if (!state) return;
400
+ state.epoch += 1;
401
+ state.privKey = undefined;
402
+ state.handshake = undefined;
403
+ }
404
+
405
+ private stateFor(stateKey: string): SignerState {
406
+ let state = this.states.get(stateKey);
407
+ if (!state) {
408
+ state = { gateEnabled: false, gateExpiresAt: 0, gateNegUntil: 0, epoch: 0, bypass: false };
409
+ this.states.set(stateKey, state);
410
+ }
411
+ return state;
412
+ }
413
+
414
+ private async gateEnabled(state: SignerState, cred: SigningCredential): Promise<boolean> {
415
+ const now = this.now();
416
+ if (state.gateExpiresAt > now) return state.gateEnabled;
417
+ if (state.gateNegUntil > now) return false;
418
+ if (state.gatePromise) return state.gatePromise;
419
+ const promise = this.probeGate(state, cred).finally(() => {
420
+ if (state.gatePromise === promise) state.gatePromise = undefined;
421
+ });
422
+ state.gatePromise = promise;
423
+ return promise;
424
+ }
425
+
426
+ private async probeGate(state: SignerState, cred: SigningCredential): Promise<boolean> {
427
+ const now = this.now();
428
+ let outcome: "enabled" | "disabled" | "unavailable";
429
+ try {
430
+ outcome = await this.fetchGate(cred);
431
+ } catch {
432
+ state.gateNegUntil = now + GATE_FAILURE_COOLDOWN_MS;
433
+ return false;
434
+ }
435
+ state.gateEnabled = outcome === "enabled";
436
+ if (outcome === "unavailable") {
437
+ // proxy deviation: the client re-probes unavailable gates on every request
438
+ // from a UI process; on the proxy hot path a short negative cache bounds
439
+ // the worst-case per-request latency to one probe per window
440
+ state.gateNegUntil = now + GATE_UNAVAILABLE_COOLDOWN_MS;
441
+ } else {
442
+ state.gateExpiresAt = now + GATE_TTL_MS;
443
+ state.gateNegUntil = 0;
444
+ }
445
+ if (state.gateEnabled) this.onEvent?.("client-signing: server enabled codingPlanSignature — signing requests");
446
+ return state.gateEnabled;
447
+ }
448
+
449
+ private async fetchGate(cred: SigningCredential): Promise<"enabled" | "disabled" | "unavailable"> {
450
+ // sYr (bundle) builds the gate-fetch identity set WITHOUT X-ZCode-Agent and
451
+ // X-Device-Mid; Bxi appends x-api-key only — this fetch carries no Accept header.
452
+ const identityHeaders = Object.fromEntries(
453
+ Object.entries(buildIdentityHeaders(this.identity))
454
+ .filter(([name]) => name !== "X-ZCode-Agent" && name !== "X-Device-Mid"),
455
+ );
456
+ const controller = new AbortController();
457
+ const timer = setTimeout(() => controller.abort(), GATE_TIMEOUT_MS);
458
+ try {
459
+ const resp = await this.fetchImpl(this.gateUrl, {
460
+ method: "GET",
461
+ headers: { ...identityHeaders, "x-api-key": cred.credential },
462
+ redirect: "manual",
463
+ signal: controller.signal,
464
+ });
465
+ if (!resp.ok) return "unavailable";
466
+ const parsed = await resp.json() as Record<string, unknown>;
467
+ if (!parsed || parsed.code !== 0) return "unavailable";
468
+ const data = parsed.data as Record<string, unknown> | undefined;
469
+ if (!data || !Object.prototype.hasOwnProperty.call(data, "codingPlanSignature")) return "disabled";
470
+ const signature = data.codingPlanSignature as Record<string, unknown> | undefined;
471
+ return signature?.enable === true ? "enabled" : "disabled";
472
+ } finally {
473
+ clearTimeout(timer);
474
+ }
475
+ }
476
+
477
+ private async ensurePrivateKey(
478
+ state: SignerState,
479
+ stateKey: string,
480
+ parsedCred: ParsedCredential,
481
+ origin: string,
482
+ ): Promise<CryptoKey> {
483
+ if (state.privKey) return state.privKey;
484
+ if (state.handshake) return state.handshake;
485
+ const epoch = state.epoch;
486
+ const handshake = this.performHandshake(parsedCred, origin).then((key) => {
487
+ if (state.epoch !== epoch) throw new Error("signing key changed during handshake");
488
+ state.privKey = key;
489
+ return key;
490
+ });
491
+ const clear = () => {
492
+ if (state.handshake === handshake) state.handshake = undefined;
493
+ };
494
+ handshake.then(clear, clear);
495
+ state.handshake = handshake;
496
+ return handshake;
497
+ }
498
+
499
+ private async performHandshake(parsedCred: ParsedCredential, origin: string): Promise<CryptoKey> {
500
+ const ts = String(Date.now());
501
+ const nonce = randomHex(NONCE_BYTES);
502
+ const sig = await handshakeSignature(
503
+ parsedCred.apiKeySecret,
504
+ `${HANDSHAKE_METHOD}\n${parsedCred.apiKeyId}\n${ts}\n${nonce}`,
505
+ );
506
+
507
+ const controller = new AbortController();
508
+ const timer = setTimeout(() => controller.abort(), HANDSHAKE_TIMEOUT_MS);
509
+ try {
510
+ const resp = await this.fetchImpl(`${origin}${HANDSHAKE_PATH}`, {
511
+ method: "POST",
512
+ headers: { Authorization: `${parsedCred.apiKeyId}.${parsedCred.apiKeySecret}`, "Content-Type": "application/json" },
513
+ body: JSON.stringify({ apiKey: `${parsedCred.apiKeyId}.${parsedCred.apiKeySecret}`, nonce, sig, ts }),
514
+ redirect: "manual",
515
+ signal: controller.signal,
516
+ });
517
+ if (resp.status !== 200) throw new Error(`handshake_http_${resp.status}`);
518
+ const envelope = await resp.json() as { code?: unknown; msg?: unknown; data?: { privateCipher?: unknown } };
519
+ if (envelope.code === 500) throw new Error("handshake_server_500");
520
+ if (envelope.code !== 200) throw new Error(`handshake_rejected: ${String(envelope.msg)}`);
521
+ const cipher = envelope.data?.privateCipher;
522
+ if (typeof cipher !== "string" || !cipher) throw new Error("handshake_omitted_privateCipher");
523
+ return await decryptSigningPrivateKey(parsedCred.apiKeyId, parsedCred.apiKeySecret, cipher);
524
+ } finally {
525
+ clearTimeout(timer);
526
+ }
527
+ }
528
+
529
+ private noteOnce(stateKey: string, message: string): void {
530
+ if (this.notedKeys.has(stateKey)) return;
531
+ this.notedKeys.add(stateKey);
532
+ this.onEvent?.(`client-signing: ${message}`);
533
+ }
534
+ }
535
+
536
+ export interface SendWithSigningParams {
537
+ url: string;
538
+ headerPairs: UpstreamHeaderPair[];
539
+ credential: string;
540
+ appVersion: string;
541
+ send: (headerPairs: UpstreamHeaderPair[]) => Promise<Response>;
542
+ debug?: (message: string) => void;
543
+ }
544
+
545
+ /**
546
+ * Send with the client's full signing retry ladder:
547
+ * signed → on 401 VERIFY: re-handshake + re-sign → on second 401 VERIFY:
548
+ * permanent bypass + unsigned. A `null` manager (feature disabled) sends as-is.
549
+ */
550
+ export async function sendWithClientSigning(
551
+ signer: ClientSigningManager | null,
552
+ params: SendWithSigningParams,
553
+ ): Promise<Response> {
554
+ const { url, headerPairs, credential, appVersion, send, debug } = params;
555
+ if (!signer) return send(headerPairs);
556
+
557
+ const first = await signer.signWithStatus(url, headerPairs, { credential, appVersion });
558
+ let resp = await send(first.pairs);
559
+ if (!first.signed || !await signer.isVerifyFailure(resp)) return resp;
560
+
561
+ debug?.("401 VERIFY_SIGNATURE_* — invalidating signing key and retrying once");
562
+ signer.invalidate(url, credential);
563
+ const second = await signer.signWithStatus(url, headerPairs, { credential, appVersion });
564
+ resp = await send(second.pairs);
565
+ if (!second.signed || !await signer.isVerifyFailure(resp)) return resp;
566
+
567
+ signer.setBypass(url, credential);
568
+ debug?.("401 VERIFY_SIGNATURE_* twice — sending unsigned (signing bypassed)");
569
+ return send(headerPairs);
570
+ }
571
+
572
+ let defaultSigner: ClientSigningManager | null = null;
573
+ let defaultSignerKey = "";
574
+
575
+ /**
576
+ * Process-wide signing manager, shared across requests (gate + key caches).
577
+ * Returns `null` when `clientSigning.enabled` is false. Recreated when the
578
+ * relevant config values change (Android `setConfig`) — keyed on the full
579
+ * identity because the manager embeds it in gate-fetch headers.
580
+ */
581
+ export function getDefaultClientSigning(config: {
582
+ clientSigning: { enabled: boolean; origin: string };
583
+ identity: ProxyIdentity;
584
+ }): ClientSigningManager | null {
585
+ if (!config.clientSigning.enabled) return null;
586
+ const key = `${config.clientSigning.origin}\n${identityCacheKey(config.identity)}`;
587
+ if (!defaultSigner || key !== defaultSignerKey) {
588
+ defaultSigner = new ClientSigningManager({
589
+ identity: config.identity,
590
+ origin: config.clientSigning.origin,
591
+ });
592
+ defaultSignerKey = key;
593
+ }
594
+ return defaultSigner;
595
+ }
src/proxy/dump.ts ADDED
@@ -0,0 +1,93 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Upstream traffic dumper — used for debugging "JSON request body" issues.
3
+ *
4
+ * Activated by env `ZCODE_DUMP_UPSTREAM=<path>`: every proxied request emits
5
+ * one JSONL line per phase (`client_in` / `upstream_out` / `upstream_in` /
6
+ * `upstream_body_sample`), so the full request→response timeline can be
7
+ * inspected offline. Inactive (no-op) when the env var is unset.
8
+ *
9
+ * Design constraints:
10
+ * - Must NEVER affect request handling — all FS work is try/catch'd.
11
+ * - Sensitive header values (Authorization / x-api-key / captcha tokens /
12
+ * proxy secrets) are masked to `abcd1234…wxyz` so fingerprints are visible
13
+ * while credentials stay redacted.
14
+ * - Bodies are JSON.parsed and re-stringified when possible (for readability);
15
+ * otherwise emitted as the raw string.
16
+ *
17
+ * The dump file is line-oriented JSON (JSONL); each line is self-contained:
18
+ *
19
+ * {"ts":"2026-07-31T12:00:00.000Z","reqId":"#001","phase":"client_in", ...}
20
+ *
21
+ * Pair lines by `reqId` to reconstruct a full request timeline.
22
+ */
23
+ import { appendFileSync } from "node:fs";
24
+
25
+ const DUMP_PATH = process.env.ZCODE_DUMP_UPSTREAM;
26
+
27
+ /** Header names whose values must be masked before dumping. */
28
+ const SENSITIVE_HEADERS = new Set([
29
+ "authorization",
30
+ "x-api-key",
31
+ "proxy-authorization",
32
+ "proxy-api-key",
33
+ "x-zcode-captcha-verify-param",
34
+ "x-zcode-captcha-verify-region",
35
+ "cookie",
36
+ ]);
37
+
38
+ function maskHeaderValue(key: string, value: string): string {
39
+ if (!SENSITIVE_HEADERS.has(key.toLowerCase())) return value;
40
+ if (value.length <= 12) return "<redacted>";
41
+ return `${value.slice(0, 8)}…${value.slice(-4)} (len=${value.length})`;
42
+ }
43
+
44
+ /** Convert a Headers object to a plain object with sensitive values masked. */
45
+ export function dumpHeaders(headers: Headers): Record<string, string> {
46
+ const out: Record<string, string> = {};
47
+ for (const [k, v] of headers.entries()) {
48
+ out[k] = maskHeaderValue(k, v);
49
+ }
50
+ return out;
51
+ }
52
+
53
+ /** Try to parse body as JSON for pretty emission; fall back to raw string. */
54
+ export function dumpBody(body: string | undefined | null): unknown {
55
+ if (body === undefined || body === null) return undefined;
56
+ if (body.length === 0) return "";
57
+ try {
58
+ return JSON.parse(body);
59
+ } catch {
60
+ return body;
61
+ }
62
+ }
63
+
64
+ interface DumpLine {
65
+ ts: string;
66
+ reqId: string;
67
+ phase: string;
68
+ [k: string]: unknown;
69
+ }
70
+
71
+ /**
72
+ * Append one dump line. No-op when `ZCODE_DUMP_UPSTREAM` is unset.
73
+ * All errors are swallowed — dumping must never break request handling.
74
+ */
75
+ export function dumpPhase(reqId: string, phase: string, data: Record<string, unknown>): void {
76
+ if (!DUMP_PATH) return;
77
+ try {
78
+ const line: DumpLine = {
79
+ ts: new Date().toISOString(),
80
+ reqId,
81
+ phase,
82
+ ...data,
83
+ };
84
+ appendFileSync(DUMP_PATH, JSON.stringify(line) + "\n", "utf-8");
85
+ } catch {
86
+ // intentional swallow — see header comment
87
+ }
88
+ }
89
+
90
+ /** True when dumping is active. Cheap check used to gate per-phase logic in handler. */
91
+ export function dumpEnabled(): boolean {
92
+ return !!DUMP_PATH;
93
+ }
src/proxy/endpoint-routing.ts ADDED
@@ -0,0 +1,215 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Provider endpoint routing — mirrors the ZCode 3.7+ `ProviderEndpointRoutingService`.
3
+ *
4
+ * The desktop client periodically fetches `GET {zcodeApiBase}/api/v1/agent/configs`
5
+ * and rewrites provider request URLs according to the returned
6
+ * `data.proxyEndpoint.mapping` table (`from` → `to`, exact normalized-URL match).
7
+ * As of 2026-08-19 the server maps the coding-plan Anthropic endpoints to
8
+ * `zcode.z.ai/api/v1/ultra[-zai]/...`; the table is server-controlled and may
9
+ * grow at any time, so resolution is generic.
10
+ *
11
+ * Failure semantics are strictly fail-open: any fetch/parse error keeps the
12
+ * previous snapshot (or none) and requests go to their original URL after a
13
+ * cooldown. See `_reverse/NOTEPAD.md` "Server-side endpoint remapping".
14
+ */
15
+ import { buildIdentityHeaders, identityCacheKey } from "./identity.js";
16
+ import type { ProxyIdentity } from "../config/types.js";
17
+
18
+ const DEFAULT_ORIGIN = "https://zcode.z.ai";
19
+ const CONFIG_PATH = "/api/v1/agent/configs";
20
+ const SUCCESS_TTL_MS = 300_000;
21
+ const FAILURE_COOLDOWN_MS = 30_000;
22
+ const REQUEST_TIMEOUT_MS = 3_000;
23
+ const MAX_MAPPING_ENTRIES = 256;
24
+
25
+ export interface EndpointRoutingOptions {
26
+ /** Origin of the agent-configs endpoint. */
27
+ origin?: string;
28
+ identity: ProxyIdentity;
29
+ /** Resolves the `x-api-key` sent on the config fetch (coding-plan credential). */
30
+ credential?: () => string | undefined;
31
+ fetchImpl?: typeof fetch;
32
+ now?: () => number;
33
+ successTtlMs?: number;
34
+ failureCooldownMs?: number;
35
+ requestTimeoutMs?: number;
36
+ onSnapshot?: (entries: number) => void;
37
+ }
38
+
39
+ export interface RoutedUrl {
40
+ routed: boolean;
41
+ url: string;
42
+ }
43
+
44
+ interface RoutingSnapshot {
45
+ expiresAt: number;
46
+ mapping: Map<string, string>;
47
+ }
48
+
49
+ function normalizePath(pathname: string): string {
50
+ if (pathname === "/") return "/";
51
+ return pathname.replace(/\/+$/u, "") || "/";
52
+ }
53
+
54
+ function routingKey(url: URL): string {
55
+ const port = url.port || "443";
56
+ return `${url.protocol}//${url.hostname.toLowerCase()}:${port}${normalizePath(url.pathname)}`;
57
+ }
58
+
59
+ function parseMappingUrl(value: unknown, field: "from" | "to"): URL {
60
+ if (typeof value !== "string") throw new Error(`mapping.${field} must be a string`);
61
+ const parsed = new URL(value);
62
+ if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.search || parsed.hash) {
63
+ throw new Error(`mapping.${field} URL is not a plain https URL`);
64
+ }
65
+ return parsed;
66
+ }
67
+
68
+ export class EndpointRoutingService {
69
+ private readonly configUrl: string;
70
+ private readonly identity: ProxyIdentity;
71
+ private readonly credential?: () => string | undefined;
72
+ private readonly fetchImpl: typeof fetch;
73
+ private readonly now: () => number;
74
+ private readonly successTtlMs: number;
75
+ private readonly failureCooldownMs: number;
76
+ private readonly requestTimeoutMs: number;
77
+ private readonly onSnapshot?: (entries: number) => void;
78
+ private snapshot: RoutingSnapshot | undefined;
79
+ private retryAfter = 0;
80
+ private refreshPromise: Promise<void> | undefined;
81
+
82
+ constructor(opts: EndpointRoutingOptions) {
83
+ this.configUrl = `${(opts.origin?.trim() || DEFAULT_ORIGIN).replace(/\/+$/u, "")}${CONFIG_PATH}`;
84
+ this.identity = opts.identity;
85
+ this.credential = opts.credential;
86
+ this.fetchImpl = opts.fetchImpl ?? fetch;
87
+ this.now = opts.now ?? Date.now;
88
+ this.successTtlMs = opts.successTtlMs ?? SUCCESS_TTL_MS;
89
+ this.failureCooldownMs = opts.failureCooldownMs ?? FAILURE_COOLDOWN_MS;
90
+ this.requestTimeoutMs = opts.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
91
+ this.onSnapshot = opts.onSnapshot;
92
+ }
93
+
94
+ /** True when at least one successful snapshot has been fetched. */
95
+ hasSnapshot(): boolean {
96
+ return this.snapshot !== undefined;
97
+ }
98
+
99
+ /**
100
+ * Resolve a request URL through the mapping table. Never throws: any error
101
+ * resolves to `{ routed: false, url }` so the caller keeps the original URL.
102
+ * The optional `credential` (coding-plan key) is attached as `x-api-key` on
103
+ * a mapping refresh fetch, mirroring the client's `sourceHeaders`.
104
+ */
105
+ async resolve(url: string, credential?: string): Promise<RoutedUrl> {
106
+ let parsed: URL;
107
+ try {
108
+ parsed = new URL(url);
109
+ } catch {
110
+ return { routed: false, url };
111
+ }
112
+ try {
113
+ await this.ensureFresh(credential);
114
+ } catch {
115
+ // fail-open: resolve without a snapshot
116
+ }
117
+ const target = this.snapshot?.mapping.get(routingKey(parsed));
118
+ if (!target) return { routed: false, url };
119
+ const rewritten = new URL(target);
120
+ rewritten.search = parsed.search;
121
+ return { routed: true, url: rewritten.href };
122
+ }
123
+
124
+ private async ensureFresh(credential?: string): Promise<void> {
125
+ const now = this.now();
126
+ if ((this.snapshot && this.snapshot.expiresAt > now) || this.retryAfter > now) return;
127
+ const pending = this.refreshPromise ?? this.beginRefresh(credential);
128
+ await pending;
129
+ }
130
+
131
+ private beginRefresh(credential?: string): Promise<void> {
132
+ const promise = this.refresh(credential).finally(() => {
133
+ if (this.refreshPromise === promise) this.refreshPromise = undefined;
134
+ });
135
+ this.refreshPromise = promise;
136
+ return promise;
137
+ }
138
+
139
+ private async refresh(credential?: string): Promise<void> {
140
+ // QSt (bundle) builds the config-fetch identity set WITHOUT X-ZCode-Agent;
141
+ // Pvo appends x-api-key + Accept. Mirror that set exactly.
142
+ const identityHeaders = Object.fromEntries(
143
+ Object.entries(buildIdentityHeaders(this.identity)).filter(([name]) => name !== "X-ZCode-Agent"),
144
+ );
145
+ const headers: Record<string, string> = {
146
+ ...identityHeaders,
147
+ Accept: "application/json",
148
+ };
149
+ const key = credential ?? this.credential?.();
150
+ if (key) headers["x-api-key"] = key;
151
+
152
+ const controller = new AbortController();
153
+ const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
154
+ try {
155
+ const resp = await this.fetchImpl(this.configUrl, {
156
+ method: "GET",
157
+ headers,
158
+ redirect: "manual",
159
+ signal: controller.signal,
160
+ });
161
+ if (resp.status < 200 || resp.status >= 300) throw new Error(`agent_configs_http_${resp.status}`);
162
+ const parsed = await resp.json() as unknown;
163
+ const envelope = parsed as { code?: unknown; data?: unknown };
164
+ if (!envelope || typeof envelope !== "object" || envelope.code !== 0) {
165
+ throw new Error("agent_configs_nonzero_code");
166
+ }
167
+ const data = envelope.data as { proxyEndpoint?: { mapping?: unknown } } | undefined;
168
+ const entries = data?.proxyEndpoint?.mapping;
169
+ const list = Array.isArray(entries) ? entries : [];
170
+ if (list.length > MAX_MAPPING_ENTRIES) throw new Error("agent_configs_too_many_mappings");
171
+
172
+ const mapping = new Map<string, string>();
173
+ for (const entry of list) {
174
+ const raw = entry as { from?: unknown; to?: unknown };
175
+ const from = parseMappingUrl(raw.from, "from");
176
+ const to = parseMappingUrl(raw.to, "to");
177
+ const key = routingKey(from);
178
+ if (mapping.has(key)) throw new Error("agent_configs_duplicate_from");
179
+ mapping.set(key, to.href);
180
+ }
181
+ this.snapshot = { expiresAt: this.now() + this.successTtlMs, mapping };
182
+ this.retryAfter = 0;
183
+ this.onSnapshot?.(mapping.size);
184
+ } catch {
185
+ this.retryAfter = this.now() + this.failureCooldownMs;
186
+ } finally {
187
+ clearTimeout(timer);
188
+ }
189
+ }
190
+ }
191
+
192
+ let defaultRouting: EndpointRoutingService | null = null;
193
+ let defaultRoutingKey = "";
194
+
195
+ /**
196
+ * Process-wide routing service, shared across requests (snapshot cache).
197
+ * Recreated when the relevant config values change (Android `setConfig`) —
198
+ * keyed on the full identity because the service embeds it in config-fetch
199
+ * headers. Returns `null` when disabled.
200
+ */
201
+ export function getDefaultEndpointRouting(config: {
202
+ endpointRouting: { enabled: boolean; origin: string };
203
+ identity: ProxyIdentity;
204
+ }): EndpointRoutingService | null {
205
+ if (!config.endpointRouting.enabled) return null;
206
+ const key = `${config.endpointRouting.origin}\n${identityCacheKey(config.identity)}`;
207
+ if (!defaultRouting || key !== defaultRoutingKey) {
208
+ defaultRouting = new EndpointRoutingService({
209
+ origin: config.endpointRouting.origin,
210
+ identity: config.identity,
211
+ });
212
+ defaultRoutingKey = key;
213
+ }
214
+ return defaultRouting;
215
+ }
src/proxy/handler.ts ADDED
@@ -0,0 +1,988 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Main proxy handler — routes requests, injects auth, forwards, and streams responses.
3
+ *
4
+ * **v2.6 upstream reality (post-PR #34)**: BOTH plan tiers post an
5
+ * Anthropic-format upstream — coding-plan mirrors the real ZCode client
6
+ * (api.z.ai/api/anthropic → ultra via endpoint routing); start-plan posts to
7
+ * zcode.z.ai's Anthropic gateway with the plan JWT. Consequently:
8
+ * - OpenAI clients are translated OpenAI→Anthropic on the way up and
9
+ * Anthropic→OpenAI on the way down ("translation" mode).
10
+ * - Anthropic clients speak the upstream's native format — requests are
11
+ * forwarded with body transforms only ("passthrough" mode,
12
+ * `decompress: false`).
13
+ *
14
+ * @see .omo/plans/zcode-proxy.md Task 6
15
+ */
16
+ import type { Format } from "../translator/types.js";
17
+ import type { ProxyConfig } from "../config/types.js";
18
+ import type { AuthManager } from "../auth/manager.js";
19
+ import { getProvider } from "../provider/providers.js";
20
+ import { buildUpstreamHeaderPairs, buildUpstreamRequest, type UpstreamHeaderPair } from "./upstream.js";
21
+ import { getDefaultEndpointRouting, type EndpointRoutingService } from "./endpoint-routing.js";
22
+ import { getDefaultClientSigning, sendWithClientSigning, type ClientSigningManager } from "./client-signing.js";
23
+ import { credentialString } from "../auth/types.js";
24
+ import { sendOrderedUpstreamRequest } from "./ordered-transport.js";
25
+ import { transformRequestBody } from "./body-transformer.js";
26
+ import { isCaptchaChallenged, retryOnCaptchaChallenge } from "./captcha-retry.js";
27
+ import { type ClientSessionResult } from "./client-session.js";
28
+ import { resolveSessionContext } from "./session-context.js";
29
+ import { gzipSync } from "node:zlib";
30
+
31
+ // captcha.ts is loaded lazily inside the `startPlan` branch (only path that
32
+ // touches it). The solver itself (captcha-happy.ts) is dynamically imported
33
+ // by captcha-solver.ts, so non-start-plan processes never pay its startup
34
+ // cost. Desktop Bun keeps the same code path; the dynamic import resolves
35
+ // synchronously enough on Bun's warm cache.
36
+ type CaptchaModule = typeof import("./captcha.js");
37
+ let captchaModule: CaptchaModule | null = null;
38
+ async function loadCaptcha(): Promise<CaptchaModule> {
39
+ if (!captchaModule) captchaModule = await import("./captcha.js");
40
+ return captchaModule;
41
+ }
42
+ import { translateRequestOpenAIToAnthropic, translateResponseAnthropicToOpenAI } from "../translator/openai-to-anthropic.js";
43
+ import { translateRequestAnthropicToOpenAI, translateResponseOpenAIToAnthropic } from "../translator/anthropic-to-openai.js";
44
+ import { anthropicSseToOpenaiSse, openaiSseToAnthropicSse } from "../translator/sse-translator.js";
45
+ import type { OpenAIChatRequest, OpenAIChatResponse, AnthropicMessagesRequest, AnthropicMessagesResponse } from "../translator/types.js";
46
+ import { dumpPhase, dumpHeaders, dumpBody, dumpEnabled } from "./dump.js";
47
+ import { inflateWithCap } from "./inflate.js";
48
+
49
+ /** Options for the proxy handler. */
50
+ export interface ProxyHandlerOptions {
51
+ config: ProxyConfig;
52
+ auth: AuthManager;
53
+ /** Override the global fetch (for testing). Defaults to global `fetch`. */
54
+ fetchImpl?: typeof fetch;
55
+ /**
56
+ * When true, emit additional per-request diagnostic lines: upstream URL,
57
+ * redacted request headers, body preview, upstream response status and
58
+ * selected response headers. Activated by `zcode-proxy serve debug`.
59
+ */
60
+ debug?: boolean;
61
+ /** Override the process-wide endpoint routing service (for testing). `null` disables. */
62
+ endpointRouting?: EndpointRoutingService | null;
63
+ /** Override the process-wide client signing manager (for testing). `null` disables. */
64
+ clientSigning?: ClientSigningManager | null;
65
+ }
66
+
67
+ /**
68
+ * Forward a client request to the upstream provider with injected auth.
69
+ *
70
+ * Upstream fetch options differ by mode:
71
+ * - **Passthrough** (OpenAI client): `{ decompress: false }` — compressed
72
+ * response bodies (gzip/deflate/br) pass through untouched; raw bytes and the
73
+ * Content-Encoding header are forwarded as-is, letting the client decompress.
74
+ * - **Translation** (Anthropic client): no options — Bun decompresses so the proxy
75
+ * can read the body and translate OpenAI→Anthropic (then re-gzip if the client
76
+ * accepts).
77
+ *
78
+ * No upstream timeout is applied — matches ZCode desktop client behaviour
79
+ * (the bundle has no automatic timer on LLM calls, only user-initiated abort).
80
+ * Connection-level errors (ECONNREFUSED, DNS failure) still surface as 502.
81
+ */
82
+ export async function proxyRequest(
83
+ clientReq: Request,
84
+ format: Format,
85
+ opts: ProxyHandlerOptions,
86
+ ): Promise<Response> {
87
+ const { config, auth } = opts;
88
+ const fetchImpl = opts.fetchImpl ?? fetch;
89
+ const hasCustomFetchImpl = opts.fetchImpl !== undefined;
90
+ const debug = opts.debug === true;
91
+ const started = Date.now();
92
+ const reqId = nextReqId();
93
+
94
+ let body: string | undefined;
95
+ try {
96
+ body = await readBody(clientReq);
97
+ } catch (err) {
98
+ if (err instanceof InflatedBodyTooLargeError) {
99
+ return errorResponse(413, "request_too_large", err.message);
100
+ }
101
+ return errorResponse(400, "invalid_request_error", (err as Error).message);
102
+ }
103
+
104
+ const meta = peekBody(body);
105
+
106
+ if (dumpEnabled()) {
107
+ dumpPhase(reqId, "client_in", {
108
+ method: clientReq.method,
109
+ url: clientReq.url,
110
+ headers: dumpHeaders(clientReq.headers),
111
+ body: dumpBody(body),
112
+ });
113
+ }
114
+
115
+ const staticProvider = getProvider(config.provider);
116
+ const provider = {
117
+ ...staticProvider,
118
+ anthropicBaseURL: config.providers[config.provider].anthropicBase,
119
+ openaiBaseURL: config.providers[config.provider].openaiBase,
120
+ };
121
+
122
+ let cred;
123
+ try {
124
+ cred = await auth.getCredential();
125
+ } catch (err) {
126
+ if (debug) debugError(reqId, "credential_unavailable", (err as Error).message);
127
+ printRow(reqId, format, meta, 503, started, Date.now(), 0, 0, 0);
128
+ return errorResponse(503, "credential_unavailable", (err as Error).message);
129
+ }
130
+
131
+ // v2.6: both plans use the Anthropic upstream. coding-plan mirrors the real
132
+ // ZCode client (api.z.ai/api/anthropic → ultra via endpoint routing);
133
+ // start-plan's old OpenAI gateway (/api/v1/zcode-plan/chat/completions) was
134
+ // retired server-side (404 as of 2026-08-28) — the live desktop client now
135
+ // posts Anthropic messages to /api/v1/zcode-plan/anthropic/v1/messages with
136
+ // the start-plan JWT, so we do the same (no OpenAI translation either way).
137
+ const startPlan = config.plan === "start-plan";
138
+ const translateAnthropicToOpenAI = false;
139
+ const translateOpenAIToAnthropic = format === "openai";
140
+ const upstreamFormat: Format = "anthropic";
141
+ const clientSession = resolveSessionContext({ clientReq, body, upstreamFormat, model: meta.model, config });
142
+ if (debug && clientSession) {
143
+ const shortSession = clientSession.sessionId ? clientSession.sessionId.slice(0, 10) : "-";
144
+ debugLine(reqId, `clientIdentity source=${clientSession.source} action=${clientSession.action} confidence=${clientSession.confidence.toFixed(2)} session=${shortSession}`);
145
+ }
146
+
147
+ let upstreamBody = body;
148
+ if (translateOpenAIToAnthropic) {
149
+ const translated = translateOpenAIBody(body);
150
+ if (translated instanceof Response) return translated;
151
+ upstreamBody = translated;
152
+ if (debug) debugLine(reqId, `translated OpenAI→Anthropic (bytes=${upstreamBody?.length ?? 0})`);
153
+ } else if (translateAnthropicToOpenAI) {
154
+ const translated = translateAnthropicBody(body);
155
+ if (translated instanceof Response) return translated;
156
+ upstreamBody = translated;
157
+ if (debug) debugLine(reqId, `translated Anthropic→OpenAI (bytes=${upstreamBody?.length ?? 0})`);
158
+ }
159
+
160
+ const transformedBody = transformRequestBody(upstreamBody, { format: upstreamFormat, userId: startPlan ? undefined : cred.userId, startPlan });
161
+ if (debug && transformedBody !== upstreamBody) {
162
+ debugLine(reqId, `body transformed (upstreamFormat=${upstreamFormat}, startPlan=${startPlan}, bytes=${transformedBody?.length ?? 0})`);
163
+ }
164
+
165
+ let captchaHeaders: Record<string, string> | undefined;
166
+ if (startPlan) {
167
+ try {
168
+ const captcha = await loadCaptcha();
169
+ const token = await captcha.getCaptchaToken(config.identity.appVersion);
170
+ captchaHeaders = { [captcha.RETRY_HEADERS.PARAM]: token.verifyParam, [captcha.RETRY_HEADERS.REGION]: token.region };
171
+ } catch {
172
+ // Will solve on 403 fallback below
173
+ }
174
+ }
175
+
176
+ const useOrderedTransport = shouldUseOrderedTransport(config, clientSession, hasCustomFetchImpl);
177
+ let upstreamHeaderPairs = buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, config.identity, config.plan, captchaHeaders, clientSession);
178
+ let upstreamReq = buildUpstreamRequest(clientReq, upstreamFormat, provider, cred, transformedBody, config.identity, config.plan, captchaHeaders, clientSession);
179
+
180
+ const routing = opts.endpointRouting !== undefined ? opts.endpointRouting : getDefaultEndpointRouting(config);
181
+ const signer = opts.clientSigning !== undefined ? opts.clientSigning : getDefaultClientSigning(config);
182
+ const translateMode = translateOpenAIToAnthropic || translateAnthropicToOpenAI;
183
+ const dispatch = async (req: Request, pairs: UpstreamHeaderPair[]): Promise<Response> => {
184
+ let sendUrl = req.url;
185
+ if (routing) {
186
+ const routed = await routing.resolve(req.url, credentialString(cred));
187
+ if (routed.routed) {
188
+ sendUrl = routed.url;
189
+ if (debug) debugLine(reqId, `endpoint routing: ${req.url} -> ${routed.url}`);
190
+ }
191
+ }
192
+ // Signing decisions (exempt-path, handshake origin, bypass keying) run
193
+ // against the PRE-routing provider URL — the client's signer wraps the
194
+ // routing transport, so its checks see the original URL too.
195
+ return sendWithClientSigning(signer, {
196
+ url: req.url,
197
+ headerPairs: pairs,
198
+ credential: credentialString(cred),
199
+ appVersion: config.identity.appVersion,
200
+ debug: debug ? (message) => debugLine(reqId, message) : undefined,
201
+ send: (finalPairs) => {
202
+ const sendReq = sendUrl === req.url && finalPairs === pairs
203
+ ? req
204
+ : new Request(sendUrl, {
205
+ method: req.method,
206
+ headers: Object.fromEntries(finalPairs),
207
+ body: transformedBody ?? undefined,
208
+ });
209
+ return sendUpstreamRequest(sendReq, finalPairs, transformedBody, translateMode, useOrderedTransport, fetchImpl, clientReq.signal, hasCustomFetchImpl);
210
+ },
211
+ });
212
+ };
213
+
214
+ if (debug) {
215
+ debugLine(reqId, `→ POST ${upstreamReq.url}`);
216
+ debugLine(reqId, ` ${formatHeaderPairs(upstreamReq.headers)}`);
217
+ if (transformedBody) debugLine(reqId, ` body preview: ${previewBody(transformedBody)}`);
218
+ }
219
+
220
+ if (dumpEnabled()) {
221
+ dumpPhase(reqId, "upstream_out", {
222
+ method: upstreamReq.method,
223
+ url: upstreamReq.url,
224
+ headers: dumpHeaders(upstreamReq.headers),
225
+ body: dumpBody(transformedBody),
226
+ upstreamFormat,
227
+ translateMode: translateOpenAIToAnthropic || translateAnthropicToOpenAI,
228
+ useOrderedTransport,
229
+ startPlan,
230
+ });
231
+ }
232
+
233
+ let upstreamResp: Response;
234
+ try {
235
+ // Transient connect failures (DNS blip, TLS reset, Bun "Unable to
236
+ // connect") happen a few times a day against the gateway. Retry the
237
+ // CONNECT twice with a short backoff before surfacing a 502 — the
238
+ // request never reached upstream, so resending is side-effect-free.
239
+ // Guard rails: skip retry when the client already aborted or the ordered
240
+ // transport flagged the failure postWrite; re-dispatch a FRESH Request
241
+ // each attempt — a reused Request has its body stream marked used after
242
+ // the first fetch (start-plan hits the plain pass-through path where
243
+ // dispatch does NOT rebuild the Request).
244
+ let dispatchAttempt = 0;
245
+ upstreamResp = await dispatchWithConnectRetry(
246
+ () => {
247
+ dispatchAttempt += 1;
248
+ const currentReq = dispatchAttempt === 1
249
+ ? upstreamReq
250
+ : buildUpstreamRequest(clientReq, upstreamFormat, provider, cred, transformedBody, config.identity, config.plan, captchaHeaders, clientSession);
251
+ return dispatch(currentReq, upstreamHeaderPairs);
252
+ },
253
+ {
254
+ isAborted: () => clientReq.signal.aborted,
255
+ onRetry: (attempt, err) => {
256
+ if (debug) debugError(reqId, "upstream_connect_retry", `attempt ${attempt}/${MAX_CONNECT_ATTEMPTS - 1} failed (${err.message}), retrying in ${500 * attempt}ms`);
257
+ console.log(`${reqId} upstream connect failed (${err.message}), retry ${attempt + 1}/${MAX_CONNECT_ATTEMPTS} in ${500 * attempt}ms`);
258
+ },
259
+ },
260
+ );
261
+ } catch (err) {
262
+ if (debug) debugError(reqId, "upstream_unreachable", (err as Error).message);
263
+ printRow(reqId, format, meta, 502, started, Date.now(), 0, 0, 0);
264
+ return errorResponse(502, "upstream_unreachable", (err as Error).message);
265
+ }
266
+ const headersAt = Date.now();
267
+
268
+ if (debug) {
269
+ debugLine(reqId, `← ${upstreamResp.status} ${upstreamResp.statusText}`);
270
+ debugLine(reqId, ` ${formatResponseHeaders(upstreamResp.headers)}`);
271
+ }
272
+
273
+ if (dumpEnabled()) {
274
+ dumpPhase(reqId, "upstream_in", {
275
+ status: upstreamResp.status,
276
+ statusText: upstreamResp.statusText,
277
+ headers: dumpHeaders(upstreamResp.headers),
278
+ isSSE: upstreamResp.headers.get("content-type")?.includes("text/event-stream") ?? false,
279
+ ttfbMs: headersAt - started,
280
+ });
281
+ }
282
+
283
+ if (upstreamResp.status === 401 && startPlan) {
284
+ if (debug) debugError(reqId, "start_plan_jwt_invalid", "JWT rejected upstream");
285
+ printRow(reqId, format, meta, 401, started, headersAt, 0, 0, 0);
286
+ return errorResponse(401, "start_plan_jwt_invalid", "Start-plan JWT was rejected. Re-run: zcode-proxy auth login");
287
+ }
288
+
289
+ // start-plan: on explicit captcha challenge, retry once with a fresh
290
+ // pooled token (the challenged token was already consumed by this request;
291
+ // getCaptchaToken takes the next pre-solved one). Detection covers the
292
+ // response-header variant AND the in-body `{"code":3007}` variant (observed
293
+ // 2026-08-29 as HTTP 400 JSON with no captcha header) via the shared
294
+ // captcha-retry seam (used by /v1/responses too).
295
+ const captcha = startPlan ? await loadCaptcha() : null;
296
+ const captchaChallenge = captcha ? await isCaptchaChallenged(upstreamResp, captcha) : false;
297
+ if (captchaChallenge && captcha) {
298
+ console.log(`${reqId} captcha challenge, re-solving...`);
299
+ const outcome = await retryOnCaptchaChallenge({
300
+ captcha,
301
+ appVersion: config.identity.appVersion,
302
+ challengedResp: upstreamResp,
303
+ debug: debug ? (message) => debugLine(reqId, message) : undefined,
304
+ solveAndRetry: (retryHeaders) => {
305
+ console.log(`${reqId} captcha re-solved (token ${retryHeaders[captcha.RETRY_HEADERS.PARAM].length} chars), retrying...`);
306
+ upstreamHeaderPairs = buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, config.identity, config.plan, retryHeaders, clientSession);
307
+ upstreamReq = buildUpstreamRequest(clientReq, upstreamFormat, provider, cred, transformedBody, config.identity, config.plan, retryHeaders, clientSession);
308
+ return dispatch(upstreamReq, upstreamHeaderPairs).then((resp) => {
309
+ if (debug) debugLine(reqId, `← retry ${resp.status} ${resp.statusText}`);
310
+ return resp;
311
+ });
312
+ },
313
+ mapError: (err, phase) => {
314
+ if (phase === "solver") {
315
+ if (debug) debugError(reqId, "captcha_solver_failed", err.message);
316
+ printRow(reqId, format, meta, 503, started, Date.now(), 0, 0, 0);
317
+ return errorResponse(503, "captcha_solver_failed", err.message);
318
+ }
319
+ if (debug) debugError(reqId, "upstream_unreachable", err.message);
320
+ printRow(reqId, format, meta, 502, started, Date.now(), 0, 0, 0);
321
+ return errorResponse(502, "upstream_unreachable", err.message);
322
+ },
323
+ });
324
+ if (!outcome.ok) return outcome.resp;
325
+ upstreamResp = outcome.resp;
326
+ }
327
+
328
+ const isSSE = upstreamResp.headers.get("content-type")?.includes("text/event-stream") ?? false;
329
+
330
+ if (translateOpenAIToAnthropic) {
331
+ if (!upstreamResp.ok) {
332
+ const errBody = await upstreamResp.text().catch(() => "");
333
+ printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0);
334
+ return errorResponse(502, "translation_failed", `upstream returned ${upstreamResp.status}: ${errBody.slice(0, 200)}`);
335
+ }
336
+ if (isSSE && upstreamResp.body) {
337
+ const translated = anthropicSseToOpenaiSse(upstreamResp.body, meta.model);
338
+ const [clientBody, statsBody] = translated.tee();
339
+ observeStream(reqId, format, meta, upstreamResp.status, started, statsBody, null);
340
+ return translatedSseResponse(clientBody);
341
+ }
342
+ return await translatedBatchResponse(clientReq, upstreamResp, meta.model, reqId, format, meta, started, headersAt);
343
+ }
344
+
345
+ if (translateAnthropicToOpenAI) {
346
+ if (!upstreamResp.ok) {
347
+ const errBody = await upstreamResp.text().catch(() => "");
348
+ printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0);
349
+ return errorResponse(502, "translation_failed", `upstream returned ${upstreamResp.status}: ${errBody.slice(0, 200)}`);
350
+ }
351
+ if (isSSE && upstreamResp.body) {
352
+ const translated = openaiSseToAnthropicSse(upstreamResp.body, meta.model);
353
+ const [clientBody, statsBody] = translated.tee();
354
+ observeStream(reqId, format, meta, upstreamResp.status, started, statsBody, null);
355
+ return translatedSseResponse(clientBody);
356
+ }
357
+ return await translatedOpenAIToAnthropicBatchResponse(clientReq, upstreamResp, reqId, format, meta, started, headersAt);
358
+ }
359
+
360
+ if (isSSE && upstreamResp.body) {
361
+ const [clientBody, statsBody] = upstreamResp.body.tee();
362
+ observeStream(reqId, format, meta, upstreamResp.status, started, statsBody, upstreamResp.headers.get("content-encoding"));
363
+ return passthroughResponse(upstreamResp, clientAcceptsGzip(clientReq), clientBody);
364
+ }
365
+
366
+ printRow(reqId, format, meta, upstreamResp.status, started, headersAt, 0, 0, 0);
367
+ return passthroughResponse(upstreamResp, clientAcceptsGzip(clientReq));
368
+ }
369
+
370
+ export function shouldUseOrderedTransport(config: ProxyConfig, clientSession: ClientSessionResult | undefined, hasCustomFetchImpl: boolean): boolean {
371
+ if (hasCustomFetchImpl) return false;
372
+ return clientSession?.action === "enforce" || clientSession?.source === "explicit";
373
+ }
374
+
375
+ /** Max attempts (initial + 2 retries) for transient CONNECT-level failures. */
376
+ export const MAX_CONNECT_ATTEMPTS = 3;
377
+
378
+ /**
379
+ * Connect-level retry ladder shared by the chat hot path and /v1/responses.
380
+ * Transient connect failures (DNS blip, TLS reset, Bun "Unable to connect")
381
+ * happen a few times a day against the gateway; the request never reached
382
+ * upstream, so resending is side-effect-free.
383
+ *
384
+ * Contract (review P1/P2, PR #34/#35):
385
+ * - `attemptDispatch` must dispatch a FRESH request each call — a reused
386
+ * Request has its body stream marked used after the first fetch.
387
+ * - failures flagged `postWrite` (ordered transport already wrote the full
388
+ * request) are never retried — the upstream may have processed it.
389
+ * - no retry once the client aborted (`opts.isAborted`).
390
+ */
391
+ export async function dispatchWithConnectRetry(
392
+ attemptDispatch: () => Promise<Response>,
393
+ opts: { isAborted?: () => boolean; onRetry?: (attempt: number, err: Error) => void } = {},
394
+ ): Promise<Response> {
395
+ for (let attempt = 1; ; attempt++) {
396
+ if (opts.isAborted?.()) throw new Error("client aborted before upstream connect");
397
+ try {
398
+ return await attemptDispatch();
399
+ } catch (err) {
400
+ if ((err as { postWrite?: boolean }).postWrite) throw err;
401
+ if (attempt >= MAX_CONNECT_ATTEMPTS) throw err;
402
+ const backoffMs = 500 * attempt;
403
+ opts.onRetry?.(attempt, err as Error);
404
+ await new Promise((r) => setTimeout(r, backoffMs));
405
+ }
406
+ }
407
+ }
408
+
409
+ /**
410
+ * True on runtimes whose fetch ignores Bun's `decompress: false` extension and
411
+ * transparently inflates compressed response bodies while KEEPING the
412
+ * `content-encoding`/`content-length` headers (verified empirically against
413
+ * Node 22/26 undici and Bun 1.3: gzip, deflate and br are all decoded, headers
414
+ * unchanged). Bun honors `decompress: false` (raw bytes + truthful header), so
415
+ * no normalization is needed there.
416
+ */
417
+ const FETCH_AUTO_DECOMPRESSES = typeof Bun === "undefined";
418
+
419
+ /** Content codings a `FETCH_AUTO_DECOMPRESSES` runtime inflates transparently. */
420
+ const AUTO_DECODED_ENCODINGS = new Set(["gzip", "x-gzip", "deflate", "br"]);
421
+
422
+ /**
423
+ * Strip `content-encoding`/`content-length` from a Response whose body the
424
+ * runtime fetch has ALREADY inflated. Without this, passthrough on Node would
425
+ * forward a decoded body still labeled `content-encoding: gzip` — clients that
426
+ * advertise gzip then fail to decompress it, and the `passthroughResponse`
427
+ * safety net would double-decompress an already-inflated stream for clients
428
+ * that don't. No-op for encodings the runtime leaves untouched. Returns a new
429
+ * Response because a fetch Response's headers can be immutable.
430
+ */
431
+ export function stripAutoDecodedEncoding(resp: Response): Response {
432
+ const encoding = resp.headers.get("content-encoding")?.toLowerCase().trim() ?? "";
433
+ if (!encoding) return resp;
434
+ const codings = encoding.split(",").map((c) => c.trim());
435
+ if (!codings.every((c) => AUTO_DECODED_ENCODINGS.has(c))) return resp;
436
+ const headers = new Headers(resp.headers);
437
+ headers.delete("content-encoding");
438
+ headers.delete("content-length");
439
+ return new Response(resp.body, {
440
+ status: resp.status,
441
+ statusText: resp.statusText,
442
+ headers,
443
+ });
444
+ }
445
+
446
+ async function sendUpstreamRequest(
447
+ upstreamReq: Request,
448
+ headerPairs: UpstreamHeaderPair[],
449
+ body: string | undefined,
450
+ translateMode: boolean,
451
+ useOrderedTransport: boolean,
452
+ fetchImpl: typeof fetch,
453
+ abortSignal?: AbortSignal,
454
+ hasCustomFetchImpl = false,
455
+ ): Promise<Response> {
456
+ if (useOrderedTransport) {
457
+ return sendOrderedUpstreamRequest({
458
+ url: upstreamReq.url,
459
+ method: upstreamReq.method,
460
+ headers: headerPairs,
461
+ body,
462
+ decompress: translateMode,
463
+ signal: abortSignal,
464
+ });
465
+ }
466
+ const fetchOpts: RequestInit & { decompress?: boolean } = translateMode ? {} : { decompress: false };
467
+ if (abortSignal) fetchOpts.signal = abortSignal;
468
+ const resp = await fetchImpl(upstreamReq, fetchOpts);
469
+ // Passthrough on a runtime whose fetch auto-decompresses (Node/undici in the
470
+ // Android bundle): the body arrives inflated while its headers still claim
471
+ // compression. Drop the stale labels so the body/header pairing downstream
472
+ // stays truthful. Skipped for injected fetch impls (tests) — their bodies are
473
+ // genuinely compressed and their decompression semantics are their own.
474
+ if (!translateMode && FETCH_AUTO_DECOMPRESSES && !hasCustomFetchImpl) {
475
+ return stripAutoDecodedEncoding(resp);
476
+ }
477
+ return resp;
478
+ }
479
+
480
+ /**
481
+ * Read the request body as a string, returning undefined for empty bodies.
482
+ * Transparently inflates `content-encoding: gzip` request bodies (the OpenAI /
483
+ * Anthropic upstreams accept gzipped request bodies; without this, clients
484
+ * that send them got a misleading "body is not valid JSON" 400). Corrupt gzip
485
+ * throws a descriptive Error; inflation past `MAX_INFLATED_BODY_BYTES` throws
486
+ * `InflatedBodyTooLargeError` (streamed + aborted early, so a small wire
487
+ * payload cannot expand into unbounded proxy memory).
488
+ */
489
+ export async function readBody(req: Request): Promise<string | undefined> {
490
+ if (req.method === "GET" || req.method === "HEAD") return undefined;
491
+ const bytes = new Uint8Array(await req.arrayBuffer());
492
+ if (bytes.byteLength === 0) return undefined;
493
+ const encoding = req.headers.get("content-encoding")?.toLowerCase().trim() ?? "";
494
+ if (encoding === "gzip" || encoding === "x-gzip") {
495
+ return new TextDecoder().decode(await inflateGzipBody(bytes));
496
+ }
497
+ return new TextDecoder().decode(bytes);
498
+ }
499
+
500
+ /**
501
+ * Decompressed-size ceiling for gzip request bodies. Generous by design:
502
+ * plain bodies on `/v1/*` routes are intentionally uncapped (long-context LLM
503
+ * requests reach several MB), so this only rejects pathological amplification.
504
+ */
505
+ const MAX_INFLATED_BODY_BYTES = 64 * 1024 * 1024;
506
+
507
+ /** Thrown when a gzip request body expands past MAX_INFLATED_BODY_BYTES. */
508
+ export class InflatedBodyTooLargeError extends Error {
509
+ constructor(limit: number) {
510
+ super(`gzip request body exceeds ${limit} bytes after decompression`);
511
+ this.name = "InflatedBodyTooLargeError";
512
+ }
513
+ }
514
+
515
+ async function inflateGzipBody(bytes: Uint8Array): Promise<Uint8Array> {
516
+ const result = await inflateWithCap(bytes, MAX_INFLATED_BODY_BYTES);
517
+ if (!result.ok) {
518
+ if (result.reason === "too_large") throw new InflatedBodyTooLargeError(MAX_INFLATED_BODY_BYTES);
519
+ throw new Error(`request body is marked content-encoding: gzip but failed to decompress: ${result.detail}`);
520
+ }
521
+ return result.bytes;
522
+ }
523
+
524
+ /**
525
+ * Create a passthrough response that streams the upstream body to the client.
526
+ * Preserves status and the allowlisted headers, and honors the client's
527
+ * `Accept-Encoding` for gzip.
528
+ *
529
+ * The upstream request FORWARDS the client's `accept-encoding` (only
530
+ * defaulting to "gzip" when the client sent none — see
531
+ * `buildUpstreamHeaderPairs`), so the upstream compresses only when the
532
+ * client can decode it. If THIS client did not advertise gzip but the body
533
+ * arrived gzip-compressed anyway, we decompress before forwarding and drop
534
+ * the now-mismatched `content-encoding`/`content-length` headers — otherwise
535
+ * clients whose HTTP stack does not auto-decompress (e.g. some Tauri-based
536
+ * clients) receive raw gzip bytes and fail to parse the JSON body with
537
+ * "non-JSON body" errors despite a 200 status.
538
+ */
539
+ function passthroughResponse(
540
+ upstream: Response,
541
+ clientAcceptsGzip: boolean,
542
+ body?: ReadableStream<Uint8Array>,
543
+ ): Response {
544
+ const headers = new Headers();
545
+ const forwardHeaders = [
546
+ "content-type",
547
+ "content-encoding",
548
+ "cache-control",
549
+ "x-request-id",
550
+ "anthropic-ratelimit-requests-limit",
551
+ "anthropic-ratelimit-requests-remaining",
552
+ "anthropic-ratelimit-requests-reset",
553
+ "anthropic-ratelimit-tokens-limit",
554
+ "anthropic-ratelimit-tokens-remaining",
555
+ "anthropic-ratelimit-tokens-reset",
556
+ ];
557
+
558
+ for (const h of forwardHeaders) {
559
+ const v = upstream.headers.get(h);
560
+ if (v) headers.set(h, v);
561
+ }
562
+
563
+ const upstreamEncoding = headers.get("content-encoding")?.toLowerCase() ?? "";
564
+ const source = body ?? upstream.body;
565
+ if (upstreamEncoding.includes("gzip") && !clientAcceptsGzip && source) {
566
+ const gunzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
567
+ const decompressed = source.pipeThrough(gunzip);
568
+ headers.delete("content-encoding");
569
+ headers.delete("content-length");
570
+ return new Response(decompressed, {
571
+ status: upstream.status,
572
+ statusText: upstream.statusText,
573
+ headers,
574
+ });
575
+ }
576
+
577
+ return new Response(source, {
578
+ status: upstream.status,
579
+ statusText: upstream.statusText,
580
+ headers,
581
+ });
582
+ }
583
+
584
+ /** Build a JSON error response. */
585
+ export function errorResponse(status: number, type: string, message: string): Response {
586
+ const body = JSON.stringify({
587
+ error: { type, message },
588
+ });
589
+ return new Response(body, {
590
+ status,
591
+ headers: { "content-type": "application/json" },
592
+ });
593
+ }
594
+
595
+ /** Translate an OpenAI request body string to Anthropic JSON. Returns error Response on failure. */
596
+ function translateOpenAIBody(body: string | undefined): Response | string | undefined {
597
+ if (body === undefined || body.length === 0) {
598
+ return errorResponse(400, "translation_failed", "OpenAI request body is empty; cannot translate.");
599
+ }
600
+ let parsed: unknown;
601
+ try {
602
+ parsed = JSON.parse(body);
603
+ } catch (err) {
604
+ return errorResponse(400, "translation_failed", `OpenAI request body is not valid JSON: ${(err as Error).message}`);
605
+ }
606
+ try {
607
+ const translated = translateRequestOpenAIToAnthropic(parsed as OpenAIChatRequest);
608
+ return JSON.stringify(translated);
609
+ } catch (err) {
610
+ return errorResponse(400, "translation_failed", `OpenAI→Anthropic translation failed: ${(err as Error).message}`);
611
+ }
612
+ }
613
+
614
+ /** True when the client request explicitly accepts gzip (and has not disabled it via q=0). */
615
+ function clientAcceptsGzip(req: Request): boolean {
616
+ const ae = req.headers.get("accept-encoding");
617
+ if (!ae) return false;
618
+ return /\bgzip\b(?!\s*;\s*q=0(?:\.0+)?\s*(?:,|$))/i.test(ae);
619
+ }
620
+
621
+ /** Build a translated batch (non-streaming) OpenAI response. Gzip if client accepts. */
622
+ async function translatedBatchResponse(
623
+ clientReq: Request,
624
+ upstream: Response,
625
+ model: string,
626
+ reqId: string,
627
+ format: Format,
628
+ meta: RequestMeta,
629
+ started: number,
630
+ headersAt: number,
631
+ ): Promise<Response> {
632
+ const raw = await upstream.text();
633
+ let parsedAnthropic: AnthropicMessagesResponse;
634
+ try {
635
+ parsedAnthropic = JSON.parse(raw) as AnthropicMessagesResponse;
636
+ } catch (err) {
637
+ printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0);
638
+ return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`);
639
+ }
640
+ if (!isAnthropicMessagesResponse(parsedAnthropic)) {
641
+ printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0);
642
+ return errorResponse(502, "translation_failed", `upstream returned invalid Anthropic message: ${raw.slice(0, 200)}`);
643
+ }
644
+ const openaiResp = translateResponseAnthropicToOpenAI(parsedAnthropic, model);
645
+ const json = JSON.stringify(openaiResp);
646
+ const payload = new TextEncoder().encode(json);
647
+
648
+ const respHeaders = new Headers();
649
+ respHeaders.set("content-type", "application/json");
650
+ for (const h of forwardedUpstreamHeaders()) {
651
+ const v = upstream.headers.get(h);
652
+ if (v) respHeaders.set(h, v);
653
+ }
654
+
655
+ if (clientAcceptsGzip(clientReq)) {
656
+ respHeaders.set("content-encoding", "gzip");
657
+ printRow(reqId, format, meta, upstream.status, started, headersAt, openaiResp.usage?.completion_tokens ?? 0, 0, 0);
658
+ return new Response(gzipSync(payload), {
659
+ status: upstream.status,
660
+ headers: respHeaders,
661
+ });
662
+ }
663
+ printRow(reqId, format, meta, upstream.status, started, headersAt, openaiResp.usage?.completion_tokens ?? 0, 0, 0);
664
+ return new Response(payload, {
665
+ status: upstream.status,
666
+ headers: respHeaders,
667
+ });
668
+ }
669
+
670
+ async function translatedOpenAIToAnthropicBatchResponse(
671
+ clientReq: Request,
672
+ upstream: Response,
673
+ reqId: string,
674
+ format: Format,
675
+ meta: RequestMeta,
676
+ started: number,
677
+ headersAt: number,
678
+ ): Promise<Response> {
679
+ const raw = await upstream.text();
680
+ let parsedOpenAI: OpenAIChatResponse;
681
+ try {
682
+ parsedOpenAI = JSON.parse(raw) as OpenAIChatResponse;
683
+ } catch (err) {
684
+ printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0);
685
+ return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`);
686
+ }
687
+ const anthropicResp = translateResponseOpenAIToAnthropic(parsedOpenAI);
688
+ const json = JSON.stringify(anthropicResp);
689
+ const payload = new TextEncoder().encode(json);
690
+
691
+ const respHeaders = new Headers();
692
+ respHeaders.set("content-type", "application/json");
693
+ for (const h of forwardedUpstreamHeaders()) {
694
+ const v = upstream.headers.get(h);
695
+ if (v) respHeaders.set(h, v);
696
+ }
697
+
698
+ if (clientAcceptsGzip(clientReq)) {
699
+ respHeaders.set("content-encoding", "gzip");
700
+ printRow(reqId, format, meta, upstream.status, started, headersAt, anthropicResp.usage.output_tokens, 0, 0);
701
+ return new Response(gzipSync(payload), {
702
+ status: upstream.status,
703
+ headers: respHeaders,
704
+ });
705
+ }
706
+ printRow(reqId, format, meta, upstream.status, started, headersAt, anthropicResp.usage.output_tokens, 0, 0);
707
+ return new Response(payload, {
708
+ status: upstream.status,
709
+ headers: respHeaders,
710
+ });
711
+ }
712
+
713
+ function translateAnthropicBody(body: string | undefined): Response | string | undefined {
714
+ if (body === undefined || body.length === 0) {
715
+ return errorResponse(400, "translation_failed", "Anthropic request body is empty; cannot translate.");
716
+ }
717
+ let parsed: unknown;
718
+ try {
719
+ parsed = JSON.parse(body);
720
+ } catch (err) {
721
+ return errorResponse(400, "translation_failed", `Anthropic request body is not valid JSON: ${(err as Error).message}`);
722
+ }
723
+ try {
724
+ const translated = translateRequestAnthropicToOpenAI(parsed as AnthropicMessagesRequest);
725
+ return JSON.stringify(translated);
726
+ } catch (err) {
727
+ return errorResponse(400, "translation_failed", `Anthropic→OpenAI translation failed: ${(err as Error).message}`);
728
+ }
729
+ }
730
+
731
+ function isAnthropicMessagesResponse(value: unknown): value is AnthropicMessagesResponse {
732
+ if (typeof value !== "object" || value === null) return false;
733
+ const candidate = value as Partial<AnthropicMessagesResponse>;
734
+ return candidate.type === "message" && candidate.role === "assistant" && Array.isArray(candidate.content);
735
+ }
736
+
737
+ function forwardedUpstreamHeaders(): string[] {
738
+ return [
739
+ "x-request-id",
740
+ "anthropic-ratelimit-requests-limit",
741
+ "anthropic-ratelimit-requests-remaining",
742
+ "anthropic-ratelimit-requests-reset",
743
+ "anthropic-ratelimit-tokens-limit",
744
+ "anthropic-ratelimit-tokens-remaining",
745
+ "anthropic-ratelimit-tokens-reset",
746
+ ];
747
+ }
748
+
749
+ function translatedSseResponse(body: ReadableStream<Uint8Array>): Response {
750
+ return new Response(body, {
751
+ status: 200,
752
+ headers: {
753
+ "content-type": "text/event-stream",
754
+ "cache-control": "no-cache",
755
+ },
756
+ });
757
+ }
758
+
759
+ interface RequestMeta {
760
+ model: string;
761
+ stream: boolean;
762
+ }
763
+
764
+ function peekBody(body: string | undefined): RequestMeta {
765
+ if (!body) return { model: "-", stream: false };
766
+ try {
767
+ const p = JSON.parse(body) as Record<string, unknown>;
768
+ return {
769
+ model: typeof p.model === "string" ? p.model : "-",
770
+ stream: p.stream === true,
771
+ };
772
+ } catch {
773
+ return { model: "-", stream: false };
774
+ }
775
+ }
776
+
777
+ let reqCounter = 0;
778
+ let headerPrinted = false;
779
+
780
+ /** Format a unix-ms timestamp as local HH:MM:SS in the host's timezone (not UTC). */
781
+ function localTime(ms: number): string {
782
+ const d = new Date(ms);
783
+ const hh = String(d.getHours()).padStart(2, "0");
784
+ const mm = String(d.getMinutes()).padStart(2, "0");
785
+ const ss = String(d.getSeconds()).padStart(2, "0");
786
+ return `${hh}:${mm}:${ss}`;
787
+ }
788
+
789
+ function nextReqId(): string {
790
+ return `#${String(++reqCounter).padStart(3, "0")}`;
791
+ }
792
+
793
+ const DEBUG_BODY_PREVIEW = 200;
794
+ const SENSITIVE_HEADERS = new Set(["authorization", "x-api-key", "cookie", "set-cookie", "proxy-authorization"]);
795
+
796
+ function debugLine(reqId: string, msg: string): void {
797
+ console.log(`${reqId} debug: ${msg}`);
798
+ }
799
+
800
+ function debugError(reqId: string, kind: string, msg: string): void {
801
+ console.log(`${reqId} debug: ERROR ${kind}: ${msg}`);
802
+ }
803
+
804
+ function redactHeaderVal(key: string, val: string): string {
805
+ const k = key.toLowerCase();
806
+ if (!SENSITIVE_HEADERS.has(k)) return val;
807
+ if (k === "authorization") {
808
+ const sp = val.indexOf(" ");
809
+ return sp > 0 ? `${val.slice(0, sp)} <redacted>` : "<redacted>";
810
+ }
811
+ if (val.length <= 10) return "<redacted>";
812
+ return `${val.slice(0, 6)}...${val.slice(-4)}`;
813
+ }
814
+
815
+ function formatHeaderPairs(headers: Headers): string {
816
+ const pairs: string[] = [];
817
+ for (const [k, v] of headers.entries()) {
818
+ pairs.push(`${k}=${redactHeaderVal(k, v)}`);
819
+ }
820
+ return pairs.join(" ");
821
+ }
822
+
823
+ function formatResponseHeaders(headers: Headers): string {
824
+ const interesting = [
825
+ "content-type",
826
+ "content-encoding",
827
+ "content-length",
828
+ "x-request-id",
829
+ "anthropic-ratelimit-requests-remaining",
830
+ "anthropic-ratelimit-tokens-remaining",
831
+ ];
832
+ const pairs: string[] = [];
833
+ for (const h of interesting) {
834
+ const v = headers.get(h);
835
+ if (v) pairs.push(`${h}=${v}`);
836
+ }
837
+ return pairs.length > 0 ? pairs.join(" ") : "(no notable headers)";
838
+ }
839
+
840
+ function previewBody(body: string): string {
841
+ const flat = body.replace(/\s+/g, " ").trim();
842
+ if (flat.length <= DEBUG_BODY_PREVIEW) return flat;
843
+ return `${flat.slice(0, DEBUG_BODY_PREVIEW)}…(${flat.length} bytes total)`;
844
+ }
845
+
846
+ const COMPACT_LOG = process.env.ZCODE_LOG_FORMAT === "compact";
847
+
848
+ function printHeader(): void {
849
+ if (headerPrinted) return;
850
+ headerPrinted = true;
851
+ if (COMPACT_LOG) return;
852
+ console.log(
853
+ "| # | Time | Fmt | Model | Mode | Stat | TTFB | Tok | tok/s | Total |",
854
+ );
855
+ console.log(
856
+ "|------|------------|-----|-------------|--------|------|---------|-------|--------|---------|",
857
+ );
858
+ }
859
+
860
+ function printRow(
861
+ reqId: string,
862
+ format: Format,
863
+ meta: RequestMeta,
864
+ status: number,
865
+ started: number,
866
+ headersAt: number,
867
+ tokens: number,
868
+ avgTps: number,
869
+ streamEndAt: number,
870
+ ): void {
871
+ printHeader();
872
+ const tag = format === "anthropic" ? "ANT" : "OAI";
873
+ const mode = meta.stream ? "stream" : "batch";
874
+
875
+ if (COMPACT_LOG) {
876
+ const ttfbMs = headersAt - started;
877
+ const totalMs = streamEndAt > started ? streamEndAt - started : ttfbMs;
878
+ const ttfbStr = fmtMs(ttfbMs);
879
+ const tokStr = tokens > 0 ? `${tokens}tok` : "";
880
+ const tpsStr = avgTps > 0 ? `${avgTps.toFixed(0)}t/s` : "";
881
+ const parts = [reqId, tag, meta.model, String(status), mode];
882
+ if (meta.stream && streamEndAt > started) {
883
+ parts.push(`${ttfbStr}→${fmtMs(totalMs)}`);
884
+ } else {
885
+ parts.push(ttfbStr);
886
+ }
887
+ if (tokStr) parts.push(tokStr);
888
+ if (tpsStr) parts.push(tpsStr);
889
+ console.log(parts.join(" "));
890
+ return;
891
+ }
892
+
893
+ const ts = localTime(started);
894
+ const ttfb = `${headersAt - started}ms`;
895
+ const total = streamEndAt > started ? `${streamEndAt - started}ms` : "-";
896
+ const tok = tokens > 0 ? String(tokens) : "-";
897
+ const tps = avgTps > 0 ? avgTps.toFixed(1) : "-";
898
+ console.log(
899
+ `| ${reqId.padEnd(4)} | ${ts.padEnd(10)} | ${tag} | ${meta.model.padEnd(11)} | ${mode.padEnd(6)} | ${String(status).padStart(4)} | ${ttfb.padStart(7)} | ${tok.padStart(5)} | ${tps.padStart(6)} | ${total.padStart(7)} |`,
900
+ );
901
+ }
902
+
903
+ function fmtMs(ms: number): string {
904
+ if (ms < 1000) return `${ms}ms`;
905
+ if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
906
+ return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
907
+ }
908
+
909
+ function observeStream(
910
+ reqId: string,
911
+ format: Format,
912
+ meta: RequestMeta,
913
+ status: number,
914
+ requestSentAt: number,
915
+ body: ReadableStream<Uint8Array>,
916
+ contentEncoding: string | null,
917
+ ): void {
918
+ const compressed = contentEncoding !== null;
919
+ const dumpOn = dumpEnabled();
920
+ let tokens = 0;
921
+ let sseBuffer = "";
922
+ let firstChunkAt = 0;
923
+ let totalBytes = 0;
924
+ let firstBytesSample = "";
925
+
926
+ function parseSse(text: string): void {
927
+ for (const line of text.split("\n")) {
928
+ if (!line.startsWith("data:") || line.includes("[DONE]")) continue;
929
+ try {
930
+ const j = JSON.parse(line.slice(5).trim());
931
+ if (j.usage?.completion_tokens) { tokens = j.usage.completion_tokens; continue; }
932
+ if (j.usage?.output_tokens) { tokens = j.usage.output_tokens; continue; }
933
+ // OpenAI content delta: choices[0].delta.content
934
+ const oai = j.choices?.[0]?.delta?.content;
935
+ if (typeof oai === "string" && oai.length > 0) { tokens++; continue; }
936
+ // Anthropic content delta: type=content_block_delta, delta.type=text_delta
937
+ if (j.type === "content_block_delta" && j.delta?.type === "text_delta") {
938
+ const t = j.delta?.text;
939
+ if (typeof t === "string" && t.length > 0) tokens++;
940
+ }
941
+ } catch {}
942
+ }
943
+ }
944
+
945
+ (async () => {
946
+ const reader = body.getReader();
947
+ const decoder = new TextDecoder();
948
+ try {
949
+ while (true) {
950
+ const { done, value } = await reader.read();
951
+ if (done) break;
952
+ if (firstChunkAt === 0) firstChunkAt = Date.now();
953
+ if (dumpOn && value) {
954
+ totalBytes += value.byteLength;
955
+ if (firstBytesSample.length < 4096) {
956
+ firstBytesSample += decoder.decode(value.slice(0, 4096 - firstBytesSample.length), { stream: true });
957
+ }
958
+ }
959
+ if (!compressed) {
960
+ sseBuffer += decoder.decode(value, { stream: true });
961
+ const idx = sseBuffer.lastIndexOf("\n");
962
+ if (idx >= 0) {
963
+ parseSse(sseBuffer.slice(0, idx));
964
+ sseBuffer = sseBuffer.slice(idx + 1);
965
+ }
966
+ }
967
+ }
968
+ if (!compressed && sseBuffer) parseSse(sseBuffer);
969
+ } catch {}
970
+ const endAt = Date.now();
971
+ const ttfbMs = (firstChunkAt > 0 ? firstChunkAt : endAt) - requestSentAt;
972
+ const totalMs = endAt - requestSentAt;
973
+ const avgTps = tokens > 0 && totalMs > 0 ? tokens / (totalMs / 1000) : 0;
974
+ printRow(reqId, format, meta, status, requestSentAt, requestSentAt + ttfbMs, tokens, avgTps, endAt);
975
+ if (dumpOn) {
976
+ dumpPhase(reqId, "upstream_stream_summary", {
977
+ status,
978
+ contentEncoding,
979
+ compressed,
980
+ totalBytes,
981
+ tokensObserved: tokens,
982
+ ttfbMs,
983
+ totalMs,
984
+ firstBytesSample: firstBytesSample.length > 0 ? firstBytesSample.slice(0, 4096) : "(empty stream)",
985
+ });
986
+ }
987
+ })().catch(() => {});
988
+ }
src/proxy/identity.ts ADDED
@@ -0,0 +1,195 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Identity header builders — emit the ZCode desktop client's companion
3
+ * headers so the proxy is indistinguishable from the official client at the
4
+ * fingerprinting layer.
5
+ *
6
+ * TWO distinct bundle functions are mirrored (ZCode 3.11.2, `_reverse/zcode.cjs`):
7
+ *
8
+ * 1. `csn` = buildCliZCodeSourceHeaders (CLI LLM path, wrapped by `x4i`
9
+ * which appends `X-ZCode-Agent: "glm"` as the LAST header) — used for
10
+ * every LLM completion request → {@link buildLlmIdentityHeaders}.
11
+ * Shape: HTTP-Referer, User-Agent, [X-ZCode-App-Version], X-Title,
12
+ * X-Release-Channel (always), X-Client-Language (always, "unknown"
13
+ * fallback), X-Client-Timezone (always, "unknown" fallback),
14
+ * [X-Platform], X-Os-Category (when platform resolves), [X-Os-Version],
15
+ * X-ZCode-Agent ("glm", last). NO X-Device-Mid — the CLI LLM path never
16
+ * carried it.
17
+ *
18
+ * 2. `HRt` = buildZCodeSourceHeadersFromContext (host-side control-plane
19
+ * fetches: endpoint-routing configs, signing gate, claim/billing) —
20
+ * used by {@link buildIdentityHeaders}. Shape keeps the historical
21
+ * `pio`-derived order with conditional language/timezone and the
22
+ * optional X-Device-Mid (server-required on the claim/billing plane
23
+ * since the 0828 campaign). Consumers: endpoint-routing.ts,
24
+ * client-signing.ts, claim/client.ts, routes-quota.ts, async bridge.
25
+ *
26
+ * Both gate header values through the bundle's `fio` printable-ASCII rule;
27
+ * `n = fio(...)` validates appVersion and, when it fails, drops
28
+ * X-ZCode-App-Version entirely and falls the User-Agent back to
29
+ * `ZCode/unknown`.
30
+ *
31
+ * Runtime values are read via env overrides (matching the existing
32
+ * ZCODE_IDENTITY_PLATFORM/ARCH/RELEASE pattern) so the Android entry can emit
33
+ * desktop-Linux identity without changing this module:
34
+ * - ZCODE_IDENTITY_RELEASE_CHANNEL
35
+ * - ZCODE_IDENTITY_CLIENT_LANGUAGE (default: Intl locale, e.g. "zh-CN")
36
+ * - ZCODE_IDENTITY_CLIENT_TIMEZONE (default: Intl timezone, e.g. "Asia/Shanghai")
37
+ * - ZCODE_IDENTITY_DEVICE_MID (no default; omitted unless set)
38
+ *
39
+ * @see _reverse/NOTEPAD.md "How Credential is Used for LLM Calls"
40
+ */
41
+ import os from "node:os";
42
+ import type { ProxyIdentity } from "../config/types.js";
43
+
44
+ /** Printable-ASCII gate copied from the ZCode bundle's `fio` helper. */
45
+ const ASCII_PRINTABLE = /^[\x20-\x7e]+$/;
46
+
47
+ /** Resolve the appVersion the way `fio` does: trimmed + printable ASCII, else undefined. */
48
+ function resolveAppVersion(raw: string | undefined): string | undefined {
49
+ if (typeof raw !== "string") return undefined;
50
+ const v = raw.trim();
51
+ return v.length > 0 && ASCII_PRINTABLE.test(v) ? v : undefined;
52
+ }
53
+
54
+ /** Normalize a header value: trimmed + printable ASCII, else undefined. */
55
+ export function normalizePrintableHeaderValue(raw: string | undefined): string | undefined {
56
+ if (typeof raw !== "string") return undefined;
57
+ const v = raw.trim();
58
+ return v.length > 0 && ASCII_PRINTABLE.test(v) ? v : undefined;
59
+ }
60
+
61
+ function normalizeOsCategory(platform: NodeJS.Platform): string {
62
+ switch (platform) {
63
+ case "darwin":
64
+ return "macos";
65
+ case "win32":
66
+ return "windows";
67
+ default:
68
+ return "linux";
69
+ }
70
+ }
71
+
72
+ /** Mirrors the bundle's `lsa()` / `V8i()`: Intl locale, wrapped in try/catch. */
73
+ function resolveClientLanguage(): string | undefined {
74
+ const override = normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_CLIENT_LANGUAGE);
75
+ if (override) return override;
76
+ try {
77
+ return Intl.DateTimeFormat().resolvedOptions().locale || undefined;
78
+ } catch {
79
+ return undefined;
80
+ }
81
+ }
82
+
83
+ /** Mirrors the bundle's `csa()`: Intl timezone, wrapped in try/catch. */
84
+ function resolveClientTimezone(): string | undefined {
85
+ const override = normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_CLIENT_TIMEZONE);
86
+ if (override) return override;
87
+ try {
88
+ return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
89
+ } catch {
90
+ return undefined;
91
+ }
92
+ }
93
+
94
+ interface ResolvedIdentityValues {
95
+ n?: string;
96
+ platform?: string;
97
+ platformForCategory: NodeJS.Platform;
98
+ arch?: string;
99
+ release?: string;
100
+ releaseChannel: string;
101
+ clientLanguage?: string;
102
+ clientTimezone?: string;
103
+ deviceMid?: string;
104
+ }
105
+
106
+ /** Shared env/config resolution for both builders (values only — ordering differs per builder). */
107
+ function resolveIdentityValues(id: ProxyIdentity): ResolvedIdentityValues {
108
+ // Env overrides (ZCODE_IDENTITY_PLATFORM/ARCH/RELEASE) let the Android entry
109
+ // emit desktop-Linux identity headers without changing this module.
110
+ return {
111
+ n: resolveAppVersion(id.appVersion),
112
+ platform: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_PLATFORM ?? process.platform),
113
+ platformForCategory: (process.env.ZCODE_IDENTITY_PLATFORM ?? process.platform) as NodeJS.Platform,
114
+ arch: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_ARCH ?? os.arch()),
115
+ release: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_RELEASE ?? os.release()),
116
+ // bundle IL(): ZCODE_ENV==="test" ? "test" : "production" — always resolves.
117
+ // Mirror that default; ZCODE_IDENTITY_RELEASE_CHANNEL stays an explicit override.
118
+ releaseChannel: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_RELEASE_CHANNEL)
119
+ ?? (process.env.ZCODE_ENV?.trim().toLowerCase() === "test" ? "test" : "production"),
120
+ clientLanguage: resolveClientLanguage(),
121
+ clientTimezone: resolveClientTimezone(),
122
+ // env (Android NodeRunner injection) wins over the config.yaml value (desktop
123
+ // persistence) — both are UUIDv4 generated once and reused forever.
124
+ deviceMid: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_DEVICE_MID)
125
+ ?? normalizePrintableHeaderValue(id.deviceMid),
126
+ };
127
+ }
128
+
129
+ /**
130
+ * Identity headers for LLM completion requests — mirrors the bundle's CLI
131
+ * source-headers builder `csn` (buildCliZCodeSourceHeaders) + the `x4i`
132
+ * wrapper that appends `X-ZCode-Agent: "glm"` LAST. Differences vs the
133
+ * control-plane set (buildIdentityHeaders): language/timezone are ALWAYS
134
+ * emitted (falling back to "unknown"), X-Release-Channel sits right after
135
+ * X-Title, X-ZCode-Agent is the final header, and X-Device-Mid is NEVER sent.
136
+ * Pure function.
137
+ */
138
+ export function buildLlmIdentityHeaders(id: ProxyIdentity): Record<string, string> {
139
+ const v = resolveIdentityValues(id);
140
+ return {
141
+ "HTTP-Referer": id.refererOrigin,
142
+ "User-Agent": `ZCode/${v.n ?? "unknown"}`,
143
+ ...(v.n ? { "X-ZCode-App-Version": v.n } : {}),
144
+ "X-Title": `Z Code@${id.sourceTitle}`,
145
+ "X-Release-Channel": v.releaseChannel,
146
+ "X-Client-Language": v.clientLanguage ?? "unknown",
147
+ "X-Client-Timezone": v.clientTimezone ?? "unknown",
148
+ ...(v.platform && v.arch ? { "X-Platform": `${v.platform}-${v.arch}` } : {}),
149
+ ...(v.platform ? { "X-Os-Category": normalizeOsCategory(v.platformForCategory) } : {}),
150
+ ...(v.release ? { "X-Os-Version": v.release } : {}),
151
+ "X-ZCode-Agent": "glm",
152
+ };
153
+ }
154
+
155
+ /**
156
+ * Control-plane identity headers — mirrors the host-side bundle builder
157
+ * `HRt` (buildZCodeSourceHeadersFromContext), reached us via the historical
158
+ * `pio` shape. Used by endpoint-routing, client-signing gate, claim/billing
159
+ * and the async bridge — NOT for LLM completion requests (use
160
+ * {@link buildLlmIdentityHeaders} there).
161
+ *
162
+ * Order (with X-ZCode-Agent kept between X-Title and X-Platform):
163
+ * HTTP-Referer, User-Agent, [X-ZCode-App-Version], X-Title, X-ZCode-Agent,
164
+ * [X-Platform], [X-Release-Channel], [X-Client-Language], [X-Client-Timezone],
165
+ * [X-Os-Category], [X-Os-Version], [X-Device-Mid]
166
+ *
167
+ * Returns `Record<string, string>` rather than a fixed interface because
168
+ * several headers are conditionally omitted.
169
+ */
170
+ export function buildIdentityHeaders(id: ProxyIdentity): Record<string, string> {
171
+ const v = resolveIdentityValues(id);
172
+ return {
173
+ "HTTP-Referer": id.refererOrigin,
174
+ "User-Agent": `ZCode/${v.n ?? "unknown"}`,
175
+ ...(v.n ? { "X-ZCode-App-Version": v.n } : {}),
176
+ "X-Title": `Z Code@${id.sourceTitle}`,
177
+ "X-ZCode-Agent": "glm",
178
+ ...(v.platform && v.arch ? { "X-Platform": `${v.platform}-${v.arch}` } : {}),
179
+ ...(v.releaseChannel ? { "X-Release-Channel": v.releaseChannel } : {}),
180
+ ...(v.clientLanguage ? { "X-Client-Language": v.clientLanguage } : {}),
181
+ ...(v.clientTimezone ? { "X-Client-Timezone": v.clientTimezone } : {}),
182
+ ...(v.platform ? { "X-Os-Category": normalizeOsCategory(v.platformForCategory) } : {}),
183
+ ...(v.release ? { "X-Os-Version": v.release } : {}),
184
+ ...(v.deviceMid ? { "X-Device-Mid": v.deviceMid } : {}),
185
+ };
186
+ }
187
+
188
+ /**
189
+ * Cache key for process-wide singletons that embed a `ProxyIdentity`
190
+ * (endpoint routing, client signing): two configs producing the same key can
191
+ * share the same service instance.
192
+ */
193
+ export function identityCacheKey(identity: ProxyIdentity): string {
194
+ return JSON.stringify([identity.appVersion, identity.sourceTitle, identity.refererOrigin, identity.deviceMid ?? ""]);
195
+ }
src/proxy/inflate.ts ADDED
@@ -0,0 +1,53 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Shared bounded gzip inflation for request bodies (audit CL-17).
3
+ *
4
+ * Two call sites used to carry byte-for-byte copies of this
5
+ * DecompressionStream+reader+cancel loop (proxy/handler.ts and
6
+ * async/handler.ts); fixes to one never reached the other. The callers keep
7
+ * their own limits and error contracts — this helper only performs the
8
+ * bounded inflation and reports the outcome.
9
+ */
10
+
11
+ export type InflateResult =
12
+ | { ok: true; bytes: Uint8Array }
13
+ | { ok: false; reason: "too_large" }
14
+ | { ok: false; reason: "corrupt"; detail: string };
15
+
16
+ /**
17
+ * Inflate `bytes` as gzip, reading at most `limitBytes` of DECOMPRESSED
18
+ * output. The stream is cancelled and the reader lock released as soon as
19
+ * the limit trips (a small wire payload cannot expand into unbounded
20
+ * memory), and on any decode error.
21
+ *
22
+ * `too_large` carries no detail by design — callers embed their own limit in
23
+ * the user-facing message.
24
+ */
25
+ export async function inflateWithCap(bytes: Uint8Array, limitBytes: number): Promise<InflateResult> {
26
+ const gunzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
27
+ const source = new ReadableStream<Uint8Array>({
28
+ start(controller) {
29
+ controller.enqueue(bytes);
30
+ controller.close();
31
+ },
32
+ });
33
+ const reader = source.pipeThrough(gunzip).getReader();
34
+ const parts: Uint8Array[] = [];
35
+ let total = 0;
36
+ try {
37
+ for (;;) {
38
+ const { done, value } = await reader.read();
39
+ if (done) break;
40
+ total += value.byteLength;
41
+ if (total > limitBytes) {
42
+ await reader.cancel().catch(() => {});
43
+ return { ok: false, reason: "too_large" };
44
+ }
45
+ parts.push(value);
46
+ }
47
+ return { ok: true, bytes: Buffer.concat(parts) };
48
+ } catch (err) {
49
+ return { ok: false, reason: "corrupt", detail: (err as Error).message };
50
+ } finally {
51
+ reader.releaseLock?.();
52
+ }
53
+ }
src/proxy/ordered-transport.ts ADDED
@@ -0,0 +1,297 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import { connect as connectTcp, type Socket } from "node:net";
2
+ import { connect as connectTls, type TLSSocket } from "node:tls";
3
+
4
+ export type OrderedHeaderPair = [string, string];
5
+
6
+ export interface OrderedUpstreamRequest {
7
+ url: string;
8
+ method?: string;
9
+ headers: OrderedHeaderPair[];
10
+ body?: string | Uint8Array;
11
+ decompress?: boolean;
12
+ /** Client abort signal — destroys the socket the moment the client aborts. */
13
+ signal?: AbortSignal;
14
+ }
15
+
16
+ type WireSocket = Socket | TLSSocket;
17
+
18
+ const CRLF = "\r\n";
19
+ const HEADER_END = new Uint8Array([13, 10, 13, 10]);
20
+ const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
21
+
22
+ export async function sendOrderedUpstreamRequest(req: OrderedUpstreamRequest): Promise<Response> {
23
+ const url = new URL(req.url);
24
+ const bodyBytes = bodyToBytes(req.body);
25
+ const requestHead = buildRequestHead(url, req.method ?? "POST", req.headers, bodyBytes.byteLength);
26
+ const socket = await openSocket(url);
27
+
28
+ return await new Promise<Response>((resolve, reject) => {
29
+ let headerBuffer: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
30
+ let responseStarted = false;
31
+ let postWrite = false;
32
+ let bodyController: ReadableStreamDefaultController<Uint8Array> | null = null;
33
+ let chunkedDecoder: ChunkedDecoder | null = null;
34
+ let remainingContentLength: number | null = null;
35
+
36
+ const bodyStream = new ReadableStream<Uint8Array>({
37
+ start(controller) {
38
+ bodyController = controller;
39
+ },
40
+ cancel() {
41
+ socket.destroy();
42
+ },
43
+ });
44
+
45
+ function fail(err: unknown): void {
46
+ if (!responseStarted && postWrite) {
47
+ // Review follow-up #2 (PR #34): the full request (head + body) was
48
+ // already written to the wire, so the upstream may have processed it
49
+ // — resending could duplicate the LLM call and consume quota twice.
50
+ // Flag it so the connect-retry loop in handler.ts skips this error.
51
+ try { (err as { postWrite?: boolean }).postWrite = true; } catch {}
52
+ }
53
+ if (responseStarted) {
54
+ // Safe by spec: error() on an already-closed/errored ReadableStream
55
+ // controller is a NO-OP under WHATWG Streams semantics (only close()
56
+ // and enqueue() throw on a closed controller) — verified against both
57
+ // Bun and Node. The unguarded call below is intentional; do not wrap
58
+ // it (audit CL-01: triple-verified non-issue, closed).
59
+ bodyController?.error(err);
60
+ } else {
61
+ reject(err);
62
+ }
63
+ socket.destroy();
64
+ }
65
+
66
+ // Abort propagation (CL-04): destroy the socket the moment the client
67
+ // aborts. Without this the upstream LLM call kept running (consuming
68
+ // quota for the whole generation) after the client disappeared during a
69
+ // long-TTFB reasoning request. `fail()` both rejects this promise (a bare
70
+ // destroy() emits "close", not "error"/"end", and would leave it pending
71
+ // forever) and errors the consumer-side body stream when the response has
72
+ // already started. The resulting error carries `postWrite` (the request
73
+ // is fully on the wire by then), so handler's connect-retry ladder skips
74
+ // it — combined with the `clientReq.signal.aborted` pre-check there,
75
+ // client aborts never enter the retry loop.
76
+ if (req.signal) {
77
+ const signal = req.signal;
78
+ const onAbort = (): void => {
79
+ fail(new Error("client aborted during ordered upstream request"));
80
+ };
81
+ if (signal.aborted) {
82
+ onAbort();
83
+ return;
84
+ }
85
+ signal.addEventListener("abort", onAbort, { once: true });
86
+ // De-register when the socket settles so a signal that outlives this
87
+ // request (the handler reuses the client signal across connect
88
+ // attempts) does not accumulate listeners.
89
+ socket.once("close", () => signal.removeEventListener("abort", onAbort));
90
+ }
91
+
92
+ function finish(): void {
93
+ if (chunkedDecoder && !chunkedDecoder.done) {
94
+ try { bodyController?.error(new Error("upstream chunked body truncated")); } catch {}
95
+ socket.destroy();
96
+ return;
97
+ }
98
+ try { bodyController?.close(); } catch {}
99
+ }
100
+
101
+ function pushBody(bytes: Uint8Array): void {
102
+ if (!bodyController || bytes.byteLength === 0) return;
103
+ if (chunkedDecoder) {
104
+ chunkedDecoder.push(bytes, bodyController);
105
+ if (chunkedDecoder.done) finish();
106
+ return;
107
+ }
108
+ if (remainingContentLength !== null) {
109
+ const next = bytes.slice(0, remainingContentLength);
110
+ remainingContentLength -= next.byteLength;
111
+ if (next.byteLength > 0) bodyController.enqueue(next);
112
+ if (remainingContentLength === 0) finish();
113
+ return;
114
+ }
115
+ bodyController.enqueue(bytes);
116
+ }
117
+
118
+ socket.on("data", (chunk: Buffer) => {
119
+ try {
120
+ const bytes = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
121
+ if (!responseStarted) {
122
+ headerBuffer = concatBytes(headerBuffer, bytes);
123
+ const headerEnd = indexOfBytes(headerBuffer, HEADER_END);
124
+ if (headerEnd < 0) return;
125
+
126
+ const headerBytes = headerBuffer.slice(0, headerEnd);
127
+ const rest = headerBuffer.slice(headerEnd + HEADER_END.byteLength);
128
+ const parsed = parseResponseHeaders(headerBytes);
129
+ responseStarted = true;
130
+
131
+ const transferEncoding = parsed.headers.get("transfer-encoding")?.toLowerCase() ?? "";
132
+ if (transferEncoding.split(",").map((s) => s.trim()).includes("chunked")) {
133
+ parsed.headers.delete("transfer-encoding");
134
+ chunkedDecoder = new ChunkedDecoder();
135
+ } else {
136
+ const contentLength = parsed.headers.get("content-length");
137
+ remainingContentLength = contentLength ? Number.parseInt(contentLength, 10) : null;
138
+ if (!Number.isFinite(remainingContentLength as number)) remainingContentLength = null;
139
+ }
140
+
141
+ let responseBody: ReadableStream<Uint8Array> = bodyStream;
142
+ if (req.decompress && parsed.headers.get("content-encoding")?.toLowerCase() === "gzip") {
143
+ parsed.headers.delete("content-encoding");
144
+ parsed.headers.delete("content-length");
145
+ const gzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair<Uint8Array, Uint8Array>;
146
+ responseBody = bodyStream.pipeThrough(gzip);
147
+ }
148
+
149
+ resolve(new Response(responseBody, {
150
+ status: parsed.status,
151
+ statusText: parsed.statusText,
152
+ headers: parsed.headers,
153
+ }));
154
+ pushBody(rest);
155
+ return;
156
+ }
157
+ pushBody(bytes);
158
+ } catch (err) {
159
+ fail(err);
160
+ }
161
+ });
162
+
163
+ socket.once("error", fail);
164
+ socket.once("end", () => {
165
+ if (!responseStarted) {
166
+ reject(new Error("upstream closed before sending response headers"));
167
+ return;
168
+ }
169
+ finish();
170
+ });
171
+
172
+ socket.write(requestHead);
173
+ if (bodyBytes.byteLength > 0) socket.write(bodyBytes);
174
+ postWrite = true;
175
+ });
176
+ }
177
+
178
+ function openSocket(url: URL): Promise<WireSocket> {
179
+ const isHttps = url.protocol === "https:";
180
+ if (!isHttps && url.protocol !== "http:") {
181
+ return Promise.reject(new Error(`Unsupported upstream protocol: ${url.protocol}`));
182
+ }
183
+ const port = Number(url.port || (isHttps ? 443 : 80));
184
+
185
+ return new Promise((resolve, reject) => {
186
+ const onConnect = () => {
187
+ socket.off("error", reject);
188
+ resolve(socket);
189
+ };
190
+ const socket: WireSocket = isHttps
191
+ ? connectTls({ host: url.hostname, port, servername: url.hostname }, onConnect)
192
+ : connectTcp({ host: url.hostname, port }, onConnect);
193
+ socket.once("error", reject);
194
+ });
195
+ }
196
+
197
+ function buildRequestHead(url: URL, method: string, headers: OrderedHeaderPair[], contentLength: number): string {
198
+ const path = `${url.pathname || "/"}${url.search}`;
199
+ const lines = [
200
+ `${method} ${path} HTTP/1.1`,
201
+ `Host: ${url.host}`,
202
+ ...headers.map(headerLine),
203
+ `Content-Length: ${contentLength}`,
204
+ "Connection: close",
205
+ "",
206
+ "",
207
+ ];
208
+ return lines.join(CRLF);
209
+ }
210
+
211
+ function headerLine([name, value]: OrderedHeaderPair): string {
212
+ if (!HEADER_NAME.test(name)) throw new Error(`Invalid upstream header name: ${name}`);
213
+ if (/[\r\n]/.test(value)) throw new Error(`Invalid upstream header value for ${name}`);
214
+ return `${name}: ${value}`;
215
+ }
216
+
217
+ function bodyToBytes(body: string | Uint8Array | undefined): Uint8Array {
218
+ if (body === undefined) return new Uint8Array(0);
219
+ if (typeof body === "string") return new TextEncoder().encode(body);
220
+ return body;
221
+ }
222
+
223
+ function parseResponseHeaders(bytes: Uint8Array): { status: number; statusText: string; headers: Headers } {
224
+ const text = new TextDecoder("latin1").decode(bytes);
225
+ const lines = text.split(CRLF);
226
+ const statusLine = lines.shift() ?? "";
227
+ const match = /^HTTP\/\d(?:\.\d)?\s+(\d{3})(?:\s+(.*))?$/.exec(statusLine);
228
+ if (!match) throw new Error(`Invalid upstream status line: ${statusLine}`);
229
+
230
+ const headers = new Headers();
231
+ for (const line of lines) {
232
+ if (!line) continue;
233
+ const idx = line.indexOf(":");
234
+ if (idx <= 0) continue;
235
+ headers.append(line.slice(0, idx), line.slice(idx + 1).trimStart());
236
+ }
237
+
238
+ return { status: Number(match[1]), statusText: match[2] ?? "", headers };
239
+ }
240
+
241
+ class ChunkedDecoder {
242
+ private buffer: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
243
+ private expectedSize: number | null = null;
244
+ done = false;
245
+
246
+ push(bytes: Uint8Array, controller: ReadableStreamDefaultController<Uint8Array>): void {
247
+ if (this.done) return;
248
+ this.buffer = concatBytes(this.buffer, bytes);
249
+
250
+ while (!this.done) {
251
+ if (this.expectedSize === null) {
252
+ const lineEnd = indexOfCrlf(this.buffer);
253
+ if (lineEnd < 0) return;
254
+ const line = new TextDecoder("latin1").decode(this.buffer.slice(0, lineEnd));
255
+ const sizeHex = line.split(";", 1)[0].trim();
256
+ const size = Number.parseInt(sizeHex, 16);
257
+ if (!Number.isFinite(size)) throw new Error(`Invalid chunk size: ${line}`);
258
+ this.buffer = this.buffer.slice(lineEnd + 2);
259
+ this.expectedSize = size;
260
+ if (size === 0) {
261
+ this.done = true;
262
+ return;
263
+ }
264
+ }
265
+
266
+ if (this.buffer.byteLength < this.expectedSize + 2) return;
267
+ const chunk = this.buffer.slice(0, this.expectedSize);
268
+ controller.enqueue(chunk);
269
+ this.buffer = this.buffer.slice(this.expectedSize + 2);
270
+ this.expectedSize = null;
271
+ }
272
+ }
273
+ }
274
+
275
+ function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
276
+ const out = new Uint8Array(a.byteLength + b.byteLength);
277
+ if (a.byteLength > 0) out.set(a, 0);
278
+ if (b.byteLength > 0) out.set(b, a.byteLength);
279
+ return out;
280
+ }
281
+
282
+ function indexOfBytes(haystack: Uint8Array, needle: Uint8Array): number {
283
+ outer: for (let i = 0; i <= haystack.byteLength - needle.byteLength; i++) {
284
+ for (let j = 0; j < needle.byteLength; j++) {
285
+ if (haystack[i + j] !== needle[j]) continue outer;
286
+ }
287
+ return i;
288
+ }
289
+ return -1;
290
+ }
291
+
292
+ function indexOfCrlf(bytes: Uint8Array): number {
293
+ for (let i = 0; i < bytes.byteLength - 1; i++) {
294
+ if (bytes[i] === 13 && bytes[i + 1] === 10) return i;
295
+ }
296
+ return -1;
297
+ }
src/proxy/responses-handler.ts ADDED
@@ -0,0 +1,467 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * POST /v1/responses request handler.
3
+ *
4
+ * Pipeline:
5
+ * 1. Parse body + credential.
6
+ * 2. Resolve `previous_response_id` via `ResponseStore` (prepend stored history).
7
+ * 3. Translate Responses → Chat Completions (`responsesToChatCompletions`):
8
+ * - function / custom / namespace / tool_search tools → Chat tools.
9
+ * - web_search / web_search_preview / file_search / code_interpreter /
10
+ * computer_use / image_generation / mcp → stripped silently.
11
+ * 4. Apply the standard body transform (stream_options, user_id, start-plan system).
12
+ * 5. POST to the GLM Chat Completions upstream (reuse `buildUpstreamRequest`).
13
+ * 6. Translate the Chat response → Responses (`chatCompletionsToResponses`
14
+ * or `chatChunkToResponsesEvents` for streaming).
15
+ * 7. Store the new response under its id (unless `store:false`).
16
+ *
17
+ * State management: in-memory only (process restart clears the store); see
18
+ * `responses/store.ts`.
19
+ */
20
+ import { transformRequestBody } from "./body-transformer.js";
21
+ import { getProvider } from "../provider/providers.js";
22
+ import type { ProxyConfig } from "../config/types.js";
23
+ import type { AuthManager } from "../auth/manager.js";
24
+ import { buildUpstreamRequest, buildUpstreamHeaderPairs, type UpstreamHeaderPair } from "./upstream.js";
25
+ import { isCaptchaChallenged, retryOnCaptchaChallenge } from "./captcha-retry.js";
26
+ import { dispatchWithConnectRetry } from "./handler.js";
27
+ import type * as CaptchaExports from "./captcha.js";
28
+
29
+ // Lazy, runtime-gated module load (exception to the static-import rule, same
30
+ // as handler.ts): pulling captcha.ts eagerly drags in the happy-dom solver, so
31
+ // only start-plan — the one plan whose upstream is captcha-gated — pays for it.
32
+ type CaptchaModule = typeof CaptchaExports;
33
+ let captchaModule: CaptchaModule | null = null;
34
+ async function loadCaptcha(): Promise<CaptchaModule> {
35
+ if (!captchaModule) captchaModule = await import("./captcha.js");
36
+ return captchaModule;
37
+ }
38
+ import { getDefaultEndpointRouting, type EndpointRoutingService } from "./endpoint-routing.js";
39
+ import { getDefaultClientSigning, sendWithClientSigning, type ClientSigningManager } from "./client-signing.js";
40
+ import { credentialString } from "../auth/types.js";
41
+ import { translateRequestOpenAIToAnthropic, translateResponseAnthropicToOpenAI } from "../translator/openai-to-anthropic.js";
42
+ import { anthropicSseToOpenaiSse } from "../translator/sse-translator.js";
43
+ import type { AnthropicMessagesRequest, AnthropicMessagesResponse } from "../translator/types.js";
44
+ import type { ProviderDef } from "../provider/types.js";
45
+ import {
46
+ responsesToChatCompletions,
47
+ ToolTranslationError,
48
+ } from "../translator/responses-to-chat.js";
49
+ import {
50
+ chatCompletionsToResponses,
51
+ chatChunkToResponsesEvents,
52
+ finalizeResponsesStream,
53
+ newResponsesStreamState,
54
+ responsesEventToSse,
55
+ } from "../translator/chat-to-responses.js";
56
+ import {
57
+ generateResponsesId,
58
+ type ResponsesInputItem,
59
+ type ResponsesRequest,
60
+ type ResponsesResponse,
61
+ type ResponsesStreamEvent,
62
+ type ResponsesOutputItem,
63
+ } from "../translator/responses-types.js";
64
+ import { ResponseStore, type StoredResponse } from "../responses/store.js";
65
+ import { errorResponse, readBody, InflatedBodyTooLargeError } from "./handler.js";
66
+
67
+ export interface ResponsesHandlerOptions {
68
+ config: ProxyConfig;
69
+ auth: AuthManager;
70
+ /** Response store; if absent, `previous_response_id` always 404s. */
71
+ responseStore?: ResponseStore;
72
+ /** DI seam for tests. */
73
+ fetchImpl?: typeof fetch;
74
+ /** Verbose per-request diagnostics. */
75
+ debug?: boolean;
76
+ /** Override the process-wide endpoint routing service (for testing). `null` disables. */
77
+ endpointRouting?: EndpointRoutingService | null;
78
+ /** Override the process-wide client signing manager (for testing). `null` disables. */
79
+ clientSigning?: ClientSigningManager | null;
80
+ /** Override the lazily-imported captcha module (for testing). */
81
+ captcha?: CaptchaModule;
82
+ }
83
+
84
+ /** Handle POST /v1/responses. */
85
+ export async function handleResponses(
86
+ clientReq: Request,
87
+ opts: ResponsesHandlerOptions,
88
+ ): Promise<Response> {
89
+ const fetchImpl = opts.fetchImpl ?? fetch;
90
+ const debug = opts.debug === true;
91
+ const start = Date.now();
92
+
93
+ // ── 1. parse body ──
94
+ let rawBody: string;
95
+ try {
96
+ rawBody = (await readBody(clientReq)) ?? "";
97
+ } catch (err) {
98
+ if (err instanceof InflatedBodyTooLargeError) {
99
+ return errorResponse(413, "request_too_large", err.message);
100
+ }
101
+ return errorResponse(400, "invalid_request", `could not read request body: ${(err as Error).message}`);
102
+ }
103
+ let req: ResponsesRequest;
104
+ try {
105
+ req = JSON.parse(rawBody) as ResponsesRequest;
106
+ } catch (err) {
107
+ return errorResponse(400, "invalid_request", `request body is not valid JSON: ${(err as Error).message}`);
108
+ }
109
+ if (typeof req.input !== "string" && !Array.isArray(req.input)) {
110
+ return errorResponse(400, "invalid_request", "`input` must be a string or an array");
111
+ }
112
+ if (typeof req.model !== "string" || req.model.length === 0) {
113
+ return errorResponse(400, "invalid_request", "`model` is required");
114
+ }
115
+
116
+ const stream = req.stream === true;
117
+
118
+ // ── 2. resolve previous_response_id ──
119
+ let historyItems: ResponsesInputItem[] = [];
120
+ let prevId: string | undefined;
121
+ if (typeof req.previous_response_id === "string" && req.previous_response_id.length > 0) {
122
+ if (!opts.responseStore) {
123
+ return errorResponse(404, "response_store_disabled", "`previous_response_id` was supplied but the response store is not configured");
124
+ }
125
+ const prev = opts.responseStore.get(req.previous_response_id);
126
+ if (!prev) {
127
+ return errorResponse(404, "response_not_found", `previous_response_id ${req.previous_response_id} not found (response store is in-memory; entries are lost on restart and after the TTL)`);
128
+ }
129
+ prevId = req.previous_response_id;
130
+ historyItems = [...prev.input, ...outputItemsAsInputItems(prev.output)];
131
+ }
132
+
133
+ // ── 3. translate Responses → Chat Completions ──
134
+ const input: ResponsesInputItem[] = typeof req.input === "string"
135
+ ? [...historyItems, { type: "message", role: "user", content: req.input }]
136
+ : [...historyItems, ...req.input];
137
+ const reqWithHistory: ResponsesRequest = {
138
+ ...req,
139
+ input,
140
+ };
141
+ let translated;
142
+ try {
143
+ translated = responsesToChatCompletions(reqWithHistory);
144
+ } catch (err) {
145
+ if (err instanceof ToolTranslationError) {
146
+ return errorResponse(400, "tool_translation_error", err.message);
147
+ }
148
+ throw err;
149
+ }
150
+ const { chatRequest, customToolNames, namespaceMap, hasToolSearch } = translated;
151
+
152
+ // ── 4. credential + provider ──
153
+ let cred;
154
+ try {
155
+ cred = await opts.auth.getCredential();
156
+ } catch (err) {
157
+ return errorResponse(503, "credential_unavailable", (err as Error).message);
158
+ }
159
+ const providerDef = resolveProviderDef(opts.config);
160
+
161
+ // ── 5. body transform (start-plan system / anthropic cache_control + user_id) ──
162
+ // Both plans post Anthropic upstream (mirrors handler.ts): the start-plan
163
+ // OpenAI gateway was retired server-side (404 as of 2026-08-28), so the
164
+ // Responses → Chat → Anthropic translator chain runs unconditionally.
165
+ const startPlan = opts.config.plan === "start-plan";
166
+ const upstreamFormat: "openai" | "anthropic" = "anthropic";
167
+ let upstreamRequestBody: string;
168
+ {
169
+ let anthropicReq: AnthropicMessagesRequest;
170
+ try {
171
+ anthropicReq = translateRequestOpenAIToAnthropic(chatRequest);
172
+ } catch (err) {
173
+ return errorResponse(400, "translation_failed", `Chat→Anthropic translation failed: ${(err as Error).message}`);
174
+ }
175
+ // userId gating mirrors handler.ts: coding-plan injects the OAuth userId,
176
+ // start-plan omits it (internal consistency; the bundle is presence-gated
177
+ // with no plan concept — whether start-plan should carry it is not
178
+ // determinable from _reverse, kept aligned with the sibling path).
179
+ upstreamRequestBody = transformRequestBody(JSON.stringify(anthropicReq), {
180
+ format: "anthropic",
181
+ userId: startPlan ? undefined : cred.userId,
182
+ startPlan,
183
+ }) ?? JSON.stringify(anthropicReq);
184
+ }
185
+ const transformedBody = upstreamRequestBody;
186
+
187
+ // ── 6. POST upstream ──
188
+ // start-plan gates every upstream call behind an Aliyun captcha token. The
189
+ // Anthropic/OpenAI routes mint one in handler.ts; /v1/responses did not, so
190
+ // start-plan users got {"code":3007,"msg":"captcha verify failed"} surfaced
191
+ // as HTTP 400 upstream_error on every request.
192
+ let captchaHeaders: Record<string, string> | undefined;
193
+ if (startPlan) {
194
+ try {
195
+ const captcha = opts.captcha ?? (await loadCaptcha());
196
+ const token = await captcha.getCaptchaToken(opts.config.identity.appVersion);
197
+ captchaHeaders = { [captcha.RETRY_HEADERS.PARAM]: token.verifyParam, [captcha.RETRY_HEADERS.REGION]: token.region };
198
+ } catch {
199
+ // Fall through: the 3007 retry below solves on demand.
200
+ }
201
+ }
202
+ const upstreamHeaders = buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, opts.config.identity, opts.config.plan, captchaHeaders, undefined);
203
+ const upstreamReq = buildUpstreamRequest(clientReq, upstreamFormat, providerDef, cred, transformedBody, opts.config.identity, opts.config.plan, captchaHeaders, undefined);
204
+ if (debug) console.log(`[responses] → POST ${upstreamReq.url}`);
205
+
206
+ const routing = opts.endpointRouting !== undefined ? opts.endpointRouting : getDefaultEndpointRouting(opts.config);
207
+ const signer = opts.clientSigning !== undefined ? opts.clientSigning : getDefaultClientSigning(opts.config);
208
+ const dispatch = async (pairs: UpstreamHeaderPair[]): Promise<Response> => {
209
+ const routed = routing ? await routing.resolve(upstreamReq.url, credentialString(cred)) : null;
210
+ const sendUrl = routed?.routed ? routed.url : upstreamReq.url;
211
+ if (debug && routed?.routed) console.log(`[responses] endpoint routing: ${upstreamReq.url} -> ${sendUrl}`);
212
+ // signing decisions run against the PRE-routing provider URL (mirrors the
213
+ // client, whose signer wraps the routing transport)
214
+ return sendWithClientSigning(signer, {
215
+ url: upstreamReq.url,
216
+ headerPairs: pairs,
217
+ credential: credentialString(cred),
218
+ appVersion: opts.config.identity.appVersion,
219
+ debug: debug ? (message) => console.log(`[responses] ${message}`) : undefined,
220
+ send: (finalPairs) => {
221
+ const req = new Request(sendUrl, {
222
+ method: "POST",
223
+ headers: Object.fromEntries(finalPairs),
224
+ body: transformedBody ?? undefined,
225
+ });
226
+ return fetchImpl(req, { method: "POST", headers: Object.fromEntries(finalPairs), body: transformedBody ?? undefined, signal: clientReq.signal });
227
+ },
228
+ });
229
+ };
230
+
231
+ let upstreamResp: Response;
232
+ try {
233
+ // Connect-retry ladder mirrors the chat hot path (handler.ts): 3 attempts,
234
+ // fresh Request per dispatch (built inside `dispatch`), 500ms×attempt
235
+ // backoff, no retry once the client aborted.
236
+ upstreamResp = await dispatchWithConnectRetry(() => dispatch(upstreamHeaders), {
237
+ isAborted: () => clientReq.signal.aborted,
238
+ });
239
+ } catch (err) {
240
+ return errorResponse(502, "upstream_unreachable", (err as Error).message);
241
+ }
242
+
243
+ // Captcha challenge retry (mirrors handler.ts via the shared captcha-retry
244
+ // seam): the gateway signals it either through the captcha response header
245
+ // or as HTTP 400 with {"code":3007} in the body. The challenged token is
246
+ // already spent, so retry once with a fresh pooled one.
247
+ if (startPlan && !upstreamResp.ok) {
248
+ const captcha = opts.captcha ?? (await loadCaptcha());
249
+ if (await isCaptchaChallenged(upstreamResp, captcha)) {
250
+ if (debug) console.log("[responses] captcha challenge — re-solving and retrying once");
251
+ const outcome = await retryOnCaptchaChallenge({
252
+ captcha,
253
+ appVersion: opts.config.identity.appVersion,
254
+ challengedResp: upstreamResp,
255
+ debug: debug ? (message) => console.log(`[responses] ${message}`) : undefined,
256
+ solveAndRetry: (retryHeaders) => dispatch(
257
+ buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, opts.config.identity, opts.config.plan, retryHeaders, undefined),
258
+ ),
259
+ mapError: (err, phase) =>
260
+ phase === "solver"
261
+ ? errorResponse(503, "captcha_solver_failed", err.message)
262
+ : errorResponse(502, "upstream_unreachable", err.message),
263
+ });
264
+ if (!outcome.ok) return outcome.resp;
265
+ upstreamResp = outcome.resp;
266
+ }
267
+ }
268
+
269
+ if (!upstreamResp.ok) {
270
+ const errText = await upstreamResp.text().catch(() => "");
271
+ return errorResponse(upstreamResp.status, "upstream_error", errText.slice(0, 500) || `upstream returned ${upstreamResp.status}`);
272
+ }
273
+
274
+ if (upstreamFormat === "anthropic") {
275
+ // normalize the Anthropic upstream response into the OpenAI Chat shape the
276
+ // downstream Responses translators already consume (SSE + batch)
277
+ if (stream) {
278
+ if (!upstreamResp.body) {
279
+ return errorResponse(502, "translation_failed", "upstream returned no body for stream");
280
+ }
281
+ upstreamResp = new Response(anthropicSseToOpenaiSse(upstreamResp.body, req.model), {
282
+ status: upstreamResp.status,
283
+ headers: { "content-type": "text/event-stream" },
284
+ });
285
+ } else {
286
+ const rawAnthropic = await upstreamResp.text();
287
+ let parsedAnthropic: AnthropicMessagesResponse;
288
+ try {
289
+ parsedAnthropic = JSON.parse(rawAnthropic) as AnthropicMessagesResponse;
290
+ } catch (err) {
291
+ return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`);
292
+ }
293
+ const openaiResp = translateResponseAnthropicToOpenAI(parsedAnthropic, req.model);
294
+ upstreamResp = new Response(JSON.stringify(openaiResp), {
295
+ status: upstreamResp.status,
296
+ headers: { "content-type": "application/json" },
297
+ });
298
+ }
299
+ }
300
+
301
+ // ── 8. translate Chat → Responses ──
302
+ const responseId = generateResponsesId();
303
+ const meta = { customToolNames, namespaceMap, hasToolSearch };
304
+
305
+ if (stream) {
306
+ return streamResponse(upstreamResp, { responseId, model: req.model, meta, request: req, input, options: opts });
307
+ }
308
+
309
+ const rawChatResp = await upstreamResp.text();
310
+ let chatRespJson;
311
+ try {
312
+ chatRespJson = JSON.parse(rawChatResp);
313
+ } catch (err) {
314
+ return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`);
315
+ }
316
+ const responsesResp = chatCompletionsToResponses(chatRespJson, req.model, {
317
+ responseId,
318
+ meta,
319
+ ...(typeof req.instructions === "string" ? { instructions: req.instructions } : {}),
320
+ ...(prevId ? { previousResponseId: prevId } : {}),
321
+ });
322
+
323
+ // ── 9. store the response (unless `store:false`) ──
324
+ if (req.store !== false && opts.responseStore) {
325
+ const stored = buildStoredResponse(responsesResp, input, req.instructions);
326
+ opts.responseStore.set(stored);
327
+ }
328
+
329
+ if (debug) console.log(`[responses] ← ${responsesResp.status} (${Date.now() - start}ms)`);
330
+
331
+ return new Response(JSON.stringify(responsesResp), {
332
+ status: 200,
333
+ headers: { "content-type": "application/json" },
334
+ });
335
+ }
336
+
337
+ // ─────────────────────────────────────────────
338
+ // Streaming response
339
+ // ─────────────────────────────────────────────
340
+
341
+ interface StreamResponseContext {
342
+ responseId: string;
343
+ model: string;
344
+ meta: { customToolNames: Set<string>; namespaceMap: Map<string, { namespace: string; name: string }>; hasToolSearch: boolean };
345
+ request: ResponsesRequest;
346
+ input: ResponsesInputItem[];
347
+ options: ResponsesHandlerOptions;
348
+ }
349
+
350
+ function streamResponse(upstreamResp: Response, context: StreamResponseContext): Response {
351
+ if (!upstreamResp.body) {
352
+ return errorResponse(502, "translation_failed", "upstream returned no body for stream");
353
+ }
354
+ const state = newResponsesStreamState(context.model, { meta: context.meta, responseId: context.responseId });
355
+
356
+ const stream = new ReadableStream<Uint8Array>({
357
+ async start(controller) {
358
+ const encoder = new TextEncoder();
359
+ const send = (evt: ResponsesStreamEvent) => controller.enqueue(encoder.encode(responsesEventToSse(evt)));
360
+ try {
361
+ const reader = upstreamResp.body!.getReader();
362
+ const decoder = new TextDecoder();
363
+ let buffer = "";
364
+ let errored = false;
365
+ for (;;) {
366
+ if (errored) break;
367
+ const { done, value } = await reader.read();
368
+ if (done) break;
369
+ buffer += decoder.decode(value, { stream: true });
370
+ // SSE chunks are separated by `\n\n`; process complete frames.
371
+ let nl: number;
372
+ while ((nl = buffer.indexOf("\n\n")) >= 0) {
373
+ const frame = buffer.slice(0, nl);
374
+ buffer = buffer.slice(nl + 2);
375
+ const dataLine = extractSseData(frame);
376
+ if (!dataLine || dataLine === "[DONE]") continue;
377
+ try {
378
+ const chunk = JSON.parse(dataLine);
379
+ for (const evt of chatChunkToResponsesEvents(chunk, state)) send(evt);
380
+ } catch (err) {
381
+ errored = true;
382
+ // Release the upstream reader too — without the cancel the
383
+ // upstream connection lingers until GC. Fire-and-forget so a
384
+ // slow cancel never delays the client-visible error. The
385
+ // errored-flag + early-return semantics (anti-pattern #24) are
386
+ // unchanged: no further reads, no finalize, no close().
387
+ reader.cancel().catch(() => {});
388
+ controller.error(err);
389
+ return;
390
+ }
391
+ }
392
+ }
393
+ const finalEvents = finalizeResponsesStream(state);
394
+ for (const evt of finalEvents) send(evt);
395
+ const finalEvent = finalEvents.find((evt) => evt.type === "response.completed" || evt.type === "response.incomplete");
396
+ if (finalEvent && context.request.store !== false && context.options.responseStore) {
397
+ context.options.responseStore.set(buildStoredResponse(finalEvent.response, context.input, context.request.instructions));
398
+ }
399
+ try { controller.close(); } catch {}
400
+ } catch (err) {
401
+ try { controller.error(err); } catch {}
402
+ }
403
+ },
404
+ cancel(reason) {
405
+ context.options.debug === true && console.log(`[responses] stream cancelled: ${String(reason)}`);
406
+ try { upstreamResp.body?.cancel(); } catch {}
407
+ },
408
+ });
409
+
410
+ return new Response(stream, {
411
+ status: 200,
412
+ headers: {
413
+ "content-type": "text/event-stream",
414
+ "cache-control": "no-cache",
415
+ connection: "keep-alive",
416
+ },
417
+ });
418
+ }
419
+
420
+ function extractSseData(frame: string): string | null {
421
+ for (const line of frame.split(/\r?\n/)) {
422
+ if (line.startsWith("data:")) return line.slice(5).replace(/^\s/, "");
423
+ }
424
+ return null;
425
+ }
426
+
427
+ // ─────────────────────────────────────────────
428
+ // Helpers
429
+ // ─────────────────────────────────────────────
430
+
431
+ function resolveProviderDef(config: ProxyConfig): ProviderDef & { openaiBaseURL: string; anthropicBaseURL: string } {
432
+ const base = getProvider(config.provider);
433
+ const endpoints = config.providers[config.provider];
434
+ return {
435
+ ...base,
436
+ anthropicBaseURL: endpoints.anthropicBase,
437
+ openaiBaseURL: endpoints.openaiBase,
438
+ };
439
+ }
440
+
441
+ /**
442
+ * Cast stored output items back into input items so the next turn's history is
443
+ * a flat list the translator can walk. Responses output and input item shapes
444
+ * overlap enough that a structural cast is sound (the fields we read — `type`,
445
+ * `call_id`, `name`, `arguments`, `content`, `role` — are shared).
446
+ */
447
+ function outputItemsAsInputItems(outputs: ResponsesOutputItem[]): ResponsesInputItem[] {
448
+ return outputs as unknown as ResponsesInputItem[];
449
+ }
450
+
451
+ function buildStoredResponse(
452
+ resp: ResponsesResponse,
453
+ input: ResponsesInputItem[],
454
+ instructions: string | undefined,
455
+ ): StoredResponse {
456
+ return {
457
+ id: resp.id,
458
+ model: resp.model,
459
+ status: (resp.status === "completed" || resp.status === "incomplete" || resp.status === "failed" ? resp.status : "completed"),
460
+ input,
461
+ output: resp.output,
462
+ usage: resp.usage,
463
+ instructions,
464
+ createdAt: Date.now(),
465
+ lastAccessedAt: Date.now(),
466
+ };
467
+ }