workbuddy2api 2.0.5__tar.gz → 2.0.7__tar.gz

{workbuddy2api-2.0.5 → workbuddy2api-2.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workbuddy2api
-Version: 2.0.5
+Version: 2.0.7
 Summary: Local OpenAI/Responses/Anthropic compatible proxy for CodeBuddy
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -19,6 +19,8 @@ Dynamic: license-file
 
 > **中文版文档见 [README_zh.md](README_zh.md).**
 
+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.
+
 ## ✨ Core Features
 
 - **Protocol conversion** - Supports three standard formats: OpenAI Chat Completions, Anthropic Messages API, and Responses
@@ -140,6 +142,21 @@ Endpoint precedence is: explicit `--endpoint` > the `--global` profile default
 Therefore `--global` without `--endpoint` cannot be redirected to the domestic
 host by `CODEBUDDY_ENDPOINT`.
 
+### Domestic gateway: developer-role compatibility
+
+The domestic default upstream (`https://copilot.tencent.com`) may reject
+Chat Completions requests containing a `developer` message with HTTP 400 /
+code 11128. Before forwarding to **that upstream only**, the proxy maps
+`developer` to `system` without changing message order, content, tool-call
+history, or the original client request. If enabled, `--desensitize` runs
+after this role adaptation. No client-side configuration is needed.
+
+This compatibility mapping does not apply to the international backend or
+custom endpoints. Because the legacy upstream does not represent the separate
+`system` and `developer` instruction priorities, it is an approximation,
+not exact semantic equivalence. The `upstream_role_compat` log event reports
+only the number of mapped messages, not prompt contents.
+
 Runtime model catalogs are loaded from the packaged profile resources
 `src/codebuddy_proxy/models_config.domestic.json` and
 `src/codebuddy_proxy/models_config.global.json`. The root
@@ -704,6 +721,16 @@ Example output:
 
 ---
 
+### Process diagnostics (2.0.7)
+
+In addition to the existing business logs, `console.log` mirrors Python stdout/stderr
+(including Uvicorn errors and tracebacks), `process-events.jsonl` records process
+startup, exit codes, signals and unhandled exceptions, and `crash.log` captures
+Python fatal fault stacks. These files are written alongside `--log-file`.
+The console and process-event files rotate by size; see
+[process diagnostics](docs/process-diagnostics-2.0.7.md) for details.
+**Console logs may contain sensitive data: review before sharing.**
+
 ### Logging
 
 Logs include:
@@ -712,6 +739,20 @@ Logs include:
 
 Each JSONL record contains `app_version`, `system_version`, `python_version`, and `machine` fields; a `startup` event is also recorded at launch.
 
+Upstream connection errors/timeouts are retried at most twice (0.5s / 1s backoff,
+three attempts total). HTTP errors and read/write failures are not retried;
+once response headers arrive, the request is never replayed. Each attempt keeps
+the existing 30s connection timeout, so a persistent outage can take up to about
+91.5s before the final error. This applies to streaming and aggregated responses.
+
+`upstream_connect_retry` / `upstream_connect_failed` record the attempt number,
+target host/port, and bounded `exception_chain` with exception types and native
+`errno` / `winerror` values when available. `request_id` links these to stream
+start, error, and terminal records. `stream_completed` is reserved for streams
+that received upstream `[DONE]` and finished forwarding; other terminal events
+are `stream_failed`, `stream_incomplete` (EOF/guard limit without `[DONE]`), and
+`stream_cancelled`. `status: null` means no upstream HTTP response was received.
+
 You can also specify an absolute path for the log file:
 
 ```bash
@@ -797,6 +838,24 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
   --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
 ```
 
+### Upstream error 11148 "tool calls and tool results do not match"
+
+Some agent clients produce nonconforming Anthropic / Responses tool histories.
+The CodeBuddy backend requires Chat tool results to directly follow the
+declaring assistant `tool_calls`. The proxy now repairs recoverable converted
+histories in `/v1/messages` and `/v1/responses`: interleaved non-tool messages
+are deferred, and orphan or identical duplicate results are dropped with
+diagnostic warnings (no tool output is logged).
+
+Ambiguous histories are **not silently truncated**. If a call has no result, a
+tool-call ID is reused, or duplicate results disagree, the proxy returns HTTP
+**422**, with `detail.code=invalid_tool_history` and a specific `reason`.
+No request is sent upstream in that case. Verify the side effects of any
+unfinished tools before retrying or starting a fresh conversation.
+
+This repair does not apply to direct `/v1/chat/completions` requests and cannot
+guarantee the absence of unrelated upstream 11148 errors.
+
 ### Port already in use
 
 ```bash

{workbuddy2api-2.0.5 → workbuddy2api-2.0.7}/README.md

@@ -4,6 +4,8 @@
 
 > **中文版文档见 [README_zh.md](README_zh.md).**
 
+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.
+
 ## ✨ Core Features
 
 - **Protocol conversion** - Supports three standard formats: OpenAI Chat Completions, Anthropic Messages API, and Responses
@@ -125,6 +127,21 @@ Endpoint precedence is: explicit `--endpoint` > the `--global` profile default
 Therefore `--global` without `--endpoint` cannot be redirected to the domestic
 host by `CODEBUDDY_ENDPOINT`.
 
+### Domestic gateway: developer-role compatibility
+
+The domestic default upstream (`https://copilot.tencent.com`) may reject
+Chat Completions requests containing a `developer` message with HTTP 400 /
+code 11128. Before forwarding to **that upstream only**, the proxy maps
+`developer` to `system` without changing message order, content, tool-call
+history, or the original client request. If enabled, `--desensitize` runs
+after this role adaptation. No client-side configuration is needed.
+
+This compatibility mapping does not apply to the international backend or
+custom endpoints. Because the legacy upstream does not represent the separate
+`system` and `developer` instruction priorities, it is an approximation,
+not exact semantic equivalence. The `upstream_role_compat` log event reports
+only the number of mapped messages, not prompt contents.
+
 Runtime model catalogs are loaded from the packaged profile resources
 `src/codebuddy_proxy/models_config.domestic.json` and
 `src/codebuddy_proxy/models_config.global.json`. The root
@@ -689,6 +706,16 @@ Example output:
 
 ---
 
+### Process diagnostics (2.0.7)
+
+In addition to the existing business logs, `console.log` mirrors Python stdout/stderr
+(including Uvicorn errors and tracebacks), `process-events.jsonl` records process
+startup, exit codes, signals and unhandled exceptions, and `crash.log` captures
+Python fatal fault stacks. These files are written alongside `--log-file`.
+The console and process-event files rotate by size; see
+[process diagnostics](docs/process-diagnostics-2.0.7.md) for details.
+**Console logs may contain sensitive data: review before sharing.**
+
 ### Logging
 
 Logs include:
@@ -697,6 +724,20 @@ Logs include:
 
 Each JSONL record contains `app_version`, `system_version`, `python_version`, and `machine` fields; a `startup` event is also recorded at launch.
 
+Upstream connection errors/timeouts are retried at most twice (0.5s / 1s backoff,
+three attempts total). HTTP errors and read/write failures are not retried;
+once response headers arrive, the request is never replayed. Each attempt keeps
+the existing 30s connection timeout, so a persistent outage can take up to about
+91.5s before the final error. This applies to streaming and aggregated responses.
+
+`upstream_connect_retry` / `upstream_connect_failed` record the attempt number,
+target host/port, and bounded `exception_chain` with exception types and native
+`errno` / `winerror` values when available. `request_id` links these to stream
+start, error, and terminal records. `stream_completed` is reserved for streams
+that received upstream `[DONE]` and finished forwarding; other terminal events
+are `stream_failed`, `stream_incomplete` (EOF/guard limit without `[DONE]`), and
+`stream_cancelled`. `status: null` means no upstream HTTP response was received.
+
 You can also specify an absolute path for the log file:
 
 ```bash
@@ -782,6 +823,24 @@ uv run --with workbuddy2api python -m codebuddy_proxy --desensitize --optimize-c
   --log-file "$HOME/.workbuddy2api/codebuddy-proxy.jsonl"
 ```
 
+### Upstream error 11148 "tool calls and tool results do not match"
+
+Some agent clients produce nonconforming Anthropic / Responses tool histories.
+The CodeBuddy backend requires Chat tool results to directly follow the
+declaring assistant `tool_calls`. The proxy now repairs recoverable converted
+histories in `/v1/messages` and `/v1/responses`: interleaved non-tool messages
+are deferred, and orphan or identical duplicate results are dropped with
+diagnostic warnings (no tool output is logged).
+
+Ambiguous histories are **not silently truncated**. If a call has no result, a
+tool-call ID is reused, or duplicate results disagree, the proxy returns HTTP
+**422**, with `detail.code=invalid_tool_history` and a specific `reason`.
+No request is sent upstream in that case. Verify the side effects of any
+unfinished tools before retrying or starting a fresh conversation.
+
+This repair does not apply to direct `/v1/chat/completions` requests and cannot
+guarantee the absence of unrelated upstream 11148 errors.
+
 ### Port already in use
 
 ```bash

{workbuddy2api-2.0.5 → workbuddy2api-2.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workbuddy2api"
-version = "2.0.5"
+version = "2.0.7"
 description = "Local OpenAI/Responses/Anthropic compatible proxy for CodeBuddy"
 readme = "README.md"
 requires-python = ">=3.10"