diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000000000000000000000000000000000..792c4472ee80a40698f005883c9bafb057ea9613 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,18 @@ +# syntax=docker/dockerfile:1 + +FROM oven/bun:1-alpine AS deps +WORKDIR /app +COPY package.json bun.lock ./ +RUN bun install --frozen-lockfile + +FROM oven/bun:1-alpine +WORKDIR /app +COPY --from=deps /app/node_modules ./node_modules +COPY package.json tsconfig.json config.example.yaml ./ +COPY src ./src +RUN mkdir -p /data && chown bun:bun /data +ENV ZCODE_PROXY_PORT=8080 +ENV ZCODE_PROXY_CONFIG=/data/config.yaml +EXPOSE 8080 +USER bun +CMD ["bun", "run", "src/index.ts", "serve"] diff --git a/README.md b/README.md index 390e3b11d537fcc7cb74a2b32b34882ef72b5c06..fee09e5b2a9f3a5dee9824ac0439bd0a9c9cc03c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ --- -title: Zcode Api -emoji: ๐Ÿƒ -colorFrom: pink -colorTo: green +title: ZCode Proxy +emoji: ๐Ÿ”Œ +colorFrom: blue +colorTo: purple sdk: docker -pinned: false +app_port: 8080 --- -Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference +# ZCode Proxy + +Minimal Docker Space deployment of the upstream `TriDefender/zcode-api`. + +The upstream credential store must be provisioned before chat requests can work. diff --git a/bun.lock b/bun.lock new file mode 100644 index 0000000000000000000000000000000000000000..80e4072eca8427634b42f67d126e93d76b600ba1 --- /dev/null +++ b/bun.lock @@ -0,0 +1,99 @@ +{ + "lockfileVersion": 1, + "configVersion": 1, + "workspaces": { + "": { + "name": "zcode-proxy", + "dependencies": { + "happy-dom": "^20.11.6", + "undici": "^8.10.0", + "yaml": "^2.5.0", + }, + "devDependencies": { + "@types/bun": "latest", + "esbuild": "^0.28.1", + }, + }, + }, + "packages": { + "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.28.1", "", { "os": "aix", "cpu": "ppc64" }, "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ=="], + + "@esbuild/android-arm": ["@esbuild/android-arm@0.28.1", "", { "os": "android", "cpu": "arm" }, "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ=="], + + "@esbuild/android-arm64": ["@esbuild/android-arm64@0.28.1", "", { "os": "android", "cpu": "arm64" }, "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg=="], + + "@esbuild/android-x64": ["@esbuild/android-x64@0.28.1", "", { "os": "android", "cpu": "x64" }, "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng=="], + + "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.28.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q=="], + + "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.28.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ=="], + + "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.28.1", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw=="], + + "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.28.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ=="], + + "@esbuild/linux-arm": ["@esbuild/linux-arm@0.28.1", "", { "os": "linux", "cpu": "arm" }, "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ=="], + + "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.28.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g=="], + + "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.28.1", "", { "os": "linux", "cpu": "ia32" }, "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w=="], + + "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg=="], + + "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ=="], + + "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.28.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ=="], + + "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ=="], + + "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.28.1", "", { "os": "linux", "cpu": "s390x" }, "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag=="], + + "@esbuild/linux-x64": ["@esbuild/linux-x64@0.28.1", "", { "os": "linux", "cpu": "x64" }, "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA=="], + + "@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw=="], + + "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.28.1", "", { "os": "none", "cpu": "x64" }, "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg=="], + + "@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.28.1", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q=="], + + "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.28.1", "", { "os": "openbsd", "cpu": "x64" }, "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw=="], + + "@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg=="], + + "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.28.1", "", { "os": "sunos", "cpu": "x64" }, "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ=="], + + "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.28.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA=="], + + "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.28.1", "", { "os": "win32", "cpu": "ia32" }, "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg=="], + + "@esbuild/win32-x64": ["@esbuild/win32-x64@0.28.1", "", { "os": "win32", "cpu": "x64" }, "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A=="], + + "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="], + + "@types/node": ["@types/node@25.9.3", "", { "dependencies": { "undici-types": ">=7.24.0 <7.24.7" } }, "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg=="], + + "@types/whatwg-mimetype": ["@types/whatwg-mimetype@3.0.2", "", {}, "sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA=="], + + "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="], + + "buffer-image-size": ["buffer-image-size@0.6.4", "", { "dependencies": { "@types/node": "*" } }, "sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ=="], + + "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="], + + "entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="], + + "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=="], + + "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=="], + + "undici": ["undici@8.10.0", "", {}, "sha512-HvltHd7avK13QIw/oLe4qoOLyoVSoafqJ2jYOrtMRBkbYT31eiBQ8O0ehRKZiEZCMEyLFQNIADpgCWC5fALvYQ=="], + + "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="], + + "whatwg-mimetype": ["whatwg-mimetype@3.0.0", "", {}, "sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q=="], + + "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=="], + + "yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="], + } +} diff --git a/config.example.yaml b/config.example.yaml new file mode 100644 index 0000000000000000000000000000000000000000..996f776a1160f5608181f5c4191be0fd073b9cf9 --- /dev/null +++ b/config.example.yaml @@ -0,0 +1,185 @@ +server: + port: 8080 + host: "0.0.0.0" + +auth: + # Key that clients must provide to use the proxy. + # Set to null/omit to disable client auth. + proxyApiKey: "your-proxy-secret" + + # Upstream credentials come from the OAuth login flow โ€” run this first: + # bun run src/index.ts auth login + # Parsed but currently not honored โ€” the credential store path is fixed at + # ~/.zcode-proxy/credentials.json: + # oauthCredentialsPath: "~/.zcode-proxy/credentials.json" + +# Which upstream provider to use: "zai" or "bigmodel" +provider: zai + +# Which plan tier to use: +# "coding-plan" (default) โ€” direct upstream endpoints, permanent API key +# "start-plan" โ€” routes through zcode.z.ai with JWT auth (requires `auth login`) +plan: coding-plan + +providers: + zai: + anthropicBase: "https://api.z.ai/api/anthropic" + openaiBase: "https://api.z.ai/api/coding/paas/v4" + bigmodel: + anthropicBase: "https://open.bigmodel.cn/api/anthropic" + openaiBase: "https://open.bigmodel.cn/api/coding/paas/v4" + +defaultModel: glm-4.6 + +models: + - glm-4.5-air + - glm-4.6 + - glm-4.6v + - glm-4.7 + - glm-5 + - glm-5-turbo + - glm-5v-turbo + - glm-5.1 + - glm-5.2 + - glm-5.3 + - glm-5.3-flash + +# Configurable identity headers injected on every upstream request to mimic the +# ZCode desktop client (User-Agent, X-ZCode-App-Version, X-Title, +# X-ZCode-Agent, HTTP-Referer). Runtime platform headers (X-Platform, +# X-Os-Category, X-Os-Version) are detected dynamically and are not configured +# here. All fields below are optional; env vars override YAML, which overrides +# defaults. +identity: + # Mirrors process.env.ZCODE_APP_VERSION in the ZCode bundle. + # Must be printable ASCII; non-conforming values fall back to the default. + # Default: "3.11.2" (current ZCode release). Override to match your real client. + appVersion: "3.11.2" + # X-Title suffix โ†’ "Z Code@{sourceTitle}". Default "cli". + sourceTitle: "cli" + # HTTP-Referer URL. Default "https://zcode.z.ai". + refererOrigin: "https://zcode.z.ai" + # Device identity (X-Device-Mid) โ€” random UUIDv4, generated ONCE and reused + # forever (mirrors ZCode's telemetry deviceMid; no hardware values involved). + # Auto-generated into this file at first `auth login` or config creation. + # Leave empty on Android โ€” the app injects ZCODE_IDENTITY_DEVICE_MID instead. + deviceMid: "" + +# Local client-session inference for cache-affinity experiments. +# "observe" (default) logs inferred sessions in debug mode but does not change +# upstream x-session-id. "enforce" reuses a stable x-session-id for inferred +# coding-plan sessions. "off" disables inference entirely. +clientIdentity: + mode: observe + ttlSeconds: 900 + maxSessions: 1024 + +# Responses API (/v1/responses) โ€” Codex CLI / OpenAI Agents SDK endpoint. +# Translates Responses requests through Chat Completions to the Anthropic-format +# upstream (both plans post Anthropic upstream). +# State (previous_response_id) is held in-memory (cleared on restart, 24h TTL). +responses: + enabled: true + store: + maxEntries: 1000 + ttlMs: 86400000 + +# GLM MCP hosted-tool integration โ€” NOT currently wired into production. +# These keys are parsed but have no effect: hosted tools (`mcp`, +# `web_search_preview`, ...) are silently stripped by the Responses +# translator, and the MCP client subsystem (src/mcp) is retained for a +# future function-injection design. Endpoints are derived from `provider`: +# zai โ†’ https://api.z.ai/api/mcp/{tool}/mcp +# bigmodel โ†’ https://open.bigmodel.cn/api/mcp/{tool}/mcp +# Auth reuses the logged-in upstream credential โ€” no extra key needed. +mcp: + enabled: true + # (planned) Intercept `web_search`/`web_search_preview` hosted tools via + # GLM's `web_search_prime` MCP. + webSearch: true + # (planned) Inject `webReader` as a function tool the model can call directly. + webReader: false + # (planned) Inject the three `zread` tools (search_doc/get_repo_structure/read_file). + zread: false + +# Async (off-peak / "idle plan") bridge. +# When enabled, exposes POST /async/v1/messages and /async/v1/chat/completions +# that route through ZCode's off-peak ticket-queue backend โ€” free compute when +# the GLM cluster has idle capacity. The proxy holds the connection open with +# SSE keepalives during queue wait, forwards the LLM stream once a ticket is +# ready, and auto-retries on ticket-expired (up to maxRetries). +# +# IMPORTANT: off-peak needs the JWT captured by `auth login`. A credential +# without a JWT makes the route return 400 `async_credentials_unavailable`. +# Off-peak is a coding-plan feature: when `plan: start-plan`, the /async/* +# routes return 400 `async_plan_unsupported` even when enabled: true. +# +# Env overrides: ZCODE_ASYNC_ENABLED, ZCODE_ASYNC_ORIGIN, +# ZCODE_ASYNC_MAX_RETRIES, ZCODE_ASYNC_MAX_WAIT_MS. +async: + enabled: false + origin: "https://zcode.z.ai" + pollIntervalMs: 5000 + keepAliveIntervalMs: 3000 + # Maximum total wait for ticket to become ready, in ms. 0 = unlimited. + maxWaitMs: 0 + maxRetries: 3 + settleTimeoutMs: 8000 + controlTimeoutMs: 15000 + # Optional model override; empty uses the request's `model`. + defaultModel: "" + +# Manual claim ("weekend plan") โ€” mirrors the ZCode 3.10 desktop client's +# manualClaimPlan feature. When enabled, the proxy periodically lists claimable +# trial plans ({origin}/api/v1/zcode-plan/billing/preview) and auto-claims the +# highest-priority one ({origin}/api/v1/zcode-plan/billing/claim) using the +# OAuth JWT + an Aliyun captcha token (same solver as start-plan). Weekend +# campaigns are quota-limited first-come-first-served; claimed plans activate +# at the campaign's `starts_at` and land as Start-Plan quota. +# +# IMPORTANT: requires a logged-in credential (claim uses the JWT from +# `auth login`), and identity.appVersion must be >= the campaign's minimum +# client version (default 3.11.2) or the server rejects with `ineligible`. +# +# Env overrides: ZCODE_CLAIM_ENABLED, ZCODE_CLAIM_AUTO, ZCODE_CLAIM_ORIGIN, +# ZCODE_CLAIM_POLL_INTERVAL_MS. +claim: + # On by default: the scheduler polls the preview endpoint every 5 min and + # idles until a campaign goes live (404 preview = nothing to claim). + # `false` = CLI-only (`zcode-proxy claim [list|now]` still works). + enabled: true + # Auto-claim in the background while serving. `false` = CLI-only + # (`zcode-proxy claim` still works when `enabled: true`). + auto: true + origin: "https://zcode.z.ai" + # Preview poll cadence (5 min default). + pollIntervalMs: 300000 + # Backoff after failed attempts (10 min default); quota_exhausted / + # already_claimed back off to the server-provided next window instead. + cooldownMs: 600000 + # Optional: claim a specific plan_id. Empty = highest-priority preview. + planId: "" + +# Server-controlled upstream URL remapping (mirrors the ZCode client's +# ProviderEndpointRoutingService). The proxy periodically fetches +# {origin}/api/v1/agent/configs and rewrites matching upstream URLs per the +# returned proxyEndpoint.mapping table (currently the coding-plan Anthropic +# endpoints -> zcode.z.ai ultra endpoints). Fail-open: any fetch/parse error +# keeps the original URLs. Env override: ZCODE_ENDPOINT_ROUTING=false. +endpointRouting: + enabled: true + origin: "https://zcode.z.ai" + +# Client request signing V4 (mirrors the ZCode 3.9.1 ClientRequestSigningV4Signer). +# When enabled, the proxy probes {origin}/api/v1/agent/configs (cached 1h) and, +# only if the server sets data.codingPlanSignature.enable=true, signs coding-plan +# requests: handshake against {provider}/api/paas/c1f3a7e2/v2/client, Ed25519 +# signature + proof-of-work headers on every request, fail-open retry ladder +# (two 401 VERIFY rejections -> permanent unsigned bypass). Start-plan and +# off-peak paths are never signed. Env override: ZCODE_CLIENT_SIGNING=false. +clientSigning: + enabled: true + origin: "https://zcode.z.ai" + +logging: + level: info diff --git a/package.json b/package.json new file mode 100644 index 0000000000000000000000000000000000000000..06248a3a88b83c6a5e8dcc818218f0a3f8d362c4 --- /dev/null +++ b/package.json @@ -0,0 +1,26 @@ +{ + "name": "zcode-proxy", + "version": "4.6.3", + "type": "module", + "scripts": { + "dev": "bun run src/index.ts", + "start": "bun run src/index.ts", + "test": "bun test", + "build": "bun build --compile --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy.exe", + "build:linux-x64": "bun build --compile --target bun-linux-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-x64", + "build:linux-arm64": "bun build --compile --target bun-linux-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-arm64", + "build:darwin-x64": "bun build --compile --target bun-darwin-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-x64", + "build:darwin-arm64": "bun build --compile --target bun-darwin-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-arm64", + "build:android-bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/android/server.cjs --define:process.env.NODE_ENV=\\\"production\\\"", + "build:android-apk": "bash scripts/build-android-apk.sh" + }, + "dependencies": { + "happy-dom": "^20.11.6", + "undici": "^8.10.0", + "yaml": "^2.5.0" + }, + "devDependencies": { + "@types/bun": "latest", + "esbuild": "^0.28.1" + } +} diff --git a/src/android/control.ts b/src/android/control.ts new file mode 100644 index 0000000000000000000000000000000000000000..b0e6004ac2bf9d79905223cbac9201884e7ce7fb --- /dev/null +++ b/src/android/control.ts @@ -0,0 +1,389 @@ +/** + * Localhost-only HTTP control listener for the Android app's Kotlin shell. + * + * The Kotlin foreground service starts the Node.js proxy server and a small + * control listener on a separate port (passed via env `ZCODE_CONTROL_PORT`). + * The proxy listener serves `/v1/*`, `/webui`, `/health`; the control listener + * serves only `POST /control` and is bound to `127.0.0.1` so other devices on + * the LAN cannot reach it. Two layers enforce loopback-only access: + * + * 1. `server.listen(port, "127.0.0.1", ...)` โ€” never binds to `0.0.0.0`. + * 2. Per-request `req.socket.remoteAddress` check โ€” defends against a future + * bind regression where the listener accidentally widens. + * + * The listener exposes a JSON command protocol so Kotlin can drive OAuth + * (via embedded WebView), start/stop the proxy server, update runtime config + * (provider/plan), poll logs, and shut down the Node process. + */ +import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http"; +import type { ProviderId } from "../provider/types.js"; +import type { Credential } from "../auth/types.js"; +import { + ZaiOAuthClient, + BigmodelOAuthClient, + AuthCodeOAuthClient, + type OAuthFlowClient, +} from "../auth/oauth.js"; +import { KeyResolver } from "../auth/resolver.js"; +import { saveCredential, clearCredential, loadCredential } from "../auth/store.js"; + +/** Supported plan tiers. Mirrors `ProxyConfig.plan`. */ +export type PlanTier = "coding-plan" | "start-plan"; + +/** The control protocol: request shape for `POST /control`. */ +export type ControlCommand = + | { cmd: "status" } + | { cmd: "startOAuth"; provider: ProviderId } + | { cmd: "deliverOAuthCode"; provider: ProviderId; code: string; state: string } + | { cmd: "logout" } + | { cmd: "setConfig"; provider?: ProviderId; plan?: PlanTier } + | { cmd: "startProxy" } + | { cmd: "stopProxy" } + | { cmd: "getLogs"; since?: number } + | { cmd: "shutdown" }; + +/** Successful response envelope. */ +export type ControlOk = + | { ok: true; state: "running"; provider: ProviderId; plan: PlanTier; proxyPort: number; loggedIn: boolean } + | { ok: true; event: "oauthUrl"; authorizeUrl: string; callbackPort: number } + | { ok: true; event: "loginOk"; provider: ProviderId } + | { ok: true; event: "loggedOut" } + | { ok: true; event: "configUpdated"; provider: ProviderId; plan: PlanTier } + | { ok: true; event: "proxyStarted"; port: number } + | { ok: true; event: "proxyStopped" } + | { ok: true; event: "logs"; nextSince: number; lines: string[] } + | { ok: true; event: "shuttingDown" }; + +/** Failure response envelope. */ +export interface ControlError { + ok: false; + error: string; +} + +export type ControlResponse = ControlOk | ControlError; + +/** Result type returned by lifecycle hooks (start/stop proxy). */ +export type LifecycleResult = + | { ok: true; port: number } + | { ok: false; error: string }; + +/** Result type returned by `setConfig` hook. */ +export type ConfigUpdateResult = + | { ok: true; provider: ProviderId; plan: PlanTier } + | { ok: false; error: string }; + +/** Internal mutable state shared with the proxy entry. */ +export interface ControlState { + provider: ProviderId; + plan: PlanTier; + /** Currently-bound proxy server port. 0 when proxy is stopped. */ + proxyPort: number; + /** Active OAuth client while a flow is in flight; nulled on completion. */ + activeOauth?: { + client: OAuthFlowClient; + callbackUrl: string; + state: string; + }; +} + +interface StartControlOpts { + port: number; + state: ControlState; + /** Start the proxy server. Returns the bound port on success. */ + onStartProxy?: () => Promise; + /** Stop the proxy server. */ + onStopProxy?: () => Promise<{ ok: true } | { ok: false; error: string }>; + /** Update runtime config (provider and/or plan). */ + onSetConfig?: (changes: { provider?: ProviderId; plan?: PlanTier }) => Promise; + /** Hook for graceful shutdown (called by the `shutdown` command). */ + onShutdown?: () => Promise | void; + /** Log buffer polled by `getLogs`. If omitted, an internal one is used. */ + logBuffer?: LogBuffer; +} + +/** Bounded ring buffer for runtime log lines with monotonic sequence numbers. */ +export class LogBuffer { + private readonly lines: string[] = []; + private readonly capacity: number; + private nextSeq = 0; + + constructor(capacity = 500) { + this.capacity = capacity; + } + + push(line: string): void { + this.lines.push(line); + this.nextSeq++; + if (this.lines.length > this.capacity) { + this.lines.splice(0, this.lines.length - this.capacity); + } + } + + /** + * Returns lines whose logical sequence number is `>= since`, plus the + * next-since cursor (use as the next `since` value for incremental polling). + */ + since(since: number): { nextSince: number; lines: string[] } { + const baseSeq = Math.max(0, this.nextSeq - this.lines.length); + const wantStart = Math.max(since, baseSeq); + const offset = wantStart - baseSeq; + if (offset >= this.lines.length) { + return { nextSince: this.nextSeq, lines: [] }; + } + return { nextSince: this.nextSeq, lines: this.lines.slice(offset) }; + } + + /** Returns all lines currently in the buffer. */ + snapshot(): readonly string[] { + return this.lines; + } + + /** Monotonic cursor; safe to expose externally. */ + get cursor(): number { + return this.nextSeq; + } +} + +/** Start the control listener bound to 127.0.0.1. Resolves once listening. */ +export function startControlListener(opts: StartControlOpts): Promise<{ close(): Promise }> { + const logBuffer = opts.logBuffer ?? new LogBuffer(); + const server: Server = createServer(async (req, res) => { + try { + const result = await handleControlRequest(req, opts.state, { + onStartProxy: opts.onStartProxy, + onStopProxy: opts.onStopProxy, + onSetConfig: opts.onSetConfig, + onShutdown: opts.onShutdown, + logBuffer, + }); + writeJson(res, result.status, result.body); + } catch (err) { + writeJson(res, 500, { ok: false, error: `internal_error: ${(err as Error).message}` }); + } + }); + + return new Promise((resolve, reject) => { + server.on("error", reject); + server.listen(opts.port, "127.0.0.1", () => resolve({ + close: () => new Promise((r) => server.close(() => r())), + })); + }); +} + +export interface ControlHandlerResult { + status: number; + body: ControlResponse; +} + +/** Context passed to `handleControlRequest` for hook wiring + log access. */ +export interface HandlerContext { + onStartProxy?: () => Promise; + onStopProxy?: () => Promise<{ ok: true } | { ok: false; error: string }>; + onSetConfig?: (changes: { provider?: ProviderId; plan?: PlanTier }) => Promise; + onShutdown?: () => Promise | void; + logBuffer: LogBuffer; +} + +export function handleControlRequestForTest( + req: IncomingMessage, + state: ControlState, + onShutdown?: () => Promise | void, +): Promise { + // Backwards-compatible shape: only `onShutdown` is wired. + const ctx: HandlerContext = { onShutdown, logBuffer: new LogBuffer() }; + return handleControlRequest(req, state, ctx); +} + +/** + * Test entry that allows wiring all lifecycle hooks. Prefer this in new tests + * for startProxy/stopProxy/setConfig/getLogs coverage. + */ +export function handleControlRequestWithHooksForTest( + req: IncomingMessage, + state: ControlState, + ctx: HandlerContext, +): Promise { + return handleControlRequest(req, state, ctx); +} + +async function handleControlRequest( + req: IncomingMessage, + state: ControlState, + ctx: HandlerContext, +): Promise { + if (!isLoopback(req.socket.remoteAddress)) { + return { status: 403, body: { ok: false, error: "forbidden: non-loopback remote address" } }; + } + + const parsed = new URL(req.url ?? "/", "http://127.0.0.1"); + if (req.method !== "POST" || parsed.pathname !== "/control") { + return { status: 404, body: { ok: false, error: `not_found: ${req.method} ${parsed.pathname}` } }; + } + + const body = await readBody(req); + let cmd: ControlCommand; + try { + cmd = JSON.parse(body) as ControlCommand; + } catch { + return { status: 400, body: { ok: false, error: "invalid_json" } }; + } + + const result = await dispatch(cmd, state, ctx); + return { status: 200, body: result }; +} + +async function dispatch( + cmd: ControlCommand, + state: ControlState, + ctx: HandlerContext, +): Promise { + switch (cmd.cmd) { + case "status": { + const cred = await loadCredential().catch(() => null); + return { + ok: true, + state: "running", + provider: state.provider, + plan: state.plan, + proxyPort: state.proxyPort, + loggedIn: cred != null, + }; + } + + case "startOAuth": { + // Tear down any previous in-flight flow so its callback port is released. + if (state.activeOauth) { + await state.activeOauth.client.close().catch(() => {}); + state.activeOauth = undefined; + } + // Z.AI uses the server-mediated cli login (no local callback); bigmodel + // keeps the classic localhost auth-code callback server. + const client: OAuthFlowClient = + cmd.provider === "bigmodel" ? new BigmodelOAuthClient() : new ZaiOAuthClient(); + const started = await client.start(); + const callbackPort = started.callbackUrl + ? Number(new URL(started.callbackUrl).port) || 80 + : 0; + state.activeOauth = { + client, + callbackUrl: started.callbackUrl, + state: started.state, + }; + client.complete(started).then(async (tokens) => { + const resolver = new KeyResolver(); + const cred: Credential = await resolver.resolveCodingPlanCredential(tokens.accessToken, cmd.provider, tokens.userId); + if (tokens.jwt) cred.jwt = tokens.jwt; + await saveCredential(cred); + console.log(`OAuth completed for ${cmd.provider}`); + }).catch((err: unknown) => { + // Timeouts / rejections are expected when the user abandons the + // browser; nothing to surface beyond the log buffer. + console.error(`OAuth flow ended without success: ${(err as Error)?.message ?? String(err)}`); + }).finally(() => { + // MUST run on rejection too โ€” otherwise the callback port leaks until + // process death (Android: only a device reboot clears it). + void client.close().catch(() => {}); + if (state.activeOauth?.state === started.state) state.activeOauth = undefined; + }); + return { + ok: true, + event: "oauthUrl", + authorizeUrl: started.authorizeUrl, + callbackPort, + }; + } + + case "deliverOAuthCode": { + const active = state.activeOauth; + // Code delivery only applies to callback-based (auth-code) flows โ€” the + // Z.AI cli login completes via server polling and has no code to deliver. + if (!(active?.client instanceof AuthCodeOAuthClient) || active.state !== cmd.state) { + return { ok: false, error: "no_matching_oauth_flow" }; + } + try { + const { accessToken, userId, jwt } = await active.client.exchangeCode( + cmd.code, + active.callbackUrl, + cmd.state, + ); + const resolver = new KeyResolver(); + const cred: Credential = await resolver.resolveCodingPlanCredential(accessToken, cmd.provider, userId); + if (jwt) cred.jwt = jwt; + await saveCredential(cred); + state.activeOauth = undefined; + await active.client.close().catch(() => {}); + return { ok: true, event: "loginOk", provider: cmd.provider }; + } catch (err) { + state.activeOauth = undefined; + await active.client.close().catch(() => {}); + return { ok: false, error: `oauth_exchange_failed: ${(err as Error).message}` }; + } + } + + case "logout": { + await clearCredential(); + return { ok: true, event: "loggedOut" }; + } + + case "setConfig": { + if (!ctx.onSetConfig) return { ok: false, error: "config_update_unavailable" }; + const result = await ctx.onSetConfig({ provider: cmd.provider, plan: cmd.plan }); + if (!result.ok) return result; + state.provider = result.provider; + state.plan = result.plan; + return { ok: true, event: "configUpdated", provider: result.provider, plan: result.plan }; + } + + case "startProxy": { + if (!ctx.onStartProxy) return { ok: false, error: "proxy_lifecycle_unavailable" }; + const result = await ctx.onStartProxy(); + if (!result.ok) return result; + state.proxyPort = result.port; + return { ok: true, event: "proxyStarted", port: result.port }; + } + + case "stopProxy": { + if (!ctx.onStopProxy) return { ok: false, error: "proxy_lifecycle_unavailable" }; + const result = await ctx.onStopProxy(); + if (!result.ok) return result; + state.proxyPort = 0; + return { ok: true, event: "proxyStopped" }; + } + + case "getLogs": { + const since = typeof cmd.since === "number" ? cmd.since : 0; + const { nextSince, lines } = ctx.logBuffer.since(since); + return { ok: true, event: "logs", nextSince, lines: [...lines] }; + } + + case "shutdown": { + if (ctx.onShutdown) await ctx.onShutdown(); + return { ok: true, event: "shuttingDown" }; + } + + default: + return { ok: false, error: `unknown_cmd: ${(cmd as { cmd: string }).cmd}` }; + } +} + +function isLoopback(addr: string | undefined): boolean { + return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1"; +} + +function writeJson(res: ServerResponse, status: number, body: unknown): void { + const json = JSON.stringify(body); + res.writeHead(status, { + "content-type": "application/json; charset=utf-8", + "content-length": Buffer.byteLength(json), + }); + res.end(json); +} + +function readBody(req: IncomingMessage): Promise { + return new Promise((resolve, reject) => { + const chunks: Buffer[] = []; + req.on("data", (c: Buffer) => chunks.push(c)); + req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8"))); + req.on("error", reject); + }); +} diff --git a/src/async/bridge.ts b/src/async/bridge.ts new file mode 100644 index 0000000000000000000000000000000000000000..5e102a328f16947553178187a2d1e1f1c48a9784 --- /dev/null +++ b/src/async/bridge.ts @@ -0,0 +1,524 @@ +/** + * Async bridge: core state machine turning sync client stream expectation + * into off-peak async reality. See `.omo/plans/async-off-peak-bridge.md` ยง3. + * + * State machine: + * WAIT (queued) โ†’ poll every pollIntervalMs (signal-aware); emit keepalives + * READY (ready/active) โ†’ forward LLM call upstream with X-Off-Peak-Ticket-ID + * EXPIRED (ticket revoked) โ†’ settleOnce(old); if attempt < maxRetries take new ticket โ†’ WAIT; else terminal error + * DONE (stream completed) โ†’ settleOnce(current); close stream + * ABORT (client disconnect) โ†’ settleOnce(current); release resources + * + * Anti-patterns enforced (see plan ยง9): + * #1 โ€” pure `: keepalive\n\n` comments during wait; no custom data events + * #2 โ€” every takeTicket matched by exactly one settleOnce (idempotent) + * #3 โ€” retry resends original prompt (no NOe placeholder) + * #5 โ€” settle is fire-and-forget, never blocks stream closure + * + * Output: homogeneous byte stream (keepalives + upstream Anthropic bytes + terminal error events). + */ +import type { OffPeakClient } from "./client.js"; +import type { OffPeakCredentials, TakeTicketResult, TicketState } from "./types.js"; +import { isTicketExpired, isTicketReady } from "./types.js"; +import { keepaliveFrame } from "./keepalive.js"; +import { buildIdentityHeaders } from "../proxy/identity.js"; +import type { ProxyIdentity } from "../config/types.js"; + +const EXPIRED_MARKER = "off-peak-ticket-expired"; + +export interface BridgeOptions { + client: OffPeakClient; + credentials: OffPeakCredentials; + origin: string; + identity: ProxyIdentity; + llmRequestBody: string; + initialTicket: TakeTicketResult; + taskId: string; + pollIntervalMs: number; + keepAliveIntervalMs: number; + maxRetries: number; + /** Total wait cap across ALL retries (not per-ticket). 0 = unlimited. */ + maxWaitMs: number; + clientSignal?: AbortSignal; + fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise; + onTransition?: (info: BridgeTransition) => void; +} + +export interface BridgeTransition { + phase: "wait" | "ready" | "expired" | "done" | "abort" | "error"; + attempt: number; + ticketId: string; + state?: TicketState; + message?: string; +} + +export interface BridgeOutcome { + attempts: number; + finalTicketId: string; + terminalPhase: BridgeTransition["phase"]; +} + +export function runAsyncBridge(opts: BridgeOptions): { stream: ReadableStream; outcome: Promise } { + const fetchImpl = opts.fetchImpl ?? globalThis.fetch; + const encoder = new TextEncoder(); + let outcomeResolve!: (o: BridgeOutcome) => void; + const outcome = new Promise((r) => { + outcomeResolve = r; + }); + let outcomeResolved = false; + function resolveOutcome(o: BridgeOutcome): void { + if (outcomeResolved) return; + outcomeResolved = true; + outcomeResolve(o); + } + + let aborted = false; + const settledTickets = new Set(); + function settleOnce(ticketId: string): void { + if (settledTickets.has(ticketId)) return; + settledTickets.add(ticketId); + void opts.client.settle(ticketId).catch(() => { + // best-effort; settle failure is non-fatal + }); + } + + function log(info: BridgeTransition): void { + try { + opts.onTransition?.(info); + } catch { + // observability hook must never break the bridge + } + } + + function emitKeepalive(controller: ReadableStreamDefaultController): void { + if (aborted) return; + try { + controller.enqueue(keepaliveFrame()); + } catch { + // controller closed by consumer + } + } + + function emitTerminalError(controller: ReadableStreamDefaultController, message: string, type: string = "api_error"): void { + if (aborted) return; + const payload = JSON.stringify({ type: "error", error: { type, message } }); + try { + controller.enqueue(encoder.encode(`event: error\ndata: ${payload}\n\n`)); + } catch { + // already closed + } + } + + /** + * Wait until ticket becomes ready/active OR expired/not_found OR abort OR total maxWaitMs exceeded. + * `settled` and unknown states are treated as expired (server can't dispatch this ticket again). + * Polls respect clientSignal for immediate cancellation. + * + * `maxWaitExceeded: true` marks a CLIENT-SIDE deadline overrun (distinct from + * a server-side ticket expiry) so the caller terminates with a timeout error + * instead of misreading it as "ticket expired" and burning retakes. + */ + async function waitForReady(ticketId: string, deadlineAt: number): Promise<{ state: TicketState; maxWaitExceeded?: boolean }> { + while (true) { + if (aborted) return { state: "expired" as TicketState }; + const result = await pollBatchStatusWithRetry(ticketId); + if (aborted) return { state: "expired" as TicketState }; + const ticket = result.tickets[0]; + if (!ticket) return { state: "not_found" as TicketState }; + if (isTicketReady(ticket.state)) return { state: ticket.state }; + // `settled`, `expired`, `not_found`, or any unknown state โ†’ unusable, treat as expired + if (ticket.state !== "queued") return { state: "expired" as TicketState }; + + const delay = result.nextPollAfterMs ?? opts.pollIntervalMs; + if (opts.maxWaitMs > 0 && Date.now() + delay > deadlineAt) { + // The NEXT poll would overrun the total wait budget. Sleep out the + // remainder and report a deadline overrun (NOT "expired" โ€” an early + // `expired` here used to send the caller into the retake loop against + // the same deadline until maxRetries burned out). + await sleep(Math.max(0, deadlineAt - Date.now()), opts.clientSignal); + return { state: "expired" as TicketState, maxWaitExceeded: true }; + } + await sleep(delay, opts.clientSignal); + } + } + + /** + * Single batchStatus poll with local tolerance for transient control-plane + * errors: up to POLL_RETRY_LIMIT consecutive failures (backoff + * min(pollIntervalMs, 2s) between them) before the error escapes. A single + * network blip must not kill an hours-long queue wait โ€” the sync path + * (proxy/handler.ts connect-retry) retries the same class of failure. + * Abandon immediately (no retry) once the client has aborted. + */ + async function pollBatchStatusWithRetry(ticketId: string): Promise>> { + const POLL_RETRY_LIMIT = 3; + const retryDelayMs = Math.min(opts.pollIntervalMs, 2000); + let lastErr: unknown; + for (let attempt = 1; attempt <= POLL_RETRY_LIMIT; attempt++) { + if (aborted || opts.clientSignal?.aborted) throw lastErr ?? new Error("client aborted during poll"); + try { + return await opts.client.batchStatus([ticketId], opts.clientSignal); + } catch (err) { + lastErr = err; + // Client disconnected mid-poll โ€” retrying would delay the abort path. + if (aborted || opts.clientSignal?.aborted) throw err; + if (attempt < POLL_RETRY_LIMIT) await sleep(retryDelayMs, opts.clientSignal); + } + } + throw lastErr; + } + + async function forwardLLM(ticketId: string): Promise<{ response: Response; expiredInBody: boolean }> { + const url = `${opts.origin.replace(/\/+$/, "")}/api/v1/off-peak/anthropic/v1/messages`; + const headers: Record = { + "content-type": "application/json", + authorization: `Bearer ${opts.credentials.jwt}`, + "x-coding-plan-api-key": opts.credentials.codingPlanApiKey, + "x-off-peak-ticket-id": ticketId, + ...buildIdentityHeaders(opts.identity), + }; + if (opts.credentials.bigmodelOrganization) headers["bigmodel-organization"] = opts.credentials.bigmodelOrganization; + if (opts.credentials.bigmodelProject) headers["bigmodel-project"] = opts.credentials.bigmodelProject; + + const resp = await fetchImpl(url, { + method: "POST", + headers, + body: opts.llmRequestBody, + signal: opts.clientSignal, + }); + + if (!resp.ok) { + const bodyText = await resp.text().catch(() => ""); + if (bodyText.includes(EXPIRED_MARKER)) { + return { response: new Response(bodyText, { status: resp.status, headers: resp.headers }), expiredInBody: true }; + } + return { response: new Response(bodyText, { status: resp.status, headers: resp.headers }), expiredInBody: false }; + } + return { response: resp, expiredInBody: false }; + } + + const stream = new ReadableStream({ + async start(controller) { + // External signal โ†’ local aborted flag. Both paths (consumer cancel + signal abort) converge here. + if (opts.clientSignal) { + if (opts.clientSignal.aborted) aborted = true; + else opts.clientSignal.addEventListener("abort", () => { aborted = true; }, { once: true }); + } + + // Keepalive runs ONLY during WAIT/retry phases; stopped before LLM streaming to + // avoid inserting `: keepalive\n\n` inside a partial SSE frame split across chunks. + let keepAliveTimer: ReturnType | undefined; + function startKeepalive(): void { + if (keepAliveTimer) return; + keepAliveTimer = setInterval(() => emitKeepalive(controller), opts.keepAliveIntervalMs); + } + function stopKeepalive(): void { + if (keepAliveTimer) { + clearInterval(keepAliveTimer); + keepAliveTimer = undefined; + } + } + + // Total wait deadline across all retries (B11: was per-ticket, leaked to (maxRetries+1)*maxWaitMs). + const requestStartedAt = Date.now(); + const deadlineAt = opts.maxWaitMs > 0 ? requestStartedAt + opts.maxWaitMs : Number.MAX_SAFE_INTEGER; + + let currentTicket = opts.initialTicket; + let attempt = 0; + + try { + while (true) { + if (aborted) { + log({ phase: "abort", attempt, ticketId: currentTicket.ticketId }); + settleOnce(currentTicket.ticketId); + return; + } + + // WAIT phase + if (!isTicketReady(currentTicket.state)) { + log({ phase: "wait", attempt, ticketId: currentTicket.ticketId, state: currentTicket.state }); + startKeepalive(); + const wait = await waitForReady(currentTicket.ticketId, deadlineAt); + if (aborted) { + stopKeepalive(); + log({ phase: "abort", attempt, ticketId: currentTicket.ticketId }); + settleOnce(currentTicket.ticketId); + return; + } + if (wait.maxWaitExceeded) { + // CL-02: client-side maxWaitMs overrun โ€” terminal timeout, NOT a + // server expiry. Retaking would just re-wait against the same + // (already blown) deadline until maxRetries exhausts. + stopKeepalive(); + settleOnce(currentTicket.ticketId); + emitTerminalError(controller, `async max wait timeout (${opts.maxWaitMs}ms exceeded)`, "timeout"); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + if (isTicketExpired(wait.state)) { + stopKeepalive(); + settleOnce(currentTicket.ticketId); + // Check if this was a client-side maxWaitMs timeout (not server expiration). + // Distinguish the error so users don't chase server-side ticket issues. + if (opts.maxWaitMs > 0 && Date.now() >= deadlineAt) { + emitTerminalError(controller, `async max wait timeout (${opts.maxWaitMs}ms exceeded)`, "timeout"); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + log({ phase: "expired", attempt, ticketId: currentTicket.ticketId, state: wait.state, message: "expired in queue" }); + attempt++; + if (attempt > opts.maxRetries) { + emitTerminalError(controller, `async upstream exhausted retries (ticket expired in queue ${attempt}x)`, "api_error"); + resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + try { + currentTicket = await opts.client.takeTicket(opts.taskId, opts.clientSignal); + } catch (takeErr) { + emitTerminalError(controller, `async retake failed: ${(takeErr as Error).message}`, "api_error"); + resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + continue; + } + stopKeepalive(); + } + + // READY phase โ€” NO keepalive (would corrupt SSE frames split across chunks) + log({ phase: "ready", attempt, ticketId: currentTicket.ticketId }); + let resp: Response; + let expiredInBody: boolean; + try { + const forward = await forwardLLM(currentTicket.ticketId); + resp = forward.response; + expiredInBody = forward.expiredInBody; + } catch (err) { + if (aborted) { + settleOnce(currentTicket.ticketId); + return; + } + emitTerminalError(controller, `async upstream network error: ${(err as Error).message}`, "api_error"); + settleOnce(currentTicket.ticketId); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + + if (!resp.ok || expiredInBody) { + const bodyText = await resp.text().catch(() => ""); + if (expiredInBody || bodyText.includes(EXPIRED_MARKER)) { + log({ phase: "expired", attempt, ticketId: currentTicket.ticketId, message: "expired during LLM (pre-stream)" }); + settleOnce(currentTicket.ticketId); + attempt++; + if (attempt > opts.maxRetries) { + emitTerminalError(controller, `async upstream exhausted retries (ticket expired during LLM ${attempt}x)`, "api_error"); + resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + try { + currentTicket = await opts.client.takeTicket(opts.taskId, opts.clientSignal); + } catch (takeErr) { + emitTerminalError(controller, `async retake failed: ${(takeErr as Error).message}`, "api_error"); + resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + continue; + } + // Non-expired upstream error โ†’ emit standard Anthropic error event. + // Sanitized message: status only; body omitted to avoid leaking upstream internals. + emitTerminalError(controller, `async upstream HTTP ${resp.status}`, "api_error"); + settleOnce(currentTicket.ticketId); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + + // Stream upstream body with complete-frame buffering. + // + // DESIGN (fixes R3-2/R3-3/R4-1/R4-3 + bounds memory R4-5): + // - One TextDecoder for the whole streaming phase (handles partial + // multibyte UTF-8 correctly across chunk boundaries). + // - Accumulate decoded text until a complete SSE frame (`\n\n` boundary). + // - Scan the COMPLETE frame for the expired marker before forwarding. + // This catches markers split across any number of network chunks. + // - Forward via `encoder.encode(frame)` โ€” re-encoding Unicode codepoints + // through UTF-16โ†’UTF-8 is lossless for valid input, and avoids the + // raw-vs-decoded byte mismatch that previously dropped pre-commit + // chunks when the boundary spanned chunks. + // - Cap `pending` at MAX_PENDING_FRAME_BYTES to prevent a malicious + // upstream from exhausting memory by streaming without `\n\n`. + // + // State machine: + // Pre-commit (no frame forwarded yet): marker found โ†’ transparent retry. + // Post-commit (โ‰ฅ1 frame forwarded): marker found โ†’ terminal error + // (cannot retry โ€” client already saw message_start; retrying would + // produce duplicate lifecycle events). + let midStreamExpiredPreCommit = false; + let midStreamExpiredPostCommit = false; + let committed = false; + if (resp.body) { + const reader = resp.body.getReader(); + const streamDecoder = new TextDecoder(); + let pending = ""; + const MAX_PENDING_FRAME_BYTES = 1 * 1024 * 1024; + try { + while (true) { + if (aborted) { + await reader.cancel().catch(() => {}); + settleOnce(currentTicket.ticketId); + return; + } + const { done, value } = await reader.read(); + if (done) { + // SSE spec: discard pending data at EOF if it lacks a terminating + // blank line (incomplete event). Only flush if marker-free AND + // properly terminated. + if (pending.length > 0 && !aborted && !midStreamExpiredPreCommit && !midStreamExpiredPostCommit) { + if (pending.includes(EXPIRED_MARKER)) { + if (!committed) midStreamExpiredPreCommit = true; + else midStreamExpiredPostCommit = true; + } else if (pending.endsWith("\n\n")) { + // Properly terminated final frame โ€” safe to forward. + try { controller.enqueue(encoder.encode(pending)); } catch {} + } + // else: unterminated event at EOF โ€” discard per SSE spec. + pending = ""; + } + break; + } + if (aborted) break; + pending += streamDecoder.decode(value, { stream: true }).replace(/\r\n/g, "\n").replace(/\r/g, "\n"); + + // Bounded buffer: if pending exceeds the cap without a frame boundary, + // the upstream is malformed or malicious โ€” terminate. + if (pending.length > MAX_PENDING_FRAME_BYTES) { + await reader.cancel().catch(() => {}); + emitTerminalError(controller, "async upstream SSE frame exceeded 1 MiB boundary", "api_error"); + settleOnce(currentTicket.ticketId); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + + // Process all complete frames in `pending`. + let frameBoundaryFound = false; + while (true) { + const idx = pending.indexOf("\n\n"); + if (idx === -1) break; + const frame = pending.slice(0, idx + 2); + pending = pending.slice(idx + 2); + + if (frame.includes(EXPIRED_MARKER)) { + if (!committed) { + midStreamExpiredPreCommit = true; + } else { + midStreamExpiredPostCommit = true; + } + await reader.cancel().catch(() => {}); + frameBoundaryFound = true; + break; + } + try { + controller.enqueue(encoder.encode(frame)); + committed = true; + } catch { + await reader.cancel().catch(() => {}); + frameBoundaryFound = true; + break; + } + } + if (midStreamExpiredPreCommit || midStreamExpiredPostCommit || frameBoundaryFound) break; + } + // Flush decoder (no stream flag) to release internal partial-byte state. + streamDecoder.decode(); + } finally { + reader.releaseLock?.(); + } + } + + if (midStreamExpiredPreCommit && !aborted) { + log({ phase: "expired", attempt, ticketId: currentTicket.ticketId, message: "expired during LLM (mid-stream, pre-commit)" }); + settleOnce(currentTicket.ticketId); + attempt++; + if (attempt > opts.maxRetries) { + emitTerminalError(controller, `async upstream exhausted retries (ticket expired mid-stream ${attempt}x)`, "api_error"); + resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + try { + currentTicket = await opts.client.takeTicket(opts.taskId, opts.clientSignal); + } catch (takeErr) { + emitTerminalError(controller, `async retake failed: ${(takeErr as Error).message}`, "api_error"); + resolveOutcome({ attempts: attempt, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + continue; + } + + if (midStreamExpiredPostCommit && !aborted) { + // Cannot retry transparently โ€” client already saw message_start. + // Emit terminal error and close. + log({ phase: "error", attempt, ticketId: currentTicket.ticketId, message: "expired mid-stream after commit; cannot retry" }); + settleOnce(currentTicket.ticketId); + emitTerminalError(controller, "async upstream ticket expired mid-stream after output started", "api_error"); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + return; + } + + if (aborted) { + log({ phase: "abort", attempt, ticketId: currentTicket.ticketId }); + settleOnce(currentTicket.ticketId); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "abort" }); + return; + } + + log({ phase: "done", attempt, ticketId: currentTicket.ticketId }); + settleOnce(currentTicket.ticketId); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "done" }); + return; + } + } catch (err) { + if (!aborted) { + emitTerminalError(controller, `async bridge internal error: ${(err as Error).message}`, "api_error"); + } + settleOnce(currentTicket.ticketId); + resolveOutcome({ attempts: attempt + 1, finalTicketId: currentTicket.ticketId, terminalPhase: "error" }); + } finally { + stopKeepalive(); + try { + controller.close(); + } catch { + // already closed + } + // Abort paths return without calling resolveOutcome; resolve here as a fallback + // so `await outcome` never hangs. Idempotent โ€” explicit calls above take precedence. + resolveOutcome({ + attempts: attempt + 1, + finalTicketId: currentTicket.ticketId, + terminalPhase: aborted ? "abort" : "error", + }); + } + }, + + cancel() { + aborted = true; + }, + }); + + return { stream, outcome }; +} + +function sleep(ms: number, signal?: AbortSignal): Promise { + return new Promise((resolve) => { + if (signal?.aborted) { + resolve(); + return; + } + const t = setTimeout(() => { + signal?.removeEventListener("abort", onAbort); + resolve(); + }, ms); + const onAbort = (): void => { + clearTimeout(t); + resolve(); + }; + signal?.addEventListener("abort", onAbort, { once: true }); + }); +} diff --git a/src/async/client.ts b/src/async/client.ts new file mode 100644 index 0000000000000000000000000000000000000000..9d539685a0e03427397d26f7c8dd85323e562480 --- /dev/null +++ b/src/async/client.ts @@ -0,0 +1,259 @@ +/** + * HTTP client for ZCode's off-peak ticket-queue backend. + * + * Implements the 4 control-plane endpoints documented in `_reverse/NOTEPAD.md`: + * - `GET /ticket/availability` โ€” probe queue availability + * - `POST /ticket` โ€” take a number (queue entry) + * - `POST /ticket/status` โ€” batch poll ticket states + * - `POST /ticket/{id}/settle` โ€” close-out (success/abort/cancel) + * + * Each method has its own short timeout (default 15s) via `setTimeout + abort`. + * 4xx on `settle` resolves as success (server already cleaned up โ€” see `settleOne` + * in the bundle). Other 4xx/5xx throw `OffPeakServerError`. + * + * @see _reverse/NOTEPAD.md "Off-Peak / Idle Plan" โ†’ "Endpoints" / "Headers" + */ +import type { + AvailabilityResult, + BatchStatusResult, + OffPeakCredentials, + TakeTicketResult, + TicketState, + TicketStatusResult, +} from "./types.js"; +import { OffPeakServerError } from "./types.js"; + +export interface OffPeakClientOptions { + origin: string; + credentials: OffPeakCredentials; + /** Per-call timeout in ms (default 15000). Applies to all 4 methods. */ + controlTimeoutMs?: number; + /** DI seam for tests. Default `globalThis.fetch`. */ + fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise; + /** Settle-specific timeout override (default = controlTimeoutMs). Set lower for fire-and-forget abort paths. */ + settleTimeoutMs?: number; +} + +const DEFAULT_CONTROL_TIMEOUT_MS = 15_000; + +/** Maximum tickets per `/ticket/status` batch (server cap, mirrors bundle behavior). */ +const MAX_BATCH_STATUS = 100; + +export interface OffPeakClient { + getAvailability(signal?: AbortSignal): Promise; + takeTicket(taskId: string, signal?: AbortSignal): Promise; + batchStatus(ticketIds: string[], signal?: AbortSignal): Promise; + /** Settle a ticket. `settleAsSuccess` controls 4xx behavior: if true (default), 4xx resolves as success (server already cleaned up). */ + settle(ticketId: string, opts?: { settleAsSuccess?: boolean; signal?: AbortSignal }): Promise; +} + +export function createOffPeakClient(opts: OffPeakClientOptions): OffPeakClient { + const origin = opts.origin.replace(/\/+$/, ""); + const credentials = opts.credentials; + const controlTimeoutMs = opts.controlTimeoutMs ?? DEFAULT_CONTROL_TIMEOUT_MS; + const settleTimeoutMs = opts.settleTimeoutMs ?? controlTimeoutMs; + const fetchImpl = opts.fetchImpl ?? globalThis.fetch; + + function buildHeaders(hasBody: boolean): Record { + const h: Record = { + authorization: `Bearer ${credentials.jwt}`, + "x-coding-plan-api-key": credentials.codingPlanApiKey, + }; + if (hasBody) h["content-type"] = "application/json"; + if (credentials.bigmodelOrganization) h["bigmodel-organization"] = credentials.bigmodelOrganization; + if (credentials.bigmodelProject) h["bigmodel-project"] = credentials.bigmodelProject; + return h; + } + + async function request( + method: string, + path: string, + body: unknown | undefined, + timeoutMs: number, + externalSignal: AbortSignal | undefined, + isSettle: boolean, + settleAsSuccess: boolean, + ): Promise { + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), timeoutMs); + const onExternalAbort = (): void => controller.abort(); + if (externalSignal) { + if (externalSignal.aborted) controller.abort(); + else externalSignal.addEventListener("abort", onExternalAbort, { once: true }); + } + + const url = `${origin}/api/v1/off-peak${path}`; + const init: RequestInit = { + method, + headers: buildHeaders(body !== undefined), + signal: controller.signal, + }; + if (body !== undefined) init.body = JSON.stringify(body); + + // Single outer try/finally covers BOTH fetch + body consumption. + // Round 4 found that fetch rejection bypassed the body-phase cleanup, + // leaving timer + listener leaked. Outer finally guarantees cleanup on every path. + let resp: Response | undefined; + let raw = ""; + try { + try { + resp = await fetchImpl(url, init); + } catch (err) { + const msg = (err as Error)?.message ?? String(err); + if (/abort/i.test(msg)) throw new OffPeakServerError(`off-peak request aborted: ${method} ${path}`, 0); + throw new OffPeakServerError(`off-peak network error: ${method} ${path}: ${msg}`, 0); + } + raw = await resp.text(); + } finally { + clearTimeout(timer); + externalSignal?.removeEventListener("abort", onExternalAbort); + } + + if (!resp.ok) { + // Settle-specific: 4xx means server already cleaned up (ticket expired/not_found) โ€” treat as success. + if (isSettle && settleAsSuccess && resp.status >= 400 && resp.status < 500) { + return undefined; + } + let bizCode: string | undefined; + let serverMsg = `HTTP ${resp.status}`; + try { + const parsed = JSON.parse(raw); + bizCode = parsed?.code !== undefined ? String(parsed.code) : undefined; + if (parsed?.msg) serverMsg = String(parsed.msg); + else if (parsed?.message) serverMsg = String(parsed.message); + } catch { + if (raw.length > 0 && raw.length < 200) serverMsg = raw; + } + throw new OffPeakServerError( + `off-peak ${method} ${path} failed: ${serverMsg}`, + resp.status, + bizCode, + ); + } + + if (raw.length === 0) return undefined; + let parsedJson: unknown; + try { + parsedJson = JSON.parse(raw); + } catch { + return undefined; + } + // Unwrap canonical envelope `{code:0, data:{...}}`. Non-zero `code` on HTTP 200 + // is a business-level error (mirrors `requestBizApi` in `auth/resolver.ts` and + // the bundle's `n` helper: `y.code===0 ? y.data : y`). + if (parsedJson && typeof parsedJson === "object") { + const obj = parsedJson as { code?: unknown; data?: unknown; msg?: unknown; message?: unknown }; + if ("code" in obj || "data" in obj) { + // NOTEPAD spec: canonical success is numeric `code === 0` ONLY (bundle's + // `n` helper: `y.code===0 ? y.data : y`). Strict `===` rejects string "0", + // numeric 200, undefined, etc. Responses without a numeric `code` field + // but with `data` are NOT unwrapped (avoids masking biz errors). + const code = obj.code; + if (code !== 0) { + if (code === undefined) { + // Ambiguous envelope ({data:...} without code) โ€” be conservative, don't unwrap. + // Return parsedJson as-is so the caller sees the wrapper. + } else { + const msg = obj.msg ?? obj.message ?? `biz code ${String(code)}`; + throw new OffPeakServerError( + `off-peak ${method} ${path} biz error: ${msg}`, + resp?.status ?? 0, + String(code), + ); + } + } else if (obj.data !== undefined) { + return obj.data; + } + } + } + return parsedJson; + } + + return { + async getAvailability(signal?: AbortSignal): Promise { + const data = (await request("GET", "/ticket/availability", undefined, controlTimeoutMs, signal, false, false)) as + | { can_take_number?: boolean; next_take_at?: number } + | undefined; + if (!data) throw new OffPeakServerError("off-peak availability empty response", 0); + const canTakeNumber = data.can_take_number === true; + if (!canTakeNumber && data.next_take_at === undefined) { + throw new OffPeakServerError("off-peak availability missing next_take_at while unavailable", 0); + } + const result: AvailabilityResult = { canTakeNumber }; + if (data.next_take_at !== undefined) result.nextTakeAt = data.next_take_at; + return result; + }, + + async takeTicket(taskId: string, signal?: AbortSignal): Promise { + if (!taskId || typeof taskId !== "string") { + throw new Error("takeTicket: taskId must be a non-empty string"); + } + const data = (await request("POST", "/ticket", { task_id: taskId }, controlTimeoutMs, signal, false, false)) as + | { ticket_id?: string; state?: string; position?: number; next_poll_after?: number } + | undefined; + if (!data || typeof data.ticket_id !== "string" || typeof data.state !== "string") { + throw new OffPeakServerError("off-peak takeTicket malformed response", 0); + } + const state = data.state as TicketState; + const result: TakeTicketResult = { + ticketId: data.ticket_id, + state, + registeredAt: Date.now(), + }; + if (data.position != null) result.position = data.position; + if (data.next_poll_after !== undefined) result.nextPollAfterMs = data.next_poll_after * 1000; + return result; + }, + + async batchStatus(ticketIds: string[], signal?: AbortSignal): Promise { + if (ticketIds.length === 0) return { tickets: [] }; + const truncated = ticketIds.slice(0, MAX_BATCH_STATUS); + const data = (await request( + "POST", + "/ticket/status", + { ticket_ids: truncated }, + controlTimeoutMs, + signal, + false, + false, + )) as + | { next_poll_after?: number; tickets?: Array<{ ticket_id?: string; state?: string; position?: number; active_deadline?: number }> } + | undefined; + if (!data || !Array.isArray(data.tickets)) { + throw new OffPeakServerError("off-peak batchStatus malformed response", 0); + } + const result: BatchStatusResult = { + tickets: data.tickets.map((t): TicketStatusResult => { + if (typeof t.ticket_id !== "string" || typeof t.state !== "string") { + throw new OffPeakServerError("off-peak batchStatus ticket entry malformed", 0); + } + const item: TicketStatusResult = { + ticketId: t.ticket_id, + state: t.state as TicketState, + }; + if (t.position != null) item.position = t.position; + if (t.active_deadline !== undefined) item.activeDeadline = t.active_deadline; + return item; + }), + }; + if (data.next_poll_after !== undefined) result.nextPollAfterMs = data.next_poll_after * 1000; + return result; + }, + + async settle( + ticketId: string, + opts: { settleAsSuccess?: boolean; signal?: AbortSignal } = {}, + ): Promise { + const settleAsSuccess = opts.settleAsSuccess !== false; + await request( + "POST", + `/ticket/${encodeURIComponent(ticketId)}/settle`, + undefined, + settleTimeoutMs, + opts.signal, + true, + settleAsSuccess, + ); + }, + }; +} diff --git a/src/async/handler.ts b/src/async/handler.ts new file mode 100644 index 0000000000000000000000000000000000000000..d30cc2545a28d911290b618effdd23b018b5f8dd --- /dev/null +++ b/src/async/handler.ts @@ -0,0 +1,482 @@ +/** + * Async route handlers โ€” wrap the bridge with format-specific translation. + * + * Three handlers: + * - `handleAsyncMessages` (Anthropic client, POST /async/v1/messages) โ€” passthrough + * - `handleAsyncChat` (OpenAI client, POST /async/v1/chat/completions) โ€” request OAIโ†’ANT, response ANT SSEโ†’OAI SSE + * - `handleAsyncHealth` (GET /async/v1/health) โ€” probe queue availability + * + * Common pre-flight (B1 fix: validate BEFORE takeTicket so we never leak a ticket + * on JSON parse / model-missing / translation failures): + * 1. Verify credential has `jwt` (login-captured JWT; absent on imported keys) + * 2. Read + parse client body (skip for health) + * 3. Validate required fields + build the Anthropic-format upstream body + * 4. ONLY THEN takeTicket (any failure above returns 4xx WITHOUT a ticket) + * + * For non-stream (B5+B10): internally force `stream:true` upstream; return a + * chunked `application/json` response that emits legal leading whitespace during + * wait (defeats client TCP idle) and writes the final aggregated JSON at the end. + * + * @see .omo/plans/async-off-peak-bridge.md ยง3 for full design. + */ +import type { ProxyConfig } from "../config/types.js"; +import type { AuthManager } from "../auth/manager.js"; +import type { Credential } from "../auth/types.js"; +import { credentialString } from "../auth/types.js"; +import { errorResponse } from "../proxy/handler.js"; +import { transformRequestBody } from "../proxy/body-transformer.js"; +import { inflateWithCap } from "../proxy/inflate.js"; +import { translateRequestOpenAIToAnthropic, translateResponseAnthropicToOpenAI } from "../translator/openai-to-anthropic.js"; +import { anthropicSseToOpenaiSseWithKeepalive } from "./openai-stream-adapter.js"; +import type { AnthropicMessagesRequest, OpenAIChatRequest, AnthropicMessagesResponse } from "../translator/types.js"; +import { createOffPeakClient, type OffPeakClient } from "./client.js"; +import type { OffPeakCredentials, TakeTicketResult } from "./types.js"; +import { runAsyncBridge } from "./bridge.js"; + +/** Cap request body size to prevent memory exhaustion (B16). */ +const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024; + +/** Single space byte โ€” used for non-stream chunked JSON whitespace keepalive. */ +const SINGLE_SPACE = new Uint8Array([32]); + +export interface AsyncHandlerOptions { + config: ProxyConfig; + auth: AuthManager; + fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise; + debug?: boolean; +} + +function buildCredentials(cred: Credential): OffPeakCredentials { + return { + jwt: cred.jwt ?? "", + codingPlanApiKey: credentialString(cred), + }; +} + +function generateTaskId(): string { + return `proxy-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`; +} + +function resolveModel(req: { model?: string }, config: ProxyConfig): string { + const explicit = typeof req.model === "string" ? req.model.trim() : ""; + if (explicit) return explicit; + if (config.async.defaultModel && config.async.defaultModel.trim()) return config.async.defaultModel.trim(); + return config.defaultModel; +} + +async function readBody(req: Request): Promise<{ ok: true; body: string } | { ok: false; response: Response }> { + // Reject oversized Content-Length up front; otherwise drain the stream incrementally + // and abort as soon as we exceed the cap. This prevents an attacker from exhausting + // memory by sending a huge chunked body with no Content-Length. + const contentLength = req.headers.get("content-length"); + if (contentLength) { + const cl = parseInt(contentLength, 10); + if (Number.isFinite(cl) && cl > MAX_REQUEST_BODY_BYTES) { + // Cancel the request body stream so the underlying socket releases; otherwise + // the client can keep the connection alive despite the 413 response. + req.body?.cancel().catch(() => {}); + return { ok: false, response: errorResponse(413, "request_too_large", `body exceeds ${MAX_REQUEST_BODY_BYTES} byte cap`) }; + } + } + if (!req.body) { + return { ok: false, response: errorResponse(400, "invalid_request_error", "missing request body") }; + } + const reader = req.body.getReader(); + const chunks: Uint8Array[] = []; + let total = 0; + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + total += value.byteLength; + if (total > MAX_REQUEST_BODY_BYTES) { + await reader.cancel().catch(() => {}); + return { ok: false, response: errorResponse(413, "request_too_large", `body exceeds ${MAX_REQUEST_BODY_BYTES} byte cap`) }; + } + chunks.push(value); + } + } catch { + return { ok: false, response: errorResponse(400, "invalid_request_error", "could not read request body") }; + } finally { + reader.releaseLock?.(); + } + // Inflate `content-encoding: gzip` request bodies with the cap enforced on + // the DECOMPRESSED size โ€” a small gzip bomb must not bypass the byte cap. + const encoding = req.headers.get("content-encoding")?.toLowerCase().trim() ?? ""; + let bytes: Uint8Array = Buffer.concat(chunks); + if (encoding === "gzip" || encoding === "x-gzip") { + const inflated = await inflateWithCap(bytes, MAX_REQUEST_BODY_BYTES); + if (!inflated.ok) { + if (inflated.reason === "too_large") { + return { ok: false, response: errorResponse(413, "request_too_large", `decompressed body exceeds ${MAX_REQUEST_BODY_BYTES} byte cap`) }; + } + return { ok: false, response: errorResponse(400, "invalid_request_error", "could not decompress gzip request body") }; + } + bytes = inflated.bytes; + } + const body = new TextDecoder().decode(bytes); + if (!body || body.length === 0) { + return { ok: false, response: errorResponse(400, "invalid_request_error", "empty request body") }; + } + return { ok: true, body }; +} + +async function resolveCredential(opts: AsyncHandlerOptions): Promise<{ ok: true; cred: Credential; credentials: OffPeakCredentials } | { ok: false; response: Response }> { + let cred: Credential; + try { + cred = await opts.auth.getCredential(); + } catch (err) { + return { ok: false, response: errorResponse(401, "authentication_error", `credential resolution failed: ${(err as Error).message}`) }; + } + if (!cred.jwt) { + return { + ok: false, + response: errorResponse( + 400, + "async_credentials_unavailable", + "async endpoints require a logged-in oauth credential (JWT missing). Re-run `auth login` or use sync /v1/* endpoints.", + ), + }; + } + return { ok: true, cred, credentials: buildCredentials(cred) }; +} + +function buildClient(opts: AsyncHandlerOptions, credentials: OffPeakCredentials): OffPeakClient { + return createOffPeakClient({ + origin: opts.config.async.origin, + credentials, + controlTimeoutMs: opts.config.async.controlTimeoutMs, + settleTimeoutMs: opts.config.async.settleTimeoutMs, + fetchImpl: opts.fetchImpl, + }); +} + +async function takeTicketOr502(client: OffPeakClient, taskId: string, opts: AsyncHandlerOptions, signal: AbortSignal | undefined): Promise<{ ok: true; ticket: TakeTicketResult } | { ok: false; response: Response }> { + try { + const ticket = await client.takeTicket(taskId, signal); + return { ok: true, ticket }; + } catch (err) { + return { ok: false, response: errorResponse(502, "async_take_ticket_failed", `off-peak takeTicket failed: ${(err as Error).message}`) }; + } +} + +function buildBridge(opts: AsyncHandlerOptions, client: OffPeakClient, credentials: OffPeakCredentials, llmRequestBody: string, initialTicket: TakeTicketResult, taskId: string, req: Request) { + return runAsyncBridge({ + client, + credentials, + origin: opts.config.async.origin, + identity: opts.config.identity, + llmRequestBody, + initialTicket, + taskId, + pollIntervalMs: opts.config.async.pollIntervalMs, + keepAliveIntervalMs: opts.config.async.keepAliveIntervalMs, + maxRetries: opts.config.async.maxRetries, + maxWaitMs: opts.config.async.maxWaitMs, + clientSignal: req.signal, + fetchImpl: opts.fetchImpl, + onTransition: opts.debug + ? (info) => { + console.log(`[async] task=${taskId} ticket=${info.ticketId} phase=${info.phase} attempt=${info.attempt}${info.state ? ` state=${info.state}` : ""}${info.message ? ` msg=${info.message}` : ""}`); + } + : undefined, + }); +} + +function sseHeaders(): Record { + return { + "content-type": "text/event-stream; charset=utf-8", + "cache-control": "no-cache", + connection: "keep-alive", + }; +} + +export async function handleAsyncMessages(req: Request, opts: AsyncHandlerOptions): Promise { + // B1: validate everything before ticket acquisition + const cred = await resolveCredential(opts); + if (!cred.ok) return cred.response; + + const bodyResult = await readBody(req); + if (!bodyResult.ok) return bodyResult.response; + + let parsedBody: Record; + try { + const raw = JSON.parse(bodyResult.body); + if (raw === null || typeof raw !== "object" || Array.isArray(raw)) { + return errorResponse(400, "invalid_request_error", "request body must be a JSON object"); + } + parsedBody = raw as Record; + } catch { + return errorResponse(400, "invalid_request_error", "request body is not valid JSON"); + } + if (!Array.isArray(parsedBody.messages) || parsedBody.messages.length === 0) { + return errorResponse(400, "invalid_request_error", "missing or invalid `messages` field"); + } + // Anthropic spec: omitted `stream` defaults to non-streaming (false). + const clientWantsStream = parsedBody.stream === true; + + const modelStr = typeof parsedBody.model === "string" ? parsedBody.model : undefined; + // Anthropic spec: omitted `stream` defaults to non-streaming (false). + // Validated: parsedBody is a plain object with messages[]. Remaining fields + // (max_tokens, tools, etc.) are forwarded as-is โ€” upstream rejects invalid shapes. + const upstreamBody = { + ...parsedBody, + model: resolveModel({ model: modelStr }, opts.config), + stream: true, + } as AnthropicMessagesRequest; + const upstreamBodyText = transformRequestBody(JSON.stringify(upstreamBody), { format: "anthropic", userId: cred.cred.userId }) ?? JSON.stringify(upstreamBody); + + // Now we're safe to take a ticket + const client = buildClient(opts, cred.credentials); + const taskId = generateTaskId(); + const ticket = await takeTicketOr502(client, taskId, opts, req.signal); + if (!ticket.ok) return ticket.response; + + const { stream, outcome } = buildBridge(opts, client, cred.credentials, upstreamBodyText, ticket.ticket, taskId, req); + void outcome; + + if (clientWantsStream) { + return new Response(stream, { status: 200, headers: sseHeaders() }); + } + + // Non-stream: chunked response with leading whitespace during wait + final JSON (B10). + // NOTE: no explicit `transfer-encoding` header โ€” it is a forbidden Response + // constructor header (runtimes drop/override it) and Node http already sends + // chunked when no content-length is set. + return new Response(nonStreamChunkedJson(stream), { + status: 200, + headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-cache" }, + }); +} + +export async function handleAsyncChat(req: Request, opts: AsyncHandlerOptions): Promise { + const cred = await resolveCredential(opts); + if (!cred.ok) return cred.response; + + const bodyResult = await readBody(req); + if (!bodyResult.ok) return bodyResult.response; + + let openaiReq: OpenAIChatRequest; + try { + openaiReq = JSON.parse(bodyResult.body) as OpenAIChatRequest; + } catch { + return errorResponse(400, "invalid_request_error", "request body is not valid JSON"); + } + if (!Array.isArray(openaiReq.messages) || openaiReq.messages.length === 0) { + return errorResponse(400, "invalid_request_error", "missing or invalid `messages` field"); + } + openaiReq.model = resolveModel(openaiReq, opts.config); + const clientWantsStream = openaiReq.stream === true; + + let anthropicReq: AnthropicMessagesRequest; + try { + anthropicReq = translateRequestOpenAIToAnthropic(openaiReq); + } catch (err) { + return errorResponse(400, "invalid_request_error", `OpenAIโ†’Anthropic translation failed: ${(err as Error).message}`); + } + anthropicReq.stream = true; + const upstreamBodyText = transformRequestBody(JSON.stringify(anthropicReq), { format: "anthropic", userId: cred.cred.userId }) ?? JSON.stringify(anthropicReq); + + const client = buildClient(opts, cred.credentials); + const taskId = generateTaskId(); + const ticket = await takeTicketOr502(client, taskId, opts, req.signal); + if (!ticket.ok) return ticket.response; + + const { stream: rawStream, outcome } = buildBridge(opts, client, cred.credentials, upstreamBodyText, ticket.ticket, taskId, req); + void outcome; + + if (clientWantsStream) { + // B4: custom translator that preserves `: keepalive` comments and converts Anthropic errors + const openaiStream = anthropicSseToOpenaiSseWithKeepalive(rawStream, openaiReq.model); + return new Response(openaiStream, { status: 200, headers: sseHeaders() }); + } + + return new Response(nonStreamChunkedJson(rawStream, { translate: "openai", model: openaiReq.model }), { + status: 200, + headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-cache" }, + }); +} + +export async function handleAsyncHealth(_req: Request, opts: AsyncHandlerOptions): Promise { + const cred = await resolveCredential(opts); + if (!cred.ok) return cred.response; + const client = buildClient(opts, cred.credentials); + try { + const avail = await client.getAvailability(); + return new Response(JSON.stringify(avail), { status: 200, headers: { "content-type": "application/json" } }); + } catch (err) { + return errorResponse(502, "async_health_failed", (err as Error).message); + } +} + +/** + * Wrap the SSE byte stream as a non-stream JSON response. Emits leading whitespace + * during ticket-queue wait (defeats client TCP idle), then a single JSON document. + * + * Two modes: + * - default: Anthropic batch JSON shape + * - {translate: "openai"}: OpenAI batch JSON shape (translated from Anthropic) + */ +function nonStreamChunkedJson( + bridgeStream: ReadableStream, + translateOpts?: { translate: "openai"; model: string }, +): ReadableStream { + const encoder = new TextEncoder(); + return new ReadableStream({ + async start(controller) { + const reader = bridgeStream.getReader(); + const decoder = new TextDecoder(); + let sseBuffer = ""; + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + // One space byte per received chunk (not per char). Resets TCP idle timer + // while keeping allocation count proportional to chunk count, not byte count. + try { + controller.enqueue(SINGLE_SPACE); + } catch { + return; + } + sseBuffer += decoder.decode(value, { stream: true }); + } + sseBuffer += decoder.decode(); + } finally { + reader.releaseLock?.(); + } + + // Reconstruct Anthropic batch JSON from accumulated SSE + const anthropicMsg = reconstructAnthropicBatch(sseBuffer); + if (!anthropicMsg) { + const errPayload = { error: { type: "async_aggregation_failed", message: "could not reconstruct response from bridge stream" } }; + try { + controller.enqueue(encoder.encode(JSON.stringify(errPayload))); + } catch { + // closed + } + controller.close(); + return; + } + + const finalJson = translateOpts?.translate === "openai" + ? JSON.stringify(translateResponseAnthropicToOpenAI(anthropicMsg, translateOpts.model)) + : JSON.stringify(anthropicMsg); + try { + controller.enqueue(encoder.encode(finalJson)); + } catch { + // closed + } + controller.close(); + }, + }); +} + +/** + * Reconstruct a synthetic `AnthropicMessagesResponse` from a stream of Anthropic SSE bytes. + * Handles message_start, content_block_start/delta/stop, message_delta, message_stop. + * + * Fail-closed: returns null if `message_stop` not seen, or on `event: error`. + * Preserves `signature_delta` for thinking blocks. No production `any`. + */ +function reconstructAnthropicBatch(sseText: string): AnthropicMessagesResponse | null { + const blocks = sseText.split("\n\n"); + type ContentBlock = + | { type: "text"; text: string } + | { type: "thinking"; thinking: string; signature?: string } + | { type: "tool_use"; id: string; name: string; input: unknown }; + let message: Partial | null = null; + const content: ContentBlock[] = []; + let currentBlock: ContentBlock | null = null; + let currentToolJson = ""; + let sawMessageStop = false; + let sawError = false; + + for (const block of blocks) { + const lines = block.split("\n"); + let eventType: string | undefined; + let data: string | undefined; + for (const line of lines) { + if (line.startsWith("event:")) eventType = line.slice(6).trim(); + else if (line.startsWith("data:")) data = line.slice(5).trim(); + } + if (!data) continue; + let parsed: Record; + try { + parsed = JSON.parse(data) as Record; + } catch { + continue; + } + + const type = (eventType ?? parsed.type) as string; + switch (type) { + case "message_start": { + const msg = parsed.message as Partial | undefined; + message = { ...(msg ?? {}) }; + break; + } + case "content_block_start": { + const cb = parsed.content_block as Partial | undefined; + if (!cb || !cb.type) break; + if (cb.type === "text") currentBlock = { type: "text", text: "" }; + else if (cb.type === "thinking") currentBlock = { type: "thinking", thinking: "" }; + else if (cb.type === "tool_use" && typeof cb.id === "string" && typeof cb.name === "string") { + currentBlock = { type: "tool_use", id: cb.id, name: cb.name, input: {} }; + currentToolJson = ""; + } + break; + } + case "content_block_delta": { + const delta = parsed.delta as Record | undefined; + if (!currentBlock || !delta) break; + if (delta.type === "text_delta" && currentBlock.type === "text" && typeof delta.text === "string") { + currentBlock.text += delta.text; + } else if (delta.type === "thinking_delta" && currentBlock.type === "thinking" && typeof delta.thinking === "string") { + currentBlock.thinking += delta.thinking; + } else if (delta.type === "signature_delta" && currentBlock.type === "thinking" && typeof delta.signature === "string") { + currentBlock.signature = (currentBlock.signature ?? "") + delta.signature; + } else if (delta.type === "input_json_delta" && currentBlock.type === "tool_use" && typeof delta.partial_json === "string") { + currentToolJson += delta.partial_json; + } + break; + } + case "content_block_stop": { + if (currentBlock) { + if (currentBlock.type === "tool_use") { + try { + currentBlock.input = JSON.parse(currentToolJson || "{}"); + } catch { + currentBlock.input = {}; + } + currentToolJson = ""; + } + content.push(currentBlock); + currentBlock = null; + } + break; + } + case "message_delta": { + const delta = parsed.delta as Partial | undefined; + const usage = parsed.usage as Record | undefined; + if (delta && message) Object.assign(message, delta); + if (usage && message) message.usage = { ...(message.usage ?? { input_tokens: 0, output_tokens: 0 }), ...usage } as AnthropicMessagesResponse["usage"]; + break; + } + case "message_stop": + sawMessageStop = true; + break; + case "error": + sawError = true; + break; + default: + // ignore ping / unknown + break; + } + } + + if (sawError || !sawMessageStop || !message) return null; + message.content = content as AnthropicMessagesResponse["content"]; + if (!message.stop_reason) message.stop_reason = "end_turn"; + if (!message.role) message.role = "assistant"; + if (!message.usage) message.usage = { input_tokens: 0, output_tokens: 0 }; + return message as AnthropicMessagesResponse; +} diff --git a/src/async/keepalive.ts b/src/async/keepalive.ts new file mode 100644 index 0000000000000000000000000000000000000000..37bedb478f7ad38a161586f5ba4596428cd08838 --- /dev/null +++ b/src/async/keepalive.ts @@ -0,0 +1,88 @@ +/** + * SSE keepalive stream generator. + * + * Emits pure SSE comment frames (`: keepalive\n\n`) at a fixed interval. + * Used by the async bridge to keep the client connection alive during + * ticket-queue wait โ€” comment frames are universally ignored by spec-compliant + * SSE clients (OpenAI / Anthropic SDKs) but reset their idle-timeout timers. + * + * Never emits `data:` frames โ€” those carry semantic events and would confuse + * strict SDK parsers (e.g. `@ai-sdk/anthropic` zod schemas throw on unknown + * `type` values, killing the stream โ€” see plan ยง3.6 anti-pattern #1). + */ + +export interface KeepaliveOptions { + /** Interval between comment frames in ms. */ + intervalMs: number; + /** Comment text. Default `"keepalive"`. Must not contain newlines. */ + text?: string; + /** External abort โ€” when fired, the stream closes gracefully. */ + signal?: AbortSignal; +} + +/** + * Build a `ReadableStream` that emits `: ${text}\n\n` every + * `intervalMs`. The stream closes when `signal` aborts. Text encoder is + * reused across frames; the underlying buffer is fresh per emit. + * + * Cadence guarantee: first emit happens after `intervalMs` (NOT immediately) + * so callers can compose with upstream-output streams without a leading comment. + */ +export function keepaliveStream(opts: KeepaliveOptions): ReadableStream { + const text = (opts.text ?? "keepalive").replace(/[\r\n]/g, " "); + const frame = new TextEncoder().encode(`: ${text}\n\n`); + let timer: ReturnType | undefined; + let aborted = false; + + return new ReadableStream({ + start(controller) { + if (opts.signal) { + if (opts.signal.aborted) { + aborted = true; + controller.close(); + return; + } + opts.signal.addEventListener("abort", () => { + aborted = true; + if (timer) { + clearTimeout(timer); + timer = undefined; + } + try { controller.close(); } catch { /* already closed */ } + }, { once: true }); + } + + const tick = (): void => { + if (aborted) return; + try { + controller.enqueue(frame); + } catch { + // Controller closed by consumer; stop the timer. + if (timer) { + clearTimeout(timer); + timer = undefined; + } + return; + } + timer = setTimeout(tick, opts.intervalMs); + }; + timer = setTimeout(tick, opts.intervalMs); + }, + cancel() { + aborted = true; + if (timer) { + clearTimeout(timer); + timer = undefined; + } + }, + }); +} + +/** + * Emit a single immediate keepalive frame as a `Uint8Array`. + * Useful for flushing one frame before pausing on a long upstream call. + */ +export function keepaliveFrame(text: string = "keepalive"): Uint8Array { + const clean = text.replace(/[\r\n]/g, " "); + return new TextEncoder().encode(`: ${clean}\n\n`); +} diff --git a/src/async/openai-stream-adapter.ts b/src/async/openai-stream-adapter.ts new file mode 100644 index 0000000000000000000000000000000000000000..1d8e4fa9f73062d2c3b4eb1010f138db1b7c3231 --- /dev/null +++ b/src/async/openai-stream-adapter.ts @@ -0,0 +1,135 @@ +/** + * OpenAI SSE stream adapter for the async path. + * + * Single persistent state machine for the whole stream โ€” preserves message ID, + * usage, tool-call index mapping, and finish state across events. Re-using the + * same translation state is what the existing `anthropicSseToOpenaiSse` does; + * we add two extra concerns for the async bridge: + * + * 1. Preserve `: keepalive` comments (the existing translator drops them). + * Comments are the only queue-wait liveness signal; dropping them defeats + * the bridge design. + * 2. Convert Anthropic `event: error` events to OpenAI + * `data: {"error":...}` + terminal `[DONE]`. The existing translator + * silently drops Anthropic errors, which would mask permanent bridge + * failures as a clean `[DONE]`. + * + * Anti-pattern: NEVER create a fresh translator per event. State (messageId, + * toolCallIndex, finishReasonSent, usage) must persist across the whole stream + * or downstream clients see inconsistent IDs, missing tool arguments, and + * duplicate finish reasons. + */ +import { initState, parseSSEChunk, translateEvent, SSE_FRAME_SPLIT, type TranslationState, type ParsedSSE } from "../translator/sse-translator.js"; + +export function anthropicSseToOpenaiSseWithKeepalive( + upstream: ReadableStream, + model: string = "glm-4.6", +): ReadableStream { + const encoder = new TextEncoder(); + const decoder = new TextDecoder(); + const state: TranslationState = initState(model); + let doneSent = false; + let errored = false; + + function emit(out: string): void { + if (errored) return; + try { + controller0.enqueue(encoder.encode(out)); + } catch { + // controller closed by consumer + } + } + + // Hoisted controller reference so `emit()` can be defined above the ReadableStream + // constructor without forward-let noise. + let controller0: ReadableStreamDefaultController; + + return new ReadableStream({ + start(controller) { + controller0 = controller; + const reader = upstream.getReader(); + let buffer = ""; + + reader.read().then(function pump({ done, value }): Promise | undefined { + if (done) { + // Flush trailing buffer + if (buffer.trim()) processBlock(buffer, state); + buffer = ""; + emitDone(); + try { controller.close(); } catch {} + return; + } + buffer += decoder.decode(value, { stream: true }); + const blocks = buffer.split(SSE_FRAME_SPLIT); + buffer = blocks.pop() ?? ""; + for (const block of blocks) { + processBlock(block, state); + if (errored) { + try { controller.close(); } catch {} + return; + } + } + return reader.read().then(pump); + }).catch((err) => { + if (!errored) { + const errPayload = JSON.stringify({ error: { message: `async stream error: ${(err as Error).message}`, type: "server_error" } }); + emit(`data: ${errPayload}\n\n`); + emitDone(); + } + try { controller.close(); } catch {} + }).finally(() => { + reader.releaseLock?.(); + }); + }, + }); + + function processBlock(block: string, st: TranslationState): void { + const trimmed = block.trim(); + if (trimmed === "") return; + + // Pure comment frame โ€” pass through unchanged + if (trimmed.startsWith(":")) { + emit(block + "\n\n"); + return; + } + + // Detect Anthropic error event before parseSSEChunk would silently drop it + // (parseSSEChunk only returns events with data; error events have data too, + // but the existing translateEvent doesn't handle `type:"error"`). + if (trimmed.startsWith("event: error") || trimmed.startsWith("event:error")) { + const dataLine = block.split("\n").find((l) => l.startsWith("data:")); + let anthropicMsg = "unknown error"; + let anthropicType = "api_error"; + if (dataLine) { + try { + const data = JSON.parse(dataLine.slice(5).trim()); + if (data?.error?.message) anthropicMsg = String(data.error.message); + if (data?.error?.type) anthropicType = String(data.error.type); + } catch { + // leave defaults + } + } + const oaiPayload = JSON.stringify({ error: { message: anthropicMsg, type: anthropicType } }); + emit(`data: ${oaiPayload}\n\n`); + emitDone(); + errored = true; + return; + } + + // Standard Anthropic event โ€” parse + translate using shared state. + const parsed = parseSSEChunk(block); + for (const p of parsed) { + const out = translateEvent(st, p); + if (out) emit(out); + } + } + + function emitDone(): void { + if (doneSent) return; + doneSent = true; + emit("data: [DONE]\n\n"); + } +} + +// Re-export for tests +export type { ParsedSSE, TranslationState }; diff --git a/src/async/types.ts b/src/async/types.ts new file mode 100644 index 0000000000000000000000000000000000000000..0ca42af3bffdf72196e49edee048559863a41f49 --- /dev/null +++ b/src/async/types.ts @@ -0,0 +1,101 @@ +/** + * Async (off-peak) types: ticket states, server response shapes, error classes. + * + * Server-side response fields are snake_case (e.g. `ticket_id`, `next_poll_after`). + * The client converts them to camelCase on the way out; callers never see the + * raw server shape. + * + * @see _reverse/NOTEPAD.md "Off-Peak / Idle Plan" section for upstream protocol. + */ + +/** Ticket lifecycle states reported by the server. */ +export type TicketState = "queued" | "ready" | "active" | "settled" | "expired" | "not_found"; + +/** Non-terminal states โ€” ticket may still become `ready`. */ +export const TICKET_PENDING_STATES: readonly TicketState[] = ["queued"] as const; +/** Terminal states โ€” no further transitions; ticket can be settled. */ +export const TICKET_TERMINAL_STATES: readonly TicketState[] = ["settled", "expired", "not_found"] as const; + +export function isTicketReady(s: TicketState): boolean { + return s === "ready" || s === "active"; +} + +export function isTicketExpired(s: TicketState): boolean { + return s === "expired" || s === "not_found"; +} + +/** Result of `GET /ticket/availability`. */ +export interface AvailabilityResult { + canTakeNumber: boolean; + /** Unix seconds โ€” earliest time the user can retry taking a number. Present when `canTakeNumber === false`. */ + nextTakeAt?: number; +} + +/** Result of `POST /ticket` (take a number). */ +export interface TakeTicketResult { + ticketId: string; + state: TicketState; + /** Queue position (1-indexed). Present while `state === "queued"`. */ + position?: number; + /** Server-suggested next poll delay in ms. Present when server has a backoff recommendation. */ + nextPollAfterMs?: number; + /** Local timestamp (ms) when the ticket was registered. */ + registeredAt: number; +} + +/** Status of a single ticket from `POST /ticket/status`. */ +export interface TicketStatusResult { + ticketId: string; + state: TicketState; + position?: number; + /** Unix seconds โ€” deadline by which the client must use a `ready` ticket. Present on `ready`. */ + activeDeadline?: number; +} + +/** Result of `POST /ticket/status` (batch poll). */ +export interface BatchStatusResult { + /** Server-suggested next poll delay in ms (applies to all returned tickets). */ + nextPollAfterMs?: number; + tickets: TicketStatusResult[]; +} + +/** Credentials needed to authenticate with the off-peak backend. */ +export interface OffPeakCredentials { + /** ZCode plan JWT โ€” goes in `Authorization: Bearer ${jwt}`. Source: `Credential.jwt`. */ + jwt: string; + /** Coding-plan API key โ€” goes in `X-Coding-Plan-Api-Key`. Source: `Credential.apiKey`. */ + codingPlanApiKey: string; + /** Optional Bigmodel-team org/project headers. */ + bigmodelOrganization?: string; + bigmodelProject?: string; +} + +/** HTTP-status-bearing error from the off-peak server. */ +export class OffPeakServerError extends Error { + readonly httpStatus: number; + readonly bizCode?: string; + constructor(message: string, httpStatus: number, bizCode?: string) { + super(message); + this.name = "OffPeakServerError"; + this.httpStatus = httpStatus; + this.bizCode = bizCode; + } +} + +/** Thrown when credentials lack the JWT required for off-peak auth. */ +export class OffPeakCredentialsUnavailableError extends Error { + constructor(message: string = "off-peak requires a logged-in oauth credential (jwt missing)") { + super(message); + this.name = "OffPeakCredentialsUnavailableError"; + } +} + +/** Detects the upstream "off-peak-ticket-expired" error signal in any error message. */ +export function isOffPeakTicketExpiredError(e: unknown): boolean { + if (e == null) return false; + if (typeof e === "string") return e.includes("off-peak-ticket-expired"); + if (e instanceof Error) { + return e.message.includes("off-peak-ticket-expired") || e.name === "OffPeakTicketExpiredError"; + } + return false; +} diff --git a/src/auth/jwt-age.ts b/src/auth/jwt-age.ts new file mode 100644 index 0000000000000000000000000000000000000000..84f41bb6cd3c49644f6644c81120f2a58510019f --- /dev/null +++ b/src/auth/jwt-age.ts @@ -0,0 +1,39 @@ +/** + * JWT age inspection for the stored start-plan token. + * + * Informational only: the token payload carries `iat` but no `exp`, and the + * billing gateway does NOT reject by age โ€” an 8-day-old JWT still serves + * `billing/balance` (verified live). Re-login is only needed when the gateway + * actually returns 401 / 3012. The age is surfaced so operators can see how + * fresh the credential is. + */ +export interface JwtInfo { + /** Unix seconds when the token was issued. */ + iat: number; + /** Token age in hours at the time of inspection. */ + ageHours: number; + userId?: string; +} + +/** Decode a zcode-plan JWT payload without verifying the signature. */ +export function inspectJwt(jwt: string): JwtInfo | null { + const parts = jwt.split("."); + if (parts.length !== 3) return null; + try { + const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/"); + const pad = b64.length % 4 === 0 ? "" : "=".repeat(4 - (b64.length % 4)); + const payload = JSON.parse(Buffer.from(b64 + pad, "base64").toString("utf8")) as { + iat?: number; + user_id?: string; + sub?: string; + }; + if (typeof payload.iat !== "number") return null; + return { + iat: payload.iat, + ageHours: Math.max(0, (Date.now() / 1000 - payload.iat) / 3600), + ...(payload.user_id ? { userId: payload.user_id } : {}), + }; + } catch { + return null; + } +} diff --git a/src/auth/manager.ts b/src/auth/manager.ts new file mode 100644 index 0000000000000000000000000000000000000000..c6264b9192b988e9083d3e26a9a08a0ebba72e52 --- /dev/null +++ b/src/auth/manager.ts @@ -0,0 +1,39 @@ +/** + * Auth manager โ€” resolves the upstream credential from the OAuth login flow. + * @see .omo/plans/zcode-proxy.md Task 4 + */ +import type { Credential } from "./types.js"; + +/** + * Resolves the upstream credential to inject into proxied requests. + * + * The credential comes from `auth login` and is injected via + * {@link setOAuthCredential} at startup (and re-loaded on Android's + * `startProxy` so a fresh login after restart is picked up). + */ +export class AuthManager { + private oauthCred: Credential | null = null; + + /** + * Returns the current credential or throws when none is stored. + * + * There is no proactive refresh: the login flows never populate + * `expiresAt`, so expiry surfaces as an upstream 401, not here. The guard + * below is retained for the day a flow starts filling `expiresAt`. + */ + async getCredential(): Promise { + if (this.oauthCred) { + if (this.oauthCred.expiresAt && Date.now() >= this.oauthCred.expiresAt) { + this.oauthCred = null; + throw new Error("OAuth credential expired; re-authentication required โ€” run: zcode-proxy auth login"); + } + return this.oauthCred; + } + throw new Error("OAuth credential not available โ€” run: zcode-proxy auth login"); + } + + /** Set the OAuth credential (used by the `auth login` flow). */ + setOAuthCredential(cred: Credential): void { + this.oauthCred = cred; + } +} diff --git a/src/auth/oauth.ts b/src/auth/oauth.ts new file mode 100644 index 0000000000000000000000000000000000000000..88b4eda4554368f0a88db818a92b6f9ae5fab449 --- /dev/null +++ b/src/auth/oauth.ts @@ -0,0 +1,575 @@ +/** + * OAuth flow handlers for Z.AI and Bigmodel. + * + * The two providers use **different flows** (verified against the ZCode 3.10 + * desktop bundle `loginZCodeCli` / `loginBigmodelCodingPlan`, and live-probed + * 2026-08-29): + * + * - Z.AI: **server-mediated CLI login**. The client POSTs `{provider:"zai"}` to + * `zcode.z.ai/api/v1/oauth/cli/init` and gets back a server-generated + * authorize URL whose redirect_uri is zcode.z.ai's OWN callback + * (`/api/v1/oauth/cli/callback/zai`) โ€” NOT localhost. After the user + * authorizes in the browser, the client polls `/oauth/cli/poll/{flow_id}` + * until the server reports `ready` with the tokens. No local callback server + * exists for Z.AI. Building the old 3.1.x-style direct chat.z.ai authorize + * URL with a localhost redirect_uri is rejected upstream with + * `{"detail":"Redirect URI not registered for this client"}`. + * - Bigmodel: **classic auth-code flow** โ€” local callback server on 127.0.0.1, + * authorize at `bigmodel.cn/login?appId&redirect&state`, then exchange the + * returned code at the shared zcode.z.ai token endpoint. + * + * @see _reverse/NOTEPAD.md "Method 1: OAuth Flow" + */ +import type { ProviderId } from "../provider/types.js"; +import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http"; +import { randomBytes } from "node:crypto"; + +// --------------------------------------------------------------------------- +// Constants (from bundle) +// --------------------------------------------------------------------------- + +/** zcode.z.ai API base (bundle `A3o`; cli-login + token endpoints hang off it). */ +const ZCODE_API_BASE = "https://zcode.z.ai/api/v1"; +/** Shared token-exchange endpoint (bigmodel auth-code flow). Bundle: `tokenUrl`. */ +const ZCODE_TOKEN_ENDPOINT = `${ZCODE_API_BASE}/oauth/token`; +/** Default Bigmodel authorize host (bundle `BIGMODEL_OAUTH_AUTHORIZE_URL`). */ +const BIGMODEL_HOST = "https://bigmodel.cn"; +/** Default Bigmodel app id (bundle `BIGMODEL_OAUTH_APP_ID`). */ +const BIGMODEL_APP_ID = "zcode"; + +/** Overall login timeout shared by both flows (bundle `tln`). */ +export const LOGIN_TIMEOUT_MS = 300_000; + +// --------------------------------------------------------------------------- +// Shared types +// --------------------------------------------------------------------------- + +export interface OAuthResult { + accessToken: string; + provider: ProviderId; + /** Upstream user identifier, when the OAuth response included one. Passed through to `metadata.user_id` on Anthropic-format requests. */ + userId?: string; + /** ZCode plan JWT for start-plan (zcode.z.ai). The token-exchange response includes this alongside the provider access_token. */ + jwt?: string; +} + +export type FetchFn = typeof fetch; + +/** Flow handle returned by `start()`. */ +export interface OAuthFlowStart { + authorizeUrl: string; + /** Local callback URL when the flow uses one (bigmodel); `""` otherwise (zai cli flow). */ + callbackUrl: string; + /** CSRF state (auth-code) / server flow_id (zai cli flow) โ€” opaque bookkeeping. */ + state: string; +} + +/** Credentials produced by a completed flow, pre-`KeyResolver`. */ +export interface OAuthFlowTokens { + accessToken: string; + userId?: string; + jwt?: string; +} + +/** Shape of the zcode.z.ai `{code, data, msg}` envelope (token + cli-login endpoints). */ +interface ZcodeEnvelope { + code?: number; + data?: unknown; + msg?: string; +} + +// --------------------------------------------------------------------------- +// Shared flow base +// --------------------------------------------------------------------------- + +/** + * Common lifecycle for both login flows: `start()` produces the authorize URL, + * `complete()` blocks until the flow finishes (callback redirect or server + * poll), `authorize()` chains them for the CLI. `src/android/control.ts` + * drives `start()` + `complete()` so the authorize URL can be surfaced to the + * app while completion continues in the background. + */ +export abstract class OAuthFlowClient { + constructor( + readonly provider: ProviderId, + protected readonly fetchImpl: FetchFn, + ) {} + + abstract start(): Promise; + abstract complete(started: OAuthFlowStart, timeoutMs?: number): Promise; + abstract close(): Promise; + + /** Run the full flow end-to-end: surface authorize URL, wait, close. */ + async authorize( + onAuthorizeUrl?: (url: string) => void, + timeoutMs: number = LOGIN_TIMEOUT_MS, + ): Promise { + const started = await this.start(); + onAuthorizeUrl?.(started.authorizeUrl); + try { + const tokens = await this.complete(started, timeoutMs); + return { accessToken: tokens.accessToken, provider: this.provider, userId: tokens.userId, jwt: tokens.jwt }; + } finally { + await this.close(); + } + } +} + +/** + * POST/GET a zcode.z.ai endpoint and unwrap the `{code, data, msg}` envelope + * (mirrors the bundle's `H2r`: numeric code required, non-2xx or `code !== 0` + * surfaces the server `msg`). + */ +async function requestZcodeEnvelope( + fetchImpl: FetchFn, + url: string, + init: RequestInit, + label: string, +): Promise { + const resp = await fetchImpl(url, init); + const raw = safeJsonParse(await resp.text()) as ZcodeEnvelope | null; + if (!raw || typeof raw.code !== "number") { + throw new Error(`${label}: invalid response envelope (status=${resp.status})`); + } + if (!resp.ok || raw.code !== 0) { + throw new Error(`${label} failed: status=${resp.status} msg=${raw.msg ?? "(none)"}`); + } + return raw.data; +} + +// --------------------------------------------------------------------------- +// Z.AI โ€” server-mediated CLI login (init + poll, no local callback) +// --------------------------------------------------------------------------- + +/** `data` of a successful `/oauth/cli/init` call (bundle `D3o`). */ +interface ZaiCliInitData { + flow_id: string; + /** Server-issued poll token; informational โ€” poll re-sends the client Bearer. */ + poll_token: string; + authorize_url: string; + /** Unix seconds. */ + expires_at: number; + poll_interval_sec: number; +} + +/** `data` of a `/oauth/cli/poll/{flow_id}` call: pending/failed, or ready (bundle `N3o`/`L3o`). */ +interface ZaiCliPollData { + status: string; + token?: string; + user?: { user_id?: unknown }; + zai?: { access_token?: unknown }; +} + +/** + * Z.AI login client, mirroring ZCode 3.10 `loginZCodeCli`: + * + * 1. Generate a client poll token (32 random bytes, hex) โ€” sent as + * `Authorization: Bearer` on BOTH init and poll. + * 2. `POST {ZCODE_API_BASE}/oauth/cli/init` body `{provider:"zai"}` โ†’ + * `{flow_id, poll_token, authorize_url, expires_at, poll_interval_sec}`. + * 3. Open the server-provided `authorize_url` (its redirect_uri is + * zcode.z.ai's own `/oauth/cli/callback/zai` โ€” the browser never comes + * back to localhost). + * 4. `GET {ZCODE_API_BASE}/oauth/cli/poll/{flow_id}` every + * `poll_interval_sec` until `status:"ready"` โ†’ `{token, user, zai}` โ€” + * or `"failed"`, or the `expires_at`/timeout deadline passes. + */ +export class ZaiOAuthClient extends OAuthFlowClient { + private flow: ZaiCliInitData | null = null; + private pollToken = ""; + + constructor( + fetchImpl: FetchFn = fetch, + /** Injectable pause between polls (tests pass a no-op). */ + private readonly sleep: (ms: number) => Promise = defaultSleep, + ) { + super("zai", fetchImpl); + } + + start(): Promise { + this.flow = null; + this.pollToken = randomBytes(32).toString("hex"); + return (async () => { + const data = (await requestZcodeEnvelope( + this.fetchImpl, + `${ZCODE_API_BASE}/oauth/cli/init`, + { + method: "POST", + headers: { authorization: `Bearer ${this.pollToken}`, "content-type": "application/json" }, + body: JSON.stringify({ provider: this.provider }), + }, + "Z.AI login init", + )) as Partial | null; + if ( + !data || + typeof data.flow_id !== "string" || + typeof data.authorize_url !== "string" || + typeof data.expires_at !== "number" || + typeof data.poll_interval_sec !== "number" + ) { + throw new Error("Z.AI login init: invalid response data"); + } + this.flow = data as ZaiCliInitData; + return { authorizeUrl: this.flow.authorize_url, callbackUrl: "", state: this.flow.flow_id }; + })(); + } + + async complete(_started: OAuthFlowStart, timeoutMs: number = LOGIN_TIMEOUT_MS): Promise { + const flow = this.flow; + if (!flow) throw new Error("Z.AI login not started"); + const deadlineMs = Math.min(Date.now() + timeoutMs, flow.expires_at * 1000); + const intervalMs = Math.max(1_000, flow.poll_interval_sec * 1000); + + for (;;) { + if (Date.now() >= deadlineMs) { + throw new Error("Authorization timed out. Please retry login."); + } + const data = (await requestZcodeEnvelope( + this.fetchImpl, + `${ZCODE_API_BASE}/oauth/cli/poll/${encodeURIComponent(flow.flow_id)}`, + { method: "GET", headers: { authorization: `Bearer ${this.pollToken}` } }, + "Z.AI login poll", + )) as Partial | null; + + if (data?.status === "ready") { + const accessToken = typeof data.zai?.access_token === "string" ? data.zai.access_token.trim() : ""; + if (!accessToken) { + throw new Error("Z.AI login poll: response missing data.zai.access_token"); + } + return { + accessToken, + jwt: typeof data.token === "string" ? data.token.trim() : undefined, + userId: typeof data.user?.user_id === "string" ? data.user.user_id : undefined, + }; + } + if (data?.status === "failed") { + throw new Error("Authorization failed. Please retry login."); + } + if (data?.status !== "pending") { + throw new Error(`Z.AI login poll: unexpected status ${String(data?.status ?? "(none)")}`); + } + await this.sleep(Math.min(intervalMs, Math.max(0, deadlineMs - Date.now()))); + } + } + + async close(): Promise { + this.flow = null; + } +} + +// --------------------------------------------------------------------------- +// Bigmodel โ€” classic auth-code flow with a localhost callback server +// --------------------------------------------------------------------------- + +/** + * Per-provider auth-code configuration (Bigmodel only since Z.AI moved to the + * cli login flow). + */ +interface AuthCodeConfig { + readonly provider: ProviderId; + /** Base authorize URL (`?appId=&redirect=&state=` appended). */ + readonly authorizeUrl: string; + readonly appId: string; + /** Shared zcode.z.ai token-exchange endpoint. */ + readonly tokenUrl: string; + /** Path served by the localhost callback server. */ + readonly callbackPath: string; + /** Key under `data` holding the provider access token: `data[field].access_token`. */ + readonly accessTokenField: string; +} + +/** Shape of the zcode.z.ai token-exchange response (`{code, data, msg}`). */ +interface TokenExchangeResponse { + code?: number; + data?: { + token?: string; + user?: { user_id?: string }; + } & Record; + msg?: string; +} + +/** + * Auth-code OAuth client: localhost callback server + token exchange. + * + * Flow (mirrors the ZCode desktop `loginBigmodelCodingPlan`): + * 1. Start localhost HTTP server on a random port + * 2. Build authorize URL: `{authorizeUrl}?appId={appId}&redirect={localhost}&state={state}` + * 3. User opens the URL, authorizes on the provider's site + * 4. Provider redirects to localhost callback with `?authCode=...&state=...` + * 5. POST `{tokenUrl}` body `{provider, code, redirect_uri, state}` + * 6. zcode.z.ai exchanges (holding the app secret server-side) and returns + * `{code:0, data:{token:, :{access_token}, user:{user_id}}}` + */ +export class AuthCodeOAuthClient extends OAuthFlowClient { + private server: Server | null = null; + private callbackResult: { code: string; error: string | null } | null = null; + private callbackWaiters: Array<(result: { code: string; error: string | null }) => void> = []; + + constructor( + config: AuthCodeConfig, + fetchImpl: FetchFn = fetch, + ) { + super(config.provider, fetchImpl); + this.config = config; + } + + private readonly config: AuthCodeConfig; + + /** Build the provider authorize URL with the localhost redirect + state. */ + protected buildAuthorizeUrl(callbackUrl: string, state: string): string { + const params = new URLSearchParams({ + appId: this.config.appId, + redirect: callbackUrl, + state, + }); + return `${this.config.authorizeUrl}?${params.toString()}`; + } + + /** + * Start the localhost callback server and return the authorize URL. + * Call `waitForCallback()` (or `authorize()`) afterwards, then `close()`. + * + * The bind port is `0` (OS-assigned random) unless the env var + * `ZCODE_OAUTH_CALLBACK_PORT` is set, in which case that exact port is used. + * The Android entry sets the env var so the Custom Tabs redirect URL is + * predictable across launches. + */ + start(): Promise { + const state = randomBytes(32).toString("hex"); + const requestedPort = Number(process.env.ZCODE_OAUTH_CALLBACK_PORT ?? 0) || 0; + + return new Promise((resolve, reject) => { + this.server = createServer((req: IncomingMessage, res: ServerResponse) => { + this.handleCallback(req, res, state); + }); + + this.server.on("error", (err) => { + this.server = null; + reject(err); + }); + this.server.listen(requestedPort, "127.0.0.1", () => { + const addr = this.server!.address(); + if (!addr || typeof addr !== "object") { + reject(new Error("Failed to bind localhost callback server")); + return; + } + const callbackUrl = `http://127.0.0.1:${addr.port}${this.config.callbackPath}`; + const authorizeUrl = this.buildAuthorizeUrl(callbackUrl, state); + resolve({ authorizeUrl, callbackUrl, state }); + }); + }); + } + + private handleCallback(req: IncomingMessage, res: ServerResponse, expectedState: string): void { + const url = new URL(req.url ?? "/", "http://127.0.0.1"); + if (url.pathname !== this.config.callbackPath) { + res.writeHead(404, { "Content-Type": "text/plain" }); + res.end("Not found"); + return; + } + + const state = url.searchParams.get("state") ?? ""; + const code = url.searchParams.get("authCode") ?? url.searchParams.get("code") ?? ""; + + if (state !== expectedState || !code) { + res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" }); + res.end("Authorization failed: state mismatch or missing code."); + if (!this.callbackResult) { + this.callbackResult = { code: "", error: "OAuth callback state mismatch or missing code." }; + this.callbackWaiters.forEach((fn) => fn(this.callbackResult!)); + } + return; + } + + res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" }); + res.end("Authorization successful! You may close this window and return to the CLI."); + + if (!this.callbackResult) { + this.callbackResult = { code, error: null }; + this.callbackWaiters.forEach((fn) => fn(this.callbackResult!)); + } + } + + /** Wait for the OAuth callback redirect. Resolves with the auth code. */ + waitForCallback(timeoutMs: number = LOGIN_TIMEOUT_MS): Promise { + if (this.callbackResult?.code) { + return Promise.resolve(this.callbackResult.code); + } + if (this.callbackResult?.error) { + return Promise.reject(new Error(this.callbackResult.error)); + } + + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + reject(new Error("Authorization timed out. Please retry login.")); + }, timeoutMs); + + this.callbackWaiters.push((result) => { + clearTimeout(timer); + if (result.error) { + reject(new Error(result.error)); + } else { + resolve(result.code); + } + }); + }); + } + + /** + * Exchange the auth code at the shared zcode.z.ai token endpoint. + * The ZCode server holds the app secret and performs the real provider exchange. + * Returns `{ accessToken, userId, jwt }`. + */ + async exchangeCode( + authCode: string, + redirectUri: string, + state: string, + ): Promise { + const resp = await this.fetchImpl(this.config.tokenUrl, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ + provider: this.config.provider, + code: authCode, + redirect_uri: redirectUri, + state, + }), + }); + + const raw = safeJsonParse(await resp.text()) as TokenExchangeResponse | null; + + if (!resp.ok || (raw && typeof raw.code === "number" && raw.code !== 0)) { + const label = this.config.provider; + throw new Error( + `${label} token exchange failed: status=${resp.status} msg=${raw?.msg ?? "(none)"}`, + ); + } + + const providerToken = raw?.data?.[this.config.accessTokenField] as + | { access_token?: string } + | undefined; + const accessToken = providerToken?.access_token?.trim() ?? ""; + + if (!accessToken) { + throw new Error(`${this.config.provider} token response missing data.${this.config.accessTokenField}.access_token`); + } + + const userId = raw?.data?.user?.user_id; + const jwt = raw?.data?.token?.trim() ?? undefined; + return { accessToken, userId: typeof userId === "string" ? userId : undefined, jwt }; + } + + /** Wait for the browser callback, then exchange the code. */ + async complete(started: OAuthFlowStart, timeoutMs: number = LOGIN_TIMEOUT_MS): Promise { + const code = await this.waitForCallback(timeoutMs); + return this.exchangeCode(code, started.callbackUrl, started.state); + } + + async close(): Promise { + if (this.server) { + const server = this.server; + this.server = null; + // Drop idle keep-alive connections so the port is released immediately + // (plain close() would wait for them to time out). + server.closeAllConnections?.(); + await new Promise((resolve) => { + server.close(() => resolve()); + }); + } + } +} + +// --------------------------------------------------------------------------- +// Provider clients +// --------------------------------------------------------------------------- + +/** + * Bigmodel auth-code config. + * Bundle `ed`: authorizeUrl `bigmodel.cn/login`, appId `zcode`, + * token field `data.bigmodel.access_token`. + */ +const BIGMODEL_AUTH_CODE_CONFIG: AuthCodeConfig = { + provider: "bigmodel", + authorizeUrl: `${BIGMODEL_HOST}/login`, + appId: BIGMODEL_APP_ID, + tokenUrl: ZCODE_TOKEN_ENDPOINT, + callbackPath: "/oauth/callback/bigmodel", + accessTokenField: "bigmodel", +}; + +/** + * Bigmodel OAuth client (auth-code flow via bigmodel.cn + zcode.z.ai token + * exchange). `host`/`appId` are overridable to mirror the bundle's env vars + * (`BIGMODEL_OAUTH_AUTHORIZE_URL`, `BIGMODEL_OAUTH_APP_ID`). + */ +export class BigmodelOAuthClient extends AuthCodeOAuthClient { + constructor( + fetchImpl: FetchFn = fetch, + host: string = BIGMODEL_HOST, + appId: string = BIGMODEL_APP_ID, + ) { + super( + { ...BIGMODEL_AUTH_CODE_CONFIG, authorizeUrl: `${host}/login`, appId }, + fetchImpl, + ); + } +} + +// --------------------------------------------------------------------------- +// Headless paste login (auth-code flow) +// --------------------------------------------------------------------------- + +/** + * Parse a callback URL the user pasted back into the terminal (headless + * `--paste` login, mirroring gcloud/gh CLI). Only the query string is + * inspected โ€” the pathname/host are whatever the browser's address bar shows + * and are never validated. Tolerates copy artifacts from web pages: wrapping + * quotes/brackets, surrounding whitespace, and `&` entities (a paste from + * a rendered page splits the query at the `&` inside `&`, which breaks + * `state`). Returns the auth code (`authCode` or `code` param); throws on a + * CSRF `state` mismatch or a missing code. + */ +export function parsePastedCallbackUrl(raw: string, expectedState: string): string { + let text = raw.trim().replace(/^["'`<([{]+/, "").replace(/["'`>\])}]+$/, ""); + text = text.replace(/&/gi, "&"); + + const q = text.indexOf("?"); + const query = (q >= 0 ? text.slice(q + 1) : text).split("#")[0]; + const params = new URLSearchParams(query); + + const state = params.get("state") ?? ""; + if (!state || state !== expectedState) { + throw new Error( + "OAuth state mismatch โ€” the pasted URL does not belong to this login " + + "session (possible CSRF). Retry the login.", + ); + } + + const providerError = params.get("error"); + const code = params.get("authCode") ?? params.get("code") ?? ""; + if (!code) { + throw new Error( + providerError + ? `Authorization failed: provider returned error=${providerError}` + : "No authorization code in the pasted URL โ€” paste the redirected " + + "127.0.0.1 callback URL (the one that failed to load), not the authorize URL.", + ); + } + return code; +} + +// --------------------------------------------------------------------------- +// Utility +// --------------------------------------------------------------------------- + +function defaultSleep(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +function safeJsonParse(text: string): unknown { + try { + return JSON.parse(text); + } catch { + return null; + } +} diff --git a/src/auth/resolver.ts b/src/auth/resolver.ts new file mode 100644 index 0000000000000000000000000000000000000000..06adf1b4327d45eaa8e17287cbf12b10cf7895de --- /dev/null +++ b/src/auth/resolver.ts @@ -0,0 +1,170 @@ +import type { Credential } from "./types.js"; +import type { ProviderId } from "../provider/types.js"; +import type { FetchFn } from "./oauth.js"; + +const ZAI_API_KEY_NAME = "zcode-api-key"; +const DEFAULT_ORG_MARKER = "\u9ED8\u8BA4\u673A\u6784"; // ้ป˜่ฎคๆœบๆž„ +const DEFAULT_PROJECT_MARKER = "\u9ED8\u8BA4\u9879\u76EE"; // ้ป˜่ฎค้กน็›ฎ + +async function requestBizApi( + fetchImpl: FetchFn, + url: string, + authorization: string, + init?: RequestInit, +): Promise { + const resp = await fetchImpl(url, { + ...init, + headers: { + Authorization: authorization, + "Content-Type": "application/json", + ...(init?.headers ?? {}), + }, + }); + if (!resp.ok) { + throw new Error(`Biz API ${url} failed: ${resp.status}`); + } + const body = await resp.json(); + const code = body.code ?? body.status; + if (code != null && code !== 0 && code !== 200 && code !== "0" && code !== "200") { + throw new Error(body.msg ?? `Biz API error ${code}`); + } + return body.data ?? body; +} + +export class KeyResolver { + constructor(private fetchImpl: FetchFn = fetch) {} + + async resolveZaiBizToken(accessToken: string): Promise { + const resp = await this.fetchImpl("https://api.z.ai/api/auth/z/login", { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ token: accessToken }), + }); + if (!resp.ok) { + throw new Error(`z/login failed: ${resp.status}`); + } + const data = await resp.json(); + const token = data.access_token ?? data.accessToken ?? data.data?.access_token; + // Shape guard: silently returning undefined used to store a bogus + // credential that surfaced only as cryptic upstream 401s. + if (typeof token !== "string" || token.length === 0) { + throw new Error("z/login returned unexpected shape: access_token missing or empty"); + } + return token; + } + + async resolveCustomerInfo( + host: string, + authorization: string, + ): Promise<{ orgId: string; projectId: string }> { + const data = await requestBizApi( + this.fetchImpl, + `${host}/api/biz/customer/getCustomerInfo`, + authorization, + { method: "GET" }, + ); + + const orgs: any[] = data.organizations ?? data.orgs ?? []; + if (!Array.isArray(orgs) || orgs.length === 0) { + throw new Error("No organizations found"); + } + const org = orgs.find((o) => + (o.organizationName ?? o.name ?? "").includes(DEFAULT_ORG_MARKER), + ) ?? orgs[0]; + const orgId = org.organizationId ?? org.id ?? org.orgId; + + const projects: any[] = org.projects ?? []; + if (!Array.isArray(projects) || projects.length === 0) { + throw new Error("No projects found in default organization"); + } + const project = projects.find((p) => + (p.projectName ?? p.name ?? "").includes(DEFAULT_PROJECT_MARKER), + ) ?? projects[0]; + const projectId = project.projectId ?? project.id; + + return { orgId, projectId }; + } + + async findOrCreateApiKey( + host: string, + authorization: string, + orgId: string, + projectId: string, + ): Promise<{ apiKey: string }> { + const listUrl = `${host}/api/biz/v1/organization/${orgId}/projects/${projectId}/api_keys`; + + let existing: any[] = []; + try { + existing = await requestBizApi(this.fetchImpl, listUrl, authorization, { method: "GET" }) ?? []; + } catch { /* ignore โ€” will create */ } + + if (Array.isArray(existing)) { + const found = existing.find((k: any) => k.name === ZAI_API_KEY_NAME); + // Reuse the listed key only when it has a usable shape; a malformed + // entry falls through to the create path instead of poisoning the + // stored credential. + if (found && typeof found.apiKey === "string" && found.apiKey.length > 0) { + return { apiKey: found.apiKey }; + } + } + + const created = await requestBizApi(this.fetchImpl, listUrl, authorization, { + method: "POST", + body: JSON.stringify({ name: ZAI_API_KEY_NAME }), + }); + // Shape guard (CL-06): an upstream response drift (renamed/nested field) + // must fail the login with a clear error โ€” not store the string + // "undefined" and 401 on every later request. + if (typeof created?.apiKey !== "string" || created.apiKey.length === 0) { + throw new Error("API key creation returned unexpected shape: apiKey missing or empty"); + } + return { apiKey: created.apiKey }; + } + + async getSecretKey( + host: string, + authorization: string, + orgId: string, + projectId: string, + apiKey: string, + ): Promise { + const url = `${host}/api/biz/v1/organization/${orgId}/projects/${projectId}/api_keys/copy/${encodeURIComponent(apiKey)}`; + const data = await requestBizApi(this.fetchImpl, url, authorization, { method: "GET" }); + return data.secretKey ?? data.secret_key ?? ""; + } + + async resolveCodingPlanCredential( + accessToken: string, + provider: ProviderId, + userId?: string, + ): Promise { + if (provider === "zai") { + const bizToken = await this.resolveZaiBizToken(accessToken); + const host = "https://api.z.ai"; + const authorization = `Bearer ${bizToken}`; + + const { orgId, projectId } = await this.resolveCustomerInfo(host, authorization); + const { apiKey } = await this.findOrCreateApiKey(host, authorization, orgId, projectId); + let secret: string | undefined; + try { + secret = await this.getSecretKey(host, authorization, orgId, projectId, apiKey); + } catch { /* credential will be apiKey-only */ } + + return { apiKey, secret: secret || undefined, provider: "zai", userId }; + } + + const host = "https://bigmodel.cn"; + const authorization = accessToken; + + const { orgId, projectId } = await this.resolveCustomerInfo(host, authorization); + const { apiKey } = await this.findOrCreateApiKey(host, authorization, orgId, projectId); + + let fullKey = apiKey; + try { + const secret = await this.getSecretKey(host, authorization, orgId, projectId, apiKey); + if (secret) fullKey = `${apiKey}.${secret}`; + } catch { /* use apiKey only */ } + + return { apiKey: fullKey, provider: "bigmodel", userId }; + } +} diff --git a/src/auth/store.ts b/src/auth/store.ts new file mode 100644 index 0000000000000000000000000000000000000000..22abb3cd10d9eb3097d5c772777676471b95bd69 --- /dev/null +++ b/src/auth/store.ts @@ -0,0 +1,158 @@ +/** + * Encrypted file-based credential store. + * @see .omo/plans/zcode-proxy.md Task 14 + */ +import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs"; +import { join, dirname } from "node:path"; +import { homedir } from "node:os"; +import { createHash } from "node:crypto"; +import type { Credential } from "./types.js"; + +const STORE_DIR = join(homedir(), ".zcode-proxy"); +const STORE_FILE = join(STORE_DIR, "credentials.json"); +const ENV_SECRET = "ZCODE_PROXY_CREDENTIAL_SECRET"; + +/** + * Derive the AES-GCM key as SHA-256(seed) (audit R2-13). The previous XOR-fold + * construction was a pseudo-KDF: a seed shorter than 32 bytes left zero blocks + * in the key. Scope note: on default machine-derived seeds the security gain + * is ~0 (any same-user process can re-derive the seed either way, 0o600 only + * stops other users) โ€” the motivation is structural: env-secret deployments + * (`ZCODE_PROXY_CREDENTIAL_SECRET`) get real 32-byte diffusion, and the + * misleading "KDF" is gone. + */ +function getEncryptionKey(): Uint8Array { + const seed = process.env[ENV_SECRET] ?? `${homedir()}-${process.platform}-${process.arch}`; + return new Uint8Array(createHash("sha256").update(seed, "utf-8").digest()); +} + +/** + * Legacy XOR-fold key (pre-SHA-256 store format). Kept ONLY for the one-shot + * migration decrypt in {@link loadCredential} โ€” never used for new writes. + */ +function getLegacyEncryptionKey(): Uint8Array { + const hash = new Uint8Array(new ArrayBuffer(32)); + const encoder = new TextEncoder(); + + const seed = process.env[ENV_SECRET] ?? `${homedir()}-${process.platform}-${process.arch}`; + const seedBytes = encoder.encode(seed); + for (let i = 0; i < seedBytes.length; i++) { + hash[i % 32] ^= seedBytes[i]; + } + return hash; +} + +/** Atomic store write: temp file (0o600) + rename over the target. */ +function atomicWriteStore(contents: string): void { + const tmp = `${STORE_FILE}.tmp-${process.pid}-${Date.now()}`; + writeFileSync(tmp, contents, { mode: 0o600 }); + renameSync(tmp, STORE_FILE); +} + +async function importAesKey(raw: Uint8Array): Promise { + // Copy into a plain ArrayBuffer: bun-types types Uint8Array as + // ArrayBufferLike, which is not assignable to BufferSource. + const ab = new ArrayBuffer(raw.byteLength); + new Uint8Array(ab).set(raw); + return crypto.subtle.importKey( + "raw", + ab, + { name: "AES-GCM" }, + false, + ["encrypt", "decrypt"], + ); +} + +async function encryptWith(key: Uint8Array, plaintext: string): Promise { + const aesKey = await importAesKey(key); + + const iv = crypto.getRandomValues(new Uint8Array(12)); + const encoder = new TextEncoder(); + const encrypted = await crypto.subtle.encrypt( + { name: "AES-GCM", iv }, + aesKey, + encoder.encode(plaintext), + ); + + const combined = new Uint8Array(iv.length + encrypted.byteLength); + combined.set(iv, 0); + combined.set(new Uint8Array(encrypted), iv.length); + + return Buffer.from(combined).toString("base64"); +} + +async function decryptWith(key: Uint8Array, ciphertext: string): Promise { + const aesKey = await importAesKey(key); + + const combined = Buffer.from(ciphertext, "base64"); + const iv = combined.slice(0, 12); + const data = combined.slice(12); + + const decrypted = await crypto.subtle.decrypt( + { name: "AES-GCM", iv }, + aesKey, + data, + ); + + return new TextDecoder().decode(decrypted); +} + +async function encrypt(plaintext: string): Promise { + return encryptWith(getEncryptionKey(), plaintext); +} + +export async function saveCredential(cred: Credential): Promise { + mkdirSync(dirname(STORE_FILE), { recursive: true }); + const json = JSON.stringify(cred); + const encrypted = await encrypt(json); + atomicWriteStore(JSON.stringify({ encrypted })); +} + +export async function loadCredential(): Promise { + if (!existsSync(STORE_FILE)) return null; + const raw = readFileSync(STORE_FILE, "utf-8"); + const parsed = JSON.parse(raw); + if (!parsed.encrypted) return null; + + let json: string; + try { + json = await decryptWith(getEncryptionKey(), parsed.encrypted); + } catch { + // Not decryptable under the new SHA-256 KDF โ€” try the legacy XOR-fold key + // (one-shot migration), then transparently re-store under the new format. + try { + json = await decryptWith(getLegacyEncryptionKey(), parsed.encrypted); + } catch (e) { + // Stale/corrupt credential file โ€” key derivation is machine-specific + // ({homedir}-{platform}-{arch}), so cross-machine copies or OS reinstalls + // produce undecryptable ciphertext. Silently treat as "not logged in". + console.warn(`Ignoring corrupted or stale credentials at ${STORE_FILE}: ${(e as Error).message}`); + return null; + } + // Re-store under the new KDF. Best-effort by design: the credential is + // already decrypted in memory, so a failed re-write (read-only dir, AV + // lock on Windows, ...) must NOT fail this load โ€” it retries next boot. + try { + atomicWriteStore(JSON.stringify({ encrypted: await encrypt(json) })); + } catch (e) { + console.warn(`Credential re-encryption under the new key derivation failed (will retry on next load): ${(e as Error).message}`); + } + } + + try { + return JSON.parse(json) as Credential; + } catch (e) { + console.warn(`Ignoring corrupted credentials at ${STORE_FILE}: ${(e as Error).message}`); + return null; + } +} + +export function clearCredential(): void { + if (existsSync(STORE_FILE)) { + unlinkSync(STORE_FILE); + } +} + +export function getStorePath(): string { + return STORE_FILE; +} diff --git a/src/auth/types.ts b/src/auth/types.ts new file mode 100644 index 0000000000000000000000000000000000000000..b6f9c094e0c0dc3fcaf94939f7f4b4c240bbf768 --- /dev/null +++ b/src/auth/types.ts @@ -0,0 +1,41 @@ +/** + * Credential and auth type definitions. + * @see .omo/plans/zcode-proxy.md Task 4 + * @see _reverse/NOTEPAD.md "How Credential is Used" + */ +import type { ProviderId } from "../provider/types.js"; + +/** A resolved credential ready to be injected into upstream requests. */ +export interface Credential { + /** The API key portion (e.g. Z.AI API key id, or Bigmodel API key). */ + apiKey: string; + /** The secret portion (Z.AI only โ€” appended as `{apiKey}.{secret}`). */ + secret?: string; + /** Which provider this credential is for. */ + provider: ProviderId; + /** Unix timestamp (ms) when the credential expires. Present only for OAuth. */ + expiresAt?: number; + /** Upstream user identifier (OAuth only). Injected as `metadata.user_id` on Anthropic-format requests. */ + userId?: string; + /** JWT token for start-plan (zcode.z.ai). Present when login captured the ZCode plan token. */ + jwt?: string; +} + +/** + * Convert a `Credential` to the string sent upstream. + * + * - Z.AI: `{apiKey}.{secret}` (secret required) + * - Bigmodel: `{apiKey}` (no secret) + */ +export function credentialString(cred: Credential): string { + if (cred.secret) { + return `${cred.apiKey}.${cred.secret}`; + } + return cred.apiKey; +} + +/** Check whether a credential has expired. */ +export function isExpired(cred: Credential, now: number = Date.now()): boolean { + if (cred.expiresAt === undefined) return false; + return now >= cred.expiresAt; +} diff --git a/src/claim/client.ts b/src/claim/client.ts new file mode 100644 index 0000000000000000000000000000000000000000..97cb4f7ad8944cf19c9f75ac89975d57018631bd --- /dev/null +++ b/src/claim/client.ts @@ -0,0 +1,225 @@ +/** + * HTTP client for ZCode's manual-claim billing endpoints (weekend plans). + * + * Mirrors the ZCode 3.10 desktop client's `getManualClaimPlanPreviews` / + * `claimManualPlan`: + * - `GET {origin}/api/v1/zcode-plan/billing/preview?app_version=&platform=` + * - `POST {origin}/api/v1/zcode-plan/billing/claim` body `{plan_id}` + * + * Claim headers: `Authorization: Bearer {jwt}` (OAuth), Aliyun captcha + * verify param/region (same token source as the start-plan gateway), + * `X-ZCode-App-Version` and `X-Platform` (part of server-side eligibility). + * + * Since the 0828 weekend campaign the gateway REJECTS preview/claim with + * biz 3001 "parameter error" unless the request carries a UUID-format + * `X-Device-Mid` (empirically verified 2026-08-28: only that header is + * validated; non-UUID values still 3001). Pass `identity` so both calls + * carry the full identity set minus `X-ZCode-Agent` โ€” same header set the + * endpoint-routing config fetch uses for zcode.z.ai control-plane calls. + * + * @see _reverse/NOTEPAD.md (billing/claim endpoints section). + */ +import type { ClaimablePlan, ClaimOutcome, PlanEntitlement } from "./types.js"; +import { classifyClaimCode } from "./types.js"; +import { buildIdentityHeaders } from "../proxy/identity.js"; +import type { ProxyIdentity } from "../config/types.js"; + +export interface ClaimClientOptions { + origin: string; + /** OAuth JWT (`zcodejwttoken`); preview works without it, claim does not. */ + jwt?: string; + appVersion: string; + /** `${process.platform}-${process.arch}` in the real client. */ + platform: string; + /** + * Identity block driving the zcode.z.ai control-plane header set + * (incl. the server-required `X-Device-Mid`). When omitted the client + * falls back to the minimal legacy set (version + platform headers only). + */ + identity?: ProxyIdentity; + /** Per-call timeout in ms. Default `15000`. */ + timeoutMs?: number; + /** DI seam for tests. Default `globalThis.fetch`. */ + fetchImpl?: (url: string | URL | Request, init?: RequestInit) => Promise; +} + +export interface ClaimClient { + getPreviews(signal?: AbortSignal): Promise; + claim(planId: string, captcha: { verifyParam: string; region?: string }, signal?: AbortSignal): Promise; +} + +const DEFAULT_TIMEOUT_MS = 15_000; + +/** Preview failure with the HTTP status preserved (404 = campaign not deployed yet). */ +export class ClaimPreviewError extends Error { + readonly status: number; + readonly code: number | string; + constructor(message: string, status: number, code: number | string) { + super(message); + this.name = "ClaimPreviewError"; + this.status = status; + this.code = code; + } +} + +interface RawEntitlement { + entitlement_id?: string; + show_name?: string; + meter?: string; + unit_type?: string; + capabilities?: string[]; + grant_units?: number; + period?: string; + priority?: number; + effective_at?: number; +} + +interface RawPlan { + plan_id?: string; + name?: string; + description?: string; + priority?: number; + entitlements?: RawEntitlement[]; + starts_at?: number; + ends_at?: number; +} + +export function createClaimClient(opts: ClaimClientOptions): ClaimClient { + const origin = opts.origin.replace(/\/+$/, ""); + const jwt = opts.jwt?.trim() || undefined; + const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS; + const fetchImpl = opts.fetchImpl ?? globalThis.fetch; + // Identity set minus X-ZCode-Agent (zcode.z.ai control-plane precedent โ€” + // see endpoint-routing.ts); the no-identity fallback keeps the legacy shape. + const identityHeaders: Record = opts.identity + ? Object.fromEntries( + Object.entries(buildIdentityHeaders(opts.identity)).filter(([name]) => name !== "X-ZCode-Agent"), + ) + : { "X-ZCode-App-Version": opts.appVersion, "X-Platform": opts.platform }; + + function parseEntitlement(c: RawEntitlement): PlanEntitlement | null { + const entitlementId = c.entitlement_id?.trim() ?? ""; + if (!entitlementId) return null; + const e: PlanEntitlement = { + entitlementId, + showName: c.show_name?.trim() ?? "", + meter: c.meter?.trim() ?? "", + unitType: c.unit_type?.trim() ?? "", + capabilities: Array.isArray(c.capabilities) ? c.capabilities : [], + grantUnits: Number.isFinite(c.grant_units) ? (c.grant_units as number) : 0, + period: c.period?.trim() ?? "", + priority: Number.isFinite(c.priority) ? (c.priority as number) : 0, + }; + if (Number.isFinite(c.effective_at)) e.effectiveAt = c.effective_at as number; + return e; + } + + function parsePlan(p: RawPlan): ClaimablePlan | null { + const planId = p.plan_id?.trim() ?? ""; + if (!planId) return null; + const plan: ClaimablePlan = { + planId, + name: p.name?.trim() || planId, + description: p.description?.trim() ?? "", + priority: Number.isFinite(p.priority) ? (p.priority as number) : 0, + entitlements: (p.entitlements ?? []).flatMap((c) => { + const e = parseEntitlement(c); + return e ? [e] : []; + }), + }; + if (Number.isFinite(p.starts_at)) plan.startsAt = p.starts_at as number; + if (Number.isFinite(p.ends_at)) plan.endsAt = p.ends_at as number; + return plan; + } + + async function request( + method: string, + path: string, + init: { body?: unknown; headers?: Record; signal?: AbortSignal }, + ): Promise<{ status: number; json: Record | undefined; text: string }> { + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), timeoutMs); + const onExternalAbort = (): void => controller.abort(); + if (init.signal) { + if (init.signal.aborted) controller.abort(); + else init.signal.addEventListener("abort", onExternalAbort, { once: true }); + } + let resp: Response; + try { + resp = await fetchImpl(`${origin}${path}`, { + method, + headers: init.headers, + body: init.body === undefined ? undefined : JSON.stringify(init.body), + signal: controller.signal, + }); + const text = await resp.text(); + let json: Record | undefined; + try { + const parsed = JSON.parse(text) as unknown; + if (parsed && typeof parsed === "object") json = parsed as Record; + } catch { /* non-JSON body surfaced via text */ } + return { status: resp.status, json, text }; + } finally { + clearTimeout(timer); + init.signal?.removeEventListener("abort", onExternalAbort); + } + } + + function unwrapError(json: Record | undefined, status: number, text: string): { code: number | string; message: string } { + const code = json?.code !== undefined ? (json.code as number | string) : status >= 400 ? status : -1; + const rawMsg = json?.msg ?? json?.message; + const message = typeof rawMsg === "string" && rawMsg.trim() ? rawMsg.trim() : text.length > 0 && text.length < 200 ? text : `HTTP ${status}`; + return { code, message }; + } + + return { + async getPreviews(signal?: AbortSignal): Promise { + const url = `/api/v1/zcode-plan/billing/preview?app_version=${encodeURIComponent(opts.appVersion)}&platform=${encodeURIComponent(opts.platform)}`; + const headers: Record = { ...identityHeaders }; + if (jwt) headers.authorization = `Bearer ${jwt}`; + const { status, json, text } = await request("GET", url, { headers, signal }); + if (status < 200 || status >= 300 || (json?.code !== undefined && json.code !== 0) || json?.data === undefined) { + const { code, message } = unwrapError(json, status, text); + throw new ClaimPreviewError(`claim preview failed (${code}): ${message}`, status, code); + } + const data = json.data as { plans?: RawPlan[] }; + return (data.plans ?? []).flatMap((p) => { + const plan = parsePlan(p); + return plan ? [plan] : []; + }); + }, + + async claim(planId: string, captcha: { verifyParam: string; region?: string }, signal?: AbortSignal): Promise { + if (!jwt) return { ok: false, planId, failureKind: "login_required", code: 401, message: "manual_claim_login_required" }; + const headers: Record = { + ...identityHeaders, + authorization: `Bearer ${jwt}`, + "content-type": "application/json", + "X-Aliyun-Captcha-Verify-Param": captcha.verifyParam, + }; + if (captcha.region) headers["X-Aliyun-Captcha-Verify-Region"] = captcha.region; + const { status, json, text } = await request("POST", "/api/v1/zcode-plan/billing/claim", { body: { plan_id: planId }, headers, signal }); + + const data = json?.data as { plan?: RawPlan } | undefined; + const bizCode = json?.code !== undefined ? (json.code as number) : undefined; + const plan = data?.plan; + if (status >= 200 && status < 300 && bizCode === 0 && plan) { + const out: ClaimOutcome = { ok: true, planId }; + if (Number.isFinite(plan.starts_at)) out.startsAt = plan.starts_at as number; + if (Number.isFinite(plan.ends_at)) out.endsAt = plan.ends_at as number; + return out; + } + const { code, message } = unwrapError(json, status, text); + const failureEndsAt = Number.isFinite(plan?.ends_at) ? (plan?.ends_at as number) : undefined; + const httpDerived = status >= 400 && bizCode === undefined; + return { + ok: false, + planId, + failureKind: httpDerived ? (status === 401 ? "login_required" : "http_error") : classifyClaimCode(code), + code, + message, + ...(failureEndsAt !== undefined ? { failureEndsAt } : {}), + }; + }, + }; +} diff --git a/src/claim/runtime.ts b/src/claim/runtime.ts new file mode 100644 index 0000000000000000000000000000000000000000..de5c323c07252dae3d9e6b2aab1cacc60057833b --- /dev/null +++ b/src/claim/runtime.ts @@ -0,0 +1,147 @@ +/** + * Wiring between the claim subsystem and the rest of the proxy: builds a + * scheduler from a loaded `ProxyConfig` + `AuthManager` (serve path) and + * implements the one-shot CLI flow (`zcode-proxy claim [list|now]`). + */ +import type { AuthManager } from "../auth/manager.js"; +import type { ProxyConfig } from "../config/types.js"; +import type { ClaimablePlan, ClaimOutcome } from "./types.js"; +import { createClaimClient, ClaimPreviewError } from "./client.js"; +import { ClaimScheduler } from "./scheduler.js"; +import { getCaptchaToken } from "../proxy/captcha.js"; +import { loadCredential } from "../auth/store.js"; + +/** `${process.platform}-${process.arch}` โ€” mirrors the client's `TH()`. */ +export function claimPlatform(): string { + return `${process.platform}-${process.arch}`; +} + +export function startAutoClaim(config: ProxyConfig, auth: AuthManager): ClaimScheduler { + const scheduler = new ClaimScheduler({ + // AuthManager first (fresh), then the encrypted store โ€” on Android the + // login can land in the store after boot while auth hasn't been reloaded. + getJwt: async () => { + try { + const cred = await auth.getCredential(); + if (cred.jwt) return cred.jwt; + } catch { /* fall through to the store */ } + const stored = await loadCredential().catch(() => null); + return stored?.jwt; + }, + createClient: (jwt) => + createClaimClient({ + origin: config.claim.origin, + jwt, + appVersion: config.identity.appVersion, + platform: claimPlatform(), + identity: config.identity, + }), + getCaptcha: async () => { + const { verifyParam, region } = await getCaptchaToken(config.identity.appVersion); + return { verifyParam, region: region || undefined }; + }, + config: { + planId: config.claim.planId || undefined, + pollIntervalMs: config.claim.pollIntervalMs, + cooldownMs: config.claim.cooldownMs, + }, + log: (message) => console.log(`[claim] ${message}`), + }); + scheduler.start(); + return scheduler; +} + +const FAILURE_LABELS: Record = { + not_found: "plan does not exist", + unavailable: "campaign ended or not claimable yet", + already_claimed: "already claimed on this account", + ineligible: "account or client version not eligible (needs appVersion >= campaign minimum)", + quota_exhausted: "daily claim quota exhausted", + invalid_request: "invalid request", + captcha: "captcha verification failed", + login_required: "not logged in", + http_error: "HTTP error", + unknown: "unknown failure", +}; + +/** One-shot CLI: `list` prints previews; `now` claims the target plan. */ +export async function runClaimCli(config: ProxyConfig, mode: "list" | "now"): Promise { + const cred = await loadCredential(); + const jwt = cred?.jwt; + if (!jwt) { + console.error("Claim requires a logged-in oauth credential (no JWT stored). Run: zcode-proxy auth login "); + process.exit(1); + } + const client = createClaimClient({ + origin: config.claim.origin, + jwt, + appVersion: config.identity.appVersion, + platform: claimPlatform(), + identity: config.identity, + }); + + let plans: ClaimablePlan[]; + try { + plans = await client.getPreviews(); + } catch (err) { + if (err instanceof ClaimPreviewError && err.status === 404) { + console.log("No claimable plans: the campaign endpoint is not deployed yet (404)."); + console.log("Weekend campaigns typically go live shortly before the window โ€” keep the proxy"); + console.log("serving with claim.enabled, or re-run this command later."); + return; + } + throw err; + } + if (plans.length === 0) { + console.log("No claimable plans right now."); + return; + } + printPlans(plans); + + if (mode === "list") return; + + const wanted = config.claim.planId.trim(); + const target = wanted ? plans.find((p) => p.planId === wanted) : [...plans].sort((a, b) => b.priority - a.priority)[0]; + if (!target) { + console.error(`Configured claim.planId "${wanted}" not in the preview list.`); + process.exit(1); + } + if (target.planId !== plans[0].planId) console.log(`Claiming configured plan: ${target.planId}`); + + const captcha = await getCaptchaToken(config.identity.appVersion); + const outcome = await client.claim(target.planId, { verifyParam: captcha.verifyParam, region: captcha.region || undefined }); + printOutcome(outcome); + if (!outcome.ok) process.exit(1); +} + +function printPlans(plans: ClaimablePlan[]): void { + console.log(`Claimable plans (${plans.length}):`); + for (const p of plans) { + const window = [fmtTime(p.startsAt), fmtTime(p.endsAt)].filter(Boolean).join(" โ†’ "); + console.log(` - ${p.planId} "${p.name}" priority=${p.priority}${window ? ` ${window}` : ""}`); + for (const e of p.entitlements) { + const quota = e.grantUnits > 0 ? ` ${e.grantUnits} ${e.unitType}` : ""; + const activate = e.effectiveAt !== undefined ? ` (activates ${new Date(e.effectiveAt * 1000).toISOString()})` : ""; + console.log(` ยท ${e.showName || e.entitlementId}${quota}${activate}`); + } + } +} + +function printOutcome(outcome: ClaimOutcome): void { + if (outcome.ok) { + console.log(`\nClaimed: ${outcome.planId}`); + if (outcome.startsAt !== undefined) console.log(` activates: ${new Date(outcome.startsAt * 1000).toISOString()}`); + if (outcome.endsAt !== undefined) console.log(` expires: ${new Date(outcome.endsAt * 1000).toISOString()}`); + if (outcome.startsAt === undefined && outcome.endsAt === undefined) console.log(" active immediately"); + return; + } + const label = FAILURE_LABELS[outcome.failureKind] ?? FAILURE_LABELS.unknown; + console.error(`\nClaim failed: ${label} (code ${String(outcome.code)}) โ€” ${outcome.message}`); + if (outcome.failureEndsAt !== undefined) { + console.error(` retry window opens: ${new Date(outcome.failureEndsAt * 1000).toISOString()}`); + } +} + +function fmtTime(sec: number | undefined): string { + return sec === undefined ? "" : new Date(sec * 1000).toISOString(); +} diff --git a/src/claim/scheduler.ts b/src/claim/scheduler.ts new file mode 100644 index 0000000000000000000000000000000000000000..a4b8880b99a6622f9dc65dd692fb9e70f73a85dd --- /dev/null +++ b/src/claim/scheduler.ts @@ -0,0 +1,186 @@ +/** + * Auto-claim scheduler โ€” polls the manual-claim preview endpoint and claims + * weekend/trial plans the moment they become available (first-come-first-served: + * the server caps daily claims with biz code 1005). + * + * Backoff semantics per failure kind (biz codes from the desktop client): + * - success / already_claimed โ†’ hold until the plan's `ends_at` (unix sec) + * - quota_exhausted โ†’ hold until `failureEndsAt` (next window) else cooldown + * - ineligible / unavailable / not_found โ†’ cooldown + * - captcha / network / unknown โ†’ cooldown (retry next window) + * - login_required โ†’ stop (needs re-login) + * + * `starts_at` / `ends_at` / `failureEndsAt` are unix SECONDS (the desktop + * client compares them against `Date.now()/1e3`). + */ +import type { ClaimOutcome, ClaimablePlan } from "./types.js"; +import { ClaimPreviewError } from "./client.js"; + +interface ClaimGateway { + getPreviews(): Promise; + claim(planId: string, captcha: { verifyParam: string; region?: string }): Promise; +} + +export interface ClaimSchedulerConfig { + /** Claim this plan_id; empty = highest-priority preview. */ + planId?: string; + pollIntervalMs: number; + cooldownMs: number; +} + +export interface ClaimSchedulerDeps { + getJwt(): Promise; + createClient(jwt: string): ClaimGateway; + getCaptcha(): Promise<{ verifyParam: string; region?: string }>; + config: ClaimSchedulerConfig; + log?: (message: string) => void; + now?: () => number; +} + +export type TickResult = + | { action: "skipped_hold" } + | { action: "stopped" } + | { action: "idle" } + | { action: "claimed"; planId: string; startsAt?: number; endsAt?: number } + | { action: "failed"; outcome: Extract; holdMs: number } + | { action: "error"; message: string; holdMs: number }; + +export class ClaimScheduler { + private stopped = false; + private holdUntil = 0; + private timer: ReturnType | null = null; + private readonly now: () => number; + private readonly log: (message: string) => void; + + constructor(private readonly deps: ClaimSchedulerDeps) { + this.now = deps.now ?? Date.now; + this.log = deps.log ?? (() => {}); + } + + isStopped(): boolean { + return this.stopped; + } + + start(): void { + if (this.stopped) return; + this.scheduleNext(0); + } + + stop(): void { + this.stopped = true; + if (this.timer !== null) { + clearTimeout(this.timer); + this.timer = null; + } + } + + /** One pollโ†’claim cycle. Exposed for tests; `start()` drives it on a timer. */ + async tick(): Promise { + if (this.stopped) return { action: "stopped" }; + const nowMs = this.now(); + if (nowMs < this.holdUntil) return { action: "skipped_hold" }; + + let jwt: string | undefined; + try { + jwt = await this.deps.getJwt(); + } catch (err) { + return this.errorBackoff(`credential resolution failed: ${(err as Error).message}`); + } + if (!jwt) { + // Missing JWT is "login pending" (Android logs in after boot), not fatal: + // back off and retry โ€” the login_required CLAIM FAILURE (server 401) is + // the terminal case handled below. + return this.errorBackoff("no JWT available (oauth login pending)"); + } + + const client = this.deps.createClient(jwt); + let plans: ClaimablePlan[]; + try { + plans = await client.getPreviews(); + } catch (err) { + // 404 = campaign endpoint not deployed yet (the expected pre-launch state + // for weekend plans); poll at normal cadence instead of error backoff. + if (err instanceof ClaimPreviewError && err.status === 404) { + this.holdUntil = nowMs + this.deps.config.pollIntervalMs; + return { action: "idle" }; + } + return this.errorBackoff(`preview failed: ${(err as Error).message}`); + } + if (plans.length === 0) { + this.holdUntil = nowMs + this.deps.config.pollIntervalMs; + return { action: "idle" }; + } + + const target = this.pickPlan(plans); + if (!target) { + // Configured planId not in the current preview list โ€” plain poll cadence. + this.holdUntil = nowMs + this.deps.config.pollIntervalMs; + return { action: "idle" }; + } + + let captcha: { verifyParam: string; region?: string }; + try { + captcha = await this.deps.getCaptcha(); + } catch (err) { + return this.errorBackoff(`captcha token failed: ${(err as Error).message}`); + } + + let outcome: ClaimOutcome; + try { + outcome = await client.claim(target.planId, captcha); + } catch (err) { + return this.errorBackoff(`claim request failed: ${(err as Error).message}`); + } + + if (outcome.ok) { + const endsAtMs = outcome.endsAt !== undefined ? outcome.endsAt * 1000 : undefined; + this.holdUntil = endsAtMs ?? nowMs + this.deps.config.pollIntervalMs; + this.log(`claim: claimed plan ${target.planId}${outcome.startsAt !== undefined ? ` (activates ${new Date(outcome.startsAt * 1000).toISOString()})` : ""}`); + return { action: "claimed", planId: target.planId, startsAt: outcome.startsAt, endsAt: outcome.endsAt }; + } + + const holdMs = this.holdForFailure(outcome.failureKind, outcome.failureEndsAt, nowMs); + this.holdUntil = nowMs + holdMs; + this.log(`claim: ${outcome.failureKind} (${outcome.code}) โ€” ${outcome.message}; retry in ${Math.round(holdMs / 1000)}s`); + if (outcome.failureKind === "login_required") { + this.stop(); + } + return { action: "failed", outcome, holdMs }; + } + + private pickPlan(plans: ClaimablePlan[]): ClaimablePlan | null { + const wanted = this.deps.config.planId?.trim(); + if (wanted) return plans.find((p) => p.planId === wanted) ?? null; + // Server order first, highest priority breaks ties (stable sort). + const sorted = [...plans].sort((a, b) => b.priority - a.priority); + return sorted[0] ?? null; + } + + private holdForFailure(kind: Extract["failureKind"], failureEndsAtSec: number | undefined, nowMs: number): number { + if ((kind === "already_claimed" || kind === "quota_exhausted") && Number.isFinite(failureEndsAtSec)) { + const untilMs = (failureEndsAtSec as number) * 1000; + if (untilMs > nowMs) return Math.min(untilMs - nowMs, 24 * 60 * 60 * 1000); + } + return this.deps.config.cooldownMs; + } + + private errorBackoff(message: string): TickResult { + const holdMs = this.deps.config.cooldownMs; + this.holdUntil = this.now() + holdMs; + this.log(`claim: ${message}; retry in ${Math.round(holdMs / 1000)}s`); + return { action: "error", message, holdMs }; + } + + private scheduleNext(delayMs: number): void { + if (this.stopped) return; + this.timer = setTimeout(() => { + this.timer = null; + void this.tick().finally(() => this.scheduleNext(this.nextDelay())); + }, delayMs); + } + + private nextDelay(): number { + const remaining = this.holdUntil - this.now(); + return remaining > 0 ? remaining : this.deps.config.pollIntervalMs; + } +} diff --git a/src/claim/types.ts b/src/claim/types.ts new file mode 100644 index 0000000000000000000000000000000000000000..f8d40b5b19c401b4f52c0f160da0bb3d7e0fee4a --- /dev/null +++ b/src/claim/types.ts @@ -0,0 +1,66 @@ +/** + * Types for the manual-claim ("weekend plan") subsystem โ€” mirrors the ZCode + * 3.10 desktop client's `manualClaimPlan` feature. + * + * Server biz codes โ†’ failure kinds match the desktop client's `$vt` mapper: + * 1001 notFound, 1002 unavailable, 1003 alreadyClaimed, 1004 ineligible, + * 1005 quotaExhausted, 3001 invalidRequest, 3007 captcha, 401 loginRequired. + * + * @see _reverse/NOTEPAD.md "Manual Claim Plan" section. + */ + +/** One entitlement inside a claimable plan (normalized from snake_case upstream). */ +export interface PlanEntitlement { + entitlementId: string; + showName: string; + meter: string; + unitType: string; + capabilities: string[]; + grantUnits: number; + period: string; + priority: number; + /** Unix seconds when the entitlement activates (weekend plans activate late). */ + effectiveAt?: number; +} + +/** A claimable trial plan from `GET /api/v1/zcode-plan/billing/preview`. */ +export interface ClaimablePlan { + planId: string; + name: string; + description: string; + priority: number; + entitlements: PlanEntitlement[]; + startsAt?: number; + endsAt?: number; +} + +export type ClaimFailureKind = + | "not_found" + | "unavailable" + | "already_claimed" + | "ineligible" + | "quota_exhausted" + | "invalid_request" + | "captcha" + | "login_required" + | "http_error" + | "unknown"; + +export type ClaimOutcome = + | { ok: true; planId: string; startsAt?: number; endsAt?: number } + | { ok: false; planId: string; failureKind: ClaimFailureKind; code: number | string; message: string; failureEndsAt?: number }; + +/** Map a server biz code to the client failure kind (mirrors `$vt` in the desktop bundle). */ +export function classifyClaimCode(code: number | string | undefined): ClaimFailureKind { + switch (typeof code === "string" ? Number.parseInt(code, 10) : code) { + case 1001: return "not_found"; + case 1002: return "unavailable"; + case 1003: return "already_claimed"; + case 1004: return "ineligible"; + case 1005: return "quota_exhausted"; + case 3001: return "invalid_request"; + case 3007: return "captcha"; + case 401: return "login_required"; + default: return "unknown"; + } +} diff --git a/src/config/edit.ts b/src/config/edit.ts new file mode 100644 index 0000000000000000000000000000000000000000..0159c53e01775777731e89aad7faa89d7e81166d --- /dev/null +++ b/src/config/edit.ts @@ -0,0 +1,38 @@ +/** + * Targeted YAML config editing helpers shared by the CLI entries (serve / + * android / tui) and the TUI runtime. + */ +import { parseDocument } from "yaml"; +import { readFileSync, writeFileSync, existsSync } from "node:fs"; +import type { ProviderId } from "../provider/types.js"; +import { EXAMPLE_CONFIG_YAML } from "./template.js"; + +/** + * Targeted YAML update of top-level `provider` and `plan` keys. + * + * Uses `yaml`'s document model (`parseDocument` โ†’ `set` โ†’ `String(doc)`) so + * comments and formatting in the rest of the file survive the edit โ€” the old + * `parse`/`stringify` round-trip dropped every comment, and this file is what + * users see (and edit) in config.yaml. + */ +export function updateConfigYaml( + path: string, + fields: { provider: ProviderId; plan: "coding-plan" | "start-plan" }, +): void { + const doc = parseDocument(readFileSync(path, "utf-8")); + doc.set("provider", fields.provider); + doc.set("plan", fields.plan); + writeFileSync(path, String(doc), "utf-8"); +} + +/** + * Create the config file from the bundled template when missing. + * Shared by the CLI entries (serve / android / auth login) and the TUI โ€” + * they used to each hand-roll this block. Returns true when the file was + * created, false when it already existed. + */ +export function ensureConfigFile(path: string): boolean { + if (existsSync(path)) return false; + writeFileSync(path, EXAMPLE_CONFIG_YAML, "utf-8"); + return true; +} diff --git a/src/config/loader.ts b/src/config/loader.ts new file mode 100644 index 0000000000000000000000000000000000000000..960a9601879e22715f3af052ba299869e750aa6e --- /dev/null +++ b/src/config/loader.ts @@ -0,0 +1,393 @@ +/** + * YAML config loader with env-var overrides and validation. + * @see .omo/plans/zcode-proxy.md Task 2 + */ +import { readFileSync, existsSync } from "node:fs"; +import { parse } from "yaml"; +import type { ClientIdentityConfig, ProxyConfig, ProviderEndpoints, ProxyIdentity, ResponsesConfig, McpConfig, AsyncConfig, EndpointRoutingConfig, ClientSigningConfig, ClaimConfig } from "./types.js"; + +/** Environment variable keys that override YAML values. */ +const ENV = { + PORT: "ZCODE_PROXY_PORT", + PROXY_API_KEY: "ZCODE_PROXY_API_KEY", + PROVIDER: "ZCODE_PROVIDER", + APP_VERSION: "ZCODE_APP_VERSION", + SOURCE_TITLE: "ZCODE_SOURCE_TITLE", + REFERER_ORIGIN: "ZCODE_REFERER_ORIGIN", + ASYNC_ENABLED: "ZCODE_ASYNC_ENABLED", + ASYNC_ORIGIN: "ZCODE_ASYNC_ORIGIN", + ASYNC_MAX_RETRIES: "ZCODE_ASYNC_MAX_RETRIES", + ASYNC_MAX_WAIT_MS: "ZCODE_ASYNC_MAX_WAIT_MS", + CLAIM_ENABLED: "ZCODE_CLAIM_ENABLED", + CLAIM_AUTO: "ZCODE_CLAIM_AUTO", + CLAIM_ORIGIN: "ZCODE_CLAIM_ORIGIN", + CLAIM_POLL_INTERVAL_MS: "ZCODE_CLAIM_POLL_INTERVAL_MS", + ENDPOINT_ROUTING_ENABLED: "ZCODE_ENDPOINT_ROUTING", + CLIENT_SIGNING_ENABLED: "ZCODE_CLIENT_SIGNING", +} as const; + +const DEFAULTS = { + PORT: 8080, + HOST: "0.0.0.0", + PROVIDER: "zai" as const, + PLAN: "coding-plan" as const, + DEFAULT_MODEL: "glm-4.6", + LOG_LEVEL: "info" as const, + ZAI_ANTHROPIC_BASE: "https://api.z.ai/api/anthropic", + ZAI_OPENAI_BASE: "https://api.z.ai/api/coding/paas/v4", + BIGMODEL_ANTHROPIC_BASE: "https://open.bigmodel.cn/api/anthropic", + BIGMODEL_OPENAI_BASE: "https://open.bigmodel.cn/api/coding/paas/v4", + APP_VERSION: "3.11.2", + SOURCE_TITLE: "cli", + REFERER_ORIGIN: "https://zcode.z.ai", + CLIENT_IDENTITY_MODE: "observe" as const, + CLIENT_IDENTITY_TTL_SECONDS: 900, + CLIENT_IDENTITY_MAX_SESSIONS: 1024, + RESPONSES_ENABLED: true, + RESPONSES_STORE_MAX_ENTRIES: 1000, + RESPONSES_STORE_TTL_MS: 24 * 60 * 60 * 1000, + MCP_ENABLED: true, + MCP_WEB_SEARCH: true, + MCP_WEB_READER: false, + MCP_ZREAD: false, + ASYNC_ENABLED: false, + ASYNC_ORIGIN: "https://zcode.z.ai", + ASYNC_POLL_INTERVAL_MS: 5000, + ASYNC_KEEPALIVE_INTERVAL_MS: 3000, + ASYNC_MAX_WAIT_MS: 0, + ASYNC_MAX_RETRIES: 3, + ASYNC_SETTLE_TIMEOUT_MS: 8000, + ASYNC_CONTROL_TIMEOUT_MS: 15000, + ASYNC_DEFAULT_MODEL: "", + CLAIM_ENABLED: true, + CLAIM_AUTO: true, + CLAIM_ORIGIN: "https://zcode.z.ai", + CLAIM_POLL_INTERVAL_MS: 300000, + CLAIM_COOLDOWN_MS: 600000, + CLAIM_PLAN_ID: "", + ENDPOINT_ROUTING_ENABLED: true, + ENDPOINT_ROUTING_ORIGIN: "https://zcode.z.ai", + CLIENT_SIGNING_ENABLED: true, + CLIENT_SIGNING_ORIGIN: "https://zcode.z.ai", +}; + +/** Printable-ASCII gate copied from the ZCode bundle's `rYn` helper. */ +const ASCII_PRINTABLE = /^[\x20-\x7e]+$/; + +/** + * Load and validate proxy configuration from a YAML file, applying env overrides. + * @throws Error if file not found or required fields are invalid. + */ +export function loadConfig(path: string): ProxyConfig { + if (!existsSync(path)) { + throw new Error(`Config file not found: ${path}`); + } + + const raw = readFileSync(path, "utf-8"); + const parsed = parse(raw) ?? {}; + + // --- server --- + const port = resolvePort(process.env[ENV.PORT] ?? parsed?.server?.port); + const host = typeof parsed?.server?.host === "string" ? parsed.server.host : DEFAULTS.HOST; + + // --- auth --- + const proxyApiKey = process.env[ENV.PROXY_API_KEY] ?? parsed?.auth?.proxyApiKey; + const oauthCredentialsPath = parsed?.auth?.oauthCredentialsPath; + + // --- provider --- + const provider = resolveProvider(process.env[ENV.PROVIDER] ?? parsed?.provider); + const plan = resolvePlan(parsed?.plan); + + // --- providers --- + const zai: ProviderEndpoints = { + anthropicBase: parsed?.providers?.zai?.anthropicBase ?? DEFAULTS.ZAI_ANTHROPIC_BASE, + openaiBase: parsed?.providers?.zai?.openaiBase ?? DEFAULTS.ZAI_OPENAI_BASE, + }; + const bigmodel: ProviderEndpoints = { + anthropicBase: parsed?.providers?.bigmodel?.anthropicBase ?? DEFAULTS.BIGMODEL_ANTHROPIC_BASE, + openaiBase: parsed?.providers?.bigmodel?.openaiBase ?? DEFAULTS.BIGMODEL_OPENAI_BASE, + }; + + // --- models --- + const defaultModel = typeof parsed?.defaultModel === "string" ? parsed.defaultModel : DEFAULTS.DEFAULT_MODEL; + const models = Array.isArray(parsed?.models) ? parsed.models : [defaultModel]; + + // --- logging --- + const logLevel = resolveLogLevel(parsed?.logging?.level); + + // --- identity --- + const identity = resolveIdentity({ + appVersionEnv: process.env[ENV.APP_VERSION], + appVersionYaml: parsed?.identity?.appVersion, + sourceTitleEnv: process.env[ENV.SOURCE_TITLE], + sourceTitleYaml: parsed?.identity?.sourceTitle, + refererEnv: process.env[ENV.REFERER_ORIGIN], + refererYaml: parsed?.identity?.refererOrigin, + deviceMidYaml: parsed?.identity?.deviceMid, + }); + + const clientIdentity = resolveClientIdentity(parsed?.clientIdentity); + const responses = resolveResponsesConfig(parsed?.responses); + const mcp = resolveMcpConfig(parsed?.mcp); + const asyncCfg = resolveAsyncConfig(parsed?.async); + const claimCfg = resolveClaimConfig(parsed?.claim); + const endpointRouting = resolveEndpointRoutingConfig(parsed?.endpointRouting); + const clientSigning = resolveClientSigningConfig(parsed?.clientSigning); + + const config: ProxyConfig = { + server: { port, host }, + auth: { proxyApiKey, oauthCredentialsPath }, + provider, + plan, + providers: { zai, bigmodel }, + defaultModel, + models, + identity, + clientIdentity, + responses, + endpointRouting, + clientSigning, + mcp, + async: asyncCfg, + claim: claimCfg, + logging: { level: logLevel }, + }; + + validate(config); + return config; +} + +function resolveClientIdentity(raw: unknown): ClientIdentityConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + const mode = resolveClientIdentityMode(obj.mode); + const ttlSeconds = resolvePositiveInt(obj.ttlSeconds, DEFAULTS.CLIENT_IDENTITY_TTL_SECONDS, "clientIdentity.ttlSeconds"); + const maxSessions = resolvePositiveInt(obj.maxSessions, DEFAULTS.CLIENT_IDENTITY_MAX_SESSIONS, "clientIdentity.maxSessions"); + return { mode, ttlSeconds, maxSessions }; +} + +function resolveClientIdentityMode(raw: unknown): ClientIdentityConfig["mode"] { + if (raw === undefined || raw === null) return DEFAULTS.CLIENT_IDENTITY_MODE; + if (raw === "off" || raw === "observe" || raw === "enforce") return raw; + throw new Error(`Invalid clientIdentity.mode "${String(raw)}": must be "off", "observe", or "enforce"`); +} + +function resolveResponsesConfig(raw: unknown): ResponsesConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + const storeRaw = obj.store && typeof obj.store === "object" ? obj.store as Record : {}; + return { + enabled: resolveBool(obj.enabled, DEFAULTS.RESPONSES_ENABLED), + storeMaxEntries: resolvePositiveInt(storeRaw.maxEntries, DEFAULTS.RESPONSES_STORE_MAX_ENTRIES, "responses.store.maxEntries"), + storeTtlMs: resolvePositiveInt(storeRaw.ttlMs, DEFAULTS.RESPONSES_STORE_TTL_MS, "responses.store.ttlMs"), + }; +} + +function resolveMcpConfig(raw: unknown): McpConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + return { + enabled: resolveBool(obj.enabled, DEFAULTS.MCP_ENABLED), + webSearch: resolveBool(obj.webSearch ?? obj.web_search, DEFAULTS.MCP_WEB_SEARCH), + webReader: resolveBool(obj.webReader ?? obj.web_reader, DEFAULTS.MCP_WEB_READER), + zread: resolveBool(obj.zread, DEFAULTS.MCP_ZREAD), + }; +} + +function resolveAsyncConfig(raw: unknown): AsyncConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + const enabledEnv = process.env[ENV.ASYNC_ENABLED]; + const originEnv = process.env[ENV.ASYNC_ORIGIN]; + const maxRetriesEnv = process.env[ENV.ASYNC_MAX_RETRIES]; + const maxWaitMsEnv = process.env[ENV.ASYNC_MAX_WAIT_MS]; + + const origin = (originEnv ?? (typeof obj.origin === "string" ? obj.origin : DEFAULTS.ASYNC_ORIGIN)).trim() || DEFAULTS.ASYNC_ORIGIN; + validateOrigin(origin, "async.origin"); + + return { + enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.ASYNC_ENABLED) : resolveBool(obj.enabled, DEFAULTS.ASYNC_ENABLED), + origin, + pollIntervalMs: resolvePositiveInt(obj.pollIntervalMs ?? obj.poll_interval_ms, DEFAULTS.ASYNC_POLL_INTERVAL_MS, "async.pollIntervalMs"), + keepAliveIntervalMs: resolvePositiveInt(obj.keepAliveIntervalMs ?? obj.keepalive_interval_ms, DEFAULTS.ASYNC_KEEPALIVE_INTERVAL_MS, "async.keepAliveIntervalMs"), + maxWaitMs: resolveNonNegativeInt(maxWaitMsEnv ?? obj.maxWaitMs ?? obj.max_wait_ms, DEFAULTS.ASYNC_MAX_WAIT_MS, "async.maxWaitMs"), + maxRetries: resolveNonNegativeInt(maxRetriesEnv ?? obj.maxRetries ?? obj.max_retries, DEFAULTS.ASYNC_MAX_RETRIES, "async.maxRetries"), + settleTimeoutMs: resolvePositiveInt(obj.settleTimeoutMs ?? obj.settle_timeout_ms, DEFAULTS.ASYNC_SETTLE_TIMEOUT_MS, "async.settleTimeoutMs"), + controlTimeoutMs: resolvePositiveInt(obj.controlTimeoutMs ?? obj.control_timeout_ms, DEFAULTS.ASYNC_CONTROL_TIMEOUT_MS, "async.controlTimeoutMs"), + defaultModel: typeof obj.defaultModel === "string" ? obj.defaultModel : DEFAULTS.ASYNC_DEFAULT_MODEL, + }; +} + +function validateOrigin(origin: string, name: string): void { + let parsed: URL; + try { + parsed = new URL(origin); + } catch { + throw new Error(`${name} "${origin}" is not a valid URL`); + } + // Scheme allowlist: only http/https. Other schemes (ftp:, file:, etc.) rejected. + if (parsed.protocol !== "https:" && parsed.protocol !== "http:") { + throw new Error(`${name} must use http: or https: scheme (got ${parsed.protocol})`); + } + // Cleartext HTTP only for loopback (dev/mock mode). Real off-peak backend requires + // HTTPS โ€” cleartext would leak the JWT + coding-plan API key to any network observer. + const hostname = parsed.hostname.replace(/^\[|\]$/g, ""); // strip IPv6 brackets + const isLoopback = hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1"; + if (parsed.protocol === "http:" && !isLoopback) { + throw new Error(`${name} http:// is only allowed for loopback hosts (got ${hostname}). Use https:// for remote origins.`); + } + if (parsed.username || parsed.password) { + throw new Error(`${name} must not contain userinfo`); + } + if (parsed.hash) { + throw new Error(`${name} must not contain a fragment`); + } + if (parsed.pathname !== "/" && parsed.pathname !== "") { + throw new Error(`${name} must not contain a path (got "${parsed.pathname}"); clients append their own paths`); + } + if (parsed.search) { + throw new Error(`${name} must not contain a query string`); + } +} + +function resolveEndpointRoutingConfig(raw: unknown): EndpointRoutingConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + const enabledEnv = process.env[ENV.ENDPOINT_ROUTING_ENABLED]; + const origin = (typeof obj.origin === "string" ? obj.origin : DEFAULTS.ENDPOINT_ROUTING_ORIGIN).trim() + || DEFAULTS.ENDPOINT_ROUTING_ORIGIN; + validateOrigin(origin, "endpointRouting.origin"); + return { + enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.ENDPOINT_ROUTING_ENABLED) : resolveBool(obj.enabled, DEFAULTS.ENDPOINT_ROUTING_ENABLED), + origin, + }; +} + +function resolveClientSigningConfig(raw: unknown): ClientSigningConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + const enabledEnv = process.env[ENV.CLIENT_SIGNING_ENABLED]; + const origin = (typeof obj.origin === "string" ? obj.origin : DEFAULTS.CLIENT_SIGNING_ORIGIN).trim() + || DEFAULTS.CLIENT_SIGNING_ORIGIN; + validateOrigin(origin, "clientSigning.origin"); + return { + enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.CLIENT_SIGNING_ENABLED) : resolveBool(obj.enabled, DEFAULTS.CLIENT_SIGNING_ENABLED), + origin, + }; +} + +function resolveBool(raw: unknown, fallback: boolean): boolean { + if (typeof raw === "boolean") return raw; + if (typeof raw === "string") return raw === "true" || raw === "1"; + return fallback; +} + +function resolvePositiveInt(raw: unknown, fallback: number, name: string): number { + if (raw === undefined || raw === null) return fallback; + const n = typeof raw === "number" ? raw : parseInt(String(raw), 10); + if (!Number.isInteger(n) || n < 1) { + throw new Error(`${name} must be a positive integer`); + } + return n; +} + +function resolveNonNegativeInt(raw: unknown, fallback: number, name: string): number { + if (raw === undefined || raw === null) return fallback; + const n = typeof raw === "number" ? raw : parseInt(String(raw), 10); + if (!Number.isInteger(n) || n < 0) { + throw new Error(`${name} must be a non-negative integer`); + } + return n; +} + +/** Resolve port from raw value (YAML or env), defaulting to 8080. */ +function resolvePort(raw: unknown): number { + if (raw === undefined || raw === null) return DEFAULTS.PORT; + const n = typeof raw === "number" ? raw : parseInt(String(raw), 10); + if (!Number.isFinite(n)) { + throw new Error("server.port must be a valid number"); + } + return n; +} + +/** Resolve and validate provider string. */ +function resolveProvider(raw: unknown): "zai" | "bigmodel" { + const v = typeof raw === "string" ? raw : DEFAULTS.PROVIDER; + if (v !== "zai" && v !== "bigmodel") { + throw new Error(`Invalid provider "${v}": must be "zai" or "bigmodel"`); + } + return v; +} + +/** + * Resolve and validate the plan tier. Mirrors `resolveProvider`'s hard + * validation style: an unrecognized value (e.g. `start_plan`/`startplan` + * typos) THROWS instead of silently falling back to coding-plan โ€” a silent + * fallback sent users to the wrong upstream (401/403, no captcha/quota flow) + * with nothing pointing at the config typo. + */ +function resolvePlan(raw: unknown): "coding-plan" | "start-plan" { + if (raw === undefined || raw === null) return DEFAULTS.PLAN; + if (raw === "coding-plan" || raw === "start-plan") return raw; + throw new Error(`Invalid plan "${String(raw)}": must be "coding-plan" or "start-plan"`); +} + +/** Resolve log level with fallback. */ +function resolveLogLevel(raw: unknown): "debug" | "info" | "warn" | "error" { + const levels = ["debug", "info", "warn", "error"] as const; + if (typeof raw === "string" && (levels as readonly string[]).includes(raw)) { + return raw as "debug" | "info" | "warn" | "error"; + } + return DEFAULTS.LOG_LEVEL; +} + +interface IdentityInputs { + appVersionEnv?: string; + appVersionYaml?: string; + sourceTitleEnv?: string; + sourceTitleYaml?: string; + refererEnv?: string; + refererYaml?: string; + deviceMidYaml?: string; +} + +/** Resolve identity fields (env > YAML > default). Non-ASCII `appVersion` silently falls back to the default. */ +function resolveIdentity(inp: IdentityInputs): ProxyIdentity { + const rawVersion = (inp.appVersionEnv ?? inp.appVersionYaml ?? DEFAULTS.APP_VERSION).trim(); + const appVersion = ASCII_PRINTABLE.test(rawVersion) ? rawVersion : DEFAULTS.APP_VERSION; + + const sourceTitle = (inp.sourceTitleEnv ?? inp.sourceTitleYaml ?? DEFAULTS.SOURCE_TITLE).trim() + || DEFAULTS.SOURCE_TITLE; + + const refererOrigin = (inp.refererEnv ?? inp.refererYaml ?? DEFAULTS.REFERER_ORIGIN).trim() + || DEFAULTS.REFERER_ORIGIN; + + const deviceMid = typeof inp.deviceMidYaml === "string" ? inp.deviceMidYaml.trim() : ""; + return { appVersion, sourceTitle, refererOrigin, ...(deviceMid ? { deviceMid } : {}) }; +} + +/** Cross-field validation after all fields are resolved. */ +function resolveClaimConfig(raw: unknown): ClaimConfig { + const obj = raw && typeof raw === "object" ? raw as Record : {}; + const enabledEnv = process.env[ENV.CLAIM_ENABLED]; + const autoEnv = process.env[ENV.CLAIM_AUTO]; + const originEnv = process.env[ENV.CLAIM_ORIGIN]; + const pollIntervalEnv = process.env[ENV.CLAIM_POLL_INTERVAL_MS]; + + const origin = (originEnv ?? (typeof obj.origin === "string" ? obj.origin : DEFAULTS.CLAIM_ORIGIN)).trim() || DEFAULTS.CLAIM_ORIGIN; + validateOrigin(origin, "claim.origin"); + + return { + enabled: enabledEnv !== undefined ? resolveBool(enabledEnv, DEFAULTS.CLAIM_ENABLED) : resolveBool(obj.enabled, DEFAULTS.CLAIM_ENABLED), + auto: autoEnv !== undefined ? resolveBool(autoEnv, DEFAULTS.CLAIM_AUTO) : resolveBool(obj.auto, DEFAULTS.CLAIM_AUTO), + origin, + pollIntervalMs: resolvePositiveInt(pollIntervalEnv ?? obj.pollIntervalMs ?? obj.poll_interval_ms, DEFAULTS.CLAIM_POLL_INTERVAL_MS, "claim.pollIntervalMs"), + cooldownMs: resolvePositiveInt(obj.cooldownMs ?? obj.cooldown_ms, DEFAULTS.CLAIM_COOLDOWN_MS, "claim.cooldownMs"), + planId: typeof obj.planId === "string" ? obj.planId.trim() : DEFAULTS.CLAIM_PLAN_ID, + }; +} + +function validate(config: ProxyConfig): void { + if (config.server.port < 1 || config.server.port > 65535) { + throw new Error(`server.port ${config.server.port} is out of range (1-65535)`); + } + + if (!config.models.includes(config.defaultModel)) { + // defaultModel not in the models list โ€” add it automatically + config.models.push(config.defaultModel); + } +} diff --git a/src/config/template.ts b/src/config/template.ts new file mode 100644 index 0000000000000000000000000000000000000000..c3070935649d0a3f575ccbe5f502923f329d2481 --- /dev/null +++ b/src/config/template.ts @@ -0,0 +1,109 @@ +/** + * Bundled config template โ€” inlined as a string constant so it compiles into + * the single-file binary (`bun build --compile`) without requiring a sidecar + * `config.example.yaml` file at runtime. + * + * Source of truth: config.example.yaml at repo root. When editing the schema, + * update BOTH this file AND config.example.yaml to keep them in sync. + */ + +export const EXAMPLE_CONFIG_YAML: string = `server: + port: 8080 + host: "0.0.0.0" + +auth: + # Key that clients must provide to use the proxy. + # Set to null/omit to disable client auth. + proxyApiKey: "your-proxy-secret" + + # Upstream credentials come from the OAuth login flow โ€” run this first: + # bun run src/index.ts auth login + # Parsed but currently not honored โ€” the credential store path is fixed at + # ~/.zcode-proxy/credentials.json: + # oauthCredentialsPath: "~/.zcode-proxy/credentials.json" + +# Which upstream provider to use: "zai" or "bigmodel" +provider: zai + +# Which plan tier to use: +# "coding-plan" (default) โ€” direct upstream endpoints, permanent API key +# "start-plan" โ€” routes through zcode.z.ai with JWT auth (requires \`auth login\`) +plan: coding-plan + +providers: + zai: + anthropicBase: "https://api.z.ai/api/anthropic" + openaiBase: "https://api.z.ai/api/coding/paas/v4" + bigmodel: + anthropicBase: "https://open.bigmodel.cn/api/anthropic" + openaiBase: "https://open.bigmodel.cn/api/coding/paas/v4" + +defaultModel: glm-4.6 + +models: + - glm-4.5-air + - glm-4.6 + - glm-4.6v + - glm-4.7 + - glm-5 + - glm-5-turbo + - glm-5v-turbo + - glm-5.1 + - glm-5.2 + - glm-5.3 + - glm-5.3-flash + +# Configurable identity headers injected on every upstream request to mimic the +# ZCode desktop client (User-Agent, X-ZCode-App-Version, X-Title, +# X-ZCode-Agent, HTTP-Referer). Runtime platform headers (X-Platform, +# X-Os-Category, X-Os-Version) are detected dynamically and are not configured +# here. All fields below are optional; env vars override YAML, which overrides +# defaults. +identity: + # Mirrors process.env.ZCODE_APP_VERSION in the ZCode bundle. + # Must be printable ASCII; non-conforming values fall back to the default. + # Default: "3.11.2" (current ZCode release). Override to match your real client. + appVersion: "3.11.2" + # X-Title suffix โ†’ "Z Code@{sourceTitle}". Default "cli". + sourceTitle: "cli" + # HTTP-Referer URL. Default "https://zcode.z.ai". + refererOrigin: "https://zcode.z.ai" + # Device identity (X-Device-Mid) โ€” random UUIDv4, generated ONCE and reused + # forever (mirrors ZCode's telemetry deviceMid; no hardware values involved). + # Auto-generated into this file at first \`auth login\` or config creation. + # Leave empty on Android โ€” the app injects ZCODE_IDENTITY_DEVICE_MID instead. + deviceMid: "" + +# Local client-session inference for cache-affinity experiments. +# "observe" (default) logs inferred sessions in debug mode but does not change +# upstream x-session-id. "enforce" reuses a stable x-session-id for inferred +# coding-plan sessions. "off" disables inference entirely. +clientIdentity: + mode: observe + ttlSeconds: 900 + maxSessions: 1024 + +# Server-controlled upstream URL remapping (mirrors the ZCode client's +# ProviderEndpointRoutingService). The proxy periodically fetches +# {origin}/api/v1/agent/configs and rewrites matching upstream URLs per the +# returned proxyEndpoint.mapping table (currently the coding-plan Anthropic +# endpoints -> zcode.z.ai ultra endpoints). Fail-open: any fetch/parse error +# keeps the original URLs. Env override: ZCODE_ENDPOINT_ROUTING=false. +endpointRouting: + enabled: true + origin: "https://zcode.z.ai" + +# Client request signing V4 (mirrors the ZCode 3.9.1 ClientRequestSigningV4Signer). +# When enabled, the proxy probes {origin}/api/v1/agent/configs (cached 1h) and, +# only if the server sets data.codingPlanSignature.enable=true, signs coding-plan +# requests: handshake against {provider}/api/paas/c1f3a7e2/v2/client, Ed25519 +# signature + proof-of-work headers on every request, fail-open retry ladder +# (two 401 VERIFY rejections -> permanent unsigned bypass). Start-plan and +# off-peak paths are never signed. Env override: ZCODE_CLIENT_SIGNING=false. +clientSigning: + enabled: true + origin: "https://zcode.z.ai" + +logging: + level: info +`; diff --git a/src/config/types.ts b/src/config/types.ts new file mode 100644 index 0000000000000000000000000000000000000000..032ca2797764c02a26b22cfc5340da16b10917a0 --- /dev/null +++ b/src/config/types.ts @@ -0,0 +1,222 @@ +/** + * Configuration types for zcode-proxy. + * @see .omo/plans/zcode-proxy.md Task 2 + */ + +/** Provider endpoint configuration (one per upstream provider). */ +export interface ProviderEndpoints { + /** Base URL for Anthropic-format API, e.g. "https://api.z.ai/api/anthropic". */ + anthropicBase: string; + /** Base URL for OpenAI-format API, e.g. "https://api.z.ai/api/coding/paas/v4". */ + openaiBase: string; +} + +/** Auth section of the proxy configuration. */ +interface AuthConfig { + /** + * Key that clients must provide to use the proxy (via `Authorization: Bearer {proxyApiKey}`). + * If unset, the proxy does not require client auth. + */ + proxyApiKey?: string; + /** Path to stored OAuth credentials created by `auth login`. */ + oauthCredentialsPath?: string; +} + +/** + * Identity headers injected on every upstream request to mimic the ZCode + * desktop client. Mirrors the `pio` builder in the reverse-engineered bundle + * (`_reverse/zcode.cjs`); see `_reverse/NOTEPAD.md` "How Credential is Used". + * + * Resolution: env var (matches ZCode's own convention) โ†’ YAML override โ†’ default. + * `appVersion` must be printable ASCII (`/^[\x20-\x7e]+$/`); non-conforming + * values are silently dropped and fall back to the default (current ZCode + * release), exactly like `fio` in the bundle. + */ +export interface ProxyIdentity { + appVersion: string; + sourceTitle: string; + refererOrigin: string; + /** + * Device identity for `X-Device-Mid` (mirrors ZCode's telemetry deviceMid: + * a random UUIDv4 generated ONCE and reused forever โ€” no hardware values). + * Empty/undefined omits the header. Desktop: persisted in config.yaml + * (`ensureDeviceMidInConfig`). Android: injected via the + * `ZCODE_IDENTITY_DEVICE_MID` env var (NodeRunner, app-private file) โ€” env + * wins over YAML. Must stay stable per anti-pattern #13; never randomize + * per-request. + */ + deviceMid?: string; +} + +/** Local client-session inference mode for upstream session affinity. */ +export interface ClientIdentityConfig { + /** "observe" logs/instruments only; "enforce" reuses upstream x-session-id; "off" disables inference. */ + mode: "off" | "observe" | "enforce"; + /** In-memory session TTL in seconds. */ + ttlSeconds: number; + /** Maximum number of inferred sessions retained in memory. */ + maxSessions: number; +} + +/** + * Responses-API (`/v1/responses`) configuration. When `enabled`, the proxy + * translates Codex-style Responses requests to the GLM Chat Completions upstream. + */ +export interface ResponsesConfig { + /** Enable the `/v1/responses` route. Default `true`. */ + enabled: boolean; + /** Max stored responses (LRU). Default 1000. */ + storeMaxEntries: number; + /** Stored-response TTL in ms. Default 24h (in-memory; cleared on restart). */ + storeTtlMs: number; +} + +/** GLM MCP hosted-tool configuration. Endpoints are derived from the active provider. */ +export interface McpConfig { + /** Enable MCP interception (web_search) and function-tool injection (web_reader/zread). Default `true`. */ + enabled: boolean; + /** Intercept `web_search` / `web_search_preview` hosted tools via GLM `web_search_prime` MCP. Default `true`. */ + webSearch: boolean; + /** Inject `webReader` as a function tool the model can call. Default `false` (off by default to limit scope). */ + webReader: boolean; + /** Inject the three `zread` tools as function tools. Default `false`. */ + zread: boolean; +} + +/** + * Async (off-peak / idle-plan) bridge configuration. When `enabled`, exposes + * `/async/v1/messages` and `/async/v1/chat/completions` that route to ZCode's + * off-peak ticket-queue backend. The proxy keeps the client connection alive + * with SSE comments during ticket-queue wait, forwards the LLM stream once + * the ticket is `ready`, and auto-retries on ticket-expired (up to `maxRetries`). + * + * Requires a logged-in oauth credential (off-peak needs both + * `Authorization: Bearer ${jwt}` and `X-Coding-Plan-Api-Key` headers). A + * credential lacking the JWT makes the route entry return 400 + * `async_credentials_unavailable`. + * + * @see _reverse/NOTEPAD.md "Off-Peak / Idle Plan" section for full upstream protocol. + */ +export interface AsyncConfig { + /** Enable the `/async/*` routes. Default `false`. */ + enabled: boolean; + /** Base origin for off-peak endpoints. Default `"https://zcode.z.ai"`. */ + origin: string; + /** Ticket-status poll interval in ms. Default `5000`. */ + pollIntervalMs: number; + /** SSE keepalive comment interval during ticket-queue wait, in ms. Default `3000`. */ + keepAliveIntervalMs: number; + /** Maximum total wait time for a ticket to become `ready`, in ms. `0` = unlimited. Default `0`. */ + maxWaitMs: number; + /** Maximum auto-retry count on `off-peak-ticket-expired`. Default `3`. */ + maxRetries: number; + /** Settle call timeout in ms (best-effort close-out on completion/abort). Default `8000`. */ + settleTimeoutMs: number; + /** Control-plane call (takeTicket/pollStatus) timeout in ms. Default `15000`. */ + controlTimeoutMs: number; + /** Optional model override; empty string uses the request's `model`. Default `""`. */ + defaultModel: string; +} + +/** + * Manual claim ("weekend plan") โ€” mirrors the ZCode 3.10 desktop client's + * `manualClaimPlan` feature: periodically list claimable trial plans + * (`GET {origin}/api/v1/zcode-plan/billing/preview`) and, when one is + * available, claim it (`POST {origin}/api/v1/zcode-plan/billing/claim`) with + * the OAuth JWT and an Aliyun captcha token. Claimed plans grant Start-Plan + * style quota with delayed activation (`effective_at` / `starts_at`). + * + * Requires `auth.mode: oauth` (claim uses `Authorization: Bearer ${jwt}`). + * + * @see _reverse/NOTEPAD.md "Manual Claim Plan" section for the protocol. + */ +export interface ClaimConfig { + /** Enable the claim subsystem (CLI `claim` command + auto scheduler). Default `true`. */ + enabled: boolean; + /** Auto-claim in the background while the proxy is serving. Default `true` (effective when `enabled`). */ + auto: boolean; + /** Base origin of the zcode-plan billing endpoints. Default `"https://zcode.z.ai"`. */ + origin: string; + /** Preview poll interval in ms. Default `300000` (5 min). */ + pollIntervalMs: number; + /** Backoff after a failed claim attempt in ms. Default `600000` (10 min). */ + cooldownMs: number; + /** Optional `plan_id` to claim; empty string claims the highest-priority preview. Default `""`. */ + planId: string; +} + +/** + * Provider endpoint routing โ€” mirrors the ZCode client's + * `ProviderEndpointRoutingService`: periodically fetch + * `GET {configUrl}/api/v1/agent/configs` and rewrite matching upstream URLs + * per the server-controlled `data.proxyEndpoint.mapping` table. As of + * 2026-08-19 only the coding-plan Anthropic endpoints are mapped (to + * `zcode.z.ai/api/v1/ultra[-zai]/...`); resolution is generic so future + * entries apply automatically. Always fail-open. + */ +export interface EndpointRoutingConfig { + /** Enable URL remapping. Default `true`. */ + enabled: boolean; + /** Base origin of the agent-configs endpoint. Default `"https://zcode.z.ai"`. */ + origin: string; +} + +/** + * Client request signing V4 โ€” mirrors the ZCode 3.9.1 + * `ClientRequestSigningV4Signer`. When enabled, the proxy probes the same + * feature gate the client uses (`GET {origin}/api/v1/agent/configs` โ†’ + * `data.codingPlanSignature.enable`) and, only if the server turns the feature + * on, signs coding-plan upstream requests (handshake + Ed25519 + proof-of-work, + * with the client's fail-open retry ladder). Start-plan and off-peak paths are + * permanently exempt. + */ +export interface ClientSigningConfig { + /** Enable gate probing + signing. Default `true`. */ + enabled: boolean; + /** Base origin of the feature-gate endpoint. Default `"https://zcode.z.ai"`. */ + origin: string; +} + +/** Top-level proxy configuration. */ +export interface ProxyConfig { + server: { + port: number; + host: string; + }; + auth: AuthConfig; + /** Active upstream provider. */ + provider: "zai" | "bigmodel"; + /** Which plan tier to use. "coding-plan" (default) uses direct upstream endpoints; "start-plan" routes through zcode.z.ai with JWT auth. */ + plan: "coding-plan" | "start-plan"; + /** Per-provider endpoint overrides. */ + providers: { + zai: ProviderEndpoints; + bigmodel: ProviderEndpoints; + }; + /** Default model id used when client request omits `model`. */ + defaultModel: string; + /** Whitelist of allowed model ids. */ + models: string[]; + /** + * Identity headers injected upstream. Always present after `loadConfig`; + * defaults mirror the production ZCode desktop client. + */ + identity: ProxyIdentity; + /** Local client session inference for cache-affinity experiments. */ + clientIdentity: ClientIdentityConfig; + /** Responses-API (`/v1/responses`) configuration. */ + responses: ResponsesConfig; + /** Server-controlled upstream URL remapping (ultra endpoints). */ + endpointRouting: EndpointRoutingConfig; + /** Client request signing V4 (Ed25519 + PoW, gate-driven). */ + clientSigning: ClientSigningConfig; + /** GLM MCP hosted-tool configuration. */ + mcp: McpConfig; + /** Async (off-peak / idle-plan) bridge configuration. */ + async: AsyncConfig; + /** Manual claim ("weekend plan") configuration. */ + claim: ClaimConfig; + logging: { + level: "debug" | "info" | "warn" | "error"; + }; +} diff --git a/src/index.ts b/src/index.ts new file mode 100644 index 0000000000000000000000000000000000000000..bde498b8d9da85afc4fc646d9c8c77aaf990d6a3 --- /dev/null +++ b/src/index.ts @@ -0,0 +1,596 @@ +/** + * Entry point โ€” load config, create auth manager, start proxy server. + * @see .omo/plans/zcode-proxy.md Task 7 + */ +import { loadConfig } from "./config/loader.js"; +import { AuthManager } from "./auth/manager.js"; +import { startServer, type ProxyServer } from "./server/server.js"; +import { startControlListener, LogBuffer, type ControlState } from "./android/control.js"; +import { loadCredential, saveCredential, clearCredential, getStorePath } from "./auth/store.js"; +import { ZaiOAuthClient, BigmodelOAuthClient, LOGIN_TIMEOUT_MS, parsePastedCallbackUrl, type OAuthResult } from "./auth/oauth.js"; +import { KeyResolver } from "./auth/resolver.js"; +import type { Credential } from "./auth/types.js"; +import type { ProviderId } from "./provider/types.js"; +import type { ProxyConfig } from "./config/types.js"; +import { updateConfigYaml, ensureConfigFile } from "./config/edit.js"; +import { openBrowser } from "./runtime/open-browser.js"; +import { pasteLoginInstructions, readPastedLine, boldIfTTY } from "./runtime/paste-login.js"; +import { buildServerOptions } from "./server/server-options.js"; +import { readFileSync, existsSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { homedir } from "node:os"; +import { randomUUID } from "node:crypto"; +import { ensureNodeFetchNoTimeouts } from "./runtime/node-fetch-compat.js"; + +export const VERSION = "4.6.3"; + +if (require.main === module) main(); + +export interface ServeArgs { + configPath?: string; + debug: boolean; +} + +/** + * Parse `serve` subcommand arguments. The token `debug` toggles debug mode; + * any other token is treated as the config path. Order-independent: + * [] โ†’ { debug: false } + * ["debug"] โ†’ { debug: true } + * ["my.yaml"] โ†’ { configPath: "my.yaml", debug: false } + * ["debug","x.yaml"] โ†’ { configPath: "x.yaml", debug: true } + * ["x.yaml","debug"] โ†’ { configPath: "x.yaml", debug: true } + */ +export function parseServeArgs(args: string[]): ServeArgs { + const debug = args.includes("debug"); + const configPath = args.find((a) => a !== "debug"); + return { configPath, debug }; +} + +export function main(): void { + // Fire-and-forget is race-safe: the dynamic import resolves in a microtask, + // before the listener's event-loop callback can admit a request. + void ensureNodeFetchNoTimeouts(); + try { + runCli(); + } catch (err) { + process.stderr.write(`zcode-proxy: uncaught error: ${(err as Error).stack ?? String(err)}\n`); + process.exit(1); + } +} + +function runCli(): void { + const args = process.argv.slice(2); + + // `--cli` opts out of the default TUI and restores the classic CLI dispatch + // (bare `--cli` = the old no-arg default: serve). + if (args[0] === "--cli") { + dispatchCli(args.slice(1)); + return; + } + // Default surface is the TUI. Bare invocation, the retired `tui` token + // (kept as a silent alias), and tui-style args (`debug`, `*.yaml`) all land + // here โ€” the former `tui ` subcommand simply dropped its prefix. + if ( + args.length === 0 || + args[0] === "tui" || + args[0] === "debug" || + args[0].endsWith(".yaml") || + args[0].endsWith(".yml") + ) { + launchTui(parseServeArgs(args[0] === "tui" ? args.slice(1) : args)); + return; + } + dispatchCli(args); +} + +/** Classic CLI dispatch โ€” subcommand routing where bare = serve. */ +function dispatchCli(args: string[]): void { + const cmd = args[0] ?? "serve"; + + if (cmd === "auth") { + authCommand(args.slice(1)); + } else if (cmd === "claim") { + void claimCommand(args.slice(1)); + } else if (cmd === "android") { + // Explicit catch: an async startup failure (e.g. control port already + // bound by an orphaned process) must exit non-zero deterministically, not + // surface as an unhandled rejection. + runAndroid().catch((err: unknown) => { + process.stderr.write(`zcode-proxy: android entry failed: ${(err as Error).stack ?? String(err)}\n`); + process.exit(1); + }); + } else if (cmd === "tui") { + // Kept for muscle memory under `--cli`: the default dispatch already + // routes `tui` to the TUI, but `--cli tui` should not regress to an error. + launchTui(parseServeArgs(args.slice(1))); + } else if (cmd === "serve" || cmd.endsWith(".yaml") || cmd.endsWith(".yml")) { + const serveArgs = cmd === "serve" + ? parseServeArgs(args.slice(1)) + : parseServeArgs(args); + serve(serveArgs.configPath, serveArgs.debug); + } else if (cmd === "version" || cmd === "--version" || cmd === "-v") { + console.log(`zcode-proxy ${VERSION}`); + } else if (cmd === "help" || cmd === "--help" || cmd === "-h") { + printHelp(); + } else { + console.error(`Unknown command: ${cmd}\n`); + printHelp(); + process.exit(1); + } +} + +function launchTui(args: ServeArgs): void { + // Dynamic import: the TUI module imports helpers back from this file, so a + // static edge would create a load-time cycle (same pattern as claimCommand). + import("./tui/app.js") + .then((m) => m.runTui(args)) + .catch((err: unknown) => { + process.stderr.write(`zcode-proxy: tui failed: ${(err as Error).stack ?? String(err)}\n`); + process.exit(1); + }); +} + +function printHelp(): void { + console.log(`zcode-proxy ${VERSION} + +Usage: + zcode-proxy Interactive terminal UI (default): + login, start/stop, live logs + zcode-proxy [debug] [config.yaml] Same, with debug diagnostics / custom config + zcode-proxy serve [config.yaml] Start the proxy server (classic CLI mode) + zcode-proxy serve debug [config.yaml] + Start with verbose per-request diagnostics + zcode-proxy --cli Classic CLI mode (bare --cli = serve) + zcode-proxy android Android entry: proxy + localhost control listener + zcode-proxy auth login Login via OAuth (provider: zai | bigmodel) + zcode-proxy auth login --import + Import API key from ~/.zcode/v2/config.json + zcode-proxy auth logout Clear stored credentials + zcode-proxy auth status Show current authentication state + zcode-proxy claim [list|now] List / claim weekend-plan trial packages + zcode-proxy version Show version + zcode-proxy help Show this help + +Examples: + zcode-proxy Terminal UI: login, start/stop, live logs + zcode-proxy debug Terminal UI with per-request diagnostics + zcode-proxy serve debug CLI: start with extra debug logging + zcode-proxy auth login bigmodel OAuth login for Bigmodel + zcode-proxy auth login bigmodel --import + Import existing key from ZCode config + zcode-proxy auth status Check if logged in +`); +} + +async function serve(configPath: string | undefined, debug: boolean): Promise { + const path = configPath ?? process.env.ZCODE_PROXY_CONFIG ?? "config.yaml"; + if (ensureConfigFile(path)) { + ensureDeviceMidInConfig(path); + console.log(`Created ${path} from bundled template.`); + console.log(`Run: zcode-proxy auth login \n`); + } + const config = loadConfig(path); + + const auth = new AuthManager(); + const cred = await loadCredential(); + if (!cred) { + console.error("Not logged in. Run: zcode-proxy auth login " + config.provider); + process.exit(1); + } + auth.setOAuthCredential(cred); + + if (debug) printDebugBanner(config, path, cred); + + const server = await startServer(buildServerOptions(config, auth, debug)); + const url = `http://${server.hostname}:${server.port}`; + console.log(`zcode-proxy listening on ${url}`); + if (config.plan === "start-plan") { + // Pre-solve the captcha token pool in the background so first requests + // don't pay the full solve latency (in-process happy-dom backend). + import("./proxy/captcha.js") + .then((m) => m.startCaptchaPool(config.identity.appVersion)) + .catch((err) => console.error(`[captcha] pool warmup failed: ${(err as Error).message}`)); + } + if (config.claim.enabled && config.claim.auto) { + import("./claim/runtime.js") + .then((m) => { + m.startAutoClaim(config, auth); + console.log(` claim: auto ON (poll ${Math.round(config.claim.pollIntervalMs / 1000)}s)`); + }) + .catch((err) => console.error(`[claim] scheduler failed to start: ${(err as Error).message}`)); + } + console.log(` provider: ${config.provider}`); + console.log(` plan: ${config.plan}`); + console.log(` models: ${config.models.length} available`); + if (config.responses.enabled) console.log(` /v1/responses: ON`); + if (config.async.enabled) { + console.log(config.plan === "coding-plan" ? ` /async/v1/*: ON` : ` /async/v1/*: OFF (requires plan "coding-plan")`); + } + if (debug) console.log(` debug: ON`); + + process.on("SIGINT", () => { + console.log("\nShutting down..."); + server.stop(true); + }); + process.on("SIGTERM", () => { + server.stop(true); + }); +} + +/** + * Desktop-Linux identity defaults for the Android entry (anti-pattern #34). + * Without these, the Node process on Android reports its true host values: + * `X-Platform: linux-arm64` and `X-Os-Version: 6.1.xx-android14-โ€ฆ` โ€” a kernel + * string no real ZCode desktop emits. `identity.ts` reads these env vars per + * request, so setting them once here retargets every upstream call. Values are + * deliberately CONSTANT (Ubuntu 24.04 x64 profile โ€” the largest desktop-Linux + * population): kernel strings are shared by millions of real machines, and + * stability is required by anti-pattern #13 (never randomize fingerprints). + * Explicit env values (adb shell setprop / NodeRunner) still win โ€” each is set + * with `??`, not unconditionally. + */ +export function applyAndroidIdentityDefaults(): void { + process.env.ZCODE_IDENTITY_PLATFORM = process.env.ZCODE_IDENTITY_PLATFORM ?? "linux"; + process.env.ZCODE_IDENTITY_ARCH = process.env.ZCODE_IDENTITY_ARCH ?? "x64"; + process.env.ZCODE_IDENTITY_RELEASE = process.env.ZCODE_IDENTITY_RELEASE ?? "6.8.0-49-generic"; +} + +/** + * Android entry โ€” starts the proxy plus a localhost control listener. + * Caller (Kotlin shell) must set env: ZCODE_CONTROL_PORT (control listener), + * ZCODE_OAUTH_CALLBACK_PORT (fixed OAuth callback port for WebView redirect). + */ +async function runAndroid(): Promise { + applyAndroidIdentityDefaults(); + const path = process.env.ZCODE_PROXY_CONFIG ?? "config.yaml"; + ensureConfigFile(path); + const config = loadConfig(path); + + const logBuffer = new LogBuffer(); + const origLog = console.log; + const origErr = console.error; + const origWarn = console.warn; + console.log = (...args: unknown[]) => { logBuffer.push(args.join(" ")); origLog(...args); }; + console.error = (...args: unknown[]) => { logBuffer.push("[error] " + args.join(" ")); origErr(...args); }; + console.warn = (...args: unknown[]) => { logBuffer.push("[warn] " + args.join(" ")); origWarn(...args); }; + + const auth = new AuthManager(); + + const serverRef: { current: ProxyServer | null } = { current: null }; + + async function startProxy(): Promise<{ ok: true; port: number } | { ok: false; error: string }> { + if (serverRef.current) return { ok: false, error: "already_running" }; + const cred = await loadCredential().catch(() => null); + if (!cred) return { ok: false, error: "not_logged_in" }; + auth.setOAuthCredential(cred); + try { + const s = await startServer(buildServerOptions(config, auth, false)); + serverRef.current = s; + console.log(`zcode-proxy listening on http://${s.hostname}:${s.port}`); + return { ok: true, port: s.port }; + } catch (err) { + return { ok: false, error: (err as Error).message }; + } + } + + async function stopProxy(): Promise<{ ok: true } | { ok: false; error: string }> { + const s = serverRef.current; + if (!s) return { ok: false, error: "not_running" }; + try { + s.stop(false); + serverRef.current = null; + console.log("zcode-proxy stopped"); + return { ok: true }; + } catch (err) { + return { ok: false, error: (err as Error).message }; + } + } + + async function setConfig(changes: { + provider?: ProviderId; + plan?: "coding-plan" | "start-plan"; + }): Promise<{ ok: true; provider: ProviderId; plan: "coding-plan" | "start-plan" } | { ok: false; error: string }> { + if (serverRef.current) return { ok: false, error: "stop_proxy_first" }; + if (changes.provider) config.provider = changes.provider; + if (changes.plan) config.plan = changes.plan; + updateConfigYaml(path, { provider: config.provider, plan: config.plan }); + console.log(`config updated: provider=${config.provider} plan=${config.plan}`); + return { ok: true, provider: config.provider, plan: config.plan }; + } + + console.log("control listener ready; proxy stopped โ€” use startProxy command to start"); + + if (config.claim.enabled && config.claim.auto) { + import("./claim/runtime.js") + .then((m) => { + m.startAutoClaim(config, auth); + console.log(`[claim] auto ON (poll ${Math.round(config.claim.pollIntervalMs / 1000)}s; waits for login)`); + }) + .catch((err) => console.error(`[claim] scheduler failed to start: ${(err as Error).message}`)); + } + + const controlPort = Number(process.env.ZCODE_CONTROL_PORT ?? 0) || 0; + const controlState: ControlState = { + provider: config.provider, + plan: config.plan, + proxyPort: serverRef.current?.port ?? 0, + }; + const controlListener = await startControlListener({ + port: controlPort, + state: controlState, + logBuffer, + onStartProxy: startProxy, + onStopProxy: stopProxy, + onSetConfig: setConfig, + onShutdown: async () => { + serverRef.current?.stop(true); + }, + }); + + console.log(`control listener: 127.0.0.1:${controlPort}`); + console.log(`provider: ${config.provider}`); + console.log(`plan: ${config.plan}`); + + process.on("SIGINT", () => { + void controlListener.close().then(() => serverRef.current?.stop(true)); + }); + process.on("SIGTERM", () => { + void controlListener.close().then(() => serverRef.current?.stop(true)); + }); +} + +function printDebugBanner(config: ProxyConfig, path: string, cred: Credential | null): void { + const credShape = cred + ? `${cred.apiKey.slice(0, 6)}...${cred.apiKey.slice(-4)} (${cred.apiKey.length} chars)` + : "(none)"; + const active = config.providers[config.provider]; + console.log("=== zcode-proxy DEBUG MODE ==="); + console.log(` config file: ${path}`); + console.log(` server: ${config.server.host}:${config.server.port}`); + console.log(` proxy api key: ${config.auth.proxyApiKey ? "required" : "open (no client auth)"}`); + console.log(` provider: ${config.provider}`); + console.log(` plan: ${config.plan}`); + console.log(` identity: appVersion=${config.identity.appVersion} sourceTitle=${config.identity.sourceTitle} referer=${config.identity.refererOrigin}`); + console.log(` client identity: mode=${config.clientIdentity.mode} ttl=${config.clientIdentity.ttlSeconds}s max=${config.clientIdentity.maxSessions}`); + console.log(` anthropic base: ${active.anthropicBase}`); + console.log(` openai base: ${active.openaiBase}`); + console.log(` credential: ${credShape}`); + console.log(` models (${config.models.length}): ${config.models.join(", ")}`); + console.log(` log level: ${config.logging.level}`); + console.log("==============================="); +} + +function authCommand(args: string[]): void { + const sub = args[0]; + + if (sub === "login") { + authLogin(args.slice(1)); + } else if (sub === "logout") { + authLogout(); + } else if (sub === "status") { + authStatus(); + } else { + console.error("Usage: zcode-proxy auth "); + process.exit(1); + } +} + +async function claimCommand(args: string[]): Promise { + const sub = args[0] ?? "now"; + if (sub !== "list" && sub !== "now") { + console.error("Usage: zcode-proxy claim [list|now]"); + process.exit(1); + } + const path = process.env.ZCODE_PROXY_CONFIG ?? "config.yaml"; + if (!existsSync(path)) { + console.error(`Config file not found: ${path} (run serve once or create it).`); + process.exit(1); + } + // The billing gateway requires a stable X-Device-Mid โ€” self-heal configs + // created before the deviceMid feature (idempotent: reuses existing value). + ensureDeviceMidInConfig(path); + const config = loadConfig(path); + try { + const { runClaimCli } = await import("./claim/runtime.js"); + await runClaimCli(config, sub); + } catch (err) { + console.error(`claim failed: ${(err as Error).message}`); + process.exit(1); + } +} + +async function authLogin(args: string[]): Promise { + const provider = args[0] as ProviderId | undefined; + const importMode = args.includes("--import"); + // Headless paste login: --paste flag or ZCODE_OAUTH_PASTE=1 (docker-friendly). + const pasteMode = + args.includes("--paste") || /^(1|true|yes)$/i.test(process.env.ZCODE_OAUTH_PASTE ?? ""); + + if (!provider || (provider !== "zai" && provider !== "bigmodel")) { + console.error("Usage: zcode-proxy auth login [--import] [--paste]"); + process.exit(1); + } + if (pasteMode && provider !== "bigmodel") { + console.error("--paste applies to the bigmodel auth-code flow only."); + console.error("zai login is server-mediated (no localhost callback) and already works headless."); + process.exit(1); + } + + ensureConfigWithDeviceMid(); + + const mode = importMode ? "(import)" : pasteMode ? "(OAuth, paste)" : "(OAuth)"; + console.log(`Logging in: ${provider} ${mode}\n`); + + let cred: Credential; + + if (importMode) { + cred = importFromZCodeConfig(provider); + } else { + const { accessToken, userId, jwt } = await runOAuth(provider, pasteMode); + console.log("\nResolving API key..."); + const resolver = new KeyResolver(); + cred = await resolver.resolveCodingPlanCredential(accessToken, provider, userId); + if (jwt) cred.jwt = jwt; + } + + await saveCredential(cred); + console.log(`\nLogged in as ${provider}.`); + console.log(` API Key: ${cred.apiKey.substring(0, 12)}...`); + if (cred.userId) console.log(` User ID: ${cred.userId}`); + console.log(` Stored: ${getStorePath()}`); +} + +/** + * Ensure config.yaml exists and carries a stable `identity.deviceMid`. + * Creates the file from the bundled template when missing (desktop flow; + * Android's mid comes from NodeRunner env injection instead and is never + * written here). Returns the mid (existing or freshly generated). + */ +function ensureConfigWithDeviceMid(): string { + const path = process.env.ZCODE_PROXY_CONFIG ?? "config.yaml"; + if (ensureConfigFile(path)) { + console.log(`Created ${path} from bundled template.`); + } + return ensureDeviceMidInConfig(path); +} + +/** + * Generate-or-reuse `identity.deviceMid` in a YAML config via targeted line + * edit (comments preserved): fills an empty `deviceMid:` value, inserts one + * under a block-style `identity:` key, or appends a new `identity:` block when + * the key is absent entirely. Idempotent โ€” an existing non-empty value is + * returned untouched. The regexes are function-local on purpose: `main()` runs + * synchronously at module top (before later top-level statements initialize), + * so any module-level const this function touches would still be undefined on + * the boot-time `serve` path. + */ +export function ensureDeviceMidInConfig(path: string): string { + const deviceMidLine = /^(\s*)deviceMid:\s*(.*)$/m; + const identityBlockLine = /^identity:\s*$/m; + const raw = readFileSync(path, "utf-8"); + + const existing = deviceMidLine.exec(raw); + if (existing) { + const value = existing[2].trim().replace(/^"|"$/g, ""); + if (value.length > 0) return value; + } + + const mid = randomUUID(); + let updated: string; + if (existing) { + updated = raw.replace(deviceMidLine, `${existing[1]}deviceMid: "${mid}"`); + } else if (identityBlockLine.test(raw)) { + updated = raw.replace(identityBlockLine, `identity:\n deviceMid: "${mid}"`); + } else { + const block = `identity:\n deviceMid: "${mid}"\n`; + updated = raw.endsWith("\n") || raw.length === 0 ? raw + block : raw + "\n" + block; + } + writeFileSync(path, updated, "utf-8"); + console.log(`Device identity generated: ${mid.slice(0, 8)}โ€ฆ (stored in ${path})`); + return mid; +} + +function authLogout(): void { + if (!existsSync(getStorePath())) { + console.log("Not logged in."); + return; + } + clearCredential(); + console.log("Logged out. Credentials removed."); +} + +async function authStatus(): Promise { + const cred = await loadCredential(); + if (!cred) { + console.log("Not logged in."); + console.log("Run: zcode-proxy auth login "); + return; + } + console.log(`Logged in: ${cred.provider}`); + console.log(` API Key: ${cred.apiKey.substring(0, 12)}...`); + console.log(` Store: ${getStorePath()}`); +} + +async function runOAuth(provider: ProviderId, pasteMode: boolean): Promise { + if (provider === "bigmodel") { + const oauth = new BigmodelOAuthClient(); + if (pasteMode) return runPasteLogin(oauth); + const result = await oauth.authorize((url) => { + console.log("Open this URL to authorize:\n"); + console.log(` ${url}\n`); + console.log("Waiting for authorization... (expires in 300s)\n"); + console.log( + "Headless/Docker? The callback page will NOT load here โ€” Ctrl-C and " + + "re-run with `auth login bigmodel --paste` to paste the redirected URL instead.\n", + ); + openBrowser(url); + }); + return result; + } + + const oauth = new ZaiOAuthClient(); + const result = await oauth.authorize((url) => { + console.log("Open this URL to authorize:\n"); + console.log(` ${url}\n`); + console.log("Waiting for authorization... (expires in 300s)\n"); + openBrowser(url); + }); + return result; +} + +/** + * Headless bigmodel login (`auth login bigmodel --paste`): the localhost + * callback server is still bound โ€” it defines the redirect port and the + * browser can never reach it from inside a container anyway โ€” but instead of + * waiting on it, the user pastes the redirected URL back. The exact + * `started.callbackUrl` string is used BOTH as the authorize `redirect` param + * and as the exchange `redirect_uri` (the token endpoint requires them to + * match), so the pair stays consistent by construction. + */ +async function runPasteLogin(oauth: BigmodelOAuthClient): Promise { + const started = await oauth.start(); + try { + console.log(pasteLoginInstructions(started.authorizeUrl, started.callbackUrl, LOGIN_TIMEOUT_MS)); + openBrowser(started.authorizeUrl); + process.stdout.write("\n" + boldIfTTY("Paste the FULL redirected URL here, then press Enter:") + "\n> "); + const pasted = await readPastedLine(LOGIN_TIMEOUT_MS); + const code = parsePastedCallbackUrl(pasted, started.state); + console.log("\nExchanging authorization code..."); + const tokens = await oauth.exchangeCode(code, started.callbackUrl, started.state); + return { accessToken: tokens.accessToken, provider: "bigmodel", userId: tokens.userId, jwt: tokens.jwt }; + } finally { + await oauth.close(); + } +} + +function importFromZCodeConfig(provider: ProviderId): Credential { + const configPath = join(homedir(), ".zcode", "v2", "config.json"); + let raw: string; + try { + raw = readFileSync(configPath, "utf-8"); + } catch { + console.error(`Cannot read ${configPath}.`); + console.error("Make sure ZCode is installed and you've logged in at least once."); + process.exit(1); + } + + const config = JSON.parse(raw) as { + provider?: Record; + }; + + const providerKey = `builtin:${provider}-coding-plan`; + const entry = config.provider?.[providerKey]; + const apiKey = entry?.options?.apiKey?.trim(); + + if (!apiKey) { + console.error(`No API key for ${providerKey} in ZCode config.`); + process.exit(1); + } + + const startPlanKey = `builtin:${provider}-start-plan`; + const jwt = config.provider?.[startPlanKey]?.options?.apiKey?.trim() || undefined; + + console.log(`Imported from ${configPath}`); + if (jwt) console.log(` Start-plan JWT: ${jwt.slice(0, 12)}...`); + return { apiKey, provider, jwt }; +} diff --git a/src/mcp/client.ts b/src/mcp/client.ts new file mode 100644 index 0000000000000000000000000000000000000000..8a07879c0d82836f44eeb622e9d6adc4a20e6ded --- /dev/null +++ b/src/mcp/client.ts @@ -0,0 +1,315 @@ +/** + * Minimal MCP (Model Context Protocol) JSON-RPC client for GLM's remote MCP + * servers. Designed for the GLM wire shape verified by live probing (see + * `_reverse/NOTEPAD.md` and the exploration notes): + * + * - Transport: Streamable HTTP over POST; responses are ALWAYS + * `text/event-stream` (server ignores `Accept: application/json`). + * - Each SSE frame is a 3-line block: + * `id:1` (SSE event id, fixed โ€” NOT the JSON-RPC id, ignore it) + * `event:message` + * `data:{}` + * - Sessions are mandatory: `initialize` returns `Mcp-Session-Id`, and every + * subsequent request MUST carry it back as a header. + * - Protocol version: client sends `2025-06-18`; server downgrades to + * `2024-11-05`. We accept whatever the server returns. + * - `notifications/initialized` must be sent once after `initialize` (HTTP + * 200 with empty body, no SSE). + * - Auth failure returns HTTP 200 with a non-JSON-RPC envelope: + * `{"code":1001,"msg":"...","success":false}` (not a JSON-RPC error) โ€” + * the client detects this and throws `McpAuthError`. + * - Tool results carry a `content[]` array of `{type:"text",text}` blocks; + * some tools (web_search_prime) return a *doubly-encoded* JSON string in + * `text` (a stringified JSON array) โ€” the caller decodes. + * + * No external dependencies. Pure `fetch()`. Works on both Bun and Node. + * + * @see https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle + * @see https://modelcontextprotocol.io/specification/2025-06-18/server/tools + */ +import type { ProviderId } from "../provider/types.js"; + +/** MCP tool definition (subset we care about). */ +export interface McpToolDef { + name: string; + description?: string; + inputSchema?: Record; +} + +/** Result of a successful tools/call. */ +export interface McpToolCallResult { + content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType?: string }>; + isError: boolean; +} + +/** Thrown when the server returns the non-JSON-RPC auth envelope. */ +export class McpAuthError extends Error { + readonly code: number; + constructor(code: number, msg: string) { + super(`MCP auth error (code=${code}): ${msg}`); + this.name = "McpAuthError"; + this.code = code; + } +} + +/** Thrown when the server returns a JSON-RPC `error` object. */ +export class McpRpcError extends Error { + readonly code: number; + constructor(code: number, message: string) { + super(`MCP RPC error (code=${code}): ${message}`); + this.name = "McpRpcError"; + this.code = code; + } +} + +export interface McpClientOptions { + /** Full MCP endpoint URL, e.g. `https://open.bigmodel.cn/api/mcp/web_search_prime/mcp`. */ + url: string; + /** Bearer credential โ€” same GLM API key used for the LLM upstream. */ + apiKey: string; + /** Protocol version to advertise in `initialize`; default `2025-06-18`. */ + protocolVersion?: string; + /** Per-request timeout in ms; default 30000. */ + timeoutMs?: number; + /** DI seam for tests. Defaults to global `fetch`. */ + fetchImpl?: typeof fetch; +} + +interface JsonRpcResponse { + jsonrpc: "2.0"; + id?: number | string; + result?: unknown; + error?: { code: number; message: string; data?: unknown }; +} + +const DEFAULT_PROTOCOL_VERSION = "2025-06-18"; +const DEFAULT_TIMEOUT_MS = 30000; + +/** + * Stateless-per-instance is forbidden by GLM (session is required), so a client + * owns its session. One instance per (server, apiKey) โ€” pool via `GlmMcpPool`. + */ +export class McpClient { + private readonly url: string; + private readonly apiKey: string; + private readonly protocolVersion: string; + private readonly timeoutMs: number; + private readonly fetchImpl: typeof fetch; + private sessionId: string | undefined; + private nextId = 1; + private initialized = false; + + constructor(opts: McpClientOptions) { + this.url = opts.url; + this.apiKey = opts.apiKey; + this.protocolVersion = opts.protocolVersion ?? DEFAULT_PROTOCOL_VERSION; + this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS; + this.fetchImpl = opts.fetchImpl ?? fetch; + } + + /** + * Perform the MCP handshake: `initialize` (captures session id) + + * `notifications/initialized`. Idempotent โ€” subsequent calls are no-ops. + * Called lazily by `listTools` / `callTool`. + */ + async initialize(): Promise { + if (this.initialized) return; + const initResp = await this.postRpc("initialize", { + protocolVersion: this.protocolVersion, + capabilities: {}, + clientInfo: { name: "zcode-proxy", version: "2.2.0" }, + }); + const result = initResp.json.result as { protocolVersion?: string } | undefined; + // GLM downgrades the version; we accept the server's choice silently. + void result?.protocolVersion; + this.initialized = true; + // notifications/initialized has no response body; swallow the empty SSE. + try { + await this.postRpc("notifications/initialized", undefined); + } catch { + // Some servers return empty bodies that fail SSE parse โ€” safe to ignore. + } + } + + /** List the tools the server exposes. */ + async listTools(): Promise { + await this.initialize(); + const resp = await this.postRpc("tools/list", {}); + const result = resp.json.result as { tools?: McpToolDef[] } | undefined; + return result?.tools ?? []; + } + + /** Invoke a tool. Returns the raw `content[]`; callers decode per-tool. */ + async callTool(name: string, args: Record): Promise { + await this.initialize(); + const resp = await this.postRpc("tools/call", { name, arguments: args }); + const result = resp.json.result as McpToolCallResult | undefined; + if (!result || !Array.isArray(result.content)) { + throw new McpRpcError(-32603, `tool "${name}" returned malformed result`); + } + return result; + } + + /** Drop the session. Next call re-initializes. Safe to call when not initialized. */ + reset(): void { + this.sessionId = undefined; + this.initialized = false; + } + + /** + * Send a JSON-RPC request and parse the SSE response. For notifications + * (no `id`) the response is empty โ€” the parser tolerates a 0-event stream. + */ + private async postRpc( + method: string, + params: unknown, + ): Promise<{ json: JsonRpcResponse; headers: Headers }> { + const id = method.startsWith("notifications/") ? undefined : this.nextId++; + const body: string = JSON.stringify({ + jsonrpc: "2.0", + ...(id !== undefined ? { id } : {}), + method, + ...(params !== undefined ? { params } : {}), + }); + + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), this.timeoutMs); + let httpResp: Response; + try { + httpResp = await this.fetchImpl(this.url, { + method: "POST", + headers: { + "content-type": "application/json", + accept: "application/json, text/event-stream", + authorization: `Bearer ${this.apiKey}`, + ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}), + }, + body, + signal: controller.signal, + }); + } finally { + clearTimeout(timer); + } + + if (!httpResp.ok) { + throw new McpRpcError(-32000, `HTTP ${httpResp.status} ${httpResp.statusText}`); + } + + // Capture the session id on the FIRST response (initialize). + if (!this.sessionId) { + const sid = httpResp.headers.get("mcp-session-id"); + if (sid) this.sessionId = sid; + } + + const contentType = httpResp.headers.get("content-type") ?? ""; + const raw = await httpResp.text(); + + // GLM's auth failures are HTTP 200 + a non-JSON-RPC envelope. + if (!contentType.includes("event-stream") && !contentType.includes("application/json")) { + // Still inspect the body โ€” some auth failures come back without a proper CT. + throw this.classifyEnvelope(raw); + } + + // Empty body (notifications/initialized) โ†’ no JSON-RPC payload to return. + if (raw.length === 0 || raw.trim() === "") { + return { json: { jsonrpc: "2.0" }, headers: httpResp.headers }; + } + + const payload = contentType.includes("event-stream") + ? parseSseFrame(raw) + : safeParseJson(raw); + + if (payload === null) { + // Could be the auth envelope on a 200 with no/odd CT. + throw this.classifyEnvelope(raw); + } + + // Detect GLM's auth envelope even when it leaks into a JSON-looking CT. + if ( + typeof payload === "object" + && payload !== null + && "success" in payload + && payload.success === false + && typeof (payload as { code?: unknown }).code === "number" + && !("jsonrpc" in payload) + ) { + const env = payload as unknown as { code: number; msg?: string }; + throw new McpAuthError(env.code, env.msg ?? "auth failed"); + } + + const jsonRpc = payload as JsonRpcResponse; + if (jsonRpc.error) { + throw new McpRpcError(jsonRpc.error.code, jsonRpc.error.message); + } + return { json: jsonRpc, headers: httpResp.headers }; + } + + /** Parse a body as JSON; if it looks like GLM's `{code, msg, success:false}` envelope, return the right error. */ + private classifyEnvelope(raw: string): Error { + const parsed = safeParseJson(raw); + if ( + parsed !== null + && typeof parsed === "object" + && parsed !== null + && "success" in parsed + && (parsed as { success?: unknown }).success === false + && typeof (parsed as { code?: unknown }).code === "number" + ) { + const env = parsed as unknown as { code: number; msg?: string }; + return new McpAuthError(env.code, env.msg ?? "auth failed"); + } + return new McpRpcError(-32700, `unparseable MCP response (content-type missing, body: ${raw.slice(0, 200)})`); + } +} + +/** + * Parse one SSE frame from GLM's response into a JSON value. + * + * GLM emits exactly one `data:` line per response, so this is simpler than a + * full streaming parser. The frame shape (verified by probing): + * + * id:1 + * event:message + * data:{"jsonrpc":"2.0",...} + * + * `id:1` is the SSE event id (fixed at 1 by the server โ€” not the JSON-RPC id). + * We ignore it and parse only the `data:` payload. + */ +function parseSseFrame(raw: string): unknown { + let dataLine: string | null = null; + for (const line of raw.split(/\r?\n/)) { + if (line.startsWith("data:")) { + // GLM uses `data:{...}` (no space). Tolerate both forms. + dataLine = line.slice(5).replace(/^\s/, ""); + break; + } + } + if (dataLine === null) return null; + return safeParseJson(dataLine); +} + +function safeParseJson(raw: string): unknown { + try { + return JSON.parse(raw); + } catch { + return null; + } +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Provider-aware endpoint derivation +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** GLM MCP host per provider (verified: both providers serve identical MCP shapes). */ +const MCP_HOSTS: Record = { + bigmodel: "https://open.bigmodel.cn", + zai: "https://api.z.ai", +}; + +/** GLM MCP server identifiers. Path is `/api/mcp/{server}/mcp` for both providers. */ +export type GlmMcpServerId = "web_search_prime" | "web_reader" | "zread"; + +/** Build the full MCP endpoint URL for a (provider, server) pair. */ +export function glmMcpEndpoint(provider: ProviderId, server: GlmMcpServerId): string { + return `${MCP_HOSTS[provider]}/api/mcp/${server}/mcp`; +} diff --git a/src/mcp/glm-tools.ts b/src/mcp/glm-tools.ts new file mode 100644 index 0000000000000000000000000000000000000000..379528e46a28688e21df1912392aedd500621f5b --- /dev/null +++ b/src/mcp/glm-tools.ts @@ -0,0 +1,192 @@ +/** + * GLM MCP server registry + tool-call wrappers for the three official remote + * MCP servers (web_search_prime / web_reader / zread). All three use the same + * GLM API key as the LLM upstream, and their endpoints are derived from the + * active provider (see `glmMcpEndpoint`). + * + * Used by the Responses handler to: + * - intercept `web_search` / `web_search_preview` hosted tools and route + * them to GLM's `web_search_prime` MCP tool, + * - (P2, off by default) inject `web_reader` / `zread` as function tools the + * model can call directly. + * + * Each wrapper decodes the MCP result into a typed shape. `web_search_prime` is + * the trickiest: its `content[0].text` is a *doubly-encoded* JSON string (a + * stringified JSON array). The wrapper does `JSON.parse` once to unwrap the + * array, leaving consumers with a clean `WebSearchHit[]`. + */ +import { McpClient, glmMcpEndpoint, type GlmMcpServerId, type McpClientOptions } from "./client.js"; +import type { ProviderId } from "../provider/types.js"; + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Result types +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +export interface WebSearchHit { + title: string; + link: string; + content: string; + /** GLM's per-result reference id (e.g. "ref_1"). */ + refer?: string; +} + +export interface WebPageContent { + /** Decoded page content (markdown or text, per `return_format`). */ + text: string; + /** Raw MCP content blocks (preserved for future field extraction). */ + raw: Array<{ type: string; text?: string }>; +} + +export interface ZreadSearchResult { + // GLM zread returns free-form text content; keep it loose. + text: string; +} + +export interface ZreadRepoStructure { + text: string; +} + +export interface ZreadFileContent { + text: string; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Pool: one McpClient per (provider, server) โ€” reuses the session. +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +export interface GlmMcpPoolOptions { + provider: ProviderId; + apiKey: string; + fetchImpl?: typeof fetch; + timeoutMs?: number; +} + +/** + * Lazily-initialised pool of MCP clients keyed by server id. Reuses sessions + * across calls (GLM sessions are stateful and expensive to re-establish). + * Call `close()` on shutdown to reset all sessions (best-effort). + */ +export class GlmMcpPool { + private readonly opts: GlmMcpPoolOptions; + private readonly clients = new Map(); + + constructor(opts: GlmMcpPoolOptions) { + this.opts = opts; + } + + private client(server: GlmMcpServerId): McpClient { + let c = this.clients.get(server); + if (!c) { + const clientOpts: McpClientOptions = { + url: glmMcpEndpoint(this.opts.provider, server), + apiKey: this.opts.apiKey, + fetchImpl: this.opts.fetchImpl, + timeoutMs: this.opts.timeoutMs, + }; + c = new McpClient(clientOpts); + this.clients.set(server, c); + } + return c; + } + + /** Reset all cached sessions (e.g. on credential rotation). */ + reset(): void { + for (const c of this.clients.values()) c.reset(); + } + + // โ”€โ”€ web_search_prime โ”€โ”€ + /** + * Search the web via GLM's MCP. `arguments` mirror GLM's inputSchema + * (verified by live `tools/list`): + * - `search_query` (required) + * - `search_domain_filter`, `search_recency_filter`, `content_size`, `location` + */ + async webSearch(args: { + search_query: string; + search_domain_filter?: string; + search_recency_filter?: "oneDay" | "oneWeek" | "oneMonth" | "oneYear" | "noLimit"; + content_size?: "medium" | "high"; + location?: "cn" | "us"; + }): Promise { + const result = await this.client("web_search_prime").callTool("web_search_prime", args as Record); + return decodeWebSearchResult(result.content); + } + + // โ”€โ”€ web_reader โ”€โ”€ + /** Fetch a URL's content via GLM's MCP `webReader` tool. */ + async webRead(args: { + url: string; + return_format?: "markdown" | "text"; + no_cache?: boolean; + retain_images?: boolean; + no_gfm?: boolean; + with_images_summary?: boolean; + with_links_summary?: boolean; + timeout?: number; + }): Promise { + const result = await this.client("web_reader").callTool("webReader", args as Record); + return { text: joinText(result.content), raw: result.content as Array<{ type: string; text?: string }> }; + } + + // โ”€โ”€ zread โ”€โ”€ + /** Search a GitHub repo's docs/issues/commits via GLM's `zread` MCP. */ + async zreadSearchDoc(args: { repo_name: string; query: string; language?: "zh" | "en" }): Promise { + const result = await this.client("zread").callTool("search_doc", args as Record); + return { text: joinText(result.content) }; + } + + /** Get a GitHub repo's directory structure via GLM's `zread` MCP. */ + async zreadGetRepoStructure(args: { repo_name: string; dir_path?: string }): Promise { + const result = await this.client("zread").callTool("get_repo_structure", args as Record); + return { text: joinText(result.content) }; + } + + /** Read a file in a GitHub repo via GLM's `zread` MCP. */ + async zreadReadFile(args: { repo_name: string; file_path: string }): Promise { + const result = await this.client("zread").callTool("read_file", args as Record); + return { text: joinText(result.content) }; + } +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Decoders +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** + * Decode `web_search_prime`'s doubly-encoded result. The MCP `content[0].text` + * field holds a JSON-stringified array: `"[{\"title\":...,\"link\":..., ...}]"`. + * Caller-friendly: returns `[]` on any parse failure rather than throwing. + */ +export function decodeWebSearchResult(contentBlocks: Array<{ type: string; text?: string }>): WebSearchHit[] { + const text = contentBlocks.find((c) => c.type === "text")?.text; + if (!text) return []; + // First unwrap: text โ†’ JSON array string. + let arrayStr: string; + try { + // The text field itself may be a quoted JSON string ("[...]" โ†’ [...]) + const unquoted = JSON.parse(text); + arrayStr = typeof unquoted === "string" ? unquoted : text; + } catch { + arrayStr = text; + } + let arr: unknown; + try { + arr = JSON.parse(arrayStr); + } catch { + return []; + } + if (!Array.isArray(arr)) return []; + return arr.filter((h): h is WebSearchHit => { + if (typeof h !== "object" || h === null) return false; + const hit = h as Record; + return typeof hit.title === "string" && typeof hit.link === "string"; + }); +} + +/** Concatenate all `text` blocks in an MCP result into a single string. */ +function joinText(content: Array<{ type: string; text?: string }>): string { + return content + .filter((c) => c.type === "text" && typeof c.text === "string") + .map((c) => c.text as string) + .join("\n"); +} diff --git a/src/provider/models.ts b/src/provider/models.ts new file mode 100644 index 0000000000000000000000000000000000000000..1360db1ae95663b0cf7e822303a492af2a118124 --- /dev/null +++ b/src/provider/models.ts @@ -0,0 +1,28 @@ +/** + * Pinned model catalog for GLM coding plan. + * + * Hardcoded to the exact models available on the Z.AI / Bigmodel coding-plan + * tier. This replaces the previous `_reverse/models_catalog.json` import, + * removing that runtime dependency. Update this list when new GLM models are + * released or specs change. + * + * @see .omo/plans/zcode-proxy.md Task 3 + */ +import type { ModelDef } from "./types.js"; + +/** All models available on the GLM coding plan, pinned with verified specs. */ +export const MODELS: ModelDef[] = [ + { id: "glm-4.5-air", name: "GLM 4.5 Air", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-4.6", name: "GLM 4.6", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-4.6v", name: "GLM 4.6V", contextWindow: 200_000, maxOutputTokens: 128_000 }, + { id: "glm-4.7", name: "GLM 4.7", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-5", name: "GLM 5", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-5-turbo", name: "GLM 5 Turbo", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-5v-turbo", name: "GLM 5V Turbo", contextWindow: 200_000, maxOutputTokens: 128_000 }, + { id: "glm-5.1", name: "GLM 5.1", contextWindow: 200_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-5.2", name: "GLM 5.2", contextWindow: 1_000_000, maxOutputTokens: 128_000, reasoning: true }, + { id: "glm-5.3", name: "GLM 5.3", contextWindow: 1_000_000, maxOutputTokens: 128_000, reasoning: true }, + // start-plan gateway serves the -flash variant (used by claimed trial plans + // like the weekend package); advertised so client-side discovery lists it. + { id: "glm-5.3-flash", name: "GLM 5.3 Flash", contextWindow: 1_000_000, maxOutputTokens: 128_000, reasoning: true }, +]; diff --git a/src/provider/providers.ts b/src/provider/providers.ts new file mode 100644 index 0000000000000000000000000000000000000000..6e6760177c2dd9f435a616d257a8c0d4da9074f6 --- /dev/null +++ b/src/provider/providers.ts @@ -0,0 +1,36 @@ +/** + * Z.AI and Bigmodel provider definitions. + * @see .omo/plans/zcode-proxy.md Task 3 + * @see _reverse/NOTEPAD.md "Provider Endpoints" + */ +import type { ProviderDef, ProviderId } from "./types.js"; + +export const ZAI_PROVIDER: ProviderDef = { + id: "zai", + displayName: "Z.AI", + anthropicBaseURL: "https://api.z.ai/api/anthropic", + openaiBaseURL: "https://api.z.ai/api/coding/paas/v4", + bizHost: "https://api.z.ai", +}; + +export const BIGMODEL_PROVIDER: ProviderDef = { + id: "bigmodel", + displayName: "BigModel / ๆ™บ่ฐฑ", + anthropicBaseURL: "https://open.bigmodel.cn/api/anthropic", + openaiBaseURL: "https://open.bigmodel.cn/api/coding/paas/v4", + bizHost: "https://open.bigmodel.cn", +}; + +const PROVIDERS: Record = { + zai: ZAI_PROVIDER, + bigmodel: BIGMODEL_PROVIDER, +}; + +/** Look up a provider definition by id. */ +export function getProvider(id: ProviderId): ProviderDef { + const def = PROVIDERS[id]; + if (!def) { + throw new Error(`Unknown provider: "${id}"`); + } + return def; +} diff --git a/src/provider/reasoning.ts b/src/provider/reasoning.ts new file mode 100644 index 0000000000000000000000000000000000000000..016a7996df18410ddb6d4278f985087e27feea7c --- /dev/null +++ b/src/provider/reasoning.ts @@ -0,0 +1,124 @@ +/** + * GLM-5.3 family reasoning-effort contract. + * + * The Anthropic upstream ignores the OpenAI `reasoning_effort` field entirely + * for this model family โ€” `output_config.effort` is the only channel that + * actually changes how much the model thinks, and it must be paired with a + * matching `thinking.budget_tokens` (the effort label alone still produces + * near-zero thinking). Values below come from ZCode's own model catalog + * entry for `glm-5.3` (`defaultLevel: "max"`, three effort levels each + * setting both fields) plus live upstream verification. + */ + +/** The three legal `output_config.effort` levels for GLM-5.3 models (module-local; the type below is the public contract). */ +const GLM53_EFFORT_LEVELS = ["low", "high", "max"] as const; + +/** One of the three legal GLM-5.3 effort levels. */ +export type Glm53Effort = (typeof GLM53_EFFORT_LEVELS)[number]; + +/** ZCode catalog's `defaultLevel` for glm-5.3 โ€” used when no effort is requested. */ +export const GLM53_DEFAULT_EFFORT: Glm53Effort = "max"; + +/** + * Thinking token budgets ZCode's catalog pairs with each effort level. + * Sending `output_config.effort` without a matching `thinking.budget_tokens` + * leaves the upstream at its own near-zero default. + */ +export const GLM53_THINKING_BUDGETS: Readonly> = { + low: 8_000, + high: 16_000, + max: 32_000, +}; + +/** + * Floor below which a thinking budget stops being useful โ€” measured live + * against the upstream (a budget this small collapses back to near-zero + * thinking output). + */ +export const GLM53_MIN_THINKING_BUDGET = 1_024; + +/** + * Tokens reserved for the actual answer once the thinking budget is + * subtracted from `max_tokens` โ€” see `fitGlm53Budget`. ZCode's own clamp + * (`Math.min(budgetTokens, maxOutputTokens - 1)`) is written against the + * *model's* maxOutputTokens ceiling, a large fixed number (128,000 for + * glm-5.3) where reserving a single token for the answer is harmless. + * Applying that same "-1" literally against a small per-request + * `max_tokens` is not โ€” it leaves the response with essentially nothing to + * work with. 1,024 tokens (matching `GLM53_MIN_THINKING_BUDGET`'s own + * granularity) is a defensible floor: enough for a short but real answer, + * without meaningfully eating into a large thinking budget when + * `max_tokens` is generous. + */ +export const GLM53_ANSWER_RESERVE = 1_024; + +/** + * Match the GLM-5.3 model family, including `glm-5.3-flash`, case-insensitively + * (the upstream also accepts `GLM-5.3`). Deliberately excludes `glm-5`, + * `glm-5.1`, and `glm-5.2` โ€” the negative lookahead rejects a trailing digit + * so `glm-5.30` (were it ever added) would not falsely match either. + */ +const GLM53_MODEL_PATTERN = /glm-5\.3(?![0-9])/i; + +/** True when `model` belongs to the GLM-5.3 family (`glm-5.3`, `glm-5.3-flash`, ...). */ +export function isGlm53Model(model: string | undefined): boolean { + if (!model) return false; + return GLM53_MODEL_PATTERN.test(model); +} + +/** + * Map an OpenAI `reasoning_effort` value onto the three GLM-5.3 effort + * levels, per Z.AI's official mapping table. Unrecognized or absent values + * fall back to the catalog default (`max`) rather than the OpenAI-side + * default (`medium`), since ZCode's own `defaultLevel` for this family is + * `max`. The mapping rounds UP, not to nearest โ€” `medium` maps to `high`, + * not `low`. + */ +export function normalizeGlm53Effort(effort: string | undefined): Glm53Effort { + switch (effort) { + case "none": + case "minimal": + case "light": + case "low": + return "low"; + case "medium": + case "high": + return "high"; + case "xhigh": + case "max": + case "ultra": + return "max"; + default: + return GLM53_DEFAULT_EFFORT; + } +} + +/** Build the paired `thinking` + `output_config` fields for a GLM-5.3 effort level. */ +export function buildGlm53Reasoning(effort: Glm53Effort): { + thinking: { type: "enabled"; budget_tokens: number }; + output_config: { effort: Glm53Effort }; +} { + return { + thinking: { type: "enabled", budget_tokens: GLM53_THINKING_BUDGETS[effort] }, + output_config: { effort }, + }; +} + +/** + * Clamp a thinking budget to fit inside `max_tokens`, reserving + * `GLM53_ANSWER_RESERVE` tokens for the answer โ€” ZCode's catalog spends the + * thinking budget out of the same token pool as the response, so a budget + * that eats the whole of `max_tokens` (or all but one token of it) would + * leave no meaningful room for output. Returns `undefined` when the clamped + * budget falls below `GLM53_MIN_THINKING_BUDGET` (the caller should then + * fall back to `{type:"enabled"}` with no explicit budget). Passes `budget` + * through unchanged when `maxTokens` isn't a finite number โ€” the upstream + * doesn't validate this either, so there is nothing useful to clamp against. + */ +export function fitGlm53Budget(budget: number, maxTokens: unknown): number | undefined { + if (typeof maxTokens !== "number" || !Number.isFinite(maxTokens)) return budget; + // Floor first: JSON permits a fractional `max_tokens`, and a fractional + // `budget_tokens` is not a value the upstream should ever be handed. + const clamped = Math.min(budget, Math.floor(maxTokens) - GLM53_ANSWER_RESERVE); + return clamped >= GLM53_MIN_THINKING_BUDGET ? clamped : undefined; +} diff --git a/src/provider/types.ts b/src/provider/types.ts new file mode 100644 index 0000000000000000000000000000000000000000..3eea82142c3154422a650630f8b2b8f3fa0e43a7 --- /dev/null +++ b/src/provider/types.ts @@ -0,0 +1,29 @@ +/** + * Provider and model type definitions. + * @see .omo/plans/zcode-proxy.md Task 3 + */ + +/** Supported provider identifiers. */ +export type ProviderId = "zai" | "bigmodel"; + +/** Static provider definition with endpoint URLs. */ +export interface ProviderDef { + id: ProviderId; + displayName: string; + /** Base URL for Anthropic-format requests (no trailing slash). */ + anthropicBaseURL: string; + /** Base URL for OpenAI-format requests (no trailing slash). */ + openaiBaseURL: string; + /** Host for OAuth/API-key resolution business APIs. */ + bizHost: string; +} + +/** Model definition derived from the catalog. */ +export interface ModelDef { + id: string; + name: string; + contextWindow: number; + maxOutputTokens?: number; + /** Whether the model supports reasoning/thinking mode. */ + reasoning?: boolean; +} diff --git a/src/proxy/body-transformer.ts b/src/proxy/body-transformer.ts new file mode 100644 index 0000000000000000000000000000000000000000..ceb8ed6846683716e8918bda888c2cca48da9b5f --- /dev/null +++ b/src/proxy/body-transformer.ts @@ -0,0 +1,194 @@ +/** + * Request body transformer โ€” applies ZCode-equivalent body mutations before + * forwarding upstream. All transformations are no-ops on parse failure (the + * original body is returned unchanged) so a malformed body never breaks the + * proxy: it just loses the optimization. + * + * Transformations applied: + * 1. OpenAI + `stream: true` โ†’ inject `stream_options.include_usage: true` + * (matches `@ai-sdk/openai-compatible` default in `_reverse/zcode.cjs`). + * 2. start-plan โ†’ prepend ZCode gateway system blocks. OpenAI upstream gets + * system messages; Anthropic-shaped input gets the Anthropic `system` field. + * 3. Anthropic format โ†’ clear existing `cache_control` markers on all + * non-system messages, then add `{ type: "ephemeral" }` to the last + * content block of the last non-system message (mirrors the bundle's + * `zsi`+`Fsi` pair). Anthropic's API silently ignores `cache_control` + * below the per-model token floor, so unconditional marking is safe and + * matches ZCode's `applyCacheControl: true` default. + * 4. Anthropic format + `ctx.userId` set โ†’ inject `metadata: { user_id }`. + * Mirrors `user_id: B.metadata.userId` at bundle offset ~4760586. + * + * @see _reverse/NOTEPAD.md "How Credential is Used for LLM Calls" + */ +import type { Format } from "../translator/types.js"; +import { buildStartPlanSystem } from "./system-prompt.js"; + +interface TransformContext { + format: Format; + /** When set (OAuth mode), the Anthropic-format body gets `metadata.user_id` injected. */ + userId?: string; + /** When true (start-plan), prepend ZCode gateway system blocks. */ + startPlan?: boolean; +} + +/** + * Apply body transformations. Returns the original `body` string when nothing + * changed OR when parsing failed; otherwise returns the re-serialized body. + */ +export function transformRequestBody(body: string | undefined, ctx: TransformContext): string | undefined { + if (body === undefined || body.length === 0) return body; + + let parsed: unknown; + try { + parsed = JSON.parse(body); + } catch { + return body; + } + if (typeof parsed !== "object" || parsed === null) return body; + + let modified = false; + + if (ctx.format === "openai") { + if (ctx.startPlan) { + modified = applyStartPlanOpenAISystem(parsed as Record) || modified; + } + modified = applyStreamOptionsIncludeUsage(parsed as Record) || modified; + } + if (ctx.format === "anthropic") { + const obj = parsed as Record; + if (ctx.startPlan) { + modified = applyStartPlanSystem(obj) || modified; + } + modified = applyAnthropicCacheControl(obj) || modified; + if (ctx.userId) { + modified = applyAnthropicUserId(obj, ctx.userId) || modified; + } + } + + return modified ? JSON.stringify(parsed) : body; +} + +/** OpenAI streaming: ensure `stream_options.include_usage: true`. */ +function applyStreamOptionsIncludeUsage(body: Record): boolean { + if (body.stream !== true) return false; + const existing = body.stream_options; + if (isPlainObject(existing) && existing.include_usage === true) { + return false; + } + const merged: Record = isPlainObject(existing) ? { ...existing } : {}; + merged.include_usage = true; + body.stream_options = merged; + return true; +} + +function isPlainObject(v: unknown): v is Record { + return typeof v === "object" && v !== null; +} + +/** + * Anthropic: two-phase cache_control injection, mirroring the bundle's + * `zsi` (clear) + `Fsi` (mark) pair: + * (1) strip `cache_control` from every content block of every NON-system + * message (string content carries no marker to clear); + * (2) mark the last content block of the LAST non-system message (existing + * location algorithm) with `{type: "ephemeral"}`; string content is + * converted to a block array first (kept from the previous behavior). + * + * Without the clear phase, client-supplied `cache_control` on earlier messages + * would pass through alongside our marker โ†’ multiple cache breakpoints and + * more cache writes than the real client produces. The top-level `system` + * field is untouched. The bundle's skipCacheWrite variant (marks the + * second-to-last message instead) is NOT implemented โ€” this proxy always + * writes cache. + * + * Output-stable: applying this to an already-canonical body yields the same + * bytes (no duplicate markers, target block unchanged). Note the function + * still reports `modified` in that case โ€” the clear phase strips the target + * block's own marker before phase 2 re-adds the identical one โ€” so callers + * re-serialize once more; harmless (byte-identical output), just not free. + */ +function applyAnthropicCacheControl(body: Record): boolean { + const messages = body.messages; + if (!Array.isArray(messages) || messages.length === 0) return false; + + // Phase 1 (bundle `zsi`): clear stale markers on non-system messages. + let cleaned = false; + for (const msg of messages) { + if (typeof msg !== "object" || msg === null) continue; + if (msg.role === "system") continue; + if (!Array.isArray(msg.content)) continue; + for (const block of msg.content) { + if (typeof block === "object" && block !== null && "cache_control" in block) { + delete block.cache_control; + cleaned = true; + } + } + } + + // Phase 2 (bundle `Fsi`): mark the last non-system message's last block. + for (let i = messages.length - 1; i >= 0; i--) { + const msg = messages[i]; + if (typeof msg !== "object" || msg === null) continue; + if (msg.role === "system") continue; + + if (typeof msg.content === "string") { + msg.content = [{ type: "text", text: msg.content, cache_control: { type: "ephemeral" } }]; + return true; + } + if (Array.isArray(msg.content) && msg.content.length > 0) { + const lastBlock = msg.content[msg.content.length - 1]; + if (typeof lastBlock === "object" && lastBlock !== null && !lastBlock.cache_control) { + lastBlock.cache_control = { type: "ephemeral" }; + return true; + } + // Already marked โ€” only report modified if the clear phase stripped + // stray markers elsewhere (idempotency: avoid needless re-serialize). + return cleaned; + } + return cleaned; + } + return cleaned; +} + +/** + * Anthropic: inject `metadata: { user_id }` when not already set. + * Preserves any existing `metadata.*` fields other than `user_id`. + */ +function applyAnthropicUserId(body: Record, userId: string): boolean { + const existing = body.metadata; + if (isPlainObject(existing) && existing.user_id === userId) { + return false; + } + body.metadata = { + ...(isPlainObject(existing) ? existing : {}), + user_id: userId, + }; + return true; +} + +/** + * start-plan: prepend ZCode gateway system blocks. The gateway rejects + * requests without these identity blocks with 3012 "method not allowed". + * Forwards `body.model` so `buildStartPlanSystem` can merge the dynamic + * "You are powered by the model named ${model}." line into the trailing + * Environment block (matches bundle 3.11.2 `T9o`/buildEnvInfoSection โ€” the + * line lives INSIDE the Environment text, not as a separate block). + */ +function applyStartPlanSystem(body: Record): boolean { + const model = typeof body.model === "string" ? body.model : undefined; + body.system = buildStartPlanSystem(body.system, model); + return true; +} + +function applyStartPlanOpenAISystem(body: Record): boolean { + const messages = body.messages; + if (!Array.isArray(messages)) return false; + + const model = typeof body.model === "string" ? body.model : undefined; + const official = buildStartPlanSystem(undefined, model).map((block) => ({ + role: "system", + content: typeof block === "object" && block !== null && "text" in block ? String(block.text) : "", + })); + body.messages = [...official, ...messages]; + return true; +} diff --git a/src/proxy/captcha-cpu-governor.ts b/src/proxy/captcha-cpu-governor.ts new file mode 100644 index 0000000000000000000000000000000000000000..4961800a7aa49574847f209ad06574899483fecc --- /dev/null +++ b/src/proxy/captcha-cpu-governor.ts @@ -0,0 +1,206 @@ +import fs from "node:fs/promises"; +import os from "node:os"; + +export type CpuGovernorConfig = { + /** Host CPU ceiling โ€” 100 = all vCPUs saturated (0 disables governor). */ + cpuLimitPercent: number; + /** Hysteresis band below limit before ramping up again. */ + hysteresisPercent: number; + poolSizeMin: number; + poolSizeMax: number; + maxSolveConcurrency: number; + intervalMs: number; +}; + +export type CpuGovernorSnapshot = { + cpuPercent: number; + limitPercent: number; + concurrency: number; + maxEffectiveTarget: number; + throttled: boolean; +}; + +/** 100 = entire host (all vCPUs) may be used; governor prevents exceeding that. */ +const DEFAULT_CPU_LIMIT = Number(process.env.CAPTCHA_CPU_LIMIT_PCT || 100); +const DEFAULT_INTERVAL_MS = Number(process.env.CAPTCHA_CPU_GOVERNOR_INTERVAL_MS || 2_000); +const TARGET_STEP = 15; + +type CpuCounters = { idle: number; total: number }; + +async function readCpuCounters(): Promise { + try { + const stat = await fs.readFile("/proc/stat", "utf8"); + const line = stat.split("\n")[0] ?? ""; + const parts = line.split(/\s+/).slice(1).map((v) => Number(v) || 0); + const idle = (parts[3] ?? 0) + (parts[4] ?? 0); + const total = parts.reduce((sum, n) => sum + n, 0); + return { idle, total }; + } catch { + const load = os.loadavg()[0] ?? 0; + const cpus = Math.max(1, os.cpus().length); + const pct = (load / cpus) * 100; + return { idle: 100 - pct, total: 100 }; + } +} + +/** Samples host-wide CPU via /proc/stat (100% = all cores busy). */ +export class CaptchaCpuGovernor { + private prevCpu: CpuCounters | null = null; + private lastCpuPercent = 0; + private concurrency: number; + private maxEffectiveTarget: number; + private timer: ReturnType | null = null; + + constructor(private cfg: CpuGovernorConfig) { + this.concurrency = 1; + this.maxEffectiveTarget = cfg.poolSizeMin; + } + + get enabled(): boolean { + return this.cfg.cpuLimitPercent > 0; + } + + configure(partial: Partial): void { + this.cfg = { ...this.cfg, ...partial }; + this.maxEffectiveTarget = Math.max( + this.cfg.poolSizeMin, + Math.min(this.maxEffectiveTarget, this.cfg.poolSizeMax), + ); + this.concurrency = Math.min(this.concurrency, this.cfg.maxSolveConcurrency); + } + + start(): void { + if (!this.enabled || this.timer) return; + void this.tick(); + this.timer = setInterval(() => void this.tick(), this.cfg.intervalMs); + } + + stop(): void { + if (this.timer) { + clearInterval(this.timer); + this.timer = null; + } + } + + snapshot(): CpuGovernorSnapshot { + const limit = this.cfg.cpuLimitPercent; + return { + cpuPercent: Math.round(this.lastCpuPercent * 10) / 10, + limitPercent: limit, + concurrency: this.concurrency, + maxEffectiveTarget: this.maxEffectiveTarget, + throttled: this.lastCpuPercent >= limit - 3, + }; + } + + /** Parallel background solves allowed right now (may be 0 when pool is warm). */ + backgroundConcurrency(readyTokens: number): number { + if (!this.enabled) return this.cfg.maxSolveConcurrency; + + const cpu = this.lastCpuPercent; + const limit = this.cfg.cpuLimitPercent; + let allowed = this.concurrency; + + if (cpu >= limit) { + allowed = 0; + } else if (cpu >= limit - 4) { + allowed = Math.min(allowed, 1); + } else if (cpu >= limit - 10) { + allowed = Math.min(allowed, 2); + } + + if (readyTokens < this.cfg.poolSizeMin) { + return Math.max(1, allowed); + } + + return allowed; + } + + maxPoolTarget(): number { + return this.maxEffectiveTarget; + } + + private async tick(): Promise { + const cpu = await this.sampleCpuPercent(); + this.lastCpuPercent = cpu; + + const limit = this.cfg.cpuLimitPercent; + const rampThreshold = limit - this.cfg.hysteresisPercent; + + if (cpu >= limit) { + this.concurrency = 1; + this.maxEffectiveTarget = this.cfg.poolSizeMin; + } else if (cpu >= limit - 4) { + if (this.concurrency > 1) this.concurrency -= 1; + this.maxEffectiveTarget = this.cfg.poolSizeMin; + } else if (cpu >= limit - 10) { + if (this.concurrency > 2) this.concurrency -= 1; + this.maxEffectiveTarget = Math.max( + this.cfg.poolSizeMin, + this.maxEffectiveTarget - TARGET_STEP, + ); + } else if (cpu <= rampThreshold) { + if (this.concurrency < this.cfg.maxSolveConcurrency) { + this.concurrency += 1; + } + if (this.maxEffectiveTarget < this.cfg.poolSizeMax) { + this.maxEffectiveTarget = Math.min( + this.cfg.poolSizeMax, + this.maxEffectiveTarget + TARGET_STEP, + ); + } + } + } + + private async sampleCpuPercent(): Promise { + const cur = await readCpuCounters(); + if (!this.prevCpu) { + this.prevCpu = cur; + return this.lastCpuPercent; + } + const idleDelta = cur.idle - this.prevCpu.idle; + const totalDelta = cur.total - this.prevCpu.total; + this.prevCpu = cur; + if (totalDelta <= 0) return this.lastCpuPercent; + const used = ((totalDelta - idleDelta) / totalDelta) * 100; + return Math.max(0, Math.min(100, used)); + } +} + +export function resolveCpuGovernorConfig(opts: { + poolSizeMin?: number; + poolSizeMax?: number; + solveConcurrency?: number; + cpuLimitPercent?: number; + cpuGovernorIntervalSec?: number; +}): CpuGovernorConfig { + const poolSizeMin = opts.poolSizeMin ?? Number(process.env.CAPTCHA_POOL_MIN || 40); + const poolSizeMax = Math.max( + poolSizeMin, + opts.poolSizeMax ?? Number(process.env.CAPTCHA_POOL_MAX || 120), + ); + const maxSolveConcurrency = + opts.solveConcurrency ?? + Number( + process.env.CAPTCHA_SOLVE_CONCURRENCY || + (process.env.ZCODE_CAPTCHA_LOW_CPU === "1" ? 3 : 6), + ); + + const cpuLimitPercent = + opts.cpuLimitPercent ?? + (process.env.CAPTCHA_CPU_GOVERNOR === "0" ? 0 : DEFAULT_CPU_LIMIT); + + const intervalMs = + opts.cpuGovernorIntervalSec != null + ? opts.cpuGovernorIntervalSec * 1000 + : DEFAULT_INTERVAL_MS; + + return { + cpuLimitPercent, + hysteresisPercent: 5, + poolSizeMin, + poolSizeMax, + maxSolveConcurrency, + intervalMs, + }; +} diff --git a/src/proxy/captcha-happy.ts b/src/proxy/captcha-happy.ts new file mode 100644 index 0000000000000000000000000000000000000000..6490862fa9f5264b94235c115c39d916ded431e6 --- /dev/null +++ b/src/proxy/captcha-happy.ts @@ -0,0 +1,2450 @@ +// @ts-nocheck โ€” ported from the proven Node happy-dom solver (solve-happy-lib.js) +/** + * captcha-happy.ts โ€” in-process happy-dom Aliyun captcha solver. + * + * Ported from the production-proven standalone happy-dom solver to run + * INSIDE the Bun process so the release binary stays self-contained: + * no external Node.js, no canvas/playwright/Chromium. + * + * Mechanics: + * 1. cookie priming of https://zcode.z.ai/ (5-min cache) + * 2. CDN disk cache at ~/.zcode-captcha-cdn-cache/ + in-mem cache + * 3. installNativeToString (mask JS-implemented platform APIs as native) + * 4. per-request client-hint / UA / origin / referer injection (interceptor) + * 5. guest-side patches (Event.isTrusted, HTMLDocument naming, btoa) + * 6. solve contract: initAliyunCaptcha + getInstance().startTracelessVerification() + */ +import { GlobalWindow as Window, PropertySymbol } from "happy-dom"; +import WindowBrowserContext from "happy-dom/lib/window/WindowBrowserContext.js"; +import { ProxyAgent, setGlobalDispatcher } from "undici"; +import crypto from "node:crypto"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { Worker } from "node:worker_threads"; + +// โ”€โ”€ Blocking fetch for sync XHR (self-contained builds) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// happy-dom implements sync XHR by spawning `process.argv[0] -e +`; + +function diskPathFor(url) { + return path.join(CDN_CACHE_DIR, crypto.createHash("sha1").update(String(url)).digest("hex")); +} + +function sniffMime(url) { + if (/\.js(\?|$)/i.test(url)) return "application/javascript"; + if (/\.css(\?|$)/i.test(url)) return "text/css"; + if (/\.png(\?|$)/i.test(url)) return "image/png"; + if (/\.(jpg|jpeg)(\?|$)/i.test(url)) return "image/jpeg"; + if (/\.json(\?|$)/i.test(url)) return "application/json"; + return "application/octet-stream"; +} + +// โ”€โ”€ pe.* bytecode VM harvest hook (same as solve-core) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +const peVmCallRegex = + /55==A\?\(f=r\[n\+\+\],l=e\.pop\(\),h=e\.pop\(\),o=\[\],\w+\(f\)\.forEach\(function\(\)\{o\.unshift\(e\.pop\(\)\)\}\),p=null===h\?l\.apply\((\w+),o\):h\[l\]\.apply\(h,o\),r\[n\+\+\]&&e\.push\(p\)\):/; +function patchPeBundle(buf, url) { + if (process.env.PE_PATCH === "off") return buf; + if (!/dynamicJS\/[^/]*\/pe\.\d+\./.test(url)) return buf; + let src = buf.toString("utf8"); + if (src.includes("__DBT")) return buf; + const m = src.match(peVmCallRegex); + if (!m) return buf; + const locals = m[1]; + const hook = `55==A?(f=r[n++],l=e.pop(),h=e.pop(),o=[],v(f).forEach(function(){o.unshift(e.pop())}),p=null===h?l.apply(${locals},o):h[l].apply(h,o),r[n++]&&e.push(p),function(){try{if(l===window.btoa||l===window.atob){window.__DBT=window.__DBT||[];var __sav=[];for(var __i=0;__i 0) { + _memCdnCache.set(url, buf); + try { + const p = diskPathFor(url); + fs.mkdirSync(CDN_CACHE_DIR, { recursive: true }); + fs.writeFileSync(p, buf); + // verify write completed (no partial file) + const stat = fs.statSync(p); + if (stat.size !== buf.length) { + process.stderr.write(`[cache-write-short] ${url} wrote ${stat.size}/${buf.length}b โ€” rewrite\n`); + fs.writeFileSync(p, buf); + } + } catch (err) { + if (_DEBUG) process.stderr.write(`[cache-write-err] ${url}: ${err.message}\n`); + } + } + return buf; + } catch (err) { + if (_DEBUG) process.stderr.write(`[loader-fetch-err] ${url}: ${err.message}\n`); + return null; + } +} + +// โ”€โ”€ Request header injection (every frame request: XHR, fetch, scripts) โ”€โ”€โ”€โ”€ +function injectRequestHeaders(request) { + const h = request.headers; + try { + h.set("sec-ch-ua", '"Chromium";v="' + fp.uaMajor + '", "Not)A;Brand";v="24"'); + h.set("sec-ch-ua-mobile", "?0"); + h.set("sec-ch-ua-platform", '"Linux"'); + h.set("user-agent", fp.userAgent); + h.set("accept-language", "en-US,en;q=0.9"); + h.set("referer", "https://zcode.z.ai/"); + let origin = null; + try { + const u = new URL(request.url); + const method = String(request.method || "GET").toUpperCase(); + const crossOrigin = u.origin !== "https://zcode.z.ai"; + if (crossOrigin || (method !== "GET" && method !== "HEAD")) { + origin = "https://zcode.z.ai"; + } + } catch (_) {} + if (origin) h.set("origin", origin); + } catch (_) {} +} + +function cookieHeader(request, window, browserFrame) { + try { + const ctx = browserFrame.page.context; + const u = new URL(request.url); + if (request.credentials === "omit") return null; + const cookies = ctx.cookieContainer.getCookies(u, false); + if (cookies.length > 0) { + return cookies.map((c) => `${c.name}=${c.value}`).join("; "); + } + } catch (_) {} + return null; +} + +function storeSetCookies(res, url) { + try { + const list = typeof res.headers.getSetCookie === "function" ? res.headers.getSetCookie() : []; + if (list.length) { + const cookieContainer = global.__cookieContainer; + if (cookieContainer) { + for (const raw of list) { + const u = new URL(url); + const parts = raw.split(";"); + const pair = parts[0].split("="); + const cookie = { + name: pair[0].trim(), + value: pair.slice(1).join("=").trim(), + url: u.origin, + domain: u.hostname, + path: "/", + }; + for (const p of parts.slice(1)) { + const kv = p.trim().split(/=(.*)/s); + const k = (kv[0] || "").toLowerCase(); + if (k === "domain" && kv[1]) cookie.domain = kv[1]; + if (k === "path" && kv[1]) cookie.path = kv[1]; + if (k === "expires") cookie.expires = new Date(kv[1]).getTime(); + if (k === "max-age") cookie.maxAge = parseInt(kv[1], 10); + if (k === "httponly") cookie.httpOnly = true; + if (k === "secure") cookie.secure = true; + if (k === "samesite") cookie.sameSite = kv[1]; + } + try { + cookieContainer.addCookies([cookie]); + } catch (_) {} + } + } + } + } catch (_) {} +} + +// โ”€โ”€ The interceptor: replaces happy-dom's network layer completely โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// All frame requests (scripts, XHR, fetch, images) funnel through here. +function makeInterceptor(bypassPeCache = false) { + const skipPeCache = (url) => bypassPeCache && /dynamicJS\/.*\/pe\.\d+\./.test(url); + return { + async beforeAsyncRequest({ request, window: w }) { + const url = request.url; + _requestLog.push({ at: Date.now(), method: request.method, url }); + injectRequestHeaders(request); + if (/\balicdn\.com/i.test(url)) { + let body = skipPeCache(url) ? null : getCachedBody(url); + if (body && /\.js(\?|$)/i.test(url)) { + try { + new Function(body.toString("utf8")); + } catch (parseErr) { + process.stderr.write(`[cache-bad-js] ${url} len=${body.length} ${parseErr.message} โ€” refetch fresh\n`); + _memCdnCache.delete(url); + try { fs.unlinkSync(diskPathFor(url)); } catch (_) {} + body = null; + } + } + // sync interceptor serves only from cache; the async interceptor + // above warms the cache on first load, so misses fall through to + // the async fetch path handled by happy-dom. + if (body) { + if (/dynamicJS\/[^/]*\/pe\.\d+\./.test(url)) { + try { w.__lastPeUrl = url; } catch (_) {} + } + return new w.Response(patchPeBundle(Buffer.from(body), url), { + status: 200, + statusText: "OK", + headers: { "content-type": sniffMime(url) }, + }); + } + } + // Passthrough via global fetch (undici; honors global ProxyAgent). + try { + const init = { method: request.method, headers: {} }; + request.headers.forEach((value, key) => { + init.headers[key] = value; + }); + const bs = new URL(url); + const cookie = cookieHeader(request, w, global.__browserFrame); + if (cookie) init.headers.cookie = cookie; + let hasBody = false; + try { + if (request.body) { + const ab = await request.arrayBuffer(); + if (ab && ab.byteLength > 0) { + init.body = ab; + hasBody = true; + } + } + } catch (_) {} + const res = await fetch(url, init); + const buf = Buffer.from(await res.arrayBuffer()); + storeSetCookies(res, url); + if (_DEBUG && /captcha-open|verify\.|device\.saf|cloudauth-device|upload\./i.test(url) && buf.length && buf.length < 4096) { + try { + process.stderr.write(`[xhr-body] ${request.method} ${bs.hostname}${bs.pathname}-> ${res.status} ${buf.toString("utf8").slice(0, 1200)}\n`); + } catch (_) {} + } + const headers = {}; + const ct = res.headers.get("content-type"); + if (ct) headers["content-type"] = ct; + const logHost = bs.hostname; + if (_DEBUG) + process.stderr.write( + `[xhr] ${request.method} ${logHost}${bs.pathname} -> ${res.status} (${buf.length}b)\n`, + ); + return new w.Response(buf, { + status: res.status, + statusText: res.statusText || "", + headers, + }); + } catch (err) { + if (_DEBUG) process.stderr.write(`[xhr-err] ${url}: ${err.message}\n`); + return new w.Response("", { status: 503, statusText: "passthrough failed" }); + } + }, + beforeSyncRequest({ request, window: w }) { + const url = request.url; + _requestLog.push({ at: Date.now(), method: request.method, url, sync: true }); + injectRequestHeaders(request); + let body = null; + if (/\balicdn\.com/i.test(url)) { + body = skipPeCache(url) ? null : getCachedBody(url); + if (body && /\.js(\?|$)/i.test(url)) { + try { + new Function(body.toString("utf8")); + } catch (parseErr) { + process.stderr.write(`[cache-bad-js:sync] ${url} len=${body.length} ${parseErr.message} โ€” refetch fresh\n`); + _memCdnCache.delete(url); + try { fs.unlinkSync(diskPathFor(url)); } catch (_) {} + body = null; + } + } + // sync interceptor serves only from cache; the async interceptor + // above warms the cache on first load, so misses fall through to + // the async fetch path handled by happy-dom. + } + if (body) { + if (/dynamicJS\/[^/]*\/pe\.\d+\./.test(url)) { + try { w.__lastPeUrl = url; } catch (_) {} + } + return { + status: 200, + statusText: "OK", + ok: true, + url, + redirected: false, + headers: new w.Headers({ "content-type": sniffMime(url) }), + body: patchPeBundle(Buffer.from(body), url), + [PropertySymbol.virtualServerFile]: null, + }; + } + // Non-CDN sync request: serve it blocking via a worker thread. Never + // fall through to happy-dom's own sync fetch โ€” it spawns a child + // process with `process.argv[0] -e`, which breaks compiled binaries. + const init = { method: request.method, headers: {} as Record }; + request.headers.forEach((value, key) => { + init.headers[key] = value; + }); + const cookie = cookieHeader(request, w, global.__browserFrame); + if (cookie) init.headers.cookie = cookie; + try { + if (request.body) { + const ab = request.body; + if (ab && (ab as any).byteLength > 0) init.body = ab; + } + } catch (_) {} + const res = syncFetchBlocking(url, init as any) as any; + if (res.error) { + process.stderr.write(`[sync-xhr-err] ${url}: ${res.error}\n`); + return new w.Response("", { status: 503, statusText: "sync fetch failed" }); + } + try { + for (const raw of res.setCookie || []) { + const cookieContainer = global.__cookieContainer; + if (!cookieContainer) break; + const u = new URL(url); + const parts = raw.split(";"); + const pair = parts[0].split("="); + const cookie: any = { + name: pair[0].trim(), + value: pair.slice(1).join("=").trim(), + url: u.origin, + domain: u.hostname, + path: "/", + }; + for (const p of parts.slice(1)) { + const kv = p.trim().split(/=(.*)/s); + const k = (kv[0] || "").toLowerCase(); + if (k === "domain" && kv[1]) cookie.domain = kv[1]; + if (k === "path" && kv[1]) cookie.path = kv[1]; + if (k === "expires") cookie.expires = new Date(kv[1]).getTime(); + if (k === "max-age") cookie.maxAge = parseInt(kv[1], 10); + if (k === "httponly") cookie.httpOnly = true; + if (k === "secure") cookie.secure = true; + if (k === "samesite") cookie.sameSite = kv[1]; + } + try { cookieContainer.addCookies([cookie]); } catch (_) {} + } + } catch (_) {} + const hdrs: Record = {}; + for (const [k, v] of Object.entries(res.headers || {})) hdrs[k] = String(v); + // Sync interceptor contract: PLAIN OBJECT with Buffer body (happy-dom's + // SyncFetch reads `.body.toString()`); a window.Response here would + // stringify its ReadableStream body and corrupt script loading. + return { + status: res.status, + statusText: res.statusText || "", + ok: res.status >= 200 && res.status < 300, + url, + redirected: false, + headers: new w.Headers(hdrs), + body: Buffer.from(res.body), + [PropertySymbol.virtualServerFile]: null, + }; + }, + }; +} + +// โ”€โ”€ Lexical guest scope: timer OWNERSHIP, not caller guessing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Under Bun, guest scripts execute in the HOST realm, so a bare `setTimeout` +// inside SDK code resolves to the host's. Host timers outlive the window: +// a stray FeiLin callback that re-arms its 2s heartbeat (feilin008.js: +// `tV = setInterval(tE, 2e3)`) after destroyDom keeps firing forever and +// eventually dereferences a torn-down global โ€” the field-reported +// "ReferenceError: moveBy is not defined" that killed the TUI. +// +// Guest timers must therefore land on the WINDOW registry, which happy-dom +// clears in happyDOM.close(). The previous approach decided this at CALL time +// by sniffing `new Error().stack` for a CDN frame, but a stack describes the +// call chain, not ownership, and it misjudges BOTH ways: +// โ€ข false negative โ€” guest code built via `new Function` carries no CDN +// frame, so its heartbeat escaped onto the immortal host lane; +// โ€ข false positive โ€” host runtime code invoked beneath a guest frame was +// handed a window timer with no `.unref()`, the v4.5.2 crash shape. +// Ownership is a property of where CODE COMES FROM, so we bind it lexically. +// Each guest script is evaluated inside `with (scope) { โ€ฆ }`, where `scope` +// carries this window's timer methods. Identifier resolution is settled by the +// scope chain at parse time; no stack is ever consulted, so neither misjudgement +// is expressible. `with` (not an IIFE wrapper) because guest top-level `var` and +// `function` declarations must keep escaping to the global object โ€” an IIFE +// swallows them and `initAliyunCaptcha` never appears (measured: every solve +// timed out). The FeiLin/pe bundles have no top-level "use strict" (their +// `"use strict"` directives sit inside module functions, which is fine), so +// `with` parses; a script that did carry one would throw at parse time and take +// the unwrapped fallback path in installEvalInstrumentation. +const GUEST_TIMER_PROPS = ["setTimeout", "setInterval", "clearTimeout", "clearInterval"]; + +// Guest scopes are keyed per window so concurrent solves never share timers: +// the wrapper reads `globalThis[GUEST_SCOPE_ROOT][id]` at RUN time, and each +// window gets its own id. A plain object (not a Map) because the wrapper text +// indexes it directly from guest source. +const GUEST_SCOPE_ROOT = "__capGuestScopes"; +let _guestScopeSeq = 0; + +/** + * Create this window's guest scope and return the id the wrapper embeds. + * + * Holds the window's own timer methods (bound to the window), a `Function` + * stand-in (see makeScopedFunction), and the window's console. The console + * matters as much as the timers: the FeiLin SDK probes for devtools by + * printing invisible `%c%d` format strings across every console method, ~1/sec + * while solving. Resolved lexically it lands on the window's silent console; + * left to the host it garbles the TUI's alternate screen with bare "NaN" rows. + */ +function installGuestScope(w) { + const root = (globalThis[GUEST_SCOPE_ROOT] ??= Object.create(null)); + const id = `w${++_guestScopeSeq}`; + const scope = Object.create(null); + for (const name of GUEST_TIMER_PROPS) { + const fn = w[name]; + scope[name] = typeof fn === "function" ? fn.bind(w) : fn; + } + scope.Function = makeScopedFunction(w); + if (!_DEBUG && w.console) scope.console = w.console; + root[id] = scope; + w.__capScopeId = id; + return id; +} + +/** Drop the scope when the window dies, so it cannot pin a closed window. */ +function removeGuestScope(w) { + try { + const id = w && w.__capScopeId; + const root = globalThis[GUEST_SCOPE_ROOT]; + if (id && root) delete root[id]; + } catch {} +} + +/** + * A `Function` stand-in for guest scope. `new Function(body)` compiles in the + * GLOBAL scope, so a generated function would see the host timers again and + * re-open the escape hatch (measured: its heartbeat outlived window close). + * This variant re-wraps the generated body in the same `with` scope, so code + * the pe bytecode VM generates at runtime inherits the window's timers too. + * `eval` needs no equivalent: it inherits the caller's scope chain already. + */ +function makeScopedFunction(w) { + const Scoped = function (...args) { + const body = args.length ? String(args[args.length - 1]) : ""; + const params = args.slice(0, -1).map(String).join(","); + const id = w.__capScopeId; + const source = + `return function(${params}){with(globalThis.${GUEST_SCOPE_ROOT}[${JSON.stringify(id)}]){\n${body}\n}}`; + return Function(source)(); + }; + // Guest fingerprint code sweeps name/toString over platform builtins. + Scoped.prototype = Function.prototype; + try { + Object.defineProperty(Scoped, "name", { value: "Function", configurable: true }); + Object.defineProperty(Scoped, "toString", { + value: () => "function Function() { [native code] }", + configurable: true, + writable: true, + }); + } catch {} + return Scoped; +} + +/** + * Wrap guest source so bare timer identifiers resolve to `w`'s registry. + * + * A bare `with (โ€ฆ) { โ€ฆ }` statement, not a function wrapper, and that choice + * carries both of the properties this needs: + * + * - **Top-level declarations keep escaping.** `with` introduces an object + * environment, not a variable one, so guest `var`/`function` declarations + * still land on the global object. A function wrapper swallows them and + * `initAliyunCaptcha` never appears โ€” every solve then timed out waiting + * for it (measured: ok=0 fail=3). + * + * - **The completion value still flows out.** happy-dom's JavaScriptCompiler + * hands `evaluateScript` a `(function anonymous($happy_dom){โ€ฆ})` expression + * and calls whatever comes back. `eval` yields a statement's completion + * value, and a block completes with its last expression statement, so the + * compiler's function expression is returned through the `with` unchanged. + * (Declarations produce no completion value, so a script ending in one is + * also fine โ€” the preceding expression's value stands.) + */ +function wrapGuestSource(code, filename, scopeId) { + const sourceUrl = filename && /^https?:/.test(String(filename)) ? `\n//# sourceURL=${filename}` : ""; + const scopeRef = `globalThis.${GUEST_SCOPE_ROOT}[${JSON.stringify(scopeId)}]`; + // The leading newline keeps guest line numbers aligned with the CDN + // original; the trailing one guards a source ending in a line comment. + return `with(${scopeRef}){\n${code}\n}${sourceUrl}`; +} + +// โ”€โ”€ Parse-fail instrumentation (host side) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Wraps happy-dom's VM eval funnel (window[PropertySymbol.evaluateScript]). +// Every script tag / compiled module / dynamic chunk that happy-dom parses +// passes through here with options.filename = source URL, so any SyntaxError +// is dumped with URL + length + head/tail + sha1, and the disk cache is +// re-validated against a fresh CDN fetch when the URL is an http(s) file. +function installEvalInstrumentation(w) { + const sym = PropertySymbol && PropertySymbol.evaluateScript; + if (!sym || typeof w[sym] !== "function") { + process.stderr.write("[instr] no evaluateScript symbol, host hook skipped\n"); + return; + } + const orig = w[sym]; + w[sym] = function (code, options) { + const scopeId = w.__capScopeId; + try { + // Guest scripts run inside this window's `with` scope (wrapGuestSource): + // this funnel is the single entry point for every script tag, compiled + // module and dynamic pe/FeiLin chunk, so wrapping here covers them all. + // Our own GUEST_EVAL_PATCH goes through w.eval() and is unaffected. + if (scopeId) { + try { + return orig.call(this, wrapGuestSource(String(code ?? ""), options && options.filename, scopeId), options); + } catch (scopeErr) { + // Only a wrapper-induced parse failure (e.g. a top-level "use + // strict" making `with` illegal) falls back โ€” a genuine error from + // the guest body must propagate to the diagnostics path below. + if (!(scopeErr instanceof SyntaxError)) throw scopeErr; + process.stderr.write( + `[instr] guest scope rejected (${scopeErr.message.slice(0, 80)}), evaluating unwrapped\n`, + ); + } + } + return orig.call(this, code, options); + } catch (err) { + try { + const src = String(code || ""); + const filename = (options && options.filename) || "?"; + const sha1 = crypto.createHash("sha1").update(src).digest("hex"); + process.stderr.write( + `\n[EVAL-PARSE-FAIL] file=${filename} len=${src.length} sha1=${sha1}\n` + + ` head300: ${JSON.stringify(src.slice(0, 300))}\n` + + ` tail100: ${JSON.stringify(src.slice(-100))}\n` + + ` err: ${err && err.message}\n`, + ); + if (/^https?:/.test(filename)) { + (async () => { + try { + const res = await fetch(filename, { headers: { "user-agent": fp.userAgent } }); + const fresh = Buffer.from(await res.arrayBuffer()); + process.stderr.write( + `[EVAL-CACHE-COMPARE] cachedLen=${src.length} freshLen=${fresh.length} freshSha1=${crypto.createHash("sha1").update(fresh).digest("hex")} http=${res.status}\n`, + ); + if (fresh.length > 0 && fresh.length !== src.length) { + process.stderr.write(`[EVAL-CACHE-MISMATCH] deleting ${diskPathFor(filename)} (stale/truncated cache)\n`); + try { + fs.unlinkSync(diskPathFor(filename)); + } catch (_) {} + _memCdnCache.delete(filename); + } + } catch (fetchErr) { + process.stderr.write(`[EVAL-CACHE-COMPARE-ERR] ${fetchErr.message}\n`); + } + })(); + } + } catch (e2) {} + throw err; + } + }; +} + +// โ”€โ”€ Mask JS-implemented platform APIs as native (FeiLin toString sweep) โ”€โ”€โ”€โ”€โ”€ +function installNativeToString(w) { + const realToString = Function.prototype.toString; + const nativeRe = /\[native code\]/; + const mask = (fn) => { + if (typeof fn !== "function") return; + try { + if (nativeRe.test(realToString.call(fn))) return; + const name = fn.name || ""; + const nativeStr = `function ${name}() { [native code] }`; + Object.defineProperty(fn, "toString", { + value: () => nativeStr, + configurable: true, + writable: true, + }); + } catch (_) {} + }; + const seen = new w.Set(); + const maskObj = (obj, depth) => { + if ( + !obj || + (typeof obj !== "object" && typeof obj !== "function") || + depth > 5 + ) + return; + // Skip host-realm objects (under Bun, installGlobalWindowAlias exposes + // Bun internals via window getters; sweeping them crashes on native + // internal-field slots). happy-dom objects live in the window realm. + try { + if (obj.constructor && obj.constructor.prototype !== Object.prototype) { + const ctorName = obj.constructor.name; + if (/^(WriteStream|ReadStream|Socket|Process|Timeout|Immediate)$/.test(ctorName)) return; + } + } catch (_) {} + if (seen.has(obj)) return; + try { + seen.add(obj); + } catch (_) { + return; + } + let names = []; + try { + names = Object.getOwnPropertyNames(obj); + } catch (_) { + return; + } + for (const name of names) { + if (name === "toString" || name === "constructor") continue; + let desc; + try { + desc = Object.getOwnPropertyDescriptor(obj, name); + } catch (_) { + continue; + } + if (!desc) continue; + if (typeof desc.value === "function") { + mask(desc.value); + } else if (typeof desc.get === "function") { + mask(desc.get); + try { + const v = desc.get.call(obj); + if (typeof v === "function") mask(v); + // Probing a getter can hand back a promise that is already rejected + // (WHATWG stream `closed`/`ready` reject when the receiver is the + // prototype, not an instance). Nobody awaits these, so without a + // sink each probe surfaced as an unhandledRejection during every + // solve โ€” noise that buried real diagnostics. + else if (v && typeof v.then === "function") v.catch(() => {}); + } catch {} + } + if (depth < 3) { + try { + const v = desc.value; + if (v && (typeof v === "function" || typeof v === "object")) + maskObj(v, depth + 1); + } catch (_) {} + } + } + }; + const targets = [ + w, + w.navigator, + w.document, + w.Document && w.Document.prototype, + w.Element && w.Element.prototype, + w.HTMLElement && w.HTMLElement.prototype, + w.Node && w.Node.prototype, + w.EventTarget && w.EventTarget.prototype, + w.HTMLCanvasElement && w.HTMLCanvasElement.prototype, + w.XMLHttpRequest && w.XMLHttpRequest.prototype, + w.Event && w.Event.prototype, + w.Window && w.Window.prototype, + ].filter(Boolean); + for (const t of targets) { + try { + maskObj(t, 0); + } catch (_) {} + } +} + +// โ”€โ”€ Guest-context patches (run via window.eval inside the VM realm) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +const GUEST_EVAL_PATCH = ` +(function() { + try { + Object.defineProperty(Event.prototype, "isTrusted", { + get() { return true; }, + configurable: true + }); + } catch (e) {} + try { + if (window.HTMLDocument) { + Object.defineProperty(window.HTMLDocument, "name", { value: "HTMLDocument", configurable: true }); + Object.defineProperty(window.HTMLDocument.prototype, Symbol.toStringTag, { value: "HTMLDocument", configurable: true }); + } + } catch (e) {} + try { + Object.defineProperty(window.Document.prototype, Symbol.toStringTag, { value: "HTMLDocument", configurable: true }); + } catch (e) {} + // Guest errors are RECORDED, not printed: the Aliyun/FeiLin SDKs throw + // benign uncaught TypeErrors inside happy-dom on every solve (imperfect DOM + // emulation) while the solve still succeeds โ€” printing them flooded the + // console with [WINDOW-ERROR] spam. They land in window.__capErrs (capped, + // deduped) which solveTraceless surfaces only when a solve FAILS. + // CAPTCHA_DEBUG=1 streams them live again. + var __capDebug = ${_DEBUG ? "true" : "false"}; + function __capRecord(kind, msg, stack) { + try { + var m = String(msg || "?"); + var s = String(stack || "").split("\\n").slice(0, 2).join(" | "); + if (!window.__capErrs) window.__capErrs = []; + var last = window.__capErrs[window.__capErrs.length - 1]; + if (last && last.k === kind && last.m === m) { + last.n = (last.n || 1) + 1; + } else { + window.__capErrs.push({ k: kind, m: m, s: s, n: 1 }); + if (window.__capErrs.length > 8) window.__capErrs.shift(); + } + if (__capDebug) console.error("[" + kind + "]", m, s); + } catch (e2) {} + } + try { + window.addEventListener("unhandledrejection", function(e) { + var r = e && e.reason; + __capRecord("UH-REASON", (r && r.message) || typeof r, r && r.stack); + }); + } catch (e) {} + try { + window.addEventListener("error", function(e) { + __capRecord("WINDOW-ERROR", e && e.message, e && e.error && e.error.stack); + }); + } catch (e) {} + // ---- eval/Function parse-fail instrumentation (installed before pe chain) ---- + // Catches SyntaxError from guest-side eval()/new Function() (the dynamic pe.* + // chunk is evaluated this way in some SDK paths). Host-side twin: the + // PropertySymbol.evaluateScript wrapper in installEvalInstrumentation(). + function __capFailDump(kind, code) { + try { + var src = String(code || ""); + if (typeof window.__capDebugDump === "function") { + window.__capDebugDump(window.__lastPeUrl || "?", src, kind); + } else { + console.error("[" + kind + "] url=" + (window.__lastPeUrl || "?") + " len=" + src.length + " head=" + JSON.stringify(src.slice(0, 300)) + " tail=" + JSON.stringify(src.slice(-100))); + } + } catch (e2) {} + } + try { + var _origEval2 = window.eval; + if (_origEval2) { + window.eval = function(code) { + try { return _origEval2.call(window, code); } + catch (e) { + if (e && (/unexpected|invalid|parse|syntax/i.test(String((e && e.message) || e)))) { + __capFailDump("REALM-EVAL-FAIL", code); + } + throw e; + } + }; + } + } catch (e) {} + try { + var _of = window.Function; + if (_of) { + var _WF = function() { + var args = Array.prototype.slice.call(arguments); + var body = args.length ? String(args[args.length - 1]) : ""; + try { return _of.apply(this, args); } + catch (e) { + if (e && (/unexpected|invalid|parse|syntax/i.test(String((e && e.message) || e)))) { + __capFailDump("REALM-FN-FAIL", body); + } + throw e; + } + }; + _WF.prototype = _of.prototype; + try { Object.defineProperty(_WF, "name", { value: "Function", configurable: true }); } catch (e) {} + window.Function = _WF; + } + } catch (e) {} +})(); +`; + +// โ”€โ”€ Browser-ish polyfills (ported from solve-core applyPolyfills) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +function applyPolyfills(w) { + if (process.env.CAPTCHA_DEBUG_BODIES === "1") { + installTrafficLogger(w); + } + + // Element constructor shortcuts every real browser exposes. The FeiLin + // fingerprint SDK references `Option` as a bare identifier; missing it + // throws inside its probe chain and degrades the fingerprint. + if (typeof w.Option !== "function") { + w.Option = class Option extends w.HTMLOptionElement { + constructor(text, value, defaultSelected, selected) { + super(); + if (text !== undefined) { + const el = w.document.createElement("option"); + el.text = text; + if (value !== undefined) el.value = value; + if (defaultSelected) el.defaultSelected = true; + if (selected) el.selected = true; + return el; + } + } + }; + } + if (typeof w.Video !== "function" && w.HTMLVideoElement) { + w.Video = class Video extends w.HTMLVideoElement { + constructor() { return w.document.createElement("video"); } + }; + } + + // happy-dom lacks alert/prompt/confirm/open/close (same stubs as + // solve-shim.js line ~559-561) + if (typeof w.alert !== "function") w.alert = () => {}; + if (typeof w.prompt !== "function") w.prompt = () => null; + if (typeof w.confirm !== "function") w.confirm = () => false; + if (typeof w.open !== "function") w.open = () => null; + if (typeof w.close !== "function") w.close = () => {}; + try { Object.defineProperty(w, "alert", { value: w.alert, configurable: true, writable: true }); } catch (_) {} + try { Object.defineProperty(w, "prompt", { value: w.prompt, configurable: true, writable: true }); } catch (_) {} + try { Object.defineProperty(w, "confirm", { value: w.confirm, configurable: true, writable: true }); } catch (_) {} + try { Object.defineProperty(w, "open", { value: w.open, configurable: true, writable: true }); } catch (_) {} + try { Object.defineProperty(w, "close", { value: w.close, configurable: true, writable: true }); } catch (_) {} + + // happy-dom lacks browser globals that FeiLin / the pe risk engine probe. + // A missing one throws ReferenceError inside the VM machine โ†’ breaks the + // collection chain. Ported from solve-shim.js's stub list. + const extraGlobals = { + print: () => {}, + stop: () => {}, + moveTo: () => {}, + moveBy: () => {}, + showModalDialog: () => null, + find: () => false, + }; + for (const [k, v] of Object.entries(extraGlobals)) { + try { Object.defineProperty(w, k, { value: v, configurable: true, writable: true }); } catch (_) {} + } + // happy-dom's own open()/close() are destructive (close() tears the window + // down); the risk engine probes them โ†’ neutralize. + try { Object.defineProperty(w, "open", { value: () => null, configurable: true, writable: true }); } catch (_) {} + try { Object.defineProperty(w, "close", { value: () => {}, configurable: true, writable: true }); } catch (_) {} + + if (!w.Option) { + w.Option = class { + constructor(text, value, defaultSelected, selected) { + this.text = text ?? ""; + this.value = value ?? ""; + this.selected = selected ?? defaultSelected ?? false; + this.defaultSelected = !!defaultSelected; + this.disabled = false; + this.label = this.text; + this.index = 0; + } + }; + } + + if (!w.EventSource) { + w.EventSource = class { + constructor() { + this.readyState = 2; + this.onopen = null; + this.onmessage = null; + this.onerror = null; + } + close() { + this.readyState = 2; + } + addEventListener() {} + removeEventListener() {} + }; + } + + if (!w.Beacon) w.Beacon = class {}; + + if (!w.RTCPeerConnection) { + w.RTCPeerConnection = class { + constructor() {} + createDataChannel() { return {}; } + close() {} + createOffer() { return Promise.resolve({}); } + setLocalDescription() { return Promise.resolve(); } + addEventListener() {} + removeEventListener() {} + }; + } + + if (!w.MessageChannel) { + w.MessageChannel = class { + constructor() { + this.port1 = { onmessage: null, postMessage() {}, start() {}, close() {}, addEventListener() {}, removeEventListener() {} }; + this.port2 = { onmessage: null, postMessage() {}, start() {}, close() {}, addEventListener() {}, removeEventListener() {} }; + } + }; + } + + w.IntersectionObserver = + w.IntersectionObserver || + class { + constructor(cb) { + this.cb = cb; + } + observe() {} + unobserve() {} + disconnect() {} + takeRecords() { + return []; + } + }; + + w.ResizeObserver = + w.ResizeObserver || + class { + observe() {} + unobserve() {} + disconnect() {} + }; + + w.DeviceOrientationEvent = + w.DeviceOrientationEvent || + class extends w.Event { + constructor(type, opts) { + super(type, opts); + } + alpha = null; + beta = null; + gamma = null; + absolute = false; + }; + + w.DeviceMotionEvent = + w.DeviceMotionEvent || + class extends w.Event { + constructor(type, opts) { + super(type, opts); + } + acceleration = null; + accelerationIncludingGravity = null; + rotationRate = null; + interval = 16; + }; + + // Window-registry timers explicitly: these callbacks only touch the window + // and must die with it (they'd otherwise survive destroyDom via the dual + // dispatcher's host lane). + w.requestIdleCallback = w.requestIdleCallback || ((cb) => w.setTimeout(() => cb({ didTimeout: false, timeRemaining: () => 10 }), 1)); + w.cancelIdleCallback = w.cancelIdleCallback || ((id) => w.clearTimeout(id)); + + w.matchMedia = + w.matchMedia || + (() => ({ + matches: false, + media: "", + onchange: null, + addListener() {}, + removeListener() {}, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent() { + return false; + }, + })); + + if (!w.visualViewport) { + const VisualViewport = function () {}; + VisualViewport.prototype = { + width: fp.screen.w - 16, + height: fp.screen.h - 120, + scale: 1, + offsetLeft: 0, + offsetTop: 0, + pageLeft: 0, + pageTop: 0, + onresize: null, + onscroll: null, + onscrollend: null, + }; + w.VisualViewport = VisualViewport; + w.visualViewport = Object.create(w.VisualViewport.prototype); + } + + if (!w.indexedDB) { + const IDBFactory = function () {}; + IDBFactory.prototype = { + open: () => ({ onupgradeneeded: null, onsuccess: null, onerror: null }), + deleteDatabase: () => ({}), + databases: () => Promise.resolve([]), + }; + w.IDBFactory = IDBFactory; + w.indexedDB = Object.create(w.IDBFactory.prototype); + } + + if (!w.speechSynthesis) { + const SpeechSynthesis = function () {}; + SpeechSynthesis.prototype = { + speak() {}, + cancel() {}, + pause() {}, + resume() {}, + getVoices: () => [], + }; + w.SpeechSynthesis = SpeechSynthesis; + w.speechSynthesis = Object.create(w.SpeechSynthesis.prototype); + w.SpeechSynthesisUtterance = function () {}; + } + + w.Worker = + w.Worker || + class { + postMessage() {} + terminate() {} + addEventListener() {} + removeEventListener() {} + }; + + w.Notification = + w.Notification || + class { + static permission = "default"; + static requestPermission() { + return Promise.resolve("default"); + } + close() {} + }; + + // Canvas / WebGL + const proto = w.HTMLCanvasElement.prototype; + const nativeGetContext = typeof proto.getContext === "function" ? proto.getContext : null; + proto.getContext = function (type, ...rest) { + if (/webgl/i.test(type)) { + return makeWebGLMock(this); + } + if (nativeGetContext) { + try { + const ctx = nativeGetContext.call(this, type, ...rest); + if (ctx) return ctx; + } catch (_) {} + } + return make2DStub(this); + }; + + function makeWebGLMock(canvas) { + return { + canvas, + getParameter(p) { + if (p === 7936) return "WebKit"; + if (p === 7937) return "WebKit WebGL"; + if (p === 7938) return "WebGL 1.0 (OpenGL ES 2.0 Chromium)"; + if (p === 35724) return "WebGL GLSL ES 1.0 (OpenGL ES GLSL ES 1.0 Chromium)"; + if (p === 0x9245) return fp.webglUnmaskedVendor; + if (p === 0x9246) return fp.webglUnmaskedRenderer; + return "Intel Inc."; + }, + getExtension(name) { + if (name === "WEBGL_debug_renderer_info") { + return { UNMASKED_VENDOR_WEBGL: 0x9245, UNMASKED_RENDERER_WEBGL: 0x9246 }; + } + return null; + }, + getSupportedExtensions() { + return [ + "ANGLE_instanced_arrays", "EXT_blend_minmax", "EXT_color_buffer_half_float", + "EXT_disjoint_timer_query", "EXT_float_blend", "EXT_frag_depth", + "EXT_shader_texture_lod", "EXT_texture_compression_bptc", + "EXT_texture_compression_rgtc", "EXT_texture_filter_anisotropic", + "EXT_sRGB", "KHR_parallel_shader_compile", "OES_element_index_uint", + "OES_fbo_render_mipmap", "OES_standard_derivatives", + "OES_texture_float", "OES_texture_float_linear", + "OES_texture_half_float", "OES_texture_half_float_linear", + "OES_vertex_array_object", "WEBGL_color_buffer_float", + "WEBGL_compressed_texture_astc", "WEBGL_compressed_texture_etc", + "WEBGL_compressed_texture_etc1", "WEBGL_compressed_texture_s3tc", + "WEBGL_compressed_texture_s3tc_srgb", "WEBGL_debug_renderer_info", + "WEBGL_debug_shaders", "WEBGL_depth_texture", "WEBGL_draw_buffers", + "WEBGL_lose_context", "WEBGL_multi_draw", + ]; + }, + getContextAttributes() { + return { + alpha: true, antialias: true, depth: true, + failIfMajorPerformanceCaveat: false, powerPreference: "default", + premultipliedAlpha: true, preserveDrawingBuffer: false, + stencil: false, desynchronized: false, + }; + }, + getShaderPrecisionFormat() { + return { precision: 23, rangeMin: 127, rangeMax: 127 }; + }, + }; + } + + function make2DStub(canvas) { + return { + canvas, + fillRect() {}, + clearRect() {}, + getImageData: (_x, _y, w2 = 1, h2 = 1) => new w.ImageData(w2, h2), + putImageData() {}, + createImageData: (w2 = 1, h2 = 1) => new w.ImageData(w2, h2), + setTransform() {}, + transform() {}, + drawImage() {}, + save() {}, + restore() {}, + beginPath() {}, + moveTo() {}, + lineTo() {}, + bezierCurveTo() {}, + quadraticCurveTo() {}, + closePath() {}, + clip() {}, + stroke() {}, + fill() {}, + arc() {}, + rect() {}, + ellipse() {}, + translate() {}, + scale() {}, + rotate() {}, + fillText() {}, + strokeText() {}, + measureText: (t) => ({ width: String(t).length * 8 }), + createLinearGradient: () => ({ addColorStop() {} }), + createRadialGradient: () => ({ addColorStop() {} }), + createPattern: () => ({}), + isPointInPath: () => false, + font: "10px sans-serif", + textBaseline: "alphabetic", + textAlign: "start", + fillStyle: "#000", + strokeStyle: "#000", + globalAlpha: 1, + lineWidth: 1, + shadowBlur: 0, + shadowColor: "", + }; + } + + const nativeToDataURL = typeof proto.toDataURL === "function" ? proto.toDataURL : null; + proto.toDataURL = function (...a) { + try { + if (nativeToDataURL) return nativeToDataURL.apply(this, a); + } catch (_) {} + return fp.canvasImage; + }; + if (typeof proto.toBlob !== "function") { + proto.toBlob = (cb) => cb && cb(new w.Blob()); + } + + w.OffscreenCanvas = + w.OffscreenCanvas || + class { + constructor(width, height) { + this.width = width; + this.height = height; + } + getContext() { + return proto.getContext.call(this); + } + }; + + const audioMock = class { + constructor() { + this.sampleRate = 44100; + this.currentTime = 0; + this.state = "suspended"; + } + createOscillator() { + return { + type: "sine", + frequency: { value: 440, setValueAtTime() {} }, + connect() {}, + start() {}, + stop() {}, + }; + } + createDynamicsCompressor() { + return { + threshold: { value: -24, setValueAtTime() {} }, + knee: { value: 30, setValueAtTime() {} }, + ratio: { value: 12, setValueAtTime() {} }, + attack: { value: 0.003, setValueAtTime() {} }, + release: { value: 0.25, setValueAtTime() {} }, + connect() {}, + }; + } + createAnalyser() { + return { + fftSize: 2048, + frequencyBinCount: 1024, + getByteFrequencyData() {}, + getByteTimeDomainData() {}, + connect() {}, + }; + } + createGain() { + return { gain: { value: 1 }, connect() {} }; + } + destination = {}; + resume() { + this.state = "running"; + return Promise.resolve(); + } + close() { + this.state = "closed"; + return Promise.resolve(); + } + }; + w.AudioContext = w.AudioContext || audioMock; + w.OfflineAudioContext = + w.OfflineAudioContext || + class extends audioMock { + constructor(_channels, length, sampleRate) { + super(); + this.length = length; + this.sampleRate = sampleRate; + } + startRendering() { + const len = this.length || 44100; + const sr = this.sampleRate || 44100; + const buf = new Float32Array(len); + for (let i = 0; i < len; i += 1) { + const t = i / sr; + buf[i] = + Math.sin(2 * Math.PI * 1000 * t) * Math.exp(-t * 1.2) * 0.6 + + Math.sin(2 * Math.PI * 3000 * t) * Math.exp(-t * 1.5) * 0.25 + + Math.sin(2 * Math.PI * 5000 * t) * Math.exp(-t * 2.0) * 0.12; + } + return Promise.resolve({ + numberOfChannels: 1, + length: len, + sampleRate: sr, + getChannelData: () => buf, + }); + } + }; + + w.requestAnimationFrame = w.requestAnimationFrame || ((cb) => w.setTimeout(() => cb(Date.now()), 16)); + w.cancelAnimationFrame = w.cancelAnimationFrame || ((id) => w.clearTimeout(id)); + + try { + Object.defineProperty(w.document, "hidden", { value: false, configurable: true }); + Object.defineProperty(w.document, "visibilityState", { + value: "visible", + configurable: true, + }); + } catch (_) {} + + if (!w.document.fonts) { + w.document.fonts = { + ready: Promise.resolve(), + check: () => true, + addEventListener() {}, + removeEventListener() {}, + }; + } + + if (!w.chrome) { + w.chrome = { + app: { + isInstalled: false, + InstallState: { DISABLED: "disabled", INSTALLED: "installed", NOT_INSTALLED: "not_installed" }, + RunningState: { CANNOT_RUN: "cannot_run", CAN_RUN: "can_run", RUNNING: "running" }, + getDetails() { return null; }, + getIsInstalled() { return false; }, + installState(cb) { if (cb) cb("not_installed"); }, + runningState(cb) { if (cb) cb("cannot_run"); }, + }, + csi() { + const now = Date.now(); + return { startE: now - 100, onloadT: now, pageT: 100, tran: 15 }; + }, + loadTimes() { + const now = Date.now() / 1000; + return { + requestTime: now - 0.1, startLoadTime: now - 0.1, + commitLoadTime: now - 0.05, finishDocumentLoadTime: now, + finishLoadTime: now, firstPaintTime: now - 0.02, + firstPaintAfterLoadTime: 0, navigationType: "Other", + wasFetchedViaSpdy: true, wasNpnNegotiated: true, + npnNegotiatedProtocol: "h2", wasAlternateProtocolAvailable: false, + connectionInfo: "h2", + }; + }, + }; + } + + // navigator patch + const nav = w.navigator; + const plugins = createNavigatorPlugins(w); + const navPatch = { + userAgent: fp.userAgent, + platform: fp.platform, + language: "en-US", + languages: ["en-US", "en"], + vendor: "Google Inc.", + webdriver: false, + hardwareConcurrency: 12, + deviceMemory: 8, + maxTouchPoints: 0, + cookieEnabled: true, + plugins: plugins.plugins, + mimeTypes: plugins.mimeTypes, + appVersion: fp.userAgent.replace(/^Mozilla\//, ""), + appName: "Netscape", + appCodeName: "Mozilla", + product: "Gecko", + productSub: "20030107", + vendorSub: "", + oscpu: undefined, + doNotTrack: null, + sendBeacon: (url, data) => { + try { + const xhr = new w.XMLHttpRequest(); + xhr.open("POST", url, true); + xhr.send(data); + return true; + } catch (_) { + return false; + } + }, + }; + for (const [k, v] of Object.entries(navPatch)) { + try { + Object.defineProperty(nav, k, { value: v, configurable: true }); + } catch (_) {} + } + + // polyfill navigator sub-objects that happy-dom lacks + const makeNS = (protoObj) => { + const C = new w.Function(); + C.prototype = protoObj; + return new C(); + }; + + if (!nav.connection) { + const NetInfo = () => {}; + NetInfo.prototype = { onchange: null, effectiveType: "4g", rtt: 50, downlink: 10, saveData: false }; + w.NetworkInformation = NetInfo; + try { + Object.defineProperty(nav, "connection", { value: makeNS(NetInfo.prototype), configurable: true }); + } catch (_) {} + } + if (!nav.userAgentData) { + const UAData = function () {}; + UAData.prototype = { + brands: [ + { brand: "Chromium", version: fp.uaMajor }, + { brand: "Not)A;Brand", version: "24" }, + ], + mobile: false, + platform: "Linux", + getHighEntropyValues: () => + Promise.resolve({ + brands: [ + { brand: "Chromium", version: fp.uaMajor }, + { brand: "Not)A;Brand", version: "24" }, + ], + mobile: false, + platform: "Linux", + platformVersion: "6.5.0", + architecture: "x86", + model: "", + uaFullVersion: fp.uaFull, + fullVersionList: [ + { brand: "Chromium", version: fp.uaFull }, + { brand: "Not)A;Brand", version: "24.0.0.0" }, + ], + }), + }; + try { + Object.defineProperty(nav, "userAgentData", { value: makeNS(UAData.prototype), configurable: true }); + } catch (_) {} + } + if (!w.Permissions) { + const Perms = () => {}; + Perms.prototype = { + query: (param) => + Promise.resolve({ state: param.name === "notifications" ? "prompt" : "granted", onchange: null }), + }; + w.Permissions = Perms; + } + try { + if (!nav.permissions) Object.defineProperty(nav, "permissions", { value: makeNS(w.Permissions.prototype), configurable: true }); + } catch (_) {} + try { + if (!nav.clipboard) + Object.defineProperty(nav, "clipboard", { + value: makeNS({ readText: () => Promise.resolve(""), writeText: () => Promise.resolve() }), + configurable: true, + }); + } catch (_) {} + try { + if (!nav.geolocation) + Object.defineProperty(nav, "geolocation", { + value: makeNS({ + getCurrentPosition: (s) => s && s({ coords: { latitude: 0, longitude: 0, accuracy: 1 } }), + watchPosition: () => 1, + clearWatch: () => {}, + }), + configurable: true, + }); + } catch (_) {} + try { + if (!nav.credentials) + Object.defineProperty(nav, "credentials", { + value: makeNS({ get: () => Promise.resolve(null), create: () => Promise.resolve(null), store: () => Promise.resolve(), preventSilentAccess: () => Promise.resolve() }), + configurable: true, + }); + } catch (_) {} + try { + if (!nav.storage) + Object.defineProperty(nav, "storage", { + value: makeNS({ estimate: () => Promise.resolve({ quota: 1e8, usage: 0 }), persisted: () => Promise.resolve(false), persist: () => Promise.resolve(false) }), + configurable: true, + }); + } catch (_) {} + try { + if (!nav.usb) + Object.defineProperty(nav, "usb", { + value: makeNS({ getDevices: () => Promise.resolve([]), requestDevice: () => Promise.reject(new Error("no devices")) }), + configurable: true, + }); + } catch (_) {} + try { + if (!nav.mediaDevices) + Object.defineProperty(nav, "mediaDevices", { + value: makeNS({ enumerateDevices: () => Promise.resolve([]), getUserMedia: () => Promise.reject(new Error("NotAllowedError")) }), + configurable: true, + }); + } catch (_) {} + + // screen + const screenPatch = { + width: fp.screen.w, + height: fp.screen.h, + availWidth: fp.screen.w, + availHeight: fp.screen.ah, + availLeft: 0, + availTop: 0, + colorDepth: 24, + pixelDepth: 24, + orientation: { angle: 0, type: "landscape-primary", onchange: null }, + }; + for (const [k, v] of Object.entries(screenPatch)) { + try { + Object.defineProperty(w.screen, k, { get: () => v, configurable: true }); + } catch (_) {} + } + + w.outerWidth = fp.screen.w; + w.outerHeight = fp.screen.h - 40; + w.innerWidth = fp.screen.w - 16; + w.innerHeight = fp.screen.h - 120; + w.devicePixelRatio = 1; +} + +function createNavigatorPlugins(w) { + const indexed = [ + { name: "PDF Viewer", filename: "internal-pdf-viewer", description: "Portable Document Format" }, + { name: "Chrome PDF Viewer", filename: "mhjfbmdgcfjbbpaeojofohoefgiehjai", description: "" }, + { name: "Chromium PDF Viewer", filename: "mhjfbmdgcfjbbpaeojofohoefgiehjai", description: "" }, + ]; + const plugins = w.PluginArray ? Object.create(w.PluginArray.prototype) : {}; + const mockIndexed = []; + for (let i = 0; i < indexed.length; i++) { + const p = Object.create((w.Plugin && w.Plugin.prototype) || Object.prototype); + Object.defineProperty(p, "name", { value: indexed[i].name, configurable: true, enumerable: true }); + Object.defineProperty(p, "filename", { value: indexed[i].filename, configurable: true, enumerable: true }); + Object.defineProperty(p, "description", { value: indexed[i].description, configurable: true, enumerable: true }); + Object.defineProperty(p, "length", { value: 1, configurable: true, enumerable: true }); + Object.defineProperty(p, "0", { value: p, configurable: true, enumerable: true }); + p.item = () => p; + p.namedItem = () => p; + plugins[i] = p; + mockIndexed.push(p); + } + Object.defineProperty(plugins, "length", { value: indexed.length, configurable: true, enumerable: true }); + plugins.item = (i) => plugins[i] ?? null; + plugins.namedItem = (name) => mockIndexed.find((p) => p.name === name) ?? null; + plugins.refresh = () => {}; + const mimeTypes = + w.MimeTypeArray ? Object.create(w.MimeTypeArray.prototype) : {}; + Object.defineProperty(mimeTypes, "length", { value: 0, configurable: true, enumerable: true }); + mimeTypes.item = () => null; + mimeTypes.namedItem = () => null; + return { plugins, mimeTypes }; +} + +// โ”€โ”€ Traffic logger (XHR/fetch URL capture per solve) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +function installTrafficLogger(w) { + const origOpen = w.XMLHttpRequest.prototype.open; + const origSend = w.XMLHttpRequest.prototype.send; + w.XMLHttpRequest.prototype.open = function (method, url, ...rest) { + this.__capMethod = method; + this.__capUrl = url; + return origOpen.call(this, method, url, ...rest); + }; + w.XMLHttpRequest.prototype.send = function (body) { + const url = String(this.__capUrl || ""); + const DEBUG_HOSTS = /(cloudauth-device|captcha-open|verify|upload|nocaptcha|aliyuncs)/i; + if (DEBUG_HOSTS.test(url)) { + this.addEventListener("load", () => { + let respPreview = ""; + try { + respPreview = String(this.responseText || "").slice(0, 3000); + } catch (_) {} + try { + process.stderr.write( + `\n===== XHR ${String(this.__capMethod || "?")} ${url}\n--- RESP (${respPreview.length}b) ---\n${respPreview}\n=====\n`, + ); + } catch (_) {} + }); + } + return origSend.call(this, body); + }; +} + +function safeJson(x) { + try { + if (x instanceof Error) return `Error: ${x.message}\n${(x.stack || "").slice(0, 1500)}`; + const s = JSON.stringify(x); + return s !== undefined && s.length < 3000 ? s : String(x); + } catch (_) { + return String(x); + } +} + +// โ”€โ”€ Behavioral priming (FeiLin human-motion buffer) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +function simulateBehavior(w, durationMs = 600) { + const { document, MouseEvent, KeyboardEvent, UIEvent } = w; + if (!document || !MouseEvent) return; + const fire = (type, ctor, opts) => { + try { + const Ctor = ctor || UIEvent; + const ev = new Ctor(type, { bubbles: true, cancelable: true, view: w, ...opts }); + document.dispatchEvent(ev); + if (document.body) document.body.dispatchEvent(ev); + } catch (_) {} + }; + let x = 140 + Math.random() * 30; + let y = 110 + Math.random() * 20; + const targetX = 540 + Math.random() * 40; + const targetY = 380 + Math.random() * 30; + const steps = 22; + let i = 0; + const start = Date.now(); + const moveStep = () => { + if (i > steps) return; + x += (targetX - x) * 0.16 + (Math.random() - 0.5) * 5; + y += (targetY - y) * 0.16 + (Math.random() - 0.5) * 4; + fire("mousemove", MouseEvent, { + screenX: Math.round(x), + screenY: Math.round(y), + clientX: Math.round(x), + clientY: Math.round(y), + button: 0, + buttons: 1, + }); + i += 1; + const done = Date.now() - start >= durationMs; + if (i <= steps && !done) { + // Window-registry timer: the drag chain only touches the window and + // must die with it, not ride the dual dispatcher's host lane. + w.setTimeout(moveStep, 26 + Math.floor(Math.random() * 32)); + } else { + fire("mousedown", MouseEvent, { clientX: Math.round(x), clientY: Math.round(y), button: 0, buttons: 1 }); + fire("mouseup", MouseEvent, { clientX: Math.round(x), clientY: Math.round(y), button: 0, buttons: 0 }); + fire("click", MouseEvent, { clientX: Math.round(x), clientY: Math.round(y), button: 0 }); + try { + fire("keyup", KeyboardEvent, { key: "a", code: "KeyA", keyCode: 65, which: 65 }); + } catch (_) {} + } + }; + moveStep(); +} + +function waitFor(cond, timeoutMs = 15_000, intervalMs = 40) { + return new Promise((res, rej) => { + const started = Date.now(); + const timer = setInterval(() => { + let ok = false; + try { + ok = cond(); + } catch (_) {} + if (ok) { + clearInterval(timer); + res(); + } else if (Date.now() - started > timeoutMs) { + clearInterval(timer); + rej(new Error("timeout")); + } + }, intervalMs); + }); +} + +// โ”€โ”€ createDom โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +async function createDom(region, prefix) { + let cookies = []; + const now = Date.now(); + if (_cookieCache.ts > 0 && now - _cookieCache.ts < COOKIE_CACHE_TTL_MS) { + cookies = _cookieCache.cookies; + } else { + try { + const res = await fetch("https://zcode.z.ai/", { + headers: { + "User-Agent": fp.userAgent, + "sec-ch-ua": '"Chromium";v="' + fp.uaMajor + '", "Not)A;Brand";v="24"', + "sec-ch-ua-mobile": "?0", + "sec-ch-ua-platform": '"Linux"', + "Accept-Language": "en-US,en;q=0.9", + }, + }); + cookies = typeof res.headers.getSetCookie === "function" ? res.headers.getSetCookie() : []; + _cookieCache = { cookies, ts: Date.now() }; + } catch (_) {} + } + + const interceptor = makeInterceptor(_bypassPeCacheOnce); + _bypassPeCacheOnce = false; + // Registered once per process โ€” adding it inside createDom leaked a new + // EventEmitter listener per solve (MaxListenersExceededWarning + growth). + if (!process.__capUnhandledRejectionHooked) { + process.__capUnhandledRejectionHooked = true; + process.on("unhandledRejection", (reason) => { + if (!_DEBUG) return; + try { + const r = reason && reason.stack ? reason.stack : String(reason); + process.stderr.write(`[host-unhandledRejection] ${typeof reason} ${JSON.stringify(reason).slice(0, 200)} ${r}\n`); + } catch (_) {} + }); + // Guest scripts (rotated pe/FeiLin bundles) can throw synchronous errors + // that surface as uncaughtExceptions. Without a handler, happy-dom's + // exception observer (or Bun's default) terminates the whole proxy โ€” + // a single bad pe version must only fail that one solve, not the server. + process.on("uncaughtException", (err) => { + try { + const msg = err && err.message ? err.message : String(err); + process.stderr.write(`[captcha-guest-uncaught] ${msg}\n`); + } catch (_) {} + }); + } + // Guest console is silent unless CAPTCHA_DEBUG โ€” piping every SDK log to + // stderr spams journald and slows mints under systemd. + const noop = () => {}; + const guestConsole = _DEBUG + ? { + log: (...a) => process.stderr.write(`[guest-log] ${a.map((x) => (typeof x === "object" ? safeJson(x) : String(x))).join(" ")}\n`), + warn: (...a) => process.stderr.write(`[guest-warn] ${a.map((x) => (typeof x === "object" ? safeJson(x) : String(x))).join(" ")}\n`), + error: (...a) => process.stderr.write(`[guest-err] ${a.map((x) => (typeof x === "object" ? safeJson(x) : String(x))).join(" ")}\n`), + info: (...a) => process.stderr.write(`[guest-info] ${a.map((x) => (typeof x === "object" ? safeJson(x) : String(x))).join(" ")}\n`), + debug: (...a) => process.stderr.write(`[guest-debug] ${a.map((x) => (typeof x === "object" ? safeJson(x) : String(x))).join(" ")}\n`), + trace: (...a) => process.stderr.write(`[guest-trace] ${a.map((x) => (typeof x === "object" ? safeJson(x) : String(x))).join(" ")}\n`), + } + : { log: noop, warn: noop, error: noop, info: noop, debug: noop, trace: noop }; + const w = new Window({ + url: "https://zcode.z.ai/", + console: guestConsole, + settings: { + enableJavaScriptEvaluation: true, + enableImageFileLoading: true, + suppressInsecureJavaScriptEnvironmentWarning: true, + navigator: { userAgent: fp.userAgent }, + viewport: { width: fp.screen.w, height: fp.screen.h, devicePixelRatio: 1 }, + fetch: { + disableSameOriginPolicy: true, + interceptor, + }, + }, + }); + + // Reach into the frame for cookie container + frame ref (host side helpers). + // WindowBrowserContext imported at module scope + const browserFrame = new WindowBrowserContext(w).getBrowserFrame(); + global.__browserFrame = browserFrame; + global.__cookieContainer = browserFrame.page.context.cookieContainer; + + // Cookie priming + for (const raw of cookies) { + try { + const u = new URL("https://zcode.z.ai/"); + const parts = raw.split(";"); + const pair = parts[0].split("="); + const cookie = { + name: pair[0].trim(), + value: pair.slice(1).join("=").trim(), + url: u.origin, + domain: u.hostname, + path: "/", + }; + for (const p of parts.slice(1)) { + const kv = p.trim().split(/=(.*)/s); + const k = (kv[0] || "").toLowerCase(); + if (k === "domain" && kv[1]) cookie.domain = kv[1]; + if (k === "path" && kv[1]) cookie.path = kv[1]; + if (k === "expires") cookie.expires = new Date(kv[1]).getTime(); + if (k === "max-age") cookie.maxAge = parseInt(kv[1], 10); + if (k === "httponly") cookie.httpOnly = true; + if (k === "secure") cookie.secure = true; + if (k === "samesite") cookie.sameSite = kv[1]; + } + browserFrame.page.context.cookieContainer.addCookies([cookie]); + } catch (_) {} + } + + const visitorId = crypto.randomUUID(); + const deviceMid = crypto.randomUUID(); + const pre = [ + { name: "zcode_visitor_id", value: visitorId, domain: "zcode.z.ai" }, + { name: "zcode_device_mid", value: deviceMid, domain: "zcode.z.ai" }, + { name: "visitor_id", value: visitorId, domain: "zcode.z.ai", httpOnly: true }, + ]; + for (const c of pre) { + try { + browserFrame.page.context.cookieContainer.addCookies([{ ...c, url: "https://zcode.z.ai", path: "/" }]); + } catch (_) {} + } + + // Apply polyfills + masking BEFORE the SDK script runs. + // Bun compatibility: happy-dom's VM realm isolation doesn't apply under + // Bun โ€” script tags execute against the host globalThis, where bare + // `window`/`document`/`location` identifiers don't exist. Node needs none + // of this (its VM context resolves them natively). We alias the current + // solve's window on globalThis and remove the aliases when the window is + // destroyed, so concurrent solves with window reuse stay consistent. + applyPolyfills(w); + installNativeToString(w); + // Guest timer scope must exist BEFORE the eval hook wraps any script. + installGuestScope(w); + installEvalInstrumentation(w); + // Bun alias pass runs AFTER polyfills so polyfilled props (Option, Video, + // alert, ...) are visible to guest scripts via globalThis too. + const needsGlobalAlias = typeof Bun !== "undefined"; + if (needsGlobalAlias) { + const g = globalThis; + installGlobalWindowAlias(g, w); + } + if (w.Error) { + w.Error.prepareStackTrace = Error.prepareStackTrace; + } + // Host-side recorder the guest dump helper calls: computes sha1 of the failing + // source (guest realm has no node crypto) and re-checks the pe disk cache. + w.__capDebugDump = (url, src, kind) => { + try { + const s = String(src || ""); + const sha1 = crypto.createHash("sha1").update(s).digest("hex"); + process.stderr.write( + `\n[${kind}] url=${url} len=${s.length} sha1=${sha1}\n` + + ` head300: ${JSON.stringify(s.slice(0, 300))}\n` + + ` tail100: ${JSON.stringify(s.slice(-100))}\n`, + ); + if (/^https?:/.test(String(url))) { + (async () => { + try { + const res = await fetch(url, { headers: { "user-agent": fp.userAgent } }); + const fresh = Buffer.from(await res.arrayBuffer()); + process.stderr.write( + `[${kind}-CACHE-COMPARE] cachedLen=${s.length} freshLen=${fresh.length} freshSha1=${crypto.createHash("sha1").update(fresh).digest("hex")} http=${res.status}\n`, + ); + if (fresh.length > 0 && fresh.length !== s.length) { + process.stderr.write(`[${kind}-MISMATCH] deleting ${diskPathFor(url)} (stale/truncated cache)\n`); + try { + fs.unlinkSync(diskPathFor(url)); + } catch (_) {} + _memCdnCache.delete(url); + } + } catch (fetchErr) { + process.stderr.write(`[${kind}-CACHE-COMPARE-ERR] ${fetchErr.message}\n`); + } + })(); + } + } catch (_) {} + }; + w.eval(GUEST_EVAL_PATCH); + + // Write the page HTML (loads the SDK script) + w.document.write(HTML); + + w.AliyunCaptchaConfig = { region, prefix }; + + return { window: w, browserFrame }; +} + +// Bun-only: alias the active window on globalThis (script tags run in the +// host realm under Bun). Every own enumerable window property is exposed as a +// getter so guest scripts resolving bare identifiers (window, document, +// XMLHttpRequest, Range, HTMLElement, ...) find them, exactly as Node's VM +// realm would. Removed again in destroyDom. +// Names that must NOT be shadowed on globalThis โ€” Bun/Node host internals the +// window happens to expose but the host runtime depends on. +const HOST_CRITICAL_GLOBALS = new Set([ + "process", "Bun", "console", "performance", "crypto", "fetch", + "queueMicrotask", "structuredClone", "TextEncoder", "TextDecoder", + // Timers stay pristine on globalThis so Bun internals keep real Node timer + // objects (`.unref()`); guest code gets the window's registry lexically. + "setTimeout", "setInterval", "clearTimeout", "clearInterval", + // NOTE: requestAnimationFrame/cancelAnimationFrame were removed from this + // list (2026-09-06). Bun has no native rAF, so skipping the alias left a + // bare `requestAnimationFrame` in the FeiLin bundle unresolvable (9 call + // sites, only one `typeof`-guarded) โ€” the same silent fingerprint + // degradation that `print` caused. Aliasing the window's implementation + // shadows nothing on the host. + // NOTE: `print` was removed from this list (2026-08-29). The polyfill + // defines a harmless no-op on the window, but the alias pass skipped it, + // so under Bun (guest scripts run in the HOST realm) the Aliyun pe risk + // engine hit a bare `print` reference โ†’ ReferenceError โ†’ broken + // fingerprint chain โ†’ degraded solve success rate (711 WINDOW-ERRORs in + // one day). Bun's host global has no native `print`, so aliasing the + // stub shadows nothing critical. + "URL", "URLSearchParams", "AbortController", "AbortSignal", + "ReadableStream", "WritableStream", "TransformStream", "Blob", "File", + "FormData", "Headers", "Request", "Response", "Event", "EventTarget", + "MessageChannel", "MessagePort", "Buffer", "global", "globalThis", + // JS intrinsics โ€” GlobalWindow re-exposes them as class fields; the host + // versions are fine, so never shadow them. + "Array", "ArrayBuffer", "Boolean", "DataView", "Date", "Error", + "EvalError", "Float32Array", "Float64Array", "Function", "Infinity", + "Int8Array", "Int16Array", "Int32Array", "Intl", "JSON", "Map", "Math", + "NaN", "Number", "Object", "Promise", "RangeError", "ReferenceError", + "RegExp", "Reflect", "Set", "String", "Symbol", "SyntaxError", "TypeError", + "URIError", "Uint8Array", "Uint8ClampedArray", "Uint16Array", "Uint32Array", + "WeakMap", "WeakSet", "decodeURI", "decodeURIComponent", "encodeURI", + "encodeURIComponent", "escape", "isFinite", "isNaN", "parseFloat", + "parseInt", "unescape", "eval", +]); +// Window methods that exist as prototype members, not own props โ€” the alias +// pass must include them so guest bare-name references resolve (moveBy, +// scrollTo, ... are referenced by the FeiLin fingerprint SDK). +const EXTRA_WINDOW_PROPS = [ + "moveBy", "moveTo", "resizeBy", "resizeTo", "scrollTo", "scrollBy", "scroll", + "open", "close", "stop", "focus", "blur", "print", "alert", "confirm", + "prompt", "getSelection", "find", +]; +// Subset of the above that a real browser implements as no-op-ish window +// methods. When the tombstone expires these become harmless stubs instead of +// being deleted, so a straggling guest callback that still calls `moveBy()` +// completes silently rather than raising a fatal ReferenceError. +const INERT_WINDOW_METHODS = new Set(EXTRA_WINDOW_PROPS); + +// Ref-count: the pool solves in parallel waves; each window must keep the +// aliases alive until the LAST concurrent window is destroyed, otherwise one +// destroyDom() pulls `window` out from under a sibling mid-solve. +let _aliasRefCount = 0; + +// Post-teardown tombstone (see removeGlobalWindowAlias): how long window- +// sourced alias getters keep resolving โ€” to the CLOSED window โ€” after the +// last destroyDom. Guest (FeiLin) async fingerprint chains ride host +// machinery (fetch/promise continuations) and can outlive the window; a +// hard delete turns their next bare `Text`/`document` reference into an +// uncaught ReferenceError (v4.5.2 field report: "Text is not defined" from +// feilin005.js). The closed window's objects stay readable, so stragglers +// run harmlessly to completion; a new solve wave (generation bump) cancels +// the pending deletion entirely. The pristine host setTimeout captured at +// module load schedules it โ€” never the aliased one. +const ALIAS_TOMBSTONE_MS = 30_000; +let _aliasGeneration = 0; +let _tombstoneMs = ALIAS_TOMBSTONE_MS; +const _hostSetTimeout = globalThis.setTimeout; +// Every getter this module installs on the alias target (generic window +// forwarders, window/self/top/parent, dual timers, __capWindowFor). The +// host-global snapshot skips descriptors whose getter is in here: a wave +// that starts inside a previous wave's grace period finds OUR OWN stale +// accessors still on `g`, and saving them would "restore" window accessors +// at removal โ€” permanently pinning the first closed window (review-caught +// 2026-08-31). Host getters (Bun's navigator/self accessors) are never in +// this set and always flow to the restore path. +const _aliasGetters = new WeakSet(); + +// Same save/restore contract for every HOST-EXISTING global the alias pass +// overwrites (see installGlobalWindowAlias for the rationale). Captured on the +// FIRST install of a wave (globals are pristine then), restored on the last +// remove. +let _savedHostGlobalDescriptors: Record | undefined; + +// Guest timer/console routing is LEXICAL (see the guest scope section above): +// bare `setTimeout`/`console` inside guest source resolve through the `with` +// scope to this window's own objects. No stack sniffing โ€” the previous +// `/alicdn/.test(new Error().stack)` predicate answered "who is calling?" when +// the question is "who owns this?", and got both directions wrong (immortal +// guest heartbeats; host timers stripped of `.unref`). +// +// So globalThis keeps the PRISTINE host timers at all times, and Bun internals +// (node:_http_server keep-alive, undici, AbortSignal.timeout) always get real +// Node timer objects with an intact ref/unref contract. + +// Both take (g, w) explicitly so tests can drive the lifecycle against a +// sandbox global. `tombstoneMs` (tests only) shortens the grace period. +export function installGlobalWindowAlias(g, w, tombstoneMs?) { + // Clamp a negative refcount: an unbalanced remove would otherwise land the + // NEXT install at 0 instead of 1 and skip the host-global snapshot, so + // teardown could never restore what it overwrote. + if (_aliasRefCount < 0) _aliasRefCount = 0; + _aliasRefCount += 1; + _aliasGeneration += 1; // cancels any pending tombstone from a prior wave + _tombstoneMs = typeof tombstoneMs === "number" ? tombstoneMs : ALIAS_TOMBSTONE_MS; + // Build the alias name set FIRST, then snapshot every HOST-EXISTING global + // in it BEFORE anything is aliased. The generic props loop below overwrites + // them with window-forwarding accessors (GlobalWindow own props outside + // HOST_CRITICAL_GLOBALS); a capture taken after it would save those + // accessors and the post-remove restore would reinstate accessors onto a + // closed window. The snapshot covers atob/btoa (client-signing's base64 โ€” + // field-reported ReferenceError), WebSocket, MessageEvent, CustomEvent, + // navigator, self, ... โ€” every host global the window happens to expose. + const props = new Set(Object.getOwnPropertyNames(w)); + for (const name of EXTRA_WINDOW_PROPS) props.add(name); + // also walk the prototype chain one level (BrowserWindow getters like + // navigator/location live there in some versions) + for (const proto = Object.getPrototypeOf(w); proto && proto !== Object.prototype;) { + for (const name of Object.getOwnPropertyNames(proto)) props.add(name); + break; + } + if (_aliasRefCount === 1 && !_savedHostGlobalDescriptors) { + const saved: Record = {}; + for (const prop of props) { + if (prop === "constructor" || HOST_CRITICAL_GLOBALS.has(prop)) continue; + try { + const d = Object.getOwnPropertyDescriptor(g, prop); + // Skip OUR OWN stale accessors from a previous wave that was + // cancelled mid-grace (retry ladder / pool bursts start the next + // wave within the 30s tombstone): saving them would "restore" + // window-forwarding accessors at removal and permanently pin the + // first closed window on globalThis. They are window-sourced โ€” the + // new wave's tombstone owns their cleanup. Host getters (Bun's + // navigator/self accessors) are never in the WeakSet and keep + // flowing to the restore path. + if (d && d.get && _aliasGetters.has(d.get)) continue; + if (d) saved[prop] = d; + } catch (_) {} + } + for (const prop of ["window", "self", "top", "parent", "__capWindowFor"]) { + try { + const d = Object.getOwnPropertyDescriptor(g, prop); + if (d && d.get && _aliasGetters.has(d.get)) continue; + if (d && !saved[prop]) saved[prop] = d; + } catch (_) {} + } + _savedHostGlobalDescriptors = saved; + } + for (const prop of props) { + if (HOST_CRITICAL_GLOBALS.has(prop)) continue; + try { + const getter = function () { return w[prop]; }; + _aliasGetters.add(getter); + Object.defineProperty(g, prop, { + get: getter, + set(v) { + try { w[prop] = v; } catch (_) {} + }, + configurable: true, + }); + } catch (_) {} + } + // w.window/self may not exist as own props on this happy-dom build + for (const prop of ["window", "self", "top", "parent"]) { + try { + const getter = function () { return w; }; + _aliasGetters.add(getter); + Object.defineProperty(g, prop, { get: getter, configurable: true }); + } catch (_) {} + } + // Timers are deliberately NOT aliased: globalThis keeps Bun's pristine + // functions so node:_http_server keep-alive, undici and AbortSignal.timeout + // always receive real Node timer objects with an intact `.unref()`. Guest + // code reaches the window's registry through the lexical `with` scope + // instead, so its callbacks still die in happyDOM.close(). + // Dynamic catch-all: guest code occasionally references window methods that + // only exist on the prototype (moveBy, scrollTo, ...) or lands mid-solve on + // new props. Proxy fallback for any still-missing global property. + try { + const capGetter = function () { return w; }; + _aliasGetters.add(capGetter); + Object.defineProperty(g, "__capWindowFor", { + get: capGetter, + configurable: true, + }); + } catch (_) {} +} +export function removeGlobalWindowAlias(g, w) { + _aliasRefCount -= 1; + if (_aliasRefCount > 0) return; + // Host-contract globals come back IMMEDIATELY: every HOST-EXISTING global + // the wave overwrote โ€” atob/btoa (client-signing's JWT base64 โ€” the + // field-reported ReferenceError), WebSocket/MessageEvent/navigator/self/... + // The timers and console were never aliased, so nothing to restore there. + const restored = new Set(); + if (_savedHostGlobalDescriptors) { + for (const [name, desc] of Object.entries(_savedHostGlobalDescriptors)) { + try { Object.defineProperty(g, name, desc); } catch (_) {} + restored.add(name); + } + _savedHostGlobalDescriptors = undefined; + } + // Window-sourced globals get a TOMBSTONE grace period instead of an + // immediate delete (see the ALIAS_TOMBSTONE_MS comment). Collect what is + // still accessor-aliased, EXCLUDING the restored set โ€” a restored host + // descriptor may itself be a getter (Bun's navigator/self are accessors) + // and must never be tombstone-deleted. + const generation = _aliasGeneration; + const names: string[] = []; + try { + for (const name of Object.getOwnPropertyNames(w)) { + if (restored.has(name)) continue; + try { + if (Object.getOwnPropertyDescriptor(g, name)?.get) names.push(name); + } catch (_) {} + } + for (const prop of ["window", "self", "top", "parent", "__capWindowFor"]) { + if (restored.has(prop)) continue; + try { + if (Object.getOwnPropertyDescriptor(g, prop)?.get) names.push(prop); + } catch (_) {} + } + } catch (_) {} + try { + const t = _hostSetTimeout(() => { + if (generation !== _aliasGeneration || _aliasRefCount > 0) return; + for (const name of names) { + try { + if (!Object.getOwnPropertyDescriptor(g, name)?.get) continue; + // Do NOT `delete`: a straggler still reading the name would get a + // ReferenceError, which is fatal in the host realm. Leave an inert + // value instead โ€” the reference resolves, the call is a no-op, and + // nothing keeps the closed window alive. The window methods guest + // fingerprint code probes (moveBy/scrollTo/...) are no-ops in a real + // browser anyway, so `undefined` is a faithful stand-in for the rest. + const stub = INERT_WINDOW_METHODS.has(name) ? () => {} : undefined; + Object.defineProperty(g, name, { + value: stub, + configurable: true, + writable: true, + }); + } catch (_) {} + } + }, _tombstoneMs); + try { + if (t && typeof t.unref === "function") t.unref(); + } catch (_) {} + } catch (_) {} +} + +function destroyDom(win) { + try { + const cap = win.document.getElementById("cap"); + if (cap) cap.replaceChildren(); + win.happyDOM.close(); + } catch (_) {} + try { + global.__cookieContainer = null; + global.__browserFrame = null; + } catch (_) {} + try { + if (typeof Bun !== "undefined") removeGlobalWindowAlias(globalThis, win); + } catch (_) {} + // The scope holds window-bound timer functions; dropping it releases the + // closed window and makes any straggler's `new Function` fall back to the + // host constructor (harmless: the window registry is already cleared). + removeGuestScope(win); + try { shutdownSyncFetchWorker(); } catch (_) {} +} + +function extractVerifyParam(param) { + let verifyParam = param; + if (param && typeof param === "object") { + verifyParam = param.verifyParam || param.data || param.param; + } + if (!verifyParam || String(verifyParam).length < 20) { + throw new Error("solver returned empty param: " + JSON.stringify(param)); + } + const str = String(verifyParam); + // Strict validation: a REAL Aliyun verify param is ~280 chars of base64 + // JSON containing certifyId + sceneId + isSign + a long securityToken. + // Len-76 junk like {"certifyId":"70bdb",...,"isSign":true} (no securityToken) + // comes from a degraded SDK result path and WILL 3007 upstream โ€” never let + // it out of the solver. + if (str.length < 200) { + throw new Error( + "verify param too short (" + str.length + " chars) โ€” degraded result, refusing: " + str.slice(0, 80), + ); + } + try { + const decoded = JSON.parse(Buffer.from(str, "base64").toString("utf8")); + const secTok = decoded && (decoded.securityToken || decoded.SecurityToken); + if (!secTok || String(secTok).length < 50) { + throw new Error( + "verify param missing securityToken โ€” refusing degraded result: " + str.slice(0, 80), + ); + } + } catch (err) { + if (err instanceof SyntaxError || /securityToken/.test(String(err.message))) { + throw err instanceof SyntaxError + ? new Error("verify param not base64-JSON: " + str.slice(0, 80)) + : err; + } + throw err; + } + return str; +} + +function handleCaptchaResult(result) { + if (result && typeof result === "object" && result.verifyResult === false) { + throw new Error( + "verify rejected: " + + JSON.stringify({ verifyCode: result.verifyCode, certifyId: result.certifyId }), + ); + } + return result; +} + +// โ”€โ”€ Window reuse pool โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Reusing one happy-dom window across solves cuts CPU ~48% (measured: 426ms vs +// 815ms per solve) by amortizing the DOM boot + SDK script load. Enabled via +// CAPTCHA_WINDOW_REUSE=1 (or solveTraceless({reuseWindow:true})). The window +// is discarded after `maxSolves` (memory growth), after any stall/failure +// (fresh InitCaptchaV3 rolls a new pe version), or after `maxIdleMs` idle. +const _reusePool = { window: null, browserFrame: null, solves: 0, lastUsedAt: 0 }; +const REUSE_MAX_SOLVES = Number(process.env.CAPTCHA_REUSE_MAX_SOLVES || 25); +const REUSE_MAX_IDLE_MS = Number(process.env.CAPTCHA_REUSE_MAX_IDLE_MS || 120_000); + +function takeReusableWindow() { + const p = _reusePool; + if (!p.window) return null; + if (p.solves >= REUSE_MAX_SOLVES) { discardReusableWindow(); return null; } + if (Date.now() - p.lastUsedAt > REUSE_MAX_IDLE_MS) { discardReusableWindow(); return null; } + return { window: p.window, browserFrame: p.browserFrame, reused: true }; +} +function stageReusableWindow(window, browserFrame) { + _reusePool.window = window; + _reusePool.browserFrame = browserFrame; + _reusePool.solves = 0; + _reusePool.lastUsedAt = Date.now(); +} +function discardReusableWindow() { + const p = _reusePool; + if (p.window) { + try { destroyDom(p.window); } catch (_) {} + } + p.window = null; + p.browserFrame = null; + p.solves = 0; +} +function noteWindowSolved() { + _reusePool.solves += 1; + _reusePool.lastUsedAt = Date.now(); +} + +// โ”€โ”€ Guest error capture (read side) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// GUEST_EVAL_PATCH records every guest window error into window.__capErrs +// (capped, deduped) instead of console-printing them: the Aliyun/FeiLin SDKs +// throw benign uncaught TypeErrors inside happy-dom on every solve and the +// solve still succeeds, so printing them is pure console spam. The buffer is +// surfaced only when a solve FAILS โ€” that's when guest errors are +// actionable. CAPTCHA_DEBUG=1 streams them live again as +// [WINDOW-ERROR]/[UH-REASON]. +function guestErrorSummary(w, max = 4) { + try { + const errs = w && w.__capErrs; + if (!errs || !errs.length) return ""; + const total = errs.reduce((a, e) => a + ((e && e.n) || 1), 0); + const parts = errs.slice(0, max).map((e) => { + const n = e && e.n && e.n > 1 ? `x${e.n}` : ""; + return `${(e && e.k) || "?"}${n}: ${String((e && e.m) || "?").slice(0, 120)}`; + }); + return ` guestErrors(${total}): ${parts.join(" || ")}`; + } catch (_) { + return ""; + } +} + +async function solveTraceless(opts) { + const scene = opts.scene || "11xygtvd"; + const region = opts.region || "sgp"; + const prefix = opts.prefix || "no8xfe"; + const timeoutMs = opts.timeoutMs ?? 30_000; + + const wantReuse = opts.reuseWindow ?? process.env.CAPTCHA_WINDOW_REUSE === "1"; + let dom; + let reused = false; + if (wantReuse) { + dom = takeReusableWindow(); + if (dom) reused = true; + } + if (!dom) { + dom = await createDom(region, prefix); + } + const { window: w, browserFrame } = dom; + const solveStart = Date.now(); + let solveSucceeded = false; + let keepWindow = false; + try { + await waitFor(() => typeof w.initAliyunCaptcha === "function", timeoutMs, 50); + + simulateBehavior(w, 600); + + const param = await new Promise((resolve, reject) => { + const timer = setTimeout(() => { + const peUrl = (() => { try { return w.__lastPeUrl || "?"; } catch (_) { return "?"; } })(); + const reqs = _requestLog + .filter((r) => r.at >= solveStart) + .map((r) => `${(r.at - solveStart)}ms ${r.method} ${String(r.url).replace(/^https?:\/\//, "").slice(0, 60)}`) + .slice(-12); + reject(new Error(`captcha solve timeout pe=${peUrl.split("/").pop() || peUrl} reqs=${JSON.stringify(reqs)}`)); + }, timeoutMs); // Fail-fast stall detector: healthy solves keep firing XHRs until verify + // (~3s). If no XHR for stallMs and none pending, this pe-VM variant + // stalled (seen across rotated pe.0xx versions) โ€” abort early so the + // caller can retry with a fresh InitCaptchaV3 (new pe version). + // Fail-fast stall detector: healthy solves keep firing XHRs until + // verify (~3s, gaps <2s). If no XHR for 6s, this pe-VM variant stalled + // (seen across rotated pe.0xx versions) โ€” abort early so the caller + // can retry with a fresh InitCaptchaV3 (new pe version). + const stallMs = opts.stallMs ?? Number(process.env.CAPTCHA_STALL_MS || 6_000); + const stallTimer = setInterval(() => { + const last = _requestLog[_requestLog.length - 1]; + if (last && Date.now() - last.at > stallMs) { + const peUrl = (() => { try { return w.__lastPeUrl || "?"; } catch (_) { return "?"; } })(); + noteStallAndMaybeEvict(peUrl); + const reqs = _requestLog + .filter((r) => r.at >= solveStart) + .map((r) => `${(r.at - solveStart)}ms ${r.method} ${String(r.url).replace(/^https?:\/\//, "").slice(0, 60)}`) + .slice(-12); + clearTimeout(timer); + clearInterval(stallTimer); + reject(new Error(`captcha solve stall pe=${peUrl.split("/").pop() || peUrl} lastXhr=${(last.at - solveStart)}ms reqs=${JSON.stringify(reqs)}`)); + } + }, 500); + const finish = (fn) => (value) => { + clearTimeout(timer); + clearInterval(stallTimer); + fn(value); + }; + try { + w.initAliyunCaptcha({ + SceneId: scene, + mode: "popup", + region, + prefix, + language: "en", + element: "#cap", + button: "#btn", + captchaLogoImg: "", + showErrorTip: false, + getInstance: (inst) => { + try { + (inst.startTracelessVerification || inst.show).call(inst); + } catch (e) { + finish(reject)(new Error(`start: ${e.message}`)); + } + }, + success: (result) => { + try { + finish(resolve)(handleCaptchaResult(result)); + } catch (err) { + finish(reject)(err); + } + }, + fail: (err) => finish(reject)(new Error(`fail: ${JSON.stringify(err)}`)), + onError: (err) => finish(reject)(new Error(`onError: ${JSON.stringify(err)}`)), + }); + } catch (err) { + clearTimeout(timer); + reject(err); + } + }); + + // Success clears this pe's stall history so future isolated stalls can + // still trigger eviction after two genuine consecutive failures. Also + // clears the guest error buffer: a pooled window's next failure must + // only report errors from solves after this success. + try { + const okPe = w.__lastPeUrl; + if (okPe) _stallCounts.delete(okPe); + w.__capErrs = []; + } catch (_) {} + + // Dump the pe-VM btoa tracer if requested (rotation forensics). + if (process.env.CAPTCHA_DUMP_DBT === "1") { + try { + const dbt = w.__DBT || []; + fs.writeFileSync( + process.env.CAPTCHA_DBT_FILE || "/tmp/pe-dbt.json", + JSON.stringify({ count: dbt.length, last: dbt.slice(-8), all: dbt }, null, 1), + ); + } catch (_) {} + } + + solveSucceeded = true; + const out = extractVerifyParam(param); + if (wantReuse) { + if (reused) noteWindowSolved(); + else stageReusableWindow(w, browserFrame); + keepWindow = true; + } + return out; + } catch (err) { + // Attach captured guest window errors to the failure โ€” the only situation + // where they are actionable (a successful solve makes them irrelevant). + const summary = guestErrorSummary(w); + if (summary) { + try { + err.message = `${err && err.message ? err.message : String(err)} |${summary}`; + } catch (_) {} + } + throw err; + } finally { + // Reuse mode: on success the window stays pooled (keepWindow) for the next + // solve โ€” a ~48% CPU cut. On failure it is destroyed: a stalled window must + // not poison later solves, and the retry rolls a fresh pe anyway. + if (!keepWindow) { + if (_reusePool.window === w) _reusePool.window = null; + destroyDom(w); + } + } +} + +export { solveTraceless, createDom, destroyDom }; diff --git a/src/proxy/captcha-pool.ts b/src/proxy/captcha-pool.ts new file mode 100644 index 0000000000000000000000000000000000000000..8a09807f70c9a35cc61bdf94b86dae3224598027 --- /dev/null +++ b/src/proxy/captcha-pool.ts @@ -0,0 +1,721 @@ +import { + CaptchaCpuGovernor, + resolveCpuGovernorConfig, + type CpuGovernorSnapshot, +} from "./captcha-cpu-governor.js"; +import { + captchaSolverConcurrency, + runCaptchaSolve, + setCaptchaSolverConcurrency, + shutdownCaptchaSolver, +} from "./captcha-solver.js"; +import { isCaptchaDuplicateError, isCaptchaIpBlockError, parseCertifyId } from "./captcha-token.js"; + +export interface CaptchaPoolOptions { + /** @deprecated Use poolSizeMax โ€” kept as max cap alias. */ + poolSize?: number; + poolSizeMin?: number; + poolSizeMax?: number; + /** Idle seconds before shrinking toward min (default 120). */ + scaleDownIdleMs?: number; + /** Deep-idle floor: pool target decays to this after sustained zero traffic + * (default 1). First token take restores the full poolSizeMin. */ + idleFloor?: number; + /** Zero-traffic seconds after which background solving stops entirely โ€” + * target floor decays to 0 (default 900). One banked token is still kept + * for an instant serve on wake-up. */ + deepIdleAfterMs?: number; + tokenTtlMs?: number; + refillIntervalMs?: number; + solveRetries?: number; + staggerMs?: number; + solveConcurrency?: number; + /** Parallel solves raced when a take finds the pool empty (default 2). */ + emptyTakeRace?: number; + /** Host CPU ceiling for captcha workers (default 100, 0 = off). */ + cpuLimitPercent?: number; + cpuGovernorIntervalSec?: number; + /** + * Called when minting fails with an IP-level block ("too many captcha + * requests" family). The proxy wires this to the Telegram network reset so + * an Aliyun IP block self-heals instead of stranding the token pool. + */ + onCaptchaIpBlock?: (reason: string) => void; +} + +type TokenEntry = { param: string; cachedAt: number; certifyId: string | null }; + +/** Tracks certifyIds already handed out or queued โ€” prevents F008 duplicate usage. */ +class CertifyIdRegistry { + private seen = new Map(); + + constructor(private ttlMs: number) {} + + setTtlMs(ttlMs: number): void { + this.ttlMs = ttlMs; + } + + prune(): void { + const cutoff = Date.now() - this.ttlMs; + for (const [id, at] of this.seen) { + if (at < cutoff) this.seen.delete(id); + } + } + + has(id: string): boolean { + this.prune(); + return this.seen.has(id); + } + + add(id: string): void { + this.prune(); + this.seen.set(id, Date.now()); + } + + clear(): void { + this.seen.clear(); + } +} + +const DEFAULT_POOL_MIN = Number(process.env.CAPTCHA_POOL_MIN || 40); +const DEFAULT_POOL_MAX = Number(process.env.CAPTCHA_POOL_MAX || 120); +const DEFAULT_TOKEN_TTL_MS = Number(process.env.CAPTCHA_CACHE_TTL_MS || 95_000); +const DEFAULT_REFILL_INTERVAL_MS = Number(process.env.CAPTCHA_REFILL_INTERVAL_MS || 1_000); +const DEFAULT_STAGGER_MS = Number(process.env.CAPTCHA_SOLVE_STAGGER_MS || 0); +const DEFAULT_SOLVE_CONCURRENCY = Number( + process.env.CAPTCHA_SOLVE_CONCURRENCY || + (process.env.ZCODE_CAPTCHA_LOW_CPU === "1" ? 3 : 8), +); +const DEFAULT_SCALE_DOWN_IDLE_MS = Number(process.env.CAPTCHA_POOL_SCALE_DOWN_IDLE_MS || 120_000); +const DEFAULT_IDLE_FLOOR = Number(process.env.CAPTCHA_POOL_IDLE_FLOOR || 1); +// Zero-traffic beyond this stops background solving entirely (floor 0): no +// mint churn, near-zero CPU. The next token take restores poolSizeMin. +const DEFAULT_DEEP_IDLE_AFTER_MS = Number(process.env.CAPTCHA_DEEP_IDLE_AFTER_MS || 900_000); +// Parallel solves raced on an empty-pool take โ€” first success serves the +// client, the twins top up the pool. Cuts worst-case cold TTFB and widens +// odds against a bad rotated pe bundle stalling one racer. +const EMPTY_TAKE_RACE = Math.max(1, Number(process.env.CAPTCHA_EMPTY_TAKE_RACE || 3)); +const SOLVE_RETRIES = Number(process.env.ZCODE_CAPTCHA_RETRIES || 4); +const SCALE_UP_STEP = 20; +const TAKE_RATE_WINDOW_MS = 120_000; + +type ResolvedPoolOpts = { + poolSizeMin: number; + poolSizeMax: number; + idleFloor: number; + deepIdleAfterMs: number; + scaleDownIdleMs: number; + tokenTtlMs: number; + refillIntervalMs: number; + solveRetries: number; + staggerMs: number; + solveConcurrency: number; + emptyTakeRace: number; + onCaptchaIpBlock?: (reason: string) => void; +}; + +function resolvePoolOpts(opts: CaptchaPoolOptions): ResolvedPoolOpts { + const max = opts.poolSizeMax ?? opts.poolSize ?? DEFAULT_POOL_MAX; + const min = Math.min(opts.poolSizeMin ?? DEFAULT_POOL_MIN, max); + return { + poolSizeMin: min, + poolSizeMax: max, + idleFloor: Math.min(opts.idleFloor ?? DEFAULT_IDLE_FLOOR, min), + deepIdleAfterMs: Math.max( + opts.deepIdleAfterMs ?? DEFAULT_DEEP_IDLE_AFTER_MS, + opts.scaleDownIdleMs ?? DEFAULT_SCALE_DOWN_IDLE_MS, + ), + scaleDownIdleMs: opts.scaleDownIdleMs ?? DEFAULT_SCALE_DOWN_IDLE_MS, + tokenTtlMs: opts.tokenTtlMs ?? DEFAULT_TOKEN_TTL_MS, + refillIntervalMs: opts.refillIntervalMs ?? DEFAULT_REFILL_INTERVAL_MS, + solveRetries: opts.solveRetries ?? SOLVE_RETRIES, + staggerMs: opts.staggerMs ?? DEFAULT_STAGGER_MS, + solveConcurrency: opts.solveConcurrency ?? DEFAULT_SOLVE_CONCURRENCY, + emptyTakeRace: Math.max(1, opts.emptyTakeRace ?? EMPTY_TAKE_RACE), + onCaptchaIpBlock: opts.onCaptchaIpBlock, + }; +} + +export class CaptchaTokenPool { + private tokens: TokenEntry[] = []; + private opts: ResolvedPoolOpts; + private effectiveTarget: number; + private refillTimer: ReturnType | null = null; + private refillInFlight = false; + private lastSolveAt = 0; + private activeSolves = 0; + private cfg: CaptchaConfig | null = null; + private pausedUntil = 0; + private lastTakeAt: number; + private takeTimestamps: number[] = []; + private certifyIds: CertifyIdRegistry; + private governor: CaptchaCpuGovernor | null = null; + // Mint-storm detection: sliding windows of failed vs successful mint + // attempts. A burst of failures with zero successes means velocity/IP + // flagging โ€” fire the telegram IP reset automatically. + private mintFailures: number[] = []; + private mintSuccesses: number[] = []; + private lastStormResetAt = 0; + + constructor(opts: CaptchaPoolOptions = {}) { + // The module-level singleton constructs with no opts before config load; + // resolvePoolOpts would fall back to env/global defaults there (e.g. + // poolSizeMin 40) and configure()'s clamp would preserve that as the + // starting target โ€” minting a storm of soon-expired tokens at every + // boot. With no explicit opts, defer sizing to the first configure(). + const hasOpts = Object.keys(opts).length > 0; + this.opts = resolvePoolOpts(opts); + this.effectiveTarget = hasOpts ? this.opts.poolSizeMin : 0; + // Seed idle clock at startup so a no-traffic proxy decays to idleFloor + // instead of solving 40-60 tokens forever (lastTakeAt=0 disabled decay). + this.lastTakeAt = Date.now(); + this.certifyIds = new CertifyIdRegistry(this.opts.tokenTtlMs); + this.initGovernor(opts); + setCaptchaSolverConcurrency(this.opts.solveConcurrency); + } + + configure(opts: CaptchaPoolOptions): void { + this.opts = resolvePoolOpts({ ...this.opts, ...opts }); + this.certifyIds.setTtlMs(this.opts.tokenTtlMs); + this.effectiveTarget = Math.max( + this.opts.poolSizeMin, + Math.min(this.effectiveTarget, this.opts.poolSizeMax), + ); + this.initGovernor(opts); + // Propagate the resolved concurrency to the solver daemon โ€” the + // import-time constructor runs before config load and would otherwise + // leave the daemon at its fallback (8) instead of the configured value. + setCaptchaSolverConcurrency(this.opts.solveConcurrency); + this.trimToTarget(); + } + + stats(): { + ready: number; + target: number; + min: number; + max: number; + activeSolves: number; + solverWorkers: number; + cpu?: CpuGovernorSnapshot; + } { + this.pruneExpired(); + return { + ready: this.tokens.length, + target: this.effectiveTarget, + min: this.opts.poolSizeMin, + max: this.opts.poolSizeMax, + activeSolves: this.activeSolves, + solverWorkers: captchaSolverConcurrency(), + cpu: this.governor?.enabled ? this.governor.snapshot() : undefined, + }; + } + + invalidate(): void { + this.tokens = []; + this.certifyIds.clear(); + this.pausedUntil = Date.now() + this.opts.staggerMs; + } + + startBackgroundRefill(cfg: CaptchaConfig): void { + this.cfg = cfg; + this.stopBackgroundRefill(); + this.governor?.start(); + void this.refill({ urgent: false }); + this.refillTimer = setInterval(() => { + void this.refill({ urgent: false }); + }, this.opts.refillIntervalMs); + } + + stopBackgroundRefill(): void { + this.governor?.stop(); + if (this.refillTimer) { + clearInterval(this.refillTimer); + this.refillTimer = null; + } + } + + async takeToken(cfg: CaptchaConfig): Promise { + this.cfg = cfg; + + const readyBefore = this.tokens.length; + const token = this.popFresh(); + if (token) { + this.onTokenTaken(false, readyBefore - 1); + void this.refill({ urgent: true }); + return token; + } + + this.onTokenTaken(true, 0); + // Re-size immediately from current demand (this take is already in the + // window) so an empty-pool arrival widens the buffer right away. + this.effectiveTarget = Math.max(this.effectiveTarget, this.computeActiveTarget()); + let param: string; + try { + // Overall deadline for the racing chain: during mint storms a racer can + // grind through its retry budget (~30-45s) โ€” cap the client-facing wait + // and let the background waves finish the job instead. + const raceDeadlineMs = Number(process.env.CAPTCHA_SOLVE_RACE_DEADLINE_MS || 25_000); + param = await Promise.race([ + this.solveRaced(cfg), + new Promise((_, rej) => + setTimeout( + () => rej(new Error(`captcha take deadline (${raceDeadlineMs}ms)`)), + Math.max(1_000, raceDeadlineMs), + ), + ), + ]); + } catch (err) { + // Mints fail in clusters (pe-stall storms, F008 velocity). Background + // refill waves keep retrying โ€” give them a short window to land a + // token before surfacing a failure to the client. This converts most + // storm-window 503s into slower successes. + const graceMs = Number(process.env.CAPTCHA_TAKE_GRACE_MS || 10_000); + const deadline = Date.now() + Math.max(0, graceMs); + while (Date.now() < deadline) { + await new Promise((r) => setTimeout(r, 400)); + const token = this.popFresh(); + if (token) { + this.markParamIssued(token); + void this.refill({ urgent: true }); + return token; + } + } + throw err; + } + this.markParamIssued(param); + void this.refill({ urgent: true }); + return param; + } + + async prefill(cfg: CaptchaConfig, count?: number): Promise { + this.cfg = cfg; + const target = Math.min(count ?? this.effectiveTarget, this.effectiveTarget); + while (this.tokens.length + this.activeSolves < target) { + const need = target - this.tokens.length - this.activeSolves; + if (need <= 0) break; + const concurrency = this.governor?.enabled + ? this.governor.backgroundConcurrency(this.tokens.length) + : this.opts.solveConcurrency; + await this.solveBatch(cfg, need, Math.max(1, concurrency)); + } + } + + requestUrgentRefill(): void { + void this.refill({ urgent: true }); + } + + private poolHasCertifyId(certifyId: string): boolean { + return this.tokens.some((t) => t.certifyId === certifyId); + } + + private isDuplicateParam(param: string): boolean { + const certifyId = parseCertifyId(param); + if (!certifyId) return false; + return this.certifyIds.has(certifyId) || this.poolHasCertifyId(certifyId); + } + + private markParamIssued(param: string): void { + const certifyId = parseCertifyId(param); + if (certifyId) this.certifyIds.add(certifyId); + } + + private popFresh(): string | null { + this.pruneExpired(); + while (this.tokens.length > 0) { + const entry = this.tokens.pop()!; + if (entry.certifyId && this.certifyIds.has(entry.certifyId)) continue; + this.markParamIssued(entry.param); + return entry.param; + } + return null; + } + + private pushToken(param: string): void { + this.pruneExpired(); + if (this.tokens.length >= this.effectiveTarget) return; + const certifyId = parseCertifyId(param); + if (certifyId && (this.certifyIds.has(certifyId) || this.poolHasCertifyId(certifyId))) { + return; + } + this.tokens.push({ param, cachedAt: Date.now(), certifyId }); + } + + private pruneExpired(): void { + const now = Date.now(); + this.tokens = this.tokens.filter((t) => now - t.cachedAt < this.opts.tokenTtlMs); + } + + private deficit(): number { + this.pruneExpired(); + return Math.max(0, this.effectiveTarget - this.tokens.length - this.activeSolves); + } + + private pruneTakeWindow(): void { + const cutoff = Date.now() - TAKE_RATE_WINDOW_MS; + this.takeTimestamps = this.takeTimestamps.filter((t) => t > cutoff); + } + + private demandTarget(): number { + this.pruneTakeWindow(); + if (this.takeTimestamps.length === 0) return this.opts.poolSizeMin; + const ratePerSec = this.takeTimestamps.length / (TAKE_RATE_WINDOW_MS / 1000); + const ttlSec = this.opts.tokenTtlMs / 1000; + return Math.ceil(ratePerSec * ttlSec * 1.25); + } + + /** + * Target while traffic is recent: measured demand (take rate ร— TTL ร— + * margin) plus one token of arrival-jitter headroom, floored at + * poolSizeMin, capped by governor + poolSizeMax. This is the ONLY sizing + * authority while active โ€” bursts raise demand, quiet periods drain it. + */ + private computeActiveTarget(): number { + const demand = Math.max(this.demandTarget(), this.opts.poolSizeMin); + const raw = Math.ceil(demand * 1.25) + 1; + const governorMax = this.governor?.maxPoolTarget() ?? this.opts.poolSizeMax; + return Math.max( + this.currentFloor(), + Math.min(this.opts.poolSizeMax, governorMax, raw), + ); + } + + private onTokenTaken(wasEmpty: boolean, readyAfter: number): void { + this.lastTakeAt = Date.now(); + this.takeTimestamps.push(this.lastTakeAt); + this.pruneTakeWindow(); + this.wakeFromIdle(); + // Sizing is demand-driven via computeActiveTarget() on the next refill + // tick; takes only need to restore the active floor instantly. + } + + private maybeScaleDown(): void { + if (this.lastTakeAt === 0) return; + const idleMs = Date.now() - this.lastTakeAt; + if (idleMs < this.opts.scaleDownIdleMs) return; + + this.pruneTakeWindow(); + const recentTakes = this.takeTimestamps.filter((t) => t > Date.now() - 60_000).length; + if (recentTakes > 1) return; + + // Deep idle: decay the effective floor itself so Chromium workers and + // solve churn wind down โ€” first toward idleFloor, then to zero after + // deepIdleAfterMs (no background mints at all). Any token take snaps the + // floor back to full poolSizeMin. + const floor = this.currentFloor(); + if (this.effectiveTarget > floor) { + this.effectiveTarget = Math.max(floor, this.effectiveTarget - SCALE_UP_STEP); + this.trimToTarget(); + } + } + + /** + * Active traffic โ†’ poolSizeMin. After scaleDownIdleMs of no takes โ†’ + * idleFloor (keeper churn โ‰ˆ 1 mint/TTL). After deepIdleAfterMs โ†’ 0: + * background solving stops; the banked token still serves a wake-up take. + */ + private currentFloor(): number { + if (this.lastTakeAt === 0) return this.opts.poolSizeMin; + const idleMs = Date.now() - this.lastTakeAt; + if (idleMs >= this.opts.deepIdleAfterMs) return 0; + if (idleMs >= this.opts.scaleDownIdleMs) { + return Math.min(this.opts.idleFloor, this.opts.poolSizeMin); + } + return this.opts.poolSizeMin; + } + + /** Traffic returned: restore the full configured floor immediately. */ + private wakeFromIdle(): void { + if (this.effectiveTarget < this.opts.poolSizeMin) { + this.effectiveTarget = this.opts.poolSizeMin; + } + } + + private trimToTarget(): void { + this.pruneExpired(); + // Never trim the last banked token: it serves a wake-up take instantly + // (free TTFB) and expires naturally via pruneExpired. + const floor = Math.max(this.effectiveTarget, 1); + while (this.tokens.length > floor) { + this.tokens.shift(); + } + } + + private applyGovernorCaps(): void { + if (!this.governor?.enabled) return; + const governorMax = this.governor.maxPoolTarget(); + // Floor is idle-aware (idleFloor โ†’ 0 past deepIdleAfterMs) โ€” don't clamp + // it back up (that would refill forever during idle). + const floor = this.currentFloor(); + this.effectiveTarget = Math.max( + floor, + Math.min(this.effectiveTarget, governorMax, this.opts.poolSizeMax), + ); + } + + private async refill(opts: { urgent: boolean }): Promise { + if (!this.cfg) return; + // Refresh sizing BEFORE the in-flight guard: a fill batch with slow or + // stalling solves can hold refillInFlight for minutes, and freezing the + // target that whole time starves the buffer exactly when demand exists. + const idleDecay = + this.lastTakeAt > 0 && Date.now() - this.lastTakeAt >= this.opts.scaleDownIdleMs; + if (!idleDecay) { + this.effectiveTarget = this.computeActiveTarget(); + } else { + this.maybeScaleDown(); + } + + // Idle decay: drop the target toward the current floor (idleFloor โ†’ 0 + // past deepIdleAfterMs) and skip background solves while enough banked + // tokens remain. This is what stops mint churn at zero traffic. + if (!opts.urgent && idleDecay) { + if (this.tokens.length >= Math.max(this.currentFloor(), 1)) return; + } + + if (this.refillInFlight || Date.now() < this.pausedUntil) return; + + this.applyGovernorCaps(); + + const ready = this.tokens.length; + const concurrency = this.governor?.enabled + ? opts.urgent + ? Math.max(1, this.governor.backgroundConcurrency(ready) || this.governor.snapshot().concurrency) + : this.governor.backgroundConcurrency(ready) + : this.opts.solveConcurrency; + + if (!opts.urgent && concurrency === 0 && ready >= this.opts.poolSizeMin) { + return; + } + + const need = this.deficit(); + if (need <= 0) return; + + this.refillInFlight = true; + try { + await this.solveBatch(this.cfg, need, Math.max(1, concurrency)); + } finally { + this.refillInFlight = false; + } + } + + /** Fire up to `need` solves in parallel waves of solveConcurrency. */ + private async solveBatch(cfg: CaptchaConfig, need: number, concurrency = this.opts.solveConcurrency): Promise { + let remaining = need; + while (remaining > 0 && this.tokens.length + this.activeSolves < this.effectiveTarget) { + const wave = Math.min(remaining, concurrency, this.deficit()); + if (wave <= 0) break; + if (this.opts.staggerMs > 0) await this.waitForStagger(); + const results = await Promise.allSettled( + Array.from({ length: wave }, () => this.solveOne(cfg)), + ); + for (const r of results) { + if (r.status === "fulfilled") { + this.pushToken(r.value); + } else { + console.warn("[captcha-pool] parallel solve failed:", r.reason); + } + } + remaining -= wave; + if (results.every((r) => r.status === "rejected")) break; + } + } + + private async waitForStagger(): Promise { + const elapsed = Date.now() - this.lastSolveAt; + const wait = this.opts.staggerMs - elapsed; + if (wait > 0) { + await new Promise((r) => setTimeout(r, wait)); + } + } + + private noteMintFailure(reason: string): void { + const now = Date.now(); + this.mintFailures.push(now); + const cutoff = now - 360_000; + this.mintFailures = this.mintFailures.filter((t) => t > cutoff); + this.maybeFireMintStormReset(reason); + } + + private noteMintSuccess(): void { + const now = Date.now(); + this.mintSuccesses.push(now); + const cutoff = now - 360_000; + this.mintSuccesses = this.mintSuccesses.filter((t) => t > cutoff); + } + + /** Velocity/IP flagging signature: many failed mints in the last 5 min + * while nothing succeeded in the last 3. Fires the telegram IP reset at + * most once per cooldown โ€” requestCaptchaIpResetSync dedupes further. */ + private maybeFireMintStormReset(latestReason: string): void { + const now = Date.now(); + const fails = this.mintFailures.filter((t) => t > now - 300_000).length; + const succs = this.mintSuccesses.filter((t) => t > now - 180_000).length; + if (fails < 8 || succs > 0) return; + if (now - this.lastStormResetAt < 12 * 60_000) return; + this.lastStormResetAt = now; + console.warn( + `[captcha] mint storm detected (${fails} failures/5min, ${succs} successes/3min; latest: ${latestReason.slice(0, 120)}) -> requesting IP reset`, + ); + try { + this.opts.onCaptchaIpBlock?.(`mint storm: ${fails} failed mints in 5min`); + } catch { + // callback is best-effort; never break the pool + } + } + + private async solveFresh(cfg: CaptchaConfig): Promise { + this.activeSolves += 1; + this.lastSolveAt = Date.now(); + try { + let lastErr: string | null = null; + let sawIpBlock = false; + for (let attempt = 1; attempt <= this.opts.solveRetries; attempt += 1) { + try { + const param = await runCaptchaSolve(cfg.sceneId, cfg.region, cfg.prefix); + if (!param) { + lastErr = "solver returned empty"; + continue; + } + if (this.isDuplicateParam(param)) { + lastErr = `duplicate certifyId ${parseCertifyId(param) ?? "?"}`; + continue; + } + this.noteMintSuccess(); + return param; + } catch (err) { + lastErr = err instanceof Error ? err.message : String(err); + if (isCaptchaDuplicateError(lastErr)) { + lastErr = `duplicate certifyId (F008)`; + } else if (isCaptchaIpBlockError(lastErr)) { + sawIpBlock = true; + } + this.noteMintFailure(lastErr); + } + } + // All retries failed. If any failure was an IP-level block, ask the + // caller to rotate the egress (Telegram network reset) so the next + // mint has a fresh IP instead of being stuck unable to mint. + if (sawIpBlock && this.opts.onCaptchaIpBlock) { + try { + this.opts.onCaptchaIpBlock(lastErr ?? "captcha ip block"); + } catch (_) { + // callback is best-effort; never let it break the pool + } + } + throw new Error(`captcha failed after ${this.opts.solveRetries} attempts: ${lastErr ?? "unknown"}`); + } finally { + this.activeSolves -= 1; + } + } + + private async solveOne(cfg: CaptchaConfig): Promise { + return this.solveFresh(cfg); + } + + /** + * Empty-pool serve: race up to `emptyTakeRace` solves in parallel and + * resolve with the first success so the client waits for one mint, not a + * sequential retry chain. Extra successes are banked into the pool instead + * of being wasted; the race only rejects when every racer fails. + */ + private solveRaced(cfg: CaptchaConfig): Promise { + const racers = Math.max(1, Math.min(this.opts.emptyTakeRace, this.opts.solveConcurrency)); + if (racers <= 1) return this.solveFresh(cfg); + + return new Promise((resolve, reject) => { + let pending = racers; + let served = false; + let lastErr: unknown = null; + for (let i = 0; i < racers; i += 1) { + this.solveFresh(cfg).then( + (param) => { + if (served) { + // Lost the race but minted a valid token โ€” bank it. + this.pushToken(param); + } else { + served = true; + resolve(param); + } + }, + (err) => { + lastErr = err ?? lastErr; + }, + ).finally(() => { + pending -= 1; + if (pending === 0 && !served) { + reject( + lastErr instanceof Error + ? lastErr + : new Error(String(lastErr ?? "captcha race failed")), + ); + } + }); + } + }); + } + + private initGovernor(opts: CaptchaPoolOptions): void { + const cfg = resolveCpuGovernorConfig({ + poolSizeMin: this.opts.poolSizeMin, + poolSizeMax: this.opts.poolSizeMax, + solveConcurrency: this.opts.solveConcurrency, + cpuLimitPercent: opts.cpuLimitPercent, + cpuGovernorIntervalSec: opts.cpuGovernorIntervalSec, + }); + if (!this.governor) { + this.governor = new CaptchaCpuGovernor(cfg); + } else { + this.governor.configure(cfg); + } + } +} + +export interface CaptchaConfig { + enabled: boolean; + prefix: string; + sceneId: string; + region: string; +} + +const pool = new CaptchaTokenPool(); + +export function configureCaptchaPool(opts: CaptchaPoolOptions): void { + pool.configure(opts); +} + +export function getCaptchaPoolStats(): { + ready: number; + target: number; + min?: number; + max?: number; + activeSolves: number; + solverWorkers?: number; +} { + return pool.stats(); +} + +export function stopCaptchaPool(): void { + pool.stopBackgroundRefill(); + shutdownCaptchaSolver(); +} + +export async function takeCaptchaToken(cfg: CaptchaConfig): Promise { + if (!cfg.enabled || !cfg.prefix || !cfg.sceneId) { + throw new Error("Captcha config unavailable from ZCode API"); + } + return pool.takeToken(cfg); +} + +export function startCaptchaPoolRefill(cfg: CaptchaConfig): void { + if (!cfg.enabled || !cfg.prefix || !cfg.sceneId) return; + pool.startBackgroundRefill(cfg); +} + +export async function prefillCaptchaPool(cfg: CaptchaConfig, count?: number): Promise { + if (!cfg.enabled || !cfg.prefix || !cfg.sceneId) return; + await pool.prefill(cfg, count); +} + +export function urgentCaptchaRefill(): void { + pool.requestUrgentRefill(); +} diff --git a/src/proxy/captcha-retry.ts b/src/proxy/captcha-retry.ts new file mode 100644 index 0000000000000000000000000000000000000000..27933a6cdc24dc13090c28708230d4be380a4574 --- /dev/null +++ b/src/proxy/captcha-retry.ts @@ -0,0 +1,186 @@ +/** + * Shared captcha (3007) challenge detection + single-retry flow. + * + * The challenge arrives in two variants (observed 2026-08-29, PR #38): + * 1. response-header variant โ€” `x-aliyun-captcha-verify-param` set on a + * non-2xx response (`captcha.detectCaptchaChallenge`); + * 2. in-body variant โ€” HTTP 400 with `{"code":3007,...}` in the JSON body + * and no captcha header. + * + * Both the chat hot path (handler.ts) and /v1/responses (responses-handler.ts) + * used to hand-roll this detection and the re-solve/retry, and the copies had + * drifted (error mapping, peek handling). This module is the unified seam. + * + * Runtime-import discipline: only TYPE imports from ./captcha.js โ€” the real + * module (which drags in the happy-dom solver) is lazily loaded by the + * callers and passed in as a value, so non-start-plan processes never pay + * its startup cost. + */ +import type * as CaptchaExports from "./captcha.js"; + +/** Shape the callers pass in โ€” satisfied by the real captcha module or test fakes. */ +export type CaptchaModuleLike = Pick; + +/** Magic strings of the in-body challenge, for both JSON spacing styles. */ +export const IN_BODY_CHALLENGE_MARKERS = ['"code":3007', '"code": 3007'] as const; + +/** Bound on how many raw (possibly compressed) body bytes a challenge peek reads. */ +export const MAX_CHALLENGE_PEEK_BYTES = 64 * 1024; + +/** Bound on decompressed sniff output โ€” error bodies are small; more is waste. */ +const MAX_SNIFF_INFLATED_BYTES = 256 * 1024; + +/** + * Peek (bounded) the body of a non-ok, non-SSE response and detect the + * in-body 3007 challenge. The response stays consumable for the error path: + * the peek reads a CLONE, so the original body is untouched. + * + * Covers both passthrough transports where the body may arrive still + * gzip-compressed (Bun fetch `decompress:false`, ordered raw-TCP): when the + * response advertises `content-encoding: gzip|x-gzip`, the peek inflates + * before sniffing. On a runtime that already auto-inflated the body while + * keeping the header (Node undici), inflation fails and the raw bytes are + * sniffed as-is. + */ +export async function detectInBodyChallenge(resp: Response): Promise { + if (resp.ok) return false; + const ctype = resp.headers.get("content-type") ?? ""; + if (ctype.includes("text/event-stream")) return false; + let bytes: Uint8Array; + try { + bytes = await peekBodyBytes(resp, MAX_CHALLENGE_PEEK_BYTES); + } catch { + return false; + } + if (bytes.byteLength === 0) return false; + const text = await decodeMaybeGzip(bytes, resp.headers.get("content-encoding")); + return IN_BODY_CHALLENGE_MARKERS.some((marker) => text.includes(marker)); +} + +/** Unified challenge check: response-header variant first, then in-body peek. */ +export async function isCaptchaChallenged( + resp: Response, + captcha: Pick, +): Promise { + if (captcha.detectCaptchaChallenge(resp) !== null) return true; + return detectInBodyChallenge(resp); +} + +export interface CaptchaRetryArgs { + captcha: CaptchaModuleLike; + appVersion: string; + /** The challenged response; its body is cancelled before the retry. */ + challengedResp: Response; + /** Dispatch the retry. Receives the fresh captcha headers; must return the upstream Response. */ + solveAndRetry: (retryHeaders: Record) => Promise; + /** + * Error mapping (unified contract, mirrors handler.ts's correct shape): + * "solver" โ†’ the re-solve (getCaptchaToken) failed + * "dispatch" โ†’ the retry dispatch failed at the network level + */ + mapError: (err: Error, phase: "solver" | "dispatch") => Response; + /** Optional debug line sink. */ + debug?: (message: string) => void; +} + +/** + * Shared single-retry flow for a detected captcha challenge: cancel the old + * body, re-solve a fresh token, rebuild + re-dispatch ONCE (the challenged + * token was already consumed by this request). Never loops. + * + * The caller MUST return `ok:false` responses directly to the client โ€” they + * are already fully-formed error responses (solver โ†’ 503 captcha_solver_failed, + * dispatch โ†’ 502 upstream_unreachable); feeding them back through the + * upstream `!ok` branch would wrap the error body a second time. + */ +export async function retryOnCaptchaChallenge(args: CaptchaRetryArgs): Promise<{ ok: true; resp: Response } | { ok: false; resp: Response }> { + const { captcha, appVersion, challengedResp, solveAndRetry, mapError, debug } = args; + debug?.("captcha challenge โ€” re-solving and retrying once"); + try { + await challengedResp.body?.cancel(); + } catch { + // already drained/cancelled + } + let fresh: { verifyParam: string; region: string }; + try { + fresh = await captcha.getCaptchaToken(appVersion); + } catch (err) { + return { ok: false, resp: mapError(err as Error, "solver") }; + } + const retryHeaders: Record = { + [captcha.RETRY_HEADERS.PARAM]: fresh.verifyParam, + [captcha.RETRY_HEADERS.REGION]: fresh.region, + }; + try { + return { ok: true, resp: await solveAndRetry(retryHeaders) }; + } catch (err) { + return { ok: false, resp: mapError(err as Error, "dispatch") }; + } +} + +/** Read at most `limit` bytes from a clone of the response body. */ +async function peekBodyBytes(resp: Response, limit: number): Promise { + const body = resp.clone().body; + if (!body) return new Uint8Array(0); + const reader = body.getReader(); + const parts: Uint8Array[] = []; + let total = 0; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) break; + parts.push(value); + total += value.byteLength; + if (total >= limit) break; + } + } finally { + reader.cancel().catch(() => {}); + reader.releaseLock?.(); + } + const all = Buffer.concat(parts); + return all.byteLength > limit ? all.subarray(0, limit) : all; +} + +/** + * Decode sniff bytes, inflating first when the response is labeled gzip. + * TextDecoder is non-fatal, so invalid UTF-8 degrades to replacement chars โ€” + * the ASCII magic strings still match. + */ +async function decodeMaybeGzip(bytes: Uint8Array, encodingHeader: string | null): Promise { + const enc = encodingHeader?.toLowerCase().trim() ?? ""; + if (enc === "gzip" || enc === "x-gzip") { + try { + return new TextDecoder().decode(await inflateBounded(bytes)); + } catch { + // Runtime already inflated the body while keeping the header (Node + // undici) โ€” sniff the bytes as-is. + } + } + return new TextDecoder().decode(bytes); +} + +async function inflateBounded(bytes: Uint8Array): Promise { + const gunzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair; + const source = new ReadableStream({ + start(controller) { + controller.enqueue(bytes); + controller.close(); + }, + }); + const reader = source.pipeThrough(gunzip).getReader(); + const parts: Uint8Array[] = []; + let total = 0; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) break; + parts.push(value); + total += value.byteLength; + if (total >= MAX_SNIFF_INFLATED_BYTES) break; + } + } finally { + reader.cancel().catch(() => {}); + reader.releaseLock?.(); + } + return Buffer.concat(parts); +} diff --git a/src/proxy/captcha-solver.ts b/src/proxy/captcha-solver.ts new file mode 100644 index 0000000000000000000000000000000000000000..5e631ced9f53ea554f28d5a4f8222c9612157bed --- /dev/null +++ b/src/proxy/captcha-solver.ts @@ -0,0 +1,30 @@ +/** + * Solver backend dispatch โ€” fully in-process, self-contained. + * + * Backend (ZCODE_CAPTCHA_BACKEND): "happy" (default) โ€” the happy-dom solver + * in src/proxy/captcha-happy.ts. Runs inside the Bun process; bundled into + * the single-file release binary by `bun build --compile`. No external + * Node.js, no browser. (The historical jsdom and Node-daemon/playwright + * backends have been removed.) + */ +const BACKEND = process.env.ZCODE_CAPTCHA_BACKEND?.trim().toLowerCase() || "happy"; + +let happyMod: typeof import("./captcha-happy.js") | null = null; + +export async function runCaptchaSolve(scene: string, region: string, prefix: string): Promise { + if (BACKEND !== "happy") { + throw new Error(`captcha backend "${BACKEND}" is not available; use ZCODE_CAPTCHA_BACKEND=happy`); + } + if (!happyMod) happyMod = await import("./captcha-happy.js"); + return happyMod.solveTraceless({ scene, region, prefix }); +} + +/** In-process solving needs no worker pool management โ€” kept for the pool API. */ +export function setCaptchaSolverConcurrency(_n: number): void {} + +/** In-process solving needs no worker pool management โ€” kept for the pool API. */ +export function shutdownCaptchaSolver(): void {} + +export function captchaSolverConcurrency(): number { + return Number(process.env.CAPTCHA_DAEMON_CONCURRENCY || 4); +} diff --git a/src/proxy/captcha-token.ts b/src/proxy/captcha-token.ts new file mode 100644 index 0000000000000000000000000000000000000000..450dcc30ba73b5978532f2ce89827f95de4dd58b --- /dev/null +++ b/src/proxy/captcha-token.ts @@ -0,0 +1,32 @@ +/** Decode certifyId from a base64 Aliyun verify-param blob. */ +export function parseCertifyId(param: string): string | null { + try { + const json = JSON.parse(Buffer.from(param, "base64").toString("utf8")) as { + certifyId?: unknown; + }; + return typeof json.certifyId === "string" && json.certifyId.length > 0 + ? json.certifyId + : null; + } catch { + return null; + } +} + +/** Aliyun F008 โ€” certifyId / verify token already consumed or duplicated. */ +export function isCaptchaDuplicateError(message: string): boolean { + return /F008|"verifyCode"\s*:\s*"F008"/i.test(message); +} + +/** + * Aliyun IP-block family: no-captcha possible because the mint IP has been + * flagged ("too many captcha requests"). Distinct from F008 (duplicate + * certifyId) and from pe-VM stalls/timeouts, which are local-side issues that + * a retry can fix without rotating the IP. + */ +const CAPTCHA_IP_BLOCK_RE = + /too many|request was denied|risk control|frequent|rate\s*limit|exceeded.*(?:request|limit)|ip\s*suspicious|denied due to|retry later/i; + +export function isCaptchaIpBlockError(message: string): boolean { + if (isCaptchaDuplicateError(message)) return false; + return CAPTCHA_IP_BLOCK_RE.test(message); +} diff --git a/src/proxy/captcha.ts b/src/proxy/captcha.ts new file mode 100644 index 0000000000000000000000000000000000000000..4013ec0905c6acd06167389cc89ee906464e78ce --- /dev/null +++ b/src/proxy/captcha.ts @@ -0,0 +1,101 @@ +/** + * Aliyun Captcha V3 front-end โ€” config fetch + pre-solved token pool. + * + * Solving itself lives in captcha-happy.ts (in-process happy-dom solver, + * production-proven, self-contained: bundled into the single-file release + * binary โ€” no external Node.js, no browser, no jsdom). Tokens are minted + * into a pool (captcha-pool.ts); requests take an already-solved token + * (sub-ms) while background refills keep the pool warm โ€” the hot path + * never waits on a solve. + * + * Fingerprint stability: the happy-dom solver's polyfill/guest-patch values + * are deterministic and STABLE (never randomized) โ€” Aliyun's risk engine + * correlates fingerprint stability across requests; randomizing per-solve + * flags it as `verifyCode: F001`. See captcha-happy.ts. + */ +import { shutdownCaptchaSolver } from "./captcha-solver.js"; +import { + configureCaptchaPool, + getCaptchaPoolStats, + prefillCaptchaPool, + takeCaptchaToken, + startCaptchaPoolRefill, + stopCaptchaPool, + urgentCaptchaRefill, + type CaptchaConfig, +} from "./captcha-pool.js"; + +const CAPTCHA_HEADER = "x-aliyun-captcha-verify-param"; +const REGION_HEADER = "x-aliyun-captcha-verify-region"; +const CONFIGS_API = "https://zcode.z.ai/api/v1/client/configs"; + +interface FetchedCaptchaConfig { enabled: boolean; prefix: string; sceneId: string; region: string; } +let cachedConfig: { value: FetchedCaptchaConfig | null; expiresAt: number } = { value: null, expiresAt: 0 }; + +export function detectCaptchaChallenge(resp: Response): string | null { + const v = resp.headers.get(CAPTCHA_HEADER); + return v && v.trim().length > 0 ? v.trim() : null; +} + + +async function fetchCaptchaConfig(appVersion: string): Promise { + if (cachedConfig.value && cachedConfig.expiresAt > Date.now()) return cachedConfig.value; + try { + const resp = await fetch(`${CONFIGS_API}?app_version=${encodeURIComponent(appVersion)}&platform=win32-x64`); + const json = (await resp.json()) as { data?: { configs?: { captcha?: FetchedCaptchaConfig } } }; + const cfg = json?.data?.configs?.captcha ?? null; + cachedConfig = { value: cfg, expiresAt: Date.now() + 60000 }; + return cfg; + } catch { return null; } +} + +/** + * Solve backend: in-process happy-dom (captcha-happy.ts) served through the + * pre-solved token pool. Retries are handled inside the pool + * (ZCODE_CAPTCHA_RETRIES attempts with a fresh solve per retry). + */ +export async function getCaptchaToken(appVersion: string): Promise<{ verifyParam: string; region: string }> { + const cfg = await fetchCaptchaConfig(appVersion); + if (!cfg || !cfg.enabled || !cfg.prefix || !cfg.sceneId) throw new Error("Captcha config unavailable"); + // Pre-solved token pool: requests take an already-minted token (sub-ms) + // while background solves refill โ€” the hot path never waits on a solve. + const verifyParam = await takeCaptchaToken(cfg); + return { verifyParam, region: cfg.region }; +} + +export function shutdownCaptcha(): void { + try { shutdownCaptchaSolver(); } catch {} + try { stopCaptchaPool(); } catch {} +} + +/** + * Start background pre-solving of the token pool (happy backend). + * Warms only the idle minimum; the pool grows on demand with traffic. + */ +export async function startCaptchaPool(appVersion: string): Promise { + const cfg = await fetchCaptchaConfig(appVersion); + if (!cfg || !cfg.enabled) return; + // Size the pool before prefill: the module-level pool defers sizing to the + // first configure() so a cold boot doesn't mint a storm of soon-expired + // tokens. CAPTCHA_POOL_MIN/CAPTCHA_POOL_MAX env vars override the defaults. + const min = Number(process.env.CAPTCHA_POOL_MIN || 20); + const max = Number(process.env.CAPTCHA_POOL_MAX || Math.max(min * 6, 120)); + configureCaptchaPool({ poolSizeMin: min, poolSizeMax: max }); + startCaptchaPoolRefill(cfg as CaptchaConfig); + await prefillCaptchaPool(cfg as CaptchaConfig, min); +} + +/** Request an urgent refill burst (e.g. after a challenge/retry). */ +export function urgentCaptcha(): void { + urgentCaptchaRefill(); +} + +export function captchaPoolStats(): { ready: number; target: number; activeSolves: number } { + return getCaptchaPoolStats(); +} + +export function configureCaptchaSolving(opts: Parameters[0]): void { + configureCaptchaPool(opts); +} + +export const RETRY_HEADERS = { PARAM: CAPTCHA_HEADER, REGION: REGION_HEADER }; diff --git a/src/proxy/client-session.ts b/src/proxy/client-session.ts new file mode 100644 index 0000000000000000000000000000000000000000..aef6accca4e91da1b1580cfeb29a86343e6aa352 --- /dev/null +++ b/src/proxy/client-session.ts @@ -0,0 +1,264 @@ +/** + * Local client-session inference for cache-affinity experiments. + * + * The resolver stores only hashes and generated IDs. It deliberately avoids + * prompt markers, response mutation, and full prompt persistence. + */ +import nodeCrypto from "node:crypto"; +import type { Format } from "../translator/types.js"; +import type { ClientIdentityConfig } from "../config/types.js"; + +export type ClientSessionSource = "none" | "explicit" | "lineage"; +export type ClientSessionAction = "off" | "observe" | "enforce"; + +export interface ClientSessionResult { + source: ClientSessionSource; + action: ClientSessionAction; + confidence: number; + sessionId?: string; + upstreamSessionId?: string; + requestId?: string; + traceId?: string; + queryId?: string; +} + +interface StoredNode { + nodeHash: string; + sessionId: string; + upstreamSessionId: string; + lastSeenAt: number; +} + +interface CanonicalRequest { + model: string; + identity: unknown; + messages: unknown[]; +} + +interface ExplicitTraceContext { + requestId?: string; + traceId?: string; + queryId?: string; + sessionId?: string; +} + +export interface ClientSessionResolver { + resolve(req: Request, body: string | undefined, format: Format, model: string, config: ClientIdentityConfig): ClientSessionResult; +} + +export function createClientSessionResolver(now: () => number = () => Date.now()): ClientSessionResolver { + const nodes = new Map(); + const sessions = new Map(); + + function remember(nodeHash: string, session: StoredNode, config: ClientIdentityConfig): void { + const stored = { ...session, nodeHash, lastSeenAt: now() }; + nodes.set(nodeHash, stored); + sessions.set(stored.sessionId, stored); + prune(config); + } + + function prune(config: ClientIdentityConfig): void { + const cutoff = now() - config.ttlSeconds * 1000; + for (const [hash, node] of nodes.entries()) { + if (node.lastSeenAt < cutoff) nodes.delete(hash); + } + for (const [id, node] of sessions.entries()) { + if (node.lastSeenAt < cutoff) sessions.delete(id); + } + while (sessions.size > config.maxSessions) { + let oldestId = ""; + let oldestAt = Infinity; + for (const [id, node] of sessions.entries()) { + if (node.lastSeenAt < oldestAt) { + oldestAt = node.lastSeenAt; + oldestId = id; + } + } + if (!oldestId) break; + sessions.delete(oldestId); + for (const [hash, node] of nodes.entries()) { + if (node.sessionId === oldestId) nodes.delete(hash); + } + } + } + + function action(config: ClientIdentityConfig): ClientSessionAction { + return config.mode; + } + + return { + resolve(req, body, format, model, config) { + if (config.mode === "off") return { source: "none", action: "off", confidence: 0 }; + + prune(config); + const explicitTrace = requestTraceContext(req, body); + if (explicitTrace.sessionId) return explicitResult(explicitTrace, config); + + const canonical = canonicalize(body, format, model); + if (!canonical) { + if (hasTraceContext(explicitTrace)) return explicitResult(explicitTrace, config); + return { source: "none", action: action(config), confidence: 0 }; + } + + const nodeHash = hashJson(canonical.identity); + const existing = nodes.get(nodeHash); + if (existing) { + remember(nodeHash, existing, config); + return withTraceContext(result("lineage", action(config), existing, 0.95), explicitTrace); + } + + const parent = findLinearParent(canonical, nodes); + if (parent) { + remember(nodeHash, parent, config); + return withTraceContext(result("lineage", action(config), parent, 0.9), explicitTrace); + } + + const fresh = newSession(); + remember(nodeHash, fresh, config); + return withTraceContext(result("lineage", action(config), fresh, 0.75), explicitTrace); + }, + }; +} + +export const defaultClientSessionResolver = createClientSessionResolver(); + +function result(source: ClientSessionSource, action: ClientSessionAction, node: StoredNode, confidence: number): ClientSessionResult { + return { + source, + action, + confidence, + sessionId: node.sessionId, + upstreamSessionId: node.upstreamSessionId, + }; +} + +function requestTraceContext(req: Request, body: string | undefined): ExplicitTraceContext { + const bodyTrace = bodyMetadataTrace(body); + return { + requestId: firstHeader(req.headers, ["x-request-id"]) ?? bodyTrace.requestId, + traceId: firstHeader(req.headers, ["x-zcode-trace-id"]) ?? bodyTrace.traceId, + queryId: firstHeader(req.headers, ["x-query-id"]) ?? bodyTrace.queryId, + sessionId: firstHeader(req.headers, ["x-opencode-session", "x-claude-code-session-id", "x-session-id", "x-parent-session-id", "helicone-session-id"]) + ?? bodyTrace.sessionId, + }; +} + +function explicitResult(trace: ExplicitTraceContext, config: ClientIdentityConfig): ClientSessionResult { + return { + source: "explicit", + action: config.mode, + confidence: 1, + ...(trace.requestId ? { requestId: trace.requestId } : {}), + ...(trace.traceId ? { traceId: trace.traceId } : {}), + ...(trace.queryId ? { queryId: trace.queryId } : {}), + ...(trace.sessionId ? { sessionId: trace.sessionId, upstreamSessionId: trace.sessionId } : {}), + }; +} + +function withTraceContext(session: ClientSessionResult, trace: ExplicitTraceContext): ClientSessionResult { + if (!trace.requestId && !trace.traceId && !trace.queryId) return session; + return { + ...session, + ...(trace.requestId ? { requestId: trace.requestId } : {}), + ...(trace.traceId ? { traceId: trace.traceId } : {}), + ...(trace.queryId ? { queryId: trace.queryId } : {}), + }; +} + +function hasTraceContext(trace: ExplicitTraceContext): boolean { + return Boolean(trace.requestId || trace.traceId || trace.queryId || trace.sessionId); +} + +function firstHeader(headers: Headers, names: string[]): string | null { + for (const name of names) { + const value = headers.get(name); + if (value && value.trim()) return value.trim(); + } + return null; +} + +function bodyMetadataTrace(body: string | undefined): ExplicitTraceContext { + if (!body) return {}; + try { + const parsed = JSON.parse(body) as Record; + const metadata = parsed?.metadata as Record | undefined; + if (!metadata || typeof metadata !== "object") return {}; + return { + requestId: stringProperty(metadata, ["requestId", "request_id"]), + traceId: stringProperty(metadata, ["traceId", "trace_id"]), + queryId: stringProperty(metadata, ["queryId", "query_id"]), + sessionId: stringProperty(metadata, ["sessionId", "session_id", "conversationId", "conversation_id"]), + }; + } catch { + return {}; + } +} + +function stringProperty(obj: Record, names: string[]): string | undefined { + for (const name of names) { + const value = obj[name]; + if (typeof value === "string" && value.trim()) return value.trim(); + } + return undefined; +} + +function canonicalize(body: string | undefined, format: Format, fallbackModel: string): CanonicalRequest | null { + if (!body) return null; + let parsed: Record; + try { + parsed = JSON.parse(body); + } catch { + return null; + } + if (!parsed || typeof parsed !== "object") return null; + + const model = typeof parsed.model === "string" ? parsed.model : fallbackModel; + const messages = Array.isArray(parsed.messages) ? parsed.messages : []; + if (messages.length === 0) return null; + + const identity = { + format, + model, + system: parsed.system, + developer: messages.filter((m: unknown) => typeof m === "object" && m !== null && (m as Record).role === "developer"), + tools: parsed.tools, + tool_choice: parsed.tool_choice, + messages, + }; + return { model, identity, messages }; +} + +function findLinearParent(canonical: CanonicalRequest, nodes: Map): StoredNode | null { + if (canonical.messages.length < 3) return null; + const prefix = { + ...(canonical.identity as Record), + messages: canonical.messages.slice(0, -2), + }; + if ((prefix.messages as unknown[]).length === 0) return null; + return nodes.get(hashJson(prefix)) ?? null; +} + +function newSession(): StoredNode { + const upstreamSessionId = crypto.randomUUID(); + return { + nodeHash: "", + sessionId: `ses_${upstreamSessionId.replace(/-/g, "").slice(0, 12)}`, + upstreamSessionId, + lastSeenAt: Date.now(), + }; +} + +function hashJson(value: unknown): string { + return hashString(stableStringify(value)); +} + +function hashString(value: string): string { + return nodeCrypto.createHash("sha256").update(value, "utf-8").digest("hex"); +} + +function stableStringify(value: unknown): string { + if (value === null || typeof value !== "object") return JSON.stringify(value); + if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`; + const obj = value as Record; + return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`; +} diff --git a/src/proxy/client-signing.ts b/src/proxy/client-signing.ts new file mode 100644 index 0000000000000000000000000000000000000000..9852c60cdac360b65281a56b0b28133ed61fa838 --- /dev/null +++ b/src/proxy/client-signing.ts @@ -0,0 +1,595 @@ +/** + * Client Request Signing V4 โ€” mirrors the ZCode 3.9.1 `ClientRequestSigningV4Signer`. + * + * Per-request Ed25519 signatures + proof-of-work over coding-plan traffic. + * Everything here is fail-open, matching the client: gate disabled/unreachable + * โ†’ unsigned; handshake failure โ†’ unsigned; two consecutive 401 VERIFY_* + * rejections โ†’ permanent bypass for that (origin, credential) pair. + * + * Start-plan gateway and off-peak LLM paths are permanently exempt (the + * client's `isUnsignedModelRequestPath` set). Credentials without the + * `{apiKeyId}.{apiKeySecret}` separator (legacy bigmodel keys issued before + * the copy endpoint returned secretKeys) are silently skipped โ€” the client + * hard-throws there; skipping is a deliberate fail-open deviation. Both + * providers now issue two-part keys, which sign normally. + * + * Full protocol: `_reverse/NOTEPAD.md` "Client Request Signing V4". + */ +import type { UpstreamHeaderPair } from "./upstream.js"; +import { buildIdentityHeaders, identityCacheKey } from "./identity.js"; +import type { ProxyIdentity } from "../config/types.js"; + +const DEFAULT_ORIGIN = "https://zcode.z.ai"; +const GATE_PATH = "/api/v1/agent/configs"; +const HANDSHAKE_PATH = "/api/paas/c1f3a7e2/v2/client"; +const APP_ID = "zcode"; +const POW_BITS = 8; +const NONCE_BYTES = 16; +const POW_NONCE_BYTES = 12; +const KDF_SALT = "WD_CLIENT_SIGN_KDF_SALT"; +const KDF_INFO_HMAC = "getSignKey_hmac"; +const KDF_INFO_ED25519 = "ed25519_priv"; +const HANDSHAKE_METHOD = "get_sign_key"; +const GATE_TTL_MS = 3_600_000; +/** Negative-cache cooldown after a gate fetch network failure. */ +const GATE_FAILURE_COOLDOWN_MS = 60_000; +/** Negative-cache cooldown for "unavailable" gate responses (non-2xx / bad envelope). */ +const GATE_UNAVAILABLE_COOLDOWN_MS = 30_000; +const GATE_TIMEOUT_MS = 15_000; +const HANDSHAKE_TIMEOUT_MS = 10_000; +const VERIFY_SIGNATURE_INVALID = "VERIFY_SIGNATURE_INVALID"; +const VERIFY_APIKEY_EXPIRED = "VERIFY_APIKEY_EXPIRED"; + +/** Paths the client never signs (decoded, trailing-slash-stripped). */ +const UNSIGNED_PATHS = new Set([ + "/api/v1/zcode-plan/anthropic/v1/messages", + "/api/v1/zcode-plan/chat/completions", + "/api/v1/off-peak/anthropic/v1/messages", +]); + +const SIGNING_HEADER_NAMES = new Set([ + "x-client-ts", + "x-client-version", + "x-client-sig", + "x-client-nonce", + "x-app-id", + "x-client-pow", + "x-client-sign-verified", +]); + +export interface SigningCredential { + credential: string; + appVersion: string; +} + +export interface SignOutcome { + pairs: UpstreamHeaderPair[]; + signed: boolean; +} + +interface ParsedCredential { + apiKeyId: string; + apiKeySecret: string; +} + +interface SignerState { + gateEnabled: boolean; + gateExpiresAt: number; + gateNegUntil: number; + gatePromise?: Promise; + privKey?: CryptoKey; + handshake?: Promise; + epoch: number; + bypass: boolean; +} + +const encoder = new TextEncoder(); + +type Bytes = Uint8Array; + +function encodeUtf8(value: string): Bytes { + const bytes = encoder.encode(value); + const out = new Uint8Array(bytes.byteLength); + out.set(bytes); + return out; +} + +function bytesToBase64(bytes: Uint8Array): string { + let binary = ""; + for (const b of bytes) binary += String.fromCharCode(b); + return btoa(binary); +} + +function bytesToHex(bytes: Uint8Array): string { + return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""); +} + +function randomHex(byteCount: number): string { + return bytesToHex(crypto.getRandomValues(new Uint8Array(byteCount))); +} + +function base64ToBytes(value: string): Bytes { + if (!value || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) { + throw new Error("invalid base64"); + } + const binary = atob(value); + const out = new Uint8Array(binary.length); + for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i); + return out; +} + +async function hkdfBytes(secret: string, info: string): Promise { + const key = await crypto.subtle.importKey("raw", encodeUtf8(secret), "HKDF", false, ["deriveBits"]); + return new Uint8Array(await crypto.subtle.deriveBits( + { name: "HKDF", hash: "SHA-256", salt: encodeUtf8(KDF_SALT), info: encodeUtf8(info) }, + key, + 256, + )); +} + +async function handshakeSignature(secret: string, message: string): Promise { + const bits = await hkdfBytes(secret, KDF_INFO_HMAC); + try { + const key = await crypto.subtle.importKey("raw", bits, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]); + const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, encodeUtf8(message))); + try { + return bytesToBase64(mac); + } finally { + mac.fill(0); + } + } finally { + bits.fill(0); + } +} + +async function decryptSigningPrivateKey(apiKeyId: string, secret: string, privateCipher: string): Promise { + const cipher = base64ToBytes(privateCipher); + if (cipher.byteLength <= 12 + 16) throw new Error("privateCipher is too short"); + const aesKeyBits = await hkdfBytes(secret, KDF_INFO_ED25519); + try { + const aesKey = await crypto.subtle.importKey("raw", aesKeyBits, "AES-GCM", false, ["decrypt"]); + const plain = new Uint8Array( + await crypto.subtle.decrypt( + { name: "AES-GCM", iv: cipher.slice(0, 12), additionalData: encodeUtf8(apiKeyId), tagLength: 128 }, + aesKey, + cipher.slice(12), + ), + ); + try { + const pkcs8 = base64ToBytes(new TextDecoder().decode(plain)); + return await crypto.subtle.importKey("pkcs8", pkcs8, "Ed25519", false, ["sign"]); + } finally { + plain.fill(0); + } + } finally { + aesKeyBits.fill(0); + } +} + +async function signBusinessMessage(privateKey: CryptoKey, message: string): Promise { + const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, encodeUtf8(message))); + try { + return bytesToBase64(sig); + } finally { + sig.fill(0); + } +} + +function hasLeadingZeroBits(bytes: Uint8Array, bits: number): boolean { + const fullBytes = Math.floor(bits / 8); + for (let i = 0; i < fullBytes; i++) { + if (bytes[i] !== 0) return false; + } + const remainder = bits % 8; + if (remainder === 0) return true; + const mask = (255 << (8 - remainder)) & 255; + return ((bytes[fullBytes] ?? 255) & mask) === 0; +} + +async function createProofOfWork(apiKeyId: string, sessionId: string, ts: string, signal?: AbortSignal): Promise { + const seedDigest = new Uint8Array( + await crypto.subtle.digest("SHA-256", encodeUtf8(`${apiKeyId}\n${APP_ID}\n${sessionId}\n${ts}`)), + ); + const seed = bytesToHex(seedDigest).slice(0, 32); + const nonce = randomHex(POW_NONCE_BYTES); + for (let counter = 0; counter <= 4_294_967_295; counter++) { + signal?.throwIfAborted(); + const candidate = `${nonce}${counter.toString(16).padStart(8, "0")}`; + const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encodeUtf8(`${seed}\n${candidate}`))); + if (hasLeadingZeroBits(digest, POW_BITS)) return candidate; + } + throw new Error("Unable to solve client request proof of work"); +} + +function parseSigningCredential(credential: string): ParsedCredential | undefined { + const dot = credential.indexOf("."); + if (dot <= 0 || dot !== credential.lastIndexOf(".")) return undefined; + const apiKeyId = credential.slice(0, dot); + const apiKeySecret = credential.slice(dot + 1); + if (!apiKeyId.trim() || !apiKeySecret.trim()) return undefined; + return { apiKeyId, apiKeySecret }; +} + +function isUnsignedPath(pathname: string): boolean { + let path = pathname; + try { + path = decodeURIComponent(pathname); + } catch { + // keep raw path + } + path = path.replace(/\/+$/u, ""); + return UNSIGNED_PATHS.has(path); +} + +function findHeader(pairs: UpstreamHeaderPair[], name: string): string | undefined { + const lower = name.toLowerCase(); + for (const [key, value] of pairs) { + if (key.toLowerCase() === lower) return value; + } + return undefined; +} + +export class ClientSigningManager { + private readonly gateUrl: string; + private readonly identity: ProxyIdentity; + private readonly fetchImpl: typeof fetch; + private readonly now: () => number; + private readonly states = new Map(); + private readonly notedKeys = new Set(); + onEvent?: (message: string) => void; + + constructor(opts: { + identity: ProxyIdentity; + origin?: string; + fetchImpl?: typeof fetch; + now?: () => number; + onEvent?: (message: string) => void; + }) { + this.gateUrl = `${(opts.origin?.trim() || DEFAULT_ORIGIN).replace(/\/+$/u, "")}${GATE_PATH}`; + this.identity = opts.identity; + this.fetchImpl = opts.fetchImpl ?? fetch; + this.now = opts.now ?? Date.now; + this.onEvent = opts.onEvent; + } + + /** + * Add the V4 signing headers to an upstream header-pair list. Returns the + * input pairs unchanged whenever signing does not apply: exempt path, + * bypass, non-signable credential, missing session id, gate off/unreachable, + * or handshake failure. Never throws. + */ + async sign(url: string, pairs: UpstreamHeaderPair[], cred: SigningCredential): Promise { + return (await this.signWithStatus(url, pairs, cred)).pairs; + } + + /** + * `sign` with a `signed` flag so the retry ladder can distinguish + * "signed but rejected" from "never signed" without identity checks on the + * returned array reference. Cheap local eligibility checks (credential + * separator, session id) run BEFORE the gate probe so non-signable + * credentials never pay for network fetches. + */ + async signWithStatus(url: string, pairs: UpstreamHeaderPair[], cred: SigningCredential): Promise { + let parsed: URL; + try { + parsed = new URL(url); + } catch { + return { pairs, signed: false }; + } + if (parsed.protocol !== "https:") return { pairs, signed: false }; + if (isUnsignedPath(parsed.pathname)) return { pairs, signed: false }; + if (pairs.some(([k]) => k.toLowerCase() === "x-client-sig")) return { pairs, signed: false }; + + const stateKey = `${parsed.origin}\n${cred.credential}`; + const state = this.stateFor(stateKey); + if (state.bypass) return { pairs, signed: false }; + + const parsedCred = parseSigningCredential(cred.credential); + if (!parsedCred) { + this.noteOnce(stateKey, "credential has no {apiKeyId}.{apiKeySecret} separator โ€” signing skipped"); + return { pairs, signed: false }; + } + + const sessionId = findHeader(pairs, "x-session-id")?.trim(); + if (!sessionId) { + this.noteOnce(stateKey, "upstream request has no x-session-id โ€” signing skipped"); + return { pairs, signed: false }; + } + + if (!(await this.gateEnabled(state, cred))) return { pairs, signed: false }; + + let privateKey: CryptoKey; + try { + privateKey = await this.ensurePrivateKey(state, stateKey, parsedCred, parsed.origin); + } catch { + this.noteOnce(stateKey, "signing handshake failed โ€” sending unsigned"); + this.invalidateState(stateKey); + return { pairs, signed: false }; + } + const signedPairs = await this.buildSignedPairs(stateKey, pairs, privateKey, parsedCred, sessionId, cred.appVersion); + return signedPairs ? { pairs: signedPairs, signed: true } : { pairs, signed: false }; + } + + private async buildSignedPairs( + stateKey: string, + pairs: UpstreamHeaderPair[], + privateKey: CryptoKey, + parsedCred: ParsedCredential, + sessionId: string, + appVersion: string, + ): Promise { + const ts = String(Date.now()); + const nonce = randomHex(NONCE_BYTES); + let pow: string; + let sig: string; + try { + pow = await createProofOfWork(parsedCred.apiKeyId, sessionId, ts); + sig = await signBusinessMessage( + privateKey, + `${parsedCred.apiKeyId}\n${ts}\n${appVersion}\n${sessionId}\n${nonce}`, + ); + } catch (err) { + if ((err as Error).name !== "AbortError") { + this.noteOnce(stateKey, `signing failed (${(err as Error).message}) โ€” sending unsigned`); + } + return null; + } + const cleaned = pairs.filter(([k]) => { + const lower = k.toLowerCase(); + return !SIGNING_HEADER_NAMES.has(lower) && lower !== "x-session-id"; + }); + return [ + ...cleaned, + ["X-Client-Ts", ts], + ["X-Client-Version", appVersion], + ["X-Client-Sig", sig], + // canonical case replaces the lowercase trace copy in this append position + // (mirrors the client's i.set("X-Session-Id") Headers.set semantics) + ["X-Session-Id", sessionId], + ["X-Client-Nonce", nonce], + ["X-App-Id", APP_ID], + ["X-Client-Pow", pow], + ]; + } + + /** + * True when the response is a signing rejection the client retries on: + * HTTP 401 whose envelope mentions VERIFY_SIGNATURE_INVALID / VERIFY_APIKEY_EXPIRED. + * Reads a clone; the response body stays consumable by the caller. + */ + async isVerifyFailure(resp: Response): Promise { + if (resp.status !== 401) return false; + try { + const body = await resp.clone().json() as Record; + if (!body || typeof body !== "object" || Array.isArray(body)) return false; + const data = body.data as Record | undefined; + const error = body.error as Record | undefined; + const candidates = [body.msg, body.reason, data?.reason, error?.reason, error?.message]; + return candidates.some((v) => v === VERIFY_SIGNATURE_INVALID || v === VERIFY_APIKEY_EXPIRED); + } catch { + return false; + } + } + + /** Drop the cached signing key for a (origin, credential) pair after a VERIFY rejection. */ + invalidate(url: string, credential: string): void { + try { + const stateKey = `${new URL(url).origin}\n${credential}`; + this.invalidateState(stateKey); + } catch { + // unreachable URL โ€” nothing cached under it + } + } + + /** Permanently stop signing for a (origin, credential) pair (two VERIFY rejections). */ + setBypass(url: string, credential: string): void { + try { + const stateKey = `${new URL(url).origin}\n${credential}`; + const state = this.stateFor(stateKey); + state.bypass = true; + this.invalidateState(stateKey); + this.onEvent?.("client-signing: VERIFY rejection persisted โ€” bypassing signing for this credential"); + } catch { + // unreachable URL + } + } + + private invalidateState(stateKey: string): void { + const state = this.states.get(stateKey); + if (!state) return; + state.epoch += 1; + state.privKey = undefined; + state.handshake = undefined; + } + + private stateFor(stateKey: string): SignerState { + let state = this.states.get(stateKey); + if (!state) { + state = { gateEnabled: false, gateExpiresAt: 0, gateNegUntil: 0, epoch: 0, bypass: false }; + this.states.set(stateKey, state); + } + return state; + } + + private async gateEnabled(state: SignerState, cred: SigningCredential): Promise { + const now = this.now(); + if (state.gateExpiresAt > now) return state.gateEnabled; + if (state.gateNegUntil > now) return false; + if (state.gatePromise) return state.gatePromise; + const promise = this.probeGate(state, cred).finally(() => { + if (state.gatePromise === promise) state.gatePromise = undefined; + }); + state.gatePromise = promise; + return promise; + } + + private async probeGate(state: SignerState, cred: SigningCredential): Promise { + const now = this.now(); + let outcome: "enabled" | "disabled" | "unavailable"; + try { + outcome = await this.fetchGate(cred); + } catch { + state.gateNegUntil = now + GATE_FAILURE_COOLDOWN_MS; + return false; + } + state.gateEnabled = outcome === "enabled"; + if (outcome === "unavailable") { + // proxy deviation: the client re-probes unavailable gates on every request + // from a UI process; on the proxy hot path a short negative cache bounds + // the worst-case per-request latency to one probe per window + state.gateNegUntil = now + GATE_UNAVAILABLE_COOLDOWN_MS; + } else { + state.gateExpiresAt = now + GATE_TTL_MS; + state.gateNegUntil = 0; + } + if (state.gateEnabled) this.onEvent?.("client-signing: server enabled codingPlanSignature โ€” signing requests"); + return state.gateEnabled; + } + + private async fetchGate(cred: SigningCredential): Promise<"enabled" | "disabled" | "unavailable"> { + // sYr (bundle) builds the gate-fetch identity set WITHOUT X-ZCode-Agent and + // X-Device-Mid; Bxi appends x-api-key only โ€” this fetch carries no Accept header. + const identityHeaders = Object.fromEntries( + Object.entries(buildIdentityHeaders(this.identity)) + .filter(([name]) => name !== "X-ZCode-Agent" && name !== "X-Device-Mid"), + ); + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), GATE_TIMEOUT_MS); + try { + const resp = await this.fetchImpl(this.gateUrl, { + method: "GET", + headers: { ...identityHeaders, "x-api-key": cred.credential }, + redirect: "manual", + signal: controller.signal, + }); + if (!resp.ok) return "unavailable"; + const parsed = await resp.json() as Record; + if (!parsed || parsed.code !== 0) return "unavailable"; + const data = parsed.data as Record | undefined; + if (!data || !Object.prototype.hasOwnProperty.call(data, "codingPlanSignature")) return "disabled"; + const signature = data.codingPlanSignature as Record | undefined; + return signature?.enable === true ? "enabled" : "disabled"; + } finally { + clearTimeout(timer); + } + } + + private async ensurePrivateKey( + state: SignerState, + stateKey: string, + parsedCred: ParsedCredential, + origin: string, + ): Promise { + if (state.privKey) return state.privKey; + if (state.handshake) return state.handshake; + const epoch = state.epoch; + const handshake = this.performHandshake(parsedCred, origin).then((key) => { + if (state.epoch !== epoch) throw new Error("signing key changed during handshake"); + state.privKey = key; + return key; + }); + const clear = () => { + if (state.handshake === handshake) state.handshake = undefined; + }; + handshake.then(clear, clear); + state.handshake = handshake; + return handshake; + } + + private async performHandshake(parsedCred: ParsedCredential, origin: string): Promise { + const ts = String(Date.now()); + const nonce = randomHex(NONCE_BYTES); + const sig = await handshakeSignature( + parsedCred.apiKeySecret, + `${HANDSHAKE_METHOD}\n${parsedCred.apiKeyId}\n${ts}\n${nonce}`, + ); + + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), HANDSHAKE_TIMEOUT_MS); + try { + const resp = await this.fetchImpl(`${origin}${HANDSHAKE_PATH}`, { + method: "POST", + headers: { Authorization: `${parsedCred.apiKeyId}.${parsedCred.apiKeySecret}`, "Content-Type": "application/json" }, + body: JSON.stringify({ apiKey: `${parsedCred.apiKeyId}.${parsedCred.apiKeySecret}`, nonce, sig, ts }), + redirect: "manual", + signal: controller.signal, + }); + if (resp.status !== 200) throw new Error(`handshake_http_${resp.status}`); + const envelope = await resp.json() as { code?: unknown; msg?: unknown; data?: { privateCipher?: unknown } }; + if (envelope.code === 500) throw new Error("handshake_server_500"); + if (envelope.code !== 200) throw new Error(`handshake_rejected: ${String(envelope.msg)}`); + const cipher = envelope.data?.privateCipher; + if (typeof cipher !== "string" || !cipher) throw new Error("handshake_omitted_privateCipher"); + return await decryptSigningPrivateKey(parsedCred.apiKeyId, parsedCred.apiKeySecret, cipher); + } finally { + clearTimeout(timer); + } + } + + private noteOnce(stateKey: string, message: string): void { + if (this.notedKeys.has(stateKey)) return; + this.notedKeys.add(stateKey); + this.onEvent?.(`client-signing: ${message}`); + } +} + +export interface SendWithSigningParams { + url: string; + headerPairs: UpstreamHeaderPair[]; + credential: string; + appVersion: string; + send: (headerPairs: UpstreamHeaderPair[]) => Promise; + debug?: (message: string) => void; +} + +/** + * Send with the client's full signing retry ladder: + * signed โ†’ on 401 VERIFY: re-handshake + re-sign โ†’ on second 401 VERIFY: + * permanent bypass + unsigned. A `null` manager (feature disabled) sends as-is. + */ +export async function sendWithClientSigning( + signer: ClientSigningManager | null, + params: SendWithSigningParams, +): Promise { + const { url, headerPairs, credential, appVersion, send, debug } = params; + if (!signer) return send(headerPairs); + + const first = await signer.signWithStatus(url, headerPairs, { credential, appVersion }); + let resp = await send(first.pairs); + if (!first.signed || !await signer.isVerifyFailure(resp)) return resp; + + debug?.("401 VERIFY_SIGNATURE_* โ€” invalidating signing key and retrying once"); + signer.invalidate(url, credential); + const second = await signer.signWithStatus(url, headerPairs, { credential, appVersion }); + resp = await send(second.pairs); + if (!second.signed || !await signer.isVerifyFailure(resp)) return resp; + + signer.setBypass(url, credential); + debug?.("401 VERIFY_SIGNATURE_* twice โ€” sending unsigned (signing bypassed)"); + return send(headerPairs); +} + +let defaultSigner: ClientSigningManager | null = null; +let defaultSignerKey = ""; + +/** + * Process-wide signing manager, shared across requests (gate + key caches). + * Returns `null` when `clientSigning.enabled` is false. Recreated when the + * relevant config values change (Android `setConfig`) โ€” keyed on the full + * identity because the manager embeds it in gate-fetch headers. + */ +export function getDefaultClientSigning(config: { + clientSigning: { enabled: boolean; origin: string }; + identity: ProxyIdentity; +}): ClientSigningManager | null { + if (!config.clientSigning.enabled) return null; + const key = `${config.clientSigning.origin}\n${identityCacheKey(config.identity)}`; + if (!defaultSigner || key !== defaultSignerKey) { + defaultSigner = new ClientSigningManager({ + identity: config.identity, + origin: config.clientSigning.origin, + }); + defaultSignerKey = key; + } + return defaultSigner; +} diff --git a/src/proxy/dump.ts b/src/proxy/dump.ts new file mode 100644 index 0000000000000000000000000000000000000000..fae0c48e1ab33ba9b6f4a7128ee15a83acce2326 --- /dev/null +++ b/src/proxy/dump.ts @@ -0,0 +1,93 @@ +/** + * Upstream traffic dumper โ€” used for debugging "JSON request body" issues. + * + * Activated by env `ZCODE_DUMP_UPSTREAM=`: every proxied request emits + * one JSONL line per phase (`client_in` / `upstream_out` / `upstream_in` / + * `upstream_body_sample`), so the full requestโ†’response timeline can be + * inspected offline. Inactive (no-op) when the env var is unset. + * + * Design constraints: + * - Must NEVER affect request handling โ€” all FS work is try/catch'd. + * - Sensitive header values (Authorization / x-api-key / captcha tokens / + * proxy secrets) are masked to `abcd1234โ€ฆwxyz` so fingerprints are visible + * while credentials stay redacted. + * - Bodies are JSON.parsed and re-stringified when possible (for readability); + * otherwise emitted as the raw string. + * + * The dump file is line-oriented JSON (JSONL); each line is self-contained: + * + * {"ts":"2026-07-31T12:00:00.000Z","reqId":"#001","phase":"client_in", ...} + * + * Pair lines by `reqId` to reconstruct a full request timeline. + */ +import { appendFileSync } from "node:fs"; + +const DUMP_PATH = process.env.ZCODE_DUMP_UPSTREAM; + +/** Header names whose values must be masked before dumping. */ +const SENSITIVE_HEADERS = new Set([ + "authorization", + "x-api-key", + "proxy-authorization", + "proxy-api-key", + "x-zcode-captcha-verify-param", + "x-zcode-captcha-verify-region", + "cookie", +]); + +function maskHeaderValue(key: string, value: string): string { + if (!SENSITIVE_HEADERS.has(key.toLowerCase())) return value; + if (value.length <= 12) return ""; + return `${value.slice(0, 8)}โ€ฆ${value.slice(-4)} (len=${value.length})`; +} + +/** Convert a Headers object to a plain object with sensitive values masked. */ +export function dumpHeaders(headers: Headers): Record { + const out: Record = {}; + for (const [k, v] of headers.entries()) { + out[k] = maskHeaderValue(k, v); + } + return out; +} + +/** Try to parse body as JSON for pretty emission; fall back to raw string. */ +export function dumpBody(body: string | undefined | null): unknown { + if (body === undefined || body === null) return undefined; + if (body.length === 0) return ""; + try { + return JSON.parse(body); + } catch { + return body; + } +} + +interface DumpLine { + ts: string; + reqId: string; + phase: string; + [k: string]: unknown; +} + +/** + * Append one dump line. No-op when `ZCODE_DUMP_UPSTREAM` is unset. + * All errors are swallowed โ€” dumping must never break request handling. + */ +export function dumpPhase(reqId: string, phase: string, data: Record): void { + if (!DUMP_PATH) return; + try { + const line: DumpLine = { + ts: new Date().toISOString(), + reqId, + phase, + ...data, + }; + appendFileSync(DUMP_PATH, JSON.stringify(line) + "\n", "utf-8"); + } catch { + // intentional swallow โ€” see header comment + } +} + +/** True when dumping is active. Cheap check used to gate per-phase logic in handler. */ +export function dumpEnabled(): boolean { + return !!DUMP_PATH; +} diff --git a/src/proxy/endpoint-routing.ts b/src/proxy/endpoint-routing.ts new file mode 100644 index 0000000000000000000000000000000000000000..22440e653edde014a84df8e217f826b94984b5d2 --- /dev/null +++ b/src/proxy/endpoint-routing.ts @@ -0,0 +1,215 @@ +/** + * Provider endpoint routing โ€” mirrors the ZCode 3.7+ `ProviderEndpointRoutingService`. + * + * The desktop client periodically fetches `GET {zcodeApiBase}/api/v1/agent/configs` + * and rewrites provider request URLs according to the returned + * `data.proxyEndpoint.mapping` table (`from` โ†’ `to`, exact normalized-URL match). + * As of 2026-08-19 the server maps the coding-plan Anthropic endpoints to + * `zcode.z.ai/api/v1/ultra[-zai]/...`; the table is server-controlled and may + * grow at any time, so resolution is generic. + * + * Failure semantics are strictly fail-open: any fetch/parse error keeps the + * previous snapshot (or none) and requests go to their original URL after a + * cooldown. See `_reverse/NOTEPAD.md` "Server-side endpoint remapping". + */ +import { buildIdentityHeaders, identityCacheKey } from "./identity.js"; +import type { ProxyIdentity } from "../config/types.js"; + +const DEFAULT_ORIGIN = "https://zcode.z.ai"; +const CONFIG_PATH = "/api/v1/agent/configs"; +const SUCCESS_TTL_MS = 300_000; +const FAILURE_COOLDOWN_MS = 30_000; +const REQUEST_TIMEOUT_MS = 3_000; +const MAX_MAPPING_ENTRIES = 256; + +export interface EndpointRoutingOptions { + /** Origin of the agent-configs endpoint. */ + origin?: string; + identity: ProxyIdentity; + /** Resolves the `x-api-key` sent on the config fetch (coding-plan credential). */ + credential?: () => string | undefined; + fetchImpl?: typeof fetch; + now?: () => number; + successTtlMs?: number; + failureCooldownMs?: number; + requestTimeoutMs?: number; + onSnapshot?: (entries: number) => void; +} + +export interface RoutedUrl { + routed: boolean; + url: string; +} + +interface RoutingSnapshot { + expiresAt: number; + mapping: Map; +} + +function normalizePath(pathname: string): string { + if (pathname === "/") return "/"; + return pathname.replace(/\/+$/u, "") || "/"; +} + +function routingKey(url: URL): string { + const port = url.port || "443"; + return `${url.protocol}//${url.hostname.toLowerCase()}:${port}${normalizePath(url.pathname)}`; +} + +function parseMappingUrl(value: unknown, field: "from" | "to"): URL { + if (typeof value !== "string") throw new Error(`mapping.${field} must be a string`); + const parsed = new URL(value); + if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.search || parsed.hash) { + throw new Error(`mapping.${field} URL is not a plain https URL`); + } + return parsed; +} + +export class EndpointRoutingService { + private readonly configUrl: string; + private readonly identity: ProxyIdentity; + private readonly credential?: () => string | undefined; + private readonly fetchImpl: typeof fetch; + private readonly now: () => number; + private readonly successTtlMs: number; + private readonly failureCooldownMs: number; + private readonly requestTimeoutMs: number; + private readonly onSnapshot?: (entries: number) => void; + private snapshot: RoutingSnapshot | undefined; + private retryAfter = 0; + private refreshPromise: Promise | undefined; + + constructor(opts: EndpointRoutingOptions) { + this.configUrl = `${(opts.origin?.trim() || DEFAULT_ORIGIN).replace(/\/+$/u, "")}${CONFIG_PATH}`; + this.identity = opts.identity; + this.credential = opts.credential; + this.fetchImpl = opts.fetchImpl ?? fetch; + this.now = opts.now ?? Date.now; + this.successTtlMs = opts.successTtlMs ?? SUCCESS_TTL_MS; + this.failureCooldownMs = opts.failureCooldownMs ?? FAILURE_COOLDOWN_MS; + this.requestTimeoutMs = opts.requestTimeoutMs ?? REQUEST_TIMEOUT_MS; + this.onSnapshot = opts.onSnapshot; + } + + /** True when at least one successful snapshot has been fetched. */ + hasSnapshot(): boolean { + return this.snapshot !== undefined; + } + + /** + * Resolve a request URL through the mapping table. Never throws: any error + * resolves to `{ routed: false, url }` so the caller keeps the original URL. + * The optional `credential` (coding-plan key) is attached as `x-api-key` on + * a mapping refresh fetch, mirroring the client's `sourceHeaders`. + */ + async resolve(url: string, credential?: string): Promise { + let parsed: URL; + try { + parsed = new URL(url); + } catch { + return { routed: false, url }; + } + try { + await this.ensureFresh(credential); + } catch { + // fail-open: resolve without a snapshot + } + const target = this.snapshot?.mapping.get(routingKey(parsed)); + if (!target) return { routed: false, url }; + const rewritten = new URL(target); + rewritten.search = parsed.search; + return { routed: true, url: rewritten.href }; + } + + private async ensureFresh(credential?: string): Promise { + const now = this.now(); + if ((this.snapshot && this.snapshot.expiresAt > now) || this.retryAfter > now) return; + const pending = this.refreshPromise ?? this.beginRefresh(credential); + await pending; + } + + private beginRefresh(credential?: string): Promise { + const promise = this.refresh(credential).finally(() => { + if (this.refreshPromise === promise) this.refreshPromise = undefined; + }); + this.refreshPromise = promise; + return promise; + } + + private async refresh(credential?: string): Promise { + // QSt (bundle) builds the config-fetch identity set WITHOUT X-ZCode-Agent; + // Pvo appends x-api-key + Accept. Mirror that set exactly. + const identityHeaders = Object.fromEntries( + Object.entries(buildIdentityHeaders(this.identity)).filter(([name]) => name !== "X-ZCode-Agent"), + ); + const headers: Record = { + ...identityHeaders, + Accept: "application/json", + }; + const key = credential ?? this.credential?.(); + if (key) headers["x-api-key"] = key; + + const controller = new AbortController(); + const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs); + try { + const resp = await this.fetchImpl(this.configUrl, { + method: "GET", + headers, + redirect: "manual", + signal: controller.signal, + }); + if (resp.status < 200 || resp.status >= 300) throw new Error(`agent_configs_http_${resp.status}`); + const parsed = await resp.json() as unknown; + const envelope = parsed as { code?: unknown; data?: unknown }; + if (!envelope || typeof envelope !== "object" || envelope.code !== 0) { + throw new Error("agent_configs_nonzero_code"); + } + const data = envelope.data as { proxyEndpoint?: { mapping?: unknown } } | undefined; + const entries = data?.proxyEndpoint?.mapping; + const list = Array.isArray(entries) ? entries : []; + if (list.length > MAX_MAPPING_ENTRIES) throw new Error("agent_configs_too_many_mappings"); + + const mapping = new Map(); + for (const entry of list) { + const raw = entry as { from?: unknown; to?: unknown }; + const from = parseMappingUrl(raw.from, "from"); + const to = parseMappingUrl(raw.to, "to"); + const key = routingKey(from); + if (mapping.has(key)) throw new Error("agent_configs_duplicate_from"); + mapping.set(key, to.href); + } + this.snapshot = { expiresAt: this.now() + this.successTtlMs, mapping }; + this.retryAfter = 0; + this.onSnapshot?.(mapping.size); + } catch { + this.retryAfter = this.now() + this.failureCooldownMs; + } finally { + clearTimeout(timer); + } + } +} + +let defaultRouting: EndpointRoutingService | null = null; +let defaultRoutingKey = ""; + +/** + * Process-wide routing service, shared across requests (snapshot cache). + * Recreated when the relevant config values change (Android `setConfig`) โ€” + * keyed on the full identity because the service embeds it in config-fetch + * headers. Returns `null` when disabled. + */ +export function getDefaultEndpointRouting(config: { + endpointRouting: { enabled: boolean; origin: string }; + identity: ProxyIdentity; +}): EndpointRoutingService | null { + if (!config.endpointRouting.enabled) return null; + const key = `${config.endpointRouting.origin}\n${identityCacheKey(config.identity)}`; + if (!defaultRouting || key !== defaultRoutingKey) { + defaultRouting = new EndpointRoutingService({ + origin: config.endpointRouting.origin, + identity: config.identity, + }); + defaultRoutingKey = key; + } + return defaultRouting; +} diff --git a/src/proxy/handler.ts b/src/proxy/handler.ts new file mode 100644 index 0000000000000000000000000000000000000000..c57c0d8ef49a90934d03dfb5990031672766cd5f --- /dev/null +++ b/src/proxy/handler.ts @@ -0,0 +1,988 @@ +/** + * Main proxy handler โ€” routes requests, injects auth, forwards, and streams responses. + * + * **v2.6 upstream reality (post-PR #34)**: BOTH plan tiers post an + * Anthropic-format upstream โ€” coding-plan mirrors the real ZCode client + * (api.z.ai/api/anthropic โ†’ ultra via endpoint routing); start-plan posts to + * zcode.z.ai's Anthropic gateway with the plan JWT. Consequently: + * - OpenAI clients are translated OpenAIโ†’Anthropic on the way up and + * Anthropicโ†’OpenAI on the way down ("translation" mode). + * - Anthropic clients speak the upstream's native format โ€” requests are + * forwarded with body transforms only ("passthrough" mode, + * `decompress: false`). + * + * @see .omo/plans/zcode-proxy.md Task 6 + */ +import type { Format } from "../translator/types.js"; +import type { ProxyConfig } from "../config/types.js"; +import type { AuthManager } from "../auth/manager.js"; +import { getProvider } from "../provider/providers.js"; +import { buildUpstreamHeaderPairs, buildUpstreamRequest, type UpstreamHeaderPair } from "./upstream.js"; +import { getDefaultEndpointRouting, type EndpointRoutingService } from "./endpoint-routing.js"; +import { getDefaultClientSigning, sendWithClientSigning, type ClientSigningManager } from "./client-signing.js"; +import { credentialString } from "../auth/types.js"; +import { sendOrderedUpstreamRequest } from "./ordered-transport.js"; +import { transformRequestBody } from "./body-transformer.js"; +import { isCaptchaChallenged, retryOnCaptchaChallenge } from "./captcha-retry.js"; +import { type ClientSessionResult } from "./client-session.js"; +import { resolveSessionContext } from "./session-context.js"; +import { gzipSync } from "node:zlib"; + +// captcha.ts is loaded lazily inside the `startPlan` branch (only path that +// touches it). The solver itself (captcha-happy.ts) is dynamically imported +// by captcha-solver.ts, so non-start-plan processes never pay its startup +// cost. Desktop Bun keeps the same code path; the dynamic import resolves +// synchronously enough on Bun's warm cache. +type CaptchaModule = typeof import("./captcha.js"); +let captchaModule: CaptchaModule | null = null; +async function loadCaptcha(): Promise { + if (!captchaModule) captchaModule = await import("./captcha.js"); + return captchaModule; +} +import { translateRequestOpenAIToAnthropic, translateResponseAnthropicToOpenAI } from "../translator/openai-to-anthropic.js"; +import { translateRequestAnthropicToOpenAI, translateResponseOpenAIToAnthropic } from "../translator/anthropic-to-openai.js"; +import { anthropicSseToOpenaiSse, openaiSseToAnthropicSse } from "../translator/sse-translator.js"; +import type { OpenAIChatRequest, OpenAIChatResponse, AnthropicMessagesRequest, AnthropicMessagesResponse } from "../translator/types.js"; +import { dumpPhase, dumpHeaders, dumpBody, dumpEnabled } from "./dump.js"; +import { inflateWithCap } from "./inflate.js"; + +/** Options for the proxy handler. */ +export interface ProxyHandlerOptions { + config: ProxyConfig; + auth: AuthManager; + /** Override the global fetch (for testing). Defaults to global `fetch`. */ + fetchImpl?: typeof fetch; + /** + * When true, emit additional per-request diagnostic lines: upstream URL, + * redacted request headers, body preview, upstream response status and + * selected response headers. Activated by `zcode-proxy serve debug`. + */ + debug?: boolean; + /** Override the process-wide endpoint routing service (for testing). `null` disables. */ + endpointRouting?: EndpointRoutingService | null; + /** Override the process-wide client signing manager (for testing). `null` disables. */ + clientSigning?: ClientSigningManager | null; +} + +/** + * Forward a client request to the upstream provider with injected auth. + * + * Upstream fetch options differ by mode: + * - **Passthrough** (OpenAI client): `{ decompress: false }` โ€” compressed + * response bodies (gzip/deflate/br) pass through untouched; raw bytes and the + * Content-Encoding header are forwarded as-is, letting the client decompress. + * - **Translation** (Anthropic client): no options โ€” Bun decompresses so the proxy + * can read the body and translate OpenAIโ†’Anthropic (then re-gzip if the client + * accepts). + * + * No upstream timeout is applied โ€” matches ZCode desktop client behaviour + * (the bundle has no automatic timer on LLM calls, only user-initiated abort). + * Connection-level errors (ECONNREFUSED, DNS failure) still surface as 502. + */ +export async function proxyRequest( + clientReq: Request, + format: Format, + opts: ProxyHandlerOptions, +): Promise { + const { config, auth } = opts; + const fetchImpl = opts.fetchImpl ?? fetch; + const hasCustomFetchImpl = opts.fetchImpl !== undefined; + const debug = opts.debug === true; + const started = Date.now(); + const reqId = nextReqId(); + + let body: string | undefined; + try { + body = await readBody(clientReq); + } catch (err) { + if (err instanceof InflatedBodyTooLargeError) { + return errorResponse(413, "request_too_large", err.message); + } + return errorResponse(400, "invalid_request_error", (err as Error).message); + } + + const meta = peekBody(body); + + if (dumpEnabled()) { + dumpPhase(reqId, "client_in", { + method: clientReq.method, + url: clientReq.url, + headers: dumpHeaders(clientReq.headers), + body: dumpBody(body), + }); + } + + const staticProvider = getProvider(config.provider); + const provider = { + ...staticProvider, + anthropicBaseURL: config.providers[config.provider].anthropicBase, + openaiBaseURL: config.providers[config.provider].openaiBase, + }; + + let cred; + try { + cred = await auth.getCredential(); + } catch (err) { + if (debug) debugError(reqId, "credential_unavailable", (err as Error).message); + printRow(reqId, format, meta, 503, started, Date.now(), 0, 0, 0); + return errorResponse(503, "credential_unavailable", (err as Error).message); + } + + // v2.6: both plans use the Anthropic upstream. coding-plan mirrors the real + // ZCode client (api.z.ai/api/anthropic โ†’ ultra via endpoint routing); + // start-plan's old OpenAI gateway (/api/v1/zcode-plan/chat/completions) was + // retired server-side (404 as of 2026-08-28) โ€” the live desktop client now + // posts Anthropic messages to /api/v1/zcode-plan/anthropic/v1/messages with + // the start-plan JWT, so we do the same (no OpenAI translation either way). + const startPlan = config.plan === "start-plan"; + const translateAnthropicToOpenAI = false; + const translateOpenAIToAnthropic = format === "openai"; + const upstreamFormat: Format = "anthropic"; + const clientSession = resolveSessionContext({ clientReq, body, upstreamFormat, model: meta.model, config }); + if (debug && clientSession) { + const shortSession = clientSession.sessionId ? clientSession.sessionId.slice(0, 10) : "-"; + debugLine(reqId, `clientIdentity source=${clientSession.source} action=${clientSession.action} confidence=${clientSession.confidence.toFixed(2)} session=${shortSession}`); + } + + let upstreamBody = body; + if (translateOpenAIToAnthropic) { + const translated = translateOpenAIBody(body); + if (translated instanceof Response) return translated; + upstreamBody = translated; + if (debug) debugLine(reqId, `translated OpenAIโ†’Anthropic (bytes=${upstreamBody?.length ?? 0})`); + } else if (translateAnthropicToOpenAI) { + const translated = translateAnthropicBody(body); + if (translated instanceof Response) return translated; + upstreamBody = translated; + if (debug) debugLine(reqId, `translated Anthropicโ†’OpenAI (bytes=${upstreamBody?.length ?? 0})`); + } + + const transformedBody = transformRequestBody(upstreamBody, { format: upstreamFormat, userId: startPlan ? undefined : cred.userId, startPlan }); + if (debug && transformedBody !== upstreamBody) { + debugLine(reqId, `body transformed (upstreamFormat=${upstreamFormat}, startPlan=${startPlan}, bytes=${transformedBody?.length ?? 0})`); + } + + let captchaHeaders: Record | undefined; + if (startPlan) { + try { + const captcha = await loadCaptcha(); + const token = await captcha.getCaptchaToken(config.identity.appVersion); + captchaHeaders = { [captcha.RETRY_HEADERS.PARAM]: token.verifyParam, [captcha.RETRY_HEADERS.REGION]: token.region }; + } catch { + // Will solve on 403 fallback below + } + } + + const useOrderedTransport = shouldUseOrderedTransport(config, clientSession, hasCustomFetchImpl); + let upstreamHeaderPairs = buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, config.identity, config.plan, captchaHeaders, clientSession); + let upstreamReq = buildUpstreamRequest(clientReq, upstreamFormat, provider, cred, transformedBody, config.identity, config.plan, captchaHeaders, clientSession); + + const routing = opts.endpointRouting !== undefined ? opts.endpointRouting : getDefaultEndpointRouting(config); + const signer = opts.clientSigning !== undefined ? opts.clientSigning : getDefaultClientSigning(config); + const translateMode = translateOpenAIToAnthropic || translateAnthropicToOpenAI; + const dispatch = async (req: Request, pairs: UpstreamHeaderPair[]): Promise => { + let sendUrl = req.url; + if (routing) { + const routed = await routing.resolve(req.url, credentialString(cred)); + if (routed.routed) { + sendUrl = routed.url; + if (debug) debugLine(reqId, `endpoint routing: ${req.url} -> ${routed.url}`); + } + } + // Signing decisions (exempt-path, handshake origin, bypass keying) run + // against the PRE-routing provider URL โ€” the client's signer wraps the + // routing transport, so its checks see the original URL too. + return sendWithClientSigning(signer, { + url: req.url, + headerPairs: pairs, + credential: credentialString(cred), + appVersion: config.identity.appVersion, + debug: debug ? (message) => debugLine(reqId, message) : undefined, + send: (finalPairs) => { + const sendReq = sendUrl === req.url && finalPairs === pairs + ? req + : new Request(sendUrl, { + method: req.method, + headers: Object.fromEntries(finalPairs), + body: transformedBody ?? undefined, + }); + return sendUpstreamRequest(sendReq, finalPairs, transformedBody, translateMode, useOrderedTransport, fetchImpl, clientReq.signal, hasCustomFetchImpl); + }, + }); + }; + + if (debug) { + debugLine(reqId, `โ†’ POST ${upstreamReq.url}`); + debugLine(reqId, ` ${formatHeaderPairs(upstreamReq.headers)}`); + if (transformedBody) debugLine(reqId, ` body preview: ${previewBody(transformedBody)}`); + } + + if (dumpEnabled()) { + dumpPhase(reqId, "upstream_out", { + method: upstreamReq.method, + url: upstreamReq.url, + headers: dumpHeaders(upstreamReq.headers), + body: dumpBody(transformedBody), + upstreamFormat, + translateMode: translateOpenAIToAnthropic || translateAnthropicToOpenAI, + useOrderedTransport, + startPlan, + }); + } + + let upstreamResp: Response; + try { + // Transient connect failures (DNS blip, TLS reset, Bun "Unable to + // connect") happen a few times a day against the gateway. Retry the + // CONNECT twice with a short backoff before surfacing a 502 โ€” the + // request never reached upstream, so resending is side-effect-free. + // Guard rails: skip retry when the client already aborted or the ordered + // transport flagged the failure postWrite; re-dispatch a FRESH Request + // each attempt โ€” a reused Request has its body stream marked used after + // the first fetch (start-plan hits the plain pass-through path where + // dispatch does NOT rebuild the Request). + let dispatchAttempt = 0; + upstreamResp = await dispatchWithConnectRetry( + () => { + dispatchAttempt += 1; + const currentReq = dispatchAttempt === 1 + ? upstreamReq + : buildUpstreamRequest(clientReq, upstreamFormat, provider, cred, transformedBody, config.identity, config.plan, captchaHeaders, clientSession); + return dispatch(currentReq, upstreamHeaderPairs); + }, + { + isAborted: () => clientReq.signal.aborted, + onRetry: (attempt, err) => { + if (debug) debugError(reqId, "upstream_connect_retry", `attempt ${attempt}/${MAX_CONNECT_ATTEMPTS - 1} failed (${err.message}), retrying in ${500 * attempt}ms`); + console.log(`${reqId} upstream connect failed (${err.message}), retry ${attempt + 1}/${MAX_CONNECT_ATTEMPTS} in ${500 * attempt}ms`); + }, + }, + ); + } catch (err) { + if (debug) debugError(reqId, "upstream_unreachable", (err as Error).message); + printRow(reqId, format, meta, 502, started, Date.now(), 0, 0, 0); + return errorResponse(502, "upstream_unreachable", (err as Error).message); + } + const headersAt = Date.now(); + + if (debug) { + debugLine(reqId, `โ† ${upstreamResp.status} ${upstreamResp.statusText}`); + debugLine(reqId, ` ${formatResponseHeaders(upstreamResp.headers)}`); + } + + if (dumpEnabled()) { + dumpPhase(reqId, "upstream_in", { + status: upstreamResp.status, + statusText: upstreamResp.statusText, + headers: dumpHeaders(upstreamResp.headers), + isSSE: upstreamResp.headers.get("content-type")?.includes("text/event-stream") ?? false, + ttfbMs: headersAt - started, + }); + } + + if (upstreamResp.status === 401 && startPlan) { + if (debug) debugError(reqId, "start_plan_jwt_invalid", "JWT rejected upstream"); + printRow(reqId, format, meta, 401, started, headersAt, 0, 0, 0); + return errorResponse(401, "start_plan_jwt_invalid", "Start-plan JWT was rejected. Re-run: zcode-proxy auth login"); + } + + // start-plan: on explicit captcha challenge, retry once with a fresh + // pooled token (the challenged token was already consumed by this request; + // getCaptchaToken takes the next pre-solved one). Detection covers the + // response-header variant AND the in-body `{"code":3007}` variant (observed + // 2026-08-29 as HTTP 400 JSON with no captcha header) via the shared + // captcha-retry seam (used by /v1/responses too). + const captcha = startPlan ? await loadCaptcha() : null; + const captchaChallenge = captcha ? await isCaptchaChallenged(upstreamResp, captcha) : false; + if (captchaChallenge && captcha) { + console.log(`${reqId} captcha challenge, re-solving...`); + const outcome = await retryOnCaptchaChallenge({ + captcha, + appVersion: config.identity.appVersion, + challengedResp: upstreamResp, + debug: debug ? (message) => debugLine(reqId, message) : undefined, + solveAndRetry: (retryHeaders) => { + console.log(`${reqId} captcha re-solved (token ${retryHeaders[captcha.RETRY_HEADERS.PARAM].length} chars), retrying...`); + upstreamHeaderPairs = buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, config.identity, config.plan, retryHeaders, clientSession); + upstreamReq = buildUpstreamRequest(clientReq, upstreamFormat, provider, cred, transformedBody, config.identity, config.plan, retryHeaders, clientSession); + return dispatch(upstreamReq, upstreamHeaderPairs).then((resp) => { + if (debug) debugLine(reqId, `โ† retry ${resp.status} ${resp.statusText}`); + return resp; + }); + }, + mapError: (err, phase) => { + if (phase === "solver") { + if (debug) debugError(reqId, "captcha_solver_failed", err.message); + printRow(reqId, format, meta, 503, started, Date.now(), 0, 0, 0); + return errorResponse(503, "captcha_solver_failed", err.message); + } + if (debug) debugError(reqId, "upstream_unreachable", err.message); + printRow(reqId, format, meta, 502, started, Date.now(), 0, 0, 0); + return errorResponse(502, "upstream_unreachable", err.message); + }, + }); + if (!outcome.ok) return outcome.resp; + upstreamResp = outcome.resp; + } + + const isSSE = upstreamResp.headers.get("content-type")?.includes("text/event-stream") ?? false; + + if (translateOpenAIToAnthropic) { + if (!upstreamResp.ok) { + const errBody = await upstreamResp.text().catch(() => ""); + printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0); + return errorResponse(502, "translation_failed", `upstream returned ${upstreamResp.status}: ${errBody.slice(0, 200)}`); + } + if (isSSE && upstreamResp.body) { + const translated = anthropicSseToOpenaiSse(upstreamResp.body, meta.model); + const [clientBody, statsBody] = translated.tee(); + observeStream(reqId, format, meta, upstreamResp.status, started, statsBody, null); + return translatedSseResponse(clientBody); + } + return await translatedBatchResponse(clientReq, upstreamResp, meta.model, reqId, format, meta, started, headersAt); + } + + if (translateAnthropicToOpenAI) { + if (!upstreamResp.ok) { + const errBody = await upstreamResp.text().catch(() => ""); + printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0); + return errorResponse(502, "translation_failed", `upstream returned ${upstreamResp.status}: ${errBody.slice(0, 200)}`); + } + if (isSSE && upstreamResp.body) { + const translated = openaiSseToAnthropicSse(upstreamResp.body, meta.model); + const [clientBody, statsBody] = translated.tee(); + observeStream(reqId, format, meta, upstreamResp.status, started, statsBody, null); + return translatedSseResponse(clientBody); + } + return await translatedOpenAIToAnthropicBatchResponse(clientReq, upstreamResp, reqId, format, meta, started, headersAt); + } + + if (isSSE && upstreamResp.body) { + const [clientBody, statsBody] = upstreamResp.body.tee(); + observeStream(reqId, format, meta, upstreamResp.status, started, statsBody, upstreamResp.headers.get("content-encoding")); + return passthroughResponse(upstreamResp, clientAcceptsGzip(clientReq), clientBody); + } + + printRow(reqId, format, meta, upstreamResp.status, started, headersAt, 0, 0, 0); + return passthroughResponse(upstreamResp, clientAcceptsGzip(clientReq)); +} + +export function shouldUseOrderedTransport(config: ProxyConfig, clientSession: ClientSessionResult | undefined, hasCustomFetchImpl: boolean): boolean { + if (hasCustomFetchImpl) return false; + return clientSession?.action === "enforce" || clientSession?.source === "explicit"; +} + +/** Max attempts (initial + 2 retries) for transient CONNECT-level failures. */ +export const MAX_CONNECT_ATTEMPTS = 3; + +/** + * Connect-level retry ladder shared by the chat hot path and /v1/responses. + * Transient connect failures (DNS blip, TLS reset, Bun "Unable to connect") + * happen a few times a day against the gateway; the request never reached + * upstream, so resending is side-effect-free. + * + * Contract (review P1/P2, PR #34/#35): + * - `attemptDispatch` must dispatch a FRESH request each call โ€” a reused + * Request has its body stream marked used after the first fetch. + * - failures flagged `postWrite` (ordered transport already wrote the full + * request) are never retried โ€” the upstream may have processed it. + * - no retry once the client aborted (`opts.isAborted`). + */ +export async function dispatchWithConnectRetry( + attemptDispatch: () => Promise, + opts: { isAborted?: () => boolean; onRetry?: (attempt: number, err: Error) => void } = {}, +): Promise { + for (let attempt = 1; ; attempt++) { + if (opts.isAborted?.()) throw new Error("client aborted before upstream connect"); + try { + return await attemptDispatch(); + } catch (err) { + if ((err as { postWrite?: boolean }).postWrite) throw err; + if (attempt >= MAX_CONNECT_ATTEMPTS) throw err; + const backoffMs = 500 * attempt; + opts.onRetry?.(attempt, err as Error); + await new Promise((r) => setTimeout(r, backoffMs)); + } + } +} + +/** + * True on runtimes whose fetch ignores Bun's `decompress: false` extension and + * transparently inflates compressed response bodies while KEEPING the + * `content-encoding`/`content-length` headers (verified empirically against + * Node 22/26 undici and Bun 1.3: gzip, deflate and br are all decoded, headers + * unchanged). Bun honors `decompress: false` (raw bytes + truthful header), so + * no normalization is needed there. + */ +const FETCH_AUTO_DECOMPRESSES = typeof Bun === "undefined"; + +/** Content codings a `FETCH_AUTO_DECOMPRESSES` runtime inflates transparently. */ +const AUTO_DECODED_ENCODINGS = new Set(["gzip", "x-gzip", "deflate", "br"]); + +/** + * Strip `content-encoding`/`content-length` from a Response whose body the + * runtime fetch has ALREADY inflated. Without this, passthrough on Node would + * forward a decoded body still labeled `content-encoding: gzip` โ€” clients that + * advertise gzip then fail to decompress it, and the `passthroughResponse` + * safety net would double-decompress an already-inflated stream for clients + * that don't. No-op for encodings the runtime leaves untouched. Returns a new + * Response because a fetch Response's headers can be immutable. + */ +export function stripAutoDecodedEncoding(resp: Response): Response { + const encoding = resp.headers.get("content-encoding")?.toLowerCase().trim() ?? ""; + if (!encoding) return resp; + const codings = encoding.split(",").map((c) => c.trim()); + if (!codings.every((c) => AUTO_DECODED_ENCODINGS.has(c))) return resp; + const headers = new Headers(resp.headers); + headers.delete("content-encoding"); + headers.delete("content-length"); + return new Response(resp.body, { + status: resp.status, + statusText: resp.statusText, + headers, + }); +} + +async function sendUpstreamRequest( + upstreamReq: Request, + headerPairs: UpstreamHeaderPair[], + body: string | undefined, + translateMode: boolean, + useOrderedTransport: boolean, + fetchImpl: typeof fetch, + abortSignal?: AbortSignal, + hasCustomFetchImpl = false, +): Promise { + if (useOrderedTransport) { + return sendOrderedUpstreamRequest({ + url: upstreamReq.url, + method: upstreamReq.method, + headers: headerPairs, + body, + decompress: translateMode, + signal: abortSignal, + }); + } + const fetchOpts: RequestInit & { decompress?: boolean } = translateMode ? {} : { decompress: false }; + if (abortSignal) fetchOpts.signal = abortSignal; + const resp = await fetchImpl(upstreamReq, fetchOpts); + // Passthrough on a runtime whose fetch auto-decompresses (Node/undici in the + // Android bundle): the body arrives inflated while its headers still claim + // compression. Drop the stale labels so the body/header pairing downstream + // stays truthful. Skipped for injected fetch impls (tests) โ€” their bodies are + // genuinely compressed and their decompression semantics are their own. + if (!translateMode && FETCH_AUTO_DECOMPRESSES && !hasCustomFetchImpl) { + return stripAutoDecodedEncoding(resp); + } + return resp; +} + +/** + * Read the request body as a string, returning undefined for empty bodies. + * Transparently inflates `content-encoding: gzip` request bodies (the OpenAI / + * Anthropic upstreams accept gzipped request bodies; without this, clients + * that send them got a misleading "body is not valid JSON" 400). Corrupt gzip + * throws a descriptive Error; inflation past `MAX_INFLATED_BODY_BYTES` throws + * `InflatedBodyTooLargeError` (streamed + aborted early, so a small wire + * payload cannot expand into unbounded proxy memory). + */ +export async function readBody(req: Request): Promise { + if (req.method === "GET" || req.method === "HEAD") return undefined; + const bytes = new Uint8Array(await req.arrayBuffer()); + if (bytes.byteLength === 0) return undefined; + const encoding = req.headers.get("content-encoding")?.toLowerCase().trim() ?? ""; + if (encoding === "gzip" || encoding === "x-gzip") { + return new TextDecoder().decode(await inflateGzipBody(bytes)); + } + return new TextDecoder().decode(bytes); +} + +/** + * Decompressed-size ceiling for gzip request bodies. Generous by design: + * plain bodies on `/v1/*` routes are intentionally uncapped (long-context LLM + * requests reach several MB), so this only rejects pathological amplification. + */ +const MAX_INFLATED_BODY_BYTES = 64 * 1024 * 1024; + +/** Thrown when a gzip request body expands past MAX_INFLATED_BODY_BYTES. */ +export class InflatedBodyTooLargeError extends Error { + constructor(limit: number) { + super(`gzip request body exceeds ${limit} bytes after decompression`); + this.name = "InflatedBodyTooLargeError"; + } +} + +async function inflateGzipBody(bytes: Uint8Array): Promise { + const result = await inflateWithCap(bytes, MAX_INFLATED_BODY_BYTES); + if (!result.ok) { + if (result.reason === "too_large") throw new InflatedBodyTooLargeError(MAX_INFLATED_BODY_BYTES); + throw new Error(`request body is marked content-encoding: gzip but failed to decompress: ${result.detail}`); + } + return result.bytes; +} + +/** + * Create a passthrough response that streams the upstream body to the client. + * Preserves status and the allowlisted headers, and honors the client's + * `Accept-Encoding` for gzip. + * + * The upstream request FORWARDS the client's `accept-encoding` (only + * defaulting to "gzip" when the client sent none โ€” see + * `buildUpstreamHeaderPairs`), so the upstream compresses only when the + * client can decode it. If THIS client did not advertise gzip but the body + * arrived gzip-compressed anyway, we decompress before forwarding and drop + * the now-mismatched `content-encoding`/`content-length` headers โ€” otherwise + * clients whose HTTP stack does not auto-decompress (e.g. some Tauri-based + * clients) receive raw gzip bytes and fail to parse the JSON body with + * "non-JSON body" errors despite a 200 status. + */ +function passthroughResponse( + upstream: Response, + clientAcceptsGzip: boolean, + body?: ReadableStream, +): Response { + const headers = new Headers(); + const forwardHeaders = [ + "content-type", + "content-encoding", + "cache-control", + "x-request-id", + "anthropic-ratelimit-requests-limit", + "anthropic-ratelimit-requests-remaining", + "anthropic-ratelimit-requests-reset", + "anthropic-ratelimit-tokens-limit", + "anthropic-ratelimit-tokens-remaining", + "anthropic-ratelimit-tokens-reset", + ]; + + for (const h of forwardHeaders) { + const v = upstream.headers.get(h); + if (v) headers.set(h, v); + } + + const upstreamEncoding = headers.get("content-encoding")?.toLowerCase() ?? ""; + const source = body ?? upstream.body; + if (upstreamEncoding.includes("gzip") && !clientAcceptsGzip && source) { + const gunzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair; + const decompressed = source.pipeThrough(gunzip); + headers.delete("content-encoding"); + headers.delete("content-length"); + return new Response(decompressed, { + status: upstream.status, + statusText: upstream.statusText, + headers, + }); + } + + return new Response(source, { + status: upstream.status, + statusText: upstream.statusText, + headers, + }); +} + +/** Build a JSON error response. */ +export function errorResponse(status: number, type: string, message: string): Response { + const body = JSON.stringify({ + error: { type, message }, + }); + return new Response(body, { + status, + headers: { "content-type": "application/json" }, + }); +} + +/** Translate an OpenAI request body string to Anthropic JSON. Returns error Response on failure. */ +function translateOpenAIBody(body: string | undefined): Response | string | undefined { + if (body === undefined || body.length === 0) { + return errorResponse(400, "translation_failed", "OpenAI request body is empty; cannot translate."); + } + let parsed: unknown; + try { + parsed = JSON.parse(body); + } catch (err) { + return errorResponse(400, "translation_failed", `OpenAI request body is not valid JSON: ${(err as Error).message}`); + } + try { + const translated = translateRequestOpenAIToAnthropic(parsed as OpenAIChatRequest); + return JSON.stringify(translated); + } catch (err) { + return errorResponse(400, "translation_failed", `OpenAIโ†’Anthropic translation failed: ${(err as Error).message}`); + } +} + +/** True when the client request explicitly accepts gzip (and has not disabled it via q=0). */ +function clientAcceptsGzip(req: Request): boolean { + const ae = req.headers.get("accept-encoding"); + if (!ae) return false; + return /\bgzip\b(?!\s*;\s*q=0(?:\.0+)?\s*(?:,|$))/i.test(ae); +} + +/** Build a translated batch (non-streaming) OpenAI response. Gzip if client accepts. */ +async function translatedBatchResponse( + clientReq: Request, + upstream: Response, + model: string, + reqId: string, + format: Format, + meta: RequestMeta, + started: number, + headersAt: number, +): Promise { + const raw = await upstream.text(); + let parsedAnthropic: AnthropicMessagesResponse; + try { + parsedAnthropic = JSON.parse(raw) as AnthropicMessagesResponse; + } catch (err) { + printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0); + return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`); + } + if (!isAnthropicMessagesResponse(parsedAnthropic)) { + printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0); + return errorResponse(502, "translation_failed", `upstream returned invalid Anthropic message: ${raw.slice(0, 200)}`); + } + const openaiResp = translateResponseAnthropicToOpenAI(parsedAnthropic, model); + const json = JSON.stringify(openaiResp); + const payload = new TextEncoder().encode(json); + + const respHeaders = new Headers(); + respHeaders.set("content-type", "application/json"); + for (const h of forwardedUpstreamHeaders()) { + const v = upstream.headers.get(h); + if (v) respHeaders.set(h, v); + } + + if (clientAcceptsGzip(clientReq)) { + respHeaders.set("content-encoding", "gzip"); + printRow(reqId, format, meta, upstream.status, started, headersAt, openaiResp.usage?.completion_tokens ?? 0, 0, 0); + return new Response(gzipSync(payload), { + status: upstream.status, + headers: respHeaders, + }); + } + printRow(reqId, format, meta, upstream.status, started, headersAt, openaiResp.usage?.completion_tokens ?? 0, 0, 0); + return new Response(payload, { + status: upstream.status, + headers: respHeaders, + }); +} + +async function translatedOpenAIToAnthropicBatchResponse( + clientReq: Request, + upstream: Response, + reqId: string, + format: Format, + meta: RequestMeta, + started: number, + headersAt: number, +): Promise { + const raw = await upstream.text(); + let parsedOpenAI: OpenAIChatResponse; + try { + parsedOpenAI = JSON.parse(raw) as OpenAIChatResponse; + } catch (err) { + printRow(reqId, format, meta, 502, started, headersAt, 0, 0, 0); + return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`); + } + const anthropicResp = translateResponseOpenAIToAnthropic(parsedOpenAI); + const json = JSON.stringify(anthropicResp); + const payload = new TextEncoder().encode(json); + + const respHeaders = new Headers(); + respHeaders.set("content-type", "application/json"); + for (const h of forwardedUpstreamHeaders()) { + const v = upstream.headers.get(h); + if (v) respHeaders.set(h, v); + } + + if (clientAcceptsGzip(clientReq)) { + respHeaders.set("content-encoding", "gzip"); + printRow(reqId, format, meta, upstream.status, started, headersAt, anthropicResp.usage.output_tokens, 0, 0); + return new Response(gzipSync(payload), { + status: upstream.status, + headers: respHeaders, + }); + } + printRow(reqId, format, meta, upstream.status, started, headersAt, anthropicResp.usage.output_tokens, 0, 0); + return new Response(payload, { + status: upstream.status, + headers: respHeaders, + }); +} + +function translateAnthropicBody(body: string | undefined): Response | string | undefined { + if (body === undefined || body.length === 0) { + return errorResponse(400, "translation_failed", "Anthropic request body is empty; cannot translate."); + } + let parsed: unknown; + try { + parsed = JSON.parse(body); + } catch (err) { + return errorResponse(400, "translation_failed", `Anthropic request body is not valid JSON: ${(err as Error).message}`); + } + try { + const translated = translateRequestAnthropicToOpenAI(parsed as AnthropicMessagesRequest); + return JSON.stringify(translated); + } catch (err) { + return errorResponse(400, "translation_failed", `Anthropicโ†’OpenAI translation failed: ${(err as Error).message}`); + } +} + +function isAnthropicMessagesResponse(value: unknown): value is AnthropicMessagesResponse { + if (typeof value !== "object" || value === null) return false; + const candidate = value as Partial; + return candidate.type === "message" && candidate.role === "assistant" && Array.isArray(candidate.content); +} + +function forwardedUpstreamHeaders(): string[] { + return [ + "x-request-id", + "anthropic-ratelimit-requests-limit", + "anthropic-ratelimit-requests-remaining", + "anthropic-ratelimit-requests-reset", + "anthropic-ratelimit-tokens-limit", + "anthropic-ratelimit-tokens-remaining", + "anthropic-ratelimit-tokens-reset", + ]; +} + +function translatedSseResponse(body: ReadableStream): Response { + return new Response(body, { + status: 200, + headers: { + "content-type": "text/event-stream", + "cache-control": "no-cache", + }, + }); +} + +interface RequestMeta { + model: string; + stream: boolean; +} + +function peekBody(body: string | undefined): RequestMeta { + if (!body) return { model: "-", stream: false }; + try { + const p = JSON.parse(body) as Record; + return { + model: typeof p.model === "string" ? p.model : "-", + stream: p.stream === true, + }; + } catch { + return { model: "-", stream: false }; + } +} + +let reqCounter = 0; +let headerPrinted = false; + +/** Format a unix-ms timestamp as local HH:MM:SS in the host's timezone (not UTC). */ +function localTime(ms: number): string { + const d = new Date(ms); + const hh = String(d.getHours()).padStart(2, "0"); + const mm = String(d.getMinutes()).padStart(2, "0"); + const ss = String(d.getSeconds()).padStart(2, "0"); + return `${hh}:${mm}:${ss}`; +} + +function nextReqId(): string { + return `#${String(++reqCounter).padStart(3, "0")}`; +} + +const DEBUG_BODY_PREVIEW = 200; +const SENSITIVE_HEADERS = new Set(["authorization", "x-api-key", "cookie", "set-cookie", "proxy-authorization"]); + +function debugLine(reqId: string, msg: string): void { + console.log(`${reqId} debug: ${msg}`); +} + +function debugError(reqId: string, kind: string, msg: string): void { + console.log(`${reqId} debug: ERROR ${kind}: ${msg}`); +} + +function redactHeaderVal(key: string, val: string): string { + const k = key.toLowerCase(); + if (!SENSITIVE_HEADERS.has(k)) return val; + if (k === "authorization") { + const sp = val.indexOf(" "); + return sp > 0 ? `${val.slice(0, sp)} ` : ""; + } + if (val.length <= 10) return ""; + return `${val.slice(0, 6)}...${val.slice(-4)}`; +} + +function formatHeaderPairs(headers: Headers): string { + const pairs: string[] = []; + for (const [k, v] of headers.entries()) { + pairs.push(`${k}=${redactHeaderVal(k, v)}`); + } + return pairs.join(" "); +} + +function formatResponseHeaders(headers: Headers): string { + const interesting = [ + "content-type", + "content-encoding", + "content-length", + "x-request-id", + "anthropic-ratelimit-requests-remaining", + "anthropic-ratelimit-tokens-remaining", + ]; + const pairs: string[] = []; + for (const h of interesting) { + const v = headers.get(h); + if (v) pairs.push(`${h}=${v}`); + } + return pairs.length > 0 ? pairs.join(" ") : "(no notable headers)"; +} + +function previewBody(body: string): string { + const flat = body.replace(/\s+/g, " ").trim(); + if (flat.length <= DEBUG_BODY_PREVIEW) return flat; + return `${flat.slice(0, DEBUG_BODY_PREVIEW)}โ€ฆ(${flat.length} bytes total)`; +} + +const COMPACT_LOG = process.env.ZCODE_LOG_FORMAT === "compact"; + +function printHeader(): void { + if (headerPrinted) return; + headerPrinted = true; + if (COMPACT_LOG) return; + console.log( + "| # | Time | Fmt | Model | Mode | Stat | TTFB | Tok | tok/s | Total |", + ); + console.log( + "|------|------------|-----|-------------|--------|------|---------|-------|--------|---------|", + ); +} + +function printRow( + reqId: string, + format: Format, + meta: RequestMeta, + status: number, + started: number, + headersAt: number, + tokens: number, + avgTps: number, + streamEndAt: number, +): void { + printHeader(); + const tag = format === "anthropic" ? "ANT" : "OAI"; + const mode = meta.stream ? "stream" : "batch"; + + if (COMPACT_LOG) { + const ttfbMs = headersAt - started; + const totalMs = streamEndAt > started ? streamEndAt - started : ttfbMs; + const ttfbStr = fmtMs(ttfbMs); + const tokStr = tokens > 0 ? `${tokens}tok` : ""; + const tpsStr = avgTps > 0 ? `${avgTps.toFixed(0)}t/s` : ""; + const parts = [reqId, tag, meta.model, String(status), mode]; + if (meta.stream && streamEndAt > started) { + parts.push(`${ttfbStr}โ†’${fmtMs(totalMs)}`); + } else { + parts.push(ttfbStr); + } + if (tokStr) parts.push(tokStr); + if (tpsStr) parts.push(tpsStr); + console.log(parts.join(" ")); + return; + } + + const ts = localTime(started); + const ttfb = `${headersAt - started}ms`; + const total = streamEndAt > started ? `${streamEndAt - started}ms` : "-"; + const tok = tokens > 0 ? String(tokens) : "-"; + const tps = avgTps > 0 ? avgTps.toFixed(1) : "-"; + console.log( + `| ${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)} |`, + ); +} + +function fmtMs(ms: number): string { + if (ms < 1000) return `${ms}ms`; + if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`; + return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`; +} + +function observeStream( + reqId: string, + format: Format, + meta: RequestMeta, + status: number, + requestSentAt: number, + body: ReadableStream, + contentEncoding: string | null, +): void { + const compressed = contentEncoding !== null; + const dumpOn = dumpEnabled(); + let tokens = 0; + let sseBuffer = ""; + let firstChunkAt = 0; + let totalBytes = 0; + let firstBytesSample = ""; + + function parseSse(text: string): void { + for (const line of text.split("\n")) { + if (!line.startsWith("data:") || line.includes("[DONE]")) continue; + try { + const j = JSON.parse(line.slice(5).trim()); + if (j.usage?.completion_tokens) { tokens = j.usage.completion_tokens; continue; } + if (j.usage?.output_tokens) { tokens = j.usage.output_tokens; continue; } + // OpenAI content delta: choices[0].delta.content + const oai = j.choices?.[0]?.delta?.content; + if (typeof oai === "string" && oai.length > 0) { tokens++; continue; } + // Anthropic content delta: type=content_block_delta, delta.type=text_delta + if (j.type === "content_block_delta" && j.delta?.type === "text_delta") { + const t = j.delta?.text; + if (typeof t === "string" && t.length > 0) tokens++; + } + } catch {} + } + } + + (async () => { + const reader = body.getReader(); + const decoder = new TextDecoder(); + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + if (firstChunkAt === 0) firstChunkAt = Date.now(); + if (dumpOn && value) { + totalBytes += value.byteLength; + if (firstBytesSample.length < 4096) { + firstBytesSample += decoder.decode(value.slice(0, 4096 - firstBytesSample.length), { stream: true }); + } + } + if (!compressed) { + sseBuffer += decoder.decode(value, { stream: true }); + const idx = sseBuffer.lastIndexOf("\n"); + if (idx >= 0) { + parseSse(sseBuffer.slice(0, idx)); + sseBuffer = sseBuffer.slice(idx + 1); + } + } + } + if (!compressed && sseBuffer) parseSse(sseBuffer); + } catch {} + const endAt = Date.now(); + const ttfbMs = (firstChunkAt > 0 ? firstChunkAt : endAt) - requestSentAt; + const totalMs = endAt - requestSentAt; + const avgTps = tokens > 0 && totalMs > 0 ? tokens / (totalMs / 1000) : 0; + printRow(reqId, format, meta, status, requestSentAt, requestSentAt + ttfbMs, tokens, avgTps, endAt); + if (dumpOn) { + dumpPhase(reqId, "upstream_stream_summary", { + status, + contentEncoding, + compressed, + totalBytes, + tokensObserved: tokens, + ttfbMs, + totalMs, + firstBytesSample: firstBytesSample.length > 0 ? firstBytesSample.slice(0, 4096) : "(empty stream)", + }); + } + })().catch(() => {}); +} diff --git a/src/proxy/identity.ts b/src/proxy/identity.ts new file mode 100644 index 0000000000000000000000000000000000000000..5508aa13d73c629f0a2a4b51ff05c2803505ea1e --- /dev/null +++ b/src/proxy/identity.ts @@ -0,0 +1,195 @@ +/** + * Identity header builders โ€” emit the ZCode desktop client's companion + * headers so the proxy is indistinguishable from the official client at the + * fingerprinting layer. + * + * TWO distinct bundle functions are mirrored (ZCode 3.11.2, `_reverse/zcode.cjs`): + * + * 1. `csn` = buildCliZCodeSourceHeaders (CLI LLM path, wrapped by `x4i` + * which appends `X-ZCode-Agent: "glm"` as the LAST header) โ€” used for + * every LLM completion request โ†’ {@link buildLlmIdentityHeaders}. + * Shape: HTTP-Referer, User-Agent, [X-ZCode-App-Version], X-Title, + * X-Release-Channel (always), X-Client-Language (always, "unknown" + * fallback), X-Client-Timezone (always, "unknown" fallback), + * [X-Platform], X-Os-Category (when platform resolves), [X-Os-Version], + * X-ZCode-Agent ("glm", last). NO X-Device-Mid โ€” the CLI LLM path never + * carried it. + * + * 2. `HRt` = buildZCodeSourceHeadersFromContext (host-side control-plane + * fetches: endpoint-routing configs, signing gate, claim/billing) โ€” + * used by {@link buildIdentityHeaders}. Shape keeps the historical + * `pio`-derived order with conditional language/timezone and the + * optional X-Device-Mid (server-required on the claim/billing plane + * since the 0828 campaign). Consumers: endpoint-routing.ts, + * client-signing.ts, claim/client.ts, routes-quota.ts, async bridge. + * + * Both gate header values through the bundle's `fio` printable-ASCII rule; + * `n = fio(...)` validates appVersion and, when it fails, drops + * X-ZCode-App-Version entirely and falls the User-Agent back to + * `ZCode/unknown`. + * + * Runtime values are read via env overrides (matching the existing + * ZCODE_IDENTITY_PLATFORM/ARCH/RELEASE pattern) so the Android entry can emit + * desktop-Linux identity without changing this module: + * - ZCODE_IDENTITY_RELEASE_CHANNEL + * - ZCODE_IDENTITY_CLIENT_LANGUAGE (default: Intl locale, e.g. "zh-CN") + * - ZCODE_IDENTITY_CLIENT_TIMEZONE (default: Intl timezone, e.g. "Asia/Shanghai") + * - ZCODE_IDENTITY_DEVICE_MID (no default; omitted unless set) + * + * @see _reverse/NOTEPAD.md "How Credential is Used for LLM Calls" + */ +import os from "node:os"; +import type { ProxyIdentity } from "../config/types.js"; + +/** Printable-ASCII gate copied from the ZCode bundle's `fio` helper. */ +const ASCII_PRINTABLE = /^[\x20-\x7e]+$/; + +/** Resolve the appVersion the way `fio` does: trimmed + printable ASCII, else undefined. */ +function resolveAppVersion(raw: string | undefined): string | undefined { + if (typeof raw !== "string") return undefined; + const v = raw.trim(); + return v.length > 0 && ASCII_PRINTABLE.test(v) ? v : undefined; +} + +/** Normalize a header value: trimmed + printable ASCII, else undefined. */ +export function normalizePrintableHeaderValue(raw: string | undefined): string | undefined { + if (typeof raw !== "string") return undefined; + const v = raw.trim(); + return v.length > 0 && ASCII_PRINTABLE.test(v) ? v : undefined; +} + +function normalizeOsCategory(platform: NodeJS.Platform): string { + switch (platform) { + case "darwin": + return "macos"; + case "win32": + return "windows"; + default: + return "linux"; + } +} + +/** Mirrors the bundle's `lsa()` / `V8i()`: Intl locale, wrapped in try/catch. */ +function resolveClientLanguage(): string | undefined { + const override = normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_CLIENT_LANGUAGE); + if (override) return override; + try { + return Intl.DateTimeFormat().resolvedOptions().locale || undefined; + } catch { + return undefined; + } +} + +/** Mirrors the bundle's `csa()`: Intl timezone, wrapped in try/catch. */ +function resolveClientTimezone(): string | undefined { + const override = normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_CLIENT_TIMEZONE); + if (override) return override; + try { + return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined; + } catch { + return undefined; + } +} + +interface ResolvedIdentityValues { + n?: string; + platform?: string; + platformForCategory: NodeJS.Platform; + arch?: string; + release?: string; + releaseChannel: string; + clientLanguage?: string; + clientTimezone?: string; + deviceMid?: string; +} + +/** Shared env/config resolution for both builders (values only โ€” ordering differs per builder). */ +function resolveIdentityValues(id: ProxyIdentity): ResolvedIdentityValues { + // Env overrides (ZCODE_IDENTITY_PLATFORM/ARCH/RELEASE) let the Android entry + // emit desktop-Linux identity headers without changing this module. + return { + n: resolveAppVersion(id.appVersion), + platform: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_PLATFORM ?? process.platform), + platformForCategory: (process.env.ZCODE_IDENTITY_PLATFORM ?? process.platform) as NodeJS.Platform, + arch: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_ARCH ?? os.arch()), + release: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_RELEASE ?? os.release()), + // bundle IL(): ZCODE_ENV==="test" ? "test" : "production" โ€” always resolves. + // Mirror that default; ZCODE_IDENTITY_RELEASE_CHANNEL stays an explicit override. + releaseChannel: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_RELEASE_CHANNEL) + ?? (process.env.ZCODE_ENV?.trim().toLowerCase() === "test" ? "test" : "production"), + clientLanguage: resolveClientLanguage(), + clientTimezone: resolveClientTimezone(), + // env (Android NodeRunner injection) wins over the config.yaml value (desktop + // persistence) โ€” both are UUIDv4 generated once and reused forever. + deviceMid: normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_DEVICE_MID) + ?? normalizePrintableHeaderValue(id.deviceMid), + }; +} + +/** + * Identity headers for LLM completion requests โ€” mirrors the bundle's CLI + * source-headers builder `csn` (buildCliZCodeSourceHeaders) + the `x4i` + * wrapper that appends `X-ZCode-Agent: "glm"` LAST. Differences vs the + * control-plane set (buildIdentityHeaders): language/timezone are ALWAYS + * emitted (falling back to "unknown"), X-Release-Channel sits right after + * X-Title, X-ZCode-Agent is the final header, and X-Device-Mid is NEVER sent. + * Pure function. + */ +export function buildLlmIdentityHeaders(id: ProxyIdentity): Record { + const v = resolveIdentityValues(id); + return { + "HTTP-Referer": id.refererOrigin, + "User-Agent": `ZCode/${v.n ?? "unknown"}`, + ...(v.n ? { "X-ZCode-App-Version": v.n } : {}), + "X-Title": `Z Code@${id.sourceTitle}`, + "X-Release-Channel": v.releaseChannel, + "X-Client-Language": v.clientLanguage ?? "unknown", + "X-Client-Timezone": v.clientTimezone ?? "unknown", + ...(v.platform && v.arch ? { "X-Platform": `${v.platform}-${v.arch}` } : {}), + ...(v.platform ? { "X-Os-Category": normalizeOsCategory(v.platformForCategory) } : {}), + ...(v.release ? { "X-Os-Version": v.release } : {}), + "X-ZCode-Agent": "glm", + }; +} + +/** + * Control-plane identity headers โ€” mirrors the host-side bundle builder + * `HRt` (buildZCodeSourceHeadersFromContext), reached us via the historical + * `pio` shape. Used by endpoint-routing, client-signing gate, claim/billing + * and the async bridge โ€” NOT for LLM completion requests (use + * {@link buildLlmIdentityHeaders} there). + * + * Order (with X-ZCode-Agent kept between X-Title and X-Platform): + * HTTP-Referer, User-Agent, [X-ZCode-App-Version], X-Title, X-ZCode-Agent, + * [X-Platform], [X-Release-Channel], [X-Client-Language], [X-Client-Timezone], + * [X-Os-Category], [X-Os-Version], [X-Device-Mid] + * + * Returns `Record` rather than a fixed interface because + * several headers are conditionally omitted. + */ +export function buildIdentityHeaders(id: ProxyIdentity): Record { + const v = resolveIdentityValues(id); + return { + "HTTP-Referer": id.refererOrigin, + "User-Agent": `ZCode/${v.n ?? "unknown"}`, + ...(v.n ? { "X-ZCode-App-Version": v.n } : {}), + "X-Title": `Z Code@${id.sourceTitle}`, + "X-ZCode-Agent": "glm", + ...(v.platform && v.arch ? { "X-Platform": `${v.platform}-${v.arch}` } : {}), + ...(v.releaseChannel ? { "X-Release-Channel": v.releaseChannel } : {}), + ...(v.clientLanguage ? { "X-Client-Language": v.clientLanguage } : {}), + ...(v.clientTimezone ? { "X-Client-Timezone": v.clientTimezone } : {}), + ...(v.platform ? { "X-Os-Category": normalizeOsCategory(v.platformForCategory) } : {}), + ...(v.release ? { "X-Os-Version": v.release } : {}), + ...(v.deviceMid ? { "X-Device-Mid": v.deviceMid } : {}), + }; +} + +/** + * Cache key for process-wide singletons that embed a `ProxyIdentity` + * (endpoint routing, client signing): two configs producing the same key can + * share the same service instance. + */ +export function identityCacheKey(identity: ProxyIdentity): string { + return JSON.stringify([identity.appVersion, identity.sourceTitle, identity.refererOrigin, identity.deviceMid ?? ""]); +} diff --git a/src/proxy/inflate.ts b/src/proxy/inflate.ts new file mode 100644 index 0000000000000000000000000000000000000000..6b94607c69c442ae63641c0478d7ae68458edfa5 --- /dev/null +++ b/src/proxy/inflate.ts @@ -0,0 +1,53 @@ +/** + * Shared bounded gzip inflation for request bodies (audit CL-17). + * + * Two call sites used to carry byte-for-byte copies of this + * DecompressionStream+reader+cancel loop (proxy/handler.ts and + * async/handler.ts); fixes to one never reached the other. The callers keep + * their own limits and error contracts โ€” this helper only performs the + * bounded inflation and reports the outcome. + */ + +export type InflateResult = + | { ok: true; bytes: Uint8Array } + | { ok: false; reason: "too_large" } + | { ok: false; reason: "corrupt"; detail: string }; + +/** + * Inflate `bytes` as gzip, reading at most `limitBytes` of DECOMPRESSED + * output. The stream is cancelled and the reader lock released as soon as + * the limit trips (a small wire payload cannot expand into unbounded + * memory), and on any decode error. + * + * `too_large` carries no detail by design โ€” callers embed their own limit in + * the user-facing message. + */ +export async function inflateWithCap(bytes: Uint8Array, limitBytes: number): Promise { + const gunzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair; + const source = new ReadableStream({ + start(controller) { + controller.enqueue(bytes); + controller.close(); + }, + }); + const reader = source.pipeThrough(gunzip).getReader(); + const parts: Uint8Array[] = []; + let total = 0; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) break; + total += value.byteLength; + if (total > limitBytes) { + await reader.cancel().catch(() => {}); + return { ok: false, reason: "too_large" }; + } + parts.push(value); + } + return { ok: true, bytes: Buffer.concat(parts) }; + } catch (err) { + return { ok: false, reason: "corrupt", detail: (err as Error).message }; + } finally { + reader.releaseLock?.(); + } +} diff --git a/src/proxy/ordered-transport.ts b/src/proxy/ordered-transport.ts new file mode 100644 index 0000000000000000000000000000000000000000..b3dffb6c4dc69ad399557ed50cd215d22fb54d2b --- /dev/null +++ b/src/proxy/ordered-transport.ts @@ -0,0 +1,297 @@ +import { connect as connectTcp, type Socket } from "node:net"; +import { connect as connectTls, type TLSSocket } from "node:tls"; + +export type OrderedHeaderPair = [string, string]; + +export interface OrderedUpstreamRequest { + url: string; + method?: string; + headers: OrderedHeaderPair[]; + body?: string | Uint8Array; + decompress?: boolean; + /** Client abort signal โ€” destroys the socket the moment the client aborts. */ + signal?: AbortSignal; +} + +type WireSocket = Socket | TLSSocket; + +const CRLF = "\r\n"; +const HEADER_END = new Uint8Array([13, 10, 13, 10]); +const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/; + +export async function sendOrderedUpstreamRequest(req: OrderedUpstreamRequest): Promise { + const url = new URL(req.url); + const bodyBytes = bodyToBytes(req.body); + const requestHead = buildRequestHead(url, req.method ?? "POST", req.headers, bodyBytes.byteLength); + const socket = await openSocket(url); + + return await new Promise((resolve, reject) => { + let headerBuffer: Uint8Array = new Uint8Array(0); + let responseStarted = false; + let postWrite = false; + let bodyController: ReadableStreamDefaultController | null = null; + let chunkedDecoder: ChunkedDecoder | null = null; + let remainingContentLength: number | null = null; + + const bodyStream = new ReadableStream({ + start(controller) { + bodyController = controller; + }, + cancel() { + socket.destroy(); + }, + }); + + function fail(err: unknown): void { + if (!responseStarted && postWrite) { + // Review follow-up #2 (PR #34): the full request (head + body) was + // already written to the wire, so the upstream may have processed it + // โ€” resending could duplicate the LLM call and consume quota twice. + // Flag it so the connect-retry loop in handler.ts skips this error. + try { (err as { postWrite?: boolean }).postWrite = true; } catch {} + } + if (responseStarted) { + // Safe by spec: error() on an already-closed/errored ReadableStream + // controller is a NO-OP under WHATWG Streams semantics (only close() + // and enqueue() throw on a closed controller) โ€” verified against both + // Bun and Node. The unguarded call below is intentional; do not wrap + // it (audit CL-01: triple-verified non-issue, closed). + bodyController?.error(err); + } else { + reject(err); + } + socket.destroy(); + } + + // Abort propagation (CL-04): destroy the socket the moment the client + // aborts. Without this the upstream LLM call kept running (consuming + // quota for the whole generation) after the client disappeared during a + // long-TTFB reasoning request. `fail()` both rejects this promise (a bare + // destroy() emits "close", not "error"/"end", and would leave it pending + // forever) and errors the consumer-side body stream when the response has + // already started. The resulting error carries `postWrite` (the request + // is fully on the wire by then), so handler's connect-retry ladder skips + // it โ€” combined with the `clientReq.signal.aborted` pre-check there, + // client aborts never enter the retry loop. + if (req.signal) { + const signal = req.signal; + const onAbort = (): void => { + fail(new Error("client aborted during ordered upstream request")); + }; + if (signal.aborted) { + onAbort(); + return; + } + signal.addEventListener("abort", onAbort, { once: true }); + // De-register when the socket settles so a signal that outlives this + // request (the handler reuses the client signal across connect + // attempts) does not accumulate listeners. + socket.once("close", () => signal.removeEventListener("abort", onAbort)); + } + + function finish(): void { + if (chunkedDecoder && !chunkedDecoder.done) { + try { bodyController?.error(new Error("upstream chunked body truncated")); } catch {} + socket.destroy(); + return; + } + try { bodyController?.close(); } catch {} + } + + function pushBody(bytes: Uint8Array): void { + if (!bodyController || bytes.byteLength === 0) return; + if (chunkedDecoder) { + chunkedDecoder.push(bytes, bodyController); + if (chunkedDecoder.done) finish(); + return; + } + if (remainingContentLength !== null) { + const next = bytes.slice(0, remainingContentLength); + remainingContentLength -= next.byteLength; + if (next.byteLength > 0) bodyController.enqueue(next); + if (remainingContentLength === 0) finish(); + return; + } + bodyController.enqueue(bytes); + } + + socket.on("data", (chunk: Buffer) => { + try { + const bytes = new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength); + if (!responseStarted) { + headerBuffer = concatBytes(headerBuffer, bytes); + const headerEnd = indexOfBytes(headerBuffer, HEADER_END); + if (headerEnd < 0) return; + + const headerBytes = headerBuffer.slice(0, headerEnd); + const rest = headerBuffer.slice(headerEnd + HEADER_END.byteLength); + const parsed = parseResponseHeaders(headerBytes); + responseStarted = true; + + const transferEncoding = parsed.headers.get("transfer-encoding")?.toLowerCase() ?? ""; + if (transferEncoding.split(",").map((s) => s.trim()).includes("chunked")) { + parsed.headers.delete("transfer-encoding"); + chunkedDecoder = new ChunkedDecoder(); + } else { + const contentLength = parsed.headers.get("content-length"); + remainingContentLength = contentLength ? Number.parseInt(contentLength, 10) : null; + if (!Number.isFinite(remainingContentLength as number)) remainingContentLength = null; + } + + let responseBody: ReadableStream = bodyStream; + if (req.decompress && parsed.headers.get("content-encoding")?.toLowerCase() === "gzip") { + parsed.headers.delete("content-encoding"); + parsed.headers.delete("content-length"); + const gzip = new DecompressionStream("gzip") as unknown as ReadableWritablePair; + responseBody = bodyStream.pipeThrough(gzip); + } + + resolve(new Response(responseBody, { + status: parsed.status, + statusText: parsed.statusText, + headers: parsed.headers, + })); + pushBody(rest); + return; + } + pushBody(bytes); + } catch (err) { + fail(err); + } + }); + + socket.once("error", fail); + socket.once("end", () => { + if (!responseStarted) { + reject(new Error("upstream closed before sending response headers")); + return; + } + finish(); + }); + + socket.write(requestHead); + if (bodyBytes.byteLength > 0) socket.write(bodyBytes); + postWrite = true; + }); +} + +function openSocket(url: URL): Promise { + const isHttps = url.protocol === "https:"; + if (!isHttps && url.protocol !== "http:") { + return Promise.reject(new Error(`Unsupported upstream protocol: ${url.protocol}`)); + } + const port = Number(url.port || (isHttps ? 443 : 80)); + + return new Promise((resolve, reject) => { + const onConnect = () => { + socket.off("error", reject); + resolve(socket); + }; + const socket: WireSocket = isHttps + ? connectTls({ host: url.hostname, port, servername: url.hostname }, onConnect) + : connectTcp({ host: url.hostname, port }, onConnect); + socket.once("error", reject); + }); +} + +function buildRequestHead(url: URL, method: string, headers: OrderedHeaderPair[], contentLength: number): string { + const path = `${url.pathname || "/"}${url.search}`; + const lines = [ + `${method} ${path} HTTP/1.1`, + `Host: ${url.host}`, + ...headers.map(headerLine), + `Content-Length: ${contentLength}`, + "Connection: close", + "", + "", + ]; + return lines.join(CRLF); +} + +function headerLine([name, value]: OrderedHeaderPair): string { + if (!HEADER_NAME.test(name)) throw new Error(`Invalid upstream header name: ${name}`); + if (/[\r\n]/.test(value)) throw new Error(`Invalid upstream header value for ${name}`); + return `${name}: ${value}`; +} + +function bodyToBytes(body: string | Uint8Array | undefined): Uint8Array { + if (body === undefined) return new Uint8Array(0); + if (typeof body === "string") return new TextEncoder().encode(body); + return body; +} + +function parseResponseHeaders(bytes: Uint8Array): { status: number; statusText: string; headers: Headers } { + const text = new TextDecoder("latin1").decode(bytes); + const lines = text.split(CRLF); + const statusLine = lines.shift() ?? ""; + const match = /^HTTP\/\d(?:\.\d)?\s+(\d{3})(?:\s+(.*))?$/.exec(statusLine); + if (!match) throw new Error(`Invalid upstream status line: ${statusLine}`); + + const headers = new Headers(); + for (const line of lines) { + if (!line) continue; + const idx = line.indexOf(":"); + if (idx <= 0) continue; + headers.append(line.slice(0, idx), line.slice(idx + 1).trimStart()); + } + + return { status: Number(match[1]), statusText: match[2] ?? "", headers }; +} + +class ChunkedDecoder { + private buffer: Uint8Array = new Uint8Array(0); + private expectedSize: number | null = null; + done = false; + + push(bytes: Uint8Array, controller: ReadableStreamDefaultController): void { + if (this.done) return; + this.buffer = concatBytes(this.buffer, bytes); + + while (!this.done) { + if (this.expectedSize === null) { + const lineEnd = indexOfCrlf(this.buffer); + if (lineEnd < 0) return; + const line = new TextDecoder("latin1").decode(this.buffer.slice(0, lineEnd)); + const sizeHex = line.split(";", 1)[0].trim(); + const size = Number.parseInt(sizeHex, 16); + if (!Number.isFinite(size)) throw new Error(`Invalid chunk size: ${line}`); + this.buffer = this.buffer.slice(lineEnd + 2); + this.expectedSize = size; + if (size === 0) { + this.done = true; + return; + } + } + + if (this.buffer.byteLength < this.expectedSize + 2) return; + const chunk = this.buffer.slice(0, this.expectedSize); + controller.enqueue(chunk); + this.buffer = this.buffer.slice(this.expectedSize + 2); + this.expectedSize = null; + } + } +} + +function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array { + const out = new Uint8Array(a.byteLength + b.byteLength); + if (a.byteLength > 0) out.set(a, 0); + if (b.byteLength > 0) out.set(b, a.byteLength); + return out; +} + +function indexOfBytes(haystack: Uint8Array, needle: Uint8Array): number { + outer: for (let i = 0; i <= haystack.byteLength - needle.byteLength; i++) { + for (let j = 0; j < needle.byteLength; j++) { + if (haystack[i + j] !== needle[j]) continue outer; + } + return i; + } + return -1; +} + +function indexOfCrlf(bytes: Uint8Array): number { + for (let i = 0; i < bytes.byteLength - 1; i++) { + if (bytes[i] === 13 && bytes[i + 1] === 10) return i; + } + return -1; +} diff --git a/src/proxy/responses-handler.ts b/src/proxy/responses-handler.ts new file mode 100644 index 0000000000000000000000000000000000000000..db8e19d3051bb520cdec022bb537c64ceea51722 --- /dev/null +++ b/src/proxy/responses-handler.ts @@ -0,0 +1,467 @@ +/** + * POST /v1/responses request handler. + * + * Pipeline: + * 1. Parse body + credential. + * 2. Resolve `previous_response_id` via `ResponseStore` (prepend stored history). + * 3. Translate Responses โ†’ Chat Completions (`responsesToChatCompletions`): + * - function / custom / namespace / tool_search tools โ†’ Chat tools. + * - web_search / web_search_preview / file_search / code_interpreter / + * computer_use / image_generation / mcp โ†’ stripped silently. + * 4. Apply the standard body transform (stream_options, user_id, start-plan system). + * 5. POST to the GLM Chat Completions upstream (reuse `buildUpstreamRequest`). + * 6. Translate the Chat response โ†’ Responses (`chatCompletionsToResponses` + * or `chatChunkToResponsesEvents` for streaming). + * 7. Store the new response under its id (unless `store:false`). + * + * State management: in-memory only (process restart clears the store); see + * `responses/store.ts`. + */ +import { transformRequestBody } from "./body-transformer.js"; +import { getProvider } from "../provider/providers.js"; +import type { ProxyConfig } from "../config/types.js"; +import type { AuthManager } from "../auth/manager.js"; +import { buildUpstreamRequest, buildUpstreamHeaderPairs, type UpstreamHeaderPair } from "./upstream.js"; +import { isCaptchaChallenged, retryOnCaptchaChallenge } from "./captcha-retry.js"; +import { dispatchWithConnectRetry } from "./handler.js"; +import type * as CaptchaExports from "./captcha.js"; + +// Lazy, runtime-gated module load (exception to the static-import rule, same +// as handler.ts): pulling captcha.ts eagerly drags in the happy-dom solver, so +// only start-plan โ€” the one plan whose upstream is captcha-gated โ€” pays for it. +type CaptchaModule = typeof CaptchaExports; +let captchaModule: CaptchaModule | null = null; +async function loadCaptcha(): Promise { + if (!captchaModule) captchaModule = await import("./captcha.js"); + return captchaModule; +} +import { getDefaultEndpointRouting, type EndpointRoutingService } from "./endpoint-routing.js"; +import { getDefaultClientSigning, sendWithClientSigning, type ClientSigningManager } from "./client-signing.js"; +import { credentialString } from "../auth/types.js"; +import { translateRequestOpenAIToAnthropic, translateResponseAnthropicToOpenAI } from "../translator/openai-to-anthropic.js"; +import { anthropicSseToOpenaiSse } from "../translator/sse-translator.js"; +import type { AnthropicMessagesRequest, AnthropicMessagesResponse } from "../translator/types.js"; +import type { ProviderDef } from "../provider/types.js"; +import { + responsesToChatCompletions, + ToolTranslationError, +} from "../translator/responses-to-chat.js"; +import { + chatCompletionsToResponses, + chatChunkToResponsesEvents, + finalizeResponsesStream, + newResponsesStreamState, + responsesEventToSse, +} from "../translator/chat-to-responses.js"; +import { + generateResponsesId, + type ResponsesInputItem, + type ResponsesRequest, + type ResponsesResponse, + type ResponsesStreamEvent, + type ResponsesOutputItem, +} from "../translator/responses-types.js"; +import { ResponseStore, type StoredResponse } from "../responses/store.js"; +import { errorResponse, readBody, InflatedBodyTooLargeError } from "./handler.js"; + +export interface ResponsesHandlerOptions { + config: ProxyConfig; + auth: AuthManager; + /** Response store; if absent, `previous_response_id` always 404s. */ + responseStore?: ResponseStore; + /** DI seam for tests. */ + fetchImpl?: typeof fetch; + /** Verbose per-request diagnostics. */ + debug?: boolean; + /** Override the process-wide endpoint routing service (for testing). `null` disables. */ + endpointRouting?: EndpointRoutingService | null; + /** Override the process-wide client signing manager (for testing). `null` disables. */ + clientSigning?: ClientSigningManager | null; + /** Override the lazily-imported captcha module (for testing). */ + captcha?: CaptchaModule; +} + +/** Handle POST /v1/responses. */ +export async function handleResponses( + clientReq: Request, + opts: ResponsesHandlerOptions, +): Promise { + const fetchImpl = opts.fetchImpl ?? fetch; + const debug = opts.debug === true; + const start = Date.now(); + + // โ”€โ”€ 1. parse body โ”€โ”€ + let rawBody: string; + try { + rawBody = (await readBody(clientReq)) ?? ""; + } catch (err) { + if (err instanceof InflatedBodyTooLargeError) { + return errorResponse(413, "request_too_large", err.message); + } + return errorResponse(400, "invalid_request", `could not read request body: ${(err as Error).message}`); + } + let req: ResponsesRequest; + try { + req = JSON.parse(rawBody) as ResponsesRequest; + } catch (err) { + return errorResponse(400, "invalid_request", `request body is not valid JSON: ${(err as Error).message}`); + } + if (typeof req.input !== "string" && !Array.isArray(req.input)) { + return errorResponse(400, "invalid_request", "`input` must be a string or an array"); + } + if (typeof req.model !== "string" || req.model.length === 0) { + return errorResponse(400, "invalid_request", "`model` is required"); + } + + const stream = req.stream === true; + + // โ”€โ”€ 2. resolve previous_response_id โ”€โ”€ + let historyItems: ResponsesInputItem[] = []; + let prevId: string | undefined; + if (typeof req.previous_response_id === "string" && req.previous_response_id.length > 0) { + if (!opts.responseStore) { + return errorResponse(404, "response_store_disabled", "`previous_response_id` was supplied but the response store is not configured"); + } + const prev = opts.responseStore.get(req.previous_response_id); + if (!prev) { + 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)`); + } + prevId = req.previous_response_id; + historyItems = [...prev.input, ...outputItemsAsInputItems(prev.output)]; + } + + // โ”€โ”€ 3. translate Responses โ†’ Chat Completions โ”€โ”€ + const input: ResponsesInputItem[] = typeof req.input === "string" + ? [...historyItems, { type: "message", role: "user", content: req.input }] + : [...historyItems, ...req.input]; + const reqWithHistory: ResponsesRequest = { + ...req, + input, + }; + let translated; + try { + translated = responsesToChatCompletions(reqWithHistory); + } catch (err) { + if (err instanceof ToolTranslationError) { + return errorResponse(400, "tool_translation_error", err.message); + } + throw err; + } + const { chatRequest, customToolNames, namespaceMap, hasToolSearch } = translated; + + // โ”€โ”€ 4. credential + provider โ”€โ”€ + let cred; + try { + cred = await opts.auth.getCredential(); + } catch (err) { + return errorResponse(503, "credential_unavailable", (err as Error).message); + } + const providerDef = resolveProviderDef(opts.config); + + // โ”€โ”€ 5. body transform (start-plan system / anthropic cache_control + user_id) โ”€โ”€ + // Both plans post Anthropic upstream (mirrors handler.ts): the start-plan + // OpenAI gateway was retired server-side (404 as of 2026-08-28), so the + // Responses โ†’ Chat โ†’ Anthropic translator chain runs unconditionally. + const startPlan = opts.config.plan === "start-plan"; + const upstreamFormat: "openai" | "anthropic" = "anthropic"; + let upstreamRequestBody: string; + { + let anthropicReq: AnthropicMessagesRequest; + try { + anthropicReq = translateRequestOpenAIToAnthropic(chatRequest); + } catch (err) { + return errorResponse(400, "translation_failed", `Chatโ†’Anthropic translation failed: ${(err as Error).message}`); + } + // userId gating mirrors handler.ts: coding-plan injects the OAuth userId, + // start-plan omits it (internal consistency; the bundle is presence-gated + // with no plan concept โ€” whether start-plan should carry it is not + // determinable from _reverse, kept aligned with the sibling path). + upstreamRequestBody = transformRequestBody(JSON.stringify(anthropicReq), { + format: "anthropic", + userId: startPlan ? undefined : cred.userId, + startPlan, + }) ?? JSON.stringify(anthropicReq); + } + const transformedBody = upstreamRequestBody; + + // โ”€โ”€ 6. POST upstream โ”€โ”€ + // start-plan gates every upstream call behind an Aliyun captcha token. The + // Anthropic/OpenAI routes mint one in handler.ts; /v1/responses did not, so + // start-plan users got {"code":3007,"msg":"captcha verify failed"} surfaced + // as HTTP 400 upstream_error on every request. + let captchaHeaders: Record | undefined; + if (startPlan) { + try { + const captcha = opts.captcha ?? (await loadCaptcha()); + const token = await captcha.getCaptchaToken(opts.config.identity.appVersion); + captchaHeaders = { [captcha.RETRY_HEADERS.PARAM]: token.verifyParam, [captcha.RETRY_HEADERS.REGION]: token.region }; + } catch { + // Fall through: the 3007 retry below solves on demand. + } + } + const upstreamHeaders = buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, opts.config.identity, opts.config.plan, captchaHeaders, undefined); + const upstreamReq = buildUpstreamRequest(clientReq, upstreamFormat, providerDef, cred, transformedBody, opts.config.identity, opts.config.plan, captchaHeaders, undefined); + if (debug) console.log(`[responses] โ†’ POST ${upstreamReq.url}`); + + const routing = opts.endpointRouting !== undefined ? opts.endpointRouting : getDefaultEndpointRouting(opts.config); + const signer = opts.clientSigning !== undefined ? opts.clientSigning : getDefaultClientSigning(opts.config); + const dispatch = async (pairs: UpstreamHeaderPair[]): Promise => { + const routed = routing ? await routing.resolve(upstreamReq.url, credentialString(cred)) : null; + const sendUrl = routed?.routed ? routed.url : upstreamReq.url; + if (debug && routed?.routed) console.log(`[responses] endpoint routing: ${upstreamReq.url} -> ${sendUrl}`); + // signing decisions run against the PRE-routing provider URL (mirrors the + // client, whose signer wraps the routing transport) + return sendWithClientSigning(signer, { + url: upstreamReq.url, + headerPairs: pairs, + credential: credentialString(cred), + appVersion: opts.config.identity.appVersion, + debug: debug ? (message) => console.log(`[responses] ${message}`) : undefined, + send: (finalPairs) => { + const req = new Request(sendUrl, { + method: "POST", + headers: Object.fromEntries(finalPairs), + body: transformedBody ?? undefined, + }); + return fetchImpl(req, { method: "POST", headers: Object.fromEntries(finalPairs), body: transformedBody ?? undefined, signal: clientReq.signal }); + }, + }); + }; + + let upstreamResp: Response; + try { + // Connect-retry ladder mirrors the chat hot path (handler.ts): 3 attempts, + // fresh Request per dispatch (built inside `dispatch`), 500msร—attempt + // backoff, no retry once the client aborted. + upstreamResp = await dispatchWithConnectRetry(() => dispatch(upstreamHeaders), { + isAborted: () => clientReq.signal.aborted, + }); + } catch (err) { + return errorResponse(502, "upstream_unreachable", (err as Error).message); + } + + // Captcha challenge retry (mirrors handler.ts via the shared captcha-retry + // seam): the gateway signals it either through the captcha response header + // or as HTTP 400 with {"code":3007} in the body. The challenged token is + // already spent, so retry once with a fresh pooled one. + if (startPlan && !upstreamResp.ok) { + const captcha = opts.captcha ?? (await loadCaptcha()); + if (await isCaptchaChallenged(upstreamResp, captcha)) { + if (debug) console.log("[responses] captcha challenge โ€” re-solving and retrying once"); + const outcome = await retryOnCaptchaChallenge({ + captcha, + appVersion: opts.config.identity.appVersion, + challengedResp: upstreamResp, + debug: debug ? (message) => console.log(`[responses] ${message}`) : undefined, + solveAndRetry: (retryHeaders) => dispatch( + buildUpstreamHeaderPairs(clientReq, upstreamFormat, cred, opts.config.identity, opts.config.plan, retryHeaders, undefined), + ), + mapError: (err, phase) => + phase === "solver" + ? errorResponse(503, "captcha_solver_failed", err.message) + : errorResponse(502, "upstream_unreachable", err.message), + }); + if (!outcome.ok) return outcome.resp; + upstreamResp = outcome.resp; + } + } + + if (!upstreamResp.ok) { + const errText = await upstreamResp.text().catch(() => ""); + return errorResponse(upstreamResp.status, "upstream_error", errText.slice(0, 500) || `upstream returned ${upstreamResp.status}`); + } + + if (upstreamFormat === "anthropic") { + // normalize the Anthropic upstream response into the OpenAI Chat shape the + // downstream Responses translators already consume (SSE + batch) + if (stream) { + if (!upstreamResp.body) { + return errorResponse(502, "translation_failed", "upstream returned no body for stream"); + } + upstreamResp = new Response(anthropicSseToOpenaiSse(upstreamResp.body, req.model), { + status: upstreamResp.status, + headers: { "content-type": "text/event-stream" }, + }); + } else { + const rawAnthropic = await upstreamResp.text(); + let parsedAnthropic: AnthropicMessagesResponse; + try { + parsedAnthropic = JSON.parse(rawAnthropic) as AnthropicMessagesResponse; + } catch (err) { + return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`); + } + const openaiResp = translateResponseAnthropicToOpenAI(parsedAnthropic, req.model); + upstreamResp = new Response(JSON.stringify(openaiResp), { + status: upstreamResp.status, + headers: { "content-type": "application/json" }, + }); + } + } + + // โ”€โ”€ 8. translate Chat โ†’ Responses โ”€โ”€ + const responseId = generateResponsesId(); + const meta = { customToolNames, namespaceMap, hasToolSearch }; + + if (stream) { + return streamResponse(upstreamResp, { responseId, model: req.model, meta, request: req, input, options: opts }); + } + + const rawChatResp = await upstreamResp.text(); + let chatRespJson; + try { + chatRespJson = JSON.parse(rawChatResp); + } catch (err) { + return errorResponse(502, "translation_failed", `upstream returned non-JSON body: ${(err as Error).message}`); + } + const responsesResp = chatCompletionsToResponses(chatRespJson, req.model, { + responseId, + meta, + ...(typeof req.instructions === "string" ? { instructions: req.instructions } : {}), + ...(prevId ? { previousResponseId: prevId } : {}), + }); + + // โ”€โ”€ 9. store the response (unless `store:false`) โ”€โ”€ + if (req.store !== false && opts.responseStore) { + const stored = buildStoredResponse(responsesResp, input, req.instructions); + opts.responseStore.set(stored); + } + + if (debug) console.log(`[responses] โ† ${responsesResp.status} (${Date.now() - start}ms)`); + + return new Response(JSON.stringify(responsesResp), { + status: 200, + headers: { "content-type": "application/json" }, + }); +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Streaming response +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +interface StreamResponseContext { + responseId: string; + model: string; + meta: { customToolNames: Set; namespaceMap: Map; hasToolSearch: boolean }; + request: ResponsesRequest; + input: ResponsesInputItem[]; + options: ResponsesHandlerOptions; +} + +function streamResponse(upstreamResp: Response, context: StreamResponseContext): Response { + if (!upstreamResp.body) { + return errorResponse(502, "translation_failed", "upstream returned no body for stream"); + } + const state = newResponsesStreamState(context.model, { meta: context.meta, responseId: context.responseId }); + + const stream = new ReadableStream({ + async start(controller) { + const encoder = new TextEncoder(); + const send = (evt: ResponsesStreamEvent) => controller.enqueue(encoder.encode(responsesEventToSse(evt))); + try { + const reader = upstreamResp.body!.getReader(); + const decoder = new TextDecoder(); + let buffer = ""; + let errored = false; + for (;;) { + if (errored) break; + const { done, value } = await reader.read(); + if (done) break; + buffer += decoder.decode(value, { stream: true }); + // SSE chunks are separated by `\n\n`; process complete frames. + let nl: number; + while ((nl = buffer.indexOf("\n\n")) >= 0) { + const frame = buffer.slice(0, nl); + buffer = buffer.slice(nl + 2); + const dataLine = extractSseData(frame); + if (!dataLine || dataLine === "[DONE]") continue; + try { + const chunk = JSON.parse(dataLine); + for (const evt of chatChunkToResponsesEvents(chunk, state)) send(evt); + } catch (err) { + errored = true; + // Release the upstream reader too โ€” without the cancel the + // upstream connection lingers until GC. Fire-and-forget so a + // slow cancel never delays the client-visible error. The + // errored-flag + early-return semantics (anti-pattern #24) are + // unchanged: no further reads, no finalize, no close(). + reader.cancel().catch(() => {}); + controller.error(err); + return; + } + } + } + const finalEvents = finalizeResponsesStream(state); + for (const evt of finalEvents) send(evt); + const finalEvent = finalEvents.find((evt) => evt.type === "response.completed" || evt.type === "response.incomplete"); + if (finalEvent && context.request.store !== false && context.options.responseStore) { + context.options.responseStore.set(buildStoredResponse(finalEvent.response, context.input, context.request.instructions)); + } + try { controller.close(); } catch {} + } catch (err) { + try { controller.error(err); } catch {} + } + }, + cancel(reason) { + context.options.debug === true && console.log(`[responses] stream cancelled: ${String(reason)}`); + try { upstreamResp.body?.cancel(); } catch {} + }, + }); + + return new Response(stream, { + status: 200, + headers: { + "content-type": "text/event-stream", + "cache-control": "no-cache", + connection: "keep-alive", + }, + }); +} + +function extractSseData(frame: string): string | null { + for (const line of frame.split(/\r?\n/)) { + if (line.startsWith("data:")) return line.slice(5).replace(/^\s/, ""); + } + return null; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Helpers +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +function resolveProviderDef(config: ProxyConfig): ProviderDef & { openaiBaseURL: string; anthropicBaseURL: string } { + const base = getProvider(config.provider); + const endpoints = config.providers[config.provider]; + return { + ...base, + anthropicBaseURL: endpoints.anthropicBase, + openaiBaseURL: endpoints.openaiBase, + }; +} + +/** + * Cast stored output items back into input items so the next turn's history is + * a flat list the translator can walk. Responses output and input item shapes + * overlap enough that a structural cast is sound (the fields we read โ€” `type`, + * `call_id`, `name`, `arguments`, `content`, `role` โ€” are shared). + */ +function outputItemsAsInputItems(outputs: ResponsesOutputItem[]): ResponsesInputItem[] { + return outputs as unknown as ResponsesInputItem[]; +} + +function buildStoredResponse( + resp: ResponsesResponse, + input: ResponsesInputItem[], + instructions: string | undefined, +): StoredResponse { + return { + id: resp.id, + model: resp.model, + status: (resp.status === "completed" || resp.status === "incomplete" || resp.status === "failed" ? resp.status : "completed"), + input, + output: resp.output, + usage: resp.usage, + instructions, + createdAt: Date.now(), + lastAccessedAt: Date.now(), + }; +} diff --git a/src/proxy/session-context.ts b/src/proxy/session-context.ts new file mode 100644 index 0000000000000000000000000000000000000000..d74faaf745f93c25d2af9df20106b9356f248e77 --- /dev/null +++ b/src/proxy/session-context.ts @@ -0,0 +1,60 @@ +/** + * Session context resolution and header-emission policy. + * + * Both coding-plan and start-plan call the same resolver. The config decides + * whether inferred lineage is only observed or is forwarded upstream. + */ +import type { ProxyConfig } from "../config/types.js"; +import type { Format } from "../translator/types.js"; +import { + defaultClientSessionResolver, + type ClientSessionAction, + type ClientSessionResolver, + type ClientSessionResult, + type ClientSessionSource, +} from "./client-session.js"; + +export interface ResolveSessionContextInput { + clientReq: Request; + body: string | undefined; + upstreamFormat: Format; + model: string; + config: ProxyConfig; + resolver?: ClientSessionResolver; +} + +export interface SessionHeaderContext { + source?: ClientSessionSource; + action: ClientSessionAction; + sessionId?: string; + upstreamSessionId?: string; + requestId?: string; + traceId?: string; + queryId?: string; +} + +export function resolveSessionContext(input: ResolveSessionContextInput): ClientSessionResult | undefined { + if (input.config.clientIdentity.mode === "off") return undefined; + const resolver = input.resolver ?? defaultClientSessionResolver; + return resolver.resolve(input.clientReq, input.body, input.upstreamFormat, input.model, input.config.clientIdentity); +} + +export function shouldUseExactTraceHeaders( + plan: "coding-plan" | "start-plan", + session?: SessionHeaderContext, +): boolean { + return plan === "start-plan" || hasExplicitTraceHeaders(session) || shouldForwardSessionId(session); +} + +export function shouldForwardSessionId(session?: SessionHeaderContext): boolean { + return session?.source === "explicit" || session?.action === "enforce"; +} + +export function sessionIdForHeader(session?: SessionHeaderContext): string | undefined { + if (!session || !shouldForwardSessionId(session)) return undefined; + return session.upstreamSessionId ?? session.sessionId; +} + +function hasExplicitTraceHeaders(session?: SessionHeaderContext): boolean { + return Boolean(session?.requestId || session?.traceId || session?.queryId); +} diff --git a/src/proxy/system-prompt.ts b/src/proxy/system-prompt.ts new file mode 100644 index 0000000000000000000000000000000000000000..43d27d9b192cfcb32375fd7f8e77831f81577dc2 --- /dev/null +++ b/src/proxy/system-prompt.ts @@ -0,0 +1,78 @@ +/** + * ZCode system prompt blocks required by zcode.z.ai start-plan gateway. + * + * The gateway does content inspection โ€” if it doesn't see the ZCode identity + * blocks in the `system` field, it rejects with 3012 "method not allowed". + * + * Static blocks (CLI Prefix, Agent Identity w/ Harness, Environment Info) live + * in zcode_system.json. When a model name is available, the dynamic + * `- You are powered by the model named ${currentModel}.` line is appended + * INSIDE the trailing Environment block's text (mirrors bundle 3.11.2 `T9o` + * / buildEnvInfoSection, which emits it as the block's last line โ€” NOT as a + * separate 4th block). + * + * Source: extracted from ZCode Electron app's `buildCliPrefixSection`, + * `buildIdentitySection`, and `buildEnvInfoSection`. See PROMPT.md for the + * full prompt structure. + * + * @see zcode_system.json + * @see PROMPT.md + */ +// Inlined as a build-time constant (Bun `json` import attribute / esbuild json +// loader) so it ships inside the single-file compiled binary โ€” a runtime +// `readFileSync` would resolve `__dirname` to the build-time CI path and crash +// with ENOENT on every other host. @see types.d.ts +import blocks from "./zcode_system.json" with { type: "json" }; + +interface SystemBlock { + type: "text"; + text: string; + cache_control?: { type: "ephemeral" }; +} + +const ZCODE_SYSTEM_BLOCKS = blocks as SystemBlock[]; + +/** + * Prepend official ZCode gateway blocks to the request's `system` field. + * Client system blocks (if any) are preserved after the official blocks. + * + * When `currentModel` is a non-empty string, the powered-by line is merged + * into the LAST static block (Environment) as its trailing text line โ€” the + * block's cache_control (if any) stays as-is, no extra breakpoint is created. + */ +export function buildStartPlanSystem(existingSystem: unknown, currentModel?: string): unknown[] { + const official = ZCODE_SYSTEM_BLOCKS.map((b) => structuredClone(b)); + if (currentModel && currentModel.trim().length > 0) { + const env = official[official.length - 1]; + if (env && typeof env === "object") { + env.text = `${env.text}\n- You are powered by the model named ${currentModel}.`; + } + } + const userBlocks = normalizeUserSystem(existingSystem); + return [...official, ...userBlocks]; +} + +function normalizeUserSystem(system: unknown): SystemBlock[] { + if (system == null) return []; + if (typeof system === "string") { + const text = system.trim(); + return text ? [{ type: "text", text }] : []; + } + if (!Array.isArray(system)) return []; + const out: SystemBlock[] = []; + for (const item of system) { + if (typeof item === "string") { + if (item.trim()) out.push({ type: "text", text: item }); + } else if (item && typeof item === "object") { + const b = item as Record; + if (b.type === "text" && typeof b.text === "string" && b.text.trim()) { + out.push({ + type: "text", + text: b.text, + ...(typeof b.cache_control === "object" && b.cache_control !== null ? { cache_control: b.cache_control as { type: "ephemeral" } } : {}), + }); + } + } + } + return out; +} diff --git a/src/proxy/trace-headers.ts b/src/proxy/trace-headers.ts new file mode 100644 index 0000000000000000000000000000000000000000..20eda0a3c038a354a9fe0f478d43f9520ed3a315 --- /dev/null +++ b/src/proxy/trace-headers.ts @@ -0,0 +1,56 @@ +export interface ZcodeTraceContext { + requestId?: string; + traceId?: string; + queryId?: string; + sessionId?: string; + /** Optional override; one of "main" | "subagent" | "other" (ZCode 3.9.1 session types). */ + sessionType?: string; +} + +const QUERY_PREFIX = "query_"; +const SUBAGENT_PREFIX = "subagent_agent_"; +const SESSION_PREFIXES = ["sess_", SUBAGENT_PREFIX]; + +/** + * Resolve the `x-zcode-session-type` attribution value, mirroring the ZCode + * 3.9.1 bundle's `resolveModelRequestSessionType`/`isModelRequestSessionType`. + * + * The bundle derives main/subagent/other from the agent orchestration context. + * The proxy's equivalent signal is the client session id: ZCode-style harnesses + * prefix subagent sessions with `subagent_agent_`. Every other forwarded + * conversation turn is the moral equivalent of the main agent loop ("main"); + * an explicit ctx.sessionType wins when provided and valid. + */ +function resolveSessionType(ctx: ZcodeTraceContext): "main" | "subagent" | "other" { + const explicit = ctx.sessionType?.trim(); + if (explicit === "main" || explicit === "subagent" || explicit === "other") return explicit; + if (ctx.sessionId?.startsWith(SUBAGENT_PREFIX) && ctx.sessionId.length > SUBAGENT_PREFIX.length) return "subagent"; + return "main"; +} + +/** + * Mirrors ZCode's attribution header helper (`createModelRequestAttributionHeaders`). + * + * ZCode 3.9.1 emits, in this order: x-request-id, x-zcode-session-type, + * x-zcode-trace-id, [x-query-id], [x-session-id]. The session-type header is + * unconditional (always resolves to main/subagent/other). + */ +export function buildZcodeTraceHeaders(ctx: ZcodeTraceContext = {}): Record { + const queryId = ctx.queryId ? stripHeaderInternalPrefixes(ctx.queryId, [QUERY_PREFIX]) : undefined; + const sessionId = ctx.sessionId ? stripHeaderInternalPrefixes(ctx.sessionId, SESSION_PREFIXES) : undefined; + return { + "x-request-id": ctx.requestId ?? crypto.randomUUID(), + "x-zcode-session-type": resolveSessionType(ctx), + "x-zcode-trace-id": ctx.traceId ?? crypto.randomUUID(), + ...(queryId ? { "x-query-id": queryId } : {}), + ...(sessionId ? { "x-session-id": sessionId } : {}), + }; +} + +export function stripHeaderInternalPrefixes(value: string, prefixes: string[]): string { + let out = value; + for (const prefix of prefixes) { + if (out.startsWith(prefix) && out.length > prefix.length) out = out.slice(prefix.length); + } + return out || value; +} diff --git a/src/proxy/upstream.ts b/src/proxy/upstream.ts new file mode 100644 index 0000000000000000000000000000000000000000..fd53a0da17e92171a39bfba821d2ed35ee017c38 --- /dev/null +++ b/src/proxy/upstream.ts @@ -0,0 +1,232 @@ +/** + * Upstream request builder โ€” constructs the forwarded HTTP request. + * + * **`format` semantics**: This is the *upstream* format โ€” the format used to + * talk to the upstream LLM provider, not the client's inbound format. Both + * ZCode coding-plan and start-plan routes post an Anthropic-format upstream + * (since PR #34, 2026-08-29 โ€” start-plan's old OpenAI gateway is retired); + * OpenAI clients are translated before this builder is called. + * + * @see .omo/plans/zcode-proxy.md Task 6 + * @see _reverse/NOTEPAD.md "How Credential is Used for LLM Calls" + */ +import type { Format } from "../translator/types.js"; +import type { ProviderDef } from "../provider/types.js"; +import type { Credential } from "../auth/types.js"; +import type { ProxyIdentity } from "../config/types.js"; +import { credentialString } from "../auth/types.js"; +import { buildLlmIdentityHeaders } from "./identity.js"; +import { buildZcodeTraceHeaders } from "./trace-headers.js"; +import { sessionIdForHeader, shouldUseExactTraceHeaders } from "./session-context.js"; + +export interface UpstreamClientSession { + source?: "none" | "explicit" | "lineage"; + action: "off" | "observe" | "enforce"; + sessionId?: string; + upstreamSessionId?: string; + requestId?: string; + traceId?: string; + queryId?: string; +} + +export type UpstreamHeaderPair = [string, string]; + +const ANTHROPIC_VERSION = "2023-06-01"; + +/** + * SDK UA suffix the real client appends to its User-Agent on LLM calls + * (bundle `Cm` merges `ai-sdk/anthropic/${k0o}` into the UA; k0o = "3.0.81"). + * Only the LLM request path carries it โ€” control-plane fetches (endpoint + * routing, signing gate, claim/billing) keep the bare `ZCode/โ€ฆ` UA. + */ +const ANTHROPIC_SDK_UA = "ai-sdk/anthropic/3.0.81"; + +const STARTPLAN_ANTHROPIC_BASE = "https://zcode.z.ai/api/v1/zcode-plan"; + +const STRIP_HEADERS = new Set([ + "host", + "authorization", + "x-api-key", + "anthropic-version", + "content-length", + "connection", + "proxy-authorization", + "proxy-authenticate", + "transfer-encoding", + "x-request-id", + "x-zcode-trace-id", + "x-zcode-session-type", + "x-query-id", + "x-session-id", + // V4 signing headers are proxy-generated only; inbound copies must never + // reach the upstream (spoofed values would either fail verification or + // silently disable proxy signing via the existing-header guard). + "x-client-ts", + "x-client-version", + "x-client-sig", + "x-client-nonce", + "x-app-id", + "x-client-pow", + "x-client-sign-verified", +]); + +/** + * Build the upstream URL based on format + plan + provider. + * + * The `format` parameter is the *upstream* format โ€” callers in handler.ts + * pass the format the upstream will receive, which may differ from the + * client's inbound format when the proxy is in compatibility mode. + */ +export function buildUpstreamURL(format: Format, provider: ProviderDef, plan: "coding-plan" | "start-plan" = "coding-plan"): string { + if (plan === "start-plan") { + // Anthropic-messages gateway used by the live ZCode desktop client for + // start-plan (incl. claimed trial plans like the weekend package). + // The legacy OpenAI route `${STARTPLAN_ANTHROPIC_BASE}/chat/completions` + // returns "404 page not found" since the server-side rollout of this + // endpoint (observed 2026-08-28). + return `${STARTPLAN_ANTHROPIC_BASE}/anthropic/v1/messages`; + } + if (format === "anthropic") { + return `${provider.anthropicBaseURL}/v1/messages`; + } + return `${provider.openaiBaseURL}/chat/completions`; +} + +/** + * Build auth + identity + trace headers for the upstream LLM request. + * + * The `format` parameter is the *upstream* format โ€” selects auth scheme: + * - Anthropic upstream, coding-plan โ†’ `x-api-key: {cred}` AND + * `Authorization: Bearer {cred}` (dual headers, bundle `ebo`) + + * `anthropic-version` + * - Anthropic upstream, start-plan โ†’ `Authorization: Bearer {jwt}` + `anthropic-version` + * - OpenAI upstream (any plan) โ†’ `Authorization: Bearer {cred|jwt}` + * + * Identity headers come from `buildLlmIdentityHeaders` (bundle `csn` shape); + * the User-Agent carries the `ai-sdk/anthropic` SDK suffix (bundle `Cm`/`k0o`). + * + * Trace/attribution headers mirror the bundle's `Bdt` + * ("createModelRequestAttributionHeaders") when an explicit/enforced trace + * context exists. Default observe mode keeps the prior synthesized query/session + * behavior for compatibility. + */ +export function buildAuthHeaders( + format: Format, + cred: Credential, + identity: ProxyIdentity, + plan: "coding-plan" | "start-plan" = "coding-plan", + clientSession?: UpstreamClientSession, +): Record { + const credStr = plan === "start-plan" && cred.jwt ? cred.jwt : credentialString(cred); + const base: Record = { + // LLM requests mirror the bundle's CLI source-headers builder (`csn` + + // x4i wrapper) โ€” language/timezone always sent with "unknown" fallback, + // X-Release-Channel right after X-Title, X-ZCode-Agent LAST, no + // X-Device-Mid. Control-plane fetches use buildIdentityHeaders (`HRt`). + ...buildLlmIdentityHeaders(identity), + ...buildTraceHeaders(plan, clientSession), + }; + // Bundle `Cm`/`k0o`: the anthropic SDK merges its identity into the UA โ€” + // real LLM requests arrive as `ZCode/{ver} ai-sdk/anthropic/3.0.81`. + base["User-Agent"] = `${base["User-Agent"]} ${ANTHROPIC_SDK_UA}`; + + if (format === "anthropic") { + if (plan === "start-plan" && cred.jwt) { + base["authorization"] = `Bearer ${cred.jwt}`; + } else { + // Bundle `ebo` (coding-plan, anthropic): x-api-key from the SDK config + // AND `Authorization: Bearer {credential}` from the custom-header merge + // โ€” both headers, same value. + base["x-api-key"] = credStr; + base["authorization"] = `Bearer ${credStr}`; + } + base["anthropic-version"] = ANTHROPIC_VERSION; + } else { + base["authorization"] = `Bearer ${credStr}`; + } + + return base; +} + +function buildTraceHeaders(plan: "coding-plan" | "start-plan", clientSession?: UpstreamClientSession): Record { + if (shouldUseExactTraceHeaders(plan, clientSession)) { + return buildZcodeTraceHeaders({ + requestId: clientSession?.requestId, + traceId: clientSession?.traceId, + queryId: clientSession?.queryId, + sessionId: sessionIdForHeader(clientSession), + }); + } + + const headers: Record = { + "x-request-id": crypto.randomUUID(), + // ZCode 3.9.1 attributes every model request; a forwarded conversation turn is the main-agent loop. + "x-zcode-session-type": "main", + "x-zcode-trace-id": crypto.randomUUID(), + }; + if (plan !== "start-plan") { + headers["x-query-id"] = crypto.randomUUID(); + headers["x-session-id"] = crypto.randomUUID(); + } + return headers; +} + +function collectPassthroughHeaders(req: Request): Record { + const result: Record = {}; + for (const [key, value] of req.headers.entries()) { + const lower = key.toLowerCase(); + if (STRIP_HEADERS.has(lower)) continue; + if (lower === "anthropic-beta") { + result[lower] = value; + } + } + return result; +} + +export function buildUpstreamHeaderPairs( + clientReq: Request, + format: Format, + cred: Credential, + identity: ProxyIdentity, + plan: "coding-plan" | "start-plan" = "coding-plan", + extraHeaders?: Record, + clientSession?: UpstreamClientSession, +): UpstreamHeaderPair[] { + // Forward the client's Accept-Encoding so the upstream compresses only when + // the client can decode it. Hardcoding "gzip" broke clients (e.g. some Tauri + // builds) that send `accept-encoding: identity` and cannot auto-decompress. + const clientAcceptEncoding = clientReq.headers.get("accept-encoding") ?? "gzip"; + return [ + ["content-type", "application/json"], + ["accept-encoding", clientAcceptEncoding], + ...Object.entries(collectPassthroughHeaders(clientReq)), + ...Object.entries(buildAuthHeaders(format, cred, identity, plan, clientSession)), + ...Object.entries(extraHeaders ?? {}), + ]; +} + +export function buildUpstreamRequest( + clientReq: Request, + format: Format, + provider: ProviderDef, + cred: Credential, + body: string | undefined, + identity: ProxyIdentity, + plan: "coding-plan" | "start-plan" = "coding-plan", + extraHeaders?: Record, + clientSession?: UpstreamClientSession, +): Request { + const url = buildUpstreamURL(format, provider, plan); + const headerPairs = buildUpstreamHeaderPairs(clientReq, format, cred, identity, plan, extraHeaders, clientSession); + + const init: RequestInit = { + method: "POST", + headers: Object.fromEntries(headerPairs), + }; + + if (body !== undefined) { + init.body = body; + } + + return new Request(url, init); +} diff --git a/src/responses/store.ts b/src/responses/store.ts new file mode 100644 index 0000000000000000000000000000000000000000..6475e72082e4dc950085a92e14bcc722d3a86242 --- /dev/null +++ b/src/responses/store.ts @@ -0,0 +1,102 @@ +/** + * In-memory response store for the Responses API's `previous_response_id`. + * + * The Responses API is stateful: a client passes `previous_response_id`, and + * the server (OpenAI) reconstructs the full conversation from that stored + * response. On a non-OpenAI upstream (GLM Chat Completions) we must emulate + * this ourselves โ€” store each completed response keyed by id, and on the next + * request prepend the stored `input[]` + `output[]` history so the upstream + * sees a complete conversation. + * + * Backed by a bounded LRU cache with TTL eviction. Process restart drops + * everything (documented limitation โ€” OpenAI persists for ~30 days, we can't + * match that without a persistence layer; in-memory is the P1.0 scope). + * + * Thread-safety: single-process; JS event loop serialises access. + */ + +import type { ResponsesInputItem, ResponsesOutputItem, ResponsesUsage } from "../translator/responses-types.js"; + +/** A stored response entry โ€” enough to reconstruct the next turn's history. */ +export interface StoredResponse { + id: string; + model: string; + status: "completed" | "incomplete" | "failed"; + input: ResponsesInputItem[]; + output: ResponsesOutputItem[]; + usage?: ResponsesUsage; + instructions?: string; + createdAt: number; + lastAccessedAt: number; +} + +export interface ResponseStoreOptions { + /** Max entries before LRU eviction. Default 1000. */ + maxEntries?: number; + /** TTL in ms before an entry is considered stale. Default 24h. */ + ttlMs?: number; +} + +const DEFAULT_MAX_ENTRIES = 1000; +const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; + +/** + * Bounded LRU + TTL cache of stored responses. Iteration order = insertion + * order; `get()` re-inserts to refresh LRU position. Stale entries are evicted + * lazily on access and proactively on `set()` overflow. + */ +export class ResponseStore { + private readonly maxEntries: number; + private readonly ttlMs: number; + private readonly map = new Map(); + + constructor(opts: ResponseStoreOptions = {}) { + this.maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES; + this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS; + } + + /** Store a response. Overwrites on duplicate id. Evicts LRU entries on overflow. */ + set(entry: StoredResponse): void { + const now = Date.now(); + entry.createdAt = now; + entry.lastAccessedAt = now; + if (this.map.has(entry.id)) this.map.delete(entry.id); + this.map.set(entry.id, entry); + while (this.map.size > this.maxEntries) { + const oldestKey = this.map.keys().next().value; + if (oldestKey === undefined) break; + this.map.delete(oldestKey); + } + } + + /** + * Fetch a stored response. Returns `undefined` when missing or stale. + * Refreshes LRU position on hit. + */ + get(id: string): StoredResponse | undefined { + const entry = this.map.get(id); + if (!entry) return undefined; + const now = Date.now(); + if (now - entry.createdAt > this.ttlMs) { + this.map.delete(id); + return undefined; + } + entry.lastAccessedAt = now; + // Re-insert at the tail so the LRU eviction touches it last. + this.map.delete(id); + this.map.set(id, entry); + return entry; + } + + delete(id: string): boolean { + return this.map.delete(id); + } + + clear(): void { + this.map.clear(); + } + + size(): number { + return this.map.size; + } +} diff --git a/src/runtime/guest-error.ts b/src/runtime/guest-error.ts new file mode 100644 index 0000000000000000000000000000000000000000..145ee1eaf9869d940c2cf764027584f29cf701dd --- /dev/null +++ b/src/runtime/guest-error.ts @@ -0,0 +1,73 @@ +/** + * guest-error.ts โ€” provenance test for errors thrown by third-party captcha + * SDK code ("guest" scripts) running inside the in-process happy-dom solver. + * + * Under Bun the guest scripts execute in the HOST realm (happy-dom's VM + * isolation is a no-op there), so an error escaping a guest callback reaches + * process-level `uncaughtException` exactly like an error from our own code. + * The two must not share a fate: a rotated pe/FeiLin bundle tripping over an + * emulation gap must fail that one solve โ€” the pool retries โ€” while a genuine + * fault in the proxy still terminates loudly. + * + * `serve` mode already draws that line (captcha-happy.ts logs and continues). + * The TUI's own uncaughtException handler used to exit(1) for everything, + * which turned a recoverable guest error into a dead proxy: + * + * zcode-proxy: tui crashed: ReferenceError: moveBy is not defined + * at tE (https://g.alicdn.com/captcha-frontend/FeiLin/1.5.1/feilin008โ€ฆjs) + * + * Evidence is the source URL of the throwing frame: guest bundles are served + * from Aliyun CDN/API hosts and carry those URLs in their stack frames (and, + * for generated code, in the `//# sourceURL` we preserve when evaluating). + */ + +// CDN/API hosts serving the Aliyun captcha SDK bundles. Anchored at the URL +// authority (`scheme://`, optional userinfo) and terminated by a port/path/ +// delimiter, so the domain must be the real host โ€” `evil-alicdn.com.bad.net` +// and `โ€ฆ?ref=alicdn.com` are not guest evidence. +const GUEST_SCRIPT_HOST = + /https?:\/\/(?:[^/\s@]*@)?(?:[a-z0-9-]+\.)*(?:alicdn\.com|aliyuncs\.com)(?=[:/?#]|\s|$)/i; + +/** Follows `cause` chains without looping on self-referential errors. */ +function* errorChain(err: unknown, depth = 4): Generator { + const seen = new Set(); + let current = err; + for (let i = 0; i < depth; i++) { + if (!current || typeof current !== "object" || seen.has(current)) return; + seen.add(current); + yield current as object; + current = (current as { cause?: unknown }).cause; + } +} + +/** + * True when `err` originates in third-party captcha SDK code. + * + * Deliberately conservative: only a guest source URL counts as evidence. A + * missing/truncated stack yields `false`, so an unattributable error keeps the + * strict (fatal) treatment. + */ +export function isGuestOriginError(err: unknown): boolean { + for (const link of errorChain(err)) { + const e = link as { stack?: unknown; sourceURL?: unknown; message?: unknown }; + if (typeof e.stack === "string" && GUEST_SCRIPT_HOST.test(e.stack)) return true; + // Bun/JSC attach the throwing script's URL directly on the error. + if (typeof e.sourceURL === "string" && GUEST_SCRIPT_HOST.test(e.sourceURL)) return true; + if (typeof e.message === "string" && GUEST_SCRIPT_HOST.test(e.message)) return true; + } + return false; +} + +/** One-line render of a guest error for the log pane / stderr. */ +export function describeGuestError(err: unknown): string { + const e = err as { name?: unknown; message?: unknown; stack?: unknown } | null; + const name = typeof e?.name === "string" ? e.name : "Error"; + const message = typeof e?.message === "string" ? e.message : String(err); + const frame = + typeof e?.stack === "string" + ? (e.stack.split("\n").find((line) => GUEST_SCRIPT_HOST.test(line)) ?? "").trim() + : ""; + // Bundle URLs carry a 64-char content hash โ€” keep the readable filename only. + const source = frame.replace(/^at\s+/, "").replace(/https?:\/\/[^\s)]*\/([^/\s)]+)/, "$1"); + return source ? `${name}: ${message} (${source})` : `${name}: ${message}`; +} diff --git a/src/runtime/node-fetch-compat.ts b/src/runtime/node-fetch-compat.ts new file mode 100644 index 0000000000000000000000000000000000000000..9d78e63f08152a6441489aea8ec0ee9d6711226f --- /dev/null +++ b/src/runtime/node-fetch-compat.ts @@ -0,0 +1,41 @@ +/** + * Node-only global-fetch normalization for the Android (Node.js bundle) build. + * + * Node's global fetch (undici) enforces default client timeouts that Bun's + * fetch does not: `headersTimeout` and `bodyTimeout` both default to 300000 ms + * (undici `client.js`, verified 2026-08-16). A non-streaming LLM upstream sends + * response headers only after the ENTIRE generation completes โ€” deep-reasoning + * requests legitimately exceed 300s. Those requests work on the Bun desktop + * build but die as `UND_ERR_HEADERS_TIMEOUT` โ†’ 502 `upstream_unreachable` on + * the Node Android build. This module restores the project's intended + * "no upstream timeout on LLM calls" invariant (root AGENTS.md anti-pattern + * #7) by swapping the global dispatcher for an Agent with both timeouts + * disabled. + * + * The npm `undici` package shares the global-dispatcher registration symbol + * with Node's built-in fetch, so `setGlobalDispatcher` from the package + * configures the GLOBAL fetch (verified empirically: a 1 ms Agent aborts + * global fetch with `UND_ERR_HEADERS_TIMEOUT`). esbuild bundles the dynamic + * import into the Android `server.cjs`; on Bun this function is a no-op and + * the import never executes. + */ + +let applied = false; + +/** + * Disable Node fetch's default 300s headers/body timeouts. Safe to call from + * any runtime and any number of times: no-op under Bun, runs once under Node. + * Errors are reported but never thrown โ€” a default-timeout process still + * works for the common (<300s) request path. + */ +export async function ensureNodeFetchNoTimeouts(): Promise { + if (typeof Bun !== "undefined") return; + if (applied) return; + applied = true; + try { + const { Agent, setGlobalDispatcher } = await import("undici"); + setGlobalDispatcher(new Agent({ headersTimeout: 0, bodyTimeout: 0 })); + } catch (err) { + console.error(`zcode-proxy: could not disable Node fetch default timeouts: ${(err as Error).message}`); + } +} diff --git a/src/runtime/open-browser.ts b/src/runtime/open-browser.ts new file mode 100644 index 0000000000000000000000000000000000000000..4188bdd6d31044b816feabbeaa58ec8a4403b14f --- /dev/null +++ b/src/runtime/open-browser.ts @@ -0,0 +1,33 @@ +/** + * Cross-platform default-browser launcher, shared by the CLI auth flows and + * the TUI login action. Best-effort: a failure leaves the URL on screen for + * the user to copy manually. + */ +import { spawn, type SpawnOptions } from "node:child_process"; + +export function openBrowser(url: string): void { + try { + if (process.platform === "win32") { + spawnDetached("cmd.exe", ["/c", `start "" "${url}"`], { + windowsHide: true, windowsVerbatimArguments: true, + }); + } else if (process.platform === "darwin") { + spawnDetached("open", [url]); + } else { + spawnDetached("xdg-open", [url]); + } + } catch { /* user copies URL manually */ } +} + +/** + * Spawn a fire-and-forget browser opener. Spawn failures surface + * asynchronously on the child (ENOENT for xdg-open on headless boxes โ€” there + * is no browser to open), not as a synchronous throw, so an "error" listener + * MUST be attached or the crash takes down the whole login process. Either + * way the authorize URL is already on screen for manual copying. + */ +function spawnDetached(cmd: string, args: string[], extra: SpawnOptions = {}): void { + const child = spawn(cmd, args, { detached: true, stdio: "ignore", ...extra }); + child.on("error", () => { /* headless โ€” user copies URL manually */ }); + child.unref(); +} diff --git a/src/runtime/paste-login.ts b/src/runtime/paste-login.ts new file mode 100644 index 0000000000000000000000000000000000000000..e0c210b4f8bfd85ca65d708e4b10fb2c7253d098 --- /dev/null +++ b/src/runtime/paste-login.ts @@ -0,0 +1,81 @@ +/** + * Shared plumbing for the headless "paste" login (auth-code flow): the + * terminal instructions and the readline-with-timeout that collects the + * pasted callback URL. Pure presentation/IO โ€” the URL parsing and CSRF state + * check live in `parsePastedCallbackUrl` (auth/oauth.ts). + * + * Used by the CLI (`auth login bigmodel --paste`) and the TUI (`L` key), + * which suspend their own rendering before calling into these. + */ +import { createInterface } from "node:readline"; + +/** Bold only when attached to a terminal โ€” keeps piped output ANSI-free. */ +export function boldIfTTY(text: string): string { + return process.stdout.isTTY ? `\x1b[1m${text}\x1b[0m` : text; +} + +/** + * Multi-line instructions shown after the flow started, before reading the + * pasted URL. Printed to the REAL terminal by both entries (the CLI's + * console is never intercepted; the TUI passes its captured stdout writer). + * Deliberately loud: the user must understand that the browser "error" page + * is the expected hand-off, and what the redirected URL looks like. + */ +export function pasteLoginInstructions( + authorizeUrl: string, + callbackUrl: string, + timeoutMs: number, +): string { + const bar = "=".repeat(72); + return [ + "", + bar, + boldIfTTY(" PASTE LOGIN โ€” the callback page is expected NOT to load"), + bar, + "", + "Open this URL to authorize (any machine with a browser):", + "", + ` ${authorizeUrl}`, + "", + "After you authorize, the browser redirects to a localhost URL shaped like:", + "", + ` (${callbackUrl}?authCode=xxxxxxxx&state=xxxxxxxx)`, + "", + "That page will NOT load (connection refused) โ€” that is NORMAL on a", + "headless machine. Copy the FULL redirected URL from the browser's", + "address bar, paste it below, and press Enter.", + `(timeout: ${Math.round(timeoutMs / 1000)}s)`, + bar, + ].join("\n"); +} + +/** + * Read one line of stdin (the pasted callback URL) with an overall timeout. + * Callers put the terminal into cooked mode first (the TUI leaves raw mode + * before this), so the tty line discipline echoes the paste. Rejects with + * the standard login-timeout message, or when stdin closes without a line + * (e.g. piped/empty input) so the flow can never hang forever. + */ +export function readPastedLine( + timeoutMs: number, + input: NodeJS.ReadableStream = process.stdin, +): Promise { + return new Promise((resolve, reject) => { + const rl = createInterface({ input, crlfDelay: Infinity }); + let settled = false; + const settle = (fn: () => void): void => { + if (settled) return; + settled = true; + clearTimeout(timer); + rl.close(); + fn(); + }; + const timer = setTimeout(() => { + settle(() => reject(new Error("Authorization timed out. Please retry login."))); + }, timeoutMs); + rl.on("line", (line: string) => settle(() => resolve(line))); + rl.on("close", () => { + settle(() => reject(new Error("stdin closed before a callback URL was pasted."))); + }); + }); +} diff --git a/src/server/routes-anthropic.ts b/src/server/routes-anthropic.ts new file mode 100644 index 0000000000000000000000000000000000000000..e9edf46dd1b14defa1252dfcb8cfe50644df4684 --- /dev/null +++ b/src/server/routes-anthropic.ts @@ -0,0 +1,13 @@ +/** + * Anthropic-format route handler: POST /v1/messages. + * @see .omo/plans/zcode-proxy.md Task 8 + */ +import { proxyRequest, type ProxyHandlerOptions } from "../proxy/handler.js"; + +/** Handle POST /v1/messages โ€” forward to upstream Anthropic endpoint. */ +export async function handleMessages( + req: Request, + opts: ProxyHandlerOptions, +): Promise { + return proxyRequest(req, "anthropic", opts); +} diff --git a/src/server/routes-async.ts b/src/server/routes-async.ts new file mode 100644 index 0000000000000000000000000000000000000000..e016fd9f96be4a81607f249704b769c0ca3edfa9 --- /dev/null +++ b/src/server/routes-async.ts @@ -0,0 +1,28 @@ +/** + * Async (off-peak) route handlers โ€” thin adapters from the HTTP layer to + * `src/async/handler.ts`. Mirrors the `routes-responses.ts` pattern. + * + * Route registration lives in `server.ts:createFetchHandler` (gated by + * `config.async.enabled`). Per-route Node socket timeout extension lives + * in `server.ts:startServer` (24h for `/async/*`; default 600s elsewhere). + */ +import { + handleAsyncMessages, + handleAsyncChat, + handleAsyncHealth, + type AsyncHandlerOptions, +} from "../async/handler.js"; + +export { handleAsyncMessages, handleAsyncChat, handleAsyncHealth, type AsyncHandlerOptions }; + +export async function handleAsyncMessagesRoute(req: Request, opts: AsyncHandlerOptions): Promise { + return handleAsyncMessages(req, opts); +} + +export async function handleAsyncChatRoute(req: Request, opts: AsyncHandlerOptions): Promise { + return handleAsyncChat(req, opts); +} + +export async function handleAsyncHealthRoute(req: Request, opts: AsyncHandlerOptions): Promise { + return handleAsyncHealth(req, opts); +} diff --git a/src/server/routes-openai.ts b/src/server/routes-openai.ts new file mode 100644 index 0000000000000000000000000000000000000000..0157a4779da304fa6ecb739bd94aecd9f9e0e3cb --- /dev/null +++ b/src/server/routes-openai.ts @@ -0,0 +1,60 @@ +/** + * OpenAI-format route handlers: /v1/chat/completions + /v1/models. + * @see .omo/plans/zcode-proxy.md Task 7 + */ +import { proxyRequest, type ProxyHandlerOptions } from "../proxy/handler.js"; +import { MODELS } from "../provider/models.js"; +import type { OpenAIModelList } from "../translator/types.js"; + +/** Handle POST /v1/chat/completions โ€” forward OpenAI-compatible chat requests upstream. */ +export async function handleChatCompletions( + req: Request, + opts: ProxyHandlerOptions, +): Promise { + return proxyRequest(req, "openai", opts); +} + +/** Handle GET /v1/models โ€” return the model list in OpenAI format. */ +export function handleListModels(req: Request): Response { + // CLIProxyAPI-style rich catalog: DSH's better-basicfun synchronizer probes + // with ?client_version=pi and parses a top-level `models[]` array with + // slug/context_window/max_tokens/supported_reasoning_levels fields. A plain + // OpenAI request keeps the original `data[]` shape. + const clientVersion = new URL(req.url).searchParams.get("client_version"); + if (clientVersion === "pi") { + const body = { + object: "list", + models: MODELS.map((m) => ({ + slug: m.id, + display_name: m.name, + description: m.name, + context_window: m.contextWindow, + max_context_window: m.contextWindow, + ...(m.maxOutputTokens === undefined ? {} : { max_tokens: m.maxOutputTokens }), + // Heuristic: vision-capable ZCode models embed "v" in their id (e.g. glm-4.6v). + // Revisit if upstream introduces non-vision ids that merely contain "v". + input_modalities: m.id.includes("v") ? ["text", "image"] : ["text"], + supported_reasoning_levels: m.reasoning + ? [{ effort: "low" }, { effort: "medium" }, { effort: "high" }, { effort: "xhigh" }] + : [], + visibility: "list", + })), + }; + return new Response(JSON.stringify(body), { + status: 200, + headers: { "content-type": "application/json" }, + }); + } + const list: OpenAIModelList = { + object: "list", + data: MODELS.map((m) => ({ + id: m.id, + object: "model" as const, + owned_by: "zcode-proxy", + })), + }; + return new Response(JSON.stringify(list), { + status: 200, + headers: { "content-type": "application/json" }, + }); +} diff --git a/src/server/routes-quota.ts b/src/server/routes-quota.ts new file mode 100644 index 0000000000000000000000000000000000000000..d7e4de1fe744f6e282109fe93257445e78664ec9 --- /dev/null +++ b/src/server/routes-quota.ts @@ -0,0 +1,175 @@ +/** + * GET /quota โ€” live free-quota snapshot from ZCode billing endpoints. + * + * Queries the same control plane the desktop client uses (`billing/balance` + + * `billing/preview` on the configured claim origin) with the stored OAuth JWT + * and the full desktop identity fingerprint. The billing gateway requires a + * stable `X-Device-Mid`, so the config identity is forwarded unchanged. + * + * @see scripts in vibe-coding-labs/zcode-reverse-engineer (header shape) and + * zcode.z.ai desktop bundle `pio()` (identity header semantics). + */ +import os from "node:os"; +import { loadCredential } from "../auth/store.js"; +import { buildIdentityHeaders, normalizePrintableHeaderValue } from "../proxy/identity.js"; +import { inspectJwt } from "../auth/jwt-age.js"; +import type { ProxyConfig } from "../config/types.js"; +import { errorResponse } from "../proxy/handler.js"; + +export interface QuotaBalanceEntry { + showName: string; + remainingUnits: number; + totalUnits: number; + usedUnits: number; + unitType?: string; + expiresAt?: number; +} + +export interface QuotaPlanEntry { + planId: string; + name: string; + description?: string; + entitlements: Array<{ showName: string; grantUnits: number; unitType: string; effectiveAt?: number }>; +} + +export interface QuotaSnapshot { + provider: string; + serverTime: number; + /** + * Stored start-plan JWT age (informational). The token has no `exp` and is + * not rejected by age โ€” an 8-day-old JWT still serves billing/balance. Only + * a real 401/3012 from the billing gateway indicates re-login is needed, + * which surfaces in `errors`. + */ + jwt: { ageHours: number; issuedAt: number } | null; + balances: QuotaBalanceEntry[]; + claimablePlans: QuotaPlanEntry[]; + errors: string[]; +} + +/** Query one billing URL, tolerating per-endpoint failures. */ +async function fetchBilling( + origin: string, + path: string, + headers: Record, + fetchImpl: typeof fetch, +): Promise<{ code?: number; msg?: string; data?: unknown } | null> { + try { + const resp = await fetchImpl(`${origin.replace(/\/+$/, "")}${path}`, { headers }); + const text = await resp.text(); + try { + return JSON.parse(text) as { code?: number; msg?: string; data?: unknown }; + } catch { + return { code: resp.status, msg: text.slice(0, 120) }; + } + } catch (e) { + return { code: -1, msg: String(e).slice(0, 120) }; + } +} + +/** Coerce an upstream value to a finite number, or undefined (never NaN โ€” JSON.stringify would emit null). */ +function toFiniteNumber(v: unknown): number | undefined { + const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN; + return Number.isFinite(n) ? n : undefined; +} + +/** Build the billing snapshot. Exported for tests. `loadCredentialImpl` is injectable for tests. */ +export async function collectQuotaSnapshot( + config: ProxyConfig, + fetchImpl: typeof fetch = fetch, + loadCredentialImpl: typeof loadCredential = loadCredential, +): Promise { + const cred = await loadCredentialImpl(); + if (!cred?.jwt) { + throw new Error("not logged in โ€” no JWT credential (run: zcode-proxy auth login)"); + } + const jwtInfo = inspectJwt(cred.jwt); + const jwt = jwtInfo + ? { ageHours: Number(jwtInfo.ageHours.toFixed(2)), issuedAt: jwtInfo.iat } + : null; + const identity = config.identity; + const idHeaders = buildIdentityHeaders(identity); + // The claim client drops X-ZCode-Agent for zcode.z.ai control-plane calls; + // the billing gateway follows the same precedent. + delete idHeaders["X-ZCode-Agent"]; + const headers: Record = { ...idHeaders, authorization: `Bearer ${cred.jwt}`, Accept: "application/json" }; + // Billing fingerprint is reconstructed from the observed claim-client format + // (`${platform}-${arch}`). Reuses identity.ts's env-override normalization + // (same ZCODE_IDENTITY_PLATFORM/ARCH overrides the proxy headers use โ€” + // Android seeds linux-x64 via index.ts); empty or non-printable overrides + // fall back to the real values โ€” an empty override must not yield + // `-x64`/`linux-`. + // NOTE: ProxyIdentity has no platform/arch fields โ€” do not read them off `identity`. + const platform = `${normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_PLATFORM) ?? process.platform}-${normalizePrintableHeaderValue(process.env.ZCODE_IDENTITY_ARCH) ?? os.arch()}`; + const origin = config.claim.origin || "https://zcode.z.ai"; + const appVersion = identity.appVersion; + + const errors: string[] = []; + const [balance, preview] = await Promise.all([ + fetchBilling(origin, `/api/v1/zcode-plan/billing/balance?app_version=${encodeURIComponent(appVersion)}&platform=${encodeURIComponent(platform)}`, headers, fetchImpl), + fetchBilling(origin, `/api/v1/zcode-plan/billing/preview?app_version=${encodeURIComponent(appVersion)}&platform=${encodeURIComponent(platform)}`, headers, fetchImpl), + ]); + if (balance && balance.code !== 0) errors.push(`balance: ${balance.code} ${balance.msg ?? ""}`.trim()); + if (preview && preview.code !== 0) errors.push(`preview: ${preview.code} ${preview.msg ?? ""}`.trim()); + + const balances: QuotaBalanceEntry[] = []; + const balanceData = (balance?.data ?? {}) as { balances?: any[]; server_time?: number }; + for (const b of Array.isArray(balanceData.balances) ? balanceData.balances : []) { + // unitType/expiresAt camelCase aliases observed live alongside snake_case; + // accept both so neither casing drops the field. + const expiresAt = toFiniteNumber(b.expires_at ?? b.expiresAt); + const unitType = b.unit_type ?? b.unitType; + balances.push({ + showName: String(b.show_name ?? ""), + remainingUnits: toFiniteNumber(b.remaining_units ?? b.remainingUnits) ?? 0, + totalUnits: toFiniteNumber(b.total_units ?? b.totalUnits) ?? 0, + usedUnits: toFiniteNumber(b.used_units ?? b.usedUnits) ?? 0, + ...(unitType ? { unitType: String(unitType) } : {}), + ...(expiresAt !== undefined ? { expiresAt } : {}), + }); + } + + const claimablePlans: QuotaPlanEntry[] = []; + const previewData = (preview?.data ?? {}) as { plans?: any[] }; + for (const p of Array.isArray(previewData.plans) ? previewData.plans : []) { + claimablePlans.push({ + planId: String(p.plan_id ?? ""), + name: String(p.name ?? p.plan_id ?? ""), + ...(p.description ? { description: String(p.description) } : {}), + entitlements: (Array.isArray(p.entitlements) ? p.entitlements : []).map((e: any) => ({ + showName: String(e.show_name ?? ""), + grantUnits: toFiniteNumber(e.grant_units ?? e.grantUnits) ?? 0, + unitType: String(e.unit_type ?? e.unitType ?? "token"), + ...(toFiniteNumber(e.effective_at ?? e.effectiveAt) !== undefined + ? { effectiveAt: toFiniteNumber(e.effective_at ?? e.effectiveAt) as number } + : {}), + })), + }); + } + + return { + provider: config.provider, + serverTime: toFiniteNumber(balanceData.server_time) ?? Math.floor(Date.now() / 1000), + jwt, + balances, + claimablePlans, + errors, + }; +} + +/** Handle GET /quota โ€” JSON snapshot with the proxy error envelope on failure. `loadCredentialImpl` is injectable for tests. */ +export async function handleQuota( + config: ProxyConfig, + fetchImpl: typeof fetch = fetch, + loadCredentialImpl: typeof loadCredential = loadCredential, +): Promise { + try { + const snapshot = await collectQuotaSnapshot(config, fetchImpl, loadCredentialImpl); + return new Response(JSON.stringify(snapshot, null, 1), { + status: 200, + headers: { "content-type": "application/json" }, + }); + } catch (e) { + return errorResponse(503, "quota_unavailable", `quota query failed: ${(e as Error).message}`); + } +} diff --git a/src/server/routes-responses.ts b/src/server/routes-responses.ts new file mode 100644 index 0000000000000000000000000000000000000000..f6dcb48dc065820b77a6c2706d797a40b70f175f --- /dev/null +++ b/src/server/routes-responses.ts @@ -0,0 +1,12 @@ +/** + * Responses-format route handler: POST /v1/responses. + */ +import { handleResponses, type ResponsesHandlerOptions } from "../proxy/responses-handler.js"; + +/** Handle POST /v1/responses โ€” translate Responses API to the GLM Chat Completions upstream. */ +export async function handleResponsesRoute( + req: Request, + opts: ResponsesHandlerOptions, +): Promise { + return handleResponses(req, opts); +} diff --git a/src/server/server-options.ts b/src/server/server-options.ts new file mode 100644 index 0000000000000000000000000000000000000000..93aa64b429755dc43de685fe635e23251ec4c752 --- /dev/null +++ b/src/server/server-options.ts @@ -0,0 +1,20 @@ +/** + * `startServer` option assembly shared by every entry that boots the proxy + * in-process (serve / android / tui). + */ +import type { ProxyConfig } from "../config/types.js"; +import type { AuthManager } from "../auth/manager.js"; +import { ResponseStore } from "../responses/store.js"; + +/** Build `startServer` options, wiring the Responses store when its config gate is on. */ +export function buildServerOptions( + config: ProxyConfig, + auth: AuthManager, + debug: boolean, +): { config: ProxyConfig; auth: AuthManager; debug: boolean; responseStore?: ResponseStore } { + const opts: { config: ProxyConfig; auth: AuthManager; debug: boolean; responseStore?: ResponseStore } = { config, auth, debug }; + if (config.responses.enabled) { + opts.responseStore = new ResponseStore({ maxEntries: config.responses.storeMaxEntries, ttlMs: config.responses.storeTtlMs }); + } + return opts; +} diff --git a/src/server/server.ts b/src/server/server.ts new file mode 100644 index 0000000000000000000000000000000000000000..01fc2cac7835b26ce1f4c62e12cc383e34a7595e --- /dev/null +++ b/src/server/server.ts @@ -0,0 +1,329 @@ +/** + * HTTP server bootstrap with routing and proxy API key auth. + * + * Replaces the original `Bun.serve` adapter with `node:http.createServer` so + * the same code runs on Bun (dev mode, source TS) and on Node (Android bundle). + * Bun supports `node:http` natively; Node has no `Bun.serve` equivalent. + * + * @see .omo/plans/zcode-proxy.md Task 7 + */ +import { createServer, type Server } from "node:http"; +import { Readable } from "node:stream"; +import { timingSafeEqual } from "node:crypto"; +import webuiHtml from "./webui.txt" with { type: "text" }; +import type { ProxyConfig } from "../config/types.js"; +import type { AuthManager } from "../auth/manager.js"; +import { handleChatCompletions, handleListModels } from "./routes-openai.js"; +import { handleMessages } from "./routes-anthropic.js"; +import { handleResponsesRoute } from "./routes-responses.js"; +import { handleAsyncMessagesRoute, handleAsyncChatRoute, handleAsyncHealthRoute } from "./routes-async.js"; +import { handleQuota } from "./routes-quota.js"; +import { errorResponse } from "../proxy/handler.js"; +import type { ResponseStore } from "../responses/store.js"; + +interface ServerOptions { + config: ProxyConfig; + auth: AuthManager; + /** Override fetch for testing. */ + fetchImpl?: typeof fetch; + /** When true, enable per-request debug diagnostics in the proxy handler. */ + debug?: boolean; + /** Responses-API state store. When absent, `/v1/responses` runs stateless (`previous_response_id` returns 404). */ + responseStore?: ResponseStore; +} + +/** Minimal server handle: what the caller needs to print URLs and shut down. */ +export interface ProxyServer { + hostname: string; + port: number; + /** Close the server. When `exit` is true, also call `process.exit(0)`. */ + stop(exit?: boolean): void; + /** Promise that resolves once the server has fully stopped. */ + close(): Promise; +} + +/** Create a fetch-style handler that routes the request through the proxy. */ +export function createFetchHandler(opts: ServerOptions): (req: Request) => Promise { + const { config, auth } = opts; + const proxyOpts = { config, auth, fetchImpl: opts.fetchImpl, debug: opts.debug === true }; + const responsesOpts = { + config, + auth, + fetchImpl: opts.fetchImpl, + debug: opts.debug === true, + ...(opts.responseStore ? { responseStore: opts.responseStore } : {}), + }; + const asyncOpts = { + config, + auth, + fetchImpl: opts.fetchImpl, + debug: opts.debug === true, + }; + + return async (req: Request): Promise => { + const url = new URL(req.url); + const path = url.pathname; + const method = req.method; + + // CORS preflight + if (method === "OPTIONS") { + return corsResponse(); + } + + if (method === "GET" && (path === "/webui" || path.startsWith("/webui/"))) { + return new Response(webuiHtml, { + status: 200, + headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" }, + }); + } + + if (config.auth.proxyApiKey) { + const authHeader = req.headers.get("authorization") ?? req.headers.get("x-api-key"); + if (!authHeader || !checkProxyKey(authHeader, config.auth.proxyApiKey)) { + return errorResponse(401, "authentication_error", "Invalid or missing proxy API key"); + } + } + + // --- Routing --- + + if (path === "/v1/chat/completions" && method === "POST") { + return handleChatCompletions(req, proxyOpts); + } + if (config.responses.enabled && path === "/v1/responses" && method === "POST") { + return handleResponsesRoute(req, responsesOpts); + } + if (path === "/v1/models" && method === "GET") { + return handleListModels(req); + } + + if (path === "/quota" && method === "GET") { + return handleQuota(config, opts.fetchImpl); + } + + if (path === "/v1/messages" && method === "POST") { + return handleMessages(req, proxyOpts); + } + + if (config.async.enabled) { + // Off-peak is a coding-plan feature: on start-plan the async routes are + // disabled even when async.enabled=true (explicit error, not a silent 404). + const isAsyncRoute = + (path === "/async/v1/messages" && method === "POST") || + (path === "/async/v1/chat/completions" && method === "POST") || + (path === "/async/v1/health" && method === "GET"); + if (isAsyncRoute && config.plan !== "coding-plan") { + return errorResponse( + 400, + "async_plan_unsupported", + `async (off-peak) endpoints are only available with plan "coding-plan" (current plan: ${config.plan})`, + ); + } + if (path === "/async/v1/messages" && method === "POST") { + return handleAsyncMessagesRoute(req, asyncOpts); + } + if (path === "/async/v1/chat/completions" && method === "POST") { + return handleAsyncChatRoute(req, asyncOpts); + } + if (path === "/async/v1/health" && method === "GET") { + return handleAsyncHealthRoute(req, asyncOpts); + } + } + + if (path === "/health" || path === "/") { + return new Response(JSON.stringify({ status: "ok", provider: config.provider }), { + status: 200, + headers: { "content-type": "application/json" }, + }); + } + + return errorResponse(404, "not_found_error", `No route for ${method} ${path}`); + }; +} + +/** + * Start the HTTP server. Resolves once the listener is bound; the returned + * `ProxyServer.stop()` closes the underlying `node:http.Server`. + * + * `idleTimeout: 0` (the original Bun.serve setting for self-hosted long + * reasoning calls) is mirrored by zeroing Node's request/keep-alive/headers + * timeouts. + */ +export function startServer(opts: ServerOptions): Promise { + const handler = createFetchHandler(opts); + const { port: requestedPort, host } = opts.config.server; + + const server: Server = createServer(async (req, res) => { + const abortController = new AbortController(); + const onClientClose = (): void => { + if (!res.writableEnded) abortController.abort(); + }; + res.on("close", onClientClose); + + // `/async/*` routes can hold the connection open for minutes-to-hours while + // waiting for an off-peak ticket. Lift the per-request socket timeout from + // the default 600s (set below via server.requestTimeout) to 24h so the long + // queue wait + LLM stream doesn't get killed mid-flight. Non-async routes + // keep the default timeout. + if ((req.url ?? "").startsWith("/async/")) { + req.setTimeout(24 * 60 * 60 * 1000); + } + + try { + const webReq = nodeReqToWebRequest(req, abortController.signal); + const resp = await handler(webReq).then((r) => addCorsHeaders(r)); + await writeWebResponseToNodeResp(resp, res, abortController.signal); + } catch (err) { + if (abortController.signal.aborted) return; + if (!res.headersSent) { + res.writeHead(500, { "content-type": "application/json" }); + res.end(JSON.stringify({ error: { type: "internal_error", message: (err as Error).message } })); + } else { + try { res.end(); } catch {} + } + } + }); + + // Disable all Node HTTP server timeouts to match Bun's `idleTimeout: 0`. + // Long LLM reasoning calls (60-120s before first token) would otherwise + // be killed by Node's defaults. + server.requestTimeout = 600_000; + server.keepAliveTimeout = 120_000; + server.headersTimeout = 600_000; + + return new Promise((resolve, reject) => { + server.on("error", reject); + server.listen(requestedPort, host, () => { + const addr = server.address(); + const actualPort = typeof addr === "object" && addr ? addr.port : requestedPort; + resolve({ + hostname: host, + port: actualPort, + stop: (exit) => { + server.close(); + if (exit) process.exit(0); + }, + close: () => new Promise((r) => server.close(() => r())), + }); + }); + }); +} + +/** Convert a Node.js IncomingMessage to a Web API Request. */ +function nodeReqToWebRequest(req: import("node:http").IncomingMessage, signal?: AbortSignal): Request { + const headers = new Headers(); + for (const [key, val] of Object.entries(req.headers)) { + if (val == null) continue; + if (Array.isArray(val)) { + for (const v of val) headers.append(key, v); + } else { + headers.set(key, val); + } + } + const host = headers.get("host") ?? "localhost"; + const url = `http://${host}${req.url ?? "/"}`; + const method = req.method ?? "GET"; + + if (method === "GET" || method === "HEAD") { + return new Request(url, { method, headers, signal }); + } + + // Cast: Node's ReadableStream type โ‰  Web ReadableStream type at the type layer, but `Readable.toWeb` returns a spec-compliant stream at runtime. + const bodyStream = Readable.toWeb(req) as unknown as ReadableStream; + const init: RequestInit & { duplex?: "half" } = { + method, + headers, + body: bodyStream, + duplex: "half", + signal, + }; + return new Request(url, init); +} + +/** Write a Web API Response to a Node.js ServerResponse. */ +async function writeWebResponseToNodeResp(resp: Response, res: import("node:http").ServerResponse, abortSignal?: AbortSignal): Promise { + const headers: Record = {}; + resp.headers.forEach((value, key) => { + const existing = headers[key]; + if (existing === undefined) { + headers[key] = value; + } else if (typeof existing === "string") { + headers[key] = [existing, value]; + } else { + existing.push(value); + } + }); + + res.writeHead(resp.status, resp.statusText, headers); + + if (resp.body == null) { + res.end(); + return; + } + + const reader = resp.body.getReader(); + const onAbort = (): void => { reader.cancel().catch(() => {}); }; + abortSignal?.addEventListener("abort", onAbort); + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + if (!res.write(Buffer.from(value))) { + await new Promise((resolve) => res.once("drain", () => resolve())); + } + } + res.end(); + } catch (err) { + if (abortSignal?.aborted) { + try { res.end(); } catch {} + } else { + try { res.destroy(err as Error); } catch {} + } + } finally { + abortSignal?.removeEventListener("abort", onAbort); + } +} + +/** + * Check whether the client provided the correct proxy API key. + * Constant-time comparison (audit R2-10): a plain `===` on the presented vs + * expected key is a timing side channel on public-network deployments + * (default bind is 0.0.0.0). Behavior is unchanged for honest callers. + */ +function checkProxyKey(authHeader: string, expected: string): boolean { + const trimmed = authHeader.trim(); + const presented = trimmed.startsWith("Bearer ") ? trimmed.slice(7).trim() : trimmed; + const a = Buffer.from(presented, "utf-8"); + const b = Buffer.from(expected, "utf-8"); + if (a.length !== b.length) return false; + return timingSafeEqual(a, b); +} + +/** Build a CORS preflight response. */ +function corsResponse(): Response { + return new Response(null, { + status: 204, + headers: corsHeaders(), + }); +} + +/** Add CORS headers to an existing response (non-mutating). */ +function addCorsHeaders(resp: Response): Response { + const headers = new Headers(resp.headers); + for (const [k, v] of Object.entries(corsHeaders())) { + headers.set(k, v); + } + return new Response(resp.body, { + status: resp.status, + statusText: resp.statusText, + headers, + }); +} + +function corsHeaders(): Record { + return { + "access-control-allow-origin": "*", + "access-control-allow-methods": "GET, POST, OPTIONS", + "access-control-allow-headers": "Content-Type, Authorization, x-api-key, anthropic-version, anthropic-beta", + "access-control-max-age": "86400", + }; +} diff --git a/src/server/webui.txt b/src/server/webui.txt new file mode 100644 index 0000000000000000000000000000000000000000..c83ce5c426a6f4a2e1d436bc065e6f8452128224 --- /dev/null +++ b/src/server/webui.txt @@ -0,0 +1,1420 @@ + + + + + + + zcode-proxy + + + + + + + + +
+ + + + +
+
+ + +
+ +
+
+
+ +
+
+
+ +
+
+
+ +
+
+ + +
+ + +
+
+
+ +
+
+
+ + +
+ +
+ +
+ + + + diff --git a/src/translator/anthropic-to-openai.ts b/src/translator/anthropic-to-openai.ts new file mode 100644 index 0000000000000000000000000000000000000000..6eefa21388ce1a3728883aaddeae76de9c9c2cad --- /dev/null +++ b/src/translator/anthropic-to-openai.ts @@ -0,0 +1,321 @@ +/** + * Anthropic โ†’ OpenAI request translator and OpenAI โ†’ Anthropic response translator. + * @see .omo/plans/zcode-proxy.md Task 11 + */ +import type { + OpenAIChatRequest, + OpenAIChatResponse, + OpenAIUsage, + OpenAIMessage, + OpenAIContentPart, + OpenAIToolCall, + AnthropicMessagesRequest, + AnthropicMessagesResponse, + AnthropicMessage, + AnthropicContentBlock, + AnthropicUsage, +} from "./types.js"; +import { isGlm53Model } from "../provider/reasoning.js"; + +/** Translate an Anthropic messages request into an OpenAI chat request. */ +export function translateRequestAnthropicToOpenAI(req: AnthropicMessagesRequest): OpenAIChatRequest { + const messages: OpenAIMessage[] = []; + + if (req.system) { + const systemText = typeof req.system === "string" + ? req.system + : req.system.map((s) => s.text).join("\n"); + messages.push({ role: "system", content: systemText }); + } + + for (const m of req.messages) { + messages.push(...translateMessageAnthropicToOpenAI(m)); + } + + const result: OpenAIChatRequest = { + model: req.model, + messages, + ...(req.temperature !== undefined ? { temperature: req.temperature } : {}), + ...(req.top_p !== undefined ? { top_p: req.top_p } : {}), + ...(req.stream !== undefined ? { stream: req.stream } : {}), + ...(req.max_tokens !== undefined ? { max_tokens: req.max_tokens } : {}), + }; + + if (req.stop_sequences?.length) { + result.stop = req.stop_sequences.length === 1 ? req.stop_sequences[0] : req.stop_sequences; + } + + if (req.thinking) { + result.thinking = req.thinking; + } + + // GLM-5.3+ Anthropic clients set reasoning effort via `output_config.effort` + // (the Anthropic upstream ignores `reasoning_effort`); the OpenAI-format + // upstream on start-plan reads `reasoning_effort` instead, so carry it over. + // + // Scoped to the GLM-5.3 family, which is the only one that defines + // `output_config`. Carrying it over unconditionally would let a client that + // sends `output_config` on any other model silently change that model's + // reasoning behaviour through a channel it never opted into. + if (isGlm53Model(req.model) && req.output_config?.effort) { + result.reasoning_effort = req.output_config.effort as OpenAIChatRequest["reasoning_effort"]; + } + + if (req.tools?.length) { + result.tools = req.tools.map((t) => ({ + type: "function" as const, + function: { + name: t.name, + ...(t.description ? { description: t.description } : {}), + ...(t.input_schema ? { parameters: t.input_schema } : {}), + }, + })); + } + + if (req.tool_choice) { + const translated = mapToolChoiceAnthropicToOpenAI(req.tool_choice); + if (translated !== undefined) result.tool_choice = translated; + } + + return result; +} + +/** + * Map an Anthropic `tool_choice` to the OpenAI Chat Completions form. + * + * Anthropic: `{type:"auto"|"any"|"tool", name?}` (a top-level string is also + * accepted by the API). There is no `none` โ€” suppressing tools is done by + * omitting the `tools` array entirely. + * OpenAI: `"auto" | "required"` or `{type:"function", function:{name}}`. + * Note: Anthropic `any` (force some tool) maps to OpenAI `required`. + */ +function mapToolChoiceAnthropicToOpenAI( + choice: { type: "auto" | "any" | "tool"; name?: string }, +): "auto" | "required" | { type: "function"; function: { name: string | undefined } } | undefined { + switch (choice.type) { + case "auto": + return "auto"; + case "any": + return "required"; + case "tool": + // Pass `name` through verbatim (possibly undefined). Anthropic mandates a + // name for type:"tool", so a missing one is a client contract violation โ€” + // forwarding it lets the upstream reject with its native error rather than + // masking the bug behind a synthetic empty function name. + return { type: "function", function: { name: choice.name } }; + default: + return undefined; + } +} + +/** Translate an OpenAI chat response into an Anthropic messages response. */ +export function translateResponseOpenAIToAnthropic( + resp: OpenAIChatResponse, +): AnthropicMessagesResponse { + const choice = resp.choices?.[0]; + const content: AnthropicContentBlock[] = []; + + if (choice?.message?.reasoning_content) { + content.push({ type: "thinking", thinking: choice.message.reasoning_content }); + } + + if (choice?.message?.content) { + const textContent = typeof choice.message.content === "string" + ? choice.message.content + : Array.isArray(choice.message.content) + ? choice.message.content.filter((c) => c.type === "text").map((c) => c.text ?? "").join("") + : ""; + if (textContent) content.push({ type: "text", text: textContent }); + } + + if (choice?.message?.tool_calls) { + for (const tc of choice.message.tool_calls) { + let input: Record = {}; + try { + input = JSON.parse(tc.function.arguments); + } catch { + input = {}; + } + content.push({ + type: "tool_use", + id: tc.id, + name: tc.function.name, + input, + }); + } + } + + const stopReason = mapFinishReasonToStopReason(choice?.finish_reason); + + return { + id: resp.id, + type: "message", + role: "assistant", + content: content.length > 0 ? content : [{ type: "text", text: "" }], + model: resp.model, + stop_reason: stopReason, + stop_sequence: null, + usage: openaiUsageToAnthropic(resp.usage), + }; +} + +/** + * Translate a single Anthropic message into one or more OpenAI messages. + * + * A single Anthropic message can fan out to multiple OpenAI messages because + * `tool_result` blocks must become standalone `role:"tool"` messages (OpenAI + * has no inline equivalent). The carrier message (text/image/tool_use) is + * emitted last, preserving the Anthropic role for text/assistant content. + */ +function translateMessageAnthropicToOpenAI(m: AnthropicMessage): OpenAIMessage[] { + if (typeof m.content === "string") { + return [{ role: m.role, content: m.content }]; + } + + const result: OpenAIMessage[] = []; + const contentParts: OpenAIContentPart[] = []; + const toolCalls: OpenAIToolCall[] = []; + const reasoningParts: string[] = []; + + for (const block of m.content) { + switch (block.type) { + case "text": { + contentParts.push({ type: "text", text: block.text }); + break; + } + case "image": { + if (block.source.type === "base64") { + contentParts.push({ + type: "image_url", + image_url: { url: `data:${block.source.media_type};base64,${block.source.data}` }, + }); + } else if (block.source.type === "url") { + contentParts.push({ + type: "image_url", + image_url: { url: block.source.url }, + }); + } + break; + } + case "tool_use": { + toolCalls.push({ + id: block.id, + type: "function", + function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) }, + }); + break; + } + case "tool_result": { + result.push({ + role: "tool", + tool_call_id: block.tool_use_id, + content: toolResultContentToOpenAI(block.content, block.is_error === true), + }); + break; + } + case "thinking": { + if (block.thinking.length > 0) reasoningParts.push(block.thinking); + break; + } + default: + break; + } + } + + // Emit the carrier message when there is text/image content, tool calls, or + // assistant reasoning โ€” otherwise a thinking-only assistant turn would lose + // its reasoning_content (and the next user turn would be misaligned). + const hasReasoning = m.role === "assistant" && reasoningParts.length > 0; + if (contentParts.length > 0 || toolCalls.length > 0 || hasReasoning) { + const content: string | null | OpenAIContentPart[] = contentParts.length === 0 + ? null + : contentParts.length === 1 && contentParts[0].type === "text" + ? contentParts[0].text ?? "" + : contentParts; + result.push({ + role: m.role, + content, + ...(hasReasoning ? { reasoning_content: reasoningParts.join("\n") } : {}), + ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}), + }); + } + + // Guarantee at least one message so the turn isn't silently dropped. + if (result.length === 0) { + result.push({ role: m.role, content: null }); + } + + return result; +} + +/** + * Flatten an Anthropic tool_result `content` field into an OpenAI tool-message + * `content` string. Text blocks are joined; non-text blocks are JSON-serialized + * to avoid data loss (OpenAI tool messages are stringly-typed). + * + * OpenAI has no native "this tool call failed" flag, so a truthy `isError` + * (Anthropic's `tool_result.is_error`) is encoded as a leading `[tool_error]` + * marker so the downstream model can still tell a failed execution from a + * successful one. + */ +function toolResultContentToOpenAI( + content: string | AnthropicContentBlock[] | undefined, + isError: boolean, +): string { + const body = flattenToolResultContent(content); + return isError && body.length > 0 ? `[tool_error] ${body}` : body; +} + +function flattenToolResultContent(content: string | AnthropicContentBlock[] | undefined): string { + if (typeof content === "string") return content; + if (!Array.isArray(content)) return ""; + const texts = content + .filter((b) => b.type === "text") + .map((b) => b.text); + if (texts.length > 0) return texts.join(""); + return JSON.stringify(content); +} + +function mapFinishReasonToStopReason( + finishReason: string | null | undefined, +): "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | null { + switch (finishReason) { + case "stop": + return "end_turn"; + case "length": + return "max_tokens"; + case "tool_calls": + return "tool_use"; + case "content_filter": + return "end_turn"; + default: + return null; + } +} + +/** + * Convert an OpenAI usage block into Anthropic usage semantics. + * + * OpenAI `prompt_tokens` is *inclusive* of cache hits, while Anthropic + * `input_tokens` is the fresh (uncached) input. The three buckets are mutually + * exclusive and sum to `prompt_tokens`: `input + cache_read + cache_creation`. + * Cache values are accepted from either the standard `prompt_tokens_details` + * breakdown or Anthropic-style direct fields (some compatible upstreams emit + * those). Missing buckets default to 0, so a vanilla OpenAI usage with no cache + * fields passes through unchanged. + */ +export function openaiUsageToAnthropic(usage: OpenAIUsage | undefined): AnthropicUsage { + const promptTokens = usage?.prompt_tokens ?? 0; + const cacheRead = usage?.cache_read_input_tokens + ?? usage?.prompt_tokens_details?.cached_tokens + ?? 0; + const cacheCreation = usage?.cache_creation_input_tokens ?? 0; + const inputTokens = Math.max(0, promptTokens - cacheRead - cacheCreation); + const result: AnthropicUsage = { + input_tokens: inputTokens, + output_tokens: usage?.completion_tokens ?? 0, + }; + if (cacheRead > 0) result.cache_read_input_tokens = cacheRead; + if (cacheCreation > 0) result.cache_creation_input_tokens = cacheCreation; + return result; +} diff --git a/src/translator/chat-to-responses.ts b/src/translator/chat-to-responses.ts new file mode 100644 index 0000000000000000000000000000000000000000..72fac94d8f79a911bac8bdad2fcd76432ab2bccc --- /dev/null +++ b/src/translator/chat-to-responses.ts @@ -0,0 +1,862 @@ +/** + * Chat Completions โ†’ Responses API translation. + * + * Two entry points: + * - `chatCompletionsToResponses()` โ€” batch response translation. + * - `chatCompletionsSseToResponsesStream()` โ€” streaming SSE translation, + * producing the full Responses event lifecycle Codex requires: + * `response.created` + * โ†’ `response.output_item.added` (reasoning) + * โ†’ `reasoning_summary_part.added` / `delta` / `done` / `part.done` / `output_item.done` + * โ†’ `response.output_item.added` (message) + * โ†’ `content_part.added` / `output_text.delta` / `output_text.done` / `content_part.done` / `output_item.done` + * โ†’ per tool_call: `output_item.added` โ†’ `function_call_arguments.delta`* โ†’ `.done` + `output_item.done` + * โ†’ `response.completed` + * + * Reasoning/tool-call lifecycle completeness is non-negotiable: without + * `function_call_arguments.done` + `output_item.done` Codex never finalises the + * call and the session wedges (verified against sub2api's + * `closeChatToolItems`). + * + * Namespace/custom/tool_search tool calls are restored to their Responses + * item type using the bookkeeping from `responsesToChatCompletions()`. + */ +import type { + OpenAIChatResponse, + OpenAIChoice, + OpenAIMessage, + OpenAIUsage, + OpenAIStreamChunk, + OpenAIStreamChoice, +} from "./types.js"; +import type { + ResponsesResponse, + ResponsesOutputItem, + ResponsesContentPart, + ResponsesStreamEvent, + ResponsesUsage, +} from "./responses-types.js"; +import { generateResponsesId, generateItemId, generateCallId } from "./responses-types.js"; +import type { ResponsesToChatResult } from "./responses-to-chat.js"; + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Batch translation +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +export interface ChatToResponsesOptions { + /** Bookkeeping from the request translation (custom/namespace/tool_search maps). */ + meta?: Pick; + /** Optional override id (otherwise generated). */ + responseId?: string; + /** Optional `instructions` echoed onto the response (OpenAI does this). */ + instructions?: string; + /** Optional `previous_response_id` echoed onto the response. */ + previousResponseId?: string; +} + +/** Translate a non-streaming Chat Completions response into a Responses response. */ +export function chatCompletionsToResponses( + resp: OpenAIChatResponse, + model: string, + opts: ChatToResponsesOptions = {}, +): ResponsesResponse { + const id = opts.responseId ?? generateResponsesId(); + const choice = resp.choices?.[0]; + + const output: ResponsesOutputItem[] = []; + if (choice) { + const items = chatChoiceToOutputItems(choice, opts.meta); + output.push(...items); + } + if (output.length === 0) { + output.push(emptyMessageOutput()); + } + + const status: ResponsesResponse["status"] = choice?.finish_reason === "length" ? "incomplete" : "completed"; + const incomplete = status === "incomplete" + ? { reason: "max_output_tokens" } + : undefined; + + return { + id, + object: "response", + created_at: Date.now(), + model: model || resp.model || "", + status, + output, + ...(incomplete ? { incomplete_details: incomplete } : {}), + ...(resp.usage ? { usage: chatUsageToResponsesUsage(resp.usage) } : {}), + ...(opts.instructions ? { instructions: opts.instructions } : {}), + ...(opts.previousResponseId ? { previous_response_id: opts.previousResponseId } : {}), + }; +} + +/** Convert a single Chat choice into one or more Responses output items. */ +function chatChoiceToOutputItems( + choice: OpenAIChoice, + meta: ChatToResponsesOptions["meta"], +): ResponsesOutputItem[] { + const items: ResponsesOutputItem[] = []; + const msg = choice.message; + + if (msg?.reasoning_content) { + items.push({ + type: "reasoning", + id: generateItemId(), + summary: [{ type: "summary_text", text: msg.reasoning_content }], + status: "completed", + }); + } + + const text = extractAssistantText(msg); + const toolCalls = msg?.tool_calls ?? []; + const customNames = meta?.customToolNames ?? new Set(); + const nsMap = meta?.namespaceMap ?? new Map(); + const hasToolSearch = meta?.hasToolSearch === true; + + // Message item: emit when there's text, or when there are no tool calls + // (Codex expects at least one output item; an empty message is the safe default). + if (text.length > 0 || toolCalls.length === 0) { + items.push({ + type: "message", + id: generateItemId(), + role: "assistant", + content: [{ type: "output_text", text }], + status: "completed", + }); + } + + for (const tc of toolCalls) { + const flatName = tc.function.name; + const args = tc.function.arguments && tc.function.arguments.trim().length > 0 + ? tc.function.arguments + : "{}"; + + // Restore custom tools (input extracted from {input:"..."}). + if (customNames.has(flatName)) { + const inputStr = extractCustomToolInput(args); + items.push({ + type: "custom_tool_call", + id: generateItemId(), + call_id: tc.id || generateCallId(), + name: flatName, + input: inputStr, + status: "completed", + }); + continue; + } + + // Restore tool_search (must be `tool_search_call` with execution:"client"). + if (flatName === "tool_search" && hasToolSearch) { + let argsObj: Record = {}; + try { argsObj = JSON.parse(args); } catch { argsObj = {}; } + items.push({ + type: "tool_search_call", + id: generateItemId(), + call_id: tc.id || generateCallId(), + arguments: argsObj, + execution: "client", + status: "completed", + }); + continue; + } + + // Restore namespace tools (flatten name โ†’ {namespace, name}). + const ns = nsMap.get(flatName); + if (ns) { + items.push({ + type: "function_call", + id: generateItemId(), + call_id: tc.id || generateCallId(), + name: ns.name, + namespace: ns.namespace, + arguments: args, + status: "completed", + }); + continue; + } + + // Plain function_call. + items.push({ + type: "function_call", + id: generateItemId(), + call_id: tc.id || generateCallId(), + name: flatName, + arguments: args, + status: "completed", + }); + } + + return items; +} + +function emptyMessageOutput(): ResponsesOutputItem { + return { + type: "message", + id: generateItemId(), + role: "assistant", + content: [{ type: "output_text", text: "" }], + status: "completed", + }; +} + +function extractAssistantText(msg: OpenAIMessage | undefined): string { + if (!msg) return ""; + if (typeof msg.content === "string") return msg.content; + if (Array.isArray(msg.content)) { + return msg.content + .filter((c) => c.type === "text" && typeof c.text === "string") + .map((c) => c.text as string) + .join("\n"); + } + return ""; +} + +/** + * Extract the `input` string from a custom-tool-call's arguments. + * The translator wrapped the input as `{input:"..."}` on the way out; on the + * way back we try to parse it. If the model produced malformed JSON, fall back + * to the raw argument text (sub2api rule). + */ +export function extractCustomToolInput(rawArgs: string): string { + try { + const obj = JSON.parse(rawArgs) as { input?: unknown }; + if (typeof obj.input === "string") return obj.input; + } catch { + // fallthrough โ€” raw text (some models emit the bare string). + } + return rawArgs; +} + +function chatUsageToResponsesUsage(u: OpenAIUsage): ResponsesUsage { + return { + input_tokens: u.prompt_tokens ?? 0, + output_tokens: u.completion_tokens ?? 0, + total_tokens: u.total_tokens ?? (u.prompt_tokens ?? 0) + (u.completion_tokens ?? 0), + ...(u.prompt_tokens_details?.cached_tokens ? { input_tokens_details: { cached_tokens: u.prompt_tokens_details.cached_tokens } } : {}), + ...(u.output_tokens_details?.reasoning_tokens ? { output_tokens_details: { reasoning_tokens: u.output_tokens_details.reasoning_tokens } } : {}), + }; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Streaming translation +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** + * Stateful converter: feed it Chat SSE chunks, get Responses SSE events. + * Lifecycle mirrors sub2api's `ChatCompletionsToResponsesStreamState`: + * - reasoning item opened lazily on first `reasoning_content` delta, closed + * before the message item or any tool call opens. + * - message item + `output_text` content part opened lazily on first content delta. + * - tool calls tracked by upstream index; each emits output_item.added โ†’ + * function_call_arguments.delta(s) โ†’ arguments.done + output_item.done. + * - On `finish_reason`, emit the terminal events for every open item, then + * `response.completed` carrying the full reconstructed `output[]`. + */ +export interface ResponsesStreamState { + responseId: string; + model: string; + createdAt: number; + sequenceNumber: number; + createdSent: boolean; + completedSent: boolean; + + // Output-index allocator (matches final `output[]` ordering). + nextOutputIndex: number; + + // Reasoning item lifecycle. + reasoningItemId: string | undefined; + reasoningIndex: number; + reasoningOpen: boolean; + reasoningDone: boolean; + reasoningText: string; + + // Message item + output_text content-part lifecycle. + messageItemId: string | undefined; + messageIndex: number; + textPartOpen: boolean; + text: string; + + // Tool-call lifecycle, keyed by the upstream tool_call index. + toolCalls: Map; + + finishReason: string | undefined; + usage: ResponsesUsage | undefined; + meta: ChatToResponsesOptions["meta"]; +} + +export function newResponsesStreamState( + model: string, + opts: { + meta?: ChatToResponsesOptions["meta"]; + responseId?: string; + } = {}, +): ResponsesStreamState { + return { + responseId: opts.responseId ?? generateResponsesId(), + model, + createdAt: Date.now(), + sequenceNumber: 0, + createdSent: false, + completedSent: false, + nextOutputIndex: 0, + reasoningItemId: undefined, + reasoningIndex: -1, + reasoningOpen: false, + reasoningDone: false, + reasoningText: "", + messageItemId: undefined, + messageIndex: -1, + textPartOpen: false, + text: "", + toolCalls: new Map(), + finishReason: undefined, + usage: undefined, + meta: opts.meta, + }; +} + +/** + * Convert one Chat SSE chunk into zero or more Responses SSE events. + * Stateless aside from the `state` argument โ€” caller drives the loop. + */ +export function chatChunkToResponsesEvents( + chunk: OpenAIStreamChunk, + state: ResponsesStreamState, +): ResponsesStreamEvent[] { + const events: ResponsesStreamEvent[] = []; + events.push(...ensureCreated(state)); + + if (chunk.model && !state.model) state.model = chunk.model; + if (chunk.usage) state.usage = chatUsageToResponsesUsage(chunk.usage); + + for (const choice of chunk.choices ?? []) { + events.push(...handleChoice(choice, state)); + } + + return events; +} + +function handleChoice(choice: OpenAIStreamChoice, state: ResponsesStreamState): ResponsesStreamEvent[] { + const events: ResponsesStreamEvent[] = []; + const delta = choice.delta ?? {}; + + // โ”€โ”€ reasoning โ”€โ”€ + if (delta.reasoning_content && delta.reasoning_content.length > 0) { + events.push(...ensureReasoningItem(state)); + state.reasoningText += delta.reasoning_content; + events.push(seq(state, { + type: "response.reasoning_summary_text.delta", + output_index: state.reasoningIndex, + summary_index: 0, + delta: delta.reasoning_content, + item_id: state.reasoningItemId, + })); + } + + // โ”€โ”€ content โ”€โ”€ + if (typeof delta.content === "string" && delta.content.length > 0) { + events.push(...closeReasoningItem(state)); + events.push(...ensureMessageItem(state)); + events.push(...ensureTextPart(state)); + state.text += delta.content; + events.push(seq(state, { + type: "response.output_text.delta", + output_index: state.messageIndex, + content_index: 0, + delta: delta.content, + item_id: state.messageItemId, + })); + } + + // โ”€โ”€ tool calls โ”€โ”€ + for (const tc of delta.tool_calls ?? []) { + const idx = tc.index ?? 0; + let entry = state.toolCalls.get(idx); + if (!entry) { + // First chunk for this tool call: close reasoning, open the item. + events.push(...closeReasoningItem(state)); + const itemId = generateItemId(); + const outputIndex = allocIndex(state); + const callId = tc.id || generateCallId(); + const name = tc.function?.name ?? ""; + entry = { id: callId, name, args: "", itemId, outputIndex }; + state.toolCalls.set(idx, entry); + // GLM sometimes packs id+name+arguments into the first chunk; reset args + // here so the append below doesn't double them (sub2api bug fix). + const initialArgs = tc.function?.arguments ?? ""; + entry.args += initialArgs; + events.push(seq(state, { + type: "response.output_item.added", + output_index: outputIndex, + item: toolCallAddedItem(entry, state.meta), + })); + if (initialArgs.length > 0) { + events.push(seq(state, toolArgsDeltaEvent(entry, initialArgs, state))); + } + } else { + // Continuation chunk. + if (tc.id) entry.id = tc.id; + if (tc.function?.name) entry.name = tc.function.name; + const argDelta = tc.function?.arguments ?? ""; + if (argDelta.length > 0) { + entry.args += argDelta; + events.push(seq(state, toolArgsDeltaEvent(entry, argDelta, state))); + } + } + } + + if (choice.finish_reason) { + state.finishReason = choice.finish_reason; + } + + return events; +} + +/** Build the `output_item.added` item shape for a tool call, restoring custom/tool_search/namespace types. */ +function toolCallAddedItem( + entry: { id: string; name: string; args: string; itemId: string }, + meta: ChatToResponsesOptions["meta"], +): ResponsesOutputItem { + const customNames = meta?.customToolNames ?? new Set(); + const nsMap = meta?.namespaceMap ?? new Map(); + const hasToolSearch = meta?.hasToolSearch === true; + + if (customNames.has(entry.name)) { + return { + type: "custom_tool_call", + id: entry.itemId, + call_id: entry.id, + name: entry.name, + input: "", // final value emitted at output_item.done + status: "in_progress", + }; + } + if (entry.name === "tool_search" && hasToolSearch) { + return { + type: "tool_search_call", + id: entry.itemId, + call_id: entry.id, + execution: "client", + status: "in_progress", + }; + } + const ns = nsMap.get(entry.name); + if (ns) { + return { + type: "function_call", + id: entry.itemId, + call_id: entry.id, + name: ns.name, + namespace: ns.namespace, + status: "in_progress", + }; + } + return { + type: "function_call", + id: entry.itemId, + call_id: entry.id, + name: entry.name, + status: "in_progress", + }; +} + +/** Choose the right "args delta" event for the tool type (function vs custom). */ +function toolArgsDeltaEvent( + entry: { id: string; name: string; args: string; itemId: string; outputIndex: number }, + delta: string, + state: ResponsesStreamState, +): ResponsesStreamEvent { + const customNames = state.meta?.customToolNames ?? new Set(); + const isCustom = customNames.has(entry.name); + const base = { + output_index: entry.outputIndex, + delta, + item_id: entry.itemId, + call_id: entry.id, + name: entry.name, + }; + return seq(state, isCustom + ? { type: "response.custom_tool_call_input.delta", ...base } + : { type: "response.function_call_arguments.delta", ...base }); +} + +/** + * Emit terminal events for all open items, then `response.completed`. + * Idempotent via `state.completedSent`. + */ +export function finalizeResponsesStream(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (state.completedSent) return []; + const events: ResponsesStreamEvent[] = []; + events.push(...ensureCreated(state)); + events.push(...closeReasoningItem(state)); + events.push(...synthesizeReasoningFallbackMessage(state)); + events.push(...closeMessageItem(state)); + events.push(...closeToolItems(state)); + + const status: ResponsesResponse["status"] = state.finishReason === "length" ? "incomplete" : "completed"; + const incomplete = status === "incomplete" ? { reason: "max_output_tokens" } : undefined; + + state.completedSent = true; + events.push(seq(state, { + type: status === "incomplete" ? "response.incomplete" : "response.completed", + response: { + id: state.responseId, + object: "response", + created_at: state.createdAt, + model: state.model, + status, + output: buildFinalOutput(state), + ...(incomplete ? { incomplete_details: incomplete } : {}), + ...(state.usage ? { usage: state.usage } : {}), + }, + })); + return events; +} + +function ensureCreated(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (state.createdSent) return []; + state.createdSent = true; + return [seq(state, { + type: "response.created", + response: { + id: state.responseId, + object: "response", + created_at: state.createdAt, + model: state.model, + status: "in_progress", + output: [], + }, + })]; +} + +function ensureReasoningItem(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (state.reasoningOpen || state.reasoningDone) return []; + state.reasoningOpen = true; + state.reasoningItemId = generateItemId(); + state.reasoningIndex = allocIndex(state); + return [ + seq(state, { + type: "response.output_item.added", + output_index: state.reasoningIndex, + item: { type: "reasoning", id: state.reasoningItemId, status: "in_progress" }, + }), + seq(state, { + type: "response.reasoning_summary_part.added", + output_index: state.reasoningIndex, + summary_index: 0, + item_id: state.reasoningItemId, + part: { type: "summary_text" }, + }), + ]; +} + +function closeReasoningItem(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (!state.reasoningOpen) return []; + state.reasoningOpen = false; + state.reasoningDone = true; + const text = state.reasoningText; + return [ + seq(state, { + type: "response.reasoning_summary_text.done", + output_index: state.reasoningIndex, + summary_index: 0, + text, + item_id: state.reasoningItemId, + }), + seq(state, { + type: "response.reasoning_summary_part.done", + output_index: state.reasoningIndex, + summary_index: 0, + item_id: state.reasoningItemId, + part: { type: "summary_text", text }, + }), + seq(state, { + type: "response.output_item.done", + output_index: state.reasoningIndex, + item: { + type: "reasoning", + id: state.reasoningItemId, + status: "completed", + summary: [{ type: "summary_text", text }], + }, + }), + ]; +} + +/** + * Some upstreams (DeepSeek-style) stream reasoning but no content and no tool + * calls. Codex renders nothing in that case unless we synthesise a message + * item from the reasoning text. Mirror sub2api's behaviour. + */ +function synthesizeReasoningFallbackMessage(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (state.messageItemId || state.text.length > 0 || state.reasoningText.length === 0 || state.toolCalls.size > 0) { + return []; + } + const text = state.reasoningText; + if (text.trim().length === 0) return []; + const events: ResponsesStreamEvent[] = []; + events.push(...ensureMessageItem(state)); + events.push(...ensureTextPart(state)); + state.text = text; + events.push(seq(state, { + type: "response.output_text.delta", + output_index: state.messageIndex, + content_index: 0, + delta: text, + item_id: state.messageItemId, + })); + return events; +} + +function ensureMessageItem(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (state.messageItemId) return []; + state.messageItemId = generateItemId(); + state.messageIndex = allocIndex(state); + return [seq(state, { + type: "response.output_item.added", + output_index: state.messageIndex, + item: { + type: "message", + id: state.messageItemId, + role: "assistant", + status: "in_progress", + content: [{ type: "output_text" }], + }, + })]; +} + +function ensureTextPart(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (state.textPartOpen) return []; + state.textPartOpen = true; + return [seq(state, { + type: "response.content_part.added", + output_index: state.messageIndex, + content_index: 0, + item_id: state.messageItemId, + part: { type: "output_text", text: "" }, + })]; +} + +function closeMessageItem(state: ResponsesStreamState): ResponsesStreamEvent[] { + if (!state.messageItemId) return []; + const events: ResponsesStreamEvent[] = []; + if (state.textPartOpen) { + events.push(seq(state, { + type: "response.output_text.done", + output_index: state.messageIndex, + content_index: 0, + text: state.text, + item_id: state.messageItemId, + })); + events.push(seq(state, { + type: "response.content_part.done", + output_index: state.messageIndex, + content_index: 0, + item_id: state.messageItemId, + part: { type: "output_text", text: state.text }, + })); + } + events.push(seq(state, { + type: "response.output_item.done", + output_index: state.messageIndex, + item: { + type: "message", + id: state.messageItemId, + role: "assistant", + status: "completed", + content: [{ type: "output_text", text: state.text }], + }, + })); + return events; +} + +function closeToolItems(state: ResponsesStreamState): ResponsesStreamEvent[] { + const events: ResponsesStreamEvent[] = []; + // Emit in index order (some upstreams deliver out-of-order). + const sortedKeys = [...state.toolCalls.keys()].sort((a, b) => a - b); + for (const idx of sortedKeys) { + const entry = state.toolCalls.get(idx)!; + const customNames = state.meta?.customToolNames ?? new Set(); + const nsMap = state.meta?.namespaceMap ?? new Map(); + const hasToolSearch = state.meta?.hasToolSearch === true; + const isCustom = customNames.has(entry.name); + const isToolSearch = entry.name === "tool_search" && hasToolSearch; + const ns = nsMap.get(entry.name); + const finalArgs = entry.args.trim().length === 0 ? "{}" : entry.args; + + // args.done event (function vs custom differ in event name + payload key). + if (isCustom) { + const inputStr = extractCustomToolInput(finalArgs); + events.push(seq(state, { + type: "response.custom_tool_call_input.done", + output_index: entry.outputIndex, + input: inputStr, + item_id: entry.itemId, + call_id: entry.id, + name: entry.name, + })); + events.push(seq(state, { + type: "response.output_item.done", + output_index: entry.outputIndex, + item: { + type: "custom_tool_call", + id: entry.itemId, + call_id: entry.id, + name: entry.name, + input: inputStr, + status: "completed", + }, + })); + } else if (isToolSearch) { + let argsObj: Record = {}; + try { argsObj = JSON.parse(finalArgs); } catch { argsObj = {}; } + events.push(seq(state, { + type: "response.function_call_arguments.done", + output_index: entry.outputIndex, + arguments: finalArgs, + item_id: entry.itemId, + call_id: entry.id, + name: entry.name, + })); + events.push(seq(state, { + type: "response.output_item.done", + output_index: entry.outputIndex, + item: { + type: "tool_search_call", + id: entry.itemId, + call_id: entry.id, + arguments: argsObj, + execution: "client", + status: "completed", + }, + })); + } else { + events.push(seq(state, { + type: "response.function_call_arguments.done", + output_index: entry.outputIndex, + arguments: finalArgs, + item_id: entry.itemId, + call_id: entry.id, + name: entry.name, + })); + events.push(seq(state, { + type: "response.output_item.done", + output_index: entry.outputIndex, + item: ns + ? { + type: "function_call", + id: entry.itemId, + call_id: entry.id, + name: ns.name, + namespace: ns.namespace, + arguments: finalArgs, + status: "completed", + } + : { + type: "function_call", + id: entry.itemId, + call_id: entry.id, + name: entry.name, + arguments: finalArgs, + status: "completed", + }, + })); + } + } + return events; +} + +/** Reconstruct the final `output[]` array for `response.completed`. Order: reasoning โ†’ message โ†’ tool_calls. */ +function buildFinalOutput(state: ResponsesStreamState): ResponsesOutputItem[] { + const out: ResponsesOutputItem[] = []; + if (state.reasoningDone && state.reasoningText.length > 0) { + out.push({ + type: "reasoning", + id: state.reasoningItemId!, + summary: [{ type: "summary_text", text: state.reasoningText }], + status: "completed", + }); + } + if (state.messageItemId || state.toolCalls.size === 0) { + out.push({ + type: "message", + id: state.messageItemId ?? generateItemId(), + role: "assistant", + content: [{ type: "output_text", text: state.text }], + status: "completed", + }); + } + const sortedKeys = [...state.toolCalls.keys()].sort((a, b) => a - b); + for (const idx of sortedKeys) { + const entry = state.toolCalls.get(idx)!; + const customNames = state.meta?.customToolNames ?? new Set(); + const nsMap = state.meta?.namespaceMap ?? new Map(); + const hasToolSearch = state.meta?.hasToolSearch === true; + const isCustom = customNames.has(entry.name); + const isToolSearch = entry.name === "tool_search" && hasToolSearch; + const ns = nsMap.get(entry.name); + const finalArgs = entry.args.trim().length === 0 ? "{}" : entry.args; + + if (isCustom) { + out.push({ + type: "custom_tool_call", + id: entry.itemId, + call_id: entry.id, + name: entry.name, + input: extractCustomToolInput(finalArgs), + status: "completed", + }); + } else if (isToolSearch) { + let argsObj: Record = {}; + try { argsObj = JSON.parse(finalArgs); } catch { argsObj = {}; } + out.push({ + type: "tool_search_call", + id: entry.itemId, + call_id: entry.id, + arguments: argsObj, + execution: "client", + status: "completed", + }); + } else if (ns) { + out.push({ + type: "function_call", + id: entry.itemId, + call_id: entry.id, + name: ns.name, + namespace: ns.namespace, + arguments: finalArgs, + status: "completed", + }); + } else { + out.push({ + type: "function_call", + id: entry.itemId, + call_id: entry.id, + name: entry.name, + arguments: finalArgs, + status: "completed", + }); + } + } + return out; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Helpers +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +function allocIndex(state: ResponsesStreamState): number { + return state.nextOutputIndex++; +} + +/** Attach the next `sequence_number` and freeze the event `type`/payload. */ +function seq(state: ResponsesStreamState, evt: Omit): ResponsesStreamEvent { + const n = state.sequenceNumber++; + return { ...(evt as ResponsesStreamEvent), sequence_number: n }; +} + +/** Format a Responses SSE event as an SSE wire line. */ +export function responsesEventToSse(evt: ResponsesStreamEvent): string { + return `event: ${evt.type}\ndata: ${JSON.stringify(evt)}\n\n`; +} diff --git a/src/translator/openai-to-anthropic.ts b/src/translator/openai-to-anthropic.ts new file mode 100644 index 0000000000000000000000000000000000000000..5878b4bbeb6fe59aee468f900aed9eb202645e3b --- /dev/null +++ b/src/translator/openai-to-anthropic.ts @@ -0,0 +1,417 @@ +/** + * OpenAI โ†’ Anthropic request translator and Anthropic โ†’ OpenAI response translator. + * @see .omo/plans/zcode-proxy.md Task 11 + */ +import type { + OpenAIChatRequest, + OpenAIChatResponse, + OpenAIUsage, + OpenAIMessage, + OpenAIToolDefinition, + AnthropicMessagesRequest, + AnthropicMessagesResponse, + AnthropicMessage, + AnthropicContentBlock, + AnthropicToolDefinition, + AnthropicThinkingConfig, + AnthropicUsage, + AnthropicOutputConfig, +} from "./types.js"; +import { MODELS } from "../provider/models.js"; +import { + isGlm53Model, + normalizeGlm53Effort, + buildGlm53Reasoning, + fitGlm53Budget, +} from "../provider/reasoning.js"; + +/** Default max_tokens if the OpenAI request doesn't specify one. */ +const DEFAULT_MAX_TOKENS = 4096; + +/** Translate an OpenAI chat request into an Anthropic messages request. */ +export function translateRequestOpenAIToAnthropic(req: OpenAIChatRequest): AnthropicMessagesRequest { + const systemMessages = req.messages.filter((m) => m.role === "system"); + const nonSystemMessages = req.messages.filter((m) => m.role !== "system"); + + const system = systemMessages.length > 0 + ? systemMessages.map((m) => extractText(m)).join("\n\n") + : undefined; + + const anthropicMessages = translateMessagesWithToolCoalescing(nonSystemMessages); + + const result: AnthropicMessagesRequest = { + model: req.model, + messages: anthropicMessages, + max_tokens: req.max_tokens ?? resolveDefaultMaxTokens(req.model), + }; + + if (system) result.system = system; + if (req.temperature !== undefined) result.temperature = req.temperature; + if (req.top_p !== undefined) result.top_p = req.top_p; + if (req.stream !== undefined) result.stream = req.stream; + if (req.stop) result.stop_sequences = Array.isArray(req.stop) ? req.stop : [req.stop]; + if (isGlm53Model(req.model)) { + const { thinking, output_config } = translateGlm53Reasoning(req, result.max_tokens); + result.thinking = thinking; + if (output_config) result.output_config = output_config; + } else { + const thinking = translateThinking(req); + if (thinking) result.thinking = thinking; + } + if (req.tools?.length && req.tool_choice !== "none") { + result.tools = req.tools.map(translateToolOpenAIToAnthropic); + } + if (req.tool_choice !== undefined && req.tool_choice !== "none") { + const translated = translateToolChoice(req.tool_choice); + if (translated) result.tool_choice = translated; + } + + return result; +} + +function translateThinking(req: OpenAIChatRequest): AnthropicThinkingConfig | undefined { + const explicit = req.thinking; + if (explicit && typeof explicit === "object") { + if (explicit.type === "disabled") return { type: "disabled" }; + if (explicit.type === "enabled" || explicit.type === "adaptive") { + const budget = explicit.budget_tokens ?? explicit.budgetTokens; + return { + type: explicit.type, + ...(typeof budget === "number" && Number.isFinite(budget) && budget > 0 + ? { budget_tokens: Math.floor(budget) } + : {}), + ...(explicit.type === "adaptive" && typeof explicit.display === "boolean" + ? { display: explicit.display } + : {}), + }; + } + } + if (req.reasoning_effort === "none") return { type: "disabled" }; + if (isReasoningModel(req.model)) return { type: "enabled" }; + return undefined; +} + +function isReasoningModel(model: string): boolean { + return MODELS.some((m) => m.id === model && m.reasoning === true); +} + +/** + * Resolve the max_tokens fallback when the OpenAI client omits it. + * + * The generic `DEFAULT_MAX_TOKENS` (4096) is too small to coexist with the + * GLM-5.3 effort-based thinking budgets `translateGlm53Reasoning` attaches + * below (up to 32,000) โ€” `fitGlm53Budget` would clamp nearly the entire + * allowance into thinking, leaving almost nothing for the answer. ZCode's own + * clamp is written against the *model's* maxOutputTokens ceiling (128,000 for + * glm-5.3), not a generic request-level fallback, so for this family look up + * that ceiling in the catalog instead. Falls back to the generic default if + * the model id isn't in the catalog. Every other model's default is + * untouched โ€” this is deliberately scoped to GLM-5.3 only. + */ +function resolveDefaultMaxTokens(model: string): number { + if (!isGlm53Model(model)) return DEFAULT_MAX_TOKENS; + const catalogEntry = MODELS.find((m) => m.id === model); + return catalogEntry?.maxOutputTokens ?? DEFAULT_MAX_TOKENS; +} + +/** + * Build the `thinking` + `output_config` pair for a GLM-5.3 family request. + * + * `output_config.effort` is the only channel the Anthropic upstream honors + * for this family โ€” bare `reasoning_effort` is silently ignored โ€” so every + * GLM-5.3 request gets an explicit effort level, defaulting to ZCode's + * catalog default (`max`) rather than falling through to a near-zero + * upstream default. `reasoning_effort:"none"` maps to `"low"` here (via + * `normalizeGlm53Effort`) instead of `{type:"disabled"}`: disabling does not + * actually work for plain glm-5.3 (54 chars of thinking still came back in + * live testing), so routing it through the effort channel is the closer + * approximation across the whole family. + * + * An explicit `req.thinking:{type:"disabled"}` is still forwarded as-is + * (rather than overridden to an effort level) since it does work for + * glm-5.3-flash, and is the closest available signal for plain glm-5.3. + * An explicit `req.thinking` budget is respected over the effort-level + * default budget, but `output_config.effort` is still attached โ€” without it + * the upstream runs at its own near-zero default regardless of budget. + */ +function translateGlm53Reasoning( + req: OpenAIChatRequest, + maxTokens: number, +): { thinking: AnthropicThinkingConfig; output_config?: AnthropicOutputConfig } { + const explicit = req.thinking; + if (explicit && typeof explicit === "object" && explicit.type === "disabled") { + return { thinking: { type: "disabled" } }; + } + + const effort = normalizeGlm53Effort(req.reasoning_effort); + const base = buildGlm53Reasoning(effort); + + let budget: number = base.thinking.budget_tokens; + if (explicit && typeof explicit === "object" && (explicit.type === "enabled" || explicit.type === "adaptive")) { + const explicitBudget = explicit.budget_tokens ?? explicit.budgetTokens; + if (typeof explicitBudget === "number" && Number.isFinite(explicitBudget)) { + // Floor before the positivity test, not after: JSON permits a fractional + // budget, and a value like 0.5 passes `> 0` yet floors to 0 โ€” which then + // survives `fitGlm53Budget` untouched whenever `max_tokens` is not a + // finite number, handing the upstream `budget_tokens: 0`. + const floored = Math.floor(explicitBudget); + if (floored > 0) budget = floored; + } + } + + const fitted = fitGlm53Budget(budget, maxTokens); + return { + thinking: fitted !== undefined ? { type: "enabled", budget_tokens: fitted } : { type: "enabled" }, + output_config: base.output_config, + }; +} + +function translateToolChoice( + choice: "none" | "auto" | "required" | { type: "function"; function: { name: string | undefined } }, +): { type: "auto" | "any" | "tool"; name?: string } | undefined { + if (choice === "auto") return { type: "auto" }; + if (choice === "required") return { type: "any" }; + if (typeof choice === "object" && choice.type === "function") { + return { type: "tool", name: choice.function.name }; + } + return undefined; +} + +/** + * Translate non-system OpenAI messages into Anthropic messages, coalescing + * consecutive `role:"tool"` messages into a single Anthropic `user` message + * with multiple `tool_result` blocks (Anthropic's expected shape for parallel + * tool results). + */ +function translateMessagesWithToolCoalescing(messages: OpenAIMessage[]): AnthropicMessage[] { + const out: AnthropicMessage[] = []; + let i = 0; + while (i < messages.length) { + const m = messages[i]; + if (m.role === "tool" && m.tool_call_id) { + const results: AnthropicContentBlock[] = []; + while (i < messages.length) { + const tool = messages[i]; + const toolCallId = tool.tool_call_id; + if (tool.role !== "tool" || !toolCallId) break; + results.push({ + type: "tool_result", + tool_use_id: toolCallId, + content: toolResultContent(tool), + }); + i++; + } + out.push({ role: "user", content: results }); + continue; + } + out.push(translateMessageOpenAIToAnthropic(m)); + i++; + } + return out; +} + +function translateMessageOpenAIToAnthropic(msg: OpenAIMessage): AnthropicMessage { + if (msg.role === "assistant" && msg.tool_calls?.length) { + const blocks: AnthropicContentBlock[] = []; + const text = extractText(msg); + if (text.length > 0) blocks.push({ type: "text", text }); + for (const tc of msg.tool_calls) { + blocks.push({ + type: "tool_use", + id: tc.id, + name: tc.function.name, + input: parseToolArguments(tc.function.arguments), + }); + } + return { role: "assistant", content: blocks }; + } + return { + role: msg.role === "assistant" ? "assistant" : "user", + content: translateContentOpenAIToAnthropic(msg), + }; +} + +function parseToolArguments(raw: string | undefined): Record { + if (!raw) return {}; + try { + const parsed = JSON.parse(raw); + return parsed && typeof parsed === "object" && !Array.isArray(parsed) + ? parsed as Record + : {}; + } catch { + return {}; + } +} + +function toolResultContent(msg: OpenAIMessage): string | AnthropicContentBlock[] { + if (typeof msg.content === "string") return msg.content; + if (!Array.isArray(msg.content)) return ""; + if (msg.content.every((c) => c.type === "text")) { + const joined = msg.content.map((c) => c.text ?? "").join(""); + return joined; + } + return msg.content.map((c) => { + if (c.type === "text") return { type: "text" as const, text: c.text ?? "" }; + if (c.type === "image_url" && c.image_url?.url) { + return imageUrlToAnthropicBlock(c.image_url.url); + } + return { type: "text" as const, text: "" }; + }); +} + +function parseDataUrl(url: string): { mediaType: string; data: string } | undefined { + const m = /^data:([^;]+);base64,(.*)$/s.exec(url); + if (!m) return undefined; + return { mediaType: m[1], data: m[2] }; +} + +/** + * Map an OpenAI `image_url` string to an Anthropic image block. + * + * `data:` base64 URLs become inline base64 sources; http(s) URLs become + * url-source image blocks โ€” the same two shapes the ZCode client emits + * (`image-data` โ†’ base64 source, `image-url` โ†’ url source). Anything else + * (non-base64 data URLs, exotic schemes) degrades to a text block carrying + * the URL verbatim rather than emitting a block the upstream would reject. + * OpenAI's `detail` hint has no Anthropic equivalent and is dropped. + */ +function imageUrlToAnthropicBlock(url: string): AnthropicContentBlock { + const parsed = parseDataUrl(url); + if (parsed) { + return { + type: "image", + source: { type: "base64", media_type: parsed.mediaType, data: parsed.data }, + }; + } + if (/^https?:\/\//i.test(url)) { + return { type: "image", source: { type: "url", url } }; + } + return { type: "text", text: url }; +} + +/** + * Convert an Anthropic usage block into OpenAI's cache-inclusive usage + * semantics โ€” the counterpart of `openaiUsageToAnthropic`. + * + * Anthropic reports the fresh (uncached) input in `input_tokens` and keeps the + * three buckets mutually exclusive; OpenAI's `prompt_tokens` is *inclusive* of + * cache hits. So prompt = input + cache_read + cache_creation, with the cache + * read additionally surfaced through the standard `prompt_tokens_details`. + * The Anthropic-style cache fields are deliberately not mirrored onto the + * OpenAI usage object โ€” strict-schema clients reject unknown members. + * + * Totals round-trip exactly; buckets do not. OpenAI has no cache-creation + * member, so a converted-and-converted-back usage reclassifies those tokens as + * fresh input. `prompt_tokens` and `total_tokens` stay correct either way. + */ +export function anthropicUsageToOpenAI(usage: AnthropicUsage | undefined): OpenAIUsage { + const inputTokens = usage?.input_tokens ?? 0; + const outputTokens = usage?.output_tokens ?? 0; + const cacheRead = usage?.cache_read_input_tokens ?? 0; + const cacheCreation = usage?.cache_creation_input_tokens ?? 0; + const promptTokens = inputTokens + cacheRead + cacheCreation; + + return { + prompt_tokens: promptTokens, + completion_tokens: outputTokens, + total_tokens: promptTokens + outputTokens, + // Presence-preserving: an upstream explicitly reporting 0 cache reads stays + // distinguishable from one reporting no cache breakdown at all. + ...(usage?.cache_read_input_tokens != null + ? { prompt_tokens_details: { cached_tokens: cacheRead } } + : {}), + }; +} + +/** Translate an Anthropic messages response into an OpenAI chat completion response. */ +export function translateResponseAnthropicToOpenAI( + resp: AnthropicMessagesResponse, + model: string, +): OpenAIChatResponse { + const textBlocks = resp.content.filter((b) => b.type === "text"); + const toolUseBlocks = resp.content.filter((b) => b.type === "tool_use"); + const thinkingBlocks = resp.content.filter((b) => b.type === "thinking"); + + const content = textBlocks.map((b) => (b as any).text).join("") || null; + const reasoningContent = thinkingBlocks.map((b) => (b as any).thinking ?? "").join("") || undefined; + const toolCalls = toolUseBlocks.length > 0 + ? toolUseBlocks.map((b, i) => ({ + id: (b as any).id, + type: "function" as const, + function: { + name: (b as any).name, + arguments: JSON.stringify((b as any).input ?? {}), + }, + })) + : undefined; + + const finishReason = mapStopReasonToFinishReason(resp.stop_reason); + + return { + id: resp.id, + object: "chat.completion", + created: Math.floor(Date.now() / 1000), + model, + choices: [{ + index: 0, + message: { + role: "assistant", + content, + ...(reasoningContent ? { reasoning_content: reasoningContent } : {}), + ...(toolCalls ? { tool_calls: toolCalls } : {}), + }, + finish_reason: finishReason, + }], + usage: anthropicUsageToOpenAI(resp.usage), + }; +} + +function extractText(msg: OpenAIMessage): string { + if (typeof msg.content === "string") return msg.content; + if (Array.isArray(msg.content)) { + return msg.content + .filter((c) => c.type === "text") + .map((c) => c.text ?? "") + .join(""); + } + return ""; +} + +function translateContentOpenAIToAnthropic(msg: OpenAIMessage): string | AnthropicContentBlock[] { + if (typeof msg.content === "string") return msg.content; + if (msg.content === null) return ""; + if (Array.isArray(msg.content)) { + return msg.content.map((c) => { + if (c.type === "text") return { type: "text" as const, text: c.text ?? "" }; + if (c.type === "image_url" && c.image_url?.url) { + return imageUrlToAnthropicBlock(c.image_url.url); + } + return { type: "text" as const, text: "" }; + }); + } + return ""; +} + +function translateToolOpenAIToAnthropic(tool: OpenAIToolDefinition): AnthropicToolDefinition { + return { + name: tool.function.name, + ...(tool.function.description ? { description: tool.function.description } : {}), + ...(tool.function.parameters ? { input_schema: tool.function.parameters } : {}), + }; +} + +function mapStopReasonToFinishReason( + stopReason: string | null | undefined, +): "stop" | "length" | "tool_calls" | "content_filter" | null { + switch (stopReason) { + case "end_turn": + case "stop_sequence": + return "stop"; + case "max_tokens": + return "length"; + case "tool_use": + return "tool_calls"; + default: + return null; + } +} diff --git a/src/translator/responses-to-chat.ts b/src/translator/responses-to-chat.ts new file mode 100644 index 0000000000000000000000000000000000000000..a33081e6e93494cbda8ccf3dcbe538389c3e1b18 --- /dev/null +++ b/src/translator/responses-to-chat.ts @@ -0,0 +1,493 @@ +/** + * Responses API โ†’ Chat Completions request translation. + * + * Mirrors the de-facto ecosystem approach verified against three independent + * implementations (sub2api, cc-switch PR#3640, LiteLLM PR#29281) and adapted to + * GLM as the upstream. Key rules: + * + * - `instructions` becomes `messages[0]` (system). + * - `input[]` items become user/assistant/tool messages. Function-call / + * custom-tool-call / tool-search histories are rebuilt with the tool-reply + * invariant Chat Completions requires (assistant.tool_calls โ†’ tool reply, + * strictly paired, nothing in between). + * - `function` tools pass through to Chat `tools`. + * - `custom` tools (Codex's `exec` / `apply_patch`) downgrade to `function` + * with a `{input:string}` schema โ€” this is the make-or-break for Codex. + * - `namespace` tools flatten to `{ns}__{name}` and are restored on the way + * back (see `chat-to-responses.ts`). Ambiguous collisions are rejected. + * - `tool_search` downgrades to a same-named `function` proxy with + * `execution:"client"` semantics (Codex routes by item type, not just name). + * - `web_search` / `web_search_preview` are stripped here; the Responses + * handler intercepts them via GLM MCP (see `proxy/responses-handler.ts`). + * - `file_search` / `code_interpreter` / `computer_use_preview` / + * `image_generation` / `mcp` (hosted) are stripped silently. + * - When all convertible tools are gone, `tool_choice` AND + * `parallel_tool_calls` are dropped (cc-switch PR#3640: leaving them with + * empty `tools[]` causes upstream 400/503 on strict backends). + * + * `previous_response_id` is NOT handled here โ€” the Responses handler resolves + * it via `ResponseStore` and prepends the stored history to `input[]` before + * calling this translator. This module is pure and stateless. + */ +import type { + OpenAIChatRequest, + OpenAIMessage, + OpenAIToolDefinition, + OpenAIContentPart, +} from "./types.js"; +import type { + ResponsesRequest, + ResponsesInputItem, + ResponsesTool, + ResponsesContentPart, +} from "./responses-types.js"; +import { isHostedTool, isWebSearchTool } from "./responses-types.js"; + +/** Output of the translator: the Chat request + bookkeeping for the reverse path. */ +export interface ResponsesToChatResult { + chatRequest: OpenAIChatRequest; + /** Tool names that were `type:"custom"` on the request โ€” used to restore `custom_tool_call` items on the response. */ + customToolNames: Set; + /** Flattened namespace tool names โ†’ {namespace, name} โ€” used to restore `namespace` on the response. */ + namespaceMap: Map; + /** True when the request declared a `web_search` hosted tool (handler intercepts it). */ + hasWebSearch: boolean; + /** True when the request declared `type:"tool_search"` (response must emit `tool_search_call` items). */ + hasToolSearch: boolean; + /** Names of tools the model may legally emit (after conversion). Used for response routing. */ + convertibleToolNames: Set; +} + +/** Sentinel schema for `custom` tools (free-text input โ€” matches Codex's `exec`). */ +const CUSTOM_TOOL_SCHEMA: Record = { + type: "object", + properties: { input: { type: "string" } }, + required: ["input"], + additionalProperties: false, +}; + +/** Sentinel schema for the `tool_search` proxy function. */ +const TOOL_SEARCH_PROXY_SCHEMA: Record = { + type: "object", + properties: { query: { type: "string" }, limit: { type: "number" } }, + additionalProperties: false, +}; + +/** + * Translate a Responses request into a Chat Completions request. + * Throws on unrecoverable ambiguity (e.g. namespace flatten collisions). + */ +export function responsesToChatCompletions(req: ResponsesRequest): ResponsesToChatResult { + const messages: OpenAIMessage[] = []; + + // โ”€โ”€ instructions โ†’ system message โ”€โ”€ + if (typeof req.instructions === "string" && req.instructions.trim().length > 0) { + messages.push({ role: "system", content: req.instructions }); + } + + // โ”€โ”€ input[] โ†’ messages โ”€โ”€ + const inputItems = normaliseInput(req.input); + const built = buildMessagesFromItems(inputItems); + messages.push(...built); + + // โ”€โ”€ tools + bookkeeping โ”€โ”€ + const customToolNames = new Set(); + const namespaceMap = new Map(); + const convertibleToolNames = new Set(); + let hasWebSearch = false; + let hasToolSearch = false; + + const tools: OpenAIToolDefinition[] = []; + if (Array.isArray(req.tools)) { + for (const tool of req.tools) { + collectTools(tool, "", tools, customToolNames, namespaceMap, convertibleToolNames, ref => { + if (ref === "web_search") hasWebSearch = true; + if (ref === "tool_search") hasToolSearch = true; + }); + } + } + + // โ”€โ”€ assemble chat request โ”€โ”€ + const chatRequest: OpenAIChatRequest = { + model: req.model, + messages, + ...(req.max_output_tokens !== undefined ? { max_tokens: req.max_output_tokens } : {}), + ...(req.temperature !== undefined ? { temperature: req.temperature } : {}), + ...(req.top_p !== undefined ? { top_p: req.top_p } : {}), + ...(req.stream !== undefined ? { stream: req.stream } : {}), + ...(req.user !== undefined ? { user: req.user } : {}), + }; + if (tools.length > 0) chatRequest.tools = tools; + + // โ”€โ”€ tool_choice + parallel_tool_calls (cc-switch PR#3640 cleanup) โ”€โ”€ + if (tools.length > 0 && req.tool_choice !== undefined) { + const mapped = mapToolChoice(req.tool_choice, convertibleToolNames, hasToolSearch); + if (mapped !== undefined) chatRequest.tool_choice = mapped; + } + if (tools.length > 0 && req.parallel_tool_calls !== undefined) { + chatRequest.parallel_tool_calls = req.parallel_tool_calls; + } + + // โ”€โ”€ reasoning.effort โ†’ reasoning_effort โ”€โ”€ + if (req.reasoning?.effort) { + chatRequest.reasoning_effort = req.reasoning.effort; + } + + return { + chatRequest, + customToolNames, + namespaceMap, + hasWebSearch, + hasToolSearch, + convertibleToolNames, + }; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Input โ†’ messages +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** Coerce `input` (string or array) into a flat array of items. */ +function normaliseInput(input: ResponsesRequest["input"]): ResponsesInputItem[] { + if (typeof input === "string") { + return [{ type: "message", role: "user", content: input }]; + } + if (!Array.isArray(input)) return []; + return input.filter((x): x is ResponsesInputItem => x !== null && typeof x === "object"); +} + +/** + * Walk input items and build Chat messages. Preserves the tool-call invariant + * Chat Completions requires: an assistant `tool_calls` message must be followed + * immediately by one `tool` message per call_id, in order, nothing between. + * + * Strategy mirrors sub2api's `buildChatMessagesFromItems` + `normalizeChatMessages` + * (combined here in a single pass for simplicity): + * - `reasoning` text attaches to the next assistant tool-call message. + * - parallel `function_call` items coalesce into one assistant message. + * - unknown item types with no Chat equivalent are skipped (web_search_call, + * file_search_call, etc.) โ€” they have no Chat representation. + */ +function buildMessagesFromItems(items: ResponsesInputItem[]): OpenAIMessage[] { + const out: OpenAIMessage[] = []; + let pendingReasoning = ""; + + for (const item of items) { + const type = (item as { type?: string }).type ?? ""; + + switch (type) { + case "message": { + const role = (item as { role?: string }).role; + const chatRole = role === "assistant" ? "assistant" + : role === "developer" || role === "system" ? "system" + : "user"; + const content = contentPartsToChat((item as { content?: ResponsesContentPart[] | string }).content, chatRole); + out.push({ role: chatRole, content }); + if (chatRole !== "assistant") pendingReasoning = ""; + continue; + } + case "reasoning": { + const text = extractReasoningText(item); + if (text) pendingReasoning = text; + continue; + } + case "function_call": { + const fc = item as { call_id: string; name: string; arguments?: string }; + const args = (fc.arguments ?? "").trim().length === 0 ? "{}" : fc.arguments!; + const toolCall = { + id: fc.call_id, + type: "function" as const, + function: { name: fc.name, arguments: args }, + }; + mergeToolCallIntoAssistant(out, toolCall, pendingReasoning); + pendingReasoning = ""; + continue; + } + case "custom_tool_call": { + // Custom tool calls arrive as {call_id, name, input}; rewrite to a + // function_call-shaped assistant message so the upstream sees the same + // tool-call invariant. Input is wrapped in {input: "..."}. + const ct = item as { call_id: string; name: string; input?: string }; + const argObj = JSON.stringify({ input: ct.input ?? "" }); + const toolCall = { + id: ct.call_id, + type: "function" as const, + function: { name: ct.name, arguments: argObj }, + }; + mergeToolCallIntoAssistant(out, toolCall, pendingReasoning); + pendingReasoning = ""; + continue; + } + case "function_call_output": + case "custom_tool_call_output": { + const fco = item as { call_id: string; output?: string }; + out.push({ + role: "tool", + tool_call_id: fco.call_id, + content: fco.output ?? "", + }); + pendingReasoning = ""; + continue; + } + case "tool_search_call": { + const tsc = item as { call_id?: string; arguments?: Record | string }; + const argStr = typeof tsc.arguments === "string" ? tsc.arguments : JSON.stringify(tsc.arguments ?? {}); + const toolCall = { + id: tsc.call_id ?? "", + type: "function" as const, + function: { name: "tool_search", arguments: argStr }, + }; + mergeToolCallIntoAssistant(out, toolCall, pendingReasoning); + pendingReasoning = ""; + continue; + } + case "tool_search_output": { + const tso = item as { call_id?: string; output?: unknown }; + out.push({ + role: "tool", + tool_call_id: tso.call_id ?? "", + content: typeof tso.output === "string" ? tso.output : JSON.stringify(tso.output ?? {}), + }); + pendingReasoning = ""; + continue; + } + case "additional_tools": + // Already absorbed into `tools[]` by the tools-walker; not a message. + continue; + default: + // Unknown / hosted-only items (web_search_call, file_search_call, โ€ฆ) + // have no Chat representation โ€” skip them rather than emit a spurious + // message between an assistant tool_calls and its reply. + if (type !== "") pendingReasoning = ""; + continue; + } + } + + return out; +} + +/** + * Push (or merge into the previous assistant) an assistant tool-call message. + * Parallel tool calls arrive as consecutive items and must share one assistant + * message so the Chat schema accepts the following tool replies. + */ +function mergeToolCallIntoAssistant( + out: OpenAIMessage[], + toolCall: { id: string; type: "function"; function: { name: string; arguments: string } }, + reasoning: string, +): void { + const last = out[out.length - 1]; + if (last && last.role === "assistant" && Array.isArray(last.tool_calls)) { + last.tool_calls.push(toolCall); + if (!last.reasoning_content && reasoning) last.reasoning_content = reasoning; + } else { + out.push({ + role: "assistant", + content: null, + tool_calls: [toolCall], + ...(reasoning ? { reasoning_content: reasoning } : {}), + }); + } +} + +/** Extract reasoning text from a `reasoning` item (summary[] or content[]). */ +function extractReasoningText(item: ResponsesInputItem): string { + const r = item as { summary?: ResponsesContentPart[]; content?: ResponsesContentPart[] }; + const parts = Array.isArray(r.summary) && r.summary.length > 0 ? r.summary : r.content; + if (!Array.isArray(parts)) return ""; + return parts + .map((p) => (typeof p.text === "string" ? p.text : "")) + .filter((t) => t.length > 0) + .join("\n"); +} + +/** Convert Responses content parts to a Chat `content` value (string or parts[]). */ +function contentPartsToChat( + content: ResponsesContentPart[] | string | undefined, + role: string, +): string | OpenAIContentPart[] { + if (typeof content === "string") return content; + if (!Array.isArray(content)) return ""; + const textParts: string[] = []; + const chatParts: OpenAIContentPart[] = []; + let hasImage = false; + for (const part of content) { + if ((part.type === "input_text" || part.type === "output_text" || part.type === "text") && typeof part.text === "string") { + if (part.text.length === 0) continue; + textParts.push(part.text); + chatParts.push({ type: "text", text: part.text }); + } else if (part.type === "input_image" || part.type === "image_url") { + const url = typeof part.image_url === "string" ? part.image_url : part.image_url?.url; + if (!url) continue; + hasImage = true; + chatParts.push({ type: "image_url", image_url: { url } }); + } + } + // No image โ†’ collapse to plain string (cleaner for the upstream). + if (!hasImage) return textParts.join("\n"); + // Non-user roles can't carry image_url in many upstreams โ€” degrade to text. + if (role !== "user") return textParts.join("\n"); + return chatParts; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Tools collection +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +type RefSignal = (ref: "web_search" | "tool_search") => void; + +/** + * Walk a tool (possibly a namespace tree) and collect Chat-function tools. + * Rejects on ambiguous namespace flatten collisions (sub2api rule). + */ +function collectTools( + tool: ResponsesTool, + namespacePrefix: string, + out: OpenAIToolDefinition[], + customToolNames: Set, + namespaceMap: Map, + convertibleToolNames: Set, + signal: RefSignal, +): void { + const type = (tool as { type?: string }).type ?? ""; + + if (type === "function") { + const name = (tool as { name: string }).name; + const flatName = namespacePrefix ? `${namespacePrefix}__${name}` : name; + if (convertibleToolNames.has(flatName)) { + throw new ToolTranslationError(`duplicate tool name after flattening: "${flatName}"`); + } + const t = tool as { description?: string; parameters?: Record }; + out.push({ + type: "function", + function: { + name: flatName, + ...(t.description ? { description: t.description } : {}), + ...(t.parameters ? { parameters: t.parameters } : {}), + }, + }); + convertibleToolNames.add(flatName); + if (namespacePrefix) namespaceMap.set(flatName, { namespace: namespacePrefix, name }); + return; + } + + if (type === "custom") { + const name = (tool as { name: string }).name; + const flatName = namespacePrefix ? `${namespacePrefix}__${name}` : name; + if (convertibleToolNames.has(flatName)) { + throw new ToolTranslationError(`duplicate tool name after flattening: "${flatName}"`); + } + const t = tool as { description?: string }; + out.push({ + type: "function", + function: { + name: flatName, + ...(t.description ? { description: t.description } : {}), + parameters: CUSTOM_TOOL_SCHEMA, + }, + }); + convertibleToolNames.add(flatName); + customToolNames.add(flatName); + if (namespacePrefix) namespaceMap.set(flatName, { namespace: namespacePrefix, name }); + return; + } + + if (type === "namespace") { + const ns = (tool as { name: string }).name; + const children = (tool as { tools?: ResponsesTool[]; children?: ResponsesTool[] }).tools + ?? (tool as { children?: ResponsesTool[] }).children + ?? []; + const childPrefix = namespacePrefix ? `${namespacePrefix}__${ns}` : ns; + for (const child of children) { + collectTools(child, childPrefix, out, customToolNames, namespaceMap, convertibleToolNames, signal); + } + return; + } + + if (type === "tool_search") { + signal("tool_search"); + if (convertibleToolNames.has("tool_search")) return; // de-dup identical declarations + out.push({ + type: "function", + function: { + name: "tool_search", + description: "Search the available tool registry.", + parameters: TOOL_SEARCH_PROXY_SCHEMA, + }, + }); + convertibleToolNames.add("tool_search"); + return; + } + + if (isWebSearchTool(tool)) { + // Stripped here; handler intercepts via GLM MCP. + signal("web_search"); + return; + } + + if (isHostedTool(tool)) { + // file_search, code_interpreter, computer_use_preview, image_generation, mcp โ€” strip silently. + return; + } + + // Unknown tool type โ€” pass through as a function if it carries a name+parameters, else drop. + const maybeName = (tool as { name?: string }).name; + const maybeParams = (tool as { parameters?: Record }).parameters; + if (typeof maybeName === "string" && maybeParams && typeof maybeParams === "object") { + const flatName = namespacePrefix ? `${namespacePrefix}__${maybeName}` : maybeName; + if (!convertibleToolNames.has(flatName)) { + out.push({ type: "function", function: { name: flatName, parameters: maybeParams } }); + convertibleToolNames.add(flatName); + } + } +} + +/** + * Map a Responses `tool_choice` to a Chat `tool_choice`. + * Returns `undefined` when the choice points to a stripped/non-convertible tool + * (cc-switch rule: dropping tools must also drop their forced choice or the + * upstream 400s on "tool_choice references unknown tool"). + */ +function mapToolChoice( + raw: ResponsesRequest["tool_choice"], + convertible: Set, + hasToolSearch: boolean, +): OpenAIChatRequest["tool_choice"] { + if (raw === undefined || raw === null) return undefined; + if (typeof raw === "string") { + // "auto" | "none" | "required" pass through verbatim. + return raw as "auto" | "none" | "required"; + } + if (typeof raw !== "object") return undefined; + const obj = raw as { type?: string; name?: string; function?: { name?: string } }; + const type = obj.type ?? ""; + + // String-typed choices like {type:"web_search"} must drop entirely (the tool was stripped). + if (type === "web_search" || type === "web_search_preview") return undefined; + if (type === "file_search" || type === "code_interpreter" || type === "computer_use_preview" || type === "image_generation" || type === "mcp") { + return undefined; + } + + if (type === "tool_search") { + // Forced tool_search maps to a forced function choice on the proxy. + return hasToolSearch ? { type: "function", function: { name: "tool_search" } } : undefined; + } + + if (type === "custom" || type === "function") { + const name = obj.name ?? obj.function?.name; + if (typeof name !== "string" || name.length === 0) return undefined; + // Drop if the named tool didn't survive conversion. + if (!convertible.has(name)) return undefined; + return { type: "function", function: { name } }; + } + + return undefined; +} + +/** Thrown when a Responses request cannot be safely translated. */ +export class ToolTranslationError extends Error { + constructor(message: string) { + super(message); + this.name = "ToolTranslationError"; + } +} diff --git a/src/translator/responses-types.ts b/src/translator/responses-types.ts new file mode 100644 index 0000000000000000000000000000000000000000..b37d393970d30e0e5675c4181b6390e487222cf7 --- /dev/null +++ b/src/translator/responses-types.ts @@ -0,0 +1,188 @@ +/** + * Type definitions for the OpenAI Responses API (`/v1/responses`). + * + * The Responses API is OpenAI's stateful successor to Chat Completions, used by + * Codex CLI and the OpenAI Agents SDK. The proxy translates it bidirectionally + * against the GLM Chat Completions upstream so non-OpenAI clients (Codex) can + * drive GLM models directly. + * + * Reference: https://platform.openai.com/docs/api-reference/responses + * + * Scope (P1.0): request body, batch response, and streaming SSE events covering + * text / reasoning / function_call / web_search_call outputs. The streaming + * event set mirrors what Codex CLI consumes (verified against the Vercel AI SDK + * Responses provider in `_reverse/zcode.cjs` L1814 and sub2api's bridge). + */ + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Request +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** Reasoning configuration on a Responses request. */ +export interface ResponsesReasoning { + effort?: "minimal" | "low" | "medium" | "high"; + summary?: "auto" | "concise" | "detailed" | "none"; +} + +/** A single text content part inside a Responses input/output message. */ +export interface ResponsesContentPart { + type: "input_text" | "output_text" | "text" | "input_image" | "image_url" | "summary_text"; + text?: string; + image_url?: string | { url: string; detail?: string }; +} + +/** Tool definitions on a Responses request. */ +export type ResponsesTool = + | { type: "function"; name: string; description?: string; parameters?: Record; strict?: boolean } + | { type: "custom"; name: string; description?: string; format?: { type: "text" | "json" }; on_redirect?: string } + | { type: "namespace"; name: string; description?: string; tools?: ResponsesTool[]; children?: ResponsesTool[] } + | { type: "tool_search" } + | { type: "web_search" | "web_search_preview"; search_context_size?: "low" | "medium" | "high"; user_location?: unknown } + | { type: "file_search"; vector_store_ids?: string[] } + | { type: "code_interpreter"; container?: unknown } + | { type: "computer_use_preview"; display_height?: number; display_width?: number } + | { type: "image_generation"; background?: string; input_fidelity?: string; size?: string } + | { type: "mcp"; server_label?: string; server_url?: string; allowed_tools?: string[] } + | { type: string; name?: string; description?: string; [k: string]: unknown }; + +/** Input items โ€” Responses conversations are a flat list of typed items. */ +export type ResponsesInputItem = + | { type: "message"; role: "user" | "assistant" | "developer" | "system"; content: ResponsesContentPart[] | string; [k: string]: unknown } + | { type: "reasoning"; id?: string; content?: ResponsesContentPart[]; summary?: ResponsesContentPart[]; encrypted_content?: string; [k: string]: unknown } + | { type: "function_call"; call_id: string; name: string; arguments: string; id?: string; [k: string]: unknown } + | { type: "function_call_output"; call_id: string; output: string; id?: string; [k: string]: unknown } + | { type: "custom_tool_call"; call_id: string; name: string; input: string; id?: string; [k: string]: unknown } + | { type: "custom_tool_call_output"; call_id: string; output: string; id?: string; [k: string]: unknown } + | { type: "tool_search_call"; call_id?: string; arguments?: Record | string; id?: string; [k: string]: unknown } + | { type: "tool_search_output"; call_id?: string; output?: unknown; id?: string; [k: string]: unknown } + | { type: "additional_tools"; role?: string; tools?: ResponsesTool[]; [k: string]: unknown } + | { type: "web_search_call"; id?: string; status?: string; action?: unknown; [k: string]: unknown } + | { type: "file_search_call" | "code_interpreter_call" | "computer_call" | "image_generation_call"; id?: string; status?: string; [k: string]: unknown } + | { type: string; [k: string]: unknown }; + +/** POST /v1/responses request body. */ +export interface ResponsesRequest { + model: string; + input: ResponsesInputItem[] | string; + instructions?: string; + max_output_tokens?: number; + temperature?: number; + top_p?: number; + stream?: boolean; + tools?: ResponsesTool[]; + tool_choice?: "auto" | "none" | "required" | { type: string; name?: string; function?: { name?: string } } | Record; + parallel_tool_calls?: boolean; + reasoning?: ResponsesReasoning; + previous_response_id?: string; + store?: boolean; + metadata?: Record; + user?: string; + service_tier?: string; + prompt_cache_key?: string; + include?: string[]; + [k: string]: unknown; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Batch response +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +export interface ResponsesUsage { + input_tokens: number; + output_tokens: number; + total_tokens: number; + input_tokens_details?: { cached_tokens?: number }; + output_tokens_details?: { reasoning_tokens?: number }; +} + +export interface ResponsesIncompleteDetails { + reason?: string; +} + +/** An output item in a completed Responses payload. */ +export type ResponsesOutputItem = + | { type: "message"; id?: string; role: "assistant"; content: ResponsesContentPart[]; status?: string; [k: string]: unknown } + | { type: "reasoning"; id?: string; summary?: ResponsesContentPart[]; content?: ResponsesContentPart[]; status?: string; [k: string]: unknown } + | { type: "function_call"; id?: string; call_id: string; name: string; arguments: string; status?: string; namespace?: string; [k: string]: unknown } + | { type: "custom_tool_call"; id?: string; call_id: string; name: string; input: string; status?: string; [k: string]: unknown } + | { type: "tool_search_call"; id?: string; call_id?: string; arguments?: Record | string; execution?: "client" | "server"; status?: string; [k: string]: unknown } + | { type: "web_search_call"; id?: string; call_id?: string; status?: string; action?: unknown; [k: string]: unknown } + | { type: string; id?: string; status?: string; [k: string]: unknown }; + +export interface ResponsesResponse { + id: string; + object: "response"; + created_at?: number; + model: string; + status: "completed" | "incomplete" | "failed" | "in_progress" | "cancelled"; + output: ResponsesOutputItem[]; + usage?: ResponsesUsage; + incomplete_details?: ResponsesIncompleteDetails; + instructions?: string; + previous_response_id?: string; + metadata?: Record; + [k: string]: unknown; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Streaming SSE events +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** Discriminated union of all Responses SSE event shapes the proxy emits. */ +export type ResponsesStreamEvent = + | { type: "response.created"; response: ResponsesResponse; sequence_number?: number; [k: string]: unknown } + | { type: "response.in_progress"; response: ResponsesResponse; sequence_number?: number; [k: string]: unknown } + | { type: "response.output_item.added"; output_index: number; item: ResponsesOutputItem; sequence_number?: number; [k: string]: unknown } + | { type: "response.output_item.done"; output_index: number; item: ResponsesOutputItem; sequence_number?: number; [k: string]: unknown } + | { type: "response.content_part.added"; output_index: number; content_index: number; item_id?: string; part: ResponsesContentPart; sequence_number?: number; [k: string]: unknown } + | { type: "response.content_part.done"; output_index: number; content_index: number; item_id?: string; part: ResponsesContentPart; sequence_number?: number; [k: string]: unknown } + | { type: "response.output_text.delta"; output_index: number; content_index: number; delta: string; item_id?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.output_text.done"; output_index: number; content_index: number; text: string; item_id?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.reasoning_summary_part.added"; output_index: number; summary_index: number; item_id?: string; part: ResponsesContentPart; sequence_number?: number; [k: string]: unknown } + | { type: "response.reasoning_summary_text.delta"; output_index: number; summary_index: number; delta: string; item_id?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.reasoning_summary_text.done"; output_index: number; summary_index: number; text: string; item_id?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.reasoning_summary_part.done"; output_index: number; summary_index: number; item_id?: string; part: ResponsesContentPart; sequence_number?: number; [k: string]: unknown } + | { type: "response.function_call_arguments.delta"; output_index: number; delta: string; item_id?: string; call_id?: string; name?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.function_call_arguments.done"; output_index: number; arguments: string; item_id?: string; call_id?: string; name?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.custom_tool_call_input.delta"; output_index: number; delta: string; item_id?: string; call_id?: string; name?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.custom_tool_call_input.done"; output_index: number; input: string; item_id?: string; call_id?: string; name?: string; sequence_number?: number; [k: string]: unknown } + | { type: "response.completed"; response: ResponsesResponse; sequence_number?: number; [k: string]: unknown } + | { type: "response.incomplete"; response: ResponsesResponse; sequence_number?: number; [k: string]: unknown } + | { type: "response.failed"; response: ResponsesResponse; sequence_number?: number; error?: unknown; [k: string]: unknown } + | { type: "error"; code?: string; message?: string; sequence_number?: number; [k: string]: unknown }; + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Helpers +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** Generate a Responses-style id: `resp_<22 url-safe chars>`. */ +export function generateResponsesId(prefix = "resp_"): string { + const bytes = new Uint8Array(16); + crypto.getRandomValues(bytes); + const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""); + return `${prefix}${hex}`; +} + +/** Generate a per-output-item id: `item_<22 hex>`. Used by the response translator. */ +export function generateItemId(): string { + return generateResponsesId("item_"); +} + +/** Generate a call_id: `call_<22 hex>`. Used for tool calls. */ +export function generateCallId(): string { + return generateResponsesId("call_"); +} + +/** Type guard: a Responses tool is "hosted" (runs on the server side) โ€” we strip these. */ +export function isHostedTool(t: ResponsesTool): boolean { + return t.type === "file_search" + || t.type === "code_interpreter" + || t.type === "computer_use_preview" + || t.type === "image_generation" + || t.type === "mcp"; +} + +/** Type guard: a web-search hosted tool โ€” we route this to GLM MCP (intercepted). */ +export function isWebSearchTool(t: ResponsesTool): boolean { + return t.type === "web_search" || t.type === "web_search_preview"; +} diff --git a/src/translator/sse-translator.ts b/src/translator/sse-translator.ts new file mode 100644 index 0000000000000000000000000000000000000000..87e05ad6076a84b3b0fe153f1cca2ee0af71a987 --- /dev/null +++ b/src/translator/sse-translator.ts @@ -0,0 +1,618 @@ +/** + * SSE event translator โ€” converts streaming events between OpenAI and Anthropic formats. + * @see .omo/plans/zcode-proxy.md Task 12 + * @see https://docs.anthropic.com/en/api/messages-streaming + */ +import type { AnthropicStreamEvent, AnthropicUsage, OpenAIStreamChunk, OpenAIStreamToolCall, OpenAIUsage } from "./types.js"; +import { openaiUsageToAnthropic } from "./anthropic-to-openai.js"; +import { anthropicUsageToOpenAI } from "./openai-to-anthropic.js"; + +/** Parse a raw SSE chunk string into event type + JSON data. */ +export interface ParsedSSE { + event: string; + data: unknown; +} + +/** + * SSE frame boundary splitter: a blank line in any of the three line-ending + * styles. Mirrors the 3.11.2 bundle's `Kxo` frame regex โ€” a CRLF-only + * upstream (`\r\n\r\n`) never produces a `\n\n` boundary and would buffer + * forever under a plain `indexOf("\n\n")` / `split("\n\n")`. + */ +export const SSE_FRAME_SPLIT = /\r\n\r\n|\n\n|\r\r/; + +export function parseSSEChunk(raw: string): ParsedSSE[] { + const results: ParsedSSE[] = []; + const blocks = raw.split(SSE_FRAME_SPLIT); + + for (const block of blocks) { + const lines = block.trim().split("\n").filter(Boolean); + if (lines.length === 0) continue; + + let eventType = ""; + let dataStr = ""; + + for (const line of lines) { + if (line.startsWith("event: ")) { + eventType = line.slice(7).trim(); + } else if (line.startsWith("data:")) { + // SSE spec: the colon may be followed by at most ONE space. Strip at + // most one leading space so both `data: x` and `data:x` parse while + // existing `data: x` payloads stay byte-identical. + let data = line.slice(5); + if (data.startsWith(" ")) data = data.slice(1); + dataStr = data; + } + } + + if (dataStr) { + try { + results.push({ event: eventType, data: JSON.parse(dataStr) }); + } catch { + // Skip malformed JSON + } + } + } + + return results; +} + +export interface TranslationState { + messageId: string; + model: string; + roleSent: boolean; + /** Running Anthropic usage snapshot; the upstream reports it incrementally. */ + usage: AnthropicUsage; + toolCallIndex: number; + blockIndexToToolCallIndex: Map; + finishReasonSent: boolean; +} + +export function initState(model: string): TranslationState { + return { + messageId: "", + model, + roleSent: false, + usage: { input_tokens: 0, output_tokens: 0 }, + toolCallIndex: 0, + blockIndexToToolCallIndex: new Map(), + finishReasonSent: false, + }; +} + +/** + * Fold an incremental usage report into the running snapshot, field by field. + * Overwrite (not accumulate) semantics: the upstream re-reports absolute + * totals, so a later 0 must win over an earlier non-zero, while a field the + * event omits keeps its previous value. + */ +function mergeAnthropicUsage(target: AnthropicUsage, patch: Partial | undefined): void { + if (!patch) return; + if (patch.input_tokens != null) target.input_tokens = patch.input_tokens; + if (patch.output_tokens != null) target.output_tokens = patch.output_tokens; + if (patch.cache_read_input_tokens != null) target.cache_read_input_tokens = patch.cache_read_input_tokens; + if (patch.cache_creation_input_tokens != null) target.cache_creation_input_tokens = patch.cache_creation_input_tokens; +} + +function makeChunk( + state: TranslationState, + delta: Record, + finishReason: string | null = null, + usage?: OpenAIUsage, +): string { + const chunk: OpenAIStreamChunk = { + id: state.messageId || "chatcmpl-stream", + object: "chat.completion.chunk", + created: Math.floor(Date.now() / 1000), + model: state.model, + choices: [{ + index: 0, + delta: delta as any, + finish_reason: finishReason as any, + }], + }; + if (usage) chunk.usage = usage; + return `data: ${JSON.stringify(chunk)}\n\n`; +} + +/** + * Transform an Anthropic SSE stream into OpenAI SSE format. + * Input: ReadableStream (Anthropic SSE bytes) + * Output: ReadableStream (OpenAI SSE bytes) + */ +export function anthropicSseToOpenaiSse( + upstream: ReadableStream, + model: string = "glm-4.6", +): ReadableStream { + const state = initState(model); + const decoder = new TextDecoder(); + const encoder = new TextEncoder(); + let buffer = ""; + + return new ReadableStream({ + async start(controller) { + const reader = upstream.getReader(); + let errored = false; + + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + buffer += decoder.decode(value, { stream: true }); + const blocks = buffer.split(SSE_FRAME_SPLIT); + buffer = blocks.pop() ?? ""; + + for (const block of blocks) { + const parsed = parseSSEChunk(block); + for (const p of parsed) { + const output = translateEvent(state, p); + if (output) { + controller.enqueue(encoder.encode(output)); + } + } + } + } + + // Flush remaining buffer + if (buffer.trim()) { + const parsed = parseSSEChunk(buffer); + for (const p of parsed) { + const output = translateEvent(state, p); + if (output) controller.enqueue(encoder.encode(output)); + } + } + + // Emit [DONE] + controller.enqueue(encoder.encode("data: [DONE]\n\n")); + } catch (err) { + errored = true; + // error()/close() ไบ’ๆ–ฅ:errored ๆตไธŠๅ† close() ไผšๆŠ› TypeError,่ฟ›่€Œ่งฆๅ‘ Bun ๅผ•ๆ“Ž็ฉบๆŒ‡้’ˆๅดฉๆบƒใ€‚ + try { controller.error(err); } catch {} + } finally { + if (!errored) { + try { controller.close(); } catch {} + } + reader.releaseLock(); + } + }, + }); +} + +export function translateEvent(state: TranslationState, sse: ParsedSSE): string | null { + const data = sse.data as AnthropicStreamEvent; + + switch (data.type) { + case "message_start": { + const msg = (data as any).message; + state.messageId = msg?.id ?? "msg_stream"; + state.model = msg?.model ?? state.model; + mergeAnthropicUsage(state.usage, msg?.usage); + if (!state.roleSent) { + state.roleSent = true; + return makeChunk(state, { role: "assistant" }); + } + return null; + } + + case "content_block_start": { + if (data.type !== "content_block_start") return null; + const block = data.content_block; + const blockIdx = data.index; + if (block.type === "tool_use") { + const myIndex = state.toolCallIndex++; + state.blockIndexToToolCallIndex.set(blockIdx, myIndex); + return makeChunk(state, { + tool_calls: [{ + index: myIndex, + id: block.id, + type: "function", + function: { name: block.name, arguments: "" }, + }], + }); + } + return null; + } + + case "content_block_delta": { + if (data.type !== "content_block_delta") return null; + const delta = data.delta; + const blockIdx = data.index; + if (delta.type === "text_delta") { + return makeChunk(state, { content: delta.text }); + } + if (delta.type === "thinking_delta") { + return makeChunk(state, { reasoning_content: delta.thinking }); + } + if (delta.type === "signature_delta") { + return null; + } + if (delta.type === "input_json_delta") { + const myIndex = state.blockIndexToToolCallIndex.get(blockIdx); + if (myIndex === undefined) return null; + return makeChunk(state, { + tool_calls: [{ + index: myIndex, + function: { arguments: delta.partial_json ?? "" }, + }], + }); + } + return null; + } + + case "message_delta": { + // Fold usage in *before* the stop_reason branch: the upstream carries + // both in the same event, and this is the only place the real input and + // cache counts ever arrive. Usage that lands only *after* the finish + // chunk was emitted updates the snapshot but is not re-announced โ€” the + // alternative is a trailing `choices: []` usage chunk, which some clients + // index into blindly. No observed upstream orders the events that way. + mergeAnthropicUsage(state.usage, data.usage); + if (data.delta?.stop_reason && !state.finishReasonSent) { + const finishReason = mapStopReason(data.delta.stop_reason); + state.finishReasonSent = true; + return makeChunk(state, {}, finishReason, anthropicUsageToOpenAI(state.usage)); + } + return null; + } + + case "message_stop": { + if (state.finishReasonSent) return null; + state.finishReasonSent = true; + return makeChunk(state, {}, "stop", anthropicUsageToOpenAI(state.usage)); + } + + case "ping": + case "content_block_stop": + return null; + + default: + return null; + } +} + +function mapStopReason(stopReason: string): string { + switch (stopReason) { + case "end_turn": + case "stop_sequence": + return "stop"; + case "max_tokens": + return "length"; + case "tool_use": + return "tool_calls"; + default: + return "stop"; + } +} + +/** + * Transform an OpenAI SSE stream into Anthropic SSE format. + * Input: ReadableStream (OpenAI SSE bytes) + * Output: ReadableStream (Anthropic SSE bytes) + */ +export function openaiSseToAnthropicSse( + upstream: ReadableStream, + model: string = "glm-4.6", +): ReadableStream { + const encoder = new TextEncoder(); + const decoder = new TextDecoder(); + let buffer = ""; + let messageStarted = false; + let blockIndex = 0; + let activeBlock: { type: "text" | "thinking"; index: number } | null = null; + /** OpenAI tool_call index โ†’ Anthropic block state. */ + const toolBlocks = new Map(); + /** Anthropic block indices of started tool_use blocks, in open order. */ + const openToolBlockIndices: number[] = []; + let outputTokens = 0; + /** Latest upstream usage โ€” OpenAI only emits it in the final chunk, so we + * accumulate and emit it once, deferred to end-of-stream. */ + let latestUsage: OpenAIUsage | undefined; + /** Stop reason captured from the finish_reason chunk; held until we can pair + * it with the complete usage before emitting message_delta. */ + let pendingStopReason: string | null = null; + let contentClosed = false; + let messageDeltaSent = false; + let messageStopped = false; + const messageId = `msg_${Date.now()}`; + + return new ReadableStream({ + async start(controller) { + const reader = upstream.getReader(); + let errored = false; + + const enqueueAnthropicEvent = (eventType: string, data: unknown) => { + controller.enqueue(encoder.encode(formatAnthropicSSE(eventType, data))); + }; + + const closeActiveBlock = () => { + if (!activeBlock) return; + enqueueAnthropicEvent("content_block_stop", { + type: "content_block_stop", + index: activeBlock.index, + }); + activeBlock = null; + }; + + const closeToolBlocks = () => { + for (const idx of openToolBlockIndices) { + enqueueAnthropicEvent("content_block_stop", { + type: "content_block_stop", + index: idx, + }); + } + openToolBlockIndices.length = 0; + }; + + const ensureActiveBlock = (type: "text" | "thinking"): number => { + if (activeBlock?.type === type) return activeBlock.index; + closeActiveBlock(); + const index = blockIndex++; + activeBlock = { type, index }; + enqueueAnthropicEvent("content_block_start", { + type: "content_block_start", + index, + content_block: type === "text" + ? { type: "text", text: "" } + : { type: "thinking", thinking: "", signature: "" }, + }); + return index; + }; + + /** + * Route OpenAI streaming tool_call deltas into Anthropic tool_use blocks. + * OpenAI identifies each parallel call by `index`; we lazily allocate an + * Anthropic block per index, emit `content_block_start` once id+name + * arrive, then stream `input_json_delta` for each arguments fragment. + * Arguments that arrive before id/name (non-standard ordering from some + * compatible upstreams) are buffered into `pendingArgs` and flushed on + * start, so the tool input is never silently truncated. + */ + const handleToolCalls = (toolCalls: OpenAIStreamToolCall[]) => { + // Tool calls never share a block with text/thinking โ€” close any open prose block first. + closeActiveBlock(); + for (const tc of toolCalls) { + const idx = tc.index ?? 0; + let state = toolBlocks.get(idx); + if (!state) { + state = { index: blockIndex++, id: "", name: "", started: false, pendingArgs: "" }; + toolBlocks.set(idx, state); + } + if (tc.id) state.id = tc.id; + if (tc.function?.name) state.name = tc.function.name; + + if (!state.started && state.id && state.name) { + state.started = true; + enqueueAnthropicEvent("content_block_start", { + type: "content_block_start", + index: state.index, + content_block: { type: "tool_use", id: state.id, name: state.name, input: {} }, + }); + openToolBlockIndices.push(state.index); + if (state.pendingArgs.length > 0) { + enqueueAnthropicEvent("content_block_delta", { + type: "content_block_delta", + index: state.index, + delta: { type: "input_json_delta", partial_json: state.pendingArgs }, + }); + state.pendingArgs = ""; + } + } + + const argsDelta = tc.function?.arguments; + if (argsDelta) { + if (state.started) { + enqueueAnthropicEvent("content_block_delta", { + type: "content_block_delta", + index: state.index, + delta: { type: "input_json_delta", partial_json: argsDelta }, + }); + } else { + // id/name not yet seen โ€” buffer until the block can open. + state.pendingArgs += argsDelta; + } + } + } + }; + + /** + * Force-open any tool blocks that accumulated arguments (or a partial + * id/name) but never crossed the id+name threshold before the stream + * ended. Uses fallback id/name so the data is surfaced rather than + * silently dropped. Mirrors cc-switch's "late tool starts" flush. + */ + const startPendingToolBlocks = () => { + const lateStarts: Array<{ index: number; id: string; name: string; args: string }> = []; + for (const [openaiIdx, state] of toolBlocks) { + if (state.started) continue; + if (!state.pendingArgs && !state.id && !state.name) continue; + state.started = true; + lateStarts.push({ + index: state.index, + id: state.id || `tool_call_${openaiIdx}`, + name: state.name || "unknown_tool", + args: state.pendingArgs, + }); + state.pendingArgs = ""; + openToolBlockIndices.push(state.index); + } + lateStarts.sort((a, b) => a.index - b.index); + for (const ls of lateStarts) { + enqueueAnthropicEvent("content_block_start", { + type: "content_block_start", + index: ls.index, + content_block: { type: "tool_use", id: ls.id, name: ls.name, input: {} }, + }); + if (ls.args.length > 0) { + enqueueAnthropicEvent("content_block_delta", { + type: "content_block_delta", + index: ls.index, + delta: { type: "input_json_delta", partial_json: ls.args }, + }); + } + } + }; + + /** + * Close every open content block (text/thinking/tool_use). Idempotent via + * the `contentClosed` flag so it is safe to call at both finish_reason + * and end-of-stream. Split from `finalizeStream` so the finish_reason + * chunk can close blocks *without* emitting message_delta โ€” the usage + * chunk arrives afterwards and must be folded in first. + */ + const closeContent = () => { + if (contentClosed) return; + contentClosed = true; + closeActiveBlock(); + startPendingToolBlocks(); + closeToolBlocks(); + }; + + /** + * Emit the terminal message_delta + message_stop. The message_delta + * carries the full Anthropic usage (input + output + cache) derived from + * the latest upstream usage snapshot. This is what lets Anthropic clients + * see a non-zero input_tokens despite OpenAI only reporting usage in the + * stream's final chunk โ€” the delta is deferred until that chunk lands. + */ + const finalizeStream = () => { + closeContent(); + if (!messageDeltaSent) { + messageDeltaSent = true; + const usage = openaiUsageToAnthropic(latestUsage); + if (!latestUsage) usage.output_tokens = outputTokens; + enqueueAnthropicEvent("message_delta", { + type: "message_delta", + delta: { + stop_reason: pendingStopReason ?? "end_turn", + stop_sequence: null, + }, + usage, + }); + } + if (!messageStopped) { + messageStopped = true; + enqueueAnthropicEvent("message_stop", { type: "message_stop" }); + } + }; + + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + buffer += decoder.decode(value, { stream: true }); + const lines = buffer.split("\n"); + buffer = lines.pop() ?? ""; + + for (const line of lines) { + if (!line.startsWith("data: ")) continue; + const dataStr = line.slice(6).trim(); + + if (dataStr === "[DONE]") { + finalizeStream(); + continue; + } + + try { + const chunk = JSON.parse(dataStr) as OpenAIStreamChunk; + const choice = chunk.choices?.[0]; + + // Accumulate usage from every chunk that carries one. OpenAI's + // include_usage stream emits it only on the final (often + // choices-less) chunk, but compatible upstreams may spread it + // across chunks โ€” keep the freshest snapshot. + if (chunk.usage) { + latestUsage = chunk.usage; + outputTokens = chunk.usage.completion_tokens ?? outputTokens; + } + + if (!messageStarted) { + messageStarted = true; + // message_start must lead the stream, but the upstream usage + // has not arrived yet at this point, so input_tokens starts at + // 0 here and is delivered for real via the deferred + // message_delta once usage lands. (Anthropic's own streaming + // also reports input_tokens up-front; we cannot, given the + // upstream timing.) + const startUsage = openaiUsageToAnthropic(chunk.usage); + enqueueAnthropicEvent("message_start", { + type: "message_start", + message: { + id: chunk.id ?? messageId, + type: "message", + role: "assistant", + content: [], + model: chunk.model || model, + stop_reason: null, + stop_sequence: null, + usage: startUsage, + }, + }); + } + + if (choice?.delta?.content) { + const index = ensureActiveBlock("text"); + enqueueAnthropicEvent("content_block_delta", { + type: "content_block_delta", + index, + delta: { type: "text_delta", text: choice.delta.content }, + }); + } + + if (choice?.delta?.reasoning_content) { + const index = ensureActiveBlock("thinking"); + enqueueAnthropicEvent("content_block_delta", { + type: "content_block_delta", + index, + delta: { type: "thinking_delta", thinking: choice.delta.reasoning_content }, + }); + } + + if (choice?.delta?.tool_calls?.length) { + handleToolCalls(choice.delta.tool_calls); + } + + if (choice?.finish_reason) { + // Close blocks now, but hold message_delta until the stream + // actually ends so the usage chunk (which follows finish_reason + // in include_usage streams) is folded into the final usage. + pendingStopReason = mapFinishReason(choice.finish_reason); + closeContent(); + } + } catch { + // Skip malformed + } + } + } + + // Stream ended โ€” emit the deferred message_delta (with full usage) and + // message_stop. Covers both explicit [DONE] already handled above and + // streams that terminate without one. + finalizeStream(); + } catch (err) { + errored = true; + // error()/close() ไบ’ๆ–ฅ:errored ๆตไธŠๅ† close() ไผšๆŠ› TypeError,่ฟ›่€Œ่งฆๅ‘ Bun ๅผ•ๆ“Ž็ฉบๆŒ‡้’ˆๅดฉๆบƒใ€‚ + try { controller.error(err); } catch {} + } finally { + if (!errored) { + try { controller.close(); } catch {} + } + reader.releaseLock(); + } + }, + }); +} + +function formatAnthropicSSE(eventType: string, data: unknown): string { + return `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`; +} + +function mapFinishReason(finishReason: string): string { + switch (finishReason) { + case "stop": return "end_turn"; + case "length": return "max_tokens"; + case "tool_calls": return "tool_use"; + default: return "end_turn"; + } +} diff --git a/src/translator/types.ts b/src/translator/types.ts new file mode 100644 index 0000000000000000000000000000000000000000..86fed84d37704799b2ebc930c9cd4d2fe7c408e5 --- /dev/null +++ b/src/translator/types.ts @@ -0,0 +1,275 @@ +/** + * Type definitions for OpenAI and Anthropic API formats. + * @see .omo/plans/zcode-proxy.md Task 5 + * @see https://platform.openai.com/docs/api-reference/chat + * @see https://docs.anthropic.com/en/api/messages + */ + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Shared types +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** API format identifier. */ +export type Format = "openai" | "anthropic"; + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// OpenAI types +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** OpenAI message role. */ +type OpenAIRole = "system" | "user" | "assistant" | "tool"; + +/** OpenAI message in a chat completion request. */ +export interface OpenAIMessage { + role: OpenAIRole; + content: string | null | OpenAIContentPart[]; + name?: string; + tool_call_id?: string; + tool_calls?: OpenAIToolCall[]; + /** Reasoning / chain-of-thought content (GLM, DeepSeek-R1, o1-style models). */ + reasoning_content?: string; +} + +/** Multi-modal content part (OpenAI format). */ +export interface OpenAIContentPart { + type: "text" | "image_url"; + text?: string; + image_url?: { url: string; detail?: string }; +} + +/** Tool call in an assistant message. */ +export interface OpenAIToolCall { + id: string; + type: "function"; + function: { name: string; arguments: string }; +} + +/** Tool call delta in a streaming chunk (carries `index` to align parallel calls). */ +export interface OpenAIStreamToolCall { + index: number; + id?: string; + type?: "function"; + function?: { name?: string; arguments?: string }; +} + +/** + * OpenAI usage block. `prompt_tokens` is *inclusive* of cache hits on most + * compatible upstreams, so the Anthropic `input_tokens` (exclusive of cache) + * is derived by subtracting the cache buckets โ€” see `openaiUsageToAnthropic`. + */ +export interface OpenAIUsage { + prompt_tokens: number; + completion_tokens: number; + total_tokens: number; + /** Standard OpenAI cache breakdown. */ + prompt_tokens_details?: { cached_tokens?: number }; + /** Anthropic-style direct cache fields (some compatible upstreams emit these). */ + cache_read_input_tokens?: number; + cache_creation_input_tokens?: number; + /** Standard OpenAI reasoning-token breakdown (mirrors `prompt_tokens_details`). */ + output_tokens_details?: { reasoning_tokens?: number; audio_tokens?: number }; +} + +/** Tool definition in OpenAI format. */ +export interface OpenAIToolDefinition { + type: "function"; + function: { + name: string; + description?: string; + parameters?: Record; + }; +} + +/** POST /v1/chat/completions request body. */ +export interface OpenAIChatRequest { + model: string; + messages: OpenAIMessage[]; + temperature?: number; + top_p?: number; + n?: number; + stream?: boolean; + stop?: string | string[]; + max_tokens?: number; + presence_penalty?: number; + frequency_penalty?: number; + logit_bias?: Record; + user?: string; + tools?: OpenAIToolDefinition[]; + tool_choice?: "none" | "auto" | "required" | { type: "function"; function: { name: string | undefined } }; + parallel_tool_calls?: boolean; + response_format?: { type: "text" | "json_object" }; + seed?: number; + reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; + thinking?: AnthropicThinkingConfig & { budgetTokens?: number }; +} + +/** Non-streaming response. */ +export interface OpenAIChatResponse { + id: string; + object: "chat.completion"; + created: number; + model: string; + choices: OpenAIChoice[]; + usage?: OpenAIUsage; + status?: number; + statusText?: string; + headers?: Record; +} + +/** Single choice in a non-streaming chat completion response. */ +export interface OpenAIChoice { + index?: number; + message: OpenAIMessage; + finish_reason?: "stop" | "length" | "tool_calls" | "content_filter" | null; +} + +/** Streaming chunk (SSE `data:` payload). */ +export interface OpenAIStreamChunk { + id: string; + object: "chat.completion.chunk"; + created: number; + model: string; + choices: OpenAIStreamChoice[]; + /** Present on the final chunk when `stream_options.include_usage` is set. */ + usage?: OpenAIUsage; +} + +/** Choice in a streaming chunk. */ +export interface OpenAIStreamChoice { + index: number; + delta: { + role?: "assistant"; + content?: string; + reasoning_content?: string; + tool_calls?: OpenAIStreamToolCall[]; + }; + finish_reason?: "stop" | "length" | "tool_calls" | "content_filter" | null; +} + +/** /v1/models list entry. */ +interface OpenAIModel { + id: string; + object: "model"; + created?: number; + owned_by: string; +} + +/** /v1/models list response. */ +export interface OpenAIModelList { + object: "list"; + data: OpenAIModel[]; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Anthropic types +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** Anthropic image source: inline base64 payload or a remote URL. */ +export type AnthropicImageSource = + | { type: "base64"; media_type: string; data: string } + | { type: "url"; url: string }; + +/** Anthropic content block types. */ +export type AnthropicContentBlock = + | { type: "text"; text: string } + | { type: "image"; source: AnthropicImageSource } + | { type: "tool_use"; id: string; name: string; input: Record } + | { type: "tool_result"; tool_use_id: string; content: string | AnthropicContentBlock[]; is_error?: boolean } + | { type: "thinking"; thinking: string; signature?: string }; + +/** Anthropic message in a request. */ +export interface AnthropicMessage { + role: "user" | "assistant"; + content: string | AnthropicContentBlock[]; +} + +/** POST /v1/messages request body. */ +export interface AnthropicMessagesRequest { + model: string; + messages: AnthropicMessage[]; + system?: string | Array<{ type: "text"; text: string }>; + max_tokens: number; + temperature?: number; + top_p?: number; + top_k?: number; + stream?: boolean; + stop_sequences?: string[]; + metadata?: { user_id?: string }; + tools?: AnthropicToolDefinition[]; + tool_choice?: { type: "auto" | "any" | "tool"; name?: string }; + thinking?: AnthropicThinkingConfig; + /** GLM-5.3+ reasoning-effort channel; the Anthropic upstream ignores `reasoning_effort`. */ + output_config?: AnthropicOutputConfig; +} + +/** GLM-5.3+ reasoning-effort control (Anthropic upstream extension). */ +export interface AnthropicOutputConfig { + effort?: string; + task_budget?: { type: string; [k: string]: unknown }; +} + +/** Anthropic thinking/reasoning control. */ +export interface AnthropicThinkingConfig { + type: "enabled" | "disabled" | "adaptive"; + budget_tokens?: number; + display?: boolean; +} + +/** Tool definition in Anthropic format. */ +export interface AnthropicToolDefinition { + name: string; + description?: string; + input_schema?: Record; +} + +/** Non-streaming response. */ +export interface AnthropicMessagesResponse { + id: string; + type: "message"; + role: "assistant"; + content: AnthropicContentBlock[]; + model: string; + stop_reason: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use" | null; + stop_sequence: string | null; + usage: AnthropicUsage; +} + +/** Anthropic usage block (cache buckets are optional โ€” only present when non-zero). */ +export interface AnthropicUsage { + input_tokens: number; + output_tokens: number; + cache_read_input_tokens?: number; + cache_creation_input_tokens?: number; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Anthropic SSE event types +// @see https://docs.anthropic.com/en/api/messages-streaming +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +export type AnthropicStreamEvent = + | { type: "message_start"; message: AnthropicMessagesResponse } + | { type: "content_block_start"; index: number; content_block: AnthropicContentBlock } + | { + type: "content_block_delta"; + index: number; + delta: + | { type: "text_delta"; text: string } + | { type: "input_json_delta"; partial_json: string } + | { type: "thinking_delta"; thinking: string } + | { type: "signature_delta"; signature: string } + | { type: "stop_reason"; stop_reason: string }; + } + | { type: "content_block_stop"; index: number } + | { + type: "message_delta"; + delta?: { stop_reason?: string | null; stop_sequence?: string | null }; + /** + * The upstream reports the real token counts here rather than in + * `message_start` โ€” including the input and cache buckets. Extra vendor + * members (`server_tool_use`, `service_tier`) are left unmodelled. + */ + usage?: Partial; + } + | { type: "message_stop" } + | { type: "ping" }; diff --git a/src/tui/app.ts b/src/tui/app.ts new file mode 100644 index 0000000000000000000000000000000000000000..777d4e492627b657a6635702e7bb790f84e10cb2 --- /dev/null +++ b/src/tui/app.ts @@ -0,0 +1,665 @@ +/** + * PC terminal UI (zcode-proxy's default mode) โ€” an in-process control panel + * mirroring the Android app's three-card layout: Settings & Login / Proxy + * Server / Logs. + * + * The TUI owns the terminal (alternate screen + raw mode) and, like the + * Android entry, intercepts console.log/warn/error into a ring buffer so the + * per-request log rows land in the Logs card. Zero new dependencies: the + * renderer, input parser and width math are hand-rolled ANSI/VT (Bun- and + * Node-compatible, bundles into both release artifacts). + * + * index.ts dispatches here via dynamic import (this module imports helpers + * back from index.js), mirroring the claimCommand pattern. + */ +import { loadConfig } from "../config/loader.js"; +import { updateConfigYaml, ensureConfigFile } from "../config/edit.js"; +import { AuthManager } from "../auth/manager.js"; +import { startServer, type ProxyServer } from "../server/server.js"; +import { buildServerOptions } from "../server/server-options.js"; +import { loadCredential, saveCredential, clearCredential } from "../auth/store.js"; +import { ZaiOAuthClient, BigmodelOAuthClient, LOGIN_TIMEOUT_MS, parsePastedCallbackUrl, type OAuthFlowClient, type OAuthFlowStart, type OAuthFlowTokens } from "../auth/oauth.js"; +import { KeyResolver } from "../auth/resolver.js"; +import { openBrowser } from "../runtime/open-browser.js"; +import { pasteLoginInstructions, readPastedLine, boldIfTTY } from "../runtime/paste-login.js"; +import { isGuestOriginError, describeGuestError } from "../runtime/guest-error.js"; +import { ensureDeviceMidInConfig, VERSION, type ServeArgs } from "../index.js"; +import { appendFileSync } from "node:fs"; +import type { ProxyConfig } from "../config/types.js"; +import type { ProviderId } from "../provider/types.js"; +import { LogPane, type LogLevel } from "./log-pane.js"; +import { KeyParser, type KeyAction } from "./keys.js"; +import { buildFrame, findRegion, type ClickAction, type ClickRegion, type Frame } from "./frame.js"; + +type PlanTier = "coding-plan" | "start-plan"; +type ServerStatus = "stopped" | "starting" | "running" | "error"; + +const RENDER_MS = 33; +const PAGE_LINES = 10; +const TOAST_MS = 2600; + +export async function runTui(args: ServeArgs): Promise { + if (!process.stdout.isTTY || !process.stdin.isTTY) { + process.stderr.write( + "zcode-proxy: TUI mode needs an interactive terminal (TTY). " + + "For headless/CLI use run: zcode-proxy --cli serve\n", + ); + process.exit(1); + } + + const path = args.configPath ?? process.env.ZCODE_PROXY_CONFIG ?? "config.yaml"; + let config: ProxyConfig; + try { + if (ensureConfigFile(path)) { + ensureDeviceMidInConfig(path); + process.stderr.write(`Created ${path} from bundled template.\n`); + } + config = loadConfig(path); + } catch (err) { + process.stderr.write(`zcode-proxy: config error: ${(err as Error).message}\n`); + process.exit(1); + } + + const auth = new AuthManager(); + const pane = new LogPane(2000); + const serverRef: { current: ProxyServer | null } = { current: null }; + + const state = { + provider: config.provider as ProviderId, + plan: config.plan as PlanTier, + loggedIn: false, + apiKeyPreview: "", + serverStatus: "stopped" as ServerStatus, + serverUrl: "", + serverError: "", + loginInFlight: false, + loginHint: "", + toast: null as { text: string; kind: "ok" | "err" | "info" } | null, + }; + + // --- terminal setup ------------------------------------------------------ + const stdout = process.stdout; + const stdin = process.stdin; + // Captured before any interception: the TUI's own frame/setup writes and + // the post-cleanup error path must always reach the real terminal, even + // after process.stdout/stderr.write are rerouted into the log pane below. + const realStdoutWrite = stdout.write.bind(stdout) as (...a: unknown[]) => boolean; + const realStderrWrite = process.stderr.write.bind(process.stderr) as (...a: unknown[]) => boolean; + // Raw-mode availability check BEFORE any terminal state is touched: the + // failure message must reach the real terminal, not the (not yet visible) + // log pane, and nothing needs restoring if we never entered the alt screen. + if (typeof (stdin as { setRawMode?: (m: boolean) => void }).setRawMode !== "function") { + realStderrWrite("zcode-proxy: tui requires a terminal with raw-mode input.\n"); + process.exit(1); + } + // Alt screen + hide cursor + SGR mouse tracking (buttons clickable, wheel scrolls). + const enterAltScreen = (): void => { + realStdoutWrite("\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h\x1b[2J"); + }; + enterAltScreen(); + + const restore = (): void => { + try { realStdoutWrite("\x1b[0m\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l"); } catch { /* terminal gone */ } + }; + + // --- console interception โ†’ log pane (Android-entry pattern) ------------ + // ALL console methods are intercepted, not just log/warn/error: guest + // scripts (the captcha SDK) probe the full console surface, and anything + // left unpatched would bypass the pane and write raw into the alt-screen + // frame. Originals are kept for the pre-TUI error path and restore. + const origConsole: Record void> = {}; + const origError = console.error; + const logFile = process.env.ZCODE_TUI_LOGFILE; + const emit = (text: string, level: "info" | "warn" | "error"): void => { + pane.push(text, level); + if (logFile) { + try { appendFileSync(logFile, text + "\n", "utf-8"); } catch { /* best-effort tee */ } + } + scheduleRender(); + }; + const consoleOwner = console as unknown as Record; + for (const key of Object.keys(console)) { + const fn = consoleOwner[key]; + if (typeof fn !== "function") continue; + origConsole[key] = fn as (...a: unknown[]) => void; + consoleOwner[key] = (...a: unknown[]) => { + const level = key === "error" ? "error" : key === "warn" ? "warn" : "info"; + const prefix = key === "error" ? "[error] " : key === "warn" ? "[warn] " : ""; + emit(prefix + a.map(String).join(" "), level); + }; + } + const restoreConsole = (): void => { + for (const [key, fn] of Object.entries(origConsole)) consoleOwner[key] = fn; + }; + const restoreStdio = (): void => { + process.stdout.write = realStdoutWrite as typeof process.stdout.write; + process.stderr.write = realStderrWrite as typeof process.stderr.write; + }; + + // Reroute raw process.stdout/stderr writers into the log pane. The codebase + // has ~30 direct `process.stderr.write` call sites (captcha diagnostics, + // runtime notices) that bypass the console interception above โ€” on the alt + // screen their text + newlines land mid-frame, garbling the rendered UI and + // the click regions with it. The TUI's own writes go through the captured + // originals, never through these overrides. + const routeToPane = + (level: LogLevel) => + (chunk: unknown, encOrCb?: unknown, maybeCb?: unknown): boolean => { + const text = + typeof chunk === "string" + ? chunk + : Buffer.isBuffer(chunk) + ? chunk.toString("utf8") + : chunk instanceof Uint8Array + ? new TextDecoder().decode(chunk) + : String(chunk); + try { emit(text, level); } catch { /* pane failure must not break the writer */ } + const cb = typeof encOrCb === "function" ? encOrCb : typeof maybeCb === "function" ? maybeCb : undefined; + if (cb) (cb as () => void)(); + return true; + }; + process.stdout.write = routeToPane("info") as typeof process.stdout.write; + process.stderr.write = routeToPane("warn") as typeof process.stderr.write; + + // --- rendering ----------------------------------------------------------- + let renderTimer: ReturnType | null = null; + let lastRenderAt = 0; + let activeRegions: ClickRegion[] = []; + // Paste login (L key) hands the terminal back for a moment: renders and + // key handling are frozen while the real screen shows the paste prompt. + let rendersSuspended = false; + let inputSuspended = false; + function renderNow(): void { + if (rendersSuspended) return; // paste prompt owns the terminal + if (renderTimer) clearTimeout(renderTimer); // watchdog may fire mid-cycle + renderTimer = null; + lastRenderAt = Date.now(); + let frame: Frame; + try { + const width = stdout.columns || 80; + const height = stdout.rows || 24; + const view = pane.view(Math.max(4, height - 14)); + frame = buildFrame({ + version: VERSION, + configPath: path, + provider: state.provider, + plan: state.plan, + loggedIn: state.loggedIn, + apiKeyPreview: state.apiKeyPreview, + loginInFlight: state.loginInFlight, + loginHint: state.loginHint, + serverStatus: state.serverStatus, + serverUrl: state.serverUrl, + serverError: state.serverError, + modelCount: config.models.length, + responsesEnabled: config.responses.enabled, + claimAuto: config.claim.enabled && config.claim.auto, + logTotal: view.total, + logView: view.lines, + logFollowing: pane.following, + logFromBottom: view.fromBottom, + toast: state.toast, + width, + height, + }); + } catch (err) { + // A broken frame must never escape: through the uncaughtException + // handler it would tear down the whole TUI. Record it WITHOUT + // rescheduling (pane.push, not emit) โ€” emit's scheduleRender would turn + // a deterministic buildFrame failure into a ~30 Hz render-error loop. + // The watchdog retries at its own 2-4s cadence instead. + try { pane.push(`frame render failed: ${(err as Error).message}`, "error"); } catch { /* ignore */ } + return; + } + activeRegions = frame.regions; + try { realStdoutWrite("\x1b[H" + frame.text); } catch { /* terminal gone */ } + } + function scheduleRender(): void { + if (renderTimer) return; + renderTimer = setTimeout(renderNow, RENDER_MS); + if (typeof renderTimer.unref === "function") renderTimer.unref(); + } + let toastTimer: ReturnType | null = null; + function setToast(text: string, kind: "ok" | "err" | "info"): void { + state.toast = { text, kind }; + if (toastTimer) clearTimeout(toastTimer); + toastTimer = setTimeout(() => { + state.toast = null; + toastTimer = null; + scheduleRender(); + }, TOAST_MS); + if (typeof toastTimer.unref === "function") toastTimer.unref(); + scheduleRender(); + } + + // --- auth ---------------------------------------------------------------- + async function refreshAuth(): Promise { + const cred = await loadCredential().catch(() => null); + state.loggedIn = cred != null; + state.apiKeyPreview = cred ? `${cred.apiKey.slice(0, 8)}โ€ฆ` : ""; + scheduleRender(); + } + + // --- proxy lifecycle (mirrors the Android startProxy/stopProxy hooks) ---- + async function startProxy(): Promise { + if (state.serverStatus === "running" || state.serverStatus === "starting") return; + state.serverStatus = "starting"; + state.serverError = ""; + scheduleRender(); + const cred = await loadCredential().catch(() => null); + if (!cred) { + state.serverStatus = "stopped"; + setToast("not logged in โ€” press l to login", "err"); + return; + } + auth.setOAuthCredential(cred); + try { + const s = await startServer(buildServerOptions(config, auth, args.debug)); + serverRef.current = s; + state.serverStatus = "running"; + state.serverUrl = `http://${s.hostname}:${s.port}`; + setToast(`proxy started on ${state.serverUrl}`, "ok"); + startBackgroundJobsOnce(); + } catch (err) { + state.serverStatus = "error"; + state.serverError = (err as Error).message; + setToast(`start failed: ${(err as Error).message}`, "err"); + } + } + + function stopProxy(): void { + const s = serverRef.current; + if (!s) return; + try { + s.stop(false); // NOT stop(true) โ€” must not kill the process (anti-pattern #19) + } catch (err) { + setToast(`stop failed: ${(err as Error).message}`, "err"); + return; + } + serverRef.current = null; + state.serverStatus = "stopped"; + state.serverUrl = ""; + setToast("proxy stopped", "info"); + } + + function toggleProxy(): void { + if (state.serverStatus === "running" || state.serverStatus === "starting") stopProxy(); + else void startProxy(); + } + + // Captcha warmup + claim scheduler start once per process, even across + // proxy stop/start cycles โ€” the pools and scheduler are process-global. + let backgroundJobsStarted = false; + function startBackgroundJobsOnce(): void { + if (backgroundJobsStarted) return; + backgroundJobsStarted = true; + if (config.plan === "start-plan") { + import("../proxy/captcha.js") + .then((m) => m.startCaptchaPool(config.identity.appVersion)) + .catch((err) => console.error(`[captcha] pool warmup failed: ${(err as Error).message}`)); + } + if (config.claim.enabled && config.claim.auto) { + import("../claim/runtime.js") + .then((m) => { + m.startAutoClaim(config, auth); + console.log(`[claim] auto ON (poll ${Math.round(config.claim.pollIntervalMs / 1000)}s)`); + }) + .catch((err) => console.error(`[claim] scheduler failed to start: ${(err as Error).message}`)); + } + } + + // --- provider / plan switching (mirrors the Android setConfig command) --- + function switchProvider(): void { + const next: ProviderId = state.provider === "zai" ? "bigmodel" : "zai"; + applyConfigChange(next, state.plan, `provider โ†’ ${next}`); + } + + function switchPlan(): void { + const next: PlanTier = state.plan === "coding-plan" ? "start-plan" : "coding-plan"; + applyConfigChange(state.provider, next, `plan โ†’ ${next}`); + } + + function applyConfigChange(provider: ProviderId, plan: PlanTier, message: string): void { + if (state.serverStatus === "running" || state.serverStatus === "starting") { + setToast("stop the proxy before switching (press s)", "err"); + return; + } + config.provider = provider; + config.plan = plan; + try { + updateConfigYaml(path, { provider, plan }); + state.provider = provider; + state.plan = plan; + setToast(message, "ok"); + console.log(`config updated: provider=${provider} plan=${plan}`); + } catch (err) { + setToast(`config update failed: ${(err as Error).message}`, "err"); + } + scheduleRender(); + } + + // --- login / logout (mirrors the control-listener startOAuth/logout) ----- + let activeOauth: { client: OAuthFlowClient; provider: ProviderId } | null = null; + /** Set while a bigmodel login waits on the browser callback; `L` invokes it to switch to paste mode. */ + let pasteSwitchBigmodel: (() => void) | null = null; + + async function startLogin(opts: { paste?: boolean } = {}): Promise { + if (state.loginInFlight) { + setToast("login already in progress", "info"); + return; + } + const provider = state.provider; + if (opts.paste && provider !== "bigmodel") { + setToast("paste login is bigmodel-only โ€” zai login already works headless (press l)", "info"); + return; + } + + if (provider === "bigmodel") { + const client = new BigmodelOAuthClient(); + let started: Awaited>; + try { + started = await client.start(); + } catch (err) { + void client.close().catch(() => {}); + setToast(`login failed: ${(err as Error).message}`, "err"); + return; + } + activeOauth = { client, provider }; + state.loginInFlight = true; + console.log(`OAuth: opening ${started.authorizeUrl}`); + console.log("If the browser did not open, copy the URL above into a browser."); + openBrowser(started.authorizeUrl); + if (opts.paste) { + state.loginHint = "paste the callback URL in the terminalโ€ฆ"; + scheduleRender(); + settleLogin(runPasteLoginInTui(client, started), client, provider); + } else { + console.log( + "โ–ธ HEADLESS (Docker/VPS)? The callback page will NOT load here โ€” " + + "PRESS L to paste the redirected URL instead.", + ); + state.loginHint = "waiting for callback ยท HEADLESS? PRESS L to paste URL"; + scheduleRender(); + settleLogin(waitForCallbackOrPaste(client, started), client, provider); + } + return; + } + + const client: OAuthFlowClient = new ZaiOAuthClient(); + let started: Awaited>; + try { + started = await client.start(); + } catch (err) { + void client.close().catch(() => {}); + setToast(`login failed: ${(err as Error).message}`, "err"); + return; + } + activeOauth = { client, provider }; + state.loginInFlight = true; + state.loginHint = "waiting for browser authorizationโ€ฆ"; + console.log(`OAuth: opening ${started.authorizeUrl}`); + console.log("If the browser did not open, copy the URL above into a browser."); + openBrowser(started.authorizeUrl); + scheduleRender(); + + settleLogin(client.complete(started), client, provider); + } + + /** Sentinel the `L` key resolves to switch a pending login over to paste mode. */ + const PASTE_MODE = Symbol("paste-mode"); + + /** + * Wait for the browser callback โ€” but let `L` switch a pending login to + * paste mode (a headless machine never receives the callback). Exactly one + * branch wins; the loser's eventual timeout rejection is swallowed by the + * race, and the client is closed exactly once in settleLogin. + */ + async function waitForCallbackOrPaste( + client: BigmodelOAuthClient, + started: OAuthFlowStart, + ): Promise { + let requestPaste: () => void = () => {}; + const pasteRequested = new Promise((resolve) => { + requestPaste = () => resolve(PASTE_MODE); + }); + pasteSwitchBigmodel = () => { + state.loginHint = "paste the callback URL in the terminalโ€ฆ"; + scheduleRender(); + requestPaste(); + }; + try { + const winner = await Promise.race([client.waitForCallback(), pasteRequested]); + if (winner === PASTE_MODE) return await runPasteLoginInTui(client, started); + return await client.exchangeCode(winner, started.callbackUrl, started.state); + } finally { + pasteSwitchBigmodel = null; + } + } + + /** `L` key: switch a pending bigmodel login to paste mode (or start one). */ + function requestPasteLogin(): void { + if (state.provider !== "bigmodel") { + setToast("paste login is bigmodel-only โ€” zai login already works headless", "info"); + return; + } + if (state.loginInFlight) { + if (pasteSwitchBigmodel) pasteSwitchBigmodel(); + else setToast("already pasting โ€” finish in the terminal", "info"); + return; + } + void startLogin({ paste: true }); + } + + /** Shared completion tail: resolve key, save, and ALWAYS close the client. */ + function settleLogin(pending: Promise, client: OAuthFlowClient, provider: ProviderId): void { + pending.then(async (tokens) => { + const resolver = new KeyResolver(); + const cred = await resolver.resolveCodingPlanCredential(tokens.accessToken, provider, tokens.userId); + if (tokens.jwt) cred.jwt = tokens.jwt; + await saveCredential(cred); + if (serverRef.current) auth.setOAuthCredential(cred); + console.log(`OAuth completed for ${provider}`); + setToast("logged in", "ok"); + }).catch((err: unknown) => { + const msg = (err as Error)?.message ?? String(err); + console.error(`OAuth flow ended without success: ${msg}`); + setToast(`login failed: ${msg}`, "err"); + }).finally(() => { + // MUST run on rejection too โ€” otherwise the callback port leaks + // (fixed Android bug 5746857, same discipline applies here). + void client.close().catch(() => {}); + if (activeOauth?.client === client) activeOauth = null; + state.loginInFlight = false; + state.loginHint = ""; + void refreshAuth(); + }); + } + + /** + * Paste login for the TUI: briefly hands the terminal back (leaves the alt + * screen, drops raw mode) so the user can paste the redirected callback + * URL, then re-enters the TUI and exchanges the code. The callback server + * stays bound โ€” it only defines the redirect port; the browser cannot + * reach it from another machine anyway. + */ + async function runPasteLoginInTui( + client: BigmodelOAuthClient, + started: OAuthFlowStart, + ): Promise { + let pasted: string; + try { + rendersSuspended = true; + inputSuspended = true; + try { (stdin as { setRawMode(m: boolean): void }).setRawMode(false); } catch { /* not raw-able */ } + restore(); // leave the alt screen: the real terminal takes over + realStdoutWrite("\n" + pasteLoginInstructions(started.authorizeUrl, started.callbackUrl, LOGIN_TIMEOUT_MS) + "\n\n"); + realStdoutWrite(boldIfTTY("Paste the FULL redirected URL here, then press Enter:") + "\n> "); + pasted = await readPastedLine(LOGIN_TIMEOUT_MS); + } finally { + enterAltScreen(); + try { (stdin as { setRawMode(m: boolean): void }).setRawMode(true); } catch { /* ignore */ } + inputSuspended = false; + rendersSuspended = false; + renderNow(); + } + const code = parsePastedCallbackUrl(pasted, started.state); + realStdoutWrite("Exchanging authorization codeโ€ฆ\n"); + return client.exchangeCode(code, started.callbackUrl, started.state); + } + + async function logout(): Promise { + // Stop-first guard: the running proxy keeps serving with its in-memory + // credential until restarted, so logging out mid-run would only look applied. + if (state.serverStatus === "running" || state.serverStatus === "starting") { + setToast("stop the proxy before logging out (press s)", "err"); + return; + } + if (activeOauth) { + void activeOauth.client.close().catch(() => {}); + activeOauth = null; + state.loginInFlight = false; + state.loginHint = ""; + } + try { + clearCredential(); + } catch { /* best-effort logout */ } + await refreshAuth(); + if (serverRef.current) setToast("logged out โ€” restart the proxy to apply", "info"); + else setToast("logged out", "ok"); + } + + // --- input loop ------------------------------------------------------------ + const parser = new KeyParser(); + stdin.setEncoding("utf8"); + (stdin as { setRawMode(m: boolean): void }).setRawMode(true); + stdin.resume(); + stdin.on("data", (chunk: string) => { + if (inputSuspended) return; // paste-login readline owns the terminal + for (const action of parser.feed(chunk)) handleKey(action); + }); + + function scrollUp(n: number): void { + pane.scrollUp(n); + scheduleRender(); + } + function scrollDown(n: number): void { + pane.scrollDown(n); + scheduleRender(); + } + + function handleKey(action: KeyAction): void { + switch (action.type) { + case "ctrl-c": + quit(); + return; + case "click": { + const hit = findRegion(activeRegions, action.y, action.x); + if (hit) dispatchClick(hit); + return; + } + case "wheel-up": + scrollUp(3); + return; + case "wheel-down": + scrollDown(3); + return; + case "char": { + // Uppercase L must not collapse into "l" below: paste fallback (headless). + if (action.key === "L") { requestPasteLogin(); return; } + switch (action.key.toLowerCase()) { + case "q": quit(); return; + case "s": toggleProxy(); return; + case "l": void startLogin(); return; + case "o": void logout(); return; + case "p": switchProvider(); return; + case "t": switchPlan(); return; + case "c": pane.clear(); scheduleRender(); return; + case "g": pane.followBottom(); scheduleRender(); return; + case "k": scrollUp(1); return; + case "j": scrollDown(1); return; + default: return; + } + } + case "up": scrollUp(1); return; + case "down": scrollDown(1); return; + case "pageup": scrollUp(PAGE_LINES); return; + case "pagedown": scrollDown(PAGE_LINES); return; + case "home": scrollUp(pane.count); return; + case "end": pane.followBottom(); scheduleRender(); return; + default: return; + } + } + + /** Mouse clicks hit the same actions as their keyboard shortcuts. */ + function dispatchClick(action: ClickAction): void { + switch (action.kind) { + case "key": + handleKey({ type: "char", key: action.key }); + return; + case "provider": + applyConfigChange(action.value, state.plan, `provider โ†’ ${action.value}`); + return; + case "plan": + applyConfigChange(state.provider, action.value, `plan โ†’ ${action.value}`); + return; + case "follow": + pane.followBottom(); + scheduleRender(); + return; + } + } + + // --- teardown --------------------------------------------------------------- + function quit(): void { + cleanup(); + process.exit(0); + } + function cleanup(): void { + restore(); + restoreConsole(); + restoreStdio(); + try { serverRef.current?.stop(false); } catch { /* already closed */ } + } + // Render watchdog: if the 33ms render chain ever dies (stuck timer id, + // swallowed exception in a runtime with different uncaught semantics), the + // screen would freeze while the proxy keeps serving. The watchdog re-renders + // whenever nothing has painted for 3s and un-pauses a stalled stdin, so the + // worst-case freeze is bounded. Fires fine unref'd (timers only keep the + // process alive when everything else is gone; the server handle already does). + const watchdog = setInterval(() => { + try { if (stdin.isPaused()) stdin.resume(); } catch { /* stdin gone */ } + if (Date.now() - lastRenderAt > 3000) renderNow(); + }, 2000); + if (typeof watchdog.unref === "function") watchdog.unref(); + process.on("SIGINT", quit); + process.on("SIGTERM", quit); + process.on("exit", restore); + stdout.on("resize", scheduleRender); + // Guest captcha-SDK errors must NOT kill the TUI. Under Bun the Aliyun/ + // FeiLin bundles run in the HOST realm, so an error escaping one of their + // stray callbacks arrives here exactly like an internal fault. `serve` mode + // already logs-and-continues (captcha-happy.ts); the TUI used to exit(1) for + // everything, turning a retryable solve failure into a dead proxy (field + // report: "tui crashed: ReferenceError: moveBy is not defined" from + // feilin008.js). The pool retries the solve; the proxy keeps serving. + process.on("uncaughtException", (err: Error) => { + if (isGuestOriginError(err)) { + emit(`[warn] captcha SDK error (ignored): ${describeGuestError(err)}`, "warn"); + return; + } + cleanup(); + origError(`zcode-proxy: tui crashed: ${err.stack ?? String(err)}`); + process.exit(1); + }); + + // --- boot --------------------------------------------------------------------- + console.log(`zcode-proxy TUI โ€” config: ${path}`); + console.log(`provider: ${state.provider} ยท plan: ${state.plan}`); + await refreshAuth(); + renderNow(); + if (!state.loggedIn) { + setToast("not logged in โ€” press l to login", "err"); + } else { + await startProxy(); + } +} diff --git a/src/tui/frame.ts b/src/tui/frame.ts new file mode 100644 index 0000000000000000000000000000000000000000..38ba94e17b3a5012fc47fe30fb8ab4e49006fc2f --- /dev/null +++ b/src/tui/frame.ts @@ -0,0 +1,388 @@ +/** + * Pure frame renderer for the TUI. Takes a complete view-model and returns + * the full ANSI frame plus the clickable hit regions โ€” interactive rows are + * rendered as bracketed buttons (`[ zai ]`, `[S] Start`) and every button + * registers a row/column span the app hit-tests against mouse clicks (SGR + * mouse tracking, opencode-style). No I/O, no clock โ€” fully deterministic so + * tests can snapshot both the text and the regions. + * + * Layout mirrors the Android app: three stacked cards (Settings & Login / + * Proxy Server / Logs) plus a toast line and a key-hint footer (the hints + * are themselves clickable). The top two cards are fixed-height; the log + * card absorbs the remaining terminal rows. + */ +import { displayWidth, truncateToWidth } from "./width.js"; + +export type Seg = { t: string; c?: string }; + +/** What a mouse click on a button should do. `key` reuses the key bindings. */ +export type ClickAction = + | { kind: "key"; key: string } + | { kind: "provider"; value: "zai" | "bigmodel" } + | { kind: "plan"; value: "coding-plan" | "start-plan" } + | { kind: "follow" }; + +/** 0-based terminal-cell span carrying an action. */ +export interface ClickRegion { + row: number; + col: number; + width: number; + action: ClickAction; +} + +export interface Frame { + text: string; + regions: ClickRegion[]; +} + +/** Hit-test: the action whose button contains (col,row), if any. */ +export function findRegion(regions: readonly ClickRegion[], row: number, col: number): ClickAction | null { + for (const r of regions) { + if (r.row === row && col >= r.col && col < r.col + r.width) return r.action; + } + return null; +} + +export interface FrameState { + version: string; + configPath: string; + provider: string; + plan: string; + loggedIn: boolean; + apiKeyPreview: string; + loginInFlight: boolean; + loginHint: string; + serverStatus: "stopped" | "starting" | "running" | "error"; + serverUrl: string; + serverError: string; + modelCount: number; + responsesEnabled: boolean; + claimAuto: boolean; + logTotal: number; + logView: ReadonlyArray<{ level: string; text: string }>; + logFollowing: boolean; + logFromBottom: number; + toast: { text: string; kind: "ok" | "err" | "info" } | null; + width: number; + height: number; +} + +const DIM = "90"; +const RED = "31"; +const GREEN = "32"; +const AMBER = "33"; +const CYAN = "36"; +const BOLD = "1"; +const LABEL_W = 12; // fixed label column inside cards + +// Solid filled buttons โ€” GitHub dark-theme button palette via 24-bit +// truecolor SGR (Windows Terminal / mintty / modern Unix terminals render it +// natively; a legacy terminal falls back to its defaults with text intact). +// green #238636 success red #da3633 danger +// blue #1f6feb primary gray #30363d secondary (text #c9d1d9) +const BTN_GREEN = "38;2;255;255;255;48;2;35;134;54"; +const BTN_RED = "38;2;255;255;255;48;2;218;54;51"; +const BTN_BLUE = "38;2;255;255;255;48;2;31;111;235"; +const BTN_GRAY = "38;2;201;209;217;48;2;48;54;61"; +const BTN_SELECTED = BTN_BLUE; +/** Black on bright yellow โ€” login-hint attention chip, 16-color safe. */ +const HINT_CHIP = "30;103"; + +function paint(code: string, t: string): string { + return `\x1b[${code}m${t}\x1b[0m`; +} + +function segWidth(segs: readonly Seg[]): number { + let w = 0; + for (const s of segs) w += displayWidth(s.t); + return w; +} + +function paintSegs(segs: readonly Seg[]): string { + return segs.map((s) => (s.c ? paint(s.c, s.t) : s.t)).join(""); +} + +function segPlain(segs: readonly Seg[]): string { + return segs.map((s) => s.t).join(""); +} + +/** `โ•ญโ”€ title โ”€โ”€โ”€โ”€โ€ฆโ”€โ”€โ”€โ”€ pill โ”€โ•ฎ` */ +function renderTopBorder(w: number, left: Seg[], right: Seg[] = []): string { + let l = left; + let r = right; + if (r.length === 0) { + // โ•ญ(1) โ”€(1) sp(1) left sp(1) fill โ•ฎ(1) = w + if (5 + segWidth(l) > w - 1) l = [{ t: truncateToWidth(segPlain(l), Math.max(0, w - 7)) }]; + const fill = Math.max(1, w - 5 - segWidth(l)); + return paint(DIM, "โ•ญโ”€ ") + paintSegs(l) + paint(DIM, ` ${"โ”€".repeat(fill)}โ•ฎ`); + } + // โ•ญ(1) โ”€(1) sp(1) left sp(1) fill sp(1) right sp(1) โ”€(1) โ•ฎ(1) = w + const lw = segWidth(l); + const rw = segWidth(r); + let fill = w - 8 - lw - rw; + if (fill < 1) { + // Degenerate: shrink the right side, then the left. + const budget = Math.max(0, w - 9 - lw); + r = [{ t: truncateToWidth(segPlain(r), budget) }]; + fill = Math.max(1, w - 8 - lw - segWidth(r)); + if (fill < 1) { + l = [{ t: truncateToWidth(segPlain(l), Math.max(0, w - 8 - segWidth(r))) }]; + fill = Math.max(1, w - 8 - segWidth(l) - segWidth(r)); + } + } + return ( + paint(DIM, "โ•ญโ”€ ") + paintSegs(l) + paint(DIM, ` ${"โ”€".repeat(fill)} `) + + paintSegs(r) + paint(DIM, " โ”€โ•ฎ") + ); +} + +function renderBottomBorder(w: number): string { + return paint(DIM, `โ•ฐ${"โ”€".repeat(Math.max(0, w - 2))}โ•ฏ`); +} + +interface Part { + t: string; + c?: string; + action?: ClickAction; +} + +/** + * `โ”‚ Label [button] [button] โ€ฆ โ”‚` for an interactive row: parts are laid + * out left-to-right after the (optional) label column; parts carrying an + * action register a click region spanning exactly their cells. Overflow is + * dropped on the part that crosses the budget (and its region never added). + * With `chrome: false` the card borders/padding are omitted (footer row). + */ +function composeRow( + w: number, + row: number, + label: string | null, + parts: readonly Part[], + opts: { chrome?: boolean } = {}, +): { line: string; regions: ClickRegion[] } { + const chrome = opts.chrome !== false; + const contentW = Math.max(0, w - (chrome ? 4 : 2)); + const prefixPlain = label !== null ? " ".repeat(2) + label.padEnd(LABEL_W - 2) : " ".repeat(2); + const prefixW = displayWidth(prefixPlain); + const prefixPainted = label !== null ? paint(DIM, prefixPlain) : prefixPlain; + + const regions: ClickRegion[] = []; + const painted: string[] = []; + let col = prefixW; + for (const p of parts) { + const pw = displayWidth(p.t); + if (col + pw > contentW) break; + // With chrome the content starts after `โ”‚ ` (2 cells); without it the + // prefix itself starts at column 0. + if (p.action) regions.push({ row, col: (chrome ? 2 : 0) + col, width: pw, action: p.action }); + painted.push(p.c ? paint(p.c, p.t) : p.t); + col += pw; + } + if (!chrome) { + return { line: prefixPainted + painted.join(""), regions }; + } + const pad = " ".repeat(Math.max(0, contentW - col)); + return { + line: `${paint(DIM, "โ”‚")} ${prefixPainted}${painted.join("")}${pad} ${paint(DIM, "โ”‚")}`, + regions, + }; +} + +/** Radio-style option buttons rendered in FIXED slot order โ€” selection only + * changes colors, never positions, so clicking the same spot twice always + * hits the same button. */ +function optionParts( + slots: readonly [string, string], + selected: string, + makeAction: (v: string) => ClickAction, + disabled: boolean, +): Part[] { + const parts: Part[] = []; + slots.forEach((v, i) => { + if (i > 0) parts.push({ t: " " }); + parts.push({ + t: ` ${v} `, + c: disabled ? DIM : v === selected ? BTN_SELECTED : BTN_GRAY, + action: disabled ? undefined : makeAction(v), + }); + }); + if (disabled) parts.push({ t: " " }, { t: "(stop to switch)", c: AMBER }); + return parts; +} + +function logLineCode(level: string): string | undefined { + if (level === "error") return RED; + if (level === "warn") return AMBER; + return undefined; +} + +export function buildFrame(s: FrameState): Frame { + const w = s.width; + const h = s.height; + const regions: ClickRegion[] = []; + const lines: string[] = []; + const emit = (line: string): number => { + lines.push(line + "\x1b[0m\x1b[K"); + return lines.length - 1; + }; + + if (w < 40 || h < 14) { + // Untruncated on purpose: shrinking the diagnostic would defeat it. + emit("zcode-proxy: terminal too small for the TUI."); + emit(` need >= 40x14, got ${w}x${h}`); + return { text: lines.join("\n") + "\x1b[0m\x1b[J", regions }; + } + + const pill: Seg[] = s.loginInFlight + ? [{ t: "โ— logging inโ€ฆ", c: AMBER }] + : s.loggedIn + ? [{ t: "โ— ready", c: GREEN }] + : [{ t: "โ— logged out", c: AMBER }]; + + const busy = s.serverStatus === "running" || s.serverStatus === "starting"; + + // --- Settings & Login card --------------------------------------------- + emit(renderTopBorder(w, [{ t: "Settings & Login", c: BOLD }], pill)); + + const providerRow = composeRow( + w, lines.length, "Provider", + optionParts( + ["zai", "bigmodel"], + s.provider, + (v) => ({ kind: "provider", value: v as "zai" | "bigmodel" }), + busy, + ), + ); + emit(providerRow.line); + regions.push(...providerRow.regions); + + const planRow = composeRow( + w, lines.length, "Plan", + optionParts( + ["coding-plan", "start-plan"], + s.plan, + (v) => ({ kind: "plan", value: v as "coding-plan" | "start-plan" }), + busy, + ), + ); + emit(planRow.line); + regions.push(...planRow.regions); + + const authSegs: Seg[] = s.loggedIn + ? [{ t: "โ— ", c: GREEN }, { t: `logged in ยท ${s.apiKeyPreview}` }] + : [{ t: "โ—‹ not logged in", c: AMBER }]; + emit((composeRow(w, lines.length, "Auth", authSegs.map((g) => ({ t: g.t, c: g.c })))).line); + + const loginRow = composeRow(w, lines.length, "", s.loginInFlight + ? [{ t: " Logging inโ€ฆ ", c: DIM }] + : s.loggedIn + ? [ + { t: " Logged In ", c: DIM }, + { t: " " }, + // Logout is stop-first while the proxy is running โ€” the server keeps + // serving with its in-memory credential until restarted. + busy + ? { t: " Logout ", c: DIM } + : { t: " Logout ", c: BTN_GRAY, action: { kind: "key", key: "o" } }, + ] + : [ + { t: " OAuth Login ", c: BTN_GREEN, action: { kind: "key", key: "l" } }, + { t: " " }, + { t: " Logout ", c: DIM }, + ]); + emit(loginRow.line); + regions.push(...loginRow.regions); + + if (s.loginInFlight && s.loginHint) { + // High-contrast attention chip (black on bright yellow): the headless + // paste fallback hint must not be missed โ€” plain amber text reads as + // ordinary on many terminal palettes. + emit((composeRow(w, lines.length, "Login", [{ t: ` โ–ธ ${s.loginHint} `, c: HINT_CHIP }])).line); + } + + emit(renderBottomBorder(w)); + emit(""); + + // --- Proxy Server card -------------------------------------------------- + emit(renderTopBorder(w, [{ t: "Proxy Server", c: BOLD }])); + + const statusSegs: Seg[] = + s.serverStatus === "running" + ? [{ t: "โ— running", c: GREEN }, { t: " " + s.serverUrl, c: CYAN }] + : s.serverStatus === "starting" + ? [{ t: "โ— startingโ€ฆ", c: AMBER }] + : s.serverStatus === "error" + ? [{ t: "โœ— failed", c: RED }] + : [{ t: "โ—‹ stopped", c: DIM }]; + emit((composeRow(w, lines.length, "Status", statusSegs.map((g) => ({ t: g.t, c: g.c })))).line); + + const configText = [ + `${s.provider} ยท ${s.plan} ยท ${s.modelCount} models`, + s.responsesEnabled ? "/v1/responses" : "", + s.claimAuto ? "claim:auto" : "", + `v${s.version}`, + ].filter(Boolean).join(" ยท "); + emit((composeRow(w, lines.length, "Config", [{ t: configText, c: DIM }])).line); + + const startEnabled = s.serverStatus === "stopped" || s.serverStatus === "error"; + const stopEnabled = s.serverStatus === "running"; + const serverButtonsRow = composeRow(w, lines.length, "", [ + { t: " Start ", c: startEnabled ? BTN_GREEN : DIM, action: startEnabled ? { kind: "key", key: "s" } : undefined }, + { t: " " }, + { t: " Stop ", c: stopEnabled ? BTN_RED : DIM, action: stopEnabled ? { kind: "key", key: "s" } : undefined }, + ]); + emit(serverButtonsRow.line); + regions.push(...serverButtonsRow.regions); + + if (s.serverStatus === "error" && s.serverError) { + emit((composeRow(w, lines.length, "Error", [{ t: s.serverError, c: RED }])).line); + } + emit(renderBottomBorder(w)); + emit(""); + + // --- Logs card (absorbs remaining height) ------------------------------- + const logRight: Seg[] = s.logFollowing + ? [{ t: "following", c: GREEN }] + : [{ t: `โ–ผ ${s.logFromBottom} more ยท g follow`, c: AMBER }]; + const fixed = + lines.length + 2 /* log card borders */ + 1 /* footer */ + (s.toast ? 1 : 0); + const logRows = Math.max(1, h - fixed); + const logBorderRow = emit(renderTopBorder(w, [{ t: "Logs", c: BOLD }, { t: ` (${s.logTotal})`, c: DIM }], logRight)); + if (!s.logFollowing) { + // Clicking the log title bar jumps back to the tail, like the g key. + regions.push({ row: logBorderRow, col: 0, width: w, action: { kind: "follow" } }); + } + if (s.logView.length === 0) { + emit((composeRow(w, lines.length, null, [{ t: "(no logs yet โ€” start the server and send requests)", c: DIM }])).line); + } else { + for (const line of s.logView.slice(-logRows)) { + emit((composeRow(w, lines.length, null, [{ t: truncateToWidth(line.text, w - 6), c: logLineCode(line.level) }])).line); + } + } + emit(renderBottomBorder(w)); + + // --- Toast + footer ------------------------------------------------------ + if (s.toast) { + const color = s.toast.kind === "ok" ? GREEN : s.toast.kind === "err" ? RED : CYAN; + emit(" " + paint(color, truncateToWidth(`โ–ธ ${s.toast.text}`, w - 2))); + } + const footerRow = lines.length; + const footerParts: Part[] = []; + // Priority order โ€” the footer composes greedily and drops its tail on + // narrow terminals, so the primary actions must come first. + const footerItems: Array<[string, string]> = [ + ["s", "start/stop"], ["l", "login"], ["o", "logout"], ["g", "follow"], ["q", "quit"], + ["p", "provider"], ["t", "plan"], ["c", "clear"], + ]; + footerParts.push({ t: "โ†‘โ†“ scroll", c: DIM }); + for (const [key, label] of footerItems) { + footerParts.push({ t: " ยท ", c: DIM }); + footerParts.push({ t: `[${key}] ${label}`, c: DIM, action: { kind: "key", key } }); + } + // The footer lives outside the card borders โ€” no chrome, plain indent. + const footer = composeRow(w, footerRow, null, footerParts, { chrome: false }); + emit(footer.line); + regions.push(...footer.regions); + + return { text: lines.join("\n") + "\x1b[0m\x1b[J", regions }; +} diff --git a/src/tui/keys.ts b/src/tui/keys.ts new file mode 100644 index 0000000000000000000000000000000000000000..63ec121720eb33c71f1b63deb9d568090e1c475e --- /dev/null +++ b/src/tui/keys.ts @@ -0,0 +1,129 @@ +/** + * Incremental VT/ANSI input parser for the TUI keyboard loop. + * + * stdin is read in raw mode as a UTF-8 string stream; `KeyParser.feed` + * converts chunks into actions. A chunk can end in the middle of an escape + * sequence (lone `\x1b` before more bytes arrive), so unconsumed input is + * buffered until the sequence completes on a later chunk. Works identically + * under Bun and Node โ€” no readline keypress events involved. + * + * Mouse: with SGR mouse tracking enabled (`\x1b[?1000h\x1b[?1006h`), the + * terminal reports presses/releases as `ESC [ < b ; x ; y M/m` and wheel + * events as button codes 64/65 โ€” parsed into click/wheel actions so TUI + * buttons are directly clickable (coordinates arrive 1-based, converted + * to 0-based terminal cells). + */ + +export type KeyAction = + | { type: "char"; key: string } + | { type: "up" } + | { type: "down" } + | { type: "pageup" } + | { type: "pagedown" } + | { type: "home" } + | { type: "end" } + | { type: "click"; x: number; y: number } + | { type: "wheel-up" } + | { type: "wheel-down" } + | { type: "ctrl-c" } + /** Recognized but without a binding (Enter, Tab, bare Esc, Alt+key, drag/release, โ€ฆ). */ + | { type: "ignore" }; + +export class KeyParser { + private pending = ""; + + /** Consume a raw stdin chunk and return the actions it completes. */ + feed(chunk: string): KeyAction[] { + // Wedge guard: no real sequence is anywhere near 64 bytes (SGR mouse is + // ~16), so a pending tail this long means the parser is stuck on garbage. + // Drop it โ€” otherwise the stuck prefix would swallow every future chunk + // and the TUI would stop responding to keys and clicks for good. + if (this.pending.length > 64) this.pending = ""; + const buf = this.pending + chunk; + const actions: KeyAction[] = []; + let i = 0; + + while (i < buf.length) { + const ch = buf[i]!; + + if (ch === "\x1b") { + if (i + 1 >= buf.length) break; // lone ESC at chunk end โ€” wait for the rest + if (buf[i + 1] === "[") { + let j = i + 2; + while (j < buf.length && !/[A-Za-z~]/.test(buf[j]!)) j++; + if (j >= buf.length) break; // incomplete CSI โ€” wait + actions.push(csiAction(buf[j]!, buf.slice(i + 2, j))); + i = j + 1; + continue; + } + if (buf[i + 1] === "O") { + if (i + 2 >= buf.length) break; // incomplete SS3 โ€” wait + actions.push(csiAction(buf[i + 2]!, "")); + i += 3; + continue; + } + // Alt+key or other two-byte sequence โ€” no binding. + actions.push({ type: "ignore" }); + i += 2; + continue; + } + + if (ch === "\x03") { + actions.push({ type: "ctrl-c" }); + i++; + continue; + } + + if (ch < " " || ch === "\x7f") { + // Remaining control bytes (Enter/Tab/backspace/โ€ฆ) carry no binding. + actions.push({ type: "ignore" }); + i++; + continue; + } + + actions.push({ type: "char", key: ch }); + i++; + } + + this.pending = buf.slice(i); + return actions; + } +} + +function csiAction(final: string, params: string): KeyAction { + if (params.startsWith("<")) return mouseAction(params.slice(1), final); + switch (final) { + case "A": + return { type: "up" }; + case "B": + return { type: "down" }; + case "H": + return { type: "home" }; + case "F": + return { type: "end" }; + case "~": + if (params === "5" || params === "5;5") return { type: "pageup" }; + if (params === "6" || params === "6;5") return { type: "pagedown" }; + if (params === "1" || params === "7") return { type: "home" }; + if (params === "4" || params === "8") return { type: "end" }; + return { type: "ignore" }; + default: + return { type: "ignore" }; + } +} + +/** SGR mouse event: `