@qwen-code/qwen-code 0.23.1 → 0.23.2-nightly.20260909.2e212144d3

package/bundled/qc-helper/docs/features/computer-use.md

@@ -26,7 +26,7 @@ When first used, the skill runs these commands itself:
 
 ```bash
 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
+npm install --no-save --package-lock=false @qwen-code/cua-sdk@0.20.5
 ```
 
 Restart Qwen Code after the MCP server is first added. The skill then resumes

package/bundled/qc-helper/docs/features/cross-session-protocol.md

@@ -0,0 +1,291 @@
+# Cross-Session Protocol
+
+This page is the contract for a program that wants to take part in
+cross-session messaging without being a Qwen Code session: a voice
+front-end, a relay daemon, a script that watches a build. It describes
+what a session writes to the registry, what its inbox reads off a
+connection, and what it sends back. Everything here is what the code
+does today at schema version 1 and frame version 1; the last section
+says what may change and how you will know.
+
+Every value that crosses a process boundary is untrusted on arrival and
+validated by the reader. Where this page says a field "must" have some
+shape, a value that does not is dropped, never rejected with an error.
+
+## 1. The session registry
+
+A running session publishes one record:
+
+```
+$QWEN_HOME/sessions/<pid>.json        (directory 0700, file 0600)
+```
+
+`$QWEN_HOME` defaults to `~/.qwen`. The file name is the writer's PID
+and nothing else; a record whose `pid` field disagrees with its file
+name is ignored.
+
+```json
+{
+  "schemaVersion": 1,
+  "pid": 41337,
+  "procStart": "a1b2c3d4-…-boot-uuid:8895124",
+  "pidNs": 4026531836,
+  "sessionId": "8e016be8-5b48-4c13-ad22-1f5326ae64ac",
+  "cwd": "/home/me/project",
+  "name": "project-3f",
+  "startedAt": 1788959000000,
+  "qwenVersion": "0.23.0",
+  "kind": "tui",
+  "ipcPath": "/run/user/1000/qwen-socks/41337.sock",
+  "ipcToken": "c0ffee…64 hex…"
+}
+```
+
+| Field           | Meaning                                                                                                                                                                                                                                                                                               |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schemaVersion` | Always `1`. A reader skips a record with a higher version and never deletes it.                                                                                                                                                                                                                       |
+| `pid`           | The writer's process id. Must equal the file name.                                                                                                                                                                                                                                                    |
+| `procStart`     | `<boot id>:<process start ticks>` on Linux (`/proc/sys/kernel/random/boot_id` and field 22 of `/proc/<pid>/stat`); `null` elsewhere. Guards against PID reuse, and against records written on another machine that shares this home directory.                                                        |
+| `pidNs`         | Inode number of `/proc/self/ns/pid` on Linux; `null` elsewhere. A reader only lists and sweeps records from its own namespace.                                                                                                                                                                        |
+| `sessionId`     | The session's id. `/clear` and `/resume` swap it under the same PID, so re-read the record before each send.                                                                                                                                                                                          |
+| `cwd`           | Working directory at registration.                                                                                                                                                                                                                                                                    |
+| `name`          | Display name. Derived from the cwd basename (Unicode letters, marks, digits, `.`, `_`, `-`; up to 32 code points) plus `-` and the first two hex characters of `sha256(sessionId)`, unless the writer chose one. Not unique.                                                                          |
+| `startedAt`     | Epoch milliseconds. Newest first is the listing order and the tie-break between twins.                                                                                                                                                                                                                |
+| `qwenVersion`   | Free text or `null`.                                                                                                                                                                                                                                                                                  |
+| `kind`          | What registered: `tui` (someone at a terminal), `headless`, `serve`, `external`. Lowercase ASCII, digits and dashes, at most 16 characters; anything else is dropped on read. Absent means a writer older than the field, which reads as `tui`. A label for listings — never a credential; see below. |
+| `ipcPath`       | The inbox socket, present only while it is bound. Absent means discoverable but not messageable.                                                                                                                                                                                                      |
+| `ipcToken`      | 64 hex characters. What a connection to `ipcPath` presents on its auth line. Absent means the inbox requires none (records from older builds).                                                                                                                                                        |
+
+**A record is a self-report.** Every field in it was written by the
+process it describes, so `name`, `cwd` and `kind` are claims, not facts a
+reader can lean on. Nothing that decides what a sender may do reads
+them — that is settled by what a connection presents (§3) and by the
+receiving session's own policy (§6). Set `kind` so a listing can group
+sessions honestly; do not expect it to buy you anything.
+
+**Writing your own record.** An external process that wants to be
+found — listed by `qwen sessions ps`, addressable from `send_message`,
+able to receive receipts — writes the same record for itself: its own
+`pid`, `procStart` and `pidNs` computed the same way, a `sessionId` it
+mints (any UUID), `kind: "external"`, a `name` (yours, or derived the
+same way; it is flattened to one line and bounded when displayed), and
+`ipcPath` + `ipcToken` for an inbox it binds itself (§2). Write to a
+temp file in the same directory and `rename` over the target; create the
+file 0600; refuse to write through a symlink. Remove the record on exit.
+A record whose process is gone is swept by the next session that lists,
+but only when `procStart` proves the PID is not merely reused.
+
+**Reading.** Anything that can read the directory can read every record,
+including tokens: being able to discover a session and being able to
+authenticate to it are one capability by design. Do not print
+`ipcToken` anywhere a model or a log can see it.
+
+**Liveness.** A record is live when all of these hold: the file name
+matches `pid`; `pidNs` equals the reader's; the boot id inside
+`procStart` equals the reader's (or `procStart` is `null`); and the PID
+is alive with the same start ticks. A live record with an `ipcPath`
+still has to be dialed before it is advertised as reachable — a socket
+file outlives a crash.
+
+**Refs.** Displayed handles use `ref = sha256(sessionId)[0:6]`. Two
+sessions may share a `name`; the address grammar a sender types is
+`name`, `name [ref]`, `[ref]` or the bare `ref`, and an ambiguous
+`name` is an error rather than a guess.
+
+## 2. The inbox socket
+
+One UNIX domain socket per session, at the first of these that binds:
+
+1. `$XDG_RUNTIME_DIR/qwen-socks/<pid>.sock`
+2. `$TMPDIR/qwen-socks-<16 hex>/<pid>.sock`
+3. `/tmp/qwen-socks-<16 hex>/<pid>.sock`
+
+The directory is 0700 and the socket 0600. A path longer than 103 bytes
+is skipped. When the PID-keyed name is already held by a live listener
+(two PID namespaces sharing a runtime directory), the session binds
+`<pid>-<8 hex>.sock` next to it instead. Peers never derive a socket
+path; they read `ipcPath` from the record.
+
+A connection carries newline-delimited JSON, one object per line, UTF-8.
+A single line longer than 1 MiB (measured in UTF-16 code units) drops
+the connection. A connection that goes 30 seconds without completing a
+line that parses is dropped; junk lines do not extend the deadline. The
+listener accepts at most 64 connections at once.
+
+The expected exchange is one message per connection: connect, write the
+auth line and the frame in one write, half-close, wait for the peer to
+close. The receiver never writes on the same connection; anything it
+has to say comes back as a separate connection to your own `ipcPath`.
+
+## 3. The auth line
+
+When the target record has an `ipcToken`, the first line must be:
+
+```json
+{ "msgV": 1, "type": "auth", "token": "<token>" }
+```
+
+Three kinds of token are accepted, and the inbox remembers which one it
+saw:
+
+| Presented                                                                     | The inbox concludes            | Effect                                                                           |
+| ----------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------- |
+| The `ipcToken` from the target's registry record                              | an ordinary peer               | subject to policy and mode parity (§6)                                           |
+| `QWEN_CODE_MESSAGING_TOKEN` from the target's own environment                 | a process that session started | delivered under the parity default; `origin="own-process"`                       |
+| A controller token `qpc_<64 hex>` minted with `qwen sessions controllers add` | a program the user trusts      | delivered under the parity default; `origin="controller"` with the grant's label |
+
+A first line that is not an auth line, or that presents a token matching
+none of the three, drops the connection silently. When the record has no
+`ipcToken`, do not send an auth line; an older inbox reads it as an
+unknown frame type and skips it, so leading with one is always safe.
+
+Nothing here authenticates the _sender_: a token proves the connection is
+allowed, not who opened it. `from`, `fromName`, `fromMode` and every
+field of the record are claims.
+
+This is also the whole of the trust model. A program the user wants
+driving their sessions gets a controller token, minted by hand and given
+to that one program; it is what makes the difference between a message
+that is delivered and one that waits for review. Writing
+`kind: "external"` or a familiar-looking `name` buys nothing.
+
+## 4. The user frame
+
+```json
+{
+  "msgV": 1,
+  "msgId": "5f1d0c9e-3b2a-4e8f-9c7d-1a2b3c4d5e6f",
+  "type": "user",
+  "from": "/run/user/1000/qwen-socks/40011.sock",
+  "replyToken": "<my own ipcToken>",
+  "fromName": "project-3f",
+  "fromMode": "prompting",
+  "toSessionId": "8e016be8-…",
+  "priority": "next",
+  "message": { "role": "user", "content": "build finished, 0 failures" }
+}
+```
+
+| Field         | Rule                                                                                                                                                                                                                          |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `msgV`        | Number. Must be ≤ 1; higher is dropped.                                                                                                                                                                                       |
+| `msgId`       | `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`, and must not canonicalize (dashes stripped, lower-cased) to `all`. Use a fresh UUID per message: the receiver remembers ids it has settled and repeats the old verdict for a re-sent one. |
+| `type`        | `"user"`.                                                                                                                                                                                                                     |
+| `from`        | Your `ipcPath`, if you have one. Where receipts go. Absent means no receipts.                                                                                                                                                 |
+| `replyToken`  | Your `ipcToken`, so the receiver can authenticate its receipts to you.                                                                                                                                                        |
+| `fromName`    | Display name; flattened to one line, at most 200 characters.                                                                                                                                                                  |
+| `fromMode`    | `"prompting"` (a person reviews each action) or `"bypass"` (some actions apply without review). Absent means "asserts nothing", which is held for review (§6).                                                                |
+| `toSessionId` | The `sessionId` you read from the record. A receiver holding a different id answers `misaddressed`. Always send it.                                                                                                           |
+| `priority`    | `"now"` or `"next"`; anything else reads as `"next"`. Carried for a future interrupt path; today the receiver queues both for the next turn.                                                                                  |
+| `message`     | `role` must be `"user"`; `content` a non-empty string.                                                                                                                                                                        |
+
+Unknown fields are ignored.
+
+## 5. The delivery-status frame
+
+The receiver reports what became of a message with one control frame per
+outcome, sent to the message's `from` and authenticated with its
+`replyToken`:
+
+```json
+{
+  "msgV": 1,
+  "msgId": "<fresh id>",
+  "type": "control",
+  "action": "delivery_status",
+  "status": "held",
+  "origMsgId": "5f1d0c9e-…",
+  "from": "/run/user/1000/qwen-socks/41337.sock",
+  "reason": "Your message is held for the recipient user to review …"
+}
+```
+
+| `status`       | When                                                                                                                                                      | What to do                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `held`         | Parked for the user to review. Repeated on a retry, and on a release that could not be queued.                                                            | Wait; a decision or an expiry follows.                                             |
+| `delivered`    | Queued for the model.                                                                                                                                     | Nothing. Not proof it was read.                                                    |
+| `denied`       | A person reviewed it and said no.                                                                                                                         | Do not re-send.                                                                    |
+| `refused`      | The session's policy turns peer messages away; nobody saw it. Only ever the first receipt.                                                                | Stop; reach that user another way.                                                 |
+| `expired`      | A held message ran out its wait, the session exited with it unread, or it arrived while that session was shutting down. Can follow `held` or `delivered`. | Re-send later if it still matters.                                                 |
+| `misaddressed` | `toSessionId` does not match the session at that address.                                                                                                 | Re-read the registry.                                                              |
+| `dropped`      | The inbox turned it away before any policy ran (§6).                                                                                                      | Treat as unsent. Do not retry in a loop; fold what matters into one later message. |
+
+A `dropped` receipt carries two more fields. `dropReason` is
+`rate-limited`, `duplicate` or `queue-full`. `droppedMsgIds` lists up to
+256 further ids the same receipt settles: a burst is answered with one
+receipt rather than one each, so a sender moves every message it lost to
+a terminal state from a single frame. Both are meaningless on any other
+status and are ignored there.
+
+`reason` is free text for a human. Order of receipts is not guaranteed
+across connections; apply them as state transitions:
+
+```
+pending   → held | delivered | denied | refused | expired | misaddressed | dropped
+held      → delivered | denied | expired | misaddressed
+delivered → expired | misaddressed
+```
+
+Anything else is a repeat and should be ignored. A receipt for an id you
+never sent is noise; ignore it. Receipts are best-effort on the
+receiver's side: a full outbound limit or a dead `from` loses them
+silently, so a sender must tolerate never hearing back.
+
+Your own inbox receives these frames from the sessions you messaged. If
+you only ever send, bind an inbox and give `from` anyway: without one you
+are blind to every outcome above.
+
+## 6. What the receiver does with a message
+
+In order:
+
+1. **Admission.** Per sender: a burst of 30, then one message every two seconds. All senders together: a burst of 32, then one a second — a sender names itself on the frame, so rotating that name buys a fresh allowance from the first limit but not the second. The same body from another session inside 30 seconds is a `duplicate`; a process the session started and a trusted controller are exempt from that check, and rate-limited like everyone else. A dropped message is never held, never delivered, and leaves no record, so a sender that waits out its burst and retries still lands.
+2. **Settled ids.** A `msgId` the gate already decided repeats its earlier verdict.
+3. **Policy.** `agents.crossSessionInbound` set to `accept`, `hold` or `refuse` wins. Unset: a process the session started or a trusted controller is accepted; otherwise a message is accepted only when `fromMode` names the same review class the receiver is in, and held in every other case, including when `fromMode` is absent.
+4. **Hold.** Up to 50 messages wait. A message arriving at a full buffer is `dropped` with `queue-full` rather than evicting one already parked. A held message expires after `agents.crossSessionHeldExpiry` (`1m`, `5m`, `10m`, `never`; default `5m`). The user releases or denies from `/peers`; a mode change re-evaluates the backlog.
+5. **Queue.** An accepted message joins the session's input queue, which holds at most 50 from peers. A full queue is `dropped` with `queue-full` too.
+
+A sender does not have to discover the limits the hard way: a Qwen Code
+session mirrors them per address and refuses its own send before writing
+it, telling its model to batch instead.
+
+The model sees a delivered message as:
+
+```
+<cross_session_message from="/run/user/1000/qwen-socks/40011.sock" name="project-3f">
+build finished, 0 failures
+</cross_session_message>
+```
+
+followed by a notice stating the sender's authority. `origin="own-process"`
+or `origin="controller" controller="<label>"` is added by the receiver
+from what the connection presented, never from the frame; a controller's
+label comes from the grant the user minted, not from `fromName`. Tags
+that look like the envelope are defanged inside `content`.
+
+## 7. Compatibility
+
+- A reader ignores fields it does not know. Adding a field to a record or
+  a frame is not a breaking change.
+- `schemaVersion` and `msgV` are bumped only for a change to the shape of
+  existing fields. A reader drops a frame or skips a record with a
+  version above what it knows, and never deletes such a record.
+- New `status` values may appear; treat an unknown one as "no transition"
+  and keep waiting. The same goes for a `kind` you do not recognize:
+  show it, do not correct it.
+- Constants that may change without notice: the burst and rate figures,
+  the hold ceiling and expiry choices, the 1 MiB line cap, the 30-second
+  line deadline, the 64-connection cap.
+
+## 8. Not settled yet
+
+- **Name yielding.** Two sessions in one directory can register the same
+  `name`; today they are told apart only by `ref`. A registration that
+  yields to a live name, and a control frame that tells peers a session
+  renamed itself, are both still to come.
+- **Same-name reporting.** `qwen sessions ps` and `list_agents` do not
+  flag records that still collide.
+- **Daemon-managed sessions.** Only the interactive UI registers today, so
+  a session `qwen serve` drives is not in the registry, cannot be
+  addressed, and cannot send. The `serve` and `headless` kinds are
+  reserved for it.

package/bundled/qc-helper/docs/features/goals.md

@@ -18,7 +18,9 @@ Creating, editing, or resuming a Goal requires a trusted workspace (`/trust`). H
 
 Once a Goal has billed a turn, the footer pill and every status card show what it has spent against the window it is allowed, as `1.2k/30.0m`. The figure counts the model calls the Goal makes in its own turns; subagents and the verifier's own checks are not included. The window is set by [`model.goalTokenBudget`](../configuration/settings.md); resuming a Goal that has spent its window grants another one on top of what it has already spent, so the figure reads `30.0m/60.0m` rather than starting over. A Goal with no budget shows only what it has spent. A Goal that has not billed a turn yet shows no figures at all.
 
-A long Goal periodically compresses the evidence it has recorded into checkpoint claims with a side model call, so later turns and the verifier still have it to cite. That call is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default; a checkpoint 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. The call is streamed, so the per-request transport timeout bounds only connect and first response, and the ceiling itself stops at the stream guards' 15-minute lifetime cap because past that the guard, not the setting, ends the call. That 15-minute limit on the setting is fixed, and raising the stream guard's own cap does not lift it.
+Each turn the session takes on its own reports what the Goal has spent so far, how many turns are behind it, and — unless the Goal runs unbounded — the window it is allowed. Every such turn except the final wind-down hand-off also carries standing instructions to re-check the workspace rather than trust earlier turns' reports, to work toward the end state the objective asks for, to do something different when the previous turn changed nothing (from the second turn on, once there is a previous turn to judge), and to check every requirement against citable evidence before proposing that the Goal is done.
+
+A long Goal periodically compresses the evidence it has recorded into checkpoint claims with a side model check, so later turns and the verifier still have it to cite. The check is bounded by [`model.goalCheckpointTimeoutSeconds`](../configuration/settings.md), 180 seconds by default. If its claims overrun the aggregate byte budget, or include a claim over the per-claim character limit, it makes one corrective model call and both calls share that ceiling. A check that does not finish in time is abandoned as inconclusive; it counts toward the checkpoint stall limit only when the evidence window has overflowed, while a non-overflowing check preserves the streak and retries on a later turn. The calls are streamed, so the per-request transport timeout bounds only connect and first response, and the ceiling itself stops at the stream guards' 15-minute lifetime cap because past that the guard, not the setting, ends the check. That 15-minute limit on the setting is fixed, and raising the stream guard's own cap does not lift it.
 
 ## Interrupting a Goal
 

package/bundled/qc-helper/docs/features/sub-agents.md

@@ -131,6 +131,14 @@ When a session is restored, compatible background agents are added back to the s
 
 Use continuation for related follow-up work. Launch a new agent when the task is unrelated or the previous agent cannot be resumed.
 
+## Notification Queue
+
+In the interactive TUI and ACP session, completion notifications from background agents, shells, monitors and workflows share a queue that drains into a model turn once the session is idle. These queues hold at most 20 notifications so a noisy producer cannot accumulate an unbounded backlog. The headless CLI's local queue is not capped by this rule.
+
+When a 21st notification arrives, Qwen Code evicts an interim monitor pulse first — the monitor's next poll supersedes it — and otherwise the oldest queued notification. Agent results, workflow results and scheduled prompts are never evicted in the interactive TUI; a notification that would displace one is dropped instead, and so is an arriving pulse when only terminal results are queued.
+
+Discarded notifications are reported rather than dropped quietly. The summary appears before the next notification in the live transcript. ACP also prefixes it to that turn's model input; the TUI keeps it parked for the next Notification batch so cron prompts still pass unchanged through slash, shell and `@` preprocessing. A daemon notification is recorded before it is acknowledged, so after a reload its durable record can precede the later overflow summary. ACP can discard a pending summary if the session is cleared or switched, or if a client cancels or preempts the notification turn. Discarding a notification never stops or deletes its task, and completed tasks retain their results; the summary points at `/tasks` and task output files when there is a task to inspect. A discarded scheduled prompt was never delivered and is not retried. A daemon notification that was recorded but could not be delivered live remains available in the session transcript and is reported separately from lost notifications.
+
 ## Agent Working Directory
 
 For a named regular subagent, `working_dir` pins the agent to an existing git worktree of the current repository. Relative paths resolve from the current directory, and the worktree must already be registered with git as a linked worktree of this repository.