@qwen-code/qwen-code 0.23.1-preview.2 → 0.23.2-preview.0

package/bundled/computer-use/SKILL.md

@@ -3,163 +3,236 @@ 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.
 ---
 
-# Computer Use with the CUA SDK
+## node_repl + @qwen-code/cua-sdk (Computer Use)
 
-- Prefer a dedicated connector or API. Use Computer Use only for UI state or
-  interactions the dedicated interface does not expose.
-- Perform Computer Use through `node_repl` and the typed `ComputerUse` API.
-  Do not use generic `callTool`, direct driver imports, AppleScript, JXA, or
-  synthesized-input utilities.
-- Observe the exact current window before acting. Prefer current element tokens
-  over screenshot coordinates; use coordinates only when accessibility is
-  incomplete and the screenshot provides the target.
-- Treat an action result as delivery evidence, not task completion. Decide from
-  fresh state and require stable postcondition evidence.
+- 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 (e.g. AppleScript, `osascript`, JXA, System Events, 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.
+- `node_repl` state is persistent across calls.
+- For text output, use `nodeRepl.write(...)`. `nodeRepl.write(...)` takes a string. If you would like to read a whole object, wrap it with `JSON.stringify(...)`.
 
-## Setup
+## Bootstrap
 
-If `node_repl` is unavailable, run these commands yourself:
+If `node_repl` is unavailable, run:
 
 ```bash
-qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.2
-npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.3
+qwen mcp add --scope user node-repl npx -y @qwen-code/node-repl-mcp@0.1.3
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.4
 ```
 
-Tell the user to restart Qwen Code, then stop. If only the SDK import is
-missing, run the second command and retry.
+Tell the user to restart Qwen Code, then stop. If only the SDK import is missing,
+run the second command and retry.
 
-Create one persistent client per REPL kernel:
+Import the `ComputerUse` API directly once per fresh `node_repl` session:
 
 ```js
 globalThis.computer = await (
   await import('@qwen-code/cua-sdk/computer-use')
 ).ComputerUse.create();
-globalThis.cuaRevisions ??= new Map();
 ```
 
-## Target and observe
+## API surface
 
-Use `listApps({signal:nodeRepl.signal})` and filter in JavaScript; print only
-likely matches. After selecting a real PID, call
-`listWindows({pid,signal:nodeRepl.signal})` and choose from returned
-metadata. Never guess a PID, window ID, element token, or coordinate. If the
-app is not running, start it with ordinary Node.js process APIs and refresh the
-lists.
+```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 ExactActionTarget = WindowTarget | ElementTarget;
+type DeliveryOptions = { deliveryMode?: DeliveryMode };
+
+type ComputerUse = {
+  click: (
+    args: PointOrElementTarget &
+      DeliveryOptions & { button?: MouseButton; count?: number },
+  ) => Promise<object>;
+  doubleClick: (
+    args: PointOrElementTarget & DeliveryOptions,
+  ) => Promise<object>;
+  rightClick: (
+    args: PointOrElementTarget & DeliveryOptions & { modifier?: string[] },
+  ) => Promise<object>;
+  drag: (
+    args: WindowTarget &
+      DeliveryOptions & {
+        fromX: number;
+        fromY: number;
+        toX: number;
+        toY: number;
+      },
+  ) => Promise<object>;
+  observeWindow: (
+    args: WindowTarget & { disableDiff?: boolean; includeScreenshot?: boolean },
+  ) => Promise<WindowObservation>;
+  listApps: () => Promise<Array<App>>;
+  listWindows: (args: { pid: number }) => Promise<Array<Window>>;
+  performSecondaryAction: (
+    args: ElementTarget & { action: string },
+  ) => Promise<object>;
+  pressKey: (
+    args: ExactActionTarget &
+      DeliveryOptions & { key: string; modifiers?: string[] },
+  ) => Promise<object>;
+  hotkey: (
+    args: ExactActionTarget & DeliveryOptions & { keys: string[] },
+  ) => Promise<object>;
+  scroll: (
+    args: PointOrElementTarget &
+      DeliveryOptions & { direction: Direction; amount?: number },
+  ) => Promise<object>;
+  setValue: (args: ElementTarget & { value: string }) => Promise<object>;
+  typeText: (
+    args: ExactActionTarget & DeliveryOptions & { text: string },
+  ) => Promise<object>;
+  close: () => Promise<void>;
+};
+
+type App = {
+  name?: string;
+  bundle_id?: string;
+  pid?: number;
+  running?: boolean;
+  launch_path?: string;
+};
 
-Maintain one revision cursor per window surface. The first observation has no
-base; later observations use only the last revision actually consumed for that
-same surface:
+type Window = {
+  window_id: number;
+  title?: string;
+  is_on_screen?: boolean;
+  on_current_space?: boolean;
+};
 
-```js
-globalThis.observeCuaWindow = async (target, options = {}) => {
-  const key = `${target.pid}:${target.windowId}`;
-  const state = await computer.observeWindow({
-    ...target,
-    ...options,
-    baseRevisionId: cuaRevisions.get(key),
-    signal: nodeRepl.signal,
-  });
-  if (state.revisionId) cuaRevisions.set(key, state.revisionId);
-  return state;
+type WindowObservation = {
+  pid: number;
+  windowId: number;
+  mode: 'full' | 'diff' | 'no_change';
+  resyncReason?: string;
+  text: string;
+  elements: Array<Element>;
+  screenshot?: Screenshot;
 };
+
+type Element = {
+  element_token?: string;
+  role?: string;
+  label?: string;
+  automation_id?: string;
+  value?: unknown;
+  actions?: string[];
+};
+
+type Screenshot = {
+  images: Array<{ mimeType: string; dataBase64: string }>;
+};
+
+type Direction = 'up' | 'down' | 'left' | 'right';
+type MouseButton = 'left' | 'right' | 'middle';
+type DeliveryMode = 'background' | 'foreground';
+```
+
+## Workflow
+
+### 1. Initialize
+
+Start by getting the state for the app and window you want to use. When the task
+names an app, filter for that name directly:
+
+```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));
+
+var windows = await computer.listWindows({ pid: matches[0].pid });
+var target = { pid: matches[0].pid, windowId: windows[0].window_id };
+var state = await computer.observeWindow(target);
+nodeRepl.write(state.text); // This will return the accessibility tree
 ```
 
-Use accessibility text for efficient decisions. Request a screenshot when the
-tree is incomplete, visual layout matters, or action evidence conflicts with
-the tree. Emit only decision-relevant images:
+If you cannot identify an app from the task, prior context, or builtin apps,
+start by discovering the available apps:
 
 ```js
-for (const image of state.screenshot?.images ?? []) {
-  if (image?.dataBase64 && image?.mimeType) {
-    await nodeRepl.emitImage(
-      `data:${image.mimeType};base64,${image.dataBase64}`,
-    );
-  }
-}
+var apps = await computer.listApps();
+nodeRepl.write(JSON.stringify(apps));
 ```
 
-If the SDK explicitly reports a missing/invalid base or a stale lineage,
-perform one observation with `forceFull: true`, replace that surface's cursor,
-then resume the normal helper. Do not make full observations the default.
+After performing one or more UI actions, call `observeWindow(...)` before
+deciding what to do next. This keeps you in the current UI state. Read the
+current actionable `element_token` values from `state.elements`; tokens for
+unchanged elements remain valid across `diff` and `no_change` observations.
 
-## Act and verify
+For token efficiency, when appropriate, the accessibility tree will be returned
+as a diff from the most previous accessibility tree, listing only the elements
+that were removed, added, or changed. Prefer this default diff output; pass
+`disableDiff: true` only when you need a fresh full accessibility tree. If you
+disregard the text from a previous call to `observeWindow`, such as when you only
+emit the screenshot, get the full tree next time you inspect AX text.
+`state.elements` remains the current full actionable element list when
+`state.text` is a diff or reports no change.
 
-Choose the narrowest action supported by current state. Pass an observed
-`element_token` as `elementToken`. Use `performSecondaryAction` only when that
-exact action appears in the element's current `actions` list.
+### 2. Actions using app
 
-Before acting, state a concrete observable postcondition. For postconditions
-expressible as window or element state, use `actAndVerify` with `verifyState`:
+Perform one or more actions, and then fetch the latest state:
 
 ```js
-try {
-  globalThis.lastCuaOutcome = await computer.actAndVerify({
-    action: () =>
-      computer.setValue({
-        ...target,
-        elementToken,
-        value: expectedValue,
-        signal: nodeRepl.signal,
-      }),
-    verify: () =>
-      computer.verifyState({
-        ...target,
-        expect: [
-          {
-            element: {
-              selector: { role: expectedRole, label_contains: expectedLabel },
-              value_equals: expectedValue,
-            },
-          },
-        ],
-        stableSamples: 2,
-        signal: nodeRepl.signal,
-      }),
-  });
-  nodeRepl.write(JSON.stringify(lastCuaOutcome));
-} catch (error) {
-  nodeRepl.write(JSON.stringify(error?.details ?? { message: String(error) }));
-  throw error;
-}
+await computer.click({ pid: target.pid, elementToken });
+await computer.setValue({ pid: target.pid, elementToken, value: 'openai.com' });
+await computer.pressKey({ ...target, key: 'Enter' });
+await computer.typeText({ ...target, text: 'hello' });
+await computer.scroll({
+  pid: target.pid,
+  elementToken,
+  direction: 'down',
+  amount: 1,
+});
+await computer.performSecondaryAction({
+  pid: target.pid,
+  elementToken,
+  action: 'Show Menu',
+});
+nodeRepl.write((await computer.observeWindow(target)).text);
 ```
 
-`verifyState.expect` accepts one to eight AND-combined predicates:
+Notes:
 
-- `{window:{exists, bounds?}}`
-- `{element:{selector:{role?, label_contains?}, exists:true?,
-value_equals?, enabled?, selected?}}`
+- Prefer `element_token`-based actions over coordinate actions. If AX actions or AX text are unavailable or behave unexpectedly, switch to screenshots, coordinate clicks, and key presses.
+- `doubleClick` and `rightClick` invoke their dedicated SDK actions; `rightClick` also accepts optional modifiers.
+- If the UI is not behaving as expected, try fetching the latest `observeWindow(...)` state to make sure you have the latest context.
+- Prefer using accessibility text over screenshots for efficiency, but if the interface is not fully working or not providing enough context, make sure to fetch a screenshot to get more context. The accessibility interface may be incomplete in some applications, so a screenshot helps fully understand what is going on.
+- `performSecondaryAction` invokes an accessibility action that an element exposes besides a normal click, such as expanding a disclosure row, showing a menu, incrementing a control, or cancelling something. It requires an action actually exposed for that element in the accessibility text. Do not guess action names.
+- `pressKey` presses one key and accepts optional modifiers; `hotkey` sends a key combination such as `{ keys: ['ctrl', 'c'] }`. Single-key examples include `"a"`, `"Enter"`, `"Tab"`, and `"Up"`.
+- Take care when passing strings containing `\n` or `\r` to `typeText`, as it simulates pressing the return key. Many apps with message composers or forms will respond by sending the message or submitting the form rather than inserting a newline.
+- The SDK targets an exact PID and window ID. If an action opens a dialog, menu, or new window, call `listWindows({ pid })` again and select the current window before continuing.
 
-Element absence is not provable. `unknown` and `stable:false` are not success.
-When the postcondition is visual or unsupported, observe the exact window
-again with a screenshot and inspect the fresh result before deciding. If state
-is unexpected, observe again rather than repeating the action blindly.
+## Reading screenshots
 
-Read every action result. `effect` is `confirmed`, `partial`, `unverifiable`,
-`suspected_noop`, or `refused`; `route`, `delivery`, `evidence`, `escalation`,
-and `operation` explain what actually happened. A committed operation can
-still have `cancellationRequested:true`, so it still requires verification.
-Follow an advertised escalation only after fresh state shows it is needed.
+Request a screenshot with the observation, read its accessibility text, and
+emit each returned image:
 
-## Interaction details
+`includeScreenshot: true` is the parameter that requests a screenshot.
 
-- After navigation, dialogs, menus, or other surface changes, refresh the
-  relevant window list and observe the new exact surface.
-- Use returned state to determine text-field behavior; do not assume typing
-  replaces existing text. Use the platform-appropriate select-all action when
-  replacement is required.
-- Prefer background delivery. Use `deliveryMode:'foreground'` only when the
-  action result or fresh state shows the background route is unavailable or
-  ineffective.
-- Stop as soon as the requested postcondition is stably satisfied. Do not add
-  extra cleanup actions that could undo the result.
+```js
+var state = await computer.observeWindow({
+  ...target,
+  includeScreenshot: true,
+});
+nodeRepl.write(state.text);
+for (const image of state.screenshot?.images ?? []) {
+  await nodeRepl.emitImage(`data:${image.mimeType};base64,${image.dataBase64}`);
+}
+```
 
-## Finish
+When all Computer Use work is complete:
 
 ```js
 await computer.close();
 globalThis.computer = undefined;
-globalThis.cuaRevisions = undefined;
-globalThis.observeCuaWindow = undefined;
 ```
 
-Reset the REPL only when no other persistent state is needed.
+Reset the Node REPL only when no other persistent state is needed.

package/bundled/goal-draft/SKILL.md

@@ -13,7 +13,7 @@ allowedTools:
 
 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.
+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. Deliver a concise objective for approval or a command the user can run; if essential information is missing, deliver only a draft marked "Needs clarification".
 
 ## How Goals are judged (why the format below matters)
 
@@ -32,12 +32,14 @@ Say no, briefly, when the request is a normal one-shot task, needs a design or p
 
 ## 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.
+Call `get_goal`. If a Goal is active, preserve the user's explicit choice to edit it (same goal, tighter wording → `/goal edit`) or replace it (`/goal set`). If that choice is unclear, include it in Step 3's single round of questions; do not choose on the user's behalf. 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.
 
+Read only what is needed to establish the scope and verification path. Stop exploring once those are grounded; do not audit the implementation, reproduce failures, run builds or tests, install dependencies, or start services while drafting. A requested new output file is a proposed destination, not evidence that the file already exists.
+
 ## 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:
@@ -54,7 +56,7 @@ Rules for the questions:
 - 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.
+If you cannot ask (headless, or a client without prompts), use a recommended default only for nonessential choices and mark it `[ASSUMPTION]` in Context. An unknown success criterion, unverified command or input path, or unresolved edit-versus-replace choice stays `<TODO: …>`; do not invent an answer just to finish the hand-off. If essential information is still missing after the single question round, keep the draft incomplete rather than starting another round.
 
 ## Step 4 — draft the objective
 
@@ -64,7 +66,7 @@ Use exactly these labels, in this order. Keep the whole objective on one line wh
 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
+Budget: <user's stopping agreement; otherwise stop as blocked after 20 turns, and mark that default [ASSUMPTION] in Context>
 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>
 ```
@@ -72,19 +74,24 @@ Context: <only facts the agent cannot derive: paths, branch, environment, earlie
 Rules of thumb:
 
 - One Outcome. Several outcomes = several goals, or a checklist file plus a single "every item in `<file>` is checked" goal.
+- Usually 3–5 Done-when checks suffice; use fewer when enough. Do not add checks just to reach a count, and preserve explicit user requirements.
 - 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).
+- For audits and exploratory work, agree on bounded coverage and require evidence for each conclusion. Zero defects is a valid result: never require a positive defect count. Do not invent minimum scenario counts, evidence-file counts, or exploration-round quotas; include them only when the user requested them.
 - 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.
+- `Budget` is a stopping agreement for the model, not a runtime-enforced turn or wall-clock limit. Do not claim that writing it configures a timer or changes the Goal token budget. Preserve a user-specified budget; otherwise mark the default `[ASSUMPTION]` in Context.
+
+For example, an audit's Done-when checks can require a report covering the agreed scenarios, observed results and evidence for each scenario, and reproduction steps for each confirmed defect (or an explicit "no confirmed defects" result). Ground the scenarios and report destination before offering the objective for use.
 
 ### 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.                                                                                                                                             |
+| 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. Context: [ASSUMPTION] the 20-turn budget is the drafter's default, not the user's. |
+| 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
 
@@ -96,18 +103,21 @@ Check every line before printing:
 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>`.
+7. Every path and command in Context was verified in the workspace; an unverified path or command is essential and stays `<TODO: …>`.
 8. Under ~1200 characters.
 9. Irreversible actions (push, delete, publish) are listed in Must not, or the user explicitly allowed them.
+10. No invented coverage quotas, required defect findings, or claims that a prose budget is enforced by the runtime; an unrequested default Budget is marked `[ASSUMPTION]` in Context.
+
+**If an essential item remains unresolved — an unknown success criterion, an unverified command or input path, or an unresolved edit-versus-replace choice (each written as `<TODO: …>`) —**, print only a draft marked "Needs clarification" (in the user's language) and briefly list what is missing. Do not call `propose_goal` or print a runnable `/goal set` or `/goal edit` line. Stop here; the ready-objective hand-off below does not apply.
 
 Then hand off, and nothing else:
 
 **If the `propose_goal` tool is available and no Goal is active**, call it with the objective on one line. The user approves or declines it in a dialog; only their approval sets the Goal. If they decline you will not be told why: stop, do not ask about it, and do not propose the same or a reworded objective again. After approval, acknowledge it in one sentence and end the turn — the Goal runtime starts the first Goal turn on its own.
 
-**Otherwise** (headless, the tool is disabled, or a Goal is active), print:
+**Otherwise** (Web Shell or another ACP client, headless, the tool is disabled, or a Goal is active), print:
 
 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.
+3. One sentence explaining that the draft has not been applied and the user must run the command to apply it; include any `[ASSUMPTION]` items. Do not promise a dialog in Web Shell or other ACP sessions.
 
 Do not run /goal yourself. Do not begin the task. Stop and wait for the user.

package/bundled/qc-helper/docs/_meta.ts

@@ -16,6 +16,7 @@ export default {
   'integration-github-action': 'GitHub Actions',
   'qwen-serve': 'Daemon mode (qwen serve)',
   'qwen-serve-deploy-local': 'Daemon mode — local launch templates',
+  'conversations-recovery': 'Conversations writer locks and recovery',
   'Code with Qwen Code': {
     type: 'separator',
     title: 'Code with Qwen Code', // Title is optional

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

@@ -568,12 +568,58 @@ The configuration resolution follows a strict layering model with one crucial ru
 | 3        | `settings.model.generationConfig`             | Only used for **Runtime Models** (when no provider model is selected)                                    |
 | 4        | Content-generator defaults                    | Provider-specific defaults (e.g., OpenAI vs Gemini) - only for Runtime Models                            |
 
+### Dynamic values in `customHeaders`
+
+A `customHeaders` value may contain the placeholder `${session_id}`, which is
+expanded per request with the current Qwen Code session ID. Use it for gateways
+that require a stable per-conversation identifier — OpenCode Go, for example,
+rejects requests without `x-opencode-session`:
+
+```json
+{
+  "generationConfig": {
+    "customHeaders": {
+      "x-opencode-session": "${session_id}"
+    }
+  }
+}
+```
+
+Because the value is resolved per request rather than baked into the SDK client,
+`/new` and `/resume` rotate it without a restart.
+
+⚠️ **Two steps are required.** The provider entry above is only half of it — a
+placeholder is inert until you also switch on
+[`outboundCorrelation.allowDynamicHeaderValues`](settings.md#outboundcorrelation):
+
+```json
+{
+  "outboundCorrelation": {
+    "allowDynamicHeaderValues": true
+  }
+}
+```
+
+Until you do, a value containing a placeholder is **dropped** rather than sent,
+and Qwen Code prints a warning at startup naming the header and this setting.
+The header is never sent with a literal `${session_id}` in it.
+
+The switch is global because it is a consent decision, separate from _where_ the
+value goes: an expanded value carries live session state to whoever receives it,
+and the switch controls only whether `${session_id}` may be expanded. It does not
+identify which settings source supplied the header.
+
+**Privacy note:** the session ID is a stable identifier for the life of a
+conversation, so any host you send it to can group every request of that
+conversation. Which hosts those are is decided by which provider entries carry
+the header — there is no separate host list to keep in sync with your `baseUrl`.
+
 ### Atomic field treatment
 
 The following fields are treated as atomic objects - provider values completely replace the entire object, no merging occurs:
 
 - `samplingParams` - Temperature, top_p, max_tokens, etc.
-- `customHeaders` - Custom HTTP headers
+- `customHeaders` - Custom HTTP headers (may contain `${session_id}`; see [Dynamic values](#dynamic-values-in-customheaders))
 - `extra_body` - Extra request body parameters
 
 ### Example

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

@@ -181,6 +181,7 @@ These settings are read from operator scopes only (User, System, and SystemDefau
 | `model.maxSessionTurns`                            | integer | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `-1`        |
 | `model.maxWallTimeSeconds`                         | number  | Wall-clock budget for headless / unattended runs, in seconds. `-1` means unlimited. Overridable per-invocation via `--max-wall-time`, which requires a positive duration (`90`, `30s`, `5m`, `1h`, `1.5h`); the minimum is 1 second — sub-second values (`500ms`, `0.5`) are rejected as typos. Omit the flag to fall back to this setting. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `-1`        |
 | `model.goalTokenBudget`                            | integer | Autonomous spend window armed on each new Goal, in tokens as counted by the Goal meter (`totalTokenCount` summed over the model calls the Goal makes in its own turns). A Goal that spends its window gets one wind-down turn to hand off, then stops until you resume it, which arms another window. Unset uses the built-in default of 30,000,000; `-1` means unlimited. Zero, values above 300,000,000 (10x the default, a typo guard), other negative, fractional, or non-number values are rejected at startup.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `30000000`  |
+| `model.goalCheckpointTimeoutSeconds`               | integer | Ceiling on one Goal evidence-checkpoint call, in seconds. A long Goal periodically compresses its evidence into checkpoint claims with a side model call; a call that does not finish in time is abandoned as an inconclusive check — the checkpoint stall streak is preserved rather than incremented — and a later turn retries it. Unset uses the built-in default of 180. Must be an integer between 1 and 900; other values are rejected at startup. The call is streamed, so the per-request transport timeout (`model.generationConfig.timeout`, default 120 s) bounds only connect and first response, and values above 900 are rejected because past the default stream lifetime guard that guard, not this setting, ends the call. The 900 ceiling is fixed: raising `QWEN_STREAM_MAX_LIFETIME_MS` does not lift it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `180`       |
 | `model.maxToolCalls`                               | number  | Cumulative tool-call budget for a run (counts every executed tool, success or failure; `structured_output` under `--json-schema` is exempt). `-1` means unlimited; `0` means "no tool calls allowed". Capped at 1,000,000 to catch typos. Overridable via `--max-tool-calls`. Aborts with exit code 55 when exceeded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `-1`        |
 | `model.maxSubagentDepth`                           | number  | Maximum sub-agent nesting depth (1-based levels: a top-level sub-agent is level 1). `1` keeps sub-agents available but disables nesting — the pre-nesting behavior. Values clamp to the range 1–100; non-finite values fall back to the default. Teammates, forks, and workflow-spawned agents never nest regardless of this setting. Overridable via `--max-subagent-depth`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `5`         |
 | `model.generationConfig`                           | object  | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `retryInitialDelayMs`, `retryMaxDelayMs`, `enableCacheControl`, `splitToolMedia` (default `true`; splits tool-returned media — including images read by the built-in read_file — into a follow-up user message instead of the spec-violating `role: "tool"` message, so strict OpenAI-compatible servers like doubao / new-api / LM Studio can see it; set `false` to restore the legacy embed-in-tool behavior), `toolResultContentFormat` (default `"parts"`; set `"string"` only for legacy OpenAI-compatible runtimes whose tool templates ignore text content parts), `contextWindowSize` (override model's context window size), `modalities` (override auto-detected input modalities), `customHeaders` (custom HTTP headers for API requests), and `extra_body` (additional body parameters for OpenAI-compatible API requests only), along with fine-tuning knobs under `samplingParams` (for example `temperature`, `top_p`, `max_tokens`). Leave unset to rely on provider defaults.                                                                                                                                                                                                                | `undefined` |
@@ -661,6 +662,38 @@ Configures logging and metrics collection for Qwen Code. For more information, s
 | `telemetry.sensitiveSpanAttributeMaxLength` | number  | Maximum JavaScript string length for each sensitive native OTel span attribute content payload. Must be between `1` and `104857600` (100 MiB). Set lower if your collector or backend rejects large attributes.                                                                          | `1048576` |
 | `telemetry.outfile`                         | string  | Path to write telemetry to a file. When set, overrides OTLP export.                                                                                                                                                                                                                      |           |
 
+#### outboundCorrelation
+
+⚠️ **Security-relevant.** Controls what client-side correlation data Qwen Code writes into outbound LLM API requests — a separate consent decision from `telemetry.*`, which governs data flowing into your OWN observability backend. All values default to off.
+
+| Setting                                        | Type    | Description                                                                                                                                                     | Default |
+| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `outboundCorrelation.propagateTraceContext`    | boolean | Inject W3C `traceparent` on outbound `fetch` requests and as a `TRACEPARENT` env var in shell child processes. Requires `telemetry.enabled: true`.              | `false` |
+| `outboundCorrelation.allowDynamicHeaderValues` | boolean | Allow `customHeaders` values to contain runtime placeholders such as `${session_id}`, expanded per request. When off, such a value is dropped rather than sent. | `false` |
+
+```json
+{
+  "outboundCorrelation": {
+    "allowDynamicHeaderValues": true
+  }
+}
+```
+
+`allowDynamicHeaderValues` is only the consent switch. _Which_ hosts receive the
+value and _what_ the header is called are decided where the header lives —
+`modelProviders[].generationConfig.customHeaders`, see
+[Dynamic values in `customHeaders`](model-providers.md#dynamic-values-in-customheaders).
+That scoping is why there is no host allowlist here: you already chose the
+endpoint when you wrote the provider's `baseUrl`, and providers that should not
+send the header simply do not carry it.
+
+If a provider entry has a placeholder while this is off, the header is dropped
+and a warning naming both is printed at startup — so a gateway rejecting your
+requests should never be a silent mystery.
+
+**Privacy note:** an expanded value is a stable per-conversation identifier.
+Only put one on a provider you already send your prompt content to.
+
 ### Example `settings.json`
 
 Here is an example of a `settings.json` file with the nested structure, new as of v0.3.0:
@@ -791,6 +824,23 @@ When both user-level `.env` files define the same variable, the Qwen-specific
 file wins: `<QWEN_HOME>/.env` (or `~/.qwen/.env` when `QWEN_HOME` is unset) is
 loaded before `~/.env`, and existing environment values are not overwritten.
 
+### Standalone update download source
+
+Set `QWEN_UPDATE_BASE_URL` to use a custom HTTPS release root for standalone updates:
+
+```bash
+export QWEN_UPDATE_BASE_URL="https://downloads.example.com/qwen-code"
+qwen update
+```
+
+For version `0.23.0`, the updater downloads the platform archive, `SHA256SUMS`, and `SHA256SUMS.sig` from `<base-url>/v0.23.0/`. Host these files using the same names and directory layout as an official release. Existing checksum and signature checks still apply, including `QWEN_REQUIRE_SIGNATURE=1` when a signature is required.
+
+The URL must use HTTPS and cannot contain credentials, a query string, or a fragment. Surrounding whitespace and trailing slashes are removed. An empty or whitespace-only value preserves the built-in download sources and their fallback order. When a custom root is set, a failed download does not fall back to the built-in sources.
+
+Configure this variable in the launching shell or a user-level `.env` file. It is rejected from project `.env` and `.qwen/.env` files and from the top-level `settings.json` `env` section at every scope. A user-level `.env` value is loaded at startup; restart Qwen Code after changing it.
+
+This setting applies to `qwen update`, `/update`, and automatic standalone updates. It does not change npm registry version discovery. It is separate from the installer's `QWEN_INSTALL_BASE_URL`, which points directly to a version-specific directory.
+
 ## Command-Line Arguments
 
 Arguments passed directly when running the CLI can override other configurations for that specific session.