Skip to content

Latest commit

 

History

History
108 lines (90 loc) · 6.4 KB

PROTOCOL.md

File metadata and controls

108 lines (90 loc) · 6.4 KB

ZCode protocol notes (3.16.x captures, 3.18.0 client default)

Evidence: six retained model captures and OAuth/billing flows, plus the installed ZCode client's resources/glm/zcode.cjs bundle and resources/app.asar archive. No live credential values are included in this document or the committed fixtures.

Messages

POST https://zcode.z.ai/api/v1/zcode-plan/anthropic/v1/messages

The same coding-plan JWT is sent as Authorization: Bearer ... and x-api-key. Anthropic version is 2023-06-01; beta is mid-conversation-system-2026-04-07. Fingerprinting matches the captured ZCode UA, version, platform, agent and session headers. Native Anthropic blocks are kept intact. OpenAI requests are converted at the transport boundary. Both routes include ZCode's default identity and harness system blocks. Existing native bootstrap blocks are preserved without duplication; caller instructions follow the defaults. No captured workspace context or extra tools are injected. Model requests include HTTP-Referer and carry the saved ZCode device identity in metadata; billing/OAuth requests also include X-Device-Mid. See the 3012 investigation for the resolved initialization issue. The coding-plan catalog is separate from chat.z.ai/api/models and the API-key providers. Only GLM-5.3 and GLM-5.3-Flash were validated in the supplied captures.

OAuth: correction to the audit prose

The installed client's Xdn/OAuth broker implementation generates a 32-byte random hex poll token before POST /oauth/cli/init. It sends that value as Bearer authorization, with JSON { "provider": "zai" }. The response returns flow_id, authorize_url, expires_at, poll_interval_sec, and sometimes a poll_token echo.

The echoed poll_token is optional. The client keeps the token it generated; requiring the server to echo it back broke login when the field disappeared. Polling /oauth/cli/poll/{flow_id} uses that same self-generated token as Bearer auth. Poll states include pending, failed and ready. The ready response contains the coding-plan JWT and user identity. No WorkOS exchange, short user code or secondary business token exchange is needed.

The captured coding-plan JWT has no exp, so ZcodeGate stores expiry zero as long-lived. The login poll may still return a refresh_token for some providers; when it does, the snapshot keeps it, but nothing silently refreshes a coding-plan JWT. A 401 may recover only by loading a changed credential from its source; otherwise the account is marked dead and needs login/import.

Credential encryption: correction to the audit prose

The local client implements enc:v1:<iv>.<tag>.<ciphertext>, each part base64url. The cipher is AES-256-GCM with a 12-byte nonce and 16-byte authentication tag. Its key is SHA-256 of ZCODE_CREDENTIAL_SECRET, if supplied, otherwise of zcode-credential-fallback:<node platform>:<home directory>:<username>. This is the implementation in the installed source, rather than the audit's Electron safeStorage description. The port uses authenticated Windows CNG and verifies a known AES-GCM vector and tamper rejection in tests.

Quotas

The observed working URL is /zcode-plan/billing/balance?app_version=<version> (the slash form, not billing_balance). The device/client headers are required. Version-gated endpoints (billing preview, marketing touch, balance) read the same value as x-zcode-app-version; it must stay at or above the current client build (3.18.0 at time of writing). 3.16.1 is the floor below which the preview answers an empty list, and marketing offers need 3.17.1 or newer. A successful business envelope has code: 0 and data with plans and balances. Buckets are aggregated by GLM model only for active, unexpired plans. available_units takes precedence over remaining_units, with daily period_end kept separately from the plan's ends_at. A depleted model does not park the other model. No stale captured trial dates or token balances are hard-coded.

Plan claim inventory

GET /zcode-plan/billing/preview and GET /marketing/touch?seq=0 are separate inventories. Start Plan variants (zcode-v3-start-plan-*) appear in the preview; Global/Weekend Build cards appear only as marketing deliveries, as a banner or popup button whose action.type is claim_zcode_plan. The card's plan_id is in action.args, and its display name (when present) in <slot>.background|hero.args.zcode_plan. The name is the stable key: campaign ids rotate per drop, so -1024 / -500m are history, not a pattern. A held Start Plan does not block cards — the buckets are independent, which is why the claim pass still walks the marketing feed for an account that already has -0817. A preview that answers data: null carries no offers; treat the two sources independently and claim whatever the other one returns. Marketing deliveries are impression-deduped per account: the first seq=0 page returns the card and the next call returns an empty list, so discovery and claim must happen in one pass (never pre-fetch for display and claim later).

Failure behavior

401 requires credentials; 402/code 11113 parks the affected model until its known quota reset; 429 uses Retry-After or a short cooldown; 403 parks only the model's entitlement. Transport and server failures can rotate before output. Model overload (HTTP 529, code 1305, or overloaded_error) uses a separate retry budget: 11 attempts by default, 2-second exponential base delay, 60-second maximum and 50-100% jitter. These defaults match the installed ZCode client's model retry options and delay calculation. Retry-After/Retry-After-Ms are respected within the maximum delay. Each rejected response closes and releases its reservation before waiting. Overload does not cool an account, consume its quota locally or park the model; another model stays routable. Quota/authentication failover keeps its separate account-attempt limit. Client disconnects stop delayed retries.

Once content is emitted, failures are surfaced without replaying the request. Truncated streams are errors; account reservations and HTTP responses close on success, failure, cancellation and early consumer disconnect.

Live quota and inference checks succeeded after the native system bootstrap was added. Flash rejected disabled thinking with code 1210. The adapter supports low/high/max and returns a clear 400 for unsupported off/none requests. Persistent model overload is returned as 529/code 1305 after bounded retries.