workbuddy2api 2.0.6__tar.gz → 2.0.8.dev1__tar.gz

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.
Files changed (35) hide show
  1. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/PKG-INFO +162 -28
  2. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/README.md +159 -27
  3. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/pyproject.toml +5 -3
  4. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/__main__.py +889 -409
  5. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/account_checkin.py +4 -0
  6. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/account_manager.py +947 -0
  7. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/account_store.py +4 -0
  8. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/admin.html +1883 -0
  9. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/admin_api.py +496 -0
  10. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/anthropic_adapter.py +5 -0
  11. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/backend_profile.py +4 -0
  12. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/billing_proxy.py +4 -0
  13. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/codebuddy_client_demo.py +116 -0
  14. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/process_diagnostics.py +445 -0
  15. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/protocol_response.py +132 -0
  16. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/responses_adapter.py +25 -3
  17. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/role_compat.py +55 -0
  18. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/tool_pairing.py +136 -0
  19. workbuddy2api-2.0.8.dev1/src/codebuddy_proxy/upstream_request.py +147 -0
  20. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/PKG-INFO +162 -28
  21. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/SOURCES.txt +11 -0
  22. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/requires.txt +2 -0
  23. workbuddy2api-2.0.6/src/codebuddy_proxy/backend_profile.py +0 -198
  24. workbuddy2api-2.0.6/src/codebuddy_proxy/codebuddy_client_demo.py +0 -533
  25. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/LICENSE +0 -0
  26. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/setup.cfg +0 -0
  27. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/desensitize.py +0 -0
  28. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/dsml_parser.py +0 -0
  29. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/models_config.domestic.json +0 -0
  30. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/models_config.global.json +0 -0
  31. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/projection_metadata.py +0 -0
  32. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/codebuddy_proxy/responses_projection.py +0 -0
  33. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/dependency_links.txt +0 -0
  34. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/entry_points.txt +0 -0
  35. {workbuddy2api-2.0.6 → workbuddy2api-2.0.8.dev1}/src/workbuddy2api.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: workbuddy2api
3
- Version: 2.0.6
3
+ Version: 2.0.8.dev1
4
4
  Summary: Local OpenAI/Responses/Anthropic compatible proxy for CodeBuddy
5
5
  Requires-Python: >=3.10
6
6
  Description-Content-Type: text/markdown
@@ -9,6 +9,8 @@ Requires-Dist: fastapi>=0.104.0
9
9
  Requires-Dist: uvicorn>=0.24.0
10
10
  Requires-Dist: httpx[socks]>=0.25.0
11
11
  Requires-Dist: requests>=2.31.0
12
+ Requires-Dist: buddy-agent-auth<0.2,>=0.1.0.dev1
13
+ Requires-Dist: buddy-agent-checkin[workbuddy]<0.2,>=0.1.1.dev2
12
14
  Provides-Extra: dev
13
15
  Requires-Dist: pytest>=7.4.0; extra == "dev"
14
16
  Dynamic: license-file
@@ -19,6 +21,8 @@ Dynamic: license-file
19
21
 
20
22
  > **中文版文档见 [README_zh.md](README_zh.md).**
21
23
 
24
+ For unexplained Windows process exits, use the [independent process monitor](docs/external-process-monitor.md) to collect uv/Python exit codes, lifecycle, memory, health, and available Windows events without restarting the proxy.
25
+
22
26
  ## ✨ Core Features
23
27
 
24
28
  - **Protocol conversion** - Supports three standard formats: OpenAI Chat Completions, Anthropic Messages API, and Responses
@@ -28,7 +32,9 @@ Dynamic: license-file
28
32
  - **DSML parsing** - Automatically detects and converts DeepSeek Markup Language (DSML) tool calls
29
33
  - **Streaming responses** - SSE streaming output, returning generated content in real time, with built-in 60-second timeout protection
30
34
  - **Domestic and international backends** - Uses domestic CodeBuddy by default and switches to the international CodeBuddy service with `--global`, with isolated sessions and model catalogs
31
- - **Multi-account management** - Supports isolation of multiple login states for easy switching between work/personal accounts
35
+ - **Multi-account management** - Link domestic and Global accounts, switch the active account, and remove non-active accounts from the local admin page
36
+ - **Model-level 429 handling** - Track cooldowns per account and model, with optional same-region failover
37
+ - **Daily check-in** - Check in manually or enable background checks for all linked accounts
32
38
 
33
39
  ---
34
40
 
@@ -64,12 +70,14 @@ uv sync
64
70
  uv run python -m codebuddy_proxy --desensitize
65
71
  ```
66
72
 
67
- On first use, when login is required:
73
+ On first use, start the proxy and open the local account manager:
68
74
 
69
75
  ```bash
70
- uv run python -m codebuddy_proxy --login --desensitize
76
+ uv run python -m codebuddy_proxy --desensitize
71
77
  ```
72
78
 
79
+ Then visit `http://127.0.0.1:8787/admin` and link a domestic or Global account.
80
+
73
81
  ## Quick Start
74
82
 
75
83
  ### 1. Start the proxy
@@ -78,8 +86,8 @@ uv run python -m codebuddy_proxy --login --desensitize
78
86
  # Use the latest version (recommended)
79
87
  uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
80
88
 
81
- # First use: log in and start
82
- uv run --with workbuddy2api python -m codebuddy_proxy --login --desensitize
89
+ # First use: start, then link an account at http://127.0.0.1:8787/admin
90
+ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
83
91
 
84
92
  # International service: first login and start
85
93
  uv run --with workbuddy2api python -m codebuddy_proxy --global --login --desensitize
@@ -95,12 +103,23 @@ Listens on `http://127.0.0.1:8787` by default.
95
103
  The proxy supports both CodeBuddy regions. Domestic mode remains the default,
96
104
  so existing startup commands continue to work unchanged.
97
105
 
98
- | Mode | Startup option | Upstream endpoint | Default session file |
99
- | --- | --- | --- | --- |
100
- | Domestic (default) | none | `https://copilot.tencent.com` | `~/.codebuddy-session.json` |
101
- | International | `--global` | `https://www.codebuddy.ai` | `~/.codebuddy-global-session.json` |
106
+ | Mode | Startup option | Upstream endpoint |
107
+ | --- | --- | --- |
108
+ | Domestic (default) | none | `https://copilot.tencent.com` |
109
+ | International | `--global` | `https://www.codebuddy.ai` |
110
+
111
+ Linked accounts are stored separately by region in `~/.workbuddy2api/accounts`.
112
+ Use `--accounts-dir DIR` to choose another local directory. With no explicit
113
+ selector, the proxy restores the saved active account. On the first migration,
114
+ matching legacy session files are imported once and kept; deleting an imported
115
+ account does not import it again. Explicit `--global` or `--endpoint` selects a
116
+ matching account, while `--session-file` can import that file again. If there is
117
+ no match, the proxy starts without an active account. `--login` uses a temporary
118
+ session file to add or refresh an account without replacing a legacy file.
102
119
 
103
- First login and daily startup for the international service:
120
+ The account manager can add accounts for either region while the proxy is
121
+ running. For a terminal-driven login, the existing `--login` option remains
122
+ available:
104
123
 
105
124
  ```bash
106
125
  # First login
@@ -116,16 +135,18 @@ If the package is installed as a command, the equivalent short form is
116
135
  `workbuddy2api --global --login`. When running from source, use
117
136
  `uv run python -m codebuddy_proxy --global --login`.
118
137
 
119
- `--global` changes only the upstream service. Codex CLI, Claude Code/CC Switch,
120
- OpenCode, and other clients continue to use the same local proxy URLs. The
121
- selected profile also controls the model catalog returned by `/v1/models`.
138
+ `--global` selects the Global backend and a matching account when one exists.
139
+ Codex CLI, Claude Code/CC Switch, OpenCode, and other clients continue to use
140
+ the same local proxy URLs. The selected profile also controls the model catalog
141
+ returned by `/v1/models`.
122
142
 
123
- Domestic and international sessions are intentionally isolated. An explicit
124
- `--session-file` takes precedence, but its saved backend and endpoint must match
125
- the current startup options. The proxy refuses mismatched credentials and does
126
- not modify the original file.
143
+ Domestic and international accounts remain isolated. An explicit
144
+ `--session-file` is imported only when its saved backend and endpoint match the
145
+ current startup options. The proxy refuses mismatched credentials and does not
146
+ modify the original file.
127
147
 
128
- For a custom international endpoint, always use a dedicated session file:
148
+ For a custom international endpoint, use a dedicated session file when
149
+ importing or creating a login from the command line:
129
150
 
130
151
  ```bash
131
152
  uv run --with workbuddy2api python -m codebuddy_proxy \
@@ -140,6 +161,24 @@ Endpoint precedence is: explicit `--endpoint` > the `--global` profile default
140
161
  Therefore `--global` without `--endpoint` cannot be redirected to the domestic
141
162
  host by `CODEBUDDY_ENDPOINT`.
142
163
 
164
+ ### Built-in CodeBuddy gateways: developer-role compatibility
165
+
166
+ The built-in domestic (`https://copilot.tencent.com`) and international
167
+ (`https://www.codebuddy.ai`) Chat Completions gateways may reject requests
168
+ containing a `developer` message with HTTP 400 / code 11128. Before forwarding
169
+ to either matching backend and host, the proxy maps `developer` to `system`
170
+ without changing message order, content, tool-call history, or the original
171
+ client request. If enabled, `--desensitize` runs after this role adaptation.
172
+ No client-side configuration is needed.
173
+
174
+ The mapping is scoped to these exact backend/host pairs; endpoints using
175
+ other host names keep their original roles. International `X-Conversation-*` headers
176
+ are still generated after request-body transformations. Because the upstreams
177
+ do not represent the separate `system` and `developer` instruction priorities,
178
+ the mapping is an approximation, not exact semantic equivalence. The
179
+ `upstream_role_compat` log event reports the backend and number of mapped
180
+ messages, not prompt contents.
181
+
143
182
  Runtime model catalogs are loaded from the packaged profile resources
144
183
  `src/codebuddy_proxy/models_config.domestic.json` and
145
184
  `src/codebuddy_proxy/models_config.global.json`. The root
@@ -307,6 +346,7 @@ Select the model inside OMP with `/model codebuddy/hy3` (or set it as the defaul
307
346
  --global Use the international CodeBuddy backend (default domestic)
308
347
  --endpoint ENDPOINT CodeBuddy backend address (overrides the profile default)
309
348
  --session-file PATH Session file path (isolated by profile by default)
349
+ --accounts-dir DIR Account library directory (default ~/.workbuddy2api/accounts)
310
350
  --log-file PATH JSONL log file (default ~/.workbuddy2api/codebuddy-proxy.jsonl)
311
351
  --desensitize Enable desensitization (recommended)
312
352
  --optimize-context Enable message compression (recommended for Codex CLI)
@@ -367,15 +407,58 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
367
407
 
368
408
  ### Multi-account switching
369
409
 
370
- ```bash
371
- # Account 1
372
- uv run --with workbuddy2api python -m codebuddy_proxy --session-file ~/.codebuddy-work.json --login \
373
- --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
374
-
375
- # Account 2
376
- uv run --with workbuddy2api python -m codebuddy_proxy --session-file ~/.codebuddy-personal.json --login \
377
- --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
378
- ```
410
+ Start the proxy and open [http://127.0.0.1:8787/admin](http://127.0.0.1:8787/admin).
411
+ Choose **Domestic** or **Global**, then link the account in the browser window.
412
+ The first linked account becomes active automatically; linking another account
413
+ does not change the account currently in use. Use **Set active** to switch, or
414
+ remove a non-active account from the same page. The selection is saved for the
415
+ next proxy start. Switching affects new requests; requests already in progress
416
+ continue with the account selected when they began.
417
+
418
+ ![Account manager with check-in controls and redacted account identifiers](docs/images/account-manager-checkin.png)
419
+
420
+ The screenshot uses synthetic demo accounts. Account UIDs are covered, and no
421
+ credentials or session contents are shown. Accounts are kept separately by
422
+ backend, normalized endpoint, and user ID in `~/.workbuddy2api/accounts`; use
423
+ `--accounts-dir DIR` to choose another local directory. The manager remains
424
+ available before any account is linked. Its page and API are restricted to
425
+ loopback access, and API responses do not include tokens or session data.
426
+
427
+ Use the language selector at the top of the page to switch between Chinese and
428
+ English. The choice is remembered in this browser; without a saved preference,
429
+ the page follows the browser language. Switching languages keeps ongoing login
430
+ and account operations running.
431
+
432
+ Automatic account switching after an upstream HTTP `429` is off by default.
433
+ When enabled, a request can fail over only before any response has been sent,
434
+ and only to accounts with the same region and endpoint. Each account is tried
435
+ at most once per request. The proxy skips a candidate only when the request's
436
+ model is cooling down there; other models on that account remain eligible. A
437
+ missing or invalid model does not create a model cooldown or trigger failover.
438
+ If all tried accounts return `429`, the final status remains `429`, and the
439
+ last upstream response's `Retry-After` header is preserved when present.
440
+ Cooldowns are tracked per account and model, using upstream `Retry-After` or a
441
+ default 60 seconds when that value is missing or invalid. The setting and model
442
+ cooldowns persist across restarts. Old v1 account-wide cooldowns had no model
443
+ identity and are not carried forward during upgrade. The page shows a separate
444
+ remaining countdown and source for each model, and refreshes account state
445
+ periodically and immediately when a hidden page becomes visible again.
446
+
447
+ The account list also shows each linked account's check-in status for today
448
+ (Beijing time). The **Check in** action is available for every account, including
449
+ the active one; it checks the account first and does nothing when today's check-in
450
+ is already complete. The global automatic check-in setting is off by default and
451
+ applies to all linked accounts without changing the active account. The page saves
452
+ this setting and displays status; the proxy performs automatic checks and check-ins
453
+ in the background, including when the management page is closed. When enabled, the
454
+ proxy checks all linked accounts immediately and on startup. At Beijing midnight it
455
+ checks them, waits a random 0–10 minutes, then checks again before signing; disabling
456
+ it cancels pending scheduled work. Unknown status is never treated as permission to
457
+ sign. The setting persists; after restart, check-in status is confirmed by querying
458
+ the upstream service again.
459
+
460
+ The command-line `--login` flow and `--session-file` option remain available for
461
+ terminal use and importing an existing session.
379
462
 
380
463
  ### Listening on all interfaces (LAN sharing)
381
464
 
@@ -391,11 +474,20 @@ All endpoints do not require an extra token in the request by default; the proxy
391
474
  | Method | Path | Purpose |
392
475
  | --- | --- | --- |
393
476
  | GET | `/health` | Query local service and auth status |
477
+ | GET | `/admin` | Open the local account manager |
394
478
  | GET | `/v1/models` | Query the CodeBuddy model list |
395
479
  | POST | `/v1/chat/completions` | OpenAI Chat Completions, supports tools and streaming |
396
480
  | POST | `/v1/responses` | Responses API, compatible with Codex CLI |
397
481
  | POST | `/v1/messages` | Anthropic Messages API, compatible with Claude Code / CC Switch |
398
482
 
483
+ Account-management endpoints live under `/admin/api` and are restricted to
484
+ loopback clients. Write requests require the `X-Account-Manager: 1` header, and
485
+ cross-origin requests are rejected. `GET /admin/api/accounts` reports active
486
+ account, cooldown, and cached check-in state. `GET /admin/api/accounts/{id}/checkin-status`
487
+ checks that account against the upstream service; `POST /admin/api/accounts/{id}/checkin`
488
+ checks first and signs only when needed. `GET` and `PATCH /admin/api/settings` read
489
+ and save the automatic-switch and automatic-check-in preferences independently.
490
+
399
491
  ### `/health` - health check
400
492
 
401
493
  ```bash
@@ -704,6 +796,16 @@ Example output:
704
796
 
705
797
  ---
706
798
 
799
+ ### Process diagnostics (2.0.7)
800
+
801
+ In addition to the existing business logs, `console.log` mirrors Python stdout/stderr
802
+ (including Uvicorn errors and tracebacks), `process-events.jsonl` records process
803
+ startup, exit codes, signals and unhandled exceptions, and `crash.log` captures
804
+ Python fatal fault stacks. These files are written alongside `--log-file`.
805
+ The console and process-event files rotate by size; see
806
+ [process diagnostics](docs/process-diagnostics-2.0.7.md) for details.
807
+ **Console logs may contain sensitive data: review before sharing.**
808
+
707
809
  ### Logging
708
810
 
709
811
  Logs include:
@@ -712,6 +814,20 @@ Logs include:
712
814
 
713
815
  Each JSONL record contains `app_version`, `system_version`, `python_version`, and `machine` fields; a `startup` event is also recorded at launch.
714
816
 
817
+ Upstream connection errors/timeouts are retried at most twice (0.5s / 1s backoff,
818
+ three attempts total). HTTP errors and read/write failures are not retried;
819
+ once response headers arrive, the request is never replayed. Each attempt keeps
820
+ the existing 30s connection timeout, so a persistent outage can take up to about
821
+ 91.5s before the final error. This applies to streaming and aggregated responses.
822
+
823
+ `upstream_connect_retry` / `upstream_connect_failed` record the attempt number,
824
+ target host/port, and bounded `exception_chain` with exception types and native
825
+ `errno` / `winerror` values when available. `request_id` links these to stream
826
+ start, error, and terminal records. `stream_completed` is reserved for streams
827
+ that received upstream `[DONE]` and finished forwarding; other terminal events
828
+ are `stream_failed`, `stream_incomplete` (EOF/guard limit without `[DONE]`), and
829
+ `stream_cancelled`. `status: null` means no upstream HTTP response was received.
830
+
715
831
  You can also specify an absolute path for the log file:
716
832
 
717
833
  ```bash
@@ -797,6 +913,24 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
797
913
  --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
798
914
  ```
799
915
 
916
+ ### Upstream error 11148 "tool calls and tool results do not match"
917
+
918
+ Some agent clients produce nonconforming Anthropic / Responses tool histories.
919
+ The CodeBuddy backend requires Chat tool results to directly follow the
920
+ declaring assistant `tool_calls`. The proxy now repairs recoverable converted
921
+ histories in `/v1/messages` and `/v1/responses`: interleaved non-tool messages
922
+ are deferred, and orphan or identical duplicate results are dropped with
923
+ diagnostic warnings (no tool output is logged).
924
+
925
+ Ambiguous histories are **not silently truncated**. If a call has no result, a
926
+ tool-call ID is reused, or duplicate results disagree, the proxy returns HTTP
927
+ **422**, with `detail.code=invalid_tool_history` and a specific `reason`.
928
+ No request is sent upstream in that case. Verify the side effects of any
929
+ unfinished tools before retrying or starting a fresh conversation.
930
+
931
+ This repair does not apply to direct `/v1/chat/completions` requests and cannot
932
+ guarantee the absence of unrelated upstream 11148 errors.
933
+
800
934
  ### Port already in use
801
935
 
802
936
  ```bash
@@ -4,6 +4,8 @@
4
4
 
5
5
  > **中文版文档见 [README_zh.md](README_zh.md).**
6
6
 
7
+ For unexplained Windows process exits, use the [independent process monitor](docs/external-process-monitor.md) to collect uv/Python exit codes, lifecycle, memory, health, and available Windows events without restarting the proxy.
8
+
7
9
  ## ✨ Core Features
8
10
 
9
11
  - **Protocol conversion** - Supports three standard formats: OpenAI Chat Completions, Anthropic Messages API, and Responses
@@ -13,7 +15,9 @@
13
15
  - **DSML parsing** - Automatically detects and converts DeepSeek Markup Language (DSML) tool calls
14
16
  - **Streaming responses** - SSE streaming output, returning generated content in real time, with built-in 60-second timeout protection
15
17
  - **Domestic and international backends** - Uses domestic CodeBuddy by default and switches to the international CodeBuddy service with `--global`, with isolated sessions and model catalogs
16
- - **Multi-account management** - Supports isolation of multiple login states for easy switching between work/personal accounts
18
+ - **Multi-account management** - Link domestic and Global accounts, switch the active account, and remove non-active accounts from the local admin page
19
+ - **Model-level 429 handling** - Track cooldowns per account and model, with optional same-region failover
20
+ - **Daily check-in** - Check in manually or enable background checks for all linked accounts
17
21
 
18
22
  ---
19
23
 
@@ -49,12 +53,14 @@ uv sync
49
53
  uv run python -m codebuddy_proxy --desensitize
50
54
  ```
51
55
 
52
- On first use, when login is required:
56
+ On first use, start the proxy and open the local account manager:
53
57
 
54
58
  ```bash
55
- uv run python -m codebuddy_proxy --login --desensitize
59
+ uv run python -m codebuddy_proxy --desensitize
56
60
  ```
57
61
 
62
+ Then visit `http://127.0.0.1:8787/admin` and link a domestic or Global account.
63
+
58
64
  ## Quick Start
59
65
 
60
66
  ### 1. Start the proxy
@@ -63,8 +69,8 @@ uv run python -m codebuddy_proxy --login --desensitize
63
69
  # Use the latest version (recommended)
64
70
  uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
65
71
 
66
- # First use: log in and start
67
- uv run --with workbuddy2api python -m codebuddy_proxy --login --desensitize
72
+ # First use: start, then link an account at http://127.0.0.1:8787/admin
73
+ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize
68
74
 
69
75
  # International service: first login and start
70
76
  uv run --with workbuddy2api python -m codebuddy_proxy --global --login --desensitize
@@ -80,12 +86,23 @@ Listens on `http://127.0.0.1:8787` by default.
80
86
  The proxy supports both CodeBuddy regions. Domestic mode remains the default,
81
87
  so existing startup commands continue to work unchanged.
82
88
 
83
- | Mode | Startup option | Upstream endpoint | Default session file |
84
- | --- | --- | --- | --- |
85
- | Domestic (default) | none | `https://copilot.tencent.com` | `~/.codebuddy-session.json` |
86
- | International | `--global` | `https://www.codebuddy.ai` | `~/.codebuddy-global-session.json` |
89
+ | Mode | Startup option | Upstream endpoint |
90
+ | --- | --- | --- |
91
+ | Domestic (default) | none | `https://copilot.tencent.com` |
92
+ | International | `--global` | `https://www.codebuddy.ai` |
93
+
94
+ Linked accounts are stored separately by region in `~/.workbuddy2api/accounts`.
95
+ Use `--accounts-dir DIR` to choose another local directory. With no explicit
96
+ selector, the proxy restores the saved active account. On the first migration,
97
+ matching legacy session files are imported once and kept; deleting an imported
98
+ account does not import it again. Explicit `--global` or `--endpoint` selects a
99
+ matching account, while `--session-file` can import that file again. If there is
100
+ no match, the proxy starts without an active account. `--login` uses a temporary
101
+ session file to add or refresh an account without replacing a legacy file.
87
102
 
88
- First login and daily startup for the international service:
103
+ The account manager can add accounts for either region while the proxy is
104
+ running. For a terminal-driven login, the existing `--login` option remains
105
+ available:
89
106
 
90
107
  ```bash
91
108
  # First login
@@ -101,16 +118,18 @@ If the package is installed as a command, the equivalent short form is
101
118
  `workbuddy2api --global --login`. When running from source, use
102
119
  `uv run python -m codebuddy_proxy --global --login`.
103
120
 
104
- `--global` changes only the upstream service. Codex CLI, Claude Code/CC Switch,
105
- OpenCode, and other clients continue to use the same local proxy URLs. The
106
- selected profile also controls the model catalog returned by `/v1/models`.
121
+ `--global` selects the Global backend and a matching account when one exists.
122
+ Codex CLI, Claude Code/CC Switch, OpenCode, and other clients continue to use
123
+ the same local proxy URLs. The selected profile also controls the model catalog
124
+ returned by `/v1/models`.
107
125
 
108
- Domestic and international sessions are intentionally isolated. An explicit
109
- `--session-file` takes precedence, but its saved backend and endpoint must match
110
- the current startup options. The proxy refuses mismatched credentials and does
111
- not modify the original file.
126
+ Domestic and international accounts remain isolated. An explicit
127
+ `--session-file` is imported only when its saved backend and endpoint match the
128
+ current startup options. The proxy refuses mismatched credentials and does not
129
+ modify the original file.
112
130
 
113
- For a custom international endpoint, always use a dedicated session file:
131
+ For a custom international endpoint, use a dedicated session file when
132
+ importing or creating a login from the command line:
114
133
 
115
134
  ```bash
116
135
  uv run --with workbuddy2api python -m codebuddy_proxy \
@@ -125,6 +144,24 @@ Endpoint precedence is: explicit `--endpoint` > the `--global` profile default
125
144
  Therefore `--global` without `--endpoint` cannot be redirected to the domestic
126
145
  host by `CODEBUDDY_ENDPOINT`.
127
146
 
147
+ ### Built-in CodeBuddy gateways: developer-role compatibility
148
+
149
+ The built-in domestic (`https://copilot.tencent.com`) and international
150
+ (`https://www.codebuddy.ai`) Chat Completions gateways may reject requests
151
+ containing a `developer` message with HTTP 400 / code 11128. Before forwarding
152
+ to either matching backend and host, the proxy maps `developer` to `system`
153
+ without changing message order, content, tool-call history, or the original
154
+ client request. If enabled, `--desensitize` runs after this role adaptation.
155
+ No client-side configuration is needed.
156
+
157
+ The mapping is scoped to these exact backend/host pairs; endpoints using
158
+ other host names keep their original roles. International `X-Conversation-*` headers
159
+ are still generated after request-body transformations. Because the upstreams
160
+ do not represent the separate `system` and `developer` instruction priorities,
161
+ the mapping is an approximation, not exact semantic equivalence. The
162
+ `upstream_role_compat` log event reports the backend and number of mapped
163
+ messages, not prompt contents.
164
+
128
165
  Runtime model catalogs are loaded from the packaged profile resources
129
166
  `src/codebuddy_proxy/models_config.domestic.json` and
130
167
  `src/codebuddy_proxy/models_config.global.json`. The root
@@ -292,6 +329,7 @@ Select the model inside OMP with `/model codebuddy/hy3` (or set it as the defaul
292
329
  --global Use the international CodeBuddy backend (default domestic)
293
330
  --endpoint ENDPOINT CodeBuddy backend address (overrides the profile default)
294
331
  --session-file PATH Session file path (isolated by profile by default)
332
+ --accounts-dir DIR Account library directory (default ~/.workbuddy2api/accounts)
295
333
  --log-file PATH JSONL log file (default ~/.workbuddy2api/codebuddy-proxy.jsonl)
296
334
  --desensitize Enable desensitization (recommended)
297
335
  --optimize-context Enable message compression (recommended for Codex CLI)
@@ -352,15 +390,58 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
352
390
 
353
391
  ### Multi-account switching
354
392
 
355
- ```bash
356
- # Account 1
357
- uv run --with workbuddy2api python -m codebuddy_proxy --session-file ~/.codebuddy-work.json --login \
358
- --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
359
-
360
- # Account 2
361
- uv run --with workbuddy2api python -m codebuddy_proxy --session-file ~/.codebuddy-personal.json --login \
362
- --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
363
- ```
393
+ Start the proxy and open [http://127.0.0.1:8787/admin](http://127.0.0.1:8787/admin).
394
+ Choose **Domestic** or **Global**, then link the account in the browser window.
395
+ The first linked account becomes active automatically; linking another account
396
+ does not change the account currently in use. Use **Set active** to switch, or
397
+ remove a non-active account from the same page. The selection is saved for the
398
+ next proxy start. Switching affects new requests; requests already in progress
399
+ continue with the account selected when they began.
400
+
401
+ ![Account manager with check-in controls and redacted account identifiers](docs/images/account-manager-checkin.png)
402
+
403
+ The screenshot uses synthetic demo accounts. Account UIDs are covered, and no
404
+ credentials or session contents are shown. Accounts are kept separately by
405
+ backend, normalized endpoint, and user ID in `~/.workbuddy2api/accounts`; use
406
+ `--accounts-dir DIR` to choose another local directory. The manager remains
407
+ available before any account is linked. Its page and API are restricted to
408
+ loopback access, and API responses do not include tokens or session data.
409
+
410
+ Use the language selector at the top of the page to switch between Chinese and
411
+ English. The choice is remembered in this browser; without a saved preference,
412
+ the page follows the browser language. Switching languages keeps ongoing login
413
+ and account operations running.
414
+
415
+ Automatic account switching after an upstream HTTP `429` is off by default.
416
+ When enabled, a request can fail over only before any response has been sent,
417
+ and only to accounts with the same region and endpoint. Each account is tried
418
+ at most once per request. The proxy skips a candidate only when the request's
419
+ model is cooling down there; other models on that account remain eligible. A
420
+ missing or invalid model does not create a model cooldown or trigger failover.
421
+ If all tried accounts return `429`, the final status remains `429`, and the
422
+ last upstream response's `Retry-After` header is preserved when present.
423
+ Cooldowns are tracked per account and model, using upstream `Retry-After` or a
424
+ default 60 seconds when that value is missing or invalid. The setting and model
425
+ cooldowns persist across restarts. Old v1 account-wide cooldowns had no model
426
+ identity and are not carried forward during upgrade. The page shows a separate
427
+ remaining countdown and source for each model, and refreshes account state
428
+ periodically and immediately when a hidden page becomes visible again.
429
+
430
+ The account list also shows each linked account's check-in status for today
431
+ (Beijing time). The **Check in** action is available for every account, including
432
+ the active one; it checks the account first and does nothing when today's check-in
433
+ is already complete. The global automatic check-in setting is off by default and
434
+ applies to all linked accounts without changing the active account. The page saves
435
+ this setting and displays status; the proxy performs automatic checks and check-ins
436
+ in the background, including when the management page is closed. When enabled, the
437
+ proxy checks all linked accounts immediately and on startup. At Beijing midnight it
438
+ checks them, waits a random 0–10 minutes, then checks again before signing; disabling
439
+ it cancels pending scheduled work. Unknown status is never treated as permission to
440
+ sign. The setting persists; after restart, check-in status is confirmed by querying
441
+ the upstream service again.
442
+
443
+ The command-line `--login` flow and `--session-file` option remain available for
444
+ terminal use and importing an existing session.
364
445
 
365
446
  ### Listening on all interfaces (LAN sharing)
366
447
 
@@ -376,11 +457,20 @@ All endpoints do not require an extra token in the request by default; the proxy
376
457
  | Method | Path | Purpose |
377
458
  | --- | --- | --- |
378
459
  | GET | `/health` | Query local service and auth status |
460
+ | GET | `/admin` | Open the local account manager |
379
461
  | GET | `/v1/models` | Query the CodeBuddy model list |
380
462
  | POST | `/v1/chat/completions` | OpenAI Chat Completions, supports tools and streaming |
381
463
  | POST | `/v1/responses` | Responses API, compatible with Codex CLI |
382
464
  | POST | `/v1/messages` | Anthropic Messages API, compatible with Claude Code / CC Switch |
383
465
 
466
+ Account-management endpoints live under `/admin/api` and are restricted to
467
+ loopback clients. Write requests require the `X-Account-Manager: 1` header, and
468
+ cross-origin requests are rejected. `GET /admin/api/accounts` reports active
469
+ account, cooldown, and cached check-in state. `GET /admin/api/accounts/{id}/checkin-status`
470
+ checks that account against the upstream service; `POST /admin/api/accounts/{id}/checkin`
471
+ checks first and signs only when needed. `GET` and `PATCH /admin/api/settings` read
472
+ and save the automatic-switch and automatic-check-in preferences independently.
473
+
384
474
  ### `/health` - health check
385
475
 
386
476
  ```bash
@@ -689,6 +779,16 @@ Example output:
689
779
 
690
780
  ---
691
781
 
782
+ ### Process diagnostics (2.0.7)
783
+
784
+ In addition to the existing business logs, `console.log` mirrors Python stdout/stderr
785
+ (including Uvicorn errors and tracebacks), `process-events.jsonl` records process
786
+ startup, exit codes, signals and unhandled exceptions, and `crash.log` captures
787
+ Python fatal fault stacks. These files are written alongside `--log-file`.
788
+ The console and process-event files rotate by size; see
789
+ [process diagnostics](docs/process-diagnostics-2.0.7.md) for details.
790
+ **Console logs may contain sensitive data: review before sharing.**
791
+
692
792
  ### Logging
693
793
 
694
794
  Logs include:
@@ -697,6 +797,20 @@ Logs include:
697
797
 
698
798
  Each JSONL record contains `app_version`, `system_version`, `python_version`, and `machine` fields; a `startup` event is also recorded at launch.
699
799
 
800
+ Upstream connection errors/timeouts are retried at most twice (0.5s / 1s backoff,
801
+ three attempts total). HTTP errors and read/write failures are not retried;
802
+ once response headers arrive, the request is never replayed. Each attempt keeps
803
+ the existing 30s connection timeout, so a persistent outage can take up to about
804
+ 91.5s before the final error. This applies to streaming and aggregated responses.
805
+
806
+ `upstream_connect_retry` / `upstream_connect_failed` record the attempt number,
807
+ target host/port, and bounded `exception_chain` with exception types and native
808
+ `errno` / `winerror` values when available. `request_id` links these to stream
809
+ start, error, and terminal records. `stream_completed` is reserved for streams
810
+ that received upstream `[DONE]` and finished forwarding; other terminal events
811
+ are `stream_failed`, `stream_incomplete` (EOF/guard limit without `[DONE]`), and
812
+ `stream_cancelled`. `status: null` means no upstream HTTP response was received.
813
+
700
814
  You can also specify an absolute path for the log file:
701
815
 
702
816
  ```bash
@@ -782,6 +896,24 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
782
896
  --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
783
897
  ```
784
898
 
899
+ ### Upstream error 11148 "tool calls and tool results do not match"
900
+
901
+ Some agent clients produce nonconforming Anthropic / Responses tool histories.
902
+ The CodeBuddy backend requires Chat tool results to directly follow the
903
+ declaring assistant `tool_calls`. The proxy now repairs recoverable converted
904
+ histories in `/v1/messages` and `/v1/responses`: interleaved non-tool messages
905
+ are deferred, and orphan or identical duplicate results are dropped with
906
+ diagnostic warnings (no tool output is logged).
907
+
908
+ Ambiguous histories are **not silently truncated**. If a call has no result, a
909
+ tool-call ID is reused, or duplicate results disagree, the proxy returns HTTP
910
+ **422**, with `detail.code=invalid_tool_history` and a specific `reason`.
911
+ No request is sent upstream in that case. Verify the side effects of any
912
+ unfinished tools before retrying or starting a fresh conversation.
913
+
914
+ This repair does not apply to direct `/v1/chat/completions` requests and cannot
915
+ guarantee the absence of unrelated upstream 11148 errors.
916
+
785
917
  ### Port already in use
786
918
 
787
919
  ```bash
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "workbuddy2api"
3
- version = "2.0.6"
3
+ version = "2.0.8.dev1"
4
4
  description = "Local OpenAI/Responses/Anthropic compatible proxy for CodeBuddy"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -9,6 +9,8 @@ dependencies = [
9
9
  "uvicorn>=0.24.0",
10
10
  "httpx[socks]>=0.25.0",
11
11
  "requests>=2.31.0",
12
+ "buddy-agent-auth>=0.1.0.dev1,<0.2",
13
+ "buddy-agent-checkin[workbuddy]>=0.1.1.dev2,<0.2",
12
14
  ]
13
15
 
14
16
  [project.optional-dependencies]
@@ -27,9 +29,9 @@ build-backend = "setuptools.build_meta"
27
29
  where = ["src"]
28
30
 
29
31
  [tool.setuptools.package-data]
30
- codebuddy_proxy = ["models_config.*.json"]
32
+ codebuddy_proxy = ["models_config.*.json", "admin.html"]
31
33
 
32
34
  [dependency-groups]
33
35
  dev = [
34
36
  "pytest>=7.4.0",
35
- ]
37
+ ]