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

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,628 @@
1
- # Temporary Holding Version
1
+ # @jianmu-plugins/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
+ Since 0.2.35 a WorkBuddy AI chat is also reported on `POST /v2/report`, as
209
+ WorkBuddy AI 5.9.4's client reports one (#691): once the reply has been
210
+ read to its end, `chat_message_send`, then `chat_message_response` and
211
+ `chat_message_status` (with `chat_request_send` first when the user's own
212
+ message opened the step, and `chat_request_response` last when the step
213
+ ends the turn), then `agent_task_completed` and `chat_response_complete`
214
+ for a step that ends it. They carry the chat's ids, model, token counts and
215
+ finish reason, and the client's common fields: the account's id and name,
216
+ WorkBuddy's version, this computer's OS, CPU and memory, and a machine id
217
+ that is a hash of the host's and user's names. Only the user's own chats
218
+ are reported, never a message of the plugin's own; a reply cut off, a
219
+ refusal, a key account and the China build send none, and a report that
220
+ fails is dropped. Whether the daily credit reads these reports is not
221
+ known yet.
222
+
223
+ A chat that doesn't open with a system message is given WorkBuddy's
224
+ default one, as the app does.
225
+
226
+ WorkBuddy refuses some agents' identity lines as an "unapproved channel"
227
+ (11128), so those lines are reworded before a chat goes out. Since 0.1.27
228
+ (#279) that includes DeepSeek Harness's opening line. Since 0.2.3 a refusal
229
+ of words not reworded yet is answered first by saying the same line with one
230
+ more comma — a vendor matches such a line whole and exactly, so the comma
231
+ passes it while the line still names the harness (measured 2026-10-30; a word
232
+ added after the product name did not pass, the comma did). The comma is set in
233
+ the system and assistant messages only — the two WorkBuddy reads — so the
234
+ user's own words and tools' results go out as they were sent. A system prompt
235
+ whose comma passed is remembered while the plugin is loaded, as a moved one
236
+ is, and its next chats go with the comma already in before the first send:
237
+ otherwise every turn, and every step of a tool loop, would pay the refusal
238
+ once. Only a chat refused still is sent once more, since 0.1.29, with the
239
+ system prompt moved into the first user message (inside `<instructions>` tags)
240
+ and WorkBuddy's default system prompt in its place: WorkBuddy checks only the
241
+ system and assistant messages, and the line it matched is then in neither. A system message later
242
+ in the chat becomes a user message where it stands. The plugin remembers each
243
+ refused system prompt while it is loaded, so that agent's next chats go moved
244
+ at once. The move can't reach an assistant message, so words the model quotes
245
+ back into one keep that chat refused until they are in the list reworded in
246
+ every message (since 0.1.30, the "Web GUI whose URL the runtime context names"
247
+ line, #291); otherwise only a new chat clears it. A refusal that stands after
248
+ the move ends in a hint that names no one client (since 0.1.28): WorkBuddy
249
+ refused words in this client's prompt; use it from Hermes, OpenCode or Pi, or
250
+ add another provider to the group. Since 0.2.3 that hint is preceded by the
251
+ address of [REFUSED.md](REFUSED.md), which says what the check reads, how a
252
+ line is reworded to pass it, and how to turn such a line off in an agent that
253
+ has a switch for it — so the error carries its own fix, for the person who
254
+ reads it or the agent they paste it to. Neither refusal rests the account.
255
+
256
+ The loader also translates OpenAI-compatible request spellings WorkBuddy
257
+ doesn't take: `max_completion_tokens` becomes `max_tokens`, `developer`
258
+ messages become `system`, an object `tool_choice` becomes WorkBuddy's
259
+ string form, and an earlier assistant turn's `reasoning_content` (or
260
+ `reasoning_details` text) goes as `reasoning`, the field WorkBuddy's own
261
+ client sends. WorkBuddy drops `reasoning_content`, so a client such as Grok
262
+ Build that sends it lost its earlier thinking; nothing is folded into the
263
+ message's content.
264
+
265
+ A chat's tools are given shapes WorkBuddy's models take. Without them
266
+ WorkBuddy AI answers 400 "Invalid request parameters" (11133), DeepSeek's
267
+ models to each shape below and Kimi's, GPT's, Gemini's and GLM's to some:
268
+ - a tool's parameters with no `type`, empty, or a union (`anyOf`, `oneOf`,
269
+ `allOf`) at the root are an object, the union's fields merged;
270
+ - a `pattern`'s `\0` is `\u0000`, which matches the same;
271
+ - REA's exact `^[^\uD800-\uDFFF]*$` surrogate guard is omitted from the
272
+ outbound schema: WorkBuddy AI's DeepSeek rejects it with "invalid function
273
+ call parameters". Other path constraints and REA's own validation stay;
274
+ - a tuple's `items` (a list) is one schema any of them fits;
275
+ - an `enum` with no `type` takes its values' type (or that and `"null"`),
276
+ and an `enum` of several types is an `anyOf` of one typed `enum` for
277
+ each, at any depth; an empty `enum` is left out (Kimi and DeepSeek, an
278
+ MCP server's tools, #122);
279
+ - `true` and `false` where a schema goes are `{}` and `{"not": {}}`
280
+ (`additionalProperties` is left); a `required` that isn't a list, and a
281
+ `type` JSON Schema doesn't name, are left out, and `"String"` is
282
+ `"string"`;
283
+ - a tool's name with a character other than letters, digits, `_` and `-`
284
+ (`.`, `:`, `/`, a space, CJK) is sent with `_` there, and the model's
285
+ calls come back under the tool's own name.
286
+
287
+ WorkBuddy AI's `gemini-3.8-flash` answers 400 "the conversation must end
288
+ with a user message" (11153) to a chat whose tool results are followed by
289
+ the user's message, as magpie sends Claude Code's reminders, words typed
290
+ mid-task and a tool's images. Such a chat goes again with an empty
291
+ assistant message between the results and the user's message, which it
292
+ serves; a model that refused it once gets it that way from then on, until
293
+ the plugin restarts. A chat ending with the assistant's message (a prefill)
294
+ is refused as before.
295
+
296
+ WorkBuddy's safety filter can refuse a reply it has begun:
297
+ `deepseek-v4.1-flash` reasoned, said "Sorry, I can't respond to this
298
+ question.", and ended with `finish_reason: "content_filter"` and no output
299
+ tokens, all under a 200 (#540). Since 0.2.4 that line is taken out of a
300
+ streamed chat ending `content_filter`, so the reply says nothing before the
301
+ filter's stop: magpie hands such a refusal to the group's next member
302
+ instead of passing it to the agent as an answer. Only text that is still
303
+ the filter's line is held, so any other reply's words go as they come; the
304
+ same words ending `stop`, or the filter cutting off a reply after other
305
+ words, go through as they came.
306
+ copilot.tencent.com sends the line with a newline on each side
307
+ (`"\nSorry, I can't respond to this question.\n"`); since 0.2.5 white
308
+ space around it no longer lets it through. It also puts `"tool_calls": []` on
309
+ every delta; since 0.2.6 only a list with a call in it lets the reply
310
+ through as it came.
311
+
312
+ ## Models
313
+
314
+ When you are signed in, the models are the ones WorkBuddy's product config
315
+ gives its CLI agent (`GET /v3/config`), with their context, image input and
316
+ reasoning levels. Until then, or if WorkBuddy doesn't answer, the list below
317
+ is used. Since 0.2.9 its models take images, as the config says of every
318
+ model, except WorkBuddy AI's GLM models, whose images WorkBuddy AI drops
319
+ (#572).
320
+
321
+ `workbuddy`:
322
+ - Auto
323
+ - Hy4 preview, Hy3, Hy3-X
324
+ - Deepseek-V4.1-Flash, Deepseek-V4-Pro
325
+ - GLM-5.3, GLM-5.3-Flash, GLM-5.2, GLM-5.1, GLM-5v-Turbo
326
+ - MiniMax-M3
327
+ - Kimi-K3, Kimi-K2.7-Code, Kimi-K2.6
328
+
329
+ `workbuddy-ai`:
330
+ - Default, Fast, Balanced, Primary, Deep
331
+ - GPT-5.5, GPT-5.4, GPT-5.3-Codex
332
+ - Gemini-3.1-Pro, Gemini-3.5-Flash
333
+ - GLM-5.3, GLM-5.2
334
+ - Hy3
335
+ - Kimi-K3, Kimi-K2.6
336
+ - MiniMax-M3
337
+
338
+ A model's reasoning levels are its variants (`reasoningEffort`). A chat
339
+ that names no level goes at the model's own default from the config
340
+ (`reasoning.defaultEffort`, "high" for DeepSeek-V4.1-Flash), as WorkBuddy's
341
+ client sends it: WorkBuddy doesn't think when a chat names none, so
342
+ OpenCode's default variant got answers without thinking. An effort the
343
+ client names, `none` too, goes as it came. A chat whose `max_tokens` is
344
+ 1024 or less gets no default (since 0.2.15, #643): a title or a
345
+ classification asked at 64 tokens spent all 64 on reasoning and answered
346
+ nothing. Anthropic's API takes no thinking under a 1024-token budget, so
347
+ no client means to think in one that small.
348
+
349
+ One value differs from the config, measured with real requests:
350
+ DeepSeek-V4.1-Flash (and its paid `-sg` id) lists `none`, though the
351
+ config says it only reasons: WorkBuddy answers `reasoning_effort: "none"`
352
+ on it with no thinking at all (since 0.2.7, #563).
353
+
354
+ A model's context is the config's `maxInputTokens` on both sites. 0.2.7
355
+ capped DeepSeek-V4.1-Flash at 100000 on `workbuddy` (copilot.tencent.com)
356
+ from one report's error; China accounts took prompts up to 992,389 tokens
357
+ on it, so 0.2.8 lifted the cap (#561). A prompt WorkBuddy does find too
358
+ long ("prompt is too long: … > … maximum") is answered with its own 400,
359
+ passed on as it came, which magpie takes as the context overflowing.
360
+
361
+ A model's reply limit is the config's `maxOutputTokens`. The list used
362
+ before the config is read gives it too since 0.2.26, for the models a
363
+ config read from each site named (Deepseek-V4.1-Flash: 128000 on both).
364
+ Before, that list gave none, and magpie filled in models.dev's: 384000
365
+ for Deepseek-V4.1-Flash. A model it gives none for still gets models.dev's.
366
+
367
+ A chat goes gzipped (`Content-Encoding: gzip`), as WorkBuddy's own client
368
+ sends its model requests (`RequestBodyGzip` in both builds' product.json).
369
+ Claude's Messages route goes as it came, and so does anything that isn't a
370
+ chat completion: magpie's drawings (`/v2/images/generations`,
371
+ `/v2/images/edits`) go as plain JSON, which is all the images API reads.
372
+
373
+ A model's price is its `credits` ("x0.29") and the config's
374
+ `modelPromotions`. A discount for whole days (Step-5-Preview's 独家限免) is
375
+ the price now, with the price before it (`rateWas`). A price that holds only
376
+ some hours of the day (Hy4 preview, free 23:00–8:00) is given as its full
377
+ price, never as free: magpie keeps the list until it asks again, so a list
378
+ asked for at night would say "free" all day (#121).
379
+
380
+ ### Free models only
381
+
382
+ Each site (WorkBuddy, WorkBuddy AI) has a "Free models only" switch in its
383
+ provider settings in magpie, off by default (#430). When it is on:
384
+
385
+ - the list holds only the models the site serves at no cost now. A model free
386
+ only at night, or one with no price, counts as paid;
387
+ - a request for any other model is answered by the plugin with a 404
388
+ `model_not_found` and never sent, so no credits are spent. magpie rests
389
+ only that model and tries the next provider;
390
+ - if the price list can't be read, nothing is sent (503), since whether the
391
+ model is free is unknown. An API key WorkBuddy lists no prices for lists
392
+ no models.
393
+
394
+ The price list is read again at most once a minute for requests.
395
+
396
+ The switch gives its label and description in magpie's other languages
397
+ (`labels`, `descriptions`: Chinese, Traditional Chinese, Japanese, German),
398
+ and says `filtersModels`, so while it is on magpie says under the models
399
+ that the list is filtered (#590). Both are magpie's own fields; an older
400
+ magpie shows the English words and no note.
401
+
402
+ ### Hide DeepSeek Harness's name
403
+
404
+ Since 0.2.23 each site also has a "Hide DeepSeek Harness's name" switch, on
405
+ by default, and on in OpenCode, which has no switches. A user reported a
406
+ WorkBuddy account banned after use from DeepSeek Harness, with a reply saying
407
+ its built-in prompt is recognised. With the switch on, the harness's name is
408
+ taken out of the system prompt and the tools' descriptions: "You are an AI
409
+ agent powered by DeepSeek Harness." becomes "You are an AI agent.", and the
410
+ runtime lines naming its checkout and Web GUI say "agent implementation
411
+ checkout" and "Web GUI", wherever they are. Since 0.2.25 the user's and the
412
+ assistant's own words go as written (a path such as `/root/DSH/Work/` was
413
+ sent as `/root/the agent harness/Work/` before), and so does the name in a
414
+ path or a file name anywhere. Tools' results, commands and names such as
415
+ `DSH_HOME` or `~/.dsh` go as they were.
416
+ Whether this keeps an account from being banned is not known.
417
+
418
+ ## Credits in magpie
419
+
420
+ magpie's usage card shows the account's credits from the resource summary.
421
+ It also says when the soonest credits left run out (`runsOutAt`, and how
422
+ many: `runsOut`), from the paid and free package lists WorkBuddy's own
423
+ client reads. The daily Free Plan slice isn't counted: it ends at the same
424
+ midnight on every account. magpie's smart routing spends the account whose
425
+ credits run out first.
426
+
427
+ The plan's own credits and the rest are two windows. "Credits" is the
428
+ plan's base credits: what the subscription grants each cycle (Pro monthly
429
+ or yearly, youth, advanced, flagship, the Pro trials, the free plan's
430
+ monthly base, or the subscription the summary names), with the plan's
431
+ cycle, so its pace line is the month's. "Extra credits" is every other
432
+ kind WorkBuddy's own usage panel lists: the plan's bonus, top-ups (bought
433
+ credit packs) and platform rewards (gifted and activity credits,
434
+ 赠送积分). The summary's CreditGroups say which is which (plan_base
435
+ against plan_bonus, addon and benefit); a summary without them is split
436
+ by package code as WorkBuddy's client does. Neither stops the account,
437
+ since WorkBuddy serves it while any credits are left: both are set aside,
438
+ and a third window, "Total credits", the two together, stops it. It has
439
+ the plan's cycle and the soonest lapse of the two, so every account reads
440
+ the same, its plan's credits spent or not (ferock on Discord; before
441
+ 0.2.24 the extra window stood in for the account only once the plan's
442
+ were spent). Extra credits only the detail lists carry (a China-site free
443
+ account's summary can list the plan's base alone) are their own "Extra
444
+ credits" window, with a "Total credits" by the same rule. A summary with
445
+ only one kind keeps the one "Credits" window (akic404 on Discord; since
446
+ 0.2.16 the plan's bonus is extra too, Jiabubu on Discord).
447
+
448
+ An enterprise (team) account's resource summary lists no packages. Its
449
+ credits are read from the enterprise meter
450
+ (`/billing/meter/get-enterprise-user-usage`), the one WorkBuddy's own usage
451
+ page reads: the cycle's credits used of its limit, and when the cycle
452
+ resets (magpie #1904).
453
+
454
+ ## The free model's daily window (both builds)
455
+
456
+ The credits above are not the only limit. `deepseek-v4.1-flash` is served at
457
+ `x0.00` and costs the plan nothing, yet WorkBuddy AI refuses it long before
458
+ 160 credits are touched:
459
+
460
+ ```
461
+ 429 usage exceeds frequency limit, but don't worry, your usage will reset at
462
+ 2026-10-20 19:47:41 UTC+8, alternatively, you can switch to the other models
463
+ to continue using it.
464
+ ```
465
+
466
+ That is a token allowance of its own — per account, per 24 hours, about 1e8
467
+ tokens, counted as prompt + cache-read + completion. Nothing the vendor
468
+ answers with reports it, so the plugin rebuilds the current window from
469
+ magpie's `usage.jsonl` and gives it to the card as **Free model tokens**
470
+ beside **Credits**. `quota alert` and `magpie quota` show it too; before,
471
+ the card read 0% on an account that was already refused.
472
+
473
+ What is measured, and what is easy to read wrongly:
474
+
475
+ - **`cache_read` counts.** Prompt and completion alone are 20× smaller and
476
+ never approach the cap, so a window read that way looks empty while full.
477
+ - **The window is fixed, not sliding.** It runs 24 hours from the first
478
+ request answered after the previous window ended, not from the reset
479
+ instant; a gap between the two means the new window starts later.
480
+ - **`deepseek-v4.1-flash-sg` shares the window.** It is the paid id of the
481
+ same model (`ModelRateLimitCap` in the product config), not a second
482
+ allowance — switching to it continues the same window, at `x0.03`.
483
+ - **1e8 is an estimate within 0.2%.** The largest value seen to still be
484
+ answered is 100,183,315, and the next request is refused, so it cannot be
485
+ probed higher.
486
+ - **A refusal is exact, and the sum is not.** The ledger is this machine's
487
+ only: one window was refused at 92,792,962 because the rest of that
488
+ account's spending happened on another machine, which read as 93%. So a
489
+ 429 whose named reset is still ahead makes the window full — `used: 100`,
490
+ `resetsAt` the reset the vendor named — whatever the rows add up to. The
491
+ sum carries the window only until the first refusal.
492
+ - **A refusal hidden by routing still counts.** A group that moves to
493
+ another provider after the 429 writes only the 200 that answered, so the
494
+ failed WorkBuddy attempt is read from `routing/YYYY-MM-DD.jsonl` (or its
495
+ `.gz`, and a busy day's numbered `YYYY-MM-DD.N.jsonl` files) as well: its
496
+ vendor words — or the gateway rest's `until` and `key`, which names the
497
+ account and model — pin the window the same way. Three days of traces are
498
+ read a line at a time, never held whole, and what they held is kept until
499
+ a trace itself changes; an append to `usage.jsonl` does not decompress
500
+ them again, and an append to today's plain file is read from where the
501
+ last read stopped.
502
+ - **The sum is shown, not routed on.** Until the vendor refuses, the card is
503
+ set aside (`aside: true`): magpie draws it beside the account and never
504
+ counts it as the account's allowance, so an estimate near its cap does not
505
+ stop the model. The refusal's card does (`refused: true`), and magpie's
506
+ gateway rests this model alone on this account until the reset the
507
+ refusal names. Before 0.2.14 the sum stopped the model too, and a paid
508
+ China account read 99% of a cap it had never been refused at, with 2,457
509
+ credits left (plugins#641).
510
+ - **The card names both ids**, `deepseek-v4.1-flash` and
511
+ `deepseek-v4.1-flash-sg`: magpie matches a window's models by exact id
512
+ (only an `@size` suffix folds into the bare id), so one alone would leave
513
+ the other unrestricted.
514
+ - **The ledger is read in magpie's own folder** (`appdir.Config()`: the
515
+ portable data folder, `$XDG_CONFIG_HOME/magpie` when that is set (an
516
+ absolute path, as `appdir.rooted` has it), or `~/.config/magpie`), from its
517
+ end backwards — a heavy ledger runs to hundreds of MB.
518
+ - The window is a chain, so where it now began depends on every window
519
+ before it: read a slice of the ledger that starts mid-chain and every
520
+ window after it is shifted (4% on an account two hours from its cap, or
521
+ 100% on one still served). The read therefore goes back until it reaches
522
+ an edge this account's own rows spell out — a refusal whose reset can be
523
+ read, or a gap of a day between two of its answered rows — plus a day
524
+ below that, and with neither it reads to the file's start, where there is
525
+ no earlier window to be shifted by.
526
+ - Nothing bounds that by age, so two things keep a heavy ledger cheap: a
527
+ line's time is read before the line is decoded, so a line under the edge
528
+ (of any provider or account) ends the read at once; and a read past 24h
529
+ with no answered free-model row of this account stops, since the window
530
+ has lapsed and nothing would be reported. Both bounds leave out a line
531
+ a client reported (`"source":"reported"`, #1874): magpie appends those
532
+ dated where the client's call happened, so a backfilled row says nothing
533
+ about where the file has got to.
534
+ - `providerAccount` is the account's label. Two accounts sharing a label
535
+ get its slot added (`pluginLabels`), the label no longer matches what
536
+ their rows were written under, and the card reports no free window.
537
+ - **The offset comes from the refusal's words** (`UTC+8`, `GMT-5`,
538
+ `UTC+05:30`). A reset whose offset cannot be read is no edge at all,
539
+ rather than +08:00 guessed.
540
+
541
+ A window that has lapsed reports nothing rather than 0%: nothing is
542
+ exhausted, and the next request opens a fresh one.
543
+
544
+ ### The China build's windows (measured, shown as estimates)
545
+
546
+ The China build (`copilot.tencent.com`) carries the same kind of window,
547
+ measured one model at a time. `deepseek-v4.1-flash`: two Free-plan accounts
548
+ refused on 2026-11-02 at 200,389,043 and 200,485,923 tokens, so its cap is
549
+ about **2e8** — and its refusals name the reset in Chinese
550
+ (`将在 … UTC+8 重置`), which reads as an edge the same way.
551
+
552
+ Unlike the AI build's, the China model is **charged in credits** (`x0.11`)
553
+ — the token window and the credits meter are two limits on one model — so
554
+ the card is not a "free model" card. It is named after its model and says
555
+ its cap is an estimate: **`deepseek-v4.1-flash tokens (est.)`**, with
556
+ `~200M` in its text (`151.5M / ~200M`). The estimate is this machine's ledger
557
+ against a cap measured on two accounts; the vendor reports neither, and the
558
+ first refusal of a window pins the card full at the reset the vendor names.
559
+
560
+ The measured windows live in one table (`CN_ESTIMATED_WINDOWS`), one entry
561
+ per model. Only measured models have a card — a guessed cap would read wrong
562
+ every day. Add an entry when another model's window is measured; remove one
563
+ when the vendor stops applying it. Because the card is set aside (shown, not
564
+ routed on), a stale cap costs a wrong percentage, never a wrongly rested
565
+ model: the refusal is what stops a model, on both builds.
566
+
567
+ ## When free models work but a credit model does not
568
+
569
+ Check the failing account and model separately before concluding that the
570
+ wallet is empty:
571
+
572
+ - Use the exact API id from the account's model list. For example,
573
+ `glm-5.3-flash` is the id; `GLM-5.3-Flash` is its display name. A route
574
+ copied from another provider need not be a valid WorkBuddy model id.
575
+ - The WorkBuddy 5.6+ encrypted-desktop message means this sign-in cannot
576
+ be read, not that the account has zero credits. Use **Account (browser)**
577
+ for the same build/region. Keep the old entry until the new identity and
578
+ model list are confirmed. The desktop file is not decrypted or changed.
579
+ - An account restricted by WorkBuddy is a different failure. Code 11140
580
+ with its unusual-activity message calls for **Submit feedback** in
581
+ WorkBuddy; signing in repeatedly or changing the model does not lift it.
582
+ See [magpie#1849](https://github.com/yetone/magpie/issues/1849).
583
+ - Inspect each attempted provider/account in magpie's routing details.
584
+ A ZCode trial quota failure, another provider's insufficient credits, or
585
+ one account's restriction is not the balance of every WorkBuddy account.
586
+
587
+ A model response confirms that the selected account can answer. It does
588
+ not, without a matching vendor usage record, prove how many credits that
589
+ request deducted. A usage-read error means the balance is unknown.
590
+
591
+ The encrypted-desktop result can be reproduced without an account using
592
+ `packages/workbuddy/usage.test.mjs` in an isolated temporary HOME (and
593
+ USERPROFILE on Windows). It covers sign-in, usage and chat against a
594
+ synthetic sealed desktop file, and checks that the file stays unchanged.
595
+ A successful browser authorization alone is not a migration: compare the
596
+ returned identity with the intended desktop account before replacing its
597
+ entry. An already signed-in browser can simply renew another saved account.
598
+
599
+
600
+ ## Not here
601
+
602
+ magpie's built-in WorkBuddy does more than this package: several accounts
603
+ under one provider.
604
+
605
+ OpenCode's plugin API has no place for these.
606
+
607
+ 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.
608
+
609
+ ## Daily check-in
610
+
611
+ The account's daily credits are claimed through the billing meter. magpie
612
+ can run it once a day per account when its WorkBuddy check-in switch is on;
613
+ Settings → Usage → Plugins has that switch and a *Check in now* button.
614
+ The activity status is read first: inactive is `inactive`, a day already
615
+ checked in is `done`, and only an active unchecked day is claimed. A claim
616
+ that WorkBuddy answers 1001, 1002 or 1003 is `done`, `ineligible` or
617
+ `inactive`. A claim turned away 401 while the account's credits still read
618
+ is `ineligible`: that check-in takes WorkBuddy's own app. A transient
619
+ billing failure is retried twice before the card shows the failure.
620
+ Only WorkBuddy (China) checks in: the AI build has no claim endpoint, and
621
+ its plugin carries no check-in hook.
622
+ A request that gets no answer at all leaves the hook as a thrown error, so
623
+ magpie retries it on its 1-minute offline backoff rather than the 30-minute
624
+ one it gives a failed answer (#149).
625
+
626
+ An `inactive` answer is kept for the whole Beijing day: the plugin host
627
+ gives it no recheck, and a manual refresh reads the kept one (tracked in
628
+ [yetone/magpie#2696](https://github.com/yetone/magpie/issues/2696)).