@jianmu-plugins/opencode-workbuddy-auth 0.0.0-stage → 0.2.34

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,613 @@
1
- # Temporary Holding Version
1
+ # @magpie-community/opencode-workbuddy-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 the plans of WorkBuddy, Tencent's desktop agent from CodeBuddy.
4
+ It has one provider for each of WorkBuddy's two builds:
5
+
6
+ | Provider id | Build | API |
7
+ |---|---|---|
8
+ | `workbuddy` | WorkBuddy, the China build (CodeBuddy plan) | `https://copilot.tencent.com/v2` |
9
+ | `workbuddy-ai` | WorkBuddy AI, the international build | `https://www.workbuddy.ai/v2` |
10
+
11
+ The package exports `WorkBuddyAuthPlugin` (`workbuddy`) and
12
+ `WorkBuddyAIAuthPlugin` (`workbuddy-ai`).
13
+
14
+ ## Signing in
15
+
16
+ - **Account (browser).** Opens Tencent's sign-in page for the build, the
17
+ one WorkBuddy's desktop app opens. The plugin then asks WorkBuddy for the
18
+ token every second until you're signed in, for 5 minutes at most. Nothing
19
+ needs to be pasted.
20
+ - **Desktop's sign-in.** Uses the account WorkBuddy desktop is signed in
21
+ to. Nothing is copied: the app's file is read on each request, and never
22
+ changed:
23
+ - macOS: `~/Library/Application Support/CodeBuddyExtension/Data/Public/auth/workbuddy-desktop[-ai].info`
24
+ - Windows: `~/AppData/Local/CodeBuddyExtension/…`
25
+ - Linux: `~/.local/share/CodeBuddyExtension/…`
26
+
27
+ WorkBuddy 5.6 and later keep the sign-in encrypted, which only the app
28
+ opens, so this way fails there and says so: use the browser sign-in.
29
+ - **API key** (since 0.1.37). A key made on the build's own keys page
30
+ (`https://www.workbuddy.cn/profile/keys` for `workbuddy`,
31
+ `https://www.workbuddy.ai/profile/keys` for `workbuddy-ai`), sent as
32
+ WorkBuddy's own CLI sends one: `X-API-Key` and `Authorization: Bearer`,
33
+ both the key, and `X-User-Id: anonymous_<the key's last 8 characters>`,
34
+ to the same API as the other sign-ins. A key isn't renewed; a refused one
35
+ says to check it. A key's credits are unknown (WorkBuddy's own client reads
36
+ none with a key), and its models are `/v3/config`'s only for `ck_`/`pt_`
37
+ keys, as the CLI asks; any other key keeps the list below.
38
+
39
+ - **Import from a file** (since 0.2.32; magpie with plugin imports).
40
+ magpie's "Import accounts from a file…" takes WorkBuddy desktop's
41
+ sign-in file (`workbuddy-desktop[-ai].info`, above) or a copy of a
42
+ sign-in: JSON with its access and refresh tokens, as this plugin's
43
+ `auth.json` entry, `accessToken`/`refreshToken` or
44
+ `access_token`/`refresh_token`, alone, in a map or in a list. Each is
45
+ renewed with WorkBuddy before it is added, as a browser sign-in is, so
46
+ the app or tool the file came from is signed out of that account. An
47
+ encrypted file (WorkBuddy 5.6 and later) and the other build's sign-in
48
+ are refused with why.
49
+
50
+ A browser sign-in is kept as an OpenCode `oauth` auth: the access and
51
+ refresh tokens, their expiry, the user id and the domain; desktop's as a
52
+ marker, `{"type": "oauth", "source": "desktop", "accountId", "uid"}`. OpenCode keeps it in
53
+ `auth.json`; magpie keeps it in `plugin-auth.json`. The access token is
54
+ refreshed a minute before it ends, and the new one is saved. If the refresh
55
+ fails, the old token is used while it lasts.
56
+
57
+ In magpie (0.1.684 or later) the plugin also gives `auth.refresh` with
58
+ `refreshLead` of 5 minutes: magpie renews a browser sign-in (an hour's
59
+ token) 5 minutes before it ends, once for the account, before its
60
+ requests, models and usage ask, and saves what it gives. It goes through
61
+ the same one-refresh-at-a-time as a request's refresh, so a refresh token
62
+ is never spent twice. A failed renewal, a refresh token past its end
63
+ included, doesn't mark the account, as the built-in never did; magpie
64
+ tries again later, and the old token is used meanwhile.
65
+ OpenCode doesn't call `auth.refresh`; the check before each request stays.
66
+
67
+ An enterprise (team) account is asked for as the enterprise. A browser
68
+ sign-in keeps the enterprise id WorkBuddy names for the account (from
69
+ `/login/account`, else its account list), and desktop's is read from the
70
+ app's file. Every request then carries `X-Enterprise-Id` and `X-Tenant-Id`,
71
+ as WorkBuddy's own client sends them; without them WorkBuddy answers as the
72
+ personal account, with the personal plan's models. A browser sign-in made
73
+ before 0.1.13 has no enterprise id kept: sign in again.
74
+
75
+ A cloud-hosted enterprise's account (its sign-in's domain is
76
+ `<enterprise>.sso.copilot.tencent.com`, `<enterprise>.copilot.qq.com` or
77
+ `<enterprise>.sso.codebuddy.cn`, the cloud-hosted hosts WorkBuddy's own
78
+ `product.json` lists) is served at that host, as WorkBuddy's client sets
79
+ the enterprise's endpoint for it: its refresh, account list, models, usage
80
+ and chats go there. Tencent's own iOA host
81
+ (`tencent.sso.copilot.tencent.com`) stays on `copilot.tencent.com`, as in
82
+ WorkBuddy's `product.ioa.json`. Before 0.2.32 every account was sent to
83
+ the build's own endpoint. A self-hosted enterprise's host isn't known to
84
+ the plugin and isn't routed.
85
+
86
+ An enterprise's own models (`custom:<name>|<name>`) are listed after the
87
+ plan's, as WorkBuddy's own client lists them, with their context, output,
88
+ images and efforts; the id goes to WorkBuddy as it is. Before 0.2.28 they
89
+ were left out of the list.
90
+
91
+ Which account a browser sign-in gives is chosen on WorkBuddy's own sign-in
92
+ page. After a phone sign-in it lists the person's accounts (personal, a
93
+ team, 「WorkBuddy 教育公益版」…) and binds the one picked to the sign-in, so
94
+ to add an education or team account, pick it there. Its account is named
95
+ with the enterprise too (`nickname · enterprise name`, or the end of the
96
+ enterprise id when WorkBuddy names none): one person's personal and
97
+ enterprise accounts share the uid and the nickname, and magpie keeps one
98
+ account per name and uid, so before 0.2.1 signing in to the enterprise
99
+ account replaced the personal one. An enterprise account signed in before
100
+ 0.2.1 keeps its old name until its Sign in again, which renames it in
101
+ place; its free-model window, read from usage rows kept under the old
102
+ name, starts again from the new one.
103
+
104
+ Desktop's sign-in is refreshed only when the app hasn't refreshed it
105
+ itself, and the new token is kept in memory, never written back, as magpie's
106
+ built-in WorkBuddy does.
107
+
108
+ A chat or usage read WorkBuddy answers 401 (since 0.1.31) is renewed once,
109
+ whatever the token's time, and sent once more. A token another process
110
+ saved since is taken first instead of spending the refresh token again. A
111
+ desktop sign-in is never renewed for it: the app's file is read again, and
112
+ its token is used if the app signed in again. A 401 again, or no new
113
+ token, ends in a 401 that says to sign in again (Providers → WorkBuddy →
114
+ this account's Sign in again in magpie; WorkBuddy desktop for a desktop
115
+ sign-in). The plugin marks the account expired in magpie
116
+ (`X-Magpie-Sign-In: expired`, usage's `signIn`) only on WorkBuddy's word
117
+ that the sign-in is gone: the refresh token refused (401, `invalid_grant`),
118
+ or the access token refused (`WWW-Authenticate: … error="invalid_token"`)
119
+ with no refresh token left to renew it with or just after renewing. A
120
+ failed renewal for another reason, or a bare 401 without `invalid_token`,
121
+ leaves the account as it is; a desktop sign-in is never marked. A 401
122
+ after a renewal takes a mark off (`renewed`).
123
+
124
+ ## Requests
125
+
126
+ Chats are chat completions (`@ai-sdk/openai-compatible`) at `<API>/chat/completions`.
127
+ They are streamed only; WorkBuddy refuses a chat that isn't.
128
+
129
+ **On WorkBuddy (China), the Claude models are served on Anthropic's Messages
130
+ API** instead: `@ai-sdk/anthropic` at `<endpoint>/v1/messages` (streamed only
131
+ as well). `claude-opus-5.5`, `claude-sonnet-5.5`, `claude-opus-5` and
132
+ `claude-opus-4.8-1m` answered there when each model of `/v3/config`'s `cli`
133
+ agent was asked on 2026-10-24; `glm-5.3` and `deepseek-v4.1-flash` answered
134
+ 500, `gpt-5.5` and `kimi-k3-1` 400, so every other model stays on chat.
135
+ WorkBuddy AI has no such route (`/v1/messages` is `404 Route Not Found` there
136
+ for every model), so all its models stay on chat, a Claude one too.
137
+
138
+ A Messages request goes as the agent sent it: no default system message, no
139
+ `max_completion_tokens`/`developer` rewrites, no tool reshaping, and nothing
140
+ moved for a refused system prompt — Claude Code's own prompt is taken as it
141
+ is, billing line and all, where a chat answers 11128 to it. One thing is
142
+ left out: a `thinking` block with no `signature`. A conversation that began
143
+ on chat (or on another provider) carries such blocks, and once a signed one
144
+ from this route sits beside them WorkBuddy refuses the whole request, 11159
145
+ "Invalid `signature` in `thinking` block … bound to a different
146
+ conversation", on every try. Signed blocks go back as they came. It carries
147
+ WorkBuddy's headers as a chat does, the same conversation and turn ids
148
+ included: a tool result in a `user` message of `tool_result` blocks answers
149
+ the step before it, as a `role: "tool"` message does in a chat.
150
+
151
+ The point of the route is effort. A chat carries `reasoning_effort` alone,
152
+ and WorkBuddy's chat endpoint answers at about the same length whatever it
153
+ says: asked the same question four times each (2026-10-24,
154
+ `claude-opus-5.5`), the median answer was 3884 output tokens at `low`, 5144
155
+ at `max` and 5715 at a value that isn't a level at all. Messages carries
156
+ `output_config.effort`, and `max` is honored there: a median of 30850
157
+ against 5748 at `low`, same model and question, four runs each. A Claude
158
+ model on Messages therefore lists `max` in its levels even where
159
+ `/v3/config` stops at `xhigh`.
160
+
161
+ `/v1/messages/count_tokens` **is not served** (404). magpie treats a 404 on
162
+ count_tokens as "no counter" (`unsupportedCount`) and answers with its own
163
+ estimate.
164
+
165
+ Each chat carries WorkBuddy's headers:
166
+ - `Authorization`, `X-User-Id`, `X-Domain`, `X-Product: SaaS`, `X-IDE-Type: WorkBuddy`;
167
+ - the desktop CLI's `User-Agent`, `WorkBuddy/<app> <appName>/<app> CLI/<cli>`:
168
+ `WorkBuddy/5.9.3 WorkBuddy/5.9.3 CLI/2.165.0` on the China build and
169
+ `WorkBuddy/5.9.3 workbuddy-ai/5.9.3 CLI/2.165.0` on WorkBuddy AI, each
170
+ build's current app on 2026-10-29; `X-IDE-Version` is the app's version.
171
+ A User-Agent not starting `WorkBuddy/<version>` is answered error 10085;
172
+ - the client's, which WorkBuddy's usage list shows as the client that asked
173
+ (使用端): `X-Agent-Purpose: conversation`, `X-IDE-Name: WorkBuddy`,
174
+ `X-IDE-Version`, `X-Agent-Intent: craft`, `X-Requested-With`. Both builds
175
+ send them, as WorkBuddy's own client does; a chat without them is counted
176
+ under no client at all;
177
+ - the conversation's ids: `X-Conversation-ID`, `X-Conversation-Request-ID`,
178
+ `X-Conversation-Message-ID`, `X-Request-ID`. WorkBuddy's backend counts a
179
+ user send as one request by `X-Conversation-Request-ID`, so every step of
180
+ one send — a tool result sent back, a retry — carries the same one, and
181
+ the user's next message carries another. Both ids are one account's own,
182
+ as WorkBuddy's client is signed in as one: a conversation sent as another
183
+ account (another of a group, or a sign-in saved since) carries that
184
+ account's ids, never the same ones under two `X-User-Id`s. The
185
+ conversation's is the session magpie (or OpenCode) names the request by,
186
+ else the chat's first user message; nothing is made up when neither names
187
+ one, a made-up conversation of the request's own being what splits one
188
+ conversation into many in the usage detail;
189
+ - what the CLI adds to a model request alone: `X-Agent-Type: main` on both
190
+ builds, `X-Agent-Runtime: local-agent` (new in 5.9),
191
+ `Accept: application/json`, and the `X-Stainless-*` headers of the OpenAI
192
+ SDK it sends through (openai 6.25.0 on Electron 37's Node v22.21.1, a
193
+ 1200s timeout, no retries).
194
+
195
+ Not sent: `X-Device-Token`, which the desktop app gets from Tencent's
196
+ native device SDK before each prompt, and a `traceparent`, which the CLI
197
+ adds only while its server-side tracing is on.
198
+
199
+ A WorkBuddy AI chat also carries, in its body, the `extra_vars` its own
200
+ client sends (#691): `initiator: "user"` and `growthEvent`, a JSON string
201
+ holding a `chat_request_send` event for the chat's `X-Conversation-ID`, with
202
+ the user's last message's length, the model's id and name, `mode: "craft"`
203
+ and no command. WorkBuddy AI's CLI sends this event in the chat itself
204
+ instead of on `/v2/report`; whether WorkBuddy reads it for the daily credit
205
+ is not known. Anything the caller put in `extra_vars` is kept. The China
206
+ build's chats go without it.
207
+
208
+ A chat that doesn't open with a system message is given WorkBuddy's
209
+ default one, as the app does.
210
+
211
+ WorkBuddy refuses some agents' identity lines as an "unapproved channel"
212
+ (11128), so those lines are reworded before a chat goes out. Since 0.1.27
213
+ (#279) that includes DeepSeek Harness's opening line. Since 0.2.3 a refusal
214
+ of words not reworded yet is answered first by saying the same line with one
215
+ more comma — a vendor matches such a line whole and exactly, so the comma
216
+ passes it while the line still names the harness (measured 2026-10-30; a word
217
+ added after the product name did not pass, the comma did). The comma is set in
218
+ the system and assistant messages only — the two WorkBuddy reads — so the
219
+ user's own words and tools' results go out as they were sent. A system prompt
220
+ whose comma passed is remembered while the plugin is loaded, as a moved one
221
+ is, and its next chats go with the comma already in before the first send:
222
+ otherwise every turn, and every step of a tool loop, would pay the refusal
223
+ once. Only a chat refused still is sent once more, since 0.1.29, with the
224
+ system prompt moved into the first user message (inside `<instructions>` tags)
225
+ and WorkBuddy's default system prompt in its place: WorkBuddy checks only the
226
+ system and assistant messages, and the line it matched is then in neither. A system message later
227
+ in the chat becomes a user message where it stands. The plugin remembers each
228
+ refused system prompt while it is loaded, so that agent's next chats go moved
229
+ at once. The move can't reach an assistant message, so words the model quotes
230
+ back into one keep that chat refused until they are in the list reworded in
231
+ every message (since 0.1.30, the "Web GUI whose URL the runtime context names"
232
+ line, #291); otherwise only a new chat clears it. A refusal that stands after
233
+ the move ends in a hint that names no one client (since 0.1.28): WorkBuddy
234
+ refused words in this client's prompt; use it from Hermes, OpenCode or Pi, or
235
+ add another provider to the group. Since 0.2.3 that hint is preceded by the
236
+ address of [REFUSED.md](REFUSED.md), which says what the check reads, how a
237
+ line is reworded to pass it, and how to turn such a line off in an agent that
238
+ has a switch for it — so the error carries its own fix, for the person who
239
+ reads it or the agent they paste it to. Neither refusal rests the account.
240
+
241
+ The loader also translates OpenAI-compatible request spellings WorkBuddy
242
+ doesn't take: `max_completion_tokens` becomes `max_tokens`, `developer`
243
+ messages become `system`, an object `tool_choice` becomes WorkBuddy's
244
+ string form, and an earlier assistant turn's `reasoning_content` (or
245
+ `reasoning_details` text) goes as `reasoning`, the field WorkBuddy's own
246
+ client sends. WorkBuddy drops `reasoning_content`, so a client such as Grok
247
+ Build that sends it lost its earlier thinking; nothing is folded into the
248
+ message's content.
249
+
250
+ A chat's tools are given shapes WorkBuddy's models take. Without them
251
+ WorkBuddy AI answers 400 "Invalid request parameters" (11133), DeepSeek's
252
+ models to each shape below and Kimi's, GPT's, Gemini's and GLM's to some:
253
+ - a tool's parameters with no `type`, empty, or a union (`anyOf`, `oneOf`,
254
+ `allOf`) at the root are an object, the union's fields merged;
255
+ - a `pattern`'s `\0` is `\u0000`, which matches the same;
256
+ - REA's exact `^[^\uD800-\uDFFF]*$` surrogate guard is omitted from the
257
+ outbound schema: WorkBuddy AI's DeepSeek rejects it with "invalid function
258
+ call parameters". Other path constraints and REA's own validation stay;
259
+ - a tuple's `items` (a list) is one schema any of them fits;
260
+ - an `enum` with no `type` takes its values' type (or that and `"null"`),
261
+ and an `enum` of several types is an `anyOf` of one typed `enum` for
262
+ each, at any depth; an empty `enum` is left out (Kimi and DeepSeek, an
263
+ MCP server's tools, #122);
264
+ - `true` and `false` where a schema goes are `{}` and `{"not": {}}`
265
+ (`additionalProperties` is left); a `required` that isn't a list, and a
266
+ `type` JSON Schema doesn't name, are left out, and `"String"` is
267
+ `"string"`;
268
+ - a tool's name with a character other than letters, digits, `_` and `-`
269
+ (`.`, `:`, `/`, a space, CJK) is sent with `_` there, and the model's
270
+ calls come back under the tool's own name.
271
+
272
+ WorkBuddy AI's `gemini-3.8-flash` answers 400 "the conversation must end
273
+ with a user message" (11153) to a chat whose tool results are followed by
274
+ the user's message, as magpie sends Claude Code's reminders, words typed
275
+ mid-task and a tool's images. Such a chat goes again with an empty
276
+ assistant message between the results and the user's message, which it
277
+ serves; a model that refused it once gets it that way from then on, until
278
+ the plugin restarts. A chat ending with the assistant's message (a prefill)
279
+ is refused as before.
280
+
281
+ WorkBuddy's safety filter can refuse a reply it has begun:
282
+ `deepseek-v4.1-flash` reasoned, said "Sorry, I can't respond to this
283
+ question.", and ended with `finish_reason: "content_filter"` and no output
284
+ tokens, all under a 200 (#540). Since 0.2.4 that line is taken out of a
285
+ streamed chat ending `content_filter`, so the reply says nothing before the
286
+ filter's stop: magpie hands such a refusal to the group's next member
287
+ instead of passing it to the agent as an answer. Only text that is still
288
+ the filter's line is held, so any other reply's words go as they come; the
289
+ same words ending `stop`, or the filter cutting off a reply after other
290
+ words, go through as they came.
291
+ copilot.tencent.com sends the line with a newline on each side
292
+ (`"\nSorry, I can't respond to this question.\n"`); since 0.2.5 white
293
+ space around it no longer lets it through. It also puts `"tool_calls": []` on
294
+ every delta; since 0.2.6 only a list with a call in it lets the reply
295
+ through as it came.
296
+
297
+ ## Models
298
+
299
+ When you are signed in, the models are the ones WorkBuddy's product config
300
+ gives its CLI agent (`GET /v3/config`), with their context, image input and
301
+ reasoning levels. Until then, or if WorkBuddy doesn't answer, the list below
302
+ is used. Since 0.2.9 its models take images, as the config says of every
303
+ model, except WorkBuddy AI's GLM models, whose images WorkBuddy AI drops
304
+ (#572).
305
+
306
+ `workbuddy`:
307
+ - Auto
308
+ - Hy4 preview, Hy3, Hy3-X
309
+ - Deepseek-V4.1-Flash, Deepseek-V4-Pro
310
+ - GLM-5.3, GLM-5.3-Flash, GLM-5.2, GLM-5.1, GLM-5v-Turbo
311
+ - MiniMax-M3
312
+ - Kimi-K3, Kimi-K2.7-Code, Kimi-K2.6
313
+
314
+ `workbuddy-ai`:
315
+ - Default, Fast, Balanced, Primary, Deep
316
+ - GPT-5.5, GPT-5.4, GPT-5.3-Codex
317
+ - Gemini-3.1-Pro, Gemini-3.5-Flash
318
+ - GLM-5.3, GLM-5.2
319
+ - Hy3
320
+ - Kimi-K3, Kimi-K2.6
321
+ - MiniMax-M3
322
+
323
+ A model's reasoning levels are its variants (`reasoningEffort`). A chat
324
+ that names no level goes at the model's own default from the config
325
+ (`reasoning.defaultEffort`, "high" for DeepSeek-V4.1-Flash), as WorkBuddy's
326
+ client sends it: WorkBuddy doesn't think when a chat names none, so
327
+ OpenCode's default variant got answers without thinking. An effort the
328
+ client names, `none` too, goes as it came. A chat whose `max_tokens` is
329
+ 1024 or less gets no default (since 0.2.15, #643): a title or a
330
+ classification asked at 64 tokens spent all 64 on reasoning and answered
331
+ nothing. Anthropic's API takes no thinking under a 1024-token budget, so
332
+ no client means to think in one that small.
333
+
334
+ One value differs from the config, measured with real requests:
335
+ DeepSeek-V4.1-Flash (and its paid `-sg` id) lists `none`, though the
336
+ config says it only reasons: WorkBuddy answers `reasoning_effort: "none"`
337
+ on it with no thinking at all (since 0.2.7, #563).
338
+
339
+ A model's context is the config's `maxInputTokens` on both sites. 0.2.7
340
+ capped DeepSeek-V4.1-Flash at 100000 on `workbuddy` (copilot.tencent.com)
341
+ from one report's error; China accounts took prompts up to 992,389 tokens
342
+ on it, so 0.2.8 lifted the cap (#561). A prompt WorkBuddy does find too
343
+ long ("prompt is too long: … > … maximum") is answered with its own 400,
344
+ passed on as it came, which magpie takes as the context overflowing.
345
+
346
+ A model's reply limit is the config's `maxOutputTokens`. The list used
347
+ before the config is read gives it too since 0.2.26, for the models a
348
+ config read from each site named (Deepseek-V4.1-Flash: 128000 on both).
349
+ Before, that list gave none, and magpie filled in models.dev's: 384000
350
+ for Deepseek-V4.1-Flash. A model it gives none for still gets models.dev's.
351
+
352
+ A chat goes gzipped (`Content-Encoding: gzip`), as WorkBuddy's own client
353
+ sends its model requests (`RequestBodyGzip` in both builds' product.json).
354
+ Claude's Messages route goes as it came, and so does anything that isn't a
355
+ chat completion: magpie's drawings (`/v2/images/generations`,
356
+ `/v2/images/edits`) go as plain JSON, which is all the images API reads.
357
+
358
+ A model's price is its `credits` ("x0.29") and the config's
359
+ `modelPromotions`. A discount for whole days (Step-5-Preview's 独家限免) is
360
+ the price now, with the price before it (`rateWas`). A price that holds only
361
+ some hours of the day (Hy4 preview, free 23:00–8:00) is given as its full
362
+ price, never as free: magpie keeps the list until it asks again, so a list
363
+ asked for at night would say "free" all day (#121).
364
+
365
+ ### Free models only
366
+
367
+ Each site (WorkBuddy, WorkBuddy AI) has a "Free models only" switch in its
368
+ provider settings in magpie, off by default (#430). When it is on:
369
+
370
+ - the list holds only the models the site serves at no cost now. A model free
371
+ only at night, or one with no price, counts as paid;
372
+ - a request for any other model is answered by the plugin with a 404
373
+ `model_not_found` and never sent, so no credits are spent. magpie rests
374
+ only that model and tries the next provider;
375
+ - if the price list can't be read, nothing is sent (503), since whether the
376
+ model is free is unknown. An API key WorkBuddy lists no prices for lists
377
+ no models.
378
+
379
+ The price list is read again at most once a minute for requests.
380
+
381
+ The switch gives its label and description in magpie's other languages
382
+ (`labels`, `descriptions`: Chinese, Traditional Chinese, Japanese, German),
383
+ and says `filtersModels`, so while it is on magpie says under the models
384
+ that the list is filtered (#590). Both are magpie's own fields; an older
385
+ magpie shows the English words and no note.
386
+
387
+ ### Hide DeepSeek Harness's name
388
+
389
+ Since 0.2.23 each site also has a "Hide DeepSeek Harness's name" switch, on
390
+ by default, and on in OpenCode, which has no switches. A user reported a
391
+ WorkBuddy account banned after use from DeepSeek Harness, with a reply saying
392
+ its built-in prompt is recognised. With the switch on, the harness's name is
393
+ taken out of the system prompt and the tools' descriptions: "You are an AI
394
+ agent powered by DeepSeek Harness." becomes "You are an AI agent.", and the
395
+ runtime lines naming its checkout and Web GUI say "agent implementation
396
+ checkout" and "Web GUI", wherever they are. Since 0.2.25 the user's and the
397
+ assistant's own words go as written (a path such as `/root/DSH/Work/` was
398
+ sent as `/root/the agent harness/Work/` before), and so does the name in a
399
+ path or a file name anywhere. Tools' results, commands and names such as
400
+ `DSH_HOME` or `~/.dsh` go as they were.
401
+ Whether this keeps an account from being banned is not known.
402
+
403
+ ## Credits in magpie
404
+
405
+ magpie's usage card shows the account's credits from the resource summary.
406
+ It also says when the soonest credits left run out (`runsOutAt`, and how
407
+ many: `runsOut`), from the paid and free package lists WorkBuddy's own
408
+ client reads. The daily Free Plan slice isn't counted: it ends at the same
409
+ midnight on every account. magpie's smart routing spends the account whose
410
+ credits run out first.
411
+
412
+ The plan's own credits and the rest are two windows. "Credits" is the
413
+ plan's base credits: what the subscription grants each cycle (Pro monthly
414
+ or yearly, youth, advanced, flagship, the Pro trials, the free plan's
415
+ monthly base, or the subscription the summary names), with the plan's
416
+ cycle, so its pace line is the month's. "Extra credits" is every other
417
+ kind WorkBuddy's own usage panel lists: the plan's bonus, top-ups (bought
418
+ credit packs) and platform rewards (gifted and activity credits,
419
+ 赠送积分). The summary's CreditGroups say which is which (plan_base
420
+ against plan_bonus, addon and benefit); a summary without them is split
421
+ by package code as WorkBuddy's client does. Neither stops the account,
422
+ since WorkBuddy serves it while any credits are left: both are set aside,
423
+ and a third window, "Total credits", the two together, stops it. It has
424
+ the plan's cycle and the soonest lapse of the two, so every account reads
425
+ the same, its plan's credits spent or not (ferock on Discord; before
426
+ 0.2.24 the extra window stood in for the account only once the plan's
427
+ were spent). Extra credits only the detail lists carry (a China-site free
428
+ account's summary can list the plan's base alone) are their own "Extra
429
+ credits" window, with a "Total credits" by the same rule. A summary with
430
+ only one kind keeps the one "Credits" window (akic404 on Discord; since
431
+ 0.2.16 the plan's bonus is extra too, Jiabubu on Discord).
432
+
433
+ An enterprise (team) account's resource summary lists no packages. Its
434
+ credits are read from the enterprise meter
435
+ (`/billing/meter/get-enterprise-user-usage`), the one WorkBuddy's own usage
436
+ page reads: the cycle's credits used of its limit, and when the cycle
437
+ resets (magpie #1904).
438
+
439
+ ## The free model's daily window (both builds)
440
+
441
+ The credits above are not the only limit. `deepseek-v4.1-flash` is served at
442
+ `x0.00` and costs the plan nothing, yet WorkBuddy AI refuses it long before
443
+ 160 credits are touched:
444
+
445
+ ```
446
+ 429 usage exceeds frequency limit, but don't worry, your usage will reset at
447
+ 2026-10-20 19:47:41 UTC+8, alternatively, you can switch to the other models
448
+ to continue using it.
449
+ ```
450
+
451
+ That is a token allowance of its own — per account, per 24 hours, about 1e8
452
+ tokens, counted as prompt + cache-read + completion. Nothing the vendor
453
+ answers with reports it, so the plugin rebuilds the current window from
454
+ magpie's `usage.jsonl` and gives it to the card as **Free model tokens**
455
+ beside **Credits**. `quota alert` and `magpie quota` show it too; before,
456
+ the card read 0% on an account that was already refused.
457
+
458
+ What is measured, and what is easy to read wrongly:
459
+
460
+ - **`cache_read` counts.** Prompt and completion alone are 20× smaller and
461
+ never approach the cap, so a window read that way looks empty while full.
462
+ - **The window is fixed, not sliding.** It runs 24 hours from the first
463
+ request answered after the previous window ended, not from the reset
464
+ instant; a gap between the two means the new window starts later.
465
+ - **`deepseek-v4.1-flash-sg` shares the window.** It is the paid id of the
466
+ same model (`ModelRateLimitCap` in the product config), not a second
467
+ allowance — switching to it continues the same window, at `x0.03`.
468
+ - **1e8 is an estimate within 0.2%.** The largest value seen to still be
469
+ answered is 100,183,315, and the next request is refused, so it cannot be
470
+ probed higher.
471
+ - **A refusal is exact, and the sum is not.** The ledger is this machine's
472
+ only: one window was refused at 92,792,962 because the rest of that
473
+ account's spending happened on another machine, which read as 93%. So a
474
+ 429 whose named reset is still ahead makes the window full — `used: 100`,
475
+ `resetsAt` the reset the vendor named — whatever the rows add up to. The
476
+ sum carries the window only until the first refusal.
477
+ - **A refusal hidden by routing still counts.** A group that moves to
478
+ another provider after the 429 writes only the 200 that answered, so the
479
+ failed WorkBuddy attempt is read from `routing/YYYY-MM-DD.jsonl` (or its
480
+ `.gz`, and a busy day's numbered `YYYY-MM-DD.N.jsonl` files) as well: its
481
+ vendor words — or the gateway rest's `until` and `key`, which names the
482
+ account and model — pin the window the same way. Three days of traces are
483
+ read a line at a time, never held whole, and what they held is kept until
484
+ a trace itself changes; an append to `usage.jsonl` does not decompress
485
+ them again, and an append to today's plain file is read from where the
486
+ last read stopped.
487
+ - **The sum is shown, not routed on.** Until the vendor refuses, the card is
488
+ set aside (`aside: true`): magpie draws it beside the account and never
489
+ counts it as the account's allowance, so an estimate near its cap does not
490
+ stop the model. The refusal's card does (`refused: true`), and magpie's
491
+ gateway rests this model alone on this account until the reset the
492
+ refusal names. Before 0.2.14 the sum stopped the model too, and a paid
493
+ China account read 99% of a cap it had never been refused at, with 2,457
494
+ credits left (plugins#641).
495
+ - **The card names both ids**, `deepseek-v4.1-flash` and
496
+ `deepseek-v4.1-flash-sg`: magpie matches a window's models by exact id
497
+ (only an `@size` suffix folds into the bare id), so one alone would leave
498
+ the other unrestricted.
499
+ - **The ledger is read in magpie's own folder** (`appdir.Config()`: the
500
+ portable data folder, `$XDG_CONFIG_HOME/magpie` when that is set (an
501
+ absolute path, as `appdir.rooted` has it), or `~/.config/magpie`), from its
502
+ end backwards — a heavy ledger runs to hundreds of MB.
503
+ - The window is a chain, so where it now began depends on every window
504
+ before it: read a slice of the ledger that starts mid-chain and every
505
+ window after it is shifted (4% on an account two hours from its cap, or
506
+ 100% on one still served). The read therefore goes back until it reaches
507
+ an edge this account's own rows spell out — a refusal whose reset can be
508
+ read, or a gap of a day between two of its answered rows — plus a day
509
+ below that, and with neither it reads to the file's start, where there is
510
+ no earlier window to be shifted by.
511
+ - Nothing bounds that by age, so two things keep a heavy ledger cheap: a
512
+ line's time is read before the line is decoded, so a line under the edge
513
+ (of any provider or account) ends the read at once; and a read past 24h
514
+ with no answered free-model row of this account stops, since the window
515
+ has lapsed and nothing would be reported. Both bounds leave out a line
516
+ a client reported (`"source":"reported"`, #1874): magpie appends those
517
+ dated where the client's call happened, so a backfilled row says nothing
518
+ about where the file has got to.
519
+ - `providerAccount` is the account's label. Two accounts sharing a label
520
+ get its slot added (`pluginLabels`), the label no longer matches what
521
+ their rows were written under, and the card reports no free window.
522
+ - **The offset comes from the refusal's words** (`UTC+8`, `GMT-5`,
523
+ `UTC+05:30`). A reset whose offset cannot be read is no edge at all,
524
+ rather than +08:00 guessed.
525
+
526
+ A window that has lapsed reports nothing rather than 0%: nothing is
527
+ exhausted, and the next request opens a fresh one.
528
+
529
+ ### The China build's windows (measured, shown as estimates)
530
+
531
+ The China build (`copilot.tencent.com`) carries the same kind of window,
532
+ measured one model at a time. `deepseek-v4.1-flash`: two Free-plan accounts
533
+ refused on 2026-11-02 at 200,389,043 and 200,485,923 tokens, so its cap is
534
+ about **2e8** — and its refusals name the reset in Chinese
535
+ (`将在 … UTC+8 重置`), which reads as an edge the same way.
536
+
537
+ Unlike the AI build's, the China model is **charged in credits** (`x0.11`)
538
+ — the token window and the credits meter are two limits on one model — so
539
+ the card is not a "free model" card. It is named after its model and says
540
+ its cap is an estimate: **`deepseek-v4.1-flash tokens (est.)`**, with
541
+ `~200M` in its text (`151.5M / ~200M`). The estimate is this machine's ledger
542
+ against a cap measured on two accounts; the vendor reports neither, and the
543
+ first refusal of a window pins the card full at the reset the vendor names.
544
+
545
+ The measured windows live in one table (`CN_ESTIMATED_WINDOWS`), one entry
546
+ per model. Only measured models have a card — a guessed cap would read wrong
547
+ every day. Add an entry when another model's window is measured; remove one
548
+ when the vendor stops applying it. Because the card is set aside (shown, not
549
+ routed on), a stale cap costs a wrong percentage, never a wrongly rested
550
+ model: the refusal is what stops a model, on both builds.
551
+
552
+ ## When free models work but a credit model does not
553
+
554
+ Check the failing account and model separately before concluding that the
555
+ wallet is empty:
556
+
557
+ - Use the exact API id from the account's model list. For example,
558
+ `glm-5.3-flash` is the id; `GLM-5.3-Flash` is its display name. A route
559
+ copied from another provider need not be a valid WorkBuddy model id.
560
+ - The WorkBuddy 5.6+ encrypted-desktop message means this sign-in cannot
561
+ be read, not that the account has zero credits. Use **Account (browser)**
562
+ for the same build/region. Keep the old entry until the new identity and
563
+ model list are confirmed. The desktop file is not decrypted or changed.
564
+ - An account restricted by WorkBuddy is a different failure. Code 11140
565
+ with its unusual-activity message calls for **Submit feedback** in
566
+ WorkBuddy; signing in repeatedly or changing the model does not lift it.
567
+ See [magpie#1849](https://github.com/yetone/magpie/issues/1849).
568
+ - Inspect each attempted provider/account in magpie's routing details.
569
+ A ZCode trial quota failure, another provider's insufficient credits, or
570
+ one account's restriction is not the balance of every WorkBuddy account.
571
+
572
+ A model response confirms that the selected account can answer. It does
573
+ not, without a matching vendor usage record, prove how many credits that
574
+ request deducted. A usage-read error means the balance is unknown.
575
+
576
+ The encrypted-desktop result can be reproduced without an account using
577
+ `packages/workbuddy/usage.test.mjs` in an isolated temporary HOME (and
578
+ USERPROFILE on Windows). It covers sign-in, usage and chat against a
579
+ synthetic sealed desktop file, and checks that the file stays unchanged.
580
+ A successful browser authorization alone is not a migration: compare the
581
+ returned identity with the intended desktop account before replacing its
582
+ entry. An already signed-in browser can simply renew another saved account.
583
+
584
+
585
+ ## Not here
586
+
587
+ magpie's built-in WorkBuddy does more than this package: several accounts
588
+ under one provider.
589
+
590
+ OpenCode's plugin API has no place for these.
591
+
592
+ Credit multipliers accept the international catalog's `x0.34 credits` text as well as `x0.34`. An empty credits value (for example Auto) stays unknown, never free.
593
+
594
+ ## Daily check-in
595
+
596
+ The account's daily credits are claimed through the billing meter. magpie
597
+ can run it once a day per account when its WorkBuddy check-in switch is on;
598
+ Settings → Usage → Plugins has that switch and a *Check in now* button.
599
+ The activity status is read first: inactive is `inactive`, a day already
600
+ checked in is `done`, and only an active unchecked day is claimed. A claim
601
+ that WorkBuddy answers 1001, 1002 or 1003 is `done`, `ineligible` or
602
+ `inactive`. A claim turned away 401 while the account's credits still read
603
+ is `ineligible`: that check-in takes WorkBuddy's own app. A transient
604
+ billing failure is retried twice before the card shows the failure.
605
+ Only WorkBuddy (China) checks in: the AI build has no claim endpoint, and
606
+ its plugin carries no check-in hook.
607
+ A request that gets no answer at all leaves the hook as a thrown error, so
608
+ magpie retries it on its 1-minute offline backoff rather than the 30-minute
609
+ one it gives a failed answer (#149).
610
+
611
+ An `inactive` answer is kept for the whole Beijing day: the plugin host
612
+ gives it no recheck, and a manual refresh reads the kept one (tracked in
613
+ [yetone/magpie#2696](https://github.com/yetone/magpie/issues/2696)).