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

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,488 @@
1
- # Temporary Holding Version
1
+ # @jianmu-plugins/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. A model the gift plans' balance
121
+ doesn't name (an agent left on GLM-5.2 while the gift serves only
122
+ GLM-5.3-Flash) would spend none of the free quota, so it is answered
123
+ with the models the balance names and not sent. The balance is the one
124
+ the model list read; a model it doesn't name has it read again first.
125
+ When the plan list can't be read, an account whose last read found no
126
+ plan stays on the gift plans rather than sending its key to the coding
127
+ plan's host, which bills a key with no plan pay-as-you-go.
128
+
129
+ Every request carries the key as both `x-api-key` and
130
+ `Authorization: Bearer`.
131
+
132
+ **The gift's trial entries.** An account with a GLM Coding Plan can
133
+ also hold gift plans from ZCode activities, ones that expire on a fixed
134
+ date. Their allowance would lapse unused if every request went to the
135
+ coding plan, so the plugin reads the gift's balance (per the sign-in's
136
+ session, kept for 10 minutes) and lists every model a live bucket
137
+ serves again as `<model>-Trial`, named in the catalog's spelling
138
+ (GLM-5.3-Flash-Trial). Asking a trial entry sends the model to the
139
+ gift, dressed as ZCode's own; asking the plain model spends the coding
140
+ plan — the choice is the user's. A bucket is judged spent only by its
141
+ `remaining_units` — a missing one is unknown, not spent. A trial entry
142
+ whose bucket is spent or blocked answers 429 without touching the
143
+ coding plan; when the gift answers a trial entry with a quota error
144
+ (code 1113 "Insufficient balance or no resource package", code 1005
145
+ "exceed quota limit", which it can answer inside an HTTP 200) that too
146
+ becomes a 429 and keeps the entry off for a minute. Any other gift
147
+ answer (its 405, its 401, its 5xx) goes on as it came: the user picked
148
+ the gift, so the coding plan is not spent behind their back. Every other
149
+ 429 counts as spent — Z.ai's 1302/1303 rate limits among them — while the
150
+ plan's own in-flight cap (3008/3009/3010) does not: such a request is asked
151
+ again instead (see [A few at once](#a-few-at-once)). A stream's body is
152
+ never read or buffered on the way.
153
+
154
+ Since 0.1.58 the trial entries are marked free in the model list: they
155
+ spend the gift, which costs nothing. magpie then reads a coding plan
156
+ model's weekly or monthly limit (code 1310) as that model's, not the
157
+ account's, so the account's `-Trial` entries are still asked while the
158
+ plan's model rests (plugins#438). In magpie's pickers the trial entries
159
+ carry the Free mark, and a routing group that prefers free models picks
160
+ them first.
161
+
162
+ **Free first.** Picking `-Trial` by hand keeps the choice the user's,
163
+ but an agent that always asks the plain model never sees the gift.
164
+ `freeFirst`, on by default since 0.1.42, turns the preference around:
165
+ the plain model spends the account's own live gift first, and falls
166
+ back to the coding plan when the gift cannot serve it — a bucket that
167
+ is spent, a model the gift does not serve, no ZCode session, or the
168
+ minute's rest a refusal just earned. In magpie, the switch is in the
169
+ provider's editor: Providers › ZCode, **Free quota first** under Plugin
170
+ options, just above Advanced (since 0.1.49). It is on by default; off
171
+ keeps the plain models on the plan. The JSON below still works, and a
172
+ `freeFirst: false` there keeps it off whatever the switch says. Turn it
173
+ off for the whole plugin in magpie's Plugins › Options
174
+
175
+ 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.
176
+
177
+ ```json
178
+ { "freeFirst": false }
179
+ ```
180
+
181
+ or on the provider alone, under `provider.zcode.options` in the config
182
+ magpie hands its plugins — a key only `plugins.json`'s `config` carries,
183
+ so the plugin's own options are the ones magpie's Plugins › Options
184
+ edits. Where both say something, the provider's word stands. An account
185
+ with a coding plan and a gift spends the gift until it is spent, then
186
+ the plan; a gift-only account already goes to the gift by its plain
187
+ names, so the option changes nothing there. Across the accounts magpie
188
+ rotates, each spends its own gift before its own plan — which is the
189
+ point: free allowance is spent before subscribed quota, on every
190
+ account, with no per-account naming to keep up.
191
+
192
+ Two boundaries worth knowing. The gift is judged before the request is
193
+ sent, from the balance read the plugin keeps for ten minutes: a gift
194
+ that runs out between that read and the send has its refusal answered
195
+ from the plan in the same request — any gift failure is, its own
196
+ waited-out busy cap included, and the replay waits out the plan's busy
197
+ cap as any plan request does — and a spent answer or a block page rests
198
+ the model a minute and drops the route's balance read, so the requests
199
+ behind it go straight to the plan. Only a spent answer holds the
200
+ model's `-Trial` entry too; a refusal for another reason (a 405/3012)
201
+ keeps free first off the gift for the minute but leaves the `-Trial`
202
+ entry asking ZCode, which answers it as it came. Before 0.1.49 the two
203
+ rests were one, and a refused free-first request made the next `-Trial`
204
+ request answer a local "quota exhausted" 429 without asking. A gift that cannot be asked at all —
205
+ the network, the host — is answered from the plan the same way, the
206
+ route read dropped for the next request, while a caller's own abort
207
+ stays an abort. The agent sees the plan's answer
208
+ either way. And the `-Trial` entries keep their own strict semantics —
209
+ asking one is still an explicit pick of the gift alone, never the plan;
210
+ a spent one answers 429 with freeFirst on, as it does without it.
211
+
212
+ ## A few at once
213
+
214
+ A plan serves one account a few requests at a time; past that, ZCode
215
+ answers 429 with code 3008 "user concurrency limit exceeded", 3009
216
+ "model concurrency limit exceeded" or 3010. magpie funnels every agent's
217
+ and every session's requests of one computer through this one plugin
218
+ process, so magpie's own queue spaces an account's requests by the number
219
+ this plugin declares — `maxConcurrency` on the auth hook, and
220
+ `magpie.maxConcurrency` in its `package.json`, both three. A request the
221
+ vendor refuses anyway is asked again after 1s and once more after 2s, the
222
+ same request byte for byte, as ZCode's own client (3.17.2) does. A cap
223
+ that outlasts both goes on as a 429, ZCode's words followed by what they
224
+ mean, so the agent reads why. magpie still reads it as a rate limit: the
225
+ account rests a minute and the request goes to the next member of its
226
+ routing group.
227
+
228
+ For a coding plan three is a default, not a cap the plugin enforces. A
229
+ plan's real cap follows its tier — Z.ai serves a Max plan more at once
230
+ than a Pro, and a Lite fewer — and is higher off-peak
231
+ ([Z.ai's usage policy](https://docs.z.ai/devpack/usage-policy)), so a
232
+ number written into the plugin would hold a Max account to a Lite one's
233
+ with no way to raise it. A user who knows their plan's cap sets it on the
234
+ account or the provider in magpie, and magpie's queue follows that.
235
+
236
+ The free Start Plan is one tier, measured at about three in flight
237
+ (plugins#395), so there the plugin keeps its own gate too: an account's
238
+ fourth Start Plan request waits in the plugin, in arrival order, until
239
+ one of the three has been read to its end (or its agent went away), and
240
+ is not sent to be refused. That covers what magpie's queue cannot see —
241
+ a `maxConcurrency` raised past three, two magpie providers on one ZCode
242
+ account, an older host. A request that has waited two minutes is answered
243
+ here with a 429 that says it was not sent and why. Free first skips the
244
+ gift while its account's gate is full, so the plain model goes to the
245
+ coding plan rather than queueing.
246
+
247
+ A run of caps is also the edge firewall's countdown: two days of logs
248
+ (11-05 and 11-06) show ~18 requests/min on the Start Plan, up to ten in
249
+ flight on one account, bringing 3008 caps in a run, then 3–7 minutes
250
+ later a 405 block page that refuses the whole IP for 1–2 hours. Up to
251
+ 0.1.55 the plugin itself added to that run: it sent every request magpie
252
+ passed it, asked a capped one again up to six times over about ten
253
+ seconds, and counted every capped request toward the hold, so busy agents
254
+ tripped the hold on refusals it had caused. With the gate the plugin's
255
+ own requests stay under the cap, and a request counts only when ZCode
256
+ refuses it again at the 1s re-ask, the sign that someone else (the ZCode
257
+ app, another computer on the account) holds the slots. Five such
258
+ requests in one minute hold Start Plan requests off `zcode.z.ai` for
259
+ three minutes, process-wide and for every account, and answer them here
260
+ with a 429 and `Retry-After` that say what happened and what to do, so
261
+ magpie still rests the account and asks the group's next provider. A
262
+ coding plan, served by another host, is never held. The window clears
263
+ when the hold is armed, so the hold's own 429s cannot keep it armed, and
264
+ a request already in flight or queued stops asking too. This is distinct
265
+ from the network's 405 block page hold (plugins#649), which is what an IP
266
+ already refused needs; when both are on, the 405 hold's answer wins.
267
+ `inflight.test.mjs` replays the two days at 20× speed against a fake that
268
+ refuses past three in flight: 0.1.55 drew 24 refusals in it, this version
269
+ none.
270
+
271
+ Some accounts are served fewer than three at a time (plugins#438: one
272
+ account, one agent, refused at two in flight). Since 0.1.58 a request
273
+ refused again at its 1s re-ask while others of the same account were in
274
+ flight beside it narrows that account's gate to one fewer than were in
275
+ flight, at least one, for five minutes, after which it is back to three.
276
+ Such a refusal is this computer asking too much at once, which the
277
+ narrowed gate now stops, so it counts toward no hold; up to 0.1.57 those
278
+ refusals armed the hold at about five requests a minute, and armed it
279
+ again within a minute of its end. A request refused again alone, nothing
280
+ else of its account in flight, still counts as before: someone else holds
281
+ the slots. An account whose slots are taken elsewhere is narrowed to one
282
+ within a few refusals and then refused alone, so the firewall hold still
283
+ comes before the 405.
284
+
285
+ Since 0.1.64 the request that brought about such a narrowing is not
286
+ failed either. Up to 0.1.63 it went back to magpie as a 429 after its
287
+ re-asks, so two sessions on an account served one at a time showed a 429
288
+ every time the narrowing ran out (JJLIN070414 on X), and with one account
289
+ the agent was told it. Now it gives its slot back at once, without the 2s
290
+ re-ask, and waits at the head of the queue until one of the account's
291
+ other requests has ended, then is sent again, as ZCode's own client
292
+ (its dynamic-workflow governor) cuts its cap and queues a capped request
293
+ rather than failing it. The waits share the gate's two minutes, after
294
+ which it is answered here with the queue's 429. A request refused alone,
295
+ or free first's gift (which goes to the coding plan), is answered as
296
+ before.
297
+
298
+ ## Every account, one address
299
+
300
+ The plugin declares no `maxAccounts`, so magpie sends requests to every
301
+ ZCode account of the user's: the routing chosen spreads them, and one
302
+ that runs out or fails rests while the others go on. A user who wants
303
+ fewer sets the number on the provider in magpie (Advanced → Accounts at
304
+ once, or `magpie provider at-once zcode <n>`).
305
+
306
+ What zcode.z.ai's firewall refuses an address for (405, for an hour or
307
+ two) is too many Start Plan requests in flight from it at once, whichever
308
+ accounts they are for. So besides each account's three, the Start Plan
309
+ is sent at most six requests at a time from this computer over all its
310
+ accounts; the rest wait their turn in the plugin, as an account's own do.
311
+ Six is what two accounts sent when 0.1.40 to 0.1.67 declared
312
+ `maxAccounts` two after a 405 with three (01huadalang on Discord), which
313
+ held a user's other accounts in reserve. The coding plan, on another
314
+ host, is held to none of it.
315
+
316
+ ## The usage card
317
+
318
+ An account with both plans shows both allowances: the coding plan's
319
+ windows first, then the gift's buckets, each with its own name, models
320
+ and end. The card's plan and term stay the coding plan's. A gift read
321
+ that fails leaves just the coding card — magpie hides a card's windows
322
+ behind an error, so a gift hiccup must not black out a working Coding
323
+ Plan. A gift that goes out of date while requests use it simply stops
324
+ showing. Beside the coding plan's windows each gift bucket is named by
325
+ its model first, as ZCode's own "Today's balance" lists it, then by its
326
+ plan ("GLM-5.1-Trial · Start Plan"), one plan or several, so the two
327
+ allowances can't be read as one. The model comes first because magpie's
328
+ ring and account row cut a long name short: "ZCODE GLOBAL BUI…" (the
329
+ Start Plan claimed on 10-29) said neither (#504).
330
+
331
+ **Gift plans that start later.** A plan on the balance whose `starts_at`
332
+ is still to come (a Start Plan taking effect at 23:00 today) serves
333
+ nothing yet: no request goes to it and its buckets don't count. The card
334
+ names it in a line set aside, "ZCode gift plan not started yet", with
335
+ the plan's name and its start in this computer's time as the display
336
+ ("Start Plan · 2026-10-29 23:00"), soonest first. An account whose only
337
+ gift plan starts later gets a card with that line, not "ended or never
338
+ started", and signs in with it too, as ZCode counts such a plan as the
339
+ account's (its "pending" Start Plan). The status ZCode gives such a plan has not been seen, so any
340
+ status but `expired` is taken; `starts_at` decides it.
341
+
342
+ **Resets.** A GLM Coding Plan of the account's own, and a team seat,
343
+ show the resets the vendor's usage page lists
344
+ (`/api/biz/customer-package-reset/list`, `targetType=PERSONAL` with the
345
+ plan's key, `TEAM` with the team's sign-in): how many of the five hours
346
+ and of the week are still available, and when each runs out, soonest
347
+ first. A team's are marked a team's. They are only read; a reset is
348
+ spent on the vendor's own page. A list that can't be read, or has none
349
+ left, shows no count.
350
+
351
+ **Gift plans ZCode holds but has not granted.** ZCode hands out one-off
352
+ trust-build / gift plans (a day's ZCode Trust Build, say) that are not
353
+ on the account until the ZCode app claims them. The plugin reads the
354
+ app's own lists of them with the card and names them there: its claim
355
+ banners' feed (`GET /api/v1/marketing/touch`, each delivery's
356
+ `claim_zcode_plan` button) and `GET /api/v1/zcode-plan/billing/preview`.
357
+ A banner plan (a weekend's ZCODE WEEKEND BUILD, 10-30) is in the feed
358
+ alone, never in the preview (#503) — the window is named "Gift plans to
359
+ claim in the ZCode app" and the display shows "1 · ZCode Trust Build"
360
+ — set aside, so the line stops nothing and routing, usage caps and the
361
+ menu bar pass it over. The name is a fixed sentence magpie can
362
+ translate; the count and the plan's own name are the display. Reading
363
+ the card never claims one. A preview that fails, or lists nothing, adds
364
+ no line at all, and a card that is an error keeps its error. Claim the
365
+ plan in the ZCode app (open it once); while ZCode asks its security check
366
+ for a claim, as it does now, the daily claim below posts none. The next
367
+ read shows it as an ordinary gift bucket: its `-Trial` entry is listed and
368
+ free first spends it. Until then a `-Trial` pick that finds no gift is
369
+ refused with the held plan's name and "claim it in the ZCode app", not
370
+ only "no active limited quota" (heduian and bg5eau on X, 11-14).
371
+
372
+ ## The daily claim
373
+
374
+ With ZCode turned on in magpie's Settings → Daily check-in (it is off
375
+ until you turn it on), magpie has the plugin claim each account's gift
376
+ plans once a day (`auth.checkin`; `magpie accounts checkin` asks now). It
377
+ reads the banner feed above — the v3.17 client replaced the old preview
378
+ polling with the feed alone, and the feed is gated on the client's
379
+ version, so the plugin asks as the current client (3.17.2) sends — and
380
+ posts each plan the feed offers to
381
+ `POST /api/v1/zcode-plan/billing/claim` (`{"plan_id": …}`) with the
382
+ account's ZCode session, as the app does. An answer of nothing to claim
383
+ carries an `until` half an hour out, so magpie's loop asks again then,
384
+ and again, all day while the feed names no plan — one GET, nothing
385
+ posted: ZCode drops plans into the feed on its own schedule (a weekend
386
+ banner starting at 19:00 Beijing, say), and one that arrives
387
+ after the day's ask used to sit unclaimed past its short life. The
388
+ other answers stand for the day — but an *ineligible* (code 1004, below)
389
+ is read again in half an hour, as an inactive is: a claimed plan leaves
390
+ the feed, so
391
+ asking again half an hour later would find nothing and flip the card
392
+ from "Checked in today" to "No check-in event now"; a captcha plan
393
+ re-asked makes ZCode demand its captcha again; a done plan re-asked
394
+ posts a claim ZCode already answered. So a second plan the same day,
395
+ after one was claimed, is seen the next day. The answer is judged by
396
+ the body's code, not the HTTP status:
397
+
398
+ - nothing listed: *inactive* (ZCode answers an account with nothing to
399
+ claim `{"code":0,"msg":""}`, with no list at all). A feed that doesn't
400
+ read is *failed*, never nothing to claim;
401
+ - code 0: *claimed* (the next request uses the plan);
402
+ - code 1003 "target already exists" (HTTP 200): *done*, claimed before;
403
+ - ZCode's own client config (`GET /api/v1/client/configs`, read at most
404
+ every ten minutes) says whether a claim needs its security check
405
+ (`captcha.enabled`). While it does, which is so since 11-07, nothing is
406
+ posted: every plan answers *captcha*, "claim it in the ZCode app", since
407
+ a claim without the app's proof only spends one of ZCode's refusals. A
408
+ config that doesn't read answers *failed*, and nothing is posted then
409
+ either;
410
+ - code 3007 "captcha verify failed": *captcha*, the plan is claimed in
411
+ the ZCode app — the claim is gated on the Aliyun captcha the app's
412
+ renderer answers, and a claim from outside the app is refused it
413
+ (11-03: seven accounts' ZCODE GLOBAL BUILD all answered 3007). Once
414
+ claimed there, the gift lands on the account and freeFirst spends it
415
+ like any other;
416
+ - code 1004 "…not eligible for this plan yet" (HTTP 400): *ineligible*,
417
+ ZCode is not offering this account the plan at that moment. It is read
418
+ again half an hour out, since a plan can be offered later in the day
419
+ (11-04: an account's GLOBAL BUILD banner appeared 28 minutes after it
420
+ signed in). When *every* account answers 1004, check `APP_VERSION`
421
+ first: six accounts all answered 1004 under 3.16.3's header, and four
422
+ of them claimed with code 0 under 3.17.2's, one night, with nothing
423
+ else changed;
424
+ - HTTP 429 "Too Many Requests", or a body code 3002 "请求过于频繁": *failed*,
425
+ and the account is then **held in the plugin**: until the wait is over, a
426
+ check-in answers that same failed (`until` and all) and asks ZCode nothing.
427
+ magpie asks a failed again after 30 minutes of its own whatever `until`
428
+ says, so the hold has to live here (magpie from v0.1.3165 honors a failed's
429
+ `until` itself; older versions lean on this hold). A `Retry-After` ZCode
430
+ sent is honored up to six hours; without one the account's own wait doubles
431
+ from half an hour, and a read that comes through forgets it. The hold
432
+ belongs to one account and lives in memory — a magpie restart forgets it.
433
+ (11-04, #503: one owner read 180 of them over four days at magpie's
434
+ 30-minute retry, across several accounts.);
435
+ - anything else, an HTTP error without a code, or a reply that isn't
436
+ JSON: *failed*, which magpie asks again later that day. It is never
437
+ taken as claimed, and a failed claim leaves the account's sign-in
438
+ alone.
439
+
440
+ The rewards center in the client (奖励中心, the embedded
441
+ `zcode.z.ai/{cn|en}/rewards` page) is the referral program's website,
442
+ separate from these gift plans; its rewards are claimed on that page.
443
+
444
+ An account added with a GLM Coding Plan key has no ZCode session to claim
445
+ with (*ineligible*).
446
+
447
+ **No ZCode session.** A card read with a key, or with a sign-in whose
448
+ ZCode session has run out (it can't be renewed), sets aside a line named
449
+ "ZCode gift plans (-Trial models) need ZCode's sign-in", with why in its
450
+ display: such an account reads no gift and lists no `-Trial` entries.
451
+ Sign in again with ZCode to get them back. A gift read that fails
452
+ otherwise is asked again a minute later, not ten.
453
+
454
+ ## Models
455
+
456
+ The models are the ones ZCode offers for the account's plan. They come
457
+ from ZCode's provider config: the release zcode.z.ai names, or an
458
+ installed ZCode's copy if that one is newer. The list is kept for 10
459
+ minutes. When the config can't be read, the plugin falls back to this list
460
+ (and magpie keeps the list it was told last, unless the account's gift
461
+ plans add `-Trial` entries, which are told as read):
462
+
463
+ | Model | Context | Output | Efforts |
464
+ |---|---|---|---|
465
+ | GLM-5.3 | 1M | 128K | low, high, max |
466
+ | GLM-5.3-Flash | 1M | 128K | low, high, max |
467
+ | GLM-5.2 | 1M | 128K | none, high, max |
468
+ | GLM-5-Turbo | 200K | 64K | none, high |
469
+
470
+ The Start Plan's config has all of these except GLM-5.3. An account
471
+ with no GLM Coding Plan lists the models its gift plans' balance names,
472
+ under each model's own name, as ZCode does (the Start Plan's GLM-5.3
473
+ bucket makes GLM-5.3 a model), since all of its requests go to the gift
474
+ anyway. A config model the balance doesn't name is left out: an account
475
+ whose Start Plan holds only GLM-5.3-Flash lists GLM-5.3-Flash (and its
476
+ -Trial entry), not GLM-5.2 or GLM-5-Turbo. Only a balance that names no
477
+ model leaves the config's list standing.
478
+
479
+ A gift plan's models appear again as `<model>-Trial` entries, so a
480
+ request can spend the gift's quota on purpose. A trial entry is listed
481
+ while any live bucket serves its model, spent buckets included (a spent
482
+ entry answers 429 rather than vanishing mid-session).
483
+
484
+ Two plans can give one model (ZCode Trust Build and the Start Plan both
485
+ give GLM-5.3-Flash). The server picks the bucket, so the usage card
486
+ counts the model on its live bucket, the least used, and sets a spent
487
+ sibling aside. A spent sibling never makes the model, or the account,
488
+ look used up while another bucket still has quota.