qwen-code/docs
jinye 878f35fc4f
feat(serve): per-request sessionScope override on POST /session (#4175 Wave 2 PR 5) (#4209)
* feat(serve): per-request sessionScope override on POST /session

Resolves the FIXME at httpAcpBridge.ts:BridgeOptions.sessionScope from
#3803 — clients can now override the daemon-wide sessionScope per
request instead of being stuck with whatever boot-time value the
operator picked. A VSCode window that wants strict isolation can ask
for `'thread'` against a default-`'single'` daemon, and vice versa.

Wire change:
- POST /session body accepts optional `sessionScope: 'single' | 'thread'`
- Per-request value wins; daemon-wide default remains the fallback when
  the field is omitted (bit-for-bit backward compat for every existing
  caller)
- Invalid values yield 400 `{ code: 'invalid_session_scope' }`
- New capability tag `session_scope_override` advertised on
  /capabilities.features for negotiation

Bridge changes:
- BridgeSpawnRequest gains optional `sessionScope`
- spawnOrAttach validates the per-request value and resolves
  effectiveScope = req.sessionScope ?? defaultSessionScope
- doSpawn now takes effectiveScope and only stamps `defaultEntry`
  (the single-scope attach slot) when the spawn is single-scope —
  fixes a mixed-scope leak where a thread-first call would let a
  later omitted-scope call attach to the supposedly-isolated session

SDK:
- CreateSessionRequest gains optional `sessionScope`
- DaemonClient.createOrAttachSession conditionally spreads it into the
  JSON body so omitted callers send the same wire shape as before

Tests:
- 4 new bridge tests (override single→thread, override thread→single,
  mixed-scope leak regression, invalid-value rejection)
- 3 new server tests (valid passthrough, invalid 400, omitted backward
  compat)
- 2 new SDK tests (forwards/omits sessionScope on the wire)
- EXPECTED_STAGE1_FEATURES updated for the new capability tag

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

* fix(serve): address Wave 2 PR 5 review findings

Three independent review passes found three real issues:

1. Bridge `TypeError` on invalid `sessionScope` collapsed to opaque 500
   in `sendBridgeError` instead of the typed `400 invalid_session_scope`
   the route layer guarantees. Direct embed / test / future entry-point
   callers bypassing the route would see a generic 500 with stack noise
   on stderr — disagreeing with the route contract.

   Fix: add `InvalidSessionScopeError` class (alongside
   `SessionNotFoundError` / `WorkspaceMismatchError` /
   `SessionLimitExceededError`); the `spawnOrAttach` validator now
   throws it, and `sendBridgeError` translates to the same
   `{ error, code: 'invalid_session_scope' }` shape.

2. SDK `DaemonClient.createOrAttachSession` used a truthy check
   (`req.sessionScope ? ...`) for the conditional spread, silently
   erasing falsy-but-defined values (`''`, `null`, `0`) on the wire.
   A buggy caller would never see the daemon's 400 — it'd inherit the
   daemon-wide default while believing it requested a specific scope.
   Fix: use `!== undefined` (matching the bridge's own validation
   shape). Same fix to the server-side spread for consistency.

3. JSDoc and docs referenced `serve --sessionScope` as if it were a
   shipping CLI flag. It isn't — `ServeOptions` has no field, neither
   `runQwenServe` nor `serve.ts` plumbs one, and the production daemon
   default is hardcoded to `'single'`. Strike the references; note
   that #4175 may add the flag in a follow-up.

Test coverage expanded:
- Cap-bypass guard: per-request `'thread'` overrides cannot bypass
  `maxSessions` on a daemon-default-`'single'` deployment. Without
  this, a future refactor that gated the cap on `defaultSessionScope`
  instead of `effectiveScope` would silently let `'thread'` overrides
  amplify past the limit — the exact N-amplification cliff #3803 was
  about.
- Symmetric mixed-scope leak: daemon-default-`'thread'` +
  single-first-call followed by omitted-scope-second-call must produce
  distinct sessions. Mirrors the existing daemon-default-`'single'` +
  thread-first leak regression.
- Concurrent mixed-scope coalescing: simultaneous single + thread
  `spawnOrAttach` against the same workspace under slow `initialize`
  must not collide on `inFlightSpawns` (tracker keys differ by scope).
- Updated invalid-scope rejection test to assert
  `InvalidSessionScopeError` instance + carried `sessionScope` field.

🤖 Generated with [Qwen Code](https://github.com/QwenLM/qwen-code)
2026-05-16 23:54:20 +08:00
..
design feat(telemetry): unify span creation paths for hierarchical trace tree (#4126) 2026-05-16 22:29:55 +08:00
developers feat(serve): per-request sessionScope override on POST /session (#4175 Wave 2 PR 5) (#4209) 2026-05-16 23:54:20 +08:00
e2e-tests feat(tools): add generic worktree support — EnterWorktree/ExitWorktree + Agent isolation (#4073) 2026-05-14 18:00:30 +08:00
plans feat(vscode-ide-companion): add agent execution tool display (#2590) 2026-04-18 23:39:26 +08:00
users feat(cli): readline Ctrl+P/N for history and selection navigation (#4082) 2026-05-16 23:07:25 +08:00
_meta.ts feat: refactor docs 2025-12-05 10:51:57 +08:00
index.md fix: lint issues 2025-12-19 15:52:11 +08:00