ZCode provider: bring-your-own Z.AI coding plan (GLM)

[panudetjt]

Ask

Should T3 Code support ZCode — the CLI for Z.AI's GLM Coding Plan — as a provider? This is the product case that was asked for when #33684 was closed: a provider is a product decision that needs maintainer direction before code, so this thread is the place to settle direction and scope, not to request a merge. No PR is open.

Everything that was in the separate zcode serve design thread (#34215) is folded into Appendix A below below, so this is the single thread to read.

What ZCode is

Z.AI sells GLM Coding Plan subscriptions and ships an official zcode CLI for them. A subscriber signs in once with zcode login; the CLI holds the session and the plan entitlements, and exposes a local protocol (app-server --stdio, and a long-running zcode serve) for hosts to drive turns.

Why it fits T3 Code

• Bring your own subscription. Same shape as the other providers: sign in with the vendor CLI, T3 Code drives it. No API keys to paste.
• Plan-aware models. The picker comes from the plan, not a static list: GLM-5.3 and GLM-5.3-Flash, each with reasoning levels low, high, max and a 1M context window, so new plan models appear without an adapter change.
• Runtime modes map onto the CLI's own enforcement instead of being faked client-side; capabilities the CLI cannot prove over its protocol stay off.
• Remote ready. The CLI runs on the host server, so web, desktop, and mobile all work through the existing transport with nothing ZCode-specific on the client.

Two ways to integrate it, and what each costs

1. zcode app-server --stdio (what feat(provider-zcode): add ZCode as a provider #33684 did). This protocol splits the CLI into a host and an agent, and T3 Code plays the host, so the host has to answer the agent's credential requests: read the CLI's encrypted credential store and mint short-lived project tokens through Z.AI's endpoints. It would be the only provider here that decrypts a vendor credential store or reimplements a vendor endpoint chain — every other one integrates where the vendor binary owns credentials end to end (Kiro kiro-cli acp --auth-method=cli, Claude and Antigravity over ACP/SDK authenticate, Codex account/login/start, OpenCode opencode serve). We do not recommend this route, and it is the main reason not to revive that branch.
2. zcode serve (what feat(provider-zcode): add the ZCode provider on the zcode serve transport #34713 did). The CLI's own server performs the credential exchange in vendor code. T3 Code reads the daemon's local control files (run/status.json plus an ingress token) — not Z.AI credentials — and calls the daemon's host services for login state, entitlement, and the model list. Design detail and measurements in Appendix A below.

If this is in scope, route 2 is the one we would stand behind.

What it costs the maintainers

• One package (packages/provider-zcode) plus registry wiring: builtInDrivers, model-manifest.json, providerStatusCache, settingsSecrets, managedProviders, contracts, settings search on web and mobile, a provider docs page, and the release smoke script.
• A CLI version floor (MINIMUM_ZCODE_VERSION = 0.17.0) to pin behavior.
• The real risk: zcode serve is a hidden subcommand (absent from --help) and its channel protocol is undocumented, so we reverse-engineered it from the shipped bundle. Any CLI upgrade can move it. That is an argument for keeping the whole transport behind one adapter file, and a fair reason to say no until the CLI documents a host protocol.

Evidence that route 2 works

Against zcode 3.17.2 / CLI 0.17.1 on a developer machine: provider status, the GLM picker, a streaming turn, AskUserQuestion, steering, interrupt, /compact, and resume after a T3 restart. Captures of each are in Appendix D.

The credential-free claim is measured, not asserted, and the scripts plus raw payloads are published in Appendix C. An isolated daemon seeded with the runtime catalog, setting.json, and provider_config.json but no credentials.json returns oauth.getActiveProvider → null, every account provider at availability: "unavailable" / entitled: false / executable: false / unavailableReason: "not-connected", and an empty model picker. With the real login, the same three read-only calls return the account, the two GLM models with the same reasoning levels, and per-provider accountState. The entitlement ladder and model enumeration therefore come from the daemon; nothing reads the Z.AI credential store. Details in Appendix A below.

Questions for maintainers

1. Is a GLM / GLM Coding Plan provider in scope at all?
2. If yes, is zcode serve the route you want, or would you rather wait until the CLI documents a host protocol?
3. Who owns the CLI version floor and the breakage when the hidden protocol moves?
4. Naming in the picker: "ZCode" (the CLI), or "Z.AI" / "GLM" (the vendor and model family)?

Status

Both attempts are closed and unmerged, and both are kept as tags on the fork so this stays reference material rather than a pending PR:

• panudetjt/t3code@zcode-ref-33684 — app-server transport (closed feat(provider-zcode): add ZCode as a provider #33684)
• panudetjt/t3code@zcode-ref-serve — serve transport (closed feat(provider-zcode): add the ZCode provider on the zcode serve transport #34713)

The former design thread #34215 is now part of this one; see Appendix A.

Appendix A — the `zcode serve` transport, measured

Why route 2 exists

zcode app-server --stdio splits the CLI into a host and an agent, and the agent asks its host for provider credentials before every account-model request. Playing the host means T3 Code has to read the CLI's encrypted credential store and mint a project access token through Z.AI's business endpoints itself. The serve route removes both: the CLI's own server owns the exchange.

What it costs to switch transports:

• The wire changes from stdio NDJSON JSON-RPC to the CLI server's HTTP/WS surface: session create, streaming, approvals, and MCP injection.
• The CLI owns install, upgrade, and listening-port lifecycle. The OpenCode provider's server-owner/ledger code already models that and could be reused.
• Model enumeration and the entitlement ladder move from the CLI's config files to the daemon's services, which is the part measured below.

What the daemon exposes instead of the credential store

Read-only calls against a live daemon (zcode 3.17.2, provider CLI 0.17.1):

call	returns
oauth.getActiveProvider	"zai" — the login indicator (2 ms)
model-selection.getView	one provider account:zai-individual-coding-plan, models GLM-5.3 and GLM-5.3-Flash, reasoningLevel: [low, high, max], contextWindow: 1000000 (1 ms, 1958 B)
provider-settings.getView	all six account providers with accountState { availability, entitled, current, unavailableReason } plus executable (1-2 ms, 44 KB)

model-selection.getView matches what the branch's file-based enumeration produced, model for model, including reasoning levels. So provider/updateAccountConfig is not needed at all, and the badge and picker no longer need setting.json, current.json, or the catalog files.

Credential-free negative control

An isolated serve --supervisor instance seeded with the runtime catalog, setting.json, and provider_config.json, but no credentials.json, returns:

oauth.getActiveProvider      -> null
provider-settings.getView    -> 6 providers, availability "unavailable",
                                entitled false, executable false,
                                unavailableReason "not-connected"
model-selection.getView      -> providers: []

Nothing in that path touches the Z.AI credential store. The only local files a client needs are the daemon's own run/status.json and run/ingress-token.

Traps worth recording before anyone builds on this

1. usage-stats.getEntitlementSnapshot().authenticated is true even with no credentials ({"authenticated": true, "unavailableReason": "not_configured"}), so it is not a login signal. Use oauth.getActiveProvider !== null.
2. Logged out surfaces as unavailableReason: "not-connected", not "not-authenticated". accountState alone cannot separate "logged out" from "logged in, plan not connected", so pair it with oauth.getActiveProvider.
3. availability: "unknown" (account probe still running) makes models non-executable. An offline probe means an empty picker, where today's catalog enumeration would still list models — the badge has to distinguish "no models" from "not probed yet".

Cost

Warm daemon calls are 1-2 ms. The zcode doctor --json probe status.ts runs today is ~1.0 s (1.05 / 1.00 / 1.03 over three runs). provider-settings.onDidChange and model-selection.onDidChange are subscribable, so the badge and picker can refresh without polling.

Transport mechanics, for whoever reads the code

Frames are 1 byte kind + u32 id + u32 ack + u32 len, body is tagged/varint. A call header is [100, id, channel, method] with a single-element arg list; replies are 200 initialized, 201 result, 202 error, 203 rejected, 204 event. Dispatch is handler[cmd].apply(handler, args) on the service object, so the callable surface is exactly that object's methods — there is no introspection endpoint. The capability comes from POST /api/rpc-host-capability with the ingress token as Bearer, then travels as x-zcode-rpc-host-capability on ws://<host>:<port>/ws/host?token=….

Appendix B — what already exists in the branches

panudetjt/t3code@zcode-ref-serve (the head of #34713) is the full provider on this transport: package packages/provider-zcode, the orchestration adapter and its tests, the daemon client (status.json + ingress token, capability handshake, v4 conversation channel, resolveInteraction), and the registry wiring listed above. panudetjt/t3code@zcode-ref-33684 is the earlier app-server version. The serve branch already carries its adapter work, so that tag is kept only to compare the two credential paths.

Neither is a merge candidate as-is: both sit behind 384 commits of main, and the conflicts are concentrated in the registry files, not in the provider package.

Appendix C — the measurements, published so they can be checked

Everything below was measured on this machine against ZCode 3.16.3 (CLI 0.17.0, the branch's declared floor) and 3.17.2 (CLI 0.17.1). The scripts, raw payloads, and the one patch live on the fork so the numbers are auditable rather than asserted:

panudetjt/t3code@zcode-evidence — README is the index.

claim	file	how it was measured
The daemon exposes login, entitlement, and the model list without the credential store	01-daemon-rpc.md	three read-only channel calls, plus an isolated daemon with no credentials.json
session/resume takes no mode; setMode exists at the floor version	02-mode-and-errors.md	JSON-RPC against app-server --stdio on both versions
the endpoint override is reduced to an origin, and the catalog hash agrees	03-endpoint-origin.md	the vendor's shipped zcodeEndpoint.ts plus the catalog directory name
being the CLI's host doubled credential exchanges	04-route1-mints.md	measured while developing the app-server branch; the patch is included

Three results worth having inline, because they are the ones someone would otherwise take on faith:

Error taxonomy is usable for a version floor. session/doesNotExist → -32601 Method not found, session/resume with an unknown key → -32602 Invalid params — Unrecognized key: "mode", unknown session → -32004 Session not found. So "this CLI is too old" is distinguishable from "this call is wrong". Both versions behave identically.

A trap in the mode API. session/create { mode: "guarded" } lands in settings.permission.mode, while session.mode in the same reply is always "build" — that field is the build/plan interaction mode. Reading session.mode makes a working permission selection look ignored. session/resume preserves the permission mode but rejects a mode parameter outright, which is exactly why a host has to call session/setMode after a resume and before a turn when the two disagree.

The endpoint is an origin, and the catalog hash says so. normalizeZCodeEndpointOrigin returns new URL(value).origin, and buildZCodeEndpointUrls rebuilds <origin>/api/v1. The built-in catalog directory is …/3.17.2/endpoint-78d7c3bef4024722642626fe3669a799, and sha256("https://zcode.z.ai") is 78d7c3bef4024722642626fe3669a7995df81a7686ae62e0c31d41a14e61faca — the first 32 hex characters of the production origin. Hash the origin for both the environment and the catalog path, or the CLI reports no models for a valid login.

No script in the pack sends a prompt or starts a turn, so reproducing any of it costs nothing.

Appendix D — captures from the two branches

All of these are from the closed branches, live against the CLI on one machine. They live on the fork's release tag pr-evidence so the links survive the branches; the machine name in the window chrome is the host these ran on.

Route 1 — zcode app-server --stdio (#33684)

capture	shows
01-settings-providers-zcode.png	provider page reads "Authenticated · zcode", v0.17.1
02-model-picker-zcode.png	plan models in the picker, with the account id as the provider label
03-chat-glm-reply.png	a GLM-5.3-Flash turn answering in a T3 thread

Route 2 — zcode serve (#34713)

capture	shows
zcode-serve-provider.png	same page; launch arguments now read "passed to zcode serve when T3 Code starts the ZCode daemon"
zcode-serve-config.png	add-provider wizard, Config step for the daemon
zcode-serve-models.png	picker fed by model-selection.getView
zcode-serve-turn.png	streaming turn over the daemon channel
zcode-serve-interaction.png	an AskUserQuestion answered through resolveInteraction
zcode-serve-interrupt.png	interrupt mid-turn
zcode-serve-resume.png	resume after a T3 restart. The red "Reasoning level is required" line is the pre-fix state of a bug that branch then fixed, which is why it is here rather than cropped out
zcode-serve-walkthrough.mp4	end-to-end walkthrough, ~4 MB; GitHub does not inline video, so it is a link

Four of them inline, for scanning:

[panudetjt]

Follow-up scope for the same provider: #34215 — ZCode provider: drive zcode serve so the CLI owns credential exchange. The current app-server --stdio transport makes the server the CLI's host, so request auth has to be minted host-side; the zcode serve route would leave credentials with the CLI.

[panudetjt]

Follow-up implementing the zcode serve transport from #34215: #34713 upstream (stacked diff view: panudetjt#1).

T3 attaches to the user-level daemon, so the adapter no longer reads the credential store or mints project tokens itself. Everything else in this idea — GLM model picking, runtime modes, steering — is unchanged.