Compare commits

..

38 Commits

Author SHA1 Message Date
易良
cea15a118b
fix(core,cli): replace full-history structuredClone with shallow/tail variants to prevent OOM on resume (#4644)
* fix(core,cli): replace full-history structuredClone with shallow/tail variants to prevent OOM on resume

Several UI and service call sites clone the entire chat history via
structuredClone(getHistory()) every turn. On a resumed session with
thousands of entries, each clone allocates 150-200 MB transiently.
When multiple async side-requests overlap (suggestion generation,
auto-title, checkpointing), multiple clones coexist on the heap,
pushing V8 past its limit within 10 turns (2 GB heap cap).

Changes:
- AppContainer.tsx: use getHistoryTail(40, true) instead of
  getHistory(true) + slice(-40)
- btwCommand.ts: same pattern, use getHistoryTail(40, true)
- sessionTitle.ts: use getHistoryShallow() (read-only filtering)
- sessionRecap.ts: use getHistoryShallow() (read-only filtering)
- useGeminiStream.ts: use getHistoryShallow() for checkpoint
  serialization (only needs to survive JSON.stringify)

Closes #4624

* fix(test): update mocks for getHistoryShallow/getHistoryTail in sessionTitle and btwCommand tests

* fix(cli): migrate remaining getHistory() clone sites to shallow/tail variants

- AppContainer.tsx rewind path: getHistory() → getHistoryShallow()
  (only used read-only by computeApiTruncationIndex)
- Session.ts ACP rewind: getHistory() → getHistoryShallow()
  (only walks entries to compute truncation index)
- Session.ts stop-hook: getHistory() + filter(.model).pop() →
  getLastModelMessageText() (O(1) backward scan, no clone)

* fix(core): use client-level getHistoryShallow with fallback

sessionTitle.ts and sessionRecap.ts were calling
chat.getHistoryShallow() directly, bypassing the client-level
wrapper that provides a getHistory() fallback when the chat
implementation doesn't support shallow reads. Use
geminiClient.getHistoryShallow() instead.

Update test mocks to match the new call site.

* fix(test): add getHistoryShallow and getLastModelMessageText to Session test mocks

Session.ts now calls chat.getHistoryShallow() in rewindToTurn and
chat.getLastModelMessageText() in the Stop hook. Update all mockChat
instances in Session.test.ts to provide these methods.
2026-06-01 22:53:48 +08:00
JerryLee
68e4819d73
fix(cli): use session channel when closing ACP sessions (#4522)
Detach closeSession/killSession from the session entry's owning channel instead of the current attach target, so the correct channel is decremented and killed during channel overlap (old channel dying while a fresh channel is current). Extracts findChannelInfoForEntry/detachSessionIdFromEntryChannel helpers with unit + integration coverage. Fixes #4325.
2026-06-01 16:23:42 +08:00
qqqys
788f215117
Improve hooks matcher display (#4545)
* feat(cli): improve hooks matcher display

* test(cli): cover hooks navigation levels
2026-06-01 16:18:10 +08:00
jinye
7448724d8a
fix(core): preserve uid in atomicWriteFile to avoid breaking shared-write files (#4431)
* fix(core): preserve uid/gid in atomicWriteFile to avoid breaking shared-write files

atomicWriteFile uses write-to-tmp + rename for crash atomicity. POSIX
rename creates a new inode owned by the calling process's euid/egid, so
the rename silently strips the original uid/gid. On shared-write setups
(e.g. a group-writable file owned by another user in a shared workspace
where the current user has group-write access), every Write/Edit/
NotebookEdit through qwen-code would reset ownership to the running
user and effectively revoke write access for the original collaborators.

The fix:

1. If the target exists and is owned by a different uid/gid than the
   process's effective uid/gid (and we are not root), fall back to
   in-place writeFile. This truncates the existing inode in place,
   preserving uid/gid. The trade-off is loss of crash atomicity for
   this specific case — an acceptable trade for not silently breaking
   shared-write file ownership.

2. If running as root, atomic rename is still used, and ownership is
   restored via chown(uid, gid) after the rename. Root can chown back;
   non-root cannot, hence the in-place fallback for non-root.

3. Windows is unaffected (no POSIX ownership semantics).

Tests:

- New: in-place fallback on uid mismatch — verify content updates, mode
  preserved, and inode unchanged (the inode is the signal that the
  fallback path ran rather than rename).
- New: same scenario triggered via gid mismatch.
- New: positive case — ownership matches → atomic rename → inode changes.

Regression: a v0.16.0 user reported "every write turns a world-writable
file into one other users can no longer write." Bisected to #4096 which
introduced atomicWriteFile + write-to-tmp + rename.

* fix(core): route root through in-place fallback + doc/test follow-ups

Review follow-ups on the atomic-write ownership fix:

1. Remove the root-special-case (rename + post-rename chown). chown
   silently fails inside user-namespaced or CAP_CHOWN-stripped Docker
   containers, which re-triggers the original bug for root-in-Docker
   users — exactly the scenario this fix was reported against. Routing
   root through the same in-place fallback as non-root eliminates this
   failure mode and drops an untestable branch (chown-back can't be
   exercised under non-root CI).

2. Document the three properties traded away by the in-place fallback:
   crash atomicity, concurrent-reader isolation, inotify watcher
   semantics (MODIFY vs MOVED_TO).

3. Document that the in-place fallback surfaces EACCES when the file's
   mode forbids the current user from writing — this is correct
   behavior (atomic rename used to silently replace files the user had
   no permission on, which was arguably a privilege issue).

4. Replace the brittle "see step 6 in the function doc" comment with a
   step-number-independent reference.

5. New test covering the EACCES path: chmod 0o444 + mocked geteuid
   triggers the fallback, fallback hits the read-only file, EACCES
   propagates cleanly, original content is preserved.

* fix(core): harden in-place fallback against symlink/unlink/inode races + doc/test follow-ups

Review follow-ups on #4431 ownership-preservation fix:

CRITICAL — in-place fallback security hardening (wenshao review):

The path-based `fs.writeFile(targetPath, ...)` fallback introduced
three races that the prior `rename(tmp, target)` form did not have:

1. Non-regular files (FIFO/socket/device): fs.writeFile calls
   open(O_WRONLY|O_CREAT|O_TRUNC). On a FIFO this blocks forever
   waiting for a reader. On a character/block device it writes to
   the actual device. The rename path replaced these with a
   regular file.

2. Symlink-swap TOCTOU: an attacker with parent-dir write can swap
   targetPath for a symlink between our stat and our writeFile.
   fs.writeFile follows symlinks at the destination; POSIX rename
   does not. In the very "shared-write workspace / Docker bind-mount"
   scenarios this PR targets, this lets a directory-writable
   attacker redirect agent writes elsewhere (e.g. /etc/passwd if
   the agent runs as root).

3. Unlink race: if targetPath is unlinked between stat and write,
   O_CREAT silently recreates it owned by the calling user — the
   exact ownership change the fallback was designed to prevent.
   Silent regression to the pre-fix bug under this race.

Fix: extract the fallback into writeInPlaceWithFdGuards():

  - open(target, O_WRONLY | O_TRUNC | O_NOFOLLOW) — no O_CREAT, so
    unlink-race surfaces ENOENT instead of silently recreating; and
    O_NOFOLLOW rejects symlink-swaps with ELOOP.
  - fstat(fd) verifies the bound inode's uid/gid still match
    existingStat — refuses the write if an inode-swap happened
    between stat and open.
  - Write through the fd (locked to the verified inode), chmod
    through the fd, close.

Caller now gates the fallback on existingStat.isFile() — non-regular
targets fall through to the atomic path which has well-defined
"replace special-file with regular-file" semantics.

DOC / TEST follow-ups:

- Add hardlink-propagation as a 4th trade-off in the in-place
  fallback JSDoc (review comment #4): rename creates a new inode so
  sibling hardlinks keep old content; in-place truncate+write keeps
  the inode so all hardlinks see new content.

- Update atomicWriteJSON JSDoc to note the write is now
  *conditionally* atomic (review comment #5): atomic when uid/gid
  matches the process, in-place when ownership differs. Previously
  the JSDoc still claimed unconditional atomicity.

- Update caller comments at runtimeStatus.ts and
  worktreeSessionService.ts that advertised crash-atomic writes via
  tmp+rename — those guarantees are now conditional (review
  comment #6).

- Add mode + tmp-leftover assertions to the gid-mismatch test to
  match the uid-mismatch test (review comment #2 — test
  consistency). Without these, a gid-fallback regression that
  silently dropped permissions or left a tmp file would not be
  caught.

- New test: FIFO + ownership mismatch must take the atomic path,
  not in-place (verifies the existingStat.isFile() guard works;
  hang on in-place would trip vitest timeout).

- New test: writing through a symlink with ownership mismatch
  exercises the resolve-then-stat-then-open flow and verifies the
  symlink itself is preserved.

Tests: 192/192 pass (atomicFileWrite + write-file + edit +
fileSystemService).

* fix(core): defer O_TRUNC and verify dev+ino in writeInPlaceWithFdGuards

PR #4431 review follow-up (wenshao critical):

The previous form opened with `O_WRONLY | O_TRUNC | O_NOFOLLOW`, which
truncated the bound file *before* the fd-bound fstat verification ran.
If an attacker swapped the path between the caller's stat and our
open, we would truncate the attacker's substituted inode (destroying
unrelated content) before detecting the swap.

Two fixes:

1. Open without O_TRUNC. Verify dev+ino+uid+gid+isFile match
   expectedStat through fh.stat(). Only then call fh.truncate(0)
   through the validated fd.

2. Expand the verification beyond uid+gid to include dev+ino+isFile.
   uid+gid alone misses a same-owner inode swap (attacker replaces
   the path with a different inode they own). dev+ino is the strong
   identity check; isFile catches a swap to FIFO/socket/device after
   the caller's existingStat.isFile() gate.

JSDoc updated to enumerate the four guards (NOFOLLOW, no CREAT, no
TRUNC at open, dev+ino+uid+gid+isFile via fstat) and explain why
truncation must wait until after verification.

192/192 tests pass.

* fix(core): close FIFO swap race with O_NONBLOCK + cover EOWNERSHIP_CHANGED path

PR #4431 review follow-up (deepseek-v4-pro via /review):

CRITICAL — FIFO swap TOCTOU:

The caller's `existingStat.isFile()` gate uses stat data captured
earlier. An attacker with parent-dir write can swap the regular file
for a FIFO between the caller's stat and our open inside
`writeInPlaceWithFdGuards`. The previous `O_WRONLY | O_NOFOLLOW` open
would then block indefinitely waiting for a FIFO reader; O_NOFOLLOW
only catches symlinks.

Fix: add O_NONBLOCK to the open flags. Defense in depth:

- On a reader-less FIFO, `open(O_WRONLY | O_NONBLOCK)` returns ENXIO
  immediately — no hang.
- If the FIFO has a reader (open succeeds), the subsequent fstat
  isFile() check still refuses the write via EOWNERSHIP_CHANGED.
- For regular files, O_NONBLOCK is a no-op.

CRITICAL test gap — EOWNERSHIP_CHANGED branch untested:

The primary TOCTOU defense (fdStat dev/ino/uid/gid/isFile vs
expectedStat) had no coverage. Exported `writeInPlaceWithFdGuards` so
it can be unit-tested directly:

- New test: simulate post-stat inode swap (unlink + recreate at same
  path), call helper with stale stat, assert EOWNERSHIP_CHANGED and
  that the attacker's content survives.
- New test: simulate post-stat regular→FIFO swap, assert open fails
  fast (ENXIO) or fstat catches it — either way no hang, no write.

DOC fix:

JSDoc said "we open read-write without truncating" but the code uses
O_WRONLY. Wording corrected to "write-only".

194/194 tests pass.

* fix(core): fix flaky inode-swap test + apply review follow-ups

PR #4431 review follow-up (glm-5.1 via /review) — 7 suggestions adopted,
1 partially adopted, 0 rejected:

CI FIX (Ubuntu test failure on tmpfs inode reuse):

The EOWNERSHIP_CHANGED inode-swap test used unlink+create to simulate
a post-stat swap. On Linux tmpfs the freshly-freed inode number is
often reused by the immediately-following create, so dev+ino remained
identical and the guard didn't trip (intermittent on Ubuntu CI; macOS
APFS happened to allocate different inodes). Switched to rename(decoy,
target) which moves an existing distinct inode into place, guaranteed
to differ from the original.

CODE:

- Wrap fh.writeFile failure after fh.truncate(0) with
  EINPLACE_WRITE_FAILED + cause, so callers see explicitly that the
  file was truncated and the write didn't complete (otherwise they
  see raw ENOSPC/EIO and may wrongly assume the original is intact
  given this lives in atomicFileWrite.ts).
- Skip fh.chmod when euid is neither root nor expectedStat.uid —
  chmod is guaranteed to fail with EPERM in that case (POSIX requires
  owner or root). Avoids a guaranteed-failing syscall on every call.
- Caller catches ENOENT from writeInPlaceWithFdGuards and falls
  through to atomic rename path. If the file was deleted between
  caller's stat and our open there is no ownership to preserve; the
  rename path correctly creates a new file at targetPath.

DOC:

- Replaced "defends against four races" with "hardened against
  post-stat races" (the bullet list has 5 items, the count was wrong).
- Reworded "non-regular targets must not reach this function" to
  describe defense-in-depth — O_NONBLOCK + !fdStat.isFile() reject
  post-stat regular→FIFO/socket/device swaps. The old wording made
  it look like O_NONBLOCK was redundant.
- Documented the dual chmod behavior (root vs non-root with foreign
  uid) inline.

TESTS:

- Added happy-path test for writeInPlaceWithFdGuards (write succeeds,
  inode preserved, mode preserved).
- Added ENOENT regression test (verifies the missing-O_CREAT
  property — if file unlinked between stat and open, no silent
  recreate with caller's uid).
- Renamed the misleading "O_NOFOLLOW guard" test (it actually tests
  resolve-through-symlink, not O_NOFOLLOW) to reflect what it does,
  and added a direct ELOOP test that drives writeInPlaceWithFdGuards
  with a path whose final component is a symlink — that's the real
  O_NOFOLLOW exercise.
- Fixed the FIFO test to pass a stat captured from the FIFO itself
  (not a stale regular-file stat) so only the FIFO-specific defense
  fires, not the inode/dev mismatch from a different file.

NOT ADOPTED:

- Skip-when-non-root chmod optimization adopted (small, useful), but
  the larger "structured chmod error model" deferred — best-effort
  matches the existing tryChmod pattern at file scope.

197/197 tests pass.

* fix(core): wrap truncate err + post-write nlink check + guard close + chmod sync

PR #4431 review follow-up (qwen-latest-series-invite-beta-v34 via /review)
— 7 of 10 suggestions adopted, 3 deferred:

CODE:

- **EINPLACE_TRUNCATE_FAILED wrap** (review #3291863048): symmetric to
  the existing EINPLACE_WRITE_FAILED — distinguishes "truncate failed,
  original intact" from "write failed post-truncate, original lost".

- **Post-write nlink === 0 check** (review #3291863059):
  EINODE_UNLINKED_DURING_WRITE detects the fstat-to-close window where
  a concurrent rename-over drops our bound inode's link count to zero
  and our write goes to an anonymous inode close will free. Silent
  data loss path now surfaces.

- **fh.close() guarded in finally** (review #3291863044): close failure
  on NFS/FUSE was masking the original try-body exception (including
  the meaningful EOWNERSHIP_CHANGED, EINPLACE_*, EINODE_*). flush:true
  already fsync'd, so close-after-flush is best-effort.

- **fdStat.uid in canChmod** (review #3291863055 part 1): use the
  fd-bound verified value instead of expectedStat.uid. Defense in depth
  — a future weakening of the fstat guard won't silently widen chmod
  privilege.

- **fh.sync() after chmod** (review #3291863053): chmod is metadata,
  not covered by writeFile({ flush: true }). A crash before lazy
  metadata flush would lose the mode restoration (matters for
  setuid/setgid). One extra syscall, best-effort.

- **@remarks freshness contract** (review #3291863051 partial): JSDoc
  now spells out that expectedStat MUST be a fresh stat captured
  immediately before the call. Stale stats nullify every guard.

- **Concurrent-writer limitation noted** (review #3291863061 partial):
  added a "Known limitation — no advisory locking" paragraph to JSDoc
  rather than adopting flock (Linux-specific, NFS issues, scope
  expansion). Callers needing multi-process coordination should layer
  their own lockfile.

- **@throws documentation** (review #3291863051 partial): four
  documented error codes (EOWNERSHIP_CHANGED, EINODE_UNLINKED_DURING_WRITE,
  EINPLACE_TRUNCATE_FAILED, EINPLACE_WRITE_FAILED).

TESTS:

- **EINPLACE_WRITE_FAILED via FileHandle.prototype.writeFile monkey-patch**
  (review #3291863040): triggers the data-loss path, asserts the wrapped
  code + message + cause, and verifies the file is empty (truncate ran).

- **canChmod=false actually skips chmod** (review #3291863055 part 2):
  prior uid-mismatch test had desiredMode === current mode, couldn't
  distinguish "skipped" from "no-op". New test uses desiredMode=0o755
  on a 0o644 file under canChmod=false → asserts mode stays 0o644.

NOT ADOPTED:

- ENOENT/ELOOP/ENXIO catch extension (review #3291863043): keeping the
  strict refusal for swap-to-special-file. Silent fallthrough-to-replace
  was pre-PR atomic-rename behavior, but in shared-write workspaces
  (this PR's target users) a special-file appearing at the target path
  is a signal worth surfacing, not papering over.

- Diagnostic logging (review #3291863049): the function has no logger
  dependency today; adding one is an architecture decision outside
  this PR's scope. The path taken is implied by the side effects
  (inode preserved vs new) but agreed: out-of-band telemetry would
  help ops. Defer to follow-up.

- flock advisory locking (review #3291863061 main): scope expansion;
  Linux-specific semantics, NFS edge cases. Documented as known
  limitation instead.

- Integration test for ENOENT fallthrough at atomicWriteFile level
  (review #3291863043 part 1): ESM module bindings prevent monkey-
  patching writeInPlaceWithFdGuards from outside. The unit test for
  the helper's ENOENT path covers the throwing behavior; the catch is
  3 lines and review-visible. Defer until a refactor opens an
  injection seam.

- Error code string constants export (review #3291863051 part 3): two
  codes don't merit a constant module. Magic strings are fine at this
  size.

199/199 tests pass.

* docs(core): sync writeRuntimeStatus JSDoc with conditional-atomic contract

PR #4431 review follow-up: function-level JSDoc still claimed
unconditional "Atomically write" and "never sees a partially written
file", inconsistent with the module-level docblock updated in earlier
commits. Updated to describe the conditional-atomic behavior (atomic
when uid/gid matches, in-place fallback when ownership differs) and
explicitly note the concurrent-reader visibility trade-off in the
fallback path. Links to atomicWriteJSON for the full contract.

Doc-only change. 199/199 tests pass.

* fix(core): add explicit fh.sync() — FileHandle.writeFile ignores flush option

PR #4431 review follow-up (qwen3.7-max via /review):

CRITICAL — FileHandle.writeFile silently ignores flush:

Node.js FileHandle.writeFile takes an early-return path that bypasses
the flush option entirely (the option is only honored on the
path-based fs.writeFile form). Our previous code passed
{ flush: true } to fh.writeFile and relied on the implicit fsync.
The only explicit fh.sync() was nested in the chmod block guarded by
canChmod — which is FALSE precisely when a non-root group member
writes to a group-writable file they don't own (the exact shared-write
scenario this PR targets). Net effect: in that branch, zero fsync.
Data sits in the kernel page cache; a crash before lazy flush leaves
the file empty (truncate succeeded) or partially written.

Fix:
- Drop flush from the fhWriteOptions object (silently ignored anyway).
- Add an explicit `fh.sync()` after writeFile succeeds, gated on
  options.flush. Runs BEFORE the chmod block so the canChmod=false
  branch also fsyncs.
- The chmod-block fh.sync() becomes metadata-only (covers the mode
  change), as the data is already on disk.

Updated comments to reflect the actual semantics rather than the
incorrect "writeFile({ flush: true }) fsyncs" assumption.

TESTS (partial adoption of review #3293252349):

- EINPLACE_TRUNCATE_FAILED: sibling test to EINPLACE_WRITE_FAILED.
  Monkey-patches FileHandle.prototype.truncate to throw EIO; asserts
  err.code + cause + "original content is intact" message, and
  verifies the file's original bytes are unchanged (truncate didn't
  run).
- Buffer in in-place fallback: locks in binary fidelity (byte-exact
  comparison) so a future encoding-passthrough regression for Buffer
  data would be caught.

NOT ADOPTED in this commit:

- EINODE_UNLINKED_DURING_WRITE test: requires post-write fh.stat()
  mocking with call-count discrimination (first call: real stat for
  verification; second call: nlink=0). The monkey-patch pattern works
  but is fragile; deferred to a follow-up that may also refactor the
  helper to accept an injectable stat fn for cleaner testability.

201/201 tests pass.

* fix: correct stale flush comment + add fh.sync() regression test

- Fix misleading close() comment that said "flush:true already
  fsync'd" — the explicit fh.sync() does the actual fsync, not the
  flush option (which is silently ignored on FileHandle.writeFile).
- Add regression test verifying fh.sync() is called when flush:true
  and skipped when flush is absent, preventing silent removal of the
  core durability fix.

Addresses wenshao review threads from 2026-05-23.

* test: add EINODE_UNLINKED_DURING_WRITE regression test

Monkey-patches FileHandle.stat to return nlink:0 on the post-write
check, verifying the nlink guard throws with the correct error code.
Addresses wenshao review from 2026-05-28.

* simplify: replace writeInPlaceWithFdGuards with plain fs.writeFile

Address yiliang114's review (CHANGES_REQUESTED):

1. [Critical] Remove ~120 lines of fd-level TOCTOU hardening
   (writeInPlaceWithFdGuards) — over-engineering for a local CLI.
   The in-place fallback now uses plain fs.writeFile + tryChmod,
   matching the EXDEV fallback pattern.

2. [Suggestion] Fix macOS GID false-positive: only compare uid in
   ownershipWouldChange(). macOS inherits parent dir GID for new
   files, so egid !== file.gid was a false positive that needlessly
   dropped crash atomicity.

3. [Suggestion] Trim 60+ lines of JSDoc to project style (AGENTS.md:
   "default to none, add only when WHY is non-obvious").

Net: -748 lines. 24 tests pass.

* fix: restore Stats type import (TS2304 build failure)

* docs: narrow scope from uid/gid to uid-only preservation

The gid check is intentionally skipped because macOS inherits the
parent directory's GID for new files, making egid !== file.gid a
false positive. Update comments and PR description to match the
actual implementation scope.

* test: add inode assertion to symlink ownership-mismatch test

Proves the in-place fallback actually ran instead of atomic rename.
2026-06-01 16:15:15 +08:00
Dragon
59c283670e
Hide internal docs from docs site (#4357) 2026-06-01 15:55:14 +08:00
顾盼
707f1bdb5f
fix(cli): persist /memory toggle state across dialog reopen (#4650)
The Auto-memory / Auto-dream / Auto-skill rows initialized their state
from Config getters, which are frozen at startup and never reflect a
setValue() write. Each /memory reopen re-mounts the dialog and re-reads
that stale snapshot, so a just-flipped toggle appeared to revert. Read the
initial state from the live merged settings instead, matching the existing
write path (bareMode semantics preserved).

Also switch the test's `act` import to `react` — the previously used
@testing-library/react is declared in package.json but not installed, so
the suite could not run — and add a mount/unmount/remount regression test.
2026-06-01 11:29:02 +08:00
Yufeng He
1c48e4121b
fix(core): apply output language to side queries (#4636) 2026-05-31 18:03:05 +08:00
Yufeng He
a3bc42dc55
fix(core): harden context error text collection (#4632) 2026-05-31 18:02:39 +08:00
yao
d074ed8434
feat(cli): Add settings JSON corrupted warning dialog (#4560)
* feat(cli): add settings corruption recovery dialog

* fix(cli): address review1 comments – copy instead of rename, clean DEBUG logs & lint

* test(cli): add SettingsCorruptedDialog keyboard navigation & callback coverage

* Update packages/cli/src/config/settings.test.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* Update packages/cli/src/config/settings.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): drop corrupted-path filter, use corruptedPath as sole signal

* fix(test): add missing truncateToItem to mockUIState

* fix(cli): prevent env var stale state and unnecessary normalization writes

* Apply suggestions from code review

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): resolve merge conflict and fix formatting errors from PR review update

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

* fix(cli): prevent validateAuthMethod from consuming corruption env vars

* test(settings): fix scope guard test to actually set env vars

* fix(cli): separate corruption warning from migrationWarnings

* fix(ui): extract CORRUPTED_SUFFIX constant to avoid magic string

* fix(ui): emit error on restore failure in onExit handler

* test(ui): strengthen up/down arrow test to assert selection on target line

* test(settings): strengthen double-corruption and scope guard assertions

* test(ui): assert selection moves in onContinue test before pressing Enter

* fix(ui): include corruption dialog in dialogsVisible to suppress global keypress

* fix(ui): resolve type incompatibility in dialogsVisible and test helpers

* fix(cli): block corruption env var injection and harden error handling

Co-Authored-By: wenshao <shaojin.wensj@alibaba-inc.com>

* fix(cli): harden corruption env var guard with helper, comment, and regression test

* fix(cli): add afterSpawn callback to clear corruption env vars after spawn

Co-Authored-By: qwen3.7-max <noreply@qwen-code.ai>

* fix(cli): share mockSpawn instance between default and named exports in relaunch test

* Update packages/cli/src/utils/relaunch.ts

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

---------

Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>
Co-authored-by: qwen3.7-max <noreply@qwen-code.ai>
2026-05-31 18:02:20 +08:00
Yufeng He
093545b71f
fix(cli): hide completed sticky todos (#4635)
* fix(cli): hide completed sticky todos

* fix(cli): remeasure sticky todos on status changes
2026-05-31 17:59:12 +08:00
Yufeng He
9dafd60d5d
fix(core): enforce adjacent tool results (#4622)
* fix(core): enforce adjacent tool results

* fix(core): handle orphan cleanup edge cases
2026-05-31 17:57:22 +08:00
Yufeng He
5743c2a05c
fix(acp): drop discontinued Qwen OAuth method (#4639) 2026-05-31 17:56:05 +08:00
Kagura
1014848234
fix(config): load home .env vars before settings ${VAR} resolution (#4466) (#4474)
* fix(config): load home .env vars before settings ${VAR} resolution (#4466)

${VAR} placeholders in settings.json (e.g. MCP server headers) could not
reference variables defined in ~/.qwen/.env because resolveEnvVarsInObject()
ran before loadEnvironment() loaded the .env file into process.env.

Add preLoadHomeEnvVars() that loads all variables from home-level .env files
(~/.qwen/.env, ~/.env) into process.env in no-override mode before settings
env var resolution. Workspace .env files and settings.env are still handled
by the existing loadEnvironment() call after settings merge.

Fixes #4466

* test: add env var resolution from .env file test (#4466)

* fix(config): use customEnv fallback for home .env resolution (#4466)

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>
Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>

* fix: align .env precedence and fix test mock

- Use ??= in getHomeEnvFallbackVars() so the more-specific file
  (~/.qwen/.env) wins over ~/.env, matching dotenv first-occurrence-wins
- Fix test 'QWEN_HOME is set': use customSettingsPath matching the
  runtime QWEN_HOME instead of the module-level USER_SETTINGS_PATH
  constant (fixes mock mismatch that cascaded into 7 test failures)
- Remove unused homeEnvPath variable (tsc/eslint warning)
- Add debugLogger.warn in catch block for I/O errors
- Document that the dict intentionally skips
  PROJECT_ENV_HARDCODED_EXCLUSIONS (substitution scope is narrower
  than process.env population)

Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>

* test: add .env fallback, precedence, and error path tests

Address R2 reviewer suggestions:
- Add ~/.env fallback positive path test (no QWEN_HOME)
- Add precedence test: ~/.qwen/.env wins over ~/.env (first-write-wins)
- Add error path test: readFileSync throws, loadSettings still succeeds
- Add code comment explaining intentional path discrepancy between
  getHomeEnvFallbackVars() and getUserLevelEnvPaths()

* docs: clarify customEnv precedence comment per reviewer suggestion

---------

Signed-off-by: kagura-agent <kagura.agent.ai@gmail.com>
Co-authored-by: Claude Opus 4 (1M context) <noreply@anthropic.com>
2026-05-31 15:03:46 +08:00
Yan Shen
54b6b204d2
fix(cli): stabilize statusline preset ordering (#4634)
* fix(cli): stabilize statusline preset ordering

* test(cli): make statusline helper contracts explicit

Add direct coverage for exported statusline preset helper behavior requested during PR review.

Constraint: Address PR #4634 review feedback for direct exported helper tests.
Rejected: Relying on existing integration coverage | Direct tests were requested for exported helper contracts.
Confidence: high
Scope-risk: narrow
Directive: Keep preset item ordering and reasoning formatting contracts directly covered when these helpers change.
Tested: cd packages/cli && npx vitest run src/ui/statusLinePresets.test.ts; cd packages/cli && npx vitest run src/ui/statusLinePresets.test.ts src/ui/components/StatusLineDialog.test.tsx src/ui/hooks/useStatusLine.test.ts; cd packages/cli && npx eslint src/ui/statusLinePresets.ts src/ui/statusLinePresets.test.ts; git diff --check
Not-tested: Full repository test suite.
2026-05-31 14:44:22 +08:00
JerryLee
7a31c80f0e
fix(core): guard oversized resumed history sends (#4531)
* fix(core): guard oversized resumed history sends

* fix(core): preserve history on hard rescue stop

* fix(core): defer hard-rescue compression recording until guard passes

* test(core): clarify hard-rescue compression status

* test(core): cover hard rescue rollback invariants

* docs(core): clarify hard rescue rollback comment

* docs(core): document deferred compression recording
2026-05-31 14:27:35 +08:00
ZevGit
3fc1849892
feat(core): add memory pressure monitor (#4403)
* feat(core): add memory pressure monitor

* fix(core): address memory pressure review

* fix(core): isolate session memory cleanup
2026-05-31 13:57:52 +08:00
Dragon
60f6c5aba8
fix(core): surface Anthropic empty stream provider errors (#4540)
* fix(core): surface Anthropic empty stream provider errors

* fix(core): address PR #4540 review feedback

- Move convertAnthropicResponseToGemini inside try/catch so converter
  errors are redacted the same way as API errors (Critical fix)
- Add regression guard: assert createImpl called once on normal streams
  to catch accidental double-request regressions
- Replace provider-specific Chinese mock error with generic '400 quota
  exceeded' for portability
- Add comment explaining why test uses message_delta instead of bare
  message_stop
2026-05-31 13:15:55 +08:00
jinye
a1043ee3c9
fix(core): emit enable_thinking on DashScope when reasoning is disabled (#4505) 2026-05-31 12:32:52 +08:00
jinye
c699738f9a
fix(rewind): use notification type for mid-turn messages to fix count mismatch (#4580)
Mid-turn user messages (typed during tool execution) were added to UI
history as type 'user', causing isRealUserTurn to count them. But in
the API history, they are merged into the preceding tool_result Content
(alongside functionResponse), making them invisible to isUserTextContent.

This UI/API count mismatch caused computeApiTruncationIndex to return -1,
producing a false "Cannot rewind to a compressed turn" error.

Fix: change mid-turn messages from type 'user' to type 'notification'
in both live and resume paths so isRealUserTurn no longer counts them.

Closes #4579
2026-05-29 21:32:11 +08:00
qwen-code-ci-bot
54fc50360c
chore(release): v0.17.0 [skip ci]
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-29 18:02:11 +08:00
顾盼
2a2f92aafd
fix(core,cli): label screenshot-triggered compaction accurately in the auto-compact notice (#4623)
The auto-compaction notice hardcoded "approached the input token limit"
even when the screenshot-overflow trigger fired. In computer-use sessions
that's misleading: compaction can fire on accumulated tool screenshots
while token usage is far below the window limit (observed: the notice
claimed "approached the input token limit" at ~116K/1M tokens when it was
actually the image-count trigger).

Add ChatCompressionInfo.triggerReason ('token_limit' | 'image_overflow' |
'manual'); compress() sets it to 'image_overflow' when the screenshot
trigger is what let it through the cheap gate. Both the TUI
(useGeminiStream) and ACP (Session) notices now show an accurate clause.
2026-05-29 17:35:57 +08:00
Yufeng He
a6f640a941
fix(core): use undici fetch for IDE proxy requests (#4607) 2026-05-29 17:16:17 +08:00
qwen-code-ci-bot
efba25f063
chore(release): v0.16.2 [skip ci]
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
2026-05-29 17:10:07 +08:00
qqqys
96f08ebe22
Emit PermissionDenied hooks for AUTO classifier blocks (#4376)
* fix(core): emit permission denied hooks for auto blocks

* test(cli): cover permission denied hook display

* docs(core): clarify permission denied hook semantics

* fix(core): respect disabled hooks for permission denied

* test(core): cover auto permission denied hooks

* test(cli): cover acp permission denied hooks

* test(core): cover unavailable permission denial hooks

* test(core): cover auto-approved permission hooks
2026-05-29 17:09:07 +08:00
顾盼
365409366d
refactor(core)!: replace tail-preservation compaction with summary + restoration attachments (#4599)
* refactor(core): rewrite compression prompt to 9-section claude-code-style format

Replaces the <state_snapshot> XML template with a numbered 9-section
structure that mandates verbatim preservation of user messages, including
the historical chronological list (section 6). The new format is
designed to pair with post-compact file/image restoration (separate work)
so the agent can resume long single-turn tasks without losing intent.

* refactor(core): align compaction trigger string with new 9-section prompt

The user-turn trigger injected after the system prompt still said
'generate the <state_snapshot>' from the old XML prompt era. Updated to
'produce the 9-section summary' to match Task 1's new prompt format.

Also tightens the prompt test to assert the specific user-message
verbatim mandate (not just the word 'verbatim' anywhere) so a future
regression that drops the mandate won't silently pass.

* feat(core): add postCompactAttachments module with file path extractor

extractRecentFilePaths walks history newest-first and returns the top N
unique file paths touched by read_file/write_file/edit/replace tool calls.
Pure function, no side effects, no state cache — readiness for the next
compaction-rewrite tasks.

* refactor(core): simplify extractRecentFilePaths internals

Three small cleanups from code review:
- Map<string, number> -> Set<string> (the index value was never read)
- Guard against maxFiles <= 0 explicitly (avoids returning 1 result
  when caller passes 0 as a 'disable' sentinel)
- Document 'replace' as a legacy alias for 'edit' so a future cleanup
  pass does not delete it as apparent dead code

Adds one test covering the maxFiles=0 path.

* feat(core): add image extractor with source-tool metadata

extractRecentImages walks history newest-first, collects up to N image
inlineData parts, and attributes each one to the model+functionCall that
preceded it (when one exists). Returns chronological order so callers
can render a meaningful 'last visual state ends here' strip.

* feat(core): add size-adaptive file reader for post-compact restore

readFileSizeAdaptive reads a file and returns one of: embed (full content
for files ≤ maxTokens × 4 chars), reference (path-only for large files),
missing (deleted since last touch), or binary (non-text content). The
embed/reference distinction mirrors claude-code's compact_file_reference
vs file attachment behavior, but without introducing new message types.

* refactor(core): harden readFileSizeAdaptive size accounting

Three corrections from code review:
- Import CHARS_PER_TOKEN from tokenEstimation.ts (canonical) instead of
  redeclaring locally, preventing silent drift between modules.
- Compare decoded character length, not raw byte length, against the
  cap. Otherwise a 10k-char Chinese file would be ~30k bytes and would
  be mis-classified as 'reference' despite fitting the budget.
- Rename FileReadResult -> FileEmbedResult to avoid a name collision
  with the unrelated FileReadResult interface in fileUtils.ts.

Adds a CJK-text test that catches the byte/char regression.

* feat(core): add file restoration block composer

buildFileRestorationBlocks reads each candidate file, classifies it as
embed/reference/missing/binary, and emits one consolidated reference
block (path-only list) plus one user message per embedded small file.
Total embed size is capped at POST_COMPACT_TOKEN_BUDGET; over-budget
files downgrade to reference.

* test(core): make budget test actually exercise the downgrade path

The previous version of this test wrote 3 files totalling 9k chars
against a 200k char budget. The assertions trivially passed regardless
of whether the budget check existed in the implementation.

The new version writes 11 files of 20k chars (each at the per-file cap)
so the budget is exhausted by the 10th and the 11th must downgrade
from embed to reference. Asserts both: file 11 appears in the reference
block, and file 11's content does NOT appear in any embed block.

* feat(core): add image restoration block composer

buildImageRestorationBlock emits a single user message whose first part
is a metadata header (turn index + source tool name + args per image),
followed by the inlineData parts themselves. Handles user-paste images
(no source tool) by labeling them as 'user-provided'.

* feat(core): add composePostCompactHistory orchestrator

Assembles the full post-compact history in order:
  summary → model ack → file references → file embeds → image block.

Each section is built by the per-concern extractors and builders added
in previous tasks. This is the single integration point that
chatCompressionService.compress() will call once the wire-up task lands.

* feat(core)!: rewrite compress() to claude-code-style full-history model

Replaces the split-point + tail-preservation model with full-history
compression + composePostCompactHistory. The entire curated history is
sent to the summary side-query, and the post-compact history is
assembled by the new composer (summary + ack + file restores + image
restore).

BREAKING: the previously-exported findCompressSplitPoint,
splitPointRetainingTrailingPairs, COMPRESSION_PRESERVE_THRESHOLD, and
TOOL_ROUND_RETAIN_COUNT will be removed in the next commit. Tests that
exercise them remain failing temporarily.

* chore(core): remove obsolete split-point compression infrastructure

Deletes findCompressSplitPoint, splitPointRetainingTrailingPairs,
COMPRESSION_PRESERVE_THRESHOLD, MIN_COMPRESSION_FRACTION, and
TOOL_ROUND_RETAIN_COUNT, plus the tests that exercised them. The new
behavior is covered by composePostCompactHistory and its unit tests.

Also cleans up:
- Stale orphan-strip comment in compress() that described the deleted
  manual-trigger orphan-funcCall handling.
- TEST_ONLY.COMPRESSION_PRESERVE_THRESHOLD hatch in client.ts.
- Docstring references in config.ts and compactionInputSlimming.ts.

* test(core): add single-turn computer-use compaction regression

Reproduces the scenario the rewrite targets: one user prompt kicks off
many screenshot tool calls. Asserts that (a) the user prompt is carried
into the summary verbatim and (b) the 3 most recent screenshots are
restored as an image block with source-tool metadata. This is the canary
test for the computer-use UX claim made in the design discussion.

* docs(core): remove stale "split point" references in tokenEstimation comments

Aligns the docstrings with the new compose-based compression flow. The
"split point" and "splitter" concepts no longer exist after the rewrite.

* fix(core): iterate parts reverse so parallel tool calls keep the last N

Real-session E2E surfaced a bug: a model that issues N parallel ReadFile
calls puts all N functionCall parts in ONE model+fc content. The
extractor's outer history walk is newest-first, but the inner parts
walk was forward — so for a 6-parallel batch hitting the cap of 5,
the FIRST 5 parts won and the actually-most-recent (last-listed) file
was dropped.

Fix: walk parts in reverse within each content. Applied symmetrically
to extractRecentImages (same shape, even rarer trigger).

Adds a regression test that hits a 6-parallel batch.

* fix(core): code-review fixes — fence escape, path sanitize, alias removal

- CommonMark-safe fence in file embed blocks. The old 3-backtick fence
  closed prematurely when a file's content contained a triple-backtick
  run (Markdown, CLAUDE.md, JSDoc with code examples) — leaking the
  remainder as unfenced text. Now uses a fence one longer than the
  longest backtick run in the content.

- Strip control characters (\r, \n, \t) from file paths before
  rendering into attachment markdown. Paths come from model-controlled
  history; a \n could inject markdown structure. The actual path stays
  intact for tool calls — only the displayed string is sanitized.

- Remove the historyForCompression alias for curatedHistory in
  compress(). The alias was added as a comment anchor during the
  rewrite but didn't carry semantic information.

* refactor(core): rewrite compression prompt to <state_snapshot> XML with 9 claude-aligned sections

Replaces the 9-section numbered-text prompt with qwen-code's original
<state_snapshot> XML envelope, but with the 9 inner section tags
content-aligned to claude-code:
  <primary_request_and_intent>
  <key_technical_concepts>
  <files_and_code_sections>
  <errors_and_fixes>
  <problem_solving>
  <all_user_messages>
  <pending_tasks>
  <current_work>
  <next_step>

Also:
- <scratchpad> -> <analysis>, stripped by postProcessSummary (saves
  ~600-800 tokens of CoT noise per compaction).
- "Resume directly..." trailer moved out of the prompt body and into
  postProcessSummary (no longer re-generated by the model every
  compaction; lives once in code with our own wording).
- Section 6 verbatim-policed mandate relaxed to "chronological, include
  short messages like 'ok' / 'continue'" — matches claude-code intent
  without forcing the model to literally copy long user messages.

E2E (qwen3.6-plus, 6 substantial .ts files + thorough analysis):
  raw history 6508 -> summary 1513 (after strip ~947), 38% history
  compression. Overall context 24642 -> 20647 reported (-16%), with
  another ~664 tokens actually saved by the post-strip but not
  reflected in the conservative token-math heuristic.

* docs(core): code-review polish on XML prompt rewrite

Four small follow-ups from review of 641a0eadd:

- prompts.ts: rewrite getCompressionPrompt's stale JSDoc — it still
  described the deleted 9-section numbered-text format and the
  verbatim mandate that was relaxed.
- chatCompressionService.ts: clarify the token-math comment so it's
  obvious the ~1000 token deduction covers the full compression
  system prompt + kick-off user turn (not any single instruction)
  and that newTokenCount slightly over-counts because <analysis>
  gets stripped by postProcessSummary downstream.
- postCompactAttachments.ts: add a NOTE comment on the <analysis>
  strip regex covering its strict-tag-match assumption and
  multi-block / non-greedy semantics.
- postCompactAttachments.test.ts: replace the four lazy
  `await import('./postCompactAttachments.js')` calls inside the
  postProcessSummary describe block with one top-level static import
  — consistent with how every other describe in the file imports.

* docs(core): drop stale duplicate sentence left in token-math comment

* fix(core): address wenshao review on PR #4599 (correctness + security + ergonomics)

Seven follow-ups from wenshao's review of the compaction rewrite.

Critical:
- newTokenCount now includes restoration-block tokens via
  estimateContentChars over extraHistory[2..]. Previously the formula
  only counted side-query output, so up to 5 × 5K (files) + 3 × image
  tokens were missing — letting the inflation guard miss and the
  cheap-gate under-estimate the next prompt size (Finding 1).
- composePostCompactHistory now merges every file restoration block
  and the image block into a single user Content following the model
  ack. The previous output had consecutive user roles, which
  geminiChat.test.ts:6289 enforces against and Gemini providers
  reject with 400 "consecutive same-role content" (Finding 2).
- Preserve a trailing model+functionCall through compaction so a
  pending functionResponse (sitting in sendMessageStream's
  pendingUserMessage) has a matching call. Without this, hard-rescue
  auto-compaction mid tool-use loop produces a user+functionResponse
  with no preceding model+functionCall → API 400. This restores the
  protection the split-point in-flight fallback used to provide.
  When the funcCall lands without attachments it folds into the
  ack's own model Content to avoid model→model adjacency (Finding 3).
- composePostCompactHistory now takes an optional workspaceRoot and
  silently skips file paths that resolve outside it.
  extractRecentFilePaths picks up paths from model functionCall args
  regardless of whether the tool execution succeeded; without a
  boundary check, an adversarial model that issued
  read_file('/etc/passwd') — denied by the permission system —
  would still have its path extracted and re-read into the next
  prompt. compress() passes config.getTargetDir() as the boundary
  (Finding 4).

Suggestions:
- composePostCompactHistory + buildFileRestorationBlocks +
  readFileSizeAdaptive all take optional AbortSignal and short-
  circuit / pass it to readFile's { signal } option. Cancelled
  compactions stop on the next file read (Finding 5).
- postProcessSummary fallback no longer re-injects the raw
  <analysis> block when the strip leaves nothing. The new
  stripAnalysisBlock helper runs the closed-tag strip AND an
  unclosed-tag strip (handles 'model ran out of output tokens
  before closing'). If both leave nothing, postProcessSummary
  emits '[Summary unavailable]' rather than leaking scratchpad
  (Finding 6).
- firePostCompactEvent now receives stripAnalysisBlock(summary) so
  hook consumers see the same text that lands in history. The
  resume trailer stays out of the hook payload — that's wrapper
  decoration for the next agent turn, not state for consumers
  (Finding 8a).

Docs:
- Update the geminiChat.ts comment around `trigger: 'auto'` to
  describe what the trigger actually does post-refactor (hook event
  categorization) rather than the deleted manual-only orphan-strip
  it used to guard against (Finding 8b).

Regression tests cover all six fixable code-path changes
(role alternation, trailing funcCall preservation, workspace
boundary, abort propagation, closed-tag fallback strip, unclosed-tag
fallback strip).

* fix(core): add getTargetDir to geminiChat auto-compression test mock

The R3.4 end-to-end auto-compression test drives the real
ChatCompressionService, which reads config.getTargetDir() for the
post-compact file-restoration workspace boundary. The geminiChat mock
config lacked getTargetDir, so the test threw "config.getTargetDir is
not a function" on CI. Add the mock to unblock the failing Test jobs.

* feat(core): configurable compaction retention + computer-use screenshot trigger

Add four env-overridable chatCompression settings (priority env >
settings > default):
- maxRecentFilesToRetain    (QWEN_COMPACT_MAX_RECENT_FILES,     default 5)
- maxRecentImagesToRetain   (QWEN_COMPACT_MAX_RECENT_IMAGES,    default 3)
- enableScreenshotTrigger   (QWEN_COMPACT_SCREENSHOT_TRIGGER,   default true)
- screenshotTriggerThreshold(QWEN_COMPACT_SCREENSHOT_THRESHOLD, default 50)

The screenshot trigger fires auto-compaction once tool-returned images
accumulate to the threshold even when token usage is below the auto tier,
so computer-use sessions don't drown the model in stale screenshots. It
counts only images nested in functionResponse.parts (tool results), not
user pastes, and runs only in the would-be-NOOP path when enabled.

Fix a latent bug surfaced while wiring the trigger: extractRecentImages
only inspected top-level inlineData parts, but convertToFunctionResponse
nests tool media under functionResponse.parts — so post-compact
restoration recovered ZERO tool screenshots in real sessions, while unit
tests stayed green against a fabricated top-level shape. It now walks both
shapes; the image counter and tests use the real nested shape.

Remove the now-defunct contextPercentageThreshold deprecation warning (the
field was already dropped from ChatCompressionSettings) and its tests, and
document the four new settings.

* test(core): assert screenshot trigger can't re-fire post-compaction; fix misleading docs

Code-review follow-up. The screenshot trigger counts only images nested in
functionResponse.parts. Compaction replaces those with the summary and
re-embeds survivors as TOP-LEVEL parts in the restoration block, which the
counter ignores — so the tool-image count always resets to ~0 and the
trigger cannot immediately re-fire, independent of maxRecentImages.

The resolveCompactionTuning JSDoc and the settings.md note previously warned
of a non-existent "maxRecentImages near threshold => compact every turn"
loop. Correct both, and add a regression test asserting
countToolResponseImages() is 0 on composePostCompactHistory output.

* fix(core): guard readFileSizeAdaptive against multi-GB reads; cover composer 4-entry branch

wenshao review round 2 on PR #4599.

- readFileSizeAdaptive now stats the file first and short-circuits to a
  reference when its byte size exceeds maxChars*4 (the safe UTF-8 upper
  bound — a file larger than that cannot fit within maxChars chars). This
  stops a multi-GB file the agent previously touched from being slurped
  into a Buffer and exhausting the heap mid-compaction, exactly when we're
  trying to reduce memory. A large binary file now references rather than
  reading to binary-detect.

- Add a test for composePostCompactHistory's 4-entry branch (attachments +
  trailing model+functionCall) producing [user(summary), model(ack),
  user(attachments), model(fc)]. This is the common mid-tool-loop
  compaction case; a model->model adjacency here is a provider 400. Prior
  tests only covered the 2-entry fold (no attachments) and 3-entry (no
  trailing fc) shapes.

* fix(core): resolve symlinks in workspace boundary; guard compose against throws

wenshao review round 3 on PR #4599 (two Criticals).

- isInsideWorkspace now resolves symlinks via realpathSync (safeRealpath,
  with a lexical fallback for non-existent paths). A symlink living inside
  the workspace but pointing outside (e.g. workspace/.env -> ~/.ssh/id_rsa)
  previously passed the lexical boundary check and had its target read and
  embedded into the post-compact history sent to the provider. Added a
  RED-verified security regression test (secret embedded under the old
  lexical check; rejected under realpath).

- Wrap composePostCompactHistory in try/catch inside compress(). The
  summary side-query has already succeeded at that point, so a
  restoration-assembly throw (disk I/O / malformed history) previously
  escaped to sendMessageStream, crashing the active turn AND bypassing the
  COMPRESSION_FAILED breaker. It now degrades to summary + ack.

* fix(core): close 4 compaction Criticals from review round 4

wenshao review round 4 on PR #4599.

- isSummaryEmpty now checks the STRIPPED summary: a response that is only an
  <analysis> block (no <state_snapshot>) strips to empty, so it takes the
  COMPRESSION_FAILED_EMPTY_SUMMARY path instead of "succeeding" with
  `[Summary unavailable]` as the agent's only context (silent amnesia).
- Manual /compress strips a trailing ORPHANED model+functionCall before
  composing — it has no pending functionResponse, so preserving it would
  emit model[fc] then the next user text turn -> API 400. Auto-compaction
  still keeps it (the pending response pairs with it).
- The restoration-failure catch fallback now folds a trailing
  model+functionCall into the ack turn, so a pending functionResponse
  (auto mid-tool-loop) keeps its matching call even on the degraded path.
- extractRecentFilePaths skips file paths whose tool call FAILED (an error
  functionResponse), so a denied read_file is never re-read off disk during
  compaction — closing a permission-bypass side channel.

RED-verified regression tests for the empty-summary, orphan-strip, and
permission-bypass fixes. Corrected the postProcessSummary comment.

* test(core): cover composePostCompactHistory catch-fallback; document fold text drop

wenshao review round 5 on PR #4599.

- Regression test for the restoration-failure catch fallback: mock
  composePostCompactHistory to reject and assert compaction still returns
  COMPRESSED (no escape to sendMessageStream / breaker bypass) with the
  trailing functionCall folded into the ack and the trailing text dropped.
- Document that the fold branch intentionally keeps only functionCall parts
  (the trailing turn's text is already captured in the summary); the
  asymmetry with the with-attachments branch is deliberate.
2026-05-29 16:20:13 +08:00
顾盼
39cc9b3e6f
feat(computer-use): zero-config built-in via open-computer-use MCP (#4590)
* feat(computer-use): add tool name constants

* feat(computer-use): hardcode upstream tool schemas

* feat(computer-use): add enableComputerUse setting (default true)

* chore(vscode-ide-companion): sync settings schema for computerUse

* feat(computer-use): MCP stdio client for upstream binary

* feat(computer-use): ComputerUseTool wrapper + bootstrap stub

* feat(computer-use): register 9 deferred tools when enabled

* feat(computer-use): persist install approval state under ~/.qwen

* feat(computer-use): detect upstream permission errors

* feat(computer-use): bootstrap state machine (install + permissions)

* feat(computer-use): wire install approval to qwen-code confirm UX

* chore(computer-use): script to sync schemas from upstream

* fix(computer-use): consolidate package spec, surface download progress, correct version comment

* docs(computer-use): implementation plan

* fix(computer-use): forward image content parts to the model

* fix(computer-use): coerce string numbers to integers + clarify required fields

* fix(computer-use): detect missing Screen Recording + re-spawn doctor across permission transitions

* fix(computer-use): auto-reconnect on transport-closed errors

* fix(computer-use): sync schemas with upstream canonical contract

Regenerated schemas.ts from upstream open-computer-use@latest via
scripts/sync-computer-use-schemas.ts. Key contract fixes:

- element_index: type integer → string (upstream reads via optionalString)
- x/y/from_x/from_y/to_x/to_y: type integer → number (upstream uses optionalDouble)
- scroll: adds required direction enum + requires element_index (not pages)
- click: adds optional mouse_button string enum (left/right/middle)
- Descriptions updated to upstream verbatim text (no "REQUIRED:" prefix)

* fix(computer-use): bidirectional type coercion for string element_index

Rename coerceNumericStrings → coerceTypes and add Direction 2:
when schema declares type: "string" and model sends a number,
stringify it (e.g. element_index: 2 → "2"). This fixes the upstream
runtime error where optionalString returns nil for numeric element_index.

Direction 1 (string → number for integer/number fields) is preserved
unchanged for x/y coordinate fields.

Update tests: element_index coercion tests now reflect string schema
type; add new "coerces integer element_index to string" test cases.

* feat(prompts): strengthen deferred-tools guidance to prevent param guessing

* fix(computer-use): clearer wording for permission-transition onboarding message

* fix(computer-use): only probe permissions on fresh client start, not every tool call

* docs(computer-use): correct comment about permission-revocation recovery behavior

* fix(computer-use): pin upstream version exactly to prevent schema drift

* fix(computer-use): use pinned package spec in client singleton to prevent schema drift

* fix(computer-use): decouple install gate from per-action permission grant

* fix(computer-use): route registration through PermissionManager-aware registerLazy

* fix(computer-use): probe via upstream doctor instead of get_app_state on Finder

The previous probe called get_app_state on Finder, which has the side
effect of activating the target app via upstream's unhide / open -b /
AXRaise logic. Result: Finder popped to the foreground once per fresh
session even when the user's task had nothing to do with it.

The doctor CLI reads TCC + runtime preflight and prints a summary to
stdout, exiting silently when permissions are granted. When any
permission is missing, doctor launches the onboarding window via
LaunchServices (which dedups so repeated invocations focus the
existing window). We parse the stdout summary and rely on doctor's
own window-launching for the UX trigger — no separate spawnDoctor
call needed.

Side effect for steady-state sessions (permissions already granted):
ZERO Finder activation. The probe spawns npx -y doctor once per fresh
client start (~200-500ms), and that's it.

Also bumped pollIntervalMs default from 2s to 5s to amortize the
npx-spawn overhead during the rare permission-grant flow.
2026-05-29 10:39:51 +08:00
易良
27b06290c9
fix(cli): track model-sent slash command history (#3826)
* fix(cli): prevent file paths from being treated as slash commands (#1804)

When users input file paths starting with '/' (e.g. '/api/apiFunction/...',
'/Users/name/path'), they were incorrectly parsed as slash commands, resulting
in "Unknown command" errors. The input was discarded instead of being sent to
the model for processing.

Root cause: isSlashCommand() only checked for a '/' prefix without validating
whether the first token actually looks like a command name. Any '/' prefix
triggered the slash command flow, and when no matching command was found, the
error was shown with no fallback.

Fix: Add looksLikeCommandName() that validates command names contain only
[a-zA-Z0-9:_-]. Both isSlashCommand() and handleSlashCommand() now check the
first token — if it contains path separators, dots, or non-ASCII characters,
the input falls through to normal model processing instead of the command
dispatcher.

Closes #1804

* fix(cli): allow dots in command names and fix prettier formatting

Address review feedback:
- Allow '.' in looksLikeCommandName() regex to support extension-qualified
  commands like gcp.deploy (CommandService renames conflicts as ext.cmd)
- Add regression tests for dot-named commands in both commandUtils and
  slashCommandProcessor
- Fix prettier formatting in slashCommandProcessor test file

* fix(cli): handle slash command review edge cases

* docs(cli): align slash command validation comment

* fix(cli): preserve slash prompt ordering

* fix(cli): reject shell-metacharacter slash tokens

* test(cli): align slash command action mocks

* fix(cli): track model-sent user turns

* fix(cli): narrow slash path handling scope

* fix(cli): split slash routing follow-up

* fix(cli): tighten slash routing follow-up scope

* fix(cli): address slash routing review gaps

* fix(cli): keep slash history follow-up focused

* fix(cli): align resume history item typing

* fix(cli): address slash history review suggestions

* test(cli): harden slash command history item ids

* chore(cli): use HistoryItemWithoutId in useEditorSettings.test

* refactor(cli): keep setSessionName optional in useSlashCommandProcessor

main currently exposes setSessionName as an optional trailing parameter.
The earlier addition of updateItem pushed it before updateItem and
forced every caller — including AppContainer and all tests — to pass an
explicit undefined. Reorder so updateItem stays required and
setSessionName remains optional, preserving the prior ergonomic.

* test(cli): fix slash command processor hook args

* fix(cli): harden slash command history metadata
2026-05-29 10:27:17 +08:00
gwinthis
7bed56b9b6
feat(telemetry): foundation for skill-based RT optimization (P0+P1) (#4565)
* docs(design): add RT optimization design doc

Two-round review trail documenting the analysis path: original D1-D4
proposal, code-level verification in §6 that recanted the cost estimates,
and §7 ROI reordering after DashScope ephemeral cache implementation was
confirmed already in place — which collapsed D2's net benefit and led to
deferring D2 and D4 as won't-fix.

The doc is preserved as the canonical record of why the obvious-looking
directions (fast-model routing, prevalidate scheduling) turn out to be
dead ends, so future work doesn't relitigate the same conclusions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(design): add reduce-rounds-via-skill-design with spec-first gating

Companion design to rt-optimization-design.md. The core argument:
the real lever for reducing agent loop rounds is at the skill/tool
design layer, not the agent framework. Round 2 in §1.2's baseline
exists because Round 1's skill didn't return a complete answer —
fixing that per-skill collapses 3 rounds into 2, an angle the
original framework-centric proposal completely missed.

Layout:
- §0 acceptance spec is the front-loaded gate: engineering specs
  lock at P-1, statistical thresholds lock at P1.5 (after baseline),
  per-skill specs are data-driven and live in PR descriptions
- §3-§4 three-layer plan: telemetry → per-skill rewrites → prompt
  guidance for concurrent tool calls; each layer is independently
  measurable and reversible
- §5.3 stop-loss lines split into result + process metrics to catch
  the "looks like progress, no actual ROI" failure mode early

The doc was reviewed by codex twice — once on initial draft (caught
qwen-logger dead-code path, batch_size state-passing cost, prompts.ts
line drift) and once after §0 was added (caught spec rigidity, missing
per-skill template, framework boundary case). Both rounds' findings
were either applied or explicitly recorded as not-adopted with reasons
inline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(telemetry): connect logSkillLaunch to QwenLogger

logSkillLaunch in loggers.ts went only through the OTLP path, while
QwenLogger.logSkillLaunchEvent in qwen-logger.ts had no callers anywhere
in the repo — leaving the skill_launch event invisible to any backend
that consumes from the qwen-logger pipeline rather than OTLP.

Mirror the logToolCall pattern at loggers.ts:230: forward the event to
QwenLogger before the OTLP path so the call still reaches QwenLogger when
the OTEL SDK is not initialized.

This is P0 of docs/design/rt-optimization/reduce-rounds-via-skill-design.md
§4.1.1b — a prerequisite for the prompt_id propagation in P1 so the
SkillLaunchEvent / ToolCallEvent join in §4.1.2 has data to query against.

Tests: 2 new cases under describe('logSkillLaunch') covering forwarding
to QwenLogger plus the OTLP-uninitialized branch; loggers.test.ts now
47/47 pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(telemetry): thread prompt_id through SkillLaunchEvent

To join skill_launch events with the subsequent tool_call events they
trigger, SkillLaunchEvent now carries the prompt_id of the user turn
that fired the skill. The scheduler already holds the request and its
prompt_id; the missing piece was getting that id into the invocation
that does the actual logSkillLaunch call.

Wiring:
- SkillLaunchEvent constructor adds a required prompt_id parameter so
  the field can never be silently undefined in a backend join.
- SkillToolInvocation exposes setPromptId(id) and stores the value;
  the four logSkillLaunch sites in execute() pass this.promptId through.
- CoreToolScheduler.buildInvocation grew an optional fourth promptId
  argument and duck-types setPromptId on the freshly-built invocation,
  mirroring the existing setCallId hook. The two callers (setArgs path
  at L1036 and the main schedule path at L1497) pass
  request.prompt_id / reqInfo.prompt_id.
- qwen-logger.logSkillLaunchEvent forwards prompt_id in the RUM event
  properties so the join works on the qwen-logger pipeline too.

The empty-string default on SkillToolInvocation.promptId is deliberate:
direct invocations (e.g. buildAndExecute in tests) that skip the
scheduler still log a valid event, and downstream queries can filter
prompt_id != '' to exclude non-scheduled launches from joins.

Implements P1 of docs/design/rt-optimization/reduce-rounds-via-skill-design.md
§4.1.1 — required prerequisite for the SkillFollowupRecord SQL in §4.1.2.

Tests: 2 new cases in skill.test.ts cover the setPromptId path and the
empty-default path; loggers.test.ts updated for the new 3-arg signature.
256 tests pass across loggers / skill / coreToolScheduler suites.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(scheduler): cover prompt_id propagation through buildInvocation

The duck-typed setPromptId hook added in the previous commit went
through unit tests on each side independently — SkillToolInvocation
tests verified that setting the field changes the logged event, and
the loggers tests verified the SkillLaunchEvent shape — but the
integration point in CoreToolScheduler.buildInvocation that wires the
two together was only exercised indirectly. Same is true of the older
setCallId hook it mirrors, which had no test at all.

Two cases here close that gap on the scheduler side:

- A purpose-built PromptIdAwareTool whose invocation records every
  setPromptId call; the test schedules a request with a known
  prompt_id and asserts the invocation captured it. This is the
  positive contract.

- The existing TestApprovalTool (no setPromptId) scheduled through
  the same path to confirm the duck-type guard does not throw when
  the method is absent. This is the backward-compatibility contract
  that lets every existing tool keep working unchanged.

The two cases together pin both branches of the typeof check in
buildInvocation, so future refactors of that hook cannot regress
silently. 165 tests in the suite still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(telemetry,scheduler,skill): close P0/P1 coverage gaps

Three blind spots remained after the initial P0+P1 work — each one
was a path that the production code change had already touched
mechanically but no test was pinning it against future regressions.

qwen-logger.ts logSkillLaunchEvent now has two cases asserting that
prompt_id reaches the RUM event properties, on both the success and
failure branch. Previously the loggers.test.ts spy stopped at "method
was called" and never inspected the payload qwen-logger built.

skill.ts had four logSkillLaunch sites, but only the happy path and
the empty-default path were tested. The commandExecutor-success
branch (L386), not-found branch (L399), and thrown-exception branch
(L482) now each have a test that sets promptId, drives execute()
through that specific path, and asserts the emitted event carries
both the right success flag and the right prompt_id. This catches
the failure mode where someone later edits one of those branches
and forgets the promptId argument — replace_all guaranteed today's
correctness but no test would catch a regression tomorrow.

CoreToolScheduler.buildInvocation now has two direct unit tests
that exercise the method through a type-assertion cast. Reaching
the L1036 setArgs path through the public API would require mocking
modifyWithEditor + the filesystem + an editor type, which would
dwarf the change under test. The direct call covers both L1036 and
L1497 simultaneously: when promptId is supplied the duck-typed
setPromptId is invoked; when it is omitted, the captured field
stays undefined and no throw happens.

298 tests pass across loggers / qwen-logger / skill / scheduler suites.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review(PR #4565): address Copilot + github-actions feedback

Five spots flagged by the automated review on #4565. Three were real
and worth fixing; two were comment-quality touch-ups that traveled
along with the same patch.

- SkillLaunchEvent.prompt_id is now optional with a default of '',
  removing the breaking-change footprint on the exported telemetry API.
  All current internal callers still pass the value explicitly through
  the SkillToolInvocation.promptId field, so the §0.1 spec ("prompt_id
  串联") is still enforced in production paths — type-level enforcement
  just steps aside in favor of API stability, with §0.5 治理 covering
  the discipline at the process layer.

- The skill-design doc §4.1.1 used to claim "BaseToolInvocation 已有
  request.prompt_id" which is wrong: BaseToolInvocation only holds
  params, and the prompt_id flows through CoreToolScheduler's duck-typed
  setPromptId hook (mirroring setCallId). The doc now reflects the
  actual implementation and notes that the earlier text was the bug.

- CoreToolScheduler.buildInvocation gained a short JSDoc explaining
  why the two extra args (callId, promptId) are optional — they
  match the existing duck-type pattern that lets older tools and
  non-scheduler call sites work without implementing the setters.

- skill.test.ts adds a one-comment note next to the first setPromptId
  cast explaining that setPromptId is a scheduler-only hook, not part
  of the public ToolInvocation interface.

- SkillToolInvocation.promptId field comment shrank from 8 lines to 2
  with a pointer to the design doc so the inline noise drops without
  losing the empty-string semantics.

Pre-existing scope-creep findings (Chinese-only doc, mock-config
duplication in scheduler tests, redundant optional-chain comment,
prompt_id sanitization for an internally-generated UUID) are
deliberately not addressed here — see the reply on PR #4565 for
disposition per item.

298 tests still pass across loggers / qwen-logger / skill / scheduler.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-29 02:17:40 +08:00
yuanyuanAli
7732554805
feat(channels): add Feishu (Lark) channel adapter (#4379)
* feat(channels): add Feishu (Lark) channel adapter

* fix(channels/feishu): fix webhook stop button, memory leak, spin-wait timeout, and reaction cleanup

* fix(channels/feishu): fix security, stability and build issues from PR review

* fix(channels/feishu): fix card lifecycle, streaming limits, and download safety from CR round 2

* fix(channels/feishu): harden webhook, card lifecycle, and disconnect cleanup from CR round 3

* fix(feishu): clarify stoppedMessages JSDoc to match actual cleanup behavior

* fix(channels/feishu): handle post messages without language key wrapper in quote context

* fix(channels/feishu): fix webhook signature bypass, stop-button double-send, and blockStreaming duplicates from CR round 4

* fix(channels/feishu): harden card lifecycle, markdown splitting, and defensive guards from CR round 5

* fix(channels/feishu): harden card lifecycle, markdown splitting, and defensive guards from CR round 5

- Set cardCreationFailed on onPromptStart failure to prevent retry spiral
- Skip throttle updates when card creation permanently failed
- Handle code fences in hard-split and table-stripping fallbacks
- Use parity-based fence detection in splitByTables (align with splitChunks)
- Add cs.stopped and else branch in onPromptEnd to prevent timer race and state leak
- Mark cardState.stopped after busy-wait timeout to abandon orphaned in-flight creation
- Apply MAX_CARD_CHARS truncation with fence parity in onResponseComplete
- Sanitize senderId before <at> tag interpolation
- Use replaceAll + callback form for mention replacement
- Floor token expiry to prevent thundering herd on expire:0
- Add log for stop-button auth rejection
- Fix stoppedMessages JSDoc to match actual cleanup lifecycle
- Fix test fixture to match "still creating" scenario
- Fix typecheck errors in test file (TS2571, TS4111)
- Add stop-button auth negative path tests (operator mismatch, missing operator, missing sender)
- Replace spanning regex in table-stripping with line-by-line stripTables() to resolve CodeQL ReDoS warning

* fix(channels/feishu): fix HMAC bypass, prompt injection, SSRF, and card lifecycle from CR round 5-6

Security:
- Fix webhook HMAC bypass: use defineProperty(non-enumerable) for headers instead of prototype shadowing
- Fix cross-user prompt injection: mark quoted content as untrusted with explicit marker
- Fix SSRF: validate all Feishu IDs with FEISHU_ID_RE before URL interpolation in 6 endpoints
- Fix safeSenderId regex: add hyphen to character class so ou_abc-def-123 is not rejected

Card lifecycle:
- Set cardCreationFailed on onPromptStart failure to prevent retry spiral
- Skip throttle updates when card creation permanently failed
- Fallback to plain message delivery when cardCreationFailed with accumulated text
- Track creationTimer in CardSessionState so cleanupCard/disconnect can cancel orphaned card creation
- Add cs.stopped and else branch in onPromptEnd to prevent timer race and state leak
- Mark cardState.stopped after busy-wait timeout to abandon orphaned in-flight creation
- Apply MAX_CARD_CHARS truncation with fence parity in onResponseComplete
- Preserve atPrefix in streaming truncation to prevent @mention visual snap
- Account for suffix and fence reserve in truncation maxBody calculation
- Clean up auxiliary maps after handleInbound when gate rejects the message
- Clean up blockStreaming mode Map entries in onPromptEnd
- Skip bare @mention without question text

Markdown:
- Handle code fences in hard-split and table-stripping fallbacks
- Use parity-based fence detection in splitByTables (align with splitChunks)
- Replace spanning regex in table-stripping with line-by-line stripTables() to resolve CodeQL ReDoS warning

Defensive guards:
- Sanitize senderId before <at> tag interpolation
- Use replaceAll + callback form for mention replacement
- Floor token expiry to prevent thundering herd on expire:0
- Add log for stop-button auth rejection

Tests:
- Fix stoppedMessages JSDoc to match actual cleanup lifecycle
- Fix test fixture to match "still creating" scenario
- Fix typecheck errors in test file (TS2571, TS4111)
- Add stop-button auth negative path tests (operator mismatch, missing operator, missing sender)
- Assert cancelSession called in stop-button happy-path test

* fix(channels/feishu): add request timeouts, token dedup, and harden file/quote sanitization

* fix(channels/feishu): harden card lifecycle, webhook auth, and resource cleanup from CR round 7

* fix(channels/feishu): harden card lifecycle, mention handling, and error recovery
2026-05-28 20:11:00 +08:00
jinye
34b7d472ef
fix(telemetry): improve LogToSpan bridge error info and TUI handling (#4482)
* fix(telemetry): improve LogToSpan bridge error info and TUI handling

The OTel `LogToSpanProcessor` bridge (used when traces+metrics are over
OTLP but logs aren't, e.g. Alibaba Cloud ARMS) had two diagnostic issues:

1. Empty error messages. When the OTLP HTTP exporter callback returned
   `{ code: FAILED, error }`, `error.message` is the HTTP reason-phrase —
   always empty on HTTP/2. The bridge printed literally
   `[LogToSpan] export failed: code=1 error=` with zero actionable info.
   Now we surface `name`, `httpCode` (only when numeric), and a 200-byte
   `data` snippet from the underlying OTLPExporterError, with JSON-escape
   on user content so embedded newlines can't tear the log line.

2. TUI pollution. The processor wrote diagnostics to `process.stderr`
   directly. Ink only manages stdout, so those writes punched through
   into the rendered terminal area. The processor now accepts an
   injectable `diagnosticsSink`; in interactive mode `sdk.ts` injects a
   sink that routes through `debugLogger.warn` (file-backed). Non-
   interactive runs (CI/scripts) keep the default stderr sink so export
   failures remain visible on the canonical batch-diagnostic channel.

Backward compatibility is preserved: the legacy numeric-arg constructor
keeps stderr behavior; the options-object overload gains the new field.
Other raw `process.stderr.write` sites in the CLI (errors.ts,
startupProfiler.ts, useGeminiStream.ts, etc.) have the same TUI-leak
pattern but are intentionally left out of this PR.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): address PR #4482 review comments

- Fix TS2353 compile error in keeps-processing-after-sink-throw test:
  the mock callback type was narrowed to `{ code: number }` and rejected
  the `error?: Error` field that `ExportResult` actually carries. Widen
  the type. (wenshao Critical — this was the root cause of CI lint/test
  failures across all 3 OS.)

- JSON.stringify the payload of the `export threw` diagnostic so a
  synchronously-thrown error with embedded newlines stays on one line,
  same single-line invariant enforced by `formatExportError`. Add
  coverage for both the newline case and the non-Error throw branch.
  (wenshao Suggestion)

- Remove the dead `makeFailingProcessor(err)` call in the JSON-escape
  test that was immediately overwritten — the orphaned processor
  retained a live `setInterval` timer with no cleanup. (wenshao
  Suggestion)

- Rename the "200 bytes" test name and comment to "200 characters" to
  match the actual `string.slice(0, 200)` (UTF-16 code units) behavior;
  add a note on the cap being a leak/noise budget, not a hard byte
  limit. (Copilot 2x)

- Strengthen the non-interactive test to actually trigger a failed
  export against the real `LogToSpanProcessor` and assert the default
  sink writes to stderr, not just that `diagnosticsSink === undefined`.
  (github-actions High #2)

- Reword the "shell-active bytes" comment to "characters that would
  break log parsing" — the actual concern is log-line tearing, not
  shell semantics. (github-actions Medium)

- Update class JSDoc to mention the diagnostics-sink responsibility
  alongside the bridge purpose. (github-actions Low)

- Minor JSDoc wording fix on `LogToSpanDiagnosticsSink` type for
  clarity around the no-trailing-newline contract. (github-actions Low)

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* test(telemetry): cover two unreachable formatExportError branches

Add coverage for two paths flagged by the DEEP-tier review on #4482:

- `err.message || err.name || 'unknown'` chain: the third branch (both
  message and name empty) was never exercised. Scenario: minified
  environments that strip `Error.name`. Test constructs
  `Object.assign(new Error(''), { name: '' })` and asserts the output
  contains `error="unknown"`.

- `typeof extra.data === 'string' && extra.data.length > 0` guard: the
  empty-string case (HTTP response with empty body) was never tested,
  so a future loosening to `!== undefined` would silently start
  emitting `data=""`. Test asserts `data=` is absent.

Both branches are real and reachable in production failure modes; the
tests are guards for the documented intent.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)

* fix(telemetry): tighten LogToSpan diagnostics per wenshao review

- Quote `error="unknown"` in the err-missing early return so it matches
  the JSON.stringify output produced when message+name fall back to
  'unknown'. Two paths now emit identical greppable output for
  semantically identical "unknown error" states.

- Widen the duck-typed cast to `code?: number | string` and add a
  load-bearing comment on the `typeof === 'number'` guard. The type now
  matches reality (Node networking errors surface string codes like
  ECONNREFUSED), preventing a future simplification to `if (extra.code)`
  that would mislabel networking errors as HTTP statuses.

- Reuse `formatExportError` in the sync-throw path so a synchronously-
  thrown OTLPExporterError surfaces its httpCode and data, matching the
  callback-failure path. Non-Error throws still fall back to
  JSON.stringify on String(err) to preserve the single-line invariant.

- Include batch span count in the timeout diagnostic
  ("(N span(s))") — lets an operator distinguish slow network from
  oversized batch when troubleshooting timeouts.

- Add a test for non-string truthy err.data (Buffer) — the `typeof ===
  'string'` guard's false branch was only covered for undefined and
  empty string, so a future refactor relaxing the guard would silently
  start emitting binary garbage with no test to catch it.

- Document the QWEN_DEBUG_LOG_FILE=0 trade-off at the sink wiring site:
  interactive mode plus disabled debug log = full diagnostic silence.
  This is an accepted user opt-in trade-off; falling back to stderr
  would re-introduce the TUI pollution this injection prevents.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)
2026-05-27 20:13:51 +08:00
Kagura
c425037998
fix(cli): surface startup warnings on stderr before TUI render (#4448) (#4461)
* fix(cli): surface startup warnings on stderr before TUI render (#4448)

When settings.json has invalid JSON, the file is renamed to
.corrupted.<timestamp> and a warning is added to startupWarnings.
Previously these warnings were only rendered inside the TUI's
Notifications component, which can be obscured by the onboarding
flow ('Connect a provider') — leaving users unaware their settings
were silently reset.

Now all startup warnings are written to stderr before the TUI takes
over. This ensures the message appears in the terminal scrollback
regardless of what the TUI shows. In non-interactive mode (--prompt,
piped stdin) this is the *only* output channel for these warnings,
closing a gap where they were collected but never emitted.

* fix(cli): emit settings warnings before relaunch to ensure parent surfaces them

Move getSettingsWarnings() stderr emission to right after loadSettings(),
before the sandbox/relaunch block. This ensures the parent process prints
corruption warnings before relaunchAppInChildProcess() spawns the child
and exits.

Add regression test verifying getSettingsWarnings returns non-empty,
human-readable warnings containing 'invalid JSON' when settings.json
has broken content.

Addresses review feedback from @wenshao on #4461.
Fixes #4448

Signed-off-by: kagura-agent <kagura@openclaw.dev>

---------

Signed-off-by: kagura-agent <kagura@openclaw.dev>
2026-05-27 19:46:03 +08:00
顾盼
0c3cd0052f
feat(cli): default auto-dream/auto-skill to on and add /memory toggle (#4547)
* feat(cli): default auto-dream/auto-skill to on and add /memory toggle

Bring the managed memory pipeline closer to its intended out-of-the-box
experience: auto-dream and auto-skill now default to enabled (matching
the existing auto-memory default), so users get summarized memories and
reusable project skills without having to opt in.

The /memory dialog previously only exposed Auto-memory and Auto-dream
toggles. With auto-skill now on by default, users need an equally
discoverable way to opt out, so this adds an Auto-skill row alongside
the existing two with the same focus/Enter toggle semantics and
workspace-scoped persistence (memory.enableAutoSkill).

Default-value updates are kept consistent across all three sources of
truth (settings schema, CLI loader, core Config), and the generated
vscode settings.schema.json is regenerated to match.

* test(cli): add getAutoSkillEnabled to MemoryDialog test mock

The new Auto-skill toggle row reads config.getAutoSkillEnabled() at
render time; without it on the mocked config the component throws and
the existing list-navigation tests assert against an empty frame.

* fix(cli): guard managed auto-dream in bare mode, sync tests and docs

- enableManagedAutoDream in loadCliConfig was missing the bareMode guard
  that its two siblings already had; once the default flipped to true,
  this caused a raw-field inconsistency in bare-mode sessions (the
  getter still returned false via its own !getBareMode() guard, but the
  Config.enableManagedAutoDream field itself was now true).
- docs/users/configuration/settings.md still listed
  enableManagedAutoDream's default as false, and was missing the new
  enableAutoSkill row entirely. Both fixed.
- MemoryDialog.test.tsx now covers the autoSkill row render, the new
  focus chain (list ↑ autoSkill ↑ autoDream and back down), and the
  Enter-toggle path that writes memory.enableAutoSkill to workspace
  settings.
- config.test.ts gains a non-bare default test asserting all three
  getManaged*Enabled() / getAutoSkillEnabled() return true, and the
  bare-mode test now asserts auto-dream/auto-skill also resolve to
  false in bare mode.
2026-05-27 17:25:06 +08:00
顾盼
a5ec1af301
fix(permissions): make command substitution ask, not deny (#4093) (#4386)
* fix(permissions): make command substitution ask, not deny (#4093)

`resolveDefaultPermission` hard-denied any shell command containing
$(), backticks, <(), or >(). Two problems:

1. The deny couldn't be overridden by YOLO mode — YOLO sees the
   result only as `'ask'` or `'default'`, never `'deny'`.
2. It fired inconsistently: only when `hasRelevantRules()` happened
   to be true. A compound command like
   `echo hello && python3 -c "print($(echo hello))"` was hard-denied
   because `echo hello` matched an unrelated allow rule and made
   `hasRelevantRules()` true, while the same `python3` sub-command
   in isolation kept its L3 `'ask'` (PM skipped) and was approvable.
   Same substitution, opposite verdict — purely a function of which
   unrelated rules were loaded.

This is the surviving half of a two-step migration. `fb7e30ad3
"fix(shell): remove command substitution deny check from
getDefaultPermission"` removed the equivalent L3 deny but missed
the L4 mirror — this commit completes that cleanup.

What changes:
- `resolveDefaultPermission` no longer special-cases substitution; the
  AST read-only check already marks substitution-bearing commands as
  non-read-only, so they fall through to `'ask'` with everything else.
- Return type narrowed from `'allow' | 'ask' | 'deny'` to `'allow' | 'ask'`.
- `ToolExecuteConfirmationDetails` gains an optional `warnings?: string[]`
  field. `ShellToolInvocation.getConfirmationDetails` populates it with a
  "Contains command substitution …" line when substitution is detected
  on either the original or stripped command. The CLI confirmation
  dialog renders these as ⚠-prefixed lines in the warning color,
  mirroring Claude Code's UX (see issue thread for reference).

Out of scope: `checkCommandPermissions` in shell-utils.ts still hard-
denies substitution. That path is exercised by user-authored `!{...}`
shell injections in slash commands (shellProcessor.ts) and is a
prompt-injection defense, not the agent-tool path #4093 describes.

Regression coverage:
- permission-manager.test.ts: new `command substitution (issue #4093)`
  describe with 5 cases — standalone $(), the exact compound from the
  issue, backticks, <(), and deny-rule precedence.
- shell.test.ts: new `command substitution warning (issue #4093)`
  describe with 4 cases — $()/backticks/<() each surface a warning,
  plain commands do not.
- ToolConfirmationMessage.test.tsx: 2 new render tests.

Fixes #4093

* fix(cli): reserve warnings height in exec confirmation layout (#4386 review)

Addresses two round-1 findings from Copilot on PR #4386:

1. ToolConfirmationMessage: the warnings block was rendered as a sibling
   *below* the MaxSizedBox-capped command body (with marginTop=1), but
   the height budget computed by availableBodyContentHeight() — and the
   compactMode cap of COMPACT_BODY_MAX_LINES — didn't account for the
   extra lines. On small terminals + compactMode this could push the
   options list off-screen. Reserve the warnings footprint
   (`warningsCount + 1` for marginTop) up-front so the overall exec
   block respects availableTerminalHeight / COMPACT_BODY_MAX_LINES.

   Added a regression test (`keeps options visible alongside the
   warning on a tight compactMode layout`) that renders a substitution
   command with `availableTerminalHeight=10` + `compactMode=true` and
   asserts both the warning text and all three compactMode option
   labels remain on-screen.

2. permission-manager.test.ts: the new `command substitution (issue
   #4093)` describe had a misleading inline comment that conflated the
   issue's original scenario (`echo hello && python3 ...` + `Bash(echo *)`)
   with the test fixture (`git status && python3 ...` + `Bash(git *)`).
   Rewrote it to describe what the test actually does (`git status`
   matches `Bash(git *)`, making hasRelevantRules() true; the python3
   sub-command then resolves via resolveDefaultPermission).

* fix(permissions): align monitor + propagate warnings to ACP/non-interactive (#4386 review)

Addresses round-2 review findings from wenshao on PR #4386. Four
related findings, all about sibling drift from the original #4093 fix:
either the same hard-deny-on-substitution pattern in a sibling tool, or
downstream consumers that don't propagate the new warnings field.

1. monitor.ts: `MonitorToolInvocation.getDefaultPermission()` had the
   identical `detectCommandSubstitution → 'deny'` pattern that the
   original PR removed from `PermissionManager.resolveDefaultPermission`
   — sibling drift the original audit missed. Same UX problems apply
   (YOLO unbypassable, opaque deny). Removed the deny branch, added
   the substitution warning in `getConfirmationDetails` (mirroring
   ShellToolInvocation), updated the 5 existing tests that asserted
   the old 'deny' to assert 'ask', and added a confirmation-warning
   test for the issue #4093 mirror case. Monitor still maintains its
   separate permission boundary (Monitor(...) rules don't share with
   Bash(...) — documented in the unchanged comment at the top of
   getConfirmationDetails); only the substitution-deny half is removed.

2. ACP `buildPermissionRequestContent` (permissionUtils.ts): had no
   `exec` branch, so the new `warnings` field never reached ACP
   clients (IDE integrations etc.). Added an `exec` branch that emits
   one `⚠ <warning>` text content per warning, alongside the existing
   `edit` (diff) and `plan` (text) branches. Two regression tests
   added: warning present → ⚠ content entry; no warnings → empty.

3. Non-interactive `permissionController.buildPermissionSuggestions`:
   the `case 'exec'` description string didn't read `warnings`, so
   daemon/API consumers that delegate the approval decision back to
   a user lost the substitution context. Appended warnings as a
   parenthesized `⚠ ...` suffix to the description string. (No test
   file exists for this controller — change is small and verifiable
   by inspection; adding test scaffolding is out of scope for this
   round.)

4. Test coverage: the `command substitution (issue #4093)` describe
   blocks in `shell.test.ts` and `permission-manager.test.ts` covered
   `$()`, backticks, and `<()` but not `>()` — even though
   `detectCommandSubstitution` and the warning text both list it.
   Added a `>()` case to each block to close the regression gap.

* fix(cli): wrap-aware warnings reservation + load-bearing regression test (#4386 self-review)

Two related self-review findings from my pre-push review on PR #4386:

1. SR-1: the round-1 layout regression test
   (`keeps options visible alongside the warning on a tight compactMode
   layout`) used a single-line command at `contentWidth=80`. `MaxSizedBox`
   clamps to `min(content_lines, maxHeight)`, so a 1-line command
   renders as 1 line regardless of whether `bodyContentHeight -=
   warningsHeight` is applied — the test would still pass if that line
   were silently removed. Replaced with a 4-line command and an
   assertion on the `... N lines hidden ...` truncation footer that
   MaxSizedBox emits *only* when its cap is actually active. Confirmed
   RED → fix → GREEN: the new test fails when the warnings
   subtraction is removed and passes when restored.

2. SR-2: the warnings-height reservation reserved `warningsCount + 1`
   lines (one per warning + one marginTop separator). On narrow
   terminals the warning text wraps across multiple visual rows, so
   the reservation under-counts. Replace the per-warning `+1` with
   `ceil((warning.length + 2) / max(contentWidth, 1))` to account for
   each warning's actual rendered row count. The `+ 2` accounts for
   the `⚠ ` prefix; the `max(...,1)` keeps the math defined for
   pathological inputs. Independently flagged by Codex during
   self-review as `[P3] Account for wrapped warning lines`.

* fix(core): log substitution audit trail on YOLO/auto bypass (#4386 review)

Round-3 review caught a real observability gap: when `needsConfirmation`
returns false (YOLO mode at line 1791, or auto-approve at line 1740),
the scheduler skips `getConfirmationDetails()` entirely and the
substitution warning generated there never reaches the user. Pre-#4093
this didn't matter because substitution hard-denied before reaching
the bypass; post-#4093 it executes silently with no audit trail.

YOLO/auto by design execute arbitrary LLM-emitted commands without
warnings — bypassing the substitution warning isn't a new
vulnerability vs. e.g. an unwarned `rm -rf /tmp/x`. But operators
troubleshooting a prompt-injection incident need an audit trail.

Adds a module-level `maybeLogSubstitutionBypass()` helper that emits a
`debugLogger.warn` only when (a) the canonical tool name is in the
shell-like audit set (RUN_SHELL_COMMAND / MONITOR) AND (b) the command
arg contains substitution. Called from both bypass branches with a
`yolo` / `auto-approve` discriminator so the audit log identifies
which path bypassed.

DEBUG-only — silent at default verbosity, no noise for typical YOLO
users; forensic signal lives in `DEBUG=*` traces. No separate test
added: `debugLogger` is module-private (created at the top of
coreToolScheduler.ts), and mocking the createDebugLogger module is
disproportionate complexity for a DEBUG-only audit signal whose
logic is a 7-line guard chain.

* refactor(core): extract substitution warning constant + helper, plus permissionController test (#4386 review)

Round-3 review cleanup, bundling 4 small related findings:

1. **Extract `COMMAND_SUBSTITUTION_WARNING` constant** (`shell-utils.ts`).
   The user-facing warning string was hardcoded identically in two
   source files (`shell.ts`, `monitor.ts`); tests assert via regex so
   the constant doesn't break them. Co-located with
   `detectCommandSubstitution` since they share the same domain.

2. **Extract `buildShellExecWarnings()` helper** (`shell-utils.ts`).
   The 6-line warnings-building pattern was duplicated between
   `ShellToolInvocation.getConfirmationDetails` and
   `MonitorToolInvocation.getConfirmationDetails` — same two-input
   substitution check (stripped + raw command), same literal push,
   same undefined-on-empty contract. Both call sites collapse to a
   one-liner. This is a mechanism lift, not a boilerplate lift —
   the helper captures non-trivial behavior. The
   `checkCommandPermissions` path in `shell-utils.ts` intentionally
   keeps its own deny-reason string (different code path, different
   threat model — prompt-injection defense for `!{…}` slash commands).

3. **Drop unnecessary non-null assertion** in
   `ToolConfirmationMessage.tsx`. Line 268 already defines
   `const warnings = executionProps.warnings ?? []`; the JSX block was
   using `executionProps.warnings!.map(...)` which (a) reaches past
   the null-safe local and (b) misleads readers about whether the
   field is actually guaranteed-defined.

4. **Add `permissionController.test.ts`** covering the
   `buildPermissionSuggestions` exec branch added in commit 7bb420562.
   Seven cases: warning-present (single + multiple), non-string
   filtering, warning-absent (missing key + empty array + malformed
   non-array), and the null-payload return for invalid input. No test
   file existed for this controller before; the new file establishes
   the pattern for the four sibling controllers, but stays scoped to
   only the method under review.

* fix(core): close AST substitution gaps and log AST parser failures (#4386 R4)

Round-4 critical findings from wenshao:

1. **AST substitution blind spots in non-`command` node types** —
   `evaluateStatementReadOnly` (shellAstParser.ts) only checked
   `containsCommandSubstitutionAST` inside the `command` node branch.
   Substitution living in OTHER node types slipped through as
   read-only, causing `resolveDefaultPermission` to return `'allow'`
   and `coreToolScheduler` to auto-approve silently. Verified blind
   spots (tests added):
     - `variable_assignment` / `variable_assignments`:
       `FOO=$(curl evil)` and `FOO=$(cat /etc/shadow) ls` were read-only
     - Backtick form: `FOO=\`cat /etc/shadow\`` was read-only

   The pre-PR #4386 regex check in `resolveDefaultPermission` was a
   safety net masking these AST gaps; removing it without patching
   the AST was a real security regression.

   Fix: hoist the `containsCommandSubstitutionAST` guard to the top
   of `evaluateStatementReadOnly` so every node type inherits the
   check in one place. Net behavior: substitution anywhere in the
   statement subtree marks the whole statement as non-read-only,
   matching the contract the function's docstring (and the comment
   in `resolveDefaultPermission`) already claimed.

   Tests follow Step 7.1 RED → fix → GREEN ordering: confirmed each
   of the 3 affected shapes was misclassified as read-only before
   the AST hoist, and all 4 cases pass after.

2. **Silent catch in `resolveDefaultPermission`** — the `try/catch`
   around `isShellCommandReadOnlyAST` swallowed parser exceptions
   without logging. With the regex safety net gone, the AST check is
   now the sole gatekeeper, so a parser regression would silently
   route every command to 'ask' with no trace. Added the same
   `debugLogger.warn` already used by the equivalent catches in
   `shell.ts` (line 1394) and `monitor.ts` (line 192).

3. **Misleading comment** in `resolveDefaultPermission` already
   asserted "the AST walker marks any node with a substitution
   expansion as non-read-only" — true post-fix, but false pre-fix.
   Updated to reference the load-bearing top-level guard in
   `shellAstParser.ts` so the claim is verifiable from one place.

Closes wenshao R4 findings: AST blind spots (`permission-manager.ts:417`
+ `shellAstParser.ts:884`), silent catch (`permission-manager.ts:415`).

* fix(core): extend substitution audit log + dual-check stripped form (#4386 R4)

Round-4 audit-log consistency fixes from wenshao:

1. **Dual-check stripped form in audit predicate** — round 3's
   `maybeLogSubstitutionBypass` only ran `detectCommandSubstitution`
   on the raw command, but `buildShellExecWarnings` (the
   confirmation-dialog warning helper extracted in round 3) checks
   BOTH the raw and the `stripShellWrapper`-stripped forms. For
   wrappers like `bash -c 'echo $(cat secret)'` the `$(` sits inside
   the outer single quotes, so raw-check returns false but the inner
   shell still expands the substitution. Result: dialog showed the
   warning, audit log silently dropped it — exactly the wrapper
   pattern an exfiltration attack would use. Refactored the helper
   to extract a pure predicate `shouldAuditSubstitutionBypass` that
   does the dual-check, exported for unit testing.

2. **JSDoc correction** — round 3's JSDoc claimed "DEBUG-level log
   here so the signal exists when `DEBUG=*` is set". Both clauses
   were wrong: the call uses `debugLogger.warn` (WARN level), and
   `debugLogger` is controlled by `QWEN_DEBUG_LOG_FILE` (active by
   default) rather than the `DEBUG=*` convention of the `debug` npm
   package. Rewrote the doc to match the real semantics.

3. **Audit log on three more auto-approve bypass paths** — round 3
   only covered the YOLO and auto-mode-`approved` bypasses, missing
   three other paths that auto-approve without invoking
   `getConfirmationDetails()`:
     - PM `'allow'` fast path (coreToolScheduler.ts:1664) — fires
       when an allow rule matches a substitution-bearing command
       (e.g. `allow Bash(python3 *)` + `python3 -c "$(...)"`).
     - permission-request hook `shouldAllow` (line ~1896) — fires
       when an external hook grants permission directly.
     - `autoApproveCompatiblePendingTools` sibling-tool ProceedAlways
       (line ~3300) — fires when one tool's user-issued ProceedAlways
       outcome rolls up to a sister tool. Uses `canonicalToolName`
       to normalise the legacy name in the audit log.

   New `SubstitutionBypassReason` discriminator union surfaces the
   bypass path in the log so operators can distinguish them.

4. **Unit test coverage** — added a `shouldAuditSubstitutionBypass`
   describe block to `coreToolScheduler.test.ts` covering all 8
   branches: non-shell tool, missing args, non-string command,
   absent substitution, direct substitution (shell + monitor), the
   load-bearing wrapper case (proves the dual-check works), backtick
   substitution, and env-prefix substitution.

Out of scope: reviewer also suggested forcing `'ask'` whenever
substitution is detected with a matching allow rule. Declined —
would partially re-introduce #4093 (substitution can't be allowed
via rules even with explicit user intent), and overrides the
allow-rule "trust this pattern" semantics. The audit-log extension
above gives operators the visibility they asked for without
overriding user-configured permission policy.

Closes wenshao R4 findings: dual-check (cids 3293074365, 3293075616),
JSDoc level/envvar (cids 3293074371, 3293075619), audit on PM-allow
(cid 3293078740 — partial), audit on hook + sibling-auto (rid 4351040390
non-diff), and test coverage for the predicate (cid 3293078758 — partial).

* test(core): cover env-prefix substitution + buildShellExecWarnings dual-check (#4386 R4)

Round-4 test-coverage findings from wenshao:

1. **env-prefix integration test in `shell.test.ts`** (cid 3293075622) —
   the `command substitution warning (issue #4093)` describe block in
   `shell.test.ts` covered `$()`, backticks, `<()`, `>()`, and the
   no-warning case, but had no test for the shape where
   `stripShellWrapper` strips the env-prefix + `bash -c` wrapper to
   yield a substitution-free inner command (`echo ok`) while the raw
   command has substitution in the env assignment
   (`FOO=$(cat secret.txt) bash -c 'echo ok'`). This is the exact
   shape that exercises the `|| detectCommandSubstitution(rawCommand)`
   branch of `buildShellExecWarnings` via integration through
   `getConfirmationDetails`. Without this test, removing the `||`
   clause wouldn't regress any case here.

2. **`buildShellExecWarnings` unit tests in `shell-utils.test.ts`**
   (cid 3293078758 second half) — round 3 extracted
   `buildShellExecWarnings` as an exported helper but added no direct
   unit test. Added a 5-case describe block covering: no substitution,
   stripped-form substitution, the env-prefix dual-check case (with
   a sanity-check that the stripped form actually lacks `$(` to make
   the dual-check load-bearing), backticks, and process substitution.
   These complement the integration tests in shell.test.ts /
   monitor.test.ts which exercise the helper through the tool
   confirmation paths.

Closes wenshao R4 findings: env-prefix integration test
(cid 3293075622), `buildShellExecWarnings` direct unit coverage
(cid 3293078758 — second half).

* fix(test): drop duplicate ToolNames import in coreToolScheduler.test (#4386 R4 CI)

Round-4 commit a24485029 added `import { ToolNames }` without checking
the file already had `import { ToolNames, ToolNamesMigration }` at line
35. Vitest's esbuild was permissive about the duplicate (silently used
the latter) so the test file passed locally and `npx tsc --noEmit` on
the package didn't complain either — but CI's `tsc --build` is strict
and errored with TS2300 "Duplicate identifier 'ToolNames'", taking down
Lint + all three test platforms + Coverage in one go (run 26382523711).

Removed the duplicate import. Verified locally via `rm -rf
packages/core/dist && npx tsc --build` (clean) + `npx vitest run`
(171/171 pass).

* fix(core): close env-prefix wrapper substitution bypass at L3 (#4386 R6)

Round-6 review caught a real Critical security regression my R0 +
R4 audits both missed.

**The bug.** `ShellToolInvocation.getDefaultPermission()` calls
`stripShellWrapper(this.params.command)` BEFORE the AST check. For
`FOO=$(curl evil) bash -c 'echo ok'`, `stripShellWrapper` discards the
env-prefix AND unwraps the `bash -c` wrapper, yielding `echo ok` — a
substitution-free residual that the AST classifies as read-only.
Result: L3 returns `'allow'` → coreToolScheduler fast-allow at
line 1664 auto-approves silently with no confirmation dialog and no
user-visible warning.

The R4 top-level AST guard (`evaluateStatementReadOnly` ↳
`containsCommandSubstitutionAST`) only catches substitution that
survives `stripShellWrapper` to enter the parsed tree. The env-prefix
+ wrapper shape gets stripped to nothing visible, so the AST guard is
asked to inspect a clean tree and returns true. The pre-#4386 regex
`detectCommandSubstitution` in `resolveDefaultPermission` was a safety
net masking exactly this gap — R0 removed it without recognising the
strip-before-check pattern.

Probe (vitest harness, real `isShellCommandReadOnlyAST`):
```
{
  raw: "FOO=`whoami` bash -c 'ls'",
  stripped: "ls",
  ast_on_stripped: true,   // ← classifies as read-only
  ast_on_raw: false        // ← R4 guard works on raw
}
```

**The fix — `hasShellSubstitution` single source of truth.**
Extracted dual-check predicate (`detectCommandSubstitution(raw) ||
detectCommandSubstitution(stripShellWrapper(raw))`) into
`shell-utils.ts hasShellSubstitution(rawCommand)`. The raw arm catches
the env-prefix-wrapper shape; the stripped arm catches the inside-
single-quoted-wrapper-body shape that R3 already documented. Single
predicate keeps detection semantics in lockstep across all surfaces.

Gates added at:
- `ShellToolInvocation.getDefaultPermission` (shell.ts:1384) — primary
  fix for the cited bug
- `shellReadOnlyChecker.ts evaluateShellSegment` (line 298) — regex
  fallback path has the same strip-before-check pattern; only hit when
  WASM parser fails, but same root cause
- `MonitorToolInvocation.getDefaultPermission` (monitor.ts:174) —
  belt-and-suspenders; `normalizeMonitorShellCommand`'s `safetyCommand`
  preserves env-prefix tokens so the AST already sees substitution
  there, but the gate parallels shell.ts in case
  `normalizeMonitorShellCommand`'s env-preservation ever regresses
- `PermissionManager.resolveDefaultPermission` (permission-manager.ts:413)
  — belt-and-suspenders; the raw command reaches the AST already, but
  the reviewer-requested gate makes the intent grep-discoverable

Refactor (Finding C, cid 3298521063): `buildShellExecWarnings` and
`shouldAuditSubstitutionBypass` both now delegate to
`hasShellSubstitution`, addressing the reviewer's concern that the
audit-log path and the UI-warning path were maintaining parallel
dual-check implementations that could silently diverge.

**Test-first per skill Step 7.1.** Two new tests in `shell.test.ts`
under `getDefaultPermission and getConfirmationDetails`:
- `asks (not allow) for env-prefix substitution inside a bash wrapper`
- `asks for backtick env-prefix substitution inside a bash wrapper`

Both confirmed RED pre-fix (`expected "ask" got "allow"`); GREEN
post-fix. Wider sweep (1262 tests across 19 files in permissions,
tools, utils, core, cli) all green; tsc --build clean (matching CI's
strict build).

Out of scope for this commit (deferred to follow-up #4509):
- R6 Finding B (dead catch blocks in resolveDefaultPermission / shell /
  monitor) — appended to #4509
- R6 Finding D (Record<string, unknown> cast in permissionController
  exec branch — could use discriminated-union narrow) — appended to #4509
- R6 Finding E (O(N×D) DFS in evaluateStatementReadOnly — could be
  hoisted to isShellCommandReadOnlyAST as O(N) root-level check) —
  appended to #4509

Closes wenshao R6 findings: env-prefix wrapper bypass (cid 3298521039 —
Critical, fixed) + dual-check DRY (cid 3298521063 — fixed as side
effect of A's refactor).

* revert: remove substitution audit-log infrastructure (#4386 cleanup)

Reverts:
- fd2cf080d "fix(core): log substitution audit trail on YOLO/auto bypass"
- a24485029 "fix(core): extend substitution audit log + dual-check stripped form"

The audit-log infrastructure was originally added in R3 as a self-Codex
suggestion (forensic visibility when YOLO bypasses the substitution
warning) and extended in R4 to PM-allow / hook / sibling-auto paths.
None of this is what issue #4093 asked for — #4093 is purely about
making substitution `'ask'` instead of `'deny'` so YOLO can override
and the behavior is consistent across rule configurations. The audit
log is debug-only forensic polish on a UX warning, not part of the
permission-decision fix.

Each subsequent review round (R4/R5/R6/R7) then surfaced sibling-drift
findings on this infrastructure — PM-allow audit, hook audit, ACP
audit-log parity, callId enrichment, dual-check asymmetry, integration
tests — all of which were tracking the same out-of-scope addition.
Removing the infrastructure removes the surface entirely.

`hasShellSubstitution` (added in 5a5cfb4fc) is kept — it's still used
by `shell.ts` L3 substitution gate and `buildShellExecWarnings`, both
of which ARE in scope for #4093.

* cleanup: remove out-of-scope additions from R2/R3/R6 review (#4386)

Surgical reverts that complement a5d9f087e (audit-log infrastructure
revert). These changes were accepted in earlier review rounds but were
out of scope for issue #4093 — a bug-fix PR whose stated goal is to
make command substitution `'ask'` instead of `'deny'` so YOLO can
override and the behavior is consistent across rule configurations.
Anything beyond that fix is unrelated to the bug and not this PR's
responsibility.

Removed:

1. **ACP `permissionUtils.ts`: `exec` branch in
   `buildPermissionRequestContent`** (R2, commit 7bb420562). The new
   `warnings` field propagation to ACP clients (VS Code extension,
   daemon) was UX polish on a different surface. Not what #4093 asked
   for. Plus the two regression tests in `permissionUtils.test.ts`.

2. **Non-interactive `permissionController.ts`: `case 'exec'`
   warning-suffix on the suggestion description** (R2, commit 7bb420562).
   Same pattern as above — warning propagation to daemon/API consumers
   on a non-primary surface. Plus the entire
   `buildPermissionSuggestions — exec warnings` describe block I added
   to `permissionController.test.ts` (R3, commit baa1e9f78). Main's
   #4491 timeout tests (which merged in via 6342d2810) are preserved.

3. **`monitor.ts` belt-and-suspenders `hasShellSubstitution` gate**
   (R6, commit 5a5cfb4fc). I added this with an explicit "if
   normalizeMonitorShellCommand's env-preservation ever regresses"
   justification — i.e. defense-in-depth on a non-existent bug. Not
   what #4093 asked for.

4. **`permission-manager.ts` belt-and-suspenders `hasShellSubstitution`
   gate at `resolveDefaultPermission`** (R6, commit 5a5cfb4fc). Same
   pattern — reviewer-requested gate on top of a code path the R4 AST
   guard already covered. Not what #4093 asked for.

What's kept (in scope for #4093):

- L4 `deny → ask` in `resolveDefaultPermission` (the actual fix)
- `warnings?: string[]` field on `ToolExecuteConfirmationDetails` +
  CLI rendering — #4093 explicitly asks for a user-visible reason
- `ShellToolInvocation.getDefaultPermission` env-prefix wrapper gate
  (R6, 5a5cfb4fc) — closes a real `'allow'` regression on substitution
- `shellReadOnlyChecker.ts` regex-fallback raw-check (R6, 5a5cfb4fc)
  — same root-cause bug on the WASM-fallback path
- AST top-level substitution guard in `evaluateStatementReadOnly`
  (R4, 42debd13d) — closes real AST blind spots
- `hasShellSubstitution`, `buildShellExecWarnings`,
  `COMMAND_SUBSTITUTION_WARNING` helpers — still used by the above
- Monitor tool's `'deny' → 'ask'` alignment for substitution (R2,
  7bb420562) — same root-cause as the main fix
2026-05-27 17:06:48 +08:00
顾盼
5ad5301805
feat(worktree): Phase D — startup --worktree flag + symlinkDirectories + PR refs (#4381)
* feat(worktree): Phase D — startup --worktree flag + symlinkDirectories + PR refs

Three cross-cutting capabilities on top of the Phase A-C worktree
foundation (PRs #4073, #4174).

D-1: --worktree [name] CLI flag creates a worktree (or re-attaches to
one that already exists) before any model turn runs. Supports bare,
plain-slug, `=`, and PR-reference forms; --worktree + --acp rejected
with a clear error; --worktree + --resume overrides the resumed
session's saved sidecar and emits a stderr line.

D-2: worktree.symlinkDirectories: string[] settings key opts into
symlinking main-repo directories (e.g. node_modules) into every
newly-created general-purpose worktree. Applies to all three creation
paths: --worktree flag, EnterWorktreeTool, AgentTool isolation. Path
traversal, absolute paths, and existing destinations all guarded;
missing source dirs and EEXIST silently skipped (fail-open).

D-3: --worktree=#<N> / --worktree <github-url> resolves a PR number,
runs `git fetch origin pull/<N>/head` (30s timeout, no `gh` CLI
dependency, LANG=C for stable error-taxonomy matching), and creates
the worktree off FETCH_HEAD. URL regex tolerates /files, /commits,
/checks sub-paths so users can paste any GitHub PR URL.

Phase 6 verification fixes also included:
- Re-attach to an existing worktree instead of failing with "Worktree
  already exists" — the common `qwen --resume <sid> --worktree foo`
  workflow now succeeds. The session ownership marker is preserved on
  re-attach so cross-session exit_worktree action="remove" still fails
  for non-owners.
- Normalize path-taking argv fields (mcpConfig, jsonSchema @<path>,
  openaiLoggingDir, jsonFile, inputFile, telemetryOutfile,
  includeDirectories) to absolute paths against the launch cwd BEFORE
  the worktree chdir. Otherwise downstream fs.existsSync('./mcp.json')
  resolves into the worktree, where the file doesn't exist.

Phase 7 code-review fixes:
- buildStartupWorktreeNotice differentiates "Active worktree" (fresh
  create) from "Re-attached to worktree" (re-attach path).
- Notice survives sidecar persist failure: set before the try block,
  refreshed inside with override addendum if persist succeeded.
- getRegisteredWorktreeBranch verifies the candidate path's git
  common-dir matches the source repo's — rejects sibling `git init`
  directories that happen to be on a worktree-<slug> branch.

Three-mode parity for the startup notice: TUI consumes via
AppContainer effect, headless prepends a <system-reminder> + emits a
worktree_started JSON event. ACP path is mutually exclusive with
--worktree (ACP hosts supply per-session cwd separately).

Tests (66 + 15 new):
- 15 cli/src/startup/worktreeStartup.test.ts (slug forms, PR fetch
  against local fake remote, re-attach happy + wrong-branch guard)
- 8 core/src/services/gitWorktreeService.test.ts (parsePRReference:
  #N, URLs, malformed, traversal, leading zeros, non-string)
- 10 core/src/services/gitWorktreeService.symlinks.integ.test.ts
  (symlink loop + fetchPullRequestRef error taxonomy)

Known limitations (documented in docs/users/features/worktree.md):
- Cross-slug --resume <sid> --worktree <different-new-slug> is
  unsupported by design (sessions are bound to projectHash(cwd));
  future Config refactor anchoring storage at repo root would lift this.
- Mid-session enter_worktree still does NOT switch cwd/targetDir
  (Phase A's simplification); only the startup --worktree flag does.
- yargs ambiguity: `qwen --worktree "say hi"` consumes the prompt as
  the slug. Quick Start shows the `=` form and reordering workarounds.

Docs:
- docs/users/features/worktree.md (new): Quick Start with --worktree
  flag, CLI Reference table for all four input forms + error codes,
  settings table, Limitations.
- docs/design/worktree.md: Phase D section expanded into D-1/D-2/D-3
  with open questions resolved; capability table updated.
- docs/e2e-tests/worktree-phase-d.md (new): full E2E plan with Phase 4
  dry-run baseline + Phase 6 post-impl reproduction tables.

Refs #4056

* refactor(worktree): apply self-review feedback on Phase D

Self-review pass over the Phase D commit (2636f59273) catching one real
typecheck regression plus a batch of small quality + efficiency
improvements. No user-visible behavior change beyond fixing the build.

Build fix:
- worktreeStartup.ts imports — pre-commit prettier had reorganized
  `writeWorktreeSession` and `readWorktreeSession` under an
  `import type { ... }` block, erasing them at compile time
  (verbatimModuleSyntax). `tsc --noEmit` was failing with TS1361.
  Bundle path still worked (esbuild is lenient) so this only surfaced
  when running typecheck.

Startup-path efficiency (~10-25 ms saved per --worktree invocation on
macOS; more on Windows):
- Drop redundant `isGitRepository()` probe — `getRepoTopLevel()`
  returns null on non-git paths and covers both gates in one
  subprocess.
- Run `getCurrentBranch()` + `getCurrentCommitHash()` in parallel via
  Promise.all (independent calls).
- Combine the two `git rev-parse` probes inside
  `getRegisteredWorktreeBranch` into a single multi-arg call, and run
  it in parallel with the source-repo common-dir lookup. Saves one
  fork+exec on the re-attach path.

Quality:
- Extract `withReminder()` local helper in nonInteractiveCli.ts so the
  startup-notice and resume-restore branches share the system-reminder
  wrapping.
- Log `readWorktreeSession` failures in `persistStartupWorktreeSidecar`
  with the sidecar path so operators can recover the previous slug
  from a backup. Silent swallow was making "where did my worktree
  binding go?" undebuggable.
- Drop the dead `Config.getWorktreeSettings()` accessor (only
  `getWorktreeSymlinkDirectories()` has callers); keep the underlying
  `WorktreeSettings` interface for future fields.
- Document the `pendingStartupWorktreeNotice` invariant: at most one
  consumer per process; ACP path is gated out earlier so only TUI XOR
  headless reads it.
- Add a maintainer note in the gemini.tsx path-normalization block:
  the argv path-field allowlist is hand-maintained, register new
  path-bearing flags there or `--worktree` silently breaks for them.
- Drop `Phase 6 fix (G1)/(G2)` parenthetical labels from inline
  comments — internal review-cycle identifiers that decay to noise
  post-merge. Substantive prose retained.

Tests: cli 15/15 (unchanged) + core 66/66 (unchanged); bundle smoke
verified fresh / re-attach / invalid slug / non-git cases.

Findings deliberately left for follow-up:
- Larger refactor extracting a shared `provisionUserWorktree` helper
  for the EnterWorktreeTool / startup overlap (~80% duplicate).
- Splitting the re-attach branch out of `setupStartupWorktree` into
  its own function.
- `isPathWithinRoot` / `isInsideManagedWorktree` shared utils.
- `symlinkConfiguredDirectories` loop concurrency (saves 5-15 ms on a
  cold path that runs only when symlinkDirectories is configured).

* docs(worktree): refresh stale docstring in worktreeStartup

Top-of-file docstring still said `{adj}-{noun}-{4hex}` (actual format
is 6 hex chars) and described the PR form as "detected and rejected
with a clear 'coming in D-3' message" — but D-3 shipped in the same
PR. Tighten to reflect what the code actually does.

* fix(worktree): address findings from dual-reviewer self-check

Two real bugs surfaced by an independent dual-reviewer pass (Claude +
Codex) on the Phase D commits. Both correctness-affecting; both
escaped the earlier internal reviews.

P0 — re-attach captured the wrong baseline for the exit dialog
(Codex):
  setupStartupWorktree captured `originalHeadCommit` from the launch
  cwd (main checkout) before any chdir. On the re-attach path the
  WorktreeExitDialog later runs `git rev-list <originalHeadCommit>..HEAD`
  inside the worktree to count "new commits this session". With the
  main-checkout baseline this counted every commit ever made in the
  kept worktree as new work from the current session — misleading the
  keep/remove prompt. Re-capture HEAD from inside the worktree after
  chdir so the count means what the dialog text says it means.

P0 — getRegisteredWorktreeBranch mis-identified plain directories as
registered worktrees (Claude):
  A plain directory at `<repo>/.qwen/worktrees/<slug>/` (e.g. a stale
  artifact from a previous tool) had no `.git` file of its own, so
  `git rev-parse --git-common-dir` walked up to the outer repo and
  returned the outer common-dir — matching the source repo's
  common-dir check and impersonating a registered worktree. If the
  outer repo happened to be on `worktree-<slug>`, setupStartupWorktree
  would silently chdir into the plain directory and treat it as
  attached; subsequent `exit_worktree action="remove"` would then
  delete a directory that was never registered.
  Fix: also probe `--show-toplevel` and require it to equal the
  candidate path (canonicalised via `realpath` so macOS /var → /private/var
  doesn't break the equality check). A plain dir under the main repo
  gets the outer repo's toplevel and is correctly rejected.

Smaller polish from the same review:
- Normalize the literal string `'HEAD'` returned by `getCurrentBranch`
  on detached HEAD to `undefined`, so the `baseRef` handed to
  `git worktree add -b … HEAD` does not implicitly anchor against
  the loose commit when the launch cwd is detached.
- `symlinkConfiguredDirectories`: blocklist `.git` (any nested
  ancestor) and `.qwen/worktrees` (any nested ancestor). Linking
  `.git` would silently break commits inside the worktree; linking
  `.qwen/worktrees` would create a worktrees-inside-worktrees loop
  that confuses the startup sweep.
- `WorktreeSettings.symlinkDirectories` typed `readonly string[]` to
  match the `createUserWorktree(options.symlinkDirectories)` contract
  and the immutable-config convention elsewhere. `Config.getWorktreeSymlinkDirectories()`
  return type updated to match.

Docs:
- design/worktree.md precedence table rewritten. The previous
  `--worktree` 赢 row was unreachable in practice (sessions are bound
  to `projectHash(cwd)`, and the chdir happens before session lookup).
  New table reflects what actually happens for each combination of
  `--resume` × `--worktree`, including the documented
  cross-projectHash limitation. The `persistStartupWorktreeSidecar`
  override branch is now annotated as dead-on-the-current-architecture
  but kept so a future Config refactor (anchor storage at repo root)
  picks it up for free.

Tests: cli 15/15 + core 66/66 unchanged. Bundle smoke confirms both
P0 fixes end-to-end (re-attach captures worktree HEAD = run-1 tip,
plain-dir attempt errors out without clobbering existing content).

* refactor(worktree): consolidate probe + name detached-HEAD sentinel

Second /simplify pass on the dual-reviewer fixes. Three convergent
findings; net effect is one fewer subprocess on the re-attach path
and clearer intent on string handling / blocklist guards.

Efficiency + quality:
- Fold the worktree HEAD SHA into `getRegisteredWorktreeBranch`'s
  combined rev-parse. The probe already requests common-dir,
  toplevel, and abbrev-ref HEAD in a single subprocess; adding a
  leading `HEAD` positional (which must come BEFORE `--abbrev-ref` so
  the flag doesn't apply to it) returns the SHA on its own line.
  Return type widened to `{ branch, headCommit } | null`. Removes
  the second `GitWorktreeService` instantiation and `getCurrentCommitHash`
  call that `setupStartupWorktree`'s re-attach branch used to do.

Quality:
- Hoist `'HEAD'` to a module-level `DETACHED_HEAD` constant in
  `worktreeStartup.ts`. Three uses, two meanings (input filter when
  normalizing `getCurrentBranch` output, fallback metadata for the
  sidecar's `originalBranch` field on detached state). Naming the
  sentinel makes intent self-documenting and pre-empts the "why is
  the value we just stripped re-appearing as a fallback?" reader stall
  flagged by the round-3 quality review.

Reuse + quality:
- `symlinkConfiguredDirectories`: replace two hand-rolled containment
  checks (`startsWith(prefix + sep)` for `.qwen/worktrees`; `path.relative(...).split(sep)[0]`
  for `.git`) with `isWithinRoot` from `utils/fileUtils.ts`, which is
  already imported in this file. Replace the hardcoded
  `path.join(repoRootAbs, '.qwen', 'worktrees')` with `this.getUserWorktreesDir()`
  so the layout lives in one place (the exported `WORKTREES_DIR`
  constant). Split the misleading `sourceAbs === repoRootAbs` clause
  out of the `.git` branch into its own dedicated "empty / repo-root
  path" rejection with a clearer warn message.

Tests: cli 15/15 + core 66/66 unchanged. Bundle smoke verified the
folded probe still captures the worktree's HEAD on re-attach (not
the launch-cwd HEAD).

Skipped from this review pass:
- Moving `'HEAD'` normalization into `GitWorktreeService.getCurrentBranch()`
  itself — would ripple through `enter-worktree.ts` and `agent.ts`
  callers that hand the result verbatim to `git worktree add -b ...`.
  Out of scope for a polish pass; the local const is enough.

* fix(worktree): broaden symlink blocklist from .qwen/worktrees to all of .qwen

Caught by a second pr-tracker dual-reviewer pass (Codex). The previous
guard at `symlinkConfiguredDirectories` only refused paths inside
`<repoRoot>/.qwen/worktrees/` — `.qwen` itself (the parent) sailed
through because `isWithinRoot` is a strict descendant check. A user
setting `symlinkDirectories: ['.qwen']` would therefore symlink the
entire CLI metadata tree into the new worktree, recursively pulling
in `.qwen/worktrees` and recreating the loop the guard was meant to
prevent. Other `.qwen/*` subtrees (`projects`, `tmp`, …) are CLI
state with no legitimate cross-worktree sharing use case either.

Fix: broaden the guard to reject the whole `<repoRoot>/.qwen` tree.
Both `.qwen` itself and any descendant fail closed.

Also synced the user-facing settings schema description (the in-IDE
help text and the published JSON schema) so it mentions the `.git`
and `.qwen` rejection rules. The `WorktreeSettings` interface JSDoc
already mentioned them; the schema description had not been updated.

Tests: cli 15/15 + core 66/66 unchanged. Smoke confirms `--worktree foo`
with `symlinkDirectories: ['.qwen']` configured leaves the worktree
free of any `.qwen` symlink (only the legitimate per-worktree
`.qwen-session` marker file appears).

* fix(worktree): guard fetchPullRequestRef against CodeQL command-injection alert

CodeQL flagged a "Second order command injection" finding (rule 235) on
the `git fetch origin pull/<N>/head` call in `fetchPullRequestRef`. The
taint analyzer doesn't see the type-narrowing at the function entry
(`Number.isSafeInteger(prNumber) && prNumber > 0 && prNumber <= 1e9`),
so it considers `prNumber` library input that could in principle reach
a `--upload-pack=…`-shaped flag and thereby execute an arbitrary
program. In practice the entry guard already prevents that, but the
alert blocks the CodeQL CI check.

Add `--end-of-options` between `origin` and the refspec — git's
canonical "stop parsing flags" marker (git ≥ 2.24). Tells git
definitively that every subsequent argv element is a positional, not
a flag, which (a) satisfies the analyzer, (b) adds defense-in-depth
against a future regression that might relax the entry guard, and
(c) has zero behavior change for any well-formed PR number.

Verified locally: `git fetch --end-of-options origin pull/<N>/head`
against a local bare-remote with a seeded `refs/pull/42/head` still
fetches the ref correctly; the `--worktree=#42` smoke test reads back
the PR content from the materialized worktree.

Tests: cli 15/15 + core 66/66 unchanged.

* fix(worktree): lexical sanitizer for CodeQL + missing test mock entry

Two fixes from the third CI round on PR #4381:

1. CodeQL re-fires (round 2 of the same finding).

`--end-of-options` is a git-runtime defense, not a lexical sanitizer
that CodeQL's `js/second-order-command-line-injection` taint tracker
recognises. The alert re-fired against the same call after the
previous fix.

Switch to a CodeQL-recognised sanitizer: validate the numeric
component against `/^[1-9][0-9]*$/` immediately at the sink. The
regex digit-only check is one of the documented sanitizer patterns
the rule looks for, and proves at the analyzer level that the
resulting argv element cannot resemble a flag (`--foo`). The entry
guard at the top of the function still establishes the same fact
at runtime; this layer makes the proof visible to static analysis.
Keep `--end-of-options` as a runtime fallback against any future
regression that loosens the entry guard.

2. `nonInteractiveCli.test.ts` mock was missing the new
   `consumePendingStartupWorktreeNotice` Config method.

Phase D-1 added the method on `Config` and `nonInteractiveCli`
calls it on every prompt to pick up the one-shot startup-worktree
notice. The test file's `mockConfig` literal was not updated, so
all 19 `runNonInteractive` tests threw
`TypeError: config.consumePendingStartupWorktreeNotice is not a
function` on Ubuntu / macOS CI.

Add a stub returning `null` so the helper short-circuits, matching
the equivalent Phase C stub for `getResumedSessionData`.

Local: cli (worktreeStartup + nonInteractiveCli) 60 passed + 1
skipped; core (gitWorktreeService + symlinks + hooks +
enter-worktree) 66 passed.

* test(worktree): mock getWorktreeSymlinkDirectories in three more test files

Round 4 of the same Phase D-2 mock-drift class. CI surfaced 9 test
failures across three files whose `Config` mocks construct
`EnterWorktreeTool` for setup but lack the new
`getWorktreeSymlinkDirectories` method `createUserWorktree` now
calls:

- enter-worktree.session.integ.test.ts (2 tests)
- exit-worktree.session.integ.test.ts (3 tests) — provisions
  worktrees via EnterWorktreeTool before exercising exit paths
- exit-worktree.test.ts (4 tests) — same provisioning pattern via
  `provisionWorktree()` and the `makeMockConfig` helper

Add a `getWorktreeSymlinkDirectories: () => []` stub to each so
the symlink loop is a no-op in tests.

`enter-worktree.test.ts` and `agent/agent.test.ts` intentionally
skipped — they mock `GitWorktreeService.createUserWorktree` outright,
so the method call never fires in their code paths. Adding the stub
there would be defensive speculation. If a future test exercises
the real path, it'll surface there too and we'll add it then.

Local: core tools tests now 123 passed (was 9 failed / 114 passed
on CI run 26213122427 against commit 000c9f63).

* fix(worktree): normalize repoRoot path separators + disable autocrlf in tests

Round 5 of CI: Windows-only test failures on the latest HEAD. Two
unrelated Windows-specific bugs, both in / around worktreeStartup.

1. `setupStartupWorktree` stored the raw `getRepoTopLevel()` output
   in `context.repoRoot`. git always emits POSIX paths via
   `--show-toplevel` (`C:/Users/...`), so on Windows the value was
   forward-slash where `fs.realpath` and `path.join` produce
   backslash. The sidecar's `originalCwd` field got the
   inconsistent format and a downstream `expect(...).toBe(tempRepo)`
   in the round-trip test compared `C:/Users/.../tmp/...` against
   `C:\Users\.../tmp/...`.

   Wrap the value in `path.resolve()` to normalize to the
   platform-native separator before storing. Downstream consumers
   (`path.join(session.originalCwd, '.qwen', 'worktrees')` in
   `restoreWorktreeContext`, `new GitWorktreeService(originalCwd)`
   in `AppContainer`) already handle either format, so no migration
   concern for older sidecars.

2. `makeTempRepo` in worktreeStartup.test.ts didn't configure
   `core.autocrlf=false`. On Windows runners the default is `true`,
   so files committed and pushed to the test's fake-remote `pull/<N>/head`
   ref get CRLF-converted on the worktree's checkout. The PR-content
   assertion `expect(prFile).toBe('from PR 42\n')` then failed with
   `'from PR 42\r\n'`.

   Add `core.autocrlf=false` + `core.eol=lf` to the temp-repo setup
   so test files round-trip byte-for-byte regardless of host platform.

Local mac: cli worktreeStartup 15/15 still pass. Windows verification
deferred to CI.

* fix(worktree): reject '..' segments + use junction on Windows

Two Copilot findings on symlinkConfiguredDirectories (PR #4381 round 3):

1. The settingsSchema description, docs/users/features/worktree.md, and
   WorktreeSettings JSDoc all promise that entries containing `..` are
   rejected — but the post-resolve isWithinRoot check accepted
   `foo/../bar` (resolves to `bar`, inside the repo). Add a literal `..`
   segment check before path.resolve so the code matches the contract.

2. On Windows, fs.symlink(..., 'dir') requires
   SeCreateSymbolicLinkPrivilege (admin / Developer Mode) and EPERMs on
   default consumer installs. Use 'junction' for directory entries on
   win32 — junctions are reparse points that achieve the same semantics
   without elevation. Keep 'dir' on POSIX and 'file' for non-directory
   sources (no junction-equivalent for files; rare path).

Adds an integration test exercising `foo/../bar` to lock in the
syntactic guard; existing absolute-path and traversal tests already
covered the other rejection forms.

* fix(worktree): PR-worktree HEAD-SHA capture + symlink guard tests

Three findings from wenshao round 4 (PR #4381):

1. For --worktree=#42 (PR worktrees), originalHeadCommit was captured
   from the parent repo's HEAD via getCurrentCommitHash() — but the
   worktree branches off FETCH_HEAD (the PR tip), not main. Downstream,
   WorktreeExitDialog's `rev-list <originalHeadCommit>..HEAD` would
   count every commit in the fetched PR as "new work this session"
   alongside the user's actual commits.

   Same root cause covers the FETCH_HEAD TOCTOU window: between
   `git fetch origin pull/<N>/head` and `git worktree add ... FETCH_HEAD`,
   a concurrent `git fetch` from any other process sharing this repo
   could overwrite .git/FETCH_HEAD, causing the worktree to branch off
   an unrelated commit.

   Fix: add GitWorktreeService.resolveRef(ref) that returns a 40-char
   SHA (or null). In setupStartupWorktree, immediately after
   fetchPullRequestRef succeeds, resolve FETCH_HEAD to an immutable
   SHA; pass that SHA both as the baseRef to createUserWorktree (closes
   the TOCTOU) AND as originalHeadCommit in the returned context
   (closes the exit-dialog miscount). Fail-close on null resolve.

2. Orphaned JSDoc block at gitWorktreeService.ts:1035-1048 — originally
   wrote validateUserWorktreeSlug's docs, stranded above parsePRReference
   after that function was inserted between them. Move the block down to
   sit immediately above validateUserWorktreeSlug at its current line.

3. `.git` / `.qwen` symlink rejection guards (~20 lines of security-
   critical code at gitWorktreeService.ts:1640-1655) had no regression
   tests — only absolute paths, `..` traversal, isWithinRoot escapes,
   and missing sources were covered. Add two integ tests in
   gitWorktreeService.symlinks.integ.test.ts: one asserts `.git/hooks`
   is refused, one asserts `.qwen/projects` is refused.

Also extends the existing PR-worktree integration test in
worktreeStartup.test.ts to assert originalHeadCommit equals the
resolved FETCH_HEAD SHA AND does NOT equal the parent repo's main HEAD
— the assertion would fail loudly if the new SHA-capture path were
reverted.

* fix(worktree): realpath check on symlinkDirectories source + dest paths

Security fix from PR #4381 round 7 (wenshao/qwen3.7-max). The lexical
isWithinRoot + .git/.qwen blocklist checks in symlinkConfiguredDirectories
all operated on path.resolve(repoRoot, raw) — a STRING operation that
doesn't follow symlinks. A committed (or out-of-band) symlink at
<repo>/node_modules pointing into .git would pass every gate:

  1. path.resolve gives `<repo>/node_modules` (lexical, passes
     isWithinRoot against repo root).
  2. The .git/.qwen blocklists also see the lexical path — they don't
     detect that the realpath chains into .git.
  3. fs.stat() follows the symlink and succeeds against .git/.
  4. fs.symlink writes `<worktree>/node_modules → <repo>/node_modules`,
     which OS-side resolves through to <repo>/.git. Any tool inside the
     worktree that writes to node_modules/hooks/post-merge then has RCE
     on the next hook-firing git operation.

Fix: after fs.stat succeeds, fs.realpath the source and RE-RUN the three
containment checks against the realpath. Refuse on any escape. Use the
realpath (not the lexical sourceAbs) as the symlink target so the new
link is one-hop canonical rather than preserving the chain.

Also closes the dest-side variant of the same root cause — flagged in
round 4 thread #5 (declined then as overthinking) but now in scope per
the skill's iteration rule (two consecutive rounds raising the same
root-cause class). path.join(worktreePath, raw) is also lexical: if
git worktree add materialized a committed worktree-level symlink (e.g.
HEAD ships tools → /etc), then fs.mkdir / fs.symlink for a nested entry
like "tools/cache" writes OUTSIDE the worktree. Realpath the dest
parent before mkdir and refuse if it escapes the worktree.

New integ test covers both source-side variants (escape-to-git via
out-of-band symlink + escape-to-outside-dir) in one block. Was RED
against the pre-fix code: <wt>/escape-to-git was created as a symlink
that chained into the source repo's .git. GREEN after the fix.

* fix(worktree): canonicalise repo root before symlinkDirectories checks

Round-7's source-side realpath fix introduced a canonical-vs-lexical
mismatch: `repoRootAbs = path.resolve(this.sourceRepoPath)` is purely
lexical, while `realSource = await fs.realpath(sourceAbs)` is canonical.
On macOS where `/tmp → /private/tmp` and `/var → /private/var` are
ubiquitous, and on any Linux/Windows setup where the user's checkout
sits behind a symlink, the prefixes diverge at the symlink boundary and
`isWithinRoot(realSource, repoRootAbs)` silently rejects every
configured entry.

Production callers (worktreeStartup.ts, EnterWorktreeTool,
agent isolation) all pass the lexical path returned by
`git rev-parse --show-toplevel`. The integ tests masked the bug because
the shared `beforeEach` did `repoRoot = await fs.realpath(dir)` upfront.

Round 8 fix:

- Hoist `repoRootAbs`, `gitDirAbs`, `qwenDirAbs`, and `realWorktreePath`
  outside the for-loop — they're loop invariants and were being
  recomputed once per entry.
- `await fs.realpath(this.sourceRepoPath)` for `repoRootAbs` so every
  containment check below is canonical-vs-canonical. The derived
  `gitDirAbs` / `qwenDirAbs` blocklist paths inherit the canonical
  prefix automatically. `sourceAbs = path.resolve(repoRootAbs, raw)`
  inherits it too, so the early lexical reject paths (absolute, `..`,
  repo-root equality, isWithinRoot) stay self-consistent.
- Fail-close: if the repo root itself doesn't realpath (deleted /
  inaccessible), bail out of the entire symlink loop rather than
  continuing with comparisons we can't trust. Non-destructive — the
  worktree was created earlier by `git worktree add`.

New integ test provisions the production shape: a symlink path used
as `sourceRepoPath`, distinct from its canonical realpath. RED on the
pre-fix code (assertion fired with "symlinkDirectories entry was
silently rejected — canonical vs lexical isWithinRoot mismatch"),
GREEN after.
2026-05-27 17:04:51 +08:00
DennisYu07
bc1bac506a
move new app prompt from system prompt to skills (#4567) 2026-05-27 14:57:30 +08:00
MikeWang0316tw
ce53283af4
fix(cli): auto-prepend @ when pasting or dropping multiple file paths (#4544)
* fix(cli): auto-prepend @ when pasting or dropping multiple file paths

When pasting or drag-and-dropping a single file path, Qwen Code
automatically prepends @ to convert it into an @file reference. However,
pasting or dragging multiple file paths (separated by newlines or
whitespace) did not receive the same treatment, requiring users to
manually add @ to each path.

This change extends the paste detection logic in text-buffer.ts to
detect and prepend @ to multiple file paths, matching the behavior
of single-file paste/drag. The fix also strips surrounding quotes
(common in drag-and-drop input) before path validation.

Before:
  - Drag & drop 1 file → @file ✅
  - Drag & drop 3 files → 'file1' 'file2' 'file3' ❌
  - Paste 1 file → @file ✅
  - Paste 3 files → file1 file2 file3 ❌

After:
  - Drag & drop 1 file → @file ✅ (unchanged)
  - Drag & drop 3 files → @file1 @file2 @file3 ✅ (fixed)
  - Paste 1 file → @file ✅ (unchanged)
  - Paste 3 files → @file1 @file2 @file3 ✅ (fixed)

* fix(cli): simplify path extraction and escape spaces for @-paths

Refactor multi-file paste @-path detection:
- Extract tryExtractFilePaths() and extractPathsFromSegment() helpers
  to eliminate ~100 lines of duplicated path-extraction logic
- Add shellModeActive guard to newline paste branch for consistency
- Remove redundant isPaste variable
- Escape spaces in paths with backslash so downstream parseAllAtCommands
  parser correctly handles filenames with spaces (e.g. @/path/to/my\ file.txt)

* fix(cli): address wenshao's code review for multi-file paste

Address 3 critical and 4 suggestion issues from wenshao's review:

Critical fixes:
- Prevent silent data loss: only transform paste when all tokens are
  valid paths. If any non-path token exists, preserve original content
  (hadNonPathToken tracking)
- Fix O(n²) synchronous fs calls: pre-filter tokens with looksLikePath()
  to skip non-path tokens before expensive fs.existsSync calls
- Add tests for paths with spaces and escapePath integration (6 new tests)

Suggestion fixes:
- Fix quoted path regex: require path-like prefix to avoid false matches
  on English contractions (don't → /'([~/.][^']*)'/g)
- Flatten if/else in newline paste branch
- Add CRLF, shell mode, and null-return tests
- Escape commas in paths for parseAllAtCommands compatibility

* fix(cli): use escapePath to avoid CodeQL warning

Use escapePath() for whitespace escaping instead of manual regex to
avoid CodeQL's incomplete-string-escaping warning, then additionally
escape commas.

* fix(cli): add comma to SHELL_SPECIAL_CHARS to fix CodeQL warning

- Add comma to SHELL_SPECIAL_CHARS in core so escapePath handles it
- Simplify escapePathAndCommas to just call escapePath(path)
- This avoids CodeQL's incomplete-string-escaping warning

* fix(cli): address wenshao's remaining code review findings

- looksLikePath: add support for relative paths (./, ../, ~/) and dotfiles
- Greedy matching: reverse to longest-match-first for paths with spaces
- Add tests for relative paths, longest-match-first, and invalid paths

* fix(cli): address wenshao's remaining review suggestions

- Fix stale JSDoc: change 'shortest' to 'longest' match-first
- Remove overly broad includes('/') from looksLikePath
- Sync SHELL_SPECIAL_CHARS in vscode-ide-companion (add comma)
- Add tests for shell metacharacters (parentheses, brackets, semicolons)
- Add short-circuit when hadNonPathToken is set
- Inline escapePathAndCommas (now redundant with comma in SHELL_SPECIAL_CHARS)

* fix(cli): address wenshao's latest review suggestions

- Fix quotedPathRegex to support Windows drive-letter paths
- Fix looksLikePath to handle quoted Windows paths split by whitespace
- Allow bare filenames for single-token segments
- Add tests for Windows drive-letter and quoted Windows paths
- Add comma to paths.test.ts escapePath test

* fix(cli): address wenshao's latest JSDoc and test suggestions

- Fix looksLikePath JSDoc to include ../ and ..
- Fix tryExtractFilePaths JSDoc to reflect all shell-special chars
- Add test for bare filename (README.md) single-token segment
2026-05-27 14:06:24 +08:00
jinye
77333a4d7c
fix(telemetry): attach interaction span to session root context (#4499)
* fix(telemetry): attach interaction span to session root context

startInteractionSpan was the only startSpan call site missing the ctx
argument. OTel responded by minting a fresh random trace id, splitting
the interaction span away from its semantic children (llm_request /
tool / tool.execution), which DO inherit the sessionId-derived trace
id. The result: any session producing an interaction span ends up with
two unrelated trace ids — one one-span trace for the interaction, one
multi-span trace for everything else — and the hierarchy renders as
disconnected items in trace viewers.

Pin the interaction span to the session root context. Not via
resolveParentContext() — that prefers any active OTel span over the
session root, and interaction spans are turn boundaries that must
always anchor at the session root, regardless of whatever wrapping
span happens to be active in OTel context.

Also reset session-context module state inside
clearSessionTracingForTesting() so a test that sets a fake session
root cannot leak into the next test.

Adds regression coverage on interaction span parentContext, including
the case where an unrelated OTel span is active to confirm we bypass
resolveParentContext().

Fixes #4486

* refactor(telemetry): trim verbose comments around #4486 fix

Per CLAUDE.md guidance on comment density: keep only the WHY a future
maintainer cannot derive from the code or the issue link.

- session-tracing.ts: condense the 8-line interaction-span comment to
  the single load-bearing point — resolveParentContext() is deliberately
  bypassed and should not be "simplified" back into it.
- clearSessionTracingForTesting hygiene comment: one line stating the
  cross-module reach, no restatement of the test-leak rationale.
- session-tracing.test.ts: drop the multi-line describe header and the
  inline rationale in the second test; the describe / it names + the
  production comment already convey intent. Move #4486 into the describe
  name to match the existing `(#NNNN review)` convention used elsewhere
  in this file.

No behavior change. All 72 tests still pass.

* test(telemetry): cover otelContext.active() fallback in startInteractionSpan

The two existing #4486 regression tests both call setSessionContext()
before invoking startInteractionSpan, so they never exercise the
nullish-coalescing fallback `getSessionContext() ?? otelContext.active()`.

This third case starts with no session context set (the beforeEach hook
already leaves getSessionContext() === undefined), an unrelated active
OTel span in the mock context, and asserts the interaction span attaches
to that active span rather than silently being created with no parent.

The fallback is essentially unreachable in production (sdk.ts seeds
session context during SDK init before any interaction can run), but it
exists as defense against startup edge cases / `/clear` / `/resume`
paths where session context could be transiently undefined while a stale
span lingers in the OTel async context. Without this test, a future
refactor could delete the `?? otelContext.active()` clause and silently
re-introduce the same class of bug #4486 fixed, in a different scenario.

Suggestion from wenshao on PR #4499.

* test(telemetry): tighten fallback test to match file convention

Three style nits caught by /simplify against the freshly-added test:

- Use `toMatchObject({ __activeSpan: fakeActive })` with a captured
  reference instead of `toEqual(expect.objectContaining({ __activeSpan:
  expect.anything() }))`. The latter would pass even if production code
  returned `__activeSpan: undefined`; the former gives referential proof
  that the actual active span propagated through. Matches the existing
  three re-parent tests in this file (lines 395, 669, 741).
- Use `{ kind: 'fake-active-span' }` for the active span placeholder to
  match the same convention.
- Collapse the 2-line setup comment to 1 line — the "no
  setSessionContext call" directive is the load-bearing bit; the
  "beforeEach left undefined" half was restating beforeEach.

No behavior change. 73 tests still pass.
2026-05-27 11:33:29 +08:00
易良
92d533265c
fix(vscode-ide-companion): exclude workspace packages from NOTICES.txt generation (#4455)
* fix(vscode-ide-companion): exclude workspace packages from NOTICES.txt generation

Workspace-linked packages (link: true in package-lock.json) have no
version field, causing @undefined entries in NOTICES.txt. Skip them
during dependency collection since they are first-party code.

Regenerated NOTICES.txt on top of the express 5.2.1 lockfile update.

Closes #4446

* fix(vscode-ide-companion): resolve workspace and nested deps in NOTICES.txt generation

Rewrite collectDependencies to mirror Node.js module resolution:
- Walk up node_modules chain from each package's location (not just root)
- Follow workspace link resolved pointers to collect their third-party deps
- Pass resolved lockfile key to getDependencyLicense for exact path lookup

Previously @modelcontextprotocol/sdk and its transitive deps (zod-to-json-schema,
ajv@8, etc.) were missing because they are installed under the workspace's local
node_modules and were never hoisted to root. Also fixes version mismatch where
ajv@6.12.6 license was incorrectly used instead of ajv@8.17.1.

Total NOTICES entries: 80 → 102.
2026-05-27 11:24:38 +08:00
703 changed files with 50585 additions and 104108 deletions

View File

@ -1,73 +1,66 @@
<!--
Help reviewers verify this PR quickly.
Maintainers prioritize PRs with a clear reviewer test plan — without it, review may be delayed.
Maintainers prioritize PRs that include clear proof of work.
If a PR does not include enough validation detail to reproduce and verify the change efficiently, review may be delayed.
Don't hard-wrap paragraphs: GitHub renders single newlines as <br>, so wrapped text shows as a narrow column. Write each paragraph or list item as one long line.
-->
## Summary
## What this PR does
- What changed:
- Why it changed:
- Reviewer focus:
<!-- What this PR does. Describe the change in prose, not by file or function names. -->
## Validation
## Why it's needed
<!-- Why it's needed: the motivation, the problem being solved, or the user-facing benefit. -->
## Reviewer Test Plan
<!--
Be concrete. Do not write only "tested locally".
Include the exact commands, prompts, outputs, logs, screenshots, or videos that prove the change was actually run and observed.
How a reviewer can confirm this PR: reproduction steps, expected vs observed behavior, and evidence. CI runs on macOS, Windows, and Linux — Tested on is what you verified locally.
For user-visible changes, bug fixes, CLI / TUI behavior changes, or interaction changes, include key screenshots or a short video.
When possible, show before/after behavior.
If helpful, use the `e2e-testing` skill to gather stronger end-to-end validation evidence.
User-visible / TUI: Before/After with tmux-real-user-testing skill, screenshots, or a short recording.
Non–user-visible (refactor, types, docs): commands and output below; write N/A under Before/After.
-->
- Commands run:
```bash
# paste commands here
```
- Prompts / inputs used:
- Expected result:
- Observed result:
- Quickest reviewer verification path:
- Evidence (output, logs, screenshots, video, JSON, before/after, etc.):
### How to verify
## Scope / Risk
<!-- How you reproduced it and what a reviewer should confirm — steps if needed, expected vs observed behavior. Focus on outcomes; paste logs or test output when helpful. -->
### Evidence (Before & After)
<!-- User-visible / TUI changes: paste before-and-after screenshots, tmux logs, or video side by side. Non-UI changes (docs, refactor, types): N/A -->
### Tested on
| OS | Status |
| :--------: | :----: |
| 🍏 macOS | |
| 🪟 Windows | |
| 🐧 Linux | |
<!-- ✅ tested · ⚠️ not tested · N/A -->
### Environment (optional)
<!-- Local runtime: e.g. npm run dev, Docker/Podman sandbox, seatbelt. N/A if only unit tests. -->
## Risk & Scope
- Main risk or tradeoff:
- Not covered / not validated:
- Not validated / out of scope:
- Breaking changes / migration notes:
## Testing Matrix
## Linked Issues
<!--
Use:
- ✅ tested
- ⚠️ not tested
- N/A
If anything is ⚠️, explain why briefly below.
Closes #N / Fixes #N / Resolves #N to auto-close.
Otherwise reference without a closing keyword.
-->
| | 🍏 | 🪟 | 🐧 |
| -------- | --- | --- | --- |
| npm run | ⚠️ | ⚠️ | ⚠️ |
| npx | ⚠️ | ⚠️ | ⚠️ |
| Docker | ⚠️ | ⚠️ | ⚠️ |
| Podman | ⚠️ | N/A | N/A |
| Seatbelt | ⚠️ | N/A | N/A |
Testing matrix notes:
-
## Linked Issues / Bugs
<details>
<summary>中文说明</summary>
<!--
If this PR fully resolves an issue, use one of:
- Closes #<issue_number>
- Fixes #<issue_number>
- Resolves #<issue_number>
Otherwise reference related issues without a closing keyword.
完整翻译上面的英文正文,逐段对应,不要省略或缩写。PR 标题保持英文。
-->
</details>

View File

@ -386,63 +386,6 @@ jobs:
RELEASE_VERSION: '${{ needs.prepare.outputs.release_version }}'
run: 'npm run package:standalone:release -- --version "${RELEASE_VERSION}" --out-dir dist/standalone'
- name: 'Verify Installation Release Assets'
run: 'npm run verify:installation-release -- --dir dist/standalone'
- name: 'Package Hosted Installation Assets'
env:
RELEASE_VERSION: '${{ needs.prepare.outputs.release_version }}'
run: 'npm run package:hosted-installation -- --out-dir dist/installation --version "${RELEASE_VERSION}"'
- name: 'Install ossutil'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
OSSUTIL_URL: "${{ vars.OSSUTIL_URL || 'https://gosspublic.alicdn.com/ossutil/1.7.19/ossutil-v1.7.19-linux-amd64.zip' }}"
OSSUTIL_SHA256: "${{ vars.OSSUTIL_SHA256 || 'dcc512e4a893e16bbee63bc769339d8e56b21744fd83c8212a9d8baf28767343' }}"
run: |-
set -euo pipefail
tmp_dir="$(mktemp -d)"
curl -fsSL --connect-timeout 15 --max-time 300 "${OSSUTIL_URL}" -o "${tmp_dir}/ossutil.zip"
echo "${OSSUTIL_SHA256} ${tmp_dir}/ossutil.zip" | sha256sum -c -
unzip -q "${tmp_dir}/ossutil.zip" -d "${tmp_dir}"
ossutil_path="$(find "${tmp_dir}" -type f \( -name 'ossutil' -o -name 'ossutil64' \) -print -quit)"
if [[ -z "${ossutil_path}" ]]; then
echo "::error::ossutil binary not found in downloaded archive"
exit 1
fi
chmod +x "${ossutil_path}"
mkdir -p "${HOME}/.local/bin"
install -m 0755 "${ossutil_path}" "${HOME}/.local/bin/ossutil"
echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
rm -rf "${tmp_dir}"
"${HOME}/.local/bin/ossutil" >/dev/null
- name: 'Configure Aliyun OSS Credentials'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
ALIYUN_OSS_ACCESS_KEY_ID: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_ID }}'
ALIYUN_OSS_ACCESS_KEY_SECRET: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_SECRET }}'
ALIYUN_OSS_ENDPOINT: "${{ vars.ALIYUN_OSS_ENDPOINT || 'https://oss-cn-hangzhou.aliyuncs.com' }}"
run: |-
set -euo pipefail
if [[ -z "${ALIYUN_OSS_ACCESS_KEY_ID}" || -z "${ALIYUN_OSS_ACCESS_KEY_SECRET}" ]]; then
echo "::error::Missing Aliyun OSS credentials. Set ALIYUN_OSS_ACCESS_KEY_ID and ALIYUN_OSS_ACCESS_KEY_SECRET in the production-release environment secrets."
exit 1
fi
ossutil config \
-e "${ALIYUN_OSS_ENDPOINT}" \
-i "${ALIYUN_OSS_ACCESS_KEY_ID}" \
-k "${ALIYUN_OSS_ACCESS_KEY_SECRET}" \
-L EN \
-c "${RUNNER_TEMP}/.ossutilconfig"
- name: 'Publish @qwen-code/qwen-code'
working-directory: 'dist'
run: |-
@ -457,150 +400,37 @@ jobs:
env:
NODE_AUTH_TOKEN: '${{ secrets.NPM_TOKEN }}'
- name: 'Verify Standalone Archives'
run: |-
npm run verify:installation-release -- --dir dist/standalone
- name: 'Create GitHub Release and Tag'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
# CI_BOT_PAT required: GITHUB_TOKEN events cannot trigger downstream workflows (sync-release-to-oss.yml).
GITHUB_TOKEN: '${{ secrets.CI_BOT_PAT }}'
RELEASE_BRANCH: '${{ steps.release_branch.outputs.BRANCH_NAME }}'
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
PREVIOUS_RELEASE_TAG: '${{ needs.prepare.outputs.previous_release_tag }}'
IS_NIGHTLY: '${{ needs.prepare.outputs.is_nightly }}'
IS_PREVIEW: '${{ needs.prepare.outputs.is_preview }}'
run: |-
set -euo pipefail
PRERELEASE_FLAG=""
if [[ "${IS_NIGHTLY}" == "true" || "${IS_PREVIEW}" == "true" ]]; then
PRERELEASE_FLAG="--prerelease"
fi
mapfile -t release_assets < <(node scripts/verify-installation-release.js --dir dist/standalone --list-release-asset-paths)
gh release create "${RELEASE_TAG}" \
dist/cli.js \
"${release_assets[@]}" \
dist/standalone/qwen-code-* \
dist/standalone/SHA256SUMS \
--target "${RELEASE_BRANCH}" \
--title "Release ${RELEASE_TAG}" \
--notes-start-tag "${PREVIOUS_RELEASE_TAG}" \
--generate-notes \
${PRERELEASE_FLAG}
- name: 'Sync Release Assets to Aliyun OSS'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
mapfile -t release_assets < <(node scripts/verify-installation-release.js --dir dist/standalone --list-release-asset-paths)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "releases/qwen-code/${RELEASE_TAG}" \
"${release_assets[@]}"
- name: 'Verify Aliyun OSS Release Assets'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' }}
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
npm run verify:installation-release -- --base-url "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/${RELEASE_TAG}"
- name: 'Sync Hosted Installation Assets to Aliyun OSS'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
hosted_assets=(
dist/installation/install-qwen-standalone.sh
dist/installation/install-qwen-standalone.ps1
dist/installation/install-qwen-standalone.bat
dist/installation/uninstall-qwen-standalone.sh
dist/installation/uninstall-qwen-standalone.ps1
dist/installation/SHA256SUMS
)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation/${RELEASE_TAG}" \
"${hosted_assets[@]}"
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation" \
"${hosted_assets[@]}"
- name: 'Verify Aliyun OSS Hosted Installation Assets'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
hosted_tmp_dir="$(mktemp -d)"
trap 'rm -rf "${hosted_tmp_dir}"' EXIT
mkdir -p "${hosted_tmp_dir}/versioned" "${hosted_tmp_dir}/global"
for asset in install-qwen-standalone.sh install-qwen-standalone.ps1 install-qwen-standalone.bat uninstall-qwen-standalone.sh uninstall-qwen-standalone.ps1 SHA256SUMS; do
url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${RELEASE_TAG}/${asset}"
global_url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${url}" -o "${hosted_tmp_dir}/versioned/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${global_url}" -o "${hosted_tmp_dir}/global/${asset}"
done
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || {
echo "::error::Hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || true
exit 1
}
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || {
echo "::error::Global hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || true
exit 1
}
(cd "${hosted_tmp_dir}/versioned" && sha256sum -c SHA256SUMS)
(cd "${hosted_tmp_dir}/global" && sha256sum -c SHA256SUMS)
- name: 'Publish Aliyun OSS Latest VERSION'
# Run last so the `latest/VERSION` pointer only flips after every
# release asset and hosted installer object has been uploaded and
# verified. If any earlier step fails, the pointer keeps referring
# to the previously-good release.
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ needs.prepare.outputs.release_tag }}'
run: |-
set -euo pipefail
printf '%s\n' "${RELEASE_TAG}" > "${RUNNER_TEMP}/qwen-code-latest-version"
ossutil cp "${RUNNER_TEMP}/qwen-code-latest-version" "oss://${ALIYUN_OSS_BUCKET}/releases/qwen-code/latest/VERSION" -c "${RUNNER_TEMP}/.ossutilconfig" -f --acl public-read
latest_version="$(curl -fsSL --connect-timeout 15 --max-time 300 "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/latest/VERSION" | tr -d '[:space:]')"
if [[ "${latest_version}" != "${RELEASE_TAG}" ]]; then
echo "::error::Aliyun latest VERSION points to ${latest_version}, expected ${RELEASE_TAG}"
exit 1
fi
- name: 'Cleanup Aliyun OSS Credentials'
if: |-
${{ always() && needs.prepare.outputs.is_dry_run == 'false' }}
run: |-
rm -f "${RUNNER_TEMP}/.ossutilconfig"
- name: 'Create PR to merge release branch into main'
if: |-
${{ needs.prepare.outputs.is_dry_run == 'false' && needs.prepare.outputs.is_nightly == 'false' && needs.prepare.outputs.is_preview == 'false' }}

View File

@ -0,0 +1,238 @@
name: 'Sync Release to Aliyun OSS'
on:
release:
types: ['published']
workflow_dispatch:
inputs:
tag:
description: 'The release tag to sync (e.g., v0.1.11).'
required: true
type: 'string'
concurrency:
group: 'sync-release-to-oss'
cancel-in-progress: false
jobs:
sync:
name: 'Sync Release Assets to Aliyun OSS'
runs-on: 'ubuntu-latest'
if: |-
${{ github.repository == 'QwenLM/qwen-code' }}
environment:
name: 'production-release'
permissions:
contents: 'read'
env:
RELEASE_TAG: '${{ github.event.release.tag_name || inputs.tag }}'
steps:
- name: 'Checkout'
uses: 'actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd' # v6.0.2
with:
ref: '${{ env.RELEASE_TAG }}'
- name: 'Determine release type'
id: 'meta'
env:
TAG: '${{ env.RELEASE_TAG }}'
run: |-
is_nightly="false"
is_preview="false"
if [[ "${TAG}" == *"nightly"* ]]; then
is_nightly="true"
elif [[ "${TAG}" == *"preview"* ]]; then
is_preview="true"
fi
echo "is_nightly=${is_nightly}" >> "${GITHUB_OUTPUT}"
echo "is_preview=${is_preview}" >> "${GITHUB_OUTPUT}"
echo "is_stable=$([[ ${is_nightly} == 'false' && ${is_preview} == 'false' ]] && echo true || echo false)" >> "${GITHUB_OUTPUT}"
- name: 'Setup Node.js'
uses: 'actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e' # v6.4.0
with:
node-version-file: '.nvmrc'
cache: 'npm'
cache-dependency-path: 'package-lock.json'
- name: 'Install Dependencies'
env:
NPM_CONFIG_PREFER_OFFLINE: 'true'
run: |-
npm ci --no-audit --progress=false
- name: 'Download Release Assets from GitHub'
env:
GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
mkdir -p dist/standalone
gh release download "${RELEASE_TAG}" --dir dist/standalone --pattern '*.tar.gz' --pattern '*.zip' --pattern 'SHA256SUMS'
- name: 'Verify Downloaded Release Assets'
run: |-
npm run verify:installation-release -- --dir dist/standalone
- name: 'Package Hosted Installation Assets'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
RELEASE_VERSION="${RELEASE_TAG#v}"
npm run package:hosted-installation -- --out-dir dist/installation --version "${RELEASE_VERSION}"
- name: 'Install ossutil'
env:
OSSUTIL_URL: "${{ vars.OSSUTIL_URL || 'https://gosspublic.alicdn.com/ossutil/1.7.19/ossutil-v1.7.19-linux-amd64.zip' }}"
OSSUTIL_SHA256: "${{ vars.OSSUTIL_SHA256 || 'dcc512e4a893e16bbee63bc769339d8e56b21744fd83c8212a9d8baf28767343' }}"
run: |-
set -euo pipefail
tmp_dir="$(mktemp -d)"
curl -fsSL --connect-timeout 15 --max-time 300 "${OSSUTIL_URL}" -o "${tmp_dir}/ossutil.zip"
echo "${OSSUTIL_SHA256} ${tmp_dir}/ossutil.zip" | sha256sum -c -
unzip -q "${tmp_dir}/ossutil.zip" -d "${tmp_dir}"
ossutil_path="$(find "${tmp_dir}" -type f \( -name 'ossutil' -o -name 'ossutil64' \) -print -quit)"
if [[ -z "${ossutil_path}" ]]; then
echo "::error::ossutil binary not found in downloaded archive"
exit 1
fi
chmod +x "${ossutil_path}"
mkdir -p "${HOME}/.local/bin"
install -m 0755 "${ossutil_path}" "${HOME}/.local/bin/ossutil"
echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
rm -rf "${tmp_dir}"
"${HOME}/.local/bin/ossutil" >/dev/null
- name: 'Configure Aliyun OSS Credentials'
env:
ALIYUN_OSS_ACCESS_KEY_ID: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_ID }}'
ALIYUN_OSS_ACCESS_KEY_SECRET: '${{ secrets.ALIYUN_OSS_ACCESS_KEY_SECRET }}'
ALIYUN_OSS_ENDPOINT: "${{ vars.ALIYUN_OSS_ENDPOINT || 'https://oss-cn-hangzhou.aliyuncs.com' }}"
run: |-
set -euo pipefail
if [[ -z "${ALIYUN_OSS_ACCESS_KEY_ID}" || -z "${ALIYUN_OSS_ACCESS_KEY_SECRET}" ]]; then
echo "::error::Missing Aliyun OSS credentials. Set ALIYUN_OSS_ACCESS_KEY_ID and ALIYUN_OSS_ACCESS_KEY_SECRET in the production-release environment secrets."
exit 1
fi
ossutil config \
-e "${ALIYUN_OSS_ENDPOINT}" \
-i "${ALIYUN_OSS_ACCESS_KEY_ID}" \
-k "${ALIYUN_OSS_ACCESS_KEY_SECRET}" \
-L EN \
-c "${RUNNER_TEMP}/.ossutilconfig"
- name: 'Sync Release Assets to Aliyun OSS'
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
mapfile -t release_assets < <(node scripts/verify-installation-release.js --dir dist/standalone --list-release-asset-paths)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "releases/qwen-code/${RELEASE_TAG}" \
"${release_assets[@]}"
- name: 'Verify Aliyun OSS Release Assets'
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
npm run verify:installation-release -- --base-url "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/${RELEASE_TAG}"
- name: 'Sync Hosted Installation Assets to Aliyun OSS'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
hosted_assets=(
dist/installation/install-qwen-standalone.sh
dist/installation/install-qwen-standalone.ps1
dist/installation/install-qwen-standalone.bat
dist/installation/uninstall-qwen-standalone.sh
dist/installation/uninstall-qwen-standalone.ps1
dist/installation/SHA256SUMS
)
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation/${RELEASE_TAG}" \
"${hosted_assets[@]}"
node scripts/upload-aliyun-oss-assets.js \
--bucket "${ALIYUN_OSS_BUCKET}" \
--config "${RUNNER_TEMP}/.ossutilconfig" \
--prefix "installation" \
"${hosted_assets[@]}"
- name: 'Verify Aliyun OSS Hosted Installation Assets'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
hosted_tmp_dir="$(mktemp -d)"
trap 'rm -rf "${hosted_tmp_dir}"' EXIT
mkdir -p "${hosted_tmp_dir}/versioned" "${hosted_tmp_dir}/global"
for asset in install-qwen-standalone.sh install-qwen-standalone.ps1 install-qwen-standalone.bat uninstall-qwen-standalone.sh uninstall-qwen-standalone.ps1 SHA256SUMS; do
url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${RELEASE_TAG}/${asset}"
global_url="${ALIYUN_OSS_PUBLIC_BASE_URL}/installation/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${url}" -o "${hosted_tmp_dir}/versioned/${asset}"
curl -fsSL --connect-timeout 15 --max-time 300 "${global_url}" -o "${hosted_tmp_dir}/global/${asset}"
done
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || {
echo "::error::Hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/versioned/SHA256SUMS" || true
exit 1
}
cmp -s "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || {
echo "::error::Global hosted installation SHA256SUMS does not match local dist/installation/SHA256SUMS"
diff -u "dist/installation/SHA256SUMS" "${hosted_tmp_dir}/global/SHA256SUMS" || true
exit 1
}
(cd "${hosted_tmp_dir}/versioned" && sha256sum -c SHA256SUMS)
(cd "${hosted_tmp_dir}/global" && sha256sum -c SHA256SUMS)
- name: 'Publish Aliyun OSS Latest VERSION'
if: |-
${{ steps.meta.outputs.is_stable == 'true' }}
env:
ALIYUN_OSS_BUCKET: "${{ vars.ALIYUN_OSS_BUCKET || 'qwen-code-assets' }}"
ALIYUN_OSS_PUBLIC_BASE_URL: "${{ vars.ALIYUN_OSS_PUBLIC_BASE_URL || 'https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com' }}"
RELEASE_TAG: '${{ env.RELEASE_TAG }}'
run: |-
set -euo pipefail
printf '%s\n' "${RELEASE_TAG}" > "${RUNNER_TEMP}/qwen-code-latest-version"
ossutil cp "${RUNNER_TEMP}/qwen-code-latest-version" "oss://${ALIYUN_OSS_BUCKET}/releases/qwen-code/latest/VERSION" -c "${RUNNER_TEMP}/.ossutilconfig" -f --acl public-read
latest_version="$(curl -fsSL --connect-timeout 15 --max-time 300 "${ALIYUN_OSS_PUBLIC_BASE_URL}/releases/qwen-code/latest/VERSION" | tr -d '[:space:]')"
if [[ "${latest_version}" != "${RELEASE_TAG}" ]]; then
echo "::error::Aliyun latest VERSION points to ${latest_version}, expected ${RELEASE_TAG}"
exit 1
fi
- name: 'Cleanup Aliyun OSS Credentials'
if: '${{ always() }}'
run: |-
rm -f "${RUNNER_TEMP}/.ossutilconfig"

View File

@ -23,15 +23,10 @@ Create a well-structured pull request with proper description and title.
3. **Write PR description**
- Use PR Template below
- Summarize changes clearly
- Include context and motivation
- List any breaking changes
- Link related issues if provided, or use "No linked issues"
- Leave the "Screenshots / Video Demo" section empty for the author to fill in
manually
- Add this line at the end of PR body: "🤖 Generated with [Qwen
Code](https://github.com/QwenLM/qwen-code)", with a line separator
- Fill in the PR template below — each section's HTML comment explains what
to write. PR title stays in English.
- Append at the end of the PR body, with a line separator: "🤖 Generated
with [Qwen Code](https://github.com/QwenLM/qwen-code)"
4. **Set up PR**

View File

@ -0,0 +1,136 @@
---
title: 'Memory Pressure Monitor'
date: '2026-05-21'
status: 'implemented'
---
# Memory Pressure Monitor
## Problem
Long-running Qwen Code sessions can accumulate memory through large tool
results, repeated file reads, chat history, and native/external allocations.
Before this change, the core package had diagnostics and session-reset cleanup,
but no runtime response when memory pressure rises during normal tool
execution.
The highest-value cache-specific gap is `FileReadCache`: it already has a
bounded FIFO size, but it did not have a time-based eviction path. That means a
session can retain inactive file-read metadata until the hard entry limit is
hit, even when the process is under memory pressure.
## Goals
- Add a low-overhead memory pressure check after tool execution.
- Prefer surgical cleanup before destructive cleanup.
- Respect container memory limits when cgroup v2 or cgroup v1 memory limit
files are available.
- React to V8 heap pressure before JavaScript heap OOM on high-memory hosts.
- Keep subagent/scoped `Config` instances isolated from parent session cleanup.
- Make behavior configurable through environment variables without adding a new
user-facing settings surface.
## Non-Goals
- Do not add a background polling loop.
- Do not make explicit GC the default; it only runs when enabled and Node was
started with `--expose-gc`.
- Do not change prior-read enforcement semantics. Cache eviction can remove old
metadata, but it must not weaken stale-file checks for retained entries.
## Design
`Config.initialize()` creates one `MemoryPressureMonitor` per initialized
`Config`. `getMemoryPressureMonitor()` mirrors the existing `getFileReadCache()`
Object.create isolation pattern: when a child config is created through
prototype delegation, the getter lazily installs an own monitor bound to that
child config.
`CoreToolScheduler.executeSingleToolCall()` calls `scheduleCheck()` in its
`finally` block after ending the tool span. `scheduleCheck()` coalesces multiple
calls in the same event-loop turn with `queueMicrotask`, so concurrent read-like
tool batches do not run one memory check per tool result.
The monitor uses the stronger of two pressure signals:
- RSS divided by an effective process memory limit. Prefer cgroup v2
`/sys/fs/cgroup/memory.max` when it is a finite positive value; fall back to
cgroup v1 `/sys/fs/cgroup/memory/memory.limit_in_bytes`, then to
`os.totalmem()` otherwise. cgroup v1's huge "unlimited" sentinel values are
ignored.
- V8 `heapUsed` divided by `getHeapStatistics().heap_size_limit`.
Using both signals matters because containers usually fail by RSS/cgroup limit,
while local high-memory machines can hit V8 heap OOM long before RSS is a large
fraction of total system memory.
Default thresholds are intentionally conservative enough to react before the OS
or container OOM killer does:
- `softPressureRatio = 0.50`
- `hardPressureRatio = 0.65`
- `criticalRatio = 0.80`
- `cleanupCooldownMs = 5000`
- `enableExplicitGC = false`
Environment overrides:
- `QWEN_MEMORY_PRESSURE_SOFT`
- `QWEN_MEMORY_PRESSURE_HARD`
- `QWEN_MEMORY_PRESSURE_CRITICAL`
- `QWEN_MEMORY_ENABLE_GC=1`
Invalid ratios fall back to defaults. Valid ratios must be ordered as
`soft < hard < critical`, with a lower soft bound of `0.3` and an upper
critical bound of `0.98`. Ratio env vars are parsed strictly with `Number()`,
so values such as `0.8extra` are rejected instead of partially accepted.
Invalid memory-pressure env configuration writes a visible warning to stderr
and to the debug log before falling back to defaults.
## Cleanup Policy
Pressure levels map to increasingly strong cleanup:
- `soft`: evict stale `FileReadCache` entries not accessed in 60 minutes.
- `hard`: evict cache entries not accessed in 30 minutes.
- `critical`: clear the file-read cache and optionally trigger `global.gc()`.
The monitor intentionally does not force chat compaction. Compaction can call
the model backend and rewrite active chat state, so it should be triggered only
from a call site that can safely coordinate with the conversation loop.
Cleanup is fire-and-forget from the scheduler, but the monitor guards cleanup
steps with `cleanupInProgress` and a cooldown timestamp. A higher-pressure
cleanup can bypass the cooldown and queue behind an in-progress lower-pressure
cleanup, so a `critical` check is not lost while a `soft` cleanup is finishing.
After successful cleanup it logs an RSS delta on `setImmediate()`, but RSS
movement is diagnostic only: V8 and libc may retain freed pages even when
JavaScript objects became collectible. Consecutive failures count cleanup-step
exceptions, not unchanged RSS, and the counter is reset on a new session. If
three successful cleanup attempts in a row free less than 1% RSS, the monitor
emits `memory-cleanup-ineffective` as a diagnostic signal without treating the
cleanup step itself as failed.
## Test Coverage
The implementation is covered by:
- threshold validation tests;
- environment config parsing, fallback, visible warning, and explicit GC tests;
- pressure classification tests using mocked `process.memoryUsage()`;
- cgroup v2 `memory.max` and cgroup v1 `memory.limit_in_bytes` behavior;
- V8 heap limit behavior;
- `scheduleCheck()` coalescing;
- scheduler integration that invokes `scheduleCheck()` after tool execution;
- soft and critical cleanup actions;
- cleanup failure accounting for thrown cleanup steps;
- cleanup listener exception isolation and ineffective-cleanup diagnostics;
- child `Config` monitor isolation through `Object.create`;
- `FileReadCache.evictNotAccessedSince()` behavior.
## Risks And Tradeoffs
- RSS can stay flat after cleanup because V8 or libc may retain freed memory.
RSS deltas are logged, but unchanged RSS does not count as a cleanup failure.
- Time-based file-read cache eviction may reduce fast-path hits for old files,
but it preserves recently active entries and only runs under memory pressure.

View File

View File

@ -3,6 +3,24 @@
This file provides guidance to Qwen Code when working with code in this
repository.
## Working Principles
### Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
**(This is the principle we care about most.)**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,
simplify.
_Adapted from Andrej Karpathy's [CLAUDE.md](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md)._
## Common Commands
### Building
@ -101,6 +119,9 @@ npm run preflight # Full check: clean → install → format → lint → build
between packages
- **Tests**: Collocated with source (`file.test.ts` next to `file.ts`),
vitest framework
- **File naming**: `PascalCase.tsx` for React components, `kebab-case.ts` for
new non-component files. Leave existing `camelCase` files alone — renaming breaks `git blame` and imports.
- **Comments**: Default to none. Add only when _why_ is non-obvious; don't delete existing ones as cleanup.
- **Commits**: Conventional Commits (e.g., `feat(cli): Add --json flag`)
- **Node.js**: Development and production both require `>=22` (Ink 7 + React 19.2 requirement)
@ -158,8 +179,13 @@ applicable.
- **PR description**: explain the motivation and changes in prose. Avoid
referencing file names or function names.
- **Reviewer Test Plan**: describe behaviors a reviewer should verify and what
to expect, not scripted test commands.
- **Reviewer Test Plan** (template section): describe behaviors a reviewer
should verify and what to expect, not scripted test commands. Use **How to
verify** for reproduction steps; Before/After for TUI evidence when
applicable.
- **Line wrapping**: do not hard-wrap the PR body at a fixed column width.
GitHub renders single newlines as `<br>`, so a wrapped description displays
as a narrow column. Write each paragraph or list item as one long line.
## Project Directories

View File

@ -17,13 +17,15 @@ npm install
### Setup Content
Link the documentation content from the parent `docs` directory:
Prepare the public documentation content from the parent `docs` directory:
```bash
npm run link
```
This creates a symbolic link from `../docs` to `content` in the project.
This creates a `content` directory with copies of the public docs sections.
Internal planning, design, and E2E notes remain outside the docs site content
tree.
### Development

View File

@ -7,10 +7,10 @@
"type": "module",
"main": "index.js",
"scripts": {
"link": "ln -s ../docs content",
"link": "node scripts/link-public-docs.mjs",
"clean": "rm -rf .next",
"dev": "npm run clean && next --turbopack",
"test": "echo \"Error: no test specified\" && exit 1"
"test": "vitest run --config vitest.config.js"
},
"dependencies": {
"next": "^16.0.8",
@ -18,5 +18,8 @@
"nextra-theme-docs": "^4.6.1",
"react": "^19.2.1",
"react-dom": "^19.2.1"
},
"devDependencies": {
"vitest": "^3.2.4"
}
}

View File

@ -0,0 +1,26 @@
import { cp, mkdir, rm, symlink } from 'node:fs/promises';
import { join } from 'node:path';
import { PUBLIC_DOC_ROOTS } from '../src/app/public-docs.js';
const contentDir = 'content';
async function linkPublicDocs() {
try {
await rm(contentDir, { force: true, recursive: true });
await mkdir(contentDir);
await cp('../docs/index.md', join(contentDir, 'index.md'));
await cp('../docs/_meta.ts', join(contentDir, '_meta.ts'));
for (const root of PUBLIC_DOC_ROOTS) {
await symlink(join('..', '..', 'docs', root), join(contentDir, root));
}
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
throw new Error(
`Failed to link public docs into ${contentDir}: ${message}`,
);
}
}
await linkPublicDocs();

View File

@ -1,10 +1,23 @@
import { generateStaticParamsFor, importPage } from 'nextra/pages';
import { notFound } from 'next/navigation';
import { useMDXComponents as getMDXComponents } from '../../../mdx-components';
import { filterPublicStaticParams, isPublicDocsPath } from '../public-docs';
export const generateStaticParams = generateStaticParamsFor('mdxPath');
const generateAllStaticParams = generateStaticParamsFor('mdxPath');
export const dynamicParams = false;
export async function generateStaticParams(...args) {
const staticParams = await generateAllStaticParams(...args);
return filterPublicStaticParams(staticParams);
}
export async function generateMetadata(props) {
const params = await props.params;
if (!isPublicDocsPath(params.mdxPath)) {
notFound();
}
const { metadata } = await importPage(params.mdxPath);
return metadata;
}
@ -13,6 +26,10 @@ const Wrapper = getMDXComponents().wrapper;
export default async function Page(props) {
const params = await props.params;
if (!isPublicDocsPath(params.mdxPath)) {
notFound();
}
const {
default: MDXContent,
toc,

View File

@ -0,0 +1,59 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
const mocks = vi.hoisted(() => {
const generateAllStaticParams = vi.fn();
return {
generateAllStaticParams,
generateStaticParamsFor: vi.fn(() => generateAllStaticParams),
};
});
vi.mock('nextra/pages', () => ({
generateStaticParamsFor: mocks.generateStaticParamsFor,
importPage: vi.fn(),
}));
vi.mock('next/navigation', () => ({
notFound: vi.fn(),
}));
vi.mock('../../../mdx-components', () => ({
useMDXComponents: () => ({
wrapper: ({ children }) => children,
}),
}));
describe('generateStaticParams', () => {
beforeEach(() => {
vi.clearAllMocks();
});
it('filters internal docs from Nextra static params', async () => {
mocks.generateAllStaticParams.mockResolvedValue([
{ mdxPath: [] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'users'] },
{ mdxPath: ['design', 'bar'] },
{ mdxPath: ['plans'] },
]);
const { generateStaticParams } = await import('./page.jsx');
await expect(generateStaticParams()).resolves.toEqual([
{ mdxPath: [] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'users'] },
]);
});
it('fails closed if Nextra changes the static params shape', async () => {
mocks.generateAllStaticParams.mockResolvedValue([{ slug: ['users'] }]);
const { generateStaticParams } = await import('./page.jsx');
await expect(generateStaticParams()).rejects.toThrow(
'Expected generateStaticParamsFor("mdxPath") to return objects with an mdxPath array.',
);
});
});

View File

@ -0,0 +1,33 @@
const LOCALE_SEGMENTS = new Set(['en', 'zh', 'de', 'fr', 'ja', 'ru', 'pt-BR']);
// Keep this in sync with the public top-level page entries in docs/_meta.ts.
// docs-site/scripts/link-public-docs.mjs consumes the same allowlist.
export const PUBLIC_DOC_ROOTS = ['users', 'developers'];
const PUBLIC_DOC_ROOT_SET = new Set(PUBLIC_DOC_ROOTS);
function publicRootFromSegments(segments = []) {
if (segments.length === 0 || (segments.length === 1 && segments[0] === '')) {
return undefined;
}
const rootIndex = LOCALE_SEGMENTS.has(segments[0]) ? 1 : 0;
return segments[rootIndex];
}
export function isPublicDocsPath(mdxPath = []) {
const root = publicRootFromSegments(mdxPath);
return root === undefined || PUBLIC_DOC_ROOT_SET.has(root);
}
export function filterPublicStaticParams(staticParams = []) {
return staticParams.filter((staticParam) => {
if (!Array.isArray(staticParam?.mdxPath)) {
throw new TypeError(
'Expected generateStaticParamsFor("mdxPath") to return objects with an mdxPath array.',
);
}
return isPublicDocsPath(staticParam.mdxPath);
});
}

View File

@ -0,0 +1,43 @@
import { describe, expect, it } from 'vitest';
import { filterPublicStaticParams, isPublicDocsPath } from './public-docs.js';
describe('isPublicDocsPath', () => {
it.each([
[[], true],
[[''], true],
[['users', 'foo'], true],
[['design', 'bar'], false],
[['en', 'users'], true],
[['plans'], false],
[['en'], true],
])('returns %s for %j', (mdxPath, expected) => {
expect(isPublicDocsPath(mdxPath)).toBe(expected);
});
});
describe('filterPublicStaticParams', () => {
it('keeps public paths and rejects internal docs paths', () => {
expect(
filterPublicStaticParams([
{ mdxPath: [] },
{ mdxPath: [''] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'developers'] },
{ mdxPath: ['design', 'bar'] },
{ mdxPath: ['plans'] },
]),
).toEqual([
{ mdxPath: [] },
{ mdxPath: [''] },
{ mdxPath: ['users', 'foo'] },
{ mdxPath: ['en', 'developers'] },
]);
});
it('fails closed if Nextra changes the static params shape', () => {
expect(() => filterPublicStaticParams([{ slug: ['users'] }])).toThrow(
'Expected generateStaticParamsFor("mdxPath") to return objects with an mdxPath array.',
);
});
});

View File

@ -0,0 +1,7 @@
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: ['src/**/*.test.{js,jsx}'],
},
});

View File

@ -4,6 +4,8 @@
## 背景
> 本节描述本 PR 落地**之前**的状态(pre-redesign behavior)。下文出现的 `COMPRESSION_TOKEN_THRESHOLD`、`thinkingConfig.includeThoughts = true`、`hasFailedCompressionAttempt`、以及具体的 file:line 引用都对应 PR #4345 合入前的代码——合入后这些符号 / 行号会不再有效。
当前 qwen-code 的自动压缩仅使用单一比例阈值 `COMPRESSION_TOKEN_THRESHOLD = 0.7`(`chatCompressionService.ts:33`),所有窗口大小共用同一比例。对比 claude-code 的「绝对 token 梯子」(autoCompact.ts:62-65),qwen-code 存在三个具体问题:
1. **大窗口下预留过多**:1M 模型 70% 阈值在 700K 触发,剩余 300K 远超摘要 + 输出实际所需的 ~33K
@ -136,12 +138,22 @@ export interface ChatCompressionSettings {
### Breaking change 处理
启动时 `Config` 加载发现 `chatCompression.contextPercentageThreshold` 存在:
**用户面:** 启动时 `Config` 加载发现 `chatCompression.contextPercentageThreshold` 存在:
- 写入 stderr 一行警告:`"chatCompression.contextPercentageThreshold has been removed and is now controlled by built-in thresholds."`
- **不**报错、**不**阻塞启动
- 字段值被忽略
**SDK 面(R5.4):** `CompressOptions` 的 `hasFailedCompressionAttempt: boolean` 字段重命名为 `consecutiveFailures: number`。两点差异:
| | 旧字段 | 新字段 |
| ---- | ------------------------------ | -------------------------------------------------------------------- |
| 名称 | `hasFailedCompressionAttempt` | `consecutiveFailures` |
| 类型 | `boolean` | `number` |
| 语义 | `true` = 永久禁用 auto-compact | `>= MAX_CONSECUTIVE_FAILURES`(默认 3)= 暂时禁用直到 force 成功重置 |
仓库内只有 `GeminiChat.tryCompress` 一个内部消费方,所以内部 migration 风险低;但 `@qwen-code/qwen-code-core` 是 published package、`CompressOptions` 在 d.ts 里可见,下游 SDK 直接调 `service.compress({ ..., hasFailedCompressionAttempt: true })` 的代码会拿到 TS 编译错误。**迁移指引:** 把 `true` 改为 `MAX_CONSECUTIVE_FAILURES`(或任意 >= 3 的整数),`false` 改为 `0`。如果调用方维护自己的失败计数,直接传入即可。
## Token 估算补偿
qwen-code 的 `lastPromptTokenCount` 来自上一轮 API response 的 `usageMetadata.totalTokenCount`([geminiChat.ts:1217-1232](packages/core/src/core/geminiChat.ts:1217))。这导致:
@ -415,4 +427,10 @@ const { warn, auto, hard, effectiveWindow } =
## 开放问题(等 review)
1. **breaking change 强度**:警告 + 忽略字段 vs 启动报错。当前选警告,需要确认对企业部署/团队配置是否够友好
2. **小窗口(32K)下 hard 与 auto 退化为同一值**:用户视角是否需要在 `/context` 明示「该窗口下 hard 已退化」
## 已结案
2. **小窗口(≤ ~76.7K)下 hard 与 auto 退化为同一值** — 决定**不在 `/context` 明示**。理由:
- 塌缩范围不只是 32K,所有 `effectiveWindow - HARD_BUFFER ≤ 0.7 × window` 的窗口都塌缩(包括 64K)
- 用户行为不变:塌缩窗口上 `currentTier` 跳过 `'auto'` 直接报 `'hard'`(`contextCommand.ts:43-44` 先判 `>= hard`),`context-high` band(`auto ≤ t < hard`)变成空带,少一档提示在小窗口上是合理的——窗口本身就小,用户大概率手动管理上下文
- 如果未来有真实用户报告"小窗口看不到中间档提示",再决定加 UI 标注或调整 `context-high` 触发条件(这是 UI 工作,不是 spec 工作)。当前选不增加 UI 复杂度

View File

@ -1,568 +0,0 @@
# Daemon ACP-over-HTTP → Official ACP Streamable HTTP Transport
> Targets `daemon_mode_b_main`. Branch: `feat/daemon-acp-http-streamable`.
> Author: arnoo.gao. Date: 2026-05-24. Status: **Design v1 → implementation**.
> Design-first per repo workflow: this doc lands before/with the implementation PR so the wire contract is reviewable.
---
## 0. TL;DR
The daemon (`qwen serve`) today speaks a **bespoke REST + SSE** dialect to web/SDK
clients, while speaking **real ACP JSON-RPC over stdio** to the spawned `qwen --acp`
child. This proposal adds a **second northbound transport** that implements the
**official ACP Streamable HTTP transport** (RFD #721) at a single `/acp` endpoint,
so any ACP-native client (Zed, Goose, future SDKs) can drive the daemon directly
over the standard protocol — no qwen-specific REST knowledge required.
**Decision: dual-transport, additive.** The new `/acp` endpoint is mounted
alongside the existing REST surface, reusing the same `HttpAcpBridge` +
`EventBus` underneath. The REST API is *not* removed. Rationale in §6.
**Decision: extension namespace = `_qwen/…`** (single-underscore prefix, the
ACP-spec-reserved form for custom methods) for daemon features that have no
standard ACP method (model switch, workspace introspection, heartbeat,
multi-client permission policy, SSE backpressure tuning). Rationale in §5.
A complete, locally-runnable reference implementation ships in this PR
(`packages/cli/src/serve/acpHttp/`) plus a verification harness
(`scripts/acp-http-smoke.mjs`).
---
## 1. Background — what "ACP over HTTP" means today
Three tiers (verified at commit `0c0430939`):
```
┌──────────────┐ bespoke REST + SSE (HTTP/1.1) ┌────────────┐ ACP JSON-RPC ┌──────────────┐
│ web / SDK │ ───────────────────────────────► │ qwen │ (stdio NDJSON) │ qwen --acp │
│ client │ ◄─── GET /session/:id/events ──── │ serve │ ◄─────────────► │ child (Agent)│
│ (ACP client) │ (text/event-stream) │ (daemon) │ ndJsonStream │ │
└──────────────┘ └────────────┘ └──────────────┘
northbound: NOT ACP wire bridge southbound: real ACP
```
### 1.1 Northbound (client ↔ daemon) — bespoke, today
- Express 5 app in `packages/cli/src/serve/server.ts` (~30 routes).
- Discrete REST verbs, **not** JSON-RPC:
- `POST /session` (create), `POST /session/:id/prompt`, `POST /session/:id/cancel`,
`POST /session/:id/load|resume`, `POST /session/:id/model`,
`POST /session/:id/permission/:requestId`, `POST /session/:id/heartbeat`,
`DELETE /session/:id`, plus `/workspace/*`, `/capabilities`, `/health`.
- Server→client streaming: `GET /session/:id/events` → `text/event-stream`.
- Frames: `id: <n>\nevent: <type>\ndata: <json>\n\n` (`server.ts:formatSseFrame`, ~2626).
- Per-session **monotonic `id`** + `Last-Event-ID` resume backed by a
ring-buffer `EventBus` (`acp-bridge/src/eventBus.ts`).
- Event `type`s: `session_update`, `client_evicted`, `slow_client_warning`,
`state_resync_required`, `stream_error`, …
- Auth: `Authorization: Bearer <token>` (`serve/auth.ts`), CORS deny + host allowlist.
- Backpressure: per-connection serialized write chain + 15 s heartbeat comments.
### 1.2 Southbound (daemon ↔ child) — already ACP
- `acp-bridge/src/spawnChannel.ts` spawns `qwen --acp`, wraps stdin/stdout with
`ndJsonStream` from `@agentclientprotocol/sdk` (`^0.14.1`).
- `acp-bridge/src/bridge.ts:729` `new ClientSideConnection(() => client, channel.stream)`
— the daemon is the ACP **client**, the child is the ACP **agent**.
- Extension methods already in use on this leg: `unstable_setSessionModel`,
`unstable_resumeSession`, `unstable_listSessions` (`acp-integration/acpAgent.ts`).
### 1.3 Why migrate the northbound
- Every client (webui, TS SDK, Java SDK, Python SDK, VSCode companion) re-implements
the bespoke REST mapping. An ACP-standard endpoint lets ACP-native editors attach
with zero qwen-specific glue.
- Aligns the daemon's remote surface with the protocol it already speaks internally.
---
## 2. Target: ACP Streamable HTTP (RFD #721)
Merged **Draft** RFD (`agentclientprotocol/agent-client-protocol#721`, merged 2026-04-22).
Not yet normative; not yet in any SDK. We implement against the RFD wire design.
### 2.1 Endpoint & verbs (single `/acp`)
| Verb | Behavior |
|------|----------|
| `POST /acp` | Send JSON-RPC. `initialize` → **`200`** + JSON body (capabilities) and sets `Acp-Connection-Id`. All other requests/notifications → **`202 Accepted`**, empty body; the *response* (if any) is delivered on the matching long-lived SSE stream. |
| `GET /acp` | Open a long-lived **SSE** stream. (`Upgrade: websocket` → WebSocket; **deferred**, see §7.) |
| `DELETE /acp` | Terminate the connection → `202`. |
### 2.2 Two-tier long-lived streams
- **Connection-scoped stream**: `GET /acp` with header `Acp-Connection-Id`, no session
header. Carries connection-level responses (`session/new`, `session/load`,
`authenticate`) and connection-level notifications.
- **Session-scoped stream**: `GET /acp` with `Acp-Connection-Id` **and** `Acp-Session-Id`.
Carries `session/update` notifications, **agent→client requests**
(`session/request_permission`, `fs/read_text_file`, …), and responses to
session POSTs (`session/prompt`, `session/cancel`).
### 2.3 Identity (3 layers)
- `Acp-Connection-Id` (HTTP header) — transport binding, minted at `initialize`.
- `Acp-Session-Id` (HTTP header) — required on session-scoped GET + session POSTs.
- `sessionId` (JSON-RPC param) — inside method params (must match the header).
### 2.4 Divergences from MCP StreamableHTTP
ACP uses **long-lived** streams (not per-request SSE), **two** ID headers (connection
vs session), `202`-for-non-initialize, HTTP/2-required, WebSocket-required-client. We
borrow the single-endpoint + POST/GET-SSE + session-header skeleton but adapt to the
long-lived dual-ID model. We do **not** reuse `@modelcontextprotocol/sdk`'s
`StreamableHTTPServerTransport` (its per-request stream model and single
`Mcp-Session-Id` don't fit).
### 2.5 Standard methods (confirmed from current schema)
- Client→Agent requests: `initialize`, `authenticate`, `session/new`, `session/load`,
`session/prompt`, `session/resume`, `session/close`, `session/list`,
`session/set_mode`, `session/set_config_option`, `logout`.
- Client→Agent notification: `session/cancel`.
- Agent→Client requests: `fs/read_text_file`, `fs/write_text_file`,
`session/request_permission`, `terminal/create|output|wait_for_exit|kill|release`.
- Agent→Client notification: `session/update`.
---
## 3. Architecture of the new transport
The daemon must present an **ACP Agent surface over HTTP** northbound, while it
remains an ACP **client** to the child southbound. The `/acp` layer is therefore a
**JSON-RPC router** that terminates the HTTP transport and bridges into the existing
`HttpAcpBridge`.
```
POST /acp (JSON-RPC requests/responses/notifs)
client ──────────────────────────────────────────────► ┌───────────────────────────┐
(editor) │ AcpHttpTransport │
◄── GET /acp (connection-scoped SSE) ────────── │ - connection registry │
◄── GET /acp (session-scoped SSE) ───────────── │ - JSON-RPC id correlation│
│ - method dispatch │
└────────────┬──────────────┘
│ reuses
┌────────────▼──────────────┐
│ HttpAcpBridge + EventBus │ (unchanged)
└────────────┬──────────────┘
│ ACP stdio (unchanged)
qwen --acp child
```
### 3.1 New module layout (`packages/cli/src/serve/acpHttp/`)
| File | Responsibility |
|------|----------------|
| `index.ts` | `mountAcpHttp(app, bridge, opts)` — registers `/acp` routes on the existing Express app. |
| `connectionRegistry.ts` | `Acp-Connection-Id` → `AcpConnection` (connection SSE writer, `Map<sessionId, SessionStream>`, pending agent→client requests by JSON-RPC id, monotonic id allocator). TTL + DELETE cleanup. |
| `jsonRpc.ts` | JSON-RPC 2.0 parse/validate/serialize helpers; error codes (`-32600` etc.); `_qwen/` namespace guard. |
| `dispatch.ts` | Maps inbound JSON-RPC methods → `HttpAcpBridge` calls. Maps `BridgeEvent`s → outbound JSON-RPC frames. The translation table (§4). |
| `sseStream.ts` | Long-lived SSE writer (reuses the backpressure/heartbeat pattern from `server.ts`). Distinct from REST `/events` (different framing: full JSON-RPC objects, not qwen event envelopes). |
No change to `bridge.ts` / `eventBus.ts` (additive consumer only).
### 3.2 Connection & session lifecycle
1. `POST /acp {initialize}` → mint `connectionId`, create `AcpConnection`, reply `200`
with `{protocolVersion, agentCapabilities, _meta:{qwen:{…}}}` + `Acp-Connection-Id` header.
2. Client opens `GET /acp` (connection-scoped) carrying `Acp-Connection-Id`.
3. `POST /acp {session/new}` → `202`; daemon calls `bridge.createSession(...)`; pushes
the JSON-RPC response (with `sessionId`) down the **connection** stream.
4. Client opens `GET /acp` (session-scoped) with `Acp-Connection-Id`+`Acp-Session-Id`;
daemon `bridge.subscribeEvents(sessionId)` and pipes translated frames.
5. `POST /acp {session/prompt}` → `202`; `bridge.sendPrompt(...)`; `session/update`
notifications stream live on the session stream; the final prompt **response**
(`{id, result:{stopReason}}`) is pushed on the session stream when it settles.
6. Agent→client request (e.g. `session/request_permission`) is emitted as a JSON-RPC
**request** on the session stream with a daemon-allocated id; the client answers via
`POST /acp {id, result}`; `dispatch` resolves it through the bridge's permission API.
7. `DELETE /acp` (or connection-stream close + TTL) tears down sessions/subscriptions.
---
## 4. Translation table (bridge ⇄ ACP/HTTP)
### 4.1 Inbound (client POST → bridge)
| ACP method | Bridge call | Response routed to |
|------------|-------------|--------------------|
| `initialize` | (none; capabilities from `capabilities.ts`) | inline `200` |
| `authenticate` | existing auth provider (`serve/auth/*`) | connection stream |
| `session/new` | `bridge.createSession` | connection stream |
| `session/load` / `session/resume` | `bridge.restoreSession('load'|'resume')` | connection stream |
| `session/prompt` | `bridge.sendPrompt` | session stream (deferred until settle) |
| `session/cancel` (notif) | `bridge.cancel` | — |
| `session/list` | `bridge.listSessions` (`unstable_listSessions`) | connection stream |
| `session/set_mode` | approval-mode route logic | session stream |
| JSON-RPC **response** (to agent→client req) | resolve pending (`§4.3`) | — |
| `_qwen/session/set_model` | `bridge.setSessionModel` (`unstable_setSessionModel`) | session stream |
| `_qwen/workspace/list` etc. | workspace introspection routes | connection stream |
| `_qwen/session/heartbeat` | `bridge.heartbeat` | connection stream |
### 4.2 Outbound (BridgeEvent → JSON-RPC on session stream)
| BridgeEvent.type | Emitted as |
|------------------|-----------|
| `session_update` | `{method:"session/update", params:<data>}` notification |
| permission request | `{id:<n>, method:"session/request_permission", params}` request |
| `client_evicted` / `slow_client_warning` / `state_resync_required` | `{method:"_qwen/notify", params:{kind,…}}` notification |
| `stream_error` | JSON-RPC error response on the active prompt id (or `_qwen/notify`) |
| prompt settle | `{id:<promptId>, result:{stopReason}}` |
### 4.3 Pending agent→client requests
`AcpConnection` keeps `Map<jsonRpcId, {sessionId, kind, bridgeRequestId, resolve}>`.
When the client POSTs a JSON-RPC response object, `dispatch` matches `id`, then calls the
bridge resolution path (e.g. permission `POST /session/:id/permission/:requestId`
internal equivalent).
> **v1 status:** only the `session/request_permission` agent→client round-trip is
> implemented. `fs/*` and `terminal/*` agent→client forwarding is **deferred** (§7) — the
> daemon does not yet advertise `fs`/`terminal` client-capability negotiation on `/acp`,
> so ACP clients should not assume filesystem/terminal semantics over this transport in
> v1. The intended end state (forward `fs/*` to the client; fall back to the daemon's
> workspace FS when the client lacks the `fs` capability) is the follow-up described in §7.
---
## 5. Extension strategy (requirement #2)
ACP reserves any method starting with `_` for custom extensions and provides `_meta`
on every type. The codebase's southbound leg already uses `unstable_*` method names.
**Northbound choice:** vendor-namespaced **`_qwen/<area>/<verb>`** method names
(spec-compliant `_` prefix). Capabilities advertised under
`agentCapabilities._meta.qwen` at `initialize` so clients feature-detect before use.
| Need | No standard ACP method? | Extension |
|------|------------------------|-----------|
| Model switch | yes | `_qwen/session/set_model` |
| Workspace MCP/skills/providers/env introspection | yes | `_qwen/workspace/list`, `_qwen/workspace/<area>` |
| Heartbeat / last-seen | yes | `_qwen/session/heartbeat` |
| Multi-client permission policy (consensus/designated) | partial | `session/request_permission` + `_meta.qwen.policy` |
| SSE backpressure tuning (`maxQueued`) | yes | `Acp-Qwen-Max-Queued` header on session GET |
| Resume cursor (ring `Last-Event-ID`) | RFD Phase 4 | `Last-Event-ID` header + `_meta.qwen.eventId` on frames |
Standard methods are **never** renamed; extensions are strictly additive and ignorable.
---
## 6. Dual-transport vs. replace (requirement #4)
**Decision: dual-transport (additive).**
- The official transport is a **Draft** RFD, not normative, and absent from every SDK —
hard-replacing would couple us to an unratified design and break webui + 3 SDKs +
VSCode companion at once.
- The REST surface carries features with no clean ACP mapping yet (workspace
introspection, multi-client permission mediation, ring-buffer resume, capability
registry). Those degrade to `_qwen/*` extensions on `/acp` but the REST surface stays
authoritative until the RFD ratifies.
- Both transports share **one** `HttpAcpBridge` + `EventBus` instance, so there is no
state duplication — `/acp` and `/session/*` can even drive the same live session
concurrently (multi-client is already supported by the bridge).
- Toggle (v1, shipped): on by default; **`QWEN_SERVE_ACP_HTTP=0`** disables the mount. A
`--no-acp-http` CLI flag and an `acp_http` tag in `/capabilities` for client feature-
detection are **deferred** to a follow-up (not in v1) — until then clients detect the
transport by probing `POST /acp {initialize}`.
Migration path: once the RFD ratifies and SDKs ship, REST routes can be reframed as a
thin compat shim over `/acp` (separate, later PR).
---
## 7. Scope of the implementation PR
**In scope (runnable + verified locally):**
- `POST /acp` dispatch for `initialize`, `session/new`, `session/prompt`,
`session/cancel`, `session/load`, JSON-RPC response handling.
- Connection-scoped + session-scoped `GET /acp` SSE streams with JSON-RPC framing.
- `session/update` streaming + final prompt response correlation.
- `session/request_permission` agent→client round-trip.
- `_qwen/session/set_model` extension as the worked example of #2.
- Bearer-auth + host allowlist reuse (same middleware as REST).
- Unit tests (`acpHttp/*.test.ts`) + a black-box smoke script driving a real daemon.
**Deferred (documented, not built now):**
- WebSocket upgrade path (RFD-required client cap; SSE suffices for local verify).
- HTTP/2 multiplexing (we run HTTP/1.1; POST and long-lived GET use separate sockets,
which works for CLI/Node clients and ≤6-connection browsers). Documented divergence.
- Full `fs/*` + `terminal/*` agent→client forwarding (permission path proves the
mechanism; rest is mechanical follow-up).
- SSE resumability hardening parity with the ring buffer (Phase 4 in RFD).
---
## 8. Local verification plan
1. `npm run build` (or workspace build of `cli` + `acp-bridge`).
2. Start daemon: `qwen serve --listen 127.0.0.1:0 --token <t>` (or env token).
3. Run `node scripts/acp-http-smoke.mjs`:
- `POST /acp {initialize}` → assert `200` + `Acp-Connection-Id`.
- Open connection SSE; `POST {session/new}` → assert response on stream.
- Open session SSE; `POST {session/prompt:"say hi"}` → assert ≥1 `session/update`
then a final `{result:{stopReason}}`.
- Trigger a tool needing permission → assert `session/request_permission` request,
POST a grant response → assert prompt completes.
- `POST {_qwen/session/set_model}` → assert model switch + `session/update`.
4. Vitest: `acpHttp/*.test.ts` green.
---
## 9. Risks
| Risk | Mitigation |
|------|-----------|
| RFD changes before ratification | Behind capability tag + `_qwen` namespace; isolated module; easy to revise. |
| HTTP/1.1 vs required HTTP/2 | Localhost/CLI clients unaffected; documented; h2 is a transport swap later. |
| Two transports on one bridge race | Bridge already supports multi-client; reuse its locking. |
| `fs/*` forwarding vs daemon-local FS | Capability-gated: forward when client declares `fs`, else local. |
---
## 10. Implementation & verification log (v1)
Implemented in `packages/cli/src/serve/acpHttp/` (`jsonRpc.ts`, `sseStream.ts`,
`connectionRegistry.ts`, `dispatch.ts`, `index.ts`), mounted from `server.ts`
via `mountAcpHttp(app, bridge, { boundWorkspace })`.
### Automated (`packages/cli/src/serve/acpHttp/*.test.ts`)
`transport.test.ts` boots a real Express server + the real `mountAcpHttp` over
a controllable fake bridge and drives it with `fetch` + manual SSE parsing.
15 tests green, covering: `initialize` 200 + `Acp-Connection-Id`; unknown-conn
400; `session/new` reply on the connection stream; prompt → `session/update`
stream + final result correlation; `session/request_permission` agent→client→
agent round-trip; `_qwen/session/set_model`; method-not-found; `DELETE` teardown.
### Live daemon (real model)
Booted `qwen serve --port 8767 --token … --workspace …` (bundle entry so the
spawned `qwen --acp` child is self-contained) and ran `scripts/acp-http-smoke.mjs`:
```
✓ initialize: connectionId=… protocolVersion=1
✓ session/new: sessionId=…
→ prompt: "Reply with the single word: pong"
pong
✓ prompt complete: 10 session/update frames, stopReason=end_turn
✓ DELETE /acp — connection closed
ALL CHECKS PASSED ✅
```
Error-path was also confirmed live: when the child failed to start, the bridge
timeout surfaced to the client as a JSON-RPC error frame on the connection
stream (`{"id":2,"error":{"code":-32603,…}}`), proving id-correlation + the
202/SSE split under failure.
### Review fold-in — bridge-issued clientId (found in live verify)
First live run failed `session/prompt` with *"client id … is not registered for
session"*. Root cause: `spawnOrAttach`/`loadSession` **ignore** a caller-supplied
clientId the bridge has never issued and stamp a fresh one (returned in
`BridgeSession.clientId`); the dispatcher was echoing the connection's own
(unregistered) id on `sendPrompt`. Fix: persist the bridge-stamped id on the
`SessionBinding` and echo it on every per-session call (`sessionCtx`). Re-verified
green above.
---
## 11. Review round 2 — fold-ins
Two independent reviews (correctness/concurrency + protocol-conformance/security) plus a self-read.
All fixes verified by the expanded vitest suite (**18 tests**) + a fresh live smoke run
(21 `session/update` frames → `stopReason=end_turn`).
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| R1 | **P0** | Session-stream **reconnect was permanently dead**: `SessionBinding.abort` was created once and reused; on stream close it was aborted forever, so a reconnect's `subscribeEvents(signal)` got an already-aborted signal and received zero events. | `attachSessionStream` now installs a **fresh** `AbortController` per stream (and closes any prior stream); `index.ts` pumps on that fresh signal. |
| R2 | **P0** | `await dispatcher.handle()` ran **after** `res.end(202)`; a throwing bridge call (notably the un-try/caught `isResponse` path) would reject and surface as an unhandled rejection → possible daemon crash. | Wrapped the `isResponse` path in try/catch; `.catch()` on the awaited `handle(...)` and on `pumpSessionEvents(...)`. |
| R3 | **P1** | **No connection→session ownership**: any authenticated connection could open the session SSE for, or prompt, *any* sessionId in the workspace (read-eavesdrop; prompt was only blocked incidentally by the unregistered-clientId error). | `AcpConnection.ownedSessions` populated by `session/new`/`load`/`resume`; session stream returns `403` and per-session POSTs return `INVALID_PARAMS` for unowned ids (`requireOwned`). |
| R4 | **P1** | `mountAcpHttp` handle was discarded → TTL sweep timer + live SSE streams leaked on shutdown. | Handle parked on `app.locals`; `runQwenServe` close hook calls `dispose()` before `bridge.shutdown()` (mirrors the device-flow registry). |
| R5 | **P1** | **Pending permission leak**: closing a session/connection with a permission outstanding left the bridge blocked awaiting a vote. | `closeSessionStream`/`destroy` cancel matching pending requests via an injected `onAbandonPending` → `cancelAbandonedPermission`. |
| R6 | **P1** | Pre-attach frame buffers (`connBuffer`/`binding.buffer`) were unbounded. | Capped at 256 frames (drop-oldest), matching the EventBus `maxQueued`. |
| R7 | **P2** | `initialize` ignored the client's requested `protocolVersion`. | Negotiates `min(requested, 1)`. |
| R8 | **P2** | No `Acp-Session-Id` ↔ `params.sessionId` cross-check (RFD §2.3). | POST asserts they agree; mismatch → `INVALID_PARAMS`. |
| R9 | **P2** | `session/cancel` request-form (with id) never answered; duplicate top-level `_meta.qwen`. | Reply when an id is present; single `agentCapabilities._meta.qwen`. |
### Accepted / documented (not fixed in v1)
- **Prompt-result vs trailing `session/update` ordering** (P2): `handlePrompt` awaits `sendPrompt` then
writes the result frame, while updates stream concurrently. In practice the bridge publishes all
`session/update`s to the bus before `sendPrompt` resolves and both share one ordered SSE write
chain, so the result lands last (confirmed: 21 updates then result). A strict barrier is a possible
later hardening if a client reducer proves sensitive.
- **Browser `EventSource` can't set `Authorization`** — `/acp` GET streams require the bearer header,
so browsers need the deferred WebSocket path (§7); CLI/Node clients are unaffected.
- The daemon's real trust boundary remains the **bearer token + single-workspace bind** (same as the
REST surface); R3's ownership check is defense-in-depth + contract correctness, not a tenant boundary.
---
## 12. Review round 3 — PR bot fold-ins (#4472)
Two automated PR reviewers plus the summary bot.
All fixes verified by the suite (now **22 tests**) + a fresh live run (16 `session/update` → `end_turn`).
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| B1 | **P0** | `handlePrompt`'s `AbortController` was never aborted — a disconnecting/cancelling client left the agent running (burned model quota, blocked the session FIFO). Flagged by both bots + 5 sub-agents. | `promptAbort` parked on `SessionBinding`; aborted by `session/cancel` and by session/connection teardown (`closeSessionStream`/`destroy`). |
| B2 | **P0** | `sessionCtx` missing `fromLoopback` → every ACP permission vote treated as remote; `local-only` policy would reject loopback clients. | Capture loopback at `initialize` (kernel `remoteAddress`, not forgeable headers) → `AcpConnection.fromLoopback` → threaded through `sessionCtx`. |
| B3 | **P0** | SSE write failures silently swallowed → zombie streams (heartbeats fire, zero events delivered, no logs). | First write failure logs + closes the stream. |
| B4 | **P0** | Idle sweep destroyed connections with no log + no connection cap (initialize-flood). | Sweep logs each reap; `pumpSessionEvents` calls `touch()` (long quiet prompts aren't reaped); `maxConnections` cap (64) → `503`. |
| B5 | **P1** | `sessionCtx` silently fell back to the connection's unregistered clientId when the binding lacked one (untested, always-fired in `FakeBridge`). | Throw on missing stamped clientId (invariant violation); `FakeBridge` now stamps one. |
| B6 | **P1** | `session/new|load|resume` accepted `cwd` unvalidated (REST validates string/length/absolute — amplification DoS). | Shared `parseOptionalWorkspaceCwd` (string, ≤4096, absolute). |
| B7 | **P1** | `session/prompt` forwarded an unvalidated `prompt` to the bridge. | `validatePrompt` (non-empty array of objects), mirroring REST. |
| B8 | **P1** | Raw bridge error messages echoed to the client. | `toRpcError` maps known bridge errors to coded, client-safe shapes; unknown → generic `Internal error` (full detail still to stderr). |
| B9 | **P1** | `nextId` used sequential negatives — a client legally using negative ids could collide in `pending`. | Daemon-originated ids are now strings (`_qwen_perm_N`), disjoint from any client id. |
| B10 | **P2** | `resolveClientResponse` param type excluded `JsonRpcError`; conn-scoped SSE stream had no `onClose`; `DELETE` with no header was a silent 202; `SseStream.close` ran `onClose` outside try/catch; `session/load`·`resume`·`close` untested. | Widened param to `JsonRpcResponse`; conn stream logs on close; `DELETE` missing header → `400`; `onClose` wrapped in try/catch; added load/resume/close + DELETE-400 tests. |
**Out of scope (base-branch `daemon_mode_b_main`, not this diff)** — the second reviewer flagged
typecheck errors in `acpAgent.ts` (`entryCount`/`entrySummary`/`sessionClose`) and other pre-existing
items it explicitly attributed to the base branch (introduced by #4353). Tracked separately; not
touched here.
**Still deferred** (documented): per-connection secret for `DELETE`/connection ownership (token remains
the boundary); WebSocket + HTTP/2 (§7); strict prompt-result vs trailing-update barrier (§11).
---
## 13. Review round 4 — PR fold-ins (rebased onto #4469)
Branch rebased onto `daemon_mode_b_main` (#4353 + #4469) — **clean, no conflicts**. Two PR
reviewers (GPT-5 + qwen3.7-max). Suite now **25 tests**; live re-verified (125 `session/update`
→ `end_turn`).
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| C1 | **P0** | Round-3 "SSE write-failure handling" was documented but NOT implemented — `SseStream` still left it to discarding callers (zombie streams). | `writeRaw` now owns it: first write rejection logs once + `close()`s; `doWrite` also listens for `'error'` (rejects promptly instead of hanging to `'close'`); `onClose` wrapped in try/catch. |
| C2 | **P1** | `fromLoopback` captured only at `initialize` + helper narrower than REST → `local-only` votes from a later POST misjudged. | Per-request loopback threaded through `handle`→`sessionCtx`/`resolveClientResponse`; `isLoopbackReq` widened to `127.0.0.0/8` + `::ffff:127.*` + `::1` (matches REST). |
| C3 | **P1** | Error routing inferred stream from `params.sessionId` → conn-scoped method failures (`session/load`/`resume`/`close`/`heartbeat`) misrouted to a non-existent session stream (silent loss). | `CONN_ROUTED_METHODS` set; errors route the same way as the success path. |
| C4 | **P1** | `bridge.detachClient` never called on teardown → stale bridge-stamped client ids linger in `knownClientIds()`/voter sets. | Registry takes a `DetachSessionFn`; `closeSessionStream`/`destroy` detach each owned session (best-effort). |
| C5 | **P1** | `session/close` skipped local cleanup if `bridge.closeSession` threw. | `closeSessionStream` moved into a `finally`. |
| C6 | **P2** | Windows `cwd` (`C:\…`) rejected by `startsWith('/')`. | `path.isAbsolute` (platform-aware), matching REST. |
| C7 | **P2** | `protocolVersion` could negotiate `0`/negative. | Clamp `Math.max(1, Math.min(requested, 1))`; tests for 0/neg/huge/invalid. |
| C8 | **P2** | `session/load`/`resume` accepted empty `sessionId`. | Reject empty with `INVALID_PARAMS`. |
| C9 | **P2** | Notification-form `session/prompt` errors vanished silently. | Log on the no-id path. |
| C10 | **P2** | Session SSE flushed buffered frames before headers/`retry:`. | `open()` before `attachSessionStream`. |
| C11 | **P2** | Duplicate local `logStderr`. | Shared `writeStderrLine` from `utils/stdioHelpers`. |
| C12 | **P2** | Docs advertised `--no-acp-http` flag, `acp_http` capability tag, and `fs/*` forwarding not in v1. | Doc aligned to shipped surface (env-var toggle only; `fs/*`+`terminal/*` + flag + tag marked deferred). |
Still deferred (unchanged): WebSocket + HTTP/2; per-connection secret for `DELETE`/ownership
(token + single-workspace remains the boundary); strict prompt-result ordering barrier; the
`as never` bridge-boundary casts (targeted, noted for an adapter-types follow-up).
---
## 14. Review round 5 — PR fold-ins
One more reviewer pass (qwen3.7-max). Suite **26 tests**, live re-verified.
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| D1 | **P0** | `resolveClientResponse` deleted the pending entry BEFORE calling `respondToSessionPermission`. A malformed vote (`result: {}`) makes the bridge mediator throw — and with the pending entry already gone, teardown's `abandonPendingForSession` can't cancel it, so the agent's prompt hangs on a vote that never resolves (a token-holder could stall a session with one bad POST). | Wrap the vote in try/catch; on any failure fall back to `cancelAbandonedPermission` so the mediator is always released. New test covers the malformed-vote path. |
| D2 | **P1** | Session-stream `onClose` aborted only the event pump, not `binding.promptAbort` — a client disconnect (tab close / network drop) left the in-flight prompt running (quota + FIFO) until idle TTL. | `onClose` now also aborts the session's `promptAbort`. |
| D3 | **P1** | When `pumpSessionEvents` rejected, the `.catch` only logged — the SSE stream stayed open heartbeating but delivering nothing (zombie, no reconnect signal). | `.catch` now also `closeSessionStream(sessionId)`. |
---
## 15. Review round 6 — PR fold-ins
Another reviewer pass (qwen3.7-max). Suite **28 tests**, live re-verified.
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| E1 | **P0** | `handlePrompt` overwrote `binding.promptAbort` without aborting the prior controller — two concurrent `session/prompt`s for one session orphaned the first (runs to completion in the bridge FIFO, unabortable by `session/cancel`). | Abort the prior `promptAbort` before installing the new one. Test added. |
| E2 | **P0** | The `subscribeEvents`-throws path sent a `stream_error` notify then `return`ed (resolved) — the caller's `.catch` never fired, leaving a zombie SSE stream (heartbeats, no events, no reconnect signal). | Re-throw after the notify so the caller's `.catch` closes the stream. Test asserts prompt closure. |
| E3 | **P1** | SSE heartbeat didn't mark the connection active — a long prompt with no intermediate events for >30 min got idle-reaped (streams + prompts killed). | `SseStream` takes an `onHeartbeat` hook; both GET handlers pass `() => conn.touch()`. |
| E4 | **P2** | `pumpSessionEvents` `.catch` closed by sessionId — a reconnect between the throw and the microtask could kill the NEW stream. | Identity-guard: only close if `binding.stream` is still this stream. |
| E6 | **P2** | `sendSession` auto-created a binding — a late pump/reply frame after `closeSessionStream` resurrected a ghost binding that buffered up to 256 frames forever. | `sendSession` is now lookup-only: drops frames when the session has no live binding. |
| E5 | accepted | `session/load`/`resume` don't reject when another live connection owns the session ("hijack"). | **Accepted, not changed:** the daemon's trust boundary is the bearer token + single-workspace bind, and multi-client attach is intentional (the bridge is multi-client by design; REST has the same property). A token-holder gains no capability they lack via REST. Tracked with the other token-boundary items (DELETE ownership, §13). |
---
## 16. Review round 7 — PR fold-ins
Another reviewer pass (qwen3.7-max). Suite **30 tests**, live re-verified.
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| F1 | **P0** | Concurrent `session/close` TOCTOU: `ownedSessions.delete` ran only in `finally` (after the await), so two concurrent closes both passed `requireOwned` → misleading error to the 2nd + redundant bridge close. | Delete the ownership gate SYNCHRONOUSLY before the await; bridge close runs once. Test added. |
| F2 | **P1** | Pump lifecycle: a CLEAN iterator end (subprocess ended, `done`) resolved → the `.catch` never fired → zombie stream; and a MID-STREAM iterator error sent no `stream_error`. | `pumpSessionEvents` wraps the whole loop (sync + mid-stream errors send `stream_error` then re-throw); the consumer `.then(onDone, onErr)` closes the stream on BOTH paths (identity-guarded). Tests added. |
| F3 | **P2** | 503 connection-cap rejection had no stderr log. | `writeStderrLine` with the cap value. |
| F4 | **P2** | `_qwen/notify stream_error` spread let `event.data.kind` shadow the discriminator. | Spread first, then `kind: 'stream_error'`. |
| F5 | **P2** | `MAX_WORKSPACE_PATH_LENGTH` redeclared (`= 4096`) vs the canonical `fs/paths.js`. | Import from `../fs/paths.js` (no divergence). |
| F6 | **P2** | `isObjectParams` duplicated `jsonRpc.isObject`. | Import `isObject`. |
| F7 | **P2** | Raw `process.stderr.write` in `index.ts`/`sseStream.ts` vs `writeStderrLine` elsewhere. | Unified on `writeStderrLine` across the module. |
---
## 17. REST 等价对齐 + 扩展方案审计落地(round 8)
目标:让 `/acp` 成为 REST+SSE 的**等价替代**。本批基于审计结论重构扩展方案,并补齐**所有 bridge 已暴露**的能力;bridge 尚未拥有的能力(文件 I/O、设备流、agents/memory CRUD)按架构正确性要求**先由 acp-bridge 补齐**(见 §17.3)。
### 17.1 扩展方案审计 → 落地(替换 §5 的旧方案)
依据**仓库实装 SDK `@agentclientprotocol/sdk@0.14.1`**(非仅官网)核对:
- `session/set_config_option` 是**一等(非 `unstable_`)方法**,请求 `{sessionId, configId, value}`,`category` 含 `model`/`mode`/`thought_level`;而 `set_model` 仍走 `unstable_setSessionModel`。
- 规范保留 `_` 前缀给扩展,示例为域风格 `_zed.dev/…`;厂商数据放 `_meta` 按域名分键。
落地:
- **命名空间 `_qwen/` → 反向域名 `_qwen/`**;`_meta` 统一 `_meta:{ "qwen": … }`(含 `initialize` 能力广告与 `session/request_permission` 的 requestId)。
- **模型 + 审批模式 → 标准 `session/set_config_option`**(`configId:"model"|"mode"`),路由到现有 `bridge.setSessionModel`/`setSessionApprovalMode`;`session/new` 结果**广告 `configOptions`**(取自子进程会话状态 `getSessionContextStatus().state.configOptions`,已是 ACP 形状)。**删除**厂商 `_qwen/session/set_model`。
- REST(http+sse) **无需同步修改**:两 transport 共用同一 bridge,状态天然一致。
### 17.2 本批新增的 `/acp` 方法(bridge 已支持,1:1 对齐 REST)
| REST | `/acp` | bridge |
|---|---|---|
| `POST /session/:id/model` / `approval-mode` | **标准** `session/set_config_option`(model/mode) | setSessionModel / setSessionApprovalMode |
| `GET /session/:id/context` | `_qwen/session/context` | getSessionContextStatus |
| `GET /session/:id/supported-commands` | `_qwen/session/supported_commands` | getSessionSupportedCommandsStatus |
| `PATCH /session/:id/metadata` | `_qwen/session/update_metadata` | updateSessionMetadata |
| `GET /workspace/{mcp,skills,providers,env,preflight}` | `_qwen/workspace/{…}` | getWorkspace*Status |
| `POST /workspace/init` | `_qwen/workspace/init` | initWorkspace |
| `POST /workspace/tools/:name/enable` | `_qwen/workspace/set_tool_enabled` | setWorkspaceToolEnabled |
| `POST /workspace/mcp/:server/restart` | `_qwen/workspace/restart_mcp_server` | restartMcpServer |
(既有:session/new·load·resume·close·list·prompt·cancel、heartbeat、permission、events 已对齐。)
### 17.3 仍缺口 → 要求 acp-bridge 先补齐(架构正确性)
REST 的 **文件 I/O**(`/file /glob /list /stat /file/write /file/edit`)、**设备流登录**(`/workspace/auth/*`)、**agents CRUD**(`/workspace/agents`)、**memory CRUD**(`/workspace/memory`)目前**不在 `HttpAcpBridge` 上**——REST 路由直接调 route 级服务(`WorkspaceFileSystemFactory`、`DeviceFlowRegistry`、`SubagentManager`、`writeWorkspaceContextFile`),绕过了 bridge。
**决策(采纳评审/owner 意见)**:不让 `/acp` transport 再去直连这些 route 级服务(那会复制 REST 的架构漂移、并使 transport 耦合翻倍)。**正确做法是先在 `@qwen-code/acp-bridge` 的 `HttpAcpBridge` 上补齐这些能力**(如 `readWorkspaceFile`/`writeWorkspaceFile`/`globWorkspace`、`startDeviceFlow`/`pollDeviceFlow`、`listAgents`/`upsertAgent`/`deleteAgent`、`readMemory`/`writeMemory`),让 REST 与 `/acp` 都经由 bridge。届时 `/acp` 再加 `_qwen/fs/*`、`_qwen/auth/*`、`_qwen/workspace/agent*`、`_qwen/workspace/memory*`(文件读因无标准 ACP client→agent 方法,属合法厂商扩展)。
**完整等价 = 本批(bridge 已有能力)+ acp-bridge 补齐缺口后的后续批**。
---
## 18. Review round 9 — PR fold-ins
| # | Severity | Finding | Fix |
|---|----------|---------|-----|
| G1 | **P1 (regression)** | Session-stream reconnect aborted the in-flight prompt: `attachSessionStream` closed the OLD stream before installing the new one, and the old stream's `onClose` unconditionally aborted `promptAbort` — so a reconnecting client (network glitch/roaming) lost its running prompt. | Install the new stream BEFORE closing the old; identity-guard `onClose`'s prompt-abort (only abort if THIS is still the session's live stream). Test added (prompt survives reconnect). |
| G2 | **P2** | `session/cancel` passed `undefined` as the `CancelNotification` body, dropping client-supplied cancel fields (reason/context) that REST forwards. | Forward `{ ...params, sessionId }` (mirrors REST). |
Rebased onto latest `daemon_mode_b_main` (#4473/#4483/#4484/#4500), no conflicts. Suite **33 tests**, live re-verified.
---
## 19. 路线图 / 后续 PR(防遗忘)
本 PR(#4472)= ACP Streamable HTTP transport + **全部 bridge-backed 能力对齐** + 官方扩展方案。已转 **ready**。达到「`/acp` 完全等价 REST+SSE」尚需:
1. **Follow-up PR 1 — acp-bridge 能力补齐(前置 / bridge-first)**:`HttpAcpBridge` 新增 文件 I/O、设备流、agents CRUD、memory CRUD 方法;REST 路由改走 bridge(消除直连 route 级服务的漂移)。
2. **Follow-up PR 2 — `/acp` 剩余对齐(依赖 PR 1)**:`_qwen/fs/*`、`_qwen/auth/*`、`_qwen/workspace/agent*`、`_qwen/workspace/memory*` → 完全等价 REST。
跟踪:#3803(open decisions)、#4175(Mode B roadmap)均已 comment。
Deferred 硬化项见 PR 描述「已知 deferred」。
---
## 20. Extension-namespace rename + SDK-transport analysis (round 11)
- **Namespace `_qwen.ai/` → `_qwen/`**: ACP's only hard rule is the leading `_`; the `_zed.dev/` domain segment is convention-by-example, not a MUST. Since `qwen` is distinctive, we use the shorter bare form. `_meta` key likewise `"qwen"`. (Survey of real agents: Zed/gemini-cli mostly use `_meta`-on-standard-methods + ACP's own `unstable_*`; bare custom `_` methods are rare — our `_qwen/*` are genuinely-new workspace/session ops with no standard equivalent, so a `_` method is the right tool.)
- **Why hand-rolled transport (not SDK-based)**: the TS SDK ships only `ndJsonStream` (stdio); RFD #721 HTTP is SDK Phase-3 (not implemented). The SDK `Connection` is single-duplex-stream; our transport is multi-stream (POSTs + connection-SSE + per-session-SSE) and needs outbound demux by sessionId — which our dispatcher already knows at routing time. A full SDK rewrite fights that model and wouldn't remove the bulk (bridge translation, SSE lifecycle, ownership, EventBus→JSON-RPC). **Pragmatic improvement (candidate follow-up): adopt the SDK's Zod schema validators + types for param validation while keeping the hand-rolled transport.** SDK clients using `extMethod('_qwen/…')` interoperate with our handlers (identical wire shape).

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,574 @@
# Agent Loop 减轮方案:从 Skill 设计入手
> 与 `rt-optimization-design.md` 同目录,互为补充:那份文档讨论**框架机制**层面减轮(D1 跳过末尾总结轮、D2 fast 路由、D4 prevalidate),这份文档主张**减轮的真正杠杆在 skill/tool 设计层**,并提出一条不依赖框架改造、不依赖 cache hit rate 数据的可实施路径。
---
## 0. 验收 Spec(开发前置 gate)
> 本节是开发的**前置 gate** — 列出哪些 spec 必须在动手前确认、哪些 spec 必须等数据驱动。把 spec 前置而非"做完再看指标",是为了避免:(a) 写完才发现指标不可测、(b) 阈值随结果飘移导致结论失真、(c) 没设止损线让方案陷入"看起来在做、其实没收益"。
>
> **本 spec 框架的适用边界**:本框架假设方向正确性可以在 P1.5 基线测量后判断。这个假设对"减轮"场景成立,因为它有清晰的可测信号(轮数、followup_rate、batch_size)。**超出此假设的场景**(例如未来用同一框架做"质量优化"等难以量化的方向),spec 前置可能反而阻碍快速学习;遇到时回退到 §0.5 治理流程重新评估,不机械套用本框架。
**spec 分四层 — 时机不同**:
| 层级 | 类型 | 锁定时机 |
| ---- | --------------------------------------- | -------------------------------- |
| §0.1 | 工程层 spec(数据管道、代码改动正确性) | **前置**、可立刻锁定 |
| §0.2 | 统计层 spec(项目"算成功"的指标) | **前置**、阈值待 P1.5 基线后锁定 |
| §0.3 | 止损线("如果发生就放弃"硬条件) | **前置**、不可移动 |
| §0.4 | per-skill spec(具体改哪个、目标多少) | **后置**、Layer 1 数据驱动 |
### 0.1 工程层 spec(必须前置 · 可立刻锁定)
数据管道与代码改动的正确性 spec — 不依赖任何业务判断或基线数据,开发前就该锁定:
- **qwen-logger 链路通畅**(§4.1.1b):skill_launch 事件能同时落到 OTLP 和 qwen-logger 两条管道
- **`prompt_id` 串联**:单个 user prompt 触发的 `skill_launch` + 后续 `tool_call` 能用同一个 `prompt_id` grep 出完整 trail
- **`batch_size` 非 undefined**(§4.3.2 方向 A):单工具 batch 显式设 `batch_size = 1` / `batch_position = 0`
- **SQL 可跑通**(§4.1.2):离线 SQL 在真实 telemetry backend 输出非空且能区分高/低 followup_rate skill
- **基线方差 < P50 × 20%**(P1.5):基线测量稳定(否则后续 A/B 对比不可信)—— 注:本条虽列在 §0.1 工程层,但**锁定依赖 P1.5 基线数据**,是 §0.1 中唯一的后置验证项;P1.5 未通过则 §0.2 阈值无法可信锁定
- **Skill 体积预算**(Layer 2 改造):内联 followup 后,skill 描述 token 数不超过改造前的 2×,且绝对值 ≤ 500 tokens(取较小值)。超过则按 §4.2 拆分 skill 而非合并。本条与 §7 第 2 条、§4.2 已有约束对齐,前置到 spec 层
- **`npm run preflight` 全过**:每个 PR 的硬门槛
### 0.2 统计层 spec(必须前置 · 阈值待 P1.5 后锁定)
项目算"统计意义上成功"的指标 — **方向**前置定下,**阈值**等基线测出来后锁定(避免凭空填数字):
| 指标 | 方向 | 锁定时机 | 当前占位阈值(待校准) |
| ---------------------------------- | -------- | --------- | ---------------------- |
| top-3 skill 加权 `followup_rate` | ↓ | P1.5 末 | ≥ 30% |
| 含 skill 的会话端到端 RT P50 | ↓ | P1.5 末 | ≥ 2s |
| `batch_size > 1` 的 tool_call 占比 | ↑ | P3 前 | ≥ 30% |
| 改造的 skill 触发场景 A/B 显著性 | p < 0.05 | P2 改完前 | n 待定 |
> **关键约束**:占位阈值不是承诺。P1.5 基线如果显示"top-5 skill 加权 followup_rate < 30%"(触发 §0.3 止损线 #1),项目终止;**不能为了让阈值"达到"而下调 spec**。
>
> **怎么测**:每个指标的测量方法、SQL 模板、A/B 设计见 §5.1-§5.2;统计显著性(p < 0.05)的样本量计算见 §5.1。
### 0.3 止损线(必须前置 · P-1 锁定后受限可调)
§5.3 已列。这些是"如果发生就放弃"的硬条件 — **任何情况下不能为了达成 §0.2 统计层 spec 而放宽止损线**。
- **结果指标**(3 条):top-5 加权 `followup_rate < 30%` / 改完 2 个 skill RT P50 ↓ < 1s / Layer 3 后 `batch_size P50` 仍 = 1
- **过程指标**(3 条):skill 命中率 ↓ ≥ 5pp / 内联 followup 失败率 ≥ 5% / 用户取消率 ↑ ≥ 2pp
详见 §5.3。
**可调性规则**(避免无数据支撑的纪律刚性):
| 阶段 | 可否调整 | 调整方向 |
| --------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |
| P-1 锁定时 | ✅ 任意调整(基于历史 telemetry 或共识) | 任意 |
| P-1 锁定后 → P1.5 末 | ❌ 不可调整 | — |
| P1.5 末(基线出来时) | ✅ 仅允许**放宽**一次 | 放宽(如 30% → 25%)需附数据证据 + 2 人评审;**不允许收紧**(避免事后追加止损) |
| P1.5 之后 | ❌ 不可调整 | — |
> 阈值占位值(30% / 1s / 5pp 等)当前**无历史数据支撑**,是 P-1 评审前的工程师直觉。如果 P-1 评审时能拿到最近 4 周历史 telemetry,应基于历史数据校准止损线;拿不到则保留占位值,P1.5 末执行上面的"放宽一次"规则。
### 0.4 per-skill spec(必须后置 · 数据驱动)
具体改哪个 skill、目标 `followup_rate` 改到多少 — **Layer 1 数据出来前不锁定**。
不锁定的理由:先验设计 vs 后验数据可能差很多。强行前置会重蹈 `rt-optimization-design.md` §7 D2 路线的覆辙 —— 前置假设"fast 模型快 2-3s"被 cache 实装这一后验事实推翻,导致方案净收益接近 0 甚至为负。
**产出位置**:per-skill spec 在 P1.5 末由数据驱动产出,每个 Layer 2 PR 的 description 里独立声明(不进 design 文档,避免文档每改一个 skill 就改)。
**per-skill spec 结构模板**(与 §4.2 的 PR description 必含项对齐 — 这两个清单是同一份,§4.2 是过程视角、本节是 spec 视角):
| 字段 | 内容 | 数据来源 |
| --------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| 1. 当前数据 | invocation_count、followup_rate、top followup tools | Layer 1 telemetry |
| 2. 目标 | followup_rate 从 X% 降到 Y% | 基于 §0.2 改善方向,绝对值 PR 内自行定 |
| 3. 改造范围 | 内联哪些 followup(read/grep/shell read-only),明确**不**内联什么(write 操作 / 跨 skill / 深度推理) | §4.2 改造模式表 |
| 4. 输出契约更新 | skill 描述里加的预声明("Returns: ...") | §3.2 改造示例 |
| 5. A/B 计划 | 改造后 2 周观察 followup_rate / RT P50 / 过程指标,对照 §5.1 验收线 | §5.1 |
| 6. 体积证明 | 改造前后 skill 描述 token 数(用 tiktoken 估算),不得超 §0.1"Skill 体积预算" | §0.1 第 6 条 |
### 0.5 spec 治理
- **修改 §0.1 / §0.3 spec** 需 design 文档更新 + PR 评审;§0.3 仅遵循 §0.3"可调性规则"在 P1.5 末窗口内放宽
- **修改 §0.2 阈值(P1.5 锁定后)** 需附以下至少一项数据证据:
- (a) P1.5 基线测量结果与已锁定阈值的偏差分析(含原始测量记录链接)
- (b) 同类项目的公开 benchmark 数据(含来源链接)
- (c) 内部 ≥ 2 人评审签字的偏差说明
PR 评审时若上述证据均无,评审者**有义务** block PR — 不接受"凭工程师直觉调整"
- **§0.4 per-skill spec** 在数据驱动产出后写入 PR description(按 §0.4 6 项模板),不进 design 文档
---
## 1. 背景与定位
### 1.1 问题
`rt-optimization-design.md` §1.2 给出的基线:3 轮 agent loop,13.4s 端到端,其中 LLM 调用占 78%。每一轮 ~3-4s。
```
Round 1 (3.8s, 28%): LLM 决策调 skill
Round 2 (3.0s, 22%): LLM 决策调 shell
Round 3 (3.8s, 28%): LLM 总结
```
`rt-optimization-design.md` §6/§7 经过两轮 review 后,D2/D4 已被否决,D1/D3 也降级为"等浮油完成后再评估"。但**整份原文档都聚焦在末尾的 Round 3(总结轮)或单轮内的微优化(D4)上,完全没有正面讨论 Round 1 → Round 2 这个"中间轮"为什么会出现、能不能消掉**。
事实是:Round 2 之所以存在,**绝大多数情况是因为 Round 1 调用的 skill 没有返回完整答案**,模型才追加 shell 查询补全。如果 skill 设计成"一次拿到完整结果",3 轮 → 2 轮,省掉的就是 Round 2 那 ~3s — 这是与 D1 完全不重叠的收益面。
### 1.2 与 rt-optimization-design 的关系
| 减轮方向 | 命中的轮次 | 杠杆位置 | 本文档定位 |
| -------------------- | ------------------------------- | ---------------------------- | ---------------------------- |
| D1 `skipLlmRound` | 末尾总结轮 | 框架机制 + per-tool opt-in | 兜底,**放在 Layer 2 之后** |
| D2 fast 路由 | 单轮延迟 | 框架机制 | 已 defer,**不在本文档范围** |
| D3 Summarizing 状态 | 末尾总结轮(感知层) | UI 状态机 | 可选,与本方案正交 |
| D4 prevalidate | 单轮延迟 | 框架机制 | 已 defer,**不在本文档范围** |
| **本方案 Layer 1-3** | **中间决策轮 + 并发未触发的轮** | **skill 设计 + prompt 工程** | **新增方向** |
### 1.3 核心论点
减轮的真正杠杆在 skill/tool 设计层,不在 agent 框架。三个理由:
1. **§1.2 基线本身就暴露问题在 skill** — Round 1 → Round 2 的跳跃是 skill 返回不全才发生的,框架做对了,skill 做错了
2. **框架级减轮最终也要 per-tool opt-in** — D1 的 `skipLlmRound` 必须每个工具显式标记,绕一圈回到 skill 工程,还多一套不变量修复 + 决策门控成本
3. **ROI 局部可测、灰度容易** — 改一个 skill 就少一轮 × 该 skill 触发次数,不依赖 cache hit rate 数据,不依赖跨系统改动
> **实施前必须先走 §0 验收 Spec 前置评审(P-1 阶段,0.5d)** — §0.1 工程层 spec 和 §0.3 止损线在动手前必须锁定;§0.2 统计层阈值的方向也要前置确认(具体数值等 P1.5 基线后再锁)。跳过 §0 进入 P0 实施 = 默认走"做完才看指标"的反模式,文档不背书这种做法。
---
## 2. 设计原则
1. **不改 agent 框架** — 不动 `useGeminiStream` / `coreToolScheduler` / `geminiChat` 核心路径
2. **数据驱动选优先级** — 先建 telemetry,让数据告诉你改哪个 skill,不靠拍脑袋
3. **per-skill 可测可灰度** — 每个 skill 改造独立 A/B,失败局部回退
4. **复利优先** — 收益 = 单次减轮收益 × 触发频率,高频 skill 优先
5. **不绑定 D1** — 本方案的成功不依赖 D1 是否落地
---
## 3. 三层方案
### 3.1 Layer 1:减轮 Telemetry(找金矿)
**目标**:让数据告诉你哪些 skill 最值得改 — 即"用了这个 skill 之后,模型有多大概率追加一次工具调用"。
**核心字段**(per-turn、per-skill-invocation):
```typescript
interface SkillFollowupRecord {
skill_name: string;
prompt_id: string; // 关联同一 user prompt 内的所有 events
turn_index: number; // 该 skill 在 loop 里是第几轮
followup_tool_names: string[]; // 同一 prompt_id 下,skill 之后还调了哪些工具
followup_count: number; // followup_tool_names.length
followup_kinds: Kind[]; // Read/Edit/Execute/...
next_turn_is_terminal: boolean; // skill 之后下一轮就出文字(不再调工具)
user_followup_within_30s: boolean; // 用户在结果显示后 30s 内追加新 prompt(质量回归信号)
}
```
**关键指标**:
- `skill_followup_rate = sum(followup_count > 0) / total_invocations`
- `terminal_after_skill_rate = sum(next_turn_is_terminal) / total_invocations`
- 按 `(skill_name, top followup tool)` 聚合 — 看哪些 skill 之后最常追加哪个工具
**金矿判定**:
```
(invocation_count_weekly × skill_followup_rate) ≥ threshold
↓
该 skill 是减轮金矿,优先 Layer 2 改造
```
阈值建议:top-3 按上式排序的 skill,先改前 2 个。
### 3.2 Layer 2:Skill 输出完整化
**目标**:让被识别为金矿的 skill 一次返回完整答案,消除 Round 1 → Round 2 的跳跃。
**改造模式(按 followup 类型分类)**:
| Followup 模式 | 典型场景 | 改造方向 |
| --------------------------- | -------------------------- | ---------------------------------- |
| skill → `read_file` | skill 给路径,模型再读 | skill 内部直接读,返回内容 |
| skill → `grep/glob` | skill 给目录,模型再搜 | skill 内部搜好,返回匹配 |
| skill → `shell` (read-only) | skill 给命令,模型再执行 | skill 内部跑命令,返回输出 |
| skill → `shell` (write) | skill 给方案,模型再执行写 | **保留**(写操作要确认,不应合并) |
| skill → another skill | 链式调用 | **不合并**(保持组合性) |
**改造检查清单(per-skill PR 模板)**:
1. 在 skill 描述里**预声明输出契约**:明确写 "Returns: full file content / matched lines / command output",让模型知道不必追加查询
2. 在 skill 内部**完成所有 read-only followup**:把 telemetry 显示 >50% 追加率的 read/search 操作内联进 skill
3. **不内联 write 操作**:写操作需要用户确认,必须单独成轮
4. **不内联深度推理 followup**:如果 followup 是"基于此再分析",那是模型的事,不是 skill 的事
5. **附 A/B telemetry**:改造后 2 周对比 `followup_rate` 是否下降到 <20%
**典型改造示例(示意)**:
改造前:
```
skill "list-workspaces" returns: ["ws_a", "ws_b"]
→ Round 2: model calls shell to get details for each workspace
```
改造后:
```
skill "list-workspaces" returns:
- ws_a (owner: foo, last_active: 2026-05-20, status: active)
- ws_b (owner: bar, last_active: 2026-05-01, status: archived)
description updated: "Returns workspaces with owner, last_active, status"
→ Round 2 disappears for ~80% of queries
```
### 3.3 Layer 3:Prompt 教育模型并发
**目标**:对于独立工具(多文件读、多目录搜),让模型在同一轮里并发发起 tool_calls,把 N 轮压成 1 轮。
**前提**:基础设施已就绪 — `tools/tools.ts:818` 的 `CONCURRENCY_SAFE_KINDS` + `coreToolScheduler` 的 `partitionToolCalls` 已经能并发执行同 batch 内的 read/search/fetch 工具。**差的只是模型主动发起并发 tool_calls 的意愿**,qwen-coder 默认偏串行。
**改动位置**:`packages/core/src/core/prompts.ts`(已审计过,加在 `# Final Reminder` 段 L396 附近不会破坏 cache 命中以外的事 — 仅一次性预热成本)。
**指导文本(示意,需 A/B 调优)**:
```
When you need to call multiple independent read-only tools (read_file,
grep, glob, web_fetch), emit them in a SINGLE tool_calls batch — do NOT
call them sequentially across rounds. They will execute concurrently.
Examples:
- Reading 3 files for comparison: emit 3 read_file calls in one batch
- Searching for 2 patterns: emit 2 grep calls in one batch
Do NOT batch when the second call depends on the first call's result.
```
**生效衡量**:新增 telemetry 字段 `batch_size`(同 turn 内 tool_calls 数量)— 改 prompt 前后对比分布。
#### 3.3.1 扩展 `CONCURRENCY_SAFE_KINDS`(Layer 3 子项)
prompt 教育模型并发只是供给侧(模型愿意一次发多个 tool_calls),但 `tools/tools.ts:818` 的 `CONCURRENCY_SAFE_KINDS = { Read, Search, Fetch }` 决定**实际能并发执行的工具范围**:`partitionToolCalls`(`coreToolScheduler.ts:775`)会把"连续的安全工具"打包成 concurrent batch,其余各自串行。
如果模型按指导一次发了 3 个 tool_calls 但其中 1 个属于 `Kind.Execute` 且不在安全集合,整个 batch 就会被拆开串行执行 — Layer 3 prompt 改动的收益会被运行时调度抵消。
**扩展候选**(按风险递增):
- `Kind.Think`(含 save_memory / todo_write)—— **不要加**,有隐式写入
- 只读 shell(`isShellCommandReadOnly()` 返回 true 的 Execute)—— `partitionToolCalls` 已有特判(`coreToolScheduler.ts` `partitionToolCalls` 注释里提到 "Execute (shell) is safe only when isShellCommandReadOnly() returns true"),现状已覆盖,无需改 `CONCURRENCY_SAFE_KINDS`
- MCP 工具按 `Kind` 分类 —— 各 MCP server 行为差异大,需要在工具注册时显式 opt-in 才安全
**结论**:当前集合已经合理,**Layer 3 不依赖扩展 `CONCURRENCY_SAFE_KINDS`**。本节存在的意义是:在收完 `batch_size` telemetry 数据后,**如果发现"并发 batch P50 < 期望值",先检查是不是被 `partitionToolCalls` 切断而非模型不并发**。这是 Layer 3 A/B 失败时的一个诊断路径,不是必做项。
> 信用:codex review 提出"扩展 `CONCURRENCY_SAFE_KINDS` 是被忽略的杠杆"。核对后判断为:现状已有 `isShellCommandReadOnly` 特判覆盖最大头,扩展集合本身收益小、风险大;保留作为诊断路径。
---
## 4. 详细实施
### 4.1 Layer 1:Telemetry 扩展(1-2d)
#### 4.1.1 补 `prompt_id` 到 `SkillLaunchEvent`
**位置**:`packages/core/src/telemetry/types.ts:896`
当前 `SkillLaunchEvent` 仅含 `skill_name` + `success`,**无 `prompt_id`** — 无法跟同一 turn 内的其他 `ToolCallEvent` 关联。
```typescript
// types.ts:896
export class SkillLaunchEvent implements BaseTelemetryEvent {
'event.name': 'skill_launch';
'event.timestamp': string;
skill_name: string;
success: boolean;
prompt_id: string; // 新增
turn_index?: number; // 新增
constructor(
skill_name: string,
success: boolean,
prompt_id: string, // 新增
turn_index?: number, // 新增
) { ... }
}
```
**调用方更新**:`packages/core/src/tools/skill.ts` 的 4 个 `logSkillLaunch` 调用点(L386, L399, L426, L482),传入 `this.params` 拿不到 `prompt_id` — `BaseToolInvocation` 仅持有 `params`,没有 `request.prompt_id` 字段。**实际实现**用鸭子类型方式注入:`SkillToolInvocation` 暴露 `setPromptId(id)` setter + 私有 `promptId` 字段,`CoreToolScheduler.buildInvocation`(`coreToolScheduler.ts:1253`)在 build 后 duck-type 调 `setPromptId(request.prompt_id)`,对齐既有 `setCallId` hook 的 pattern;invocation 在 `execute()` 内的 4 个 `logSkillLaunch` 都传 `this.promptId`。**早期版本的本节描述("BaseToolInvocation 已有 request.prompt_id")是错的**,已在 PR #4565 review 后更正。
#### 4.1.1b qwen-logger 链路修复(前置)
补 `prompt_id` 之前要先解决一个 **既存的链路断点**:`packages/core/src/telemetry/qwen-logger/qwen-logger.ts:908` 定义了 `logSkillLaunchEvent(event)` 方法,但**全仓库无任何调用方** —— `loggers.ts:958` 的 `logSkillLaunch` 直接走 `logs.getLogger(SERVICE_NAME).emit()` 这条 OTLP 路径,绕过了 qwen-logger。
后果:
- OTLP 路径上的 skill_launch 事件能到 OTLP collector(已工作),但 qwen-logger 那条专用上报链路目前是死的
- 如果 telemetry backend 是从 qwen-logger 消费(而非 OTLP),skill_launch 事件**完全不上报**
- §4.1.2 离线 SQL 派生 `SkillFollowupRecord` 依赖 skill_launch 事件落库 —— **必须先验证现在 skill_launch 在 backend 是否可见**
修复方向二选一:
- **A**(推荐)在 `loggers.ts:958` 的 `logSkillLaunch` 里加一行 `QwenLogger.getInstance(config)?.logSkillLaunchEvent(event)`,对齐 `logToolCall` 的 `loggers.ts:230` 写法
- **B** 确认 backend 只从 OTLP 消费,把 qwen-logger 里的 `logSkillLaunchEvent` 标 `@deprecated` 或删除
**为什么只补 QwenLogger 一条路径,不对齐 `logToolCall` 的 4 条全路径**:
`logToolCall`(`loggers.ts:220-247`)实际有 4 条出口:
1. `uiTelemetryService.addEvent(...)` — UI 展示
2. `config.getChatRecordingService()?.recordUiTelemetryEvent(...)` — 聊天历史
3. `QwenLogger.getInstance(config)?.logToolCallEvent(...)` — qwen-logger 后端遥测
4. OTLP `logger.emit(...)` — OpenTelemetry
skill_launch 是**纯后端遥测事件**,不需要在 UI 上展示(用户已经看到 SkillTool 的 returnDisplay)、也不需要进 ChatRecording 的 turn 历史(skill 内部的工具调用已经各自被 recordUiTelemetryEvent 记录)。因此只补第 3 条(QwenLogger),保留第 4 条(OTLP),跳过 1/2 是有意的,不是遗漏。
**字段透传细节**:`loggers.ts:961-966` 用 `{ ...event }` spread 自动透传新字段(`prompt_id` 加进 `SkillLaunchEvent` 后这条路自动生效),但 `qwen-logger.ts:908` 的 `logSkillLaunchEvent` 内部如果显式解构 `event.skill_name` / `event.success`,新字段不会自动纳入,需手动同步。
工作量:A 路径约 0.5d(含 backend 端确认);B 路径约 0.2d(删代码 + 文档说明)。
#### 4.1.2 派生 `SkillFollowupRecord`(离线聚合)
不需要新事件类型 — `ToolCallEvent` 和 `SkillLaunchEvent` 都已带 `prompt_id`,离线 SQL 即可派生:
```sql
-- 伪 SQL,按实际 telemetry backend 调整
WITH skill_events AS (
SELECT prompt_id, skill_name, timestamp FROM events
WHERE event_name = 'skill_launch' AND success = true
),
tool_events AS (
SELECT prompt_id, function_name, timestamp FROM events
WHERE event_name = 'tool_call'
),
followups AS (
SELECT s.skill_name, s.prompt_id,
COUNT(t.function_name) AS followup_count,
ARRAY_AGG(t.function_name) AS followup_tool_names
FROM skill_events s
LEFT JOIN tool_events t
ON s.prompt_id = t.prompt_id AND t.timestamp > s.timestamp
GROUP BY s.skill_name, s.prompt_id
)
SELECT skill_name,
COUNT(*) AS invocations,
AVG(followup_count) AS avg_followup,
SUM(CASE WHEN followup_count > 0 THEN 1 ELSE 0 END)::FLOAT / COUNT(*) AS followup_rate
FROM followups
GROUP BY skill_name
ORDER BY invocations * followup_rate DESC;
```
#### 4.1.3 跑 telemetry 1 周收数据
- 不变更 user-facing 行为
- 不需要任何配置开关 — telemetry 已有 opt-in 框架(`telemetry.target` 设置项)
- 1 周后产出 skill ranking 报告
### 4.2 Layer 2:Skill 改造(per-skill 0.5-1d)
按 Layer 1 数据从 top-down 改造。每个 skill 一个独立 PR,PR description 必须包含:
1. **数据**:当前 invocation_count、followup_rate、top followup tools
2. **改造范围**:内联了哪些 followup(明确不内联什么)
3. **输出契约更新**:skill 描述里加了什么预声明
4. **A/B 计划**:改造后 2 周再观察 followup_rate
**注意事项**:
- Skill 内联 read 操作不要重复 read_file 的所有边界情况处理(编码、二进制检测等)— 调用 `read_file` 工具本身,不要重写
- Skill 内联 grep/glob 同理
- Skill 内联 shell 命令需走 `executeToolCall` 标准路径(保留 telemetry)
- **不要让 skill 体积爆炸**:内联 followup 后 skill 描述 > 500 tokens 时,拆分 skill 而不是合并
### 4.3 Layer 3:Prompt 教育(0.5d 改动 + 实测调优)
#### 4.3.1 加并发指导
**位置**:`packages/core/src/core/prompts.ts` `# Final Reminder` 段(L396)
加上节 3.3 的指导文本。具体措辞需 A/B —— 先用最朴素版本,根据并发率提升程度再细化。
#### 4.3.2 加 `batch_size` telemetry
**位置**:`packages/core/src/telemetry/types.ts` 的 `ToolCallEvent` 或新增轻量级 `ToolBatchEvent`
```typescript
// 选项 A:在 ToolCallEvent 上加字段(侵入小)
export class ToolCallEvent {
...
batch_size?: number; // 同一 batch 内 tool_call 数量
batch_position?: number; // 在 batch 内的位置 (0-indexed)
}
// 选项 B:新增 ToolBatchEvent(语义更清晰,需走完整新事件类型流程)
```
**推荐选项 A** — 改动小、查询时聚合方便。
**状态传递路径**(关键 — 这一步成本被早期版本低估):
`coreToolScheduler.ts:2456` 的 `partitionToolCalls(callsToExecute)` 返回 `batches`,**但 batch 信息在调度路径上立刻丢失**:
```
executeToolCalls
└─ batches = partitionToolCalls(...) // 知道 batch.calls.length
└─ for batch of batches:
└─ this.runConcurrently(batch.calls, ...) // 知道 batch.calls.length
└─ executeSingleToolCall(call, ...) // ❌ 已不知道 batch
└─ ...
└─ finalizeToolCalls
└─ logToolCall(config, new ToolCallEvent(call)) // ❌ 无 batch context
```
`ToolCallEvent` 的构造器(`types.ts:189`)只接收单个 `CompletedToolCall`,无 batch 字段。
修复方向:
- **方向 A**(推荐):在 `ScheduledToolCall` 上加 `batchSize?: number` + `batchPosition?: number`。两条分支分别填充:
- 并发分支(`coreToolScheduler.ts:2459-2460`,`batch.calls.length > 1`):`runConcurrently(batch.calls, ...)` 进入循环前给每个 `call` 写 `batchSize = batch.calls.length`、`batchPosition = i`
- 串行分支(`L2462-2464` 的 `for (const call of batch.calls)`):单工具 batch 显式设 `batchSize = 1`、`batchPosition = 0`(**不要默认 undefined**,否则下游 telemetry 聚合时会把并发未生效的轮次误判为缺失数据)
`new ToolCallEvent(call)` 在构造器里从 `call` 读这两个字段
- **方向 B**:改 `ToolCallEvent` 构造器签名 `new ToolCallEvent(call, batchInfo?)`,所有调用方同步改(4 个 logToolCall 调用点 + 测试)。改动面比 A 大
工作量:方向 A 约 0.5d 含单测;方向 B 约 1d(调用方多)。
**同步衡量"模型并发意愿"** — Layer 3 改 prompts.ts 前后,对比 `batch_size > 1 的 tool_call 占比` 分布。这是 Layer 3 是否生效的关键指标,没这个数据 Layer 3 A/B 无法收尾。
#### 4.3.3 cache 影响评估
`prompts.ts` 改动会让 DashScope ephemeral cache 一次性失效(首次请求 cache miss,之后恢复)。这是已知一次性成本,参见 `rt-optimization-design.md` §7.8 的 prompt 稳态审计。
---
## 5. 验收与度量
> **本节是 §0 验收 Spec 的"方法论"配套** — §0 声明"算成功的指标 + 阈值前置/后置时机",§5 说明"怎么测、SQL 怎么写、A/B 怎么设计"。本节阈值是 §0.2 的当前占位,最终值在 P1.5 基线测量后锁定。
### 5.1 per-skill A/B 指标(改造后 2 周)
| 指标 | 验收线 | 备注 |
| ----------------------------------------- | ------------------------ | -------------------------- |
| 该 skill 的 `followup_rate` | < 20%(改造前若为 70%+) | 主指标 |
| 该 skill 触发场景的端到端 RT P50 | 下降 ≥ 2s | 来自少一轮 LLM 调用 |
| 该 skill 的 `user_followup_within_30s` 率 | 不上升 | 用户没追问 = 答案完整 |
| 该 skill 的 `success` 率 | 不下降 | 内联 followup 没引入新失败 |
### 5.2 整体 RT 指标
| 指标 | 基线 | Layer 2 改完 top-3 skill 后目标 |
| ---------------------------------- | ------------------------------------- | -------------------------------- |
| 端到端 RT P50(含 skill 的会话) | 13.4s(单次采样)/ 待补 ≥3 类场景基线 | 下降 2-3s |
| Tool batch P50 size(Layer 3) | 待测 | ≥ 1.3(>30% 调用涉及并发 batch) |
| Skill 总 followup_rate(加权平均) | 待测 | 下降 ≥ 30% |
### 5.3 失败信号 — 什么时候放弃这个方向
**结果指标止损线**:
- Layer 1 数据出来后,**top-5 skill 的加权 followup_rate < 30%** → 减轮空间小,不值得继续 Layer 2
- Layer 2 改完 2 个 skill 后,**端到端 RT P50 下降 < 1s** → 改造方向错(可能 followup 是写操作不该合并),停下复盘
- Layer 3 prompt 改动 2 周后 **batch_size P50 仍 = 1** → 模型不接受并发指导,放弃 Layer 3,只保留 Layer 1+2
**过程指标止损线(前置预警,避免方案"看起来在做、其实没收益")**:
- **Skill 命中率(intended skill vs selected skill)下降 ≥ 5pp** → skill 描述改坏让模型选错 skill。典型场景:改造前用户问 X 总是命中 skill_a,改造后偶尔被路由到 skill_b 但没产生 error(模型用错 skill 但勉强凑出答案),结果指标看起来正常但 followup_rate 反而上升。**衡量方法**:在 telemetry 加 `skill_invocation_pattern` —— 按 user prompt 前 N 个关键词聚类,看每个 cluster 主要触发哪个 skill;改造前后对比顶 1 偏移
- **Skill 内联 followup 失败率 ≥ 5%** → skill 改造引入了原本不存在的失败模式(如内联 `read_file` 处理大文件爆内存)。衡量:`SkillLaunchEvent.success` 改造前后对比
- **Per-skill 用户取消率(Ctrl+C)上升 ≥ 2pp** → skill 输出变慢或变长导致用户失去耐心。衡量:`ToolCallEvent.status === 'cancelled'` 占比
---
## 6. 与 D1/D3 的衔接
### 6.1 与 D1 的关系
Layer 2 改完 top skill 后,**剩余的 followup-heavy skill 才是 D1 `skipLlmRound` 的真正适用场景** — 那些 skill 输出已经完整(不需要 Round 2),且确实是终态查询(Round 3 总结也是浪费)。
执行次序:
1. Layer 1 telemetry 上线 → 1 周数据
2. Layer 2 改造 top 2-3 skill → A/B 2 周
3. Layer 3 prompt 并发 → 实测 1 周
4. **此时**再评估 D1:剩余高频 skill 里有多少是"输出完整 + 终态查询"形态 → 是否值得 2-3d 框架改造
### 6.2 与 D3 的关系
D3(`StreamingState.Summarizing`)是感知层优化,与本方案完全正交。Layer 1-3 减少的是**真实轮数**,D3 减少的是**用户感知等待**。如果 Layer 2 已经把 RT 降到用户可接受的范围,D3 价值下降;反之 D3 可以叠加。
---
## 7. 限制与已知风险
1. **覆盖率受改造范围限制** — 改 10 个 skill 就只覆盖那 10 个的场景。但收益是确定可测有复利的
2. **Skill 内联 followup 可能让单 skill 变重** — 描述膨胀、加载慢、复用度下降。Layer 2 检查清单第 5 条防御
3. **Layer 3 模型可能不听并发指导** — qwen-coder 训练数据偏串行;A/B 数据可能显示 prompt 改动无效,作为已知失败模式
4. **Telemetry 隐私边界** — `SkillFollowupRecord` 不应记录工具参数(已默认从 `ToolCallEvent.function_args` 拿,但要审计 skill_name 是否泄露用户意图)
5. **不适用于子 agent / cron / notification** — 这些路径不走 skill 系统,本方案不覆盖
6. **基线数据单薄** — 沿用 `rt-optimization-design.md` §1.2 的单次采样,Layer 2 落地前需补 ≥3 类场景基线
7. **`logSkillLaunch` 字段扩展会破坏既有 telemetry consumer** — 4 个调用点 + 下游 logger 都要同步改
8. **`qwen-logger.ts:908` `logSkillLaunchEvent` 当前是死代码** — 仓库内无任何调用方,§4.1.1b 已列前置修复
### 7.1 与已有框架机制的边界(不在本方案范围)
仓库已有几条与减轮间接相关的框架机制,**本方案不重新发明,也不替代**:
| 已有机制 | 位置 | 与本方案的关系 |
| ---------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `partitionToolCalls` + `runConcurrently`(并发执行) | `coreToolScheduler.ts:775, 2473` | Layer 3 直接复用;本方案不动它 |
| `CONCURRENCY_SAFE_KINDS`(决定哪些工具可并发) | `tools/tools.ts:818` | §3.3.1 已论证现状合理,不扩展 |
| `FileReadCache`(避免重复读同一文件) | `services/fileReadCache.ts` | 间接影响"模型重复读文件"轮次,已生效;本方案不依赖也不增强 |
| `chatCompressionService`(历史压缩) | `services/chatCompressionService.ts` | 与轮次正交(影响单轮成本而非轮数);与 `rt-optimization-design.md` §3.2 fast 路由的 `wouldTriggerCompression` gate 是同一组件 |
列出这些是为了避免"本方案被理解为忽略了已有机制"。
---
## 8. 实施时间线
> **前提:本时间线从 P-1 开始,不能跳过**。P-1 是 §0 验收 Spec 的前置评审,0.5d 工作量但**强制性** — 不通过则不进入 P0。这一约束是为了避免"先写代码再补 spec"的反模式:spec 后置等于把"算成功"的判断推迟到结果出来后,容易出现"为了让指标好看而调整 spec"的偏差(参见 `rt-optimization-design.md` §7 D2 路线的覆辙)。
| Phase | 内容 | 投入 | 产出 | spec 锁定动作 |
| -------- | ---------------------------------------------------------------------- | --------------------- | ------------------------------ | --------------------------------------- |
| **P-1** | spec 前置评审 | 0.5d | §0.1 / §0.3 锁定 | **锁定 §0.1 工程层 spec + §0.3 止损线** |
| **P0** | qwen-logger 链路修复(§4.1.1b 前置) | 0.5d | skill_launch 事件可见性确认 | 验证 §0.1 第 1 条 |
| **P1** | Layer 1 telemetry:补 `prompt_id` 字段 + 离线 SQL | 1-2d | skill ranking 报告 | 验证 §0.1 第 2/3/4 条 |
| **P1.5** | 1 周数据收集 + 基线测量(≥3 类场景 × ≥10 次) | 1w | 决定改哪 2-3 个 skill | **锁定 §0.2 阈值 + 验证 §0.1 第 5 条** |
| **P2** | Layer 2 改造 top-1 skill(PR + A/B) | 0.5-1d 改造 + 2w 观察 | followup_rate ↓、RT P50 ↓ 验证 | **PR 内声明 §0.4 per-skill spec** |
| **P3** | Layer 3 prompt 并发指导 + `batch_size` telemetry(含 §4.3.2 状态传递) | 1-1.5d 改动 + 1w 实测 | batch_size 分布 | 验证 §0.2 第 3 条 |
| **P4** | Layer 2 继续改 top-2 / top-3 skill(并行 P3) | 0.5-1d × N | 累计 RT P50 ↓ | 每 PR 内声明 §0.4 |
| **P5** | 评估 D1 是否还有价值 | 决策会 | 路线图更新 | — |
**关键决策点(对照 §0.3 止损线)**:
- **P-1 末**:§0.1 / §0.3 任一项无法达成共识 → 不进入 P0
- **P1.5 末**:触发 §0.3 结果指标 #1(top-5 加权 followup_rate < 30%)→ 终止方向;否则锁定 §0.2 阈值
- **P2 末**:触发 §0.3 结果指标 #2(top-1 改造后 RT P50 ↓ < 1s)或任一过程指标 → 停下复盘
- **P3 末**:触发 §0.3 结果指标 #3(batch_size P50 仍 = 1)→ 放弃 Layer 3
- **P5**:根据剩余 skill 形态决定 D1 ROI
---
## 9. 关键代码位置
| 文件 | 关键符号 | 位置 |
| -------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------- |
| `packages/core/src/telemetry/types.ts` | `ToolCallEvent`(含 `prompt_id` / `duration_ms`) | L170 |
| `packages/core/src/telemetry/types.ts` | `SkillLaunchEvent`(需补 `prompt_id`) | L896 |
| `packages/core/src/telemetry/loggers.ts` | `logToolCall` | L220 |
| `packages/core/src/telemetry/loggers.ts` | `logSkillLaunch`(走 OTLP;缺 qwen-logger 转发) | L958 |
| `packages/core/src/telemetry/loggers.ts` | `logToolCall`(双路径:OTLP + qwen-logger,作为修复样板) | L220, L230 |
| `packages/core/src/telemetry/qwen-logger/qwen-logger.ts` | `logSkillLaunchEvent`(**当前死代码**,§4.1.1b 前置修复目标) | L908 |
| `packages/core/src/core/coreToolScheduler.ts` | `partitionToolCalls` | L775 |
| `packages/core/src/core/coreToolScheduler.ts` | `runConcurrently` / batch 调度 | L2456, L2473 |
| `packages/core/src/core/coreToolScheduler.ts` | `logToolCall` 调用点(batch_size 状态传递终点) | L3163 |
| `packages/core/src/services/fileReadCache.ts` | `FileReadCache`(已有,影响重复读取轮次) | L135 |
| `packages/core/src/tools/skill.ts` | `SkillTool` + 4 个 `logSkillLaunch` 调用点 | L386, L399, L426, L482 |
| `packages/core/src/skills/skill-manager.ts` | `SkillManager`(skill 注册/加载) | 全文件 |
| `packages/core/src/skills/skill-load.ts` | skill 描述加载(输出契约改动入口) | 全文件 |
| `packages/core/src/tools/tools.ts` | `Kind` + `CONCURRENCY_SAFE_KINDS` | L793, L818 |
| `packages/core/src/core/coreToolScheduler.ts` | `partitionToolCalls` + `runConcurrently`(已有并发基础设施) | 见 rt-optimization-design.md §5.7 |
| `packages/core/src/core/prompts.ts` | `# Final Reminder` 段(Layer 3 加并发指导处) | L396 |
| `.qwen/skills/` | 各 skill 定义目录(Layer 2 改造对象) | 目录 |

File diff suppressed because it is too large Load Diff

View File

@ -21,42 +21,16 @@ returns:
## Triggers
| Trigger | Conditions | Implementation |
| --------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manual** | User runs `/recap` | `recapCommand.ts` calls the same underlying service |
| **Auto** | Terminal blurred (DECSET 1004 focus protocol) for ≥ 5 min + focus returns + stream is `Idle` | `useAwaySummary.ts` — 5min blur timer + `useFocus` event listener |
| **Daemon HTTP** | Remote client calls `POST /session/:id/recap` | `server.ts` route → `bridge.generateSessionRecap` (ext-method roundtrip) → `acpAgent.ts` calls `generateSessionRecap(session.getConfig(), signal)` |
| Trigger | Conditions | Implementation |
| ---------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Manual** | User runs `/recap` | `recapCommand.ts` calls the same underlying service |
| **Auto** | Terminal blurred (DECSET 1004 focus protocol) for ≥ 5 min + focus returns + stream is `Idle` | `useAwaySummary.ts` — 5min blur timer + `useFocus` event listener |
All three paths funnel into the same `generateSessionRecap()` function
in `core/services/sessionRecap.ts` to guarantee identical behavior. The
auto-trigger is gated by `general.showSessionRecap` (default: off —
explicit opt-in, so ambient LLM calls are never silently added to a
user's bill); the manual command and daemon HTTP route ignore that
setting (the caller is making an explicit request).
### Daemon access path
The daemon route is non-strict-gated (mirrors `/session/:id/prompt`'s
posture — recap costs tokens but mutates no state). Capability tag
`session_recap` advertises the route on `/capabilities.features`. SDK
helpers: `DaemonClient.recapSession(sessionId, opts)` and
`DaemonSessionClient.recap(opts)`. See
`docs/developers/qwen-serve-protocol.md` § `POST /session/:id/recap`
for the wire contract and error envelope.
Cancellation is **absent in v1**. The route does not listen for HTTP
client disconnect, no `AbortSignal` is threaded into
`bridge.generateSessionRecap`, and the ACP child handler passes a
never-aborting `AbortController().signal` to the core helper (no
cross-process abort plumbing yet). The only ceilings are the bridge's
60s `SESSION_RECAP_TIMEOUT_MS` backstop and the transport-closed race
against ACP channel death. Wiring an HTTP-side AbortController in
isolation would be cosmetic — the child-side LLM call would still run
to completion, so e2e cancel is not achievable without the cross-
process abort piece. This is acceptable for v1 because recap is short
(single-attempt side-query, `maxOutputTokens: 300`, ~1–5s typical).
A future request-id-based cancel ext-method can plumb full end-to-end
cancellation if/when the bandwidth cost justifies it.
Both paths funnel into a single function — `generateSessionRecap()` — to
guarantee identical behavior. The auto-trigger is gated by
`general.showSessionRecap` (default: off — explicit opt-in, so ambient
LLM calls are never silently added to a user's bill); the manual
command ignores that setting.
## Architecture

View File

@ -0,0 +1,878 @@
# Telemetry: Outbound Trace Context & Session ID Header Propagation
> 配套 issue: [#4384](https://github.com/QwenLM/qwen-code/issues/4384)
> 父 issue: [#3731](https://github.com/QwenLM/qwen-code/issues/3731) (P3 deeper observability)
> 前置 PR: #4367 (resource attributes — merged 2026-05-21, commit `64401e1`)
> 基于 2026-05-21 对 qwen-code main 分支 + 直接验证的 claude-code 源码
## 修订历史
| 修订 | 日期 | 触发 | 摘要 |
| ---- | ---------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| R1 | 2026-05-21 | 初稿 | 全广播:所有出站 LLM 请求都带 `X-Qwen-Code-Session-Id` + `traceparent` |
| R2 | 2026-05-22 | wenshao R2/R3 review | 边界安全:URL normalize、port matching、quote 对齐、staticCorrelationHeaders try/catch、host:port fallback strip |
| R3 | 2026-05-23 | LaZzyMan REQUEST_CHANGES | **重大语义改动**:`X-Qwen-Code-Session-Id` 默认作用域收窄到 first-party(Alibaba/DashScope)host 白名单。详见 §11 |
| R4 | 2026-05-25 | LaZzyMan round-8 follow-up (scope conflation) | **PR scope 大幅收窄**:本 PR 仅保留 client HTTP span + OTLP loop guard;`traceparent` 默认 off(NoopTextMapPropagator);新增 `outboundCorrelation.*` 顶级 namespace 放安全相关 toggle;R3 落地的整套 `X-Qwen-Code-Session-Id` 机器**移除本 PR**,搬到独立 follow-up PR。详见 §12 |
**特别提示**:阅读 §3.1(目标)/ §3.2(非目标)/ §4.3(Part B 设计)/ §4.4(配置 schema 影响)/ §5(文件改动清单)/ §9(与 claude-code 对比)/ §10(未来工作)/ §11(R3 host-allowlist scoping)时,请同时参考 §12 —— **R4 修订让 R1-R3 关于"本 PR 同时落地 traceparent + session id header"的论断不再成立**:本 PR 现仅为 telemetry observability + 独立的 outbound trace-context toggle,所有 outbound correlation header 工作(包括 R3 的 host allowlist)整体搬到独立 follow-up PR。R3 工作代码本身没浪费,挪到 follow-up PR 即可复用。
## 1. 背景
#4367 解决了**emitted telemetry 上的 attribute 与 cardinality**(操作员能给 span/log/metric 打 `user.id`/`tenant.id` 这类标签)。但有一类东西它没碰:**outbound LLM 请求的 HTTP header**。今天 qwen-code 发往 DashScope / OpenAI / Gemini / Anthropic 的请求**完全不带任何 cross-process correlation header**——既没有 W3C `traceparent`,也没有 session id。
后果:
1. trace context 在 qwen-code 进程边界断开。若模型服务(如 ARMS Tracing 接入的 DashScope)本身有 OTel instrumentation,它产生的 span 与 qwen-code 的 trace 彼此独立,端到端 trace tree 不存在。
2. 没有 session id 在 wire 上。后端要把 qwen-code 的 metric/log 与服务端日志关联,需要离线匹配 trace id 或时间戳,远不如直接读 header 简单。
3. 本地 trace 缺一层 client-side HTTP span。今天只能看 `api.generateContent` 的总耗时,看不到网络 TTFB / 响应体大小 / 重试次数。
## 2. 现状
### 2.1 仅启用了 `HttpInstrumentation`
`packages/core/src/telemetry/sdk.ts:330`:
```ts
instrumentations: [new HttpInstrumentation()],
```
`HttpInstrumentation` 只 hook Node 内建的 `http`/`https` 模块,**不**覆盖 `globalThis.fetch` / undici 路径。
### 2.2 两套 LLM SDK 都走 fetch / undici
| SDK | HTTP 实现 | `HttpInstrumentation` 是否覆盖 |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `openai@5.11.0` | `globalThis.fetch`(Node 18+ 即 undici)。证据:`node_modules/openai/internal/shims.mjs` 报错 `'fetch' is not defined as a global` | ❌ |
| `@google/genai@1.30.0` | `globalThis.fetch` + `new Headers()`。证据:`dist/node/index.mjs` 内的 `new Headers()` 调用 | ❌ |
| `@anthropic-ai/sdk`(anthropicContentGenerator) | 同样基于 fetch | ❌ |
### 2.3 代码库零 manual propagation
```
grep -rn "propagation\.\|setGlobalPropagator\|W3CTraceContext\|traceparent" packages/core/src --include="*.ts" | grep -v "\.test\."
```
→ 空。没有任何 `propagation.inject()` 调用,没有手动 traceparent 注入。
### 2.4 各 provider 的 `defaultHeaders` 现状
OpenAI 家族(用 `openai` SDK):
所有 OpenAI 子 provider 都 `extends DefaultOpenAICompatibleProvider`。**buildHeaders override 行为分两类**(已 grep audit 验证):
| Provider | 文件 | `buildHeaders()` 行为 | 影响 |
| ---------- | ---------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| 基类 | `default.ts:63-74` | 提供 `{ 'User-Agent' }` + customHeaders | 改这里 |
| DashScope | `dashscope.ts:110-124` | **`override` 但不 call `super`**——返回 `User-Agent` + `X-DashScope-*` 全新对象 | **必须单独改这里**,否则 correlation header 丢 |
| OpenRouter | `openrouter.ts:20-30` | `override` 但**先 `const baseHeaders = super.buildHeaders()`** | 改基类自动继承 ✅ |
| DeepSeek | `deepseek.ts` | 不 override `buildHeaders`(只 override `buildRequest` / `getDefaultGenerationConfig`) | 改基类自动继承 ✅ |
| Minimax | `minimax.ts` | 同 deepseek | 自动继承 ✅ |
| Mistral | `mistral.ts` | 同 deepseek | 自动继承 ✅ |
| ModelScope | `modelscope.ts` | 同 deepseek | 自动继承 ✅ |
→ **OpenAI 家族需要触动 2 个文件**:`default.ts` 和 `dashscope.ts`。其余 5 个自动继承。
Google Gemini:
| Provider | 文件 | 头注入路径 |
| -------- | ------------------------------ | -------------------------------------------------------------- |
| Gemini | `geminiContentGenerator.ts:59` | `new GoogleGenAI({ httpOptions: { headers } })` — SDK 原生支持 |
Anthropic:
| Provider | 文件 | 头注入路径 |
| --------- | ------------------------------------------------------------------------------------------------------ | ---------------- |
| Anthropic | `anthropicContentGenerator.ts:177` (`buildHeaders`) + `:212` (`defaultHeaders` arg to `new Anthropic`) | `defaultHeaders` |
**总计 4 个 SDK 构造点**需要注入 session id header。所有 SDK 都已支持 `defaultHeaders` / `httpOptions.headers`,无需 fetch wrapper。
### 2.5 已有的 proxy 与 fetch 配置
`provider/default.ts:87-89`:
```ts
const runtimeOptions = buildRuntimeFetchOptions(
'openai',
this.cliConfig.getProxy(),
);
```
`buildRuntimeFetchOptions` 在用户配 proxy 时返回 `{ fetch: customFetch }` 或类似,触发 `setGlobalDispatcher(new ProxyAgent(...))`(见 `config.ts:1126-1128`)。**undici 全局 dispatcher 模式与 `UndiciInstrumentation` 兼容**——它通过 monkey-patch `globalThis.fetch` 与 undici 的 channel diagnostics 协作,不依赖具体 dispatcher。
## 3. 目标 / 非目标
### 3.1 目标
- 所有 outbound LLM 请求自动带 W3C `traceparent` header(OTel SDK 默认的 `W3CTraceContextPropagator`)
- ~~所有~~ 出站 LLM 请求带 `X-Qwen-Code-Session-Id` header(claude-code 同款产品命名空间) — **R3 修订**:默认仅向 first-party (Alibaba/DashScope) host 注入,第三方 provider 默认不发;详见 §11
- 自动避免对 OTLP exporter endpoint 自身的 trace(feedback loop)
- 给 LLM 请求加一层精确的 client span(网络耗时 vs 模型耗时分离)
- 覆盖 4 个 provider 构造点:OpenAI 基类、DashScope override、Gemini、Anthropic
- streaming 请求 / proxy 模式 / 重试场景全部不退化
- 与 #4367 的设计哲学一致:通过 `defaultHeaders` 这种 SDK-native 选项 — **R1 修订**:因 staleness 问题转用 fetch wrapper;**R3 修订**:fetch wrapper 内再叠加 host gate
### 3.2 非目标
- **`baggage` header**:标准 SDK 已支持,但 qwen-code 没调 `propagation.setBaggage()`,默认不会发送。本设计不主动开启。
- **subprocess `TRACEPARENT` env var 继承**:claude-code 给 Bash/PowerShell 子进程注入 `TRACEPARENT`。qwen-code 的 `BashTool` 没做。是独立 follow-up sub-issue。
- **inbound `TRACEPARENT` / `TRACESTATE` 读取**:claude-code 的 `-p` 模式和 Agent SDK 从 env 读 traceparent 接续父进程 trace。qwen-code 没做。独立 follow-up。
- **`X-Qwen-Code-Request-Id`**:claude-code 有 `x-client-request-id`,对超时容错 correlation 有用。本期不做,可作为下一个 sub-issue。
- **自定义 propagator(B3 / Jaeger / X-Ray)**:默认 W3C 已覆盖 99% 场景。可作为 future config option。
- ~~**per-endpoint 选择性注入**:claude-code 对第三方 endpoint (Bedrock / Vertex) 不发 traceparent;qwen-code 没有第三方区分需要,统一发即可。~~ — **R3 修订**:此论断已被推翻。LaZzyMan review 指出 qwen-code 是开源 CLI 连接多个第三方 provider(OpenAI / Anthropic / OpenRouter / 等),claude-code 的 first-party→first-party 类比不适用;session id header 必须按 host 区分。详见 §11。`traceparent` 仍按 R1 设计全注入(OTel 标准 header,且 trace id 是 `sha256(sessionId)` 哈希值),可作为独立 follow-up 加 per-destination toggle(`telemetry.propagateTraceContext`)。
## 4. 设计
### 4.1 总体分层
```
┌─ qwen-code process ────────────────────────────────────────────┐
│ │
│ ┌─ session-tracing.ts ─┐ │
│ │ active span ctx │ │
│ └──────┬───────────────┘ │
│ │ │
│ ▼ │
│ ┌─ propagation.inject() (called by undici instrumentation) ─┐│
│ │ writes `traceparent: 00-<traceId>-<spanId>-01` to headers ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ┌──────▼──────────────────────────────────────────────────┐ │
│ │ fetch() — undici, instrumented │ │
│ │ creates HTTP client span │ │
│ │ injects traceparent into request headers │ │
│ │ (skipped via ignoreRequestHook if endpoint is OTLP) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ │ ┌─ defaultHeaders (per SDK constructor) ───────┐ │
│ │ │ { 'X-Qwen-Code-Session-Id': sessionId, ... } │ │
│ └───┴────────────────────────────────────────────────┘ │
│ │ │
└─────────────┼──────────────────────────────────────────────────┘
│
▼ outbound HTTP
POST /v1/chat/completions
traceparent: 00-...
X-Qwen-Code-Session-Id: ...
... (existing User-Agent, X-DashScope-*, etc.)
```
两条注入路径独立、互不依赖:
| Layer | 何时注入 | 由谁注入 |
| ------------------------ | ------------------------------------- | ------------------------------------------------------------- |
| `traceparent` | 每次 fetch 调用时 | `UndiciInstrumentation` 自动(来自 OTel SDK 默认 propagator) |
| `X-Qwen-Code-Session-Id` | SDK 构造时一次性写入 `defaultHeaders` | 应用代码 |
### 4.2 Part A — `traceparent` via undici instrumentation
**改动点**:`packages/core/src/telemetry/sdk.ts`
```ts
import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
// ...
const otlpUrls = [
config.getTelemetryOtlpEndpoint(),
config.getTelemetryOtlpTracesEndpoint(),
config.getTelemetryOtlpLogsEndpoint(),
config.getTelemetryOtlpMetricsEndpoint(),
]
.filter((u): u is string => !!u)
.map((u) => u.replace(/\/$/, ''));
instrumentations: [
new HttpInstrumentation(),
new UndiciInstrumentation({
ignoreRequestHook: (request) => {
// request.origin = "https://collector:4318", request.path = "/v1/traces"
const url = `${request.origin}${request.path}`;
return otlpUrls.some((e) => url.startsWith(e));
},
}),
],
```
#### 为什么 `ignoreRequestHook` 必须
OTel SDK 自己用 fetch 把数据 POST 到 OTLP collector。如果不跳,UndiciInstrumentation 会给"上报数据"的请求也建一个 span → 这个新 span 会被再次上报 → 无限循环 / 巨量噪声。每个 OTel 项目都踩过这个坑,OTel 文档明确推荐这种 hook。
#### 默认 propagator
OTel SDK `NodeSDK` 不传 `textMapPropagator` 时默认是 `CompositePropagator([W3CTraceContextPropagator, W3CBaggagePropagator])`。无需显式设置。
#### `traceparent` 格式
```
traceparent: 00-<32hex traceId>-<16hex spanId>-<01 sampled | 00 not sampled>
─┬─ ─┬─
version (固定 00) flags
```
固定 55 bytes,无 padding。
#### `tracestate` 与 `baggage`
- `tracestate`: 上游传过来才续传;自己 inject 不会主动加(OTel SDK 行为)。
- `baggage`: 仅当 `propagation.setBaggage(ctx, ...)` 被调用过才有。qwen-code 不调,所以不会发送。
### 4.3 Part B — `X-Qwen-Code-Session-Id` via fetch wrapper(OpenAI / Anthropic)+ static headers(Gemini)
> **R3 修订**:以下设计描述的是 fetch wrapper 的 staleness 解决和 4 个 provider 集成点 — 这些都保留。但 wrapper 内部增加了一道 host allowlist gate,`staticCorrelationHeaders` 也加了 `destinationUrl` 参数。带 host gate 的最新实现代码与 default allowlist 见 §11。
#### Critical:staleness 问题与方案选择
天真做法(`defaultHeaders` 直接 bake-in `getSessionId()`)有**真 bug**:
1. `pipeline.ts:60` 在 contentGenerator 构造时一次性 `this.client = this.config.provider.buildClient()`,SDK client 的 `defaultHeaders` 在那一刻 capture 当时的 session id
2. `config.ts:1850` 的 session reset(用户 `/clear` 时触发)更新 `this.sessionId` 并 `refreshSessionContext()`,但**不重建 contentGenerator**
3. 后续 LLM 调用仍走旧 client → wire header 仍是旧 session id → 后端 correlation 错位
→ 必须读取 session id **per-request**,不能 bake at构造时。
#### 方案
```
┌─ fetch 支持 ─┐ 方案
OpenAI SDK │ ✅ │ fetch wrapper (per-request 读 sessionId) ✅
Anthropic SDK │ ✅ │ fetch wrapper ✅
@google/genai SDK │ ❌ │ static httpOptions.headers + 接受 staleness
└──────────────┘
```
`@google/genai`'s `HttpOptions` interface 不支持 `fetch`(已 grep `node_modules/@google/genai/dist/genai.d.ts` 验证:只有 `baseUrl`/`apiVersion`/`headers`/`timeout`/`extraParams`)。所以 Gemini 走 static headers,与 OpenAI/Anthropic 不一致——这是 **known limitation**,见 §8.6。
#### 集中辅助函数(per-request fetch wrapper)
新文件 `packages/core/src/telemetry/llm-correlation-fetch.ts`:
```ts
import type { Config } from '../config/config.js';
/**
* Wrap a fetch implementation so every outbound request gets correlation
* headers (`X-Qwen-Code-Session-Id`) populated from the **current** session
* id, not the value captured when the SDK client was constructed.
*
* Matches claude-code's pattern (src/services/api/client.ts:370-390 —
* `buildFetch()`). Per-request injection is necessary because `/clear`
* resets the session id mid-process; SDK clients (and their static
* `defaultHeaders`) are NOT recreated on reset.
*
* Caller responsible for choosing the base fetch — usually
* `runtimeOptions?.fetch ?? globalThis.fetch` so proxy-aware fetch is
* preserved when ProxyAgent is in use.
*
* If telemetry is disabled, returns baseFetch unchanged (no correlation
* header is added, matching the privacy stance of §3.1).
*/
export function wrapFetchWithCorrelation(
baseFetch: typeof fetch,
config: Config,
): typeof fetch {
return async function correlationFetch(input, init) {
if (!config.getTelemetryEnabled()) {
return baseFetch(input, init);
}
const sid = config.getSessionId();
if (!sid) {
// Defensive: empty header value is rejected by some HTTP middleware.
// Skip injection rather than send `X-Qwen-Code-Session-Id: `.
return baseFetch(input, init);
}
const headers = new Headers(init?.headers);
headers.set('X-Qwen-Code-Session-Id', sid);
return baseFetch(input, { ...init, headers });
};
}
```
Companion helper for the SDKs that can only take static headers (Gemini):
```ts
/**
* Static correlation headers. Captures the session id at call time —
* **subject to staleness** if the host SDK keeps these headers in a
* captured-at-construction slot (e.g. `@google/genai`'s `httpOptions.headers`).
* Prefer `wrapFetchWithCorrelation` whenever the SDK exposes a `fetch` hook.
*/
export function staticCorrelationHeaders(
config: Config,
): Record<string, string> {
if (!config.getTelemetryEnabled()) return {};
return { 'X-Qwen-Code-Session-Id': config.getSessionId() };
}
```
#### 集成点 1: `provider/default.ts` (OpenAI 基类)
`buildClient()` 改动——compose 现有 `runtimeOptions.fetch`(proxy)与我们的 wrapper:
```ts
buildClient(): OpenAI {
// ... existing ...
const runtimeOptions = buildRuntimeFetchOptions('openai', this.cliConfig.getProxy());
const baseFetch =
(runtimeOptions as { fetch?: typeof fetch } | undefined)?.fetch
?? globalThis.fetch;
return new OpenAI({
apiKey,
baseURL: baseUrl,
timeout,
maxRetries,
defaultHeaders,
...(runtimeOptions || {}),
// After spread, override `fetch` so our correlation wrapper wraps the
// proxy-aware fetch (or globalThis.fetch when no proxy).
fetch: wrapFetchWithCorrelation(baseFetch, this.cliConfig),
});
}
```
`buildHeaders()` itself unchanged.
#### 集成点 2: `provider/dashscope.ts` (override)
`buildClient()` 同样的 compose 模式(它本来就 override buildClient)。`buildHeaders()` 不动。
#### 集成点 3: `geminiContentGenerator/index.ts` (factory, NOT 构造器)
**修正先前设计的过度声明**:`geminiContentGenerator.ts` 构造器**不需要**改签名。`index.ts:48` 的 factory 函数已经接收 `gcConfig: Config`(line 33 已经在用 `gcConfig?.getUsageStatisticsEnabled()`),只需要在 factory 里把 correlation 静态 headers merge 进 `httpOptions.headers`:
```ts
// geminiContentGenerator/index.ts
let headers: Record<string, string> = { ...baseHeaders };
if (gcConfig?.getUsageStatisticsEnabled()) {
// ... existing x-gemini-api-privileged-user-id ...
}
headers = { ...headers, ...staticCorrelationHeaders(gcConfig) }; // ← 新增
const httpOptions = config.baseUrl
? { headers, baseUrl: config.baseUrl }
: { headers };
// new GeminiContentGenerator(...) unchanged
```
零 signature 改动。
#### 集成点 4: `anthropicContentGenerator.ts`
Anthropic SDK 同样接受 custom `fetch`(已经在用 `buildRuntimeFetchOptions`)。把 `buildClient` 路径里那个 fetch wrap 一下,方式同 OpenAI default.ts。`buildHeaders` 不变。
#### 优先级链
不变:用户的 `customHeaders` 在 `defaultHeaders` merge 中仍然赢(见 §8.2 spoofing 讨论)。fetch wrapper 注入的 `X-Qwen-Code-Session-Id` 在 SDK 的 headers list 之**后**追加到最终 `Headers` 对象上——以 Node `Headers.set()` 的语义,等于覆盖任何之前同名的(包括 user 的 customHeaders 里写的同名 header)。
**对 OpenAI/Anthropic(fetch wrapper 路径)**:correlation > customHeaders > SDK defaults。
**对 Gemini(static headers 路径)**:customHeaders > correlation > SDK defaults(沿用既有 spread 顺序)。
差异是 fetch wrapper 路径下 spoofing 不再可能(fetch wrapper 在 SDK headers 之后跑)。这是 **bug 修复的副产品**,并非有意收紧——但更安全。要在 §8.2 明示。
### 4.4 配置 schema 影响
~~**几乎为零**。本设计不引入新 setting~~ — **R3 修订**:引入了一项新 setting `telemetry.sessionIdHeaderHosts: string[]`,用于覆盖默认的 first-party host 白名单。schema 项已加入 `packages/cli/src/config/settingsSchema.ts`,描述与 override 语法(`["*"]` 恢复广播 / `[]` 全关 / 自定义数组)见 §11。原文以下描述仅适用于 R3 之前:
- `traceparent` 注入由 telemetry enabled 触发(已有 toggle)
- `X-Qwen-Code-Session-Id` 注入也由 telemetry enabled 触发
- `ignoreRequestHook` 的 OTLP url 已经从现有 config 读
未来可以加的 setting(**out of scope**):
- `telemetry.outboundCorrelationHeader`: 自定义 header name(默认 `X-Qwen-Code-Session-Id`)
- `telemetry.outboundPropagationDisabled`: 全局关闭(如果 LLM 服务对未知 header 严格)
- ~~per-destination header scope toggle~~ — **R3 已落地**,见 §11
## 5. 文件改动清单
| 文件 | 改动类型 | 说明 |
| ------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/core/package.json` | 加依赖 | `@opentelemetry/instrumentation-undici` |
| `packages/core/src/telemetry/sdk.ts` | 修改 | +`UndiciInstrumentation` + `ignoreRequestHook` |
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | 新文件 | `wrapFetchWithCorrelation()` (OpenAI/Anthropic) + `staticCorrelationHeaders()` (Gemini fallback) |
| `packages/core/src/core/openaiContentGenerator/provider/default.ts` | 修改 | `buildClient()` 在 `new OpenAI({...})` 里加 `fetch: wrapFetchWithCorrelation(baseFetch, cliConfig)` |
| `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` | 修改 | 同上(override `buildClient`) |
| `packages/core/src/core/geminiContentGenerator/index.ts` | 修改 | factory 函数里 merge `staticCorrelationHeaders(gcConfig)` 进 `httpOptions.headers`(**caller 已有 Config,零 signature 改动** — 修正之前的 over-specification) |
| `packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts` | 修改 | `buildClient` 路径下用 `wrapFetchWithCorrelation` 包 SDK 的 `fetch` option |
**显式 audited 但无需改动**(避免 reviewer 怀疑漏路径):
- `packages/core/src/qwen/qwenContentGenerator.ts` — `extends OpenAIContentGenerator`,用 `DashScopeOpenAICompatibleProvider`,**自动继承 dashscope.ts 的 buildClient 改动**。所有 Qwen OAuth 流程同样受益。
- `packages/core/src/core/loggingContentGenerator/loggingContentGenerator.ts` — wrapper 模式,不构造 SDK client(它包装其他 contentGenerator 做 telemetry logging),无需改动。
- `packages/core/src/core/contentGenerator.ts` — factory 入口,不持有 client。
| `packages/core/src/telemetry/sdk.test.ts` | 修改 | 加 undici instrumentation 注册 + ignoreRequestHook 测试 |
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | 新文件 | telemetry-on/off 行为单测 + per-request 读 sessionId 验证(critical:session reset 后 wrapped fetch 读到新 id) |
| 各 provider 的 `*.test.ts` | 修改 | 断言 SDK 构造时 `fetch` option 是 wrapped 版本(OpenAI/Anthropic);断言 Gemini 构造时 `httpOptions.headers` 含 `X-Qwen-Code-Session-Id` |
| `docs/developers/development/telemetry.md` | 修改 | 新增 "Trace context & session correlation propagation" 段 |
| `docs/design/telemetry-outbound-propagation-design.md` | 本文件 | 设计文档 |
## 6. 分 PR 拆分
按 review 友好度分两个 PR(也可以合一,规模允许):
### PR 1 — `traceparent` 自动注入(structural)
- 加 `@opentelemetry/instrumentation-undici` 依赖
- `sdk.ts` 加 `UndiciInstrumentation` + `ignoreRequestHook`
- 测试:SDK 注册、OTLP endpoint 不被 trace
- 文档片段
**风险**:低。Additive。已有 client span 是 net 增益,不会改变现有 span 结构。
### PR 2 — `X-Qwen-Code-Session-Id` header(结合 helper 函数)
- 新文件 `llm-correlation-headers.ts`
- 4 个 provider 集成
- 测试:每个 provider 断言 header 存在;telemetry-off 时不发
- 文档片段
**风险**:低-中。要小心 `geminiContentGenerator` 构造器签名扩展可能波及调用方。
### PR 3(可选) — Docs + E2E verify
- 完善 `telemetry.md` 段落
- 加 E2E verify script(复用 `/tmp/verify-telemetry-pr-4367.mjs` 模式):实际跑 fetch + 抓 header
也可以合并到 PR 2 里。
### 顺序偏好
PR 1 和 PR 2 技术上**互相独立**——不共享代码。但**推荐 PR 1 先合**:
- `traceparent` 是 OTel **标准** header,任何 OTel-aware collector / 后端立刻识别 → 用户立即获益
- `X-Qwen-Code-Session-Id` 是**产品自定义** header,需要后端配置识别才有价值 → 价值滞后
- 万一 PR 2 review 周期长,PR 1 已经把 cross-process trace 跑通了
- PR 1 是 additive structural(低风险),适合先建立信心
## 7. 测试计划
### 7.1 `sdk.ts` 单测
- ✅ `UndiciInstrumentation` 在 `NodeSDK` 的 `instrumentations` 中存在
- ✅ `ignoreRequestHook` 对 `https://collector:4318/v1/traces` 返回 true
- ✅ `ignoreRequestHook` 对 `https://dashscope.aliyuncs.com/...` 返回 false
- ✅ trailing slash 与无 trailing slash 都正确匹配
### 7.2 `llm-correlation-fetch.ts` 单测
**`wrapFetchWithCorrelation`**:
| 场景 | 期望 |
| ------------------------------------------------------- | ---------------------------------------------------------------------- |
| `getTelemetryEnabled() === false` | wrapped fetch = baseFetch(不加任何 header) |
| `getTelemetryEnabled() === true`, sessionId = "abc-123" | wrapped fetch 发出的 init.headers 含 `X-Qwen-Code-Session-Id: abc-123` |
| `init.headers` 已有 `X-Qwen-Code-Session-Id: spoof` | wrapper 后覆盖为真 sessionId(fetch wrapper 路径不允许 spoof,§8.1) |
| **session reset 后 wrapped fetch 被再次调用** | **读取新 sessionId**(regression guard for staleness fix) |
| baseFetch reject | wrapper 透传 reject 不吞 |
**`staticCorrelationHeaders`**(Gemini path):
| 场景 | 期望返回 |
| ------------------------------------------------------- | ---------------------------------------------------------------- |
| `getTelemetryEnabled() === false` | `{}` |
| `getTelemetryEnabled() === true`, sessionId = "abc-123" | `{ 'X-Qwen-Code-Session-Id': 'abc-123' }` |
| sessionId 中含 unicode(`會話-1`) | 原样返回——HTTP header value 由 SDK 负责编码 |
| sessionId 为空字符串 | `{ 'X-Qwen-Code-Session-Id': '' }`——业务 invariant,不在此层校验 |
### 7.3 Per-provider 集成测试
每个 provider 的 `buildHeaders()` / 构造测试加:
```ts
it('includes X-Qwen-Code-Session-Id when telemetry enabled', () => {
const config = makeFakeConfig({
sessionId: 'sess-xyz',
telemetry: { enabled: true },
});
const provider = new DefaultProvider(genConfig, config);
expect(provider.buildHeaders()['X-Qwen-Code-Session-Id']).toBe('sess-xyz');
});
it('omits X-Qwen-Code-Session-Id when telemetry disabled', () => {
const config = makeFakeConfig({ telemetry: { enabled: false } });
const provider = new DefaultProvider(genConfig, config);
expect(provider.buildHeaders()).not.toHaveProperty('X-Qwen-Code-Session-Id');
});
```
### 7.4 E2E verification(tmux + local HTTP server)
⚠️ **不要** mock `globalThis.fetch` 来抓 header:`UndiciInstrumentation` 通过 undici 的 diagnostics channel hook,monkey-patching globalThis.fetch 可能完全 bypass instrumentation(取决于 patch 顺序),让 `traceparent` 注入测不到。**正确做法是起 local HTTP server**,让 SDK 真发请求,server 端记录收到的 headers。
写一个仿 `/tmp/verify-telemetry-pr-4367.mjs` 的脚本:
1. `http.createServer((req, res) => { capturedHeaders.push(req.headers); res.end('{}') })` 起本地 server
2. 启 telemetry + outfile + 把 OpenAI SDK 的 `baseURL` 指向 `http://127.0.0.1:<port>`(或者用 mock provider 让 SDK 真发 fetch)
3. 触发一次 `client.chat.completions.create(...)`(要带最小可解析的 mock 响应,否则 SDK 解析报错——本地 server 返回合法但空的 OpenAI 响应即可)
4. 断言 `capturedHeaders[0]` 含 `traceparent: 00-...` 和 `X-Qwen-Code-Session-Id: <sessionId>`
5. 另起一个 OTLP collector mock 在 different port,验证给它发的 OTLP 上报**不**触发 `traceparent` 注入(验证 `ignoreRequestHook`)
6. **额外:staleness 验证** — emit request 1 → call `config.resetSession(...)` → emit request 2 → 断言 request 2 的 `X-Qwen-Code-Session-Id` 是新 session id(**这是 #1 fix 的关键回归测试**)
### 7.5 回归保护
- streaming chat completion 的 fetch(带 `stream: true`)仍正常关闭——`UndiciInstrumentation` 历史上对 streaming response 的 span lifecycle 有过 bug,**实施时需要实际跑一次 streaming completion 端到端验证 client span 正常 end + 无 leaked span + 流不被截断**;不假设具体版本号已修
- proxy mode (`ProxyAgent`) 与 instrumentation 同时启用——`ignoreRequestHook` 仍按 endpoint 字符串匹配,proxy 不影响
- 重试(`maxRetries`)下每次重试都得到独立 client span,但都共享同一个 `traceparent` parent(理想是 retry 作为同一个父 span 下多个 child span — 这部分由 SDK 行为决定,本设计不强制)
## 8. 边界 / 边角
### 8.1 customHeaders override 与 spoofing 的不一致行为
不同 provider 路径的 spoofing 表面**不同**(设计后果,非原意收紧):
| Provider 路径 | spoofing 可能? | 原因 |
| --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- |
| OpenAI / Anthropic (fetch wrapper 路径) | ❌ 不能 spoof | fetch wrapper 在 SDK headers list 之后 `headers.set('X-Qwen-Code-Session-Id', ...)`,覆盖 user customHeaders 的同名 |
| Gemini (static headers 路径) | ✅ 可 spoof | merge 顺序 `{ ...baseHeaders, ...correlationHeaders, ...customHeaders }`——customHeaders 最后赢 |
claude-code 同样使用 fetch wrapper 路径,行为与 OpenAI/Anthropic 一致(spoofing 不能)。这是修 staleness bug 的副产品,不是原本要做的事。
**不打算"对齐"两条路径**——Gemini 路径的行为是 SDK 限制(没有 `fetch` hook)导致的,反向把 OpenAI 也降级到 static 不合理。
Session id spoofing 不是真威胁(用户控制本地,可以直接改 source code)。文档里要明示这个差异,避免 reviewer 看到 fetch wrapper 路径无法 spoof 时质疑 customHeaders 优先级。
### 8.2 OTLP collector URL 匹配的两类 edge case
#### (a) Auth token in URL
如果用户 OTLP endpoint 形如 `https://collector/path?token=secret`,`ignoreRequestHook` 的 `url.startsWith(e)` 比对应包含 query string。但 undici 给的 `request.path` 只到 path(不含 query),所以比较时 `e` 也只用到 path 部分。为安全起见,剥掉 query:
```ts
const otlpUrls = [...]
.map((u) => u.replace(/\?.*$/, '').replace(/\/$/, ''));
```
#### (b) startsWith 跨 hostname 边界的理论 false positive
若 `e = "http://collector"`(无 port),来路 url = `http://collector-fake/v1/traces` 会被 startsWith 错误匹配。
**实际触发概率极低**:
- OTLP endpoint 几乎总带 port(4317 gRPC / 4318 HTTP),`http://collector:4318` 形态后 `-fake` 这种延伸不可能(port 后跟的是 `/`)
- 用户配 endpoint 不带 port 是配置错误,本来 SDK 就要默认 fallback
**如果想 harden**:解析 URL origin + path 分别比较,不用裸 startsWith:
```ts
const parsed = otlpUrls.map((u) => new URL(u));
return parsed.some(
(e) =>
`${request.origin}` === e.origin && request.path.startsWith(e.pathname),
);
```
本期不做——开销没必要,false positive 实际触发不到。
### 8.3 Vertex AI 模式的 Gemini
`@google/genai` 支持 `vertexai: true` 模式(用 GCP 凭据走 Vertex 端点而非 generative ai endpoint)。两种模式都走 fetch,所以 instrumentation 都覆盖。`httpOptions.headers` 在两种模式下都有效。
### 8.4 Anthropic SDK 已有 `defaultHeaders` 逻辑
`anthropicContentGenerator.ts:177` 已经在调 `buildHeaders()` 然后传给 `new Anthropic({ defaultHeaders })`。但 staleness 同样适用——本设计改用 `fetch` wrapper 路径(与 OpenAI 一致)。
### 8.5 SDK 与 fetch 之间的 trailer header
`openai` SDK 在 streaming 时可能用 `Transfer-Encoding: chunked` 和 trailer headers。这些都不影响 request-time 的 `traceparent` / `X-Qwen-Code-Session-Id` 注入——它们都是请求头,发出时一次性写入。
### 8.6 ⚠️ Known limitation: Gemini 的 session id 在 `/clear` 后 stale
由于 `@google/genai` SDK 不支持 `fetch` hook(`HttpOptions` 接口只有 `baseUrl`/`apiVersion`/`headers`/`timeout`/`extraParams`),Gemini provider 走 static `httpOptions.headers` 路径——session id 在 SDK 构造时 capture,**`/clear` 触发 session reset 后不刷新**。
**实际影响范围**:
- 用户启动 qwen-code → `/clear` → 用 Gemini 模型 → wire 上的 `X-Qwen-Code-Session-Id` 是旧 session id
- 后端 correlation 错位(trace id 和 log 已正确切换到新 session,但 wire header 滞后)
**为什么不修**(本期):
- OpenAI / Anthropic 路径**没有这个 bug**(fetch wrapper 路径 per-request 读 session id)
- Gemini fix path 有几个选项,全部超出本期 scope(见下)
**Future fix path 选项**(按推荐顺序):
| 选项 | 描述 | 代价 |
| --------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **A. Lazy invalidate** ★ 推荐 | session reset 时只 mark contentGenerator dirty,下次 LLM 调用时 lazy recreate | 小:~10 行加在 `resetSession` + LLM 调用入口;同步 API,无侵入 |
| B. Eager recreate | session reset 时立即 `await createContentGenerator(...)`,需 async 化 `resetSession` | 中:API 改动级联多处 |
| C. Proxy headers object | 给 `httpOptions.headers` 包 Proxy 拦截 getter | 风险高:`@google/genai` 内部是否 per-request 重读 headers 不可知,行为可能 silently break |
| D. 推动 `@google/genai` 上游加 `fetch` option | 提 PR 给 google-deepmind/generative-ai-js | 长期;不可控 |
**文档要在用户面前说明**:使用 Gemini provider 时如果 `/clear` 后立刻有 LLM 调用,wire 上的 session id 在那一刻是旧的。可以靠 trace correlation 间接修正(spans/logs 上 session.id 已经是新的)。
应单开 follow-up sub-issue 跟踪选项 A。
## 9. 与 claude-code 对比
| 维度 | claude-code | qwen-code 本设计 | 决策依据 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Session id header 命名 | `X-Claude-Code-Session-Id`(产品前缀) | `X-Qwen-Code-Session-Id`(产品前缀) | ✅ 同样命名空间策略 |
| Session id 注入机制 | SDK `defaultHeaders`(`client.ts:108`)+ 自定义 `buildFetch()` wrapper(`client.ts:370-390`,per-request `randomUUID()` 注入 `x-client-request-id`) | OpenAI/Anthropic 走 fetch wrapper(per-request 读 session id,避免 `/clear` staleness);Gemini 走 static `httpOptions.headers`(SDK 限制) | 与 claude-code 的 fetch wrapper 模式对齐。claude-code 也用 fetch wrapper 才能 per-request 加 `x-client-request-id` |
| Session id 持久性 | claude-code 没有 `/clear`-式 session reset;session = process | 有 `/clear` reset → fetch wrapper 路径自动跟随;static headers 路径会 stale(§8.6) | qwen-code 独有的复杂度 |
| Session id 编码 | HTTP header(不是 baggage) | HTTP header | ✅ 同——backend 友好 |
| `traceparent` 注入 | 闭源;公开 docs 描述存在;开源 repo 无 `propagation.inject` / `UndiciInstrumentation` 引用 | `@opentelemetry/instrumentation-undici` 自动 | claude-code 怎么实现的不可见。我们选 OTel 官方推荐路径,更轻 |
| `traceparent` 发送范围 | 仅第一方 Anthropic API;不发 Bedrock/Vertex/Foundry | 发给所有出站 fetch (W3C 标准;trace id 是 `sha256(sessionId)` 哈希)。**R3 修订**:session id header 仅向 first-party (Alibaba/DashScope) 白名单注入,第三方默认不发。详见 §11 | R3 后 qwen-code 的 session header 与 claude-code 同样的 first-party-only 语义;`traceparent` 仍待 per-destination toggle follow-up |
| `x-client-request-id` (随机) | 有,自动 | 暂不做(独立 follow-up sub-issue 价值更高) | 范围控制 |
| 子进程 `TRACEPARENT` env | 文档承认存在(实现闭源) | 不做(独立 follow-up) | 范围控制 |
| 入站 `TRACEPARENT` 读取 | 文档承认存在(`-p` / Agent SDK 模式) | 不做(独立 follow-up) | 范围控制 |
**verified vs documented 注解**:
| claim | 验证状态 |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Claude-Code-Session-Id` via `defaultHeaders` | ✅ Open source `src/services/api/client.ts:108` 已读 |
| `x-client-request-id` via fetch wrapper | ✅ Open source `src/services/api/client.ts:370-390` 已读 |
| `traceparent` 注入 | ⚠️ 仅 docs.claude.com/docs/en/monitoring-usage.md 提到;开源 repo `grep -rn "propagation\.inject\|UndiciInstrumentation\|traceparent" src` 返回空 |
## 10. 未来工作
挂在 #3731 P3 下,本设计**不**包含但与之相关:
- **`X-Qwen-Code-Request-Id`** 随机 UUID per request(claude-code 等价:`x-client-request-id`)。对超时/timeout error correlation 有用——超时时服务端可能还没 assign request id,客户端先发的 id 是唯一关联手段。R3 修订后这个建议变得更有意义:per-request UUID 没有"跨请求行为画像"风险,可以作为"对所有 LLM provider 发送的支持/调试 header"。
- **`traceparent` 的 per-destination scope toggle** — R3 修订仅处理了 session id header 的作用域;`traceparent` 仍向所有出站 fetch 注入。可以加 `telemetry.propagateTraceContext: 'trusted-hosts' | 'all' | 'none'`,使用与 §11 同一份 allowlist 决定行为。
- **Gemini 的 session id staleness lazy-invalidate fix**(§8.6 选项 A):`/clear` 时 mark contentGenerator dirty,下次 LLM 调用 lazy recreate。让 Gemini 路径也享受 fetch wrapper 的实时性。
- **子进程 `TRACEPARENT` env**:给 `BashTool` 执行子进程时注入 env,让外部工具能续传 trace。需要单独看 tool execution lifecycle。
- **入站 `TRACEPARENT`**:`--prompt` 模式启动时读 env,让 CI / 外部 orchestrator 能把 qwen-code 接到更大的 trace。
- **可配置 `correlationHeader` name**:让企业 ops 自定义 header(默认 `X-Qwen-Code-Session-Id`)。
- **`baggage` propagation 策略**:是否主动 set baggage 让 `user.id` / `tenant.id` 等也走 baggage 传到下游。本期不做,等需求明确。
## 11. R3 修订 — Host-Allowlist Scoping for `X-Qwen-Code-Session-Id`
> 触发:[LaZzyMan 在 PR #4390 的 REQUEST_CHANGES review](https://github.com/QwenLM/qwen-code/pull/4390)
> 落地 commit:`1c8528a56` (核心实现) + `cb162e716` (Vertex baseUrl fail-closed + `["*"]` trim 容错)
### 11.1 触发与论证
R1 设计把 `X-Qwen-Code-Session-Id` 向**所有**出站 LLM 请求注入,仅由 `telemetry.enabled` 控制。LaZzyMan review 指出了三个递进的问题:
1. **标签错位**:`feat(telemetry):` + `telemetry/` 路径 + `getTelemetryEnabled()` gate 让用户合理理解为"自家可观测性数据流向自家 collector"。但 `X-Qwen-Code-Session-Id` 不会到达 OTLP 后端,它走在 LLM API 请求里发给 DashScope / OpenAI / Anthropic / Gemini / OpenRouter / MiniMax / ModelScope / Mistral。两种不同的数据出口决策绑在一个开关上。
2. **claude-code 类比不成立**:R1 在 §9 把命名空间策略和 fetch wrapper 模式都"对齐"了 claude-code。但 claude-code 是 Anthropic 一方 → Anthropic 一方(single vendor, single direction),qwen-code 是开源 CLI → 多个第三方 provider。"一个稳定 cross-request UUID 广播到所有第三方"是 R1 没正面回答的问题。
3. **traceparent 是同一指纹的另一通道**:trace id = `sha256(sessionId).slice(0, 32)`,对接收方来说仍是稳定 per-session 标识符(哈希后不可逆,但同一 session 仍稳定)。
LaZzyMan 标定 severity:session id `high` / traceparent `medium`。
### 11.2 解法概要
**收窄默认作用域到 first-party hosts**。新增一项 setting:
```jsonc
"telemetry": {
"sessionIdHeaderHosts": ["*"] // 恢复 R1 广播行为
"sessionIdHeaderHosts": [] // 全关 header
"sessionIdHeaderHosts": ["api.mycompany.com",
"*.gateway.mycompany.internal"]
}
```
默认值(来自 `packages/core/src/telemetry/trusted-llm-hosts.ts:DEFAULT_SESSION_ID_HEADER_HOSTS`):
```
dashscope.aliyuncs.com
dashscope-intl.aliyuncs.com
*.dashscope.aliyuncs.com
*.dashscope-intl.aliyuncs.com
*.alibaba-inc.com
*.aliyun-inc.com
```
这个集合的语义是"LLM provider、ARMS Tracing 后端、qwen-code distribution 同一法律实体"——也就是 claude-code 那个 single-vendor / single-direction 关系在 qwen-code 的对应集合。第三方 provider(OpenAI / Anthropic / OpenRouter / 等)默认**不**接收 header。
### 11.3 Pattern 语法(intentionally tiny)
`matchesTrustedHost(hostname, patterns)` 只支持两种模式,与 `DashScopeOpenAICompatibleProvider.isDashScopeProvider` 对齐:
- bare hostname → 精确匹配(case-insensitive)
- `*.suffix` → 匹配 `suffix` 自身 **AND** 任何子域;dot-anchored 拒绝 `evil-alibaba-inc.com` / `alibaba-inc.com.attacker.tld` 等 typo-suffix 攻击向量
不引入 regex、不引入端口/scheme 感知 globbing —— 让 settings 里的字符串就是它字面看起来的语义。
### 11.4 实现差异 vs R1
#### `wrapFetchWithCorrelation` (OpenAI / Anthropic)
R1 的 wrapper 只有 telemetry-enabled + sessionId 两个 gate。R3 在两者之间插入第三个 gate:
```ts
const trustedHosts =
config.getTelemetrySessionIdHeaderHosts?.() ??
DEFAULT_SESSION_ID_HEADER_HOSTS;
const broadcastAll = trustedHosts.some((p) => p.trim() === '*');
return async function correlationFetch(input, init) {
if (!config.getTelemetryEnabled()) return baseFetch(input, init);
if (!broadcastAll) {
const host = extractRequestHost(input);
if (!host || !matchesTrustedHost(host, trustedHosts)) {
return baseFetch(input, init); // host gate
}
}
const sid = config.getSessionId();
if (!sid) return baseFetch(input, init);
// ... header injection
};
```
`trustedHosts` 在 wrap 时一次性 snapshot(与 session id 的"每请求实时读"不同)。中途修改 `telemetry.sessionIdHeaderHosts` 需要重建 contentGenerator 才生效。`[" * "]` 之类带空格的写法通过 `.trim()` 兜底成 broadcast,避免 settings.json 手敲笔误沉默退化。
#### `staticCorrelationHeaders` (Gemini)
签名加一个 `destinationUrl?: string` 参数:
```ts
export function staticCorrelationHeaders(
config: Config,
destinationUrl?: string,
): Record<string, string> {
if (!config.getTelemetryEnabled()) return {};
if (!destinationUrl) return {}; // fail-closed: 不知道目的地就不发
if (!matchesTrustedHost(new URL(destinationUrl).hostname, trustedHosts)) {
return {};
}
return { [SESSION_ID_HEADER]: config.getSessionId() };
}
```
#### Gemini factory 集成
Gemini SDK 有两个不可见 default endpoint(`generativelanguage.googleapis.com` 与 `{region}-aiplatform.googleapis.com`,由 `vertexai` 决定),factory 层无法准确还原其中之一。R3 选择"`config.baseUrl` 没设就传 `undefined`",让 helper fail-closed → 不发 header。运营商想要相关性必须显式设 `baseUrl`(也是 SDK 自己用来解 destination 的同一输入)。这一改动避免了猜错 Vertex destination 后被允许列表错误命中。
### 11.5 新文件 / 新代码
| 文件 | 说明 |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `packages/core/src/telemetry/trusted-llm-hosts.ts` (NEW) | `DEFAULT_SESSION_ID_HEADER_HOSTS` + `matchesTrustedHost` + `extractRequestHost` |
| `packages/core/src/telemetry/trusted-llm-hosts.test.ts` (NEW) | 单测,含 TLD-suffix 攻击向量、IPv6 fail-closed、port/userinfo/query 提取 |
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | 加 host gate;`staticCorrelationHeaders` 加 `destinationUrl` 参数 |
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | 加 host-gate 8 个 case;`mockConfig` 用 `'hosts' in opts` 区分 "default allowlist" vs "broadcast" |
| `packages/core/src/telemetry/config.ts` (`resolveTelemetrySettings`) | 透传 `sessionIdHeaderHosts` |
| `packages/core/src/config/config.ts` | `TelemetrySettings.sessionIdHeaderHosts` + `getTelemetrySessionIdHeaderHosts()` getter |
| `packages/core/src/core/geminiContentGenerator/index.ts` | 传 `config.baseUrl` 给 helper;fail-closed when undefined |
| `packages/core/src/core/geminiContentGenerator/index.test.ts` | 重写 telemetry-on Gemini 测试以匹配新 fail-closed 语义 |
| `packages/cli/src/config/settingsSchema.ts` | `sessionIdHeaderHosts` JSON schema 入口 |
| `packages/vscode-ide-companion/schemas/settings.schema.json` | 由 `npm run generate:settings-schema` 重新生成 |
| `docs/developers/development/telemetry.md` | "Session correlation header" 段落改写 + 默认 scope + override 语法 |
### 11.6 对各 LazzyMan 论点的回应
| LazzyMan 论点 | R3 回应 |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ① telemetry 标签错位 | **化解**:在 DashScope 用例下,session id header 字面就是发给 ARMS Tracing 后端(同一法律实体),`telemetry.enabled` 语义对齐 |
| ② cross-vendor stable identifier 广播 | **化解**:默认 allowlist 只含阿里系 first-party host;广播退化为 opt-in (`["*"]`) |
| ③ traceparent 是同一指纹的另一通道 | **暂保留**:traceparent 仍按 R1 全注入。理由:W3C 标准、trace id 是 sha256 哈希、in-vendor trace 续接是 W3C 的核心设计场景。per-destination traceparent toggle 列入 §10 future work |
### 11.7 已知遗留 + 跟进
- **traceparent scope** — 见上文第 ③ 点,列入 §10
- **Per-request random UUID** (`X-Qwen-Code-Request-Id`) — LazzyMan 提的替代方案,列入 §10
- **Gemini staleness lazy-invalidate** (§8.6 选项 A) — 与 R3 解耦,独立 sub-issue
- **`matchesTrustedHost` IPv6 支持** — 当前 IPv6 destination 永不在 allowlist 上(`URL.hostname` 返回 `[::1]` 带方括号,pattern 语法无对应形式)。当前满足"命名 first-party endpoint"用例。若将来有 raw IP allowlist 需求再扩展。
## 12. R4 修订 — Scope Conflation Split
> 触发:[LaZzyMan round-8 follow-up review on PR #4390](https://github.com/QwenLM/qwen-code/pull/4390)
> 落地:本 PR 收窄;R3 落地的 session-id 整套挪到独立 follow-up PR
### 12.1 触发与论证
R3 化解了 LaZzyMan 第一轮 review 的「广播稳定指纹给第三方 provider」担忧(severity: high)。但在 round-8 follow-up 中他升级到更深的架构原则反对:
> "Telemetry is not a container for adjacent features. The `traceparent` cross-process propagation and the `X-Qwen-Code-Session-Id` header injection are **not telemetry**. They are outbound-identity / outbound-correlation work that uses some OTel APIs internally as an implementation detail."
他的核心元论点:
- **"telemetry" namespace 暗示 recipient = 用户自己的 OTLP collector**
- 但 `traceparent` 和 `X-Qwen-Code-Session-Id` 的 recipient = **第三方 LLM provider**
- 两类不同 recipient 应该有两类不同的同意决策树
- 即使默认行为安全(R3 已实现),把 wire-level 行为放在 `telemetry.*` 下**设了坏先例**:未来 telemetry PR 可以继续偷渡 wire 行为给第三方
- "If we accept that principle, the split is mechanical. If we don't, this PR is the wrong place to debate it because the technical fixes are already in."
### 12.2 解法概要("方案 C" hybrid split)
经过几轮内部讨论(含 yiliang 提出的 customHeader 模板替代方案,最终判定 customHeader 不能携带 runtime-dynamic 值),决定走 **方案 C**:
**本 PR 留下**:
- `UndiciInstrumentation` 注册(产 client HTTP span → 用户自家 OTLP collector)
- OTLP feedback-loop guard(前者的必要副作用)
- **`NoopTextMapPropagator` 默认安装** → `propagation.inject()` 是 no-op → outbound `fetch` 上**不再有 `traceparent`**
- **新增 `outboundCorrelation.propagateTraceContext: bool` (默认 false)** 作为独立 namespace 顶级设置;设 true 时安装默认 W3C composite propagator
- 整套 `R3 session-id` 代码(`llm-correlation-fetch.ts` / `trusted-llm-hosts.ts` / `telemetry.sessionIdHeaderHosts` setting / 4 个 provider 集成点 / 所有相关测试)**全部移除**
**搬到 follow-up PR**:
- `X-Qwen-Code-Session-Id` header 整套机器(R3 实现复用)
- 进入新 `outboundCorrelation.*` namespace(具体 setting key TBD,但**不会**叫 `telemetry.*`)
- Follow-up PR 自带:threat model section、独立 review、security-relevant 标注的 docs
- `X-Qwen-Code-Request-Id` per-request UUID(LazzyMan 在 R3 round 提出的替代设计)也归入此 follow-up 的考虑范围
### 12.3 与 R3 R1 论点的映射
| R1/R3 论点 | R4 后状态 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| §3.1 "所有出站 LLM 请求带 traceparent" | ❌ **R4 默认 off**;需 `outboundCorrelation.propagateTraceContext: true` 才开 |
| §3.1 "所有出站 LLM 请求带 `X-Qwen-Code-Session-Id`" | ❌ **R4 整套移出本 PR**,搬到 follow-up PR |
| §4.3 fetch wrapper 注入 session id | ❌ 整段代码不在本 PR;复用到 follow-up PR |
| §11 host allowlist (R3 设计) | ❌ 同上;整体迁移 follow-up PR |
| §4.4 不引入新 setting | ❌ **本 PR 新增 `outboundCorrelation.propagateTraceContext`** 一个 boolean;session id 相关 setting 在 follow-up PR |
| §10 future work "`X-Qwen-Code-Request-Id`" | ✅ 仍是 future work;与 session-id follow-up 一起设计 |
### 12.4 新 namespace 设计意图
`outboundCorrelation.*` 顶级 namespace 在本 PR 只有一个 boolean (`propagateTraceContext`),看起来过度结构化。但这是**精心选择的**:
- **建立命名空间作为承诺**:让后续 session-id / request-id / etc. 自然进入这个 namespace
- **标注为 security-relevant**:`settingsSchema.ts` description 显式写 "SECURITY-RELEVANT",文档化为"安全设置"而非"observability 设置"
- **defaults 全部 off**:符合 LazzyMan 提出的"open-source 客户端不应未经显式同意向第三方发稳定 id"原则
- **与 telemetry.\* 解耦**:用户读 settings.json 看到 `outboundCorrelation.*` 立刻能识别这是出站 wire 行为,不是 observability
#### 隐性依赖:`telemetry.enabled`
虽然 namespace 与 `telemetry.*` 解耦,**运行时生效仍依赖 `telemetry.enabled: true`** —— OTel SDK 只在 telemetry 启用时初始化,没有 SDK 就没有 propagator 安装、没有 `propagation.inject()` 调用,flag 等于沉默 no-op。容易踩的 footgun:运营商加 `propagateTraceContext: true` 却忘开 telemetry,trap server 上看不到任何 `traceparent`,无 error / 无 warning。
两个面向用户的面板都显式标注此依赖:
- `telemetry.md` 的 `propagateTraceContext` 段附完整双 flag JSON 示例
- `settingsSchema.ts` 的 description string **首句**即 "Requires `telemetry.enabled: true`"(前置以避免 VS Code 设置 UI 长描述折叠后看不到)
未来若添加 session-id header 或其他 `outboundCorrelation.*` setting,**同一依赖关系适用** —— 都得在 telemetry 启用前提下才有意义(因为它们都通过 OTel instrumentation/SDK 注入)。Follow-up PR 应继承此 footgun 提示模式。
### 12.5 实施
| 文件 | 改动 |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/core/src/telemetry/llm-correlation-fetch.ts` | **删除** |
| `packages/core/src/telemetry/llm-correlation-fetch.test.ts` | **删除** |
| `packages/core/src/telemetry/trusted-llm-hosts.ts` | **删除** |
| `packages/core/src/telemetry/trusted-llm-hosts.test.ts` | **删除** |
| `packages/core/src/telemetry/sdk.ts` | + `NoopTextMapPropagator`;按 `getOutboundCorrelationPropagateTraceContext()` 决定 SDK textMapPropagator |
| `packages/core/src/core/openaiContentGenerator/provider/default.ts` | 移除 `wrapFetchWithCorrelation` 引用 |
| `packages/core/src/core/openaiContentGenerator/provider/dashscope.ts` | 同上 |
| `packages/core/src/core/anthropicContentGenerator/anthropicContentGenerator.ts` | 同上 |
| `packages/core/src/core/geminiContentGenerator/index.ts` | 移除 `staticCorrelationHeaders` 引用 |
| 上述 4 个 provider 的 `*.test.ts` | 删 session-id 相关测试 case |
| `packages/core/src/config/config.ts` | 删 `TelemetrySettings.sessionIdHeaderHosts`、`getTelemetrySessionIdHeaderHosts`;**新增 `OutboundCorrelationSettings` 接口 + `outboundCorrelationSettings` 字段 + `getOutboundCorrelationPropagateTraceContext()` getter** |
| `packages/core/src/telemetry/config.ts` | 删 `resolveTelemetrySettings` 中 sessionIdHeaderHosts 透传 |
| `packages/cli/src/config/settingsSchema.ts` | 删 `sessionIdHeaderHosts` schema;**新增 `outboundCorrelation` 顶级 schema 项** |
| `packages/cli/src/config/config.ts` | 透传 `outboundCorrelation: settings.outboundCorrelation` 进 `ConfigParameters` |
| `packages/vscode-ide-companion/schemas/settings.schema.json` | `npm run generate:settings-schema` 重新生成(description 后续更新时同步刷新) |
| `docs/developers/development/telemetry.md` | 重写 "Trace context propagation" → "Client-side HTTP span on outbound fetch";删 "Session correlation header" 整节;新增 "Outbound correlation (SECURITY-RELEVANT)" 顶级 section;附 `telemetry.enabled` 依赖说明 + JSON 配置示例 |
| `docs/design/telemetry-outbound-propagation-design.md` | 本节 + R4 表头 + 修订指针 |
| `packages/core/src/config/config.test.ts` | **新增 `OutboundCorrelation Configuration` describe block**,`it.each` 4 个 case 锁定 `getOutboundCorrelationPropagateTraceContext` 的 default-false 安全不变性(omitted / `{}` / explicit true / explicit false) |
### 12.6 对 LazzyMan 元论点的回应
| 论点 | R4 后状态 |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| "Telemetry namespace 暗示自家 collector 接收方" | ✅ wire 行为已搬出 `telemetry.*`;新 `outboundCorrelation.*` namespace 显式标识"出站第三方"语义 |
| "默认行为不应未经显式同意向第三方发标识符" | ✅ `propagateTraceContext` 默认 false;session-id 整套 follow-up PR 也将默认 off |
| "telemetry PR 不应偷渡 wire-level 行为" | ✅ 本 PR 不再添加任何"telemetry 控制 wire 行为"的代码路径;wire 行为统一由 `outboundCorrelation.*` 管 |
| "split is mechanical, work isn't wasted" | ✅ R3 落地代码物理删除自本 branch,留在 git history 里给 follow-up PR 复用(或 cherry-pick) |
### 12.7 follow-up PR 大纲(信息性,不在本 PR 范围)
未来 follow-up PR 应包含:
- `outboundCorrelation.sessionIdHeader: { enabled, trustedHosts }` 或类似 setting
- 复用 R3 已实现的 `wrapFetchWithCorrelation` / `matchesTrustedHost` / `DEFAULT_SESSION_ID_HEADER_HOSTS` 代码骨架
- threat model 一节,明确:recipient 集合、稳定 id 的去匿名化窗口、可选 per-request UUID 配套
- **默认 off**(无 default allowlist —— 比 R3 更严,符合 LazzyMan 的开源 CLI 原则)
- security-relevant 标注 + docs/users/configuration/settings.md 收录

View File

@ -18,8 +18,9 @@ qwen-code 目前仅有面向 Arena 多模型对比场景的内部 worktree 实
| Post-creation setup(hooks 配置) | ❌ | ✅ | Phase C |
| StatusLine worktree 状态展示 | ❌ | ✅ | Phase C |
| WorktreeExitDialog(退出提示) | ❌ | ✅ | Phase C |
| `--worktree` CLI 启动标志 | ❌ | ✅ | Phase D |
| 符号链接目录(node_modules 等) | ❌ | ✅ | Phase D |
| `--worktree` CLI 启动标志 | ✅(Phase D) | ✅ | — |
| 符号链接目录(node_modules 等) | ✅(Phase D) | ✅ | — |
| PR 引用(`--worktree=#123`) | ✅(Phase D) | ✅ | — |
| sparse checkout | ❌ | ✅ | Future |
| tmux 集成 | ❌ | ✅ | Future |
| Arena 多模型 worktree 隔离 | ✅(qwen 独有) | ❌ | — |
@ -56,12 +57,13 @@ Arena 的 worktree 路径由 `agents.arena.worktreeBaseDir` 控制,默认 `~/.
### 扩展配置
| 配置项 | 类型 | 用途 | 阶段 |
| ----------------------------- | ---------- | -------------------------------------------------------------- | ------- |
| `worktree.symlinkDirectories` | `string[]` | 符号链接指定目录(如 `node_modules`)到 worktree,避免磁盘浪费 | Phase D |
| `worktree.sparsePaths` | `string[]` | git sparse-checkout cone 模式,大型 monorepo 只写入指定路径 | Future |
| 配置项 | 类型 | 用途 | 阶段 |
| --------------------------------- | ---------- | ---------------------------------------------------------------- | ------- |
| `ui.hideBuiltinWorktreeIndicator` | `boolean` | 隐藏 Footer 中内置 `⎇ worktree-… (…)` 行,留给 custom statusline | Phase C |
| `worktree.symlinkDirectories` | `string[]` | 符号链接指定目录(如 `node_modules`)到 worktree,避免磁盘浪费 | Phase D |
| `worktree.sparsePaths` | `string[]` | git sparse-checkout cone 模式,大型 monorepo 只写入指定路径 | Future |
Phase A / B / C 不新增任何配置项。
Phase A / B 不新增任何配置项。
## 工具设计
@ -233,32 +235,154 @@ _WorktreeExitDialog:_
---
### Phase D:启动时配置(`--worktree` CLI 标志 + 目录符号链接)
### Phase D:启动时配置(`--worktree` CLI 标志 + 目录符号链接 + PR 引用)
**目标:** 支持在启动时直接进入 worktree,并通过目录符号链接减少大型项目的磁盘开销。
**目标:** 支持在启动时直接进入 worktree、通过目录符号链接减少大型项目的磁盘开销,以及通过 PR 引用快速基于一个 pull request 创建 worktree。
**要实现的功能:**
**范围:** 三个功能在一个阶段一起落地,因为它们都挂在同一个启动入口上,且 symlink / PR fetch 两者都需要在 worktree 创建之后立即执行 — 单独拆分会重复改 bootstrap 序列。
_`--worktree [name]` CLI 启动标志:_
#### D-1:`--worktree [name]` CLI 启动标志
- `packages/cli/src/args.ts` 新增 `--worktree [name]` 参数
- 启动流程在进入主循环前调用 `createUserWorktree()`,将 `targetDir` 设为 worktree 路径,并写入 SessionService 状态
- 整个会话从启动即在 worktree 环境中运行,退出时触发 WorktreeExitDialog
**参数形态:** yargs 选项接受三种形式:
_`worktree.symlinkDirectories` 配置项:_
| 形式 | 行为 |
| ------------------------- | ---------------------------------------------------- |
| `qwen --worktree` | bare flag,自动生成 slug(`{形容词}-{名词}-{6hex}`) |
| `qwen --worktree my-name` | 显式 slug,沿用 `EnterWorktreeTool` 的 slug 校验规则 |
| `qwen --worktree=my-name` | 等价于上一种 |
- settings schema 新增 `worktree.symlinkDirectories: string[]`
- `createUserWorktree()` 后遍历配置,调用 `fs.symlink()` 将主仓库目录链接进 worktree
- 跳过目标不存在的项;目标已存在时跳过(不覆盖)
不提供短别名 `-w`(qwen-code 短别名只保留给最高频参数,避免命名冲突)。
**影响文件:**
**启动序列:** worktree 在以下位置创建:
| 文件 | 变更类型 |
| -------------------------------------------------- | ------------------------------------------- |
| `packages/cli/src/args.ts` | 新增 `--worktree [name]` 参数 |
| `packages/cli/src/main.ts`(或启动入口) | 解析 `--worktree` 并在主循环前创建 worktree |
| `packages/core/src/services/gitWorktreeService.ts` | `createUserWorktree()` 后追加 symlink 逻辑 |
| `packages/core/src/config/`(settings schema) | 新增 `worktree.symlinkDirectories` 字段 |
1. `parseArguments()` 解析 argv(已有)
2. resume picker(已有,line 588-629 of `gemini.tsx`)
3. `loadCliConfig()` 初始化 Config + auth(已有,line 643-653)
4. **新增:** 若 `argv.worktree !== undefined`,调用 `createUserWorktree()`
- 写入 sidecar(`writeWorktreeSession()`)
- 设置 `process.chdir(worktreePath)` 同时 `Config.setTargetDir(worktreePath)`
- 同一 worktree 的 re-attach 路径:跳过 `git worktree add` 并就地 chdir(Phase 6 修复)。跨 projectHash 的 `--resume` × `--worktree` 组合在 session lookup 阶段会失败,详见下文"与 `--resume` 的优先级"。
5. 主循环(TUI / headless `-p` / ACP 三种入口都要走第 4 步)
**与 Phase A 简化的差异:** Phase A 的 `EnterWorktreeTool` **不**修改 `Config.targetDir`,依赖模型从工具结果里读到绝对路径并继续使用。Phase D 的 CLI flag 在启动期就生效,没有运行中的模型上下文需要兼容,所以**直接切换 `targetDir` 和 `process.cwd()`** —— 这是更强的隔离保证。两条路径行为不同,需要在用户文档里说明。
**退出行为:** 复用现有 `WorktreeExitDialog`(Phase C 已实现)。Ctrl+C/D 两次触发 → 用户在 keep / remove / cancel 之间选择。不需要新代码路径。
**与 `--resume` 的优先级:**
由于 session 存储以 `projectHash(process.cwd())` 为 key,而 `--worktree` 在 resume picker / `loadCliConfig` 之前就 chdir 到 worktree,所以"在 worktree X 启动的 session,从 worktree Y 内 resume"是**架构上不可达**的(两者的 projectHash 不同,session 文件落在不同目录)。下表反映 D-1 实现 + Phase 6 re-attach 修复后的实际行为:
| `--resume` 状态 | `--worktree` 状态 | 结果 |
| ---------------------------- | -------------------------- | ------------------------------------------------------------------------------------------ |
| 无 | 无 | 普通会话,无 worktree |
| 无 | 有(新 slug) | 新建 worktree |
| 无 | 有(已存在的 slug) | **re-attach** 到已有 worktree(Phase 6 修复) |
| 有 | 无 | 恢复旧 worktree(Phase C 行为,sidecar 命中则注入 reminder) |
| 有(sid 出自同一 worktree) | 有(同一 slug,re-attach) | re-attach + session 命中:正常 resume |
| 有(sid 出自 main checkout) | 有(任意 slug) | **session lookup 失败**:`No saved session found with ID …`,exit 1。documented limitation |
| 有(sid 出自 worktree X) | 有(slug Y, X != Y) | 同上,session 跨 projectHash 不可寻 |
跨 projectHash override 的语义(`--worktree` 在不同 worktree / 主 checkout 的 session 之间转移)需要 storage 锚定到 repo root 而非 cwd-derived projectHash,属于未来 Config 重构范畴。`persistStartupWorktreeSidecar` 内的 `overrodeResumedWorktree` 分支代码保留是为该重构落地后能自动生效,目前在生产路径不会触发。
#### D-2:`worktree.symlinkDirectories` 配置项
**schema:**
```jsonc
{
"worktree": {
"symlinkDirectories": ["node_modules", "dist", ".turbo"],
},
}
```
- 类型:`string[]`,默认 `undefined`(不开启,opt-in)
- 顶层 namespace `worktree` 是新增的(在 `settingsSchema.ts` 中按字母序插在 `tools` 与 `ui` 之间)
- 路径**相对于主仓库根**,绝对路径或包含 `..` 的路径被路径遍历守卫拒绝
**作用范围:** 所有由通用层创建的 worktree,包括:
- `EnterWorktreeTool`(Phase A)
- `AgentTool` `isolation: 'worktree'`(Phase B)
- `--worktree` CLI flag(Phase D-1)
Arena 的 worktree 不走通用层,**不**受此配置影响。
**实现位置:** `GitWorktreeService.performPostCreationSetup()` —— 紧跟现有的 `configureHooksPath()`(Phase C 已建立的模式)。新增 `symlinkConfiguredDirectories()` 方法,遍历配置项调用 `fs.symlink(absSource, absDest, 'dir')`。
**错误处理(fail-open):**
| 场景 | 行为 |
| ----------------------------- | ------------------------------ |
| 源目录不存在(ENOENT) | 静默跳过,debug log |
| 目标路径已存在(EEXIST) | 静默跳过,debug log(不覆盖) |
| 路径遍历(`../`、绝对路径等) | 拒绝该项,debug log warn |
| 其他 I/O 错误 | debug log warn,继续处理后续项 |
worktree 创建本身**不会**因为 symlink 失败而中止 —— 与 `configureHooksPath()` 相同的"best-effort post-creation setup"原则。
#### D-3:PR 引用解析(`--worktree=#<N>` / 全 URL)
**支持形式:**
| 形式 | 解析后的 PR 号 |
| --------------------------------------------------------------- | -------------- |
| `--worktree=#123` | 123 |
| `--worktree '#123'` | 123 |
| `--worktree https://github.com/foo/bar/pull/123` | 123 |
| `--worktree https://gh.enterprise.com/foo/bar/pull/123?baz=qux` | 123 |
**slug 与分支命名:**
- slug:`pr-<N>`(特殊保留前缀,与用户 slug 区分)
- 分支:`worktree-pr-<N>`(沿用 qwen-code 现有 `worktree-<slug>` 命名规则;不采用 claude-code 的 `pr-<N>` 直接命名,避免与本地 `pr-<N>` 分支冲突)
**fetch 策略:**
```
git fetch origin pull/<N>/head
→ 用 FETCH_HEAD 作为新 worktree 的 base
```
不依赖 `gh` CLI —— 纯 git fetch,支持任何 GitHub 实例(公网或企业版),只要 `origin` 远程指向 GitHub。
**错误路径:**
| 场景 | 错误消息 |
| ------------------------ | ---------------------------------------------------------------------------- |
| `origin` 远程缺失 | `--worktree=#<N> requires an "origin" remote that points at GitHub.` |
| `git fetch` 失败 | `Failed to fetch PR #<N>: PR may not exist or origin remote is unreachable.` |
| 网络超时(30s) | 同上,加 `(timeout)` |
| `origin` 远程不是 GitHub | 不做主动检查,由 `git fetch` 自然失败(PR 协议是 GitHub 特有的) |
**与 D-2 的关系:** PR worktree **同样**应用 `symlinkDirectories`(用户期望在 PR 上立刻能跑测试,依赖目录需要复用)。
#### 影响文件
| 文件 | 变更类型 |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `packages/cli/src/config/config.ts` | yargs 新增 `--worktree` 选项;`CliArgs` 接口加 `worktree?: string \| boolean` |
| `packages/cli/src/gemini.tsx` | `loadCliConfig()` 之后、主循环之前调用新的 `setupStartupWorktree()` helper |
| `packages/cli/src/startup/worktreeStartup.ts` | 新建:`setupStartupWorktree()` 处理 slug 解析、PR fetch、sidecar 写入、cwd 切换 |
| `packages/cli/src/nonInteractiveCli.ts` | 复用同一 helper(已有 `restoreWorktreeContext` 注入逻辑,无须改) |
| `packages/cli/src/acp-integration/acpAgent.ts` | 复用同一 helper |
| `packages/core/src/services/gitWorktreeService.ts` | 新增 `parsePRReference()`、`fetchPullRequestRef()`、`symlinkConfiguredDirectories()`;`createUserWorktree()` 接受可选 `baseBranchRef` 参数 |
| `packages/cli/src/config/settingsSchema.ts` | 新增 `worktree.symlinkDirectories: string[]` 顶层项 |
| `packages/vscode-ide-companion/schemas/settings.schema.json` | 重新生成 |
| `docs/users/features/worktree.md` | 新增 Quick Start CLI flag 章节、Settings 表新增一行 |
#### 安全与回滚
- **fail-open vs fail-close:** symlink / hooks 失败 **不** 中止 worktree 创建(同 Phase C 既定模式);PR fetch 失败 **中止** 启动(无 base ref 就无法创建 worktree);slug 校验失败 **中止** 启动(与 `EnterWorktreeTool` 一致)。
- **path traversal:** `symlinkDirectories` 项必须解析后仍在 `repoRoot` 内,否则拒绝该项并 log。
- **PR fetch 超时:** 30 秒硬超时,避免无响应的网络拖死启动。
- **cwd 切换的副作用:** 切 `process.cwd()` 之后,相对路径(如 `--prompt-file ./foo.txt`)的解析会受影响。**对策:** 在切 cwd 之前先解析所有相对路径参数(具体在 `setupStartupWorktree()` 入口处做一次 normalize)。
#### 开放问题
1. **`--worktree-keep-on-exit`?** claude-code 没有,qwen-code 是否需要一个 CLI flag 让 Exit Dialog 默认选 keep?建议**先不加**,等用户反馈。
2. **`worktree.symlinkDirectories` 是否需要 per-project override?** 当前 settings 已经支持 user/workspace/project 三级合并,无需特殊处理。
3. **PR fetch 是否要拉取 `merge` ref(`pull/<N>/merge`,即与 base 合并后的 ref)而非 `head`?** claude-code 选 `head`,理由是用户通常想看 PR 的实际改动。沿用此选择。
---
@ -266,9 +390,8 @@ _`worktree.symlinkDirectories` 配置项:_
以下功能面向更特定的使用场景,当前阶段不纳入排期,待用户需求明确后再评估实现。
| 功能 | 说明 |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| sparse checkout | `worktree.sparsePaths` 配置项,大型 monorepo 只 checkout 指定路径,缩短创建时间和磁盘占用 |
| `.worktreeinclude` 文件 | 将 gitignore 的文件(`.env`、`secrets.json` 等)自动复制进 worktree |
| tmux 集成 | `--worktree --tmux` 在新 tmux 窗口启动 worktree 会话 |
| PR 引用解析 | `--worktree=#123` 自动 fetch PR 分支并基于它创建 worktree(依赖 Phase D `--worktree` 标志) |
| 功能 | 说明 |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| sparse checkout | `worktree.sparsePaths` 配置项,大型 monorepo 只 checkout 指定路径,缩短创建时间和磁盘占用 |
| `.worktreeinclude` 文件 | 将 gitignore 的文件(`.env`、`secrets.json` 等)自动复制进 worktree |
| tmux 集成 | `--worktree --tmux` 在新 tmux 窗口启动 worktree 会话 |

View File

@ -0,0 +1,96 @@
# TUI Daemon Adapter Draft
## Goal
Add a flag-gated TUI transport that talks to `qwen serve` through
`DaemonSessionClient` instead of creating an in-process `Config` + agent
runtime.
This is a dogfood path for Mode B client migration. It must not replace the
default TUI path until output sinks, typed daemon events, session-scoped
permission, and lifecycle diagnostics are stable.
## Proposed Entry Point
```bash
QWEN_DAEMON_URL=http://127.0.0.1:4170 qwen --experimental-daemon-tui
```
Optional:
```bash
QWEN_DAEMON_TOKEN=... QWEN_DAEMON_WORKSPACE=/repo qwen --experimental-daemon-tui
```
The CLI should refuse this mode unless both are true:
- `QWEN_DAEMON_URL` or `--daemon-url` is set.
- `GET /capabilities` advertises `session_create`, `session_prompt`, and
`session_events`.
## Minimal Flow
1. Create `DaemonClient` with daemon URL and token.
2. Fetch `/capabilities`.
3. Create or attach with `DaemonSessionClient.createOrAttach()`.
4. Subscribe to `session.events()`.
5. Submit user prompts through `session.prompt()`.
6. Route cancel through `session.cancel()`.
7. Route model switch through `session.setModel()`.
8. Route permission votes through `session.respondToPermission()`.
## Rendering Contract
The first implementation adds `DaemonTuiAdapter`, a locally verifiable reducer
and transport spike. It maps only these daemon events:
| Daemon event | TUI handling |
| ---------------------------------------- | -------------------------------------------- |
| `session_update` / `agent_message_chunk` | Append assistant text |
| `session_update` / `agent_thought_chunk` | Append thinking text |
| `session_update` / `tool_call` | Show tool call lifecycle |
| `permission_request` | Show existing confirmation UI where possible |
| `permission_resolved` | Close or update confirmation UI |
| `model_switched` | Update footer/model display |
| `session_died` | Show disconnected state and stop streaming |
Unknown events must be ignored, not fatal. Typed event reducers will land in a
later protocol PR.
The adapter is not wired into the default Ink app yet. Existing interactive TUI,
JSONL, stream-json, and dual-output behavior remains unchanged.
## Explicit Non-Goals
- Do not remove the current TUI in-process runtime.
- Do not change JSONL, stream-json, or dual-output behavior in this PR.
- Do not expose file CRUD, MCP management, memory CRUD, or provider/auth
mutation through TUI yet.
- Do not make browser/web direct-to-daemon assumptions; this is terminal only.
## Merge Safety
- Default off.
- Additive code path.
- No existing CLI flags change behavior.
- If the daemon is unavailable, the experimental path fails before starting the
TUI and tells the user to run `qwen serve`.
## Validation Plan
- Unit-test event-to-TUI-state mapping with synthetic daemon events.
- Unit-test prompt, cancel, model switch, and permission vote forwarding.
- Unit-test flag/env parsing when the feature flag is wired.
- Smoke-test against a local `qwen serve`:
- prompt text streams into the TUI
- cancel resolves the active prompt
- permission request can be accepted or rejected
- reconnect sends the tracked `Last-Event-ID`
## Blockers Before Default Migration
- Typed daemon event schema.
- Session-scoped permission route.
- Output sink refactor for JSONL / stream-json / dual-output parity.
- Session lifecycle close/delete semantics.
- Runtime diagnostics for MCP, skills, providers, and workspace env.

View File

@ -1,118 +0,0 @@
# Daemon Web UI Adapter
## Goal
Web chat and web terminal clients should consume `qwen serve` through the
daemon HTTP/SSE APIs and render a client-side transcript. Native local TUI,
channel, and IDE integrations keep their existing default paths for now.
## Shared UI Contract
Use the TypeScript SDK daemon UI exports as the common boundary:
```ts
import {
DaemonClient,
DaemonSessionClient,
createDaemonTranscriptStore,
normalizeDaemonEvent,
} from '@qwen-code/sdk/daemon';
```
The split is:
- `DaemonClient` handles daemon HTTP routes.
- `DaemonSessionClient` owns session creation/attachment and SSE replay.
- `normalizeDaemonEvent()` converts daemon wire events into UI events.
- `createDaemonTranscriptStore()` reduces UI events into transcript blocks.
React clients can use the optional `@qwen-code/webui` binding:
```tsx
import {
DaemonSessionProvider,
useDaemonActions,
useDaemonConnection,
useDaemonPendingPermissions,
useDaemonTranscriptBlocks,
} from '@qwen-code/webui';
```
Minimal React shape:
```tsx
function App() {
return (
<DaemonSessionProvider baseUrl="http://127.0.0.1:4170">
<Transcript />
<PromptBox />
</DaemonSessionProvider>
);
}
function Transcript() {
const blocks = useDaemonTranscriptBlocks();
return blocks.map((block) => <RenderBlock key={block.id} block={block} />);
}
```
The provider creates or attaches a daemon session, subscribes to SSE, keeps the
last event id on `DaemonSessionClient`, and reconnects the stream by default.
Callers can disable that with `autoReconnect={false}` for tests or custom
connection management.
## Browser Deployment Shapes
### Same-Origin Local POC
A daemon-served page can call the daemon directly because the page and API share
one origin. This is the preferred early POC shape for local web chat and web
terminal validation.
### Remote Web Chat / Web Terminal
A production remote web app should normally talk to a backend-for-frontend. The
BFF owns daemon URL, token, workspace routing, and session metadata, then
forwards browser-safe app events to the browser. This keeps bearer tokens out of
browser storage and lets the deployment decide which daemon/workspace a user is
allowed to reach.
### Local Browser Against Local Daemon
A separate local dev server is cross-origin from `qwen serve`; it must either
proxy daemon routes through the same origin or be served by the daemon. The
daemon intentionally rejects arbitrary browser `Origin` requests.
## Rendering Responsibilities
The shared transcript model is semantic, not visual. UI clients decide how to
render:
- user and assistant message blocks
- collapsed thought blocks
- tool status cards
- shell output blocks
- permission request controls
- status/error/debug blocks
The web terminal is a browser-native semantic renderer. It should look and feel
terminal-like with monospace layout, scrollback, prompt input, shortcuts, and
streaming blocks, but it is not a raw PTY proxy and does not require server-side
Ink rendering.
## Merge Safety
- The native `qwen` TUI remains direct and unchanged.
- `--acp`, channel, and IDE paths remain unchanged by default.
- The SDK UI core is additive.
- The WebUI React binding is optional and only runs in clients that import it.
- Removed daemon TUI spike code should not be treated as a product migration.
## Follow-Ups
- Add a daemon-served local `/web` POC or equivalent same-origin web app.
- Build first-class chat and terminal renderers on top of transcript blocks.
- Add richer typed events only where existing daemon events are too low-level
for stable browser UI behavior.
- Consider a dedicated `@qwen-code/daemon-ui-core` package if non-SDK consumers
need the UI core as an independent dependency.

View File

@ -1,337 +0,0 @@
# Migrating to `@qwen-code/sdk/daemon` v2
PR #4328 shipped the v1 daemon UI layer. PR #4353 (this PR) ships v2 with
seven additive feature commits. This guide walks through the changes for web
chat and web terminal adapter authors first. Native local TUI, channel, and IDE
maintainers can reuse the same primitives later, but those default product paths
are not migrated by this PR.
## TL;DR for existing consumers
**No breaking changes.** Every commit in this PR is additive:
- v1 fields still work (`createdAt` preserved as `@deprecated` alias for
`clientReceivedAt`)
- v1 normalizer still maps the same 13 event types the same way
- v1 reducer still produces the same blocks for chat events
- New API is opt-in via additional parameters and helpers
The PR is safe to merge without any consumer changes. **Adoption of the
new features is incremental.**
## Recommended adoption order
For each adapter, in order of effort/value ratio:
### 1. Ordering: switch sort key from `createdAt` to `eventId`
**Before:**
```ts
const ordered = [...state.blocks].sort((a, b) => a.createdAt - b.createdAt);
```
**After:**
```ts
import { selectTranscriptBlocksOrderedByEventId } from '@qwen-code/sdk/daemon';
const ordered = selectTranscriptBlocksOrderedByEventId(state);
```
**Why**: `eventId` is daemon-monotonic; survives SSE replay-after-reconnect.
`createdAt` is client clock and shifts under replay.
### 2. Display: switch `createdAt` to `serverTimestamp ?? clientReceivedAt`
**Before:**
```tsx
<TimeLabel ms={block.createdAt} />
```
**After:**
```tsx
import { formatBlockTimestamp } from '@qwen-code/sdk/daemon';
<TimeLabel text={formatBlockTimestamp(block, { locale })} />;
```
**Why**: Multiple clients see consistent "X minutes ago" only when both
read daemon clock. Renderer plus `formatBlockTimestamp` handles tz +
locale.
**Note**: Daemon needs to stamp `_meta.serverTimestamp` on envelopes for
this to take effect. SDK forward-compat-ready; falls back to
`clientReceivedAt` until then.
### 3. Listen for new event types — pick subset to render
The 16 new event types (session-meta, workspace, auth) don't push transcript
blocks. They are sidechannel observations. Each adapter picks which to surface:
```ts
// In your SSE consumer
const uiEvents = normalizeDaemonEvent(envelope, {
clientId,
suppressOwnUserEcho: true,
});
store.dispatch(uiEvents);
// Then in your UI side
for (const event of uiEvents) {
switch (event.type) {
case 'session.approval_mode.changed':
myApprovalModeBadge.update(event.next);
break;
case 'workspace.mcp.budget_warning':
myToast.show(
`MCP servers approaching budget: ${event.liveCount}/${event.budget}`,
);
break;
case 'auth.device_flow.started':
myAuthModal.show({
deviceFlowId: event.deviceFlowId,
providerId: event.providerId,
expiresAt: event.expiresAt,
});
break;
// ... etc, opt into what your UI needs
}
}
```
Or use selectors for state-mirrored sidechannels:
```ts
import { selectApprovalMode, selectCurrentTool } from '@qwen-code/sdk/daemon';
const mode = selectApprovalMode(state); // mirrored from approval_mode.changed
const currentTool = selectCurrentTool(state); // current in-flight tool
```
### 4. Render contract: use `daemonBlockToMarkdown` (or HTML / plainText)
**Before** (each adapter does its own projection):
```ts
function blockToString(block: DaemonTranscriptBlock): string {
switch (block.kind) {
case 'user':
return `You: ${block.text}`;
case 'assistant':
return block.text;
case 'tool':
return `[${block.title}]\n${block.status}`;
// ... etc
}
}
```
**After** (delegate to SDK):
```ts
import { daemonBlockToMarkdown } from '@qwen-code/sdk/daemon';
const md = daemonBlockToMarkdown(block);
```
For HTML SSR:
```ts
import MarkdownIt from 'markdown-it';
import DOMPurify from 'dompurify';
const html = DOMPurify.sanitize(md.render(daemonBlockToMarkdown(block)));
```
For plain text:
```ts
import { daemonBlockToPlainText } from '@qwen-code/sdk/daemon';
const plain = daemonBlockToPlainText(block);
```
### 5. Conformance test
Add to your adapter's test suite:
```ts
import { runAdapterConformanceSuite } from '@qwen-code/sdk/daemon';
it('adapter projects daemon UI corpus correctly', () => {
const result = runAdapterConformanceSuite({
reduce: (events) => myReduce(events),
renderToText: (state) => myRender(state),
});
expect(result.failed).toEqual([]);
});
```
This will run your adapter against 10 fixture scenarios and surface any
projection drift before it reaches users.
### 6. Tool icon dispatch via `provenance`
**Before** (string match on toolName):
```tsx
const isMcp = toolName?.startsWith('mcp__');
const isBuiltin = ['Bash', 'Edit', 'Read'].includes(toolName);
```
**After** (typed provenance from PR-A):
```tsx
import type { DaemonUiToolUpdateEvent } from '@qwen-code/sdk/daemon';
function toolIcon(event: DaemonUiToolUpdateEvent): React.ReactNode {
switch (event.provenance) {
case 'mcp':
return <McpIcon server={event.serverId} />;
case 'subagent':
return <SubagentIcon />;
case 'builtin':
return <BuiltinIcon name={event.toolName} />;
case 'unknown':
default:
return <GenericIcon />;
}
}
```
SDK has a `mcp__<server>__<tool>` naming heuristic fallback — works today
even when daemon doesn't explicitly stamp provenance.
### 7. Error categorization via `errorKind`
**Before** (regex on text):
```ts
if (error.text.includes('auth')) showAuthRetry();
else if (error.text.includes('file not found')) showFilePicker();
```
**After** (closed enum from PR-A):
```ts
import type { DaemonErrorKind } from '@qwen-code/sdk/daemon';
function errorAction(errorKind?: DaemonErrorKind): React.ReactNode {
switch (errorKind) {
case 'auth_env_error': return <RetryAuthButton />;
case 'missing_file': return <FilePicker />;
case 'blocked_egress': return <CheckProxyHint />;
case 'init_timeout': return <RestartDaemonButton />;
default: return null;
}
}
```
**Note**: Daemon needs to stamp `data.errorKind` on session_died /
stream_error for this to populate. SDK already reads it.
### 8. Cancellation handling — already automatic
In v1, cancelled prompts left in-flight tool blocks spinning forever.
In v2 (PR-E), `propagateCancellationToInFlightTools` runs automatically
on `assistant.done.reason === 'cancelled'`. Sub-agent children are
cancelled together with their parent.
**No adapter changes needed** — your spinners will resolve correctly.
### 8a. Sub-agent nesting — opt in to nested rendering (PR-K)
Tool blocks invoked inside a sub-agent delegation now carry
`parentToolCallId`, `subagentType`, and (when the parent is in state)
`parentBlockId`. Adapters can opt in to nested rendering:
**Before** (flat list, sub-agent calls visually indistinguishable from
top-level):
```tsx
state.blocks.map((b) => <ToolBlock block={b} />);
```
**After** (recursive nested rendering):
```tsx
import {
selectSubagentChildBlocks,
isSubagentChildBlock,
} from '@qwen-code/sdk/daemon';
function renderTool(block) {
const children = selectSubagentChildBlocks(state, block.toolCallId);
return (
<ToolBlock block={block}>
{block.subagentType && <SubagentBadge type={block.subagentType} />}
{children.length > 0 && <Indent>{children.map(renderTool)}</Indent>}
</ToolBlock>
);
}
const topLevel = state.blocks.filter((b) => !isSubagentChildBlock(b));
return topLevel.map(renderTool);
```
**No adapter changes needed if you prefer the flat view** — the new
fields are additive and ignored by code that doesn't read them.
### 9. Tool preview taxonomy — pick subset to render with custom components
PR-D + PR-F bring 13 preview kinds:
- 4 file-shaped: `file_diff`, `file_read`, `web_fetch`, `mcp_invocation`
- 5 content-shaped: `code_block`, `search`, `tabular`, `image_generation`, `subagent_delegation`
- 2 control: `ask_user_question`, `command`
- 2 generic: `key_value`, `generic`
Each adapter dispatches on `preview.kind`:
```tsx
function ToolPreviewComponent({ preview }: { preview: DaemonToolPreview }) {
switch (preview.kind) {
case 'file_diff':
return (
<UnifiedDiffView
path={preview.path}
old={preview.oldText}
new={preview.newText}
/>
);
case 'mcp_invocation':
return (
<McpCard serverId={preview.serverId} toolName={preview.toolName} />
);
case 'tabular':
return <DataTable columns={preview.columns} rows={preview.rows} />;
case 'image_generation':
return (
<ImagePreview
thumbnailUrl={preview.thumbnailUrl}
prompt={preview.prompt}
/>
);
// ... or fall back to:
default:
return <Markdown text={daemonToolPreviewToMarkdown(preview)} />;
}
}
```
Adapters without custom components for all 13 kinds can fall back to the
SDK's `daemonToolPreviewToMarkdown` for any unhandled kind.
## Backward-compat checklist
| Concern | Status |
| ------------------------------------------------------ | --------------------------------------------- |
| Existing `block.createdAt` reads | ✅ still works (alias for `clientReceivedAt`) |
| Existing reducer event handling | ✅ unchanged for v1 event types |
| `daemonTranscriptToUnifiedMessages(blocks)` call sites | ✅ new options param is optional |
| Existing `selectTranscriptBlocks` consumers | ✅ unchanged |
| New event types in v1 reducer | ✅ no-op, `lastEventId` still advances |
## Cross-references
- [PR #4353 SUMMARY](https://github.com/QwenLM/qwen-code/pull/4353)
- [Daemon UI README](./README.md) — full API reference
- [PR #4328](https://github.com/QwenLM/qwen-code/pull/4328) — base PR with shared UI transcript layer

View File

@ -1,391 +0,0 @@
# Daemon UI SDK — Developer Guide
The `@qwen-code/sdk/daemon` subpath ships shared UI primitives for daemon
clients. The current adoption target is web chat and web terminal; native local
TUI, channel, and IDE integrations keep their existing default paths while the
daemon UI contract stabilizes. This guide covers the API surface introduced by
PR #4353 (the unified follow-up to PR #4328's shared UI transcript layer).
## Three-layer model
```
Daemon SSE wire (NDJSON envelopes)
│
▼
normalizeDaemonEvent(envelope) → DaemonUiEvent[]
│
▼
reduceDaemonTranscriptEvents(state, events) → DaemonTranscriptState
│ { blocks, currentToolCallId,
│ approvalMode, toolProgress, ... }
▼
daemonBlockToMarkdown(block) / ToHtml / ToPlainText ← your renderer plugs here
```
- **Normalizer**: takes raw daemon SSE envelopes, returns typed UI events
- **Reducer**: accumulates events into a transcript state machine
- **Render helpers**: project state blocks to renderable strings
## Quick start
```ts
import {
DaemonSessionClient,
createDaemonTranscriptStore,
normalizeDaemonEvent,
daemonBlockToMarkdown,
selectCurrentTool,
selectApprovalMode,
} from '@qwen-code/sdk/daemon';
const session = await DaemonSessionClient.createOrAttach(client, {
workspaceCwd,
});
const store = createDaemonTranscriptStore();
for await (const envelope of session.events({ signal })) {
const events = normalizeDaemonEvent(envelope, {
clientId: session.clientId,
suppressOwnUserEcho: true,
});
store.dispatch(events);
}
// Read state from any subscriber
store.subscribe(() => {
const state = store.getSnapshot();
const currentTool = selectCurrentTool(state);
const mode = selectApprovalMode(state);
const markdown = state.blocks.map(daemonBlockToMarkdown).join('\n\n');
myRenderer.render({ markdown, currentTool, mode });
});
```
## Event taxonomy (28+ types)
`DaemonUiEvent` is a discriminated union of all UI-facing events:
### Chat-stream events
| Event | When |
| ---------------------------- | ----------------------------------------------------- |
| `user.text.delta` | User message chunk arrives from daemon |
| `assistant.text.delta` | Assistant streaming chunk |
| `assistant.done` | Prompt completion (from sendPrompt resolve) |
| `thought.text.delta` | Agent reasoning chunk |
| `tool.update` | Tool call lifecycle (running / completed / cancelled) |
| `shell.output` | Shell tool stdout/stderr chunk |
| `permission.request` | Tool needs user authorization |
| `permission.resolved` | Permission decision arrived |
| `model.changed` | Session model switched |
| `status` / `debug` / `error` | Status / debug / error blocks |
### Session-meta events (PR-A)
| Event | When |
| ------------------------------- | ------------------------------------------------ |
| `session.metadata.changed` | Session title / display name updated |
| `session.approval_mode.changed` | Mode toggled (plan / default / yolo / auto-edit) |
| `session.available_commands` | Slash command list refreshed |
### Workspace events (PR-A, Wave 3-4)
| Event | When |
| -------------------------------------- | ------------------------------------- |
| `workspace.memory.changed` | QWEN.md / memory file modified |
| `workspace.agent.changed` | Sub-agent created / updated / deleted |
| `workspace.tool.toggled` | Builtin tool enabled / disabled |
| `workspace.initialized` | `qwen init` completed |
| `workspace.mcp.budget_warning` | MCP child count approaching cap |
| `workspace.mcp.child_refused` | MCP server refused due to budget |
| `workspace.mcp.server_restarted` | Manual MCP restart succeeded |
| `workspace.mcp.server_restart_refused` | Manual restart blocked |
### Auth device-flow events (PR-A, Wave 4 OAuth)
`auth.device_flow.{started,throttled,authorized,failed,cancelled}`
Each carries the daemon's `deviceFlowId`. Failed events carry a closed-enum
`errorKind` (closed enum — see `KNOWN_DEVICE_FLOW_ERROR_KINDS` exported from `@qwen-code/sdk/daemon` for the canonical list, currently: `expired_token` / `access_denied` / `invalid_grant` / `upstream_error` / `persist_failed` / `not_found_or_evicted`).
## Render contract (PR-D)
Three projection helpers, one preview helper. All discriminate on `block.kind`
or `preview.kind`:
```ts
daemonBlockToMarkdown(block, { sanitizeUrls?, maxFieldLength?, locale? })
daemonBlockToHtml(block, { sanitizer?, ...renderOpts })
daemonBlockToPlainText(block, renderOpts)
daemonToolPreviewToMarkdown(preview, renderOpts)
```
### Cookbook: render a transcript to markdown
```ts
const markdown = state.blocks
.map((b) => daemonBlockToMarkdown(b, { sanitizeUrls: true }))
.join('\n\n');
```
### Cookbook: render to sanitized HTML for SSR
```ts
import DOMPurify from 'dompurify';
import MarkdownIt from 'markdown-it';
const md = new MarkdownIt();
const html = state.blocks
.map((b) => {
// Two-stage pipeline: markdown → HTML → DOMPurify
const rawHtml = md.render(daemonBlockToMarkdown(b));
return DOMPurify.sanitize(rawHtml);
})
.join('\n');
```
Or use the built-in conservative HTML renderer (no markdown parsing, just
HTML escape):
```ts
const html = state.blocks
.map((b) => daemonBlockToHtml(b, { sanitizer: DOMPurify.sanitize }))
.join('\n');
```
### Cookbook: copy-paste plain text
```ts
const plain = state.blocks.map(daemonBlockToPlainText).join('\n');
navigator.clipboard.writeText(plain);
```
## Tool preview taxonomy (13 kinds)
| Kind | Surface |
| --------------------- | ------------------------------------------------- |
| `ask_user_question` | Multi-choice question with options |
| `command` | Bash-style command + cwd |
| `file_diff` | File edit with oldText/newText or patch |
| `file_read` | Path + optional line range |
| `web_fetch` | URL + HTTP method |
| `mcp_invocation` | MCP server + tool + args summary |
| `code_block` | Language-tagged code snippet |
| `search` | Query + result count + top results |
| `tabular` | Columns + rows (capped at 50, truncation flagged) |
| `image_generation` | Prompt + optional thumbnail URL |
| `subagent_delegation` | Agent name + task |
| `key_value` | Generic label/value rows |
| `generic` | Fallback summary |
Each has a `daemonToolPreviewToMarkdown` projection. Custom renderers can
dispatch on `preview.kind` for rich per-type display (file diff with
syntax highlighting, MCP server badge, image thumbnail, etc.).
## State selectors (PR-E)
```ts
selectCurrentTool(state); // → DaemonToolTranscriptBlock | undefined
selectApprovalMode(state); // → 'plan' | 'default' | 'auto-edit' | 'yolo' | undefined
selectToolProgress(state, toolCallId); // → { ratio?, step? } | undefined
selectPendingPermissionBlocks(state); // → ReadonlyArray<DaemonPermissionTranscriptBlock>
selectTranscriptBlocks(state); // → ReadonlyArray<DaemonTranscriptBlock>
selectTranscriptBlocksOrderedByEventId(state); // sorted by daemon-monotonic id
// PR-K — sub-agent nesting
selectSubagentChildBlocks(state, parentToolCallId); // direct children only
isSubagentChildBlock(block); // type guard: was this tool invoked inside a sub-agent?
```
`currentToolCallId` is automatically maintained by the reducer:
- Set when a tool enters in-flight status (`running` / `in_progress` / `pending` / `confirming`)
- Cleared when tool enters terminal status (`completed` / `failed` / `cancelled` / etc.)
- Unknown statuses leave it untouched (forward-compat)
## Cancellation propagation (PR-E)
When `assistant.done.reason === 'cancelled'`, the reducer walks every
in-flight tool block and force-sets its status to `'cancelled'`. Daemon
does not guarantee a terminal `tool_call_update` for every in-flight
tool when the parent prompt is cancelled — this propagation prevents UI
spinners from spinning forever.
Sub-agent children are cancelled together with their parent because
cancellation iterates every in-flight tool block in `toolBlockByCallId`,
not just the current pointer.
## Sub-agent nesting (PR-K)
When the main agent delegates to a sub-agent (the `Task` tool, or
equivalent), the daemon stamps `parentToolCallId` and `subagentType` on
the **child** tool calls via `tool_call._meta`. The reducer reads both
and:
- Mirrors `parentToolCallId` + `subagentType` onto
`DaemonToolTranscriptBlock`
- Resolves `parentBlockId` (the parent's transcript block `id`) when the
parent block is already in state; otherwise leaves it `undefined` and
back-fills when the parent block later appears
Out-of-order arrival (child before parent) is handled transparently. A
child whose parent gets trimmed by `maxBlocks` keeps `parentToolCallId`
for selector queries, but `parentBlockId` is nulled (the dangling id
would no longer resolve via `blockIndexById`).
```ts
import {
selectSubagentChildBlocks,
isSubagentChildBlock,
} from '@qwen-code/sdk/daemon';
// Render a parent tool block, then walk children:
function renderToolBlock(state, block) {
if (block.kind !== 'tool') return renderOther(block);
const children = selectSubagentChildBlocks(state, block.toolCallId);
return (
<ToolBlock block={block}>
{children.length > 0 && (
<Indent>
{children.map((c) => renderToolBlock(state, c))}
</Indent>
)}
</ToolBlock>
);
}
// Or filter top-level vs. nested at render time:
const topLevel = state.blocks.filter((b) => !isSubagentChildBlock(b));
```
`selectSubagentChildBlocks` returns **direct** children only. Walk
recursively to render nested sub-agents (a sub-agent inside a
sub-agent). Daemon does not emit cycles, but renderers walking up via
`parentBlockId` should still detect them defensively (e.g., depth cap or
visited set).
Self-references (`parentToolCallId === toolCallId`) are dropped by the
normalizer before reaching the reducer.
## Time semantics (PR-B)
```ts
interface DaemonTranscriptBlockBase {
eventId?: number; // PRIMARY sort key — daemon-monotonic
serverTimestamp?: number; // PREFERRED display — daemon-authoritative
clientReceivedAt: number; // FALLBACK — local clock
createdAt: number; // @deprecated alias for clientReceivedAt
}
```
**Always sort by `eventId`** (use `selectTranscriptBlocksOrderedByEventId`)
when displaying long sessions. The daemon-monotonic cursor is preserved
across SSE replay-after-reconnect; client clocks are not.
**Always format display timestamps from `serverTimestamp`** (with
fallback to `clientReceivedAt`). Multiple clients viewing the same session
see the same "5 minutes ago" only when both read from the daemon clock.
```ts
import { formatBlockTimestamp } from '@qwen-code/sdk/daemon';
const label = formatBlockTimestamp(block, {
locale: 'zh-CN',
timeZone: 'Asia/Shanghai',
timeStyle: 'short',
});
```
## Adapter conformance (PR-G)
Validate your adapter projects the SDK's reference corpus to semantically
equivalent output:
```ts
import { runAdapterConformanceSuite } from '@qwen-code/sdk/daemon';
it('my adapter conforms to daemon UI corpus', () => {
const result = runAdapterConformanceSuite({
reduce: (events) => myReducer(events),
renderToText: (state) => myRenderer(state),
});
expect(result.failed).toEqual([]);
});
```
The fixture corpus (`DAEMON_UI_CONFORMANCE_FIXTURES`) covers chat, tool
lifecycle, file edits, MCP, permissions, MCP budget warning, cancellation,
malformed payload redaction, OAuth, command updates, and sub-agent
nesting. (Count is derivable at runtime — read
`DAEMON_UI_CONFORMANCE_FIXTURES.length`.)
**Format-agnostic** — your adapter can render to ANSI / HTML / markdown /
JSX; the framework only checks semantic content via `expectedContains` and
`expectedAbsent`.
## Error categorization (PR-A)
`DaemonUiErrorEvent.errorKind` is a closed-enum propagated from the
daemon's typed-error taxonomy (when the daemon stamps it):
```ts
import type { DaemonErrorKind } from '@qwen-code/sdk/daemon';
// 'missing_binary' | 'blocked_egress' | 'auth_env_error' | 'init_timeout'
// | 'protocol_error' | 'missing_file' | 'parse_error' | 'budget_exhausted'
```
Renderers should branch on `errorKind` for actionable affordances:
```ts
function errorAffordance(errorKind?: DaemonErrorKind): React.ReactNode {
switch (errorKind) {
case 'auth_env_error': return <button>Re-authenticate</button>;
case 'missing_file': return <button>Choose file</button>;
case 'blocked_egress': return <span>Network blocked — check proxy</span>;
default: return null;
}
}
```
## Tool provenance dispatch (PR-A)
`DaemonUiToolUpdateEvent.provenance` is a closed-enum (`builtin` / `mcp` /
`subagent` / `unknown`). With `serverId?: string` when `mcp`. Use it for
icon dispatch and badging:
```ts
function toolIcon(event: DaemonUiToolUpdateEvent): React.ReactNode {
switch (event.provenance) {
case 'mcp': return <McpIcon server={event.serverId} />;
case 'subagent': return <SubagentIcon />;
case 'builtin': return <BuiltinIcon name={event.toolName} />;
default: return <GenericIcon />;
}
}
```
The SDK has a `mcp__<server>__<tool>` naming heuristic fallback — even
when daemon doesn't explicitly stamp provenance, MCP tools are detectable.
## Forward-compat principles
Every layer in the daemon UI SDK follows the **forward-compat principle**:
unknown values do NOT throw; they degrade gracefully.
- Unknown daemon event types → `debug` event with the raw type name
- Unknown tool status → `currentToolCallId` left untouched (no clear)
- Unknown error kind → `errorKind` undefined (renderer falls back to text)
- Missing serverTimestamp → falls back to `clientReceivedAt`
- Unrecognized preview shape → `generic` kind with `summary`
This means **SDK can ship ahead of daemon emission**. PR-A's tool
provenance heuristic, PR-B's three-location timestamp extraction, and
PR-E's unknown-status preservation are all examples of "ready when daemon
sends; safe when it doesn't."
## Cross-references
- [PR #4328](https://github.com/QwenLM/qwen-code/pull/4328) — base PR with the shared UI transcript layer
- [PR #4353](https://github.com/QwenLM/qwen-code/pull/4353) — this PR (unified completeness follow-up)
- [Issue #3803](https://github.com/QwenLM/qwen-code/issues/3803) — daemon mode proposal
- [Issue #4175](https://github.com/QwenLM/qwen-code/issues/4175) — Mode B v0.16 implementation tracker

View File

@ -262,6 +262,99 @@ and logs still carry `session.id`, and trace / log backends (Jaeger, Tempo,
Loki, Aliyun SLS / ARMS Tracing) handle per-session slicing natively without
cardinality pressure.
### Client-side HTTP span on outbound fetch
When telemetry is enabled, Qwen Code registers `UndiciInstrumentation`
which creates a client-side HTTP span for every outbound `fetch()`
request originated by the process — including the LLM SDKs (`openai`,
`@google/genai`, `@anthropic-ai/sdk`), the MCP StreamableHTTP client, the
`WebFetch` tool, and any IDE-extension out-of-process calls. The span
lets you see network latency (TTFB / response body transfer) separately
from upstream model processing time, which the existing
`api.generateContent` span alone can't distinguish.
These spans go to your **own** OTLP collector (or file outfile) just like
the rest of the telemetry — they do not affect what is written onto the
outbound HTTP request itself. Whether the W3C `traceparent` header is
also written into the outgoing request stream is controlled by a
**separate, security-relevant setting** documented in
[outbound correlation](#outbound-correlation-security-relevant) below.
**Feedback-loop avoidance.** OTel SDK uses `fetch` internally to upload OTLP
data. Without protection, instrumenting `fetch` would trace those uploads,
which would themselves be uploaded, causing an infinite loop. Qwen Code's
undici instrumentation is configured with an `ignoreRequestHook` that skips
URLs matching the configured `telemetry.otlpEndpoint` /
`telemetry.otlpTracesEndpoint` / `telemetry.otlpLogsEndpoint` /
`telemetry.otlpMetricsEndpoint` prefixes. In file-outfile mode there are no
outbound HTTP uploads, so the hook is a no-op.
## Outbound correlation (SECURITY-RELEVANT)
These settings live in a **separate top-level namespace** from `telemetry.*`
on purpose: telemetry controls data flow into the operator's own
observability backend, while `outboundCorrelation.*` controls what
client-side correlation data qwen-code writes **into outbound LLM API
request streams** that reach third-party LLM provider endpoints
(DashScope, OpenAI, Anthropic, etc.). Different recipients, different
consent decision. **All values default to off.** See PR #4390 review
discussion for the framing rationale.
### `outboundCorrelation.propagateTraceContext`
```jsonc
"outboundCorrelation": {
"propagateTraceContext": false // default
}
```
When `false` (default), Qwen Code installs a no-op `TextMapPropagator` on
the OTel SDK. UndiciInstrumentation still creates client HTTP spans for
your OTLP collector, but `propagation.inject()` is a no-op so **no
`traceparent` is written onto outbound requests**. Trace IDs stay
internal to the operator's collector.
When `true`, the SDK's default W3C composite propagator
(`tracecontext` + `baggage`) is installed and the standard `traceparent`
header is written on every outbound `fetch`:
```
traceparent: 00-<32-hex traceId>-<16-hex parentSpanId>-<01-sampled | 00-not-sampled>
```
Opt in only when the LLM provider also reports into your OTel collector
for cross-process trace stitching — e.g. ARMS Tracing serving DashScope.
For most operators the value is `false`; cross-vendor trace continuation
is niche.
**Depends on `telemetry.enabled: true`.** The OTel SDK only initializes
when telemetry is enabled, so `propagateTraceContext` only takes effect
in that state. Setting it to `true` while telemetry is disabled is a
silent no-op — no SDK, no propagator, no `traceparent` on the wire.
Verify both flags when wiring an ARMS+DashScope correlation setup:
```jsonc
{
"telemetry": {
"enabled": true,
"otlpTracesEndpoint": "http://tracing-analysis-...",
},
"outboundCorrelation": {
"propagateTraceContext": true,
},
}
```
### Other outbound correlation headers
`X-Qwen-Code-Session-Id` and `X-Qwen-Code-Request-Id` are **not part of
this PR**. They will be designed and proposed in their own follow-up
PR(s) under the same `outboundCorrelation.*` namespace, each with its
own threat model and operator-consent flow. PR #4390 review (LaZzyMan)
established the principle: "telemetry's scope of work doesn't include
sending identifiers to LLM providers"; correlation-header work moves to
its own design discussion rather than landing under telemetry.
## Aliyun Telemetry
### Manual OTLP Export

View File

@ -27,14 +27,7 @@ import { DaemonClient, type DaemonEvent } from '@qwen-code/sdk';
const client = new DaemonClient({
baseUrl: 'http://127.0.0.1:4170',
// PR 27 (v0.16-alpha): when `token` is omitted, DaemonClient falls
// back to `process.env.QWEN_SERVER_TOKEN` automatically — same env
// var the daemon's `--token` CLI flag falls back to. So either:
// export QWEN_SERVER_TOKEN="$(openssl rand -hex 32)" # one-shot
// export QWEN_SERVER_TOKEN="$(cat ./my-token-file)" # user-managed file
// const client = new DaemonClient({ baseUrl: '...' });
// OR pass it explicitly when you have a different env-var name:
// token: process.env.MY_TOKEN,
// token: process.env.QWEN_SERVER_TOKEN, // required for non-loopback binds
});
// 1. Confirm we can reach the daemon, gate UI on its features, and
@ -240,15 +233,6 @@ const client = new DaemonClient({
});
```
**SDK env fallback (PR 27, v0.16-alpha)** — `DaemonClient` reads `QWEN_SERVER_TOKEN` from the environment automatically when `token` is omitted, mirroring the daemon's own `--token` CLI fallback. So if your shell has `export QWEN_SERVER_TOKEN=...`, this is equivalent to the above:
```ts
// Same effect as token: process.env.QWEN_SERVER_TOKEN, but without the boilerplate.
const client = new DaemonClient({ baseUrl: 'https://your-host:4170' });
```
The fallback strips leading/trailing whitespace (handy for `export QWEN_SERVER_TOKEN="$(cat token.txt)"` where `cat` adds a newline) and treats empty / whitespace-only values as unset (a stale `export QWEN_SERVER_TOKEN=""` won't accidentally send `Authorization: Bearer ` with no token). The fallback runs once at construction; later `process.env` mutations don't affect already-built clients. Browser bundles (e.g. via `@qwen-code/webui`) get `undefined` cleanly because `globalThis.process` doesn't exist there.
Wrong / missing tokens return `401` with a uniform body — the SDK throws `DaemonHttpError` on any 4xx/5xx from a route handler.
```ts

View File

@ -18,32 +18,6 @@ Without a configured token (loopback dev default) the header is optional. Token
When the flag is on, the global `bearerAuth` middleware gates **every** route — including `/capabilities`. An **unauthenticated** client therefore cannot pre-flight `caps.features` to discover that auth is required: the discovery surface for that case is the **401 response body** itself (uniform across all routes per the [Authentication](#authentication) section). The `require_auth` capability tag is a **post-authentication confirmation** — once a client successfully authenticates and reads `/capabilities`, the tag's presence confirms the daemon was started with `--require-auth` (useful for audit / compliance UIs and for SDK clients to surface "this deployment is hardened" in a settings panel). Mutation routes that opt into per-route strict mode (Wave 4 follow-ups) refuse with `401 { code: "token_required", error: "…" }` when reached on a no-token loopback default — but with `--require-auth` enabled the global bearer middleware short-circuits the request before the per-route gate, so the legacy `Unauthorized` body is what unauthenticated callers actually see.
**`--allow-origin <pattern>` (T2.4 [#4514](https://github.com/QwenLM/qwen-code/issues/4514)).** Browser webuis hitting the daemon cross-origin are blocked by default — any request carrying an `Origin` header returns `403 {"error":"Request denied by CORS policy"}` because CLI/SDK clients never send `Origin` and the daemon treats its presence as a sign the request came from a browser context the operator has not opted into. Pass `--allow-origin <pattern>` (repeatable) at boot to install an allowlist instead of the wall. Each pattern is either:
- The literal `*` — admit any origin. **Risky**: boot refuses when `*` is configured but no bearer token is set (any source: `--token`, `QWEN_SERVER_TOKEN`, or `--require-auth` which mandates a token at boot). The boot breadcrumb emits a stderr warning when `*` is in the list. **Recommendation**: pair with `--require-auth` on loopback binds so `/health` and `/demo` are also gated by the bearer — they're registered before the bearer middleware on loopback by default (so k8s/Compose probes can reach `/health` without a token), and a `*` allowlist makes them reachable from any cross-origin browser. On non-loopback binds the bearer is already mandatory at boot, so the `*` exposure surface is just `/health` (status JSON) and `/demo` (a static page whose JS still calls token-gated routes) — the actual API surface is gated regardless.
- A canonical URL origin — `<scheme>://<host>[:<port>]`. **No trailing slash, no path, no userinfo, no query.** Boot refuses with `InvalidAllowOriginPatternError` if the entry fails the round-trip `new URL(pattern).origin === pattern`; the error message names the bad pattern and the canonical form. Strict-by-intent: silent normalization (e.g. trimming a trailing `/`) would let typos slip through and accept ambiguous input.
Matched origins receive the standard CORS response headers on every request:
```
Access-Control-Allow-Origin: <echoed origin>
Vary: Origin
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Qwen-Client-Id, Last-Event-ID
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: Retry-After
```
`Access-Control-Allow-Origin` echoes the request's origin verbatim (lowercase / uppercase as the browser sent it) rather than the literal `*`, even under the `*` pattern — browser caches key responses on it paired with `Vary: Origin`, and echoing leaves room to add `Access-Control-Allow-Credentials` in a later release without a schema change. `Access-Control-Expose-Headers: Retry-After` lets browser webuis honor daemon retry hints from `429` / `503` responses. `Access-Control-Allow-Credentials` is **NOT** sent today: the daemon authenticates via bearer-in-`Authorization`, which works cross-origin without `credentials: 'include'`.
OPTIONS preflight requests (OPTIONS with `Access-Control-Request-Method` or `Access-Control-Request-Headers`) short-circuit with `204 No Content` plus the headers above. This is the conventional CORS pattern and is safe — the preflight only confirms which methods/headers the daemon will accept; the actual subsequent request still runs the full chain (host allowlist → bearer auth → routes), so anti-DNS-rebinding and bearer enforcement still fire before any state is read or mutated. Plain OPTIONS requests from matched origins keep flowing downstream with CORS headers attached.
Origins that don't match the allowlist still get `403 {"error":"Request denied by CORS policy"}` — same envelope as the default wall, so clients that already parsed the wall's response don't have to special-case allowlist-deployed daemons. The reject path **does not** emit any `Access-Control-*` headers (the browser would ignore them, and emitting would indirectly advertise the allowlist size through header presence).
The configured pattern list is intentionally NOT echoed in `/capabilities` — browser webui already knows its own origin (it called the daemon, after all), and surfacing the list would let an unauthenticated reader of `/capabilities` enumerate every trusted origin (useful recon for a misconfigured deployment). SDK clients gate on the `caps.features.allow_origin` tag for "this daemon honors cross-origin browser hits" without needing to know which specific origins.
Loopback self-origin requests (e.g. the `/demo` page calling the daemon at the same `127.0.0.1:port`) are handled by a **separate** Origin-strip shim that runs BEFORE the CORS middleware and removes the `Origin` header for `127.0.0.1:port` / `localhost:port` / `[::1]:port` / `host.docker.internal:port`. So they pass through regardless of `--allow-origin` configuration — operators don't need to list the daemon's own port to make the demo page work.
## Common error shape
5xx responses carry the original error's `code` and `data` when present (JSON-RPC style — the ACP SDK forwards `{code, message, data}` from the agent):
@ -125,22 +99,14 @@ registry. Clients **must** gate UI off `features`, not off `mode` (per design
'session_set_model', 'client_identity', 'client_heartbeat',
'session_permission_vote', 'permission_vote', 'workspace_mcp', 'workspace_skills',
'workspace_providers', 'workspace_env', 'workspace_preflight',
'session_context', 'session_supported_commands', 'session_tasks',
'session_context', 'session_supported_commands',
'session_close', 'session_metadata', 'mcp_guardrails',
'mcp_guardrail_events',
'workspace_file_read', 'workspace_file_bytes', 'workspace_file_write',
'session_approval_mode_control', 'workspace_tool_toggle',
'workspace_init', 'workspace_mcp_restart',
'auth_device_flow', 'permission_mediation']
'workspace_init', 'workspace_mcp_restart']
```
> The conditional `require_auth` tag (PR 15) appears only when the daemon
> is started with `--require-auth`. F3's `permission_mediation` tag is
> always-on and carries `modes: ['first-responder', 'designated',
'consensus', 'local-only']` so SDK clients can introspect the
> build-supported set; the runtime-active strategy is at
> `body.policy.permission`.
`session_scope_override` is the negotiation handle for the per-request `sessionScope` field on `POST /session` (see below). Older daemons silently ignore the field, so SDK clients should pre-flight `caps.features` for this tag before sending it.
`session_load` and `unstable_session_resume` advertise the explicit-restore routes (`POST /session/:id/load` and `POST /session/:id/resume`). Older daemons return `404` for these paths, so SDK clients should pre-flight `caps.features` before calling. The `unstable_` prefix on `unstable_session_resume` mirrors the underlying ACP method (`connection.unstable_resumeSession`) — the daemon's wire shape is committed for v1, but the ACP method name itself may change before ACP marks resume stable.
@ -170,10 +136,9 @@ routes and require a configured bearer token even on loopback.
**Conditional tags.** A small number of feature tags are advertised only when the matching deployment toggle is on. Tag presence = behavior is on; absence = either an older daemon predating the tag, OR a current daemon where the operator did not opt in. Currently:
| Tag | Advertised when … |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `require_auth` | the daemon was started with `--require-auth` (or `requireAuth: true` via the embedded API). Bearer token is mandatory on every route, including `/health` on loopback binds. |
| `allow_origin` | T2.4 ([#4514](https://github.com/QwenLM/qwen-code/issues/4514)). The daemon was started with at least one `--allow-origin <pattern>` (or `allowOrigins: [...]` via the embedded API). Cross-origin requests from matched origins receive proper CORS response headers; unmatched origins still get the default 403. The configured pattern list is intentionally NOT echoed in `/capabilities` to avoid leaking the trusted-origin set to unauthenticated readers — browser webui already knows its own origin. |
| Tag | Advertised when … |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `require_auth` | the daemon was started with `--require-auth` (or `requireAuth: true` via the embedded API). Bearer token is mandatory on every route, including `/health` on loopback binds. |
`mcp_guardrails` is **not** in this conditional table — it's an always-on tag, advertised whenever the binary supports the new `/workspace/mcp` budget fields, regardless of whether the operator configured a budget. Operators who haven't set `--mcp-client-budget` still get the new fields (with `budgetMode: 'off'`, `budgets: []`).
@ -243,7 +208,6 @@ Capability tags:
- `workspace_preflight` → `GET /workspace/preflight`
- `session_context` → `GET /session/:id/context`
- `session_supported_commands` → `GET /session/:id/supported-commands`
- `session_tasks` → `GET /session/:id/tasks`
Common status cell:
@ -874,36 +838,6 @@ caller named the path. Success responses and audit events include
`available_commands_update` SSE notification. `availableSkills` lists skill
names only; clients must not expect skill bodies or paths over this route.
### `GET /session/:id/tasks`
```json
{
"v": 1,
"sessionId": "<sid>",
"now": 1700000000000,
"tasks": [
{
"kind": "agent",
"id": "agent-1",
"label": "reviewer: check failure",
"description": "check failure",
"status": "running",
"startTime": 1699999999000,
"runtimeMs": 1000,
"outputFile": "/tmp/agent-1.jsonl",
"isBackgrounded": true,
"subagentType": "reviewer"
}
]
}
```
This route is a read-only out-of-band snapshot. It is intentionally not a
prompt and can be queried while the session is streaming. The response only
contains whitelisted metadata from the agent, shell, and monitor task
registries; controllers, timers, offsets, pending messages, and raw registry
objects are never exposed.
### `POST /session`
Spawn a new agent or attach to an existing one (under `sessionScope: 'single'`, the default).
@ -1165,36 +1099,6 @@ Response:
On success, publishes `model_switched` to the SSE stream. On failure, publishes `model_switch_failed` (so passive subscribers see the failure, not just the caller). Races against the agent channel exit so a wedged child can't block the HTTP handler.
### `POST /session/:id/recap`
Capability tag: `session_recap`. Bridge → ACP extMethod `qwen/control/session/recap`.
Generate a one-sentence "where did I leave off" summary of the session. Wraps core's `generateSessionRecap` (`packages/core/src/services/sessionRecap.ts`), which runs a side-query against the fast model with tools disabled, `maxOutputTokens: 300`, and a strict `<recap>...</recap>` output format. The side-query reads the session's existing GeminiClient chat history and does **not** add to it.
Request body is ignored (send `{}` or empty). Non-strict mutation gate — posture mirrors `/session/:id/prompt` (the call costs tokens but mutates no state). No SSE event is published.
Response (200):
```json
{
"sessionId": "sess:42",
"recap": "Debugging the auth retry race. Next: add deterministic timing to the integration test."
}
```
`recap` is `null` (a normal 200, not an error) when:
- the session has fewer than two dialog turns yet,
- the side-query returned no extractable `<recap>...</recap>` payload,
- or any underlying model error occurred (the core helper is best-effort and never throws).
Errors:
- `400 {code: 'invalid_client_id'}` — malformed `X-Qwen-Client-Id` header.
- `404` — session unknown.
Cancellation: **none in v1**. The route does not listen for HTTP client disconnect, no `AbortSignal` is plumbed into the bridge, and the ACP child runs the side-query to completion regardless of whether the caller has disconnected. The only ceilings are the bridge's 60s backstop timeout (`SESSION_RECAP_TIMEOUT_MS`) and the transport-closed race against ACP channel death. This is acceptable because recap is short (single-attempt, `maxOutputTokens: 300`, ~1–5s typical); a request-id-based cancel ext-method can plumb full end-to-end cancellation in a future release if the bandwidth cost ever justifies it.
### Mutation: approval, tools, init, MCP restart
Issue [#4175](https://github.com/QwenLM/qwen-code/issues/4175) Wave 4 PR 17 adds four mutation control routes that let remote clients change runtime posture without touching the daemon host's CLI. All four:
@ -1374,19 +1278,17 @@ data: {"v":1,"type":"client_evicted","data":{"reason":"queue_overflow","droppedA
The SSE-level `id:` / `event:` lines duplicate `envelope.id` / `envelope.type` for EventSource compatibility. Raw-`fetch` consumers (the SDK's `parseSseStream`) read everything off the JSON envelope and ignore the SSE preamble lines.
| Event type | Trigger |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `session_update` | Any ACP `sessionUpdate` notification (LLM chunks, tool calls, usage) |
| `permission_request` | Agent asked for tool approval |
| `permission_resolved` | Some client voted on a permission via `POST /permission/:requestId` |
| `permission_partial_vote` | (consensus only) A vote was recorded but quorum not yet reached. Carries `{requestId, sessionId, votesReceived, votesNeeded, quorum, optionTallies}`. Pre-flight `caps.features.permission_mediation`. |
| `permission_forbidden` | A vote was rejected by the active policy (`designated` mismatch, `local-only` non-loopback, or `consensus` voter not in snapshot). Carries `{requestId, sessionId, clientId?, reason}`. Pre-flight `caps.features.permission_mediation`. |
| `model_switched` | `POST /session/:id/model` succeeded |
| `model_switch_failed` | `POST /session/:id/model` rejected |
| `session_died` | Agent child crashed unexpectedly. **Terminal: SSE stream closes after this frame; the session is gone from `byId`.** Subscribers should reconnect via `POST /session` to spawn a fresh one. |
| `slow_client_warning` | Subscriber-local: queue ≥ 75% full. **Non-terminal** — the stream continues; the warning is a heads-up before eviction. Carries `{queueSize, maxQueued, lastEventId}`. Fires ONCE per overflow episode; re-arms after the queue drains below 37.5%. No `id` (synthetic). Pre-flight `caps.features.slow_client_warning`. |
| `client_evicted` | Subscriber-local: queue overflow. **Terminal: SSE stream closes after this frame** (no `id` — synthetic). Other subscribers on the same session continue. |
| `stream_error` | Daemon-side error during fan-out. **Terminal: SSE stream closes after this frame** (no `id` — synthetic). |
| Event type | Trigger |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `session_update` | Any ACP `sessionUpdate` notification (LLM chunks, tool calls, usage) |
| `permission_request` | Agent asked for tool approval |
| `permission_resolved` | Some client voted on a permission via `POST /permission/:requestId` |
| `model_switched` | `POST /session/:id/model` succeeded |
| `model_switch_failed` | `POST /session/:id/model` rejected |
| `session_died` | Agent child crashed unexpectedly. **Terminal: SSE stream closes after this frame; the session is gone from `byId`.** Subscribers should reconnect via `POST /session` to spawn a fresh one. |
| `slow_client_warning` | Subscriber-local: queue ≥ 75% full. **Non-terminal** — the stream continues; the warning is a heads-up before eviction. Carries `{queueSize, maxQueued, lastEventId}`. Fires ONCE per overflow episode; re-arms after the queue drains below 37.5%. No `id` (synthetic). Pre-flight `caps.features.slow_client_warning`. |
| `client_evicted` | Subscriber-local: queue overflow. **Terminal: SSE stream closes after this frame** (no `id` — synthetic). Other subscribers on the same session continue. |
| `stream_error` | Daemon-side error during fan-out. **Terminal: SSE stream closes after this frame** (no `id` — synthetic). |
Reconnect semantics:
@ -1403,32 +1305,20 @@ Backpressure:
### `POST /permission/:requestId`
Cast a vote on a pending `permission_request`. The active **mediation policy** decides who wins:
Cast a vote on a pending `permission_request`. **First responder wins** — once one client answers, every other client trying to answer the same id gets `404`.
| Policy | Behavior |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first-responder` (default) | Any validated voter wins; later voters get `404`. Pre-F3 baseline. |
| `designated` | Only the prompt originator (`originatorClientId`) decides; non-originators get `403 permission_forbidden / designated_mismatch`. Falls back to first-responder for anonymous prompts. |
| `consensus` | N-of-M voters must agree (default `N = floor(M/2) + 1`, override via `policy.consensusQuorum`). First option to reach `N` wins. Non-resolving votes get `200` + `permission_partial_vote` SSE frames. |
| `local-only` | Only loopback voters decide; remote callers get `403 permission_forbidden / remote_not_allowed`. |
The active policy is configured in `settings.json` under `policy.permissionStrategy` and surfaced on `/capabilities` at `body.policy.permission`. Pre-flight `caps.features.permission_mediation` (with `modes: [...]`) for the build-supported set.
> **F3 (#4175): multi-client permission coordination.** F3 added the four policies above. Pre-F3 daemons hardcoded first-responder; the wire shape stays bit-for-bit unchanged when the configured policy is `first-responder`. New events (`permission_partial_vote`, `permission_forbidden`) are additive — old SDKs see them as `unrecognized_known_event` and gracefully ignore.
> **Permission timeout (default 5 minutes).** A `permission_request`
> **Stage 1 limitation — no permission timeout.** A `permission_request`
> stays pending until: (a) some client votes here, (b) `POST /session/:id/cancel`
> fires, (c) the HTTP client driving the prompt disconnects
> (mid-prompt cancel resolves outstanding permissions as `cancelled`),
> (d) the session is killed, (e) the daemon shuts down, **or
> (f) the per-session permission timeout fires** (`DEFAULT_PERMISSION_TIMEOUT_MS`,
> 5 minutes). On timeout fire the agent's `requestPermission` resolves
> as `{outcome: 'cancelled'}`, the audit ring records a
> `permission.timeout` entry, daemon stderr emits a one-line
> breadcrumb, and the SSE bus fans out the standard
> `permission_resolved` cancelled frame so subscribers clean up. The
> timeout is configurable via `BridgeOptions.permissionResponseTimeoutMs`;
> headless callers running long-form prompts may want to extend it.
> fires, (c) the HTTP client driving the prompt
> disconnects (mid-prompt cancel resolves outstanding permissions as
> `cancelled`), (d) the session is killed, or (e) the daemon shuts
> down. **In a fully-headless deployment with no SSE subscriber,
> `requestPermission` blocks the agent indefinitely** — there's nothing
> to time out the wait. Stage 2 will add a configurable
> `permissionTimeoutMs`. Until then, headless callers should keep an
> SSE subscription open or wrap their prompt loop in their own timeout
>
> - `POST /session/:id/cancel` on expiry.
Request:
@ -1448,13 +1338,10 @@ Outcomes:
Response:
- `200 {}` — your vote was accepted (resolved OR recorded under consensus quorum)
- `403 { "code": "permission_forbidden", "reason": "designated_mismatch" | "remote_not_allowed", "requestId", "sessionId" }` — F3: the active policy rejected your vote
- `200 {}` — your vote was accepted
- `404 { "error": "..." }` — the requestId is unknown (already resolved, never existed, or session torn down)
- `500 { "code": "cancel_sentinel_collision", ... }` — F3: the agent's `allowedOptionIds` contains the reserved sentinel `'__cancelled__'`; agent / daemon contract violation
- `501 { "code": "permission_policy_not_implemented", "policy": "<name>" }` — F3 forward-compat: a policy literal landed in the schema but its mediator branch isn't built yet (currently unreachable; reserved for future policies)
After a successful vote, every connected client sees `permission_resolved` with the same `requestId` and the chosen `outcome`. Under `consensus`, intermediate votes additionally fan out `permission_partial_vote` until quorum.
After a successful vote, every connected client sees `permission_resolved` with the same `requestId` and the chosen `outcome`.
### Auth device-flow routes (issue #4175 PR 21)

View File

@ -3,6 +3,7 @@ export default {
'file-system': 'File System',
'multi-file': 'Multi-File Read',
shell: 'Shell',
monitor: 'Monitor',
'todo-write': 'Todo Write',
task: 'Task',
'exit-plan-mode': 'Exit Plan Mode',

View File

@ -45,6 +45,7 @@ Qwen Code's built-in tools can be broadly categorized as follows:
- **[File System Tools](./file-system.md):** For interacting with files and directories (reading, writing, listing, searching, etc.).
- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell commands.
- **[Monitor Tool](./monitor.md) (`monitor`):** For running long-lived shell commands that stream output back as background task notifications.
- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content from URLs.
- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions.

View File

@ -0,0 +1,154 @@
# Monitor Tool (`monitor`)
This document describes the `monitor` tool for Qwen Code.
## Description
Use `monitor` to start a long-running shell command that streams stdout and
stderr lines back to the agent as background task notifications. It is intended
for watch-style commands where new output matters over time, such as tailing
logs, watching build output, polling a health endpoint, or observing file
changes.
The monitor runs in the background, so the agent can continue working while
events arrive. Each non-empty output line becomes a notification event, subject
to throttling.
### Arguments
`monitor` takes the following arguments:
- `command` (string, required): The shell command to run and monitor.
- `description` (string, optional): A brief description of what the monitor is
watching. The display text is truncated to 80 characters.
- `max_events` (number, optional): Stop after this many notification events.
Must be a positive integer. Defaults to `1000`; maximum `10000` (values
outside this range are rejected, not silently clamped).
- `idle_timeout_ms` (number, optional): Stop if the command produces no output
for this many milliseconds. Must be a positive integer. Defaults to `300000`
(5 minutes); maximum `600000` (10 minutes), and values outside this range are
rejected.
- `directory` (string, optional): An absolute path to run the command in. Must
resolve (after symlink canonicalization) inside one of the registered
workspace directories, and must not be inside the user-skills directory. If
omitted, Qwen Code uses the project root.
## How to use `monitor` with Qwen Code
The model chooses the `monitor` tool when it needs to observe a process over
time instead of collecting a single command result. A successful invocation
returns a monitor ID, the command, the event limit, and the idle timeout.
Usage:
```
monitor(command="tail -f logs/app.log", description="app log stream")
```
Monitor output is visible in the conversation as task notifications. You can
also inspect running and completed monitors with `/tasks` or the interactive
Background tasks dialog.
To stop a running monitor, use the `task_stop` tool with the monitor ID:
```
task_stop(task_id="mon_abc123def4567890")
```
## `monitor` examples
Watch an application log:
```
monitor(
command="tail -f logs/app.log",
description="application log stream",
max_events=200
)
```
Monitor a dev server or build watcher:
```
monitor(
command="npm run build -- --watch",
description="watch build output",
idle_timeout_ms=600000
)
```
Poll a local health endpoint:
```
monitor(
command="while true; do curl -s http://localhost:8080/health; sleep 5; done",
description="local health check",
max_events=120
)
```
Run from a specific workspace directory:
```
monitor(
command="npm run dev",
description="frontend dev server",
directory="/absolute/path/to/workspace/packages/web"
)
```
## Monitor vs. background shell commands
Use `monitor` when the agent needs to react to streaming output while the
command keeps running. Use `run_shell_command` instead when you need a one-shot
result or the complete command output.
| Need | Use |
| :----------------------------------------------------- | :--------------------------------------- |
| Watch logs, build output, or periodic status updates | `monitor` |
| Run a one-time command and read the full output | `run_shell_command(is_background=false)` |
| Start a daemon that does not produce meaningful output | `run_shell_command(is_background=true)` |
Do not add `&` to monitor commands. A trailing `&`, such as
`tail -f log &`, is stripped because the monitor manages backgrounding itself.
A non-final `&`, such as `cmd1 & cmd2`, is rejected outright; restructure such
commands without backgrounding instead.
## Important notes
- **Auto-stop behavior:** Monitors stop automatically when they reach
`max_events`, when `idle_timeout_ms` elapses without output, or when the
underlying command exits on its own. A monitor's status reflects the
command's outcome, not a tool error: a clean exit (`code 0`) becomes
`completed`, a non-zero exit code becomes `failed` with message
`Exit code N`, and termination by signal becomes `failed` with message
`Killed by signal SIG`. Commands cannot be interactive because stdin is
closed. When a monitor stops, Qwen Code sends `SIGTERM` to the command's
process group and escalates to `SIGKILL` after about 200 ms. On Windows, it
uses `taskkill /f /t`. If the Qwen Code process itself is hard-killed,
crashes, or runs out of memory, the detached process group is not cleaned up
automatically; recover by stopping the monitor with `task_stop` before exit
or by terminating the process group manually.
- **Concurrency limit:** Qwen Code allows up to 16 running monitors per CLI
session as a single shared pool. Monitors started by subagents count against
the same cap as monitors started by the main agent. Stop an existing monitor
before starting another if the limit is reached.
- **Output handling:** Stdout and stderr are merged into a single notification
stream with no stream prefix. Empty lines are ignored, ANSI color and control
characters are stripped, and individual lines longer than 2000 characters are
truncated. High-volume output is rate-limited with a burst of 5 events and
about 1 event per second after that; lines beyond the rate limit are dropped,
not buffered. Monitor output flows into the agent context as
`<task-notification>` content. Structural notification tags are defanged, but
the model still reads each line's text, so avoid monitoring streams that
external parties can write to unless you trust the model to ignore embedded
instructions.
- **Permissions:** `monitor` has its own permission boundary and permission
rules, such as `Monitor(git status)`. Read-only commands are automatically
allowed; commands that modify state require user approval; commands containing
command substitution (`$(...)`, backticks, `<(...)`, or `>(...)`) are rejected
outright. The `tools.core` and `tools.exclude` settings for
`run_shell_command` do not apply to `monitor`.
- **Workspace restriction:** The optional `directory` must be an absolute path
that resolves inside a registered workspace directory and outside the
user-skills directory. Symlinks that point outside the workspace are rejected.

View File

@ -0,0 +1,748 @@
# Worktree Phase D E2E Test Plan
## Scope
End-to-end verification of Phase D features against the local build at
`/Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js`.
Phase D delivers three cross-cutting capabilities:
- **D-1** — `--worktree [name]` CLI startup flag (bare / explicit slug / `=` form),
with `process.cwd()` + `Config.targetDir` switch and `WorktreeExitDialog`
reuse on exit
- **D-2** — `worktree.symlinkDirectories: string[]` settings key, applied in
`performPostCreationSetup()` so it covers `--worktree`, `EnterWorktreeTool`,
AND `AgentTool isolation: "worktree"` paths
- **D-3** — `--worktree=#<N>` and `--worktree <github-url>` PR-reference forms,
via `git fetch origin pull/<N>/head` (no `gh` CLI dependency)
## Binaries
- **Local build (Phase 6 verification)**: `node /Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js`
- **Phase 4 dry-run baseline**: globally installed `qwen`
For dry-runs the globally installed `qwen` is expected to fail Groups A / E / F
because the features don't exist yet — that's the validation that the plan
correctly detects implementation.
### Baseline precondition for Group E
Tests **E2** (`EnterWorktreeTool` symlink) and **E3** (`AgentTool isolation`
symlink) require **Phase A + B** to be present in the baseline — they exercise
the existing `enter_worktree` tool and `agent isolation: "worktree"` parameter
to confirm the symlink loop fires on those code paths too.
The globally installed `qwen` may predate PR #4073 (Phase A+B, merged 2026-05-14)
and therefore lack these tools entirely. When that is the case, E2 / E3 cannot
validate "symlink absent because D-2 is absent" — they collapse to "tool
absent." Add this guard at the top of each:
```bash
HAS_ENTER_WORKTREE=$($QWEN "list your tools and stop" --approval-mode yolo --output-format json 2>/dev/null \
| jq -e '.[] | select(.type=="system") | .tools | index("enter_worktree")' >/dev/null && echo yes || echo no)
if [ "$HAS_ENTER_WORKTREE" != "yes" ]; then
echo "SKIP: enter_worktree absent in baseline — E2/E3 require Phase A+B"
exit 0
fi
```
For Phase 6 (post-impl) verification the local build inherently contains
Phase A-C, so the guard is a no-op and the tests run in full.
## Test environment template
Each group runs in its own temp git repo and tmux session:
```bash
TEST_DIR=$(mktemp -d -t qwen-wt-phd-XXXXXX)
TEST_DIR=$(cd "$TEST_DIR" && pwd -P) # resolve symlinks (macOS /var → /private/var)
cd "$TEST_DIR"
git init -q -b main
git config user.email t@e.com
git config user.name t
git config commit.gpgsign false
echo "hello" > README.md
git add README.md
git commit -q -m "initial" --no-verify
PROJECT_ID=$(node -e "console.log(process.argv[1].replace(/[^a-zA-Z0-9]/g,'-'))" "$TEST_DIR")
QWEN="node /Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js"
```
PR-ref tests (Group F) additionally require a checked-out clone of a public
GitHub repo with at least one merged PR. Use this repo (qwen-code itself) as
the test target — PR `#4174` (Phase C) is a guaranteed-present reference.
---
## Group A: `--worktree` flag basic forms
**Mode:** headless, `--approval-mode yolo`, `--output-format json`
### A1: bare `--worktree` (auto-slug)
```bash
$QWEN --worktree "say hello and stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a1.out
# A `worktree_started` system event is emitted at startup. The `notice`
# field contains the slug (auto-generated `adj-noun-XXXXXX`) inside the
# rendered text. Use `jq -e` so a missing event is a non-zero exit
# (instead of silent `null`).
jq -e '.[] | select(.type=="system" and .subtype=="worktree_started") | .data.notice | test("\"[a-z]+-[a-z]+-[0-9a-f]{6}\"")' < /tmp/a1.out
# The init system message's `cwd` should also point inside the worktree.
jq -e '.[] | select(.type=="system" and .subtype=="init") | .cwd | test("/\\.qwen/worktrees/[a-z]+-[a-z]+-[0-9a-f]{6}$")' < /tmp/a1.out
ls -d "$TEST_DIR/.qwen/worktrees/"*
```
**Expected (post-impl):**
- `worktree_started` event with `.data.notice` containing the auto slug
- Init `.cwd` ends with `.qwen/worktrees/<auto-slug>`
- Exactly one worktree directory under `.qwen/worktrees/`
- Branch named `worktree-<slug>` exists (`git branch | grep worktree-`)
**Expected (pre-impl baseline):** yargs rejects `--worktree` with
"Unknown argument" error and exit code != 0.
### A2: `--worktree my-feature` (explicit slug)
```bash
$QWEN --worktree my-feature "say hello and stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a2.out
ls -d "$TEST_DIR/.qwen/worktrees/my-feature"
git -C "$TEST_DIR" branch | grep "worktree-my-feature"
```
**Expected (post-impl):** worktree dir `my-feature/` and branch
`worktree-my-feature` both exist.
### A3: `--worktree=my-feature` (= form)
Identical to A2 with `=` form. Cleanup between A2 and A3 required (different
TEST_DIR).
```bash
$QWEN --worktree=my-feature "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a3.out
```
**Expected (post-impl):** same as A2.
### A4: invalid slug rejected before any git operation
```bash
$QWEN --worktree "../escape" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a4.out
echo "exit=$?"
ls "$TEST_DIR/.qwen/worktrees/" 2>/dev/null
```
**Expected (post-impl):**
- Process exits with non-zero status
- Stderr or final result message mentions "invalid slug" / "not allowed"
- `.qwen/worktrees/` directory does not exist (worktree creation never started)
### A5: not a git repository → fail-close
```bash
NON_GIT=$(mktemp -d)
cd "$NON_GIT"
$QWEN --worktree "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/a5.out
echo "exit=$?"
```
**Expected (post-impl):** exit != 0, message mentions "not a git repository"
or "git init".
---
## Group B: cwd + sidecar after `--worktree`
### B1: sidecar written with all six fields
```bash
SESSION_ID=$(uuidgen)
$QWEN --worktree b1-test --session-id "$SESSION_ID" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/b1.out
SIDECAR=~/.qwen/projects/$PROJECT_ID/chats/$SESSION_ID.worktree.json
jq '.slug, .worktreePath, .worktreeBranch, .originalCwd, .originalBranch, .originalHeadCommit' \
< "$SIDECAR"
```
**Expected:**
- `slug = "b1-test"`
- `worktreePath` ends with `.qwen/worktrees/b1-test`
- `worktreeBranch = "worktree-b1-test"`
- `originalCwd` = `$TEST_DIR` (resolved)
- `originalBranch = "main"`
- `originalHeadCommit` matches `[0-9a-f]{40}`
### B2: `process.cwd()` switched at startup
```bash
$QWEN --worktree b2-test "run the shell tool with command 'pwd', then stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/b2.out
# Extract the shell tool's stdout from the user-message tool_result
jq -r '.[] | select(.type=="user") | .message.content[] | select(.tool_use_id != null) | .content' \
< /tmp/b2.out | head -5
```
**Expected (post-impl):** the `pwd` output equals `$TEST_DIR/.qwen/worktrees/b2-test`.
### B3: `Config.targetDir` switched (Footer / status payload)
```bash
$QWEN --worktree b3-test "run the shell tool with command 'pwd && git rev-parse --abbrev-ref HEAD', then stop" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/b3.out
jq -r '.[] | select(.type=="user") | .message.content[] | select(.tool_use_id != null) | .content' \
< /tmp/b3.out
```
**Expected (post-impl):** branch is `worktree-b3-test` AND working directory
is inside the worktree.
---
## Group C: `--worktree` × `--resume` precedence
### C1: `--worktree` wins over saved sidecar (different slug)
```bash
# Run 1: create a session with worktree "first"
SESSION_ID=$(uuidgen)
$QWEN --worktree first --session-id "$SESSION_ID" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c1-run1.out
# Run 2: resume the same session but request a different worktree
$QWEN --resume "$SESSION_ID" --worktree second "say hi again" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c1-run2.out
# Sidecar should now point at "second"
SIDECAR=~/.qwen/projects/$PROJECT_ID/chats/$SESSION_ID.worktree.json
jq -r '.slug' < "$SIDECAR"
# Both worktree dirs should exist on disk (first was never removed, just unlinked)
ls -d "$TEST_DIR/.qwen/worktrees/"*
```
**Expected (post-impl):**
- Sidecar `.slug` = `"second"`
- Both `first/` and `second/` directories exist
- Run 2's stderr or init `worktree_overridden` message mentions "--worktree
overrides the resumed session's worktree"
### C2: stale sidecar (manually deleted dir) + `--worktree` → fresh worktree
```bash
SESSION_ID=$(uuidgen)
$QWEN --worktree c2 --session-id "$SESSION_ID" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c2-run1.out
rm -rf "$TEST_DIR/.qwen/worktrees/c2" # simulate user-deleted dir
$QWEN --resume "$SESSION_ID" --worktree c2-fresh "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/c2-run2.out
ls -d "$TEST_DIR/.qwen/worktrees/"*
```
**Expected (post-impl):** only `c2-fresh/` exists; sidecar updated to `c2-fresh`.
---
## Group D: WorktreeExitDialog regression (`--worktree`-started session)
**Mode:** interactive (tmux). Verifies Phase C dialog still triggers when the
worktree was created by the CLI flag rather than `EnterWorktreeTool`.
### D1: 2x Ctrl+C → dialog appears
```bash
tmux new-session -d -s d1 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree d1-test --approval-mode yolo"
sleep 3
# Verify worktree is active (Footer indicator)
tmux capture-pane -t d1 -p -S -50 | grep -q "⎇ worktree-d1-test"
# Send Ctrl+C twice
tmux send-keys -t d1 C-c
sleep 0.3
tmux send-keys -t d1 C-c
sleep 1
tmux capture-pane -t d1 -p -S -50 | grep -E "Active worktree|Keep worktree|Remove worktree"
tmux kill-session -t d1
```
**Expected (post-impl):** dialog text "Active worktree: \"d1-test\" …" and the
three radio options appear.
### D2: Dialog → Cancel → session stays alive
```bash
tmux new-session -d -s d2 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree d2-test --approval-mode yolo"
sleep 3
tmux send-keys -t d2 C-c; sleep 0.3; tmux send-keys -t d2 C-c; sleep 1
# Navigate to "Cancel" (third option) and select
tmux send-keys -t d2 Down Down Enter
sleep 1
tmux capture-pane -t d2 -p -S -10 | grep -q "Type your message"
ls -d "$TEST_DIR/.qwen/worktrees/d2-test" # still exists
tmux kill-session -t d2
```
**Expected (post-impl):** prompt input reappears; worktree dir is still on disk.
### D3: Dialog → Remove → worktree + branch + sidecar all gone
```bash
SESSION_ID=$(uuidgen)
tmux new-session -d -s d3 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree d3-test --session-id $SESSION_ID --approval-mode yolo"
sleep 3
tmux send-keys -t d3 C-c; sleep 0.3; tmux send-keys -t d3 C-c; sleep 1
tmux send-keys -t d3 Down Enter # select "Remove worktree and branch"
sleep 3
tmux kill-session -t d3
ls "$TEST_DIR/.qwen/worktrees/d3-test" 2>/dev/null && echo "FAIL: dir exists"
git -C "$TEST_DIR" branch | grep "worktree-d3-test" && echo "FAIL: branch exists"
test ! -f ~/.qwen/projects/$PROJECT_ID/chats/$SESSION_ID.worktree.json && echo "PASS: sidecar gone"
```
**Expected (post-impl):** dir, branch, and sidecar all removed.
---
## Group E: `worktree.symlinkDirectories`
**Mode:** headless. Settings configured via temp settings file.
### Setup template
```bash
mkdir -p "$TEST_DIR/node_modules"
echo "package.json" > "$TEST_DIR/node_modules/.placeholder"
mkdir -p "$TEST_DIR/.qwen"
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{
"worktree": {
"symlinkDirectories": ["node_modules"]
}
}
EOF
```
### E1: `--worktree` path applies symlink
```bash
$QWEN --worktree e1-test "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /dev/null
ls -la "$TEST_DIR/.qwen/worktrees/e1-test/node_modules"
readlink "$TEST_DIR/.qwen/worktrees/e1-test/node_modules"
```
**Expected (post-impl):** `node_modules` inside the worktree is a symlink
pointing to `$TEST_DIR/node_modules`.
### E2: `EnterWorktreeTool` path applies symlink
```bash
$QWEN "use enter_worktree to create a worktree named e2-test, then stop" \
--approval-mode yolo --output-format json 2>/dev/null > /dev/null
readlink "$TEST_DIR/.qwen/worktrees/e2-test/node_modules"
```
**Expected (post-impl):** same symlink target.
### E3: AgentTool isolation path applies symlink
Requires a sub-agent definition. Use the built-in fork mechanism:
```bash
$QWEN "use the agent tool with subagent_type='general-purpose', isolation='worktree', description='check node_modules', prompt='run pwd and ls -la node_modules then exit'" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/e3.out
# Extract agent worktree dir from result message
jq -r '.[] | select(.type=="assistant") | .message.content[] | select(.type=="tool_use") | .input' \
< /tmp/e3.out | head -5
# After execution find the agent-<7hex> worktree
ls -la "$TEST_DIR/.qwen/worktrees/"agent-*/node_modules 2>/dev/null | head -3
```
**Expected (post-impl):** symlink exists inside the `agent-<hex>` worktree
(unless auto-cleaned because there were no changes — in that case the
"no changes" path doesn't validate symlink behavior, escalate to a forced
change test).
### E4: missing source dir → silently skipped, worktree still created
```bash
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{ "worktree": { "symlinkDirectories": ["does-not-exist"] } }
EOF
$QWEN --worktree e4-test "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/e4.out
ls -d "$TEST_DIR/.qwen/worktrees/e4-test"
ls "$TEST_DIR/.qwen/worktrees/e4-test/does-not-exist" 2>/dev/null && echo "UNEXPECTED"
```
**Expected (post-impl):** worktree directory exists, the missing entry is
not created inside it, process exit = 0.
### E5: existing dest → silently skipped, no overwrite
```bash
# Pre-create a worktree at expected slug then re-create — this is contrived
# because Phase D paths should be fresh, but it exercises the EEXIST guard.
mkdir -p "$TEST_DIR/.qwen/worktrees/e5-test/node_modules"
echo "preexisting" > "$TEST_DIR/.qwen/worktrees/e5-test/node_modules/.marker"
# Force re-creation via EnterWorktreeTool (CLI would refuse "already exists")
$QWEN "use enter_worktree with name='e5-test' to retry" --approval-mode yolo 2>/dev/null
# either: tool errors out cleanly, OR symlink is skipped — both acceptable
test -f "$TEST_DIR/.qwen/worktrees/e5-test/node_modules/.marker" && echo "PASS: not overwritten"
```
**Expected (post-impl):** preexisting `.marker` survives; no symlink replaces
the dir.
### E6: absolute path / `../` → rejected
```bash
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{ "worktree": { "symlinkDirectories": ["/etc", "../escape"] } }
EOF
$QWEN --worktree e6-test "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/e6.out
ls "$TEST_DIR/.qwen/worktrees/e6-test/" | head -10
```
**Expected (post-impl):** worktree exists; neither `etc` nor `escape` linked
inside it; debug log carries warn lines.
---
## Group F: PR reference
**Mode:** headless. Requires `origin` remote pointing at a public GitHub repo.
### Setup template
```bash
# Use qwen-code itself as the test repo
TEST_DIR=$(mktemp -d -t qwen-wt-phd-pr-XXXXXX)
TEST_DIR=$(cd "$TEST_DIR" && pwd -P)
cd "$TEST_DIR"
git clone --depth 1 https://github.com/QwenLM/qwen-code.git .
PROJECT_ID=$(node -e "console.log(process.argv[1].replace(/[^a-zA-Z0-9]/g,'-'))" "$TEST_DIR")
```
### F1: `--worktree=#4174` parses + fetches
```bash
$QWEN --worktree=#4174 "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/f1.out
ls -d "$TEST_DIR/.qwen/worktrees/pr-4174"
git -C "$TEST_DIR/.qwen/worktrees/pr-4174" rev-parse --abbrev-ref HEAD
```
**Expected (post-impl):**
- Worktree dir `pr-4174/` exists
- HEAD branch = `worktree-pr-4174`
- The branch's tip resolves (git log -1) without error
### F2: full URL form
```bash
$QWEN --worktree "https://github.com/QwenLM/qwen-code/pull/4174" "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/f2.out
ls -d "$TEST_DIR/.qwen/worktrees/pr-4174"
```
**Expected (post-impl):** same as F1.
### F3: missing `origin` remote → fail-close
```bash
cd "$TEST_DIR" && git remote remove origin
$QWEN --worktree=#4174 "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/f3.out
echo "exit=$?"
```
**Expected (post-impl):** exit != 0; message mentions `origin` remote.
### F4: invalid PR number → fail-close
```bash
$QWEN --worktree=#999999999 "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/f4.out
echo "exit=$?"
```
**Expected (post-impl):** exit != 0; message mentions "Failed to fetch PR".
30-second timeout cap respected (test runtime < 35s).
### F5: malformed `#abc` falls through to slug validation
```bash
$QWEN --worktree=#abc "say hi" --approval-mode yolo --output-format json 2>/dev/null > /tmp/f5.out
echo "exit=$?"
```
**Expected (post-impl):** treated as literal slug `#abc`, rejected by
`validateUserWorktreeSlug` because `#` is not allowed. Exit != 0.
### F6: PR worktree gets symlinks too (cross-cut with E)
```bash
cat > "$TEST_DIR/.qwen/settings.json" <<'EOF'
{ "worktree": { "symlinkDirectories": ["node_modules"] } }
EOF
mkdir -p "$TEST_DIR/node_modules" && echo x > "$TEST_DIR/node_modules/.marker"
$QWEN --worktree=#4174 "say hi" --approval-mode yolo --output-format json 2>/dev/null > /dev/null
readlink "$TEST_DIR/.qwen/worktrees/pr-4174/node_modules"
```
**Expected (post-impl):** symlink target = `$TEST_DIR/node_modules`.
---
## Group G: Integration + edge cases
### G1: full lifecycle — start → write → Keep → resume
> **Pre-impl note:** Against the baseline this test exits before `sleep 3`
> finishes (yargs rejects `--worktree` immediately and the tmux pane dies).
> The `capture-pane` call then errors with "can't find pane". This is
> expected — record as PASS-by-rejection. Wrap captures with `|| true` for
> the dry-run, or skip G1 entirely in baseline mode.
```bash
SESSION_ID=$(uuidgen)
tmux new-session -d -s g1 -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --worktree g1-test --session-id $SESSION_ID --approval-mode yolo 2>&1 | tee /tmp/g1-stderr.out"
sleep 3
tmux send-keys -t g1 "use the write_file tool to create file 'work.txt' with content 'phase d test'"
sleep 0.3; tmux send-keys -t g1 Enter
sleep 8
tmux send-keys -t g1 C-c; sleep 0.3; tmux send-keys -t g1 C-c; sleep 1
tmux send-keys -t g1 Enter # default = "Keep"
sleep 2
tmux kill-session -t g1
# File survived
cat "$TEST_DIR/.qwen/worktrees/g1-test/work.txt"
# Resume reattaches
tmux new-session -d -s g1b -x 200 -y 50 \
"cd $TEST_DIR && $QWEN --resume $SESSION_ID --approval-mode yolo"
sleep 4
tmux capture-pane -t g1b -p -S -50 | grep -E "⎇ worktree-g1-test|Resumed"
tmux kill-session -t g1b
```
**Expected (post-impl):**
- `work.txt` inside the worktree contains the written content
- Resumed session Footer shows `⎇ worktree-g1-test (g1-test)`
- INFO history item or `<system-reminder>` mentions "Resumed"
### G2: relative path arg resolved before cwd switch
```bash
# Create an mcp config in TEST_DIR and reference it relatively.
# --mcp-config takes a file path; if the test plan path is resolved AFTER
# the --worktree cwd switch, the file won't be found inside the worktree
# and the CLI will error out. If resolved BEFORE the switch (correct), the
# file is loaded from TEST_DIR.
cat > "$TEST_DIR/mcp.json" <<'EOF'
{ "mcpServers": {} }
EOF
cd "$TEST_DIR"
$QWEN --worktree g2-test --mcp-config ./mcp.json "say hi" \
--approval-mode yolo --output-format json 2>/dev/null > /tmp/g2.out
echo "exit=$?"
jq -r '.[] | select(.type=="result") | .result' < /tmp/g2.out | head -3
```
**Expected (post-impl):** exit = 0; the model responds normally (the empty
mcp config means no MCP servers but no error either).
**Expected (pre-impl baseline):** yargs rejects `--worktree` (the test
cannot distinguish "worktree flag missing" from "mcp config resolution
broken" until the flag itself exists).
---
## Run order + parallelism
| Group | Mode | Runtime | Parallel-safe? |
| ----- | ------------ | ------- | ---------------------------- |
| A | headless | ~30s | yes (own TEST_DIR) |
| B | headless | ~20s | yes |
| C | headless | ~40s | yes |
| D | tmux | ~30s | yes (own session name) |
| E | headless | ~60s | yes |
| F | headless+net | ~60s | NO — shares the GitHub clone |
| G | mixed | ~60s | yes |
Run A/B/C/D/E/G in parallel; F serially after the clone setup.
## Reproduction report
### Phase 4 dry-run — baseline `qwen` v0.15.11 (2026-05-20)
Runtime: 3 parallel `test-engineer` agents, ~7 minutes total. Baseline lacks
both Phase D (expected) and Phase A+B (older binary than expected — see
E2/E3 caveat).
| Group | Result | Notes |
| -------------------------------- | ---------- | ------------------------------------------------------------------------------------- |
| A1 (bare flag) | ✅ | yargs `Unknown argument: worktree`, exit 1 |
| A2 (explicit slug) | ✅ | same |
| A3 (= form) | ✅ | same |
| A4 (invalid slug) | ✅ | yargs rejects before slug validation |
| A5 (non-git dir) | ✅ | same |
| B1 (sidecar fields) | ✅ | sidecar correctly absent; jq selector valid against sample data |
| B2 (cwd switch) | ✅ | shell-tool `tool_result.content` jq selector verified against real output |
| B3 (targetDir switch) | ✅ | same selector |
| C1 (--worktree beats sidecar) | ✅ | both runs exit 1, no sidecar |
| C2 (stale sidecar + fresh) | ✅ | same |
| E1 (--worktree symlink) | ✅ | flag rejected, no symlink — pre-impl confirmed |
| E2 (EnterWorktree symlink) | ⚠️ N/A | baseline lacks `enter_worktree` tool (older than PR #4073); guard now skips this case |
| E3 (AgentTool isolation symlink) | ⚠️ N/A | baseline `agent` schema silently drops `isolation` param; guard skips |
| E4 (missing source skip) | ✅ | flag rejected |
| E5 (existing dest not overwrite) | ⚠️ trivial | preexisting `.marker` survived but only because tool couldn't run |
| E6 (path traversal reject) | ✅ | flag rejected, no symlinks |
| F1 (--worktree=#4174 fetch) | ✅ | `Unknown argument: worktree`, no network call |
| F2 (full URL form) | ✅ | same |
| F3 (missing origin) | ✅ | rejected before git check |
| F4 (invalid PR number) | ✅ | rejected before fetch |
| F5 (`#abc` malformed) | ✅ | same |
| F6 (PR + symlinkDirs) | ✅ | same |
| G1 (lifecycle tmux) | ⚠️ partial | tmux pane dies on flag rejection; record-by-exit-code works |
| G2 (relative path) | ✅ | (after switching to `--mcp-config ./mcp.json`) yargs rejects worktree first |
**Conclusion:** test scripts are fundamentally sound. 19 / 24 cases cleanly
detect pre-impl baseline; 3 cases (E2/E3/E5) need the baseline to include
Phase A+B (which the local Phase 6 build will provide); 2 cases (G1/G2) had
script bugs that are now fixed. **Ready to proceed to Phase 5
implementation.**
### Phase 6 verification — local build
**Binary**: `node /Users/mochi/code/qwen-code/.claude/worktrees/tender-jemison-037f0a/dist/cli.js`
**Date**: 2026-05-20
**Scope**: Groups A, B, C, E, F, G (6 parallel `test-engineer` agents)
| Group | Result | Notes |
| ---------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A1 (bare flag) | ✅ (with doc tip) | yargs consumes the next positional as the slug value when user passes `qwen --worktree "say hi"`; quickstart now tells users to use `=` form or put the prompt before the flag. Auto-slug feature itself confirmed via `qwen --worktree --approval-mode yolo "say hi"` → slug `bright-elm-8a4c12`, init `.cwd` ends with `.qwen/worktrees/<auto-slug>`. |
| A2 (explicit slug) | ✅ | dir `.qwen/worktrees/my-feature` + branch `worktree-my-feature` |
| A3 (= form) | ✅ | identical to A2 |
| A4 (invalid slug) | ✅ | exit=1, message: `Worktree name may only contain letters, digits, dots, underscores, and hyphens.`, no worktree dir |
| A5 (non-git dir) | ✅ | exit=1, message: `not a git repository. Run \`git init\` first or relaunch from inside one.` |
| B1 (sidecar fields) | ✅ | All 6 fields present and correct; sidecar lives under worktree projectHash as designed |
| B2 (cwd switch) | ✅ | `pwd` inside shell tool returned worktree path exactly |
| B3 (branch + cwd) | ✅ | `pwd` = worktree path, `git rev-parse --abbrev-ref HEAD` = `worktree-b3-test` |
| C1 (cross-slug override) | ❌ → **known limitation** | Sessions are bound to `projectHash(cwd)`; `--worktree second --resume <sid-from-first>` can't find the session. Documented in user docs Limitations. A future Config refactor (anchor storage at repo root) would lift this. |
| C2 (stale sidecar + new worktree) | ❌ → **same root cause** | Same architectural constraint. |
| E1 (`--worktree` symlink) | ✅ | `node_modules` symlinked into the new worktree |
| E2 (`enter_worktree` symlink) | ✅ | same code path via `createUserWorktree` |
| E3 (agent isolation symlink) | ⚠️ test-setup | model committed `node_modules` (because the agent guard refused dirty state); EEXIST guard then correctly skipped the symlink. Code path is correct; for a clean E3 the test plan needs to pre-`.gitignore` `node_modules`. |
| E4 (missing source skip) | ✅ | worktree created, no entry, exit 0 |
| E5 (existing dest no overwrite) | ✅ | preexisting marker survived |
| E6 (absolute / `..` rejected) | ✅ | neither path linked |
| F1 (`--worktree=#4174` fetch) | ✅ | worktree dir `pr-4174/`, branch `worktree-pr-4174`, tip commit `8f4fe8e feat(cli): per-turn /diff…`; local-remote substitute (sandbox blocks real GitHub) |
| F2 (full URL form) | ✅ | same result; URL parsed → PR #4174 → local origin fetch succeeded |
| F3 (missing origin) | ✅ | exit=1 in 2s; message mentions adding `origin` remote |
| F4 (invalid PR #999999999) | ✅ | exit=1 in 2s; "PR does not exist on origin"; well within 35s cap |
| F5 (malformed `#abc`) | ✅ | slug validation rejects `#` |
| F6 (PR worktree + symlinks) | ✅ | symlink `pr-4174/node_modules` → `$TEST_DIR/node_modules` confirmed |
| G1.a (start + write + Keep) | ✅ | TUI flow, Footer indicator, dialog options, file persists |
| G1.b (`--resume … --worktree foo`) | ❌ → **fixed in this PR** | Original: `--worktree: Worktree already exists at …`. Phase 6 fix added the re-attach branch in `setupStartupWorktree`. Verified post-fix via smoke test (`--worktree foo` twice → second emits the `worktree_started` notice, no error) + new unit tests in `worktreeStartup.test.ts`. |
| G2 (relative `--mcp-config`) | ❌ → **fixed in this PR** | Original: exit=52, `Invalid MCP configuration … is not valid JSON`. Phase 6 fix normalizes path-taking argv fields (`mcpConfig`, `openaiLoggingDir`, `jsonFile`, `inputFile`, `telemetryOutfile`, `includeDirectories`) against the launch cwd BEFORE `setupStartupWorktree` chdirs. Verified post-fix via smoke test (`--worktree foo --mcp-config ./mcp.json` → model responds normally). |
**Phase 6 net result:** 22 / 24 cases passed post-fix; 2 cases (C1/C2) hit an
architectural limitation now documented; 1 case (E3) is a test-setup quirk,
not an implementation issue. **Ready for Phase 7 code review.**
### Fix references (Phase 6 fixes that landed in this PR)
| Fix | File | Change |
| ----------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Re-attach to existing worktree (G1.b) | `packages/cli/src/startup/worktreeStartup.ts` | Added pre-create check: if dir is a registered worktree on the expected branch, skip create + chdir |
| `getRegisteredWorktreeBranch()` helper | `packages/core/src/services/gitWorktreeService.ts` | Probes `git rev-parse --abbrev-ref HEAD` against the candidate path |
| Path normalization before chdir (G2) | `packages/cli/src/gemini.tsx` | Resolves `mcpConfig`, `openaiLoggingDir`, `jsonFile`, `inputFile`, `telemetryOutfile`, `includeDirectories` against launch cwd when `--worktree` is set |
| Documentation: yargs flag ordering tip + Limitations update | `docs/users/features/worktree.md` | Quick Start tip + new Limitations bullets (cross-slug, path-arg behavior) |
| Unit tests for re-attach | `packages/cli/src/startup/worktreeStartup.test.ts` | Added 2 tests: happy re-attach + "different branch occupies slot" guard |
**Phase 6 Group F network note**: The sandbox blocks `git fetch` to `https://github.com` with HTTP 403. F1/F2/F4/F6 were retested against a local bare repo (`git init --bare`) seeded with `refs/pull/4174/head` pointing at a commit whose message is `feat(cli): per-turn /diff with interactive dialog (#4277)`. F3 and F5 are network-independent and were verified directly. The local-remote substitute fully exercises the parsing + fetch + worktree-creation code path.
---
## Reproduction report — Phase 4 dry-run (Groups F + G), 2026-05-20
**Binary**: `qwen` (globally installed, v0.15.11 at `/Users/mochi/.nvm/versions/node/v22.21.1/bin/qwen`)
**Override**: `QWEN="qwen"`
### Results table
| Test ID | Result | Evidence | Fix suggestion |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| F1 `--worktree=#4174` | PASS | `Unknown argument: worktree`, exit=1 | None — expected baseline failure |
| F2 `--worktree <url>` | PASS | `Unknown argument: worktree`, exit=1 | None — expected baseline failure |
| F3 missing origin | PASS | `Unknown argument: worktree`, exit=1 — yargs rejected before any git op | None |
| F4 invalid PR #999999999 | PASS | `Unknown argument: worktree`, exit=1 | None |
| F5 malformed `#abc` | PASS | `Unknown argument: worktree`, exit=1 | None |
| F6 PR + symlinkDirs | PASS | `Unknown argument: worktree`, exit=1 | None |
| G1 lifecycle (tmux) | PASS | `Unknown argument: worktree` emitted to stdout captured in `/tmp/g1_raw.out`; tmux session exited immediately, pane was already dead by capture time | SCRIPT-BUG: see note below |
| G2 relative path | PASS | `Unknown arguments: worktree, prompt-file, promptFile`, exit=1 | SCRIPT-BUG: see note below |
### Observed behavior (all cases)
Every invocation of `--worktree` (bare, `=` form, `#<N>` form, full URL, combined with `--prompt-file`) was rejected at the yargs argument-parsing layer with exit code 1 before any application logic ran. The exact error strings are:
- `Unknown argument: worktree` (single unknown arg)
- `Unknown arguments: worktree, prompt-file, promptFile` (G2: both `--worktree` and `--prompt-file` are unknown, listed together)
No git operations, no network calls, no filesystem writes occurred in any test.
### Expected behavior
Identical rejection — this is the correct pre-implementation baseline. All 8 tests PASS in the dry-run sense (the plan correctly detects that the features do not exist).
### Key context
The failure mode is uniformly at the yargs layer, not downstream. This confirms the test plan's detection strategy is sound: once `--worktree` is wired into yargs, these tests will stop failing at this layer and will instead exercise the actual implementation paths (F1-F6 will hit git fetch, G1 will hit the TUI lifecycle, G2 will hit `--prompt-file` resolution).
### SCRIPT-BUG notes for the test plan
**G1 (tmux):** The tmux session command pipes through `tee` with a subshell `echo 'PROC_EXIT='$?` that captures the exit of `tee`, not of `qwen`. When the process exits instantly (as with an Unknown argument error), the session terminates before `sleep 3` finishes and the pane name `g1dry` is gone by the time `tmux capture-pane` runs, producing `can't find pane: g1dry`. Fix: use `|| true` after `tmux capture-pane`, or add a `|| sleep 0` guard; better still, for the baseline-fail case redirect stderr+stdout to a file outside tmux and check the file directly (as done here via `tee /tmp/g1_raw.out`).
**G2 (`--prompt-file`):** The test plan uses `--prompt-file ./relative.txt` as a combined test with `--worktree`. In the baseline, `--prompt-file` is also an unknown argument (it does not exist in v0.15.11 yargs schema either — the flag is `--prompt-interactive` / `-p`). The error lists both unknown args together. The plan should note that `--prompt-file` will need to be implemented alongside `--worktree`, or use an existing flag (e.g. pipe via stdin or use `--prompt`) for the relative-path resolution test.

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -1,280 +0,0 @@
# `qwen serve` Daemon File Logger — Design
- **Issue**: [QwenLM/qwen-code#4548](https://github.com/QwenLM/qwen-code/issues/4548)
- **Branch**: `feat/support_daemon_logger`
- **Status**: design approved, awaiting implementation plan
- **Date**: 2026-05-26
## 1. Problem
`qwen serve` emits daemon-level diagnostics (lifecycle, route errors, ACP child stderr) to `process.stderr`. That works under systemd/Docker but is fragile for SDK / Desktop / local daemon use: when a client sees `POST /session/:id/prompt` return HTTP 500, the route + session + stack context is gone unless the operator manually redirected stderr.
`createDebugLogger` (in `packages/core/src/utils/debugLogger.ts`) is session-scoped: it requires an active `DebugLogSession` and writes to `${runtimeBaseDir}/debug/<sessionId>.txt`. The serve daemon starts **before** any session exists, so daemon-level calls would silently no-op. It also can't be reused without changing the per-session `debug/latest` semantics.
This design adds a daemon-specific file sink, additive to existing stderr behavior, so daemon diagnostics survive without shell redirection.
## 2. Scope
### In scope
- A new logger initialized once per `runQwenServe` process.
- File at `${QWEN_RUNTIME_DIR or ~/.qwen}/debug/daemon/<daemon-id>.log`, append mode.
- Tee of:
- `runQwenServe.ts` lifecycle / shutdown / signal messages
- `sendBridgeError` (`server.ts`) route errors
- `bridge.ts` `writeServeDebugLine` (when `QWEN_SERVE_DEBUG` is set)
- `spawnChannel.ts` ACP child stderr forwarding
- Opt-out via `QWEN_DAEMON_LOG_FILE=0|false|off|no`.
- `latest` symlink in the daemon dir for `tail -f`.
- Documentation in serve CLI docs.
### Out of scope (non-goals from issue)
- Replacing OpenTelemetry or adding daemon tracing.
- Structured enterprise error log export (issue #2014).
- Rotation or deletion of existing session debug logs.
- Log rotation / size cap for the daemon log itself (deferred to a follow-up PR). A boot-time stderr warning is emitted if the existing file is unusually large; no automatic action.
## 3. Architecture
### 3.1 Module boundaries
| Layer | New / Changed | Responsibility |
| ------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/cli/src/serve/daemonLogger.ts` | **new** | Sink: init, format, append-to-file, tee-to-stderr, flush, latest-symlink |
| `packages/cli/src/serve/runQwenServe.ts` | changed | Init logger at boot; replace lifecycle `writeStderrLine` with `daemonLog.*`; `await flush()` on shutdown; pass `onDiagnosticLine` into bridge |
| `packages/cli/src/serve/server.ts` | changed | `sendBridgeError(...)` routes through `daemonLog.error(...)` |
| `packages/acp-bridge/src/types.ts` (`BridgeOptions`) | changed | Add optional `onDiagnosticLine?: (line: string, level?: 'info' \| 'warn' \| 'error') => void` |
| `packages/acp-bridge/src/bridge.ts:writeServeDebugLine` | changed | If `onDiagnosticLine` injected, tee the same line |
| `packages/acp-bridge/src/spawnChannel.ts` | changed | Child stderr forwarder tees each prefixed line into `onDiagnosticLine` |
**Design intent**: `daemonLogger.ts` is single-file, cli-local, no global singleton. `acp-bridge` stays ignorant of cli — it only sees a callback. Dependency graph unchanged.
### 3.2 No global singleton
Logger is created in `runQwenServe`, passed by closure to internal serve modules that need it (or by callback to `acp-bridge`). Rationale:
- Mirrors how `BridgeOptions` already injects dependencies.
- Avoids the cross-test state leaks `debugLogger` has hit historically (`resetDebugLoggingState()` exists for that reason).
## 4. Daemon ID & File Path
- Path: `Storage.getGlobalDebugDir() + '/daemon/<daemon-id>.log'`
- Resolves to `${QWEN_RUNTIME_DIR or ~/.qwen}/debug/daemon/<daemon-id>.log`.
- Reuses `Storage.getGlobalDebugDir()` so the runtime-dir override (env var, contextual) automatically applies.
- `daemon-id` = `serve-${pid}-${workspaceHash}`
- `workspaceHash` = `crypto.createHash('sha256').update(boundWorkspace).digest('hex').slice(0, 8)`
- `pid` disambiguates multiple daemons on the same workspace.
- `workspaceHash` is fixed-length, filename-safe, and stable for the same workspace path.
- `latest` symlink: `~/.qwen/debug/daemon/latest` → current process's log file. Updated on init using the existing `updateSymlink` helper (`packages/core/src/utils/symlink.ts`). Symlink failure is logged and ignored — does not degrade primary writes. Distinct from `${runtimeBaseDir}/debug/latest` (session-scoped) per non-goal.
- File mode: `'a'` (append on `O_APPEND | O_CREAT`). Existing files survive restarts for forensics.
## 5. Public API
```ts
// packages/cli/src/serve/daemonLogger.ts
export interface DaemonLogContext {
route?: string;
sessionId?: string;
clientId?: string;
childPid?: number;
channelId?: string;
[key: string]: unknown;
}
export interface DaemonLogger {
info(message: string, ctx?: DaemonLogContext): void;
warn(message: string, ctx?: DaemonLogContext): void;
/**
* `err.stack` is appended as indented continuation lines after the message.
* Both `err` and `ctx` are optional and independent.
*/
error(message: string, err?: Error | null, ctx?: DaemonLogContext): void;
/**
* File-only tee for lines whose caller is already writing to stderr
* (ACP child stderr forwarder, `writeServeDebugLine`). The line is
* appended to the daemon log under the standard `<timestamp> [<LEVEL>] [DAEMON] `
* prefix; it is NOT echoed to stderr (which would double the operator's output).
*/
raw(line: string, level?: 'info' | 'warn' | 'error'): void;
/** Absolute path to the daemon log file. */
getLogPath(): string;
/** `serve-<pid>-<workspaceHash>`. */
getDaemonId(): string;
/** Drain pending appends. Called from runQwenServe shutdown handler. */
flush(): Promise<void>;
}
export interface InitDaemonLoggerOptions {
boundWorkspace: string;
pid?: number; // default process.pid
now?: () => Date; // default () => new Date()
stderr?: (line: string) => void; // default writeStderrLine
baseDir?: string; // default Storage.getGlobalDebugDir()
}
export function initDaemonLogger(opts: InitDaemonLoggerOptions): DaemonLogger;
```
`initDaemonLogger` synchronously:
1. Computes `daemonId` + log path.
2. `mkdirSync(parentDir, { recursive: true })` — fail → return no-op logger, write one stderr warning. Boot continues.
3. `appendFileSync(path, '<first line>\n', { flag: 'a' })` — writes `daemon started pid=<pid> workspace=<boundWorkspace> version=<cli version>` synchronously. This doubles as a writability probe; on EACCES/ENOSPC, fail-mode = no-op logger + one stderr warning.
4. Updates `latest` symlink (best-effort, errors swallowed).
5. Returns logger; subsequent `info/warn/error/raw` calls enqueue async `fs.promises.appendFile`.
If `process.env['QWEN_DAEMON_LOG_FILE']` is one of `0|false|off|no`, `initDaemonLogger` short-circuits to a no-op logger before any filesystem call.
## 6. Log Line Format
Mirror `debugLogger.buildLogLine` for visual parity:
```
2026-05-26T03:14:15.926Z [ERROR] [DAEMON] [trace_id=... span_id=...] route=POST /session/:id/prompt sessionId=abc clientId=xyz daemon failed to ...
at fn (file.ts:42:7)
at ...
```
- Timestamp: ISO 8601, UTC.
- Level: `INFO` | `WARN` | `ERROR`. (No DEBUG initially — `QWEN_SERVE_DEBUG` flows in as `INFO` via `raw()`.)
- Tag: literal `DAEMON`.
- Trace context: `trace.getActiveSpan()` when available; same logic as `debugLogger.getActiveSpanTraceContext`. Helper extracted to a shared module (`packages/core/src/utils/traceContext.ts`?) or duplicated locally — leave to plan.
- Context fields: rendered as `key=value`, fixed order (`route`, `sessionId`, `clientId`, `childPid`, `channelId`), then any extra keys sorted lexicographically. Values containing whitespace or `=` are `JSON.stringify`-quoted.
- Error stack: appended as indented continuation lines after the message.
- `raw(line, level)` writes the line as-is after the standard prefix `<timestamp> [<LEVEL>] [DAEMON] `, no extra processing.
**Tee semantics (important):**
- `info` / `warn` / `error` write to **both** the daemon log file **and** stderr (via the injected `stderr` writer). Callers replacing a previous `writeStderrLine(...)` use these directly; no separate stderr call needed.
- `raw` writes to **file only**. Used by ACP child stderr forwarder and `writeServeDebugLine`, where the caller is already writing to stderr through its existing path. Doubling would flood operator output.
## 7. Boot / Shutdown Flow
```
runQwenServe(opts):
...
daemonLog = initDaemonLogger({ boundWorkspace })
writeStderrLine(`qwen serve: daemon log → ${daemonLog.getLogPath()}`)
// boot banner is stderr-only to avoid the line referencing itself
bridge = createHttpAcpBridge({
...,
onDiagnosticLine: (line, level) => daemonLog.raw(line, level),
})
app = createServeApp({ ..., daemonLog }) // injected for sendBridgeError
shutdownHandler(signal):
daemonLog.warn(`shutdown signal=${signal}`)
await drainBridge()
await daemonLog.flush()
process.exit(0)
```
- Boot banner is stderr-only (the path line about itself would be circular if logged).
- `initDaemonLogger` is synchronous so any failure is visible immediately at boot, not buried after the first error.
- Shutdown `flush()` is the last awaited step before `process.exit`. SIGKILL is unflushable by definition — we accept that.
## 8. Coverage Table
| Source | Today | After |
| ------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `runQwenServe.ts` lifecycle / signals / config warnings | `writeStderrLine(...)` | `daemonLog.info \| warn(...)` (stderr still happens — `daemonLog` tees) |
| `runQwenServe.ts` "listening on URL" (stdout) | `writeStdoutLine(...)` | unchanged — operator scripts parse stdout |
| `server.ts:sendBridgeError` | `writeStderrLine(...)` with route/sessionId | `daemonLog.error(msg, err, { route, sessionId, ... })` (stderr still emitted by daemonLog's tee) |
| `bridge.ts:writeServeDebugLine` (`QWEN_SERVE_DEBUG`) | `writeStderrLine('qwen serve debug: ...')` | tee to `onDiagnosticLine(line, 'info')` |
| `spawnChannel.ts` child stderr | `process.stderr.write(prefix + line + '\n')` | also `onDiagnosticLine(prefix + line, 'warn')` |
| `writeStdoutLine` callers | unchanged | unchanged |
| CLI usage / argparse errors (`runQwenServe` early validation) | `writeStderrLine(...)` | unchanged (logger may not exist yet) |
Every existing stderr write is preserved. Daemon log is **additive**, never substitutive.
## 9. Write Path & Flush
- Internal queue: a single `Promise<void>` chain (`this.pending = this.pending.then(() => fs.promises.appendFile(...))`).
- Each `info/warn/error/raw` call enqueues an append (file) and, for `info/warn/error`, also synchronously calls the injected `stderr` writer.
- Stderr write order is preserved (synchronous, before queuing the append). File appends are eventually consistent in enqueue order.
- Write failures set an internal `degraded` flag and emit a one-time stderr warning. Subsequent calls still attempt the write but the counter is not maintained.
- `flush()` returns the current tail promise.
- No buffering layer: each call = one `appendFile`. Volume is low (route errors + lifecycle); micro-batching is premature optimization.
## 10. Configuration
| Env var | Behavior |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `QWEN_DAEMON_LOG_FILE=0\|false\|off\|no` | `initDaemonLogger` returns no-op; tee is a no-op; stderr unchanged |
| `QWEN_DAEMON_LOG_FILE=<anything else>` or unset | Enabled (default) |
| `QWEN_RUNTIME_DIR=<path>` | Relocates `~/.qwen` root, daemon log moves with it (existing semantics) |
| `QWEN_SERVE_DEBUG=1` | Existing — `writeServeDebugLine` activates; lines now also tee to daemon log |
`QWEN_DAEMON_LOG_FILE` is intentionally separate from `QWEN_DEBUG_LOG_FILE` so disabling per-session debug logs doesn't take down the operator's daemon log (and vice versa).
## 11. Error Handling
- `initDaemonLogger` mkdir/open failure → no-op logger + one stderr warning. Daemon boot proceeds. Operator sees nothing in the file but still gets stderr.
- Per-append failures → flip degraded flag, emit one stderr warning, keep trying. Issue says nothing about a degraded-mode UI signal, so no public surface needed.
- `flush()` rejection → caught in shutdown handler, logged via `writeStderrLine`. Does not block exit.
- `latest` symlink failure → swallowed; primary writes unaffected.
## 12. Testing
### `daemonLogger.test.ts` (new)
- Sandboxed `baseDir`, mocked `now`, `pid`, `stderr`.
- Path & daemon-id derivation including the 8-char `workspaceHash` for known input.
- `latest` symlink created and updated on subsequent `initDaemonLogger` invocations in the same dir.
- Level formatting (INFO/WARN/ERROR), context field order, error stack continuation.
- Trace context injection when an active span exists.
- `raw(line, level)` writes the prefixed line verbatim.
- `flush()` resolves only after all enqueued writes hit the file.
- `QWEN_DAEMON_LOG_FILE=0` → no file created.
- `mkdir` failure → no-op logger, one stderr warning, subsequent calls don't throw.
- `appendFile` failure → degraded flag flipped, one stderr warning.
### `runQwenServe.test.ts` (extend)
- Boot writes `daemon started ...` line to the log.
- Shutdown handler awaits `daemonLog.flush()` before exit.
- Stderr boot banner contains the daemon log path.
### `server.test.ts` (extend)
- A route that throws routes the error through `daemonLog.error(...)` with the right `route` and `sessionId`.
### acp-bridge tests (extend)
- `onDiagnosticLine` callback invoked from `writeServeDebugLine` when `QWEN_SERVE_DEBUG=1` and from `spawnChannel` child stderr forwarder. Tests inject a capturing fake; no filesystem.
## 13. Documentation
- `docs/cli/serve.md` (or wherever serve is documented) gains a "Daemon log file" section covering: path, daemon-id format, `latest` symlink, `QWEN_DAEMON_LOG_FILE` opt-out, distinction from per-session `debug/<sessionId>.txt`.
- README under `packages/cli/src/serve/` if one exists.
- No CHANGELOG-style file in this repo; release notes are handled separately.
## 14. Rollback
- Pure-additive change. Rollback = revert the commit:
- Delete `daemonLogger.ts` + its test.
- Revert `runQwenServe.ts` lifecycle / sendBridgeError / bridge / spawnChannel changes.
- Remove `onDiagnosticLine` from `BridgeOptions`.
- No on-disk state to clean up; existing daemon log files become orphaned but harmless.
## 15. Acceptance Criteria (from issue)
| Criterion | How met |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `qwen serve` creates / appends daemon log without shell redirection | `initDaemonLogger` opens the file at boot |
| HTTP 500 from `POST /session/:id/prompt` correlatable in daemon log | `sendBridgeError` writes `route=` + `sessionId=` |
| ACP child stderr lines also in daemon log | `spawnChannel` tees through `onDiagnosticLine` |
| Logging works before first session and after all sessions closed | Not session-scoped; lives for daemon lifetime |
| Existing stderr behavior intact | All writes are additive; no `writeStderrLine` call is removed without an equivalent left in place |
| Log path + opt-out documented | Docs section in §13 |
## 16. Open Questions
None blocking. Possible follow-ups:
- Should `latest` symlink go in `~/.qwen/debug/daemon/latest` or `~/.qwen/debug/daemon-latest`? Spec picks the former for directory tidiness.
- Should we offer JSON-line output as a future flag (e.g., `QWEN_DAEMON_LOG_FORMAT=json`)? Out of scope for this PR; structured export is what #2014 owns.

View File

@ -1,434 +0,0 @@
# DaemonWorkspaceService 实施设计(方案 C)
> 关联:issue #4542, PR #4472, #3803, #4175
> 分支:`daemon_mode_b_main`
> 日期:2026-05-27
> 性质:实施设计文档(面向落地),非 RFC
---
> **落地范围说明(2026-05-31 更新,PR #4563)**
>
> 本文档描述的是**终态架构**。PR #4563 只落地其中一部分,其余为后续 PR 范围。阅读时请以下表为准,不要假设全部已实现:
>
> | 能力 | 本 PR (#4563) 状态 |
> | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
> | `HttpAcpBridge` → `AcpSessionBridge` 改名 | ✅ 已落地 |
> | bridge 暴露 `queryWorkspaceStatus` / `invokeWorkspaceCommand` 泛型委托 | ✅ 已落地 |
> | facade 的 workspace 级 **status / init / tool-toggle / mcp-restart** | ✅ 已落地并接线(server.ts + acpHttp dispatch 走 facade) |
> | **File / Auth / Agents / Memory 四个 sub-service** | ⏳ **deferred** —— 不在本 PR。连同各自的路由接线、`deviceFlowRegistry`/`subagentManager` 注入、e2e 测试一起在后续 PR 落地 |
> | `/workspace/memory`、`/workspace/agents` 等 REST 路由改调 facade | ⏳ **deferred** —— 当前仍由旧的 `workspaceMemory.ts` / `workspaceAgents.ts` 直接服务 |
> | `/acp` northbound `qwen/workspace/*` dispatch(§6) | ⏳ **deferred** |
> | `initWorkspace` 走 `fsFactory` / `WorkspaceFileSystem`(trust gate + audit) | ⏳ **deferred** —— 当前沿用旧 bridge 的 raw `node:fs` 实现(含 §SV TOCTOU/symlink 防护),无回归;fsFactory/audit 迁移留待后续 |
>
> 因此本文 §3.4(子服务接口)、§6(/acp northbound)、§7.1 中的 `e2e.test.ts`、§10 的 PR 形态描述均属**终态/未来范围**,本 PR 未实现。
---
## 1. 架构与边界
### 1.1 终态分层
```
CLIENTS
webui SDK/channels(via REST) Zed/Goose(/acp) future
│ │ │
═════╪═════════════╪═══════════════════════╪═════════════ L1 transport (薄)
REST+SSE REST+SSE /acp (jsonrpc/sse)
server.ts acpHttp/
└─────────────┴───────────────────────┘
│ 业务/trust/audit 一律下沉 L2
═════════════════════════╪═══════════════════════════════ L2 应用层
┌──────────────────────────┐ ┌─────────────────────────────────┐
│ AcpSessionBridge │ │ DaemonWorkspaceService (facade) │
│ (← HttpAcpBridge 改名) │ │ ┌──────────────────────────┐ │
│ • channel/session 生命周期 │ │ │ FileService │ │
│ • prompt / cancel / close │ │ │ AuthService │ │
│ • EventBus / 权限仲裁 │ │ │ AgentsService │ │
│ • 依赖 child 的状态内省 │ │ │ MemoryService │ │
│ (mcp/skills/preflight) │ │ └──────────────────────────┘ │
└──────────┬───────────────┘ │ 统一 WorkspaceRequestContext │
│ └──────────┬──────────────────────┘
│ L3 → child │
▼ │ (纯本地,不碰 child)
══════════════════════════════════════════════════════════ L3 ACP-client
══════════════════════════════════════════════════════════ L4 agent
```
### 1.2 拆分判定函数
**唯一规则:操作的 scope 是 session 还是 workspace?**
- **session-scoped**(操作特定 sessionId:prompt/cancel/close/model/approval/metadata/heartbeat)**→ 留 `AcpSessionBridge`**
- **workspace-scoped**(操作工作区整体:file/auth/agents/memory/mcp-status/skills/env/preflight/tool-toggle/init)**→ 进 `DaemonWorkspaceService`**
workspace 方法中部分需要查询 child(status getters、restartMcpServer),通过 **injected callback** 委托 bridge 的 channel 完成,service 本身不持有 connection。
### 1.3 跨切依赖:callback 注入(非共享 infra)
当前 `publishWorkspaceEvent` 和 `knownClientIds` 由 bridge 持有(per-session bus fan-out / session-derived)。service 通过 **单向 callback 注入** 使用它们,不引入共享基础设施层。
**理由:**
1. EventBus 是 per-session bus(`bridge.ts:1457`),workspace-level bus 在代码注释中已挂在 PR 24(`bridge.ts:2611`)
2. `knownClientIds` 同样是派生自 session-attach state,注释明确 "PR 24 will replace it"(`bridge.ts:2658`)
3. 这两件是已立项独立工作,硬绑进本 PR 等于叠加额外 refactor
4. callback 注入对 service 是单向依赖(只持函数引用,不知道来自 bridge);PR 24 落地后换注入源即可,service 接口不变
**硬规则:**
1. `DaemonWorkspaceServiceDeps` 中不得出现 `AcpSessionBridge` 类型引用——只用函数签名。
2. bridge 对外新暴露 `queryWorkspaceStatus` 和 `invokeWorkspaceCommand` 两个方法,供 service 通过 callback 调用。内部仍使用现有的 `requestWorkspaceStatus` / `liveChannelInfo` + timeout 逻辑,不新建抽象。
---
## 2. 构造时序与依赖注入
```ts
// runQwenServe.ts 中的构造顺序
// 1. fsFactory 先构造(两者共享)
const fsFactory = resolveBridgeFsFactory({ ... });
// 2. bridge 先构造(它是 session/channel/EventBus 的 owner)
const bridge = createAcpSessionBridge({
eventRingSize,
boundWorkspace,
fileSystem: createBridgeFileSystemAdapter(fsFactory),
// ... 其他现有参数不变
});
// 3. service 后构造,接收 bridge 的 callback 集
const workspace = createDaemonWorkspaceService({
fsFactory,
deviceFlowRegistry,
subagentManager,
boundWorkspace,
contextFilename,
// 跨切 callback — service 不知道它们来自 bridge
publishWorkspaceEvent: (event) => bridge.publishWorkspaceEvent(event),
knownClientIds: () => bridge.knownClientIds(),
// child 委托 callback — workspace-scoped ext method 通过 bridge 的 channel 到达 agent
queryWorkspaceStatus: (method, idle) => bridge.queryWorkspaceStatus(method, idle),
invokeWorkspaceCommand: (method, params, opts) => bridge.invokeWorkspaceCommand(method, params, opts),
});
// 4. 两者传给 server routes + /acp handler
createServeApp({ bridge, workspace, ... });
```
**构造顺序 bridge → service 是硬依赖**(service 需要 bridge 实例上的方法作为 callback 源)。
---
## 3. DaemonWorkspaceService 内部结构
### 3.1 目录布局
```
packages/cli/src/serve/workspace-service/
├── types.ts ← WorkspaceRequestContext + sub-service interfaces
├── index.ts ← facade factory (createDaemonWorkspaceService)
├── fileService.ts ← wraps fsFactory
├── authService.ts ← wraps DeviceFlowRegistry
├── agentsService.ts ← wraps SubagentManager
├── memoryService.ts ← wraps memory file ops
└── __tests__/
├── fileService.test.ts
├── authService.test.ts
├── agentsService.test.ts
├── memoryService.test.ts
└── e2e.test.ts
```
### 3.2 Facade 接口
```ts
export interface DaemonWorkspaceService {
file: FileService;
auth: AuthService;
agents: AgentsService;
memory: MemoryService;
// 纯本地
initWorkspace(
opts: InitWorkspaceOpts,
ctx: WorkspaceRequestContext,
): Promise<void>;
setToolEnabled(
toolName: string,
enabled: boolean,
ctx: WorkspaceRequestContext,
): Promise<ToolToggleResult>;
// 通过 callback 委托 child
getMcpStatus(): Promise<ServeWorkspaceMcpStatus>;
getSkillsStatus(): Promise<ServeWorkspaceSkillsStatus>;
getProvidersStatus(): Promise<ServeWorkspaceProvidersStatus>;
getEnvStatus(): Promise<ServeWorkspaceEnvStatus>;
getPreflightStatus(): Promise<ServeWorkspacePreflightStatus>;
restartMcpServer(
serverName: string,
ctx: WorkspaceRequestContext,
opts?: RestartOpts,
): Promise<RestartResult>;
}
```
> `listWorkspaceSessions` / `recordHeartbeat` / `getHeartbeatState` / `publishWorkspaceEvent` / `knownClientIds` 留在 bridge——它们访问 bridge 内部的 per-session state(`byId` map / session bus),是 session 衍生的基础设施。service 通过 callback 消费,不直接拥有。
### 3.3 Facade Factory 签名
```ts
export interface DaemonWorkspaceServiceDeps {
fsFactory: WorkspaceFileSystemFactory;
deviceFlowRegistry: DeviceFlowRegistry;
subagentManager: SubagentManager;
boundWorkspace: string;
contextFilename: string;
persistDisabledTools: (
workspace: string,
tool: string,
enabled: boolean,
) => Promise<void>;
// 跨切 callback(session 衍生基础设施)
publishWorkspaceEvent: (event: WorkspaceEvent) => void;
knownClientIds: () => Set<string>;
// child 委托 callback(workspace-scoped ext method 通过 bridge channel 到达 agent)
queryWorkspaceStatus: <T>(method: string, idle: () => T) => Promise<T>;
invokeWorkspaceCommand: <T>(
method: string,
params?: Record<string, unknown>,
opts?: { timeoutMs?: number },
) => Promise<T>;
}
export function createDaemonWorkspaceService(
deps: DaemonWorkspaceServiceDeps,
): DaemonWorkspaceService;
```
### 3.4 各子服务接口
| 子服务 | 方法 | 所需 deps | 现有来源 |
| ------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| FileService | `read`, `readBytes`, `write`, `edit`, `glob`, `list`, `stat` | `fsFactory`, `boundWorkspace` | `serve/routes/workspaceFileRead.ts`, `workspaceFileWrite.ts`, `serve/fs/` |
| AuthService | `startFlow`, `getFlowStatus(flowId)`, `cancelFlow(flowId)`, `getAuthStatus` | `deviceFlowRegistry` | `serve/auth/deviceFlow.ts`, `server.ts:794-966` |
| AgentsService | `list`, `get(agentType)`, `create`, `update`, `delete` | `subagentManager`, `publishWorkspaceEvent`, `knownClientIds` | `serve/workspaceAgents.ts` |
| MemoryService | `list`, `read`, `write`, `delete` | `fsFactory` or direct fs, `publishWorkspaceEvent`, `knownClientIds` | `serve/workspaceMemory.ts` |
每个方法第一个参数都是 `ctx: WorkspaceRequestContext`,trust gate 在方法入口统一执行。
---
## 4. WorkspaceRequestContext
```ts
export interface WorkspaceRequestContext {
originatorClientId?: string; // X-Qwen-Client-Id header(只读操作可缺失)
sessionId?: string; // audit 关联(如从 session context 内发起的操作)
route: string; // audit trail(如 "POST /file/write")
workspaceCwd: string; // trust boundary root
}
```
> `originatorClientId` 为 optional——当前 file read 等只读路由在 header 缺失时照常工作(`clientId ?? undefined` 传入 `fsFactory.forRequest`)。write 路由在 clientId **存在时**才校验合法性。
**构建位置**:L1 route handler / `/acp` method handler 从 request headers/params 提取后传入 L2。L2 只消费,不自行提取 HTTP context。
---
## 5. AcpSessionBridge 瘦身与改名
### 5.1 从 bridge 迁出的方法
| 方法 | 去向 | 机制 | 理由 |
| ----------------------------- | ------------------------------ | ------------------------------------- | -------------------------------------------------------------- |
| `initWorkspace` | `workspace.initWorkspace` | 直接迁(纯本地) | 附带修 FIXME(bridge 没接 fsFactory,跳过 trust gate / audit) |
| `setWorkspaceToolEnabled` | `workspace.setToolEnabled` | 直接迁(纯本地) | 纯 file I/O + event fan-out,注释明确 "no ACP roundtrip" |
| `getWorkspaceMcpStatus` | `workspace.getMcpStatus` | via `queryWorkspaceStatus` callback | workspace-scoped status query |
| `getWorkspaceSkillsStatus` | `workspace.getSkillsStatus` | via `queryWorkspaceStatus` callback | 同上 |
| `getWorkspaceProvidersStatus` | `workspace.getProvidersStatus` | via `queryWorkspaceStatus` callback | 同上 |
| `getWorkspaceEnvStatus` | `workspace.getEnvStatus` | via `queryWorkspaceStatus` callback | 同上 |
| `getWorkspacePreflightStatus` | `workspace.getPreflightStatus` | via `queryWorkspaceStatus` callback | 同上 |
| `restartMcpServer` | `workspace.restartMcpServer` | via `invokeWorkspaceCommand` callback | workspace-scoped mutation |
> `listWorkspaceSessions` / `recordHeartbeat` / `getHeartbeatState` / `updateSessionMetadata` 保留在 bridge——它们访问 bridge 内部 `byId` session map,是 session-scoped 操作。
### 5.2 留在 bridge 的
- 所有 session/channel 生命周期(spawn/load/resume/send/cancel/close/kill/detach)
- EventBus 持有 + `publishWorkspaceEvent` fan-out 实现(供 service callback 消费)
- `knownClientIds`(供 service callback 消费)
- `queryWorkspaceStatus` / `invokeWorkspaceCommand`(新暴露,封装 channel + timeout + error,供 service callback 委托)
- 权限仲裁 mediator
- session 配置变更(model/approvalMode/recap)
- session 状态(context/supportedCommands/metadata/heartbeat/listSessions)
### 5.3 改名
- `HttpAcpBridge` → `AcpSessionBridge`
- `createHttpAcpBridge` → `createAcpSessionBridge`
- 文件 `serve/httpAcpBridge.ts` → `serve/acpSessionBridge.ts`
无外部包消费者(验证过 `packages/cli/src/serve/` 和 `packages/acp-bridge/src/` 之外无引用),内部安全。
---
## 6. /acp northbound ext methods
### 6.1 命名空间
`qwen/workspace/...`(与现有 `qwen/control/...` 区分):
- `qwen/control/...` = daemon→child 转发命令(southbound,经 AcpSessionBridge)
- `qwen/workspace/...` = daemon 本地工作区操作(northbound,终止于 DaemonWorkspaceService)
> 待 chiga0 确认。如改命名空间只需换方法名前缀,不影响架构。
### 6.2 方法列表
| method | 对应 REST | L2 调用 |
| --------------------------------- | ----------------------------------------------- | --------------------------------------------------- |
| `qwen/workspace/fs/read` | `GET /file?path=...` | `workspace.file.read(ctx, path)` |
| `qwen/workspace/fs/readBytes` | `GET /file/bytes?path=...` | `workspace.file.readBytes(ctx, path)` |
| `qwen/workspace/fs/write` | `POST /file/write` | `workspace.file.write(ctx, path, content)` |
| `qwen/workspace/fs/edit` | `POST /file/edit` | `workspace.file.edit(ctx, path, edits)` |
| `qwen/workspace/fs/glob` | `GET /glob?pattern=...` | `workspace.file.glob(ctx, pattern)` |
| `qwen/workspace/fs/list` | `GET /list?path=...` | `workspace.file.list(ctx, path)` |
| `qwen/workspace/fs/stat` | `GET /stat?path=...` | `workspace.file.stat(ctx, path)` |
| `qwen/workspace/auth/start` | `POST /workspace/auth/device-flow` | `workspace.auth.startFlow(ctx)` |
| `qwen/workspace/auth/status` | `GET /workspace/auth/status` | `workspace.auth.getAuthStatus(ctx)` |
| `qwen/workspace/auth/flow` | `GET /workspace/auth/device-flow/:id` | `workspace.auth.getFlowStatus(ctx, flowId)` |
| `qwen/workspace/auth/cancel` | `POST /workspace/auth/device-flow/:id` (cancel) | `workspace.auth.cancelFlow(ctx, flowId)` |
| `qwen/workspace/agents/list` | `GET /workspace/agents` | `workspace.agents.list(ctx)` |
| `qwen/workspace/agents/get` | `GET /workspace/agents/:agentType` | `workspace.agents.get(ctx, agentType)` |
| `qwen/workspace/agents/create` | `POST /workspace/agents` | `workspace.agents.create(ctx, spec)` |
| `qwen/workspace/agents/update` | `POST /workspace/agents/:agentType` | `workspace.agents.update(ctx, agentType, spec)` |
| `qwen/workspace/agents/delete` | `DELETE /workspace/agents/:agentType` | `workspace.agents.delete(ctx, agentType)` |
| `qwen/workspace/memory/list` | `GET /workspace/memory` | `workspace.memory.list(ctx)` |
| `qwen/workspace/memory/read` | `GET /workspace/memory/:key` | `workspace.memory.read(ctx, key)` |
| `qwen/workspace/memory/write` | `POST /workspace/memory` | `workspace.memory.write(ctx, key, content)` |
| `qwen/workspace/memory/delete` | `DELETE /workspace/memory/:key` | `workspace.memory.delete(ctx, key)` |
| `qwen/workspace/init` | `POST /workspace/init` | `workspace.initWorkspace(ctx, opts)` |
| `qwen/workspace/tool/toggle` | `POST /workspace/tool/toggle` | `workspace.setToolEnabled(ctx, toolName, enabled)` |
| `qwen/workspace/status/mcp` | `GET /workspace/mcp` | `workspace.getMcpStatus()` |
| `qwen/workspace/status/skills` | `GET /workspace/skills` | `workspace.getSkillsStatus()` |
| `qwen/workspace/status/providers` | `GET /workspace/providers` | `workspace.getProvidersStatus()` |
| `qwen/workspace/status/env` | `GET /workspace/env` | `workspace.getEnvStatus()` |
| `qwen/workspace/status/preflight` | `GET /workspace/preflight` | `workspace.getPreflightStatus()` |
| `qwen/workspace/mcp/restart` | `POST /workspace/mcp/restart` | `workspace.restartMcpServer(ctx, serverName, opts)` |
Capabilities advertise 时在 `_meta.qwen.methods` 中声明这些方法。
---
## 7. 文件变更清单
### 7.1 新增
| 文件 | 用途 |
| --------------------------------------------------------- | -------------------------------------------------- |
| `serve/workspace-service/types.ts` | `WorkspaceRequestContext` + sub-service interfaces |
| `serve/workspace-service/index.ts` | facade factory |
| `serve/workspace-service/fileService.ts` | FileService 实现 |
| `serve/workspace-service/authService.ts` | AuthService 实现 |
| `serve/workspace-service/agentsService.ts` | AgentsService 实现 |
| `serve/workspace-service/memoryService.ts` | MemoryService 实现 |
| `serve/workspace-service/__tests__/fileService.test.ts` | unit test |
| `serve/workspace-service/__tests__/authService.test.ts` | unit test |
| `serve/workspace-service/__tests__/agentsService.test.ts` | unit test |
| `serve/workspace-service/__tests__/memoryService.test.ts` | unit test |
| `serve/workspace-service/__tests__/e2e.test.ts` | 端到端 REST ↔ /acp 等价验证 |
### 7.2 修改
| 文件 | 变更 |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acp-bridge/src/bridge.ts` | 移除 8 个 workspace 方法(initWorkspace / setWorkspaceToolEnabled / 5 status getters / restartMcpServer);新暴露 `queryWorkspaceStatus` + `invokeWorkspaceCommand`;重命名工厂函数 |
| `acp-bridge/src/bridgeTypes.ts` | 接口改名 `HttpAcpBridge` → `AcpSessionBridge`;移除 8 个 workspace 方法签名;新增 `queryWorkspaceStatus` + `invokeWorkspaceCommand` 签名 |
| `acp-bridge/src/bridgeOptions.ts` | 更新 JSDoc 引用 |
| `acp-bridge/src/status.ts` | 更新错误消息中的类名 |
| `cli/src/serve/httpAcpBridge.ts` → 改名 `acpSessionBridge.ts` | re-export 更新 |
| `cli/src/serve/runQwenServe.ts` | 构造 `DaemonWorkspaceService`,注入 callback,传给 routes 和 /acp handler |
| `cli/src/serve/server.ts` | routes 从直连 `fsFactory`/`DeviceFlowRegistry` 改为调 `workspace.file.*` / `workspace.auth.*` |
| `cli/src/serve/workspaceAgents.ts` | 业务逻辑迁入 `agentsService.ts`;原文件变成 route handler 薄壳(构建 ctx → 调 service) |
| `cli/src/serve/workspaceMemory.ts` | 同上 |
| `cli/src/serve/routes/workspaceFileRead.ts` | 同上 |
| `cli/src/serve/routes/workspaceFileWrite.ts` | 同上 |
| `/acp` handler(`acp-integration/` 或 `serve/` 内) | 新增 northbound method dispatch |
---
## 8. SDK 兼容与错误格式
### 8.1 SDK backward compat
REST API surface(路径、HTTP 方法、请求/响应 JSON schema)保持不变。`sdk-typescript` 中的 `DaemonClient` / `DaemonSessionClient` 无需任何改动。
验证方式:现有 `packages/sdk-typescript/test/unit/DaemonClient.test.ts` 和 `DaemonSessionClient.test.ts` 在本 PR 中必须零修改通过。
### 8.2 /acp trust gate 拒绝的错误格式
两传输语义等价但编码不同:
| 场景 | REST | /acp (JSON-RPC) |
| ----------------------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
| 无效/缺失 bearer token | `401 { error, code: "unauthorized" }` | `{ error: { code: -32001, message: "unauthorized" } }` |
| 无效 clientId | `400 { error, code: "invalid_client_id" }` | `{ error: { code: -32602, message: "invalid_client_id", data: {...} } }` |
| trust gate 拒绝(路径逃逸等) | `403 { error, code: "forbidden" }` | `{ error: { code: -32003, message: "forbidden", data: {...} } }` |
> JSON-RPC error codes 遵循 [ACP error code registry](https://spec.acpprotocol.org)(标准范围 -32000 ~ -32099 为 server-defined application errors)。具体 code 值在实现时对齐 `/acp` 现有 error 映射逻辑(`acp-integration/errorCodes.ts`)。
---
## 9. 测试策略
| 层 | 测试类型 | 覆盖目标 |
| ----------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| Sub-service unit | Jest,mock fsFactory / DeviceFlowRegistry / SubagentManager / callbacks | 业务逻辑正确性 + trust gate 拒绝非法 clientId |
| Route integration | 现有 route test 改为经 service(验证 HTTP surface 不变) | 回归保障,REST 路径不 break |
| E2e 等价验证 | 启动真实 serve + HTTP 请求 | REST 和 `/acp` 对同一操作返回等价结果;trust gate 两端一致拒绝 |
### E2e 验证矩阵
- File read/write:REST `GET /file` vs `/acp` `qwen/workspace/fs/read` → 同结果
- Agent CRUD:REST `POST /workspace/agents` vs `/acp` `qwen/workspace/agents/create` → 同行为
- Trust gate rejection:无效 clientId 两路径都 403
- Workspace init:验证 fsFactory 走通 + audit trail 产出
---
## 10. PR 形态
单 PR 原子提交,包含:
- DaemonWorkspaceService 全部新建文件
- REST route handler 改为调 service
- bridge 瘦身(迁出 8 个 workspace 方法)+ 新暴露 2 个 child 委托方法
- `HttpAcpBridge` → `AcpSessionBridge` 改名
- `/acp` northbound ext methods 新增(27 个)
- 全量测试(unit + integration + e2e)
---
## 11. 明确不做(scope boundary)
- workspace-scoped EventBus(PR 24 territory)
- workspace-scoped ClientRegistry(PR 24 territory)
- L2 ↔ L3 拆分(把 `ClientSideConnection` 从 bridge 拆出)
- REST 做成 `/acp` compat shim(长期方向)
- channels standalone 模式统一(独立部署形态问题)
- `listWorkspaceSessions` / `recordHeartbeat` / `getHeartbeatState` / `updateSessionMetadata` 迁移(session-scoped,保留原位)
- `publishWorkspaceEvent` / `knownClientIds` 的 ownership 转移(session 衍生基础设施,保留 bridge 持有,service 通过 callback 消费)
---
## 12. 待 chiga0 确认的决策点
1. `/acp` northbound 命名空间:`qwen/workspace/...` vs 其他(如复用 `qwen/control/...`)
2. 改名是否同 PR:倾向同 PR,但可按反馈拆出
> 以上两点如需调整,只影响命名和 commit 边界,不影响架构。

View File

@ -15,7 +15,6 @@ export default {
'integration-jetbrains': 'JetBrains IDEs',
'integration-github-action': 'GitHub Actions',
'qwen-serve': 'Daemon mode (qwen serve)',
'qwen-serve-deploy-local': 'Daemon mode — local launch templates',
'Code with Qwen Code': {
type: 'separator',
title: 'Code with Qwen Code', // Title is optional

View File

@ -1,9 +1,6 @@
export default {
settings: 'Settings',
auth: 'Authentication',
memory: {
display: 'hidden',
},
'qwen-ignore': 'Ignoring Files',
'trusted-folders': 'Trusted Folders',
themes: 'Themes',

View File

@ -143,10 +143,16 @@ Settings are organized into categories. Most settings should be placed within th
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `model.name` | string | The Qwen model to use for conversations. | `undefined` |
| `model.maxSessionTurns` | number | 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.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.generationConfig` | object | Advanced overrides passed to the underlying content generator. Supports request controls such as `timeout`, `maxRetries`, `enableCacheControl`, `splitToolMedia` (set `true` for strict OpenAI-compatible servers like LM Studio that reject non-text content on `role: "tool"` messages — splits media into a follow-up user message), `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` |
| `model.chatCompression.contextPercentageThreshold` | number | Sets the threshold for chat history compression as a percentage of the model's total token limit. This is a value between 0 and 1 that applies to both automatic compression and the manual `/compress` command. For example, a value of `0.6` will trigger compression when the chat history exceeds 60% of the token limit. Use `0` to disable compression entirely. | `0.7` |
| `model.chatCompression.contextPercentageThreshold` | number | **REMOVED.** Auto-compaction now uses a three-tier threshold ladder (warn / auto / hard) computed internally from the model's context window via the `computeThresholds()` function — no longer user-configurable. Setting this field in `settings.json` is silently ignored (no startup warning). There is currently no replacement for "disable compression entirely" — reactive overflow recovery remains the safety net at the API layer if compression itself fails. (See PR #4345 / `docs/design/auto-compaction-threshold-redesign.md` for the redesign rationale.) | `N/A` |
| `model.chatCompression.maxRecentFilesToRetain` | number | Number of most-recently-touched files whose current content is restored (embedded if small, otherwise referenced by path) into history after auto-compaction. `0` restores none. Env override: `QWEN_COMPACT_MAX_RECENT_FILES`. | `5` |
| `model.chatCompression.maxRecentImagesToRetain` | number | Number of most-recent images (tool screenshots / user pastes) restored into history after auto-compaction. `0` restores none. Env override: `QWEN_COMPACT_MAX_RECENT_IMAGES`. | `3` |
| `model.chatCompression.enableScreenshotTrigger` | boolean | When `true`, auto-compaction also fires once the number of tool-returned images accumulated in history reaches `screenshotTriggerThreshold`, independent of token usage — aimed at computer-use sessions where frequent screenshots dilute model attention. Counts only images returned inside tool results, not user-pasted images. Env override: `QWEN_COMPACT_SCREENSHOT_TRIGGER` (`1`/`true`/`0`/`false`). | `true` |
| `model.chatCompression.screenshotTriggerThreshold` | number | Tool-returned image count at or above which the screenshot trigger fires (only when `enableScreenshotTrigger`). Compaction resets the count — surviving images are re-embedded as top-level parts, which the trigger doesn't count — so it won't immediately re-fire. Env override: `QWEN_COMPACT_SCREENSHOT_THRESHOLD`. | `50` |
| `model.skipNextSpeakerCheck` | boolean | Skip the next speaker check. | `false` |
| `model.skipLoopDetection` | boolean | Disables loop detection checks. Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions. | `false` |
| `model.skipLoopDetection` | boolean | Disables streaming loop detection checks. Defaults to `true` (loop detection is skipped) to avoid false positives interrupting legitimate workflows. Set to `false` to re-enable streaming loop detection — useful as a guardrail in headless / non-interactive runs where stuck repetition can otherwise waste budget. | `true` |
| `model.skipStartupContext` | boolean | Skips sending the startup workspace context (environment summary and acknowledgement) at the beginning of each session. Enable this if you prefer to provide context manually or want to save tokens on startup. | `false` |
| `model.enableOpenAILogging` | boolean | Enables logging of OpenAI API calls for debugging and analysis. When enabled, API requests and responses are logged to JSON files. | `false` |
| `model.openAILoggingDir` | string | Custom directory path for OpenAI API logs. If not specified, defaults to `logs/openai` in the current working directory. Supports absolute paths, relative paths (resolved from current working directory), and `~` expansion (home directory). | `undefined` |
@ -272,7 +278,8 @@ If you are experiencing performance issues with file searching (e.g., with `@` c
| Setting | Type | Description | Default |
| -------------------------------- | ------- | --------------------------------------------------------------------------------- | ------- |
| `memory.enableManagedAutoMemory` | boolean | Enable background extraction of memories from conversations. | `true` |
| `memory.enableManagedAutoDream` | boolean | Enable automatic consolidation (deduplication and cleanup) of collected memories. | `false` |
| `memory.enableManagedAutoDream` | boolean | Enable automatic consolidation (deduplication and cleanup) of collected memories. | `true` |
| `memory.enableAutoSkill` | boolean | Enable background review for reusable project skills after tool-heavy sessions. | `true` |
See [Memory](../features/memory) for details on how auto-memory works and how to use the `/memory`, `/remember`, and `/dream` commands.
@ -703,7 +710,9 @@ Qwen Code can execute potentially unsafe operations (like shell commands and fil
- Using `--sandbox` or `-s` flag.
- Setting `QWEN_SANDBOX` environment variable.
- Sandbox is enabled when using `--yolo` or `--approval-mode=yolo` by default.
- Setting `tools.sandbox` in settings.
> ⚠️ **`--yolo` does _not_ automatically enable a sandbox.** YOLO mode only auto-approves tool calls; sandboxing must still be opted into via `--sandbox`, `QWEN_SANDBOX`, or `tools.sandbox`. In headless / non-interactive runs with `--yolo` (or `--approval-mode=yolo`) and no sandbox, the model can execute shell, write, and edit tools at the current process's privilege level — Qwen Code prints a warning to stderr in that case. Suppress with `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
By default, it uses a pre-built `qwen-code-sandbox` Docker image.

View File

@ -16,6 +16,7 @@ export default {
},
'approval-mode': 'Approval Mode',
'auto-mode': 'Auto Mode',
worktree: 'Worktrees',
mcp: 'MCP',
lsp: 'LSP (Language Server Protocol)',
'token-caching': 'Token Caching',

View File

@ -3,5 +3,6 @@ export default {
telegram: 'Telegram',
weixin: 'WeChat',
dingtalk: 'DingTalk',
feishu: 'Feishu',
plugins: 'Plugins',
};

View File

@ -0,0 +1,170 @@
# Feishu (Lark)
This guide covers setting up a Qwen Code channel on Feishu (飞书) / Lark.
## Prerequisites
- A Feishu organization account
- A Feishu application with App ID and App Secret (see below)
## Creating an Application
1. Go to the [Feishu Open Platform](https://open.feishu.cn)
2. Create a new application (or use an existing one)
3. Under the application, enable the **Bot** capability (添加应用能力 → 机器人)
4. In **Event Subscriptions** (事件与回调), select **Long Connection** (使用长连接接收事件)
5. Add the event `im.message.receive_v1` (接收消息)
6. Note the **App ID** (Client ID) and **App Secret** (Client Secret) from the application credentials page
### Required Permissions
Enable the following permissions under **Permissions & Scopes** (权限管理):
- `im:message` — Read and send messages
- `im:message:send_as_bot` — Send messages as bot
- `im:resource` — Access message resources (images, files)
### Publish the Application
After configuring permissions and events, create a version and publish it. The bot won't work until the application is published and approved.
## Configuration
Add the channel to `~/.qwen/settings.json`:
```json
{
"channels": {
"my-feishu": {
"type": "feishu",
"clientId": "<your-app-id>",
"clientSecret": "<your-app-secret>",
"senderPolicy": "open",
"sessionScope": "user",
"cwd": "/path/to/your/project",
"groupPolicy": "open",
"collapsible": true,
"groups": {
"*": { "requireMention": true }
}
}
}
}
```
### Configuration Options
| Option | Description |
| ---------------------- | ------------------------------------------------------------------- |
| `clientId` | Feishu App ID |
| `clientSecret` | Feishu App Secret |
| `collapsible` | Collapse long responses into expandable sections (default: `false`) |
| `collapsibleThreshold` | Character threshold for collapsing (default: `500`) |
| `webhookPort` | If set, use HTTP webhook mode instead of WebSocket |
| `verificationToken` | Verification token for webhook mode |
| `encryptKey` | Encrypt key for webhook mode |
## Running
```bash
# Start only the Feishu channel
qwen channel start my-feishu
# Or start all configured channels together
qwen channel start
```
Open Feishu and send a message to the bot. You should see a streaming interactive card with the response.
## Connection Modes
### WebSocket (Default)
WebSocket mode uses an outbound long connection — no public URL or server is needed. This is the recommended mode for most deployments.
### Webhook
If you need webhook mode (e.g., for shared applications), set `webhookPort` in your config:
```json
{
"channels": {
"my-feishu": {
"type": "feishu",
"webhookPort": 9321,
"verificationToken": "<from-feishu-console>",
"encryptKey": "<from-feishu-console>"
}
}
}
```
Then set the request URL in Feishu Open Platform to `http://<your-server>:9321`.
## Group Chats
Feishu bots work in both DM and group conversations. To enable group support:
1. Set `groupPolicy` to `"allowlist"` or `"open"` in your channel config
2. Add the bot to a Feishu group
3. @mention the bot in the group to trigger a response
By default, the bot requires an @mention in group chats (`requireMention: true`). Set `"requireMention": false` for a specific group to make it respond to all messages.
## Features
### Interactive Card Streaming
Responses are rendered as Feishu interactive cards with real-time streaming updates. The card shows a "generating" indicator while the response is being produced, and a **Stop** button to cancel generation.
### Quote/Reply Context
When you reply to (quote) a message, the quoted content is automatically included as context for the agent. This works for:
- Text and rich-text messages
- Interactive cards (bot's previous responses)
### Images and Files
You can send photos and documents to the bot:
- **Images:** Analyzed using multimodal vision capabilities
- **Files:** Downloaded and saved locally for the agent to read
### Concurrent Messages
Multiple users can send messages simultaneously in the same group chat. Each message gets its own independent card and response — they don't interfere with each other.
## Key Differences from DingTalk
- **Response format:** Uses Feishu interactive cards (v2 schema) with native markdown rendering, including tables
- **Streaming:** Card content is updated in-place with throttled PATCH requests (1.5s interval)
- **Connection:** WebSocket via `@larksuiteoapi/node-sdk` — same outbound-only model, no public URL needed
- **Working indicator:** An "OnIt" emoji reaction is added while processing
- **Quote context:** Supports quoting both text messages and interactive cards
## Troubleshooting
### Bot doesn't connect
- Verify your App ID and App Secret are correct
- Make sure **Long Connection** is selected in Event Subscriptions
- Check that the `im.message.receive_v1` event is subscribed
- Check the terminal output for connection errors
### Bot doesn't respond in groups
- Check that `groupPolicy` is set to `"allowlist"` or `"open"` (default is `"disabled"`)
- Make sure you @mention the bot in the group message
- Verify the bot has been added to the group
### Card stays in "generating" state
- This usually indicates the response completed but the final card update failed
- Check terminal logs for API errors (rate limiting, card size limits)
- Very long responses with many tables may hit Feishu's card element limits
### Quote doesn't include card content
- The bot reads card content via the `card_msg_content_type=user_card_content` API parameter
- Ensure the bot has `im:message` permission to read messages

View File

@ -238,9 +238,41 @@ Key command-line options for headless usage:
| `--approval-mode` | Set approval mode | `qwen -p "query" --approval-mode auto_edit` |
| `--continue` | Resume the most recent session for this project | `qwen --continue -p "Pick up where we left off"` |
| `--resume [sessionId]` | Resume a specific session (or choose interactively) | `qwen --resume 123e... -p "Finish the refactor"` |
| `--max-session-turns` | Cap the number of user/model/tool turns in the run | `qwen -p "..." --max-session-turns 30` |
| `--max-wall-time` | Wall-clock budget; accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` | `qwen -p "..." --max-wall-time 10m` |
| `--max-tool-calls` | Cumulative tool-call budget for the run | `qwen -p "..." --max-tool-calls 50` |
For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../configuration/settings).
## Safety in unattended runs
Headless / CI runs combined with `--yolo` (or `--approval-mode=yolo`) auto-approve every tool call, including `shell`, `write`, and `edit`. **`--yolo` does not enable a sandbox** — those tools run at the host process's privilege level. When Qwen Code detects this combination with no sandbox configured, it prints a one-line warning to stderr at startup. Suppress the warning with `QWEN_CODE_SUPPRESS_YOLO_WARNING=1` once you've reviewed the trade-off.
### Run-level budgets
Qwen Code can abort an unattended run when it crosses one of the following thresholds. Each is `-1` (unlimited) by default; setting any one is enough to bound runaway behavior. They are enforced cooperatively against the same `AbortController` that already carries SIGINT, so a budget abort emits a structured `FatalBudgetExceededError` (exit code **55**) — distinct from the turn-cap exit code 53 and SIGINT's 130 so CI scripts can branch on the reason.
| Flag | Settings key | What it bounds |
| --------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--max-wall-time` | `model.maxWallTimeSeconds` | Wall-clock duration of the whole run. Flag accepts `90` (s), `30s`, `5m`, `1h`, `1.5h` (fractional units supported). Minimum 1s — sub-second values are rejected as typos. Settings is seconds. |
| `--max-tool-calls` | `model.maxToolCalls` | Cumulative top-level tool calls dispatched by the main run loop (counts successes _and_ failures — the model still consumes tokens on errors). See "Scope" below for subagent / structured-output exemptions. |
| `--max-session-turns` | `model.maxSessionTurns` | Number of user/model/tool turns; pre-existing. Exits with code 53 on overrun (distinct from budget exit 55). |
#### Scope
- **`--max-tool-calls` counts top-level dispatches only.** When the model calls the `agent` tool, the dispatch counts as **1**; inner tool calls performed by the spawned subagent are **not** counted. A model that funnels work through subagents can do unbounded inner work under a small top-level budget. Combine with `--exclude-tools agent` if you need a tighter cap.
- **`structured_output` is exempt from `--max-tool-calls`.** Under `--json-schema`, the model's terminal `structured_output` call is the "I'm done" contract, not real work — it doesn't count against `--max-tool-calls` so a budget-edge completion isn't aborted as a false positive. The exemption is unconditional (including failed Ajv validations), so a model stuck in a malformed-output retry loop is NOT bounded by `--max-tool-calls`; combine with `--max-session-turns` or `--max-wall-time` to cap retries.
- **`structured_output` is NOT exempt from `--max-session-turns`.** That counter is pre-existing and bumps for every turn including the terminal contract. Size `--max-session-turns` to `N+1` if you want to allow `N` real-work turns under `--json-schema`.
- **Single-shot vs `--input-format stream-json`:** in stream-json input mode the daemon resets the budget counters at the start of every user message; the budget is per-message, not per-process.
- **`qwen serve` / ACP sessions:** the daemon ACP session path does NOT currently consult `--max-wall-time` / `--max-tool-calls` from settings.json. These budgets only apply to single-shot `qwen -p` runs and to `--input-format stream-json` sessions. (`qwen serve` does emit the YOLO-no-sandbox warning at boot if `tools.approvalMode: 'yolo'` is set in settings.)
### Recommended combinations
- **Trusted, isolated environment (ephemeral CI runner, container):** `qwen -p "..." --yolo --max-session-turns N --max-wall-time 10m --output-format json`. Pin a turn budget and a wall-clock budget so a stuck agent can't burn through your CI minutes, and capture `--output-format json` for post-run usage / tool-call auditing.
- **Local machine or shared infra:** also pass `--sandbox` (or set `QWEN_SANDBOX=1`) so shell / write / edit tools run inside the sandbox image.
- **Long-running CI with retry-on-rate-limit:** combine `QWEN_CODE_UNATTENDED_RETRY=1` with `--max-wall-time`. The retry env keeps the run alive past transient 429 / 529 responses; the wall-clock budget ensures a persistently-failing provider can't extend the job indefinitely.
- **Bounded auditing / exploration:** for read-only tasks, `--max-tool-calls 25` caps how aggressively the model can grep / read. Combine with `--exclude-tools shell,write,edit` to make the bound meaningful.
## Examples
### Code review

View File

@ -24,15 +24,32 @@ Don't include things Qwen can figure out by reading your code. QWEN.md works bes
### Where to create QWEN.md
| File | Who it applies to |
| ----------------------------- | --------------------------------------------- |
| `~/.qwen/QWEN.md` | You, across all your projects |
| `QWEN.md` in the project root | Your whole team (commit it to source control) |
| File | Who it applies to |
| ----------------------------- | ------------------------------------------------ |
| `~/.qwen/QWEN.md` | You, across all your projects |
| `QWEN.md` in the project root | Your whole team (commit it to source control) |
| `.qwen/QWEN.local.md` | Only you, only in this project (keep out of git) |
You can have both. Qwen loads all QWEN.md files it finds when you start a session — your personal one plus any in the project.
You can have any combination of these. Qwen loads all of them when you start a session.
If your repository already has an `AGENTS.md` file for other AI tools, Qwen reads that too. No need to duplicate instructions.
#### When to use `.qwen/QWEN.local.md`
Use it for **project-specific but personal** instructions — things that belong to this project but shouldn't be shared with the team:
- Your own cluster ID, container registry namespace, or cloud account
- A personal debug command that hardcodes your local environment
- Notes you want Qwen to know about your work-in-progress, but not commit
It loads **after** the shared project `QWEN.md`, so your local instructions can supplement or override the team's.
**You must gitignore it yourself.** Although `.qwen/` is often treated as a local directory, qwen-code does not generate a `.gitignore` for you, and some projects commit `.qwen/settings.json`. Add this line to your `.gitignore` (or to your global git ignore):
```
.qwen/QWEN.local.md
```
### Generate one automatically with `/init`
Run `/init` and Qwen will analyze your codebase to create a starter QWEN.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.

View File

@ -0,0 +1,345 @@
# Worktrees
> Isolate experimental work in a temporary [git worktree](https://git-scm.com/docs/git-worktree) without leaving your current session. Useful when the model is about to make wide-ranging edits you want to keep separate from your main checkout, or when you want a subagent to work in a sandbox of its own.
## Quick Start
### Start the session inside a worktree (`--worktree` flag)
If you know up front that the entire session should run inside a worktree, pass `--worktree` at launch:
```bash
# Auto-generated slug (e.g. tender-jemison-037f0a)
qwen --worktree
# Explicit name
qwen --worktree my-feature
# `=` form (recommended when also passing a positional prompt — see tip below)
qwen --worktree=my-feature
# PR reference — fetches refs/pull/<N>/head from `origin`
qwen --worktree=#4174
qwen --worktree https://github.com/QwenLM/qwen-code/pull/4174
# Continue a previous --worktree session — re-attaches to the existing dir
qwen --resume <session-id> --worktree=my-feature
```
> **Tip — bare `--worktree` followed by a positional prompt is ambiguous.** Because `--worktree` takes an optional value, `qwen --worktree "say hi"` makes yargs consume `"say hi"` as the slug (and reject it because of the space). Use one of:
>
> - `qwen --worktree=my-feature "say hi"` (always works — explicit slug via `=`)
> - `qwen "say hi" --worktree` (positional first, flag at the end → auto slug)
> - `qwen --worktree --approval-mode yolo "say hi"` (any flag between them anchors the bare form)
> **Tip — `qwen --resume --worktree foo` (no session ID) shows an empty picker on first use.** The picker scopes to the chosen worktree's session storage; sessions started outside that worktree are not listed. To resume a session that was started inside `foo`, use `qwen --resume <id> --worktree foo` directly — the CLI re-attaches to the existing `foo/` directory rather than re-creating it.
`process.cwd()` and the model's workspace are switched to the worktree before the first turn runs. Exit with `Ctrl+C` twice and the [Exit Dialog](#exit-dialog-ctrlc--ctrld) prompts to keep or remove the worktree.
The `--worktree` flag cannot be combined with `--acp`/`--experimental-acp` — for ACP hosts (like Zed), pass the worktree path as the `cwd` of the `loadSession`/`newSession` request instead.
### Or ask mid-session
Alternatively, ask Qwen Code in plain language to create a worktree from inside an existing session:
```text
> start a worktree called experiment-a
Worktree experiment-a created on branch worktree-experiment-a
.qwen/worktrees/experiment-a
```
From this point on, the model routes every file edit and shell command through `.qwen/worktrees/experiment-a/`. Your original working directory is untouched.
When you are done:
```text
> exit the worktree and remove it
Removed worktree experiment-a (branch worktree-experiment-a)
```
If you want to come back later, ask to exit with the worktree kept on disk instead:
```text
> exit the worktree but keep it
Kept worktree experiment-a at .qwen/worktrees/experiment-a
```
## When Worktrees Are Used
Worktrees are activated in four independent paths:
| Trigger | What happens |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| You launch with `--worktree` | The CLI creates the worktree before any model turn runs and chdirs the session into it. PR forms (`#N`, full URL) fetch first. |
| You explicitly ask for a worktree mid-session | Model calls `enter_worktree`; subsequent file edits go inside it. |
| You explicitly ask to leave | Model calls `exit_worktree` with `keep` or `remove`. |
| Model spawns a sub-agent with isolation enabled | A throwaway worktree (`agent-<hex>`) is created automatically and cleaned up if the agent has no diffs. |
The two mid-session tools (`enter_worktree` / `exit_worktree`) are deliberately gated behind explicit phrasing — saying "fix this bug" or "create a branch" will **not** trigger them. You must say something like "use a worktree", "start a worktree", or "in a worktree". The `--worktree` CLI flag has no such guard; it always creates one when present.
## What Gets Created
Every Qwen-managed worktree is placed under your project's `.qwen` directory:
```
<repoRoot>/.qwen/worktrees/<slug>/ # Working directory
↳ branch worktree-<slug> # Created off your current branch
```
- **Slug** — letters, digits, dot, underscore, hyphen; max 64 chars. If you don't specify a name, an `<adjective>-<noun>-<6hex>` slug is auto-generated (e.g. `tender-jemison-037f0a`). PR references produce `pr-<N>`.
- **Branch** — always `worktree-<slug>`, branched from whichever branch you have checked out when you ask for the worktree (not necessarily the main working tree's `HEAD`). For PR worktrees the branch is `worktree-pr-<N>` and is based on `FETCH_HEAD` (the PR's tip on the GitHub side) rather than your local branch.
- **Hooks** — the worktree's `core.hooksPath` is automatically pointed at the main repo's `.husky/` (preferred) or `.git/hooks/` so commits inside the worktree still trigger your existing pre-commit / commit-msg hooks.
- **Optional symlinks** — directories listed in `worktree.symlinkDirectories` (see [Settings](#settings)) are symlinked from the main repo into the new worktree so heavy dirs like `node_modules` can be reused without reinstalling.
The general-purpose worktree path is **not configurable** — it must live under `<repoRoot>/.qwen/worktrees/` so the CLI can find it on restart and on stale-cleanup sweeps. (The unrelated `agents.arena.worktreeBaseDir` setting controls only [Agent Arena](./arena.md) worktrees, which use a separate path tree under `~/.qwen/arena/`.)
## Footer and Status Line
When a worktree is active, the Footer shows a dim indicator on its own row:
```
⎇ worktree-experiment-a (experiment-a)
```
If you use a [custom status line script](./status-line.md), it also receives a `worktree` object in the JSON payload piped to stdin:
```json
{
"worktree": {
"name": "experiment-a",
"path": "/path/to/repo/.qwen/worktrees/experiment-a",
"branch": "worktree-experiment-a",
"original_cwd": "/path/to/repo",
"original_branch": "main"
}
}
```
The payload field is present **only** when a worktree is active, so a `null`-check (`input.worktree?.name`) is enough.
If your custom status line already renders worktree info, you can hide the built-in Footer row to avoid duplication — see [Settings](#settings) below.
## Exit Dialog (Ctrl+C / Ctrl+D)
Pressing the quit shortcut twice while a worktree is active opens the **Worktree Exit Dialog** instead of closing the CLI:
```
⎇ Active worktree: "experiment-a" (worktree-experiment-a)
• 2 new commit(s) on worktree-experiment-a
• 3 uncommitted file(s)
Removing the worktree will discard everything above.
What would you like to do?
○ Keep worktree (exit without deleting)
○ Remove worktree and branch (discards 2 commit(s), 3 file(s))
○ Cancel (stay in session)
```
The dialog inspects the worktree on open (`git status --porcelain` + `git rev-list <baseHEAD>..HEAD`) and surfaces both counts so you know exactly what you'd be discarding. `ESC` cancels.
If `git status` itself fails (e.g. corrupt index, worktree directory was removed under the CLI), the dialog shows a `⚠ Could not measure worktree state` warning and the counts may be unreliable — choose **Keep** or **Cancel** until you've diagnosed the underlying repo problem.
## `--resume` Restore
The active worktree binding is persisted to a sidecar file alongside your session transcript:
```
<chatsDir>/<sessionId>.worktree.json
```
When you launch the CLI with `--resume <sessionId>` (or pick the session from `/resume`), three things happen consistently across **interactive TUI**, **headless `-p`**, and **ACP/Zed** modes:
1. The sidecar is loaded and the worktree directory is verified to still exist on disk.
2. If alive, the model receives a one-shot reminder on its very next prompt:
```
[Resumed] Active worktree: "<slug>" at <path> (branch: <branch>). Continue using this path for all file operations.
```
3. If the worktree directory was deleted between sessions, the stale sidecar is cleaned up automatically — no error, the resume just continues without worktree context.
Each mode chooses its own injection mechanism, but the user-visible behavior is identical:
| Mode | Mechanism |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| Interactive (TUI) | `INFO` history item + system-reminder prefix on the next user prompt. |
| Headless (`-p`) | `<system-reminder>` prefix on the prompt + `worktree_restored` JSON system event in the output stream. |
| ACP (e.g. Zed) | Pending notice attached to the next `prompt()` call. |
The model is **not** automatically `chdir`'d into the worktree — the reminder is what keeps it routing edits through the worktree path.
## Sub-Agent Isolation
The `agent` tool accepts an optional `isolation: "worktree"` parameter. When set, Qwen Code creates an ephemeral worktree at `<repoRoot>/.qwen/worktrees/agent-<7hex>/` before the sub-agent starts, and:
- **No changes** → the worktree is automatically removed when the agent finishes.
- **Has changes** → the worktree is preserved; its path and branch are appended to the agent's result, e.g.
```
…agent output…
[worktree preserved: /path/to/.qwen/worktrees/agent-3f2a1b9 (branch worktree-agent-3f2a1b9)]
```
Review the diff and merge or delete it manually.
Two constraints:
- `isolation: "worktree"` requires a `subagent_type` — forked sub-agents (no `subagent_type`) reuse the parent's full conversation context, so isolating them would split intent from working tree.
- Background agents (`run_in_background: true`) work fine with isolation; the cleanup runs when the agent reports completion.
### Automatic Stale Cleanup
Ephemeral agent worktrees that survived a crash or `--no-cleanup` shutdown are reaped on every CLI startup, with conservative fail-closed rules:
| Guard | Behavior |
| -------------------------------------- | ---------------------------------------------- |
| Slug must match `agent-<7hex>` pattern | Named worktrees you created are never touched. |
| Directory `mtime` > 30 days | Newer entries are skipped. |
| Any uncommitted tracked change | Skip the entry (don't delete). |
| Any commit not reachable from a remote | Skip the entry (don't delete). |
| Any error reading git state | Skip the entry (don't delete). |
Named user worktrees (`enter_worktree` slugs) are **never** auto-cleaned — you keep them around until you ask to remove them.
## Safety Guards on `exit_worktree action="remove"`
Three independent guards trigger before the directory and branch are deleted:
1. **Session ownership** — each worktree carries a sidecar marker with the session ID that created it. A different session trying to remove it is refused with a clear error pointing at `git worktree remove` for the manual escape hatch.
2. **Dirty working tree** — uncommitted tracked or untracked changes block removal. Pass `discard_changes: true` to override. (Bypass requires explicit user confirmation — `action: "remove"` is never auto-approved in AUTO_EDIT mode.)
3. **Unmerged commits** — commits on `worktree-<slug>` that no other local branch or remote ref points at block removal unconditionally; there is no "discard commits" flag because losing committed work is rarely what users mean. Merge, push, or rename the branch elsewhere first.
The same three guards apply to the `WorktreeExitDialog → Remove` button.
## Settings
Two settings shape the general-purpose worktree experience:
| Key | Type | Default | Effect |
| --------------------------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ui.hideBuiltinWorktreeIndicator` | boolean | `false` | Hides the built-in `⎇ worktree-… (…)` Footer row. The `worktree` field is still delivered to custom status line scripts. Set to `true` only if your status line already renders the worktree — otherwise you lose all UI affordance. |
| `worktree.symlinkDirectories` | `string[]` | `undefined` | Directories under the main repo to symlink into every general-purpose worktree on creation. Paths are relative to the repo root; absolute paths and any entry containing `..` are rejected. Missing sources and existing destinations are silently skipped (no overwrite). |
Example:
```jsonc
// ~/.qwen/settings.json or <repo>/.qwen/settings.json
{
"worktree": {
"symlinkDirectories": ["node_modules", ".turbo", "dist"],
},
}
```
Applies to ALL worktree-creation paths: `--worktree` flag, `enter_worktree` tool, and `agent isolation: "worktree"`.
Settings unrelated to general worktrees but worth knowing about:
- `agents.arena.worktreeBaseDir` — controls **Agent Arena** worktree placement (default `~/.qwen/arena`). Does not affect general-purpose worktrees, which always live under `<repoRoot>/.qwen/worktrees/`.
There is no schema for `worktree.sparsePaths` yet — that's a roadmap item (see [Limitations](#limitations)).
## Tool Reference
### `enter_worktree`
```json
{ "name": "experiment-a" }
```
| Field | Type | Required | Notes |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `name` | string | no | Slug. Letters, digits, dot, underscore, hyphen; max 64 chars. Auto-generated when omitted. |
Refuses to run when:
- The CLI is not in a git repository.
- The current working directory is already inside `.qwen/worktrees/` (no nested worktrees).
### `exit_worktree`
```json
{ "name": "experiment-a", "action": "remove", "discard_changes": false }
```
| Field | Type | Required | Notes |
| ----------------- | ---------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| `name` | string | yes | Must match the slug used in `enter_worktree`. |
| `action` | `"keep"` \| `"remove"` | yes | `keep` preserves dir + branch; `remove` deletes both. |
| `discard_changes` | boolean | only when `action="remove"` and dirty | Overrides the dirty-tree guard. Has no effect for `action="keep"`. |
`action: "remove"` always prompts for confirmation, including under `AUTO_EDIT` approval mode — it is treated as a destructive shell operation, not an info-only tool.
### `agent` — `isolation` parameter
```json
{
"subagent_type": "my-agent",
"description": "…",
"prompt": "…",
"isolation": "worktree"
}
```
| Field | Type | Required | Notes |
| ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------- |
| `isolation` | `"worktree"` | no | Runs the agent in a fresh `agent-<7hex>` worktree. Requires `subagent_type` to be set (no forks). |
See [Sub-Agents](./sub-agents.md) for the rest of the agent tool reference.
## CLI Reference
### `--worktree [name | #N | url]`
```bash
qwen --worktree # auto-generate slug
qwen --worktree my-feature # explicit slug
qwen --worktree=my-feature # = form
qwen --worktree=#123 # PR reference
qwen --worktree https://github.com/owner/repo/pull/123 # PR URL
```
| Input | Result |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Bare flag (no value) | Auto slug `<adjective>-<noun>-<6hex>`, branch `worktree-<slug>`, base = current branch. |
| Plain slug | Branch `worktree-<slug>`, base = current branch. Slug validation: letters/digits/dot/underscore/hyphen, max 64 chars. |
| `#N` or `<github-url>/pull/N` | Slug `pr-<N>`, branch `worktree-pr-<N>`, base = `FETCH_HEAD` after `git fetch origin pull/<N>/head` (30s timeout). |
`--worktree` cannot be combined with `--acp` / `--experimental-acp`.
When `--worktree` is combined with `--resume <session-id>`, the worktree wins: the resumed session's saved worktree (if any) is overridden and a stderr line + first-prompt reminder report the override.
For interactive (TUI) and headless (`-p`) modes the worktree is automatically created and the session chdirs into it before the first turn.
PR-fetch failure modes (exit code != 0, no worktree created):
| Cause | Message excerpt |
| ----------------------------- | ---------------------------------------------------------- |
| Missing `origin` remote | `requires an "origin" remote that points at GitHub` |
| PR doesn't exist on origin | `Failed to fetch PR #<N>: the PR does not exist on origin` |
| 30s network timeout | `Failed to fetch PR #<N>: timed out after 30s` |
| PR number out of range / zero | `Invalid PR number` |
## Limitations
The following items are intentionally not implemented in the current phase:
- **No sparse checkout.** Large monorepos check out the full tree. (`worktree.sparsePaths` is a roadmap item.)
- **No tmux integration.** The CLI does not spawn worktree sessions in new tmux windows.
- **Worktrees are separate "projects" for session storage.** Sessions started with `--worktree foo` are saved under that worktree's chats dir; to resume them later you must pass `--worktree foo` again. Sessions started without `--worktree` are saved under the main checkout and won't appear in the worktree's resume picker.
- **No cross-slug session override.** `qwen --resume <sid> --worktree second` where `<sid>` was created with `--worktree first` will fail to find the session — sessions and worktrees are tightly bound by `projectHash(cwd)`. To switch worktrees on an existing session you must exit, then re-launch with the new `--worktree` and a fresh prompt. A future architectural change (anchoring storage at the repo root instead of `cwd`) would lift this constraint.
- **Mid-session `enter_worktree` does NOT switch `process.cwd()` or `Config.targetDir`.** That tool uses the model-context-only convention (see [Sub-Agents](./sub-agents.md)). Only the startup `--worktree` flag actually switches the process working directory.
- **Relative paths in other arg fields are resolved BEFORE the worktree chdir.** Path-taking flags (`--mcp-config`, `--openai-logging-dir`, `--json-file`, `--input-file`, `--telemetry-outfile`, `--include-directories`) are normalized to absolute paths against the launch cwd when `--worktree` is set. Other path-shaped argv fields not in this list still resolve against the worktree cwd — use absolute paths to be safe.
Track the roadmap in `docs/design/worktree.md`.
## Troubleshooting
**The Footer shows no worktree indicator even though I just created one.**
Check that `ui.hideBuiltinWorktreeIndicator` is not set to `true`. Also confirm the slug is non-empty in the tool's success message.
**`--resume` does not restore my worktree.**
Check `<chatsDir>/<sessionId>.worktree.json` exists. The CLI deletes the sidecar automatically when the worktree directory is gone, so a missing sidecar plus a missing directory is the normal "no worktree to restore" state — not a bug. Run with `--debug` and grep for `restoreWorktreeContext` to see the reason.
**`exit_worktree` says "created by a different session".**
This is the session-ownership guard. Resume the original session and exit from there, or run the suggested `git worktree remove …` command manually.
**Stale `agent-<hex>` worktrees keep piling up.**
The 30-day cutoff is conservative; sweep manually with `git worktree list && git worktree remove <path>`, or wait — the next CLI startup after the 30-day mark will reap them as long as they are clean and pushed.

View File

@ -1,221 +0,0 @@
# Local launch templates for `qwen serve` (v0.16-alpha)
Reference templates for running `qwen serve` as a long-lived background process on a developer workstation. Pairs with the [v0.16-alpha known limits](./qwen-serve.md#v016-alpha-known-limits) — local-only, single-user, BYO bearer token. Containerized / multi-host / TLS-fronted deployments defer to v0.16.x.
> **Audience**: dogfooding developers who want the daemon up across reboots, with logs going somewhere durable, and a clean `restart-on-failure` story. If you only need the daemon for the duration of a single shell session, plain `qwen serve` (foreground, Ctrl-C to stop) is fine.
## Generate a bearer token (once)
```bash
openssl rand -hex 32 > ~/.qwen-serve-token # user-managed, NOT a built-in path
chmod 600 ~/.qwen-serve-token
export QWEN_SERVER_TOKEN="$(cat ~/.qwen-serve-token)"
```
The path / filename is yours to choose; v0.16-alpha does not auto-generate or auto-locate a token file (deferred to v0.16.x). See the [Authentication](./qwen-serve.md#authentication) section of the user guide for the canonical BYO setup.
> **Scope this `export` to the current shell session only.** Don't add it to `~/.bashrc` / `~/.zshrc` — a profile-level export exposes the bearer token to every process spawned from that shell (IDE subprocesses, browser debuggers, `npm` scripts from unrelated projects). For long-running setups, use the systemd `EnvironmentFile=` / launchd `EnvironmentVariables` mechanisms below — both scope the token to just the daemon process.
The daemon reads the bearer token from either `--token <value>` on the CLI or the `QWEN_SERVER_TOKEN` env var (whitespace stripped from both). The TypeScript SDK's `DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` when no `token` option is passed (PR 27 fallback — clients with the env var set never need to thread the value through their script).
One shell-level `export` covers both server boot and SDK client construction (just keep it scoped to the session, per the note above).
## Linux: systemd user unit
> **Find your `qwen` binary first.** The unit file's `ExecStart=` must hold an **absolute path** — service managers don't read your shell's `PATH`. Run `which qwen` to discover it. Common locations: `/usr/local/bin/qwen` (Linuxbrew, manual installs), `~/.nvm/versions/node/vX.Y.Z/bin/qwen` (nvm), `~/.fnm/aliases/default/bin/qwen` (fnm), `~/.volta/bin/qwen` (Volta). Substitute the actual path everywhere the templates below show `/PATH/TO/qwen`.
`~/.config/systemd/user/qwen-serve.service`:
```ini
[Unit]
Description=Qwen Code daemon (loopback HTTP + SSE)
After=network.target
[Service]
Type=simple
# Replace with your project; %h expands to $HOME under user units.
WorkingDirectory=%h/your-project
# Run `which qwen` to find the absolute path. systemd does NOT read $PATH.
ExecStart=/PATH/TO/qwen serve --hostname 127.0.0.1 --port 4170
# Read the bearer token from a chmod 600 file rather than inlining it
# in the unit. `Environment=` would expose the token in the unit file
# (typically 644 = world-readable). EnvironmentFile keeps the token in
# the user-owned secret file you already created with `chmod 600`.
EnvironmentFile=%h/.qwen-serve-token-env
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=default.target
```
Build the env file once (the token file from the setup step holds the raw value; this wraps it in `KEY=value` form so systemd reads it as an env assignment):
```bash
echo "QWEN_SERVER_TOKEN=$(cat ~/.qwen-serve-token)" > ~/.qwen-serve-token-env
chmod 600 ~/.qwen-serve-token-env
```
Manage:
```bash
systemctl --user daemon-reload
systemctl --user enable --now qwen-serve.service
loginctl enable-linger "$(whoami)" # keep the user manager running after logout / across reboot
journalctl --user -u qwen-serve -f # tail logs
systemctl --user restart qwen-serve.service # after token rotation
systemctl --user disable --now qwen-serve.service
```
Without `loginctl enable-linger`, the user-level systemd instance shuts down when the user logs out and only restarts on next login — on a headless dev box the daemon would not survive an SSH session ending. `enable-linger` is what makes "across reboots" actually work.
**System-wide alternative** (shared dev hosts, less common): drop the unit at `/etc/systemd/system/qwen-serve@.service` with `User=%i`, manage via `sudo systemctl enable --now qwen-serve@<username>.service`. Same `[Service]` body otherwise — but world-readable `Environment=` exposure is even more problematic at this level, so always use `EnvironmentFile=` pointing at the user's `chmod 600` file. Pick user-level + linger for single-user workstations.
## macOS: launchd user agent
> **Find your `qwen` binary first.** Same constraint as systemd — `ProgramArguments` must hold an **absolute path**. Run `which qwen` to discover it. Common locations on macOS: `/opt/homebrew/bin/qwen` (Homebrew on Apple Silicon), `/usr/local/bin/qwen` (Homebrew on Intel, manual installs), `~/.nvm/versions/node/vX.Y.Z/bin/qwen` (nvm), `~/.volta/bin/qwen` (Volta). Substitute below where the template shows `/PATH/TO/qwen`.
`~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.qwenlm.qwen-serve</string>
<key>ProgramArguments</key>
<array>
<!-- Run `which qwen` to find the absolute path; launchd does NOT read $PATH. -->
<string>/PATH/TO/qwen</string>
<string>serve</string>
<string>--hostname</string>
<string>127.0.0.1</string>
<string>--port</string>
<string>4170</string>
</array>
<!-- launchd does NOT expand `~` or `$HOME` — use absolute paths. -->
<key>WorkingDirectory</key>
<string>/Users/YOUR-USERNAME/your-project</string>
<key>EnvironmentVariables</key>
<dict>
<!-- DO NOT COMMIT this file with a real token. Also chmod 600 the
plist itself so the inlined token is not world-readable. -->
<key>QWEN_SERVER_TOKEN</key>
<string>PASTE-YOUR-TOKEN-HERE</string>
</dict>
<key>RunAtLoad</key>
<true/>
<!-- Restart only on non-zero exits (matches systemd Restart=on-failure).
A bare `<true/>` would respawn even after a clean SIGTERM, making
`kill <pid>` impossible to use as a stop signal — operator would
have to `launchctl unload`. SuccessfulExit=false fixes that. -->
<key>KeepAlive</key>
<dict>
<key>SuccessfulExit</key>
<false/>
</dict>
<!-- Throttle restart storms on persistent failures (mirrors systemd
RestartSec=5; launchd's default would respawn every <1s). -->
<key>ThrottleInterval</key>
<integer>10</integer>
<!-- Log into the user's Library, not /tmp. /tmp is world-writable
(symlink-attack risk on shared workstations) and gets cleaned by
periodic-daily after 3 days; `~/Library/Logs/qwen-serve/` is
user-scoped and survives. launchd truncates these on every
`load`, so the unload→load token-rotation cycle wipes prior
diagnostic logs — back them up if you need post-incident
inspection. -->
<key>StandardOutPath</key>
<string>/Users/YOUR-USERNAME/Library/Logs/qwen-serve/out.log</string>
<key>StandardErrorPath</key>
<string>/Users/YOUR-USERNAME/Library/Logs/qwen-serve/err.log</string>
</dict>
</plist>
```
Manage:
```bash
mkdir -p ~/Library/Logs/qwen-serve # first time only
chmod 600 ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist # plist holds the inline token
launchctl load ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist
launchctl unload ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist # to stop
tail -f ~/Library/Logs/qwen-serve/out.log ~/Library/Logs/qwen-serve/err.log
```
After editing the plist (e.g., rotating the token) you must `unload` then `load` again — `launchctl` does not auto-reload on plist changes the way `systemd daemon-reload` does. Note: each `load` truncates the log files, so save them off if you're investigating an incident before rotating.
## tmux session (interactive supervision)
Assumes `QWEN_SERVER_TOKEN` is already exported in your shell (see the setup section above):
```bash
tmux new -d -s qwen-serve "cd ~/your-project && qwen serve --hostname 127.0.0.1"
tmux attach -t qwen-serve # see live logs; Ctrl-b d to detach
tmux kill-session -t qwen-serve
```
`tmux new -d` inherits the parent shell's environment, so `QWEN_SERVER_TOKEN` flows through automatically. Best when you want to occasionally watch the daemon's stdout (auth warnings, MCP discovery progress, slow-client warnings) without committing to a service unit. Survives terminal close but not host reboot.
## nohup one-liner (quick + dirty)
Assumes `QWEN_SERVER_TOKEN` is already exported in your shell:
```bash
nohup bash -c 'cd ~/your-project && qwen serve --hostname 127.0.0.1' > qwen-serve.log 2>&1 &
echo $! # daemon PID; capture if you want to `kill` cleanly later
```
The wrapping `bash -c '...'` ensures the daemon binds to `~/your-project` rather than wherever you happened to run the command. Without that `cd`, `qwen serve` defaults to `process.cwd()` and a `POST /session` from a client expecting your project workspace returns `400 workspace_mismatch` — silent foot-gun.
OK for one-off "let me run this in the background while I poke at the API" workflows. **Not recommended** for anything beyond a single session — no restart-on-crash, log file grows unbounded, no clean way to find the daemon if you forget the PID. Prefer tmux for interactive supervision or systemd / launchd for anything you want to outlast a reboot.
## Verifying the daemon is up
```bash
curl http://127.0.0.1:4170/health # → {"status":"ok"}
curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" \
http://127.0.0.1:4170/capabilities | jq .protocolVersions # daemon's feature set
```
When auth is configured (i.e., the daemon was started with `--token` / `QWEN_SERVER_TOKEN` set, OR `--require-auth=true`), every route except `/health` on loopback binds requires `Authorization: Bearer <token>`. If you started the daemon without a token on the loopback default (the `qwen serve` zero-config path), neither call requires a header. The templates above all configure a token, so the `Authorization` header is needed in practice. If `/capabilities` returns `401`, the unit / plist token doesn't match the env-exported token your `curl` is using.
## Token rotation
1. Generate a new token + write the env file the unit references:
```bash
openssl rand -hex 32 > ~/.qwen-serve-token
chmod 600 ~/.qwen-serve-token
echo "QWEN_SERVER_TOKEN=$(cat ~/.qwen-serve-token)" > ~/.qwen-serve-token-env
chmod 600 ~/.qwen-serve-token-env
```
(For the launchd / nohup / tmux templates: edit the plist's `<string>` value or re-`export QWEN_SERVER_TOKEN`. Don't forget `chmod 600` on the plist if you regenerate it.)
2. Restart the daemon:
- **systemd**: `systemctl --user restart qwen-serve.service`
- **launchd**: `launchctl unload ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist && launchctl load ~/Library/LaunchAgents/com.qwenlm.qwen-serve.plist`
- **tmux / nohup**: `kill <pid>` then re-run with the new token in env
3. Update any client SDKs / scripts. The TypeScript SDK's `DaemonClient` reads `QWEN_SERVER_TOKEN` automatically (PR 27 fallback) — re-`export` the new value in any client shell and reconstruct the client.
## Restart and crash behavior
Service-manager restart semantics differ across the templates:
- **systemd `Restart=on-failure`** — restart only on non-zero exit / signal. A clean SIGTERM (`systemctl stop`) does **not** trigger a restart loop.
- **launchd `KeepAlive` with `SuccessfulExit=false`** (the template above) — matches systemd behavior. A bare `<true/>` would have respawned even after a clean exit. `ThrottleInterval=10` rate-limits restart storms on persistent failures, mirroring systemd's `RestartSec=5`.
- **tmux / nohup** — no automatic restart. A daemon crash leaves you with a dead PID until you re-run.
Within a **single daemon process lifetime**, client disconnects recover via SSE `Last-Event-ID` resume per the [Durability model](./qwen-serve.md#durability-model) section of the user guide — the replay ring is in-memory.
A daemon **restart** drops all in-memory sessions; clients reconnect and start fresh. Cross-restart durability of session content (prompts, tool calls, conversation history) is **NOT** in v0.16-alpha.
## Out of scope (defers to v0.16.x or later)
- **Containerized deployment** — Dockerfile, docker-compose, Kubernetes manifests, nginx + TLS reverse proxy, multi-instance token isolation. Defers to v0.16.x once an enterprise pilot is committed; the doc would otherwise rot from no-one-validating.
- **Cross-host federation / multi-daemon coordination on one host** — `1 daemon = 1 workspace × N sessions` is enforced. Instance-path token keying + stale-token cleanup defer to v0.16.x.
- **Auto-generated daemon tokens** — alpha is BYO-token. Auto-gen + token-store infrastructure defers to v0.16.x.
- **Windows native service** (`nssm`, Service Control Manager wrapper) — for now use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) and follow the systemd section above.
See the [v0.16-alpha known limits](./qwen-serve.md#v016-alpha-known-limits) callout in the main user guide for the full deferred-features list, and [#4175](https://github.com/QwenLM/qwen-code/issues/4175) for the v0.16-alpha rollout tracking issue.

View File

@ -2,8 +2,6 @@
Run Qwen Code as a local HTTP daemon so multiple clients (IDE plugins, web UIs, CI scripts, custom CLIs) share one agent session over HTTP + Server-Sent Events instead of each spawning their own subprocess.
> **🚧 v0.16-alpha**: `qwen serve` first ships to npm in v0.16-alpha as **text-only chat / coding** with **local-only deployment**. Image / file attachments on the prompt path, containerized deployment (Docker / k8s / nginx reverse-proxy), and remote / multi-daemon hardening land in a follow-up patch when an enterprise pilot is committed. See [v0.16-alpha known limits](#v016-alpha-known-limits) for the full deferred list.
> **Status:** Stage 1 (experimental). The protocol surface is locked at the §04 routes table from issue [#3803](https://github.com/QwenLM/qwen-code/issues/3803). Stage 1.5 (`qwen --serve` flag — TUI co-hosts the same HTTP server) and Stage 2 (in-process refactor + `mDNS`/OpenAPI/WebSocket/Prometheus polish) are immediately downstream.
>
> **Scope honesty:** Stage 1 is sized for **developers prototyping clients against the protocol surface** and for **local single-user / small-team collaboration**. Production-grade multi-client / long-running / network-flaky workloads (mobile companions, IM bots reaching 1000+ chats) need Stage 1.5+ guarantees that aren't in this release. See [Stage 1.5+ runtime guarantees](#stage-15-runtime-guarantees) for the full gap list and #3803 for the convergence roadmap.
@ -14,40 +12,7 @@ Run Qwen Code as a local HTTP daemon so multiple clients (IDE plugins, web UIs,
- **Reconnect-safe streaming** — SSE with `Last-Event-ID` reconnect lets a client drop and pick up exactly where it left off (within the ring's replay window).
- **First-responder permissions** — when the agent asks for permission to run a tool, every connected client sees the request; whichever client answers first wins.
- **One daemon, one workspace** — each `qwen serve` process binds to exactly one workspace at boot (per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02). Multi-workspace deployments run one daemon per workspace on separate ports (or behind an orchestrator).
- **Remote runtime control** ([#4175](https://github.com/QwenLM/qwen-code/issues/4175) PR 17) — change a session's approval mode (`POST /session/:id/approval-mode`), toggle a tool per workspace (`POST /workspace/tools/:name/enable`), scaffold an empty `QWEN.md` (`POST /workspace/init`, mechanical only — does NOT call the model; for AI-fill, follow up with `POST /session/:id/prompt`), restart a single MCP server with a budget pre-check (`POST /workspace/mcp/:server/restart`), or add/remove MCP servers at runtime without a daemon restart (`POST /workspace/mcp/servers`, `DELETE /workspace/mcp/servers/:name`). All strict-gated — configure `--token` first.
- **Session recap** ([#4175](https://github.com/QwenLM/qwen-code/issues/4175) follow-up) — fetch a one-sentence "where did I leave off" summary of an active session (`POST /session/:id/recap`). Wraps core's `generateSessionRecap` as a side-query against the fast model; pollutes neither the main chat history nor the SSE stream. Non-strict gate (same posture as `/prompt`); SDK helper `client.recapSession(sessionId)`.
- **Known limit — token-cost amplification:** the route is a pure-cost endpoint (each call is an LLM side-query, no state benefit) and the daemon has no per-route rate limit in v1. On a no-token loopback default a buggy or malicious local client can spam it to burn tokens. Configure `--token` (and optionally `--require-auth`) on shared dev hosts before exposing the daemon.
- **Concurrent recap safety:** two simultaneous `/recap` calls on the same session run two independent side-queries. `generateSessionRecap` reads a snapshot of the chat history via `GeminiClient.getChat().getHistory()` and feeds it to a separate `BaseLlmClient.generateText` call (via `runSideQuery`); it never appends to or mutates the session's `GeminiChat`. Safe to call from multiple clients without coordination.
## v0.16-alpha known limits
The first npm release of `qwen serve` (v0.16-alpha) is intentionally narrow — text-only chat / coding for developers running the daemon on their own machine. The list below makes the deferred surface explicit so adopters can plan around it; everything here is on the v0.16.x patch roadmap or a near-term follow-up release.
**Product surface — text-only:**
- ✅ Text prompts and text responses (chat, coding, tool calls, MCP integration)
- ❌ **Image / file attachments on the prompt path** — `MessageEmitter` currently only renders text; multimodal echo lands when an alpha target with image needs is committed (#4175 chiga0 #27 P0 item)
- ❌ **Streaming uploads** — same gating as multimodal
**Deployment surface — local-only:**
- ✅ Loopback (`127.0.0.1`, default) — no auth required, suitable for dev workstations
- ✅ Local launch via `systemd` / `launchd` / `nohup &` / `tmux` — see [Local launch templates](./qwen-serve-deploy-local.md)
- ✅ Bring-your-own bearer token via `QWEN_SERVER_TOKEN` env var ([Authentication](#authentication) for setup)
- ❌ **Containerized deployment** — Docker / Compose / Kubernetes / nginx reverse-proxy with TLS termination NOT in v0.16-alpha. Defers to v0.16.x once an enterprise pilot is committed (would otherwise rot from no-one-validating).
- ❌ **Multi-daemon coordination on one host** — `1 daemon = 1 workspace × N sessions` is enforced. Cross-host federation, instance-path token keying, and stale-token cleanup defer to v0.16.x.
- ❌ **Auto-generated daemon tokens** — alpha is BYO-token (one `openssl rand -hex 32` away). Auto-gen + token-store infrastructure defers to v0.16.x.
**Hardening — minimum viable for local single-user:**
- ✅ Boot-time security gate (refuses non-loopback bind without a token, [PR 15 / #4236](https://github.com/QwenLM/qwen-code/pull/4236))
- ✅ Mutation-route auth gate, session-scoped permission routing (Wave 4 PRs)
- ✅ MCP guardrails + multi-client permission coordination (F2 / F3)
- ⏸️ **Prompt absolute deadline + SSE writer idle timeout** — current AbortSignal + 15s heartbeat + `res.on('error')` cleanup is sufficient for local dev; explicit application-layer deadlines defer to v0.16.x once a remote / long-running scenario lands.
- ⏸️ **Rate limiting + observability + load test harness** — defers to v0.17 F4 Phase-1 scale instrumentation when 30-50 active sessions becomes a real target.
- ⏸️ **`--max-body-size` CLI flag** — daemon enforces `express.json({ limit: '10mb' })` by default which comfortably covers text-only prompts (model context windows are well under 10 MiB of chars). Tunable via flag in v0.16.x.
For the deeper "what we won't fix in Stage 1" enumeration (single-host session-state mutation model + N-parallel-sessions sharing one ACP child), see [Stage 1 scope boundaries](#stage-1-scope-boundaries--what-we-wont-fix-in-stage-15) below.
- **Remote runtime control** ([#4175](https://github.com/QwenLM/qwen-code/issues/4175) PR 17) — change a session's approval mode (`POST /session/:id/approval-mode`), toggle a tool per workspace (`POST /workspace/tools/:name/enable`), scaffold an empty `QWEN.md` (`POST /workspace/init`, mechanical only — does NOT call the model; for AI-fill, follow up with `POST /session/:id/prompt`), or restart a single MCP server with a budget pre-check (`POST /workspace/mcp/:server/restart`). All four are strict-gated — configure `--token` first.
## Quickstart
@ -77,8 +42,7 @@ The `workspaceCwd` field surfaces the bound workspace so clients can pre-flight
The daemon also exposes read-only runtime snapshots for client UIs:
`GET /workspace/mcp`, `GET /workspace/skills`, `GET /workspace/providers`,
`GET /workspace/env`, `GET /workspace/preflight`,
`GET /session/:id/context`, `GET /session/:id/supported-commands`, and
`GET /session/:id/tasks`.
`GET /session/:id/context`, and `GET /session/:id/supported-commands`.
`GET /workspace/mcp`, `GET /workspace/skills`, and `GET /workspace/providers`
report the live ACP runtime and do not start the ACP child when idle; an
@ -202,20 +166,19 @@ The token comparison is constant-time (SHA-256 + `crypto.timingSafeEqual`); 401
## CLI flags
| Flag | Default | Purpose |
| ------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--port <n>` | `4170` | TCP port. `0` = OS-assigned ephemeral port. |
| `--hostname <addr>` | `127.0.0.1` | Bind interface. Anything beyond loopback requires a token. |
| `--token <str>` | — | Bearer token. Falls back to `QWEN_SERVER_TOKEN` env var (with leading/trailing whitespace stripped — handy for `$(cat token.txt)`). |
| `--require-auth` | `false` | Refuse to start without a bearer token, even on loopback. Hardens the `127.0.0.1` developer default for shared dev hosts / CI runners / multi-tenant workstations where any local user can hit the listener. Boots only with `--token` or `QWEN_SERVER_TOKEN` set; gates `/health` behind the bearer too. |
| `--max-sessions <n>` | `20` | Cap on concurrent live sessions. New `POST /session` requests that would spawn a fresh child return `503` (with `Retry-After: 5`) when the cap is hit; attaches to existing sessions are NOT counted. Set to `0` to disable. Sized for single-user / small-team usage; raise it if your deployment has the RAM/FD headroom (~30–50 MB per session). |
| `--workspace <path>` | `process.cwd()` | Absolute workspace path this daemon binds to (per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02 — 1 daemon = 1 workspace). `POST /session` requests with a mismatched `cwd` return `400 workspace_mismatch`. For multi-workspace deployments, run one `qwen serve` per workspace on separate ports. |
| `--max-connections <n>` | `256` | Listener-level TCP connection cap (`server.maxConnections`). Bounds raw socket count irrespective of session count — slow / phantom SSE clients get rejected at accept time once full. Raise alongside `--max-sessions` if your deployment expects many SSE subscribers per session. |
| `--event-ring-size <n>` | `8000` | Per-session SSE replay ring depth (#3803 §02 target). Sets the backlog available to `GET /session/:id/events` with `Last-Event-ID: N`. Larger = more reconnect headroom at the cost of a few hundred KB extra RAM per session. SDK clients can additionally request a larger per-subscriber backlog cap on a specific subscription via `?maxQueued=N` (range `[16, 2048]`, default 256). Daemons also emit a non-terminal `slow_client_warning` SSE frame at 75% queue fill so clients can drain / reconnect before getting evicted. Pre-flight `caps.features.slow_client_warning`. |
| `--mcp-client-budget <n>` | — | Positive integer cap on live MCP clients **per ACP session** (issue [#4175](https://github.com/QwenLM/qwen-code/issues/4175) PR 14 v1; PR 23 graduates this to per-workspace via the shared MCP pool). Combine with `--mcp-budget-mode`. When unset, no accounting-driven enforcement (but `GET /workspace/mcp` still reports `clientCount`). Distinct from claude-code's `MCP_SERVER_CONNECTION_BATCH_SIZE` which gates startup concurrency, not the total client count. Pre-flight `caps.features.mcp_guardrails`. |
| `--mcp-budget-mode <m>` | `warn` / `off` | How `--mcp-client-budget` is enforced. `warn` (default when budget set): no refusal, snapshot's `budgets[0].status` flips to `warning` at ≥75% of budget. `enforce`: connects past the cap are refused, per-server cell shows `disabledReason: 'budget'`, deterministic by `mcpServers` declaration order. `off` (default when budget unset): pure observability. Boot rejects `enforce` without a budget. |
| `--http-bridge` | `true` | Stage 1 mode: one `qwen --acp` child per daemon (bound to one workspace at boot, per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02); N sessions multiplex onto that child via ACP `newSession()`. Stage 2 native in-process becomes available later. |
| `--allow-origin <pat>` | — | T2.4 ([#4514](https://github.com/QwenLM/qwen-code/issues/4514)). Cross-origin allowlist for browser webui clients. Repeatable. Each value is `*` (any origin — boot refuses if no bearer token is configured; `--require-auth` on loopback is recommended so `/health` and `/demo` are also bearer-gated, since both are pre-auth on loopback by default) or a canonical URL origin (`<scheme>://<host>[:<port>]`, no trailing slash / path / userinfo / query). **Subdomain wildcards (`https://*.example.com`) are intentionally unsupported** — list each subdomain explicitly, or use `*` with a configured token (and `--require-auth` for full hardening). Matched origins receive CORS response headers (`Access-Control-Allow-Origin`, `Vary: Origin`, methods, headers, max-age, and exposed `Retry-After`); unmatched origins still get a 403 with the same envelope as today's wall. `Origin: null` (sandboxed iframes, file:// docs) is always rejected, even under `*`. Pre-flight via `caps.features.allow_origin`. Loopback self-origin hits are unaffected. |
| Flag | Default | Purpose |
| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--port <n>` | `4170` | TCP port. `0` = OS-assigned ephemeral port. |
| `--hostname <addr>` | `127.0.0.1` | Bind interface. Anything beyond loopback requires a token. |
| `--token <str>` | — | Bearer token. Falls back to `QWEN_SERVER_TOKEN` env var (with leading/trailing whitespace stripped — handy for `$(cat token.txt)`). |
| `--require-auth` | `false` | Refuse to start without a bearer token, even on loopback. Hardens the `127.0.0.1` developer default for shared dev hosts / CI runners / multi-tenant workstations where any local user can hit the listener. Boots only with `--token` or `QWEN_SERVER_TOKEN` set; gates `/health` behind the bearer too. |
| `--max-sessions <n>` | `20` | Cap on concurrent live sessions. New `POST /session` requests that would spawn a fresh child return `503` (with `Retry-After: 5`) when the cap is hit; attaches to existing sessions are NOT counted. Set to `0` to disable. Sized for single-user / small-team usage; raise it if your deployment has the RAM/FD headroom (~30–50 MB per session). |
| `--workspace <path>` | `process.cwd()` | Absolute workspace path this daemon binds to (per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02 — 1 daemon = 1 workspace). `POST /session` requests with a mismatched `cwd` return `400 workspace_mismatch`. For multi-workspace deployments, run one `qwen serve` per workspace on separate ports. |
| `--max-connections <n>` | `256` | Listener-level TCP connection cap (`server.maxConnections`). Bounds raw socket count irrespective of session count — slow / phantom SSE clients get rejected at accept time once full. Raise alongside `--max-sessions` if your deployment expects many SSE subscribers per session. |
| `--event-ring-size <n>` | `8000` | Per-session SSE replay ring depth (#3803 §02 target). Sets the backlog available to `GET /session/:id/events` with `Last-Event-ID: N`. Larger = more reconnect headroom at the cost of a few hundred KB extra RAM per session. SDK clients can additionally request a larger per-subscriber backlog cap on a specific subscription via `?maxQueued=N` (range `[16, 2048]`, default 256). Daemons also emit a non-terminal `slow_client_warning` SSE frame at 75% queue fill so clients can drain / reconnect before getting evicted. Pre-flight `caps.features.slow_client_warning`. |
| `--mcp-client-budget <n>` | — | Positive integer cap on live MCP clients **per ACP session** (issue [#4175](https://github.com/QwenLM/qwen-code/issues/4175) PR 14 v1; PR 23 graduates this to per-workspace via the shared MCP pool). Combine with `--mcp-budget-mode`. When unset, no accounting-driven enforcement (but `GET /workspace/mcp` still reports `clientCount`). Distinct from claude-code's `MCP_SERVER_CONNECTION_BATCH_SIZE` which gates startup concurrency, not the total client count. Pre-flight `caps.features.mcp_guardrails`. |
| `--mcp-budget-mode <m>` | `warn` / `off` | How `--mcp-client-budget` is enforced. `warn` (default when budget set): no refusal, snapshot's `budgets[0].status` flips to `warning` at ≥75% of budget. `enforce`: connects past the cap are refused, per-server cell shows `disabledReason: 'budget'`, deterministic by `mcpServers` declaration order. `off` (default when budget unset): pure observability. Boot rejects `enforce` without a budget. |
| `--http-bridge` | `true` | Stage 1 mode: one `qwen --acp` child per daemon (bound to one workspace at boot, per [#3803](https://github.com/QwenLM/qwen-code/issues/3803) §02); N sessions multiplex onto that child via ACP `newSession()`. Stage 2 native in-process becomes available later. |
> **Sizing the load knobs.** `--max-sessions` is the **new-child** cap.
> Three other layers also limit load — when sizing for a high-concurrency
@ -255,7 +218,7 @@ The token comparison is constant-time (SHA-256 + `crypto.timingSafeEqual`); 401
- **`--hostname 0.0.0.0` requires a token** — boot refuses without one.
- **`LOOPBACK_BINDS` includes IPv6** — `::1` and `[::1]` count as loopback for the no-token rule.
- **Host header allowlist** — on **loopback** binds the daemon checks `Host:` matches `localhost:port` / `127.0.0.1:port` / `[::1]:port` / `host.docker.internal:port` (case-insensitive per RFC 7230 §5.4) to defend against DNS rebinding. **Non-loopback binds (`--hostname 0.0.0.0`) intentionally bypass the Host allowlist** — the operator has chosen the surface area, so the bearer-token gate is the sole authentication layer; reverse proxies / SNI / client cert pinning are the operator's responsibility, not the daemon's. If you need Host-based isolation on a non-loopback bind, terminate TLS + check Host at a front proxy.
- **CORS denies any browser Origin by default** — returns `403` JSON. Pass **`--allow-origin <pattern>`** (repeatable, T2.4 #4514) to opt specific browser origins through. Each value is either the literal `*` (any origin — boot refuses if no bearer token is configured; `--require-auth` on loopback is recommended for full hardening since `/health` and `/demo` remain pre-auth on loopback by default) or a canonical URL origin (`<scheme>://<host>[:<port>]`, no trailing slash / path / userinfo). Matched origins receive proper CORS response headers (`Access-Control-Allow-Origin: <echoed>`, `Vary: Origin`, plus standard methods / headers / max-age and exposed `Retry-After`); unmatched origins still get a 403 with the same envelope as the default wall. `caps.features.allow_origin` is advertised conditionally so SDK / webui clients can pre-flight whether the daemon honors cross-origin hits before issuing them. Example: `qwen serve --allow-origin http://localhost:3000 --allow-origin http://localhost:5173`. Loopback self-origin hits (e.g. the `/demo` page) are unaffected — a separate Origin-strip shim handles them regardless of `--allow-origin`. **Browser webuis without `--allow-origin` configured** still fall back to the same Stage 1 options as before: package as a native shell (Electron/Tauri) so no `Origin` header is sent, or front the daemon with a same-origin reverse proxy.
- **CORS denies any browser Origin** — returns `403` JSON. **Implication for browser-served webuis** (BUy4e): any `packages/webui`-style frontend that lives on a separate origin will get 403 at the wire. Stage 1 options for browser-style consumption: (a) package the webui as a native shell (Electron/Tauri) so no `Origin` header is sent, or (b) front the daemon with a same-origin reverse proxy that strips/rewrites `Origin` for a known frontend. Stage 1.5 will add `--allow-origin <pattern>` for opt-in named frontends.
- **Spawned `qwen --acp` child inherits the daemon's environment** with one explicit scrub: `QWEN_SERVER_TOKEN` is removed before the child starts (the daemon's own bearer; the agent doesn't need it). Everything else — `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `QWEN_*` / `DASHSCOPE_API_KEY` / your custom `modelProviders[].envKey` / etc. — passes through, because the agent legitimately needs those to authenticate to the LLM. **This is intentional, not a sandbox.** The agent runs as the same UID with shell-tool access, so anything in `~/.bashrc` / `~/.aws/credentials` / `~/.npmrc` is reachable by prompt injection regardless. The env passthrough is not the security boundary; the user-as-trust-root is. Don't run `qwen serve` under an identity that has env-resident credentials you wouldn't trust the agent with.
- **Per-subscriber bounded SSE queues** — a slow client that overflows its queue gets a `client_evicted` terminal frame and is closed; one stuck consumer can't pin the daemon.
- **Graceful shutdown** — SIGINT/SIGTERM drain the agent children before closing the listener (10s deadline per child).
@ -271,31 +234,11 @@ The token comparison is constant-time (SHA-256 + `crypto.timingSafeEqual`); 401
> "alive" until Node's keepalive probes time out — typically ~2 hours
> on Linux defaults. On `--hostname 0.0.0.0` deployments behind such
> NATs, phantom SSE connections can accumulate and eventually hit the
> 256 `server.maxConnections` ceiling.
>
> Set [`--writer-idle-timeout-ms <n>`](#deadlines-and-writer-idle-timeout)
> (issue [#4514](https://github.com/QwenLM/qwen-code/issues/4514) T2.9)
> to close the gap with an explicit application-level idle deadline:
> when no write has successfully flushed for `n` ms the daemon emits
> a terminal `client_evicted` frame with
> `reason: 'writer_idle_timeout'` and closes the stream. The flag is
> off by default to preserve the legacy contract — operators on
> networks that swallow RSTs should pick a value well above the 15s
> heartbeat interval (e.g. `60000`–`300000`) so legitimate idle
> connections aren't evicted while genuinely stuck writers are
> reaped promptly. Pre-flight `caps.features.includes('writer_idle_timeout')`
> from your SDK to confirm the daemon supports it.
### Deadlines and writer idle timeout
Issue [#4514](https://github.com/QwenLM/qwen-code/issues/4514) T2.9 ships two opt-in flags that close the long-running / remote-deployment gaps the 15s heartbeat + AbortSignal don't cover. Both are off by default — single-user loopback workflows stay bit-for-bit unchanged.
| Flag | Env var | Default | What it does |
| ------------------------------ | ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--prompt-deadline-ms <n>` | `QWEN_SERVE_PROMPT_DEADLINE_MS` | unset | Server-side wallclock cap on a single `POST /session/:id/prompt`. On expiry the daemon aborts the prompt's AbortController and returns HTTP `504` with `{code:"prompt_deadline_exceeded", errorKind:"prompt_deadline_exceeded", deadlineMs:n}`. A per-prompt request body field `deadlineMs` can SHORTEN the effective deadline below the flag but never extend it. Capability tag (conditional): `prompt_absolute_deadline`. |
| `--writer-idle-timeout-ms <n>` | `QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS` | unset | Per-SSE-connection idle deadline. When no write has SUCCESSFULLY flushed for `n` ms — neither a real event nor the 15s heartbeat — the daemon emits a terminal `client_evicted` frame with `data.reason = 'writer_idle_timeout'` (mirrored on `data.errorKind`) and closes the stream. **Pick a value comfortably above the 15s heartbeat** (e.g. `30000`–`300000`) so legitimate idle streams aren't evicted; values `< 15000` WILL evict otherwise-healthy idle connections before the first heartbeat fires (intentional only for tests / short-lived dev sessions). Capability tag (conditional): `writer_idle_timeout`. |
Both flags accept a positive integer in milliseconds; `0`, `NaN`, non-integer, or negative values are rejected at boot with a clear error message. CLI flag wins over env var; explicit `ServeOptions` field (embedded callers) wins over env. SDK consumers should pre-flight the matching capability tag before relying on either behavior — daemons predating this PR omit both tags and the request `deadlineMs` field is silently dropped.
> 256 `server.maxConnections` ceiling. Stage 2 will add an
> application-level idle deadline (last-byte-written tracking +
> per-connection timeout). Until then, operators on networks that
> swallow RSTs may want to lower `server.keepAliveTimeout` via a
> reverse proxy or accept periodic daemon restarts.
## Multi-session & multi-workspace deployment
@ -391,10 +334,10 @@ The Stage 1.5 plan describes TUI as an in-process EventBus subscriber. In practi
No TUI shell runs inside the daemon. The slash commands listed above **don't exist** in this mode — there's no terminal UI to issue them from. Session state is therefore:
- **Boot-time-frozen** for `approval-mode` / `memory` / `agents` / `tools` allowlist / `auth` — all loaded from settings + disk when the daemon's `qwen --acp` child starts; immutable for the session's lifetime. Settings-defined MCP servers are likewise frozen at boot, but **runtime-added servers** (via `POST /workspace/mcp/servers`) can be added or removed without restart.
- **Mutable over HTTP** via `POST /session/:id/model` (publishes `model_switched`), `POST /workspace/mcp/servers` / `DELETE /workspace/mcp/servers/:name` (publishes `mcp_server_added` / `mcp_server_removed`), and permission votes (`POST /permission/:requestId`).
- **Boot-time-frozen** for `approval-mode` / `memory` / `mcp servers` / `agents` / `tools` allowlist / `auth` — all loaded from settings + disk when the daemon's `qwen --acp` child starts; immutable for the session's lifetime.
- **Mutable over HTTP** only via the routes this PR exposes — primarily `POST /session/:id/model` (publishes `model_switched`). Permission votes (`POST /permission/:requestId`) are per-request, not per-session-state.
**Consequence:** remote clients in headless mode see the **full session state**. No TUI hides additional state; no drift is possible. If you want to change `approval-mode`, restart the daemon with new settings. MCP servers can now be added/removed at runtime via the mutation routes (`POST /workspace/mcp/servers`, `DELETE /workspace/mcp/servers/:name`) — see [Runtime MCP server management](#runtime-mcp-server-management-issue-4514).
**Consequence:** remote clients in headless mode see the **full session state**. No TUI hides additional state; no drift is possible. If you want to change `approval-mode` or add an MCP server, restart the daemon with new settings — the daemon doesn't expose runtime mutation for those today.
#### Mode 2 — Stage 1.5 `qwen --serve` co-hosted TUI (not in this PR)
@ -481,161 +424,8 @@ const result = await flow.awaitCompletion({ signal: abortCtrl.signal });
**Cross-client take-over.** Two SDK clients on the same daemon that both `POST /workspace/auth/device-flow` for the same provider get the per-provider singleton: the first call starts a fresh IdP request and returns `attached: false`; the second call returns the EXISTING in-flight entry with `attached: true`. The take-over is recorded on the audit trail (under the second client's `X-Qwen-Client-Id`) but does NOT emit a separate event — both clients eventually observe the SAME `auth_device_flow_authorized` once the user finishes the IdP page. If your UI distinguishes "I started this" from "someone else's flow I joined", branch on the `attached` field returned by `start()`.
## Daemon log file
`qwen serve` writes a per-process diagnostic log to:
```
${QWEN_RUNTIME_DIR or ~/.qwen}/debug/daemon/serve-<pid>-<workspaceHash>.log
```
A `latest` symlink in the same directory always points at the current process's log, so `tail -f ~/.qwen/debug/daemon/latest` will follow whichever daemon is running.
The log captures lifecycle messages, route errors (with `route=` and `sessionId=` context), ACP child stderr, and — when `QWEN_SERVE_DEBUG=1` is set — extra bridge breadcrumbs. Lines that go to stderr today still go to stderr; the file log is **additive**, not a replacement.
### Disabling
Set `QWEN_DAEMON_LOG_FILE=0` (or `false`/`off`/`no`) to skip file logging entirely. Stderr output is unaffected.
### Relation to session debug logs
Session-scoped debug logs (`~/.qwen/debug/<sessionId>.txt` and the `~/.qwen/debug/latest` symlink) are independent. The daemon log lives in a sibling `daemon/` subdirectory; per-session debug semantics are unchanged by this feature.
### No rotation
The daemon log appends indefinitely. Rotate manually if it grows large. A future enhancement may add automatic rotation; track via [#4548](https://github.com/QwenLM/qwen-code/issues/4548) follow-ups.
## Runtime MCP server management (issue [#4514](https://github.com/QwenLM/qwen-code/issues/4514))
Add or remove MCP servers at runtime without restarting the daemon. Runtime entries live in an ephemeral overlay that **shadows** settings-defined servers of the same name; the underlying `settings.json` / `mcpServers` config is never written to.
**Pre-flight:** check `caps.features` for `mcp_server_runtime_mutation` before calling either route. Older daemons without this tag return `404`.
### `POST /workspace/mcp/servers` — add a runtime MCP server
Strict-gated (bearer token required). Connects the server immediately via the live `McpClientManager` and discovers its tools.
Request:
```json
{
"name": "my-server",
"config": {
"command": "npx",
"args": ["-y", "@my-org/mcp-server"]
}
}
```
`name` must be alphanumeric plus `_` and `-` (max 256 characters). `config` is the same MCP server configuration object used in `settings.json` `mcpServers` entries (transport-dependent fields: `command`/`args` for stdio, `url` for SSE/HTTP). Security-sensitive fields (`trust`, `env`, `cwd`, `oauth`, `headers`, `authProviderType`, `includeTools`, `excludeTools`, `type`) are stripped by the daemon and ignored.
Response (200) — success:
```json
{
"name": "my-server",
"transport": "stdio",
"replaced": false,
"shadowedSettings": false,
"toolCount": 3,
"originatorClientId": "client-1"
}
```
- `replaced: true` — a runtime entry with the same name already existed and the config fingerprint differs; old connection torn down, new one established. When the fingerprint matches (idempotent re-add), `replaced` is `false`.
- `shadowedSettings: true` — a settings-defined server with the same name exists; the runtime entry now shadows it. The settings entry is untouched and re-emerges if the runtime entry is later removed.
- `toolCount` — number of tools discovered on the newly connected server.
Response (200) — soft refuse (budget warning mode):
```json
{
"name": "my-server",
"skipped": true,
"reason": "budget_warning_only"
}
```
Returned when `--mcp-budget-mode=warn` and adding the server would exceed the configured `--mcp-client-budget`. The server is NOT connected. Callers should surface the budget pressure to the user.
Errors:
| Status | Code | When |
| ------ | ------------------------- | -------------------------------------------------------------------------------------------------- |
| `400` | `invalid_server_name` | Name empty, exceeds 256 chars, or contains characters outside `[A-Za-z0-9_-]` |
| `400` | `missing_required_field` | `config` missing or not a non-null object |
| `400` | `invalid_client_id` | `X-Qwen-Client-Id` header present but not registered for this workspace |
| `400` | `invalid_config` | Config shape rejected by the MCP transport validator |
| `401` | `token_required` | No bearer token configured (strict gate) |
| `409` | `mcp_budget_would_exceed` | `--mcp-budget-mode=enforce` and budget is full |
| `502` | `mcp_server_spawn_failed` | Server process exited or timed out during connect; body carries `serverName`, `exitCode`, `stderr` |
| `503` | `acp_channel_unavailable` | No live ACP child (no session has been created yet) |
### `DELETE /workspace/mcp/servers/:name` — remove a runtime MCP server
Strict-gated. Disconnects the server and removes it from the runtime overlay. Idempotent — removing a name that was never added returns a skip response (not an error).
The `:name` path parameter is the URL-encoded server name.
Response (200) — success:
```json
{
"name": "my-server",
"removed": true,
"wasShadowingSettings": false,
"originatorClientId": "client-1"
}
```
- `wasShadowingSettings: true` — the removed runtime entry was shadowing a settings-defined server of the same name. That settings entry is now un-shadowed and will be used on next discovery/restart.
Response (200) — idempotent skip:
```json
{
"name": "ghost",
"skipped": true,
"reason": "not_present"
}
```
Returned when the name was not in the runtime overlay (it may still exist in settings — settings entries cannot be removed via this route).
Errors:
| Status | Code | When |
| ------ | ------------------------- | ----------------------------------------------------------------------------- |
| `400` | `invalid_server_name` | Name empty, exceeds 256 chars, or contains characters outside `[A-Za-z0-9_-]` |
| `400` | `invalid_client_id` | `X-Qwen-Client-Id` header present but not registered for this workspace |
| `401` | `token_required` | No bearer token configured (strict gate) |
| `503` | `acp_channel_unavailable` | No live ACP child |
### Shadow semantics
Runtime entries form an ephemeral overlay on top of settings-defined MCP servers:
- **Adding** a runtime server with the same name as a settings entry **shadows** it — the runtime config takes precedence. The original settings entry is not modified.
- **Removing** a runtime server that was shadowing a settings entry **un-shadows** it — the settings-defined config becomes active again on next connection.
- **Daemon restart** loses all runtime entries. Only settings-defined servers survive across restarts. Runtime servers are session-lifetime scoped.
- **`GET /workspace/mcp`** reports the merged view — both settings-defined and runtime servers appear in the `servers[]` array. There is no wire-level distinction between the two origins in the snapshot today.
### Events
Both routes emit **workspace-scoped** SSE events (all active session buses receive them):
| Event | Emitted when | Payload fields |
| -------------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
| `mcp_server_added` | `POST` succeeds (not skipped) | `name`, `transport`, `replaced`, `shadowedSettings`, `toolCount`, `originatorClientId` |
| `mcp_server_removed` | `DELETE` succeeds (not skipped) | `name`, `wasShadowingSettings`, `originatorClientId` |
Skipped responses (`budget_warning_only`, `not_present`) do NOT emit events.
Budget-related events from the existing `mcp_guardrail_events` surface (`mcp_budget_warning`, `mcp_child_refused_batch`) also fire when runtime additions cross the budget threshold.
## What's next
- **Setting up a long-running daemon?** [Local launch templates (systemd / launchd / nohup / tmux)](./qwen-serve-deploy-local.md) for v0.16-alpha (local-only).
- **Build a client?** See the [DaemonClient TypeScript quickstart](../developers/examples/daemon-client-quickstart.md) and the [HTTP protocol reference](../developers/qwen-serve-protocol.md).
- **Reading the source?** Bridge code lives at `packages/cli/src/serve/`; SDK client at `packages/sdk-typescript/src/daemon/`.
- **Tracking the roadmap?** Stage 1.5 / Stage 2 progress is tracked on issue [#3803](https://github.com/QwenLM/qwen-code/issues/3803).

View File

@ -0,0 +1,120 @@
# AbortController refactor — verification plan
Scenarios used to validate the change manually before opening the PR. Each
scenario captures its tmux pane via `tmux pipe-pane -o 'cat >> <log>'`.
## Setup once
```sh
# Point WT at your local checkout of the branch under review.
WT=/path/to/qwen-code/worktree
LOGDIR=$WT/docs/verification/abort-controller-refactor/logs
mkdir -p "$LOGDIR"
# Build the CLI once (skip sandbox image, skip vscode).
( cd "$WT" && npm run build:packages )
```
## Scenarios
For each scenario:
```sh
tmux new-session -d -s qwen-verify-XX
tmux pipe-pane -t qwen-verify-XX -o "cat >> $LOGDIR/XX-name.log"
tmux send-keys -t qwen-verify-XX "cd /path/to/your/test/workspace && exec node $WT/packages/cli/dist/index.js" C-m
tmux attach -t qwen-verify-XX
```
Then drive the session manually per the matrix below. Hit `C-b d` to detach
when done; `tmux kill-session -t qwen-verify-XX` to stop the pane.
### 00 — Baseline (PRE-fix)
- **Setup:** check out `main`, build, run with `NODE_OPTIONS=--trace-warnings`.
- **Input:** long 50-round mixed-tool session (shell + edit + grep + agent).
- **Expected:** after ~30–40 rounds, `MaxListenersExceededWarning: ... 1500+ abort listeners added to [AbortSignal]` printed to stderr.
- **Log:** `00-baseline-reproduction.log`.
### 01 — Long-session, DEBUG mode (this branch)
- **Setup:** `NODE_OPTIONS=--trace-warnings DEBUG=1 qwen`.
- **Input:** same 50-round script as #00.
- **Expected:** no `MaxListenersExceededWarning` printed; any other warnings still print.
- **Log:** `01-long-session-debug.log`.
### 02 — Long-session, prod mode (this branch)
- **Setup:** `qwen` (no debug env).
- **Input:** same 50-round script.
- **Expected:** clean output; a temporary `console.error` probe inside the handler (added then removed) confirms the filter fires.
- **Log:** `02-long-session-prod.log`.
### 03 — Ctrl-C mid-stream abort
- **Setup:** this branch, interactive.
- **Input:** ask for a long generation (>30s); press Ctrl-C mid-stream.
- **Expected:** stream stops within ~200ms, "Cancelled" banner shown, next prompt accepts input. `process._getActiveHandles()` count returns to baseline (use `:debug handles`).
- **Log:** `03-ctrlc-streaming.log`.
### 04 — Cancel long-running shell
- **Setup:** this branch.
- **Input:** run `sleep 60` via the shell tool; cancel mid-execution.
- **Expected:** child process killed (verify with `pgrep -f sleep` returning empty), tool result shows cancellation, agent accepts next prompt.
- **Log:** `04-shell-cancel.log`.
### 05 — Subagent cancellation
- **Setup:** this branch.
- **Input:** spawn a long agent task via the agent tool; cancel from parent.
- **Expected:** subagent's in-flight tool calls abort, subagent's model stream stops, parent receives cancellation event.
- **Log:** `05-subagent-cancel.log`.
### 06 — Headless / non-interactive abort
- **Setup:** `qwen --prompt "do a long task"`; send `SIGINT` from outside via `kill -INT <pid>`.
- **Expected:** clean shutdown, exit code 130, no warnings.
- **Log:** `06-headless-abort.log`.
### 07 — Background agent flow
- **Setup:** interactive.
- **Input:** spawn a background agent (`run_in_background: true`); let it complete; spawn a second one; cancel the second mid-flight.
- **Expected:** first agent completes normally; second aborts cleanly; no listener leak across the two.
- **Log:** `07-background-agent.log`.
### 08 — Memory baseline
- **Setup:** `qwen --inspect`, attach Chrome devtools.
- **Input:** 100-round session.
- **Expected:** heap snapshots at round 0/50/100. `AbortSignal` instance count and per-signal listener count stable (no monotonic growth).
- **Log:** `08-memory-snapshots/`.
### 09 — Existing combinedAbortSignal consumer
- **Setup:** trigger an HTTP hook with both an external signal and timeout.
- **Input:** (a) cancel external signal mid-hook; (b) let timeout fire in a separate run.
- **Expected:** hook aborts cleanly in both cases; deprecation shim path is exercised.
- **Log:** `09-http-hook-shim.log`.
## Automated (non-interactive) verifications
The automated checks below were run during development and recorded in
`automated-results.md`:
- All abortController unit tests pass (`abortController.test.ts`, 26 tests; 1 GC test skipped under non-`--expose-gc`).
- All warningHandler tests pass (`warningHandler.test.ts`, 13 tests including a spawned-child stderr integration test).
- All `combineAbortSignals` consumer tests pass (`httpHookRunner.test.ts`); the deprecated `createCombinedAbortSignal` shim plus its own test file were removed once the lone caller migrated.
- All agent runtime / followup / openaiContentGenerator / hooks tests pass.
- Migration scope (intentional): only the agent-runtime parent→child chain (`agent-interactive.ts`, `agent-core.ts`, `agent-headless.ts`) plus `promptHookRunner.ts` (real cleanup leak) was switched to the helper. Independent short-lived controllers (per-shell-command, per-fetch, per-recall, etc.) stay on raw `new AbortController()` — they're GC'd quickly and don't accumulate listeners on a long-lived parent. See `migration-completeness.txt` for the captured grep + rationale.
- TypeScript strict-mode typecheck passes for both `packages/core` and `packages/cli`.
- Prettier check passes on all modified files.
See `automated-results.md` for the actual command output.
## How to capture the artifacts for the PR body
After running each scenario, attach the transcript file (or relevant excerpt)
to the PR. For #08 (memory), export the heap snapshots and include the
listener-count delta between snapshots.

View File

@ -0,0 +1,139 @@
# Automated verification results
Captured 2026-05-20 during the AbortController refactor.
## 1. Listener-accumulation reproducer
Direct simulation of the listener-accumulation pattern observed in long
sessions (1500+ abort listeners on a single AbortSignal). The script lives
at `listener-accumulation-repro.mjs`.
```text
$ node docs/verification/abort-controller-refactor/listener-accumulation-repro.mjs
Simulating 2000 rounds for each pattern.
OLD pattern listener count on long-lived parent: 2000
NEW pattern listener count on long-lived parent: 0
PASS: OLD pattern accumulated >1500 listeners (reproduces the bug).
PASS: NEW pattern kept listener count at 0 — the helper prevents accumulation.
```
This is a self-contained proof: the OLD pattern (raw `addEventListener`
without `{once:true}` or reverse cleanup) accumulates 2000 listeners over
2000 rounds — well past the 1500 threshold the user observed. The NEW
pattern (`createChildAbortController` from `packages/core/src/utils/abortController.ts`)
keeps the parent listener count at 0 across 2000 rounds because each child's
reverse-cleanup listener removes the parent listener when the child aborts.
## 2. Migration scope (intentional)
Only the agent-runtime parent→child chain that actually accumulates listeners
on a long-lived parent signal is migrated to the helper:
- `packages/core/src/agents/runtime/agent-interactive.ts` (master + per-message round)
- `packages/core/src/agents/runtime/agent-core.ts` (per-iteration round + waitForExternalInputs + processFunctionCalls try/finally)
- `packages/core/src/agents/runtime/agent-headless.ts` (external → execution)
- `packages/core/src/hooks/promptHookRunner.ts` (had a real cleanup leak: manual addEventListener without `{once:true}` and never removed)
Plus three `{once:true}`-only fixes (no helper switch, just defensive
correctness):
- `packages/core/src/hooks/hookRunner.ts`
- `packages/core/src/hooks/functionHookRunner.ts`
- `packages/core/src/confirmation-bus/message-bus.ts`
Independent short-lived controllers (per-shell-command in `tools/shell.ts`,
per-monitor in `tools/monitor.ts`, per-arena-session in
`agents/arena/ArenaManager.ts`, per-recall in `core/client.ts`,
per-fetch in `utils/fetch.ts`, per-dream / per-title / per-judge / per-resume,
etc.) stay on raw `new AbortController()` — they're GC'd at end of use and
do not accumulate on a long-lived parent.
See `migration-completeness.txt` for the actual grep + rationale.
## 3. Affected test suites
All 71 affected test files / 2085 tests pass (3 skipped — 1 is the GC test
that requires `--expose-gc`, 2 are pre-existing skips in the headless suite).
```text
Test Files 71 passed (71)
Tests 2085 passed | 3 skipped (2088)
Duration 16.71s
```
Coverage:
- `packages/core/src/utils/abortController.test.ts` — 26 tests: factory cap (default + custom), child propagation, reverse cleanup, fast path, undefined parent, custom-maxListeners passthrough, `combineAbortSignals` semantics (incl. cleanup-cancels-timeout, timeout-cleans-input-listeners, `timeoutMs <= 0` boundary, mid-iteration defensive check), GC safety (best-effort).
- `packages/cli/src/utils/warningHandler.test.ts` — 13 tests: idempotency, AbortSignal suppression (including `[AbortSignal{...}]` shape), generic EventTarget NOT suppressed, debug-mode passthrough, fan-out to prior listeners, spawned-child end-to-end stderr integration.
- `packages/core/src/hooks/httpHookRunner.test.ts` — covers the migrated `combineAbortSignals` consumer (the deprecated `createCombinedAbortSignal` shim plus its test file were removed once the lone caller migrated).
- `packages/core/src/agents/runtime/{agent-core,agent-interactive,agent-headless,agent-context,agent-statistics}.test.ts` — 102 tests covering the high-impact migrated files.
- `packages/core/src/core/openaiContentGenerator/**` — 280+ tests including the pipeline that lost the `raiseAbortListenerCap` band-aid.
- `packages/core/src/followup/**` — 100+ tests including the migrated speculation controller.
- `packages/core/src/tools/agent/**`, `packages/core/src/tools/shell.test.ts`, `packages/core/src/services/**`, `packages/core/src/hooks/**`, `packages/core/src/confirmation-bus/**` — all migrated tool/hook/service files.
## 4. TypeScript strict-mode typecheck
```sh
$ node_modules/.bin/tsc -p packages/core/tsconfig.json --noEmit
(no output, exit 0)
$ node_modules/.bin/tsc -p packages/cli/tsconfig.json --noEmit
(no output, exit 0)
```
## 5. Prettier formatting
```sh
$ node_modules/.bin/prettier --check packages/core/src/agents/runtime/agent-core.ts \
packages/core/src/agents/runtime/agent-headless.ts \
packages/cli/src/utils/warningHandler.ts \
packages/cli/src/utils/warningHandler.test.ts \
packages/core/src/utils/abortController.ts \
packages/core/src/utils/abortController.test.ts
Checking formatting...
All matched files use Prettier code style!
```
## 6. Build + binary smoke test
```sh
$ npm run build:packages
(succeeds for all 5 workspace packages)
$ NODE_OPTIONS=--trace-warnings node packages/cli/dist/index.js --version
0.15.11
EXIT=0
$ node packages/cli/dist/index.js --help
Usage: qwen [options] [command]
...
```
No warnings emitted during boot with `--trace-warnings`.
## 7. Codex independent review
Two full passes via the `codex:codex-rescue` agent (independent context each
time). First pass surfaced 3 issues — all addressed in subsequent commits:
1. **Throw between controller creation and explicit abort leaks listener** in
`agent-core.ts`'s per-iteration body and `agent-headless.ts`'s
pre-try-block setup. Fixed by wrapping each in `try { ... } finally {
abortController.abort(); }`.
2. **Warning suppressor regex `EventTarget` too broad**. Tightened to match
only `AbortSignal` (any shape Node ≥20 produces).
3. **`process.removeAllListeners('warning')` strips third-party listeners**.
Removed — rely on Node's "no listeners → default printer fires" semantics
so adding our handler implicitly disables the default print path while
keeping third-party telemetry listeners intact.
Second pass confirmed all fixes correct, no further blockers.
## What remains for interactive verification
The scenarios in `README.md` numbered 00–09 require a real interactive
session against the model API (long mixed-tool conversations, Ctrl-C
mid-stream, subagent cancellation, heap snapshots). Those are documented
for human execution and the transcripts should be attached to the PR body
when run.

View File

@ -0,0 +1,107 @@
#!/usr/bin/env node
/**
* Direct simulation of the listener-accumulation pattern the agent runtime
* exhibits in long sessions. Builds a deep parent → child chain to a depth
* the user observed (>1500 listeners) and asserts:
*
* 1. The OLD pattern (plain new AbortController + manual addEventListener
* without {once:true} or reverse cleanup) accumulates listeners on the
* long-lived parent — reproducing the warning.
*
* 2. The NEW pattern (createChildAbortController from the helper) keeps the
* parent listener count bounded by 1, regardless of how many short-lived
* children come and go.
*
* Run:
* node docs/verification/abort-controller-refactor/listener-accumulation-repro.mjs
*/
import { getEventListeners, setMaxListeners } from 'node:events';
// Inline copy of the production helper (packages/core/src/utils/abortController.ts)
// so this script has no build-step dependency on @qwen-code/qwen-code-core.
// Kept in sync — the child is held STRONGLY by the parent's listener closure
// (no WeakRef on child) so propagation works even when a caller drops the
// controller and keeps only the signal. WeakRef is used only on the PARENT,
// to keep child cleanup from pinning a long-lived parent in memory.
function createAbortController(maxListeners = 50) {
const c = new AbortController();
setMaxListeners(maxListeners, c.signal);
return c;
}
function createChildAbortController(parent) {
const child = createAbortController();
if (!parent) return child;
const parentSignal = parent.signal ?? parent;
if (parentSignal.aborted) {
child.abort(parentSignal.reason);
return child;
}
const weakParent = new WeakRef(parentSignal);
const handler = () => {
child.abort(weakParent.deref()?.reason);
};
parentSignal.addEventListener('abort', handler, { once: true });
child.signal.addEventListener(
'abort',
() => {
weakParent.deref()?.removeEventListener('abort', handler);
},
{ once: true },
);
return child;
}
const ROUNDS = 2000;
console.log(`Simulating ${ROUNDS} rounds for each pattern.\n`);
// ─── OLD pattern: plain new AbortController + manual addEventListener ───
const oldParent = new AbortController();
setMaxListeners(0, oldParent.signal); // disable warning so we can measure cleanly
for (let i = 0; i < ROUNDS; i++) {
const child = new AbortController();
// No {once:true}, no reverse cleanup — accumulates on oldParent.
oldParent.signal.addEventListener('abort', () => child.abort());
}
const oldCount = getEventListeners(oldParent.signal, 'abort').length;
// ─── NEW pattern: createChildAbortController ───
const newParent = createAbortController();
for (let i = 0; i < ROUNDS; i++) {
const child = createChildAbortController(newParent);
child.abort(); // simulate end-of-round cleanup via try/finally
}
const newCount = getEventListeners(newParent.signal, 'abort').length;
console.log(`OLD pattern listener count on long-lived parent: ${oldCount}`);
console.log(`NEW pattern listener count on long-lived parent: ${newCount}`);
const expectations = {
oldShouldExceed: 1500,
newMustBe: 0,
};
let pass = true;
if (oldCount <= expectations.oldShouldExceed) {
console.error(
`FAIL: OLD pattern should accumulate >${expectations.oldShouldExceed} listeners; got ${oldCount}`,
);
pass = false;
} else {
console.log(
`PASS: OLD pattern accumulated >${expectations.oldShouldExceed} listeners (reproduces the bug).`,
);
}
if (newCount !== expectations.newMustBe) {
console.error(
`FAIL: NEW pattern must have exactly ${expectations.newMustBe} listeners; got ${newCount}`,
);
pass = false;
} else {
console.log(
`PASS: NEW pattern kept listener count at ${expectations.newMustBe} — the helper prevents accumulation.`,
);
}
process.exit(pass ? 0 : 1);

View File

@ -0,0 +1,28 @@
$ grep -rn "new AbortController" packages/core/src --include="*.ts" \
| grep -v test | grep -v abortController.ts
# Scoped to the nested parent→child chain that actually accumulates listeners
# (the agent-runtime loop in long sessions, plus promptHookRunner which had a
# real cleanup leak). Independent short-lived controllers (per-shell-command,
# per-fetch, per-recall, per-arena-session etc.) intentionally stay on raw
# `new AbortController()` — they're GC'd at the end of their use and do not
# accumulate listeners on a long-lived parent signal.
packages/core/src/followup/speculation.ts:100: const abortController = new AbortController();
packages/core/src/tools/agent/agent.ts:1722: const bgAbortController = new AbortController();
packages/core/src/tools/agent/agent.ts:2116: const fgAbortController = new AbortController();
packages/core/src/tools/shell.ts:1514: const promoteAbortController = new AbortController();
packages/core/src/tools/shell.ts:2364: const entryAc = new AbortController();
packages/core/src/tools/shell.ts:2772: const entryAc = new AbortController();
packages/core/src/tools/monitor.ts:306: const entryAc = new AbortController();
packages/core/src/core/client.ts:1199: const controller = new AbortController();
packages/core/src/memory/manager.ts:936: const abortController = new AbortController();
packages/core/src/goals/goalHook.ts:70: const judgeController = new AbortController();
packages/core/src/goals/goalHook.ts:169: const signal = context?.signal ?? new AbortController().signal;
packages/core/src/agents/arena/ArenaManager.ts:305: this.masterAbortController = new AbortController();
packages/core/src/agents/arena/ArenaManager.ts:817: abortController: new AbortController(),
packages/core/src/agents/background-agent-resume.ts:421: abortController: new AbortController(),
packages/core/src/agents/background-agent-resume.ts:493: const bgAbortController = new AbortController();
packages/core/src/agents/background-agent-resume.ts:922: abortController: new AbortController(),
packages/core/src/utils/fetch.ts:64: const controller = new AbortController();
packages/core/src/services/chatRecordingService.ts:963: const controller = new AbortController();
packages/core/src/services/chatCompressionService.ts:387: abortSignal: signal ?? new AbortController().signal,

View File

@ -0,0 +1,23 @@
#!/usr/bin/env bash
# Scenario 02-lite — single real-Qwen prompt under --trace-warnings.
# Demonstrates the steady-state path emits no MaxListenersExceededWarning.
set -uo pipefail
WT="${WT:-$(git rev-parse --show-toplevel)}"
LOG="$WT/docs/verification/abort-controller-refactor/logs/02-lite-short-prompt.log"
mkdir -p "$(dirname "$LOG")"
NODE_OPTIONS=--trace-warnings node "$WT/packages/cli/dist/index.js" \
--prompt "Reply with exactly 'OK' and nothing else." > "$LOG" 2>&1 &
PID=$!
for i in $(seq 1 90); do
if ! kill -0 $PID 2>/dev/null; then break; fi
sleep 1
done
if kill -0 $PID 2>/dev/null; then kill -9 $PID; echo "TIMEOUT"; exit 1; fi
wait $PID 2>/dev/null
EC=$?
echo "EXIT=$EC"
echo "MaxListenersExceededWarning count: $(grep -c MaxListenersExceededWarning "$LOG")"
echo "--- log ---"
cat "$LOG"

View File

@ -0,0 +1,18 @@
#!/usr/bin/env bash
# Scenario 06 — headless --prompt + SIGINT. Verifies the agent shuts down
# cleanly when an external signal aborts the in-flight stream.
set -uo pipefail
WT="${WT:-$(git rev-parse --show-toplevel)}"
LOG="$WT/docs/verification/abort-controller-refactor/logs/06-headless-sigint.log"
mkdir -p "$(dirname "$LOG")"
NODE_OPTIONS=--trace-warnings node "$WT/packages/cli/dist/index.js" \
--prompt "Please write a detailed essay about the history of distributed systems, at least 500 words." > "$LOG" 2>&1 &
PID=$!
sleep 6
kill -INT $PID
wait $PID 2>/dev/null
EC=$?
echo "EXIT_CODE=$EC (expected 130)"
echo "MaxListenersExceededWarning count: $(grep -c MaxListenersExceededWarning "$LOG")"

View File

@ -0,0 +1,2 @@
0.15.11
EXIT=0

View File

@ -0,0 +1,10 @@
✓ |@qwen-code/qwen-code-core| src/core/openaiContentGenerator/provider/minimax.test.ts (9 tests) 2ms
✓ |@qwen-code/qwen-code-core| src/followup/suggestionGenerator.test.ts (16 tests) 2ms
✓ |@qwen-code/qwen-code-core| src/followup/speculation.test.ts (7 tests) 2ms
✓ |@qwen-code/qwen-code| src/utils/warningHandler.test.ts (9 tests) 5ms
Test Files 71 passed (71)
Tests 2085 passed | 3 skipped (2088)
Start at 02:35:37
Duration 16.71s (transform 1.77s, setup 92ms, collect 14.79s, tests 3.03s, environment 319ms, prepare 2.20s)

View File

@ -191,7 +191,14 @@ export default tseslint.config(
},
// extra settings for scripts that we run directly with node
{
files: ['./scripts/**/*.js', './scripts/**/*.mjs', 'esbuild.config.js', 'packages/*/scripts/**/*.js'],
files: [
'./scripts/**/*.js',
'./scripts/**/*.mjs',
'esbuild.config.js',
'packages/*/scripts/**/*.js',
// Verification reproducer scripts under docs/ also run with `node`.
'docs/**/*.mjs',
],
languageOptions: {
globals: {
...globals.node,

View File

@ -214,7 +214,6 @@ describe('qwen serve — capabilities envelope', () => {
'workspace_preflight',
'session_context',
'session_supported_commands',
'session_tasks',
'session_close',
'session_metadata',
'mcp_guardrails',

3736
package-lock.json generated

File diff suppressed because it is too large Load Diff

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/qwen-code",
"version": "0.16.1",
"version": "0.17.0",
"engines": {
"node": ">=22.0.0"
},
@ -11,6 +11,7 @@
"packages/channels/telegram",
"packages/channels/weixin",
"packages/channels/dingtalk",
"packages/channels/feishu",
"packages/channels/plugin-example"
],
"repository": {
@ -18,7 +19,7 @@
"url": "git+https://github.com/QwenLM/qwen-code.git"
},
"config": {
"sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.16.1"
"sandboxImageUri": "ghcr.io/qwenlm/qwen-code:0.17.0"
},
"scripts": {
"start": "cross-env node scripts/start.js",

View File

@ -3,15 +3,14 @@
Shared ACP bridge primitives consumed by `qwen serve`, channels, IDE, TUI,
and remote-control adapters. Lives in the monorepo, not published to npm.
Lift history (#4175 Mode B daemon roadmap):
This is **PR 22a** of the Mode B daemon roadmap (#4175 Wave 5). The full
extraction is split:
| Slice | Scope | Status |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| **PR 22a** (#4295) | Skeleton + `EventBus` + `inMemoryChannel` + `AcpChannel` types + `PermissionMediator` type-only stub | ✅ merged |
| **PR 22b/1** (#4298) | Lift `status` + `workspacePaths` + `bridgeErrors` + `bridgeTypes` | ✅ merged |
| **PR 22b/2** (#4304) | Lift `BridgeOptions` + new `DaemonStatusProvider` injection seam | ✅ merged |
| **F1** (this PR) | Lift `defaultSpawnChannelFactory` + `BridgeClient` + `createHttpAcpBridge` factory closure + new `BridgeFileSystem` injection seam (22b' scope) | ✅ in this PR |
| **F3 PR 24** | Implement the four `PermissionMediator` strategies (`first-responder`, `designated`, `consensus`, `local-only`) + pair-token revocation + audit log | F3 in the feature-cohesive plan |
| Slice | Scope | Status |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **PR 22a** (this) | Skeleton + `EventBus` + `inMemoryChannel` + `AcpChannel` types + `PermissionMediator` type-only stub | this PR |
| **PR 22b** | Lift `BridgeClient` + `createHttpAcpBridge` + `defaultSpawnChannelFactory` from `cli/src/serve/httpAcpBridge.ts` | after PR 17 (#4282) and PR 14b (#4271) merge |
| **PR 24** | Implement the four `PermissionMediator` strategies (`first-responder`, `designated`, `consensus`, `local-only`) + pair-token revocation + audit log | Wave 5 |
## What's here today
@ -22,19 +21,18 @@ Lift history (#4175 Mode B daemon roadmap):
used for in-process bridge tests and the parked Mode A
(`qwen --serve`) path.
- `channel` — `AcpChannel` / `AcpChannelExitInfo` / `ChannelFactory`
type contract that `createHttpAcpBridge` (now in this package) plus
the channels / VSCode IDE companion's own-spawn paths consume via
type contract that `httpAcpBridge.ts` already injects via
`BridgeOptions.channelFactory`.
- `permission` — type-only `PermissionMediator` interface,
`PermissionPolicy` literal union (4 strategies), and
`PermissionResolution` discriminated union. **No implementation
yet** — first-responder voting still lives in
`BridgeClient.requestPermission` (in `bridgeClient.ts` after F1).
F3 PR 24 will move that and add the other three policies behind
this interface.
`cli/src/serve/httpAcpBridge.ts BridgeClient.requestPermission`.
PR 24 will move that and add the other three policies behind this
interface.
- `status` (PR 22b/1) — wire-contract status types for
`/workspace/{mcp,skills,providers,env,preflight}` and
`/session/:id/{context,supported-commands,tasks}` routes, the
`/session/:id/{context,supported-commands}` routes, the
`STATUS_SCHEMA_VERSION` / `SERVE_*_EXT_METHODS` constants,
`BridgeTimeoutError` / `MissingCliEntryError` /
`BridgeChannelClosedError` typed exceptions, and the
@ -58,50 +56,28 @@ Lift history (#4175 Mode B daemon roadmap):
- `bridgeOptions` (PR 22b/2) — `BridgeOptions` interface (factory
construction contract: `boundWorkspace`, `channelFactory`,
`maxSessions`, `eventRingSize`, `permissionResponseTimeoutMs`,
persistence callbacks, etc.) plus the `DaemonStatusProvider`
persistence callbacks, etc.) and the new `DaemonStatusProvider`
injection seam for daemon-host env / preflight cells (production
impl in `cli/src/serve/daemonStatusProvider.ts`) and the F1
`BridgeFileSystem` injection seam for the ACP fs proxy.
- `spawnChannel` (F1) — `defaultSpawnChannelFactory` + `killChild` +
`SCRUBBED_CHILD_ENV_KEYS` denylist + `scrubChildEnv` pure env-policy
helper (exported for adapter reuse + unit-test access; isolates the
scrub + override + defense-in-depth ordering invariant the security
argument relies on). Production spawn of the `qwen --acp` child
with stderr prefix-and-forward, kill cascade, and env passthrough.
Channels (`packages/channels/base/AcpBridge.ts`) and the VSCode IDE
companion consume this directly instead of each reimplementing the
child lifecycle.
- `bridgeClient` (F1) — `BridgeClient` class implementing the ACP
`Client` surface: first-responder permission flow, session-update
fan-out into `EventBus`, child-side `extNotification` routing,
early-event buffer + tombstone bookkeeping, inline fs proxy for
`writeTextFile` / `readTextFile`. Exports the supporting
`PendingPermission` / `PermissionResolutionRecord` /
`BridgeClientSessionEntry` types + `MAX_RESOLVED_PERMISSION_RECORDS`
cap that the factory's bookkeeping maps consume.
- `bridge` (F1) — `createHttpAcpBridge` factory closure (~3000 LOC)
- `ChannelInfo` / `SessionEntry` interfaces + factory-only
helpers (`withTimeout`, `canonicalizeExistingAncestor`,
`verifyParentWithinWorkspace`, debug log helpers,
`hasControlCharacter`) + factory constants. Builds the
bookkeeping closures (`resolveEntry`, `registerPending`, etc.)
and wires them into `BridgeClient`.
- `bridgeFileSystem` (F1) — `BridgeFileSystem` interface for the
ACP fs proxy. When wired through `BridgeOptions.fileSystem`,
`BridgeClient.readTextFile` / `BridgeClient.writeTextFile`
delegate to it instead of the inline `fs.realpath` /
`fs.writeFile` / `fs.readFile` proxy. Production `qwen serve`
follow-up wraps PR 18's `WorkspaceFileSystem` here so writes
get TOCTOU + symlink + trust-gate + audit guarantees.
impl in `cli/src/serve/daemonStatusProvider.ts`).
## What's not here yet
- The bridge core itself (`BridgeClient`, `createHttpAcpBridge`,
`defaultSpawnChannelFactory`, all the `BridgeSession*` types).
It stays in `packages/cli/src/serve/httpAcpBridge.ts` until the
in-flight Wave 4 PRs that touch the bridge surface (#4282 PR 17 and
#4271 PR 14b) merge — moving it now would create a 3-way merge
on a 4400-LOC file for no win.
- The per-session FileSystemService injection point (PR 18 #4250
introduced the boundary; PR 22b will parameterize bridge writes
through it instead of the inline `BridgeClient.writeTextFile`).
## Imports — root vs subpaths
The package exposes both a barrel root (`@qwen-code/acp-bridge`) and
per-module subpaths (`/eventBus`, `/inMemoryChannel`, `/channel`,
`/permission`, `/status`, `/workspacePaths`, `/bridgeErrors`,
`/bridgeTypes`, `/bridgeOptions`, `/spawnChannel`, `/bridgeClient`,
`/bridge`, `/bridgeFileSystem`). They re-export the same symbols, so
either form resolves to the same module at runtime. Pick by intent:
`/permission`). They re-export the same symbols, so either form
resolves to the same module at runtime. Pick by intent:
- **Root** for application/test code that uses several primitives at
once — concise and matches how `serve/` imports landed today.
@ -109,7 +85,7 @@ either form resolves to the same module at runtime. Pick by intent:
`remoteControl`) that only consume one slice — keeps the
dependency surface explicit and lets bundlers tree-shake the rest.
Both variants are stable across the F1 lift.
Both variants are stable. PR 22b will not change either set.
## Backward compatibility
@ -119,20 +95,13 @@ re-export wrappers, so every existing relative import inside
`serve/` and the one external import in `cli/src/commands/serve.ts`
keeps resolving without churn.
After F1, `packages/cli/src/serve/httpAcpBridge.ts` shrinks to a
~97-line re-export shim that forwards every previously-exported
symbol (`createHttpAcpBridge`, `defaultSpawnChannelFactory`,
`BridgeClient`, all the typed errors, all the type aliases) from
the lifted subpaths. Every relative `./httpAcpBridge.js` import in
`server.ts` / `runQwenServe.ts` / `workspaceAgents.ts` /
`workspaceMemory.ts` / `index.ts` / the bridge test suite keeps
resolving without any call-site changes.
`httpAcpBridge.ts` continues to export `AcpChannel` /
`AcpChannelExitInfo` / `ChannelFactory` (now via re-export from this
package) so any external consumer of those types is unaffected.
## See also
- #4175 Mode B daemon roadmap (feature-cohesive F1-F5 plan targeting
`daemon_mode_b_main`)
- #4175 Wave 5 PR 22 row
- #3803 `Stage 1.5-prereq AcpChannel lift` (chiga0's original framing)
- F3 PR 24 will replace the inline first-responder logic in
`BridgeClient.requestPermission` with the four `PermissionMediator`
strategies declared in `permission.ts`.
- `httpAcpBridge.ts:1096-1106` (FIXME pointing at the four
`PermissionMediator` strategies this package now declares)

View File

@ -1,7 +1,7 @@
{
"name": "@qwen-code/acp-bridge",
"version": "0.16.1",
"description": "Shared ACP bridge core (createHttpAcpBridge factory, BridgeClient, defaultSpawnChannelFactory, BridgeFileSystem injection seam) + primitives (EventBus, AcpChannel, in-memory channel, PermissionMediator interface) used by qwen serve, channels, IDE, TUI, and remote-control adapters.",
"version": "0.17.0",
"description": "Shared ACP bridge primitives (EventBus, AcpChannel, in-memory channel, PermissionMediator interface) used by qwen serve, channels, IDE, TUI, and remote-control adapters.",
"repository": {
"type": "git",
"url": "git+https://github.com/QwenLM/qwen-code.git",
@ -51,30 +51,6 @@
"types": "./dist/bridgeOptions.d.ts",
"import": "./dist/bridgeOptions.js"
},
"./spawnChannel": {
"types": "./dist/spawnChannel.d.ts",
"import": "./dist/spawnChannel.js"
},
"./bridgeClient": {
"types": "./dist/bridgeClient.d.ts",
"import": "./dist/bridgeClient.js"
},
"./bridge": {
"types": "./dist/bridge.d.ts",
"import": "./dist/bridge.js"
},
"./bridgeFileSystem": {
"types": "./dist/bridgeFileSystem.d.ts",
"import": "./dist/bridgeFileSystem.js"
},
"./mcpTimeouts": {
"types": "./dist/mcpTimeouts.d.ts",
"import": "./dist/mcpTimeouts.js"
},
"./internal/testUtils": {
"types": "./dist/internal/testUtils.d.ts",
"import": "./dist/internal/testUtils.js"
},
"./package.json": "./package.json"
},
"scripts": {
@ -86,9 +62,7 @@
"typecheck": "tsc --noEmit"
},
"files": [
"dist",
"!dist/internal/testUtils.*",
"!dist/**/*.test.*"
"dist"
],
"dependencies": {
"@agentclientprotocol/sdk": "^0.14.1",

View File

@ -1,446 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
/**
* Unit tests for the `BridgeFileSystem` injection seam introduced in
* #4175 PR F1 step 5. The wider 174-test `httpAcpBridge.test.ts` suite
* exercises BridgeClient end-to-end via the lifted factory, but none
* of those tests wire `fileSystem` — they all exercise the inline
* `fs.writeFile` / `fs.readFile` proxy. These tests close that gap
* (wenshao #4319 Critical fold-in): they directly assert that
*
* 1. when `fileSystem` is provided, both `writeTextFile` and
* `readTextFile` delegate every call to it (and the inline
* proxy is fully bypassed — no `fs.writeFile` syscall);
* 2. when `fileSystem` is omitted, the inline proxy runs and
* reads / writes real disk (sanity check that the fallback
* path the 7-arg constructor's positional slot opt-outs to
* still works).
*
* Regression guard: the constructor takes 7 positional args; the
* 7th (`fileSystem`) is optional and at the tail. A subtle re-
* ordering (or dropping the arg from `bridge.ts:773` factory's
* `new BridgeClient(..., opts.fileSystem)` call) would silently
* bypass the adapter in production. Test #1 + #2 catch that
* because the mock fileSystem would never be called.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { promises as fsp } from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import type {
ReadTextFileRequest,
ReadTextFileResponse,
WriteTextFileRequest,
WriteTextFileResponse,
} from '@agentclientprotocol/sdk';
import { BridgeClient } from './bridgeClient.js';
import type { BridgeFileSystem } from './bridgeFileSystem.js';
import { CancelSentinelCollisionError } from './bridgeErrors.js';
import { CANCEL_VOTE_SENTINEL } from './permissionMediator.js';
/**
* Minimal-stub constructor for a `BridgeClient` whose only purpose is
* to exercise `writeTextFile` / `readTextFile`. The 5 callback args
* before `fileSystem` are filled with thrower-defaults so any test
* that accidentally hits the permission path (instead of the fs path)
* fails loudly instead of silently. F3 Commit 3 replaced the pre-F3
* `registerPending` + `rollbackPending` callbacks with a single
* `MultiClientPermissionMediator` reference; the test stub provides
* a thrower-Mediator that fails any unexpected `request()` /
* `vote()` / `forgetSession()` call.
*/
function makeClient(fileSystem?: BridgeFileSystem): BridgeClient {
const noPermissionFlow = () => {
throw new Error('test: permission flow should not run in fs-path tests');
};
// Wenshao review #4335 / 3272581569 — `BridgeClient.mediator` is
// narrowed to `Pick<PermissionMediator, 'request'>`, so the
// thrower stub only needs to provide `request`. Eliminates the
// 5 unused-method placeholders the pre-narrowing version
// required (policy/vote/forgetSession/peekSessionFor/pendingCount).
const throwerMediator = { request: noPermissionFlow } as never;
return new BridgeClient(
noPermissionFlow as never, // resolveEntry
noPermissionFlow as never, // resolvePendingRestoreEvents
throwerMediator, // mediator (F3 Commit 3)
0, // permissionTimeoutMs (disabled)
Infinity, // maxPendingPerSession (disabled)
fileSystem,
);
}
describe('BridgeClient — BridgeFileSystem injection seam (F1 step 5)', () => {
describe('writeTextFile', () => {
it('delegates to the injected fileSystem.writeText, bypassing the inline fs proxy', async () => {
const writeText = vi
.fn<(p: WriteTextFileRequest) => Promise<WriteTextFileResponse>>()
.mockResolvedValue({});
const readText =
vi.fn<(p: ReadTextFileRequest) => Promise<ReadTextFileResponse>>();
const fakeFs: BridgeFileSystem = { writeText, readText };
const client = makeClient(fakeFs);
const params: WriteTextFileRequest = {
path: '/this/path/never/touches/disk',
content: 'injected-content',
sessionId: 'sess:test',
};
const response = await client.writeTextFile(params);
expect(response).toEqual({});
expect(writeText).toHaveBeenCalledTimes(1);
expect(writeText).toHaveBeenCalledWith(params);
expect(readText).not.toHaveBeenCalled();
});
it('does NOT touch real fs when delegating — the mock is invoked without any disk touch', async () => {
const writeText = vi
.fn<(p: WriteTextFileRequest) => Promise<WriteTextFileResponse>>()
.mockResolvedValue({});
const fakeFs: BridgeFileSystem = {
writeText,
readText: vi.fn(),
};
const client = makeClient(fakeFs);
// A path no real disk would ever resolve to. Delegation skips
// realpath / writeFile entirely, so the call succeeds purely
// on the mock's resolve. Cross-platform-safe (avoiding `/proc/`
// because macOS / Windows would treat that path differently
// than Linux — the inline proxy's dangling-symlink fallback
// would write through there on macOS).
await client.writeTextFile({
path: '/this/dir/never/exists/file.txt',
content: '',
sessionId: 'sess:test',
});
expect(writeText).toHaveBeenCalled();
});
});
describe('readTextFile', () => {
it('delegates to the injected fileSystem.readText, bypassing the inline fs proxy', async () => {
const writeText =
vi.fn<(p: WriteTextFileRequest) => Promise<WriteTextFileResponse>>();
const readText = vi
.fn<(p: ReadTextFileRequest) => Promise<ReadTextFileResponse>>()
.mockResolvedValue({ content: 'injected-content' });
const fakeFs: BridgeFileSystem = { writeText, readText };
const client = makeClient(fakeFs);
const params: ReadTextFileRequest = {
path: '/this/path/never/touches/disk',
sessionId: 'sess:test',
};
const response = await client.readTextFile(params);
expect(response).toEqual({ content: 'injected-content' });
expect(readText).toHaveBeenCalledTimes(1);
expect(readText).toHaveBeenCalledWith(params);
expect(writeText).not.toHaveBeenCalled();
});
it('propagates fileSystem.readText errors to the caller', async () => {
const readText = vi.fn(async (): Promise<ReadTextFileResponse> => {
throw new Error('adapter-rejected');
});
const client = makeClient({ writeText: vi.fn(), readText });
await expect(
client.readTextFile({ path: '/x', sessionId: 'sess:test' }),
).rejects.toThrow('adapter-rejected');
});
});
describe('FsError preservation over ACP wire (#4175 F4 prereq, Codex #4360 round 2)', () => {
// The fix scope: when `BridgeFileSystem.writeText` /
// `BridgeFileSystem.readText` throw a structured `FsError`, the
// BridgeClient must rethrow as ACP `RequestError` with `data.
// errorKind` / `data.hint` / `data.status` preserved. Pre-fix
// the ACP SDK serialized only `error.message` so SDK consumers
// lost the discriminator and had to regex-match the message.
//
// FsError lives in `cli/src/serve/fs/errors.ts` — acp-bridge can't
// import it (cross-package dep inversion), so we synthesize the
// shape directly here. The duck typing in
// `preserveFsErrorOverAcp` keys on `err.name === 'FsError'` +
// `typeof err.kind === 'string'`.
function makeFsError(
kind: string,
message: string,
extras: { hint?: string; status?: number } = {},
): Error {
const err = new Error(message);
err.name = 'FsError';
(err as unknown as { kind: string }).kind = kind;
if (extras.hint !== undefined) {
(err as unknown as { hint: string }).hint = extras.hint;
}
if (extras.status !== undefined) {
(err as unknown as { status: number }).status = extras.status;
}
return err;
}
it('writeTextFile rethrows FsError as ACP RequestError with errorKind in data', async () => {
const writeText = vi.fn(async (): Promise<WriteTextFileResponse> => {
throw makeFsError(
'untrusted_workspace',
'workspace is not trusted; write operations are forbidden',
{
status: 403,
hint: 'enable trust via createWorkspaceFileSystemFactory',
},
);
});
const client = makeClient({ writeText, readText: vi.fn() });
const err = (await client
.writeTextFile({
path: '/x',
content: 'y',
sessionId: 'sess:test',
})
.catch((e) => e)) as Error & { code?: number; data?: unknown };
// Reshaped as JSON-RPC RequestError (-32603 = internal error)
// with structured data field.
expect(err.name).toBe('RequestError');
expect(err.code).toBe(-32603);
expect(err.message).toContain('not trusted');
expect(err.data).toMatchObject({
errorKind: 'untrusted_workspace',
status: 403,
hint: expect.any(String),
});
});
it('readTextFile rethrows FsError preserving symlink_escape kind', async () => {
const readText = vi.fn(async (): Promise<ReadTextFileResponse> => {
throw makeFsError(
'symlink_escape',
'symlink resolves outside workspace',
{ status: 400 },
);
});
const client = makeClient({ writeText: vi.fn(), readText });
const err = (await client
.readTextFile({ path: '/x', sessionId: 'sess:test' })
.catch((e) => e)) as Error & { code?: number; data?: unknown };
expect(err.name).toBe('RequestError');
expect(err.code).toBe(-32603);
expect(err.data).toMatchObject({
errorKind: 'symlink_escape',
status: 400,
});
// No `hint` field on this FsError → not stamped (spread guard).
expect((err.data as { hint?: unknown }).hint).toBeUndefined();
});
it('passes non-FsError errors through unchanged (no RequestError wrap)', async () => {
// Plain Error → bridgeClient must NOT wrap it. Only structured
// FsError gets the reshape. ACP's default serialization is
// adequate for unstructured errors.
const writeText = vi.fn(async (): Promise<WriteTextFileResponse> => {
throw new Error('boring generic failure');
});
const client = makeClient({ writeText, readText: vi.fn() });
const err = (await client
.writeTextFile({
path: '/x',
content: 'y',
sessionId: 'sess:test',
})
.catch((e) => e)) as Error & { code?: number; data?: unknown };
// Original Error preserved — no JSON-RPC code stamped.
expect(err.name).toBe('Error');
expect(err.message).toBe('boring generic failure');
expect(err.code).toBeUndefined();
expect(err.data).toBeUndefined();
});
it('readTextFile passes non-FsError errors through unchanged (wenshao #4360 review)', async () => {
// Symmetric guard for the read-side `preserveFsErrorOverAcp`
// call. The write- and read-side catch blocks are independent
// try/catch wrappers in `bridgeClient.ts`; if a future refactor
// diverges them (e.g. adds Error-wrapping to one but not the
// other), this test catches the read-side regression.
const readText = vi.fn(async (): Promise<ReadTextFileResponse> => {
throw new Error('generic read failure');
});
const client = makeClient({ writeText: vi.fn(), readText });
const err = (await client
.readTextFile({ path: '/x', sessionId: 'sess:test' })
.catch((e) => e)) as Error & { code?: number; data?: unknown };
expect(err.name).toBe('Error');
expect(err.message).toBe('generic read failure');
expect(err.code).toBeUndefined();
expect(err.data).toBeUndefined();
});
it('preserves hint field when present on the FsError', async () => {
const writeText = vi.fn(async (): Promise<WriteTextFileResponse> => {
throw makeFsError(
'file_too_large',
'file of 6 MiB exceeds write cap of 5 MiB',
{ hint: 'split large writes into bounded chunks', status: 413 },
);
});
const client = makeClient({ writeText, readText: vi.fn() });
const err = (await client
.writeTextFile({
path: '/x',
content: 'y',
sessionId: 'sess:test',
})
.catch((e) => e)) as Error & { code?: number; data?: unknown };
expect((err.data as { hint?: string }).hint).toBe(
'split large writes into bounded chunks',
);
expect((err.data as { errorKind?: string }).errorKind).toBe(
'file_too_large',
);
});
it('does not wrap an error that LOOKS like FsError but has wrong name', async () => {
// Defensive: an unrelated error class with a `kind` field but
// a different `name` should fall through to the unstructured
// path. Prevents accidental wrapping of e.g. permission errors
// that happen to carry a `kind` discriminator.
const writeText = vi.fn(async (): Promise<WriteTextFileResponse> => {
const err = new Error('looks-similar');
err.name = 'PermissionForbiddenError';
(err as unknown as { kind: string }).kind =
'designated_originator_mismatch';
throw err;
});
const client = makeClient({ writeText, readText: vi.fn() });
const err = (await client
.writeTextFile({
path: '/x',
content: 'y',
sessionId: 'sess:test',
})
.catch((e) => e)) as Error & { code?: number };
expect(err.name).toBe('PermissionForbiddenError');
expect(err.code).toBeUndefined();
});
});
describe('inline fallback when fileSystem is omitted (regression guard)', () => {
let tmpDir: string;
beforeEach(async () => {
tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'bridgeclient-test-'));
});
afterEach(async () => {
await fsp.rm(tmpDir, { recursive: true, force: true });
});
it('writeTextFile actually writes to disk through the inline proxy', async () => {
const client = makeClient(/* no fileSystem */);
const target = path.join(tmpDir, 'inline.txt');
await client.writeTextFile({
path: target,
content: 'inline-content',
sessionId: 'sess:test',
});
const onDisk = await fsp.readFile(target, 'utf8');
expect(onDisk).toBe('inline-content');
});
it('readTextFile actually reads from disk through the inline proxy', async () => {
const client = makeClient(/* no fileSystem */);
const target = path.join(tmpDir, 'src.txt');
await fsp.writeFile(target, 'on-disk-content', 'utf8');
const response = await client.readTextFile({
path: target,
sessionId: 'sess:test',
});
expect(response.content).toBe('on-disk-content');
});
});
});
/**
* Wenshao review #4335 / 3271978365 — `requestPermission`'s pre-publish
* `CancelSentinelCollisionError` guard prevents an orphan SSE
* `permission_request` event from being emitted when an agent's
* `allowedOptionIds` legitimately contains '__cancelled__'. The
* mediator-level test (`permissionMediator.test.ts:330`) covers the
* issue-time collision detection inside `mediator.request`, but
* BridgeClient layers a separate pre-publish check whose distinct
* purpose — preventing orphan SSE frames — needs its own test.
*/
describe('BridgeClient — requestPermission pre-publish collision guard', () => {
it('throws CancelSentinelCollisionError BEFORE publishing on the events bus', async () => {
// Arrange: a fake session entry whose `events.publish` is a spy.
// If the collision check ran AFTER publish, this would record a
// call and the assertion below would fail.
const publish = vi.fn().mockReturnValue(true);
const fakeEntry = {
sessionId: 'sess:test',
pendingPermissionIds: new Set<string>(),
events: { publish },
activePromptOriginatorClientId: undefined,
};
const noPermissionFlow = () => {
throw new Error('test: not reachable on collision-throw path');
};
// Wenshao review #4335 / 3272581569 — narrowed mediator type
// means the stub only needs `request`.
const throwerMediator = { request: noPermissionFlow } as never;
const client = new BridgeClient(
((sid: string) => (sid === 'sess:test' ? fakeEntry : undefined)) as never,
noPermissionFlow as never,
throwerMediator,
0,
Infinity,
);
// Act + Assert: a sentinel-colliding option causes the bridge
// client to throw before reaching publish.
await expect(
client.requestPermission({
sessionId: 'sess:test',
toolCall: { toolCallId: 'tc-1', title: 'rm -rf /' },
options: [
{ optionId: 'allow', name: 'Allow', kind: 'allow_once' },
{
optionId: CANCEL_VOTE_SENTINEL,
name: 'Adversarial label',
kind: 'allow_once',
},
],
}),
).rejects.toThrow(CancelSentinelCollisionError);
// The crucial post-condition: no SSE frame went out.
expect(publish).not.toHaveBeenCalled();
// And the cap-index was never touched (only added AFTER publish).
expect(fakeEntry.pendingPermissionIds.size).toBe(0);
});
});

File diff suppressed because it is too large Load Diff

View File

@ -25,42 +25,6 @@
import { MAX_WORKSPACE_PATH_LENGTH } from './workspacePaths.js';
export const NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE =
'Not currently generating' as const;
/**
* ACP idle-cancel compatibility contract.
*
* The current CLI agent throws `NOT_CURRENTLY_GENERATING_CANCEL_MESSAGE`
* when a client sends `cancel` while no prompt is active. Older ACP
* surfaces may wrap that text in either `message` or `data.details`.
* Treat harmless wording extensions such as
* "Not currently generating (session idle)" as the same no-op cancel,
* but keep this matcher narrow so unrelated cancel failures still
* propagate to callers.
*/
export function isNotCurrentlyGeneratingCancelError(err: unknown): boolean {
if (err instanceof Error && isNotCurrentlyGeneratingText(err.message)) {
return true;
}
if (!err || typeof err !== 'object') return false;
const maybe = err as {
message?: unknown;
data?: unknown;
};
if (isNotCurrentlyGeneratingText(maybe.message)) return true;
if (!maybe.data || typeof maybe.data !== 'object') return false;
return isNotCurrentlyGeneratingText(
(maybe.data as { details?: unknown }).details,
);
}
function isNotCurrentlyGeneratingText(value: unknown): boolean {
return (
typeof value === 'string' && /\bnot currently generating\b/i.test(value)
);
}
export class SessionNotFoundError extends Error {
readonly sessionId: string;
constructor(sessionId: string, extra?: string) {
@ -207,97 +171,6 @@ export class InvalidSessionMetadataError extends Error {
}
}
/**
* #4175 F3. Thrown by `MultiClientPermissionMediator.vote` when the
* active policy is wired into the schema/registry but the mediator
* implementation has not been built yet.
*
* **Currently unreachable in production** — F3 Commit 4 implemented
* all 4 policies in the frozen `PermissionPolicy` union. The class +
* route-level 501 mapping in `server.ts:sendPermissionVoteError` are
* RETAINED as forward-compat infrastructure: when a future PR adds a
* 5th policy literal to `PermissionPolicy` and lands its mediator
* implementation across multiple commits, the intermediate-build
* stub can throw this typed error and the operator gets a clean 501
* instead of a generic 500.
*
* Routes map this to HTTP 501 with a structured body so SDK clients
* can render "your daemon is older than your settings expect;
* upgrade".
*/
export class PermissionPolicyNotImplementedError extends Error {
readonly policy: string;
constructor(policy: string) {
super(
`Permission policy "${policy}" is declared in the contract but ` +
'not yet implemented in this daemon build.',
);
this.name = 'PermissionPolicyNotImplementedError';
this.policy = policy;
}
}
/**
* #4175 F3 Commit 1. Thrown by `MultiClientPermissionMediator.request`
* when an agent-declared `allowedOptionIds` set contains the
* cancel-vote sentinel string. The bridge maps voter cancel intent
* to that exact `optionId`; if the agent legitimately uses it as
* an option label, the mediator can no longer disambiguate. We
* fail loudly at request issue time so the operator sees a clear
* misconfiguration rather than the silent "voter approval was
* treated as cancel" semantic flip.
*
* Routes map this to HTTP 500 — it represents a contract violation
* between agent and daemon, not a client mistake.
*/
export class CancelSentinelCollisionError extends Error {
readonly requestId: string;
readonly sentinel: string;
constructor(requestId: string, sentinel: string) {
super(
`Permission ${requestId}: agent-declared optionId set contains ` +
`the cancel-vote sentinel "${sentinel}", which would prevent ` +
'the daemon from disambiguating cancel intent from a real vote.',
);
this.name = 'CancelSentinelCollisionError';
this.requestId = requestId;
this.sentinel = sentinel;
}
}
/**
* #4175 F3 Commit 2. Thrown by `bridge.respondToSessionPermission` /
* `bridge.respondToPermission` when the active permission policy
* rejects the vote (designated voter mismatch, or remote vote under
* `local-only`). The bridge converts the mediator's
* `PermissionVoteOutcome { kind: 'forbidden', reason: ... }` into
* this typed error so the route layer can map to HTTP 403 without
* pattern-matching on the error message.
*
* `reason` is forwarded verbatim from the mediator's outcome so SDK
* clients can render a precise UI ("you weren't designated to
* approve" vs "this daemon only accepts loopback approvals").
*/
export class PermissionForbiddenError extends Error {
readonly requestId: string;
readonly sessionId: string;
readonly reason: 'designated_mismatch' | 'remote_not_allowed';
constructor(
requestId: string,
sessionId: string,
reason: 'designated_mismatch' | 'remote_not_allowed',
) {
super(
`Permission ${requestId} on session ${sessionId}: ` +
`vote rejected by policy (${reason}).`,
);
this.name = 'PermissionForbiddenError';
this.requestId = requestId;
this.sessionId = sessionId;
this.reason = reason;
}
}
/**
* #4175 Wave 4 PR 17. Thrown by `initWorkspace` when the target file
* already exists with non-whitespace content and the caller did not
@ -320,78 +193,6 @@ export class WorkspaceInitConflictError extends Error {
}
}
/**
* #4297 fold-in 1 (16:32:44-round S1). Thrown by `initWorkspace` when
* the configured `context.fileName` resolves outside the bound
* workspace via path arithmetic (e.g. `../outside.md`). Translated
* to HTTP 400 by the route — distinguishable from a generic 500 so
* an operator sees "your workspace config is wrong" rather than
* "the daemon is broken." The `filename` and `boundWorkspace`
* fields let clients display a precise diagnostic.
*/
export class WorkspaceInitPathEscapeError extends Error {
readonly filename: string;
readonly boundWorkspace: string;
constructor(filename: string, boundWorkspace: string) {
super(
`Configured workspace context filename ${JSON.stringify(filename)} ` +
`resolves outside the bound workspace ${JSON.stringify(boundWorkspace)}. ` +
`Refusing to write.`,
);
this.name = 'WorkspaceInitPathEscapeError';
this.filename = filename;
this.boundWorkspace = boundWorkspace;
}
}
/**
* #4297 fold-in 1 (16:32:44-round S1). Thrown by `initWorkspace` when
* the target file is itself a symlink, OR when the parent path
* canonicalizes (via `realpath`) outside the bound workspace.
* Translated to HTTP 400 by the route — same operator-clarity
* rationale as `WorkspaceInitPathEscapeError`. `target` is the
* resolved path the bridge attempted, `kind` distinguishes the two
* symlink scenarios for diagnostics.
*/
export class WorkspaceInitSymlinkError extends Error {
readonly target: string;
readonly kind: 'target' | 'parent';
constructor(target: string, kind: 'target' | 'parent', detail: string) {
super(detail);
this.name = 'WorkspaceInitSymlinkError';
this.target = target;
this.kind = kind;
}
}
/**
* #4297 fold-in 10 (qwen-latest, addresses #3263954690). Thrown by
* `initWorkspace` when the target file's inode misbehaved at write
* time IN A NON-SYMLINK WAY — typically a TOCTOU race against a
* concurrent writer:
* - `'eexist'`: a regular file (or symlink) appeared at the target
* path between the absence check and our atomic `'wx'` create.
* - `'enoent'`: the target was deleted between the content check
* and the `O_NOFOLLOW` overwrite (concurrent git checkout, editor
* save, etc.).
*
* Split out from `WorkspaceInitSymlinkError` so the HTTP error code
* isn't misleading: an operator chasing a `workspace_init_race`
* code knows it's a benign concurrent-modification window, not a
* symlink attack vector. Same 400 mapping as the sibling class —
* the route layer still recognizes both.
*/
export class WorkspaceInitRaceError extends Error {
readonly target: string;
readonly kind: 'eexist' | 'enoent';
constructor(target: string, kind: 'eexist' | 'enoent', detail: string) {
super(detail);
this.name = 'WorkspaceInitRaceError';
this.target = target;
this.kind = kind;
}
}
/**
* #4282 fold-in 1 (gpt-5.5 C5). Thrown by `restartMcpServer` when the
* caller asks for a server name that isn't in the daemon's

View File

@ -1,97 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
import type {
ReadTextFileRequest,
ReadTextFileResponse,
WriteTextFileRequest,
WriteTextFileResponse,
} from '@agentclientprotocol/sdk';
/**
* Injection seam for the ACP fs proxy on `BridgeClient.readTextFile` /
* `BridgeClient.writeTextFile`. The immediate follow-up PR will land
* a serve-side adapter that wraps PR 18's `WorkspaceFileSystem` so
* production `qwen serve` writes pick up the TOCTOU + symlink +
* trust-gate + audit machinery PR 18 introduced — closing the
* post-PR-18 follow-up thread about `BridgeClient`'s inline fs
* proxy bypassing `WorkspaceFileSystem` (originally raised in
* #4250 review; see also FIXME(stage-1.5, chiga0 finding 4) lifted
* to this package as part of #4175 F1). Until that adapter ships and `runQwenServe` wires it
* through `BridgeOptions.fileSystem`, BridgeClient continues to use
* its inline fs proxy (preserving pre-F1 behavior).
*
* Lifted from the inline `fs.writeFile` / `fs.readFile` implementations
* BridgeClient carried before #4175 PR F1 (step 5, originally the
* 22b' scope). Bridge tests + Mode A embedded callers can omit the
* field on `BridgeOptions`; BridgeClient falls back to its inline
* proxy so the pre-lift behavior is preserved verbatim when no
* provider is injected.
*
* Method signatures intentionally mirror the ACP SDK request/response
* shapes so the adapter does the minimum amount of translation
* (`{ path, content }` ↔ `WorkspaceFileSystem`'s `ResolvedPath` brand
* types + options bag).
*/
export interface BridgeFileSystem {
/**
* Read a UTF-8 text file. Honors ACP's `line` / `limit` window
* semantics (1-based line, inclusive limit). The adapter is
* expected to surface boundary / trust / encoding errors as
* thrown JS errors — the bridge's existing error-mapping path
* (`mapDomainErrorToErrorKind`) will classify them downstream.
*
* Adapter MUST replicate the inline proxy's two defensive
* gates (the inline path is fully bypassed when a fileSystem is
* injected):
* 1. Reject non-regular files (sockets / pipes / char devices
* / procfs / sysfs entries can produce unbounded data on
* read despite reporting `stats.size === 0`). Inline path
* throws with `describeStatKind(stats)` in the message.
* 2. Cap the buffered size (the inline path uses
* `READ_FILE_SIZE_CAP = 100 MiB` to defend against a small
* `{ line: 1, limit: 10 }` request against a 500 MB log
* from costing 500 MB of RSS just to return 10 lines).
*/
readText(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
/**
* Atomically replace `params.path` with `params.content`. Returns
* the ACP-shaped empty response on success; throws an `FsError`
* (classified downstream by `mapDomainErrorToErrorKind`) on
* boundary, trust, or I/O failure.
*
* Adapter MUST provide:
* - **Write-then-rename atomicity** — a SIGKILL / OOM mid-write
* does NOT leave the target truncated.
* - **Target mode preservation** — editing a `0o600` secret
* keeps it at `0o600`; an executable `+x` bit is retained.
* - **`0o600` default for new files** — NOT umask defaults (the
* write syscall's `mode` arg bypasses umask). This is the
* security posture for agent-driven writes where the agent's
* intent about the file's audience is unknown.
* - **Symlink rejection** — paths whose target is a symlink
* surface `symlink_escape`. This is a **divergence from the
* pre-F1 inline `BridgeClient.writeTextFile` proxy** which
* resolved symlinks and wrote through to their target;
* production now matches the more conservative PR 18 +
* HTTP `POST /file` posture (PR 20). Agents that previously
* relied on writing through symlinked dotfiles will need
* to address the resolved path directly.
* - **Workspace boundary enforcement** — paths outside the
* bound workspace surface `path_outside_workspace`.
*
* Owner/group preservation is best-effort and platform-dependent
* (POSIX `chown` requires root for cross-user changes; Windows
* lacks the concept entirely). The contract does NOT require it.
*
* The serve-side adapter satisfies this via
* `WorkspaceFileSystem.writeTextOverwrite` — the PR 18 primitive
* that does atomic tmp+rename with mode preservation + `0o600`
* default + symlink reject inside a per-path lock.
*/
writeText(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
}

View File

@ -13,22 +13,7 @@
import type { ApprovalMode } from '@qwen-code/qwen-code-core';
import type { ChannelFactory } from './channel.js';
import type { PermissionPolicy } from './permission.js';
import type { PermissionAuditPublisher } from './permissionMediator.js';
import type { ServePreflightCell, ServeWorkspaceEnvStatus } from './status.js';
import type { BridgeFileSystem } from './bridgeFileSystem.js';
/**
* Sink for serve-level diagnostic lines (set by the cli daemon logger).
* When provided, the bridge tees `writeServeDebugLine` output through
* this callback alongside the existing stderr write — used by
* runQwenServe to capture them in the daemon log file. The bridge
* does not own a file logger itself; this is a pure pass-through hook.
*/
export type DiagnosticLineSink = (
line: string,
level?: 'info' | 'warn' | 'error',
) => void;
/**
* Optional injection seam for daemon-host-specific status cells —
@ -92,25 +77,8 @@ export interface DaemonStatusProvider {
): Promise<ServePreflightCell[]>;
}
export type BridgeTelemetryAttributes = Record<
string,
string | number | boolean
>;
export interface BridgeTelemetry {
captureContext(): unknown;
runWithContext<T>(captured: unknown, fn: () => Promise<T>): Promise<T>;
withSpan<T>(
operation: string,
attributes: BridgeTelemetryAttributes,
fn: () => Promise<T>,
): Promise<T>;
event(name: string, attributes: BridgeTelemetryAttributes): void;
injectPromptContext<T extends object>(request: T): T;
}
/**
* Construction options for `createAcpSessionBridge`. Most fields are
* Construction options for `createHttpAcpBridge`. Most fields are
* tuning knobs with sensible defaults; `boundWorkspace` is the only
* strictly-required field. See per-field JSDoc for caller contract.
*/
@ -190,7 +158,7 @@ export interface BridgeOptions {
* theoretically diverge from the runQwenServe canonicalize on
* NFS-transient / mid-rename filesystems, landing the bridge with
* one canonical form while `/capabilities` advertises another).
* Direct embeds / tests calling `createAcpSessionBridge` themselves
* Direct embeds / tests calling `createHttpAcpBridge` themselves
* MUST canonicalize before passing.
*/
boundWorkspace: string;
@ -231,6 +199,23 @@ export interface BridgeOptions {
boundWorkspace: string,
mode: ApprovalMode,
) => Promise<void>;
/**
* #4175 Wave 4 PR 17 — optional callback for mutating
* `tools.disabled` in workspace settings. Invoked by
* `setWorkspaceToolEnabled` to add (`enabled: false`) or remove
* (`enabled: true`) `toolName` from the persisted disabled set.
* The default `runQwenServe` wires this to a fresh
* `loadSettings(boundWorkspace)` per call so concurrent edits from
* other writers (CLI, another daemon, an editor) are picked up.
* Bridge tests / embedded callers may omit it; without the hook
* `setWorkspaceToolEnabled` throws a clear error rather than
* silently dropping the write.
*/
persistDisabledTools?: (
boundWorkspace: string,
toolName: string,
enabled: boolean,
) => Promise<void>;
/**
* #4175 Wave 5 PR 22b/2 — optional injection seam for daemon-host
* status cells (env snapshot, daemon preflight). Production
@ -254,77 +239,4 @@ export interface BridgeOptions {
* still query the routes; they'll see empty/idle cells.
*/
statusProvider?: DaemonStatusProvider;
/** Optional daemon telemetry seam. Omitted callers get no-op spans/logs. */
telemetry?: BridgeTelemetry;
/**
* Optional fs injection seam (#4175 PR F1 step 5, originally the
* 22b' scope). When provided, `BridgeClient.readTextFile` and
* `BridgeClient.writeTextFile` delegate every ACP fs call to this
* implementation instead of using BridgeClient's inline
* `fs.realpath` / `fs.writeFile` / `fs.readFile` proxy.
*
* The immediate F1 follow-up will land a serve-side adapter that
* wraps PR 18's `WorkspaceFileSystem` and a `runQwenServe` wiring
* patch so production `qwen serve` writes pick up its TOCTOU +
* symlink-substitution + trust-gate + `.gitignore` + audit
* machinery — closing the post-PR-18 follow-up thread about
* `BridgeClient`'s inline fs proxy bypassing `WorkspaceFileSystem`
* (originally raised in #4250 review). Until that lands, BridgeClient's inline
* proxy continues to handle writes (current behavior preserved).
*
* When omitted (tests, Mode A in-process consumers, channels /
* IDE companion using the bridge directly), BridgeClient's inline
* proxy is used — preserves the pre-F1 behavior verbatim so
* existing test fixtures don't need updating and channels /
* IDE keep working without depending on `cli/src/serve/fs/`.
*/
fileSystem?: BridgeFileSystem;
/**
* #4175 F3 Commit 2 — active permission mediation policy for the
* `MultiClientPermissionMediator`. When omitted, defaults to
* `'first-responder'` (the pre-F3 behavior — any validated voter
* wins immediately). The bridge captures this once at construction
* time; `runQwenServe` reads it from `settings.policy.
* permissionStrategy` and the mediator snapshots it onto every
* pending entry at issue time so live-reload of settings does not
* change the rules under in-flight requests.
*/
permissionPolicy?: PermissionPolicy;
/**
* #4175 F3 Commit 2 — optional fixed quorum for `consensus` policy.
* MUST be a positive integer if provided; the F3 settings layer
* validates this and fails startup on non-integer / non-positive
* values. Capped at `M = votersAtIssue.size` at request time to
* prevent unreachable quorum. Unset → `floor(M/2) + 1` (default
* majority).
*/
permissionConsensusQuorum?: number;
/**
* #4175 F3 Commit 2 — injection seam for the permission audit
* publisher.
*
* **When omitted**: the bridge falls back to
* `createNoOpPermissionAuditPublisher` so embedded callers (and
* the bridge unit-test suite) can run the mediator without an
* audit consumer.
*
* **In production** (`qwen serve`), `runQwenServe.ts` allocates a
* `PermissionAuditRing` (default capacity 512), wraps it with
* `createPermissionAuditPublisher`, and passes the result here.
* The ring stays alive for the lifetime of the daemon so a future
* `GET /workspace/permission/audit` route (out of F3 v1 scope)
* can lift it out for query.
*
* Permission timeouts also produce a stderr breadcrumb directly
* from the mediator's timer callback (independent of this
* publisher) so operators tailing daemon stderr always see
* timeouts even when the audit publisher is the no-op fallback.
*/
permissionAudit?: PermissionAuditPublisher;
/**
* Optional: tee `writeServeDebugLine` output. See {@link DiagnosticLineSink}.
* No-op when omitted. Set by cli `runQwenServe` from the daemon logger.
*/
onDiagnosticLine?: DiagnosticLineSink;
}

View File

@ -16,14 +16,14 @@ import type {
SetSessionModelResponse,
} from '@agentclientprotocol/sdk';
import type { BridgeEvent, SubscribeOptions } from './eventBus.js';
import type { PermissionPolicy } from './permission.js';
import type {
ServeSessionContextStatus,
ServeSessionSupportedCommandsStatus,
ServeSessionTasksStatus,
ServeWorkspaceMcpToolsStatus,
ServeWorkspaceToolsStatus,
ServeSessionContextUsageStatus,
ServeWorkspaceEnvStatus,
ServeWorkspaceMcpStatus,
ServeWorkspacePreflightStatus,
ServeWorkspaceProvidersStatus,
ServeWorkspaceSkillsStatus,
} from './status.js';
export interface BridgeSpawnRequest {
@ -81,8 +81,6 @@ export interface BridgeSessionSummary {
sessionId: string;
workspaceCwd: string;
createdAt: string;
updatedAt?: string;
title?: string;
displayName?: string;
clientCount: number;
hasActivePrompt: boolean;
@ -95,25 +93,6 @@ export interface SessionMetadataUpdate {
export interface BridgeClientRequestContext {
/** Daemon-issued client id echoed through the HTTP transport header. */
clientId?: string;
/**
* `true` when the request arrived from a loopback peer (kernel-stamped
* `req.socket.remoteAddress` ∈ {`127.0.0.1`, `::1`, `::ffff:127.0.0.1`}).
* Populated by permission-vote routes for the `local-only` mediation
* policy; other routes leave this undefined.
*
* **Security**: this is NOT computed from `X-Forwarded-For` or any
* other forwardable HTTP header — those are forgeable. Callers that
* reverse-proxy `qwen serve` should not rely on `local-only` (use a
* dedicated daemon or `designated` policy instead).
*/
fromLoopback?: boolean;
/**
* Caller-generated correlation id for non-blocking prompt mode.
* When present, the bridge stamps `turn_complete` / `turn_error` events
* with this id so the SDK's `prompt()` can match the SSE event to the
* pending HTTP 202 request.
*/
promptId?: string;
}
/**
@ -141,7 +120,7 @@ export interface BridgeHeartbeatState {
clientLastSeenAt: ReadonlyMap<string, number>;
}
export interface AcpSessionBridge {
export interface HttpAcpBridge {
/**
* Create a new session, or — under `sessionScope: 'single'` — attach to an
* existing session for the same workspace.
@ -195,13 +174,6 @@ export interface AcpSessionBridge {
opts?: SubscribeOptions,
): AsyncIterable<BridgeEvent>;
/**
* Return the most recent monotonic event id for this session's bus.
* Used by non-blocking prompt responses to tell the client where to
* start SSE replay so no events are missed.
*/
getSessionLastEventId(sessionId: string): number;
/**
* Explicitly close a live session. Force-closes even when other clients
* are attached. Throws `SessionNotFoundError` for unknown ids.
@ -276,57 +248,44 @@ export interface AcpSessionBridge {
knownClientIds(): ReadonlySet<string>;
/**
* Generic workspace-status query delegated through the live ACP channel.
* Returns `idle()` when no child is running. Used by DaemonWorkspaceService
* to forward status methods without coupling to their concrete shapes.
* Read daemon-runtime MCP status for the bound workspace. Does not spawn
* an ACP child when the daemon is idle.
*/
queryWorkspaceStatus<T>(method: string, idle: () => T): Promise<T>;
getWorkspaceMcpStatus(): Promise<ServeWorkspaceMcpStatus>;
/**
* Generic workspace command invocation delegated through the live ACP
* channel. Throws `SessionNotFoundError` when no child is running (no
* idle fallback). Used by DaemonWorkspaceService for mutations that
* require an active channel (e.g. MCP restart).
* Read daemon-runtime skill status for the bound workspace.
*/
invokeWorkspaceCommand<T>(
method: string,
params?: Record<string, unknown>,
opts?: { timeoutMs?: number },
): Promise<T>;
getWorkspaceSkillsStatus(): Promise<ServeWorkspaceSkillsStatus>;
/**
* Read discovered MCP tools for one server from the live ACP registry.
* (New in upstream — kept in bridge pending workspace service migration.)
* Read daemon-runtime model-provider status for the bound workspace.
*/
getWorkspaceMcpToolsStatus(
serverName: string,
): Promise<ServeWorkspaceMcpToolsStatus>;
getWorkspaceProvidersStatus(): Promise<ServeWorkspaceProvidersStatus>;
/**
* Read the live built-in tool registry for the bound workspace.
* (New in upstream — kept in bridge pending workspace service migration.)
* Read the daemon-process environment snapshot for the bound workspace.
* Answered entirely from `process.*` state — does not consult ACP.
*/
getWorkspaceToolsStatus(): Promise<ServeWorkspaceToolsStatus>;
getWorkspaceEnvStatus(): Promise<ServeWorkspaceEnvStatus>;
/**
* Read daemon-runtime preflight diagnostics. Daemon-level cells are
* always populated; ACP-level cells require a live ACP child — when
* the daemon is idle they are emitted with `status: 'not_started'`.
*/
getWorkspacePreflightStatus(): Promise<ServeWorkspacePreflightStatus>;
/** Read the current ACP context/config state for a live session. */
getSessionContextStatus(
sessionId: string,
): Promise<ServeSessionContextStatus>;
/** Read structured context-window usage for a live session. */
getSessionContextUsageStatus(
sessionId: string,
opts?: { detail?: boolean },
): Promise<ServeSessionContextUsageStatus>;
/** Read slash-command/skill command availability for a live session. */
getSessionSupportedCommandsStatus(
sessionId: string,
): Promise<ServeSessionSupportedCommandsStatus>;
/** Read the live background task snapshot for a live session. */
getSessionTasksStatus(sessionId: string): Promise<ServeSessionTasksStatus>;
/**
* Switch the active model service for a session. Throws
* `SessionNotFoundError` for unknown ids.
@ -355,94 +314,46 @@ export interface AcpSessionBridge {
}>;
/**
* Generate a one-sentence "where did I leave off" recap of a live
* session. Forwards through `qwen/control/session/recap`, which
* invokes `generateSessionRecap` (`core/services/sessionRecap.ts`) in
* the ACP child against the per-session chat history.
*
* Best-effort: the helper returns `null` when history is too short or
* the underlying side-query fails — both surface as a 200 response
* with `recap: null`. Hard errors (unknown session, ACP transport
* down) throw as usual.
* Add or remove a tool name from the workspace's `tools.disabled`
* settings list and fan-out a `tool_toggled` event to every live
* session SSE bus.
*/
generateSessionRecap(
sessionId: string,
context?: BridgeClientRequestContext,
): Promise<{ sessionId: string; recap: string | null }>;
setWorkspaceToolEnabled(
toolName: string,
enabled: boolean,
originatorClientId: string | undefined,
): Promise<{ toolName: string; enabled: boolean }>;
/**
* Run a side question (/btw) against the session's conversation context.
* Uses runForkedAgent (cache path) for a single-turn, tool-free LLM call.
* Returns `answer: null` on empty/failed generation.
* Scaffold an empty `QWEN.md` (or whatever
* `getCurrentGeminiMdFilename()` returns) at the bound workspace
* root. Default refuses to overwrite via
* `WorkspaceInitConflictError`; `opts.force === true` overwrites.
*/
generateSessionBtw(
sessionId: string,
question: string,
signal?: AbortSignal,
context?: BridgeClientRequestContext,
): Promise<{ sessionId: string; answer: string | null }>;
initWorkspace(
opts: { force?: boolean },
originatorClientId: string | undefined,
): Promise<{
path: string;
action: 'created' | 'overwrote' | 'noop';
}>;
/**
* Execute a shell command directly on the daemon (no LLM involvement).
* Streams output through the session's SSE bus and injects the
* command+result into the LLM's chat history via extMethod.
* Throws `SessionNotFoundError` for unknown ids.
* Restart a configured MCP server through the ACP child's
* `McpClientManager`. Pre-checks the live budget snapshot and
* returns a structured "skipped" response (200 OK) for soft refusals.
*/
executeShellCommand(
sessionId: string,
command: string,
signal?: AbortSignal,
context?: BridgeClientRequestContext,
): Promise<ShellCommandResult>;
/**
* T2.8 (#4514): Add a runtime MCP server through the ACP child's
* `McpClientManager.addRuntimeMcpServer`. On success, broadcasts an
* `mcp_server_added` event to every session bus. Soft-refuse
* (`budget_warning_only` skip) does NOT emit an event — the caller
* receives the skip shape and decides locally.
*
* Throws `SessionNotFoundError` when no ACP channel is live (caller
* should spawn or attach first). Typed ACP errors (budget-exceeded,
* spawn-failed, invalid-config) are re-instantiated from the
* JSON-RPC `data.errorKind` so the route's `sendBridgeError` can
* map them to stable HTTP status codes.
*/
addRuntimeMcpServer(
name: string,
config: Record<string, unknown>,
originatorClientId: string,
restartMcpServer(
serverName: string,
originatorClientId: string | undefined,
): Promise<
| { serverName: string; restarted: true; durationMs: number }
| {
name: string;
transport: string;
replaced: boolean;
shadowedSettings: boolean;
toolCount: number;
originatorClientId: string;
serverName: string;
restarted: false;
skipped: true;
reason: 'in_flight' | 'disabled' | 'budget_would_exceed';
}
| { name: string; skipped: true; reason: 'budget_warning_only' }
>;
/**
* T2.8 (#4514): Remove a runtime MCP server through the ACP child's
* `McpClientManager.removeRuntimeMcpServer`. On success, broadcasts
* an `mcp_server_removed` event. Idempotent skip (`not_present`)
* does NOT emit — the caller receives the skip shape.
*
* Throws `SessionNotFoundError` when no ACP channel is live.
*/
removeRuntimeMcpServer(
name: string,
originatorClientId: string,
): Promise<
| {
name: string;
removed: true;
wasShadowingSettings: boolean;
originatorClientId: string;
}
| { name: string; skipped: true; reason: 'not_present' }
>;
/**
@ -467,32 +378,9 @@ export interface AcpSessionBridge {
/** Test/inspection hook: number of live sessions. */
readonly sessionCount: number;
/**
* Whether an ACP channel is currently live (spawned and not dying).
* Distinct from `sessionCount > 0`: a channel can be live with zero
* attached sessions during the cold-spawn window, and conversely a
* killed channel may briefly retain sessions before reaping. Consumers
* that need true channel liveness (e.g. the workspace service's
* `acpChannelLive` envelope field) must use this rather than the
* session count.
*/
isChannelLive(): boolean;
/** Test/inspection hook: number of permission requests awaiting a vote. */
readonly pendingPermissionCount: number;
/**
* #4175 F3 Commit 6 — active permission mediation policy. Reflects
* the value `runQwenServe` resolved from
* `settings.policy.permissionStrategy` (or the
* `'first-responder'` default). Surfaced through the
* `/capabilities` envelope's `policy.permission` field so SDK
* clients can feature-detect at runtime which strategy is in
* effect, distinct from the build-supported set advertised on
* the `permission_mediation` capability tag.
*/
readonly permissionPolicy: PermissionPolicy;
/**
* Synchronous force-kill of every live channel. Called by signal
* handlers when the operator double-taps Ctrl+C.
@ -502,12 +390,3 @@ export interface AcpSessionBridge {
/** Close all live child processes; called on daemon shutdown. */
shutdown(): Promise<void>;
}
export interface ShellCommandResult {
exitCode: number | null;
output: string;
aborted: boolean;
}
/** @deprecated Use `AcpSessionBridge` instead. */
export type HttpAcpBridge = AcpSessionBridge;

View File

@ -9,14 +9,13 @@ import type { Stream } from '@agentclientprotocol/sdk';
/**
* One ACP NDJSON channel to a single agent. Tests inject a fake by
* replacing the channel factory; production uses
* `defaultSpawnChannelFactory` (lifted to `./spawnChannel.ts` in
* #4175 F1 step 1).
* `defaultSpawnChannelFactory` (still in `cli/src/serve/httpAcpBridge.ts`
* pending the PR 22b lift).
*
* This contract is consumed by the daemon HTTP bridge and is available
* for `packages/channels/base/AcpBridge.ts` and the VSCode IDE
* companion's `acpConnection.ts` to consume directly via
* `@qwen-code/acp-bridge/spawnChannel` instead of each reimplementing
* the child lifecycle. The adapter migrations land separately in F4.
* This contract is consumed by the daemon HTTP bridge today and will be
* shared by `packages/channels/base/AcpBridge.ts` and the VSCode IDE
* companion's `acpConnection.ts` after PR 22b — both currently spawn
* their own `qwen --acp` child via independent code paths.
*/
export interface AcpChannel {
stream: Stream;

View File

@ -65,7 +65,7 @@ describe('EventBus', () => {
abort.abort();
});
it('replay + live: new events follow the replay tail (with replay_complete sentinel)', async () => {
it('replay + live: new events follow the replay tail', async () => {
const bus = new EventBus();
bus.publish({ type: 'foo', data: 'a' });
bus.publish({ type: 'foo', data: 'b' });
@ -75,29 +75,8 @@ describe('EventBus', () => {
setTimeout(() => bus.publish({ type: 'foo', data: 'c' }), 5);
// The replay loop drains the ring, emits a `replay_complete`
// sentinel (id-less, lets consumers drop catch-up indicators), and
// then live events flow. Sentinel goes AFTER the ring tail so the
// consumer sees historical frames first, then the "you're live now"
// signal, then live events.
const events = await collect(iter, 4);
expect(events.map((e) => e.type)).toEqual([
'foo',
'foo',
'replay_complete',
'foo',
]);
expect(events.map((e) => e.data)).toEqual([
'a',
'b',
// D4: canonical `lastReplayedEventId` + deprecated `lastEventId` alias.
expect.objectContaining({
lastReplayedEventId: 2,
lastEventId: 2,
replayedCount: 2,
}),
'c',
]);
const events = await collect(iter, 3);
expect(events.map((e) => e.data)).toEqual(['a', 'b', 'c']);
abort.abort();
});
@ -295,21 +274,13 @@ describe('EventBus', () => {
// A `lastEventId: 0` resume with a queue cap larger than the ring
// collects exactly 8000 live frames; ids start at 2 because id=1
// was the one shifted out of the ring.
//
// #4175 F4 prereq: `lastEventId: 0` + earliest-id-in-ring = 2
// crosses the eviction-detection threshold (earliest > last + 1),
// so an extra synthetic `state_resync_required` frame is emitted
// FIRST. The filter below restricts to live ids, which excludes
// the synthetic (no id), so the original "8000 live frames"
// invariant is preserved.
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 0,
maxQueued: 9000,
signal: abort.signal,
});
// Collect 8001 frames now: 1 synthetic resync + 8000 live.
const events = await collect(iter, 8001);
const events = await collect(iter, 8000);
abort.abort();
const liveIds = events
.filter((e) => e.id !== undefined)
@ -317,8 +288,6 @@ describe('EventBus', () => {
expect(liveIds).toHaveLength(8000);
expect(liveIds[0]).toBe(2);
expect(liveIds[liveIds.length - 1]).toBe(8001);
// The synthetic resync frame is the first one.
expect(events[0]?.type).toBe('state_resync_required');
});
it('eviction detaches the abort listener from a stalled consumer (BmJT1)', async () => {
@ -436,15 +405,12 @@ describe('EventBus', () => {
const events: BridgeEvent[] = [];
for await (const e of iter) {
events.push(e);
// 10 replay + 1 replay_complete sentinel + 1 live = 12 total
if (events.length === 12) break;
if (events.length === 11) break;
}
// The live frame must arrive — NOT a `client_evicted` terminal.
expect(events.find((e) => e.type === 'client_evicted')).toBeUndefined();
expect(events.at(-1)?.type).toBe('live');
expect(events.filter((e) => e.type === 'replay')).toHaveLength(10);
// `replay_complete` sentinel signals end-of-replay before live frames.
expect(events.filter((e) => e.type === 'replay_complete')).toHaveLength(1);
abort.abort();
});
@ -514,227 +480,9 @@ describe('EventBus', () => {
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
// state_resync_required (synthetic) + 3 replay frames +
// replay_complete sentinel = 5 frames.
if (out.length === 5) break;
if (out.length === 3) break;
}
// First frame is the synthetic state_resync_required (no id).
expect(out[0]?.type).toBe('state_resync_required');
expect(out[0]?.id).toBeUndefined();
// Then the 3 surviving ring frames.
expect(out.slice(1, 4).map((e) => e.id)).toEqual([3, 4, 5]);
// The replay_complete sentinel fires at the end of replay even on
// the resync path — `replayedCount` is the actual frames pushed (3),
// NOT `earliestAvailableId - lastEventId` (which would over-count
// across the evicted hole).
expect(out[4]?.type).toBe('replay_complete');
expect(out[4]?.id).toBeUndefined();
expect(out[4]?.data).toMatchObject({ replayedCount: 3 });
expect(out.map((e) => e.id)).toEqual([3, 4, 5]);
abort.abort();
});
describe('state_resync_required (#4175 F4 prereq, Ilya0527 issue #15)', () => {
it('emits state_resync_required when lastEventId is past the ring head', async () => {
// Setup: ring holds 3, ids 1..5 published → ring contains [3,4,5].
// Consumer reconnects with Last-Event-ID: 1 → events 2 was evicted.
// Daemon must emit state_resync_required FIRST so SDK reducer
// knows its state is stale before applying any replay frames.
const bus = new EventBus(3);
for (let i = 1; i <= 5; i++) bus.publish({ type: 'foo', data: i });
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 1,
signal: abort.signal,
});
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
// resync + 3 replay frames + replay_complete = 5.
if (out.length === 5) break;
}
// First frame is the resync terminal (synthetic, no id).
expect(out[0]?.type).toBe('state_resync_required');
expect(out[0]?.id).toBeUndefined();
const data = out[0]?.data as {
reason: string;
lastDeliveredId: number;
earliestAvailableId: number;
};
expect(data.reason).toBe('ring_evicted');
expect(data.lastDeliveredId).toBe(1);
expect(data.earliestAvailableId).toBe(3); // event 2 was evicted
// Replay continues after the resync frame (per design — SDK can
// compute "what you missed" diff later) — so we still get the
// 3 surviving ring frames.
expect(out.slice(1, 4).map((e) => e.id)).toEqual([3, 4, 5]);
// replay_complete sentinel closes the replay even when a resync
// gap preceded it; replayedCount counts only the 3 surviving
// frames actually delivered (not the evicted hole).
expect(out[4]?.type).toBe('replay_complete');
expect(out[4]?.data).toMatchObject({ replayedCount: 3 });
abort.abort();
});
it('does NOT emit state_resync_required when lastEventId is in the ring', async () => {
// Consumer's lastEventId is well within the ring → no gap → no
// resync needed.
const bus = new EventBus(10);
for (let i = 1; i <= 5; i++) bus.publish({ type: 'foo', data: i });
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 2,
signal: abort.signal,
});
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
if (out.length === 3) break;
}
// No resync frame — just the 3 replay frames (ids 3, 4, 5).
expect(out.map((e) => e.id)).toEqual([3, 4, 5]);
expect(out.some((e) => e.type === 'state_resync_required')).toBe(false);
abort.abort();
});
it('does NOT emit state_resync_required at the exact boundary (lastEventId === earliest - 1)', async () => {
// Boundary: ring's earliest id is N, lastEventId is N-1.
// No gap → no resync. Off-by-one guard.
const bus = new EventBus(3);
for (let i = 1; i <= 5; i++) bus.publish({ type: 'foo', data: i });
// Ring is now [3, 4, 5]. lastEventId=2 means "I have 1 and 2";
// next expected is 3, which IS in the ring. No gap.
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 2,
signal: abort.signal,
});
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
// 3 replay frames + 1 replay_complete sentinel = 4 total
if (out.length === 4) break;
}
expect(out.some((e) => e.type === 'state_resync_required')).toBe(false);
// Replay frames in order, then the sentinel (id-less, signals
// catch-up complete).
expect(out.filter((e) => e.type === 'foo').map((e) => e.id)).toEqual([
3, 4, 5,
]);
expect(out.filter((e) => e.type === 'replay_complete')).toHaveLength(1);
abort.abort();
});
it('emits epoch_reset resync when lastEventId is past the bus high-water (D1)', async () => {
// doudouOUC #4484 post-merge review (D1): a fresh bus (nextId=1,
// empty ring) that receives a consumer presenting `lastEventId: 5`
// means the consumer's cursor is from a PREVIOUS bus epoch (daemon
// restart rebuilt the EventBus). Pre-fix this slid past the
// `ring_evicted` check (empty ring) and emitted a bare
// `replay_complete{replayedCount:0}` — a false "you're caught up"
// while the consumer's reducer still held dead-epoch state. Now it
// must emit `state_resync_required{reason:'epoch_reset'}` first.
const bus = new EventBus(10);
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 5,
signal: abort.signal,
});
// Publish one live event AFTER subscribe to confirm the stream works.
setTimeout(() => bus.publish({ type: 'foo', data: 1 }), 0);
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
// resync + replay_complete (0 frames) + 1 live = 3 total.
if (out.length === 3) break;
}
expect(out[0]?.type).toBe('state_resync_required');
expect(out[0]?.id).toBeUndefined();
const data = out[0]?.data as {
reason: string;
lastDeliveredId: number;
earliestAvailableId: number;
};
expect(data.reason).toBe('epoch_reset');
expect(data.lastDeliveredId).toBe(5);
expect(data.earliestAvailableId).toBe(1);
expect(out[1]?.type).toBe('replay_complete');
expect(out[1]?.data).toMatchObject({ replayedCount: 0 });
expect(out[2]?.type).toBe('foo');
expect(out[2]?.id).toBe(1);
abort.abort();
});
it('epoch_reset replays the WHOLE fresh ring (stale cursor must not filter new low ids)', async () => {
// After a restart the new epoch starts ids at 1 again. A consumer
// reconnecting with `lastEventId: 50` (dead epoch) must still receive
// the fresh ring's low-id events — filtering replay by 50 would drop
// ids 1..3 entirely, leaving the consumer permanently behind.
const bus = new EventBus(10);
for (let i = 1; i <= 3; i++) bus.publish({ type: 'foo', data: i });
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 50,
signal: abort.signal,
});
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
// resync + 3 replay frames + replay_complete = 5.
if (out.length === 5) break;
}
expect(out[0]?.type).toBe('state_resync_required');
expect((out[0]?.data as { reason: string }).reason).toBe('epoch_reset');
// All three fresh events replay despite ids < stale cursor.
expect(out.slice(1, 4).map((e) => e.id)).toEqual([1, 2, 3]);
expect(out[4]?.type).toBe('replay_complete');
expect(out[4]?.data).toMatchObject({ replayedCount: 3 });
abort.abort();
});
it('does NOT emit epoch_reset at the caught-up boundary (lastEventId === high-water)', async () => {
// Consumer fully caught up: lastEventId equals the bus high-water
// (nextId - 1). nextId is one past it, so `lastEventId >= nextId` is
// false — no epoch reset. Off-by-one guard for D1.
const bus = new EventBus(10);
for (let i = 1; i <= 3; i++) bus.publish({ type: 'foo', data: i });
// high-water is 3; nextId is 4. lastEventId: 3 is the caught-up case.
const abort = new AbortController();
const iter = bus.subscribe({
lastEventId: 3,
signal: abort.signal,
});
setTimeout(() => bus.publish({ type: 'foo', data: 99 }), 0);
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
// replay_complete (0 frames) + 1 live = 2.
if (out.length === 2) break;
}
expect(out.some((e) => e.type === 'state_resync_required')).toBe(false);
expect(out[0]?.type).toBe('replay_complete');
expect(out[1]?.id).toBe(4);
abort.abort();
});
it('does NOT emit state_resync_required when no lastEventId is provided (fresh subscribe)', async () => {
// First-time subscriber has no prior state to resync — resync
// would be meaningless. Check the no-lastEventId branch is
// skipped entirely.
const bus = new EventBus(3);
for (let i = 1; i <= 5; i++) bus.publish({ type: 'foo', data: i });
const abort = new AbortController();
const iter = bus.subscribe({ signal: abort.signal });
// Live-only — publish one event after subscribe to give the
// iterator something to yield.
setTimeout(() => bus.publish({ type: 'foo', data: 99 }), 0);
const out: BridgeEvent[] = [];
for await (const e of iter) {
out.push(e);
if (out.length === 1) break;
}
expect(out[0]?.type).toBe('foo');
expect(out.some((e) => e.type === 'state_resync_required')).toBe(false);
abort.abort();
});
});
});

View File

@ -357,140 +357,22 @@ export class EventBus {
this.subs.add(sub);
if (opts.lastEventId !== undefined) {
// Detect ring eviction on resume (#4175 F4 prereq, Ilya0527
// issue #15): if the earliest event still in the ring has
// `id > lastEventId + 1`, then events between `lastEventId + 1`
// and `earliestInRing - 1` were evicted before the consumer
// reconnected — the consumer's reducer has a gap it doesn't
// know about. Pre-fix the resume silently succeeded ("you
// caught up!") even though the SDK reducer's state was now
// diverged from the daemon's truth.
//
// Emit `state_resync_required` as an id-less synthetic frame
// (no `id` — same no-burn pattern as `client_evicted`, so it
// doesn't occupy a slot in the per-session monotonic sequence
// other subscribers observe). **Unlike `client_evicted`, the
// stream stays OPEN after this frame** — the resync frame is
// emitted FIRST (before replay), and replay + live frames
// continue flowing afterward. The SDK reducer treats this as
// "your state is stale; call loadSession before applying any
// further deltas" — see `awaitingResync` flag in the SDK
// reducer. Wenshao review (#4360) corrected the prior wording
// that called this "TERMINAL" — that's misleading for oncall;
// `client_evicted` is genuinely terminal (closes stream),
// `state_resync_required` is recovery-oriented (keeps stream
// open).
//
// Replay continues after the resync frame (per design): the
// SDK reducer will auto-skip delta application until
// loadSession clears the flag, but the frames stay on the
// wire so SDK has the option to compute a "what you missed"
// diff later. This is network-friendly (no extra reconnect).
// Epoch-reset detection (doudouOUC #4484 post-merge review, D1).
// `this.nextId` is the next id this bus will assign, so the bus has
// only ever emitted ids `< nextId` THIS epoch. A consumer presenting
// `lastEventId >= nextId` therefore saw an id this epoch never
// produced — the only way that happens is a previous bus epoch
// (daemon restart / EventBus rebuild resets `nextId` to 1 and clears
// the ring). The `ring_evicted` check below is structurally blind to
// this: after a restart the ring is empty (`earliestInRing ===
// undefined`), so it is skipped and the consumer would otherwise get
// a bare `replay_complete{replayedCount:0}` — a false "you're caught
// up" while its accumulated reducer state is stale data from the dead
// epoch. Emit `state_resync_required` (reason `epoch_reset`) first.
const epochReset = opts.lastEventId >= this.nextId;
if (epochReset) {
queue.forcePush({
v: EVENT_SCHEMA_VERSION,
type: 'state_resync_required',
data: {
reason: 'epoch_reset',
lastDeliveredId: opts.lastEventId,
// Ring is typically empty right after a restart; fall back to
// `nextId` (the first id this epoch will assign) so the field
// stays meaningful ("fresh sequence starts here").
earliestAvailableId: this.ring[0]?.id ?? this.nextId,
},
});
} else {
const earliestInRing = this.ring[0]?.id;
if (
earliestInRing !== undefined &&
earliestInRing > opts.lastEventId + 1
) {
queue.forcePush({
v: EVENT_SCHEMA_VERSION,
type: 'state_resync_required',
data: {
reason: 'ring_evicted',
lastDeliveredId: opts.lastEventId,
earliestAvailableId: earliestInRing,
},
});
}
}
// After an epoch reset the consumer's cursor belongs to a dead epoch,
// so every current-epoch event is "new" to it. Filtering replay by the
// stale `lastEventId` (e.g. 50) would drop the fresh low-id events
// (1,2,3…) entirely. Replay the whole current ring in that case.
const replayFrom = epochReset ? 0 : opts.lastEventId;
// Force-push replay frames so they bypass the per-subscriber size
// cap. The cap protects against a slow live consumer; replay is
// already historical and silently dropping it would undermine the
// `Last-Event-ID` resume contract (the consumer would think they
// caught up). If the gap really is enormous, the queue will be
// primed with a long backlog the consumer drains at its own pace.
let replayedCount = 0;
let lastReplayedId: number | undefined;
for (const e of this.ring) {
// The ring only ever contains live events (publish() always
// assigns an id before pushing to ring), so `e.id` is never
// undefined here — but the type system can't see that since
// BridgeEvent.id is optional for synthetic terminal frames.
// Guard explicitly to keep narrow typing without runtime cost.
if (e.id !== undefined && e.id > replayFrom) {
if (e.id !== undefined && e.id > opts.lastEventId) {
queue.forcePush(e);
replayedCount += 1;
lastReplayedId = e.id;
}
}
// Emit a `replay_complete` sentinel so consumers can deterministically
// drop catch-up indicators. Fires both when replay actually
// delivered frames AND when there was nothing to replay (so the
// consumer always sees the transition from "catching up" to
// "live"). Synthetic frame — no `id` so it doesn't burn a slot in
// the per-session sequence (same pattern as `client_evicted` /
// `state_resync_required`).
//
// Without this sentinel, a consumer attaching via Last-Event-ID
// has no positive signal that replay drained — they have to
// heuristically time out the spinner. The state_resync_required
// path already has its own frame (above); the success path
// needed parity.
//
// `replayedCount` is the actual number of frames force-pushed,
// counted in the loop above — NOT `lastId - opts.lastEventId`,
// which would over-count when the ring has holes (state_resync
// path leaves a gap before the ring's earliest id).
queue.forcePush({
v: EVENT_SCHEMA_VERSION,
type: 'replay_complete',
data: {
// D4 (doudouOUC #4484 post-merge review): `lastReplayedEventId`
// is the canonical wire name — the old `lastEventId` collided
// semantically with the SSE protocol's `Last-Event-ID` (envelope
// `id`) in raw daemon traces. Emit both: `lastReplayedEventId`
// for current SDKs and `lastEventId` as a deprecated alias so
// pre-rename consumers keep working (additive, non-breaking).
...(lastReplayedId !== undefined
? {
lastReplayedEventId: lastReplayedId,
lastEventId: lastReplayedId,
}
: {}),
replayedCount,
},
});
}
let disposed = false;

View File

@ -8,13 +8,8 @@ export * from './eventBus.js';
export * from './inMemoryChannel.js';
export * from './channel.js';
export * from './permission.js';
export * from './permissionMediator.js';
export * from './workspacePaths.js';
export * from './status.js';
export * from './bridgeErrors.js';
export * from './bridgeTypes.js';
export * from './bridgeOptions.js';
export * from './spawnChannel.js';
export * from './bridgeClient.js';
export * from './bridge.js';
export * from './bridgeFileSystem.js';

View File

@ -1,30 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
/**
* Shared `writeStderrLine` helper for `bridge.ts` + `bridgeClient.ts`.
*
* Originally inlined per-file in #4175 F1 steps 1-3 to keep the lifted
* modules free of any reverse import on `cli/src/utils/stdioHelpers.ts`.
* Wenshao review (#4319) noted that both consumers now live in the
* **same** `@qwen-code/acp-bridge` package — the cross-package
* justification no longer applies, and a future behavior change
* (timestamp prefix, log level, structured field) would require
* touching two identical copies. Extracted here so both `bridge.ts`
* and `bridgeClient.ts` import from a single source of truth.
*
* Not part of the package's public API — `internal/` subpath is
* excluded from `exports` in `package.json`. `spawnChannel.ts`
* deliberately does NOT consume this (its stderr writes carry their
* own `[serve pid=… cwd=…]` line prefix and use raw
* `process.stderr.write` for that reason).
*
* Byte-identical to the original `cli/src/utils/stdioHelpers.ts`
* implementation.
*/
export function writeStderrLine(message: string): void {
process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
}

View File

@ -1,313 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @internal
*
* Shared bridge test fixtures used by `bridge.test.ts` (acp-bridge
* package) and `daemonStatusProvider.test.ts` (cli package). Extracted
* during #4175 F1 test split so both suites can exercise the same
* `FakeAgent` / `makeChannel` / `makeBridge` helpers without
* cross-package duplication.
*
* Cross-package resolution uses two channels because TypeScript's
* `nodenext` moduleResolution will not fall back to tsconfig `paths`
* once a package's `exports` rejects a subpath. So:
*
* 1. `package.json` lists `./internal/testUtils` in `exports` so
* TypeScript can resolve types at compile time (and the cli's
* vitest run can resolve it at runtime even without an alias).
* 2. `packages/cli/vitest.config.ts` adds a `resolve.alias` for
* the same specifier that points at `src/` instead of `dist/`,
* so the cli test reads source directly — editing
* `testUtils.ts` doesn't require rebuilding acp-bridge.
*
* External consumers of `@qwen-code/acp-bridge` should NOT depend on
* these helpers — the `internal/` directory matches the neighboring
* `internal/stderrLine.ts` convention; the `@internal` JSDoc tag is
* an additional package-private signal (stderrLine.ts uses prose
* rather than the tag, but the intent is the same). The compiled
* file is excluded from npm publish via the package's `.npmignore`,
* so external consumers can't `import` it even though the source
* remains in the build for in-repo cli vitest resolution.
*/
import * as path from 'node:path';
import {
AgentSideConnection,
PROTOCOL_VERSION,
ndJsonStream,
} from '@agentclientprotocol/sdk';
import type {
Agent,
AuthenticateRequest,
AuthenticateResponse,
CancelNotification,
InitializeRequest,
InitializeResponse,
LoadSessionRequest,
LoadSessionResponse,
NewSessionRequest,
NewSessionResponse,
PromptRequest,
PromptResponse,
ResumeSessionRequest,
ResumeSessionResponse,
SetSessionConfigOptionRequest,
SetSessionConfigOptionResponse,
SetSessionModeRequest,
SetSessionModeResponse,
} from '@agentclientprotocol/sdk';
import { createAcpSessionBridge } from '../bridge.js';
import type { BridgeOptions } from '../bridgeOptions.js';
import type { AcpSessionBridge } from '../bridgeTypes.js';
import type { AcpChannel } from '../channel.js';
// Workspace fixtures must round-trip through `path.resolve` so the
// expected values match what the bridge canonicalizes internally on
// every platform — a literal `/work/a` resolves to `D:\work\a` on
// Windows and the assertion drifts. Same for the FakeAgent's
// `sess:<cwd>` synthetic id, since the cwd it sees is the post-resolve
// value the bridge passes through `connection.newSession`.
export const WS_A = path.resolve(path.sep, 'work', 'a');
export const WS_B = path.resolve(path.sep, 'work', 'b');
export const SESS_A = `sess:${WS_A}`;
/**
* Convenience wrapper: `createAcpSessionBridge` requires `boundWorkspace`
* (per #3803 §02 — 1 daemon = 1 workspace). Tests that only ever talk
* to `WS_A` would otherwise repeat `boundWorkspace: WS_A` everywhere;
* this helper defaults it. Tests that need a different bind path (e.g.
* the mismatch test) pass `boundWorkspace` explicitly.
*
* Unlike the pre-split cli-side helper, this version does NOT default
* `statusProvider` — that's a daemon-host-specific seam (PR 22b/2) and
* the acp-bridge tests exercise the no-provider fallback paths. The
* cli-side `daemonStatusProvider.test.ts` defines its own wrapper that
* wires `createDaemonStatusProvider()` for the 4 daemon-host
* integration tests.
*/
export function makeBridge(opts: Partial<BridgeOptions> = {}): AcpSessionBridge {
return createAcpSessionBridge({
boundWorkspace: WS_A,
...opts,
});
}
export interface FakeAgentOpts {
/** What the fake agent returns from `newSession`. */
sessionIdPrefix?: string;
/** Inject a per-call delay before responding to `initialize`. */
initializeDelayMs?: number;
/** Force `initialize` to throw. */
initializeThrows?: Error;
/**
* Custom prompt handler. Default returns `end_turn` synchronously. Useful
* for test cases that want to observe prompt ordering.
*/
promptImpl?: (
p: PromptRequest,
self: FakeAgent,
) => Promise<PromptResponse> | PromptResponse;
cancelImpl?: (p: CancelNotification, self: FakeAgent) => Promise<void> | void;
/**
* Custom `newSession` handler. Default returns a synthesized id (see
* `newSession` below). Used by tests that need to exercise the
* doSpawn newSession-failure path (e.g. throwing to cover the
* `isDying`-mark-then-kill cleanup).
*/
newSessionImpl?: (
p: NewSessionRequest,
self: FakeAgent,
) => Promise<NewSessionResponse> | NewSessionResponse;
loadSessionImpl?: (
p: LoadSessionRequest,
self: FakeAgent,
) => Promise<LoadSessionResponse> | LoadSessionResponse;
resumeSessionImpl?: (
p: ResumeSessionRequest,
self: FakeAgent,
) => Promise<ResumeSessionResponse> | ResumeSessionResponse;
extMethodImpl?: (
method: string,
params: Record<string, unknown>,
self: FakeAgent,
) => Promise<Record<string, unknown>> | Record<string, unknown>;
}
export class FakeAgent implements Agent {
newSessionCalls: NewSessionRequest[] = [];
loadSessionCalls: LoadSessionRequest[] = [];
resumeSessionCalls: ResumeSessionRequest[] = [];
promptCalls: PromptRequest[] = [];
cancelCalls: CancelNotification[] = [];
extMethodCalls: Array<{ method: string; params: Record<string, unknown> }> =
[];
constructor(private readonly opts: FakeAgentOpts = {}) {}
async initialize(_p: InitializeRequest): Promise<InitializeResponse> {
if (this.opts.initializeThrows) throw this.opts.initializeThrows;
if (this.opts.initializeDelayMs) {
await new Promise((r) => setTimeout(r, this.opts.initializeDelayMs));
}
return {
protocolVersion: PROTOCOL_VERSION,
agentInfo: { name: 'fake-agent', version: '0' },
authMethods: [],
agentCapabilities: {},
};
}
async newSession(p: NewSessionRequest): Promise<NewSessionResponse> {
this.newSessionCalls.push(p);
if (this.opts.newSessionImpl) {
return this.opts.newSessionImpl(p, this);
}
const prefix = this.opts.sessionIdPrefix ?? 'sess';
// Stage 1.5 multi-session: one FakeAgent can host multiple
// sessions (same as the real ACP agent), so each newSession call
// returns a fresh id. Suffix by call-count so tests that issue
// multiple newSession on the same channel get distinct ids.
const count = this.newSessionCalls.length;
const suffix = count === 1 ? '' : `#${count}`;
return { sessionId: `${prefix}:${p.cwd}${suffix}` };
}
async loadSession(p: LoadSessionRequest): Promise<LoadSessionResponse> {
this.loadSessionCalls.push(p);
if (this.opts.loadSessionImpl) {
return this.opts.loadSessionImpl(p, this);
}
return {};
}
async unstable_resumeSession(
p: ResumeSessionRequest,
): Promise<ResumeSessionResponse> {
this.resumeSessionCalls.push(p);
if (this.opts.resumeSessionImpl) {
return this.opts.resumeSessionImpl(p, this);
}
return {};
}
async authenticate(_p: AuthenticateRequest): Promise<AuthenticateResponse> {
throw new Error('not implemented in test fake');
}
async prompt(p: PromptRequest): Promise<PromptResponse> {
this.promptCalls.push(p);
if (this.opts.promptImpl) {
return this.opts.promptImpl(p, this);
}
return { stopReason: 'end_turn' };
}
async cancel(p: CancelNotification): Promise<void> {
this.cancelCalls.push(p);
if (this.opts.cancelImpl) {
await this.opts.cancelImpl(p, this);
}
}
async setSessionMode(
_p: SetSessionModeRequest,
): Promise<SetSessionModeResponse> {
throw new Error('not implemented in test fake');
}
async setSessionConfigOption(
_p: SetSessionConfigOptionRequest,
): Promise<SetSessionConfigOptionResponse> {
throw new Error('not implemented in test fake');
}
async extMethod(
method: string,
params: Record<string, unknown>,
): Promise<Record<string, unknown>> {
this.extMethodCalls.push({ method, params });
if (this.opts.extMethodImpl) {
return this.opts.extMethodImpl(method, params, this);
}
return {};
}
}
export interface ChannelHandle {
channel: AcpChannel;
agent: FakeAgent;
killed: boolean;
/**
* Resolve `channel.exited` without going through `kill()`. Optionally
* supply exit info so the bridge's `session_died` event carries the
* same `exitCode` / `signalCode` it would in a real crash (BX9_P).
*/
crash: (info?: {
exitCode: number | null;
signalCode: NodeJS.Signals | null;
}) => void;
}
/**
* Create a paired in-memory NDJSON channel: bridge sees `clientChannel`,
* fake agent sees `agentStream`. Each `TransformStream` carries one
* direction.
*
* Not migrated to `createInMemoryChannel()` (used by the other
* `createInMemoryChannel` sites in `bridge.test.ts`): `kill()` below
* needs the underlying `ab` / `ba` writables to simulate
* child-process termination, which the bare helper deliberately does
* not expose. See `inMemoryChannel.ts` JSDoc for the rationale.
*/
export function makeChannel(opts: FakeAgentOpts = {}): ChannelHandle {
const ab = new TransformStream<Uint8Array, Uint8Array>();
const ba = new TransformStream<Uint8Array, Uint8Array>();
const clientStream = ndJsonStream(ab.writable, ba.readable);
const agentStream = ndJsonStream(ba.writable, ab.readable);
let resolveExited:
| ((info?: {
exitCode: number | null;
signalCode: NodeJS.Signals | null;
}) => void)
| undefined;
const exited = new Promise<
{ exitCode: number | null; signalCode: NodeJS.Signals | null } | undefined
>((res) => {
resolveExited = res;
});
const handle: ChannelHandle = {
channel: undefined as unknown as AcpChannel,
agent: new FakeAgent(opts),
killed: false,
/** Test hook: simulate an unexpected child crash. */
crash: (info?: {
exitCode: number | null;
signalCode: NodeJS.Signals | null;
}) => resolveExited!(info),
};
// Spin up the fake agent on the agent side.
new AgentSideConnection(() => handle.agent, agentStream);
handle.channel = {
stream: clientStream,
exited,
kill: async () => {
handle.killed = true;
try {
await ab.writable.close();
} catch {
/* ignore */
}
try {
await ba.writable.close();
} catch {
/* ignore */
}
resolveExited!();
},
killSync: () => {
// Test fake: just mark killed; the async streams will close
// naturally on test cleanup. Mirrors the real spawn factory's
// SIGKILL semantics (fire-and-forget).
handle.killed = true;
resolveExited!();
},
};
return handle;
}

View File

@ -1,16 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
// Upper bound on a single MCP server (re)discovery. The MCP manager's
// per-server discovery can take up to 5 minutes
// (McpClientManager.MAX_DISCOVERY_TIMEOUT_MS). Both the bridge
// (server-side race deadline) and the SDK (client-side default) must
// agree on this value; see #4330 for the coupling rationale.
export const MCP_RESTART_SERVER_DEADLINE_MS = 300_000;
// Extra headroom so the client AbortSignal never fires before the
// daemon finishes serializing its success/error response.
export const MCP_RESTART_CLIENT_HEADROOM_MS = 30_000;

View File

@ -7,12 +7,10 @@
/**
* `PermissionMediator` — type-only interface contract for daemon
* permission flow. **No implementation lives here.** Permission voting
* still runs inside `BridgeClient.requestPermission`
* (`@qwen-code/acp-bridge/bridgeClient` after #4175 F1 step 2) and
* `respondToPermission` (inside `createHttpAcpBridge` factory closure
* at `@qwen-code/acp-bridge/bridge` after F1 step 3), hard-coded to
* `first-responder`. F3 PR 24 will move that code behind this
* interface and add the other three policies.
* still runs inside `BridgeClient.requestPermission` /
* `respondToPermission` in `packages/cli/src/serve/httpAcpBridge.ts`,
* hard-coded to `first-responder`. PR 24 (#4175 Wave 5) will move that
* code behind this interface and add the other three policies.
*
* The four policies are ordered from cheapest to strongest:
*
@ -32,9 +30,8 @@
* Use case: workstations where remote control should never grant
* privilege escalation.
*
* See `bridgeClient.ts BridgeClient.requestPermission` for the
* current first-responder implementation; the `FIXME(stage-1.5,
* chiga0 finding 3)` block above that method scoped this contract.
* See `httpAcpBridge.ts:1096-1106` for the original FIXME that
* scoped this contract.
*/
export type PermissionPolicy =
| 'first-responder'
@ -45,8 +42,8 @@ export type PermissionPolicy =
/**
* One pending permission tracked by a `PermissionMediator`. The
* shape mirrors the current `PendingPermission` record in
* `@qwen-code/acp-bridge/bridgeClient` (lifted in #4175 F1 step 2)
* so F3 PR 24's lift is a structural rename rather than a redesign.
* `httpAcpBridge.ts:1003` so PR 24's lift is a structural rename
* rather than a redesign.
*/
export interface PermissionRequestRecord {
/** ACP `RequestPermission` request id, unique per session. */
@ -95,9 +92,6 @@ export interface PermissionVote {
/** True when the request originated on a loopback connection.
* `local-only` requires this. */
readonly fromLoopback: boolean;
/** Opaque metadata forwarded from the voter's response body to
* the resolution (e.g. AskUserQuestion answers). */
readonly metadata?: Readonly<Record<string, unknown>>;
}
/**
@ -111,19 +105,6 @@ export type PermissionVoteOutcome =
| { readonly kind: 'already_resolved'; readonly resolvedOptionId: string }
| {
readonly kind: 'forbidden';
/**
* `designated_mismatch` fires for both:
* - `designated` policy: voter `clientId` is not the prompt
* `originatorClientId`.
* - `consensus` policy: voter `clientId` is undefined OR not
* in the issue-time `votersAtIssue` snapshot. Overloaded
* here to keep the contract closed; future versions may
* widen this union with a more specific reason if SDK
* consumers need to distinguish.
*
* `remote_not_allowed` fires under `local-only` policy when
* `vote.fromLoopback === false`.
*/
readonly reason: 'designated_mismatch' | 'remote_not_allowed';
}
| { readonly kind: 'unknown_request' };
@ -134,11 +115,7 @@ export type PermissionVoteOutcome =
* a timeout expires.
*/
export type PermissionResolution =
| {
readonly kind: 'option';
readonly optionId: string;
readonly metadata?: Readonly<Record<string, unknown>>;
}
| { readonly kind: 'option'; readonly optionId: string }
| {
readonly kind: 'cancelled';
readonly reason: 'timeout' | 'session_closed' | 'agent_cancelled';

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -1,243 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
/**
* Unit tests for `defaultSpawnChannelFactory`'s security-critical env
* scrubbing (wenshao #4319 Critical fold-in). The wider 174-test
* `httpAcpBridge.test.ts` suite uses mock channels and never spawns a
* real child, so none of those tests exercise `defaultSpawnChannelFactory`
* or `scrubChildEnv` directly. These tests close that gap.
*
* Why this matters: now that `defaultSpawnChannelFactory` is a public
* export of `@qwen-code/acp-bridge`, channels (`packages/channels/base/
* AcpBridge.ts`) and the VSCode IDE companion will consume it directly
* and cannot rely on cli-package integration tests for env-scrubbing
* guarantees. The scrubbing logic protects against:
*
* - `QWEN_SERVER_TOKEN` (the daemon's own bearer token) leaking into
* the spawned agent's environment, where prompt-injection could
* turn the agent into an authenticated client of its own daemon.
* - An `overrides` map smuggling a scrubbed key BACK into the child
* env (defense-in-depth — operators / embedders can pass overrides,
* but the denylist still wins).
* - An `overrides` map with `undefined` value silently failing to
* delete a stale inherited var (PR 14 fix #4247 wenshao R5 —
* the `runQwenServe.ts:216` use case).
*
* Each branch listed below is now regression-guarded by an assertion.
*/
import { describe, expect, it, vi } from 'vitest';
import { createStderrForwarder, scrubChildEnv } from './spawnChannel.js';
describe('createStderrForwarder', () => {
it('calls onDiagnosticLine for each complete line', () => {
const captured: Array<{ line: string; level?: string }> = [];
const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
const forwarder = createStderrForwarder({
prefix: '[test] ',
onDiagnosticLine: (l, lvl) => captured.push({ line: l, level: lvl }),
});
forwarder.onData('hello\nworld\n');
expect(captured).toEqual([
{ line: '[test] hello', level: 'warn' },
{ line: '[test] world', level: 'warn' },
]);
// Also writes to process.stderr
expect(stderrSpy).toHaveBeenCalledWith('[test] hello\n');
expect(stderrSpy).toHaveBeenCalledWith('[test] world\n');
stderrSpy.mockRestore();
});
it('buffers partial lines until newline arrives', () => {
const captured: Array<{ line: string; level?: string }> = [];
const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
const forwarder = createStderrForwarder({
prefix: '[p] ',
onDiagnosticLine: (l, lvl) => captured.push({ line: l, level: lvl }),
});
forwarder.onData('partial');
expect(captured).toHaveLength(0); // no newline yet
forwarder.onData(' more\n');
expect(captured).toEqual([{ line: '[p] partial more', level: 'warn' }]);
stderrSpy.mockRestore();
});
it('flushes buffered content on end', () => {
const captured: Array<{ line: string; level?: string }> = [];
const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
const forwarder = createStderrForwarder({
prefix: '[p] ',
onDiagnosticLine: (l, lvl) => captured.push({ line: l, level: lvl }),
});
forwarder.onData('partial');
expect(captured).toHaveLength(0);
forwarder.onEnd();
expect(captured).toEqual([{ line: '[p] partial', level: 'warn' }]);
stderrSpy.mockRestore();
});
it('does not call onDiagnosticLine for empty lines', () => {
const captured: Array<{ line: string; level?: string }> = [];
const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
const forwarder = createStderrForwarder({
prefix: '[p] ',
onDiagnosticLine: (l, lvl) => captured.push({ line: l, level: lvl }),
});
forwarder.onData('\n\n');
expect(captured).toHaveLength(0);
stderrSpy.mockRestore();
});
it('force-flushes with [truncated] when buffer exceeds 64 KiB cap', () => {
const captured: Array<{ line: string; level?: string }> = [];
const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
const forwarder = createStderrForwarder({
prefix: '[x] ',
onDiagnosticLine: (l, lvl) => captured.push({ line: l, level: lvl }),
});
// Write 65 KiB without a newline — exceeds the 64 KiB cap
const bigChunk = 'A'.repeat(65 * 1024);
forwarder.onData(bigChunk);
// Should have force-flushed the first 64 KiB with [truncated]
expect(captured.length).toBeGreaterThanOrEqual(1);
expect(captured[0]!.line).toContain('[truncated]');
expect(captured[0]!.level).toBe('warn');
// The flushed line should have the prefix
expect(captured[0]!.line).toMatch(/^\[x\] /);
stderrSpy.mockRestore();
});
it('works without onDiagnosticLine (still writes to stderr)', () => {
const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
const forwarder = createStderrForwarder({
prefix: '[no-cb] ',
});
forwarder.onData('line1\n');
expect(stderrSpy).toHaveBeenCalledWith('[no-cb] line1\n');
stderrSpy.mockRestore();
});
});
// Decoupled canary: we deliberately hand-roll the test set instead of
// importing `SCRUBBED_CHILD_ENV_KEYS` from `spawnChannel.ts` so the
// helper's behavior (clone + scrub + override + denylist-wins ordering)
// is tested as a pure function with parameterized input, independent
// of any current production denylist. The multi-key test below
// forward-guards expansion when a future sandboxed-agent mode grows
// the production set per the WARNING on `SCRUBBED_CHILD_ENV_KEYS`.
const SCRUBBED = new Set<string>(['QWEN_SERVER_TOKEN']);
describe('scrubChildEnv (defaultSpawnChannelFactory env policy)', () => {
it('shallow-clones source — never aliases into the live process.env', () => {
const source = { FOO: 'bar' };
const result = scrubChildEnv(source, SCRUBBED);
result['MUTATED'] = 'yes';
expect(source).not.toHaveProperty('MUTATED');
});
it('strips QWEN_SERVER_TOKEN from the child env', () => {
const source = { QWEN_SERVER_TOKEN: 'super-secret', PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED);
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
expect(result['PATH']).toBe('/usr/bin');
});
it('passes through non-scrubbed env vars unchanged', () => {
const source = {
OPENAI_API_KEY: 'sk-test',
DASHSCOPE_API_KEY: 'ds-test',
HOME: '/home/user',
};
const result = scrubChildEnv(source, SCRUBBED);
expect(result).toEqual(source);
});
it('overrides with a string value ADD the key', () => {
const source = { PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED, { NEW_KEY: 'new-value' });
expect(result['NEW_KEY']).toBe('new-value');
});
it('overrides with a string value REPLACE an existing key', () => {
const source = { PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED, { PATH: '/override/bin' });
expect(result['PATH']).toBe('/override/bin');
});
it('overrides with undefined value DELETE the key from the child env (PR 14 fix #4247 wenshao R5)', () => {
const source = { STALE_VAR: 'leftover', PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED, { STALE_VAR: undefined });
expect(result).not.toHaveProperty('STALE_VAR');
expect(result['PATH']).toBe('/usr/bin');
});
it('overrides CANNOT re-introduce a scrubbed key (defense in depth)', () => {
const source = { PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED, {
QWEN_SERVER_TOKEN: 'sneaky-attempt-via-override',
});
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
});
it('overrides CANNOT undo the scrub by setting undefined for a scrubbed key', () => {
// Edge case: `undefined` value would normally delete; but for a
// scrubbed key, the `continue` in the loop short-circuits BEFORE
// the undefined-vs-string check. The key stays deleted (by the
// earlier scrub pass) regardless of what overrides says.
const source = { QWEN_SERVER_TOKEN: 'secret', PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED, {
QWEN_SERVER_TOKEN: undefined,
});
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
});
it('overrides are applied AFTER scrub — the denylist always wins', () => {
// Verifies the documented ordering invariant: even if the scrub
// and override touch the same key in conflicting ways, scrub wins.
const source = { QWEN_SERVER_TOKEN: 'from-process-env' };
const result = scrubChildEnv(source, SCRUBBED, {
QWEN_SERVER_TOKEN: 'from-override',
});
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
});
it('empty overrides leaves scrub-only behavior intact', () => {
const source = { QWEN_SERVER_TOKEN: 'secret', PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED, {});
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
expect(result['PATH']).toBe('/usr/bin');
});
it('no overrides arg works the same as empty overrides', () => {
const source = { QWEN_SERVER_TOKEN: 'secret', PATH: '/usr/bin' };
const result = scrubChildEnv(source, SCRUBBED);
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
expect(result['PATH']).toBe('/usr/bin');
});
it('multi-key scrub set strips every listed key', () => {
// Forward-compat: if a future sandboxed-agent mode expands the
// denylist (as the WARNING comment on SCRUBBED_CHILD_ENV_KEYS
// anticipates), this verifies the loop handles multiple keys.
const sandboxScrub = new Set<string>([
'QWEN_SERVER_TOKEN',
'AWS_SECRET_ACCESS_KEY',
'OPENAI_API_KEY',
]);
const source = {
QWEN_SERVER_TOKEN: 't1',
AWS_SECRET_ACCESS_KEY: 't2',
OPENAI_API_KEY: 't3',
PATH: '/usr/bin',
};
const result = scrubChildEnv(source, sandboxScrub);
expect(result).not.toHaveProperty('QWEN_SERVER_TOKEN');
expect(result).not.toHaveProperty('AWS_SECRET_ACCESS_KEY');
expect(result).not.toHaveProperty('OPENAI_API_KEY');
expect(result['PATH']).toBe('/usr/bin');
});
});

View File

@ -1,324 +0,0 @@
/**
* @license
* Copyright 2025 Qwen Team
* SPDX-License-Identifier: Apache-2.0
*/
import { spawn, type ChildProcess } from 'node:child_process';
import { Readable, Writable } from 'node:stream';
import { ndJsonStream } from '@agentclientprotocol/sdk';
import type { AcpChannelExitInfo, ChannelFactory } from './channel.js';
import { MissingCliEntryError } from './status.js';
// ──────────────────────────────────────────────────────────────────────
// Stderr forwarder — extracted from the inline handler so it's testable
// in isolation without spawning a real child process.
// ──────────────────────────────────────────────────────────────────────
export interface StderrForwarderOptions {
prefix: string;
onDiagnosticLine?: (line: string, level?: 'info' | 'warn' | 'error') => void;
}
/**
* Creates a stateful forwarder that buffers incoming chunks, splits on
* newlines, writes each complete line to `process.stderr` with a prefix,
* and optionally invokes `onDiagnosticLine` for external consumers (e.g.
* the daemon log file writer).
*
* Cap behavior: if the unterminated buffer exceeds 64 KiB the excess is
* force-flushed with a `[truncated]` marker — same memory-bounding
* behavior as before the extraction.
*/
export function createStderrForwarder(opts: StderrForwarderOptions): {
onData: (chunk: string) => void;
onEnd: () => void;
} {
const { prefix, onDiagnosticLine } = opts;
const STDERR_LINE_CAP_CHARS = 64 * 1024;
let buf = '';
const flush = (line: string) => {
if (line.length > 0) {
process.stderr.write(prefix + line + '\n');
if (onDiagnosticLine) onDiagnosticLine(prefix + line, 'warn');
}
};
return {
onData(chunk: string) {
buf += chunk;
let nl = buf.indexOf('\n');
while (nl !== -1) {
flush(buf.slice(0, nl));
buf = buf.slice(nl + 1);
nl = buf.indexOf('\n');
}
// Force-flush the unterminated tail if it's grown past the cap
// — keeps memory bounded against a `\n`-less stderr storm.
while (buf.length > STDERR_LINE_CAP_CHARS) {
const truncated = buf.slice(0, STDERR_LINE_CAP_CHARS) + ' [truncated]';
process.stderr.write(prefix + truncated + '\n');
if (onDiagnosticLine) onDiagnosticLine(prefix + truncated, 'warn');
buf = buf.slice(STDERR_LINE_CAP_CHARS);
}
},
onEnd() {
if (buf.length > 0) flush(buf);
},
};
}
// ──────────────────────────────────────────────────────────────────────
// SpawnChannelFactory — configurable factory-of-factories
// ──────────────────────────────────────────────────────────────────────
export interface SpawnChannelFactoryOptions {
onDiagnosticLine?: (line: string, level?: 'info' | 'warn' | 'error') => void;
}
/**
* Creates a `ChannelFactory` that spawns `qwen --acp` child processes.
* Accepts an optional `onDiagnosticLine` callback that receives every
* child-stderr line (already prefixed) so callers can tee to a log file
* or structured logger without intercepting process.stderr globally.
*
* `defaultSpawnChannelFactory` below is `createSpawnChannelFactory()` —
* no options, same behavior as before this refactor.
*/
export function createSpawnChannelFactory(
options: SpawnChannelFactoryOptions = {},
): ChannelFactory {
return async (workspaceCwd, childEnvOverrides) => {
const cliEntry = process.env['QWEN_CLI_ENTRY'] || process.argv[1];
if (!cliEntry) {
throw new MissingCliEntryError();
}
const childEnv = scrubChildEnv(
process.env,
SCRUBBED_CHILD_ENV_KEYS,
childEnvOverrides,
);
const child = spawn(process.execPath, [cliEntry, '--acp'], {
cwd: workspaceCwd,
stdio: ['pipe', 'pipe', 'pipe'],
env: childEnv,
});
// Forward child stderr to the daemon's stderr line-by-line, with a
// `[serve pid=… cwd=…]` prefix on each line so operators can
// correlate stack traces back to the spawning request.
if (child.stderr) {
const prefix = `[serve pid=${child.pid} cwd=${workspaceCwd}] `;
const forwarder = createStderrForwarder({
prefix,
onDiagnosticLine: options.onDiagnosticLine,
});
child.stderr.setEncoding('utf8');
child.stderr.on('data', (chunk: string) => forwarder.onData(chunk));
child.stderr.on('end', () => forwarder.onEnd());
child.stderr.on('error', () => {
// Don't crash the daemon if the pipe breaks; the child is
// already gone or about to be.
});
}
const exited = new Promise<AcpChannelExitInfo | undefined>((resolve) => {
let resolved = false;
const finish = (info?: AcpChannelExitInfo) => {
if (resolved) return;
resolved = true;
resolve(info);
};
child.once('exit', (code, signal) =>
finish({ exitCode: code, signalCode: signal }),
);
child.once('error', () => finish(undefined));
});
if (!child.stdin || !child.stdout) {
child.kill('SIGKILL');
throw new Error(
'Spawned ACP child has no stdin/stdout — cannot establish NDJSON channel.',
);
}
const writable = Writable.toWeb(child.stdin) as WritableStream<Uint8Array>;
const readable = Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>;
const stream = ndJsonStream(writable, readable);
return {
stream,
kill: () => killChild(child),
killSync: () => {
if (child.exitCode === null && child.signalCode === null) {
try {
child.kill('SIGKILL');
} catch {
/* already dead / pid recycled — ignore */
}
}
},
exited,
};
};
}
/**
* Default channel factory: spawn the current Node executable running this
* CLI's entry script in `--acp` mode. `process.argv[1]` resolves to the qwen
* entry script when launched via the `qwen` bin shim.
*
* Note on `cwd`: CodeQL flags the `workspaceCwd` flow into `spawn({cwd})`
* as an "uncontrolled data used in path expression" finding. That's the
* Stage 1 trust model speaking — the caller (a token-authenticated HTTP
* client) is treated as an extension of the operator. The agent already
* runs as the same UID with shell-tool access, so restricting the spawn
* cwd to a sandbox here would be theatre. Stage 4+ remote-sandbox swaps
* this factory for a sandbox-aware variant; see issue #3803 §11.
*
* Lifted from `cli/src/serve/httpAcpBridge.ts` to `@qwen-code/acp-bridge`
* in #4175 PR F1 so `channels/base/AcpBridge.ts` and the VSCode IDE
* companion can share one spawn implementation instead of each
* reimplementing the child lifecycle (the current divergence noted in
* `channel.ts`'s top-of-file comment).
*
* Preserved as `createSpawnChannelFactory()` (no options) for backward
* compat. Use `createSpawnChannelFactory({ onDiagnosticLine })` to also
* tee child stderr lines through an external callback.
*/
export const defaultSpawnChannelFactory: ChannelFactory =
createSpawnChannelFactory();
const KILL_HARD_DEADLINE_MS = 10_000;
/**
* Environment variables stripped from the spawned `qwen --acp` child's
* environment. Everything else is passed through — see the
* threat-model rationale at the call site in `defaultSpawnChannelFactory`.
*
* Currently just `QWEN_SERVER_TOKEN`: the daemon's own bearer token,
* which the agent doesn't need (it speaks to the daemon over stdio,
* not HTTP). Leaving it in the child's env would let prompt injection
* turn the agent into an authenticated client of its own daemon — an
* escalation the agent doesn't otherwise have.
*
* **WARNING**: this denylist is correct *only because the agent
* already has unrestricted shell-tool access* — anything in the env
* is reachable via `~/.bashrc`/`~/.aws/credentials`/etc. anyway.
* Any future mode that **removes** shell-tool access (e.g. a
* sandbox-locked agent variant) MUST switch this back to an
* allowlist OR significantly expand the denylist to cover common
* provider/CI/cloud secret prefixes (`OPENAI_*`, `ANTHROPIC_*`,
* `AWS_*`, `GITHUB_TOKEN`, `CI_*`, `*_API_KEY`, `*_SECRET`, …).
* See issue #3803 §11 for the Stage 4+ remote-sandbox plan.
*
* Defined at module scope so the Set is allocated once at load.
*/
const SCRUBBED_CHILD_ENV_KEYS: ReadonlySet<string> = new Set([
'QWEN_SERVER_TOKEN',
]);
/**
* Build the env passed to the `qwen --acp` child. Pure function, exported
* for unit-test access (the surrounding `defaultSpawnChannelFactory` is
* unit-test-hostile because it actually spawns Node). Behavior:
*
* 1. Start from a shallow clone of `source` (no aliasing into the
* daemon's `process.env`).
* 2. Delete every key listed in `scrubbed` (the daemon-internal secret
* denylist — currently just `QWEN_SERVER_TOKEN`, see security
* rationale on the constant).
* 3. Apply `overrides` per-handle. `undefined` value deletes the key
* (lets an embedded caller scrub a stale inherited var without
* mutating the daemon's global `process.env`). Anything else
* assigns. **`overrides` CANNOT re-introduce a scrubbed key** —
* defense-in-depth so an operator passing
* `{ QWEN_SERVER_TOKEN: 'x' }` in overrides can't smuggle the
* daemon's bearer token back into the child.
*
* Used by `defaultSpawnChannelFactory` above. The split mirrors the
* "scrub" comment block's structure 1:1; behavior is byte-identical to
* the pre-extraction inline implementation.
*/
export function scrubChildEnv(
source: NodeJS.ProcessEnv,
scrubbed: ReadonlySet<string>,
overrides?: Readonly<Record<string, string | undefined>>,
): NodeJS.ProcessEnv {
const childEnv: NodeJS.ProcessEnv = { ...source };
for (const key of scrubbed) {
delete childEnv[key];
}
if (overrides) {
for (const [key, value] of Object.entries(overrides)) {
if (scrubbed.has(key)) continue;
if (value === undefined) {
delete childEnv[key];
} else {
childEnv[key] = value;
}
}
}
return childEnv;
}
function killChild(child: ChildProcess): Promise<void> {
return new Promise<void>((resolve) => {
if (child.exitCode !== null || child.signalCode !== null) {
resolve();
return;
}
let resolved = false;
const finish = () => {
if (resolved) return;
resolved = true;
child.removeListener('exit', finish);
resolve();
};
child.once('exit', finish);
try {
child.kill('SIGTERM');
} catch {
finish();
return;
}
setTimeout(() => {
if (!resolved && child.exitCode === null && child.signalCode === null) {
try {
child.kill('SIGKILL');
} catch {
/* swallow */
}
}
}, 5_000).unref();
// Even SIGKILL doesn't return if the child is in uninterruptible
// sleep (D-state, e.g. NFS read blocked on a dead server). Without
// this hard deadline, `bridge.shutdown()`'s `Promise.all` waits
// forever on that one wedged child and SHUTDOWN_FORCE_CLOSE_MS in
// `runQwenServe` only covers `server.close()`, not the bridge.
// After the deadline give up: the child is probably stuck in a
// kernel call we can't cancel, and `process.exit(0)` will reap it
// when the daemon returns to its caller.
//
// #4319 wenshao round 5 fold-in: emit a stderr line BEFORE we
// abandon the child so operators see a signal that a zombie
// exists. Without this, `shutdown()` returns "graceful" while a
// wedged `qwen --acp` process keeps holding FDs / memory / locks;
// under systemd/k8s supervision, the daemon respawn would then
// race the orphan for the same workspace. Single-line warning is
// intentionally noisy on the daemon's stderr so monitoring/log
// aggregators catch it.
setTimeout(() => {
if (!resolved) {
process.stderr.write(
`qwen serve: killChild hard deadline (${KILL_HARD_DEADLINE_MS}ms) ` +
`reached; child pid=${child.pid} still alive (uninterruptible sleep?) — ` +
`abandoning. Operator should check for zombie qwen --acp processes ` +
`holding workspace resources.\n`,
);
finish();
}
}, KILL_HARD_DEADLINE_MS).unref();
});
}

View File

@ -20,9 +20,9 @@ describe('SERVE_ERROR_KINDS', () => {
// kinds; PR 14 added `'budget_exhausted'` for MCP guardrail
// refusals (see #4175 PR 14); PR 16 added `'stat_failed'` for
// non-ENOENT stat failures on workspace memory discovery (see
// #4175 PR 16). Issue #4514 T2.8 added three runtime-mutation
// error kinds; T2.9 appended prompt_deadline_exceeded and
// writer_idle_timeout. Future additions append to this list.
// #4175 PR 16). Future additions append to this list — the
// order is part of the contract so SDK consumers can pattern-
// match without per-kind lookups.
expect(SERVE_ERROR_KINDS).toEqual([
'missing_binary',
'blocked_egress',
@ -33,26 +33,15 @@ describe('SERVE_ERROR_KINDS', () => {
'parse_error',
'stat_failed',
'budget_exhausted',
'mcp_budget_would_exceed',
'mcp_server_spawn_failed',
'invalid_config',
'prompt_deadline_exceeded',
'writer_idle_timeout',
]);
});
it('exposes T2.8 error kinds in SERVE_ERROR_KINDS', () => {
expect(SERVE_ERROR_KINDS).toContain('mcp_budget_would_exceed');
expect(SERVE_ERROR_KINDS).toContain('mcp_server_spawn_failed');
expect(SERVE_ERROR_KINDS).toContain('invalid_config');
});
});
describe('BridgeTimeoutError', () => {
it('preserves the legacy message format and exposes label/timeoutMs', () => {
const err = new BridgeTimeoutError('init', 250);
expect(err.name).toBe('BridgeTimeoutError');
expect(err.message).toBe('AcpSessionBridge init timed out after 250ms');
expect(err.message).toBe('HttpAcpBridge init timed out after 250ms');
expect(err.label).toBe('init');
expect(err.timeoutMs).toBe(250);
expect(err).toBeInstanceOf(Error);

View File

@ -28,13 +28,6 @@ export const SERVE_ERROR_KINDS = [
// Surfaced on per-server `mcp_server` cells (refused at discovery)
// and on the workspace-level `mcp_budget` cell (any refusal this pass).
'budget_exhausted',
// Issue #4514 T2.8: runtime MCP mutation routes
'mcp_budget_would_exceed',
'mcp_server_spawn_failed',
'invalid_config',
// Issue #4514 T2.9: prompt deadline + writer idle timeout
'prompt_deadline_exceeded',
'writer_idle_timeout',
] as const;
export type ServeErrorKind = (typeof SERVE_ERROR_KINDS)[number];
@ -48,7 +41,7 @@ export class BridgeTimeoutError extends Error {
readonly label: string;
readonly timeoutMs: number;
constructor(label: string, timeoutMs: number) {
super(`AcpSessionBridge ${label} timed out after ${timeoutMs}ms`);
super(`HttpAcpBridge ${label} timed out after ${timeoutMs}ms`);
this.name = 'BridgeTimeoutError';
this.label = label;
this.timeoutMs = timeoutMs;
@ -95,17 +88,13 @@ export class MissingCliEntryError extends Error {
export const SERVE_STATUS_EXT_METHODS = {
workspaceMcp: 'qwen/status/workspace/mcp',
workspaceMcpTools: 'qwen/status/workspace/mcp/tools',
workspaceSkills: 'qwen/status/workspace/skills',
workspaceTools: 'qwen/status/workspace/tools',
workspaceProviders: 'qwen/status/workspace/providers',
workspaceMemory: 'qwen/status/workspace/memory',
workspaceAgents: 'qwen/status/workspace/agents',
workspacePreflight: 'qwen/status/workspace/preflight',
sessionContext: 'qwen/status/session/context',
sessionContextUsage: 'qwen/status/session/context_usage',
sessionSupportedCommands: 'qwen/status/session/supported_commands',
sessionTasks: 'qwen/status/session/tasks',
} as const;
/**
@ -116,15 +105,8 @@ export const SERVE_STATUS_EXT_METHODS = {
* which then mutates Config / ToolRegistry / McpClientManager state.
*/
export const SERVE_CONTROL_EXT_METHODS = {
sessionClose: 'qwen/control/session/close',
sessionApprovalMode: 'qwen/control/session/approval_mode',
sessionRecap: 'qwen/control/session/recap',
sessionBtw: 'qwen/control/session/btw',
sessionShellHistory: 'qwen/control/session/shell_history',
workspaceMcpRestart: 'qwen/control/workspace/mcp/restart',
// T2.8 (#4514): runtime MCP server mutation ext-methods
workspaceMcpRuntimeAdd: 'qwen/control/workspace/mcp/runtime-add',
workspaceMcpRuntimeRemove: 'qwen/control/workspace/mcp/runtime-remove',
} as const;
export type ServeStatus =
@ -178,37 +160,6 @@ export interface ServeWorkspaceMcpServerStatus extends ServeStatusCell {
* arrays to render a per-server row correctly.
*/
disabledReason?: 'config' | 'budget';
/**
* F2 (#4175 commit 5): pool-mode workspaces can hold multiple
* `PoolEntry` instances under the same `name` when sessions inject
* different fingerprints (e.g. per-session OAuth headers). Absent on
* pre-F2 daemons and on F2 daemons with `QWEN_SERVE_NO_MCP_POOL=1`;
* present (≥1) when the pool advertises `mcp_workspace_pool`.
* Operators use this to render an "N entries" badge or drill into
* `entrySummary` for the per-entry breakdown.
*/
entryCount?: number;
/**
* F2 (#4175 commit 5): per-entry breakdown for multi-entry server
* names. `entryIndex` is a stable opaque integer assigned at entry
* creation (V21-7) — NOT the raw fingerprint, which would leak
* OAuth/env rotation timing through snapshot diffs. `refs` is the
* count of sessions currently attached. `status` is the per-entry
* runtime status (`connected` / `connecting` / `disconnected`) so
* dashboards can show per-entry health when the aggregated
* `mcpStatus` rolls up to `connected` while one entry is still
* reconnecting.
*
* Old SDK clients ignore the field per the additive-only protocol
* contract; new clients gate UI on `entryCount > 1`. The pair
* (`entryCount`, `entrySummary`) is always present together when
* advertised — `mcp_workspace_pool` capability tag implies both.
*/
entrySummary?: ReadonlyArray<{
entryIndex: number;
refs: number;
status: ServeMcpServerRuntimeStatus;
}>;
}
/** Budget mode for the MCP client guardrails (issue #4175 PR 14). */
@ -277,26 +228,6 @@ export interface ServeWorkspaceMcpStatus {
budgets?: ServeMcpBudgetStatusCell[];
}
export interface ServeWorkspaceMcpToolStatus {
name: string;
serverToolName?: string;
description?: string;
schema?: Record<string, unknown>;
annotations?: Record<string, unknown>;
isValid: boolean;
invalidReason?: string;
}
export interface ServeWorkspaceMcpToolsStatus {
v: typeof STATUS_SCHEMA_VERSION;
workspaceCwd: string;
serverName: string;
initialized: boolean;
acpChannelLive: boolean;
tools: ServeWorkspaceMcpToolStatus[];
errors?: ServeStatusCell[];
}
export type ServeSkillLevel = 'project' | 'user' | 'extension' | 'bundled';
export interface ServeWorkspaceSkillStatus extends ServeStatusCell {
@ -361,55 +292,6 @@ export interface ServeSessionContextStatus {
};
}
export interface ServeContextCategoryBreakdown {
systemPrompt: number;
builtinTools: number;
mcpTools: number;
memoryFiles: number;
skills: number;
messages: number;
freeSpace: number;
autocompactBuffer: number;
}
export interface ServeContextToolDetail {
name: string;
tokens: number;
}
export interface ServeContextMemoryDetail {
path: string;
tokens: number;
}
export interface ServeContextSkillDetail {
name: string;
tokens: number;
loaded?: boolean;
bodyTokens?: number;
}
export interface ServeSessionContextUsage {
modelName: string;
totalTokens: number;
contextWindowSize: number;
breakdown: ServeContextCategoryBreakdown;
builtinTools: ServeContextToolDetail[];
mcpTools: ServeContextToolDetail[];
memoryFiles: ServeContextMemoryDetail[];
skills: ServeContextSkillDetail[];
isEstimated?: boolean;
showDetails?: boolean;
}
export interface ServeSessionContextUsageStatus {
v: typeof STATUS_SCHEMA_VERSION;
sessionId: string;
workspaceCwd: string;
usage: ServeSessionContextUsage;
formattedText: string;
}
export interface ServeSessionSupportedCommandsStatus {
v: typeof STATUS_SCHEMA_VERSION;
sessionId: string;
@ -417,83 +299,6 @@ export interface ServeSessionSupportedCommandsStatus {
availableSkills: string[];
}
export type ServeSessionTaskLifecycleStatus =
| 'running'
| 'paused'
| 'completed'
| 'failed'
| 'cancelled';
export type ServeSessionProcessTaskLifecycleStatus =
| 'running'
| 'completed'
| 'failed'
| 'cancelled';
export interface ServeSessionAgentTaskStatus {
kind: 'agent';
id: string;
label: string;
description: string;
status: ServeSessionTaskLifecycleStatus;
startTime: number;
endTime?: number;
runtimeMs: number;
outputFile?: string;
subagentType?: string;
isBackgrounded: boolean;
error?: string;
resumeBlockedReason?: string;
}
export interface ServeSessionShellTaskStatus {
kind: 'shell';
id: string;
label: string;
description: string;
status: ServeSessionProcessTaskLifecycleStatus;
startTime: number;
endTime?: number;
runtimeMs: number;
outputFile?: string;
command: string;
cwd: string;
pid?: number;
exitCode?: number;
error?: string;
}
export interface ServeSessionMonitorTaskStatus {
kind: 'monitor';
id: string;
label: string;
description: string;
status: ServeSessionProcessTaskLifecycleStatus;
startTime: number;
endTime?: number;
runtimeMs: number;
command: string;
pid?: number;
eventCount: number;
lastEventTime: number;
droppedLines: number;
exitCode?: number;
error?: string;
ownerAgentId?: string;
}
export type ServeSessionTaskStatus =
| ServeSessionAgentTaskStatus
| ServeSessionShellTaskStatus
| ServeSessionMonitorTaskStatus;
export interface ServeSessionTasksStatus {
v: typeof STATUS_SCHEMA_VERSION;
sessionId: string;
now: number;
tasks: ServeSessionTaskStatus[];
}
/**
* Issue #4175 PR 16: workspace memory + agents read surfaces.
*
@ -712,22 +517,6 @@ export interface ServeWorkspaceEnvStatus {
errors?: ServeStatusCell[];
}
export interface ServeWorkspaceToolStatus {
name: string;
displayName?: string;
description?: string;
enabled: boolean;
}
export interface ServeWorkspaceToolsStatus {
v: typeof STATUS_SCHEMA_VERSION;
workspaceCwd: string;
initialized: true;
acpChannelLive: boolean;
tools: ServeWorkspaceToolStatus[];
errors?: ServeStatusCell[];
}
/**
* Discriminant for diagnostic cells emitted by `/workspace/preflight`. Cells
* with `locality: 'daemon'` are answered by the bridge process directly and

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-base",
"version": "0.16.1",
"version": "0.17.0",
"description": "Base channel infrastructure for Qwen Code",
"type": "module",
"main": "dist/index.js",

View File

@ -270,46 +270,6 @@ export abstract class ChannelBase {
this.config.cwd,
);
// 3.5. Bang (!) shell command — direct execution, no LLM
if (envelope.text.startsWith('!')) {
const cmd = envelope.text.slice(1).trim();
const bridgeShellCommand = (this.bridge as unknown as Record<string, unknown>)['shellCommand'];
if (cmd && typeof bridgeShellCommand === 'function') {
try {
const result = (await bridgeShellCommand(sessionId, cmd)) as {
exitCode: number | null;
output: string;
aborted: boolean;
};
const longestRun = Math.max(
0,
...Array.from(
(result.output || '').matchAll(/`+/g),
(m) => m[0].length,
),
);
const fence = '`'.repeat(Math.max(3, longestRun + 1));
const output = result.output
? `${fence}\n${result.output}\n${fence}`
: '(no output)';
const exitLine =
result.exitCode !== null && result.exitCode !== 0
? `\nExit code: ${result.exitCode}`
: '';
await this.sendMessage(
envelope.chatId,
`$ ${cmd}\n${output}${exitLine}`,
);
} catch (error) {
await this.sendMessage(
envelope.chatId,
`Shell command failed: ${error instanceof Error ? error.message : String(error)}`,
);
}
return;
}
}
// Prepend referenced (quoted) message text for reply context
let promptText = envelope.text;
if (envelope.referencedText) {

View File

@ -37,10 +37,6 @@ export interface DaemonChannelSessionClient {
requestId: string,
response: RequestPermissionResponse,
): Promise<boolean>;
shellCommand?(
command: string,
signal?: AbortSignal,
): Promise<{ exitCode: number | null; output: string; aborted: boolean }>;
}
export interface DaemonChannelSessionFactoryRequest {
@ -317,18 +313,6 @@ export class DaemonChannelBridge extends EventEmitter {
}
}
async shellCommand(
sessionId: string,
command: string,
signal?: AbortSignal,
): Promise<{ exitCode: number | null; output: string; aborted: boolean }> {
const session = this.ensureSession(sessionId);
if (!session.shellCommand) {
throw new Error('Shell command not supported by this session client');
}
return session.shellCommand(command, signal);
}
async cancelSession(sessionId: string): Promise<void> {
const session = this.ensureSession(sessionId);
await session.cancel();

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-dingtalk",
"version": "0.16.1",
"version": "0.17.0",
"description": "DingTalk channel adapter for Qwen Code",
"type": "module",
"main": "dist/index.js",

View File

@ -0,0 +1,27 @@
{
"name": "@qwen-code/channel-feishu",
"version": "0.17.0",
"description": "Feishu (Lark) channel adapter for Qwen Code",
"type": "module",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist"
],
"scripts": {
"build": "tsc --build"
},
"dependencies": {
"@qwen-code/channel-base": "file:../base",
"@larksuiteoapi/node-sdk": "^1.45.0"
},
"devDependencies": {
"typescript": "^5.0.0"
}
}

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,968 @@
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { FeishuChannel } from './FeishuAdapter.js';
import type { ChannelConfig, AcpBridge } from '@qwen-code/channel-base';
function createMockBridge(): AcpBridge {
return {
prompt: vi.fn().mockResolvedValue(undefined),
cancelSession: vi.fn().mockResolvedValue(undefined),
on: vi.fn(),
off: vi.fn(),
} as unknown as AcpBridge;
}
function createConfig(overrides?: Partial<ChannelConfig>): ChannelConfig {
return {
type: 'feishu',
token: '',
clientId: 'test_app_id',
clientSecret: 'test_app_secret',
senderPolicy: 'open',
allowedUsers: [],
sessionScope: 'user',
cwd: '/tmp',
groupPolicy: 'open',
groups: { '*': { requireMention: true } },
...overrides,
};
}
function createChannel(
configOverrides?: Partial<ChannelConfig>,
): FeishuChannel {
const config = createConfig(configOverrides);
const bridge = createMockBridge();
return new FeishuChannel('test', config, bridge);
}
// Access private methods for unit testing
function getPrivateMethod<T>(instance: unknown, method: string): T {
return (instance as Record<string, unknown>)[method] as T;
}
describe('FeishuChannel', () => {
describe('constructor', () => {
it('throws if clientId is missing', () => {
expect(() => createChannel({ clientId: undefined })).toThrow(
/requires clientId/,
);
});
it('throws if clientSecret is missing', () => {
expect(() => createChannel({ clientSecret: undefined })).toThrow(
/requires clientId.*clientSecret/,
);
});
});
describe('extractContent', () => {
let channel: FeishuChannel;
let extractContent: (
messageType: string,
contentJson: string,
) => {
text: string;
imageKey?: string;
fileKey?: string;
fileName?: string;
};
beforeEach(() => {
channel = createChannel();
extractContent = getPrivateMethod<
(
messageType: string,
contentJson: string,
) => {
text: string;
imageKey?: string;
fileKey?: string;
fileName?: string;
}
>(channel, 'extractContent').bind(channel);
});
it('handles text messages', () => {
const result = extractContent('text', JSON.stringify({ text: 'hello' }));
expect(result.text).toBe('hello');
});
it('handles post messages with nested paragraphs', () => {
const post = {
zh_cn: {
title: 'Post Title',
content: [
[
{ tag: 'text', text: 'Line 1 ' },
{ tag: 'a', text: 'link' },
],
[{ tag: 'text', text: 'Line 2' }],
],
},
};
const result = extractContent('post', JSON.stringify(post));
expect(result.text).toContain('Post Title');
expect(result.text).toContain('Line 1 link');
expect(result.text).toContain('Line 2');
});
it('handles image messages', () => {
const result = extractContent(
'image',
JSON.stringify({ image_key: 'img_key_123' }),
);
expect(result.text).toBe('(image)');
expect(result.imageKey).toBe('img_key_123');
});
it('handles file messages', () => {
const result = extractContent(
'file',
JSON.stringify({ file_key: 'file_key_456', file_name: 'doc.pdf' }),
);
expect(result.text).toBe('(file: doc.pdf)');
expect(result.fileKey).toBe('file_key_456');
expect(result.fileName).toBe('doc.pdf');
});
it('handles audio messages', () => {
const result = extractContent('audio', JSON.stringify({}));
expect(result.text).toBe('(audio)');
});
it('handles media (video) messages', () => {
const result = extractContent(
'media',
JSON.stringify({ file_key: 'vid_key', file_name: 'video.mp4' }),
);
expect(result.text).toBe('(video)');
expect(result.fileKey).toBe('vid_key');
expect(result.fileName).toBe('video.mp4');
});
it('returns empty text for unknown types', () => {
const result = extractContent('sticker', JSON.stringify({}));
expect(result.text).toBe('');
});
it('handles malformed JSON gracefully', () => {
const result = extractContent('text', 'not valid json');
expect(result.text).toBe('');
});
it('handles empty content', () => {
const result = extractContent('text', JSON.stringify({}));
expect(result.text).toBe('');
});
});
describe('extractCardText', () => {
let channel: FeishuChannel;
let extractCardText: (card: Record<string, unknown>) => string | undefined;
beforeEach(() => {
channel = createChannel();
extractCardText = getPrivateMethod<
(card: Record<string, unknown>) => string | undefined
>(channel, 'extractCardText').bind(channel);
});
it('extracts markdown from v2 card format (body.elements)', () => {
const card = {
body: {
elements: [
{ tag: 'markdown', content: 'Hello world' },
{ tag: 'markdown', content: 'Second block' },
],
},
};
const result = extractCardText(card);
expect(result).toContain('Hello world');
expect(result).toContain('Second block');
});
it('extracts from collapsible_panel in v2 format', () => {
const card = {
body: {
elements: [
{ tag: 'markdown', content: 'Preview' },
{
tag: 'collapsible_panel',
elements: [{ tag: 'markdown', content: 'Hidden content' }],
},
],
},
};
const result = extractCardText(card);
expect(result).toContain('Preview');
expect(result).toContain('Hidden content');
});
it('extracts from v1/API format (flat elements array)', () => {
const card = {
title: 'Card Title',
elements: [{ tag: 'markdown', content: 'Body text' }],
};
const result = extractCardText(card);
expect(result).toContain('Card Title');
expect(result).toContain('Body text');
});
it('strips streaming indicator', () => {
const card = {
body: {
elements: [{ tag: 'markdown', content: 'Content\n---\n*生成中...*' }],
},
};
const result = extractCardText(card);
expect(result).not.toContain('生成中');
expect(result).toBe('Content');
});
it('returns undefined for empty card', () => {
const result = extractCardText({});
expect(result).toBeUndefined();
});
it('filters fallback text', () => {
const card = {
elements: [
[{ tag: 'text', text: '请升级至最新版本客户端,以查看内容' }],
],
};
const result = extractCardText(card);
expect(result).toBeUndefined();
});
});
describe('state machine: dedup', () => {
let channel: FeishuChannel;
let seenMessages: Map<string, number>;
beforeEach(() => {
channel = createChannel();
seenMessages = getPrivateMethod(channel, 'seenMessages');
});
it('deduplicates messages with same ID within TTL', () => {
seenMessages.set('msg_1', Date.now());
// Simulate calling onMessage with same ID — it should be skipped
const onMessage = getPrivateMethod<(data: unknown) => void>(
channel,
'onMessage',
).bind(channel);
// Mock fetchBotInfo result
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
onMessage({
message: {
message_id: 'msg_1',
chat_id: 'chat_1',
chat_type: 'p2p',
message_type: 'text',
content: JSON.stringify({ text: 'hello' }),
},
sender: {
sender_id: { open_id: 'user_1' },
sender_type: 'user',
},
});
// Should not create a card session since it's a duplicate
const cardSessions = getPrivateMethod<Map<string, unknown>>(
channel,
'cardSessions',
);
expect(cardSessions.has('msg_1')).toBe(false);
});
it('allows message after TTL expiry', () => {
// Set a message that expired 6 minutes ago
const DEDUP_TTL_MS = 5 * 60 * 1000;
seenMessages.set('msg_old', Date.now() - DEDUP_TTL_MS - 1000);
// Simulate the cleanup timer logic
const now = Date.now();
for (const [id, ts] of seenMessages) {
if (now - ts > DEDUP_TTL_MS) {
seenMessages.delete(id);
}
}
expect(seenMessages.has('msg_old')).toBe(false);
});
});
describe('state machine: cleanupCard', () => {
let channel: FeishuChannel;
let cleanupCard: (inboundMsgId: string) => void;
beforeEach(() => {
channel = createChannel();
cleanupCard = getPrivateMethod<(id: string) => void>(
channel,
'cleanupCard',
).bind(channel);
});
it('cleans up all maps for a given inbound message', () => {
const cardSessions = getPrivateMethod<Map<string, unknown>>(
channel,
'cardSessions',
);
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
const msgToQuestion = getPrivateMethod<Map<string, string>>(
channel,
'msgToQuestion',
);
const msgToSenderName = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderName',
);
// Populate all maps
cardSessions.set('msg_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
sessionToInboundMsg.set('session_1', 'msg_1');
msgToQuestion.set('msg_1', 'question?');
msgToSenderName.set('msg_1', '<at>user</at>');
cleanupCard('msg_1');
expect(cardSessions.has('msg_1')).toBe(false);
expect(sessionToInboundMsg.has('session_1')).toBe(false);
expect(msgToQuestion.has('msg_1')).toBe(false);
expect(msgToSenderName.has('msg_1')).toBe(false);
});
it('clears pending timer on cleanup', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
const clearTimeoutSpy = vi.spyOn(global, 'clearTimeout');
const timer = setTimeout(() => {}, 10000);
cardSessions.set('msg_2', {
messageId: 'card_2',
created: true,
creating: false,
stopped: false,
accumulatedText: '',
lastUpdateAt: Date.now(),
pendingUpdateTimer: timer,
});
cleanupCard('msg_2');
expect(clearTimeoutSpy).toHaveBeenCalledWith(timer);
expect(cardSessions.has('msg_2')).toBe(false);
clearTimeoutSpy.mockRestore();
});
});
describe('state machine: stop button during card creation', () => {
let channel: FeishuChannel;
beforeEach(() => {
channel = createChannel();
});
it('marks card as stopped even when still creating', async () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
// Simulate card in "creating" state
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: false,
creating: true,
stopped: false,
accumulatedText: 'partial text',
lastUpdateAt: Date.now(),
});
// Mock bridge
const bridge = getPrivateMethod<AcpBridge>(channel, 'bridge');
const cancelSessionSpy = vi
.spyOn(bridge, 'cancelSession')
.mockResolvedValue(undefined);
// Mock updateCard to not actually call HTTP
const updateCardMock = vi.fn().mockResolvedValue(true);
(channel as unknown as Record<string, unknown>)['updateCard'] =
updateCardMock;
// Simulate sessionToInboundMsg mapping
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_abc', 'inbound_1');
// Simulate msgToSenderId mapping (fail-closed auth check)
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'user_open_id');
// Call onCardAction with stop
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'user_open_id' },
});
const state = cardSessions.get('inbound_1') as
| Record<string, unknown>
| undefined;
// cancelling is set synchronously (stopped is deferred until cancelSession resolves)
expect(state?.['cancelling']).toBe(true);
// Wait for async handleStop to complete — stopped is set after cancelSession resolves
await vi.waitFor(() => {
expect(state?.['stopped']).toBe(true);
});
expect(cancelSessionSpy).toHaveBeenCalledWith('session_abc');
expect(state?.['cancelling']).toBe(false);
});
it('rejects stop from a different user (operator mismatch)', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'original_user');
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
const result = onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'different_user' },
});
expect(result).toBe(false);
const state = cardSessions.get('inbound_1') as
| Record<string, unknown>
| undefined;
expect(state?.['stopped']).toBe(false);
});
it('rejects stop when operator field is missing (fail-closed)', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'original_user');
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
// No operator field at all
const result = onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
});
expect(result).toBe(false);
});
it('rejects stop when msgToSenderId has no entry (no originalSender)', () => {
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'test',
lastUpdateAt: Date.now(),
});
// msgToSenderId intentionally not populated for inbound_1
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
const result = onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'some_user' },
});
expect(result).toBe(false);
});
});
describe('disconnect', () => {
it('closes wsClient on disconnect', () => {
const channel = createChannel();
const mockClose = vi.fn();
(channel as unknown as Record<string, unknown>)['wsClient'] = {
close: mockClose,
};
channel.disconnect();
expect(mockClose).toHaveBeenCalled();
expect(
(channel as unknown as Record<string, unknown>)['wsClient'],
).toBeUndefined();
});
it('clears dedup timer on disconnect', () => {
const channel = createChannel();
const clearIntervalSpy = vi.spyOn(global, 'clearInterval');
const timer = setInterval(() => {}, 60000);
(channel as unknown as Record<string, unknown>)['dedupTimer'] = timer;
channel.disconnect();
expect(clearIntervalSpy).toHaveBeenCalledWith(timer);
clearIntervalSpy.mockRestore();
clearInterval(timer);
});
});
describe('extractContent: post at-node mentions', () => {
it('extracts @mention user_name from post at nodes', () => {
const channel = createChannel();
const extractContent = getPrivateMethod<
(messageType: string, contentJson: string) => { text: string }
>(channel, 'extractContent').bind(channel);
const post = {
zh_cn: {
title: '',
content: [
[
{ tag: 'text', text: 'hello ' },
{ tag: 'at', user_id: 'ou_123', user_name: 'John' },
{ tag: 'text', text: ' check this' },
],
],
},
};
const result = extractContent('post', JSON.stringify(post));
expect(result.text).toBe('hello @John check this');
});
it('handles at node without user_name gracefully', () => {
const channel = createChannel();
const extractContent = getPrivateMethod<
(messageType: string, contentJson: string) => { text: string }
>(channel, 'extractContent').bind(channel);
const post = {
zh_cn: {
title: '',
content: [
[
{ tag: 'text', text: 'hello ' },
{ tag: 'at', user_id: 'ou_123' },
],
],
},
};
const result = extractContent('post', JSON.stringify(post));
expect(result.text).toBe('hello');
});
});
describe('onCardAction: cancelSession failure', () => {
it('shows "停止失败" when cancelSession throws', async () => {
const bridge = createMockBridge();
(bridge.cancelSession as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
new Error('session not found'),
);
const config = createConfig();
const channel = new FeishuChannel('test', config, bridge);
// Set up botOpenId and card state
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: false,
accumulatedText: 'some text',
lastUpdateAt: Date.now(),
});
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
msgToSenderId.set('inbound_1', 'original_user');
const msgToSenderName = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderName',
);
msgToSenderName.set('inbound_1', '@sender');
// Set up session mapping so cancelSession is actually called
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
// Mock updateCard to capture the text
const updateCardSpy = vi.fn().mockResolvedValue(true);
(channel as unknown as Record<string, unknown>)['updateCard'] =
updateCardSpy;
const onCardAction = getPrivateMethod<
(data: Record<string, unknown>) => boolean
>(channel, 'onCardAction').bind(channel);
onCardAction({
action: { value: { action: 'stop' } },
context: { open_message_id: 'card_1' },
operator: { open_id: 'original_user' },
});
// Wait for the fire-and-forget handleStop to complete
await new Promise((r) => setTimeout(r, 50));
expect(updateCardSpy).toHaveBeenCalled();
const cardText = updateCardSpy.mock.calls[0][1] as string;
expect(cardText).toContain('停止失败');
});
});
describe('deleteCard', () => {
it('returns true on successful deletion', async () => {
const channel = createChannel();
const fetchMock = vi
.fn()
.mockResolvedValue(new Response(null, { status: 200 }));
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
// Provide a valid token
(channel as unknown as Record<string, unknown>)['tokenCache'] = {
token: 'test_token',
expiresAt: Date.now() + 3600_000,
};
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
const result = await deleteCard('om_test_msg_id');
expect(result).toBe(true);
expect(fetchMock).toHaveBeenCalledWith(
expect.stringContaining('/im/v1/messages/om_test_msg_id'),
expect.objectContaining({ method: 'DELETE' }),
);
});
it('returns false when token is unavailable', async () => {
const channel = createChannel();
// No token cache and getTenantAccessToken will fail
const fetchMock = vi
.fn()
.mockResolvedValue(
new Response(JSON.stringify({ code: -1 }), { status: 500 }),
);
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
const result = await deleteCard('om_test_msg_id');
expect(result).toBe(false);
});
it('returns false on HTTP error', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['tokenCache'] = {
token: 'test_token',
expiresAt: Date.now() + 3600_000,
};
const fetchMock = vi
.fn()
.mockResolvedValue(new Response('not found', { status: 404 }));
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
const result = await deleteCard('om_test_msg_id');
expect(result).toBe(false);
});
it('clears token cache on 401', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['tokenCache'] = {
token: 'stale_token',
expiresAt: Date.now() + 3600_000,
};
const fetchMock = vi
.fn()
.mockResolvedValue(new Response('unauthorized', { status: 401 }));
vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
const deleteCard = getPrivateMethod<
(messageId: string) => Promise<boolean>
>(channel, 'deleteCard').bind(channel);
await deleteCard('om_test_msg_id');
expect(
(channel as unknown as Record<string, unknown>)['tokenCache'],
).toBeUndefined();
});
});
describe('sendMessage: token failure logging', () => {
it('logs and returns early when token is unavailable', async () => {
const channel = createChannel();
const stderrSpy = vi
.spyOn(process.stderr, 'write')
.mockImplementation(() => true);
// No token available
await channel.sendMessage('oc_chat_id', 'hello');
expect(stderrSpy).toHaveBeenCalledWith(
expect.stringContaining('Cannot send: no access token'),
);
stderrSpy.mockRestore();
});
});
describe('onPromptEnd: error recovery branches', () => {
it('sends error fallback when card creation failed and no accumulated text', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: '',
created: false,
creating: false,
stopped: false,
finalizing: false,
completed: false,
abandoned: false,
accumulatedText: '',
lastUpdateAt: Date.now(),
});
const sendMessageSpy = vi.fn().mockResolvedValue(undefined);
(channel as unknown as Record<string, unknown>)['sendMessage'] =
sendMessageSpy;
const onPromptEnd = getPrivateMethod<
(chatId: string, sessionId: string, messageId?: string) => Promise<void>
>(channel, 'onPromptEnd').bind(channel);
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
await onPromptEnd('oc_chat_id', 'session_1');
// Should send error fallback message
expect(sendMessageSpy).toHaveBeenCalledWith(
'oc_chat_id',
expect.stringContaining('出错了'),
);
});
it('sends accumulated text via sendMessage when card creation failed', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: '',
created: false,
creating: false,
stopped: false,
finalizing: false,
completed: false,
abandoned: false,
accumulatedText: 'partial response text',
lastUpdateAt: Date.now(),
});
const sendMessageSpy = vi.fn().mockResolvedValue(undefined);
(channel as unknown as Record<string, unknown>)['sendMessage'] =
sendMessageSpy;
const onPromptEnd = getPrivateMethod<
(chatId: string, sessionId: string, messageId?: string) => Promise<void>
>(channel, 'onPromptEnd').bind(channel);
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
await onPromptEnd('oc_chat_id', 'session_1');
expect(sendMessageSpy).toHaveBeenCalledWith(
'oc_chat_id',
expect.stringContaining('partial response text'),
);
});
});
describe('onResponseComplete: stopped card cleanup', () => {
it('cleans up and returns early when card was stopped', async () => {
const channel = createChannel();
(channel as unknown as Record<string, unknown>)['botOpenId'] = 'bot_123';
const cardSessions = getPrivateMethod<
Map<string, Record<string, unknown>>
>(channel, 'cardSessions');
cardSessions.set('inbound_1', {
messageId: 'card_1',
created: true,
creating: false,
stopped: true,
finalizing: false,
completed: true,
abandoned: false,
accumulatedText: 'text',
lastUpdateAt: Date.now(),
});
const sessionToInboundMsg = getPrivateMethod<Map<string, string>>(
channel,
'sessionToInboundMsg',
);
sessionToInboundMsg.set('session_1', 'inbound_1');
const sendMessageSpy = vi.fn().mockResolvedValue(undefined);
(channel as unknown as Record<string, unknown>)['sendMessage'] =
sendMessageSpy;
const onResponseComplete = getPrivateMethod<
(chatId: string, fullText: string, sessionId: string) => Promise<void>
>(channel, 'onResponseComplete').bind(channel);
await onResponseComplete('oc_chat_id', 'full response', 'session_1');
// Should NOT call sendMessage — the stop handler owns the card
expect(sendMessageSpy).not.toHaveBeenCalled();
// Card session should be cleaned up
expect(cardSessions.has('inbound_1')).toBe(false);
});
});
describe('webhook: JSON parse error logging', () => {
it('logs error message on malformed JSON body', async () => {
// This test verifies the fix is in place by checking the source code
// contains the error capture. A full integration test would require
// starting an HTTP server.
const channel = createChannel();
const connectWebhook = getPrivateMethod<
(
port: number,
verificationToken?: string,
encryptKey?: string,
) => Promise<void>
>(channel, 'connectWebhook').bind(channel);
// Just verify the method exists and is callable
expect(typeof connectWebhook).toBe('function');
});
});
describe('auxiliary map lifecycle', () => {
it('preserves auxiliary maps after handleInbound when no card session exists', () => {
const channel = createChannel();
// Simulate the state after processMessage populates maps but
// handleInbound (collect mode) didn't create a card session
const msgToQuestion = getPrivateMethod<Map<string, string>>(
channel,
'msgToQuestion',
);
const msgToSenderName = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderName',
);
const msgToSenderId = getPrivateMethod<Map<string, string>>(
channel,
'msgToSenderId',
);
const cardSessions = getPrivateMethod<Map<string, unknown>>(
channel,
'cardSessions',
);
// Populate auxiliary maps (as processMessage would)
msgToQuestion.set('msg_collect', 'question?');
msgToSenderName.set('msg_collect', '@sender');
msgToSenderId.set('msg_collect', 'user_123');
// No cardSession for msg_collect (collect mode)
// Verify maps are intact (the old code would have deleted them here)
expect(msgToQuestion.has('msg_collect')).toBe(true);
expect(msgToSenderName.has('msg_collect')).toBe(true);
expect(msgToSenderId.has('msg_collect')).toBe(true);
expect(cardSessions.has('msg_collect')).toBe(false);
});
});
});

View File

@ -0,0 +1,13 @@
export { FeishuChannel } from './FeishuAdapter.js';
export { downloadMedia } from './media.js';
import { FeishuChannel } from './FeishuAdapter.js';
import type { ChannelPlugin } from '@qwen-code/channel-base';
export const plugin: ChannelPlugin = {
channelType: 'feishu',
displayName: 'Feishu',
requiredConfigFields: ['clientId', 'clientSecret'],
createChannel: (name, config, bridge, options) =>
new FeishuChannel(name, config, bridge, options),
};

View File

@ -0,0 +1,179 @@
import { describe, it, expect } from 'vitest';
import { buildCardContent, extractTitle, splitChunks } from './markdown.js';
interface CardElement {
tag: string;
content?: string;
value?: Record<string, unknown>;
elements?: CardElement[];
}
interface CardStructure {
schema: string;
header?: { title: { content: string }; template: string };
body: { elements: CardElement[] };
}
describe('Feishu markdown utilities', () => {
describe('buildCardContent', () => {
it('returns a valid card structure', () => {
const card = buildCardContent('Hello world') as unknown as CardStructure;
expect(card.schema).toBe('2.0');
expect(card.body.elements).toBeDefined();
expect(card.body.elements[0]!.tag).toBe('markdown');
expect(card.body.elements[0]!.content).toBe('Hello world');
});
it('adds streaming indicator when isStreaming is true', () => {
const card = buildCardContent('text', {
isStreaming: true,
}) as unknown as CardStructure;
expect(card.body.elements[0]!.content).toContain('生成中...');
});
it('adds stop button when showStopButton is true', () => {
const card = buildCardContent('text', {
showStopButton: true,
}) as unknown as CardStructure;
const button = card.body.elements.find((e) => e.tag === 'button');
expect(button).toBeDefined();
expect(button!.value).toEqual({ action: 'stop' });
});
it('sets header with title', () => {
const card = buildCardContent('text', {
title: 'My Title',
}) as unknown as CardStructure;
expect(card.header!.title.content).toBe('My Title');
expect(card.header!.template).toBe('green');
});
it('sets blue header when streaming', () => {
const card = buildCardContent('text', {
title: 'Title',
isStreaming: true,
}) as unknown as CardStructure;
expect(card.header!.template).toBe('blue');
expect(card.header!.title.content).toBe('Title ...');
});
it('uses collapsible panel for long content when enabled', () => {
const longText = 'a'.repeat(600);
const card = buildCardContent(longText, {
collapsible: true,
collapsibleThreshold: 500,
}) as unknown as CardStructure;
const panel = card.body.elements.find(
(e) => e.tag === 'collapsible_panel',
);
expect(panel).toBeDefined();
});
it('does not use collapsible for short content', () => {
const card = buildCardContent('short', {
collapsible: true,
collapsibleThreshold: 500,
}) as unknown as CardStructure;
const panel = card.body.elements.find(
(e) => e.tag === 'collapsible_panel',
);
expect(panel).toBeUndefined();
});
});
describe('extractTitle', () => {
it('extracts title from first line', () => {
expect(extractTitle('Hello World\nmore text')).toBe('Hello World');
});
it('strips markdown heading markers', () => {
expect(extractTitle('## My Title\ncontent')).toBe('My Title');
});
it('strips bold/list markers', () => {
expect(extractTitle('* Item one')).toBe('Item one');
expect(extractTitle('> Quote text')).toBe('Quote text');
});
it('truncates to 20 chars', () => {
expect(
extractTitle('This is a very long title that should be truncated')
.length,
).toBeLessThanOrEqual(20);
});
it('returns default for empty text', () => {
expect(extractTitle('')).toBe('Qwen Code');
expect(extractTitle('###')).toBe('Qwen Code');
});
});
describe('splitChunks', () => {
it('returns single chunk for short text', () => {
expect(splitChunks('short text')).toEqual(['short text']);
});
it('returns single chunk for empty text', () => {
expect(splitChunks('')).toEqual(['']);
});
it('splits long text into chunks', () => {
const line = 'a'.repeat(100) + '\n';
const text = line.repeat(50); // 5050 chars > 4000
const chunks = splitChunks(text);
expect(chunks.length).toBeGreaterThan(1);
chunks.forEach((chunk) => {
expect(chunk.length).toBeLessThanOrEqual(4100);
});
});
it('closes and reopens code fences across boundaries', () => {
const longCode = '```\n' + 'x\n'.repeat(2500) + '```';
const chunks = splitChunks(longCode);
expect(chunks.length).toBeGreaterThan(1);
expect(chunks[0]).toContain('```');
if (chunks.length > 1) {
expect(chunks[1]!.trimStart().startsWith('```')).toBe(true);
}
});
it('hard-splits a single line exceeding CHUNK_LIMIT', () => {
const longLine = 'a'.repeat(5000);
const chunks = splitChunks(longLine);
expect(chunks.length).toBe(2);
expect(chunks[0]!.length).toBe(4000);
expect(chunks[1]!.length).toBe(1000);
});
});
describe('buildCardContent table splitting', () => {
it('splits table and following content into separate elements', () => {
const md = [
'Before table',
'| A | B |',
'| --- | --- |',
'| 1 | 2 |',
'After table',
].join('\n');
const card = buildCardContent(md) as unknown as CardStructure;
const mdElements = card.body.elements.filter((e) => e.tag === 'markdown');
expect(mdElements.length).toBeGreaterThanOrEqual(3);
});
it('keeps content without tables in one element', () => {
const md = 'Hello\nWorld\nNo tables here';
const card = buildCardContent(md) as unknown as CardStructure;
const mdElements = card.body.elements.filter((e) => e.tag === 'markdown');
expect(mdElements.length).toBe(1);
});
it('does not split tables inside code fences', () => {
const md = ['```', '| A | B |', '| --- | --- |', '| 1 | 2 |', '```'].join(
'\n',
);
const card = buildCardContent(md) as unknown as CardStructure;
const mdElements = card.body.elements.filter((e) => e.tag === 'markdown');
expect(mdElements.length).toBe(1);
});
});
});

View File

@ -0,0 +1,256 @@
/**
* Feishu markdown / rich text helpers.
*
* Feishu supports Markdown in interactive cards but has quirks:
* - Tables render only in card messages (not in plain text messages)
* - Max message content ~4000 chars — split into chunks
* - Code fences must be closed/reopened across chunk boundaries
*/
const CHUNK_LIMIT = 4000;
/**
* Split markdown into segments so that each segment contains at most one table.
* This avoids Feishu card rendering issues when a single markdown element
* contains a table followed by other content.
*/
function splitByTables(text: string): string[] {
const lines = text.split('\n');
const segments: string[] = [];
let current: string[] = [];
let inTable = false;
let inCode = false;
for (const line of lines) {
// Track code fences (parity-based to handle inline code on same line)
if ((line.match(/```/g) || []).length % 2 === 1) {
inCode = !inCode;
current.push(line);
continue;
}
if (inCode) {
current.push(line);
continue;
}
const isTableLine =
line.trim().startsWith('|') && line.trim().endsWith('|');
if (isTableLine && !inTable) {
// Entering a table — if there's content before, flush it
if (current.length > 0 && current.some((l) => l.trim())) {
segments.push(current.join('\n'));
current = [];
}
inTable = true;
current.push(line);
} else if (!isTableLine && inTable) {
// Leaving a table — flush the table segment
inTable = false;
segments.push(current.join('\n'));
current = [line];
} else {
current.push(line);
}
}
if (current.length > 0) {
segments.push(current.join('\n'));
}
return segments.filter((s) => s.trim());
}
/**
* Build a Feishu interactive card JSON structure with markdown content.
* Uses a clean design with header, streaming indicator, and optional stop button.
*/
export function buildCardContent(
markdown: string,
options?: {
title?: string;
showStopButton?: boolean;
isStreaming?: boolean;
collapsible?: boolean;
collapsibleThreshold?: number;
},
): Record<string, unknown> {
const elements: Array<Record<string, unknown>> = [];
// Main content + streaming indicator in one markdown block
const contentMd = options?.isStreaming
? markdown + '\n\n---\n*生成中...*'
: markdown;
const threshold = options?.collapsibleThreshold || 500;
// For long content, use collapsible panel if enabled
if (
options?.collapsible &&
!options?.isStreaming &&
markdown.length > threshold
) {
// Find a split point near position 200 that doesn't break code fences
const previewEnd = markdown.indexOf('\n', 200);
const rawSplit = previewEnd > 0 ? previewEnd : 200;
const safeSplit = markdown.lastIndexOf(' ', rawSplit);
let splitAt = safeSplit > 100 ? safeSplit : rawSplit;
// Verify fence parity at split point — if preview has odd fences,
// move split to the nearest newline before/after where fences balance
const previewCandidate = markdown.slice(0, splitAt);
let fenceCount = 0;
for (const line of previewCandidate.split('\n')) {
if ((line.match(/```/g) || []).length % 2 === 1) fenceCount++;
}
if (fenceCount % 2 === 1) {
// Inside a code block — find the closing fence and split after it
const fenceStart = markdown.indexOf('\n```', splitAt);
if (fenceStart > 0 && fenceStart < rawSplit + 500) {
const fenceLineEnd = markdown.indexOf('\n', fenceStart + 1);
splitAt = fenceLineEnd > 0 ? fenceLineEnd : fenceStart + 4;
}
// else: no nearby closing fence, accept the split as-is
}
const preview = markdown.slice(0, splitAt);
const rest = markdown.slice(splitAt);
elements.push({
tag: 'markdown',
content: preview,
});
elements.push({
tag: 'collapsible_panel',
expanded: false,
background_color: 'default',
header: {
title: {
tag: 'plain_text',
content: '查看更多',
},
},
elements: [
{
tag: 'markdown',
content: rest,
},
],
});
} else if (options?.isStreaming) {
// During streaming, keep a single markdown element to avoid structure flicker
elements.push({
tag: 'markdown',
content: contentMd,
});
} else {
// Final render: split by tables to avoid rendering issues
const segments = splitByTables(contentMd);
for (const segment of segments) {
elements.push({
tag: 'markdown',
content: segment,
});
}
}
// Stop button
if (options?.showStopButton) {
elements.push({
tag: 'button',
text: {
tag: 'plain_text',
content: '停止',
},
type: 'danger',
value: { action: 'stop' },
});
}
// Header
const header = options?.title
? {
title: {
tag: 'plain_text',
content: options.isStreaming ? `${options.title} ...` : options.title,
},
template: options.isStreaming ? 'blue' : 'green',
}
: undefined;
return {
schema: '2.0',
config: {
wide_screen_mode: true,
summary: { content: markdown.slice(0, 3500) },
},
header,
body: { elements },
};
}
/** Extract a short title from the first line of markdown. */
export function extractTitle(text: string): string {
const firstLine = text.split('\n')[0] || '';
const cleaned = firstLine.replace(/^[#*\s\->]+/, '').slice(0, 20);
return cleaned || 'Qwen Code';
}
/**
* Split long text into chunks that fit within Feishu's message size limit.
* Handles code fence boundaries across chunks.
*/
export function splitChunks(text: string): string[] {
if (!text || text.length <= CHUNK_LIMIT) {
return [text];
}
const chunks: string[] = [];
let buf = '';
const lines = text.split('\n');
let inCode = false;
let fenceLine = '```';
for (const line of lines) {
const fenceCount = (line.match(/```/g) || []).length;
// Reserve space for closing fence when inside a code block
const reserve = inCode ? fenceLine.length + 1 : 0;
if (
buf.length + line.length + 1 + reserve > CHUNK_LIMIT &&
buf.length > 0
) {
if (inCode) {
buf += '\n```';
}
chunks.push(buf);
buf = inCode ? fenceLine : '';
}
buf += (buf ? '\n' : '') + line;
// Hard-split oversized lines that exceed the limit on their own
while (buf.length > CHUNK_LIMIT) {
const maxSlice = inCode ? CHUNK_LIMIT - '\n```'.length - 1 : CHUNK_LIMIT;
let piece = buf.slice(0, maxSlice);
buf = buf.slice(maxSlice);
if (inCode) {
piece += '\n```';
buf = fenceLine + '\n' + buf;
}
chunks.push(piece);
}
if (fenceCount % 2 === 1) {
if (!inCode) {
fenceLine = line.trim();
}
inCode = !inCode;
}
}
if (buf) {
chunks.push(buf);
}
return chunks;
}

View File

@ -0,0 +1,203 @@
import {
describe,
it,
expect,
vi,
beforeEach,
afterEach,
type MockInstance,
} from 'vitest';
import { downloadMedia } from './media.js';
describe('downloadMedia', () => {
let fetchSpy: MockInstance<typeof fetch>;
beforeEach(() => {
fetchSpy = vi.spyOn(globalThis, 'fetch');
});
afterEach(() => {
fetchSpy.mockRestore();
});
it('should download file successfully', async () => {
const mockData = new Uint8Array([1, 2, 3, 4]);
const mockResponse = {
ok: true,
headers: {
get: (key: string) => {
if (key === 'content-length') return '4';
if (key === 'content-type') return 'image/png';
return null;
},
},
body: {
getReader: () => ({
read: vi
.fn()
.mockResolvedValueOnce({ done: false, value: mockData })
.mockResolvedValueOnce({ done: true, value: undefined }),
cancel: vi.fn(),
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia(
'om_valid_msg',
'file_valid_key',
'image',
'valid_token',
);
expect(result).not.toBeNull();
expect(result?.buffer).toEqual(Buffer.from(mockData));
expect(result?.mimeType).toBe('image/png');
});
it('should reject invalid messageId (path traversal)', async () => {
const result = await downloadMedia(
'../../../etc/passwd',
'file_key',
'file',
'token',
);
expect(result).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
it('should reject invalid fileKey (path traversal)', async () => {
const result = await downloadMedia(
'om_msg',
'../../../etc/passwd',
'file',
'token',
);
expect(result).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
it('should reject empty parameters', async () => {
expect(await downloadMedia('', 'file_key', 'file', 'token')).toBeNull();
expect(await downloadMedia('om_msg', '', 'file', 'token')).toBeNull();
expect(await downloadMedia('om_msg', 'file_key', 'file', '')).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
it('should return null on HTTP error', async () => {
const mockResponse = {
ok: false,
status: 404,
text: vi.fn().mockResolvedValue('Not found'),
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should reject Content-Length exceeding 50MB', async () => {
const largeSize = 60 * 1024 * 1024; // 60 MB
const mockResponse = {
ok: true,
headers: {
get: (key: string) => {
if (key === 'content-length') return largeSize.toString();
return null;
},
},
body: {
getReader: () => ({
read: vi.fn().mockResolvedValue({ done: true, value: undefined }),
cancel: vi.fn(),
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should reject stream exceeding 50MB', async () => {
const chunkSize = 10 * 1024 * 1024; // 10 MB per chunk
const mockData = new Uint8Array(chunkSize);
const cancelMock = vi.fn();
const mockResponse = {
ok: true,
headers: {
get: () => null, // No content-length header
},
body: {
getReader: () => ({
read: vi.fn().mockResolvedValue({ done: false, value: mockData }), // Infinite stream
cancel: cancelMock,
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
expect(cancelMock).toHaveBeenCalled();
});
it('should return null when response body is null', async () => {
const mockResponse = {
ok: true,
headers: {
get: () => null,
},
body: null,
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should handle network errors', async () => {
fetchSpy.mockRejectedValueOnce(new Error('Network error'));
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).toBeNull();
});
it('should handle missing content-type header', async () => {
const mockData = new Uint8Array([1, 2, 3]);
const mockResponse = {
ok: true,
headers: {
get: () => null, // No content-type
},
body: {
getReader: () => ({
read: vi
.fn()
.mockResolvedValueOnce({ done: false, value: mockData })
.mockResolvedValueOnce({ done: true, value: undefined }),
cancel: vi.fn(),
}),
},
};
fetchSpy.mockResolvedValueOnce(mockResponse as unknown as Response);
const result = await downloadMedia('om_msg', 'file_key', 'file', 'token');
expect(result).not.toBeNull();
expect(result?.mimeType).toBe('application/octet-stream'); // Default
});
});

View File

@ -0,0 +1,102 @@
/**
* Feishu media download helpers.
*
* Downloads images, files, audio, and video from Feishu using the
* Open API: GET /im/v1/messages/:message_id/resources/:file_key
*/
const BASE_URL = 'https://open.feishu.cn/open-apis';
/** Validate Feishu ID format to prevent path traversal in URL interpolation. */
const FEISHU_ID_RE = /^[a-zA-Z0-9_.:-]+$/;
export interface MediaFile {
buffer: Buffer;
mimeType: string;
}
/**
* Download a media file from Feishu.
*
* @param messageId - The message ID containing the resource
* @param fileKey - The file_key or image_key from the message content
* @param resourceType - 'image' or 'file'
* @param accessToken - A valid tenant access token
* @returns MediaFile with buffer and mimeType, or null on failure
*/
export async function downloadMedia(
messageId: string,
fileKey: string,
resourceType: 'image' | 'file',
accessToken: string,
): Promise<MediaFile | null> {
if (
!messageId ||
!fileKey ||
!accessToken ||
!FEISHU_ID_RE.test(messageId) ||
!FEISHU_ID_RE.test(fileKey)
) {
return null;
}
try {
const url = `${BASE_URL}/im/v1/messages/${messageId}/resources/${fileKey}?type=${resourceType}`;
const resp = await fetch(url, {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`,
},
signal: AbortSignal.timeout(30_000),
});
if (!resp.ok) {
const detail = await resp.text().catch(() => '');
process.stderr.write(
`[Feishu] downloadMedia failed: HTTP ${resp.status} ${detail}\n`,
);
return null;
}
const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
const contentLength = resp.headers.get('content-length');
if (contentLength && parseInt(contentLength, 10) > MAX_DOWNLOAD_BYTES) {
process.stderr.write(
`[Feishu] downloadMedia rejected: size ${contentLength} exceeds ${MAX_DOWNLOAD_BYTES} byte limit\n`,
);
return null;
}
const mimeType =
resp.headers.get('content-type') || 'application/octet-stream';
// Stream-read with size enforcement (handles chunked transfer without Content-Length)
const reader = resp.body?.getReader();
if (!reader) {
return null;
}
const chunks: Buffer[] = [];
let totalSize = 0;
while (true) {
const { done, value } = await reader.read();
if (done) break;
totalSize += value.byteLength;
if (totalSize > MAX_DOWNLOAD_BYTES) {
reader.cancel();
process.stderr.write(
`[Feishu] downloadMedia rejected: actual size exceeds ${MAX_DOWNLOAD_BYTES} byte limit\n`,
);
return null;
}
chunks.push(Buffer.from(value));
}
const buffer = Buffer.concat(chunks);
return { buffer, mimeType };
} catch (err) {
process.stderr.write(
`[Feishu] downloadMedia error: ${err instanceof Error ? err.message : err}\n`,
);
return null;
}
}

View File

@ -0,0 +1,10 @@
{
"extends": "../../../tsconfig.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src"
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist", "src/**/*.test.ts"],
"references": [{ "path": "../base" }]
}

View File

@ -0,0 +1,8 @@
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
include: ['src/**/*.test.ts'],
globals: true,
},
});

View File

@ -1,6 +1,6 @@
{
"name": "@qwen-code/channel-plugin-example",
"version": "0.16.1",
"version": "0.17.0",
"private": true,
"type": "module",
"main": "dist/index.js",

Some files were not shown because too many files have changed in this diff Show More