* docs(serve): v0.16-alpha known limits + SDK QWEN_SERVER_TOKEN env fallback (PR 27)
First PR in the F5 release chain (PR 27 → 28 → 30a → 31) per the
2026-05-24 v0.16-alpha scope freeze in #4175 (text-only chat / coding
+ local-only deployment).
## SDK ergonomic micro-change (~50 LOC + 4 tests)
`DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` env
var when `opts.token` is absent — closes the asymmetry where the
daemon side already honors this var (--token CLI flag fallback,
already in main since PR 15) but the SDK forced clients to thread
it through every construction.
Properties:
- Browser-safe via `globalThis.process` indirection (the SDK is
imported by @qwen-code/webui; literal process.env access would
explode at module load on browser bundles)
- Whitespace stripped (matches daemon-side trim — handy for
`export QWEN_SERVER_TOKEN=\"\$(cat token.txt)\"` where cat adds a
trailing newline)
- Empty / whitespace-only treated as unset (a stale
`export QWEN_SERVER_TOKEN=\"\"` won't accidentally send
Authorization: Bearer with no token)
- Resolved at construction, not lazily per-request (later
process.env mutations don't affect already-built clients)
- Explicit opts.token wins over env
Tests: 4 new in DaemonClient.test.ts `bearer auth` describe
covering env fallback / explicit-wins / empty-treated-unset /
whitespace-stripped. Plus a defensive snapshot/restore on the
existing 'omits Authorization when no token' test so an
inherited test-runner export of QWEN_SERVER_TOKEN doesn't turn
that assertion into a false positive.
This SDK fallback is the entire ergonomic replacement for PR 29's
SDK env/file fallback. PR 29's other features (auto-gen daemon
token, instance-path keying, stale cleanup) remain deferred to
v0.16.x — all are DX improvements over the boot-time security gate
already shipped in PR 15.
## v0.16-alpha docs (~120 LOC markdown)
- docs/users/qwen-serve.md: new "v0.16-alpha known limits" section
enumerating product surface (text-only ✅, multimodal ❌),
deployment surface (local launchers ✅, containerized ❌, multi-
daemon ❌, BYO-token ✅), and hardening posture (boot security
gate ✅, mutation gate ✅, MCP guardrails ✅, prompt absolute
deadline ⏸️, rate limiting ⏸️, --max-body-size ⏸️). Adds an
alpha banner at the top of the file.
- docs/developers/examples/daemon-client-quickstart.md:
documents the SDK env fallback in both the Hello-daemon
intro and the Authentication section, with the "export +
no-token-arg" recommended path called out for local dev.
Verification: 125/125 DaemonClient.test.ts pass (121 existing +
4 new); 4/4 daemon-public-surface.test.ts pass (constructor
signature unchanged); tsc clean on packages/sdk-typescript;
eslint --max-warnings 0 clean on touched .ts files.
Part of #4175.
* fix(sdk): #4473 round 1 fold-in — 2 copilot doc threads adopted
T1 [copilot DaemonClient.ts:144 — stale line refs in readTokenFromEnv
JSDoc]: removed `runQwenServe.ts:175` (token resolution actually
lives at line 302-318 today, would drift again on next refactor)
and `docs/users/qwen-serve.md:173`. Replaced with stable
symbol/section references ("runQwenServe token-resolution path";
"qwen-serve user guide CLI flags section").
T2 [copilot daemon-client-quickstart.md:33 — `~/.qwen/server-token`
implies built-in path that doesn't exist]: PR 27 explicitly defers
token auto-generation + file-store fallback (PR 29 deferred features).
The example incorrectly suggested a standard file location.
Replaced with two explicit user-managed alternatives:
- `openssl rand -hex 32` one-shot
- `cat ./my-token-file` user-managed file
Both threads were accurate suggestions caught at the right time
(zero behavior change; pure docstring/example accuracy).
Verification: 125/125 DaemonClient tests pass; tsc + eslint clean
on touched files.
* refactor(core): F2 PR A R9 — McpClientManager options-object ctor
R9 (filed as F2 follow-up from #4336 review): 7 positional ctor args
collapse to (config, toolRegistry, options?: McpClientManagerOptions).
The trailing 5 (eventEmitter, sendSdkMcpMessage, healthConfig,
budgetConfig, pool) become named fields on `McpClientManagerOptions`.
Test factory `mkManager(overrides?)` introduced at the top of
`mcp-client-manager.test.ts` so each of the prior 80 inline
constructions becomes a single line naming only the field(s) the test
overrides; the 4 `undefined` sentinels each test threaded through to
reach the trailing `pool` arg are gone.
Net: 113 LOC removed (test) + 35 LOC added (src exposes interface +
mkManager factory + tool-registry call site update). Behavior
unchanged — same field assignments, same downgrade-enforce-without-
budget breadcrumb, same budget event wiring.
Filed bucket: F2 perf / cleanup PR A (R9 + W11 + W12 + R10/R23 T7),
see issue #4175 item 7 "F2 post-merge cleanup PRs". This is the first
of the 4 fixes in PR A; W11/W12/R10 follow as separate commits.
Test sweep: 84/84 mcp-client-manager.test.ts pass; typecheck clean.
* refactor(core): F2 PR A W11 — extract attachPooledSession + rollbackReservationOnSpawnFailure
W11 (filed as F2 follow-up from #4336 review): two private helpers
on `McpTransportPool` to eliminate inline duplication in `acquire()`:
- `attachPooledSession(entry, id, serverName, cfg, sessionId,
toolReg, promptReg)`: builds `SessionMcpView` + `entry.attach`
with the standard pool release callback. Used by both the
fast-path attach (existing entry) and the post-spawn attach
(after `await inFlight`). NOT used by `createUnpooledConnection`
— its release callback runs `entry.forceShutdown('manual')` +
`indexDetach` directly (no pool refcount accounting since
unpooled entries are per-session).
- `rollbackReservationOnSpawnFailure(reservationResult, serverName)`:
R24 T17 contract — only release the budget slot if THIS acquire
actually reserved a new slot (`'reserved'`); `'already_held'`
skips because the sibling owns it. Used by both the unpooled
catch and the pooled spawn-in-flight catch.
Race-window invariants (W10 / W77 / W90 / W111 / W125 / R24 T17)
stay at the call sites because they describe the SURROUNDING
ordering, not the helpers themselves. Helpers are documented to
defer those decisions back to callers.
Behavior unchanged. Filed bucket: F2 perf cleanup PR A (R9 done /
W11 this commit / W12 + R10 to follow).
Test sweep: 28/28 mcp-transport-pool.test.ts pass; typecheck clean.
* refactor(core): F2 PR A W12 — SessionMcpView precompute filter Sets
W12 (filed as F2 follow-up from #4336 review): `applyTools` /
`applyPrompts` precompute `excludeSet` + `includeSet` once per pass
instead of scanning `cfg.includeTools` / `cfg.excludeTools` arrays
inside every per-tool iteration.
Pre-fix the per-tool predicate (`passesSessionFilter`) walked both
arrays for every snapshot entry → O(M × N) per `applyTools` call.
With M tools × N filter entries, typical M=5-20 / N=2-5 case
finishes in microseconds either way; the win is data-structure
correctness and code clarity, not perceived perf.
`passesSessionFilter` / `passesSessionPromptFilter` (the array-
based predicates) stay exported and unchanged for unit tests + any
caller wanting to test a single name without paying Set construction.
The bulk path uses two new private helpers `compileNameFilter` +
`compiledFilterAccepts` whose Sets live on the `applyTools` /
`applyPrompts` stack frame.
Same semantics: `excludeTools` is direct-equality match (no parens
strip — pre-F2 behavior preserved); `includeTools` strips the first
`(...)` suffix so `toolName(args)` matches `toolName`.
Filed bucket: F2 perf cleanup PR A (R9 + W11 done / W12 this commit
/ R10 to follow).
Test sweep: 13/13 session-mcp-view.test.ts pass; typecheck clean.
* perf(core): F2 PR A R10 / R23 T7 — pid-descendants ps snapshot + pgrep fallback
R10 / R23 T7 (filed as F2 follow-up from #4336 review): the Linux
/ macOS pid-descendant enumeration moves from per-pid `pgrep -P
<pid>` BFS (one subprocess fork per node visited) to a single
`ps -A -o pid=,ppid=` snapshot followed by an in-memory tree walk
over `Map<ppid, pid[]>`. Windows analog: single `Get-CimInstance
Win32_Process | ConvertTo-Csv` snapshot of all `(ProcessId,
ParentProcessId)` rows replaces per-pid
`Get-CimInstance -Filter "ParentProcessId=$p"` BFS.
Two motivations:
1. **Fork count**: typical `npx → tool` / `uvx → tool` wrapper
trees are 2-3 levels deep with B=1-3 children per node →
pre-fix BFS forked ~5-10 subprocesses per pool-shutdown call.
Post-fix: exactly 1 fork regardless of tree depth.
2. **Snapshot consistency**: pre-fix BFS walked the table level
by level; a child that forked between two adjacent BFS levels
could be missed (we'd see the child but query its
descendants AFTER the new fork). The snapshot path captures
the table at one instant; new descendants forked after the
snapshot are tolerated by the existing ESRCH-tolerant
SIGTERM loop.
Caveats:
- `ps -A -o pid=,ppid=` is POSIX standard (macOS / Linux /
*BSD), but BusyBox `ps` <v1.28 (2018) doesn't support `-o`.
Distroless containers may not have `ps` at all. To preserve
behavior on those edge platforms, the legacy per-pid `pgrep`
BFS is retained as a fallback (`listDescendantPidsUnixPgrepFallback`).
Same retention on Windows for the per-pid filter path.
- Snapshot path uses `maxBuffer: 8MB` to cover ~250k-process
pathological hosts. Default 1MB would clip at ~30k processes.
- `MAX_DESCENDANTS = 256` / `MAX_DEPTH = 8` caps preserved on
both snapshot + fallback paths.
- Snapshot scans the entire host process table (not just the
target subtree). On the typical 200-500 process developer
machine this parses in <10ms; the win over BFS is real but
not order-of-magnitude — ~2x improvement, not 100x. PR A's
motivation framing is "fork hygiene + consistency", not raw
perf.
Empty-result detection: snapshot path tracks `parsedRows`. If the
ps/CIM tool runs successfully but produces 0 parseable rows
(BusyBox without `-o` echoing usage, AppLocker truncating CIM
output, etc.), we throw — the outer catch falls back to the
per-pid path. A genuine "root has no children" case parses many
rows and just returns empty from the walk. So the
"no-children-found" semantics are preserved across both paths.
Test gate update: pre-fix `integration: spawn-and-enumerate` test
skipped on `CI === '1'` because pgrep wasn't available on
minimal CI runners. Post-fix `ps -A` is universally available on
non-distroless Linux/macOS — only the Windows skip remains.
6/6 pid-descendants tests pass including the now-active
integration spawn test.
Design doc (`docs/design/f2-mcp-transport-pool.md` §6.4 + the F2
follow-up table at lines 82-85) updated to reflect the snapshot
+ fallback shape, and to mark W11 / W12 / R9 / R10 as ✅ Done in
PR A with the per-fix commit refs.
This commit completes F2 cleanup PR A. Filed bucket order:
R9 (commit 0cb1eaa27) → W11 (commit 2d546efca) → W12 (commit
a4a855ab3) → R10 (this commit). Issue #4175 item 7 "F2 post-
merge cleanup PRs": PR A done; PR B (W93 + W133-a + W134) and
PR C (W133-c SDK breaking) to follow as separate clusters.
Test sweep: 287/287 F2 + cli pass; ESLint clean; typecheck clean
(core + cli). Integration test on macOS local runs the new
snapshot path successfully.
* refactor(core): F2 PR A R2 — wenshao followup (visited set + dedup predicate)
Two Suggestions from wenshao's first PR #4411 review pass (07:15Z),
both small and worth folding before merge:
PR-A-R2 #1 (pid-descendants.ts:309 — walkDescendants visited set):
`walkDescendants`'s BFS lacked a `visited` set. If the snapshot
captures a PID-reuse cycle — rare but possible on busy hosts with
rapid pid churn between `ps -A`'s start and parse, where Linux
wraparound can show a freed pid in a different parent's children
list creating an A→B / B→A cycle — pre-fix BFS would revisit nodes
and fill the MAX_DESCENDANTS=256 quota with duplicate entries,
starving legitimate descendants. Pre-PR-A the per-pid `pgrep` BFS
had the same theoretical issue but was less exposed (each
`pgrep -P pid` call returns only DIRECT children; snapshot captures
the whole tree at once, making cycles instantly visible).
Fix: 3-LOC `Set<number>` add. `root` seeded into `visited` so a
malformed snapshot listing root as a descendant of its own child
doesn't re-enqueue root either.
PR-A-R2 #2 (session-mcp-view.ts:117 — predicate dedup):
After W12, the exported `passesSessionFilter` /
`passesSessionPromptFilter` still called `passesNameFilter` (the
pre-W12 array-based implementation), while `applyTools` /
`applyPrompts` used `compiledFilterAccepts(compileNameFilter(...))`.
Two parallel implementations of the same predicate — future change
to one without the other would silently diverge:
- the exported function's tests (passesSessionFilter unit tests)
would still pass
- the production filter path in applyTools/applyPrompts would
behave differently
Reviewer also noted `passesSessionPromptFilter` had zero callers
in production code or tests after W12 — `applyPrompts` no longer
references it. Kept the export rather than deleting it (matches
the `passesSessionFilter` shape for symmetry + the F3 audit-path
comment block earmarks both as the replay predicates), but routed
both through `compiledFilterAccepts(compileNameFilter(...))` so
there is a single source of truth. Set construction is per-call
for these exports (negligible for unit-test / one-off probes);
the bulk paths in `applyTools` / `applyPrompts` still construct
ONE filter per pass via the original W12 code path.
`passesNameFilter` (the standalone array-based helper) deleted —
its only callers were the two exports, which now use the compiled
path. Public-API surface unchanged: the two exported functions
keep their signatures and semantics.
Test sweep: 19/19 pid-descendants + session-mcp-view tests pass;
typecheck + ESLint clean.
Continues commit chain: f05917071 (R9) → 20d2f1b90 (W11) →
6cf18f641 (W12) → 2a41c6fae (R10) → this (R2 followups).
* fix(core): F2 PR A R3 T3 — Windows CSV delimiter locale fix
`ConvertTo-Csv -NoTypeInformation` honors the system locale's list
separator on PowerShell 5.1. On German / French / Dutch / Italian /
... locales the separator is `;` not `,`, so the regex
`^"(\d+)","(\d+)"$` in `snapshotProcessTreeWin` never matched →
`parsedRows === 0` → snapshot threw → fell back to the per-pid CIM
filter path with ~0.5-1s extra PowerShell startup latency per
descendant on every pool shutdown.
Fix: 1-LOC `-Delimiter ","` on `ConvertTo-Csv`. Forces comma
regardless of locale or PowerShell version. PowerShell 7+ defaults
to comma already; 5.1 (the Windows-bundled version most users have
without explicit upgrade) honored locale. The explicit delimiter
makes both consistent.
Skipped wenshao's companion Suggestion T4 (test coverage for
walkDescendants MAX_DESCENDANTS / MAX_DEPTH caps) as F2 hardening
follow-up — the caps are simple 2-line guards exercisable by
inspection; ~50 LOC of mock infrastructure isn't commensurate
with the regression risk on currently-stable defensive code,
and (per the issue #4175 follow-up bucket) we keep dedicated
test-coverage work out of perf-cleanup PRs.
Continues commit chain: f05917071 (R9) → 20d2f1b90 (W11) →
6cf18f641 (W12) → 2a41c6fae (R10) → ced5d62b0 (R2) → this (R3 T3).
Test sweep: 6/6 pid-descendants tests pass; typecheck + ESLint clean.
* feat(cli): implement non-interactive /context output and diagnostic
- Extract collectContextData() from contextCommand.ts for shared usage.
- Register /context in ALLOWED_BUILTIN_COMMANDS_NON_INTERACTIVE.
- Extend SDK control protocol with GET_CONTEXT_USAGE request.
- Implement handleGetContextUsage in SystemController for programmatic token queries.
- Expose getContextUsage() method in the TypeScript SDK Query interface.
* fix: address review feedback and fix critical bugs in context usage feature
- Add missing `get_context_usage` route in ControlDispatcher (SDK calls would throw)
- Fix `executionMode` defaulting: use `?? 'interactive'` to match other commands
- Validate dynamic import of `collectContextData` before invoking
- Preserve original error message in handleGetContextUsage catch block
- Add ControlDispatcher test for get_context_usage routing
- Add JSDoc comment for context command in non-interactive allowlist
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: re-check abort signal after async operations in handleGetContextUsage
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: add getContextUsage() to SDK TypeScript documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: clarify getContextUsage showDetails is a display hint, not a data filter
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: make showDetails affect response shape, add getContextUsage test
- When showDetails is false, return empty detail arrays instead of full
data so /context and /context detail produce different payloads
- Add unit test for Query.getContextUsage() covering request payload
and response handling
* fix: strip UI type from SDK response, sync Java SDK protocol
- Remove leaked `type: 'context_usage'` from control response payload
- Add GET_CONTEXT_USAGE to Java SDK protocol mirror (enum, interface,
union type)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Refactor subagent model configuration from nested modelConfig object to a simple model string field for better UX and clarity.
Changes:
- Replace modelConfig object with model string in SubagentConfig interface
- Add model-selection.ts utility for parsing and validating model selectors
- Support 'inherit' keyword and bare model IDs (e.g., 'glm-5', 'claude-sonnet-4-6')
- Maintain backward compatibility by parsing legacy modelConfig frontmatter
- Update validation to reject cross-provider authType-prefixed selectors
- Update SDK types (TypeScript and Java) to reflect new schema
- Add comprehensive tests for model selection and validation
- Update documentation with model selection examples
Breaking changes:
- modelConfig.frontmatter field deprecated in favor of model field
- Cross-provider model selectors (e.g., 'openai:gpt-4') not supported for subagents
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>