@qwen-code/qwen-code 0.22.0 → 0.22.2-nightly.20260828.7357136dd1

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/goal-draft/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: goal-draft
+description: Turn a fuzzy intention into a /goal objective the Goal verifier can actually judge - one outcome, numbered binary "Done when" checks that leave evidence in the transcript, guardrails, a budget, and a block protocol. Use when the user wants to set or define a goal, asks whether a goal is good enough, or says "keep going until X". Usage - /goal-draft <what you want done>, or /goal-draft <existing goal> to tighten it. This skill only writes the objective; it never starts the work.
+argument-hint: '[intent, or an existing goal to tighten]'
+allowedTools:
+  - get_goal
+  - read_file
+  - glob
+  - grep_search
+---
+
+# /goal-draft — write a Goal the verifier can judge
+
+You are already inside the loaded `goal-draft` skill — do not call the `skill` tool to invoke it again; start with Step 0.
+
+You are drafting the text for `/goal set`. You are NOT doing the work the goal describes. Do not edit files, do not run the checks, do not start on the task. The only deliverable is the objective text and the `/goal set` line the user can run.
+
+## How Goals are judged (why the format below matters)
+
+An active Goal is re-fed to the model every turn, and its completion is judged by an independent verifier that sees ONLY transcript evidence:
+
+- Visible assistant output and tool results count as evidence. The objective itself, user prompts, and hidden reasoning do not.
+- `delivered_output` evidence proves only that text was printed. It cannot prove that tests passed, files changed, or remote state changed — those need a tool result in the transcript (an `external_fact`).
+- A claim that the user confirmed, chose, or approved something needs a real user message as evidence; otherwise the completion proposal is rejected.
+- Vague, subjective, or open-ended conditions never accumulate enough evidence; the loop then runs until a limit is hit.
+
+So a good objective makes the agent PRODUCE evidence: run the named check and paste the decisive output line.
+
+## Step 0 — should this be a Goal at all?
+
+Say no, briefly, when the request is a normal one-shot task, needs a design or product judgement call, or has no way to be checked from the agent's own output. Offer to just do it, or to write a plan instead. A goal that cannot be checked is a prompt, not a goal.
+
+## Step 1 — check the active Goal
+
+Call `get_goal`. If a Goal is active, ask whether to edit it (same goal, tighter wording → `/goal edit`) or replace it (`/goal set`). Never draft a second concurrent goal.
+
+## Step 2 — ground the draft in the workspace
+
+Before asking anything, verify what you can with `read_file`, `glob`, and `grep_search`: that named files and packages exist, and what the real check commands are (`package.json` scripts, `Makefile`, CI workflow, test config). Use those exact commands in "Done when". Never invent paths, IDs, or commands; write `<TODO: …>` for anything you cannot confirm.
+
+## Step 3 — at most one round of questions
+
+Ask with `ask_user_question`, 1–3 questions in one call, each with options and a recommended default. Ask only when the answer changes the check, the scope, or the budget. Typical questions:
+
+- Which check defines success: a test command, a build, a metric threshold, a file or state assertion?
+- Which environment: local, CI, staging?
+- What is off limits: which files, which actions (push, delete, publish)?
+- How long to try before stopping as blocked?
+
+Rules for the questions:
+
+- Never ask what you could find out by reading the workspace.
+- Batch them into one `ask_user_question` call; do not drip one per turn.
+- Only ask things only the user can answer: what counts as done, what is off limits, how long to try.
+- If you cannot find a concrete way to verify the outcome, you MUST ask, offering 2–3 candidate checks. Do not skip this and do not invent one.
+
+If you cannot ask (headless, or a client without prompts), take the recommended default and mark it `[ASSUMPTION]` in Context.
+
+## Step 4 — draft the objective
+
+Use exactly these labels, in this order. Keep the whole objective on one line when you hand it over — the `/goal` parser joins lines with spaces, so number items instead of relying on newlines. Body text follows the user's language; labels stay English so the verifier can match them.
+
+```text
+Outcome: <one sentence: what is true when done>
+Done when: 1) <command> exits 0 and its output shows <…> (paste that line); 2) <file/state assertion provable via read or grep>; 3) …
+Must not: <files not to touch; tests/thresholds not to weaken; irreversible actions not to take>
+Budget: stop as blocked after <N> turns (default 20) or <M> minutes without measurable progress
+On block: propose blocked with the exact blocker and the decision a human must make; never claim completion without evidence for every Done-when item
+Context: <only facts the agent cannot derive: paths, branch, environment, earlier decisions>
+```
+
+Rules of thumb:
+
+- One Outcome. Several outcomes = several goals, or a checklist file plus a single "every item in `<file>` is checked" goal.
+- Every Done-when item is binary, and at least one is tool-observable (a command with an exit code or output line, a file that exists, a grep that matches).
+- Prefer "the smallest safe change in `<scope>`" over open-ended refactors.
+- Put anything that must not change on the way into Must not — this is what stops the loop from deleting a failing test to "pass".
+- Keep it short: everything the agent can derive from the workspace stays out. Aim for under ~1200 characters.
+
+### Weak → strong
+
+| Weak                          | Strong                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| make checkout faster          | Outcome: checkout API p95 is below 250 ms on the documented slow path. Done when: 1) `npm run bench:checkout` exits 0 and prints a p95 below 250 (paste the line); 2) `npm test` exits 0. Must not: change the benchmark, skip tests, touch files outside `src/checkout`. Budget: stop as blocked after 20 turns. On block: report the measured p95 and what blocks it.                          |
+| keep handling the PR comments | Outcome: every unresolved review thread on PR #123 is fixed or answered. Done when: 1) the review-threads query shows zero unresolved threads (paste the count); 2) CI on the head commit is green (paste the check summary). Must not: force-push, resolve a thread without replying to it. Budget: stop as blocked after 30 turns. On block: list the threads that need a maintainer decision. |
+| clean up the auth module      | Not a goal — "clean" has no check. Ask what would be observable (zero lint warnings in `src/auth`? a file count? a coverage threshold?) or offer a refactor plan instead.                                                                                                                                                                                                                        |
+| get the release out           | Not a goal as written — publishing is irreversible. Either narrow it to a checkable pre-release state (tag exists, changelog entry present, `npm run release:dry-run` exits 0) and put "do not publish" in Must not, or leave publishing to a human.                                                                                                                                             |
+
+## Step 5 — self-check, then hand off
+
+Check every line before printing:
+
+1. "Done when" exists, its items are numbered, and each is binary.
+2. At least one item names a command, exit code, file, or grep pattern and asks to paste the output.
+3. No subjective adjectives as conditions (clean, better, robust, elegant, reasonable, …).
+4. No "after the user confirms/approves" as a completion condition — that belongs in On block as a decision a human must make.
+5. Budget or On block is present.
+6. Exactly one Outcome.
+7. Every path and command in Context was verified in the workspace or is marked `<TODO>`.
+8. Under ~1200 characters.
+9. Irreversible actions (push, delete, publish) are listed in Must not, or the user explicitly allowed them.
+
+Then print, and nothing else:
+
+1. The objective in a fenced code block.
+2. One line the user can run as-is: `/goal set <objective on one line>` (or `/goal edit …` when tightening the active goal). Print it as plain text with no code markers, so it can be copied verbatim.
+3. One sentence on what you assumed (`[ASSUMPTION]` / `<TODO>` items), if any.
+
+Do not run /goal yourself. Do not begin the task. Stop and wait for the user.

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.
 >