@qwen-code/qwen-code 0.22.0 → 0.22.2-preview.0

package/bundled/computer-use/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: computer-use
+description: Control local desktop applications through Computer Use for tasks that require reading or operating app UI. Prefer purpose-built connectors, APIs, or CLIs when available.
+---
+
+## `node_repl` + `@qwen-code/cua-sdk` (Computer Use)
+
+- Use `node_repl` (JavaScript) for all Computer Use actions.
+- Do not use other technologies besides `node_repl` for computer interactions
+  unless specifically requested by the user. This includes AppleScript,
+  `osascript`, JXA, System Events, and synthesized input.
+- Prefer a dedicated plugin or skill when it can complete the task; use
+  Computer Use for app interactions that are not exposed through a more
+  specific interface.
+- Use only the typed `ComputerUse` API. Do not use a generic SDK `callTool`,
+  direct `CuaDriver` imports, or a Qwen global bridge.
+- `node_repl` state persists across calls.
+- Use `nodeRepl.write(...)` for text output. It takes a string, so wrap objects
+  with `JSON.stringify(...)`.
+
+## Install automatically
+
+Run `qwen mcp list` to check whether the `node-repl` server is configured. If it
+is not configured, run both commands yourself:
+
+```bash
+qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.0
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.0
+```
+
+Tell the user to restart Qwen Code after adding the MCP server, then stop. Do
+not ask the user to copy or run the commands.
+
+If `node_repl` is available but the SDK import fails, run the SDK installation
+command yourself from the current workspace, then retry the import:
+
+```bash
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.0
+```
+
+## Bootstrap
+
+Import the SDK once per fresh `node_repl` kernel:
+
+```js
+globalThis.computer = await (
+  await import('@qwen-code/cua-sdk/computer-use')
+).ComputerUse.create();
+```
+
+## API surface
+
+```ts
+type WindowTarget = { pid: number; windowId: number };
+type ElementTarget = {
+  pid: number;
+  windowId?: number;
+  elementToken: string;
+};
+type CoordinateTarget = WindowTarget & { x: number; y: number };
+type PointOrElementTarget = CoordinateTarget | ElementTarget;
+type App = {
+  name?: string;
+  bundle_id?: string;
+  pid?: number;
+  running?: boolean;
+  launch_path?: string;
+};
+type Window = {
+  window_id: number;
+  title?: string;
+  is_on_screen?: boolean;
+  on_current_space?: boolean;
+};
+type Element = {
+  element_token?: string;
+  role?: string;
+  label?: string;
+  value?: unknown;
+  actions?: string[];
+};
+
+type ComputerUse = {
+  listApps: () => Promise<App[]>;
+  listWindows: (args?: {
+    pid?: number;
+    onScreenOnly?: boolean;
+  }) => Promise<Window[]>;
+  observeWindow: (
+    args: WindowTarget & {
+      baseRevisionId?: string;
+      forceFull?: boolean;
+      includeScreenshot?: boolean;
+    },
+  ) => Promise<{
+    text: string;
+    elements: Element[];
+    revisionId?: string;
+    screenshot?: { images: object[] };
+  }>;
+  click: (
+    args: PointOrElementTarget & {
+      button?: 'left' | 'right' | 'middle';
+      count?: number;
+    },
+  ) => Promise<object>;
+  doubleClick: (args: PointOrElementTarget) => Promise<object>;
+  rightClick: (args: PointOrElementTarget) => Promise<object>;
+  setValue: (args: ElementTarget & { value: string }) => Promise<object>;
+  typeText: (args: WindowTarget & { text: string }) => Promise<object>;
+  pressKey: (args: WindowTarget & { key: string }) => Promise<object>;
+  hotkey: (args: WindowTarget & { keys: string[] }) => Promise<object>;
+  scroll: (
+    args: PointOrElementTarget & {
+      direction: 'up' | 'down' | 'left' | 'right';
+      by?: 'line' | 'page';
+      amount?: number;
+    },
+  ) => Promise<object>;
+  drag: (
+    args: WindowTarget & {
+      fromX: number;
+      fromY: number;
+      toX: number;
+      toY: number;
+      deliveryMode?: 'background' | 'foreground';
+    },
+  ) => Promise<object>;
+  performSecondaryAction: (
+    args: ElementTarget & { action: string },
+  ) => Promise<object>;
+  close: () => Promise<void>;
+};
+```
+
+## Workflow
+
+### 1. Initialize
+
+Resolve the exact running application and window named by the task. Filter
+inside `node_repl`; do not print the entire application list:
+
+```js
+var apps = await computer.listApps();
+var matches = apps.filter(
+  (app) => app.name === 'Target App' || app.bundle_id === 'com.example.target',
+);
+nodeRepl.write(JSON.stringify(matches));
+```
+
+After choosing the application from returned metadata, list only its windows:
+
+```js
+var pid = matches[0].pid;
+var windows = await computer.listWindows({ pid });
+nodeRepl.write(JSON.stringify(windows));
+```
+
+Choose the window from returned metadata, then get its current accessibility
+state:
+
+```js
+var target = { pid, windowId: windows[0].window_id };
+var state = await computer.observeWindow({ ...target, forceFull: true });
+nodeRepl.write(state.text);
+```
+
+Never guess a PID, window ID, coordinate, or element token. `ComputerUse`
+discovers running applications but does not launch them; if necessary, start
+the application from `node_repl` with ordinary Node.js process APIs, then
+refresh the application and window lists.
+
+### 2. Act and get the latest state
+
+Choose only the action needed for the user's task. Prefer current
+`element_token` values over coordinates. Pass an observed `element_token` as
+the camel-case `elementToken` action field:
+
+```js
+await computer.setValue({
+  ...target,
+  elementToken,
+  value: 'hello',
+});
+
+state = await computer.observeWindow({
+  ...target,
+  baseRevisionId: state.revisionId,
+});
+nodeRepl.write(state.text);
+```
+
+After one or more actions, always observe the exact window before deciding what
+to do next. If the updated state shows the requested result, stop acting,
+clean up, and answer the user. If the UI does not behave as expected, get a
+fresh full state before choosing a different action.
+
+Use a secondary action only when the current accessibility state advertises
+that exact action. Prefer accessibility text for efficiency; use a screenshot
+when it is incomplete or visual layout matters.
+
+## Reading screenshots
+
+```js
+var state = await computer.observeWindow({
+  ...target,
+  forceFull: true,
+  includeScreenshot: true,
+});
+
+for (var image of state.screenshot?.images ?? []) {
+  if (image?.dataBase64 && image?.mimeType) {
+    await nodeRepl.emitImage(
+      `data:${image.mimeType};base64,${image.dataBase64}`,
+    );
+  }
+}
+```
+
+## Finish
+
+When the task is complete, close the SDK client:
+
+```js
+await computer.close();
+globalThis.computer = undefined;
+```
+
+Call `node_repl_reset` when no other REPL state is needed.

package/bundled/computer-use/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Computer Use'
+  short_description: 'Control desktop apps through the Qwen CUA SDK'
+  default_prompt: 'Use $computer-use to inspect and operate the requested desktop application safely.'

package/bundled/coordinate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coordinate
-description: Coordinate up to three Qwen Code teammates with enforced read-only workers, an optional worktree-pinned writer, shared tasks, peer messages, and existing Agent View tabs. Invoke explicitly with /coordinate.
+description: Coordinate a small team of Qwen Code teammates with enforced read-only workers, an optional worktree-pinned writer, shared tasks, peer messages, and existing Agent View tabs. Invoke explicitly with /coordinate.
 argument-hint: '<goal>'
 disable-model-invocation: true
 ---
@@ -14,7 +14,7 @@ Act as the team leader. Decompose the goal, keep task ownership clear, reconcile
 When `team_create` is available:
 
 1. Create one team and one self-contained task per current investigation workstream. Do not queue an implementation task while read-only teammates are idle because tasks are auto-assigned.
-2. Spawn one to three named investigation teammates with `read_only: true`. Do not pass `model`; use the session-default model unless the selected agent definition explicitly overrides it.
+2. Spawn named investigation teammates with `read_only: true` — one per workstream, and prefer three at most. Never exceed the team's configured cap, which `team_create` reports; spawning past it fails outright. Do not pass `model`; use the session-default model unless the selected agent definition explicitly overrides it.
 3. Assign tasks and let teammates collaborate through `send_message` and the shared task list. Send targeted follow-ups when evidence conflicts, a task needs clarification, or a result is incomplete.
 4. Accept or reject each result based on its evidence. Reassign rejected work instead of silently using it.
 
@@ -25,7 +25,7 @@ Read-only teammates have a positive execution allowlist. They cannot use shell,
 When the goal requires code changes:
 
 1. Finish the parallel investigation first.
-2. Send each investigation teammate a `shutdown_request`. Once shutdown is pending, they are excluded from automatic task assignment.
+2. Call `request_shutdown` for each investigation teammate. Once shutdown is pending, they are excluded from automatic task assignment.
 3. Call `enter_worktree` once and keep the returned path.
 4. Create the implementation task, then spawn exactly one named writer with `subagent_type: "general-purpose"` and `working_dir: <path>`. Do not set `read_only` for this teammate.
 5. Give the writer the accepted investigation evidence and require all changes to stay inside the worktree.
@@ -34,7 +34,7 @@ When the goal requires code changes:
 
 If the checkout is not a Git repository or worktree creation fails, keep all teammates read-only and let the leader make the final change in the current checkout.
 
-After synthesis, send each still-active teammate a `shutdown_request`, then delete the team.
+After synthesis, call `request_shutdown` for each still-active teammate, then delete the team.
 
 The existing Agent View tabs show teammate conversations, messages, status, and approvals. Do not create another roster, session manager, or terminal UI.
 
@@ -42,7 +42,7 @@ If the Agent Team tools are unavailable, say that `experimental.agentTeam` must
 
 ## Keep coordination bounded
 
-- Use one teammate for a narrow task and no more than three for this workflow.
+- Use one teammate for a narrow task. Past roughly three, the leader spends more of its turn reconciling reports than doing the work, so add a fourth only when the workstreams are genuinely independent — and never past the configured cap.
 - Give every task an objective, scope, completion condition, and required evidence.
 - Default every teammate to `read_only: true`; add one worktree writer only when implementation is required.
 - Do not use Arena: it is for competing solutions to the same task, not collaboration on different tasks.

package/bundled/qc-helper/docs/configuration/auth.md

@@ -3,7 +3,7 @@
 Qwen Code's first-run `/auth` menu has three top-level options. Pick the one that matches how you want to run the CLI:
 
 - **Alibaba ModelStudio**: official recommended setup. Opens a sub-menu with **Coding Plan** (for individual developers · weekly quota included), **Token Plan** (for teams and companies · usage-based billing with a dedicated endpoint), or **Standard API Key** (connect with an existing ModelStudio API key).
-- **Third-party Providers**: choose a built-in provider and connect with an API key (DeepSeek, MiniMax, Z.AI, Idealab, ModelScope, OpenRouter, Requesty).
+- **Third-party Providers**: choose a built-in provider and connect with an API key (DeepSeek, Grok, MiniMax, Z.AI, Kimi, Idealab, ModelScope, OpenRouter, Requesty).
 - **Custom Provider**: manually connect a local server, proxy, or unsupported provider — supports OpenAI, Anthropic, Gemini, and other compatible endpoints.
 
 > [!note]
@@ -157,12 +157,12 @@ The key concept is **Model Providers** (`modelProviders`): Qwen Code supports mu
 
 #### Supported protocols
 
-| Protocol          | `modelProviders` key | Environment variables                                                                                | Providers                                                                                             |
-| ----------------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| OpenAI-compatible | `openai`             | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` (alias: `QWEN_MODEL`)                            | OpenAI, Azure OpenAI, OpenRouter, Requesty, ModelScope, Alibaba Cloud, any OpenAI-compatible endpoint |
-| Anthropic         | `anthropic`          | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`                                         | Anthropic Claude                                                                                      |
-| Google GenAI      | `gemini`             | `GEMINI_API_KEY`, `GEMINI_MODEL`                                                                     | Google Gemini                                                                                         |
-| Vertex AI         | `vertex-ai`          | `GOOGLE_API_KEY`, `GOOGLE_MODEL` (sets `GOOGLE_GENAI_USE_VERTEXAI=true`; uses the `gemini` protocol) | Google Vertex AI                                                                                      |
+| Protocol          | `modelProviders` key | Environment variables                                                                                                                                                                                                                                                                                 | Providers                                                                                             |
+| ----------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| OpenAI-compatible | `openai`             | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` (alias: `QWEN_MODEL`)                                                                                                                                                                                                                             | OpenAI, Azure OpenAI, OpenRouter, Requesty, ModelScope, Alibaba Cloud, any OpenAI-compatible endpoint |
+| Anthropic         | `anthropic`          | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`                                                                                                                                                                                                                                          | Anthropic Claude                                                                                      |
+| Google GenAI      | `gemini`             | `GEMINI_API_KEY`, `GEMINI_MODEL`                                                                                                                                                                                                                                                                      | Google Gemini                                                                                         |
+| Vertex AI         | `vertex-ai`          | `GOOGLE_API_KEY` or `GOOGLE_CLOUD_PROJECT` (+ optional `GOOGLE_CLOUD_LOCATION`), `GOOGLE_MODEL` (uses the `gemini` protocol; a keyless project-only setup is not auto-detected from the environment, so select the auth type explicitly with `--auth-type vertex-ai` or `security.auth.selectedType`) | Google Vertex AI                                                                                      |
 
 #### Step 1: Configure models and providers in `~/.qwen/settings.json`
 

package/bundled/qc-helper/docs/configuration/model-providers.md

@@ -18,6 +18,53 @@ Use `modelProviders` to declare models per provider id that the `/model` picker
 >
 > **Model uniqueness:** Models within the same `authType` are uniquely identified by the combination of `id` + `baseUrl`. This means you can define the same model ID (e.g., `"gpt-4o"`) multiple times under a single `authType` as long as each entry has a different `baseUrl` — for example, one pointing to OpenAI directly and another to a proxy endpoint. If two entries share both the same `id` and the same `baseUrl` (or both omit `baseUrl`), the first occurrence wins and subsequent duplicates are skipped with a warning.
 
+### Image generation routes
+
+Set `supportsImageGeneration: true` when a route can be used by the built-in
+`image_gen` tool. This capability is independent from image input support such
+as `capabilities.vision` or `generationConfig.modalities.image`.
+
+Use `imageOnly: true` when the route is dedicated to image generation and must
+not appear in ordinary model selectors. For backward compatibility,
+`imageOnly: true` also implies image-generation capability, so existing settings
+do not need to be migrated.
+
+A dual-role route can be selected both as the main model and through
+`/model --image`:
+
+```json
+{
+  "modelProviders": {
+    "openai": [
+      {
+        "id": "omni-model",
+        "envKey": "MODEL_API_KEY",
+        "baseUrl": "https://gateway.example.com/model-api",
+        "supportsImageGeneration": true
+      }
+    ]
+  }
+}
+```
+
+A dedicated image route sets both fields. The legacy form with only
+`imageOnly: true` remains valid:
+
+```json
+{
+  "id": "image-model",
+  "envKey": "MODEL_API_KEY",
+  "baseUrl": "https://images.example.com/api/v1",
+  "supportsImageGeneration": true,
+  "imageOnly": true
+}
+```
+
+The selected route must declare an explicit HTTPS `baseUrl` and a non-empty
+`envKey`. Image generation uses the same endpoint and credential as the route;
+if chat and image generation require different endpoints or credentials,
+configure two routes instead.
+
 ## Configuration Examples by Auth Type
 
 Below are comprehensive configuration examples for different authentication types, showing the available parameters and their combinations.
@@ -34,6 +81,9 @@ The `modelProviders` object keys must be valid `authType` values. Currently supp
 | `qwen-oauth` | Qwen OAuth (hard-coded, cannot be overridden in `modelProviders`)                                                                               |
 | `vertex-ai`  | Google Vertex AI (uses the `gemini` protocol and the `@google/genai` SDK in Vertex AI mode; selecting it sets `GOOGLE_GENAI_USE_VERTEXAI=true`) |
 
+> [!note]
+> Vertex AI entries can authenticate with **Application Default Credentials**. Set `GOOGLE_CLOUD_PROJECT` (and optionally `GOOGLE_CLOUD_LOCATION`, which defaults to `global`) and leave `envKey` unset, along with every other key source the resolver reads: `GOOGLE_API_KEY`, `settings.security.auth.apiKey`, and the CLI key flags. Any API key value that reaches a Vertex entry switches the Google SDK to Vertex Express mode, which ignores the project, the location and your ADC credentials. An entry that declares an `envKey` is never routed to ADC, so a key that fails to be injected keeps failing on that variable instead of silently authenticating as a different principal.
+
 > [!warning]
 > A provider id that is neither a built-in protocol nor mapped via `providerProtocol` (e.g. a typo like `"openai-custom"`) cannot be routed, so its whole entry is **skipped** with a warning — its models simply won't appear in the `/model` picker. Use one of the supported auth type values above for built-in providers, or add a [`providerProtocol`](#custom-provider-ids-providerprotocol) mapping for a custom id.
 
@@ -270,6 +320,7 @@ Most local inference servers (vLLM, Ollama, LM Studio, etc.) provide an OpenAI-c
         "baseUrl": "http://localhost:11434/v1",
         "generationConfig": {
           "timeout": 300000,
+          "streamIdleTimeoutMs": 600000,
           "maxRetries": 1,
           "contextWindowSize": 32768,
           "samplingParams": {
@@ -311,6 +362,13 @@ Most local inference servers (vLLM, Ollama, LM Studio, etc.) provide an OpenAI-c
 }
 ```
 
+For queued or slow local OpenAI-compatible servers, `streamIdleTimeoutMs`
+controls how long this model may stay silent between streamed chunks. It
+overrides the global `QWEN_STREAM_IDLE_TIMEOUT_MS` value for the selected
+provider entry; set it to `0` to disable the idle guard. The separate 15-minute
+stream lifetime cap still applies unless `QWEN_STREAM_MAX_LIFETIME_MS` is raised
+or disabled.
+
 For local servers that don't require authentication, you can use any placeholder value for the API key:
 
 ```bash
@@ -583,14 +641,15 @@ The optional `reasoning` field under `generationConfig` controls how aggressivel
 
 ### Per-provider behavior
 
-| Protocol / provider                           | Wire shape                                                           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| --------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **OpenAI / DashScope** (`qwen3.8-max` family) | Flat `reasoning_effort: <effort>` body parameter                     | The five `/effort` tiers (`low`, `medium`, `high`, `xhigh`, `max`) are passed through verbatim for any model id starting with `qwen3.8-max` (including dated snapshots and `-latest` aliases); DashScope applies any model-specific mapping. When `reasoning_effort` and `thinking_budget` conflict, the normal `extra_body` > `samplingParams` > `reasoning` precedence keeps only the higher-priority field; an explicit same-layer pair keeps `reasoning_effort`, matching the provider's behavior before cross-layer resolution. If a static field wins, `/effort` reports that field instead of implying the requested tier is effective. When an effort tier wins, a conflicting `enable_thinking` is also dropped. An explicit `enable_thinking: false` in `extra_body` is honoured rather than dropped: it overrides the configured tier as `reasoning_effort: 'none'`, one of the few places `extra_body` does not win verbatim. Other Qwen models continue to map a selected effort to `enable_thinking: true`; a `reasoning_effort` override passes through there unless it conflicts with a `thinking_budget` (a pair DashScope rejects), in which case the inert `reasoning_effort` is dropped and both `enable_thinking` and `thinking_budget` survive. |
-| **OpenAI / DeepSeek** (`api.deepseek.com`)    | Flat `reasoning_effort: <effort>` body parameter                     | When `reasoning.effort` is set in the nested config shape, it's rewritten to flat `reasoning_effort` and `'low'`/`'medium'` are normalized to `'high'`, `'xhigh'` to `'max'` — mirroring DeepSeek's [server-side back-compat](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion). Top-level `samplingParams.reasoning_effort` or `extra_body.reasoning_effort` overrides skip this normalization and ship verbatim.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| **OpenAI** (other compatible servers)         | `reasoning: { effort, ... }` passed through verbatim                 | Set via `samplingParams` (e.g. `samplingParams.reasoning_effort` for GPT-5/o-series) when the provider expects a different shape.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **Anthropic** (real `api.anthropic.com`)      | `output_config: { effort }` plus the `effort-2025-11-24` beta header | Real Anthropic accepts `'low'`/`'medium'`/`'high'` only. `'max'` is **clamped to `'high'`** with a `debugLogger.warn` line (once per generator); if you want max effort, switch the baseURL to a DeepSeek-compatible endpoint that supports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| **Anthropic** (`api.deepseek.com/anthropic`)  | Same `output_config: { effort }` + beta header                       | `'max'` is passed through unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| **Gemini** (`@google/genai`)                  | `thinkingConfig: { includeThoughts: true, thinkingLevel }`           | `'low'` → `LOW`, `'high'`/`'max'` → `HIGH`, others → `THINKING_LEVEL_UNSPECIFIED` (Gemini has no `MAX` tier).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Protocol / provider                           | Wire shape                                                           | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **OpenAI / DashScope** (`qwen3.8-max` family) | Flat `reasoning_effort: <effort>` body parameter                     | The `/effort` tiers are passed through for any model id starting with `qwen3.8-max` (including dated snapshots and `-latest` aliases); DashScope applies any model-specific mapping. This family's ladder stops at `xhigh`, so a configured `max` is clamped to `xhigh` (logged once) rather than sent and rejected. An explicit `reasoning_effort` in `samplingParams` or `extra_body` is a verbatim override and is not clamped. When `reasoning_effort` and `thinking_budget` conflict, the normal `extra_body` > `samplingParams` > `reasoning` precedence keeps only the higher-priority field; an explicit same-layer pair keeps `reasoning_effort`, matching the provider's behavior before cross-layer resolution. If a static field wins, `/effort` reports that field instead of implying the requested tier is effective. When an effort tier wins, a conflicting `enable_thinking` is also dropped. An explicit `enable_thinking: false` in `extra_body` is honoured rather than dropped: it overrides the configured tier as `reasoning_effort: 'none'`, one of the few places `extra_body` does not win verbatim. Other Qwen models continue to map a selected effort to `enable_thinking: true`; a `reasoning_effort` override passes through there unless it conflicts with a `thinking_budget` (a pair DashScope rejects), in which case the inert `reasoning_effort` is dropped and both `enable_thinking` and `thinking_budget` survive. |
+| **OpenAI / DeepSeek** (`api.deepseek.com`)    | Flat `reasoning_effort: <effort>` body parameter                     | When `reasoning.effort` is set in the nested config shape, it's rewritten to flat `reasoning_effort` and `'low'`/`'medium'` are normalized to `'high'`, `'xhigh'` to `'max'` — mirroring DeepSeek's [server-side back-compat](https://api-docs.deepseek.com/zh-cn/api/create-chat-completion). Top-level `samplingParams.reasoning_effort` or `extra_body.reasoning_effort` overrides skip this normalization and ship verbatim. `max` is accepted only on a real DeepSeek hostname; a `deepseek`-named model on another host keeps the generic `xhigh` ceiling, matching the hostname gate on the reshape itself.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **OpenAI / Z.ai** (`z.ai`, `bigmodel.cn`)     | Flat `reasoning_effort: <effort>` body parameter                     | GLM-5.2+ on a Z.ai host takes the full ladder, `max` included, and the nested `reasoning.effort` is rewritten to the flat field. Older GLM ids, and a `glm-*` model reached on any other host, keep the generic `xhigh` ceiling: the model name alone says nothing about what that endpoint accepts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **OpenAI** (other compatible servers)         | `reasoning: { effort, ... }` passed through                          | A configured `max` is clamped to `xhigh` (logged once), since `max` is a vendor extension rather than part of the generic OpenAI ladder. Set via `samplingParams` (e.g. `samplingParams.reasoning_effort` for GPT-5/o-series) when the provider expects a different shape; an explicit `samplingParams` / `extra_body` value is not clamped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **Anthropic** (real `api.anthropic.com`)      | `output_config: { effort }` plus the `effort-2025-11-24` beta header | Real Anthropic accepts `'low'`/`'medium'`/`'high'` only. `'max'` is **clamped to `'high'`** with a `debugLogger.warn` line (once per generator); if you want max effort, switch the baseURL to a DeepSeek-compatible endpoint that supports it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Anthropic** (`api.deepseek.com/anthropic`)  | Same `output_config: { effort }` + beta header                       | `'max'` is passed through unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **Gemini** (`@google/genai`)                  | `thinkingConfig: { includeThoughts: true, thinkingLevel }`           | `'low'` → `LOW`, `'high'`/`'max'` → `HIGH`, others → `THINKING_LEVEL_UNSPECIFIED` (Gemini has no `MAX` tier).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ### `reasoning: false`
 
@@ -598,11 +657,13 @@ Setting `reasoning: false` (the literal boolean) explicitly disables thinking on
 
 On a `api.deepseek.com` baseURL, the OpenAI pipeline emits the explicit `thinking: { type: 'disabled' }` field that DeepSeek V4+ requires — the server-side default is `'enabled'`, so simply omitting `reasoning_effort` would still pay thinking latency/cost. Self-hosted DeepSeek backends (sglang/vllm) and other OpenAI-compatible servers do **not** receive this field; if you need to disable thinking on those, inject `thinking: { type: 'disabled' }` (or whatever knob your inference framework exposes) via `samplingParams`/`extra_body`.
 
+On an `openrouter.ai` baseURL, the OpenAI pipeline emits OpenRouter's provider-level `reasoning: { enabled: false }` field when reasoning is disabled. Other OpenAI-compatible servers do not receive this OpenRouter-specific field; use `samplingParams`/`extra_body` for their native disable knob.
+
 ### Interaction with `samplingParams` (OpenAI-compatible only)
 
 > [!warning]
 >
-> When `generationConfig.samplingParams` is set on an OpenAI-compatible provider, the pipeline ships those keys to the wire **verbatim** and skips the separate `reasoning` injection entirely. So a config like `{ samplingParams: { temperature: 0.5 }, reasoning: { effort: 'max' } }` will silently drop the reasoning field on OpenAI/DeepSeek requests.
+> When `generationConfig.samplingParams` is set on an OpenAI-compatible provider, the pipeline ships those keys to the wire **verbatim** and skips the separate `reasoning` injection entirely. So a config like `{ samplingParams: { temperature: 0.5 }, reasoning: { effort: 'max' } }` will silently drop the reasoning field on OpenAI/DeepSeek requests. A `reasoning` object placed inside `samplingParams` is your own value and ships unchanged: the effort ceiling above applies only to the tier the pipeline injects from `/effort`.
 >
 > DashScope Qwen models are an exception: their provider reads `reasoning` directly and maps it to `reasoning_effort` or `enable_thinking`. On the qwen3.8-max family, provider-specific `samplingParams` fields still take precedence when the wire parameters conflict; on older qwen hybrids, a configured effort tier collapses to `enable_thinking: true`, which overrides a `samplingParams.enable_thinking` value.
 >