@jianmu-plugins/opencode-zcode-auth 0.0.0-stage → 0.1.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,459 @@
1
- # Temporary Holding Version
1
+ # @magpie-community/opencode-zcode-auth
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Signs in to Z.ai's GLM Coding Plan, or BigModel's (智谱). It does this the
4
+ way [ZCode](https://zcode.z.ai) does, and serves the plan's GLM models
5
+ over Anthropic's Messages API. Provider id: `zcode`.
6
+
7
+ ## Signing in
8
+
9
+ - **ZCode: Z.ai GLM Coding Plan** and **ZCode: BigModel (智谱) GLM Coding Plan**
10
+ - zcode.z.ai opens a sign-in flow, and the browser signs in to Z.ai or to
11
+ BigModel. The plugin polls the flow until it is done, so there is
12
+ nothing to paste.
13
+ - With that sign-in it takes the key named `zcode-api-key` from the
14
+ account's default project, or makes it if it isn't there, as ZCode does.
15
+ Requests go to `api.z.ai/api/anthropic` or
16
+ `open.bigmodel.cn/api/anthropic`.
17
+ - If the account has no plan of its own, it looks for a seat on a team's
18
+ plan and uses that team project's `zcode-team-api-key`.
19
+ - Failing both, it uses ZCode's free **Start Plan**, served by zcode.z.ai
20
+ with ZCode's session token.
21
+ - zcode.z.ai serves the Start Plan only to requests that look like the
22
+ ZCode client's own, and refuses others with HTTP 405 "request has been
23
+ blocked due to unusual activity". So a Start Plan request goes as
24
+ ZCode's does: ZCode's headers, ZCode's three system blocks with the
25
+ agent's system prompt at the end of the third (a fourth block is
26
+ refused, #343), the day in a `<system-reminder>` turn before the agent's
27
+ turns, and the sign-in's device id in `metadata.user_id`. GLM Coding
28
+ Plan and team requests go as the agent sent them, but for that same
29
+ `metadata.user_id` when the agent sent none: ZCode puts it on every
30
+ request, and the plan's endpoint keeps a prompt cache on the machine it
31
+ picks by it, so without it the cache is mostly missed (#387). An
32
+ account known only by its key gets a device id made from the key, the
33
+ same on every start. Every request also carries the `x-session-id`
34
+ header below. ZCode's headers are the desktop app's (3.17.2):
35
+ `X-Title: Z Code@electron`, and an `x-query-id` per user turn, a UUID
36
+ that stays the same through the turn's tool results and is new with
37
+ the next user message, as ZCode makes one per query. zcode.z.ai also
38
+ answers 405 code 3012 to every request of an account its risk control
39
+ blocked, ZCode's own app's included (plugins#348). That answer comes
40
+ back as ZCode's words, then "ZCode's risk control blocked this account
41
+ for unusual activity (code 3012); …", which magpie reads as the account
42
+ restricted: it rests, and the group's other providers are used. Only
43
+ ZCode support lifts such a block. A block page from ZCode's edge
44
+ firewall says this network's address was blocked instead. Since 0.1.43
45
+ (plugins#649) such a page also holds zcode.z.ai off for three minutes,
46
+ for every account of the plugin, since they share the address: the
47
+ Start Plan and a picked `-Trial` entry are answered at once with the
48
+ same 405 and words, so magpie still uses the group's other providers,
49
+ and free first keeps a dual account on its coding plan. The first
50
+ request after the three minutes asks again. A GLM Coding Plan key, on
51
+ api.z.ai, is never held.
52
+ - The Start Plan's token can't be refreshed. When it runs out, sign in
53
+ again.
54
+ - Every request, on any plan, names its conversation in `x-session-id`,
55
+ as ZCode does: a bare UUID, the same on each turn. BigModel's prompt
56
+ cache follows it: without it a long conversation's turns hit the cache
57
+ about one time in twenty, with it nearly every turn (#387). The
58
+ agent's own session id (magpie tells it to the plugin) goes as it is
59
+ when it is a UUID, else as a UUID made from it, so the vendor sees
60
+ only ZCode's format; with none, a UUID made from the device. The same
61
+ id is `metadata.user_id`'s `session_id`, as in ZCode's requests.
62
+ - **ZCode: a team's GLM Coding Plan**
63
+ - For an account with a plan of its own and a seat on a team's plan
64
+ (#285). The sign-ins above take the account's own plan, as ZCode does
65
+ by default; this one asks which site, signs in the same way, and
66
+ takes the team seat's `zcode-team-api-key`, as ZCode does when its
67
+ plan picker is switched to the team's plan.
68
+ - It is kept as an account of its own, named `<email> (team)`, beside
69
+ the account's own plan, so both can be used.
70
+ - With no seat on a team's plan, it says so and signs in to nothing.
71
+ - The same ZCode session also reads the person's gift plans. Their
72
+ `<model>-Trial` entries and gift buckets appear beside the team's
73
+ models and allowance. Plain models spend the team plan; trial entries
74
+ spend the personal gift, with no fallback to the team on refusal.
75
+ - **ZCode app's sign-in**
76
+ - Uses the account the ZCode app on this computer is signed in to. For
77
+ every request it reads ZCode's own credentials (`~/.zcode/v2`), so it
78
+ follows ZCode as it signs in again, renews its session or switches to a
79
+ team's plan, but only while ZCode is signed in to that same account.
80
+ Once ZCode signs out, or signs in to another account, the sign-in uses
81
+ what it saved when it was added; when that session has run out, it
82
+ asks to be signed in again. It never sends one account's requests with
83
+ another's credentials: to use both, add the app's sign-in once for each.
84
+ - **GLM Coding Plan API key**
85
+ - Paste a key (`<id>.<secret>`) and say which site it is from.
86
+ - A key reaches the GLM Coding Plan alone. ZCode's gift plans (the
87
+ Start Plan, ZCode 1024 Dev Day) are served to ZCode's own session,
88
+ which a key doesn't carry: for an account with only a gift plan, the
89
+ card and each refused request (1113) say to sign in with ZCode
90
+ instead. For an account with a GLM Coding Plan, the card says the
91
+ gift plans' `-Trial` models need ZCode's sign-in, since a key lists
92
+ none of them.
93
+
94
+ ## Where the sign-in is kept
95
+
96
+ In OpenCode's `auth.json` (magpie: `plugin-auth.json`), under `zcode`:
97
+
98
+ - **The browser sign-ins** are kept as an `oauth` entry:
99
+ - `access` is the key.
100
+ - `refresh` is JSON holding the site, the endpoint, the key, ZCode's
101
+ token, the team project, the plan and a device id of this plugin's own.
102
+ - **A pasted key** is kept as an `api` entry, with the site in `metadata`.
103
+
104
+ The plugin never writes ZCode's own credential store. It reads it only for
105
+ the ZCode app's sign-in (`refresh` then holds `"source": "zcode"`).
106
+
107
+ ## How requests are routed
108
+
109
+ Before each request, the plugin checks which plan the account is on, and
110
+ asks again every 10 minutes, and with every read of the usage card, so a
111
+ plan bought, a gift claimed or a plan lapsed reaches the requests when the
112
+ card shows it. A key whose plan list once reads no plan after reading one
113
+ is asked again after a minute, and a Start Plan refusal on such a key reads
114
+ the plans again on the next request:
115
+
116
+ - If the key's account has a GLM Coding Plan
117
+ (`/api/biz/subscription/list`), its requests go to that plan. A model
118
+ the account's gift plans also serve is listed again as
119
+ `<model>-Trial`; asking that entry spends the gift (see below).
120
+ - Otherwise they go to the gift plans.
121
+
122
+ Every request carries the key as both `x-api-key` and
123
+ `Authorization: Bearer`.
124
+
125
+ **The gift's trial entries.** An account with a GLM Coding Plan can
126
+ also hold gift plans from ZCode activities, ones that expire on a fixed
127
+ date. Their allowance would lapse unused if every request went to the
128
+ coding plan, so the plugin reads the gift's balance (per the sign-in's
129
+ session, kept for 10 minutes) and lists every model a live bucket
130
+ serves again as `<model>-Trial`, named in the catalog's spelling
131
+ (GLM-5.3-Flash-Trial). Asking a trial entry sends the model to the
132
+ gift, dressed as ZCode's own; asking the plain model spends the coding
133
+ plan — the choice is the user's. A bucket is judged spent only by its
134
+ `remaining_units` — a missing one is unknown, not spent. A trial entry
135
+ whose bucket is spent or blocked answers 429 without touching the
136
+ coding plan; when the gift answers a trial entry with a quota error
137
+ (code 1113 "Insufficient balance or no resource package", code 1005
138
+ "exceed quota limit", which it can answer inside an HTTP 200) that too
139
+ becomes a 429 and keeps the entry off for a minute. Any other gift
140
+ answer (its 405, its 401, its 5xx) goes on as it came: the user picked
141
+ the gift, so the coding plan is not spent behind their back. Every other
142
+ 429 counts as spent — Z.ai's 1302/1303 rate limits among them — while the
143
+ plan's own in-flight cap (3008/3009/3010) does not: such a request is asked
144
+ again instead (see [A few at once](#a-few-at-once)). A stream's body is
145
+ never read or buffered on the way.
146
+
147
+ Since 0.1.58 the trial entries are marked free in the model list: they
148
+ spend the gift, which costs nothing. magpie then reads a coding plan
149
+ model's weekly or monthly limit (code 1310) as that model's, not the
150
+ account's, so the account's `-Trial` entries are still asked while the
151
+ plan's model rests (plugins#438). In magpie's pickers the trial entries
152
+ carry the Free mark, and a routing group that prefers free models picks
153
+ them first.
154
+
155
+ **Free first.** Picking `-Trial` by hand keeps the choice the user's,
156
+ but an agent that always asks the plain model never sees the gift.
157
+ `freeFirst`, on by default since 0.1.42, turns the preference around:
158
+ the plain model spends the account's own live gift first, and falls
159
+ back to the coding plan when the gift cannot serve it — a bucket that
160
+ is spent, a model the gift does not serve, no ZCode session, or the
161
+ minute's rest a refusal just earned. In magpie, the switch is in the
162
+ provider's editor: Providers › ZCode, **Free quota first** under Plugin
163
+ options, just above Advanced (since 0.1.49). It is on by default; off
164
+ keeps the plain models on the plan. The JSON below still works, and a
165
+ `freeFirst: false` there keeps it off whatever the switch says. Turn it
166
+ off for the whole plugin in magpie's Plugins › Options
167
+
168
+ Since 0.1.59 a reply the gift answered says its model as the picker lists it (`GLM-5.3-Flash-Trial`), whether free first or a `-Trial` pick sent the request, so the Usage page, the sessions and the request log show which route spent the turn; a reply the coding plan answered, a free-first replay among them, keeps the plan's name.
169
+
170
+ ```json
171
+ { "freeFirst": false }
172
+ ```
173
+
174
+ or on the provider alone, under `provider.zcode.options` in the config
175
+ magpie hands its plugins — a key only `plugins.json`'s `config` carries,
176
+ so the plugin's own options are the ones magpie's Plugins › Options
177
+ edits. Where both say something, the provider's word stands. An account
178
+ with a coding plan and a gift spends the gift until it is spent, then
179
+ the plan; a gift-only account already goes to the gift by its plain
180
+ names, so the option changes nothing there. Across the accounts magpie
181
+ rotates, each spends its own gift before its own plan — which is the
182
+ point: free allowance is spent before subscribed quota, on every
183
+ account, with no per-account naming to keep up.
184
+
185
+ Two boundaries worth knowing. The gift is judged before the request is
186
+ sent, from the balance read the plugin keeps for ten minutes: a gift
187
+ that runs out between that read and the send has its refusal answered
188
+ from the plan in the same request — any gift failure is, its own
189
+ waited-out busy cap included, and the replay waits out the plan's busy
190
+ cap as any plan request does — and a spent answer or a block page rests
191
+ the model a minute and drops the route's balance read, so the requests
192
+ behind it go straight to the plan. Only a spent answer holds the
193
+ model's `-Trial` entry too; a refusal for another reason (a 405/3012)
194
+ keeps free first off the gift for the minute but leaves the `-Trial`
195
+ entry asking ZCode, which answers it as it came. Before 0.1.49 the two
196
+ rests were one, and a refused free-first request made the next `-Trial`
197
+ request answer a local "quota exhausted" 429 without asking. A gift that cannot be asked at all —
198
+ the network, the host — is answered from the plan the same way, the
199
+ route read dropped for the next request, while a caller's own abort
200
+ stays an abort. The agent sees the plan's answer
201
+ either way. And the `-Trial` entries keep their own strict semantics —
202
+ asking one is still an explicit pick of the gift alone, never the plan;
203
+ a spent one answers 429 with freeFirst on, as it does without it.
204
+
205
+ ## A few at once
206
+
207
+ A plan serves one account a few requests at a time; past that, ZCode
208
+ answers 429 with code 3008 "user concurrency limit exceeded", 3009
209
+ "model concurrency limit exceeded" or 3010. magpie funnels every agent's
210
+ and every session's requests of one computer through this one plugin
211
+ process, so magpie's own queue spaces an account's requests by the number
212
+ this plugin declares — `maxConcurrency` on the auth hook, and
213
+ `magpie.maxConcurrency` in its `package.json`, both three. A request the
214
+ vendor refuses anyway is asked again after 1s and once more after 2s, the
215
+ same request byte for byte, as ZCode's own client (3.17.2) does. A cap
216
+ that outlasts both goes on as a 429, ZCode's words followed by what they
217
+ mean, so the agent reads why. magpie still reads it as a rate limit: the
218
+ account rests a minute and the request goes to the next member of its
219
+ routing group.
220
+
221
+ For a coding plan three is a default, not a cap the plugin enforces. A
222
+ plan's real cap follows its tier — Z.ai serves a Max plan more at once
223
+ than a Pro, and a Lite fewer — and is higher off-peak
224
+ ([Z.ai's usage policy](https://docs.z.ai/devpack/usage-policy)), so a
225
+ number written into the plugin would hold a Max account to a Lite one's
226
+ with no way to raise it. A user who knows their plan's cap sets it on the
227
+ account or the provider in magpie, and magpie's queue follows that.
228
+
229
+ The free Start Plan is one tier, measured at about three in flight
230
+ (plugins#395), so there the plugin keeps its own gate too: an account's
231
+ fourth Start Plan request waits in the plugin, in arrival order, until
232
+ one of the three has been read to its end (or its agent went away), and
233
+ is not sent to be refused. That covers what magpie's queue cannot see —
234
+ a `maxConcurrency` raised past three, two magpie providers on one ZCode
235
+ account, an older host. A request that has waited two minutes is answered
236
+ here with a 429 that says it was not sent and why. Free first skips the
237
+ gift while its account's gate is full, so the plain model goes to the
238
+ coding plan rather than queueing.
239
+
240
+ A run of caps is also the edge firewall's countdown: two days of logs
241
+ (11-05 and 11-06) show ~18 requests/min on the Start Plan, up to ten in
242
+ flight on one account, bringing 3008 caps in a run, then 3–7 minutes
243
+ later a 405 block page that refuses the whole IP for 1–2 hours. Up to
244
+ 0.1.55 the plugin itself added to that run: it sent every request magpie
245
+ passed it, asked a capped one again up to six times over about ten
246
+ seconds, and counted every capped request toward the hold, so busy agents
247
+ tripped the hold on refusals it had caused. With the gate the plugin's
248
+ own requests stay under the cap, and a request counts only when ZCode
249
+ refuses it again at the 1s re-ask, the sign that someone else (the ZCode
250
+ app, another computer on the account) holds the slots. Five such
251
+ requests in one minute hold Start Plan requests off `zcode.z.ai` for
252
+ three minutes, process-wide and for every account, and answer them here
253
+ with a 429 and `Retry-After` that say what happened and what to do, so
254
+ magpie still rests the account and asks the group's next provider. A
255
+ coding plan, served by another host, is never held. The window clears
256
+ when the hold is armed, so the hold's own 429s cannot keep it armed, and
257
+ a request already in flight or queued stops asking too. This is distinct
258
+ from the network's 405 block page hold (plugins#649), which is what an IP
259
+ already refused needs; when both are on, the 405 hold's answer wins.
260
+ `inflight.test.mjs` replays the two days at 20× speed against a fake that
261
+ refuses past three in flight: 0.1.55 drew 24 refusals in it, this version
262
+ none.
263
+
264
+ Some accounts are served fewer than three at a time (plugins#438: one
265
+ account, one agent, refused at two in flight). Since 0.1.58 a request
266
+ refused again at its 1s re-ask while others of the same account were in
267
+ flight beside it narrows that account's gate to one fewer than were in
268
+ flight, at least one, for five minutes, after which it is back to three.
269
+ Such a refusal is this computer asking too much at once, which the
270
+ narrowed gate now stops, so it counts toward no hold; up to 0.1.57 those
271
+ refusals armed the hold at about five requests a minute, and armed it
272
+ again within a minute of its end. A request refused again alone, nothing
273
+ else of its account in flight, still counts as before: someone else holds
274
+ the slots. An account whose slots are taken elsewhere is narrowed to one
275
+ within a few refusals and then refused alone, so the firewall hold still
276
+ comes before the 405.
277
+
278
+ ## Two accounts at once
279
+
280
+ Three ZCode accounts used at once from one address can get the address
281
+ refused with a 405, where two are served (01huadalang on Discord). So the
282
+ plugin declares `maxAccounts` two, on the auth hook and as
283
+ `magpie.maxAccounts` in its `package.json`: magpie sends requests to the
284
+ first two accounts of the user's list only, and holds the others in
285
+ reserve. One that runs out or fails rests, and the first in reserve takes
286
+ its place until it is back. A user changes the number on the provider in
287
+ magpie (Advanced → Accounts at once, or `magpie provider at-once zcode
288
+ <n>`), 0 for every account at once. A magpie older than the one that
289
+ reads it uses every account, as before.
290
+
291
+ ## The usage card
292
+
293
+ An account with both plans shows both allowances: the coding plan's
294
+ windows first, then the gift's buckets, each with its own name, models
295
+ and end. The card's plan and term stay the coding plan's. A gift read
296
+ that fails leaves just the coding card — magpie hides a card's windows
297
+ behind an error, so a gift hiccup must not black out a working Coding
298
+ Plan. A gift that goes out of date while requests use it simply stops
299
+ showing. Beside the coding plan's windows each gift bucket is named by
300
+ its model first, as ZCode's own "Today's balance" lists it, then by its
301
+ plan ("GLM-5.1-Trial · Start Plan"), one plan or several, so the two
302
+ allowances can't be read as one. The model comes first because magpie's
303
+ ring and account row cut a long name short: "ZCODE GLOBAL BUI…" (the
304
+ Start Plan claimed on 10-29) said neither (#504).
305
+
306
+ **Gift plans that start later.** A plan on the balance whose `starts_at`
307
+ is still to come (a Start Plan taking effect at 23:00 today) serves
308
+ nothing yet: no request goes to it and its buckets don't count. The card
309
+ names it in a line set aside, "ZCode gift plan not started yet", with
310
+ the plan's name and its start in this computer's time as the display
311
+ ("Start Plan · 2026-10-29 23:00"), soonest first. An account whose only
312
+ gift plan starts later gets a card with that line, not "ended or never
313
+ started", and signs in with it too, as ZCode counts such a plan as the
314
+ account's (its "pending" Start Plan). The status ZCode gives such a plan has not been seen, so any
315
+ status but `expired` is taken; `starts_at` decides it.
316
+
317
+ **Resets.** A GLM Coding Plan of the account's own, and a team seat,
318
+ show the resets the vendor's usage page lists
319
+ (`/api/biz/customer-package-reset/list`, `targetType=PERSONAL` with the
320
+ plan's key, `TEAM` with the team's sign-in): how many of the five hours
321
+ and of the week are still available, and when each runs out, soonest
322
+ first. A team's are marked a team's. They are only read; a reset is
323
+ spent on the vendor's own page. A list that can't be read, or has none
324
+ left, shows no count.
325
+
326
+ **Gift plans ZCode holds but has not granted.** ZCode hands out one-off
327
+ trust-build / gift plans (a day's ZCode Trust Build, say) that are not
328
+ on the account until the ZCode app claims them. The plugin reads the
329
+ app's own lists of them with the card and names them there: its claim
330
+ banners' feed (`GET /api/v1/marketing/touch`, each delivery's
331
+ `claim_zcode_plan` button) and `GET /api/v1/zcode-plan/billing/preview`.
332
+ A banner plan (a weekend's ZCODE WEEKEND BUILD, 10-30) is in the feed
333
+ alone, never in the preview (#503) — the window is named "Gift plans to
334
+ claim in the ZCode app" and the display shows "1 · ZCode Trust Build"
335
+ — set aside, so the line stops nothing and routing, usage caps and the
336
+ menu bar pass it over. The name is a fixed sentence magpie can
337
+ translate; the count and the plan's own name are the display. Reading
338
+ the card never claims one. A preview that fails, or lists nothing, adds
339
+ no line at all, and a card that is an error keeps its error. Claim the
340
+ plan in the ZCode app (open it once), or let the daily claim below do it;
341
+ the next read shows it as an ordinary gift bucket.
342
+
343
+ ## The daily claim
344
+
345
+ With ZCode turned on in magpie's Settings → Daily check-in (it is off
346
+ until you turn it on), magpie has the plugin claim each account's gift
347
+ plans once a day (`auth.checkin`; `magpie accounts checkin` asks now). It
348
+ reads the banner feed above — the v3.17 client replaced the old preview
349
+ polling with the feed alone, and the feed is gated on the client's
350
+ version, so the plugin asks as the current client (3.17.2) sends — and
351
+ posts each plan the feed offers to
352
+ `POST /api/v1/zcode-plan/billing/claim` (`{"plan_id": …}`) with the
353
+ account's ZCode session, as the app does. An answer of nothing to claim
354
+ carries an `until` half an hour out, so magpie's loop asks again then,
355
+ and again, all day while the feed names no plan — one GET, nothing
356
+ posted: ZCode drops plans into the feed on its own schedule (a weekend
357
+ banner starting at 19:00 Beijing, say), and one that arrives
358
+ after the day's ask used to sit unclaimed past its short life. The
359
+ other answers stand for the day — but an *ineligible* (code 1004, below)
360
+ is read again in half an hour, as an inactive is: a claimed plan leaves
361
+ the feed, so
362
+ asking again half an hour later would find nothing and flip the card
363
+ from "Checked in today" to "No check-in event now"; a captcha plan
364
+ re-asked makes ZCode demand its captcha again; a done plan re-asked
365
+ posts a claim ZCode already answered. So a second plan the same day,
366
+ after one was claimed, is seen the next day. The answer is judged by
367
+ the body's code, not the HTTP status:
368
+
369
+ - nothing listed: *inactive* (ZCode answers an account with nothing to
370
+ claim `{"code":0,"msg":""}`, with no list at all). A feed that doesn't
371
+ read is *failed*, never nothing to claim;
372
+ - code 0: *claimed* (the next request uses the plan);
373
+ - code 1003 "target already exists" (HTTP 200): *done*, claimed before;
374
+ - ZCode's own client config (`GET /api/v1/client/configs`, read at most
375
+ every ten minutes) says whether a claim needs its security check
376
+ (`captcha.enabled`). While it does, which is so since 11-07, nothing is
377
+ posted: every plan answers *captcha*, "claim it in the ZCode app", since
378
+ a claim without the app's proof only spends one of ZCode's refusals. A
379
+ config that doesn't read answers *failed*, and nothing is posted then
380
+ either;
381
+ - code 3007 "captcha verify failed": *captcha*, the plan is claimed in
382
+ the ZCode app — the claim is gated on the Aliyun captcha the app's
383
+ renderer answers, and a claim from outside the app is refused it
384
+ (11-03: seven accounts' ZCODE GLOBAL BUILD all answered 3007). Once
385
+ claimed there, the gift lands on the account and freeFirst spends it
386
+ like any other;
387
+ - code 1004 "…not eligible for this plan yet" (HTTP 400): *ineligible*,
388
+ ZCode is not offering this account the plan at that moment. It is read
389
+ again half an hour out, since a plan can be offered later in the day
390
+ (11-04: an account's GLOBAL BUILD banner appeared 28 minutes after it
391
+ signed in). When *every* account answers 1004, check `APP_VERSION`
392
+ first: six accounts all answered 1004 under 3.16.3's header, and four
393
+ of them claimed with code 0 under 3.17.2's, one night, with nothing
394
+ else changed;
395
+ - HTTP 429 "Too Many Requests", or a body code 3002 "请求过于频繁": *failed*,
396
+ and the account is then **held in the plugin**: until the wait is over, a
397
+ check-in answers that same failed (`until` and all) and asks ZCode nothing.
398
+ magpie asks a failed again after 30 minutes of its own whatever `until`
399
+ says, so the hold has to live here (magpie from v0.1.3165 honors a failed's
400
+ `until` itself; older versions lean on this hold). A `Retry-After` ZCode
401
+ sent is honored up to six hours; without one the account's own wait doubles
402
+ from half an hour, and a read that comes through forgets it. The hold
403
+ belongs to one account and lives in memory — a magpie restart forgets it.
404
+ (11-04, #503: one owner read 180 of them over four days at magpie's
405
+ 30-minute retry, across several accounts.);
406
+ - anything else, an HTTP error without a code, or a reply that isn't
407
+ JSON: *failed*, which magpie asks again later that day. It is never
408
+ taken as claimed, and a failed claim leaves the account's sign-in
409
+ alone.
410
+
411
+ The rewards center in the client (奖励中心, the embedded
412
+ `zcode.z.ai/{cn|en}/rewards` page) is the referral program's website,
413
+ separate from these gift plans; its rewards are claimed on that page.
414
+
415
+ An account added with a GLM Coding Plan key has no ZCode session to claim
416
+ with (*ineligible*).
417
+
418
+ **No ZCode session.** A card read with a key, or with a sign-in whose
419
+ ZCode session has run out (it can't be renewed), sets aside a line named
420
+ "ZCode gift plans (-Trial models) need ZCode's sign-in", with why in its
421
+ display: such an account reads no gift and lists no `-Trial` entries.
422
+ Sign in again with ZCode to get them back. A gift read that fails
423
+ otherwise is asked again a minute later, not ten.
424
+
425
+ ## Models
426
+
427
+ The models are the ones ZCode offers for the account's plan. They come
428
+ from ZCode's provider config: the release zcode.z.ai names, or an
429
+ installed ZCode's copy if that one is newer. The list is kept for 10
430
+ minutes. When the config can't be read, the plugin falls back to this list
431
+ (and magpie keeps the list it was told last, unless the account's gift
432
+ plans add `-Trial` entries, which are told as read):
433
+
434
+ | Model | Context | Output | Efforts |
435
+ |---|---|---|---|
436
+ | GLM-5.3 | 1M | 128K | low, high, max |
437
+ | GLM-5.3-Flash | 1M | 128K | low, high, max |
438
+ | GLM-5.2 | 1M | 128K | none, high, max |
439
+ | GLM-5-Turbo | 200K | 64K | none, high |
440
+
441
+ The Start Plan's config has all of these except GLM-5.3. An account
442
+ with no GLM Coding Plan lists the models its gift plans' balance names,
443
+ under each model's own name, as ZCode does (the Start Plan's GLM-5.3
444
+ bucket makes GLM-5.3 a model), since all of its requests go to the gift
445
+ anyway. A config model the balance doesn't name is left out: an account
446
+ whose Start Plan holds only GLM-5.3-Flash lists GLM-5.3-Flash (and its
447
+ -Trial entry), not GLM-5.2 or GLM-5-Turbo. Only a balance that names no
448
+ model leaves the config's list standing.
449
+
450
+ A gift plan's models appear again as `<model>-Trial` entries, so a
451
+ request can spend the gift's quota on purpose. A trial entry is listed
452
+ while any live bucket serves its model, spent buckets included (a spent
453
+ entry answers 429 rather than vanishing mid-session).
454
+
455
+ Two plans can give one model (ZCode Trust Build and the Start Plan both
456
+ give GLM-5.3-Flash). The server picks the bucket, so the usage card
457
+ counts the model on its live bucket, the least used, and sets a spent
458
+ sibling aside. A spent sibling never makes the model, or the account,
459
+ look used up while another bucket still has quota.